Skip to content

feat: logic API for agreement@1.0.0 templates (defineLogic, transactions, composed clauses) - #187

Draft
mttrbrts wants to merge 1 commit into
mainfrom
claude/agreement-1.0-logic
Draft

mttrbrts wants to merge 1 commit into
mainfrom
claude/agreement-1.0-logic

Conversation

@mttrbrts

@mttrbrts mttrbrts commented Oct 1, 2026

Copy link
Copy Markdown
Member

Summary

Adds a second way to write template logic, for templates on the org.accordproject 1.0.0 namespaces. Their data extends templatedata@1.0.0.TemplateData, their state extends StateData, and their requests extend runtime@1.0.0.Request (accordproject/models#200, plus #205's composed clauses). Templates that use TemplateLogic are unchanged, and all existing tests pass as before.

import { defineLogic, Self } from '@accordproject/template-engine/logic';
import { LatePaymentState, PaymentOverdue, PaymentReminder, ReminderSent } from './generated/types';

export default defineLogic<Self<ILatePaymentData, ILatePaymentState>>()
    .init(clause => clause.setState(LatePaymentState.create({ remindersSent: 0, discharged: false })))
    .on(PaymentOverdue, async (request, clause) => {
        clause.setState({ ...clause.state, remindersSent: clause.state.remindersSent + 1 });
        clause.emit(PaymentReminder.create({ /* ... */ }));
        return ReminderSent.create({ /* ... */ });
    });

How logic runs

  • One handler per request type, no switch. Each handler takes (request, self).
  • self is the instance. It is this template instance's node in an agreement@1.0.0 Agreement. The Agreement is one tree of instances: each document is the root instance, and each composed Clause is an instance with its own data and state. self reads everything in the tree but writes only its own state (setState), its events (emit) and the clauses composed into it (self.clauses.x.trigger(...)).
  • Clause APIs are typed. Clause<ApiOf<typeof thatLogic>> gives the clause's trigger an overload for each request type it handles.
  • Each request is a transaction. It commits as one revision of runtime@1.0.0.AgreementState, or not at all if the handler throws. A composed clause runs in a nested transaction, so a parent that catches a clause's error loses only that clause's writes.
  • Logic is deterministic. Time comes from requests and data, never the clock.
  • Every value comes from a generated factory. PayOut.create({...}) fills in $class, so logic never writes one by hand.

What's added

Path What
src/agreement/logic.ts The logic API. Self-contained: it declares its shapes structurally, so it is also what the compiler declares to template logic (src/runtime/logicDeclarations.ts, generated at prebuild).
src/agreement/execute.ts initialise() / execute(), JSON in and JSON out, so a stateless function (e.g. serverless) can host an agreement. Also Transaction, the tree, and read-only views.
src/agreement/types.ts, codegen.ts, bin/codegen.js One factory per concrete type. template-engine-codegen [dir] [--offline] writes logic/generated/*.ts: Concerto's interfaces plus types.ts.
src/agreement/loader.ts Loads compiled logic and rewrites its value imports to modules the engine supplies: the logic API, the factories, generated enums, dayjs and jsonpath. Type-only imports are erased, so logic can import a composed clause's API from that clause's own logic.
src/agreement/testing.ts testInstance (a self with committed) and stubClause (typed by the clause's API), exported as @accordproject/template-engine/testing.
src/AgreementProcessor.ts Runs an agreement over several Templates, merging their models and refusing a namespace that two templates define differently.
TemplateArchiveProcessor init / trigger run such logic as the one document of an agreement. draft passes the template model's FQN explicitly. Runtime hierarchy checks accept runtime@1.0.0 as well as runtime@0.2.0.

Dependencies

This needs cicero-core to find the template model by TemplateData and to read accordproject.templateModel (accordproject/template-archive#946 and #950). Until those are released, @accordproject/cicero-core points at #950's prebuilt dist branch. Swap it for the release before merging.

The prebuilt dist branch claude/agreement-1.0-logic-dist (5.2.0-agreement.0) lets cicero-template-library install this branch from git.

Tests

  • test/AgreementLogic.test.ts covers the transaction semantics with toy logic: nested clauses, catch and rethrow, read-only views, reference resolution, dispatch to a supertype handler, and validation. It also covers the testing helpers.

  • test/AgreementProcessor.test.ts runs an agreement of three real templates (test/archives/agreement, copied from cicero-template-library), compiled and loaded by the engine:

    • a licence that reads a cousin document;
    • a composed late-payment clause, committed together with the licence;
    • rejection that commits nothing;
    • determinism.

    It also covers TemplateArchiveProcessor's draft, init and trigger for these templates, plus codegen and import rewriting.

  • npm test gives 140 passed: the 109 existing tests are unchanged, plus 31 new. npm run webpack builds.

Related: accordproject/models#205, accordproject/template-archive#950, accordproject/cicero-template-library#528.

🤖 Generated with Claude Code

https://claude.ai/code/session_011LWZaJoaq9HFMVceNxCXMS


Generated by Claude Code

Templates whose models extend org.accordproject.templatedata@1.0.0 and
runtime@1.0.0 can write their logic with defineLogic(), imported from
'@accordproject/template-engine/logic', instead of a TemplateLogic class:
one handler per request type, each taking (request, self), where self is
the template instance's node in an agreement@1.0.0 Agreement (models#205).

- src/agreement/logic.ts: the logic API (defineLogic, Self, Clause, ApiOf,
  conceptType / identifiedType factories). Self-contained, so it is also
  what the compiler declares to template logic.
- src/agreement/execute.ts: initialise() and execute(), from JSON to JSON,
  over the agreement's tree of instances and its runtime@1.0.0
  AgreementState. Writes are buffered in a transaction that commits as one
  revision; a composed clause runs in a nested transaction.
- src/agreement/types.ts and codegen.ts, bin/codegen.js: one factory per
  concrete model type (logic/generated/types.ts), generated with Concerto's
  interfaces by template-engine-codegen.
- src/agreement/loader.ts: loads compiled logic, supplying the logic API,
  the factories, generated enums, dayjs and jsonpath to its imports.
- src/agreement/testing.ts: testInstance and stubClause, as
  '@accordproject/template-engine/testing'.
- TemplateArchiveProcessor: init() and trigger() run such logic as the one
  document of an agreement; draft() names the template model explicitly;
  runtime hierarchy checks accept runtime@1.0.0 alongside 0.2.0.
- AgreementProcessor: runs an agreement over several templates.

TemplateLogic templates are unchanged. Depends on cicero-core finding the
template model by TemplateData (template-archive#946, #950), installed
from that PR's dist branch until it is released.

Signed-off-by: Claude <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_011LWZaJoaq9HFMVceNxCXMS
mttrbrts pushed a commit to accordproject/cicero-template-library that referenced this pull request Oct 1, 2026
… API, as three templates

The prototype's local runtime is replaced by the released shape of the
design:

- Models: the 1.0.0 namespaces are refreshed from accordproject/models#205,
  which folds the prototype's proposal namespace (composition.cto) into
  agreement@1.0.0 (Clause with data and clauses, AgreementReference with a
  documentId), runtime@1.0.0 (AgreementState.states) and obligation@1.0.0
  (ObligationIssued). composition.cto is removed.
- Templates: the composed late payment clause and the licensed work
  schedule become sibling templates, late-payment-poc and
  licensed-work-schedule-poc, since cicero-core loads model/ and logic/
  recursively. The licence keeps copies of their models, which its logic
  uses, and names its template model in package.json
  (accordproject.templateModel).
- Logic imports defineLogic from @accordproject/template-engine/logic and
  its factories from logic/generated/types.ts, which template-engine-codegen
  writes with Concerto's interfaces (npm run compile). runtime/ and
  scripts/generate-types.js are removed.
- Tests use @accordproject/template-engine/testing, and the agreement tests
  run on template-engine's AgreementProcessor, which compiles and loads each
  template's logic. Without a direct concerto-core import, the vitest alias
  around concerto-core's ESM version is no longer needed.
- The library depends on template-engine and cicero-core from the dist
  branches of accordproject/template-engine#187 and
  accordproject/template-archive#950, so the render suite loads, drafts,
  initialises and triggers all three templates; the expectedLoadFailures
  entry is removed.

Signed-off-by: Claude <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_011LWZaJoaq9HFMVceNxCXMS
@coveralls

Copy link
Copy Markdown

Coverage Report for CI Build 36911453722

Coverage increased (+7.8%) to 62.208%

Details

  • Coverage increased (+7.8%) from the base build.
  • Patch coverage: 27 uncovered changes across 8 files (427 of 454 lines covered, 94.05%).
  • No coverage regressions found.

Uncovered Changes

File Changed Covered %
src/agreement/codegen.ts 25 13 52.0%
src/agreement/execute.ts 163 158 96.93%
src/agreement/loader.ts 59 55 93.22%
src/AgreementProcessor.ts 44 42 95.45%
src/TemplateArchiveProcessor.ts 51 50 98.04%
src/agreement/logic.ts 30 29 96.67%
src/agreement/testing.ts 28 27 96.43%
src/agreement/types.ts 39 38 97.44%
Total (13 files) 454 427 94.05%

Coverage Regressions

No coverage regressions found.


Coverage Stats

Coverage Status
Relevant Lines: 1880
Covered Lines: 1281
Line Coverage: 68.14%
Relevant Branches: 1245
Covered Branches: 663
Branch Coverage: 53.25%
Branches in Coverage %: Yes
Coverage Strength: 2536.67 hits per line

💛 - Coveralls

@github-actions

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.

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

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants