d-bis/CurrenciCombo
4
0
Fork 0
Code Issues Pull Requests 9 Actions Packages Projects Releases Wiki Activity

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

Merged
nsatoshi merged 1 commits from devin/1776876637-arch-note-amendments into main 2026-04-22 17:13:01 +00:00
Conversation 0 Commits 1 Files Changed 1 +236
nsatoshi commented 2026-04-22 16:52:37 +00:00
Owner
Copy Link

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.

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 added 1 commit 2026-04-22 16:52:38 +00:00
PR H: architecture note amendments (\u00a75.1 trust, \u00a79.2 settlement, \u00a74.1 unwind)
Some checks failed
Code Quality / SonarQube Analysis (pull_request) Failing after 21s
Details
Code Quality / Code Quality Checks (pull_request) Failing after 6s
Details
Security Scan / Dependency Vulnerability Scan (pull_request) Failing after 4s
Details
Security Scan / OWASP ZAP Scan (pull_request) Failing after 4s
Details
e15aa11417 
Three normative amendments identified during the gap-analysis and now
captured as a standalone doc. Each amendment cites the implementation
impact on PRs A-G and lists follow-up tickets that extend (not regress)
the already-landed code.

\u00a75.1 Transaction Coordinator trust model:
  - names the operator the Workflow Authority
  - requires SoD between Coordinator operator, Identity service, and
    Ledger Anchor
  - requires signed state transitions verifiable by participants
  - CurrenciCombo ref topology: issuing bank runs it (single-party
    hosted); federated and neutral-utility topologies are future work
    and can swap in without changing the API.

\u00a79.2 Commit rule (accepted != settled):
  - enumerates the exact SWIFT/ISO-20022 messages that count as
    settlement: pacs.002 ACSC, camt.025 ACSC, camt.054 CRDT,
    MT910/MT900
  - ACCP/ACSP/PDNG do NOT satisfy COMMIT; stay in VALIDATING until
    settlement evidence or timer expiry -> ABORTED
  - wires explicitly to PR E's camt parsers + PR B's exception taxonomy.

\u00a74.1 Instrument irrevocability matrix:
  - UNWIND_PENDING is a Coordinator state, not a guarantee the
    underlying banking artefacts reverse
  - separate instrument-leg and payment-leg matrices based on
    observable progress (dispatched / acknowledged / accepted /
    settled)
  - irrevocable once instrument.acknowledged; only remaining control
    plane actions are accelerated expiry, counter-guarantee, or
    legal discharge
  - refines the reason payload on ABORTED -> UNWIND_PENDING; no
    transition-table change.

Lands docs-only; no code change. Implementation follow-ups enumerated
in "Summary of downstream tickets".
nsatoshi merged commit 6166c48426 into main 2026-04-22 17:13:01 +00:00
nsatoshi deleted branch devin/1776876637-arch-note-amendments 2026-04-22 17:13:04 +00:00
Sign in to join this conversation.
Reviewers
No Reviewers
Labels
No items
No Label
Milestone
No items
No Milestone
Projects
Clear projects
No project
Assignees
Clear assignees
70rn4710n A.r.yavari SEG nsatoshi
No Assignees
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: d-bis/CurrenciCombo#12
Delete Branch "devin/1776876637-arch-note-amendments"

Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?