@cynodia/axiom-runtime 0.3.1-alpha.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 AskTech AS
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,28 @@
+# Axiom Runtime
+
+Part of [Axiom](https://github.com/cynodia/axiom), an AI-native semantic web application
+framework.
+
+**Status: experimental / alpha.** The API may change between alpha releases.
+
+The domain-independent runtime: the state store, expression evaluation, the mutation
+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.
+
+## Installation
+
+```bash
+npm install @cynodia/axiom-runtime@alpha
+```
+
+Most applications should install the facade package instead, which re-exports this one:
+
+```bash
+npm install @cynodia/axiom@alpha
+```
+
+## License
+
+MIT
+
+Copyright (c) 2026 AskTech AS.

package/dist/dom.d.ts

@@ -0,0 +1,42 @@
+/**
+ * The narrow DOM surface the renderer uses. Declaring it structurally keeps the runtime
+ * free of DOM library types and lets tests supply an in-memory implementation.
+ */
+export interface DomEvent {
+    type: string;
+    preventDefault?(): void;
+    target?: unknown;
+}
+export type DomListener = (event: DomEvent) => void;
+export interface DomElement {
+    tagName: string;
+    textContent: string | null;
+    value?: string;
+    checked?: boolean;
+    selectionStart?: number | null;
+    setAttribute(name: string, value: string): void;
+    appendChild(child: DomElement): unknown;
+    replaceChildren(...children: DomElement[]): void;
+    addEventListener(type: string, listener: DomListener): void;
+    focus?(): void;
+}
+export interface DomDocument {
+    createElement(tagName: string): DomElement;
+}
+export interface StorageAdapter {
+    read(key: string): string | null;
+    write(key: string, value: string): void;
+}
+/** Everything the runtime needs from its environment, so nothing is read from globals. */
+export interface HostEnvironment {
+    document: DomDocument;
+    getPath(): string;
+    pushPath(path: string): void;
+    onPathChange(listener: () => void): void;
+    confirm(message: string): boolean;
+    now(): string;
+    uuid(): string;
+    storage?: StorageAdapter;
+    report?(message: string): void;
+}
+//# sourceMappingURL=dom.d.ts.map

package/dist/dom.js

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

package/dist/index.d.ts

@@ -0,0 +1,10 @@
+export * from './dom.js';
+export * from './mutation/values.js';
+export * from './mutation/store.js';
+export * from './mutation/transaction.js';
+export * from './mutation/resolve-location.js';
+export * from './mutation/mutation-engine.js';
+export * from './runtime.js';
+export * from './memory-host.js';
+export * from './source.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -0,0 +1,9 @@
+export * from './dom.js';
+export * from './mutation/values.js';
+export * from './mutation/store.js';
+export * from './mutation/transaction.js';
+export * from './mutation/resolve-location.js';
+export * from './mutation/mutation-engine.js';
+export * from './runtime.js';
+export * from './memory-host.js';
+export * from './source.js';

package/dist/memory-host.d.ts

@@ -0,0 +1,52 @@
+import type { DomDocument, DomElement, DomEvent, DomListener, HostEnvironment, StorageAdapter } from './dom.js';
+/**
+ * An in-memory DOM and host. The runtime never touches browser globals directly, so the
+ * same renderer that drives a real page can be driven headlessly in tests.
+ */
+export declare class MemoryElement implements DomElement {
+    readonly tagName: string;
+    readonly attributes: Map<string, string>;
+    children: MemoryElement[];
+    textContent: string | null;
+    value?: string;
+    checked?: boolean;
+    selectionStart: number | null;
+    focused: boolean;
+    private readonly listeners;
+    constructor(tagName: string);
+    setAttribute(name: string, value: string): void;
+    getAttribute(name: string): string | null;
+    appendChild(child: DomElement): unknown;
+    replaceChildren(...children: DomElement[]): void;
+    addEventListener(type: string, listener: DomListener): void;
+    focus(): void;
+    dispatch(type: string, event?: Partial<DomEvent>): void;
+    hasListener(type: string): boolean;
+}
+export declare class MemoryDocument implements DomDocument {
+    createElement(tagName: string): DomElement;
+}
+export interface MemoryHostOptions {
+    path?: string;
+    confirm?: boolean | (() => boolean);
+    storage?: boolean;
+}
+export interface MemoryHost extends HostEnvironment {
+    root: MemoryElement;
+    path: string;
+    reports: string[];
+    confirmations: string[];
+    storage?: StorageAdapter;
+}
+export declare function createMemoryHost(options?: MemoryHostOptions): MemoryHost;
+/** Depth-first collection of every element matching a predicate. */
+export declare function findAll(root: MemoryElement, predicate: (element: MemoryElement) => boolean): MemoryElement[];
+export declare function findByNodeId(root: MemoryElement, nodeId: string): MemoryElement[];
+export declare function findByTag(root: MemoryElement, tagName: string): MemoryElement[];
+/** Concatenated text of an element and its descendants. */
+export declare function textOf(element: MemoryElement): string;
+export declare function typeInto(element: MemoryElement, value: string): void;
+export declare function toggle(element: MemoryElement, checked: boolean): void;
+export declare function click(element: MemoryElement): void;
+export declare function submit(element: MemoryElement): void;
+//# sourceMappingURL=memory-host.d.ts.map

package/dist/memory-host.js

@@ -0,0 +1,145 @@
+/**
+ * An in-memory DOM and host. The runtime never touches browser globals directly, so the
+ * same renderer that drives a real page can be driven headlessly in tests.
+ */
+export class MemoryElement {
+    tagName;
+    attributes = new Map();
+    children = [];
+    textContent = null;
+    value;
+    checked;
+    selectionStart = null;
+    focused = false;
+    listeners = new Map();
+    constructor(tagName) {
+        this.tagName = tagName;
+    }
+    setAttribute(name, value) {
+        this.attributes.set(name, value);
+    }
+    getAttribute(name) {
+        return this.attributes.get(name) ?? null;
+    }
+    appendChild(child) {
+        this.children.push(child);
+        return child;
+    }
+    replaceChildren(...children) {
+        this.children = children.map((child) => child);
+    }
+    addEventListener(type, listener) {
+        const existing = this.listeners.get(type) ?? [];
+        existing.push(listener);
+        this.listeners.set(type, existing);
+    }
+    focus() {
+        this.focused = true;
+    }
+    dispatch(type, event = {}) {
+        const payload = { type, target: this, preventDefault: () => undefined, ...event };
+        for (const listener of this.listeners.get(type) ?? []) {
+            listener(payload);
+        }
+    }
+    hasListener(type) {
+        return (this.listeners.get(type) ?? []).length > 0;
+    }
+}
+export class MemoryDocument {
+    createElement(tagName) {
+        return new MemoryElement(tagName);
+    }
+}
+export function createMemoryHost(options = {}) {
+    const listeners = [];
+    const values = new Map();
+    let counter = 0;
+    const confirmResult = options.confirm ?? true;
+    const host = {
+        root: new MemoryElement('div'),
+        path: options.path ?? '/',
+        reports: [],
+        confirmations: [],
+        document: new MemoryDocument(),
+        getPath: () => host.path,
+        pushPath: (next) => {
+            host.path = next;
+        },
+        onPathChange: (listener) => {
+            listeners.push(listener);
+        },
+        confirm: (message) => {
+            host.confirmations.push(message);
+            return typeof confirmResult === 'function' ? confirmResult() : confirmResult;
+        },
+        now: () => {
+            counter += 1;
+            return `2026-01-01T00:00:${String(counter).padStart(2, '0')}.000Z`;
+        },
+        uuid: () => {
+            counter += 1;
+            return `id-${counter}`;
+        },
+        report: (message) => {
+            host.reports.push(message);
+        },
+    };
+    if (options.storage) {
+        host.storage = {
+            read: (key) => values.get(key) ?? null,
+            write: (key, value) => {
+                values.set(key, value);
+            },
+        };
+    }
+    return host;
+}
+/** Depth-first collection of every element matching a predicate. */
+export function findAll(root, predicate) {
+    const found = [];
+    const visit = (element) => {
+        if (predicate(element)) {
+            found.push(element);
+        }
+        for (const child of element.children) {
+            visit(child);
+        }
+    };
+    visit(root);
+    return found;
+}
+export function findByNodeId(root, nodeId) {
+    return findAll(root, (element) => element.getAttribute('data-node') === nodeId);
+}
+export function findByTag(root, tagName) {
+    return findAll(root, (element) => element.tagName === tagName);
+}
+/** Concatenated text of an element and its descendants. */
+export function textOf(element) {
+    const parts = [];
+    const visit = (current) => {
+        if (current.textContent) {
+            parts.push(current.textContent);
+        }
+        for (const child of current.children) {
+            visit(child);
+        }
+    };
+    visit(element);
+    return parts.join(' ');
+}
+export function typeInto(element, value) {
+    element.value = value;
+    element.dispatch('input');
+}
+export function toggle(element, checked) {
+    element.checked = checked;
+    element.dispatch('change');
+}
+export function click(element) {
+    element.dispatch('click');
+}
+export function submit(element) {
+    element.dispatch('submit');
+}

package/dist/mutation/mutation-engine.d.ts

@@ -0,0 +1,44 @@
+import type { MutationOperation, NodeId } from '@cynodia/axiom-core';
+import type { LocationRuntime, ResolvedPath } from './resolve-location.js';
+/** Where a mutation came from, so every state change stays attributable. */
+export interface MutationContext {
+    source: 'action' | 'ui' | 'system' | 'native';
+    sourceNodeId?: NodeId;
+    transactionId?: string;
+}
+export interface MutationResult {
+    affectedStates: NodeId[];
+    affectedLocations: ResolvedPath[];
+}
+export interface MutationLogEntry {
+    transactionId?: string;
+    source: MutationContext['source'];
+    sourceNodeId?: NodeId;
+    operation: MutationOperation['kind'];
+    path: ResolvedPath;
+    description: string;
+    oldValue?: unknown;
+    newValue?: unknown;
+    /** Set when the surrounding transaction settles. */
+    outcome?: 'committed' | 'rolled-back';
+}
+export interface MutationEngineOptions {
+    runtime: LocationRuntime;
+    /** Records previous and next values in the log. */
+    recordValues?: boolean;
+    onLog?(entry: MutationLogEntry): void;
+}
+export interface MutationEngine {
+    apply(operation: MutationOperation, scope: unknown, context: MutationContext): MutationResult;
+    /** Applies a value directly to a location, used by inputs and native results. */
+    set(location: MutationOperation extends {
+        target: infer L;
+    } ? L : never, value: unknown, scope: unknown, context: MutationContext): MutationResult;
+}
+/**
+ * The single place Axiom-managed state is written. Everything else — actions, inputs,
+ * native results — goes through here, which is what makes every mutation observable and
+ * attributable.
+ */
+export declare function createMutationEngine(options: MutationEngineOptions): MutationEngine;
+//# sourceMappingURL=mutation-engine.d.ts.map

package/dist/mutation/mutation-engine.js

@@ -0,0 +1,92 @@
+import { describePath, resolveLocation } from './resolve-location.js';
+import { cloneValue, isRecord, valuesEqual } from './values.js';
+/**
+ * The single place Axiom-managed state is written. Everything else — actions, inputs,
+ * native results — goes through here, which is what makes every mutation observable and
+ * attributable.
+ */
+export function createMutationEngine(options) {
+    const { runtime } = options;
+    const recordValues = options.recordValues !== false;
+    function log(entry) {
+        options.onLog?.(entry);
+    }
+    function applyValue(location, value, scope, context, kind) {
+        const resolved = resolveLocation(location, scope, runtime);
+        const previous = recordValues ? cloneValue(resolved.read()) : undefined;
+        resolved.write(value);
+        log({
+            ...context,
+            operation: kind,
+            path: resolved.path,
+            description: describePath(resolved.path),
+            ...(recordValues ? { oldValue: previous, newValue: cloneValue(value) } : {}),
+        });
+        return { affectedStates: [resolved.rootStateId], affectedLocations: [resolved.path] };
+    }
+    return {
+        set(location, value, scope, context) {
+            return applyValue(location, value, scope, context, 'set');
+        },
+        apply(operation, scope, context) {
+            switch (operation.kind) {
+                case 'set':
+                    return applyValue(operation.target, runtime.evaluate(operation.value, scope), scope, context, 'set');
+                case 'insert': {
+                    const resolved = resolveLocation(operation.target, scope, runtime);
+                    const current = resolved.read();
+                    const items = Array.isArray(current) ? current : [];
+                    const value = cloneValue(runtime.evaluate(operation.value, scope));
+                    const next = operation.position === 'start' ? [value, ...items] : [...items, value];
+                    resolved.write(next);
+                    log({
+                        ...context,
+                        operation: 'insert',
+                        path: resolved.path,
+                        description: describePath(resolved.path),
+                        ...(recordValues ? { newValue: value } : {}),
+                    });
+                    return { affectedStates: [resolved.rootStateId], affectedLocations: [resolved.path] };
+                }
+                case 'remove': {
+                    const collection = resolveLocation(operation.target.collection, scope, runtime);
+                    const current = collection.read();
+                    const items = Array.isArray(current) ? current : [];
+                    const selector = operation.target.selector;
+                    const position = selector.kind === 'identity'
+                        ? items.findIndex((item) => isRecord(item) &&
+                            valuesEqual(item[selector.fieldId], runtime.evaluate(selector.value, scope)))
+                        : Number(runtime.evaluate(selector.index, scope));
+                    if (position < 0 || position >= items.length) {
+                        return { affectedStates: [], affectedLocations: [] };
+                    }
+                    const removed = recordValues ? cloneValue(items[position]) : undefined;
+                    collection.write(items.filter((_, index) => index !== position));
+                    const path = {
+                        rootStateId: collection.path.rootStateId,
+                        segments: [
+                            ...collection.path.segments,
+                            selector.kind === 'identity'
+                                ? {
+                                    kind: 'collection-item',
+                                    fieldId: selector.fieldId,
+                                    identity: runtime.evaluate(selector.value, scope),
+                                }
+                                : { kind: 'collection-item', index: position },
+                        ],
+                    };
+                    log({
+                        ...context,
+                        operation: 'remove',
+                        path,
+                        description: describePath(path),
+                        ...(recordValues ? { oldValue: removed } : {}),
+                    });
+                    return { affectedStates: [collection.path.rootStateId], affectedLocations: [path] };
+                }
+                default:
+                    throw new Error(`Unknown mutation kind "${operation.kind}"`);
+            }
+        },
+    };
+}

package/dist/mutation/resolve-location.d.ts

@@ -0,0 +1,37 @@
+import type { Expression, FieldId, Location, NodeId } from '@cynodia/axiom-core';
+export interface ResolvedPathSegment {
+    kind: 'field' | 'collection-item';
+    fieldId?: FieldId;
+    /** The resolved identity value, for an identity selector. */
+    identity?: unknown;
+    index?: number;
+}
+/** Semantic provenance of a resolved location: which state, then how to get inside it. */
+export interface ResolvedPath {
+    rootStateId: NodeId;
+    segments: ResolvedPathSegment[];
+}
+export interface ResolvedLocation<T = unknown> {
+    read(): T;
+    write(value: T): void;
+    rootStateId: NodeId;
+    path: ResolvedPath;
+}
+export declare class LocationResolutionError extends Error {
+    readonly path: ResolvedPath;
+    constructor(message: string, path: ResolvedPath);
+}
+export interface LocationRuntime {
+    readState(stateId: NodeId): unknown;
+    writeState(stateId: NodeId, value: unknown): void;
+    evaluate(expression: Expression, scope: unknown): unknown;
+}
+/** Renders a resolved path the way the inspector and the mutation log show it. */
+export declare function describePath(path: ResolvedPath): string;
+/**
+ * Turns a Location into a readable and writable address. Writes rebuild the path from
+ * the root state, so a mutation never depends on the identity of an object that some
+ * expression happened to return.
+ */
+export declare function resolveLocation<T = unknown>(location: Location, scope: unknown, runtime: LocationRuntime): ResolvedLocation<T>;
+//# sourceMappingURL=resolve-location.d.ts.map

package/dist/mutation/resolve-location.js

@@ -0,0 +1,108 @@
+import { isRecord, valuesEqual } from './values.js';
+export class LocationResolutionError extends Error {
+    path;
+    constructor(message, path) {
+        super(message);
+        this.name = 'LocationResolutionError';
+        this.path = path;
+    }
+}
+/** Renders a resolved path the way the inspector and the mutation log show it. */
+export function describePath(path) {
+    const segments = path.segments.map((segment) => {
+        if (segment.kind === 'field') {
+            return String(segment.fieldId);
+        }
+        return segment.index === undefined ? `[${String(segment.identity)}]` : `[#${segment.index}]`;
+    });
+    return [path.rootStateId, ...segments].join(' → ');
+}
+function toPath(location, scope, runtime) {
+    switch (location.kind) {
+        case 'state':
+            return { rootStateId: location.stateId, segments: [] };
+        case 'field': {
+            const parent = toPath(location.target, scope, runtime);
+            return {
+                rootStateId: parent.rootStateId,
+                segments: [...parent.segments, { kind: 'field', fieldId: location.fieldId }],
+            };
+        }
+        case 'collection-item': {
+            const parent = toPath(location.collection, scope, runtime);
+            const segment = location.selector.kind === 'identity'
+                ? {
+                    kind: 'collection-item',
+                    fieldId: location.selector.fieldId,
+                    identity: runtime.evaluate(location.selector.value, scope),
+                }
+                : {
+                    kind: 'collection-item',
+                    index: Number(runtime.evaluate(location.selector.index, scope)),
+                };
+            return { rootStateId: parent.rootStateId, segments: [...parent.segments, segment] };
+        }
+        default:
+            throw new Error(`Unknown location kind "${location.kind}"`);
+    }
+}
+function indexOfItem(collection, segment) {
+    if (segment.index !== undefined) {
+        return segment.index >= 0 && segment.index < collection.length ? segment.index : -1;
+    }
+    return collection.findIndex((item) => isRecord(item) && valuesEqual(item[String(segment.fieldId)], segment.identity));
+}
+function readAt(value, segments, index) {
+    if (index >= segments.length) {
+        return value;
+    }
+    const segment = segments[index];
+    if (segment.kind === 'field') {
+        const source = isRecord(value) ? value[String(segment.fieldId)] : undefined;
+        return readAt(source === undefined ? null : source, segments, index + 1);
+    }
+    if (!Array.isArray(value)) {
+        return null;
+    }
+    const position = indexOfItem(value, segment);
+    return position < 0 ? null : readAt(value[position], segments, index + 1);
+}
+/** Rebuilds the value with one position replaced. Nothing existing is mutated. */
+function writeAt(value, segments, index, next, path) {
+    if (index >= segments.length) {
+        return next;
+    }
+    const segment = segments[index];
+    if (segment.kind === 'field') {
+        const base = isRecord(value) ? value : {};
+        const key = String(segment.fieldId);
+        return { ...base, [key]: writeAt(base[key], segments, index + 1, next, path) };
+    }
+    if (!Array.isArray(value)) {
+        throw new LocationResolutionError(`${describePath(path)} does not address a collection`, path);
+    }
+    const position = indexOfItem(value, segment);
+    if (position < 0) {
+        throw new LocationResolutionError(`No item matches ${describePath(path)}`, path);
+    }
+    const copy = value.slice();
+    copy[position] = writeAt(value[position], segments, index + 1, next, path);
+    return copy;
+}
+/**
+ * Turns a Location into a readable and writable address. Writes rebuild the path from
+ * the root state, so a mutation never depends on the identity of an object that some
+ * expression happened to return.
+ */
+export function resolveLocation(location, scope, runtime) {
+    const path = toPath(location, scope, runtime);
+    return {
+        rootStateId: path.rootStateId,
+        path,
+        read: () => readAt(runtime.readState(path.rootStateId), path.segments, 0),
+        write: (value) => {
+            const root = runtime.readState(path.rootStateId);
+            runtime.writeState(path.rootStateId, writeAt(root, path.segments, 0, value, path));
+        },
+    };
+}

package/dist/mutation/store.d.ts

@@ -0,0 +1,14 @@
+/**
+ * The state store. It hands out only frozen values and is the sole owner of the map, so
+ * no consumer can change application state by holding on to something it read.
+ */
+export interface StateStore {
+    has(stateId: string): boolean;
+    read(stateId: string): unknown;
+    write(stateId: string, value: unknown): void;
+    keys(): string[];
+    capture(): unknown;
+    restore(snapshot: unknown): void;
+}
+export declare function createStateStore(): StateStore;
+//# sourceMappingURL=store.d.ts.map

package/dist/mutation/store.js

@@ -0,0 +1,19 @@
+import { deepFreeze } from './values.js';
+export function createStateStore() {
+    const values = new Map();
+    return {
+        has: (stateId) => values.has(stateId),
+        read: (stateId) => values.get(stateId),
+        write: (stateId, value) => {
+            values.set(stateId, deepFreeze(value));
+        },
+        keys: () => [...values.keys()],
+        capture: () => new Map(values),
+        restore: (snapshot) => {
+            values.clear();
+            for (const [key, value] of snapshot) {
+                values.set(key, value);
+            }
+        },
+    };
+}

package/dist/mutation/transaction.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Runtime transactions. The semantic API is independent of the snapshot strategy, so a
+ * coarse whole-store snapshot can be replaced later without touching graph semantics.
+ */
+export interface StoreSnapshot {
+    capture(): unknown;
+    restore(snapshot: unknown): void;
+}
+export interface RuntimeTransaction {
+    id: string;
+    /** True for the outermost transaction; nested ones join their parent. */
+    isRoot: boolean;
+    commit(): void;
+    rollback(): void;
+}
+export interface TransactionManager {
+    begin(): RuntimeTransaction;
+    currentId(): string | undefined;
+}
+export declare function createTransactionManager(store: StoreSnapshot, nextId: () => string): TransactionManager;
+//# sourceMappingURL=transaction.d.ts.map