ADR 010 Service Use Contract Render Source

Context

Legacy service-use contract generation reloads reservation, payment, caregiver, branch stamp, and mother signature rows during render. That makes printed artifacts drift when a branch changes data after payment, when a signature file is overwritten, or when caregiver assignment changes after a queued document request.

Money, identity, schedule, roster, and asset facts must be decided before render. The renderer must receive immutable evidence, not live PHP-style source lookups or UI-calculated amounts.

flowchart LR
  assignment[Care team assignment command]
  invalidation[Document projection invalidation]
  facts[Service-use contract fact reader]
  source[ServiceUseContractRenderSource]
  queue[Document render queue]
  worker[Printable document worker]
  artifact[Stored printable artifact]

  assignment --> invalidation
  invalidation --> facts
  facts --> source
  source --> queue
  queue --> worker
  worker --> artifact

Decision

Use ServiceUseContractRenderSource as the only render authority for service-use contracts.

Producer flow:

1. Care-team assignment or related projection change records a typed invalidation.
2. ServiceUseContractEvidenceSnapshotFactReader loads frozen facts from backend read models and Supabase revision rows.
3. ProjectServiceUseContractRenderSourceHandler writes a ready render source only when all required facts exist.
4. Missing facts write waiting_for_required_facts with exact missing fact codes, so workers retry instead of generating partial artifacts.
5. Render workers consume the render source and store a versioned artifact.

Required producer facts:

• contract template effective version;
• payment-deposited contract date;
• privacy-safe identity evidence;
• service occurrence set and period;
• current roster snapshot;
• charge component revision snapshots;
• branch stamp asset snapshot;
• mother signature asset snapshot;
• source evidence keys.

Boundaries

• Frontend must not calculate service-use contract totals or synthesize render source requests.
• Renderer must not query reservation, payment, caregiver, branch, or storage rows directly.
• Adapter code may read Supabase rows, but application/domain contracts own missing-fact readiness and net amount semantics.
• UI may show readiness and missing contract gaps; it may not invent fallback document data.

Consequences

This increases producer work before render, but removes artifact drift and post-payment mutation bugs. It also makes payment, asset, and roster provenance visible for support investigations.

Implementation Evidence

• Render-source projection application boundary
• Supabase fact-reader adapter
• Contract projection schema

These links prove code and contract foundations at pinned revisions. They do not prove active worker binding or live rendering.

Known Gaps

• runtime binding and backfill for voucher recipient identity evidence recording;
• immutable stamp/signature asset fact readers;
• storage/access grants for immutable stamp and signature objects;
• live E2E proof that rendering does not reload mutable legacy rows.

Revision History

• 2026-07-07: accepted immutable render-source decision.
• 2026-07-10: separated repository evidence from unverified runtime rollout.