@cynodia/axiom-runtime 0.3.1-alpha.1 → 0.4.1-alpha.1

package/dist/mutation/transaction.d.ts

@@ -16,6 +16,12 @@ export interface RuntimeTransaction {
 export interface TransactionManager {
     begin(): RuntimeTransaction;
     currentId(): string | undefined;
+    /**
+     * Committed state as it was immediately before the outermost open transaction began —
+     * what a transition rule means by "previous". Not the previous operation, not the
+     * previous iteration.
+     */
+    entrySnapshot(): unknown;
 }
 export declare function createTransactionManager(store: StoreSnapshot, nextId: () => string): TransactionManager;
 //# sourceMappingURL=transaction.d.ts.map

package/dist/mutation/transaction.js

@@ -2,6 +2,7 @@ export function createTransactionManager(store, nextId) {
     const open = [];
     return {
         currentId: () => open[0]?.id,
+        entrySnapshot: () => open[0]?.snapshot,
         begin() {
             const isRoot = open.length === 0;
             const id = isRoot ? nextId() : open[0].id;

package/dist/mutation/values.d.ts

@@ -1,3 +1,13 @@
+/**
+ * Raised when an expression cannot be evaluated — a collection operator applied to
+ * something that is not a collection, an aggregation over non-numeric data, a reference
+ * that does not resolve. Failing loudly is deliberate: an expression must never return a
+ * plausible-looking value and report a failure at the same time.
+ */
+export declare class ExpressionEvaluationError extends Error {
+    readonly details: Record<string, unknown>;
+    constructor(message: string, details?: Record<string, unknown>);
+}
 /**
  * Value helpers shared by the runtime and the mutation subsystem.
  *
@@ -5,11 +15,20 @@
  * throws in strict mode, which is what keeps "no implicit object mutation" an enforced
  * invariant rather than a convention.
  */
+/**
+ * A structured clone, not a JSON round trip: a JSON round trip turns values like NaN into
+ * null, which would silently disguise a failed computation as an absent one.
+ */
 export declare function cloneValue<T>(value: T): T;
 export declare function deepFreeze<T>(value: T): T;
 export declare function isRecord(value: unknown): value is Record<string, unknown>;
-/** Presence semantics used by `required` — distinct from boolean coercion. */
+/**
+ * Presence answers one question: does a value exist? It says nothing about whether the
+ * value is empty. An empty collection, an empty string, zero and false are all present.
+ */
 export declare function isPresent(value: unknown): boolean;
+/** Emptiness of a collection or a string. Anything else is never empty. */
+export declare function isEmptyValue(value: unknown): boolean;
 export declare function toBoolean(value: unknown): boolean;
 export declare function toText(value: unknown): string;
 export declare function compareValues(left: unknown, right: unknown): number;

package/dist/mutation/values.js

@@ -1,3 +1,17 @@
+/**
+ * Raised when an expression cannot be evaluated — a collection operator applied to
+ * something that is not a collection, an aggregation over non-numeric data, a reference
+ * that does not resolve. Failing loudly is deliberate: an expression must never return a
+ * plausible-looking value and report a failure at the same time.
+ */
+export class ExpressionEvaluationError extends Error {
+    details;
+    constructor(message, details = {}) {
+        super(message);
+        this.name = 'ExpressionEvaluationError';
+        this.details = details;
+    }
+}
 /**
  * Value helpers shared by the runtime and the mutation subsystem.
  *
@@ -5,8 +19,12 @@
  * throws in strict mode, which is what keeps "no implicit object mutation" an enforced
  * invariant rather than a convention.
  */
+/**
+ * A structured clone, not a JSON round trip: a JSON round trip turns values like NaN into
+ * null, which would silently disguise a failed computation as an absent one.
+ */
 export function cloneValue(value) {
-    return value === undefined ? value : JSON.parse(JSON.stringify(value));
+    return value === undefined ? value : structuredClone(value);
 }
 export function deepFreeze(value) {
     if (value === null || typeof value !== 'object' || Object.isFrozen(value)) {
@@ -20,18 +38,25 @@ export function deepFreeze(value) {
 export function isRecord(value) {
     return typeof value === 'object' && value !== null && !Array.isArray(value);
 }
-/** Presence semantics used by `required` — distinct from boolean coercion. */
+/**
+ * Presence answers one question: does a value exist? It says nothing about whether the
+ * value is empty. An empty collection, an empty string, zero and false are all present.
+ */
 export function isPresent(value) {
+    return value !== null && value !== undefined;
+}
+/** Emptiness of a collection or a string. Anything else is never empty. */
+export function isEmptyValue(value) {
     if (value === null || value === undefined) {
-        return false;
+        return true;
     }
     if (typeof value === 'string') {
-        return value.trim().length > 0;
+        return value.trim().length === 0;
     }
     if (Array.isArray(value)) {
-        return value.length > 0;
+        return value.length === 0;
     }
-    return true;
+    return false;
 }
 export function toBoolean(value) {
     if (Array.isArray(value)) {
@@ -59,6 +84,19 @@ export function compareValues(left, right) {
     const rightText = toText(right);
     return leftText === rightText ? 0 : leftText < rightText ? -1 : 1;
 }
+/** A stable serialization, so record comparison does not depend on key order. */
+function canonical(value) {
+    if (value === null || typeof value !== 'object') {
+        return JSON.stringify(value) ?? 'null';
+    }
+    if (Array.isArray(value)) {
+        return `[${value.map(canonical).join(',')}]`;
+    }
+    const entries = Object.entries(value)
+        .filter(([, entry]) => entry !== undefined)
+        .sort(([left], [right]) => (left < right ? -1 : left > right ? 1 : 0));
+    return `{${entries.map(([key, entry]) => `${JSON.stringify(key)}:${canonical(entry)}`).join(',')}}`;
+}
 export function valuesEqual(left, right) {
     if (left === right) {
         return true;
@@ -67,7 +105,7 @@ export function valuesEqual(left, right) {
         return (left ?? null) === (right ?? null);
     }
     if (typeof left === 'object' || typeof right === 'object') {
-        return JSON.stringify(left) === JSON.stringify(right);
+        return canonical(left) === canonical(right);
     }
     return false;
 }

package/dist/runtime.d.ts

@@ -1,12 +1,49 @@
-import type { ApplicationIR, CompiledRoute, FieldId, NodeId } from '@cynodia/axiom-core';
+import type { ApplicationIR, CompiledRoute, FieldId, Location, NodeId } from '@cynodia/axiom-core';
 import type { DomElement, HostEnvironment } from './dom.js';
 import type { MutationLogEntry } from './mutation/mutation-engine.js';
+/**
+ * The diagnostics a runtime can report. Agents match on the code rather than parsing the
+ * message, so this vocabulary is part of the public contract.
+ */
+export declare const RUNTIME_DIAGNOSTIC_CODES: {
+    readonly ACTION_NOT_FOUND: "ACTION_NOT_FOUND";
+    readonly PARAMETER_MISSING: "PARAMETER_MISSING";
+    readonly PRECONDITION_FAILED: "PRECONDITION_FAILED";
+    readonly POSTCONDITION_FAILED: "POSTCONDITION_FAILED";
+    readonly CONSTRAINT_VIOLATION: "CONSTRAINT_VIOLATION";
+    readonly REQUIRED_FIELD_MISSING: "REQUIRED_FIELD_MISSING";
+    readonly ENUM_VALUE_INVALID: "ENUM_VALUE_INVALID";
+    readonly TYPE_MISMATCH: "TYPE_MISMATCH";
+    readonly EXPRESSION_EVALUATION_FAILED: "EXPRESSION_EVALUATION_FAILED";
+    readonly UNRESOLVED_REFERENCE: "UNRESOLVED_REFERENCE";
+    readonly LOCATION_RESOLUTION_FAILED: "LOCATION_RESOLUTION_FAILED";
+    readonly MUTATION_FAILED: "MUTATION_FAILED";
+    readonly DERIVED_STATE_WRITE: "DERIVED_STATE_WRITE";
+    readonly UNKNOWN_STATE: "UNKNOWN_STATE";
+    readonly TRANSITION_CONSTRAINT_VIOLATION: "TRANSITION_CONSTRAINT_VIOLATION";
+    readonly UNSUPPORTED_EXPRESSION: "UNSUPPORTED_EXPRESSION";
+    readonly UNSUPPORTED_OPERATION: "UNSUPPORTED_OPERATION";
+    readonly ROUTE_NOT_FOUND: "ROUTE_NOT_FOUND";
+    readonly NATIVE_OPERATION_MISSING: "NATIVE_OPERATION_MISSING";
+    readonly UI_NODE_MISSING: "UI_NODE_MISSING";
+    readonly UNSUPPORTED_UI_NODE: "UNSUPPORTED_UI_NODE";
+    readonly INPUT_REJECTED: "INPUT_REJECTED";
+    readonly PERSISTED_STATE_UNREADABLE: "PERSISTED_STATE_UNREADABLE";
+};
+export type RuntimeDiagnosticCode = (typeof RUNTIME_DIAGNOSTIC_CODES)[keyof typeof RUNTIME_DIAGNOSTIC_CODES];
 export interface RuntimeDiagnostic {
-    code: string;
+    code: RuntimeDiagnosticCode;
     message: string;
     severity: 'error' | 'warning';
     nodeId?: NodeId;
     fieldId?: FieldId;
+    actionId?: NodeId;
+    constraintId?: NodeId;
+    stateId?: NodeId;
+    location?: Location;
+    transactionId?: string;
+    /** Structured context, so an agent never has to read the message. */
+    details?: Record<string, unknown>;
 }
 export interface ActionResult {
     ok: boolean;
@@ -33,11 +70,20 @@ export interface AxiomRuntime {
     start(): void;
     render(): void;
     getState(id: NodeId): unknown;
-    setState(id: NodeId, value: unknown): void;
+    /**
+     * Replaces a state value outright, for hosts, tests and seeding.
+     *
+     * This is an administrative facility, not a semantic write: it does not evaluate
+     * preconditions, entity constraints or transition constraints. Application behaviour
+     * belongs in actions and input bindings, which are governed.
+     */
+    hydrateState(id: NodeId, value: unknown): void;
     invokeAction(id: NodeId, args?: Record<string, unknown>): ActionResult;
     navigate(path: string): void;
     currentRoute(): RouteMatch | null;
+    /** Every diagnostic reported so far. Per-invocation results carry their own. */
     diagnostics(): RuntimeDiagnostic[];
+    clearDiagnostics(): void;
     /** Every mutation this runtime has applied, in order, with its semantic location. */
     getMutationLog(): MutationLogEntry[];
     registerNativeOperation(implementationId: string, implementation: NativeImplementation): void;

package/dist/runtime.js

@@ -2,7 +2,36 @@ import { createMutationEngine } from './mutation/mutation-engine.js';
 import { LocationResolutionError, resolveLocation } from './mutation/resolve-location.js';
 import { createStateStore } from './mutation/store.js';
 import { createTransactionManager } from './mutation/transaction.js';
-import { cloneValue, compareValues, deepFreeze, isPresent, isRecord, toBoolean, toText, valuesEqual, } from './mutation/values.js';
+import { ExpressionEvaluationError, cloneValue, compareValues, deepFreeze, isEmptyValue, isPresent, isRecord, toBoolean, toText, valuesEqual, } from './mutation/values.js';
+/**
+ * The diagnostics a runtime can report. Agents match on the code rather than parsing the
+ * message, so this vocabulary is part of the public contract.
+ */
+export const RUNTIME_DIAGNOSTIC_CODES = {
+    ACTION_NOT_FOUND: 'ACTION_NOT_FOUND',
+    PARAMETER_MISSING: 'PARAMETER_MISSING',
+    PRECONDITION_FAILED: 'PRECONDITION_FAILED',
+    POSTCONDITION_FAILED: 'POSTCONDITION_FAILED',
+    CONSTRAINT_VIOLATION: 'CONSTRAINT_VIOLATION',
+    REQUIRED_FIELD_MISSING: 'REQUIRED_FIELD_MISSING',
+    ENUM_VALUE_INVALID: 'ENUM_VALUE_INVALID',
+    TYPE_MISMATCH: 'TYPE_MISMATCH',
+    EXPRESSION_EVALUATION_FAILED: 'EXPRESSION_EVALUATION_FAILED',
+    UNRESOLVED_REFERENCE: 'UNRESOLVED_REFERENCE',
+    LOCATION_RESOLUTION_FAILED: 'LOCATION_RESOLUTION_FAILED',
+    MUTATION_FAILED: 'MUTATION_FAILED',
+    DERIVED_STATE_WRITE: 'DERIVED_STATE_WRITE',
+    UNKNOWN_STATE: 'UNKNOWN_STATE',
+    TRANSITION_CONSTRAINT_VIOLATION: 'TRANSITION_CONSTRAINT_VIOLATION',
+    UNSUPPORTED_EXPRESSION: 'UNSUPPORTED_EXPRESSION',
+    UNSUPPORTED_OPERATION: 'UNSUPPORTED_OPERATION',
+    ROUTE_NOT_FOUND: 'ROUTE_NOT_FOUND',
+    NATIVE_OPERATION_MISSING: 'NATIVE_OPERATION_MISSING',
+    UI_NODE_MISSING: 'UI_NODE_MISSING',
+    UNSUPPORTED_UI_NODE: 'UNSUPPORTED_UI_NODE',
+    INPUT_REJECTED: 'INPUT_REJECTED',
+    PERSISTED_STATE_UNREADABLE: 'PERSISTED_STATE_UNREADABLE',
+};
 const MISSING = Symbol('missing');
 function unwrapType(type) {
     return type.kind === 'optional' ? unwrapType(type.valueType) : type;
@@ -30,6 +59,30 @@ function defaultForType(type) {
             return null;
     }
 }
+/**
+ * Collection operators are strict about their source: `null` means a missing or invalid
+ * collection, and an empty collection means an empty collection. Conflating the two is
+ * what made 0.4 hard to reason about.
+ */
+function requireCollection(value, operator) {
+    if (!Array.isArray(value)) {
+        throw new ExpressionEvaluationError(`${operator} expects a collection but received ${describeValue(value)}`, { operator, received: value });
+    }
+    return value;
+}
+/** A short, structured description of a runtime value, for diagnostics. */
+function describeValue(value) {
+    if (value === null || value === undefined) {
+        return 'nothing';
+    }
+    if (Array.isArray(value)) {
+        return `a collection of ${value.length}`;
+    }
+    if (typeof value === 'object') {
+        return 'a record';
+    }
+    return `${typeof value} ${JSON.stringify(value)}`;
+}
 export function createAxiomRuntime(options) {
     const { ir, rootElement, host } = options;
     const store = createStateStore();
@@ -56,12 +109,27 @@ export function createAxiomRuntime(options) {
             parameterTypes.set(parameter.id, parameter.valueType);
         }
     }
+    /** Diagnostics reported while the current invocation runs, if one is collecting. */
+    let collector = null;
     function report(diagnostic) {
         diagnostics.push(diagnostic);
+        collector?.push(diagnostic);
         if (diagnostic.severity === 'error') {
             host.report?.(`${diagnostic.code}: ${diagnostic.message}`);
         }
     }
+    /** Runs `body` while gathering every diagnostic it reports. */
+    function collecting(body) {
+        const previous = collector;
+        const collected = [];
+        collector = collected;
+        try {
+            return body(collected);
+        }
+        finally {
+            collector = previous;
+        }
+    }
     // ---------------------------------------------------------------- state store
     function storageKey(state) {
         if (state.persistence?.kind !== 'local-storage') {
@@ -84,7 +152,7 @@ export function createAxiomRuntime(options) {
                     }
                     catch {
                         report({
-                            code: 'PERSISTED_STATE_UNREADABLE',
+                            code: RUNTIME_DIAGNOSTIC_CODES.PERSISTED_STATE_UNREADABLE,
                             message: `Stored value for ${state.id} could not be parsed; falling back to the initial value`,
                             severity: 'warning',
                             nodeId: state.id,
@@ -116,9 +184,16 @@ export function createAxiomRuntime(options) {
                 return derivedCache.get(stateId);
             }
             derivedCache.set(stateId, null);
-            const value = deepFreeze(cloneValue(evaluate(state.derivation, rootScope())));
-            derivedCache.set(stateId, value);
-            return value;
+            try {
+                const value = deepFreeze(cloneValue(evaluate(state.derivation, rootScope())));
+                derivedCache.set(stateId, value);
+                return value;
+            }
+            catch (error) {
+                report(evaluationFailure(error, { nodeId: state.id, stateId: state.id }));
+                derivedCache.set(stateId, null);
+                return null;
+            }
         }
         return store.read(stateId);
     }
@@ -126,7 +201,7 @@ export function createAxiomRuntime(options) {
     function writeState(stateId, value) {
         if (!statesById.has(stateId)) {
             report({
-                code: 'UNKNOWN_STATE',
+                code: RUNTIME_DIAGNOSTIC_CODES.UNKNOWN_STATE,
                 message: `Cannot write to unknown state ${stateId}`,
                 severity: 'error',
                 nodeId: stateId,
@@ -135,7 +210,7 @@ export function createAxiomRuntime(options) {
         }
         if (statesById.get(stateId)?.derivation) {
             report({
-                code: 'DERIVED_STATE_WRITE',
+                code: RUNTIME_DIAGNOSTIC_CODES.DERIVED_STATE_WRITE,
                 message: `${stateId} is derived state and cannot be written to`,
                 severity: 'error',
                 nodeId: stateId,
@@ -189,6 +264,28 @@ export function createAxiomRuntime(options) {
             }
         }
     }
+    /** Turns an evaluation failure into a diagnostic instead of letting it escape. */
+    function evaluationFailure(error, context = {}) {
+        if (error instanceof ExpressionEvaluationError) {
+            return {
+                code: RUNTIME_DIAGNOSTIC_CODES.EXPRESSION_EVALUATION_FAILED,
+                message: error.message,
+                severity: 'error',
+                ...context,
+                details: { ...error.details, ...(context.details ?? {}) },
+            };
+        }
+        throw error;
+    }
+    /** Evaluates an expression, reporting rather than throwing if it cannot be evaluated. */
+    function tryEvaluate(expression, scope, context = {}) {
+        try {
+            return { ok: true, value: evaluate(expression, scope) };
+        }
+        catch (error) {
+            return { ok: false, diagnostic: evaluationFailure(error, context) };
+        }
+    }
     /** Applies a mutation inside the current transaction and reports resolution failures. */
     function mutate(apply, context, failures) {
         try {
@@ -196,7 +293,7 @@ export function createAxiomRuntime(options) {
         }
         catch (error) {
             const failure = {
-                code: error instanceof LocationResolutionError ? 'LOCATION_UNRESOLVED' : 'MUTATION_FAILED',
+                code: error instanceof LocationResolutionError ? RUNTIME_DIAGNOSTIC_CODES.LOCATION_RESOLUTION_FAILED : 'MUTATION_FAILED',
                 message: error instanceof Error ? error.message : String(error),
                 severity: 'error',
                 ...(context.sourceNodeId ? { nodeId: context.sourceNodeId } : {}),
@@ -242,13 +339,7 @@ export function createAxiomRuntime(options) {
                 if (statesById.has(expression.targetId)) {
                     return readState(expression.targetId);
                 }
-                report({
-                    code: 'UNRESOLVED_REFERENCE',
-                    message: `Reference ${expression.targetId} could not be resolved`,
-                    severity: 'error',
-                    nodeId: expression.targetId,
-                });
-                return null;
+                throw new ExpressionEvaluationError(`Reference ${expression.targetId} could not be resolved`, { targetId: expression.targetId });
             }
             case 'field': {
                 const source = evaluate(expression.source, scope);
@@ -274,27 +365,42 @@ export function createAxiomRuntime(options) {
             case 'call':
                 return evaluateCall(expression.function, expression.arguments, scope);
             case 'filter': {
-                const source = evaluate(expression.source, scope);
-                if (!Array.isArray(source)) {
-                    return [];
-                }
+                const source = requireCollection(evaluate(expression.source, scope), 'filter');
                 return source.filter((item) => toBoolean(evaluate(expression.predicate, childScope(scope, expression.scopeId, item))));
             }
+            case 'map': {
+                const source = requireCollection(evaluate(expression.source, scope), 'map');
+                return source.map((item) => evaluate(expression.projection, childScope(scope, expression.scopeId, item)));
+            }
+            case 'sort': {
+                const source = requireCollection(evaluate(expression.source, scope), 'sort');
+                const direction = expression.direction === 'desc' ? -1 : 1;
+                const key = (item) => evaluate(expression.by, childScope(scope, expression.scopeId, item));
+                return [...source].sort((left, right) => direction * compareValues(key(left), key(right)));
+            }
+            case 'every': {
+                const source = requireCollection(evaluate(expression.source, scope), 'every');
+                return source.every((item) => toBoolean(evaluate(expression.predicate, childScope(scope, expression.scopeId, item))));
+            }
+            case 'some': {
+                const source = requireCollection(evaluate(expression.source, scope), 'some');
+                return source.some((item) => toBoolean(evaluate(expression.predicate, childScope(scope, expression.scopeId, item))));
+            }
+            case 'flatten': {
+                const source = requireCollection(evaluate(expression.source, scope), 'flatten');
+                return source.flatMap((member) => requireCollection(member, 'flatten'));
+            }
+            case 'conditional':
+                return toBoolean(evaluate(expression.condition, scope))
+                    ? evaluate(expression.whenTrue, scope)
+                    : evaluate(expression.whenFalse, scope);
             case 'find': {
-                const source = evaluate(expression.source, scope);
-                if (!Array.isArray(source)) {
-                    return null;
-                }
+                const source = requireCollection(evaluate(expression.source, scope), 'find');
                 const found = source.find((item) => toBoolean(evaluate(expression.predicate, childScope(scope, expression.scopeId, item))));
                 return found === undefined ? null : found;
             }
             default:
-                report({
-                    code: 'UNKNOWN_EXPRESSION',
-                    message: `Unknown expression kind "${expression.kind}"`,
-                    severity: 'error',
-                });
-                return null;
+                throw new ExpressionEvaluationError(`Unknown expression kind "${expression.kind}"`, { kind: expression.kind });
         }
     }
     function evaluateBinary(operator, leftExpression, rightExpression, scope) {
@@ -330,21 +436,36 @@ export function createAxiomRuntime(options) {
                 return divisor === 0 ? null : Number(left ?? 0) / divisor;
             }
             default:
-                report({ code: 'UNKNOWN_OPERATOR', message: `Unknown operator "${operator}"`, severity: 'error' });
-                return null;
+                throw new ExpressionEvaluationError(`Unknown operator "${operator}"`, { operator });
         }
     }
     function evaluateCall(fn, args, scope) {
         const values = args.map((argument) => evaluate(argument, scope));
         switch (fn) {
             case 'required':
+                // Presence only: an empty collection or string exists, and so does 0 and false.
                 return isPresent(values[0]);
             case 'is-empty':
-                return !isPresent(values[0]);
+                return isEmptyValue(values[0]);
+            case 'non-empty':
+                return !isEmptyValue(values[0]);
             case 'length':
                 return Array.isArray(values[0]) ? values[0].length : toText(values[0]).length;
             case 'count':
-                return Array.isArray(values[0]) ? values[0].length : 0;
+                return requireCollection(values[0], 'count').length;
+            case 'sum': {
+                // An aggregation that cannot be computed fails; it never returns a number that
+                // would quietly satisfy a guard.
+                const source = requireCollection(values[0], 'sum');
+                let total = 0;
+                for (const member of source) {
+                    if (typeof member !== 'number' || !Number.isFinite(member)) {
+                        throw new ExpressionEvaluationError(`sum encountered ${describeValue(member)} where a number was required`, { member });
+                    }
+                    total += member;
+                }
+                return total;
+            }
             case 'contains': {
                 const [haystack, needle] = values;
                 if (Array.isArray(haystack)) {
@@ -355,6 +476,7 @@ export function createAxiomRuntime(options) {
             case 'concat':
                 return values.map(toText).join('');
             case 'coalesce':
+                // Nullish, not "non-empty": falling back to an empty collection has to be possible.
                 return values.find((value) => isPresent(value)) ?? null;
             case 'one-of':
                 return values.slice(1).some((option) => valuesEqual(option, values[0]));
@@ -367,8 +489,7 @@ export function createAxiomRuntime(options) {
             case 'uuid':
                 return host.uuid();
             default:
-                report({ code: 'UNKNOWN_FUNCTION', message: `Unknown function "${fn}"`, severity: 'error' });
-                return null;
+                throw new ExpressionEvaluationError(`Unknown function "${fn}"`, { function: fn });
         }
     }
     // -------------------------------------------------------------- validation
@@ -380,32 +501,110 @@ export function createAxiomRuntime(options) {
         }
         return resolved.kind === 'entity' ? resolved.entityId : null;
     }
-    function instancesOf(entityId) {
-        const instances = [];
+    /**
+     * Every canonical occurrence of every entity, found by walking state values against
+     * their declared types. Entities nested inside collections and inside other entities
+     * are reached recursively, so their constraints apply wherever they actually live.
+     */
+    function collectInstances(read = readState) {
+        const found = new Map();
+        const visit = (value, type) => {
+            const resolved = unwrapType(type);
+            if (resolved.kind === 'collection') {
+                if (Array.isArray(value)) {
+                    for (const item of value) {
+                        visit(item, resolved.itemType);
+                    }
+                }
+                return;
+            }
+            if (resolved.kind !== 'entity' || !isRecord(value)) {
+                return;
+            }
+            const instances = found.get(resolved.entityId) ?? [];
+            instances.push(value);
+            found.set(resolved.entityId, instances);
+            for (const field of entitiesById.get(resolved.entityId)?.fields ?? []) {
+                visit(value[field.id], field.valueType);
+            }
+        };
         for (const state of ir.states) {
             // Drafts are incomplete by definition, and derived states are views of data that
             // is already validated where it is stored.
             if (state.draft || state.derivation) {
                 continue;
             }
-            if (collectionEntityId(state) !== entityId) {
+            visit(read(state.id), state.valueType);
+        }
+        return found;
+    }
+    /**
+     * Transition rules, evaluated against the state the transaction started from and the
+     * state it now proposes. Every governed mutation path runs this before committing, so a
+     * rule holds regardless of which path attempted the write.
+     */
+    function evaluateTransitions() {
+        const snapshot = transactions.entrySnapshot();
+        if (!snapshot || ir.transitionConstraints.length === 0) {
+            return [];
+        }
+        const previousInstances = collectInstances((stateId) => snapshot.get(stateId));
+        const proposedInstances = collectInstances();
+        const failures = [];
+        for (const rule of ir.transitionConstraints) {
+            const entity = entitiesById.get(rule.entityId);
+            const identity = entity?.identityFieldId;
+            if (!identity) {
                 continue;
             }
-            const value = readState(state.id);
-            if (Array.isArray(value)) {
-                instances.push(...value);
+            const identify = (instance) => (isRecord(instance) ? instance[identity] : undefined);
+            const proposedByIdentity = new Map();
+            for (const instance of proposedInstances.get(rule.entityId) ?? []) {
+                proposedByIdentity.set(toText(identify(instance)), instance);
             }
-            else if (isRecord(value)) {
-                instances.push(value);
+            for (const previous of previousInstances.get(rule.entityId) ?? []) {
+                const key = toText(identify(previous));
+                // A removed instance is a transition too: its proposed form is nothing.
+                const proposed = proposedByIdentity.get(key) ?? null;
+                if (proposed !== null && valuesEqual(previous, proposed)) {
+                    continue;
+                }
+                const scope = childScope(childScope(rootScope(), rule.previousScopeId, previous), rule.proposedScopeId, proposed);
+                const outcome = tryEvaluate(rule.expression, scope, {
+                    nodeId: rule.id,
+                    constraintId: rule.id,
+                });
+                if (outcome.ok && toBoolean(outcome.value)) {
+                    continue;
+                }
+                failures.push(outcome.ok
+                    ? {
+                        code: RUNTIME_DIAGNOSTIC_CODES.TRANSITION_CONSTRAINT_VIOLATION,
+                        message: rule.message ?? `Transition ${rule.name ?? rule.id} is not allowed`,
+                        severity: rule.severity ?? 'error',
+                        nodeId: rule.id,
+                        constraintId: rule.id,
+                        details: {
+                            transitionConstraintId: rule.id,
+                            entityId: rule.entityId,
+                            identity: identify(previous),
+                            previousValue: previous,
+                            proposedValue: proposed,
+                        },
+                    }
+                    : outcome.diagnostic);
             }
         }
-        return instances;
+        return failures;
+    }
+    function instancesOf(entityId) {
+        return collectInstances().get(entityId) ?? [];
     }
     function checkFieldValue(field, value, entityId) {
         if (!isPresent(value)) {
             if (field.required) {
                 return {
-                    code: 'REQUIRED_FIELD_MISSING',
+                    code: RUNTIME_DIAGNOSTIC_CODES.REQUIRED_FIELD_MISSING,
                     message: `${field.name ?? field.id} is required`,
                     severity: 'error',
                     nodeId: entityId,
@@ -417,7 +616,7 @@ export function createAxiomRuntime(options) {
         const resolved = unwrapType(field.valueType);
         if (resolved.kind === 'enum' && !resolved.values.includes(toText(value))) {
             return {
-                code: 'ENUM_VALUE_INVALID',
+                code: RUNTIME_DIAGNOSTIC_CODES.ENUM_VALUE_INVALID,
                 message: `${field.name ?? field.id} must be one of: ${resolved.values.join(', ')}`,
                 severity: 'error',
                 nodeId: entityId,
@@ -426,7 +625,7 @@ export function createAxiomRuntime(options) {
         }
         if (resolved.kind === 'primitive' && resolved.primitive === 'number' && typeof value !== 'number') {
             return {
-                code: 'TYPE_MISMATCH',
+                code: RUNTIME_DIAGNOSTIC_CODES.TYPE_MISMATCH,
                 message: `${field.name ?? field.id} must be a number`,
                 severity: 'error',
                 nodeId: entityId,
@@ -435,7 +634,7 @@ export function createAxiomRuntime(options) {
         }
         if (resolved.kind === 'primitive' && resolved.primitive === 'boolean' && typeof value !== 'boolean') {
             return {
-                code: 'TYPE_MISMATCH',
+                code: RUNTIME_DIAGNOSTIC_CODES.TYPE_MISMATCH,
                 message: `${field.name ?? field.id} must be a boolean`,
                 severity: 'error',
                 nodeId: entityId,
@@ -444,11 +643,15 @@ export function createAxiomRuntime(options) {
         }
         return null;
     }
-    /** Schema conformance plus declared constraints, evaluated over live instances. */
+    /**
+     * Schema conformance plus declared constraints, evaluated over every canonical instance
+     * — including instances nested inside collections and inside other entities.
+     */
     function evaluateInvariants() {
         const failures = [];
+        const instances = collectInstances();
         for (const entity of ir.entities) {
-            for (const instance of instancesOf(entity.id)) {
+            for (const instance of instances.get(entity.id) ?? []) {
                 if (!isRecord(instance)) {
                     continue;
                 }
@@ -461,7 +664,7 @@ export function createAxiomRuntime(options) {
             }
         }
         for (const constraint of ir.constraints) {
-            failures.push(...evaluateConstraint(constraint));
+            failures.push(...evaluateConstraint(constraint, instances));
         }
         return failures;
     }
@@ -503,39 +706,81 @@ export function createAxiomRuntime(options) {
         }
         return introduced;
     }
-    function evaluateConstraint(constraint) {
+    /**
+     * An entity-scoped constraint is evaluated once per instance, with `ref(entityId)`
+     * bound to the instance under validation.
+     */
+    function evaluateConstraint(constraint, instances) {
         const severity = constraint.severity ?? 'error';
         const failures = [];
-        const record = () => {
+        const record = (instance) => {
             failures.push({
-                code: 'CONSTRAINT_VIOLATION',
+                code: RUNTIME_DIAGNOSTIC_CODES.CONSTRAINT_VIOLATION,
                 message: constraint.message ?? `Constraint ${constraint.name ?? constraint.id} failed`,
                 severity,
                 nodeId: constraint.id,
+                constraintId: constraint.id,
+                ...(constraint.entityId ? { details: { entityId: constraint.entityId, instance } } : {}),
             });
         };
+        /** A constraint that cannot be evaluated counts as violated, never as satisfied. */
+        const holds = (scope) => {
+            const outcome = tryEvaluate(constraint.expression, scope, {
+                nodeId: constraint.id,
+                constraintId: constraint.id,
+            });
+            if (!outcome.ok) {
+                failures.push(outcome.diagnostic);
+                return false;
+            }
+            return toBoolean(outcome.value);
+        };
         if (!constraint.entityId) {
-            if (!toBoolean(evaluate(constraint.expression, rootScope()))) {
+            if (!holds(rootScope())) {
                 record();
             }
             return failures;
         }
-        for (const instance of instancesOf(constraint.entityId)) {
-            const scope = childScope(rootScope(), constraint.entityId, instance);
-            if (!toBoolean(evaluate(constraint.expression, scope))) {
-                record();
+        for (const instance of instances.get(constraint.entityId) ?? []) {
+            if (!holds(childScope(rootScope(), constraint.entityId, instance))) {
+                record(instance);
             }
         }
         return failures;
     }
     // --------------------------------------------------------------- behaviour
     function executeOperation(operation, scope, context, result) {
+        try {
+            executeOperationUnguarded(operation, scope, context, result);
+        }
+        catch (error) {
+            result.push(evaluationFailure(error, {
+                ...(context.sourceNodeId ? { nodeId: context.sourceNodeId, actionId: context.sourceNodeId } : {}),
+                ...(context.transactionId ? { transactionId: context.transactionId } : {}),
+            }));
+        }
+    }
+    function executeOperationUnguarded(operation, scope, context, result) {
         switch (operation.kind) {
             case 'set':
             case 'insert':
             case 'remove':
                 mutate(() => mutations.apply(operation, scope, context), context, result);
                 return;
+            case 'for-each': {
+                // The members are read once, before any of them are mutated, so the iteration
+                // walks the collection as it stood when the operation began. Nothing here opens
+                // a transaction: these mutations belong to the action's own transaction, and a
+                // failure in any iteration rolls back every iteration with it.
+                const members = requireCollection(evaluate(operation.collection, scope), 'for-each');
+                for (const member of members) {
+                    const iteration = childScope(scope, operation.scopeId, member);
+                    for (const nested of operation.operations ?? []) {
+                        executeOperation(nested, iteration, context, result);
+                    }
+                }
+                return;
+            }
             case 'invoke': {
                 const args = {};
                 for (const [parameterId, argument] of Object.entries(operation.arguments ?? {})) {
@@ -553,7 +798,7 @@ export function createAxiomRuntime(options) {
                 const route = ir.routes.find((candidate) => candidate.id === operation.routeId);
                 if (!route) {
                     result.push({
-                        code: 'ROUTE_NOT_FOUND',
+                        code: RUNTIME_DIAGNOSTIC_CODES.ROUTE_NOT_FOUND,
                         message: `Navigate operation could not resolve route ${String(operation.routeId)}`,
                         severity: 'error',
                     });
@@ -570,7 +815,7 @@ export function createAxiomRuntime(options) {
                 const implementation = natives.get(operation.implementationId);
                 if (!implementation) {
                     result.push({
-                        code: 'NATIVE_OPERATION_MISSING',
+                        code: RUNTIME_DIAGNOSTIC_CODES.NATIVE_OPERATION_MISSING,
                         message: `No implementation registered for "${operation.implementationId}"`,
                         severity: 'error',
                     });
@@ -590,22 +835,25 @@ export function createAxiomRuntime(options) {
             }
             default:
                 result.push({
-                    code: 'UNKNOWN_OPERATION',
+                    code: RUNTIME_DIAGNOSTIC_CODES.UNSUPPORTED_OPERATION,
                     message: `Unknown operation kind "${operation.kind}"`,
                     severity: 'error',
                 });
         }
     }
     function runAction(actionId, args = {}) {
+        return collecting((collected) => runActionCollecting(actionId, args, collected));
+    }
+    function runActionCollecting(actionId, args, collected) {
         const action = ir.actions[actionId];
         if (!action) {
             const failure = {
-                code: 'ACTION_NOT_FOUND',
+                code: RUNTIME_DIAGNOSTIC_CODES.ACTION_NOT_FOUND,
                 message: `Action ${actionId} is not defined`,
                 severity: 'error',
             };
             report(failure);
-            return { ok: false, diagnostics: [failure] };
+            return { ok: false, diagnostics: [...collected] };
         }
         const scope = rootScope();
         for (const parameter of action.parameters ?? []) {
@@ -615,7 +863,7 @@ export function createAxiomRuntime(options) {
         for (const parameter of action.parameters ?? []) {
             if (parameter.required && !isPresent(scope.values.get(parameter.id))) {
                 failures.push({
-                    code: 'PARAMETER_MISSING',
+                    code: RUNTIME_DIAGNOSTIC_CODES.PARAMETER_MISSING,
                     message: `Action ${action.name ?? action.id} requires ${parameter.name ?? parameter.id}`,
                     severity: 'error',
                     nodeId: action.id,
@@ -624,25 +872,34 @@ export function createAxiomRuntime(options) {
         }
         if (failures.length > 0) {
             failures.forEach(report);
-            return { ok: false, diagnostics: failures };
-        }
-        for (const precondition of action.preconditions ?? []) {
-            if (!toBoolean(evaluate(precondition, scope))) {
-                const failure = {
-                    code: 'PRECONDITION_FAILED',
-                    message: action.failureModes?.[0]?.message ??
-                        `A precondition of ${action.name ?? action.id} was not satisfied`,
-                    severity: 'error',
-                    nodeId: action.id,
-                };
-                report(failure);
-                return { ok: false, diagnostics: [failure] };
+            return { ok: false, diagnostics: [...collected] };
+        }
+        // Failure modes line up with preconditions by position, so a refusal says which
+        // condition was not met rather than always naming the first one.
+        for (const [index, precondition] of (action.preconditions ?? []).entries()) {
+            const outcome = tryEvaluate(precondition, scope, { nodeId: action.id, actionId: action.id });
+            if (!outcome.ok) {
+                report(outcome.diagnostic);
+                return { ok: false, diagnostics: [...collected] };
+            }
+            if (toBoolean(outcome.value)) {
+                continue;
             }
+            const mode = action.failureModes?.[index];
+            report({
+                code: RUNTIME_DIAGNOSTIC_CODES.PRECONDITION_FAILED,
+                message: mode?.message ?? `A precondition of ${action.name ?? action.id} was not satisfied`,
+                severity: 'error',
+                nodeId: action.id,
+                actionId: action.id,
+                details: { preconditionIndex: index, ...(mode?.code ? { failureMode: mode.code } : {}) },
+            });
+            return { ok: false, diagnostics: [...collected] };
         }
         if (action.requiresConfirmation) {
             const message = action.confirmationMessage ?? `Confirm ${action.name ?? action.id}. This cannot be undone.`;
             if (!host.confirm(message)) {
-                return { ok: false, diagnostics: [] };
+                return { ok: false, diagnostics: [...collected] };
             }
         }
         const transaction = transactions.begin();
@@ -652,32 +909,46 @@ export function createAxiomRuntime(options) {
             transactionId: transaction.id,
         };
         const operationDiagnostics = [];
+        const reportedBefore = collected.length;
         for (const operation of action.operations ?? []) {
             executeOperation(operation, scope, context, operationDiagnostics);
         }
+        // Anything reported while the operations ran — an expression that could not be
+        // evaluated, for instance — is a failure of this action, not a passing curiosity.
         const violations = [
             ...operationDiagnostics.filter((diagnostic) => diagnostic.severity === 'error'),
+            ...collected.slice(reportedBefore).filter((diagnostic) => diagnostic.severity === 'error'),
             ...evaluateInvariants().filter((diagnostic) => diagnostic.severity === 'error'),
+            ...evaluateTransitions().filter((diagnostic) => diagnostic.severity === 'error'),
         ];
         for (const postcondition of action.postconditions ?? []) {
-            if (!toBoolean(evaluate(postcondition, scope))) {
+            const outcome = tryEvaluate(postcondition, scope, { nodeId: action.id, actionId: action.id });
+            if (!outcome.ok || !toBoolean(outcome.value)) {
+                if (!outcome.ok) {
+                    violations.push(outcome.diagnostic);
+                }
                 violations.push({
-                    code: 'POSTCONDITION_FAILED',
+                    code: RUNTIME_DIAGNOSTIC_CODES.POSTCONDITION_FAILED,
                     message: `A postcondition of ${action.name ?? action.id} was not satisfied`,
                     severity: 'error',
                     nodeId: action.id,
+                    actionId: action.id,
                 });
             }
         }
         if (violations.length > 0) {
             settle(transaction, 'rolled-back');
-            violations.forEach(report);
+            for (const violation of violations) {
+                if (!collected.includes(violation)) {
+                    report({ ...violation, actionId: action.id, transactionId: transaction.id });
+                }
+            }
             renderApplication();
-            return { ok: false, diagnostics: violations };
+            return { ok: false, diagnostics: [...collected] };
         }
         settle(transaction, 'committed');
         renderApplication();
-        return { ok: true, diagnostics: operationDiagnostics };
+        return { ok: true, diagnostics: [...collected] };
     }
     // ------------------------------------------------------------------ routing
     function buildPath(route, values) {
@@ -838,10 +1109,19 @@ export function createAxiomRuntime(options) {
         return raw;
     }
     function renderNode(id, scope) {
+        try {
+            return renderNodeUnguarded(id, scope);
+        }
+        catch (error) {
+            report(evaluationFailure(error, { nodeId: id }));
+            return null;
+        }
+    }
+    function renderNodeUnguarded(id, scope) {
         const node = ir.uiNodes[id];
         if (!node) {
             report({
-                code: 'UI_NODE_MISSING',
+                code: RUNTIME_DIAGNOSTIC_CODES.UI_NODE_MISSING,
                 message: `UI node ${id} is not defined`,
                 severity: 'error',
                 nodeId: id,
@@ -983,15 +1263,21 @@ export function createAxiomRuntime(options) {
                         failures.forEach(report);
                     }
                     else {
-                        const introduced = before ? violationsIntroducedSince(before) : [];
-                        if (introduced.length > 0) {
+                        // A transition rule always applies: it compares against the state this
+                        // mutation started from, so it can never be a pre-existing violation.
+                        const rejected = [
+                            ...(before ? violationsIntroducedSince(before) : []),
+                            ...evaluateTransitions().filter((diagnostic) => diagnostic.severity === 'error'),
+                        ];
+                        if (rejected.length > 0) {
                             settle(transaction, 'rolled-back');
-                            introduced.forEach(report);
+                            rejected.forEach((diagnostic) => report({ ...diagnostic, details: { ...diagnostic.details, source: 'input', nodeId: node.id } }));
                             report({
-                                code: 'INPUT_REJECTED',
-                                message: `${node.label ?? node.id} kept its previous value: ${introduced[0].message}`,
+                                code: RUNTIME_DIAGNOSTIC_CODES.INPUT_REJECTED,
+                                message: `${node.label ?? node.id} kept its previous value: ${rejected[0].message}`,
                                 severity: 'warning',
                                 nodeId: node.id,
+                                details: { source: 'input' },
                             });
                         }
                         else {
@@ -1036,7 +1322,7 @@ export function createAxiomRuntime(options) {
             }
             default:
                 report({
-                    code: 'UNKNOWN_UI_NODE',
+                    code: RUNTIME_DIAGNOSTIC_CODES.UNSUPPORTED_UI_NODE,
                     message: `Unknown UI node kind "${node.kind}"`,
                     severity: 'error',
                 });
@@ -1093,7 +1379,7 @@ export function createAxiomRuntime(options) {
         getState(id) {
             return cloneValue(readState(id));
         },
-        setState(id, value) {
+        hydrateState(id, value) {
             const transaction = transactions.begin();
             const failures = [];
             const context = { source: 'system', transactionId: transaction.id };
@@ -1117,6 +1403,9 @@ export function createAxiomRuntime(options) {
         diagnostics() {
             return diagnostics.map((diagnostic) => ({ ...diagnostic }));
         },
+        clearDiagnostics() {
+            diagnostics.length = 0;
+        },
         getMutationLog() {
             return mutationLog.map((entry) => ({ ...entry }));
         },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cynodia/axiom-runtime",
-  "version": "0.3.1-alpha.1",
+  "version": "0.4.1-alpha.1",
   "description": "Domain-independent runtime that executes an Axiom application graph.",
   "license": "MIT",
   "author": "AskTech AS",
@@ -31,7 +31,7 @@
     }
   },
   "dependencies": {
-    "@cynodia/axiom-core": "0.3.1-alpha.1"
+    "@cynodia/axiom-core": "0.4.1-alpha.1"
   },
   "scripts": {
     "build": "tsc -b tsconfig.json tsconfig.test.json",