Skip to content
Sanmopia Modernization

ADR 013 Settlement Component Acknowledgement Ledger

Switch to normal mode

Context

Section titled “Context”

Legacy branch/HQ settlement confirmation used browser checkbox state and positive-only form fields to decide whether membership dues, delivery fees, coupon fees, gift fees, and manual rows were paid. Omitted or zero values became silent no-ops. Later closeout SQL inferred arrears from flag/count state.

That design loses actor intent, hides partial payment, makes replay ambiguous, and lets frontend state shape financial truth.

Decision

Section titled “Decision”

Settlement component acknowledgement is a backend command and ledgered decision.

Each command must include:

  1. Settlement board reference.
  2. Expected board revision.
  3. Actor kind and actor profile id.
  4. Idempotency key.
  5. Decision timestamp.
  6. One or more line decisions.

Each line decision must include:

  1. Settlement line key.
  2. Line revision.
  3. Component kind.
  4. Decision kind: paid, unpaid, or partially_paid.
  5. Paid and unpaid amounts.
  6. Source evidence keys.

Frontend must not submit legacy flags such as STATUS_FL, fmembership-pay-status-fl, fis-checked-delivery, or selected-id arrays as authority. Backend rejects those fields recursively.

Authorization uses SpiceDB. Runtime API checks sanmopia/branch_settlement#review for the authenticated actor before writing sanmopia_settlement_component_acknowledgement_decisions.

Operator board projections must expose the latest backend acknowledgement snapshot per settlement line. Frontend may display that snapshot, but must not derive paid/unpaid/partial state from local checkbox values or raw line totals.

Consequences

Section titled “Consequences”

Branch/HQ settlement closeout gains durable actor intent and can distinguish paid, unpaid, and partial amounts per component. Conflict handling can compare line revision keys instead of trusting stale browser state.

Implementation Evidence

Section titled “Implementation Evidence”

Known Gaps

Section titled “Known Gaps”

Stage endpoint proof against self-hosted Supabase and SpiceDB is not current evidence in this audit. Board closeout consumption of recorded component decisions also remains unproven; implementation stays partial.

Revision History

Section titled “Revision History”
  • 2026-07-09: accepted revisioned settlement acknowledgement ledger.
  • 2026-07-10: added pinned implementation evidence and explicit rollout gaps.