Example: operations and processes¶

operations-processes.md is the operation catalog and cross-operation hub for a single library. Doc gen produces one per library folder, listing every operation the library performs and linking each one to its own step-by-step page under operations/.

What reviewers should check¶

The Operation column of the catalog links to that operation's detail page at operations/validate-claim-record.md. A link to an on-page anchor such as #validate-claim-record is a contract violation — the step-by-step logic does not live on this page.
The catalog carries the template's full column set — Operation, Intent, Trigger, Inputs, Outputs, Rules, Tables, SQL — and every row fills all eight.
Rule identifiers in the Rules column are links into business-rules.md, and SQL identifiers are links into sql/. A bare VAL-021 or SQL-001 with no link is a defect wherever it appears.
No step-by-step logic, per-step citations, or embedded dependency steps appear on this page. If the hub is describing what happens in order, that content belongs in the per-operation document.
The inherited section names the originating class and library, marks inherited intent with †, and records which local operation each inherited behavior is embedded in — it does not restate the inherited steps here.
The Database interactions table lists one row per operation that touches the database, with a Read or Write type, and is omitted entirely for libraries that never issue SQL.
## Related documentation lists every standard page except this one, uses the canonical document names, and includes conditional pages only when the library really has them.
## Sources is the final section and lists real repo-relative paths for the code the operations were derived from.

Example¶

The document below is a complete, correct operations-processes.md for a fictional library.

View rendered example — the same document as a real page, so you can compare rendering as well as source.

---
title: SAIF.Framework.Validation operations and processes
summary: Business and technical operations supported by this library.
status: draft
owner: Claims Systems Team
last_reviewed: 2026-08-14
library: SAIF.Framework.Validation
reference_type: package
---

# SAIF.Framework.Validation operations and processes

This page is the operation catalog and cross-operation hub for this library. Each operation's detailed, step-by-step logic lives in its own page under `operations/`.

## Operation catalog

| Operation | Intent | Trigger | Inputs | Outputs | Rules | Tables | SQL |
| --- | --- | --- | --- | --- | --- | --- | --- |
| [Validate claim record](operations/validate-claim-record.md) | Apply the `ClaimIntake` rule set to a single claim record and report every failure it produces | `ValidationEngine.Validate` called by `SAIF.Claims.Intake` when an operator submits the claim entry screen | Claim record, rule set name `ClaimIntake`, `IValidationContext` | `ValidationResult` with ordered failures and warnings; one validation failure audit row per blocking failure | [VAL-014](business-rules.md#val-014-claim-number-must-be-eight-digits), [VAL-021](business-rules.md#val-021-date-of-injury-cannot-be-in-the-future) | [ValidationFailureAudit](database-tables.md#validationfailureaudit) | [SQL-001](sql/SQL-001.md) |
| [Load rule set](operations/load-rule-set.md) | Materialize and cache the `ValidationRule` collection for a named rule set from its XML definition | First request for a rule set name that is not yet in the process cache | Rule set name, rule set file path from configuration | Cached, ordered `ValidationRule` collection | None — structural operation with no business rule of its own | None | None |
| [Resolve jurisdiction context](operations/resolve-jurisdiction-context.md) | Determine the effective jurisdiction and load the active rule definitions for that state before state-scoped rules run | Invoked by `Validate claim record` when the active rule set contains at least one state-scoped rule | `IValidationContext.JurisdictionCode`, rule set name | Resolved `JurisdictionCode` and the applicable rule definition collection | [VAL-021](business-rules.md#val-021-date-of-injury-cannot-be-in-the-future) | [ValidationRuleDefinition](database-tables.md#validationruledefinition), [Jurisdiction](database-tables.md#jurisdiction) | [SQL-004](sql/SQL-004.md) |
| [Validate provider record](operations/validate-provider-record.md) | Apply the `ProviderIntake` rule set to a medical provider record supplied by a billing application | `ValidationEngine.Validate` called with rule set name `ProviderIntake` | Provider record, rule set name `ProviderIntake`, `IValidationContext` | `ValidationResult` for the provider record; one validation failure audit row per blocking failure | [VAL-032](business-rules.md#val-032-provider-tax-id-must-be-nine-digits) | [ValidationFailureAudit](database-tables.md#validationfailureaudit) | [SQL-001](sql/SQL-001.md) |
| [Screen pending audit queue](operations/screen-pending-audit-queue.md) | Revalidate queued premium audit records ahead of an overnight batch run so malformed rows are rejected before processing | `SAIF.PremiumAudit.Batch` calls `AuditQueueScreener.Screen` at the start of each batch window | Audit period start and end dates, optional policy number | Collection of `ValidationResult` keyed by audit queue identifier | [VAL-037](business-rules.md#val-037-benefit-rate-must-be-positive) | [PremiumAuditQueue](database-tables.md#premiumauditqueue) | [SQL-007](sql/SQL-007.md) |

## Process flow diagram

The following diagram visualizes the primary operational flow across operations.

```mermaid
flowchart TD
    Start([Caller submits a record]) --> Load[Load rule set]
    Load --> Jur{Rule set contains state-scoped rules?}
    Jur -->|Yes| Resolve[Resolve jurisdiction context]
    Jur -->|No| Evaluate[Evaluate rules in declaration order]
    Resolve --> Evaluate
    Evaluate --> Audit[Write a validation failure audit row for each blocking failure]
    Audit --> Blocking{Any blocking failure recorded?}
    Blocking -->|Yes| Rejected([Return invalid result; caller blocks persistence])
    Blocking -->|No| Accepted([Return valid result with any warnings])
```

## Inherited operations and processes

Operations in this section originate from base classes or services provided by dependency framework libraries. They are inherited or delegated, not implemented in this library.

### From `ValidationComponentBase` (`SAIF.Framework.Core`)

| Operation | Intent | Provided by | Origin | Embedded in |
| --- | --- | --- | --- | --- |
| Initialize component | Complete framework startup configuration and establish trace routing before any component performs work† | `ValidationComponentBase` | `SAIF.Framework.Core` | [Validate claim record](operations/validate-claim-record.md) |
| Write trace entry | Emit a component trace entry through the configured framework trace listener† | `ValidationComponentBase` | `SAIF.Framework.Core` | [Validate claim record](operations/validate-claim-record.md) |

> **Origin**: These operations are defined in `SAIF.Framework.Core` / `ValidationComponentBase` and inherited or delegated by this component. Their step-by-step logic is embedded inline (with `> Origin` callouts) in the consuming operation's detail page.

## Database interactions

The following table summarizes which operations read from or write to the database. Per-step SQL and table citations live in each operation's detail page under `operations/`.

| Operation | SQL | Tables | Type |
| --- | --- | --- | --- |
| [Validate claim record](operations/validate-claim-record.md) | [SQL-001](sql/SQL-001.md) | [ValidationFailureAudit](database-tables.md#validationfailureaudit) | Write |
| [Resolve jurisdiction context](operations/resolve-jurisdiction-context.md) | [SQL-004](sql/SQL-004.md) | [ValidationRuleDefinition](database-tables.md#validationruledefinition), [Jurisdiction](database-tables.md#jurisdiction) | Read |
| [Validate provider record](operations/validate-provider-record.md) | [SQL-001](sql/SQL-001.md) | [ValidationFailureAudit](database-tables.md#validationfailureaudit) | Write |
| [Screen pending audit queue](operations/screen-pending-audit-queue.md) | [SQL-007](sql/SQL-007.md) | [PremiumAuditQueue](database-tables.md#premiumauditqueue), [Policy](database-tables.md#policy) | Read |

## Failure and edge-case behavior

- A rule set name that has no matching XML definition raises `RuleSetNotFoundException` from `Load rule set`; no partially populated rule collection is cached, so a corrected deployment succeeds on the next call without a process restart.
- A missing jurisdiction code stops evaluation before any state-scoped rule runs and is reported as a blocking failure rather than a skipped rule, so the gap is visible to the operator.
- The jurisdiction rule definition read is treated as advisory: if `SQL-004` times out, the base rule severities from the XML definition are used and a warning is added to the result rather than failing the whole submission.
- The failure audit insert never blocks validation. When `SQL-001` fails, the failure is traced through `ValidationComponentBase.WriteTrace` and the `ValidationResult` is still returned to the caller.
- `Screen pending audit queue` skips queue rows already locked by another process, so two overlapping batch windows cannot revalidate the same audit.
- Validation is not transactional. Callers that persist a record after a valid result are responsible for their own transaction scope; this library opens no transaction of its own.

## Stored procedure operations

Operations implemented in SQL Server stored procedures referenced by this library.

| Operation | Description | Source | Link |
| --- | --- | --- | --- |
| Retrieve pending audits | Returns queued premium audits due within a processing window, ordered oldest due date first | `dbo.usp_GetPendingAudits` | [Details](procedures/usp-getpendingaudits.md#operations) |

## Related documentation
- [Index](index.md)
- [Overview](overview.md)
- [Architecture](architecture.md)
- [Dependencies](dependencies.md)
- [Configuration](configuration.md)
- [Business rules](business-rules.md)
- [Database tables](database-tables.md)
- [SQL catalog](sql/index.md)
- [Procedures](procedures/index.md)
- [API reference](api/index.md)

## Sources
- src/SAIF.Framework.Validation/ValidationEngine.vb
- src/SAIF.Framework.Validation/RuleSetLoader.vb
- src/SAIF.Framework.Validation/Rules/ValidationRule.vb
- src/SAIF.Framework.Validation/Jurisdiction/JurisdictionResolver.vb
- src/SAIF.Framework.Validation/Data/RuleDefinitionRepository.vb
- src/SAIF.Framework.Validation/Data/ValidationAuditRepository.vb
- src/SAIF.Framework.Validation/Data/PendingAuditRepository.vb
- src/SAIF.Framework.Validation/Batch/AuditQueueScreener.vb
- src/SAIF.Framework.Validation/RuleSets/ClaimIntake.rules.xml
- src/SAIF.Framework.Validation/RuleSets/ProviderIntake.rules.xml