@cynodia/axiom-core 0.3.1-alpha.1 → 0.4.1-alpha.1

package/dist/derive-edges.d.ts

@@ -1,18 +1,22 @@
 import type { Expression } from './expressions.js';
 import type { NodeId } from './ids.js';
 import type { GraphEdge } from './nodes.js';
+import type { AnyNode } from './types.js';
 import type { ApplicationGraph } from './graph.js';
 /** Ids a `ref` expression mentions anywhere in the tree. */
 export declare function referencedIds(expression: Expression): NodeId[];
 /**
- * Recomputes the structural edges implied by node definitions. Edges index semantics
- * that already exist in the nodes, so they are derived rather than hand maintained:
- * any transformation that changes a node can simply re-run this pass.
+ * Recomputes the structural edges implied by node definitions. Edges index semantics that
+ * already exist in the nodes, so they are derived rather than hand maintained — see
+ * `ApplicationGraph.semanticEdges()`, which keeps them current automatically.
  *
- * Write edges carry the fields they touch, so an agent can distinguish an action that
- * writes one field of a record from one that replaces the record.
- *
- * Edges added by hand (without the `derived` marker) are preserved.
+ * Write edges carry the fields they touch, so writing one field of a record is
+ * distinguishable from writing another.
+ */
+export declare function deriveEdges(nodes: readonly AnyNode[]): GraphEdge[];
+/**
+ * Writes the derived edges into the graph. Queries derive them on demand, so this is only
+ * needed to materialize edges into serialized graph data.
  */
 export declare function synchronizeEdges(graph: ApplicationGraph): GraphEdge[];
 //# sourceMappingURL=derive-edges.d.ts.map

package/dist/derive-edges.js

@@ -1,4 +1,4 @@
-import { expressionFieldIds, walkExpression } from './expressions.js';
+import { constructedFieldIds, expressionFieldIds, walkExpression } from './expressions.js';
 import { locationExpressions, locationFieldIds, locationRootStateId, locationSelectorFieldIds, } from './location.js';
 import { isUINode } from './ui.js';
 /** Ids a `ref` expression mentions anywhere in the tree. */
@@ -24,184 +24,300 @@ function entityIdsIn(type) {
     }
 }
 /**
- * Recomputes the structural edges implied by node definitions. Edges index semantics
- * that already exist in the nodes, so they are derived rather than hand maintained:
- * any transformation that changes a node can simply re-run this pass.
+ * Recomputes the structural edges implied by node definitions. Edges index semantics that
+ * already exist in the nodes, so they are derived rather than hand maintained — see
+ * `ApplicationGraph.semanticEdges()`, which keeps them current automatically.
  *
- * Write edges carry the fields they touch, so an agent can distinguish an action that
- * writes one field of a record from one that replaces the record.
- *
- * Edges added by hand (without the `derived` marker) are preserved.
+ * Write edges carry the fields they touch, so writing one field of a record is
+ * distinguishable from writing another.
  */
-export function synchronizeEdges(graph) {
-    for (const edge of graph.listEdges()) {
-        if (edge.metadata?.derived === true) {
-            graph.removeEdge(edge.id);
-        }
-    }
-    const nodes = graph.listNodes();
+export function deriveEdges(nodes) {
     const known = new Set(nodes.map((node) => node.id));
     const states = new Set(nodes.filter((node) => node.kind === 'state').map((node) => node.id));
     const pending = new Map();
-    // An iteration scope stands for an item of whatever collection its repeat reads, so a
-    // template that shows a field of the item still reads that field of the state.
-    const scopeStates = new Map();
+    // A repeat's template refers to the current item by the repeat node's own id.
+    const rootScope = new Map();
     for (const node of nodes) {
         if (node.kind === 'repeat') {
-            scopeStates.set(node.id, referencedIds(node.source).filter((id) => states.has(id)));
+            rootScope.set(node.id, statesOf(node.source, new Map(), states));
+        }
+    }
+    // Which states can hold instances of an entity, including nested ones. An entity-scoped
+    // constraint reads its fields wherever those instances actually live.
+    const entities = new Map(nodes.filter((node) => node.kind === 'entity').map((node) => [node.id, node]));
+    const statesByEntity = new Map();
+    for (const node of nodes) {
+        if (node.kind !== 'state' || node.draft || node.derivation) {
+            continue;
+        }
+        for (const entityId of reachableEntities(node.valueType, entities)) {
+            statesByEntity.set(entityId, [...(statesByEntity.get(entityId) ?? []), node.id]);
         }
     }
-    const resolveStates = (id) => {
-        if (states.has(id)) {
-            return [id];
+    const entityScope = (entityId) => new Map([...rootScope, [entityId, statesByEntity.get(entityId) ?? []]]);
+    const link = (from, to, kind, fieldIds = []) => {
+        if (from === to || !known.has(from) || !known.has(to)) {
+            return;
         }
-        return scopeStates.get(id) ?? [];
+        const key = `${from}|${to}|${kind}`;
+        const entry = pending.get(key) ?? { from, to, kind, fieldIds: new Set() };
+        for (const fieldId of fieldIds) {
+            entry.fieldIds.add(fieldId);
+        }
+        pending.set(key, entry);
     };
-    const linker = {
-        statesFor: resolveStates,
-        link(from, to, kind, fieldIds = []) {
-            if (from === to || !known.has(from) || !known.has(to)) {
-                return;
-            }
-            const key = `${from}|${to}|${kind}`;
-            const entry = pending.get(key) ?? { from, to, kind, fieldIds: new Set() };
-            for (const fieldId of fieldIds) {
-                entry.fieldIds.add(fieldId);
-            }
-            pending.set(key, entry);
-        },
-        reads(from, expression, kind = 'reads') {
-            // Attribute a field to a state only where the expression actually reads that
-            // state's field, so "reads X.name" never over-reports.
-            const perState = new Map();
-            const referenced = new Set();
-            walkExpression(expression, (node) => {
-                if (node.kind === 'ref') {
-                    for (const stateId of resolveStates(node.targetId)) {
-                        referenced.add(stateId);
-                    }
-                }
-                if (node.kind === 'field' && node.source.kind === 'ref') {
-                    for (const stateId of resolveStates(node.source.targetId)) {
-                        const existing = perState.get(stateId) ?? new Set();
-                        existing.add(node.fieldId);
-                        perState.set(stateId, existing);
-                    }
-                }
-            });
-            for (const id of referenced) {
-                linker.link(from, id, kind, [...(perState.get(id) ?? [])]);
-            }
-        },
-        writes(from, location, kind = 'writes', extraFields = []) {
-            linker.link(from, locationRootStateId(location), kind, [
-                ...locationFieldIds(location),
-                ...extraFields,
-            ]);
-            // Addressing the location is itself a read of whatever the selectors consult.
-            for (const expression of locationExpressions(location)) {
-                linker.reads(from, expression);
-            }
-            const selectorFields = locationSelectorFieldIds(location);
-            if (selectorFields.length > 0) {
-                linker.link(from, locationRootStateId(location), 'reads', selectorFields);
-            }
-        },
+    const reads = (from, expression, scope, kind = 'reads') => {
+        for (const [stateId, fieldIds] of collectReads(expression, scope, states)) {
+            link(from, stateId, kind, [...fieldIds]);
+        }
+    };
+    const writes = (from, location, scope, kind = 'writes', extraFields = []) => {
+        link(from, locationRootStateId(location), kind, [...locationFieldIds(location), ...extraFields]);
+        // Addressing the location is itself a read of whatever the selectors consult.
+        for (const expression of locationExpressions(location)) {
+            reads(from, expression, scope);
+        }
+        const selectorFields = locationSelectorFieldIds(location);
+        if (selectorFields.length > 0) {
+            link(from, locationRootStateId(location), 'reads', selectorFields);
+        }
     };
     for (const node of nodes) {
         if (isUINode(node)) {
-            linkUiNode(node, linker);
+            linkUiNode(node, { link, reads, writes, scope: rootScope, states });
             continue;
         }
         switch (node.kind) {
             case 'entity':
-                linkEntity(node, linker);
+                for (const field of node.fields) {
+                    for (const target of entityIdsIn(field.valueType)) {
+                        link(node.id, target, 'references', [field.id]);
+                    }
+                }
                 break;
             case 'state':
-                linkState(node, linker);
+                linkState(node, link, reads, rootScope);
                 break;
             case 'action':
-                linkAction(node, linker);
+                linkAction(node, { link, reads, writes, scope: rootScope, states });
                 break;
             case 'constraint':
-                linkConstraint(node, linker);
+                if (node.entityId) {
+                    link(node.id, node.entityId, 'constrains', expressionFieldIds(node.expression));
+                }
+                reads(node.id, node.expression, node.entityId ? entityScope(node.entityId) : rootScope);
                 break;
+            case 'transition-constraint': {
+                link(node.id, node.entityId, 'constrains', expressionFieldIds(node.expression));
+                const holders = statesByEntity.get(node.entityId) ?? [];
+                reads(node.id, node.expression, new Map([...rootScope, [node.previousScopeId, holders], [node.proposedScopeId, holders]]));
+                break;
+            }
             case 'route':
-                linker.link(node.id, node.viewId, 'routes-to');
+                link(node.id, node.viewId, 'routes-to');
                 break;
             default:
         }
     }
-    for (const entry of pending.values()) {
-        graph.addEdge(entry.from, entry.to, entry.kind, {
-            metadata: {
-                derived: true,
-                ...(entry.fieldIds.size > 0 ? { fieldIds: [...entry.fieldIds] } : {}),
-            },
-        });
+    return [...pending.values()].map((entry) => ({
+        id: `${entry.from}:${entry.kind}:${entry.to}`,
+        from: entry.from,
+        to: entry.to,
+        kind: entry.kind,
+        metadata: {
+            derived: true,
+            ...(entry.fieldIds.size > 0 ? { fieldIds: [...entry.fieldIds] } : {}),
+        },
+    }));
+}
+/**
+ * The states an expression ultimately draws its members from. Following `field` and calls
+ * matters: a collection reached as `coalesce(field(ref(state), lines), [])` still comes
+ * from that state, and its members' fields are still reads of it.
+ */
+function statesOf(expression, scope, states) {
+    switch (expression.kind) {
+        case 'ref': {
+            const bound = scope.get(expression.targetId);
+            if (bound) {
+                return [...bound];
+            }
+            return states.has(expression.targetId) ? [expression.targetId] : [];
+        }
+        case 'filter':
+        case 'find':
+        case 'sort':
+        case 'map':
+        case 'flatten':
+            return statesOf(expression.source, scope, states);
+        case 'conditional':
+            return [
+                ...new Set([
+                    ...statesOf(expression.whenTrue, scope, states),
+                    ...statesOf(expression.whenFalse, scope, states),
+                ]),
+            ];
+        case 'field':
+            return statesOf(expression.source, scope, states);
+        case 'call':
+            return [...new Set(expression.arguments.flatMap((argument) => statesOf(argument, scope, states)))];
+        default:
+            return [];
     }
-    return graph.listEdges();
 }
-function linkEntity(entity, linker) {
-    for (const field of entity.fields) {
-        for (const target of entityIdsIn(field.valueType)) {
-            linker.link(entity.id, target, 'references', [field.id]);
+/** Entities reachable from a type, following entity fields as well as collections. */
+function reachableEntities(type, entities, seen = new Set()) {
+    const found = [];
+    for (const entityId of entityIdsIn(type)) {
+        if (seen.has(entityId)) {
+            continue;
+        }
+        seen.add(entityId);
+        found.push(entityId);
+        for (const field of entities.get(entityId)?.fields ?? []) {
+            found.push(...reachableEntities(field.valueType, entities, seen));
         }
     }
+    return found;
+}
+function bind(scope, id, targets) {
+    const next = new Map(scope);
+    next.set(id, targets);
+    return next;
 }
-function linkState(state, linker) {
+/**
+ * Reads an expression performs, as state id → fields. Iteration scopes are followed, so
+ * projecting a field of each member is recorded as a read of that field of the state the
+ * members came from.
+ */
+function collectReads(expression, scope, states, found = new Map()) {
+    const record = (stateId, fieldId) => {
+        const entry = found.get(stateId) ?? new Set();
+        if (fieldId) {
+            entry.add(fieldId);
+        }
+        found.set(stateId, entry);
+    };
+    switch (expression.kind) {
+        case 'ref':
+            for (const stateId of statesOf(expression, scope, states)) {
+                record(stateId);
+            }
+            return found;
+        case 'field':
+            for (const stateId of statesOf(expression.source, scope, states)) {
+                record(stateId, expression.fieldId);
+            }
+            collectReads(expression.source, scope, states, found);
+            return found;
+        case 'object':
+            for (const entry of expression.entries) {
+                collectReads(entry.value, scope, states, found);
+            }
+            return found;
+        case 'binary':
+            collectReads(expression.left, scope, states, found);
+            collectReads(expression.right, scope, states, found);
+            return found;
+        case 'unary':
+            collectReads(expression.operand, scope, states, found);
+            return found;
+        case 'call':
+            for (const argument of expression.arguments) {
+                collectReads(argument, scope, states, found);
+            }
+            return found;
+        case 'filter':
+        case 'find':
+        case 'map':
+        case 'sort':
+        case 'every':
+        case 'some': {
+            collectReads(expression.source, scope, states, found);
+            const inner = bind(scope, expression.scopeId, statesOf(expression.source, scope, states));
+            const body = expression.kind === 'map'
+                ? expression.projection
+                : expression.kind === 'sort'
+                    ? expression.by
+                    : expression.predicate;
+            collectReads(body, inner, states, found);
+            return found;
+        }
+        case 'flatten':
+            collectReads(expression.source, scope, states, found);
+            return found;
+        case 'conditional':
+            collectReads(expression.condition, scope, states, found);
+            collectReads(expression.whenTrue, scope, states, found);
+            collectReads(expression.whenFalse, scope, states, found);
+            return found;
+        default:
+            return found;
+    }
+}
+function linkState(state, link, reads, scope) {
     for (const target of entityIdsIn(state.valueType)) {
-        linker.link(state.id, target, 'references');
+        link(state.id, target, 'references');
     }
     if (state.derivation) {
-        linker.reads(state.id, state.derivation, 'derives-from');
+        reads(state.id, state.derivation, scope, 'derives-from');
     }
 }
 function linkAction(action, linker) {
     for (const expression of [...(action.preconditions ?? []), ...(action.postconditions ?? [])]) {
-        linker.reads(action.id, expression);
+        linker.reads(action.id, expression, linker.scope);
     }
-    for (const operation of action.operations ?? []) {
+    linkOperations(action.id, action.operations ?? [], linker, linker.scope);
+}
+function linkOperations(actionId, operations, linker, scope) {
+    for (const operation of operations) {
         switch (operation.kind) {
             case 'set':
-                linker.writes(action.id, operation.target);
-                linker.reads(action.id, operation.value);
+                linker.writes(actionId, operation.target, scope);
+                linker.reads(actionId, operation.value, scope);
                 break;
             case 'insert':
-                // Inserting a constructed record writes every field the record declares.
-                linker.writes(action.id, operation.target, 'writes', expressionFieldIds(operation.value));
-                linker.reads(action.id, operation.value);
+                // A constructed record writes the fields it declares. Fields consulted while
+                // computing those values are reads, and must not be reported as writes.
+                linker.writes(actionId, operation.target, scope, 'writes', constructedFieldIds(operation.value));
+                linker.reads(actionId, operation.value, scope);
                 break;
             case 'remove':
-                linker.writes(action.id, operation.target);
+                linker.writes(actionId, operation.target, scope);
+                break;
+            case 'for-each': {
+                linker.reads(actionId, operation.collection, scope);
+                const inner = bind(scope, operation.scopeId, statesOf(operation.collection, scope, linker.states));
+                linkOperations(actionId, operation.operations, linker, inner);
                 break;
+            }
             case 'invoke':
-                linker.link(action.id, operation.actionId, 'depends-on');
+                linker.link(actionId, operation.actionId, 'depends-on');
                 for (const argument of Object.values(operation.arguments ?? {})) {
-                    linker.reads(action.id, argument);
+                    linker.reads(actionId, argument, scope);
                 }
                 break;
             case 'navigate':
                 if (operation.routeId) {
-                    linker.link(action.id, operation.routeId, 'depends-on');
+                    linker.link(actionId, operation.routeId, 'depends-on');
                 }
                 for (const argument of Object.values(operation.parameters ?? {})) {
-                    linker.reads(action.id, argument);
+                    linker.reads(actionId, argument, scope);
                 }
                 break;
             case 'native':
                 for (const input of Object.values(operation.inputs ?? {})) {
-                    linker.reads(action.id, input);
+                    linker.reads(actionId, input, scope);
                 }
                 if (operation.resultTarget) {
-                    linker.writes(action.id, operation.resultTarget);
+                    linker.writes(actionId, operation.resultTarget, scope);
                 }
                 for (const effect of operation.declaredEffects ?? []) {
                     if (effect.kind === 'reads-state') {
-                        linker.link(action.id, effect.stateId, 'reads');
+                        linker.link(actionId, effect.stateId, 'reads');
                     }
                     if (effect.kind === 'writes-state') {
-                        linker.link(action.id, effect.stateId, 'writes');
+                        linker.link(actionId, effect.stateId, 'writes');
                     }
                 }
                 break;
@@ -209,74 +325,85 @@ function linkAction(action, linker) {
         }
     }
 }
-function linkConstraint(constraint, linker) {
-    if (constraint.entityId) {
-        linker.link(constraint.id, constraint.entityId, 'constrains', expressionFieldIds(constraint.expression));
-    }
-    linker.reads(constraint.id, constraint.expression);
-}
 function linkUiNode(node, linker) {
+    const { link, reads, writes, scope } = linker;
     if (node.visibleWhen) {
-        linker.reads(node.id, node.visibleWhen);
+        reads(node.id, node.visibleWhen, scope);
     }
     switch (node.kind) {
         case 'view':
         case 'container':
             for (const childId of node.children) {
-                linker.link(node.id, childId, 'contains');
+                link(node.id, childId, 'contains');
             }
             return;
         case 'form':
             for (const childId of node.children) {
-                linker.link(node.id, childId, 'contains');
+                link(node.id, childId, 'contains');
             }
-            linker.reads(node.id, node.target);
+            reads(node.id, node.target, scope);
             if (node.submitActionId) {
-                linker.link(node.id, node.submitActionId, 'invokes');
+                link(node.id, node.submitActionId, 'invokes');
             }
             return;
         case 'conditional':
             for (const childId of [...node.whenTrue, ...(node.whenFalse ?? [])]) {
-                linker.link(node.id, childId, 'contains');
+                link(node.id, childId, 'contains');
             }
-            linker.reads(node.id, node.condition);
+            reads(node.id, node.condition, scope);
             return;
         case 'repeat':
-            linker.link(node.id, node.templateId, 'renders');
+            link(node.id, node.templateId, 'renders');
             if (node.emptyTemplateId) {
-                linker.link(node.id, node.emptyTemplateId, 'renders');
+                link(node.id, node.emptyTemplateId, 'renders');
             }
-            linker.reads(node.id, node.source);
+            reads(node.id, node.source, scope);
             return;
         case 'text':
             if (typeof node.value !== 'string') {
-                linker.reads(node.id, node.value);
+                reads(node.id, node.value, scope);
             }
             return;
         case 'field-display':
-            for (const id of referencedIds(node.source).flatMap((target) => linker.statesFor(target))) {
-                linker.link(node.id, id, 'reads', [node.fieldId]);
+            for (const stateId of statesOf(node.source, scope, linker.states)) {
+                link(node.id, stateId, 'reads', [node.fieldId]);
             }
+            reads(node.id, node.source, scope);
             return;
         case 'input':
             // An input both reads and writes the location it is bound to.
             if (node.binding?.location) {
-                linker.writes(node.id, node.binding.location, 'binds');
-                linker.writes(node.id, node.binding.location, 'writes');
+                writes(node.id, node.binding.location, scope, 'binds');
+                writes(node.id, node.binding.location, scope, 'writes');
             }
             if (node.options) {
-                linker.reads(node.id, node.options.source);
+                reads(node.id, node.options.source, scope);
             }
             return;
         case 'button':
-            linker.link(node.id, node.actionId, 'invokes');
+            link(node.id, node.actionId, 'invokes');
             if (typeof node.label !== 'string') {
-                linker.reads(node.id, node.label);
+                reads(node.id, node.label, scope);
             }
             for (const argument of Object.values(node.arguments ?? {})) {
-                linker.reads(node.id, argument);
+                reads(node.id, argument, scope);
             }
             return;
         default:
     }
 }
+/**
+ * Writes the derived edges into the graph. Queries derive them on demand, so this is only
+ * needed to materialize edges into serialized graph data.
+ */
+export function synchronizeEdges(graph) {
+    for (const edge of graph.listEdges()) {
+        if (edge.metadata?.derived === true) {
+            graph.removeEdge(edge.id);
+        }
+    }
+    for (const edge of deriveEdges(graph.listNodes())) {
+        graph.addEdge(edge.from, edge.to, edge.kind, { id: edge.id, metadata: edge.metadata });
+    }
+    return graph.listEdges();
+}

package/dist/diagnostics.d.ts

@@ -5,6 +5,10 @@ export interface ValidationIssue {
     nodeId?: NodeId;
     fieldId?: FieldId;
     edgeId?: EdgeId;
+    /** Where inside a value the problem is, such as `state_orders[2].field_lines[1]`. */
+    path?: string;
+    /** Structured context an agent can act on without parsing the message. */
+    details?: Record<string, unknown>;
 }
 export interface ValidationResult {
     valid: boolean;
@@ -35,5 +39,16 @@ export declare const VALIDATION_CODES: {
     readonly identityFieldMismatch: "IDENTITY_FIELD_MISMATCH";
     readonly assignmentTypeMismatch: "ASSIGNMENT_TYPE_MISMATCH";
     readonly invalidSelectorType: "INVALID_SELECTOR_TYPE";
+    readonly unsupportedExpression: "UNSUPPORTED_EXPRESSION";
+    readonly unsupportedOperation: "UNSUPPORTED_OPERATION";
+    readonly unsupportedConstraintScope: "UNSUPPORTED_CONSTRAINT_SCOPE";
+    readonly invalidAggregation: "INVALID_AGGREGATION";
+    readonly notACollection: "NOT_A_COLLECTION";
+    readonly initialValueTypeMismatch: "INITIAL_VALUE_TYPE_MISMATCH";
+    readonly initialValueUnknownField: "INITIAL_VALUE_UNKNOWN_FIELD";
+    readonly initialValueMissingRequiredField: "INITIAL_VALUE_MISSING_REQUIRED_FIELD";
+    readonly initialValueInvalidEntity: "INITIAL_VALUE_INVALID_ENTITY";
+    readonly scopeShadowing: "SCOPE_SHADOWING";
+    readonly scopeCollidesWithNode: "SCOPE_COLLIDES_WITH_NODE";
 };
 //# sourceMappingURL=diagnostics.d.ts.map

package/dist/diagnostics.js

@@ -22,4 +22,15 @@ export const VALIDATION_CODES = {
     identityFieldMismatch: 'IDENTITY_FIELD_MISMATCH',
     assignmentTypeMismatch: 'ASSIGNMENT_TYPE_MISMATCH',
     invalidSelectorType: 'INVALID_SELECTOR_TYPE',
+    unsupportedExpression: 'UNSUPPORTED_EXPRESSION',
+    unsupportedOperation: 'UNSUPPORTED_OPERATION',
+    unsupportedConstraintScope: 'UNSUPPORTED_CONSTRAINT_SCOPE',
+    invalidAggregation: 'INVALID_AGGREGATION',
+    notACollection: 'NOT_A_COLLECTION',
+    initialValueTypeMismatch: 'INITIAL_VALUE_TYPE_MISMATCH',
+    initialValueUnknownField: 'INITIAL_VALUE_UNKNOWN_FIELD',
+    initialValueMissingRequiredField: 'INITIAL_VALUE_MISSING_REQUIRED_FIELD',
+    initialValueInvalidEntity: 'INITIAL_VALUE_INVALID_ENTITY',
+    scopeShadowing: 'SCOPE_SHADOWING',
+    scopeCollidesWithNode: 'SCOPE_COLLIDES_WITH_NODE',
 };