@cynodia/axiom-runtime 0.5.2-alpha.1 → 0.6.1-alpha.1

package/README.md

@@ -19,13 +19,13 @@ Main exports: `createAxiomRuntime`, `createBrowserHost`, `createMemoryHost`,
 ## Installation
 
 ```bash
-npm install @cynodia/axiom-runtime@alpha
+npm install @cynodia/axiom-runtime
 ```
 
 Most applications should install the facade package instead, which re-exports this one:
 
 ```bash
-npm install @cynodia/axiom@alpha
+npm install @cynodia/axiom
 ```
 
 

package/dist/index.d.ts

@@ -4,6 +4,7 @@ export * from './mutation/store.js';
 export * from './mutation/transaction.js';
 export * from './mutation/resolve-location.js';
 export * from './mutation/mutation-engine.js';
+export * from './remote.js';
 export * from './format.js';
 export * from './presentation-classes.js';
 export * from './runtime.js';

package/dist/index.js

@@ -4,6 +4,7 @@ export * from './mutation/store.js';
 export * from './mutation/transaction.js';
 export * from './mutation/resolve-location.js';
 export * from './mutation/mutation-engine.js';
+export * from './remote.js';
 export * from './format.js';
 export * from './presentation-classes.js';
 export * from './runtime.js';

package/dist/mutation/values.d.ts

@@ -31,6 +31,16 @@ export declare function isPresent(value: unknown): boolean;
 export declare function isEmptyValue(value: unknown): boolean;
 export declare function toBoolean(value: unknown): boolean;
 export declare function toText(value: unknown): string;
+/**
+ * Lexicographic order by Unicode code point.
+ *
+ * Not locale collation, and deliberately not the language's default string comparison:
+ * ordering is part of the semantic contract, so two conforming runtimes must agree on it
+ * character for character. Code points are the one ordering every language can reproduce
+ * exactly — a UTF-16 comparison, which is what `<` does here, disagrees with a UTF-8 one
+ * whenever a string mixes astral characters with U+E000..U+FFFF.
+ */
+export declare function compareText(left: string, right: string): number;
 export declare function compareValues(left: unknown, right: unknown): number;
 export declare function valuesEqual(left: unknown, right: unknown): boolean;
 //# sourceMappingURL=values.d.ts.map

package/dist/mutation/values.js

@@ -76,13 +76,33 @@ export function toText(value) {
     }
     return JSON.stringify(value);
 }
+/**
+ * Lexicographic order by Unicode code point.
+ *
+ * Not locale collation, and deliberately not the language's default string comparison:
+ * ordering is part of the semantic contract, so two conforming runtimes must agree on it
+ * character for character. Code points are the one ordering every language can reproduce
+ * exactly — a UTF-16 comparison, which is what `<` does here, disagrees with a UTF-8 one
+ * whenever a string mixes astral characters with U+E000..U+FFFF.
+ */
+export function compareText(left, right) {
+    const leftPoints = Array.from(left);
+    const rightPoints = Array.from(right);
+    const shared = Math.min(leftPoints.length, rightPoints.length);
+    for (let index = 0; index < shared; index += 1) {
+        const leftPoint = leftPoints[index].codePointAt(0);
+        const rightPoint = rightPoints[index].codePointAt(0);
+        if (leftPoint !== rightPoint) {
+            return leftPoint < rightPoint ? -1 : 1;
+        }
+    }
+    return leftPoints.length === rightPoints.length ? 0 : leftPoints.length < rightPoints.length ? -1 : 1;
+}
 export function compareValues(left, right) {
     if (typeof left === 'number' && typeof right === 'number') {
         return left === right ? 0 : left < right ? -1 : 1;
     }
-    const leftText = toText(left);
-    const rightText = toText(right);
-    return leftText === rightText ? 0 : leftText < rightText ? -1 : 1;
+    return compareText(toText(left), toText(right));
 }
 /** A stable serialization, so record comparison does not depend on key order. */
 function canonical(value) {

package/dist/remote.d.ts

@@ -0,0 +1,51 @@
+import type { NodeId, RuntimeDiagnostic } from './runtime-types.js';
+/**
+ * A browser-safe gateway to an Axiom authority.
+ *
+ * It lives here, in the runtime, rather than in the server package, because a browser
+ * client needs it and that package imports Node built-ins a browser has no use for.
+ * Everything below uses `fetch` and nothing else, so a generated page can reach an
+ * authority with no application code and no Node dependency at all.
+ *
+ * The protocol is the semantic one: the client asks for actions, never for URLs. The
+ * endpoint is a single path, the same for every application.
+ */
+/** Must match `PROTOCOL_VERSION` in `@cynodia/axiom-server`. */
+export declare const AXIOM_PROTOCOL_VERSION = "axiom.protocol.v1";
+/** The endpoint an Axiom authority answers on, unless a host says otherwise. */
+export declare const AXIOM_DEFAULT_ENDPOINT = "/axiom";
+export interface HttpRemoteGatewayOptions {
+    /** Defaults to `/axiom` on the current origin. */
+    endpoint?: string;
+    /** Read per request, so a host can refresh a credential without rebuilding the client. */
+    credential?: () => string | null;
+    /** Defaults to the global `fetch`. */
+    fetch?: typeof globalThis.fetch;
+    timeoutMs?: number;
+}
+/**
+ * Builds the gateway a client runtime is configured with.
+ *
+ * ```ts
+ * createAxiomRuntime({ ir, rootElement, host, remote: createHttpRemoteGateway() });
+ * ```
+ *
+ * A transport failure becomes a structured diagnostic rather than an exception escaping
+ * into application code, so a refused or unreachable authority reaches the interface the
+ * same way a refused local action does.
+ */
+export declare function createHttpRemoteGateway(options?: HttpRemoteGatewayOptions): {
+    invoke(request: {
+        actionId: NodeId;
+        arguments: Record<string, unknown>;
+        requestId: string;
+    }): Promise<{
+        ok: boolean;
+        diagnostics: RuntimeDiagnostic[];
+        changes: Record<NodeId, unknown>;
+    }>;
+    snapshot(): Promise<{
+        states: Record<NodeId, unknown>;
+    }>;
+};
+//# sourceMappingURL=remote.d.ts.map

package/dist/remote.js

@@ -0,0 +1,101 @@
+/**
+ * A browser-safe gateway to an Axiom authority.
+ *
+ * It lives here, in the runtime, rather than in the server package, because a browser
+ * client needs it and that package imports Node built-ins a browser has no use for.
+ * Everything below uses `fetch` and nothing else, so a generated page can reach an
+ * authority with no application code and no Node dependency at all.
+ *
+ * The protocol is the semantic one: the client asks for actions, never for URLs. The
+ * endpoint is a single path, the same for every application.
+ */
+/** Must match `PROTOCOL_VERSION` in `@cynodia/axiom-server`. */
+export const AXIOM_PROTOCOL_VERSION = 'axiom.protocol.v1';
+/** The endpoint an Axiom authority answers on, unless a host says otherwise. */
+export const AXIOM_DEFAULT_ENDPOINT = '/axiom';
+function unreachable(message) {
+    return {
+        code: 'AUTHORITY_UNREACHABLE',
+        message,
+        severity: 'error',
+    };
+}
+/**
+ * Builds the gateway a client runtime is configured with.
+ *
+ * ```ts
+ * createAxiomRuntime({ ir, rootElement, host, remote: createHttpRemoteGateway() });
+ * ```
+ *
+ * A transport failure becomes a structured diagnostic rather than an exception escaping
+ * into application code, so a refused or unreachable authority reaches the interface the
+ * same way a refused local action does.
+ */
+export function createHttpRemoteGateway(options = {}) {
+    const endpoint = options.endpoint ?? AXIOM_DEFAULT_ENDPOINT;
+    const fetchImpl = options.fetch ?? globalThis.fetch;
+    async function send(body) {
+        if (!fetchImpl) {
+            throw new Error('No fetch implementation is available');
+        }
+        const controller = options.timeoutMs && typeof AbortController === 'function' ? new AbortController() : undefined;
+        const timer = controller ? setTimeout(() => controller.abort(), options.timeoutMs) : undefined;
+        try {
+            const response = await fetchImpl(endpoint, {
+                method: 'POST',
+                headers: { 'content-type': 'application/json' },
+                body: JSON.stringify({
+                    ...body,
+                    protocol: AXIOM_PROTOCOL_VERSION,
+                    credential: options.credential?.() ?? null,
+                }),
+                ...(controller ? { signal: controller.signal } : {}),
+            });
+            if (!response.ok) {
+                throw new Error(`The authority answered ${response.status}`);
+            }
+            return (await response.json());
+        }
+        finally {
+            if (timer !== undefined) {
+                clearTimeout(timer);
+            }
+        }
+    }
+    return {
+        async invoke(request) {
+            try {
+                const answer = await send({
+                    kind: 'invoke',
+                    actionId: request.actionId,
+                    arguments: request.arguments,
+                    requestId: request.requestId,
+                });
+                if (answer.kind === 'result') {
+                    return {
+                        ok: answer.ok === true,
+                        diagnostics: answer.diagnostics ?? [],
+                        changes: answer.changes ?? {},
+                    };
+                }
+                return { ok: false, diagnostics: answer.diagnostics ?? [], changes: {} };
+            }
+            catch (error) {
+                return {
+                    ok: false,
+                    diagnostics: [unreachable(error instanceof Error ? error.message : String(error))],
+                    changes: {},
+                };
+            }
+        },
+        async snapshot() {
+            // A failed snapshot must reject: `start()` distinguishes "not loaded" from "empty",
+            // and swallowing the failure here would erase that difference.
+            const answer = await send({ kind: 'snapshot' });
+            if (answer.kind !== 'snapshot' || !answer.snapshot) {
+                throw new Error('The authority did not return a snapshot');
+            }
+            return { states: answer.snapshot.states ?? {} };
+        },
+    };
+}

package/dist/runtime-types.d.ts

@@ -0,0 +1,19 @@
+/**
+ * The handful of types the browser-safe gateway needs, declared without importing the
+ * runtime module.
+ *
+ * `remote.ts` is inlined into generated pages, and a value import from core would be
+ * stripped from that bundle. Keeping these local also means the gateway pulls in nothing
+ * else at all.
+ */
+export type NodeId = string & {
+    readonly __brand?: 'NodeId';
+};
+export interface RuntimeDiagnostic {
+    code: string;
+    message: string;
+    severity: 'error' | 'warning';
+    details?: Record<string, unknown>;
+    [key: string]: unknown;
+}
+//# sourceMappingURL=runtime-types.d.ts.map

package/dist/runtime-types.js

@@ -0,0 +1 @@
+export {};

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,6 +29,12 @@ 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";
+    /** The authority could not be reached. Authoritative state was not loaded. */
+    readonly AUTHORITY_UNREACHABLE: "AUTHORITY_UNREACHABLE";
 };
 export type RuntimeDiagnosticCode = (typeof RUNTIME_DIAGNOSTIC_CODES)[keyof typeof RUNTIME_DIAGNOSTIC_CODES];
 /**
@@ -52,6 +58,34 @@ 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.
@@ -63,7 +97,8 @@ export interface ActionResult {
  */
 export interface ActionOutcome {
     actionId: NodeId;
-    outcome: 'ok' | 'failed' | 'cancelled';
+    /** `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 {
@@ -83,12 +118,45 @@ export interface AxiomRuntimeOptions {
     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;
 }
 export interface AxiomRuntime {
-    start(): void;
+    /**
+     * Brings the runtime to its initial usable state.
+     *
+     * The lifecycle is fixed and does not depend on whether a gateway is configured:
+     *
+     * 1. local state is initialized from `initialValue` and persistence, before anything else;
+     * 2. route matching is resolved and the application renders once, so a slow authority
+     *    never leaves a blank page;
+     * 3. if a `remote` gateway with a snapshot is configured, authoritative state is loaded
+     *    and applied, and the application renders again.
+     *
+     * `start()` returns a promise that settles when step 3 has completed. Awaiting it is the
+     * whole startup sequence: **there is no second call to remember.** Ignoring the promise
+     * is safe — steps 1 and 2 have already run synchronously — but authoritative state may
+     * not have arrived yet.
+     *
+     * If synchronization fails, the failure is reported as an `AUTHORITY_UNREACHABLE`
+     * diagnostic and `authoritativeStateLoaded()` stays false, so an empty authoritative
+     * collection is never mistaken for a loaded one.
+     */
+    start(): Promise<void>;
+    /**
+     * Whether authoritative state has been loaded successfully.
+     *
+     * `false` with a configured gateway means the authority has not answered — which is not
+     * the same as an authoritative collection that is genuinely empty. Applications with no
+     * remote gateway are always `true`: all their state is local.
+     */
+    authoritativeStateLoaded(): boolean;
     render(): void;
     /** A deep clone of the value. Derived state is recomputed. */
     getState(id: NodeId): unknown;
@@ -121,6 +189,37 @@ export interface AxiomRuntime {
     /** 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>;
+    /**
+     * Resolves when no remote invocation is outstanding.
+     *
+     * An action started from the interface has no promise the caller can hold; this is how a
+     * test, a script or a host waits for the authority to have answered without guessing a
+     * delay. Resolves immediately when nothing is in flight.
+     */
+    settled(): 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,12 @@ 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',
+    /** The authority could not be reached. Authoritative state was not loaded. */
+    AUTHORITY_UNREACHABLE: 'AUTHORITY_UNREACHABLE',
 };
 const MISSING = Symbol('missing');
 function unwrapType(type) {
@@ -85,6 +91,17 @@ function describeValue(value) {
     }
     return `${typeof value} ${JSON.stringify(value)}`;
 }
+/**
+ * Distinguishes runtimes that share a process.
+ *
+ * `host.uuid()` is the only entropy a runtime has, and a deterministic host — the memory
+ * host, a conformance host, a test double — hands every runtime it constructs the same
+ * sequence. Two clients would then generate the same request id for their first remote
+ * invocation, and the authority would answer the second from the first one's idempotency
+ * record. A counter that lives above the host closes that: within a process it is what
+ * separates two runtimes, and across processes a real host's uuid is.
+ */
+let runtimeSessions = 0;
 export function createAxiomRuntime(options) {
     const { ir, rootElement, host } = options;
     const store = createStateStore();
@@ -93,12 +110,35 @@ export function createAxiomRuntime(options) {
     const diagnostics = [];
     /** Rendered controls, keyed by render instance — not by node id. */
     const inputElements = new Map();
+    /**
+     * How each rendered form submits, keyed by the form's render instance.
+     *
+     * A form with a declared submit control must invoke the action **exactly** as that button
+     * would on its own — same arguments, evaluated in the button's own scope. Registering the
+     * button's invocation here is what makes the two paths literally the same code, rather
+     * than two that have to be kept in step.
+     */
+    const submitInvokers = new Map();
     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;
+    /** Generated once, and only when this runtime can actually talk to an authority. */
+    const sessionId = remote ? `s${(runtimeSessions += 1)}-${host.uuid()}` : '';
+    /** False until the authority has answered, when one is configured. */
+    let authoritativeLoaded = options.remote?.snapshot === undefined;
+    let startup = Promise.resolve();
     const theme = ir.theme;
     const locale = theme?.locale ?? 'en-US';
     /**
@@ -272,6 +312,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,
@@ -501,19 +553,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':
@@ -930,7 +989,135 @@ 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 — and one
+        // carrying this runtime's own session identity, so two clients never claim the same key.
+        const requestId = `${ir.id}:${sessionId}:${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);
+        void settle.finally(() => {
+            if (pending.get(action.id) === settle) {
+                pending.delete(action.id);
+            }
+        });
+        return { ok: false, pending: true, diagnostics: [] };
+    }
+    /** In-flight remote invocations, so `invokeActionAsync` can await one. */
+    const pending = new Map();
+    /**
+     * Waits until nothing is outstanding with an authority.
+     *
+     * A remote action started from the interface — a click, a form submit — returns to the
+     * event handler immediately, so there is no promise for the caller to hold. Without this,
+     * anything driving the UI has to guess a delay. It loops because settling one invocation
+     * may start another.
+     */
+    async function allSettled() {
+        while (pending.size > 0) {
+            await Promise.allSettled([...pending.values()]);
+        }
+    }
+    /**
+     * Loads authoritative state and applies it.
+     *
+     * A failure is a diagnostic, not an exception, and leaves `authoritativeLoaded` false —
+     * so an application can tell "the authority has not answered" from "the collection is
+     * empty", which are very different things to show a person.
+     */
+    async function syncAuthoritative() {
+        if (!remote?.snapshot) {
+            return;
+        }
+        try {
+            const snapshot = await remote.snapshot();
+            applyAuthoritative(snapshot.states ?? {});
+            authoritativeLoaded = true;
+        }
+        catch (error) {
+            authoritativeLoaded = false;
+            report({
+                code: RUNTIME_DIAGNOSTIC_CODES.AUTHORITY_UNREACHABLE,
+                message: `Authoritative state could not be loaded: ${error instanceof Error ? error.message : String(error)}`,
+                severity: 'error',
+            });
+        }
+        renderApplication();
+    }
     function runAction(actionId, args = {}) {
+        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);
@@ -1331,6 +1518,18 @@ export function createAxiomRuntime(options) {
             }
             return target;
         };
+        /**
+         * `data-control` names the one element a person actually operates.
+         *
+         * A single semantic node can render as more than one element — an input is a label
+         * wrapping a control, and both carry `data-node`, because both are that node. Anything
+         * that wants to type into it, click it or read its value needs the inner one, and
+         * `data-node` cannot say which that is. This can.
+         */
+        const asControl = (target) => {
+            target.setAttribute('data-control', node.id);
+            return target;
+        };
         switch (node.kind) {
             case 'view': {
                 const container = identify(element('div', nodeClasses(node, 'axiom-view')));
@@ -1429,8 +1628,15 @@ export function createAxiomRuntime(options) {
                         actions.appendChild(submit);
                         form.appendChild(actions);
                     }
+                    const formInstance = instanceKey(node.id, path);
                     form.addEventListener('submit', (event) => {
                         event.preventDefault?.();
+                        // A declared control carries the arguments; a generated one has none to carry.
+                        const declared = submitInvokers.get(formInstance);
+                        if (declared) {
+                            declared();
+                            return;
+                        }
                         runAction(submitActionId);
                     });
                 }
@@ -1466,7 +1672,10 @@ export function createAxiomRuntime(options) {
                 const describedBy = [];
                 const control = identify(element(grouped ? 'div' : descriptor.tag, grouped ? 'axiom-radio-group' : 'axiom-control'));
                 if (descriptor.variant) {
-                    control.setAttribute('data-control', descriptor.variant);
+                    control.setAttribute('data-variant', descriptor.variant);
+                }
+                if (!grouped) {
+                    asControl(control);
                 }
                 if (!grouped) {
                     control.setAttribute('id', controlId);
@@ -1484,7 +1693,9 @@ export function createAxiomRuntime(options) {
                     }
                 }
                 if (grouped) {
-                    wrapper.setAttribute('data-control', descriptor.variant ?? 'radio-group');
+                    // A radio group has no single element to operate, so the group itself is it.
+                    wrapper.setAttribute('data-variant', descriptor.variant ?? 'radio-group');
+                    asControl(wrapper);
                 }
                 if (descriptor.variant === 'switch') {
                     control.setAttribute('role', 'switch');
@@ -1628,7 +1839,7 @@ export function createAxiomRuntime(options) {
             }
             case 'button': {
                 const submits = submitControls.get(node.id);
-                const button = identify(element('button', nodeClasses(node, 'axiom-button', submits ? 'axiom-submit' : '')));
+                const button = asControl(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 (presentation?.icon) {
@@ -1654,18 +1865,40 @@ export function createAxiomRuntime(options) {
                 if (reporting) {
                     button.setAttribute('aria-describedby', reporting);
                 }
+                // A remote action is in flight until the authority answers, and a person watching a
+                // button that does nothing will press it again. `pending` is already a semantic
+                // runtime outcome; this is the whole of its presentation — the control says it is
+                // working, and refuses a second invocation until it is not. No async model, no
+                // spinner vocabulary, nothing an author writes.
+                const pending = actionOutcomes.get(node.actionId)?.outcome === 'pending';
+                if (pending) {
+                    button.setAttribute('data-pending', 'true');
+                    button.setAttribute('aria-busy', 'true');
+                    button.setAttribute('disabled', 'true');
+                }
+                /** What this button does, wherever the interaction came from. */
+                const invoke = () => {
+                    if (pending) {
+                        // The authority has not answered the last one. Pressing again would be a second
+                        // transaction, not a retry of the first.
+                        return;
+                    }
+                    const args = {};
+                    for (const [parameterId, argument] of Object.entries(node.arguments ?? {})) {
+                        args[parameterId] = evaluate(argument, scope);
+                    }
+                    runAction(node.actionId, args);
+                };
                 if (submits) {
                     // Native form submission runs the action; a click handler here would run it twice.
+                    // The form invokes exactly this, so the button's arguments are not lost.
                     button.setAttribute('type', 'submit');
+                    submitInvokers.set(instanceKey(submits.formId, path), invoke);
                     return button;
                 }
                 button.addEventListener('click', (event) => {
                     event.preventDefault?.();
-                    const args = {};
-                    for (const [parameterId, argument] of Object.entries(node.arguments ?? {})) {
-                        args[parameterId] = evaluate(argument, scope);
-                    }
-                    runAction(node.actionId, args);
+                    invoke();
                 });
                 return button;
             }
@@ -1713,6 +1946,7 @@ export function createAxiomRuntime(options) {
     }
     function renderApplication() {
         inputElements.clear();
+        submitInvokers.clear();
         const scope = rootScope();
         if (!activeRoute) {
             const missing = element('div', 'axiom-no-route');
@@ -1747,7 +1981,7 @@ export function createAxiomRuntime(options) {
     return {
         start() {
             if (started) {
-                return;
+                return startup;
             }
             started = true;
             host.onPathChange(() => {
@@ -1758,7 +1992,14 @@ export function createAxiomRuntime(options) {
                 inputErrors.clear();
                 renderApplication();
             });
+            // Local state and a first render happen synchronously, so an application is on screen
+            // before the authority is consulted.
             syncRoute();
+            startup = remote?.snapshot ? syncAuthoritative() : Promise.resolve();
+            return startup;
+        },
+        authoritativeStateLoaded() {
+            return authoritativeLoaded;
         },
         render: renderApplication,
         getState(id) {
@@ -1804,6 +2045,23 @@ 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;
+        },
+        syncAuthoritativeState() {
+            return syncAuthoritative();
+        },
+        settled() {
+            return allSettled();
+        },
+        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/dist/source.js

@@ -12,6 +12,7 @@ const RUNTIME_MODULES = [
     './mutation/resolve-location.js',
     './mutation/mutation-engine.js',
     './format.js',
+    './remote.js',
     './presentation-classes.js',
     './runtime.js',
 ];

package/package.json

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