feat: add obligation definitions to protocol

[rockaxorb13]

Description

Addresses Issue #57 "Create Obligation Definitions for triggering responses".

This PR extends the protocol.cto model to include standardized definitions for legal obligations. This standardizes the output of contract triggers, allowing external systems (like Banking APIs or Distributed Ledgers) to programmatically understand required actions (payments, transfers, etc.).

Changes

• Modified model/protocol.cto: Added ObligationStatus enum and concepts:
  • BaseObligation
  • PaymentObligation
  • OwnershipTransferObligation
  • EscrowReleaseObligation
  • AccessControlObligation
• Updated TriggerResponse: Now includes an optional obligations array to emit these events.
• Regenerated Artifacts: Ran npm run build to update openapi.json and client/typescript/apap.ts.

Verification

• Ran npm run build successfully.
• Verified openapi.json contains the new schema definitions (e.g., PaymentObligation).

[github-actions]

This PR is stale because it has been open 15 days with no activity. Remove stale label or comment or this will be closed in 10 days.

[rockaxorb13]

Be gone, bot.

…

On Sat, 14 Feb 2026, 07:50 github-actions[bot], ***@***.***> wrote: *github-actions[bot]* left a comment (accordproject/apap#89) <#89 (comment)> This PR is stale because it has been open 15 days with no activity. Remove stale label or comment or this will be closed in 10 days. — Reply to this email directly, view it on GitHub <#89 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AYXRV6YLBNVUHNPLZHAWYUL4L2BAXAVCNFSM6AAAAACTK47EJGVHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMZTSMBQGQ3TIMZTG4> . You are receiving this because you authored the thread.Message ID: ***@***.***>

[dselman]

This requires more discussion with the legal folks in the WG and taking into account the existing Obligations defined in https://models.accordproject.org/cicero/runtime@0.2.0.html

Before we move into implementation lets create a separate CTO file with the proposed obligations and present/validate with the WG.

[github-actions]

This PR is stale because it has been open 15 days with no activity. Remove stale label or comment or this will be closed in 10 days.

[niallroche]

I have started a document as a basis for discussion at https://docs.google.com/document/d/15vtcLDK4ymJ17q4w4Rd3N1hCJdSZ6mlH/edit?usp=share_link&ouid=112259737190306437667&rtpof=true&sd=true

[github-actions]

This PR is stale because it has been open 15 days with no activity. Remove stale label or comment or this will be closed in 10 days.

[rockaxorb13]

Be gone, bot.

…

On Fri, 17 Apr 2026, 07:52 github-actions[bot], ***@***.***> wrote: *github-actions[bot]* left a comment (accordproject/apap#89) <#89 (comment)> This PR is stale because it has been open 15 days with no activity. Remove stale label or comment or this will be closed in 10 days. — Reply to this email directly, view it on GitHub <#89 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AYXRV64BATPTMR4LEK74ODD4WGIOPAVCNFSM6AAAAACTK47EJGVHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHM2DENRUHAZDQNRUGM> . You are receiving this because you authored the thread.Message ID: ***@***.***>

[github-actions]

This PR is stale because it has been open 15 days with no activity. Remove stale label or comment or this will be closed in 10 days.

[github-actions]

This PR is stale because it has been open with no activity. Remove the stale label or comment to keep it active. Only items with maintainer engagement are auto-closed.

[JayDS22]

Doing a pass on stale PRs from a GSoC-contributor angle. Flagging where this stands so it can move forward productively rather than sit under the stale bot.

Unaddressed maintainer feedback

• @dselman requested changes on 2026-03-11 asking for two things: (a) put the proposed obligations in a separate CTO file rather than editing model/protocol.cto inline, and (b) reconcile against the existing runtime obligations at https://models.accordproject.org/cicero/runtime@0.2.0.html before implementation. Neither is done in the current diff. The new concepts are still inline at model/protocol.cto:220-278 and there is no reference to the runtime model.
• @niallroche shared a discussion doc on 2026-04-01. If that doc has landed on decisions since, they would need to be reflected here.

Direction has moved since this PR opened

Since January, Issue #183 has developed a clearer position on how identity should be modeled: obligationRef with VC-backed provenance, did:web/did:key for parties, and Sanket noted a Tech WG discussion is starting on this. Every party field in this PR is a bare String (debtor, creditor, grantee, escrowAgent, currentOwner, newOwner), which would need to be revisited once the WG lands on an identifier shape. Not something to fix now, but worth naming so the review scope is clear.

Other notes

• ObligationStatus has 11 states including RESOLVED_WITH_ADJUSTMENT / SUPERSEDED / PARTIALLY_FULFILLED. Each one is a downstream compatibility commitment. Trimming to the states the WG actually needs at v1 would be lower risk.
• TriggerResponse.obligations is typed as BaseObligation[] but BaseObligation is abstract. The generated openapi.json handles this via anyOf over the concrete subtypes, worth confirming the TS client validates against the same set.
• Missing trailing newline on model/protocol.cto.

Rebase scope is smaller than it looks

model/protocol.cto on main has not been touched since 81a9e4c (2025-07-08), so the source-file rebase is trivial. The 13k/11k line delta is entirely regenerated artifacts (openapi.json, client/typescript/apap.ts, index.md, _site/index.html) that have drifted through months of unrelated PRs. Standard fix: rebase model/protocol.cto only, drop the stale generated files from the branch, then re-run npm run build and commit whatever regen produces.

Suggested productive path while WG discussion continues

Since you're still active on #204, and the blocking design question sits with the Tech WG, the highest-value work here is probably:

1. Move the new concepts into a separate CTO file per @dselman's request.
2. Add a short comparison table in the PR body: which fields are carried over from runtime@0.2.0, which are new, which are dropped, and why.
3. Leave party fields as String for now but note in the PR body that they are the join point for the DIDs and Verifiable Credentials as the Identity and Verification Substrate for Accord Project [Contract Governance] #183 identity work, so reviewers can see the seam.

Points 1 and 2 are inside the PR's original scope and would let the WG conversation converge on a concrete diff rather than a proposal.

[JayDS22]

Circling back: my Jul 25 comment flagged @dselman's Mar 11 change-request (put obligations in a separate CTO file, reconcile against the current model) as the outstanding blocker on this PR. It has now been ~4 months without an update from either author (@rockaxorb13) or maintainer side, and the PR remains conflicting with the current model/protocol.cto shape after the recent slice landings (#211, #213, #214, #216).

Applying the maintainer stale-PR policy (1-week grace from this nudge). If there's no author response by 2026-08-07, I'll evaluate taking this over: (a) refactor the obligation definitions into a separate CTO file per @dselman's Mar 11 request, (b) reconcile against the current TriggerResponse shape, (c) open a replacement PR attributing original framing to @rockaxorb13.

@rockaxorb13 if you're still active on this and want to drive it, a quick response here (even just "still on it") pauses the takeover clock. Otherwise no reply = takeover proceeds Aug 7.

---

EDIT (2026-08-02): Retracted, see the follow-up retraction comment. @rockaxorb13 was hospitalized during this window; the Aug 7 deadline (later tightened to Aug 3 in a subsequent amendment, also retracted) was posted without that context. No takeover clock is being enforced. Take the time you need.

[JayDS22]

Amending the deadline: 2026-08-03 (Sun) instead of Aug 7. Bringing this in line with the other two stale-PR nudges this week and the maintainer directive to clear backlog faster.

Same terms otherwise: a response from you pauses the clock; silence past Sunday triggers takeover with attribution via Co-authored-by: trailer.

---

EDIT (2026-08-02): Retracted, see follow-up comment below. @rockaxorb13 was hospitalized during this window; the deadline was posted without that context. No clock is being enforced. Take the time you need.

[JayDS22]

Just saw your Aug 2 update on #204: welcome back, glad you're okay. Retracting the Aug 3 takeover deadline; that was posted without the hospital context.

Take the time you need. #89 is not on any critical path. Focus on #204 and any active work first; #89 can wait until you're fully back on your feet, whenever that is. If you decide you don't want to drive #89 to landing, a note here works and someone can pick it up down the line. No clock either way.

[rockaxorb13]

Thank you so much!! And yes after I finish my work there, with the template retrieval I definitely will get back to this.