feat(agreement): 1.0 agreement, party and runtime models

[mttrbrts]

Closes #N/A

Proposes the 1.0 family of Accord Project models: an agreement is a set of documents rather than a single instrument, a template is identified independently of anything created from it, and the types a template extends are held apart from the envelopes that carry them.

This is a design target, not a migration-ready change. It exists so the structural questions behind a stable 1.0 release can be reviewed as a whole rather than one namespace at a time. It builds on #197, #198 and #196, whose commits are included beneath it.

The namespaces

namespace	holds	imports	Concerto
templatedata@1.0.0	TemplateData, StateData	nothing	^3.0.0
party@1.0.0	Party, PartyRef	nothing	^3.0.0
template@1.0.0	TemplateReference, TemplateArtifact, TemplateArtifactRole	crypto	^3.0.0
agreement@1.0.0	Agreement, AgreementDocument, Clause, Clauses, AgreementParty, AgreementReference	crypto, templatedata, party, template	^4.0.0
runtime@1.0.0	Request, Response, AgreementState, ClauseStates	crypto, templatedata, agreement	^4.2.0
obligation@1.0.0	Obligation and its subtypes, ObligationTransition, FulfilmentAttempt	crypto, money, party, agreement	^4.0.0
obligation/settlement@1.0.0	SettlementObligation, SettlementEvidence, and the evidence concepts	crypto, party, obligation	^4.0.0

The Concerto floors follow the map types: only agreement and runtime declare one. runtime needs 4.2.0 specifically because both the declared value type of ClauseStates and the concrete types an instance carries are imported from other namespaces.

agreement@1.0.0 replaces the contract@1.0.0 namespace proposed in #197.

An agreement is a set of documents

A master agreement with schedules and confirmations is one agreement recorded across several instruments. Agreement holds an ordered list of AgreementDocument, each of which may bind its own subset of the parties and may be generated from its own template — or from none, where an instrument binds sub-templates per clause without a document-level template of its own.

Clause instances are addressed by instance path

AgreementDocument.clauses is a map keyed by the TemplateMark instance path of each clause: payment, or deliveries[2].inspection. A static clause tree cannot express this, because the number of instances is decided by the data — a ClauseDefinition inside a ListBlockDefinition yields one instance per element, and one inside a ConditionalDefinition may yield none.

The path is held only in the map key. Clause carries no path property, so there is one statement of it and no invariant tying two copies together.

The map records sub-template archives composed into a document, not the document's clause structure. An inline {{#clause}} block, written in the parent grammar and composing no separate archive, gets no entry — a document whose clause blocks are all inline has no clauses map rather than an empty one. This is why Clause.template is required.

CiceroMark remains authoritative for document structure. This model records provenance over it and does not restate it.

Template data is carried by composition

A template declares one concrete subtype of templatedata@1.0.0.TemplateData holding its instantiated variables, and that subtype is carried in AgreementDocument.data. A template no longer subclasses the agreement envelope, so the envelope's type and its relationship URIs stay stable across template versions.

The data of a clause is a subtree of its document's data, addressed by the clause's instance path. A clause carries no copy of its own. Instance paths are rooted at the data rather than at the document, so a clause bound to the paymentTerms property has the path paymentTerms and never data.paymentTerms.

The template root is found by its parent type

Extending TemplateData is what declares a template's data. A template's model holds exactly one concrete subtype of it, and that subtype is the renderable root. No @template decorator marks it: the supertype already carries that meaning, and an annotation restating it is a second statement of the same fact that nothing keeps in agreement with the first. Types the data is composed of stay ordinary concepts; only the root extends TemplateData. StateData is resolved the same way.

The root must be the data and not an envelope, and that is a hard constraint rather than a preference: markdown-template resolves clause and with blocks with getOwnProperty, which does not walk supertypes, so {{#with data}} on an empty subclass of an envelope never resolves. Plain variables resolve through inheritance; block constructs do not.

Runtime state is one revisioned document per agreement

AgreementState is a single identified, revisioned snapshot covering the agreement and every clause instance in it, with clauseStates keyed by the same instance paths as AgreementDocument.clauses. A transition spanning scopes — marking a clause breached because of a condition detected in a peer clause — is then one write producing one revision and one hash, with sibling state in scope without a further lookup. Per-clause state assets would need a cross-asset transaction Concerto does not provide, and would leave revision and previousStateHash without a well-defined meaning.

AgreementState is registry-resident, and intentionally so. It holds a relationship to its Agreement rather than the portable AgreementReference that obligations and settlement evidence use, because a revision counter and a previous-state hash chain are only meaningful where successive revisions resolve against one another. Records that must travel standalone reference an agreement portably; state does not travel, so it does not need to. This mirrors the Party / PartyRef distinction.

templatedata@1.0.0 holds only what templates extend

TemplateData and StateData are empty abstract concepts, and they are the two types every template subclasses. Holding them in a namespace that imports nothing means declaring the shape of a template's own data does not drag in the agreement envelope, the state envelope, or the party and hash types those carry.

The template quoted under Engine compatibility below is the whole of the effect: it declares concerto version "^3.0.0", and its imports are templatedata@1.0.0, runtime@0.2.0 and money@0.3.0 — no agreement, no crypto, no party, and no Concerto 4 floor, because the map types requiring it are in the consumers rather than the extension points.

template@1.0.0 is independent of agreements

A template is cited by records that hold no agreement — obligations, attestations and settlement evidence all name the template an artefact derives from, and a registry may catalogue templates with no agreement in sight. template@1.0.0 imports only the hash types, so naming a template does not require taking on the agreement model.

TemplateReference.templateId names the template rather than the reference. The type is deliberately not Concerto-identified, so templateId carries no identity semantics of its own, and its syntax remains deferred to a profile.

One party representation

party@1.0.0 defines Party, which is registry-resident, and PartyRef, a portable projection for records that must travel standalone and cannot assume a resolver. The 1.0 family uses these two throughout, in place of the three representations in use today (--> Party, obligation's local PartyRef, signature's Signatory).

PartyRef deliberately carries no role. A role is a property of an act, not of a party: the same party may sign in different roles on different documents. Role therefore belongs on AgreementParty for a party's role under an agreement, and on an attestation for the capacity in which a signature was given.

Template data should name parties with PartyRef rather than a relationship to Party. Data reaches contract logic as a serialized value with no resolution step, where a relationship arrives as an unresolvable "resource:...#me" string.

Hashes are optional and their canonicalization is deferred

Agreement.agreementHash, AgreementDocument.documentHash, AgreementState.stateHash and AgreementReference.agreementHash are optional, and these models do not define how the bytes they commit to are produced. Two implementations hashing the same agreement under different canonicalization rules would both be conformant, so a hash is meaningful only under a profile that fixes those rules.

The properties are optional rather than required because optional-to-required is the breaking direction and this family publishes permanently: a profile can tighten what the core model leaves open, and nothing can loosen it afterwards. Where a hash is supplied, its crypto@1.0.0 Canonicalization should be populated, so a verifier can tell which discipline produced it rather than having to assume one. CanonicalizationType already carries RFC8785_JCS.

Engine compatibility

Measured against unmodified cicero-core@2.1.1 and template-engine@4.0.0.

Composition renders. A concept that extends templatedata@1.0.0.TemplateData rather than an agreement asset, with nested clauses that are plain concepts, loads, validates and renders with no change to the render path:

templateModel: test.msa4@1.0.0.MsaData | super: org.accordproject.templatedata@1.0.0.TemplateData
requestTypes: [ 'org.accordproject.runtime@0.2.0.Request', 'test.msa4@1.0.0.FeeRequest' ]
sample validates: OK
--- RENDER ---
Agreement with Acme Corporation for a fee of 15000.0 USD.
Confidentiality. Term of 5 years.

Neither half of the engine requires Contract or Clause inheritance. {{#clause X}} resolves property X on the current model and recurses, and nothing in the render path depends on the envelope.

Finding the template root needs a cicero-core change. That measurement was taken with @template still on the data concept, which is how findTemplateConcept locates the renderable root today: it looks for exactly one non-abstract declaration carrying the decorator. This design no longer uses it, so the root has to be resolved by parent type instead. Until that ships, a template written to this design has no root the published engine can find. Fixed by accordproject/template-archive#946.

Concerto 4 is not a consumer-side constraint. cicero-core@2.1.1 and template-engine@4.0.0 both already bundle concerto-core@4.1.4, and map-bearing models load and render today. runtime@1.0.0's 4.2.0 floor is real but confined to it: on 4.1.4 an AgreementState carrying template-defined clause states fails to serialize, and on 4.2.0 the same instance round-trips with every key and $class preserved (accordproject/concerto#1279).

Adopting runtime@1.0.0 needs the same change. Template resolves the runtime base types by fully-qualified name against runtime@0.2.0, and getType() throws when a namespace is absent, so a template on a 1.0 runtime namespace cannot be opened at all. This is version-bump coupling that lands on any runtime@1.0.0, including the conservative promotions in #198 and #199. Also fixed by accordproject/template-archive#946.

Landing order

Publish order is a hard chain, since the build resolves imports over HTTP:

templatedata → party → template → agreement → runtime → obligation → obligation/settlement

templatedata, party, template, agreement, obligation and obligation/settlement can land and publish independently of the engine. Templates adopt the 1.0 data shape while keeping runtime@0.2.0 for Request and Response.

runtime@1.0.0 should follow the release of accordproject/template-archive#946. Publishing it earlier creates a namespace no template can adopt, and model URLs are permanent.

For the same reason contract@1.0.0 must never be published if this direction is taken. A dead namespace is worse than the rename.

Migration cost

Measured against the 37 active templates in accordproject/cicero-template-library. The library's other 20 carry "archived": true and are excluded from its index page by run.js, so they are excluded here too.

what changes	active templates affected	needs an engine change?
asset TemplateModel extends Contract|Clause becomes concept … extends TemplateData	37 of 37	yes — template-archive#946
@template is dropped; the root is found by its TemplateData supertype	37 of 37	yes — template-archive#946
extends Clause has no direct analogue; a standalone clause template becomes a document with data	22	no
extends runtime@0.2.0.Obligation (an event) becomes an obligation@1.0.0 asset	16	no
extends State becomes extends StateData, composed rather than subclassed	10	yes — template-archive#946
extends Request / extends Response — unchanged	32 / 31	n/a

Every active template subclasses Contract or Clause, so the inheritance-to-composition change reaches all of them without exception. The edit itself is mechanical, but it is no longer one today's engine accepts unaided: dropping the decorator moves root resolution onto the supertype, so the whole migration is now gated on template-archive#946 rather than only the state and runtime parts of it. That is a real change in cost from an earlier revision of this PR, which measured the composition shape with the decorator still present.

Composition of templates, which this model is largely built to support, is used by exactly 1 of 37 active templates today (copyright-license). The case for it is forward-looking rather than a fix for current pain, and that is worth being explicit about.

Deliberately not modelled

Each of these was considered and left to an extension profile. The models document what a profile would have to define.

• Hash canonicalization — how the bytes a hash commits to are produced, and that the hash property is excluded from its own pre-image. A deterministic profile must define this and may require the four hash properties this model leaves optional.
• Order of precedence — which document prevails where two conflict. Agreement.documents holds reading order, and precedence is commonly its inverse.
• Supersession and amendment — a link between documents rather than an ordering over them.
• Incorporation by reference — including terms published elsewhere, and whether as at a fixed version or as amended from time to time.
• Cross-level hash commitment — every hash commits only to its own level. There is no Merkle relationship between an agreement, its documents and its clauses.
• Party role vocabulary — AgreementParty.role is an open string.
• Template identifier syntax — whether TemplateReference.templateId is a name, a URI or a registry key, and how it is compared.
• Template artifact manifests — where TemplateReference.artifacts is populated, a profile must define the manifest canonicalization and require the list to agree with artifactManifestHash.

Other notes

• Obligations may be created without template provenance. AgreementReference.template is optional, where obligation's local AgreementRef required templateId and templateHash. An agreement recorded across several documents has no single template, so the stricter rule was not satisfiable.
• runtime@1.0.0 drops the deprecated runtime@0.2.0.Obligation event. 21 templates subclass it; obligation@1.0.0 is the destination.
• templatedata@1.0.0 was data@1.0.0 in an earlier revision. data was too generic a namespace for this repository to claim for two concepts, and the name is free to change now and impossible to change after publication.

Screenshots or Video

Not applicable. Concerto model changes only.

Related Issues

• Pull Request feat(contract): add contract 1.0 model #197, feat(runtime): add runtime 1.0 model #198, Codex/obligation 1.0 models #196, feat(signature): add org.accordproject.signature@1.0.0 #195
• Pull Request fix(models): promote contract, runtime and party to 1.0 without breaking templates #199
• fix(concerto-core): serialize maps with cross-namespace concept values concerto#1279
• feat(cicero-core)!: require the 1.0 runtime models template-archive#946

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
• Ensure that CI passes

🤖 Generated with Claude Code

https://claude.ai/code/session_01NPtNYorvvn7MQwTovLXp2r

[mttrbrts]

Findings from the prototype migration, and four proposed changes

cicero-template-library#528 migrates copyright-license onto this design. It surfaced two problems — duplicated clause data in sample.json, and a grammar that has to wrap its whole body in {{#with data}}. Both are worth acting on here, though only one is a defect in this PR.

The duplication is a divergence from this PR, not a flaw in it

Clause here has no data property — it was removed during review precisely because a clause's data is a subtree of the document's data. The prototype re-added it, along with a ClauseData type that doesn't exist in this namespace:

// this PR                            // prototype's agreement.cto
concept Clause {                      concept Clause {
  o String path                         o String path
  o TemplateReference template          o ClauseData data   <- reintroduced
  o String clauseId optional          }
  o ContentHash clauseHash optional
}

The cost shows up in the prototype's logic.ts, which cannot tell which copy is authoritative:

const paymentTerms = (clauses['paymentTerms']?.data as IPaymentTerms) ?? licenseData.paymentTerms;

But it exposed a real gap in this PR. Clause.template is required, because Clause means "a sub-template archive composed into this document". copyright-license has no sub-template: its old PaymentClause extends Clause was nested data carrying an id, and {{#clause paymentTerms}} is an inline grammar block. Its clauses map should therefore be absent, not populated with a duplicate. This PR never says so plainly, which is how it came to be read the other way. Worth noting that copyright-license is the one active template that does not exercise composition of templates, so it is a harder migration target than it looks.

The {{#with data}} wrapper is caused by @template sitting on the envelope

The prototype declares @template asset TemplateModel extends AgreementDocument {}, so the grammar's root is the envelope and every variable is one level down under data.

That is not only verbose, it cannot work at all. In markdown-template/lib/TypeVisitor.js:

construct	line	lookup	walks supertypes
VariableDefinition	184	getProperty	yes
ClauseDefinition	219	getOwnProperty	no
WithDefinition	249	getOwnProperty	no

Confirmed against concerto-core: for Sub extends AgreementDocument {}, getProperty("data") returns true but getOwnProperty("data") returns false. So {{#with data}} on a subclass with an empty body can never resolve, which is why the prototype's render tests are expected failures. Plain {{variable}} works through inheritance; block constructs do not.

Proposed fix: the renderable root is the TemplateData subtype

@template
concept CopyrightLicenseData extends TemplateData {
  o DateTime effectiveDate
  o PartyRef licensee
  o PartyRef licensor
  o String territory
  o String purposeDescription
  o String workDescription
  o PaymentTerms paymentTerms
}

This resolves all three symptoms together:

• no {{#with}} — the grammar roots at the data, so {{effectiveDate}} resolves directly
• no getOwnProperty failure — the @template class declares its properties directly, so nothing depends on the supertype walk
• no duplication — sample.json's root becomes the data, so there is no envelope and no clauses map in it

The division of labour becomes explicit: a template author writes data; the runtime wraps it in a provenance envelope. The envelope keeps the stable $class that motivated composition in the first place, and the template author never has to see it.

Template data should use PartyRef, not --> Party

The prototype hand-rolls a resolveParty() helper to walk the parties array, because a relationship arrives at trigger() as a "resource:...#me" string with no resolution step. That is exactly what PartyRef is for in party@1.0.0 — a portable, embedded party value for records that travel standalone, and template data is such a record. --> Party belongs on the envelope's AgreementParty, where a resolver exists. Making this change deletes resolveParty entirely.

Changes to make in this PR

1. Document the @template placement rule: the renderable root is the TemplateData subtype, never the envelope.
2. State that clauses records composed sub-template archives only; inline {{#clause}} blocks get no entry.
3. Pin the root of Clause.path. The prototype used "data.paymentTerms"; this PR intends "paymentTerms". Moving @template onto the data makes that unambiguous.
4. Note that template data should carry PartyRef rather than --> Party.

Points 1 and 3 are the substantive ones: they mean the agreement envelope is a runtime concern rather than something a template author writes, which is a clearer statement of the design than the PR currently makes.

Not pushed as a commit — raising for discussion first.

[github-actions]

🧩 Concerto Playground Preview

The .cto model changes in this PR are pre-loaded into the Concerto Playground — click a link below for a live preview.

File	Preview
src/accordproject/agreement@1.0.0.cto	Diagram · Code · Open in Playground
src/accordproject/obligation/settlement@1.0.0.cto	Diagram · Code · Open in Playground
src/accordproject/obligation@1.0.0.cto	Diagram · Code · Open in Playground
src/accordproject/party@1.0.0.cto	Diagram · Code · Open in Playground
src/accordproject/runtime@1.0.0.cto	Diagram · Code · Open in Playground
src/accordproject/template@1.0.0.cto	Diagram · Code · Open in Playground
src/accordproject/templatedata@1.0.0.cto	Diagram · Code · Open in Playground

All 7 changed models together: Preview combined

_{Auto-generated from commit e8e0fb3. Updates automatically on new commits.}

[niallroche]

thanks for consolidating into this PR Matt and for catching the 'runtime@0.2.0' dependency. I am happy for agreement@1.0.0 to replace contract@1.0.0, and to close #197.

Here are some observations:

1. Hash rules

Agreement.agreementHash, AgreementDocument.documentHash, AgreementState.stateHash and AgreementReference.agreementHash are each documented as committing to "the canonical representation, excluding the property itself", and the canonicalization is not yet defined. As it stands two conformant implementations could produce different hashes for the same agreement and neither would be wrong.

This is the same point I raised about stateHash on #198, and I mention it again only because the surface has grown from one field to four, which makes it worth settling deliberately rather than by default.

The awkward part is that optional-to-required is a breaking change, so whichever way 1.0 publishes is effectively permanent. That suggests either making the four optional in the core models and letting a deterministic profile require them and define the rules, or defining the canonicalization normatively here.

I have a working canonicalization for this in the x402 settlement work — RFC 8785 JCS over Concerto JSON with the hash field excluded, with golden and tamper vectors. I would be glad to write it up as a profile PR against whichever of the two routes you prefer, so it is not extra work landing on you.

2. Finishing the party consolidation

Collapsing the three party representations is clearly right, and Party registry-resident with PartyRef portable is a cleaner statement of the distinction than I managed — scheme in particular is a real improvement on the bare identifier I had in Signatory.

One point on signature:

signature@1.0.0 Signatory { identifier, name optional, role optional, uri optional }
party@1.0.0     PartyRef  { id, scheme, label optional }

role is doing work in attestations — it distinguishes a signatory who is a party from a witness, a delegate, or a counter-signing provider, and an attestation that cannot record which is weaker as evidence.

I do not think it belongs on PartyRef, since the same party may sign in different roles on different documents. It sits more naturally on the attestation. If you agree, I will make that change in #195 as part of moving it onto party@1.0.0, and you would not need to alter anything here.

3. Clause.path and the map key

AgreementDocument.clauses is keyed by clause instance path, and Clause also declares o String path, so the same value is recorded in both places with nothing requiring them to agree.

Dropping Clause.path and letting the key be authoritative would remove the question. If it is there for the case where a Clause travels outside its map, that is a good reason to keep it, and documenting the invariant plus a test would cover it.

4. templateId

A small consideration is that identifier inside a TemplateReference still reads to me as though it identifies the reference rather than the template, which is the confusion behind the "should this be identified?" comments on #197. Deferring identifier syntax to a profile is right and separate from what the field is called. Entirely your call.

5. Questions

• Is AgreementState intentionally registry-bound? It holds --> Agreement, and Agreement holds --> AgreementDocument[], so state cannot travel without a resolver, while obligations and settlement evidence reference agreements portably. You state the registry-resident and portable rule explicitly for Party; the equivalent sentence for state would settle it.

• data@1.0.0 naming. Of your two alternatives I prefer templatedata — extension names the mechanism, whereas the namespace holds exactly the two types templates extend.

[niallroche]

Great @mttrbrts. Does removing the decorator need a 'cicero-core' change? Your earlier analysis had 'findTemplateConcept' looking for exactly one non-abstract declaration carrying '@template'. If the supertype now carries that meaning, the lookup has to resolve by parent type instead. The engine-compatibility result was measured with the decorator in place, so I want to check whether this adds a second engine dependency alongside template-archive#946. it seems that it matters for the migration table, which is careful about which rows need one.

[mttrbrts]

Yes, you're right @niallroche. The template-archive prototype now includes the necessary changes too, accordproject/template-archive#946. Similarly, the prototype template migration in accordproject/cicero-template-library#528 aligns.

I want to validate the sample template with a clause reference to a separate template, but otherwise think that we're pretty close.

[niallroche]

Thanks Matt, that answers the decorator/root-resolution question for me. If template-archive#946 is carrying the TemplateData parent-type lookup with decorator fallback, then the engine dependency is clear and I am happy with that part of the story.

The remaining thing I would like to pin before we call this settled is the composed-template evidence. As I read it, #946 proves the engine can find/load the template data root and move to the 1.0 runtime shape, but it does not construct the runtime agreement envelope: AgreementDocument, documentHash, or the clauses provenance map.

Your note about validating a sample template with a clause reference to a separate template is exactly the missing evidence. The current migration text says composition is used by exactly 1 of 37 active templates today, citing copyright-license; but copyright-license is the inline {{#clause}} case, so it is useful migration coverage but not evidence for composed sub-template archive provenance. Could we either correct that count/wording, or add the separate-template clause sample and use that as the composition evidence?

One related sequencing question: if the envelope construction is not in #946, who owns the first implementation that wraps template data into AgreementDocument, populates documentHash, and builds the clauses map? That feels relevant to whether agreement@1.0.0 can publish ahead of implementation, given the HTTP import publish chain.

Separately, I can take the APAP/LCP L3/L4 follow-up for TermsAcceptance, evidence binding, and hash-discipline alignment as its own PR.

And yes, the extra point about Template.EMIT_TYPE = 'org.accordproject.obligation@1.0.0.Obligation' matters. It means obligation@1.0.0 is no longer off to the side: #946’s engine change depends on it as part of the 1.0 runtime shape, so your #196 becomes part of the practical publish chain.