@cynodia/axiom-runtime 0.5.0-alpha.1 → 0.6.0-alpha.1

package/README.md

@@ -9,9 +9,12 @@ The domain-independent runtime: the state store, expression evaluation, the muta
 engine, constraint checking, the semantic UI renderer and routing. It takes its whole
 environment through a `HostEnvironment`, so it runs in a browser or headlessly.
 
-The renderer reads presentation that the compiler has already resolved and turns it into
+The renderer reads presentation the compiler has already resolved and turns it into
 semantic class names, landmark and heading elements, and formatted values. It writes no
-styles and computes no lengths — what those classes mean is the theme's business.
+styles and computes no lengths.
+
+Main exports: `createAxiomRuntime`, `createBrowserHost`, `createMemoryHost`,
+`RUNTIME_DIAGNOSTIC_CODES`, `formatValue`, `presentationClassList`.
 
 ## Installation
 
@@ -25,6 +28,13 @@ Most applications should install the facade package instead, which re-exports th
 npm install @cynodia/axiom@alpha
 ```
 
+
+## Documentation
+
+The canonical operational contract lives in the `docs/` directory of the
+[`@cynodia/axiom`](https://www.npmjs.com/package/@cynodia/axiom) package, and in
+[the repository](https://github.com/cynodia/axiom). Start with `docs/AGENT_REFERENCE.md`.
+
 ## License
 
 MIT

package/dist/presentation-classes.d.ts

@@ -1,4 +1,4 @@
-import type { ResolvedPresentation, TextRole, UxRole } from '@cynodia/axiom-core';
+import type { ResolvedPresentation, UxRole } from '@cynodia/axiom-core';
 /** Every class a node's resolved presentation implies, in a stable order. */
 export declare function presentationClassList(resolved: ResolvedPresentation | undefined): string[];
 export declare function presentationClasses(resolved: ResolvedPresentation | undefined, ...extra: string[]): string;
@@ -9,10 +9,13 @@ export declare function presentationClasses(resolved: ResolvedPresentation | und
 export declare function landmarkTag(uxRole: UxRole | undefined): string | undefined;
 /**
  * Headings are real headings, so the document has an outline rather than a set of large
- * words. The three heading text roles are three levels: an application title, a title
- * within it, and a section heading under that.
+ * words.
+ *
+ * The element follows the resolved **`headingLevel`**, never the type scale: a value drawn
+ * at `display` size with `headingLevel: 'none'` is a `<span>`, which is what a monetary
+ * total or a dashboard statistic should be.
  */
-export declare function headingTag(textRole: TextRole | undefined): string | undefined;
+export declare function headingTag(resolved: ResolvedPresentation | undefined): string | undefined;
 /** The ARIA role a UX role implies, where one is warranted. */
 export declare function ariaRoleFor(uxRole: UxRole | undefined): string | undefined;
 //# sourceMappingURL=presentation-classes.d.ts.map

package/dist/presentation-classes.js

@@ -6,7 +6,12 @@
  * the same resolved presentation can drive an entirely different renderer.
  */
 function layoutClasses(prefix, layout) {
-    const classes = [`axiom-${prefix}layout-${layout.kind}`, `axiom-${prefix}gap-${layout.gap}`];
+    // A `none` token is the absence of the property, not a value to assert. Emitting it
+    // would override the component rules that give a control its own metrics.
+    const classes = [`axiom-${prefix}layout-${layout.kind}`];
+    if (layout.gap !== 'none') {
+        classes.push(`axiom-${prefix}gap-${layout.gap}`);
+    }
     if (!prefix) {
         classes.push(`axiom-align-${layout.align}`, `axiom-justify-${layout.justify}`);
         classes.push(layout.wrap ? 'axiom-wrap' : 'axiom-nowrap');
@@ -32,7 +37,14 @@ function sizingClasses(prefix, sizing) {
     return classes;
 }
 function paddingClasses(prefix, padding) {
-    return [`axiom-${prefix}pad-x-${padding.horizontal}`, `axiom-${prefix}pad-y-${padding.vertical}`];
+    const classes = [];
+    if (padding.horizontal !== 'none') {
+        classes.push(`axiom-${prefix}pad-x-${padding.horizontal}`);
+    }
+    if (padding.vertical !== 'none') {
+        classes.push(`axiom-${prefix}pad-y-${padding.vertical}`);
+    }
+    return classes;
 }
 function responsiveClasses(device, override) {
     const prefix = `${device}-`;
@@ -115,20 +127,15 @@ export function landmarkTag(uxRole) {
 }
 /**
  * Headings are real headings, so the document has an outline rather than a set of large
- * words. The three heading text roles are three levels: an application title, a title
- * within it, and a section heading under that.
+ * words.
+ *
+ * The element follows the resolved **`headingLevel`**, never the type scale: a value drawn
+ * at `display` size with `headingLevel: 'none'` is a `<span>`, which is what a monetary
+ * total or a dashboard statistic should be.
  */
-export function headingTag(textRole) {
-    switch (textRole) {
-        case 'display':
-            return 'h1';
-        case 'title':
-            return 'h2';
-        case 'heading':
-            return 'h3';
-        default:
-            return undefined;
-    }
+export function headingTag(resolved) {
+    const level = resolved?.headingLevel;
+    return typeof level === 'number' ? `h${level}` : undefined;
 }
 /** The ARIA role a UX role implies, where one is warranted. */
 export function ariaRoleFor(uxRole) {

package/dist/runtime.d.ts

@@ -1,4 +1,4 @@
-import type { ApplicationIR, CompiledRoute, FieldId, Location, NodeId } from '@cynodia/axiom-core';
+import type { ApplicationIR, CompiledRoute, Expression, FieldId, Location, NodeId } from '@cynodia/axiom-core';
 import type { DomElement, HostEnvironment } from './dom.js';
 import type { MutationLogEntry } from './mutation/mutation-engine.js';
 /**
@@ -29,8 +29,16 @@ export declare const RUNTIME_DIAGNOSTIC_CODES: {
     readonly UNSUPPORTED_UI_NODE: "UNSUPPORTED_UI_NODE";
     readonly INPUT_REJECTED: "INPUT_REJECTED";
     readonly PERSISTED_STATE_UNREADABLE: "PERSISTED_STATE_UNREADABLE";
+    /** A local write was attempted against state whose authority is the server. */
+    readonly SERVER_STATE_WRITE: "SERVER_STATE_WRITE";
+    /** An action belongs to the authority, but no gateway to it was configured. */
+    readonly REMOTE_ACTION_UNAVAILABLE: "REMOTE_ACTION_UNAVAILABLE";
 };
 export type RuntimeDiagnosticCode = (typeof RUNTIME_DIAGNOSTIC_CODES)[keyof typeof RUNTIME_DIAGNOSTIC_CODES];
+/**
+ * A structured runtime failure. Match on `code` and read `details`; the `message` is for
+ * people and is not a stable contract.
+ */
 export interface RuntimeDiagnostic {
     code: RuntimeDiagnosticCode;
     message: string;
@@ -48,6 +56,48 @@ export interface RuntimeDiagnostic {
 export interface ActionResult {
     ok: boolean;
     diagnostics: RuntimeDiagnostic[];
+    /**
+     * Set when the invocation was dispatched to the authority. `ok` is not yet meaningful:
+     * the outcome arrives later, and reaches the interface through the action's recorded
+     * outcome and any `diagnostic` node presenting it.
+     */
+    pending?: true;
+}
+/**
+ * How a client reaches the authority.
+ *
+ * The client requests **semantic actions**; it never sends operations. A remote invocation
+ * is dispatched and answered later, so `invokeAction` returns `pending` and the outcome
+ * arrives through the same diagnostic lifecycle a local refusal uses.
+ */
+export interface RemoteGateway {
+    invoke(request: {
+        actionId: NodeId;
+        arguments: Record<string, unknown>;
+        requestId: string;
+    }): Promise<{
+        ok: boolean;
+        diagnostics: RuntimeDiagnostic[];
+        changes: Record<NodeId, unknown>;
+    }>;
+    /** The authoritative values of every observable state. */
+    snapshot?(): Promise<{
+        states: Record<NodeId, unknown>;
+    }>;
+}
+/**
+ * The outcome of an action's most recent invocation.
+ *
+ * `ok` and `cancelled` both carry no diagnostics, so a `diagnostic` UI node presenting
+ * this action shows nothing after either. They are distinguished here because the
+ * difference matters to an agent: `cancelled` means a person declined the confirmation,
+ * not that the action was refused.
+ */
+export interface ActionOutcome {
+    actionId: NodeId;
+    /** `pending` means the request is with the authority and the outcome is not yet known. */
+    outcome: 'ok' | 'failed' | 'cancelled' | 'pending';
+    diagnostics: RuntimeDiagnostic[];
 }
 export interface RouteMatch {
     route: CompiledRoute;
@@ -55,13 +105,22 @@ export interface RouteMatch {
     parameters: Record<string, string>;
 }
 export type NativeImplementation = (inputs: Record<string, unknown>) => unknown;
-/** When constraints are evaluated after an input writes to its location. */
+/**
+ * When entity constraints are evaluated after an input writes to its location.
+ * `'deferred'` turns the per-keystroke check off entirely, leaving validity to the next
+ * action. Transition constraints are unaffected by this setting and always apply.
+ */
 export type InputValidationMode = 'immediate' | 'deferred';
 export interface AxiomRuntimeOptions {
     ir: ApplicationIR;
     rootElement: DomElement;
     host: HostEnvironment;
     nativeOperations?: Record<string, NativeImplementation>;
+    /**
+     * How to reach the authority. Required if the application has server-authoritative
+     * state; without it a remote invocation reports `REMOTE_ACTION_UNAVAILABLE`.
+     */
+    remote?: RemoteGateway;
     inputValidation?: InputValidationMode;
     /** Records previous and next values in the mutation log. */
     recordMutationValues?: boolean;
@@ -69,6 +128,7 @@ export interface AxiomRuntimeOptions {
 export interface AxiomRuntime {
     start(): void;
     render(): void;
+    /** A deep clone of the value. Derived state is recomputed. */
     getState(id: NodeId): unknown;
     /**
      * Replaces a state value outright, for hosts, tests and seeding.
@@ -78,15 +138,50 @@ export interface AxiomRuntime {
      * belongs in actions and input bindings, which are governed.
      */
     hydrateState(id: NodeId, value: unknown): void;
+    /**
+     * Runs an action as a transaction and returns the diagnostics **of that invocation**,
+     * so nothing has to diff global history. Either every mutation commits or every one is
+     * rolled back.
+     */
     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[];
+    /** Clears the running log **and** every recorded action outcome. */
     clearDiagnostics(): void;
+    /**
+     * The outcome of this action's most recent invocation, or `undefined` if it has not been
+     * invoked since the last clear or route change. This is what a `diagnostic` UI node
+     * presents.
+     */
+    getActionOutcome(id: NodeId): ActionOutcome | undefined;
     /** Every mutation this runtime has applied, in order, with its semantic location. */
     getMutationLog(): MutationLogEntry[];
     registerNativeOperation(implementationId: string, implementation: NativeImplementation): void;
+    /**
+     * Invokes an action and waits for its outcome. For a remote action this awaits the
+     * authority's answer; for a local one it is `invokeAction` in promise form.
+     */
+    invokeActionAsync(id: NodeId, args?: Record<string, unknown>): Promise<ActionResult>;
+    /**
+     * Loads the authoritative snapshot and applies it. Called by `start()` when a gateway
+     * provides one.
+     */
+    syncAuthoritativeState(): Promise<void>;
+    /**
+     * Evaluates an expression in the root scope, reporting rather than throwing. It is a
+     * pure read: an expression cannot change state.
+     *
+     * An authority uses it to evaluate an authorization rule before opening a transaction.
+     */
+    evaluate(expression: Expression): {
+        ok: true;
+        value: unknown;
+    } | {
+        ok: false;
+        diagnostic: RuntimeDiagnostic;
+    };
 }
 export declare function createAxiomRuntime(options: AxiomRuntimeOptions): AxiomRuntime;
 /** Builds a host bound to the browser globals. Used by generated pages. */

package/dist/runtime.js

@@ -33,6 +33,10 @@ export const RUNTIME_DIAGNOSTIC_CODES = {
     UNSUPPORTED_UI_NODE: 'UNSUPPORTED_UI_NODE',
     INPUT_REJECTED: 'INPUT_REJECTED',
     PERSISTED_STATE_UNREADABLE: 'PERSISTED_STATE_UNREADABLE',
+    /** A local write was attempted against state whose authority is the server. */
+    SERVER_STATE_WRITE: 'SERVER_STATE_WRITE',
+    /** An action belongs to the authority, but no gateway to it was configured. */
+    REMOTE_ACTION_UNAVAILABLE: 'REMOTE_ACTION_UNAVAILABLE',
 };
 const MISSING = Symbol('missing');
 function unwrapType(type) {
@@ -68,7 +72,7 @@ function defaultForType(type) {
  */
 function requireCollection(value, operator) {
     if (!Array.isArray(value)) {
-        throw new ExpressionEvaluationError(`${operator} expects a collection but received ${describeValue(value)}`, { operator, received: value });
+        throw new ExpressionEvaluationError(`${operator} expects a collection but received ${describeValue(value)}`, { collectionOperator: operator, received: value });
     }
     return value;
 }
@@ -91,21 +95,93 @@ export function createAxiomRuntime(options) {
     const derivedCache = new Map();
     const natives = new Map(Object.entries(options.nativeOperations ?? {}));
     const diagnostics = [];
+    /** Rendered controls, keyed by render instance — not by node id. */
     const inputElements = new Map();
-    let focusedNodeId = null;
+    let focusedInstance = null;
     let focusedCaret = null;
     let started = false;
     let transactionCounter = 0;
     const mutationLog = [];
     const inputValidation = options.inputValidation ?? 'immediate';
+    const remote = options.remote;
+    const remoteActionIds = new Set(ir.remoteActionIds ?? []);
+    /**
+     * Set only while an authoritative answer is being applied. The authority owns the value;
+     * every other path is refused, which is what makes the boundary structural rather than a
+     * convention about where inputs are bound.
+     */
+    let applyingAuthoritative = false;
+    let remoteRequests = 0;
     const theme = ir.theme;
     const locale = theme?.locale ?? 'en-US';
-    /** Messages for inputs whose last write was refused, so a control can say so. */
+    /**
+     * Messages for inputs whose last write was refused, so a control can say so. Keyed by
+     * render instance: refusing a write in one row must not mark another row invalid.
+     */
     const inputErrors = new Map();
+    /**
+     * The most recent outcome of each action, which is what a `diagnostic` node presents.
+     * Ephemeral runtime state: it is replaced by the next invocation of the same action, and
+     * cleared by `clearDiagnostics()` and by navigating to another route.
+     */
+    const actionOutcomes = new Map();
+    /**
+     * Buttons that are their form's declared submit control, and the action each submits.
+     * Such a button carries native submit behaviour instead of its own click handler, so a
+     * click runs the action exactly once.
+     */
+    const submitControls = new Map();
+    for (const node of Object.values(ir.uiNodes)) {
+        if (node.kind !== 'form' || !node.submitButtonId) {
+            continue;
+        }
+        const button = ir.uiNodes[node.submitButtonId];
+        if (button?.kind === 'button') {
+            submitControls.set(node.submitButtonId, {
+                formId: node.id,
+                actionId: node.submitActionId ?? button.actionId,
+            });
+        }
+    }
+    /** Diagnostic regions, by the action they report. Indexed once. */
+    const diagnosticRegions = new Map();
+    for (const node of Object.values(ir.uiNodes)) {
+        if (node.kind === 'diagnostic') {
+            diagnosticRegions.set(node.actionId, [...(diagnosticRegions.get(node.actionId) ?? []), node.id]);
+        }
+    }
+    function recordOutcome(actionId, outcome, diagnostics) {
+        actionOutcomes.set(actionId, {
+            actionId: actionId,
+            outcome,
+            // Only what this invocation reported, and only what a region could present.
+            diagnostics: diagnostics.map((diagnostic) => ({ ...diagnostic })),
+        });
+    }
     /** Presentation, already resolved by the compiler. The renderer decides nothing. */
     function presentationOf(id) {
         return ir.presentation?.[id];
     }
+    /**
+     * Where a rendered element sits: the repeat instances enclosing it, outermost first.
+     *
+     * A UI node inside a `repeat` is rendered once per member, so `NodeId` alone cannot
+     * identify a rendered element. The graph still holds one semantic node; this is the
+     * runtime presentation identity that goes with it, and the two are deliberately
+     * distinct — `data-node` carries the first, `data-instance` the second.
+     */
+    const ROOT_INSTANCE = [];
+    /** Everything a renderer-generated id, relationship or lookup is keyed by. */
+    function instanceKey(nodeId, path) {
+        return path.length === 0 ? nodeId : `${nodeId}--${path.join('--')}`;
+    }
+    /** A DOM-safe fragment of an item's identity. */
+    function identityFragment(value, index) {
+        const text = typeof value === 'string' || typeof value === 'number' ? String(value) : '';
+        const safe = text.replace(/[^A-Za-z0-9_-]+/g, '-').replace(/^-+|-+$/g, '');
+        // An absent or unusable identity falls back to a deterministic iteration index.
+        return safe === '' ? `i${index}` : safe;
+    }
     const statesById = new Map(ir.states.map((state) => [state.id, state]));
     const entitiesById = new Map(ir.entities.map((entity) => [entity.id, entity]));
     const parameterTypes = new Map();
@@ -209,6 +285,18 @@ export function createAxiomRuntime(options) {
     }
     /** The only place the store is written. Values are frozen on the way in. */
     function writeState(stateId, value) {
+        if (!applyingAuthoritative && ir.authority?.[stateId] === 'server') {
+            // Whatever the path — an action, an input, an administrative hydrate — a client does
+            // not commit state the authority owns.
+            report({
+                code: RUNTIME_DIAGNOSTIC_CODES.SERVER_STATE_WRITE,
+                message: `${stateId} is server-authoritative and cannot be written by this client`,
+                severity: 'error',
+                nodeId: stateId,
+                stateId: stateId,
+            });
+            return;
+        }
         if (!statesById.has(stateId)) {
             report({
                 code: RUNTIME_DIAGNOSTIC_CODES.UNKNOWN_STATE,
@@ -274,11 +362,25 @@ export function createAxiomRuntime(options) {
             }
         }
     }
+    /**
+     * Classifies an evaluation failure. The code says what kind of failure it was, so an
+     * agent can distinguish an identifier that did not resolve from a value of the wrong
+     * shape without reading the message.
+     */
+    function evaluationFailureCode(details) {
+        if (details.targetId !== undefined) {
+            return RUNTIME_DIAGNOSTIC_CODES.UNRESOLVED_REFERENCE;
+        }
+        if (details.kind !== undefined || details.operator !== undefined || details.function !== undefined) {
+            return RUNTIME_DIAGNOSTIC_CODES.UNSUPPORTED_EXPRESSION;
+        }
+        return RUNTIME_DIAGNOSTIC_CODES.EXPRESSION_EVALUATION_FAILED;
+    }
     /** 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,
+                code: evaluationFailureCode(error.details),
                 message: error.message,
                 severity: 'error',
                 ...context,
@@ -303,7 +405,9 @@ export function createAxiomRuntime(options) {
         }
         catch (error) {
             const failure = {
-                code: error instanceof LocationResolutionError ? RUNTIME_DIAGNOSTIC_CODES.LOCATION_RESOLUTION_FAILED : 'MUTATION_FAILED',
+                code: error instanceof LocationResolutionError
+                    ? RUNTIME_DIAGNOSTIC_CODES.LOCATION_RESOLUTION_FAILED
+                    : RUNTIME_DIAGNOSTIC_CODES.MUTATION_FAILED,
                 message: error instanceof Error ? error.message : String(error),
                 severity: 'error',
                 ...(context.sourceNodeId ? { nodeId: context.sourceNodeId } : {}),
@@ -422,19 +526,26 @@ export function createAxiomRuntime(options) {
         }
         const left = evaluate(leftExpression, scope);
         const right = evaluate(rightExpression, scope);
+        /**
+         * A number that is not finite has no place in an ordering. Every ordered comparison
+         * against one is false, so a guard fails closed rather than passing on a value that
+         * could not be computed — or one a hostile caller supplied.
+         */
+        const unordered = (typeof left === 'number' && !Number.isFinite(left)) ||
+            (typeof right === 'number' && !Number.isFinite(right));
         switch (operator) {
             case 'eq':
                 return valuesEqual(left, right);
             case 'neq':
                 return !valuesEqual(left, right);
             case 'gt':
-                return compareValues(left, right) > 0;
+                return !unordered && compareValues(left, right) > 0;
             case 'gte':
-                return compareValues(left, right) >= 0;
+                return !unordered && compareValues(left, right) >= 0;
             case 'lt':
-                return compareValues(left, right) < 0;
+                return !unordered && compareValues(left, right) < 0;
             case 'lte':
-                return compareValues(left, right) <= 0;
+                return !unordered && compareValues(left, right) <= 0;
             case 'add':
                 return Number(left ?? 0) + Number(right ?? 0);
             case 'subtract':
@@ -851,9 +962,109 @@ export function createAxiomRuntime(options) {
                 });
         }
     }
+    /**
+     * Applies an authoritative answer. The only path permitted to write server-owned state —
+     * and it still goes through `writeState`, so the store keeps exactly one writer.
+     */
+    function applyAuthoritative(changes) {
+        applyingAuthoritative = true;
+        try {
+            for (const [stateId, value] of Object.entries(changes)) {
+                if (statesById.has(stateId)) {
+                    writeState(stateId, cloneValue(value));
+                }
+            }
+        }
+        finally {
+            applyingAuthoritative = false;
+        }
+    }
+    /**
+     * Dispatches a semantic action to the authority.
+     *
+     * The client sends an action id and typed arguments — never operations. The answer is
+     * applied when it arrives, and recorded through the same outcome lifecycle a local
+     * refusal uses, so a `diagnostic` node presents a server refusal exactly as it presents
+     * a local one.
+     */
+    function runRemoteAction(action, args) {
+        if (!remote) {
+            const failure = {
+                code: RUNTIME_DIAGNOSTIC_CODES.REMOTE_ACTION_UNAVAILABLE,
+                message: `${action.name ?? action.id} executes on the authority, but no gateway to it is configured`,
+                severity: 'error',
+                nodeId: action.id,
+                actionId: action.id,
+            };
+            report(failure);
+            recordOutcome(action.id, 'failed', [failure]);
+            renderApplication();
+            return { ok: false, diagnostics: [failure] };
+        }
+        if (action.requiresConfirmation && !askForConfirmation(action)) {
+            // Confirmation is interaction, and it happens here. The authority never treats it as
+            // an authorization mechanism.
+            recordOutcome(action.id, 'cancelled', []);
+            renderApplication();
+            return { ok: false, diagnostics: [] };
+        }
+        remoteRequests += 1;
+        // A stable key, so a retry after a lost answer cannot execute the action twice.
+        const requestId = `${ir.id}:${action.id}:${remoteRequests}:${host.uuid()}`;
+        recordOutcome(action.id, 'pending', []);
+        renderApplication();
+        const settle = remote
+            .invoke({ actionId: action.id, arguments: args, requestId })
+            .then((answer) => {
+            applyAuthoritative(answer.changes ?? {});
+            answer.diagnostics.forEach(report);
+            recordOutcome(action.id, answer.ok ? 'ok' : 'failed', answer.ok ? [] : answer.diagnostics);
+            renderApplication();
+            return { ok: answer.ok, diagnostics: answer.diagnostics };
+        })
+            .catch((error) => {
+            // A transport failure becomes a structured diagnostic, not an escaping exception.
+            const failure = {
+                code: RUNTIME_DIAGNOSTIC_CODES.REMOTE_ACTION_UNAVAILABLE,
+                message: error instanceof Error ? error.message : String(error),
+                severity: 'error',
+                nodeId: action.id,
+                actionId: action.id,
+            };
+            report(failure);
+            recordOutcome(action.id, 'failed', [failure]);
+            renderApplication();
+            return { ok: false, diagnostics: [failure] };
+        });
+        pending.set(action.id, settle);
+        return { ok: false, pending: true, diagnostics: [] };
+    }
+    /** In-flight remote invocations, so `invokeActionAsync` can await one. */
+    const pending = new Map();
     function runAction(actionId, args = {}) {
-        return collecting((collected) => runActionCollecting(actionId, args, collected));
+        const remoteAction = remoteActionIds.has(actionId) ? ir.actions[actionId] : undefined;
+        if (remoteAction) {
+            return runRemoteAction(remoteAction, args);
+        }
+        return collecting((collected) => {
+            const started = collected.length;
+            const result = runActionCollecting(actionId, args, collected);
+            if (ir.actions[actionId]) {
+                // The record is this invocation's own diagnostics, so a later invocation of another
+                // action can never appear to belong to this one.
+                recordOutcome(actionId, result.ok ? 'ok' : cancelled ? 'cancelled' : 'failed', result.ok ? [] : collected.slice(started));
+            }
+            cancelled = false;
+            // Any invocation can change what a diagnostic region presents, including one refused
+            // before a transaction was ever opened. Render once, at the outermost invocation.
+            if (transactions.currentId() === undefined) {
+                renderApplication();
+            }
+            return result;
+        });
     }
+    /** Set when the most recent invocation stopped because a confirmation was declined. */
+    let cancelled = false;
     function runActionCollecting(actionId, args, collected) {
         const action = ir.actions[actionId];
         if (!action) {
@@ -908,6 +1119,8 @@ export function createAxiomRuntime(options) {
         }
         if (action.requiresConfirmation) {
             if (!askForConfirmation(action)) {
+                // Declining a confirmation is not a refusal: it reports nothing.
+                cancelled = true;
                 return { ok: false, diagnostics: [...collected] };
             }
         }
@@ -952,11 +1165,9 @@ export function createAxiomRuntime(options) {
                     report({ ...violation, actionId: action.id, transactionId: transaction.id });
                 }
             }
-            renderApplication();
             return { ok: false, diagnostics: [...collected] };
         }
         settle(transaction, 'committed');
-        renderApplication();
         return { ok: true, diagnostics: [...collected] };
     }
     // ------------------------------------------------------------------ routing
@@ -1004,7 +1215,13 @@ export function createAxiomRuntime(options) {
         syncRoute();
     }
     function syncRoute() {
+        const previous = activeRoute?.route.id;
         activeRoute = matchRoute(host.getPath());
+        if (previous !== undefined && previous !== activeRoute?.route.id) {
+            // Diagnostics are about the screen that produced them.
+            actionOutcomes.clear();
+            inputErrors.clear();
+        }
         derivedCache.clear();
         renderApplication();
     }
@@ -1060,9 +1277,36 @@ export function createAxiomRuntime(options) {
         };
         return host.confirmRequest(request);
     }
-    function renderChildren(ids, scope, parent) {
+    /**
+     * The diagnostics a region presents: those of its action's most recent invocation, at or
+     * above the region's own severity.
+     */
+    function presentedDiagnostics(node) {
+        const record = actionOutcomes.get(node.actionId);
+        if (!record) {
+            return [];
+        }
+        const minimum = node.severity ?? 'error';
+        return record.diagnostics.filter((diagnostic) => minimum === 'warning' || diagnostic.severity === 'error');
+    }
+    /** Whether any region currently reports something about this action. */
+    function reportingRegionFor(actionId, path) {
+        if (path.length > 0) {
+            // A region reports one action, not one row; relating a repeated control to it would
+            // be guesswork. Rows report through their own input diagnostics instead.
+            return null;
+        }
+        for (const regionId of diagnosticRegions.get(actionId) ?? []) {
+            const region = ir.uiNodes[regionId];
+            if (region?.kind === 'diagnostic' && presentedDiagnostics(region).length > 0) {
+                return `axiom-diagnostic-${regionId}`;
+            }
+        }
+        return null;
+    }
+    function renderChildren(ids, scope, parent, path) {
         for (const id of ids) {
-            const child = renderNode(id, scope);
+            const child = renderNode(id, scope, path);
             if (child) {
                 parent.appendChild(child);
             }
@@ -1169,16 +1413,16 @@ export function createAxiomRuntime(options) {
         }
         return raw;
     }
-    function renderNode(id, scope) {
+    function renderNode(id, scope, path) {
         try {
-            return renderNodeUnguarded(id, scope);
+            return renderNodeUnguarded(id, scope, path);
         }
         catch (error) {
             report(evaluationFailure(error, { nodeId: id }));
             return null;
         }
     }
-    function renderNodeUnguarded(id, scope) {
+    function renderNodeUnguarded(id, scope, path) {
         const node = ir.uiNodes[id];
         if (!node) {
             report({
@@ -1193,18 +1437,25 @@ export function createAxiomRuntime(options) {
             return null;
         }
         const presentation = presentationOf(node.id);
+        const instance = instanceKey(node.id, path);
+        /** `data-node` is the semantic node; `data-instance` is this rendering of it. */
+        const identify = (target) => {
+            target.setAttribute('data-node', node.id);
+            if (path.length > 0) {
+                target.setAttribute('data-instance', instance);
+            }
+            return target;
+        };
         switch (node.kind) {
             case 'view': {
-                const container = element('div', nodeClasses(node, 'axiom-view'));
-                container.setAttribute('data-node', node.id);
-                renderChildren(node.children, scope, container);
+                const container = identify(element('div', nodeClasses(node, 'axiom-view')));
+                renderChildren(node.children, scope, container, path);
                 return container;
             }
             case 'container': {
                 // A UX role that names a region of the page becomes the element that means it, so
                 // the landmark structure an author declared is the one assistive technology sees.
-                const container = element(landmarkTag(presentation?.uxRole) ?? 'div', nodeClasses(node, 'axiom-container'));
-                container.setAttribute('data-node', node.id);
+                const container = identify(element(landmarkTag(presentation?.uxRole) ?? 'div', nodeClasses(node, 'axiom-container')));
                 const ariaRole = ariaRoleFor(presentation?.uxRole);
                 if (ariaRole) {
                     container.setAttribute('role', ariaRole);
@@ -1213,12 +1464,11 @@ export function createAxiomRuntime(options) {
                     container.setAttribute('aria-label', presentation.accessibleLabel);
                 }
                 appendIcon(container, presentation);
-                renderChildren(node.children, scope, container);
+                renderChildren(node.children, scope, container, path);
                 return container;
             }
             case 'text': {
-                const text = element(headingTag(presentation?.textRole) ?? 'span', nodeClasses(node, 'axiom-text'));
-                text.setAttribute('data-node', node.id);
+                const text = identify(element(headingTag(presentation) ?? 'span', nodeClasses(node, 'axiom-text')));
                 // A status role announces itself whatever kind of node carries it.
                 const textRole = ariaRoleFor(presentation?.uxRole);
                 if (textRole) {
@@ -1240,25 +1490,27 @@ export function createAxiomRuntime(options) {
                 return text;
             }
             case 'repeat': {
-                const container = element('div', nodeClasses(node, 'axiom-repeat'));
-                container.setAttribute('data-node', node.id);
+                const container = identify(element('div', nodeClasses(node, 'axiom-repeat')));
                 const source = evaluate(node.source, scope);
                 const items = Array.isArray(source) ? source : [];
                 if (items.length === 0 && node.emptyTemplateId) {
-                    renderChildren([node.emptyTemplateId], scope, container);
+                    renderChildren([node.emptyTemplateId], scope, container, path);
                     return container;
                 }
-                for (const item of items) {
-                    const child = renderNode(node.templateId, childScope(scope, node.id, item));
+                // Each member gets its own render instance, preferring its semantic identity so
+                // the identity survives reordering. Nested repeats compose rather than collide.
+                const identityFieldId = ir.repeatIdentityFields?.[node.id];
+                items.forEach((item, index) => {
+                    const identity = identityFieldId && isRecord(item) ? item[identityFieldId] : undefined;
+                    const child = renderNode(node.templateId, childScope(scope, node.id, item), [...path, identityFragment(identity, index)]);
                     if (child) {
                         container.appendChild(child);
                     }
-                }
+                });
                 return container;
             }
             case 'field-display': {
-                const container = element('div', nodeClasses(node, 'axiom-field'));
-                container.setAttribute('data-node', node.id);
+                const container = identify(element('div', nodeClasses(node, 'axiom-field')));
                 const field = fieldOf(node.fieldId);
                 if (node.label ?? field?.name) {
                     const label = element('span', 'axiom-field-label');
@@ -1276,20 +1528,25 @@ export function createAxiomRuntime(options) {
                 return container;
             }
             case 'form': {
-                const form = element('form', nodeClasses(node, 'axiom-form'));
-                form.setAttribute('data-node', node.id);
-                renderChildren(node.children, scope, form);
-                if (node.submitActionId) {
-                    const actions = element('div', 'axiom-container axiom-ux-action-group axiom-layout-horizontal axiom-gap-small axiom-align-center axiom-justify-end axiom-wrap axiom-width-fill');
-                    const submit = element('button', 'axiom-submit axiom-button axiom-role-primary axiom-emphasis-strong axiom-ux-primary-action');
-                    submit.setAttribute('type', 'submit');
-                    submit.textContent = node.submitLabel ?? 'Submit';
-                    actions.appendChild(submit);
-                    form.appendChild(actions);
-                    const actionId = node.submitActionId;
+                const form = identify(element('form', nodeClasses(node, 'axiom-form')));
+                renderChildren(node.children, scope, form, path);
+                const declaredControl = node.submitButtonId
+                    ? submitControls.get(node.submitButtonId)
+                    : undefined;
+                const submitActionId = declaredControl?.actionId ?? node.submitActionId;
+                if (submitActionId) {
+                    if (!declaredControl) {
+                        // The simple form: the renderer supplies the button.
+                        const actions = element('div', 'axiom-container axiom-ux-action-group axiom-layout-horizontal axiom-gap-small axiom-align-center axiom-justify-end axiom-wrap axiom-width-fill');
+                        const submit = element('button', 'axiom-submit axiom-button axiom-role-primary axiom-emphasis-strong axiom-ux-primary-action');
+                        submit.setAttribute('type', 'submit');
+                        submit.textContent = node.submitLabel ?? 'Submit';
+                        actions.appendChild(submit);
+                        form.appendChild(actions);
+                    }
                     form.addEventListener('submit', (event) => {
                         event.preventDefault?.();
-                        runAction(actionId);
+                        runAction(submitActionId);
                     });
                 }
                 return form;
@@ -1297,10 +1554,9 @@ export function createAxiomRuntime(options) {
             case 'input': {
                 const descriptor = resolveInputTag(node);
                 const grouped = descriptor.tag === 'radio-group';
-                const controlId = `axiom-control-${node.id}`;
+                const controlId = `axiom-control-${instance}`;
                 const required = ir.locationRequired?.[node.id] === true;
-                const wrapper = element(grouped ? 'div' : 'label', nodeClasses(node, 'axiom-input'));
-                wrapper.setAttribute('data-node', node.id);
+                const wrapper = identify(element(grouped ? 'div' : 'label', nodeClasses(node, 'axiom-input')));
                 if (grouped) {
                     wrapper.setAttribute('role', 'group');
                 }
@@ -1323,8 +1579,7 @@ export function createAxiomRuntime(options) {
                 }
                 const current = readLocation(node.binding.location, scope);
                 const describedBy = [];
-                const control = element(grouped ? 'div' : descriptor.tag, grouped ? 'axiom-radio-group' : 'axiom-control');
-                control.setAttribute('data-node', node.id);
+                const control = identify(element(grouped ? 'div' : descriptor.tag, grouped ? 'axiom-radio-group' : 'axiom-control'));
                 if (descriptor.variant) {
                     control.setAttribute('data-control', descriptor.variant);
                 }
@@ -1420,7 +1675,7 @@ export function createAxiomRuntime(options) {
                     mutate(() => mutations.set(node.binding.location, next, scope, context), context, failures);
                     if (failures.length > 0) {
                         settle(transaction, 'rolled-back');
-                        inputErrors.set(node.id, failures[0].message);
+                        inputErrors.set(instance, failures[0].message);
                         failures.forEach(report);
                     }
                     else {
@@ -1432,7 +1687,7 @@ export function createAxiomRuntime(options) {
                         ];
                         if (rejected.length > 0) {
                             settle(transaction, 'rolled-back');
-                            inputErrors.set(node.id, rejected[0].message);
+                            inputErrors.set(instance, rejected[0].message);
                             rejected.forEach((diagnostic) => report({ ...diagnostic, details: { ...diagnostic.details, source: 'input', nodeId: node.id } }));
                             report({
                                 code: RUNTIME_DIAGNOSTIC_CODES.INPUT_REJECTED,
@@ -1444,10 +1699,10 @@ export function createAxiomRuntime(options) {
                         }
                         else {
                             settle(transaction, 'committed');
-                            inputErrors.delete(node.id);
+                            inputErrors.delete(instance);
                         }
                     }
-                    focusedNodeId = node.id;
+                    focusedInstance = instance;
                     focusedCaret = typeof source.selectionStart === 'number' ? source.selectionStart : null;
                     renderApplication();
                 };
@@ -1456,10 +1711,10 @@ export function createAxiomRuntime(options) {
                     target.addEventListener('input', apply);
                     target.addEventListener('change', apply);
                     target.addEventListener('focus', () => {
-                        focusedNodeId = node.id;
+                        focusedInstance = instance;
                     });
                 }
-                inputElements.set(node.id, control);
+                inputElements.set(instance, control);
                 wrapper.appendChild(control);
                 if (presentation?.description) {
                     const help = element('span', 'axiom-input-description axiom-text-caption');
@@ -1468,7 +1723,7 @@ export function createAxiomRuntime(options) {
                     describedBy.push(`${controlId}-description`);
                     wrapper.appendChild(help);
                 }
-                const rejection = inputErrors.get(node.id);
+                const rejection = inputErrors.get(instance);
                 if (rejection) {
                     // The refusal is related to the control it refused, not left floating.
                     const error = element('span', 'axiom-input-description axiom-role-destructive axiom-text-caption');
@@ -1487,14 +1742,22 @@ export function createAxiomRuntime(options) {
                 return wrapper;
             }
             case 'button': {
-                const button = element('button', nodeClasses(node, 'axiom-button'));
-                button.setAttribute('data-node', node.id);
+                const submits = submitControls.get(node.id);
+                const button = identify(element('button', nodeClasses(node, 'axiom-button', submits ? 'axiom-submit' : '')));
                 button.setAttribute('type', 'button');
                 const label = typeof node.label === 'string' ? node.label : toText(evaluate(node.label, scope));
-                if (appendIcon(button, presentation)) {
+                if (presentation?.icon) {
                     const caption = element('span', 'axiom-button-label');
                     caption.textContent = label;
-                    button.appendChild(caption);
+                    // Where the icon sits is a theme decision, not a per-button one.
+                    if (theme?.buttons?.iconPlacement === 'trailing') {
+                        button.appendChild(caption);
+                        appendIcon(button, presentation);
+                    }
+                    else {
+                        appendIcon(button, presentation);
+                        button.appendChild(caption);
+                    }
                 }
                 else {
                     button.textContent = label;
@@ -1502,6 +1765,15 @@ export function createAxiomRuntime(options) {
                 if (presentation?.accessibleLabel) {
                     button.setAttribute('aria-label', presentation.accessibleLabel);
                 }
+                const reporting = reportingRegionFor(node.actionId, path);
+                if (reporting) {
+                    button.setAttribute('aria-describedby', reporting);
+                }
+                if (submits) {
+                    // Native form submission runs the action; a click handler here would run it twice.
+                    button.setAttribute('type', 'submit');
+                    return button;
+                }
                 button.addEventListener('click', (event) => {
                     event.preventDefault?.();
                     const args = {};
@@ -1512,11 +1784,37 @@ export function createAxiomRuntime(options) {
                 });
                 return button;
             }
+            case 'diagnostic': {
+                const region = identify(element('div', nodeClasses(node, 'axiom-diagnostic')));
+                region.setAttribute('id', `axiom-diagnostic-${instance}`);
+                const ariaRole = ariaRoleFor(presentation?.uxRole);
+                if (ariaRole) {
+                    region.setAttribute('role', ariaRole);
+                }
+                if (presentation?.accessibleLabel) {
+                    region.setAttribute('aria-label', presentation.accessibleLabel);
+                }
+                const reported = presentedDiagnostics(node);
+                if (reported.length === 0) {
+                    // Nothing to report: the region renders empty rather than disappearing, so the
+                    // relationship an initiating control declares stays resolvable.
+                    region.setAttribute('data-empty', 'true');
+                    return region;
+                }
+                appendIcon(region, presentation);
+                for (const diagnostic of reported) {
+                    const entry = element('span', 'axiom-diagnostic-entry axiom-text-body');
+                    entry.setAttribute('data-code', diagnostic.code);
+                    // The wording is the structured diagnostic's own; the renderer invents none.
+                    entry.textContent = diagnostic.message;
+                    region.appendChild(entry);
+                }
+                return region;
+            }
             case 'conditional': {
-                const container = element('div', nodeClasses(node, 'axiom-conditional'));
-                container.setAttribute('data-node', node.id);
+                const container = identify(element('div', nodeClasses(node, 'axiom-conditional')));
                 const branch = toBoolean(evaluate(node.condition, scope)) ? node.whenTrue : node.whenFalse ?? [];
-                renderChildren(branch, scope, container);
+                renderChildren(branch, scope, container, path);
                 return container;
             }
             default:
@@ -1537,15 +1835,15 @@ export function createAxiomRuntime(options) {
             rootElement.replaceChildren(missing);
             return;
         }
-        const view = renderNode(activeRoute.route.viewId, scope);
+        const view = renderNode(activeRoute.route.viewId, scope, ROOT_INSTANCE);
         rootElement.replaceChildren(...(view ? [view] : []));
         restoreFocus();
     }
     function restoreFocus() {
-        if (!focusedNodeId) {
+        if (!focusedInstance) {
             return;
         }
-        const control = inputElements.get(focusedNodeId);
+        const control = inputElements.get(focusedInstance);
         if (!control) {
             return;
         }
@@ -1570,6 +1868,9 @@ export function createAxiomRuntime(options) {
             host.onPathChange(() => {
                 activeRoute = matchRoute(host.getPath());
                 derivedCache.clear();
+                // Diagnostics are about the screen that produced them.
+                actionOutcomes.clear();
+                inputErrors.clear();
                 renderApplication();
             });
             syncRoute();
@@ -1604,6 +1905,13 @@ export function createAxiomRuntime(options) {
         },
         clearDiagnostics() {
             diagnostics.length = 0;
+            actionOutcomes.clear();
+            inputErrors.clear();
+            renderApplication();
+        },
+        getActionOutcome(id) {
+            const record = actionOutcomes.get(id);
+            return record ? { ...record, diagnostics: record.diagnostics.map((d) => ({ ...d })) } : undefined;
         },
         getMutationLog() {
             return mutationLog.map((entry) => ({ ...entry }));
@@ -1611,6 +1919,25 @@ export function createAxiomRuntime(options) {
         registerNativeOperation(implementationId, implementation) {
             natives.set(implementationId, implementation);
         },
+        async invokeActionAsync(id, args = {}) {
+            const result = runAction(id, args);
+            if (!result.pending) {
+                return result;
+            }
+            return (await pending.get(id)) ?? result;
+        },
+        async syncAuthoritativeState() {
+            if (!remote?.snapshot) {
+                return;
+            }
+            const snapshot = await remote.snapshot();
+            applyAuthoritative(snapshot.states ?? {});
+            renderApplication();
+        },
+        evaluate(expression) {
+            const outcome = tryEvaluate(expression, rootScope(), {});
+            return outcome.ok ? { ok: true, value: outcome.value } : { ok: false, diagnostic: outcome.diagnostic };
+        },
     };
 }
 /** Builds a host bound to the browser globals. Used by generated pages. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cynodia/axiom-runtime",
-  "version": "0.5.0-alpha.1",
+  "version": "0.6.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.5.0-alpha.1"
+    "@cynodia/axiom-core": "0.6.0-alpha.1"
   },
   "scripts": {
     "build": "tsc -b tsconfig.json tsconfig.test.json",