Draft: explore v1.2 return and reversal alignment in reference server

[Raafet57]

Draft note for Tom

Hi Tom,

I am keeping this as a draft PR, not a request for immediate merge.

I wanted to keep the work on a separate branch while giving you something concrete and executable to inspect. My goal is to test whether my reference-server and conformance work can line up with your upstream instruction-api-v1.2.yaml direction, especially the return and reversal paths, without presenting it as a competing standard or forcing a merge decision before the semantics are agreed.

Branch under test: Raafet57:feat/demo-frontend

What I tried to accomplish

My fork already had an executable reference stack around instruction submission, execution and finality evidence, reporting, webhooks, and an exception-family model for investigations and returns.

When I compared that with your upstream v1.2 instruction API, the main gap was that my fork still exposed its own exception-family surfaces while your spec now defines canonical instruction-level paths:

• POST /instruction/{instructionId}/return
• POST /instruction/{instructionId}/reverse
• GET /instruction/{instructionId}/reversal-status

So this draft PR tries to make my fork behave as an executable stress test of your v1.2 shape:

1. Adopt your paths as the public surface.

   The reference server now implements the three v1.2 paths above so a reviewer can inspect behavior through your API shape, rather than through a separate return/reversal API.

2. Map those paths onto the existing exception-family runtime.

   The existing RETURN, investigation, and operator-audit machinery remains the backing model, but Tom v1.2 requests are marked and shaped so the public contract follows your API.

3. Keep on-chain finality semantics honest.

   The implementation does not mutate or rewrite the original final instruction. A final on-chain payment remains final. Any remediation happens through a new compensating instruction or a reversal-request workflow.

4. Create executable evidence instead of only documentation.

   The tests exercise successful and negative cases against the reference server, including response shapes, validation, duplicate active return/reversal protection, and the rule that REVERSAL requests do not leak through the legacy /exceptions/returns list/detail routes.

What changed in this branch

POST /instruction/{instructionId}/return

I implemented this as a compensating-return flow:

• validates a Tom-style ReturnRequest;
• requires the original instruction to exist and be FINAL;
• creates a real compensating instruction with its own instruction id and UETR;
• records a Tom-origin RETURN case in the existing exception-family store;
• returns a CompensatingInstructionResponse-style body:
  • compensating_instruction_id
  • compensating_uetr
  • original_instruction_id
  • optional return_identification
  • status: PENDING
  • accepted_at

POST /instruction/{instructionId}/reverse

I implemented this as a reversal request, not a literal chain undo:

• validates a Tom-style ReversalRequest;
• requires the original instruction to exist and be FINAL;
• records a Tom-origin REVERSAL exception-family case in REQUESTED state;
• does not invent or return a compensating instruction while the request is only REQUESTED;
• returns a ReversalRequestResponse-style body.

GET /instruction/{instructionId}/reversal-status

I implemented this as the polling fallback/status read:

• returns the latest reversal request for that original instruction;
• uses the upstream ReversalRequestStatus field set;
• omits compensating-instruction fields while status remains REQUESTED.

Legacy exception-family guardrail

/exceptions/returns list/detail now filters out REVERSAL cases so a reversal request does not appear as an ordinary return case in my existing fork-specific surfaces.

Verification performed

Local verification on the branch:

• cd reference-server && npm ci && npm test passed during the reconciliation pass.
• cd reference-server && npm test reported 56 passed / 0 failed after final patches.
• git diff --check passed.
• Docs/static sanity check passed.
• Independent Codex review of the final diff reported APPROVED, with no blockers and no non-blocking notes.

Things where I need your guidance

These are the points I wanted surfaced explicitly rather than hidden in implementation detail.

1. Does reverse mean the right thing for irreversible on-chain settlement?

The draft implementation treats reverse as a request/compensation workflow. It deliberately does not imply that the original on-chain transfer can be unwound.

Questions for you:

• Is reverse the term you want to keep in the public API, with this compensating-flow discipline explained in the spec?
• Or should the naming or body text make the compensating nature more explicit?

2. ISO 20022 alignment: pacs.004, pacs.007, camt.056, camt.029

This draft treats:

• /return as closest to a pacs.004-like compensating return/remediation flow;
• /reverse as following your v1.2 reversal request/status framing;
• investigation, cancellation, and status-request ideas as related, but not expanded here.

Questions for you:

• Do you want the reference implementation to lean harder into pacs.007 for /reverse?
• Or should some of this sit nearer camt.056 / camt.029 style investigation and cancellation flows?

3. Should status-request exist in this phase?

My fork had ideas around status and investigation surfaces, but this PR intentionally does not add a status-request path.

Questions for you:

• Should status-request disappear from this contribution entirely?
• Should it become a later-phase exception/investigation feature?
• Or do you see it belonging in the same v1.2 instruction API family?

4. Is the exception-family backing model useful or too fork-specific?

This branch keeps the exception-family model as the internal backing store because it gives the reference server auditability and operator workflow without changing the public Tom v1.2 path names.

Question for you:

• Is that useful implementation evidence, or would you rather see a thinner reference implementation that mirrors the OpenAPI shapes more directly?

5. Should this branch be split further before any merge consideration?

This draft branch also contains my earlier static demo frontend commit. If you want to review only the v1.2 reconciliation, I can keep this as a draft and split the work into a narrower branch/PR.

Questions for you:

• Would you prefer this to stay as a separate draft/reference branch only?
• Or should I prepare a cleaner, narrower PR with just the v1.2 return/reversal reference-server changes?

Suggested review posture

Please treat this as a concrete proposal and discussion artifact:

• not a demand to merge;
• not an alternate standard;
• not a claim that all ISO semantics are settled;
• just executable evidence showing one way my reference work could align with your v1.2 API direction.

If the direction is useful, I can tighten the branch based on your answers. If not, I can keep it separate as a draft branch and avoid merging it upstream.

[tomalaerts-dev]

Hi Raafet,
Thanks for putting this together. Concrete executables are much more useful than design-by-discussion alone, I am impressed.
On your specific questions:
Reverse/return terminology. Keep these. pacs.004 and pacs.007 are the recognised names in the industry; keeping them preserves dictionary recognition while the spec description block handles the compensating-transaction practicalities.
pacs vs camt alignment. /reverse is pacs.007-aligned and should stay there. camt.056 only works pre-broadcast, which on a public chain is essentially zero window. pacs.007 is the message designed for post-settlement remediation, hence current alignment is right.
Status-request and the broader exception/investigation family. Reading questions 3 and 4 together, I think you are looking at the same question from two angles: how should pacs.crypto handle the broader exception, investigation, and request-for-information topics, and how should that align with what you already have running?
Well, this area is on the roadmap but not yet designed. Pure status-request is already covered by GET /instruction/{instructionId} and does not need its own path. The richer investigation flows (camt.026/027/087 analogues, request-for-information, exception cases that need operator workflow rather than just a status read) are interesting, and I want to come to them with a clear architectural view. The questions I need to resolve first include whether this sits as an extension to an existing spec or as a new Investigation API, how it relates to the Travel Rule and Instruction APIs, and what the flow looks like when one VASP requests information from another.
That your fork already has an exception-family layer in working order is definitely useful input when I get to that design work. I would not want to lock in the details already, but having your running implementation of that workflow is useful for making design ideas more concrete than starting from a blank page. I suggest: keep your current exception-family machinery as is in the reference server for now, and we revisit alignment when the spec discussion catches up to that area.
Branch structure. Keep it as a draft for now. A draft branch in your fork is the right home until we have a clearer governance model for how reference implementations relate to the spec repo. When that question matures, a narrower focused PR with just the v1.2 work is the path forward.
This is the kind of contribution that moves spec adoption forward. Working reference implementations make the difference between a spec people read and a spec people use. Happy to keep iterating on the design questions as the spec evolves.
Best,
Tom

[Raafet57]

Hi Tom,

Thanks a lot, this is very helpful.

I agree with the direction: keep the current exception-family machinery in the reference server for now, without trying to lock it into the spec too early. That gives us something concrete to test ideas against while the broader investigation/API design matures.

One thing I would like to set up next is something more visual around the flows. Not just code and YAML, but a simple way to see the lifecycle:

• instruction creation
• Travel Rule enrichment
• status readback
• return/reversal path
• exception or investigation path
• where pacs.004, pacs.007, camt.056, and future camt-style investigation flows fit

My thinking is that a visual reference, maybe sequence diagrams or a lightweight interactive flow map, would make the design discussion much easier. It could show what is already implemented, what is intentionally draft, and what is still open for future spec work.

What do you think? Would that be useful from your side, and is there a visual format you would prefer for this kind of spec/reference implementation discussion?

Best,
Raafet

[tomalaerts-dev]

Hi Raafet.
Regarding a diagram, yes, I have been thinking similarly. Now I did have a flow illustration in my latest article and I thought to expand and simplify at the same time, as I add something new (probably E&I and liquidity management first)

[Raafet57]

Hi Tom, thanks, that makes sense.

I started turning this into a visual reference rather than adding more API shape into the PR. The direction I am testing is:

• keep the main lifecycle narrow: bank, sending VASP, chain, receiving VASP, status and finality
• keep pacs.004 and pacs.007 terminology visible for return and reversal alignment
• treat camt.056 as pre-broadcast only
• leave the richer investigation family (camt.026, camt.027, camt.087, RFI/operator flows) as draft/reference-server discussion material, not as something locked into the spec

I also mocked up a short visual flow/video locally to test whether this helps reviewers orient before reading the YAML. I will keep this PR as draft and avoid expanding the normative surface here. If the visual direction is useful, I can tighten it into a narrower v1.2-oriented artifact next, especially around E&I and liquidity management once you have the direction you want there.

[Raafet57]

Hi Tom,

Small fix: GitHub was not displaying the first MP4 nicely in the file viewer, so I added a lightweight 720p review copy as the primary video link.

For now, here are the two lightweight review assets:

• MP4 preview, lite copy: https://github.com/Raafet57/pacs.crypto/blob/efb722da645ce27ecb7a2acc9e0afab03498a6ef/videos/visual-flow-map-narrated/renders/pacs-crypto-visual-flow-tom-preview-narrated-lite.mp4
• Direct download if GitHub's viewer is awkward: https://raw.githubusercontent.com/Raafet57/pacs.crypto/efb722da645ce27ecb7a2acc9e0afab03498a6ef/videos/visual-flow-map-narrated/renders/pacs-crypto-visual-flow-tom-preview-narrated-lite.mp4
• Screenshot:

I also kept docs/visual-showcase.html in the branch as the richer artifact, with the clean cut, narrated cut, lite review copy, and the supporting flow notes grouped together:

https://github.com/Raafet57/pacs.crypto/blob/efb722da645ce27ecb7a2acc9e0afab03498a6ef/docs/visual-showcase.html

If this visual direction is useful, I can keep the PR as draft and later make a small GitHub Pages preview from my fork, separate from any normative spec changes.

[Raafet57]

Hi Tom,

I tightened the visual/reference artifacts on this draft branch around the lifecycle boundary we discussed.

What changed:

• Added reversal-status wherever the reversal visual appears: POST /instruction/{instructionId}/reverse plus GET /instruction/{instructionId}/reversal-status.
• Updated the root SVG labels to exact endpoint wording.
• Aligned the render README commands with the canonical tom-preview assets.
• Pruned the older draft MP4 renders, leaving the three canonical preview files.

Review assets:

• Clean MP4: https://github.com/Raafet57/pacs.crypto/blob/d1d0270e0c64f35dac2ceacd742252c22a467ed6/videos/visual-flow-map/renders/pacs-crypto-visual-flow-tom-preview.mp4
• Narrated MP4: https://github.com/Raafet57/pacs.crypto/blob/d1d0270e0c64f35dac2ceacd742252c22a467ed6/videos/visual-flow-map-narrated/renders/pacs-crypto-visual-flow-tom-preview-narrated.mp4
• Lite 720p MP4: https://github.com/Raafet57/pacs.crypto/blob/d1d0270e0c64f35dac2ceacd742252c22a467ed6/videos/visual-flow-map-narrated/renders/pacs-crypto-visual-flow-tom-preview-narrated-lite.mp4
• Review showcase: https://github.com/Raafet57/pacs.crypto/blob/d1d0270e0c64f35dac2ceacd742252c22a467ed6/docs/visual-showcase.html
• Visual flow note: https://github.com/Raafet57/pacs.crypto/blob/d1d0270e0c64f35dac2ceacd742252c22a467ed6/docs/visual-flow-map.md

I am still treating these as non-normative discussion aids for the draft PR. They do not add API scope, and the E&I/investigation lane remains draft/TBD. If this visual direction works, the next pass can stay focused on E&I and liquidity-management framing.