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

package/dist/mutation/values.d.ts

@@ -5,6 +5,10 @@
  * 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>;

package/dist/mutation/values.js

@@ -5,8 +5,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)) {

package/dist/runtime.d.ts

@@ -1,12 +1,48 @@
-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 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;
@@ -37,7 +73,9 @@ export interface AxiomRuntime {
     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

@@ -3,6 +3,34 @@ import { LocationResolutionError, resolveLocation } from './mutation/resolve-loc
 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';
+/**
+ * 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',
+    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 +58,19 @@ function defaultForType(type) {
             return null;
     }
 }
+/** 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 +97,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 +140,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,
@@ -126,7 +182,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 +191,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,
@@ -196,7 +252,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 } : {}),
@@ -243,7 +299,7 @@ export function createAxiomRuntime(options) {
                     return readState(expression.targetId);
                 }
                 report({
-                    code: 'UNRESOLVED_REFERENCE',
+                    code: RUNTIME_DIAGNOSTIC_CODES.UNRESOLVED_REFERENCE,
                     message: `Reference ${expression.targetId} could not be resolved`,
                     severity: 'error',
                     nodeId: expression.targetId,
@@ -280,6 +336,32 @@ export function createAxiomRuntime(options) {
                 }
                 return source.filter((item) => toBoolean(evaluate(expression.predicate, childScope(scope, expression.scopeId, item))));
             }
+            case 'map': {
+                const source = evaluate(expression.source, scope);
+                if (!Array.isArray(source)) {
+                    report({
+                        code: RUNTIME_DIAGNOSTIC_CODES.EXPRESSION_EVALUATION_FAILED,
+                        message: `map expects a collection but received ${describeValue(source)}`,
+                        severity: 'error',
+                    });
+                    return [];
+                }
+                return source.map((item) => evaluate(expression.projection, childScope(scope, expression.scopeId, item)));
+            }
+            case 'sort': {
+                const source = evaluate(expression.source, scope);
+                if (!Array.isArray(source)) {
+                    report({
+                        code: RUNTIME_DIAGNOSTIC_CODES.EXPRESSION_EVALUATION_FAILED,
+                        message: `sort expects a collection but received ${describeValue(source)}`,
+                        severity: 'error',
+                    });
+                    return [];
+                }
+                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 'find': {
                 const source = evaluate(expression.source, scope);
                 if (!Array.isArray(source)) {
@@ -290,7 +372,7 @@ export function createAxiomRuntime(options) {
             }
             default:
                 report({
-                    code: 'UNKNOWN_EXPRESSION',
+                    code: RUNTIME_DIAGNOSTIC_CODES.UNSUPPORTED_EXPRESSION,
                     message: `Unknown expression kind "${expression.kind}"`,
                     severity: 'error',
                 });
@@ -330,7 +412,7 @@ export function createAxiomRuntime(options) {
                 return divisor === 0 ? null : Number(left ?? 0) / divisor;
             }
             default:
-                report({ code: 'UNKNOWN_OPERATOR', message: `Unknown operator "${operator}"`, severity: 'error' });
+                report({ code: RUNTIME_DIAGNOSTIC_CODES.UNSUPPORTED_EXPRESSION, message: `Unknown operator "${operator}"`, severity: 'error' });
                 return null;
         }
     }
@@ -345,6 +427,34 @@ export function createAxiomRuntime(options) {
                 return Array.isArray(values[0]) ? values[0].length : toText(values[0]).length;
             case 'count':
                 return Array.isArray(values[0]) ? values[0].length : 0;
+            case 'sum': {
+                // An aggregation that cannot be computed must not quietly produce a value that
+                // makes a guard pass. It reports, and yields a number no comparison accepts.
+                const source = values[0];
+                if (!Array.isArray(source)) {
+                    report({
+                        code: RUNTIME_DIAGNOSTIC_CODES.EXPRESSION_EVALUATION_FAILED,
+                        message: `sum expects a collection of numbers but received ${describeValue(source)}`,
+                        severity: 'error',
+                        details: { received: source },
+                    });
+                    return Number.NaN;
+                }
+                let total = 0;
+                for (const member of source) {
+                    if (typeof member !== 'number' || !Number.isFinite(member)) {
+                        report({
+                            code: RUNTIME_DIAGNOSTIC_CODES.EXPRESSION_EVALUATION_FAILED,
+                            message: `sum encountered ${describeValue(member)} where a number was required`,
+                            severity: 'error',
+                            details: { member },
+                        });
+                        return Number.NaN;
+                    }
+                    total += member;
+                }
+                return total;
+            }
             case 'contains': {
                 const [haystack, needle] = values;
                 if (Array.isArray(haystack)) {
@@ -367,7 +477,7 @@ export function createAxiomRuntime(options) {
             case 'uuid':
                 return host.uuid();
             default:
-                report({ code: 'UNKNOWN_FUNCTION', message: `Unknown function "${fn}"`, severity: 'error' });
+                report({ code: RUNTIME_DIAGNOSTIC_CODES.UNSUPPORTED_EXPRESSION, message: `Unknown function "${fn}"`, severity: 'error' });
                 return null;
         }
     }
@@ -380,32 +490,51 @@ 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() {
+        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) {
-                continue;
-            }
-            const value = readState(state.id);
-            if (Array.isArray(value)) {
-                instances.push(...value);
-            }
-            else if (isRecord(value)) {
-                instances.push(value);
-            }
+            visit(readState(state.id), state.valueType);
         }
-        return instances;
+        return found;
+    }
+    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 +546,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 +555,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 +564,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 +573,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 +594,7 @@ export function createAxiomRuntime(options) {
             }
         }
         for (const constraint of ir.constraints) {
-            failures.push(...evaluateConstraint(constraint));
+            failures.push(...evaluateConstraint(constraint, instances));
         }
         return failures;
     }
@@ -503,15 +636,21 @@ 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 } } : {}),
             });
         };
         if (!constraint.entityId) {
@@ -520,10 +659,10 @@ export function createAxiomRuntime(options) {
             }
             return failures;
         }
-        for (const instance of instancesOf(constraint.entityId)) {
+        for (const instance of instances.get(constraint.entityId) ?? []) {
             const scope = childScope(rootScope(), constraint.entityId, instance);
             if (!toBoolean(evaluate(constraint.expression, scope))) {
-                record();
+                record(instance);
             }
         }
         return failures;
@@ -536,6 +675,29 @@ export function createAxiomRuntime(options) {
             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 = evaluate(operation.collection, scope);
+                if (!Array.isArray(members)) {
+                    result.push({
+                        code: RUNTIME_DIAGNOSTIC_CODES.EXPRESSION_EVALUATION_FAILED,
+                        message: `for-each expects a collection but received ${describeValue(members)}`,
+                        severity: 'error',
+                        ...(context.sourceNodeId ? { actionId: context.sourceNodeId } : {}),
+                    });
+                    return;
+                }
+                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 +715,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 +732,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 +752,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 +780,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 +789,29 @@ 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()) {
+            if (toBoolean(evaluate(precondition, scope))) {
+                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 +821,41 @@ 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'),
         ];
         for (const postcondition of action.postconditions ?? []) {
             if (!toBoolean(evaluate(postcondition, scope))) {
                 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) {
@@ -841,7 +1019,7 @@ export function createAxiomRuntime(options) {
         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,
@@ -988,7 +1166,7 @@ export function createAxiomRuntime(options) {
                             settle(transaction, 'rolled-back');
                             introduced.forEach(report);
                             report({
-                                code: 'INPUT_REJECTED',
+                                code: RUNTIME_DIAGNOSTIC_CODES.INPUT_REJECTED,
                                 message: `${node.label ?? node.id} kept its previous value: ${introduced[0].message}`,
                                 severity: 'warning',
                                 nodeId: node.id,
@@ -1036,7 +1214,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',
                 });
@@ -1117,6 +1295,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.0-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.0-alpha.1"
   },
   "scripts": {
     "build": "tsc -b tsconfig.json tsconfig.test.json",