@cynodia/axiom-agent-api 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,27 @@
+# Axiom Agent API
+
+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 machine-facing interface: semantic queries over the graph, field-level dependency
+and mutation-impact analysis, and transactional graph transformations.
+
+## Installation
+
+```bash
+npm install @cynodia/axiom-agent-api@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/api.d.ts

@@ -0,0 +1,25 @@
+import type { ApplicationGraph, ValidationResult } from '@cynodia/axiom-core';
+import { GraphQueries } from './queries.js';
+import { Transaction } from './transaction.js';
+import type { ChangeSet } from './changes.js';
+/**
+ * The machine-facing interface to an application. Agents query semantics and apply
+ * structural transformations; they never edit generated code.
+ */
+export declare class AgentAPI extends GraphQueries {
+    private readonly changeLog;
+    constructor(graph: ApplicationGraph);
+    validate(): ValidationResult;
+    beginTransaction(): Transaction;
+    /** Runs a set of transformations, committing only if the result validates. */
+    transact(apply: (transaction: Transaction) => void, options?: {
+        reason?: string;
+        actor?: string;
+    }): {
+        committed: boolean;
+        change?: ChangeSet;
+        result: ValidationResult;
+    };
+    history(): ChangeSet[];
+}
+//# sourceMappingURL=api.d.ts.map

package/dist/api.js

@@ -0,0 +1,35 @@
+import { validateGraph } from '@cynodia/axiom-core';
+import { GraphQueries } from './queries.js';
+import { Transaction } from './transaction.js';
+/**
+ * The machine-facing interface to an application. Agents query semantics and apply
+ * structural transformations; they never edit generated code.
+ */
+export class AgentAPI extends GraphQueries {
+    changeLog = [];
+    constructor(graph) {
+        super(graph);
+    }
+    validate() {
+        return validateGraph(this.graph);
+    }
+    beginTransaction() {
+        return new Transaction(this.graph, (change) => {
+            this.changeLog.push(change);
+        });
+    }
+    /** Runs a set of transformations, committing only if the result validates. */
+    transact(apply, options = {}) {
+        const transaction = this.beginTransaction();
+        apply(transaction);
+        const result = transaction.validate();
+        if (!result.valid) {
+            transaction.rollback();
+            return { committed: false, result };
+        }
+        return { committed: true, change: transaction.commit(options), result };
+    }
+    history() {
+        return this.changeLog.map((change) => ({ ...change, operations: [...change.operations] }));
+    }
+}

package/dist/changes.d.ts

@@ -0,0 +1,46 @@
+import type { AnyNode, FieldDef, FieldId, GraphEdge, NodeId } from '@cynodia/axiom-core';
+export type GraphChange = AddNodeChange | RemoveNodeChange | UpdateNodeChange | AddFieldChange | RemoveFieldChange | AddEdgeChange | RemoveEdgeChange;
+export interface AddNodeChange {
+    kind: 'add-node';
+    nodeId: NodeId;
+    node: AnyNode;
+}
+export interface RemoveNodeChange {
+    kind: 'remove-node';
+    nodeId: NodeId;
+    node: AnyNode;
+}
+export interface UpdateNodeChange {
+    kind: 'update-node';
+    nodeId: NodeId;
+    before: AnyNode;
+    after: AnyNode;
+}
+export interface AddFieldChange {
+    kind: 'add-field';
+    entityId: NodeId;
+    field: FieldDef;
+}
+export interface RemoveFieldChange {
+    kind: 'remove-field';
+    entityId: NodeId;
+    fieldId: FieldId;
+    field: FieldDef;
+}
+export interface AddEdgeChange {
+    kind: 'add-edge';
+    edge: GraphEdge;
+}
+export interface RemoveEdgeChange {
+    kind: 'remove-edge';
+    edge: GraphEdge;
+}
+/** A semantic change record: graph operations and intent, never a textual diff. */
+export interface ChangeSet {
+    id: string;
+    timestamp: number;
+    operations: GraphChange[];
+    reason?: string;
+    actor?: string;
+}
+//# sourceMappingURL=changes.d.ts.map

package/dist/changes.js

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

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+export * from './changes.js';
+export * from './queries.js';
+export * from './transaction.js';
+export * from './api.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -0,0 +1,4 @@
+export * from './changes.js';
+export * from './queries.js';
+export * from './transaction.js';
+export * from './api.js';

package/dist/queries.d.ts

@@ -0,0 +1,70 @@
+import type { ActionDef, AnyNode, ApplicationGraph, ConstraintDef, EdgeKind, Expression, FieldId, FormNode, GraphEdge, Location, NodeId, StateDef, UINode, ViewNode } from '@cynodia/axiom-core';
+export interface SubgraphRequest {
+    root: NodeId;
+    depth?: number;
+    edgeKinds?: readonly EdgeKind[];
+}
+export interface Subgraph {
+    nodes: AnyNode[];
+    edges: GraphEdge[];
+}
+/** What a change to a location can reach. */
+export interface MutationImpact {
+    location: Location;
+    rootStateId: NodeId;
+    fieldIds: FieldId[];
+    directWriters: AnyNode[];
+    dependentDerivedStates: StateDef[];
+    affectedConstraints: ConstraintDef[];
+    affectedViews: ViewNode[];
+}
+export declare class GraphQueries {
+    protected graph: ApplicationGraph;
+    constructor(graph: ApplicationGraph);
+    getNode(id: NodeId): AnyNode | undefined;
+    getField(id: FieldId): import("@cynodia/axiom-core").FieldIndexEntry | undefined;
+    getEdges(id: NodeId, kinds?: readonly EdgeKind[]): GraphEdge[];
+    getDependencies(id: NodeId, kinds?: readonly EdgeKind[]): AnyNode[];
+    getDependents(id: NodeId, kinds?: readonly EdgeKind[]): AnyNode[];
+    /** Nodes that read a state: views, derived state and action conditions. */
+    getReaders(stateId: NodeId): AnyNode[];
+    /** Actions that mutate a state. */
+    getWriters(stateId: NodeId): ActionDef[];
+    /** States whose value type mentions the entity. */
+    getStatesForEntity(entityId: NodeId): StateDef[];
+    getConstraintsForEntity(entityId: NodeId): ConstraintDef[];
+    /** Actions that write a state holding the entity, or that construct instances of it. */
+    getActionsForEntity(entityId: NodeId): ActionDef[];
+    /** Every UI node that binds or displays one of the entity's fields. */
+    getUiNodesForEntity(entityId: NodeId): UINode[];
+    /** Views that render any UI node touching the entity. */
+    getViewsForEntity(entityId: NodeId): ViewNode[];
+    /** Forms that edit the entity — where a new field usually needs an input. */
+    getFormsForEntity(entityId: NodeId): FormNode[];
+    /** Actions an agent should treat as destructive, declared or inferred. */
+    findDestructiveActions(): ActionDef[];
+    /**
+     * The neighbourhood of a node, optionally restricted to particular relationships.
+     * This is the query an agent uses instead of reading files.
+     */
+    getSubgraph(request: SubgraphRequest): Subgraph;
+    /** Ids a node's expressions reference, for dependency reporting. */
+    referencedBy(expression: Expression): NodeId[];
+    /** Nodes that read a specific field, from the field metadata on their read edges. */
+    getFieldReaders(fieldId: FieldId): AnyNode[];
+    /** Nodes that write a specific field — actions and the inputs bound to it. */
+    getFieldWriters(fieldId: FieldId): AnyNode[];
+    /**
+     * What can change this location, and what observes it. The answer comes entirely from
+     * graph relationships, so an agent never has to read application source to find out.
+     */
+    getMutationImpact(location: Location): MutationImpact;
+    private constraintTouches;
+    /** Derived states that depend on a state, directly or through other derived states. */
+    private derivedStatesFrom;
+    private nodesWithFieldEdge;
+    protected ancestors(id: NodeId): UINode[];
+    protected enclosingViews(id: NodeId): ViewNode[];
+    private resolve;
+}
+//# sourceMappingURL=queries.d.ts.map

package/dist/queries.js

@@ -0,0 +1,292 @@
+import { isUINode, locationFieldIds, locationRootStateId, locationSelectorFieldIds, referencedIds, } from '@cynodia/axiom-core';
+const READ_KINDS = ['reads', 'binds', 'derives-from'];
+const WRITE_KINDS = ['writes'];
+const CONTAINMENT_KINDS = ['contains', 'renders'];
+function edgeFieldIds(edge) {
+    const fieldIds = edge.metadata?.fieldIds;
+    return Array.isArray(fieldIds) ? fieldIds : [];
+}
+export class GraphQueries {
+    graph;
+    constructor(graph) {
+        this.graph = graph;
+    }
+    getNode(id) {
+        return this.graph.getNode(id);
+    }
+    getField(id) {
+        return this.graph.getField(id);
+    }
+    getEdges(id, kinds) {
+        return this.graph.getEdges(id, kinds ? { kinds } : {});
+    }
+    getDependencies(id, kinds) {
+        return this.resolve(this.graph.getOutgoingEdges(id, kinds ? { kinds } : {}).map((edge) => edge.to));
+    }
+    getDependents(id, kinds) {
+        return this.resolve(this.graph.getIncomingEdges(id, kinds ? { kinds } : {}).map((edge) => edge.from));
+    }
+    /** Nodes that read a state: views, derived state and action conditions. */
+    getReaders(stateId) {
+        return this.getDependents(stateId, READ_KINDS);
+    }
+    /** Actions that mutate a state. */
+    getWriters(stateId) {
+        return this.getDependents(stateId, WRITE_KINDS).filter((node) => node.kind === 'action');
+    }
+    /** States whose value type mentions the entity. */
+    getStatesForEntity(entityId) {
+        return this.graph
+            .getNodesByKind('state')
+            .filter((state) => this.graph
+            .getOutgoingEdges(state.id, { kinds: ['references'] })
+            .some((edge) => edge.to === entityId));
+    }
+    getConstraintsForEntity(entityId) {
+        return this.graph.getNodesByKind('constraint').filter((constraint) => constraint.entityId === entityId);
+    }
+    /** Actions that write a state holding the entity, or that construct instances of it. */
+    getActionsForEntity(entityId) {
+        const stateIds = new Set(this.getStatesForEntity(entityId).map((state) => state.id));
+        return this.graph.getNodesByKind('action').filter((action) => {
+            const touchesState = this.graph
+                .getOutgoingEdges(action.id, { kinds: ['writes'] })
+                .some((edge) => stateIds.has(edge.to));
+            if (touchesState) {
+                return true;
+            }
+            return (action.operations ?? []).some((operation) => 'value' in operation && operation.value.kind === 'object'
+                ? operation.value.entityId === entityId
+                : false);
+        });
+    }
+    /** Every UI node that binds or displays one of the entity's fields. */
+    getUiNodesForEntity(entityId) {
+        const fieldIds = new Set((this.graph.getNode(entityId)?.fields ?? []).map((field) => field.id));
+        return this.graph
+            .listNodes()
+            .filter((node) => isUINode(node))
+            .filter((node) => {
+            if (node.kind === 'input') {
+                return locationFieldIds(node.binding.location).some((id) => fieldIds.has(id));
+            }
+            if (node.kind === 'field-display') {
+                return fieldIds.has(node.fieldId);
+            }
+            return false;
+        });
+    }
+    /** Views that render any UI node touching the entity. */
+    getViewsForEntity(entityId) {
+        const views = new Map();
+        for (const node of this.getUiNodesForEntity(entityId)) {
+            for (const view of this.enclosingViews(node.id)) {
+                views.set(view.id, view);
+            }
+        }
+        return [...views.values()];
+    }
+    /** Forms that edit the entity — where a new field usually needs an input. */
+    getFormsForEntity(entityId) {
+        const forms = new Map();
+        for (const node of this.getUiNodesForEntity(entityId)) {
+            if (node.kind !== 'input') {
+                continue;
+            }
+            for (const ancestor of this.ancestors(node.id)) {
+                if (ancestor.kind === 'form') {
+                    forms.set(ancestor.id, ancestor);
+                }
+            }
+        }
+        return [...forms.values()];
+    }
+    /** Actions an agent should treat as destructive, declared or inferred. */
+    findDestructiveActions() {
+        return this.graph
+            .getNodesByKind('action')
+            .filter((action) => action.destructive === true ||
+            (action.operations ?? []).some((operation) => operation.kind === 'remove'));
+    }
+    /**
+     * The neighbourhood of a node, optionally restricted to particular relationships.
+     * This is the query an agent uses instead of reading files.
+     */
+    getSubgraph(request) {
+        const depth = request.depth ?? 1;
+        const query = request.edgeKinds ? { kinds: request.edgeKinds } : {};
+        const visited = new Set([request.root]);
+        const edges = new Map();
+        let frontier = [request.root];
+        for (let level = 0; level < depth; level += 1) {
+            const next = [];
+            for (const id of frontier) {
+                for (const edge of this.graph.getEdges(id, query)) {
+                    edges.set(edge.id, edge);
+                    const neighbour = edge.from === id ? edge.to : edge.from;
+                    if (!visited.has(neighbour)) {
+                        visited.add(neighbour);
+                        next.push(neighbour);
+                    }
+                }
+            }
+            frontier = next;
+            if (frontier.length === 0) {
+                break;
+            }
+        }
+        return { nodes: this.resolve([...visited]), edges: [...edges.values()] };
+    }
+    /** Ids a node's expressions reference, for dependency reporting. */
+    referencedBy(expression) {
+        return referencedIds(expression);
+    }
+    /** Nodes that read a specific field, from the field metadata on their read edges. */
+    getFieldReaders(fieldId) {
+        return this.nodesWithFieldEdge(fieldId, READ_KINDS);
+    }
+    /** Nodes that write a specific field — actions and the inputs bound to it. */
+    getFieldWriters(fieldId) {
+        return this.nodesWithFieldEdge(fieldId, WRITE_KINDS);
+    }
+    /**
+     * What can change this location, and what observes it. The answer comes entirely from
+     * graph relationships, so an agent never has to read application source to find out.
+     */
+    getMutationImpact(location) {
+        const rootStateId = locationRootStateId(location);
+        const fieldIds = locationFieldIds(location);
+        const selectorFieldIds = locationSelectorFieldIds(location);
+        const directWriters = this.graph
+            .getIncomingEdges(rootStateId, { kinds: WRITE_KINDS })
+            .filter((edge) => {
+            if (fieldIds.length === 0) {
+                return true;
+            }
+            const edgeFields = edgeFieldIds(edge);
+            // An edge with no field metadata replaces the whole value.
+            return edgeFields.length === 0 || edgeFields.some((id) => fieldIds.includes(id));
+        })
+            .map((edge) => this.graph.getNode(edge.from))
+            .filter((node) => Boolean(node));
+        const dependentDerivedStates = this.derivedStatesFrom(rootStateId);
+        const entityIds = new Set([...fieldIds, ...selectorFieldIds]
+            .map((id) => this.graph.getField(id)?.entityId)
+            .filter((id) => Boolean(id)));
+        if (entityIds.size === 0) {
+            // Replacing a whole state affects every entity stored in it.
+            for (const edge of this.graph.getOutgoingEdges(rootStateId, { kinds: ['references'] })) {
+                entityIds.add(edge.to);
+            }
+        }
+        const affectedConstraints = this.graph.getNodesByKind('constraint').filter((constraint) => {
+            if (constraint.entityId && entityIds.has(constraint.entityId)) {
+                return fieldIds.length === 0 || this.constraintTouches(constraint, fieldIds);
+            }
+            return this.graph
+                .getOutgoingEdges(constraint.id, { kinds: READ_KINDS })
+                .some((edge) => edge.to === rootStateId);
+        });
+        const observers = new Set([rootStateId, ...dependentDerivedStates.map((state) => state.id)]);
+        const views = new Map();
+        for (const node of this.graph.listNodes()) {
+            if (!isUINode(node)) {
+                continue;
+            }
+            const touches = this.graph
+                .getOutgoingEdges(node.id, { kinds: [...READ_KINDS, ...WRITE_KINDS] })
+                .some((edge) => observers.has(edge.to));
+            if (!touches) {
+                continue;
+            }
+            for (const view of this.enclosingViews(node.id)) {
+                views.set(view.id, view);
+            }
+        }
+        return {
+            location,
+            rootStateId,
+            fieldIds,
+            directWriters,
+            dependentDerivedStates,
+            affectedConstraints,
+            affectedViews: [...views.values()],
+        };
+    }
+    constraintTouches(constraint, fieldIds) {
+        const declared = this.graph
+            .getOutgoingEdges(constraint.id, { kinds: ['constrains'] })
+            .flatMap((edge) => edgeFieldIds(edge));
+        return declared.length === 0 || declared.some((id) => fieldIds.includes(id));
+    }
+    /** Derived states that depend on a state, directly or through other derived states. */
+    derivedStatesFrom(stateId) {
+        const found = new Map();
+        let frontier = [stateId];
+        const seen = new Set([stateId]);
+        while (frontier.length > 0) {
+            const next = [];
+            for (const current of frontier) {
+                for (const edge of this.graph.getIncomingEdges(current, { kinds: ['derives-from'] })) {
+                    if (seen.has(edge.from)) {
+                        continue;
+                    }
+                    seen.add(edge.from);
+                    const node = this.graph.getNode(edge.from);
+                    if (node?.kind === 'state') {
+                        found.set(node.id, node);
+                        next.push(node.id);
+                    }
+                }
+            }
+            frontier = next;
+        }
+        return [...found.values()];
+    }
+    nodesWithFieldEdge(fieldId, kinds) {
+        const found = new Map();
+        for (const edge of this.graph.listEdges()) {
+            if (!kinds.includes(edge.kind) || !edgeFieldIds(edge).includes(fieldId)) {
+                continue;
+            }
+            const node = this.graph.getNode(edge.from);
+            if (node) {
+                found.set(node.id, node);
+            }
+        }
+        return [...found.values()];
+    }
+    ancestors(id) {
+        const found = [];
+        const seen = new Set([id]);
+        let frontier = [id];
+        while (frontier.length > 0) {
+            const next = [];
+            for (const current of frontier) {
+                for (const edge of this.graph.getIncomingEdges(current, { kinds: CONTAINMENT_KINDS })) {
+                    if (seen.has(edge.from)) {
+                        continue;
+                    }
+                    seen.add(edge.from);
+                    const parent = this.graph.getNode(edge.from);
+                    if (parent && isUINode(parent)) {
+                        found.push(parent);
+                        next.push(parent.id);
+                    }
+                }
+            }
+            frontier = next;
+        }
+        return found;
+    }
+    enclosingViews(id) {
+        const node = this.graph.getNode(id);
+        const self = node && node.kind === 'view' ? [node] : [];
+        return [...self, ...this.ancestors(id).filter((ancestor) => ancestor.kind === 'view')];
+    }
+    resolve(ids) {
+        return ids
+            .map((id) => this.graph.getNode(id))
+            .filter((node) => Boolean(node));
+    }
+}

package/dist/transaction.d.ts

@@ -0,0 +1,103 @@
+import { ApplicationGraph } from '@cynodia/axiom-core';
+import type { ActionDef, AnyNode, ButtonNode, ConditionalNode, ConstraintDef, ContainerNode, EdgeId, EdgeKind, Expression, FieldDef, FieldDisplayNode, FieldId, FormNode, InputNode, Location, NodeId, RepeatNode, RouteDef, StateDef, TextNode, UINode, ValidationResult, ViewNode } from '@cynodia/axiom-core';
+import { GraphQueries } from './queries.js';
+import type { ChangeSet, GraphChange } from './changes.js';
+export declare class TransactionError extends Error {
+    readonly result?: ValidationResult;
+    constructor(message: string, result?: ValidationResult);
+}
+type UIInput<T extends UINode> = Omit<T, 'id' | 'kind'> & {
+    id?: NodeId;
+};
+/**
+ * A staged set of graph transformations. Every change is applied to a private copy, so
+ * the graph an agent (or a runtime) can observe is unchanged until `commit()` succeeds.
+ */
+export declare class Transaction extends GraphQueries {
+    private readonly target;
+    private readonly onCommit;
+    private readonly operations;
+    private settled;
+    constructor(target: ApplicationGraph, onCommit: (change: ChangeSet) => void);
+    /** The staged graph. Reading it shows uncommitted changes. */
+    get staged(): ApplicationGraph;
+    get changes(): GraphChange[];
+    addEntity(entity: {
+        id?: NodeId;
+        name?: string;
+        fields?: FieldDef[];
+        identityFieldId?: FieldId;
+    }): NodeId;
+    /** Adds a field to an existing entity without the caller rebuilding the entity. */
+    addField(entityId: NodeId, field: Omit<FieldDef, 'id'> & {
+        id?: FieldId;
+    }): FieldId;
+    removeField(fieldId: FieldId): void;
+    addState(state: Omit<StateDef, 'id' | 'kind'> & {
+        id?: NodeId;
+    }): NodeId;
+    addAction(action: Omit<ActionDef, 'id' | 'kind'> & {
+        id?: NodeId;
+    }): NodeId;
+    addConstraint(constraint: Omit<ConstraintDef, 'id' | 'kind'> & {
+        id?: NodeId;
+    }): NodeId;
+    addRoute(route: Omit<RouteDef, 'id' | 'kind'> & {
+        id?: NodeId;
+    }): NodeId;
+    addView(view: UIInput<ViewNode>): NodeId;
+    addContainer(container: UIInput<ContainerNode>): NodeId;
+    addText(text: UIInput<TextNode>): NodeId;
+    addRepeat(repeat: UIInput<RepeatNode>): NodeId;
+    addForm(form: UIInput<FormNode>): NodeId;
+    addConditional(conditional: UIInput<ConditionalNode>): NodeId;
+    addInput(input: UIInput<InputNode>): NodeId;
+    addButton(button: UIInput<ButtonNode>): NodeId;
+    addFieldDisplay(display: UIInput<FieldDisplayNode>): NodeId;
+    /**
+     * Creates an input for a field and attaches it to a parent, which is the whole of
+     * "make this field editable here".
+     */
+    bindField(request: {
+        parentId: NodeId;
+        /** The addressable position the input writes to. */
+        location: Location;
+        label?: string;
+        inputHint?: InputNode['inputHint'];
+        id?: NodeId;
+        position?: number;
+    }): NodeId;
+    /** Creates a read-only display for a field and attaches it to a parent. */
+    displayField(request: {
+        parentId: NodeId;
+        source: Expression;
+        fieldId: FieldId;
+        label?: string;
+        id?: NodeId;
+        position?: number;
+    }): NodeId;
+    /**
+     * Teaches every action that constructs instances of an entity about a new field, so a
+     * field added to the model is also populated by the actions that create records.
+     */
+    addFieldToConstructors(entityId: NodeId, fieldId: FieldId, value: Expression): NodeId[];
+    appendChild(parentId: NodeId, childId: NodeId, position?: number): void;
+    addNode<T extends AnyNode>(node: T): NodeId;
+    updateNode(node: AnyNode): void;
+    removeNode(id: NodeId): void;
+    addEdge(from: NodeId, to: NodeId, kind: EdgeKind): EdgeId;
+    removeEdge(id: EdgeId): void;
+    /** Re-derives structural edges and checks referential integrity of the staged graph. */
+    validate(): ValidationResult;
+    commit(options?: {
+        reason?: string;
+        actor?: string;
+        timestamp?: number;
+    }): ChangeSet;
+    rollback(): void;
+    private assertOpen;
+    private addUiNode;
+    private requireNode;
+}
+export {};
+//# sourceMappingURL=transaction.d.ts.map

package/dist/transaction.js

@@ -0,0 +1,290 @@
+import { ApplicationGraph, createFieldId, createNodeId, randomHex, synchronizeEdges, validateGraph, } from '@cynodia/axiom-core';
+import { GraphQueries } from './queries.js';
+export class TransactionError extends Error {
+    result;
+    constructor(message, result) {
+        super(message);
+        this.name = 'TransactionError';
+        this.result = result;
+    }
+}
+/**
+ * A staged set of graph transformations. Every change is applied to a private copy, so
+ * the graph an agent (or a runtime) can observe is unchanged until `commit()` succeeds.
+ */
+export class Transaction extends GraphQueries {
+    target;
+    onCommit;
+    operations = [];
+    settled = false;
+    constructor(target, onCommit) {
+        super(ApplicationGraph.deserialize(target.toJSON()));
+        this.target = target;
+        this.onCommit = onCommit;
+    }
+    /** The staged graph. Reading it shows uncommitted changes. */
+    get staged() {
+        return this.graph;
+    }
+    get changes() {
+        return this.operations.map((operation) => ({ ...operation }));
+    }
+    // ------------------------------------------------------------ transformations
+    addEntity(entity) {
+        const id = entity.id ?? createNodeId('entity');
+        this.addNode({
+            id,
+            kind: 'entity',
+            name: entity.name,
+            fields: entity.fields ?? [],
+            identityFieldId: entity.identityFieldId,
+        });
+        return id;
+    }
+    /** Adds a field to an existing entity without the caller rebuilding the entity. */
+    addField(entityId, field) {
+        const entity = this.requireNode(entityId, 'entity');
+        const id = field.id ?? createFieldId('field');
+        const before = structuredClone(entity);
+        entity.fields = [...entity.fields, { ...field, id }];
+        this.graph.updateNode(entity);
+        this.operations.push({ kind: 'add-field', entityId, field: { ...field, id } });
+        this.operations.push({ kind: 'update-node', nodeId: entityId, before, after: structuredClone(entity) });
+        return id;
+    }
+    removeField(fieldId) {
+        const location = this.graph.getField(fieldId);
+        if (!location) {
+            throw new TransactionError(`Field ${fieldId} does not exist`);
+        }
+        const entity = this.requireNode(location.entityId, 'entity');
+        const before = structuredClone(entity);
+        entity.fields = entity.fields.filter((field) => field.id !== fieldId);
+        if (entity.identityFieldId === fieldId) {
+            delete entity.identityFieldId;
+        }
+        this.graph.updateNode(entity);
+        this.operations.push({
+            kind: 'remove-field',
+            entityId: location.entityId,
+            fieldId,
+            field: location.field,
+        });
+        this.operations.push({
+            kind: 'update-node',
+            nodeId: location.entityId,
+            before,
+            after: structuredClone(entity),
+        });
+    }
+    addState(state) {
+        const id = state.id ?? createNodeId('state');
+        this.addNode({ ...state, id, kind: 'state' });
+        return id;
+    }
+    addAction(action) {
+        const id = action.id ?? createNodeId('action');
+        this.addNode({ ...action, id, kind: 'action' });
+        return id;
+    }
+    addConstraint(constraint) {
+        const id = constraint.id ?? createNodeId('constraint');
+        this.addNode({ ...constraint, id, kind: 'constraint' });
+        return id;
+    }
+    addRoute(route) {
+        const id = route.id ?? createNodeId('route');
+        this.addNode({ ...route, id, kind: 'route' });
+        return id;
+    }
+    addView(view) {
+        return this.addUiNode({ ...view, kind: 'view' });
+    }
+    addContainer(container) {
+        return this.addUiNode({ ...container, kind: 'container' });
+    }
+    addText(text) {
+        return this.addUiNode({ ...text, kind: 'text' });
+    }
+    addRepeat(repeat) {
+        return this.addUiNode({ ...repeat, kind: 'repeat' });
+    }
+    addForm(form) {
+        return this.addUiNode({ ...form, kind: 'form' });
+    }
+    addConditional(conditional) {
+        return this.addUiNode({ ...conditional, kind: 'conditional' });
+    }
+    addInput(input) {
+        return this.addUiNode({ ...input, kind: 'input' });
+    }
+    addButton(button) {
+        return this.addUiNode({ ...button, kind: 'button' });
+    }
+    addFieldDisplay(display) {
+        return this.addUiNode({ ...display, kind: 'field-display' });
+    }
+    /**
+     * Creates an input for a field and attaches it to a parent, which is the whole of
+     * "make this field editable here".
+     */
+    bindField(request) {
+        const inputId = this.addInput({
+            id: request.id,
+            label: request.label,
+            inputHint: request.inputHint,
+            binding: { location: request.location },
+        });
+        this.appendChild(request.parentId, inputId, request.position);
+        return inputId;
+    }
+    /** Creates a read-only display for a field and attaches it to a parent. */
+    displayField(request) {
+        const displayId = this.addFieldDisplay({
+            id: request.id,
+            source: request.source,
+            fieldId: request.fieldId,
+            label: request.label,
+        });
+        this.appendChild(request.parentId, displayId, request.position);
+        return displayId;
+    }
+    /**
+     * Teaches every action that constructs instances of an entity about a new field, so a
+     * field added to the model is also populated by the actions that create records.
+     */
+    addFieldToConstructors(entityId, fieldId, value) {
+        const updated = [];
+        for (const action of this.graph.getNodesByKind('action')) {
+            let changed = false;
+            const operations = (action.operations ?? []).map((operation) => {
+                if (!('value' in operation) || operation.value.kind !== 'object') {
+                    return operation;
+                }
+                if (operation.value.entityId !== entityId) {
+                    return operation;
+                }
+                if (operation.value.entries.some((entry) => entry.fieldId === fieldId)) {
+                    return operation;
+                }
+                changed = true;
+                return {
+                    ...operation,
+                    value: { ...operation.value, entries: [...operation.value.entries, { fieldId, value }] },
+                };
+            });
+            if (changed) {
+                this.updateNode({ ...action, operations });
+                updated.push(action.id);
+            }
+        }
+        return updated;
+    }
+    appendChild(parentId, childId, position) {
+        const parent = this.graph.getNode(parentId);
+        if (!parent || !('children' in parent) || !Array.isArray(parent.children)) {
+            throw new TransactionError(`Node ${parentId} cannot contain children`);
+        }
+        const before = structuredClone(parent);
+        const container = parent;
+        const children = [...container.children];
+        children.splice(position ?? children.length, 0, childId);
+        container.children = children;
+        this.graph.updateNode(parent);
+        this.operations.push({
+            kind: 'update-node',
+            nodeId: parentId,
+            before,
+            after: structuredClone(parent),
+        });
+    }
+    addNode(node) {
+        const id = this.graph.addNode(node);
+        const stored = this.graph.getNode(id);
+        if (stored) {
+            this.operations.push({ kind: 'add-node', nodeId: id, node: stored });
+        }
+        return id;
+    }
+    updateNode(node) {
+        const before = this.graph.getNode(node.id);
+        if (!before) {
+            throw new TransactionError(`Node ${node.id} does not exist`);
+        }
+        this.graph.updateNode(node);
+        this.operations.push({ kind: 'update-node', nodeId: node.id, before, after: structuredClone(node) });
+    }
+    removeNode(id) {
+        const node = this.graph.getNode(id);
+        if (!node) {
+            throw new TransactionError(`Node ${id} does not exist`);
+        }
+        for (const edge of this.graph.getEdges(id)) {
+            this.operations.push({ kind: 'remove-edge', edge });
+        }
+        this.graph.removeNode(id);
+        this.operations.push({ kind: 'remove-node', nodeId: id, node });
+    }
+    addEdge(from, to, kind) {
+        const id = this.graph.addEdge(from, to, kind);
+        const edge = this.graph.getEdge(id);
+        if (edge) {
+            this.operations.push({ kind: 'add-edge', edge });
+        }
+        return id;
+    }
+    removeEdge(id) {
+        const edge = this.graph.getEdge(id);
+        if (!edge) {
+            return;
+        }
+        this.graph.removeEdge(id);
+        this.operations.push({ kind: 'remove-edge', edge });
+    }
+    // ------------------------------------------------------------------ lifecycle
+    /** Re-derives structural edges and checks referential integrity of the staged graph. */
+    validate() {
+        synchronizeEdges(this.graph);
+        return validateGraph(this.graph);
+    }
+    commit(options = {}) {
+        this.assertOpen();
+        const result = this.validate();
+        if (!result.valid) {
+            throw new TransactionError(`Refusing to commit an invalid graph:\n${result.errors
+                .map((problem) => `  [${problem.code}] ${problem.message}`)
+                .join('\n')}`, result);
+        }
+        this.target.restore(this.graph.toJSON());
+        this.settled = true;
+        const change = {
+            id: `change_${randomHex(6)}`,
+            timestamp: options.timestamp ?? Date.now(),
+            operations: this.changes,
+            ...(options.reason ? { reason: options.reason } : {}),
+            ...(options.actor ? { actor: options.actor } : {}),
+        };
+        this.onCommit(change);
+        return change;
+    }
+    rollback() {
+        this.assertOpen();
+        this.settled = true;
+    }
+    assertOpen() {
+        if (this.settled) {
+            throw new TransactionError('This transaction has already been committed or rolled back');
+        }
+    }
+    addUiNode(node) {
+        const id = node.id ?? createNodeId(node.kind.replace('-', '_'));
+        return this.addNode({ ...node, id });
+    }
+    requireNode(id, kind) {
+        const node = this.graph.getNode(id);
+        if (!node || node.kind !== kind) {
+            throw new TransactionError(`${id} is not a ${String(kind)} node`);
+        }
+        return node;
+    }
+}

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "@cynodia/axiom-agent-api",
+  "version": "0.3.1-alpha.1",
+  "description": "Semantic queries and transactional graph transformations for AI agents.",
+  "license": "MIT",
+  "author": "AskTech AS",
+  "type": "module",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/cynodia/axiom.git"
+  },
+  "homepage": "https://github.com/cynodia/axiom",
+  "bugs": {
+    "url": "https://github.com/cynodia/axiom/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "dist/**/*.js",
+    "dist/**/*.d.ts",
+    "README.md",
+    "LICENSE"
+  ],
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "dependencies": {
+    "@cynodia/axiom-core": "0.3.1-alpha.1"
+  },
+  "scripts": {
+    "build": "tsc -b tsconfig.json tsconfig.test.json",
+    "test": "node --test dist-test/**/*.test.js"
+  }
+}