Skip to content

feat(cicero-core)!: require the 1.0 runtime models - #946

Open
mttrbrts wants to merge 3 commits into
mainfrom
claude/runtime-1.0-namespace-support
Open

mttrbrts wants to merge 3 commits into
mainfrom
claude/runtime-1.0-namespace-support

Conversation

@mttrbrts

@mttrbrts mttrbrts commented Aug 27, 2026 •

Copy link
Copy Markdown
Member

Closes #N/A

Template resolved the runtime base types by fully-qualified name, hardcoded to org.accordproject.runtime@0.2.0 in five places. This makes a hard break: those names now point at the 1.0 generation, and at nothing else.

Changes

src/template.ts before after
getRequestTypes() runtime@0.2.0.Request Template.REQUEST_TYPE → runtime@1.0.0.Request
getResponseTypes() runtime@0.2.0.Response Template.RESPONSE_TYPE → runtime@1.0.0.Response
getEmitTypes() runtime@0.2.0.Obligation Template.EMIT_TYPE → obligation@1.0.0.Obligation
getStateTypes() runtime@0.2.0.State Template.STATE_TYPE → templatedata@1.0.0.StateData
isStateful() runtime@0.2.0.State Template.STATE_TYPE
getTemplateModel() @template decorator Template.TEMPLATE_DATA_TYPE → templatedata@1.0.0.TemplateData, decorator as fallback
  • State is composed, not subclassed. templatedata@1.0.0.StateData is an abstract concept carried in the runtime's state envelope, following feat(agreement): 1.0 agreement, party and runtime models models#200. Because it is abstract, getStateTypes() returns only the template's own state type — where 0.2.0 also returned the concrete base State. isStateful() no longer has to exclude a base type, so the excludeBaseType parameter and the multi-type lookup helper are both gone.
  • The template model is found by its parent type, not by a decorator. A template's model declares exactly one concrete subtype of templatedata@1.0.0.TemplateData, and that subtype is the template model: extending TemplateData is the declaration. getTemplateModel() resolves it by reusing findConcreteSubclassNames, the same helper the other getters use. More than one concrete subtype is rejected with an error naming them. Zero — the namespace predates this convention, or simply is not loaded — falls back to the legacy @template lookup, so decorated templates keep loading unchanged. The decorator is no longer necessary; it is not forbidden.
  • The extension point moved namespace. TemplateData and StateData live in templatedata@1.0.0, which imports nothing. It was called data@1.0.0 in an earlier revision of feat(agreement): 1.0 agreement, party and runtime models models#200 and StateData was briefly in runtime@1.0.0; neither is true any more.
  • Obligations move out of the runtime namespace. runtime@1.0.0 defines no obligation of its own; obligation lifecycle is durable state in org.accordproject.obligation@1.0.0, which is where getEmitTypes() now looks.
  • A missing base type is not an error. findConcreteSubclassNames treats a base type whose namespace the template does not load as contributing nothing. A template that declares no state does not import the namespace its base type lives in and must not fail to open because of it. Only TypeNotFoundException is swallowed; every other error propagates.
  • src/external/ is deleted. It bundled copies of contract@0.2.0 and runtime@0.2.0 that nothing referenced and files never shipped.

The major version bump

The packages move to 2.0.0, which enforces the break at load time rather than leaving it to be discovered. Metadata already rejects a template whose accordproject.cicero range excludes the running version, so a template written for cicero 1.x now fails with

The template targets Cicero version ^1.0.0 but the current Cicero version is 2.0.0.

instead of loading and silently reporting no request, response, state or emit types. Every fixture's accordproject.cicero moves to ^2.0.0, and cicero-cli's dependency on cicero-core moves with it. The generator's scaffolded package.json picks the range up from its own version, so it needs no separate change.

Fixtures

Every template under packages/*/test/data that imported runtime@0.2.0 now imports runtime@1.0.0: asset X extends State became concept X extends StateData, and helloemit's event Greeting extends Obligation became asset Greeting extends Obligation. Fixtures that declare state take StateData from templatedata@1.0.0.

runtime@1.0.0, obligation@1.0.0 and templatedata@1.0.0 are not published, so each fixture carries a reduced local copy declaring only the base types this package resolves by name. The published namespaces also define the state envelope, the clause-state map, the concrete obligation kinds and the transition event, none of which cicero-core looks up, and whose properties would pull in four further 1.0 namespaces and a Concerto version this repository does not pin. Worth revisiting once the namespaces are published.

Because those namespaces cannot be fetched, the suite now loads templates offline. template-decorator imports only published namespaces and is the one fixture still resolved over HTTP, so should create a template from a directory and download external models by default is pointed at it and keeps that path covered. The e2e spec loads offline for the same reason.

Also removed: six state.json fixtures whose only content was {"$class": "org.accordproject.runtime@0.2.0.State"}. Nothing reads them, and 1.0 has no concrete base state for them to name.

Tests

cicero-core, excluding templatelibrary.test.ts:

Test Suites: 16 passed, 16 total
Tests:       2 skipped, 174 passed, 176 total

templatelibrary.test.ts needs live access to templates.accordproject.org, which the environment these numbers were taken in cannot reach — every failure there is Failed to load template index with HTTP 405, reproduces identically on the commit before this change, and is unrelated to it. cicero-cli: 56 passed, 1 skipped. npm run lint and the license header check pass. The Playwright e2e spec was not run; the one e2e-relevant fixture resolves its template model unchanged.

Fixtures added and getter tests reworked to the 1.0 shape:

  • test/data/legacy-runtime — a template exactly as it was written for cicero 1.x, asserting it is now rejected:
it('should be rejected rather than loaded', async () => {
    await expect(Template.fromDirectory('./test/data/legacy-runtime', options))
        .rejects.toThrow('The template targets Cicero version ^1.0.0 but the current Cicero version is');
});
  • test/data/no-runtime-namespace — a template importing no runtime namespace at all, asserting all four getters return [] and isStateful() returns false instead of throwing. It also covers the @template fallback: with no concrete subtype of TemplateData in scope, cicero-core still finds the template model by the decorator.
  • test/data/no-template-decorator (new) — a template carrying no decorator anywhere, whose model declares concept SomethingData extends TemplateData, asserting getTemplateModel() resolves it and that data round-trips against it.
  • test/data/multiple-concepts — reworked to declare two concrete subtypes of TemplateData, asserting the new ambiguity error rather than the old decorator-library message.

Deliberately left alone

  • contract@0.2.0. Templates still take Clause and Contract from it. cicero-core resolves nothing in that namespace by name. This change makes the engine able to find a TemplateData-rooted model; migrating the templates themselves onto that shape is separate work, tracked against feat(agreement): 1.0 agreement, party and runtime models models#200.
  • Three unreferenced .cta archives in cicero-core/test/data still contain 0.2.0 templates. No test loads them; they can be regenerated or dropped whenever the directories they mirror are next touched.

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

🤖 Generated with Claude Code

@coveralls

coveralls commented Aug 27, 2026 •

Copy link
Copy Markdown

Coverage Report for CI Build 33872195474

Coverage increased (+0.2%) to 89.619%

Details

  • Coverage increased (+0.2%) from the base build.
  • Patch coverage: 1 uncovered change across 1 file (20 of 21 lines covered, 95.24%).
  • No coverage regressions found.

Uncovered Changes

File Changed Covered %
packages/cicero-core/src/template.ts 21 20 95.24%

Coverage Regressions

No coverage regressions found.


Coverage Stats

Coverage Status
Relevant Lines: 889
Covered Lines: 802
Line Coverage: 90.21%
Relevant Branches: 267
Covered Branches: 234
Branch Coverage: 87.64%
Branches in Coverage %: Yes
Coverage Strength: 462.63 hits per line

💛 - Coveralls

Copilot AI left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

This PR removes hard-coded coupling to org.accordproject.runtime@0.2.0 when resolving runtime base types, allowing Template to discover request/response/emit/state types across multiple runtime namespace generations and to degrade cleanly when a runtime namespace is not present.

Changes:

  • Added generation-aware base-type lists on Template and updated the type-discovery getters to union results across those lists.
  • Updated subclass discovery to treat missing base types (absent namespaces) as “no contribution” instead of throwing, while still rethrowing non-TypeNotFoundException errors.
  • Added fixtures + tests for a runtime@1.0.0-based template (offline) and for a template that imports no runtime namespace.

Reviewed changes

Copilot reviewed 15 out of 15 changed files in this pull request and generated 1 comment.

Show a summary per file
File Description
packages/cicero-core/src/template.ts Resolves runtime base types across multiple namespace generations and skips absent namespaces.
packages/cicero-core/test/template.test.ts Adds coverage for runtime generation resolution and missing-runtime behavior.
packages/cicero-core/test/data/runtime1-state/README.md Documents the runtime@1.0.0 offline fixture purpose.
packages/cicero-core/test/data/runtime1-state/package.json Adds a stateful runtime@1.0.0-based fixture template manifest.
packages/cicero-core/test/data/runtime1-state/request.json Adds a sample request for the runtime@1.0.0 fixture.
packages/cicero-core/test/data/runtime1-state/model/model.cto Defines a template model importing runtime@1.0.0 base types.
packages/cicero-core/test/data/runtime1-state/model/@models.accordproject.org.accordproject.runtime@1.0.0.cto Provides a reduced local runtime@1.0.0 model for offline testing.
packages/cicero-core/test/data/runtime1-state/model/@models.accordproject.org.accordproject.contract@0.2.0.cto Provides a reduced local contract@0.2.0 model for offline testing.
packages/cicero-core/test/data/runtime1-state/text/grammar.tem.md Adds the grammar template for the runtime@1.0.0 fixture.
packages/cicero-core/test/data/runtime1-state/text/sample.md Adds sample text for the runtime@1.0.0 fixture.
packages/cicero-core/test/data/no-runtime-namespace/README.md Documents the “no runtime namespace” fixture purpose.
packages/cicero-core/test/data/no-runtime-namespace/package.json Adds a fixture template manifest with no runtime imports.
packages/cicero-core/test/data/no-runtime-namespace/model/model.cto Defines a template model that intentionally imports no runtime namespace.
packages/cicero-core/test/data/no-runtime-namespace/text/grammar.tem.md Adds the grammar template for the “no runtime namespace” fixture.
packages/cicero-core/test/data/no-runtime-namespace/text/sample.md Adds sample text for the “no runtime namespace” fixture.
Suppressed comments (1)

packages/cicero-core/src/template.ts:547

  • The JSDoc for getStateTypes() references an excludeBaseType parameter (and mentions "Response") even though the method takes no parameters. This looks like stale/copy-pasted documentation and should be corrected.
     * @param {boolean} excludeBaseType Exclude the runtime base Response type
    * @return {String[]} a list of the state types
     */
    getStateTypes() {
        return this.findConcreteSubclassNamesForAll(Template.STATE_TYPES);

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

Comment thread packages/cicero-core/src/template.ts Outdated
Comment on lines +533 to +538
/**
* Provides a list of the emit types that are emitted by this Template. Types use the fully-qualified form.
* @return {Array} a list of the emit types
*/
getEmitTypes() {
return this.findConcreteSubclassNames('org.accordproject.runtime@0.2.0.Obligation');
return this.findConcreteSubclassNamesForAll(Template.EMIT_TYPES);
`Template` resolved its runtime base types by fully-qualified name, hardcoded
to `org.accordproject.runtime@0.2.0` in five places. Those names now point at
the 1.0 generation, and only at it:

| | before | after |
|---|---|---|
| `getRequestTypes()` | `runtime@0.2.0.Request` | `runtime@1.0.0.Request` |
| `getResponseTypes()` | `runtime@0.2.0.Response` | `runtime@1.0.0.Response` |
| `getEmitTypes()` | `runtime@0.2.0.Obligation` | `obligation@1.0.0.Obligation` |
| `getStateTypes()` | `runtime@0.2.0.State` | `runtime@1.0.0.StateData` |
| `isStateful()` | `runtime@0.2.0.State` | `runtime@1.0.0.StateData` |

State is now composed into the runtime's state envelope rather than
subclassing it, so `StateData` is an abstract concept and a template's own
state type is the only thing `getStateTypes()` can return. `isStateful()`
therefore no longer needs to exclude a concrete base type, and the base type
exclusion has been dropped along with the multi-type lookup helper.

runtime@1.0.0 defines no obligation of its own; obligations are durable state
in `org.accordproject.obligation@1.0.0`, which is where `getEmitTypes()` now
looks.

A base type whose namespace a template does not load is not an error: it
contributes nothing. A template that declares no state does not import the
namespace its base type lives in, and must not fail to open because of it.
Only `TypeNotFoundException` is swallowed; every other error propagates.

The packages move to 2.0.0 so the break is enforced at load time: `Metadata`
rejects a template whose `accordproject.cicero` range excludes the running
version, so a 1.x template fails with a clear message instead of loading and
silently reporting no request, response, state or emit types.

BREAKING CHANGE: templates built on org.accordproject.runtime@0.2.0 are no
longer supported. A template must import org.accordproject.runtime@1.0.0,
declare its state as a concrete subtype of runtime@1.0.0.StateData, declare
any emitted obligation as a subtype of obligation@1.0.0.Obligation, and set
`accordproject.cicero` to a range that admits 2.0.0. Templates targeting
^1.0.0 are rejected by Template.fromDirectory and Template.fromArchive.

Signed-off-by: Matt Roberts <code@rbrts.uk>
@mttrbrts
mttrbrts force-pushed the claude/runtime-1.0-namespace-support branch from 1c7e2bb to 676a521 Compare August 27, 2026 10:00
@mttrbrts mttrbrts changed the title fix(cicero-core): resolve runtime base types across namespace generations feat(cicero-core)!: require the 1.0 runtime models Aug 27, 2026
…or alone

accordproject/models#200 moved on since #946 was written: the base
namespace for a template's own data model is now templatedata@1.0.0
(renamed from data@1.0.0), and it, not runtime@1.0.0, is where
StateData lives. Template.STATE_TYPE follows the rename.

The bigger change is how the template model itself is found. A
template's model now declares exactly one concrete subtype of
templatedata@1.0.0.TemplateData, and that subtype is the template
model: extending TemplateData is the declaration, so no @template
decorator is required to identify it. getTemplateModel() resolves
this the same way getStateTypes() and friends already do, by reusing
findConcreteSubclassNames(Template.TEMPLATE_DATA_TYPE):

- exactly one concrete subtype is the template model
- more than one is rejected with an error naming the offending types
- none (the namespace predates this convention, or simply is not
  loaded) falls back to the legacy @template-decorator lookup, so
  existing decorated templates keep loading unchanged

Fixtures that declare state now extend templatedata@1.0.0.StateData,
and every reduced local copy of runtime@1.0.0 drops StateData in
favour of a new reduced local copy of templatedata@1.0.0. Added
test/data/no-template-decorator to cover the decorator-free path and
reworked test/data/multiple-concepts to declare two concrete
subtypes of TemplateData, covering the new ambiguity error.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01NPtNYorvvn7MQwTovLXp2r
Signed-off-by: Claude <noreply@anthropic.com>
mttrbrts pushed a commit to accordproject/cicero-template-library that referenced this pull request Sep 4, 2026
The model design proposed in accordproject/models#200 has moved on
substantially since this prototype was written. Bring it back in line:

- No `@template` decorator, no envelope class. A template's model now
  declares exactly one concrete subtype of
  `templatedata@1.0.0.TemplateData`, and that subtype IS the template
  model (`CopyrightLicenseData`), carrying its variables directly. This
  also fixes the specific rendering gap the previous revision hit:
  TemplateMark's TypeVisitor resolves properties via
  `ClassDeclaration#getOwnProperty`, which doesn't walk supertypes, so
  an empty `TemplateModel extends AgreementDocument {}` could never
  resolve its inherited `data`. Rooting the grammar at the data itself
  removes the `{{#with data}}` wrapper and the problem it hit.
- No `clauses` map. `copyright-license` has no sub-template archive --
  `{{#clause paymentTerms}}` is an inline grammar block in this
  template's own grammar -- so `PaymentTerms` is simply a nested
  ordinary concept, addressed as a subtree of the data. This removes
  the data-duplication `logic.ts` previously had to paper over with
  `clauses['paymentTerms']?.data ?? licenseData.paymentTerms`.
- `licensee`/`licensor` are `PartyRef` values (a portable embedded
  reference), not `--> Party` relationships. A relationship reaches
  `trigger()` as an unresolvable `"resource:...#me"` string with no
  registry to resolve it against; `resolveParty()` is gone along with
  the relationship. `--> Party` belongs on the envelope's
  `AgreementParty`, where a registry exists (see model/agreement.cto,
  which documents that wider envelope even though this template's own
  model has none to be composed onto).
- Renamed the vendored `data@1.0.0` stand-in to `templatedata@1.0.0`,
  split into its own model/templatedata.cto per the current namespace
  split, and updated model/party.cto (adds `PartyRef`) and
  model/agreement.cto (drops `Clause.path`, adds `AgreementParty`,
  documents why `Clause`/`Clauses` are out of scope for this
  prototype) to match.

Empirically, removing `@template` fixes rendering but trades it for a
worse problem: the installed `@accordproject/cicero-core` (2.1.1, and
the copy vendored inside `@accordproject/template-engine`) finds a
template's root exclusively via the `@template` decorator, and
`Template#validate()` -- called unconditionally by
`Template.fromDirectory()` -- calls `getTemplateModel()`
unconditionally too. So without the decorator this template cannot be
*loaded* at all with today's toolchain, let alone drafted or triggered
-- confirmed empirically (see README). The fix is
accordproject/template-archive#946, which is not released.

`@template` has deliberately not been added back -- that would paper
over the exact gap this prototype exists to demonstrate. Instead,
test/render.test.mjs gains an `expectedLoadFailures` set (a strict
superset of `expectedFailures`, since a template here can't even load)
covering this template in both the render and trigger describes, each
`it.fails` naming template-archive#946, and the module-level
template-loading probe now tolerates a known load failure without
taking down the whole render-test file for every other template.

npm run test --workspaces --if-present: 49/49 workspace test files
pass (212 tests). npm run test:render: 114 passed, 5 expected fail (of
119), 0 unexpected failures.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01NPtNYorvvn7MQwTovLXp2r
Signed-off-by: Claude <noreply@anthropic.com>
Resolved all package.json merge conflicts by keeping main branch versions while preserving runtime 1.0 model changes from the PR branch.

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Signed-off-by: Matt Roberts <code@rbrts.uk>
@github-actions

github-actions Bot commented Oct 3, 2026

Copy link
Copy Markdown
Contributor

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.

@github-actions github-actions Bot added the Stale label Oct 3, 2026

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

Projects

None yet

Development

Successfully merging this pull request may close these issues.

4 participants