Example: business rules¶

business-rules.md enumerates the business behavior a library enforces. Doc gen produces one per library, and other documents — API reference pages, screen documents — link back to its rule anchors.

What reviewers should check¶

Every rule is an H2 heading of the form ## BR-001 Rule title followed by a Field/Value table. A rule that exists only as a row in a summary table has no anchor, so nothing can link to it.
Each table carries Statement, Trigger, Enforcement, Outcome, and Source rows. Enforcement names the method or symbol that applies the rule, not a vague "the engine validates this".
Statements describe business behavior, not implementation detail. "Claims older than 90 days require a late-filing reason" is a rule; "the loop calls Evaluate on each item" is not.
Inherited rules use the INH- prefix, carry † on the statement, and record the originating class and library in an Origin field rather than a separate sub-heading.
Inferred statements are marked with a trailing * and unknown ones with **. Bold inline confidence labels such as "Inferred:" are wrong.
The stored procedure section is present only when the library actually calls procedures, and ## Sources is the last section on the page.

Example¶

The document below is a complete, correct business-rules.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 business rules
summary: Enumerated business rules with per-rule trigger, enforcement, and outcomes.
status: draft
owner: Policy Systems Team
last_reviewed: 2026-02-18
library: SAIF.Framework.Validation
reference_type: package
---

# SAIF.Framework.Validation business rules

This page captures business rules enforced by this library.

## BR-001 Required policy identifiers must be present

| Field | Value |
| --- | --- |
| **Statement** | A policy or claims record must carry a non-empty policy number and claim number before it can be accepted for persistence. |
| **Trigger** | Evaluated on every call to `ValidationEngine.Validate` for records in the `ClaimIntake` and `PremiumAudit` rule sets. |
| **Enforcement** | `ValidationRule.Evaluate` applies the `RequiredField` rule type to the `PolicyNumber` and `ClaimNumber` fields and records a blocking failure when either is empty or whitespace. |
| **Outcome** | `ValidationResult.IsValid` is `False` and a failure carrying rule ID BR-001 is returned; `SAIF.Claims.Intake` blocks submission and `SAIF.PremiumAudit.Batch` skips the record. |
| **Source** | src/SAIF.Framework.Validation/Rules/ValidationRule.vb |

---

## BR-002 Jurisdiction must be supplied for state-scoped rules

| Field | Value |
| --- | --- |
| **Statement** | Rules that vary by state may only be evaluated when the calling application supplies a jurisdiction code; a missing jurisdiction is treated as a validation failure rather than a skipped rule. |
| **Trigger** | Evaluated when a rule set contains at least one rule whose definition includes a `jurisdiction` attribute. |
| **Enforcement** | `ValidationEngine.Validate` reads `IValidationContext.JurisdictionCode` before rule execution and records a blocking failure when the value is null or empty. |
| **Outcome** | Evaluation stops before any state-scoped rule runs, and a failure carrying rule ID BR-002 is returned so the defect is visible instead of silently passing. |
| **Source** | src/SAIF.Framework.Validation/ValidationEngine.vb |

---

## BR-003 Claim dates must fall within the policy period

| Field | Value |
| --- | --- |
| **Statement** | A claim's date of injury must fall on or between the policy effective date and the policy expiration date. |
| **Trigger** | Evaluated for records in the `ClaimIntake` rule set whenever a date of injury is present. |
| **Enforcement** | `ValidationRule.Evaluate` applies the `DateRange` rule type, comparing the record's date of injury against the effective and expiration dates provided by `IValidationContext`. |
| **Outcome** | A blocking failure carrying rule ID BR-003 is returned, identifying the date of injury field so the intake screen can highlight it. |
| **Source** | src/SAIF.Framework.Validation/Rules/ValidationRule.vb |

---

## BR-004 Warnings do not block persistence

| Field | Value |
| --- | --- |
| **Statement** | Rules declared with warning severity report a problem but must not prevent a record from being saved; only blocking failures stop persistence. |
| **Trigger** | Evaluated on every rule set execution that produces at least one warning-severity result. |
| **Enforcement** | `ValidationEngine.Validate` adds warning results to `ValidationResult.Warnings` and leaves `IsValid` set to `True` when no blocking failure occurred. |
| **Outcome** | `SAIF.Claims.Intake` displays warnings as advisory text and allows submission; `SAIF.PremiumAudit.Batch` writes warnings to the batch log and continues processing the record. |
| **Source** | src/SAIF.Framework.Validation/ValidationResult.vb |

---

## BR-005 All failures are reported in a single pass

| Field | Value |
| --- | --- |
| **Statement** | Validation must report every rule failure a record produces, so an operator can correct all problems in one correction cycle rather than one per submission.* |
| **Trigger** | Evaluated on every call to `ValidationEngine.Validate` where more than one rule fails. |
| **Enforcement** | `ValidationEngine.Validate` iterates the full rule collection without short-circuiting and appends each failure to the result. |
| **Outcome** | The returned `ValidationResult` contains the complete ordered failure collection, each entry carrying its own rule identifier. |
| **Source** | src/SAIF.Framework.Validation/ValidationEngine.vb |

## Inherited business rules

Rules in this section originate from base classes or services provided by
dependency framework libraries. They are enforced by inherited behavior, not by
code in this library. The originating class and library are recorded in each
rule's **Origin** field.

## INH-001 Framework components must be initialized before use

| Field | Value |
| --- | --- |
| **Statement** | A framework component may not perform work until framework startup configuration has completed, so that trace routing and environment settings are established before any business decision is made.† |
| **Trigger** | Evaluated on the first operation invoked on any component deriving from `ValidationComponentBase`. |
| **Enforcement** | `ValidationComponentBase.EnsureInitialized` checks `IsInitialized` and raises `FrameworkNotInitializedException` when startup configuration has not run. |
| **Outcome** | The operation is abandoned and the caller receives an exception identifying the uninitialized component, rather than results produced under default settings. |
| **Origin** | `SAIF.Framework.Core` — `ValidationComponentBase` |
| **Source** | Retrieved from indexed documentation via Legends CLI |

---

## Notes
- Rule severity is declared in the rule set XML, not in code, so changing a
  rule from warning to blocking is a configuration change rather than a code
  change.
- BR-005 is marked inferred because the no-short-circuit behavior is evident
  from the evaluation loop but is not stated in any code comment or
  specification in the repository.
- Statements marked with `†` were retrieved from dependency library
  documentation via the Legends CLI RAG service.

## Related documentation
- [Index](index.md)
- [Overview](overview.md)
- [Architecture](architecture.md)
- [Dependencies](dependencies.md)
- [Configuration](configuration.md)
- [Operations and processes](operations-processes.md)
- [API reference](api/index.md)

## Sources
- src/SAIF.Framework.Validation/ValidationEngine.vb
- src/SAIF.Framework.Validation/Rules/ValidationRule.vb
- src/SAIF.Framework.Validation/ValidationResult.vb
- src/SAIF.Framework.Validation/RuleSets/ClaimIntake.rules.xml
- src/SAIF.Framework.Validation/RuleSets/PremiumAudit.rules.xml