Make the Relay → Notary → programme decision boundary normative for 1.0

[jeremi]

What happened

The current 1.0 documentation and golden authoring examples contradict each other about where programme decisions belong.

Some pages correctly state that Registry Notary returns evidence and that the consuming programme owns eligibility, entitlement, payment, and action decisions:

• docs/site/src/content/docs/explanation/dpi-safeguards-alignment.mdx says Notary does not decide eligibility.
• docs/site/src/content/docs/explanation/evidence-issuance.mdx says the issuing programme converts verified evidence into an entitlement, payment, or benefit.
• docs/site/src/content/docs/explanation/integration-patterns.mdx says the social-protection MIS owns the eligibility decision.

Other current guidance directly teaches the opposite:

• docs/site/src/content/docs/explanation/disclosure-modes-and-computed-answers.mdx models an eligibility threshold as a CEL predicate inside Notary.
• docs/site/src/content/docs/explanation/records-stay-home.mdx tells authors to derive an eligibility decision with an expression rule.
• products/notary/docs/source-claim-modeling-guide.md tells authors to use CEL for purpose-specific predicates without defining the downstream programme boundary.
• products/notary/docs/notary-capability-matrix.md presents voucher and permit eligibility as supported Notary scenarios.
• Project-authoring fixtures and the snapshot tutorial use household-eligible and benefits-eligible, which reinforce Notary as an eligibility engine.

The result is a recurring architecture error: source adaptation, evidence semantics, and programme policy are collapsed into one "policy" concept.

Required 1.0 boundary

Make this flow normative and use it consistently:

Source system
  -> Registry Relay: source-specific acquisition and typed normalization
  -> Registry Notary: atomic, precise, reusable evidence statements
  -> Consuming programme: eligibility, prioritization, workflow, and action

The three policy categories must be distinguished:

1. Relay source-access and adaptation policy.
2. Notary evidence, authorization, and disclosure policy.
3. Consuming programme eligibility and action policy.

A Notary claim may be evaluated under purpose-bound authorization while retaining evidence semantics that can be reused by multiple programmes. CEL may derive evidence predicates, but it must not be documented as a general-purpose programme eligibility engine.

One explicit exception is required: Notary may attest a decision already made by an authoritative source. Such a claim must be described and named as a source-owned decision, not as a decision computed by Registry Notary.

DHIS2 proving flow

Use the public-demo-compatible DHIS2 child-health flow as the worked proof:

• DHIS2 remains the system of record.
• Relay performs bounded, same-origin DHIS2 acquisition and normalizes declared typed outputs.
• Notary exposes reusable evidence claims such as programme enrollment active, BCG birth dose recorded, OPV birth dose recorded, and measles dose recorded.
• The consuming programme computes actions such as outreach required or follow-up priority.
• true, false, null, no-match, ambiguity, and source failure retain distinct reviewed semantics. Missing evidence must not silently become a negative fact.
• Public demo connectivity is optional. Offline fixtures remain the deterministic acceptance path, with a governed live compatibility check when credentials and a reachable instance are available.

Acceptance criteria

• Add one normative evidence-versus-decision boundary to the main architecture and source/claim modeling guidance.
• Define Relay output, Notary evidence claim, programme decision, and source-owned decision in the glossary.
• Rework contradictory eligibility language in disclosure modes, records-stay-home, the Notary capability matrix, and the self-attestation guide.
• Add "not an eligibility engine" to the primary when-to-use/non-goals page.
• Add a claim-design test to authoring guidance: a claim states evidence, is precise about absence/unknown, and can be reused without importing a consuming programme's decision rules.
• Replace or explicitly qualify household-eligible and benefits-eligible examples and golden fixtures.
• Update the DHIS2 starter or add a dedicated beta example so Relay outputs, Notary evidence claims, and consuming programme decisions are visibly separate.
• Add focused tests covering the DHIS2 offline journey and failure semantics.
• Verify the full generated-project flow with repository-native locked checks.
• Perform a documentation review for cross-page consistency and a security review of auth, source authority, minimization, disclosure, audit, and no-match behavior.
• Record any live DHIS2 demo-server compatibility evidence separately from deterministic offline acceptance.

Non-goals

• Do not add DHIS2-specific dispatch to Relay. The existing product-neutral script capability remains the execution mechanism.
• Do not put programme eligibility, outreach, payment, referral, or case-workflow state inside Notary.
• Do not make the beta depend on the uptime, credentials, or data stability of a public DHIS2 demo server.
• Do not broaden source access or disclose raw DHIS2 records merely to simplify the demonstration.

Why this blocks 1.0

This is a developer-facing architecture and safety boundary. Shipping contradictory guidance and golden examples would cause adopters to encode programme policy in Notary, reduce claim reuse, overload evidence semantics, and make future integrations such as DHIS2 and OpenCRVS inconsistent.

[jeremi]

Implementation is now included in codex/1.0-remaining-integration as a58eab21.

This makes the source system → Relay → Notary → programme decision boundary normative, keeps the DHIS2 path bounded and product-neutral, and preserves the deterministic offline acceptance fixtures. Registry-backed issuance remains mandatory for credentials; source-free declarations are not introduced.

The integration branch is rebased onto current main, and the locked workspace, warnings-denied clippy, full Relay/Notary tests, and docs tests/generation pass. Leaving this ticket open until the integration branch is merged.

[jeremi]

Integration status update 2026-07-22

The implementation at a58eab21 remains only on codex/1.0-remaining-integration.

Compared with current protected main at 53918b25, that branch is 4 commits ahead and 14 behind, with merge base d6d2d167. This supersedes the earlier statement that it was rebased onto current main.

Treat the recorded verification as branch-local evidence, not delivered functionality. Keep this issue open until the change is rebuilt or rebased onto current main, merged, and its repository-native gates are rerun.

[jeremi]

Implementation refresh — 2026-07-23

Rebuilt this change on current origin/main while preserving the newer v0.12.2 DHIS2 starter metadata, digest, variables, and richer claim set.

The starter and fixtures now make the implementer boundary explicit: Registry Stack produces evidence; the consuming programme makes the programme decision. Deterministic project-authoring fixtures were refreshed accordingly.

registryctl and combined workspace/docs gates pass. Keep this issue open until review, push, and merge.