# 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](rendered/libraries/saif-framework-validation/operations-processes.md) — the same document as a real page, so you can compare rendering as well as source.

````markdown
---
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
````