PR H: architecture note amendments (§5.1 trust / §9.2 settlement / §4.1 unwind) #12

2026-04-22T09:52:37-07:00

nsatoshi commented

2026-04-22 09:52:37 -07:00

Docs-only. Captures the three normative amendments to the architecture note identified during the CurrenciCombo gap-analysis. Where this document conflicts with the original Draft 1.0 note, this document takes precedence.

Amendments

§5.1 Transaction Coordinator — trust model

Names the operator Workflow Authority; requires SoD between the Coordinator operator, the Identity and Authorization Service (§5.8), and the Ledger Anchor (§5.7); requires signed state transitions verifiable by all participants. CurrenciCombo reference topology: single-party hosted (issuing bank runs the Coordinator). Federated and neutral-utility topologies remain possible without changing the API surface.

§9.2 Commit rule — accepted ≠ settled

Replaces the loose “accepted completion evidence” clause with an explicit whitelist of settlement-grade messages:

pacs.002 status ACSC
camt.025 status ACSC
camt.054 credit notification matching expected EndToEndId + amount + currency
MT910 (credit) / MT900 (debit) with matching ref + amount

ACCP / ACSP / PDNG do not satisfy COMMIT. Transactions sit in VALIDATING until settlement evidence arrives or the settlement-deadline timer expires → ABORTED. Directly wires to PR E's camt parsers and PR B's exception taxonomy.

§4.1 Instrument irrevocability matrix

Acknowledges that an MT760/SBLC is irrevocable under UCP 600 / URDG 758 once the beneficiary's bank has acknowledged it. UNWIND_PENDING is a Coordinator state, not a guarantee that the underlying banking artefact reverses. Two matrices (instrument-leg, payment-leg) map the observable state at ABORTED to the available unwind action (withdraw / recall / counter-guarantee / return payment). Refines the reason payload on the ABORTED → UNWIND_PENDING transition; no state-table change.

Implementation impact (summary)

Each amendment cites concrete follow-up tickets; all are extensions on top of the landed PRs A–G, none regress:

WORKFLOW_AUTHORITY_NAME + JWK URL in orchestrator env (§5.1).
Wire executionCoordinator.validatePlan() to PR E's camt parsers for ACCP/ACSP/ACSC/CRDT discrimination (§9.2).
Add Timing.settlementDeadlineExpired to the Exception taxonomy (§9.2).
Capture instrument-leg + payment-leg observable state in the ABORTED → UNWIND_PENDING reason field (§4.1).
Persist the selected unwind action per the matrix (§4.1).

Series order

A → B → C → D → E → F → G → H (docs).

Base: main. This PR is independent of the A–G stack and can be merged in any order.

Docs-only. Captures the three normative amendments to the architecture note identified during the CurrenciCombo gap-analysis. Where this document conflicts with the original Draft 1.0 note, this document takes precedence. ## Amendments ### §5.1 Transaction Coordinator — trust model Names the operator **Workflow Authority**; requires SoD between the Coordinator operator, the Identity and Authorization Service (§5.8), and the Ledger Anchor (§5.7); requires signed state transitions verifiable by all participants. CurrenciCombo reference topology: single-party hosted (issuing bank runs the Coordinator). Federated and neutral-utility topologies remain possible without changing the API surface. ### §9.2 Commit rule — *accepted ≠ settled* Replaces the loose “accepted completion evidence” clause with an explicit whitelist of settlement-grade messages: - `pacs.002` status `ACSC` - `camt.025` status `ACSC` - `camt.054` credit notification matching expected `EndToEndId` + amount + currency - `MT910` (credit) / `MT900` (debit) with matching ref + amount `ACCP` / `ACSP` / `PDNG` do **not** satisfy COMMIT. Transactions sit in `VALIDATING` until settlement evidence arrives or the settlement-deadline timer expires → `ABORTED`. Directly wires to PR E's camt parsers and PR B's exception taxonomy. ### §4.1 Instrument irrevocability matrix Acknowledges that an MT760/SBLC is **irrevocable under UCP 600 / URDG 758** once the beneficiary's bank has acknowledged it. `UNWIND_PENDING` is a Coordinator state, not a guarantee that the underlying banking artefact reverses. Two matrices (instrument-leg, payment-leg) map the observable state at `ABORTED` to the available unwind action (withdraw / recall / counter-guarantee / return payment). Refines the `reason` payload on the `ABORTED → UNWIND_PENDING` transition; no state-table change. ## Implementation impact (summary) Each amendment cites concrete follow-up tickets; all are extensions on top of the landed PRs A–G, none regress: 1. `WORKFLOW_AUTHORITY_NAME` + JWK URL in orchestrator env (§5.1). 2. Wire `executionCoordinator.validatePlan()` to PR E's camt parsers for ACCP/ACSP/ACSC/CRDT discrimination (§9.2). 3. Add `Timing.settlementDeadlineExpired` to the Exception taxonomy (§9.2). 4. Capture instrument-leg + payment-leg observable state in the `ABORTED → UNWIND_PENDING` `reason` field (§4.1). 5. Persist the selected unwind action per the matrix (§4.1). ## Series order A → B → C → D → E → F → G → **H** (docs). Base: `main`. This PR is independent of the A–G stack and can be merged in any order.

nsatoshi merged commit 6166c48426 into main

2026-04-22 10:13:01 -07:00

nsatoshi deleted branch devin/1776876637-arch-note-amendments

2026-04-22 10:13:04 -07:00

nsatoshi referenced this issue from a commit

2026-04-22 10:13:04 -07:00

PR H: architecture note amendments (§5.1 trust / §9.2 settlement / §4.1 unwind) (#12)

Sign in to join this conversation.

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: d-bis/CurrenciCombo#12