ADR 014 Settlement Data-room Readiness Projection

Context

Legacy settlement data-room screens mixed branch/HQ settlement rows, document exports, mutable board ids, and UI-local state. During migration the operator projection could reach the backend branch settlement dashboard, but the frontend still rendered settlementDataRoomReadiness=contract_gap because the reconciliation export contract had no data-room readiness payload.

That kept the preview visibly incomplete even when authorization and settlement projection reads were working. A naive fix could have invented frontend labels or fake settlement periods for empty branches, but that would repeat the legacy problem: UI creates financial/document truth.

Decision

GET /branch-settlement-reconciliation-exports/{branchProfileId} owns a settlementDataRoomReadiness projection.

The projection includes:

1. collectionCode and collection.
2. readinessStatus: ready, empty, or needs_repair.
3. Nullable settlement period coverage.
4. Branch/external recipient scope.
5. Source, projection, and expected revisions.
6. Row count.
7. Source evidence keys.
8. Blocking facts.
9. Backend timestamp.

Empty exports must use settlementPeriodStart=null and settlementPeriodEnd=null. They must not synthesize current-month, epoch, or legacy placeholder dates.

Frontend may render a rollout fallback only when the field is absent. When the field is present, the shared contract validator is authority. Frontend must not calculate readiness from table rows, hardcoded settlement labels, or browser state.

Implementation Evidence

• Backend operator projection interface
• Readiness projection schema
• Frontend projection rendering

Consequences

Operator settlement preview can distinguish backend readiness from absent contract data without inventing dates or totals.

Historical stage evidence recorded 2026-07-09:

• Direct API returns collection=branch_to_headquarters_settlement, readinessStatus=empty, null period coverage, source evidence keys, and revision numbers for branch profile 00000000-0000-0000-0000-000000000101.
• pnpm playwright:operator-projection reports settlementBoardState=ready and settlementDataRoomReadiness=branch_to_headquarters_settlement on desktop and mobile with no console, request, or HTTP response errors.

This ADR audit did not rerun stage or Playwright proof.

Known Gaps

Deeper settlement data-room request/detail/action flow is partially represented: workspace repair requests can revoke active artifact grants in the domain and contract payloads. Supabase adapter persistence also round-trips revoked grant metadata plus repair revokedGrantIds and replacementArtifactRequestCode through the workspace JSON row. Remaining work is stage proof, operator-visible replacement/reissue lineage, conflict handling, and SpiceDB-backed authorization on the full workspace route set.

Revision History

• 2026-07-09: accepted backend readiness projection.
• 2026-07-10: marked stage results historical and separated remaining rollout gaps.