Example: individual operation document

A page under operations/ documents one operation end to end: what triggers it, what it takes, and the ordered steps it performs. Doc gen produces one per row in the library's operation catalog, and the catalog links to it.

What reviewers should check

• The page's operation_id frontmatter value matches the catalog row it came from, and its trigger, inputs, and outputs agree with that row rather than telling a different story.
• The Field/Value table uses the template's exact field names — Operation ID, Trigger, Inputs, Outputs, Primary components, Entry point — and the entry point is a real repo-relative path.
• Steps read as ordered, pseudo-code-like actions a reader could follow. A narrative paragraph, or a step that only names a method without saying what it does, is a defect.
• Every business rule a step enforces is cited as a link into business-rules.md, and every SQL statement is cited as a link into sql/. A bare VAL-021 or SQL-001 with no link is a contract violation.
• Conditional branches, validation failures, and error handling appear as indented sub-bullets under the step they belong to, phrased as "On failure:" or "If ...", not folded into the step text.
• Delegated logic from a referenced library is embedded inline as sub-steps with a > Origin callout, never reduced to an opaque "calls X" line. In-run origins link the originating operation page; external origins retrieved through the Legends CLI name the dotted library in backticks, mark their steps with †, and carry no link.
• The process flow diagram is a standard triple-backtick mermaid fence whose nodes correspond to the steps above it. The legacy Azure DevOps colon-fence syntax does not render in this portal.
• ## Sources is the final section and lists the files the steps were derived from, including any embedded dependency's entry point.

Example

The document below is a complete, correct operations/validate-claim-record.md for a fictional library. It is the detail page behind the first row of that library's operation catalog.

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

---
title: Validate claim record
summary: Applies the ClaimIntake rule set to a single claim record and returns every failure it produces.
status: draft
owner: Claims Systems Team
last_reviewed: 2026-08-14
library: SAIF.Framework.Validation
reference_type: package
operation_id: OP-001
trigger: ValidationEngine.Validate called by a consuming application on claim submission
---

# Validate claim record

This is the primary entry point of the library. When an operator submits the
claim entry screen in `SAIF.Claims.Intake`, the application hands the assembled
claim record to `ValidationEngine.Validate` with the rule set name `ClaimIntake`
and a context object carrying jurisdiction, policy period, and user identity.
The engine evaluates every rule in the set without stopping at the first
failure, so the operator sees the complete list of corrections in one pass, then
records an audit row for each blocking failure. The caller uses the returned
`ValidationResult` to decide whether the claim may be persisted.

| Field | Value |
| --- | --- |
| **Operation ID** | OP-001 |
| **Trigger** | Caller request: `ValidationEngine.Validate(record, "ClaimIntake", context)` invoked on claim submission by `SAIF.Claims.Intake`. |
| **Inputs** | Claim record, rule set name `ClaimIntake`, `IValidationContext` supplying `JurisdictionCode`, `PolicyPeriod`, and `UserId`. |
| **Outputs** | `ValidationResult` carrying `IsValid`, the ordered failure collection, and the warning collection; one `ValidationFailureAudit` row per blocking failure. |
| **Primary components** | `ValidationEngine.Validate`, `ValidationRule.Evaluate`, `ValidationResult`, `ValidationAuditRepository.RecordOutcome` |
| **Entry point** | src/SAIF.Framework.Validation/ValidationEngine.vb |

## Steps

1. Confirm the engine has completed framework startup configuration before any rule is evaluated.
   - Read `IsInitialized` on the inherited component base and, when it is `False`, run framework startup configuration.†
   - Resolve the environment name and trace listener registration from framework configuration, then mark the component initialized.†

   > **Origin**: Steps 1.1–1.2 are implemented in [`Initialize component`](../../saif-framework-core/operations/initialize-component.md) (`SAIF.Framework.Core`) and executed on behalf of this operation.

   - On failure: `FrameworkNotInitializedException` propagates to the caller and no rule is evaluated, so results are never produced under default settings.
2. Load the `ClaimIntake` rule set, materializing and caching its ordered `ValidationRule` collection on the first request in the process.
   - If the rule set is already cached: reuse the cached collection without re-reading the XML definition.
   - On failure: `RuleSetNotFoundException` propagates and nothing is cached, so a corrected deployment succeeds on the next call.
3. Reject the request when the caller supplied no jurisdiction code and the rule set contains at least one state-scoped rule.
   - Record a blocking failure and return immediately rather than silently skipping the state-scoped rules.
4. Load the active rule definitions for the supplied jurisdiction code ([SQL-004](../sql/SQL-004.md), [ValidationRuleDefinition](../database-tables.md#validationruledefinition), [Jurisdiction](../database-tables.md#jurisdiction)).
   - Apply each jurisdiction-specific definition to the in-memory copy of the rule collection, adjusting severity for that run only; the cached rule set is left unchanged.
   - On failure: the read is advisory, so a timeout leaves the XML-declared severities in force and adds a warning to the result.
5. Evaluate each rule in declaration order against the claim record, appending every result to the accumulating collection without short-circuiting.
   - Check that the claim number is exactly eight digits ([VAL-014](../business-rules.md#val-014-claim-number-must-be-eight-digits)).
   - Check that the date of injury is not later than the current date ([VAL-021](../business-rules.md#val-021-date-of-injury-cannot-be-in-the-future)).
   - Check that the date of injury falls within the policy period supplied by the context.
   - If a rule's severity is warning: add the result to `ValidationResult.Warnings` and leave `IsValid` unchanged.
   - If a rule's severity is blocking: add the result to `ValidationResult.Failures` and set `IsValid` to `False`.
   - On failure: an exception raised inside a single rule is captured as a blocking failure for that rule, and evaluation continues with the remaining rules.
6. Emit a trace entry summarizing the rule set name, record identifier, and failure count.
   - Format the entry with the component name and current environment, then write it to the registered framework trace listener.†

   > **Origin**: Step 6.1† is implemented in `Write trace entry` in `SAIF.Framework.Diagnostics` (retrieved via the Legends CLI RAG service) and executed on behalf of this operation.
7. Record each blocking failure for audit reporting ([SQL-001](../sql/SQL-001.md), [ValidationFailureAudit](../database-tables.md#validationfailureaudit)).
   - Write the rule set name, claim number, evaluated rule count, blocking failure count, warning count, `UserId`, and the current timestamp.
   - On failure: the insert error is traced and swallowed; validation still returns its result so an audit outage cannot block claim intake.
8. Return the assembled `ValidationResult` to the caller, which blocks persistence when `IsValid` is `False` and otherwise displays any warnings as advisory text.

## Process flow

The following diagram visualizes this operation's control flow.

```mermaid
flowchart TD
    Start([Validate called on claim submission]) --> Init[Ensure framework startup configuration is complete]
    Init --> Load[Load ClaimIntake rule set]
    Load --> Jur{Jurisdiction code supplied?}
    Jur -->|No| Blocked([Return invalid result: jurisdiction required])
    Jur -->|Yes| Overrides[Read active rule definitions for the jurisdiction]
    Overrides --> Evaluate[Evaluate every rule in declaration order]
    Evaluate --> Trace[Write trace entry with failure count]
    Trace --> Audit[Insert a validation failure audit row per blocking failure]
    Audit --> Outcome{Any blocking failure recorded?}
    Outcome -->|Yes| Invalid([Return invalid result with all failures])
    Outcome -->|No| Valid([Return valid result with any warnings])
```

## Failure and edge-case behavior

- Uninitialized component: `FrameworkNotInitializedException` propagates before any rule runs, so a misconfigured host fails loudly at first use rather than validating under default settings.
- Missing rule set definition: `RuleSetNotFoundException` propagates and no partial collection is cached, so redeploying the XML file resolves the failure without a process restart.
- Missing jurisdiction code: reported as a blocking failure carrying the jurisdiction field, not as a skipped rule, so the gap is visible to the operator.
- Rule definition read timeout: the operation continues with XML-declared severities and adds a warning, because a reporting-side outage must not stop claim intake.
- Exception inside a single rule: captured as a blocking failure for that rule only; the remaining rules still run so the operator receives a complete correction list.
- Audit insert failure: traced and swallowed. The caller always receives the `ValidationResult`, so audit availability never gates claim submission.
- Empty rule set: returns a valid result with no failures. The caller cannot distinguish this from a record that passed every rule, which is why the audit row records the evaluated rule count.

## Related documentation
- [Operations and processes](../operations-processes.md)
- [Business rules](../business-rules.md)
- [SQL catalog](../sql/index.md)
- [Database tables](../database-tables.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/ValidationResult.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/RuleSets/ClaimIntake.rules.xml