@algovoi/substrate 0.2.1 → 0.3.1

package/README.md

@@ -66,8 +66,11 @@ verifyAuditChain([row0, row1]);
 
 ## Substrate discipline
 
-This package enforces the AlgoVoi-discipline rules formalised in PR #2436
-(`x402-foundation/x402`, three-voice coalition co-signed):
+This package enforces the AlgoVoi-authored substrate-discipline rules
+formalised in [IETF Internet-Draft `draft-hopley-x402-canonicalisation-jcs-v1`](https://datatracker.ietf.org/doc/draft-hopley-x402-canonicalisation-jcs-v1/)
+(Independent Submission, Informational; sole AlgoVoi authorship) and
+proposed for inclusion in `x402-foundation/x402` via [PR #2453](https://github.com/x402-foundation/x402/pull/2453)
+(replaces closed [#2436](https://github.com/x402-foundation/x402/pull/2436)):
 
 - **Rule 1.** `timestamp_ms` is an epoch-millisecond integer. Floats, ISO
   8601 strings, and negative values are rejected at the source-side.
@@ -115,10 +118,21 @@ The reference exhibit for this substrate is AlgoVoi's
 
 ## Spec references
 
-- [PR #2436](https://github.com/x402-foundation/x402/pull/2436) -- canonicalisation discipline
-- [PR #2440](https://github.com/x402-foundation/x402/pull/2440) -- composite trust-query
-- [PR #2434](https://github.com/x402-foundation/x402/pull/2434) -- compliance-receipt-fixture
-- [draft-vauban-x402-stark-receipts](https://datatracker.ietf.org/doc/draft-vauban-x402-stark-receipts/)
+- [draft-hopley-x402-canonicalisation-jcs-v1](https://datatracker.ietf.org/doc/draft-hopley-x402-canonicalisation-jcs-v1/) -- IETF I-D (Independent Submission, Informational, sole AlgoVoi authorship). Specifies `urn:x402:canonicalisation:jcs-rfc8785-v1`.
+- [docs.algovoi.co.uk/canonicalisation-substrate](https://docs.algovoi.co.uk/canonicalisation-substrate) -- v1 discipline reference page.
+- [docs.algovoi.co.uk/canonicalisation-substrate-v2](https://docs.algovoi.co.uk/canonicalisation-substrate-v2) -- v2 (PQC-aware) additive successor.
+- [PR #2453](https://github.com/x402-foundation/x402/pull/2453) -- live upstream spec PR for the canonicalisation discipline (sole AlgoVoi authorship; replaces closed #2436).
+- [draft-vauban-x402-stark-receipts](https://datatracker.ietf.org/doc/draft-vauban-x402-stark-receipts/) -- third-party adopter-authored receipt format that anchors to the AlgoVoi canonicalisation discipline.
+
+## Conformance to the canonicalisation discipline
+
+This package emits receipts pinned to `canon_version: jcs-rfc8785-v1` in-band. Downstream verifiers (`algovoi-audit-verifier` and any conformant third-party verifier) read the pin to select the canonicalisation rule applied at emission.
+
+The pin is the load-bearing primitive for the [Substrate Adopters Registry](https://docs.algovoi.co.uk/adopters): adopters anchoring to this discipline pin the same `canon_version` value in their own publicly-citable artefacts. AlgoVoi maintains the registry as a neutral observer; this package is recorded there as the AlgoVoi reference implementation.
+
+## Substrate adopters
+
+AlgoVoi is recorded in the [Substrate Adopters Registry](https://docs.algovoi.co.uk/adopters) as the substrate author (v1 and v2). Parties anchoring their own services or specifications to `canon_version: jcs-rfc8785-v1` are recorded in the registry via the [submission process](https://docs.algovoi.co.uk/adopters#how-to-submit-an-adoption-entry). AlgoVoi validates submissions against the artefact's canonical bytes and adds qualifying entries.
 
 ## Licence
 

package/dist/index.d.ts

@@ -21,4 +21,5 @@ export { ActionRefError, type ActionRefInput, type ActionRefObject, actionRef, a
 export { CompositeTrustQueryError, type EmitterRow, compositeTrustQueryHash, } from './composite-trust-query.js';
 export { SCREEN_RESULTS, type ScreenResult, ComplianceReceiptError, type ComplianceReceipt, type BuildComplianceReceiptInput, buildComplianceReceipt, } from './compliance-receipt.js';
 export { AuditChainError, type AuditChainRow, appendToChain, verifyAuditChain, } from './audit-chain.js';
+export { TransactionalError, type TransitionPreimage, type TransitionInput, type TransitionRecord, type TransactionalChain, type TransactionalChainInput, transitionPreimage, transitionHash, buildTransactionalActionChain, } from './transactional.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,EACL,aAAa,EACb,qBAAqB,EACrB,YAAY,EACZ,iBAAiB,EACjB,SAAS,GACV,MAAM,mBAAmB,CAAC;AAE3B,OAAO,EACL,cAAc,EACd,KAAK,cAAc,EACnB,KAAK,eAAe,EACpB,SAAS,EACT,eAAe,GAChB,MAAM,iBAAiB,CAAC;AAEzB,OAAO,EACL,wBAAwB,EACxB,KAAK,UAAU,EACf,uBAAuB,GACxB,MAAM,4BAA4B,CAAC;AAEpC,OAAO,EACL,cAAc,EACd,KAAK,YAAY,EACjB,sBAAsB,EACtB,KAAK,iBAAiB,EACtB,KAAK,2BAA2B,EAChC,sBAAsB,GACvB,MAAM,yBAAyB,CAAC;AAEjC,OAAO,EACL,eAAe,EACf,KAAK,aAAa,EAClB,aAAa,EACb,gBAAgB,GACjB,MAAM,kBAAkB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,EACL,aAAa,EACb,qBAAqB,EACrB,YAAY,EACZ,iBAAiB,EACjB,SAAS,GACV,MAAM,mBAAmB,CAAC;AAE3B,OAAO,EACL,cAAc,EACd,KAAK,cAAc,EACnB,KAAK,eAAe,EACpB,SAAS,EACT,eAAe,GAChB,MAAM,iBAAiB,CAAC;AAEzB,OAAO,EACL,wBAAwB,EACxB,KAAK,UAAU,EACf,uBAAuB,GACxB,MAAM,4BAA4B,CAAC;AAEpC,OAAO,EACL,cAAc,EACd,KAAK,YAAY,EACjB,sBAAsB,EACtB,KAAK,iBAAiB,EACtB,KAAK,2BAA2B,EAChC,sBAAsB,GACvB,MAAM,yBAAyB,CAAC;AAEjC,OAAO,EACL,eAAe,EACf,KAAK,aAAa,EAClB,aAAa,EACb,gBAAgB,GACjB,MAAM,kBAAkB,CAAC;AAE1B,OAAO,EACL,kBAAkB,EAClB,KAAK,kBAAkB,EACvB,KAAK,eAAe,EACpB,KAAK,gBAAgB,EACrB,KAAK,kBAAkB,EACvB,KAAK,uBAAuB,EAC5B,kBAAkB,EAClB,cAAc,EACd,6BAA6B,GAC9B,MAAM,oBAAoB,CAAC"}

package/dist/index.js

@@ -21,4 +21,5 @@ export { ActionRefError, actionRef, actionRefObject, } from './action-ref.js';
 export { CompositeTrustQueryError, compositeTrustQueryHash, } from './composite-trust-query.js';
 export { SCREEN_RESULTS, ComplianceReceiptError, buildComplianceReceipt, } from './compliance-receipt.js';
 export { AuditChainError, appendToChain, verifyAuditChain, } from './audit-chain.js';
+export { TransactionalError, transitionPreimage, transitionHash, buildTransactionalActionChain, } from './transactional.js';
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,EACL,aAAa,EACb,qBAAqB,EACrB,YAAY,EACZ,iBAAiB,EACjB,SAAS,GACV,MAAM,mBAAmB,CAAC;AAE3B,OAAO,EACL,cAAc,EAGd,SAAS,EACT,eAAe,GAChB,MAAM,iBAAiB,CAAC;AAEzB,OAAO,EACL,wBAAwB,EAExB,uBAAuB,GACxB,MAAM,4BAA4B,CAAC;AAEpC,OAAO,EACL,cAAc,EAEd,sBAAsB,EAGtB,sBAAsB,GACvB,MAAM,yBAAyB,CAAC;AAEjC,OAAO,EACL,eAAe,EAEf,aAAa,EACb,gBAAgB,GACjB,MAAM,kBAAkB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,EACL,aAAa,EACb,qBAAqB,EACrB,YAAY,EACZ,iBAAiB,EACjB,SAAS,GACV,MAAM,mBAAmB,CAAC;AAE3B,OAAO,EACL,cAAc,EAGd,SAAS,EACT,eAAe,GAChB,MAAM,iBAAiB,CAAC;AAEzB,OAAO,EACL,wBAAwB,EAExB,uBAAuB,GACxB,MAAM,4BAA4B,CAAC;AAEpC,OAAO,EACL,cAAc,EAEd,sBAAsB,EAGtB,sBAAsB,GACvB,MAAM,yBAAyB,CAAC;AAEjC,OAAO,EACL,eAAe,EAEf,aAAa,EACb,gBAAgB,GACjB,MAAM,kBAAkB,CAAC;AAE1B,OAAO,EACL,kBAAkB,EAMlB,kBAAkB,EAClB,cAAc,EACd,6BAA6B,GAC9B,MAAM,oBAAoB,CAAC"}

package/dist/transactional.d.ts

@@ -0,0 +1,103 @@
+/**
+ * Transactional action_ref lifecycle (non-normative substrate extension).
+ *
+ * For actions that traverse multiple state transitions
+ * (authorisation -> settlement -> refund; issuance -> execution ->
+ * revocation; admission -> review -> close), the action_ref four-field
+ * preimage is the STABLE identity anchor across the full lifecycle, and
+ * per-transition lifecycle metadata sits OUTSIDE the action_ref preimage.
+ *
+ * Invariants:
+ *
+ * 1. action_ref is byte-stable across every transition of the same action.
+ * 2. transition_hash is byte-stable for identical preimage tuples.
+ * 3. transition_hash differs per state for the same action_ref + timestamps.
+ * 4. action_ref and any transition_hash are byte-distinct.
+ * 5. All timestamp fields MUST be epoch-millisecond integers per
+ *    Substrate Rule 2. RFC 3339 string forms are rejected.
+ *
+ * State value is a non-empty string with no closed enum at the
+ * canonicalisation layer, consistent with the scope-field treatment.
+ */
+export declare class TransactionalError extends Error {
+    constructor(message: string);
+}
+export interface TransitionPreimage {
+    action_ref: string;
+    state: string;
+    transition_timestamp_ms: number;
+    authority_verified_at_ms: number;
+    revocation_check_at_ms: number;
+}
+export interface TransitionInput {
+    state: string;
+    transition_timestamp_ms: number;
+    authority_verified_at_ms: number;
+    revocation_check_at_ms: number;
+}
+export interface TransitionRecord extends TransitionInput {
+    transition_hash: string;
+}
+export interface TransactionalChain {
+    action_ref: string;
+    transitions: TransitionRecord[];
+}
+export interface TransactionalChainInput {
+    agent_id: string;
+    action_type: string;
+    scope: string;
+    timestamp_ms: number;
+    transitions: TransitionInput[];
+}
+/**
+ * Return the validated preimage object for a single transition.
+ *
+ * The five-field shape is fixed at the substrate layer; the action_ref
+ * field cryptographically binds the transition to its action identity.
+ */
+export declare function transitionPreimage(input: {
+    action_ref: string;
+    state: string;
+    transition_timestamp_ms: number;
+    authority_verified_at_ms: number;
+    revocation_check_at_ms: number;
+}): TransitionPreimage;
+/**
+ * Return the lowercase hex SHA-256 transition_hash.
+ *
+ * transition_hash = SHA-256(JCS({action_ref, state,
+ *                                transition_timestamp_ms,
+ *                                authority_verified_at_ms,
+ *                                revocation_check_at_ms}))
+ */
+export declare function transitionHash(input: {
+    action_ref: string;
+    state: string;
+    transition_timestamp_ms: number;
+    authority_verified_at_ms: number;
+    revocation_check_at_ms: number;
+}): string;
+/**
+ * Build a transactional action chain.
+ *
+ * Returns the chain shape:
+ *     {
+ *         action_ref: "<lowercase 64-char hex>",
+ *         transitions: [
+ *             {
+ *                 state, transition_timestamp_ms,
+ *                 authority_verified_at_ms, revocation_check_at_ms,
+ *                 transition_hash
+ *             },
+ *             ...
+ *         ]
+ *     }
+ *
+ * The action_ref is computed once and is byte-stable across every
+ * transition. Each transition_hash is bound to the action_ref by
+ * including it in the transition preimage. Transitions are processed
+ * in the order supplied; the substrate verifies determinism, not
+ * lifecycle semantics.
+ */
+export declare function buildTransactionalActionChain(input: TransactionalChainInput): TransactionalChain;
+//# sourceMappingURL=transactional.d.ts.map

package/dist/transactional.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"transactional.d.ts","sourceRoot":"","sources":["../src/transactional.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAOH,qBAAa,kBAAmB,SAAQ,KAAK;gBAC/B,OAAO,EAAE,MAAM;CAI5B;AAED,MAAM,WAAW,kBAAkB;IACjC,UAAU,EAAE,MAAM,CAAC;IACnB,KAAK,EAAE,MAAM,CAAC;IACd,uBAAuB,EAAE,MAAM,CAAC;IAChC,wBAAwB,EAAE,MAAM,CAAC;IACjC,sBAAsB,EAAE,MAAM,CAAC;CAChC;AAED,MAAM,WAAW,eAAe;IAC9B,KAAK,EAAE,MAAM,CAAC;IACd,uBAAuB,EAAE,MAAM,CAAC;IAChC,wBAAwB,EAAE,MAAM,CAAC;IACjC,sBAAsB,EAAE,MAAM,CAAC;CAChC;AAED,MAAM,WAAW,gBAAiB,SAAQ,eAAe;IACvD,eAAe,EAAE,MAAM,CAAC;CACzB;AAED,MAAM,WAAW,kBAAkB;IACjC,UAAU,EAAE,MAAM,CAAC;IACnB,WAAW,EAAE,gBAAgB,EAAE,CAAC;CACjC;AAED,MAAM,WAAW,uBAAuB;IACtC,QAAQ,EAAE,MAAM,CAAC;IACjB,WAAW,EAAE,MAAM,CAAC;IACpB,KAAK,EAAE,MAAM,CAAC;IACd,YAAY,EAAE,MAAM,CAAC;IACrB,WAAW,EAAE,eAAe,EAAE,CAAC;CAChC;AAgDD;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE;IACxC,UAAU,EAAE,MAAM,CAAC;IACnB,KAAK,EAAE,MAAM,CAAC;IACd,uBAAuB,EAAE,MAAM,CAAC;IAChC,wBAAwB,EAAE,MAAM,CAAC;IACjC,sBAAsB,EAAE,MAAM,CAAC;CAChC,GAAG,kBAAkB,CAiBrB;AAED;;;;;;;GAOG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE;IACpC,UAAU,EAAE,MAAM,CAAC;IACnB,KAAK,EAAE,MAAM,CAAC;IACd,uBAAuB,EAAE,MAAM,CAAC;IAChC,wBAAwB,EAAE,MAAM,CAAC;IACjC,sBAAsB,EAAE,MAAM,CAAC;CAChC,GAAG,MAAM,CAGT;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,6BAA6B,CAC3C,KAAK,EAAE,uBAAuB,GAC7B,kBAAkB,CAsDpB"}

package/dist/transactional.js

@@ -0,0 +1,161 @@
+/**
+ * Transactional action_ref lifecycle (non-normative substrate extension).
+ *
+ * For actions that traverse multiple state transitions
+ * (authorisation -> settlement -> refund; issuance -> execution ->
+ * revocation; admission -> review -> close), the action_ref four-field
+ * preimage is the STABLE identity anchor across the full lifecycle, and
+ * per-transition lifecycle metadata sits OUTSIDE the action_ref preimage.
+ *
+ * Invariants:
+ *
+ * 1. action_ref is byte-stable across every transition of the same action.
+ * 2. transition_hash is byte-stable for identical preimage tuples.
+ * 3. transition_hash differs per state for the same action_ref + timestamps.
+ * 4. action_ref and any transition_hash are byte-distinct.
+ * 5. All timestamp fields MUST be epoch-millisecond integers per
+ *    Substrate Rule 2. RFC 3339 string forms are rejected.
+ *
+ * State value is a non-empty string with no closed enum at the
+ * canonicalisation layer, consistent with the scope-field treatment.
+ */
+import { actionRef } from './action-ref.js';
+import { sha256Jcs } from './canonicalize.js';
+const HEX64_RE = /^[0-9a-f]{64}$/;
+export class TransactionalError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'TransactionalError';
+    }
+}
+function requireActionRefHex(value) {
+    if (typeof value !== 'string') {
+        throw new TransactionalError(`action_ref must be string, got ${typeof value}`);
+    }
+    if (!HEX64_RE.test(value)) {
+        throw new TransactionalError('action_ref must be a lowercase 64-character SHA-256 hex string');
+    }
+    return value;
+}
+function requireState(value) {
+    if (typeof value !== 'string') {
+        throw new TransactionalError(`state must be string, got ${typeof value}`);
+    }
+    if (value.length === 0) {
+        throw new TransactionalError('state must be a non-empty string');
+    }
+    return value;
+}
+function requireIntMs(field, value) {
+    if (typeof value !== 'number') {
+        throw new TransactionalError(`${field} must be epoch-millisecond integer (Substrate Rule 2), got ${typeof value}`);
+    }
+    if (!Number.isFinite(value)) {
+        throw new TransactionalError(`${field} must be a finite number, got ${value}`);
+    }
+    if (!Number.isInteger(value)) {
+        throw new TransactionalError(`${field} must be epoch-millisecond integer (Substrate Rule 2), got float ${value}`);
+    }
+    if (value < 0) {
+        throw new TransactionalError(`${field} must be non-negative, got ${value}`);
+    }
+    return value;
+}
+/**
+ * Return the validated preimage object for a single transition.
+ *
+ * The five-field shape is fixed at the substrate layer; the action_ref
+ * field cryptographically binds the transition to its action identity.
+ */
+export function transitionPreimage(input) {
+    return {
+        action_ref: requireActionRefHex(input.action_ref),
+        state: requireState(input.state),
+        transition_timestamp_ms: requireIntMs('transition_timestamp_ms', input.transition_timestamp_ms),
+        authority_verified_at_ms: requireIntMs('authority_verified_at_ms', input.authority_verified_at_ms),
+        revocation_check_at_ms: requireIntMs('revocation_check_at_ms', input.revocation_check_at_ms),
+    };
+}
+/**
+ * Return the lowercase hex SHA-256 transition_hash.
+ *
+ * transition_hash = SHA-256(JCS({action_ref, state,
+ *                                transition_timestamp_ms,
+ *                                authority_verified_at_ms,
+ *                                revocation_check_at_ms}))
+ */
+export function transitionHash(input) {
+    const obj = transitionPreimage(input);
+    return sha256Jcs(obj);
+}
+/**
+ * Build a transactional action chain.
+ *
+ * Returns the chain shape:
+ *     {
+ *         action_ref: "<lowercase 64-char hex>",
+ *         transitions: [
+ *             {
+ *                 state, transition_timestamp_ms,
+ *                 authority_verified_at_ms, revocation_check_at_ms,
+ *                 transition_hash
+ *             },
+ *             ...
+ *         ]
+ *     }
+ *
+ * The action_ref is computed once and is byte-stable across every
+ * transition. Each transition_hash is bound to the action_ref by
+ * including it in the transition preimage. Transitions are processed
+ * in the order supplied; the substrate verifies determinism, not
+ * lifecycle semantics.
+ */
+export function buildTransactionalActionChain(input) {
+    if (!Array.isArray(input.transitions)) {
+        throw new TransactionalError('transitions must be an array');
+    }
+    if (input.transitions.length === 0) {
+        throw new TransactionalError('transitions array must be non-empty');
+    }
+    const ar = actionRef({
+        agent_id: input.agent_id,
+        action_type: input.action_type,
+        scope: input.scope,
+        timestamp_ms: input.timestamp_ms,
+    });
+    const records = input.transitions.map((t, i) => {
+        if (t === null || typeof t !== 'object') {
+            throw new TransactionalError(`transitions[${i}] must be object, got ${typeof t}`);
+        }
+        const required = [
+            'state',
+            'transition_timestamp_ms',
+            'authority_verified_at_ms',
+            'revocation_check_at_ms',
+        ];
+        for (const k of required) {
+            if (!(k in t)) {
+                throw new TransactionalError(`transitions[${i}] missing required field '${k}'`);
+            }
+        }
+        const th = transitionHash({
+            action_ref: ar,
+            state: t.state,
+            transition_timestamp_ms: t.transition_timestamp_ms,
+            authority_verified_at_ms: t.authority_verified_at_ms,
+            revocation_check_at_ms: t.revocation_check_at_ms,
+        });
+        return {
+            state: t.state,
+            transition_timestamp_ms: t.transition_timestamp_ms,
+            authority_verified_at_ms: t.authority_verified_at_ms,
+            revocation_check_at_ms: t.revocation_check_at_ms,
+            transition_hash: th,
+        };
+    });
+    return {
+        action_ref: ar,
+        transitions: records,
+    };
+}
+//# sourceMappingURL=transactional.js.map

package/dist/transactional.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"transactional.js","sourceRoot":"","sources":["../src/transactional.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@algovoi/substrate",
-  "version": "0.2.1",
+  "version": "0.3.1",
   "description": "AlgoVoi agentic-payments substrate -- JCS canonicalisation, action_ref, composite trust-query, compliance receipts, audit chain",
   "keywords": [
     "x402",

package/src/index.ts

@@ -54,3 +54,15 @@ export {
   appendToChain,
   verifyAuditChain,
 } from './audit-chain.js';
+
+export {
+  TransactionalError,
+  type TransitionPreimage,
+  type TransitionInput,
+  type TransitionRecord,
+  type TransactionalChain,
+  type TransactionalChainInput,
+  transitionPreimage,
+  transitionHash,
+  buildTransactionalActionChain,
+} from './transactional.js';

package/src/transactional.ts

@@ -0,0 +1,241 @@
+/**
+ * Transactional action_ref lifecycle (non-normative substrate extension).
+ *
+ * For actions that traverse multiple state transitions
+ * (authorisation -> settlement -> refund; issuance -> execution ->
+ * revocation; admission -> review -> close), the action_ref four-field
+ * preimage is the STABLE identity anchor across the full lifecycle, and
+ * per-transition lifecycle metadata sits OUTSIDE the action_ref preimage.
+ *
+ * Invariants:
+ *
+ * 1. action_ref is byte-stable across every transition of the same action.
+ * 2. transition_hash is byte-stable for identical preimage tuples.
+ * 3. transition_hash differs per state for the same action_ref + timestamps.
+ * 4. action_ref and any transition_hash are byte-distinct.
+ * 5. All timestamp fields MUST be epoch-millisecond integers per
+ *    Substrate Rule 2. RFC 3339 string forms are rejected.
+ *
+ * State value is a non-empty string with no closed enum at the
+ * canonicalisation layer, consistent with the scope-field treatment.
+ */
+
+import { actionRef } from './action-ref.js';
+import { sha256Jcs } from './canonicalize.js';
+
+const HEX64_RE = /^[0-9a-f]{64}$/;
+
+export class TransactionalError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = 'TransactionalError';
+  }
+}
+
+export interface TransitionPreimage {
+  action_ref: string;
+  state: string;
+  transition_timestamp_ms: number;
+  authority_verified_at_ms: number;
+  revocation_check_at_ms: number;
+}
+
+export interface TransitionInput {
+  state: string;
+  transition_timestamp_ms: number;
+  authority_verified_at_ms: number;
+  revocation_check_at_ms: number;
+}
+
+export interface TransitionRecord extends TransitionInput {
+  transition_hash: string;
+}
+
+export interface TransactionalChain {
+  action_ref: string;
+  transitions: TransitionRecord[];
+}
+
+export interface TransactionalChainInput {
+  agent_id: string;
+  action_type: string;
+  scope: string;
+  timestamp_ms: number;
+  transitions: TransitionInput[];
+}
+
+function requireActionRefHex(value: unknown): string {
+  if (typeof value !== 'string') {
+    throw new TransactionalError(
+      `action_ref must be string, got ${typeof value}`,
+    );
+  }
+  if (!HEX64_RE.test(value)) {
+    throw new TransactionalError(
+      'action_ref must be a lowercase 64-character SHA-256 hex string',
+    );
+  }
+  return value;
+}
+
+function requireState(value: unknown): string {
+  if (typeof value !== 'string') {
+    throw new TransactionalError(`state must be string, got ${typeof value}`);
+  }
+  if (value.length === 0) {
+    throw new TransactionalError('state must be a non-empty string');
+  }
+  return value;
+}
+
+function requireIntMs(field: string, value: unknown): number {
+  if (typeof value !== 'number') {
+    throw new TransactionalError(
+      `${field} must be epoch-millisecond integer (Substrate Rule 2), got ${typeof value}`,
+    );
+  }
+  if (!Number.isFinite(value)) {
+    throw new TransactionalError(
+      `${field} must be a finite number, got ${value}`,
+    );
+  }
+  if (!Number.isInteger(value)) {
+    throw new TransactionalError(
+      `${field} must be epoch-millisecond integer (Substrate Rule 2), got float ${value}`,
+    );
+  }
+  if (value < 0) {
+    throw new TransactionalError(`${field} must be non-negative, got ${value}`);
+  }
+  return value;
+}
+
+/**
+ * Return the validated preimage object for a single transition.
+ *
+ * The five-field shape is fixed at the substrate layer; the action_ref
+ * field cryptographically binds the transition to its action identity.
+ */
+export function transitionPreimage(input: {
+  action_ref: string;
+  state: string;
+  transition_timestamp_ms: number;
+  authority_verified_at_ms: number;
+  revocation_check_at_ms: number;
+}): TransitionPreimage {
+  return {
+    action_ref: requireActionRefHex(input.action_ref),
+    state: requireState(input.state),
+    transition_timestamp_ms: requireIntMs(
+      'transition_timestamp_ms',
+      input.transition_timestamp_ms,
+    ),
+    authority_verified_at_ms: requireIntMs(
+      'authority_verified_at_ms',
+      input.authority_verified_at_ms,
+    ),
+    revocation_check_at_ms: requireIntMs(
+      'revocation_check_at_ms',
+      input.revocation_check_at_ms,
+    ),
+  };
+}
+
+/**
+ * Return the lowercase hex SHA-256 transition_hash.
+ *
+ * transition_hash = SHA-256(JCS({action_ref, state,
+ *                                transition_timestamp_ms,
+ *                                authority_verified_at_ms,
+ *                                revocation_check_at_ms}))
+ */
+export function transitionHash(input: {
+  action_ref: string;
+  state: string;
+  transition_timestamp_ms: number;
+  authority_verified_at_ms: number;
+  revocation_check_at_ms: number;
+}): string {
+  const obj = transitionPreimage(input);
+  return sha256Jcs(obj);
+}
+
+/**
+ * Build a transactional action chain.
+ *
+ * Returns the chain shape:
+ *     {
+ *         action_ref: "<lowercase 64-char hex>",
+ *         transitions: [
+ *             {
+ *                 state, transition_timestamp_ms,
+ *                 authority_verified_at_ms, revocation_check_at_ms,
+ *                 transition_hash
+ *             },
+ *             ...
+ *         ]
+ *     }
+ *
+ * The action_ref is computed once and is byte-stable across every
+ * transition. Each transition_hash is bound to the action_ref by
+ * including it in the transition preimage. Transitions are processed
+ * in the order supplied; the substrate verifies determinism, not
+ * lifecycle semantics.
+ */
+export function buildTransactionalActionChain(
+  input: TransactionalChainInput,
+): TransactionalChain {
+  if (!Array.isArray(input.transitions)) {
+    throw new TransactionalError('transitions must be an array');
+  }
+  if (input.transitions.length === 0) {
+    throw new TransactionalError('transitions array must be non-empty');
+  }
+
+  const ar = actionRef({
+    agent_id: input.agent_id,
+    action_type: input.action_type,
+    scope: input.scope,
+    timestamp_ms: input.timestamp_ms,
+  });
+
+  const records: TransitionRecord[] = input.transitions.map((t, i) => {
+    if (t === null || typeof t !== 'object') {
+      throw new TransactionalError(
+        `transitions[${i}] must be object, got ${typeof t}`,
+      );
+    }
+    const required = [
+      'state',
+      'transition_timestamp_ms',
+      'authority_verified_at_ms',
+      'revocation_check_at_ms',
+    ] as const;
+    for (const k of required) {
+      if (!(k in t)) {
+        throw new TransactionalError(
+          `transitions[${i}] missing required field '${k}'`,
+        );
+      }
+    }
+    const th = transitionHash({
+      action_ref: ar,
+      state: t.state,
+      transition_timestamp_ms: t.transition_timestamp_ms,
+      authority_verified_at_ms: t.authority_verified_at_ms,
+      revocation_check_at_ms: t.revocation_check_at_ms,
+    });
+    return {
+      state: t.state,
+      transition_timestamp_ms: t.transition_timestamp_ms,
+      authority_verified_at_ms: t.authority_verified_at_ms,
+      revocation_check_at_ms: t.revocation_check_at_ms,
+      transition_hash: th,
+    };
+  });
+
+  return {
+    action_ref: ar,
+    transitions: records,
+  };
+}