Skip to content

Codex/obligation 1.0 models - #196

Open
niallroche wants to merge 2 commits into
accordproject:mainfrom
niallroche:codex/obligation-1.0-models
Open

Codex/obligation 1.0 models#196
niallroche wants to merge 2 commits into
accordproject:mainfrom
niallroche:codex/obligation-1.0-models

Conversation

@niallroche

Copy link
Copy Markdown
Contributor

Closes accordproject/apap#57

Introduces reviewable 1.0 obligation models based on the working-group proposal. The PR separates durable obligation state, lifecycle transition events and operational fulfilment attempts, and adds settlement and evidence as the first extension profile.

Changes

  • Add org.accordproject.obligation@1.0.0 with:
    • an identified, abstract Obligation asset;
    • explicit ObligationTransition events;
    • separate ObligationStatus and FulfilmentAttemptStatus lifecycles;
    • portable PartyRef and hash-bound AgreementRef provenance;
    • exact payments using money@1.0.0.PreciseAmount;
    • payment, performance, notification, remediation, evidence and mitigation obligation types; and
    • revision, authority, basis, evidence and supersession references.
  • Add org.accordproject.obligation.settlement@1.0.0 with:
    • explicit payment, refund and penalty-adjustment directions;
    • reproducible derivation and evaluation records;
    • rail-neutral settlement proof; and
    • immutable, hash-linked evidence records for pending, settled, reversed and disputed stages.
  • Preserve runtime@0.2.0.Obligation and obligation@0.2.0 unchanged for compatibility.
  • Validate both models with Concerto 4.1.5 alongside crypto@1.0.0 and money@1.0.0.

Flags

  • Representation decision: confirm that an obligation should be a durable identified asset, with authoritative lifecycle changes represented by ObligationTransition events.
  • Lifecycle decision: confirm that legal obligation status remains separate from operational fulfilment-attempt status.
  • Core-scope decision: confirm the base obligation and six reusable subtypes as the 1.0 core, while keeping specialised agent and AI-governance taxonomies outside it.
  • Profile decision: confirm settlement and evidence as the first extension profile.
  • Lifecycle rules: allowed transitions, terminal states, authorised actors, effective-time rules and the meaning of breach must be agreed before publication.
  • Settlement rules: canonical unit scales, non-ISO asset identifiers, amount constraints and hashing test vectors must be normative before publication.
  • Migration: a normative mapping from the legacy event-only obligation model is still required.
  • Repository ownership: reusable vocabulary belongs in accordproject/models; APAP TriggerResponse changes should be handled separately in the APAP repository.
  • This PR does not create byte-identical contract@1.0.0 or runtime@1.0.0 models solely for numerical alignment.
  • This PR does not duplicate the signature work in feat(signature): add org.accordproject.signature@1.0.0 #195. Evidence-to-signature binding can follow once its verification semantics are settled.
  • The two commits currently require DCO sign-off before merge.

Screenshots or Video

Not applicable. This PR contains Concerto model changes only.

Related Issues

Author Checklist

  • Ensure you provide a DCO sign-off for your commits using the --signoff option of git commit.
  • Vital features and changes captured in unit and/or integration tests
  • Commits messages follow AP format
  • Extend the documentation, if necessary
  • Merging to main from niallroche:codex/obligation-1.0-models

Signed-off-by: Niall Roche <niall.roche@gmail.com>
Signed-off-by: Niall Roche <niall.roche@gmail.com>
@niallroche
niallroche force-pushed the codex/obligation-1.0-models branch from d97595e to e90c2f9 Compare August 19, 2026 21:23
mttrbrts added a commit that referenced this pull request Aug 27, 2026
Builds on the contract, runtime and obligation 1.0 models from #197, #198
and #196, which are included here unchanged as the commits beneath this
one. This commit is the delta: it keeps their type inventory and reworks
the structure underneath it.

This is a design target, not a migration-ready change. It settles the
structural questions that a stable 1.0 release needs answered, so that the
answers can be reviewed together rather than one PR at a time.

- Rename contract@1.0.0 to agreement@1.0.0, and model an agreement as a
  set of documents rather than a single instrument, so that a master
  agreement with schedules and confirmations is expressible.
- Add party@1.0.0 defining Party and its portable PartyRef projection, so
  the 1.0 family has one party representation instead of three.
- Address clause instances by TemplateMark instance path in a map, rather
  than by a static tree, since clause instances are data-driven: a list
  block yields one instance per element and a conditional may yield none.
- Carry template data by composition in TemplateData rather than by
  subclassing the agreement envelope, so the envelope's type and its
  relationship URIs stay stable across template versions.
- Hold runtime state as one revisioned document per agreement, with
  per-clause state keyed by the same instance paths.
- Point obligation@1.0.0 at the shared PartyRef and AgreementReference in
  place of its local equivalents.

contract@1.0.0 is deleted rather than kept alongside agreement@1.0.0.
Model URLs are permanent, so it must never be published if this direction
is taken: a dead namespace is worse than the rename.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Signed-off-by: Matt Roberts <code@rbrts.uk>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Create Obligation Definitions for triggering responses

1 participant