@cynodia/axiom-core 0.15.0-alpha.3 → 0.16.0-alpha.2

package/dist/authoring-schema.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Canonical machine-readable authoring metadata (spec16 §67-78).
+ *
+ * An AI agent constructing or modifying an Axiom graph must not have to guess valid node
+ * shapes, valid references, closed vocabularies or required fields from source code. This
+ * module is the **single** structured description of every publicly authorable semantic
+ * node kind — the same eighteen kinds `SEMANTIC_NODE_KINDS` enumerates — derived from the
+ * same closed vocabularies validation and the runtime already use (`OPERATION_KINDS`,
+ * `EDGE_KINDS`, `EXPRESSION_KINDS`, `WORKFLOW_STEP_TYPES`, `AUTHORIZATION_OPERATIONS`, …)
+ * rather than duplicating them by hand (spec16 §71).
+ *
+ * It is deliberately scoped to the **graph model** — `EntityDef` through
+ * `AuthorizationPolicyDef` — not the nine UI node kinds. UI authoring already has its own
+ * canonical, mechanically-checked machine catalogue (`@cynodia/axiom-ui`'s
+ * `packages/ui-toolkit/docs/PATTERN_CATALOG.json`, generated by `npm run toolkit:catalog`);
+ * a second description of the same nodes here would be exactly the "four unrelated sources
+ * of truth" spec16 §71 warns against, so `docs/UI.md` and the toolkit catalogue remain that
+ * authority.
+ *
+ * A template is a **minimal valid shape**, not a set of defaults: it never assigns
+ * security-sensitive semantics an author did not ask for (spec16 §78) — an `ActionDef`
+ * template carries no `authorizationPolicy`, which is exactly its pre-0.15 public contract,
+ * not a silently-inserted permission.
+ */
+import type { SemanticNodeKind } from './types.js';
+/** One field an authorable node kind carries. */
+export interface AuthoringFieldDescriptor {
+    name: string;
+    required: boolean;
+    /** A short, stable, human/machine readable type description — not a TypeScript type. */
+    type: string;
+    /** Other semantic node kinds this field's value (a `NodeId` or `NodeId[]`) may reference. */
+    referenceTargets?: readonly SemanticNodeKind[];
+    /** The closed vocabulary this field's value is drawn from, when it has one. */
+    closedEnum?: readonly string[];
+    description: string;
+}
+/** Every publicly authorable graph-model semantic node kind, structurally described. */
+export interface AuthoringKindDescriptor {
+    kind: SemanticNodeKind;
+    purpose: string;
+    fields: AuthoringFieldDescriptor[];
+    /** A minimal valid shape. `NodeId`/`FieldId` values are placeholders (`"<id>"`). */
+    template: Record<string, unknown>;
+}
+/** Every graph-model semantic node kind an agent may author (spec16 §72). */
+export declare function listAuthorableKinds(): readonly SemanticNodeKind[];
+/** The structural authoring contract for one node kind, or `undefined` for an unknown kind. */
+export declare function describeAuthoringKind(kind: string): AuthoringKindDescriptor | undefined;
+/** The complete authoring schema — one descriptor per authorable graph-model kind (spec16 §69, §70). */
+export declare function authoringSchema(): readonly AuthoringKindDescriptor[];
+/** Every edge kind the graph can derive, for tooling that renders `getEdges` results. */
+export declare function authoringEdgeKinds(): readonly string[];
+//# sourceMappingURL=authoring-schema.d.ts.map

package/dist/authoring-schema.js

@@ -0,0 +1,293 @@
+/**
+ * Canonical machine-readable authoring metadata (spec16 §67-78).
+ *
+ * An AI agent constructing or modifying an Axiom graph must not have to guess valid node
+ * shapes, valid references, closed vocabularies or required fields from source code. This
+ * module is the **single** structured description of every publicly authorable semantic
+ * node kind — the same eighteen kinds `SEMANTIC_NODE_KINDS` enumerates — derived from the
+ * same closed vocabularies validation and the runtime already use (`OPERATION_KINDS`,
+ * `EDGE_KINDS`, `EXPRESSION_KINDS`, `WORKFLOW_STEP_TYPES`, `AUTHORIZATION_OPERATIONS`, …)
+ * rather than duplicating them by hand (spec16 §71).
+ *
+ * It is deliberately scoped to the **graph model** — `EntityDef` through
+ * `AuthorizationPolicyDef` — not the nine UI node kinds. UI authoring already has its own
+ * canonical, mechanically-checked machine catalogue (`@cynodia/axiom-ui`'s
+ * `packages/ui-toolkit/docs/PATTERN_CATALOG.json`, generated by `npm run toolkit:catalog`);
+ * a second description of the same nodes here would be exactly the "four unrelated sources
+ * of truth" spec16 §71 warns against, so `docs/UI.md` and the toolkit catalogue remain that
+ * authority.
+ *
+ * A template is a **minimal valid shape**, not a set of defaults: it never assigns
+ * security-sensitive semantics an author did not ask for (spec16 §78) — an `ActionDef`
+ * template carries no `authorizationPolicy`, which is exactly its pre-0.15 public contract,
+ * not a silently-inserted permission.
+ */
+import { EDGE_KINDS, OPERATION_KINDS, INVOCATION_SOURCES } from './nodes.js';
+import { EXPRESSION_KINDS } from './expressions.js';
+import { TYPE_REF_KINDS } from './type-ref.js';
+import { AUTHORIZATION_OPERATIONS } from './authorization.js';
+import { SEMANTIC_NODE_KINDS } from './types.js';
+import { WORKFLOW_STEP_TYPES } from './workflows.js';
+import { RELATIONSHIP_CARDINALITIES } from './relationships.js';
+import { MIGRATION_OPERATION_KINDS } from './migration.js';
+import { INTEGRATION_OPERATION_MODES } from './integrations.js';
+const f = (name, required, type, description, extra = {}) => ({ name, required, type, description, ...extra });
+const EXPR = 'Expression';
+const NODE_ID = 'NodeId';
+const KINDS = [
+    {
+        kind: 'entity',
+        purpose: 'A record type. Instances live wherever a StateDef says they do, including nested inside collections and other entities.',
+        fields: [
+            f('fields', true, 'FieldDef[]', 'The entity\'s fields: id, valueType, required, defaultValue.'),
+            f('identityFieldId', false, 'FieldId', 'The field distinguishing instances. Required to address one by identity, and required by every TransitionConstraintDef on this entity — without it such a rule is silently skipped.'),
+        ],
+        template: { kind: 'entity', id: '<id>', fields: [{ id: '<field-id>', valueType: { kind: 'primitive', primitive: 'string' } }] },
+    },
+    {
+        kind: 'state',
+        purpose: 'A named application value: stored, or computed from other state via `derivation`.',
+        fields: [
+            f('valueType', true, 'TypeRef', 'The value\'s structural type.', { closedEnum: TYPE_REF_KINDS }),
+            f('initialValue', false, 'LiteralValue', 'Seed data, keyed by FieldId wherever it contains a record. Absent starts the state at its type default.'),
+            f('derivation', false, EXPR, 'When present, the state is computed rather than stored, and is read-only — a write is rejected.'),
+            f('draft', false, 'boolean', 'Marks work in progress. Skipped by instance validation until an action commits it.'),
+            f('ephemeral', false, 'boolean', 'Marks a UI fact rather than a domain fact. Skipped by instance validation; may not be persisted.'),
+            f('authority', false, 'Authority', 'Who may commit a canonical mutation: \'client\' (default) or \'server\'.', { closedEnum: ['client', 'server'] }),
+            f('serverOnly', false, 'boolean', 'Excludes the state from the client IR entirely.'),
+            f('persistence', false, 'StatePersistence', 'Where a stored value survives: memory, local-storage, or remote.', { closedEnum: ['memory', 'local-storage', 'remote'] }),
+        ],
+        template: { kind: 'state', id: '<id>', valueType: { kind: 'primitive', primitive: 'string' } },
+    },
+    {
+        kind: 'action',
+        purpose: 'Behaviour expressed as data, executed as a transaction: bind parameters, evaluate guards, run operations, check constraints, commit or roll back everything.',
+        fields: [
+            f('parameters', false, 'ActionParameter[]', 'Named, typed inputs.'),
+            f('guards', false, 'ActionGuard[]', 'Condition + failure pairs, checked in order before any transaction opens. Preferred over the parallel preconditions/failureModes arrays.'),
+            f('operations', true, 'Operation[]', 'The mutations and effects this action performs, run sequentially against provisional state.', { closedEnum: OPERATION_KINDS }),
+            f('postconditions', false, `${EXPR}[]`, 'Checked against proposed state after operations run, before commit.'),
+            f('destructive', false, 'boolean', 'Declared destructive intent (also inferred from a `remove` operation).'),
+            f('requiresConfirmation', false, 'boolean', 'UX only — never an authorization mechanism.'),
+            f('authorization', false, EXPR, 'Legacy boolean expression, evaluated on the authority with the caller bound to PRINCIPAL. Never reaches the client.'),
+            f('authorizationPolicy', false, NODE_ID, 'The AuthorizationPolicyDef governing action.invoke (spec15). If both this and `authorization` are present, the effective decision is their conjunction.', { referenceTargets: ['authorization-policy'] }),
+            f('invocation', false, 'ActionInvocationPolicy', 'Restricts which invocation sources (client / system) may reach this action at all.', { closedEnum: INVOCATION_SOURCES }),
+        ],
+        template: { kind: 'action', id: '<id>', operations: [] },
+    },
+    {
+        kind: 'constraint',
+        purpose: 'An invariant over proposed state, evaluated after every governed mutation. A constraint that cannot be evaluated counts as violated, never satisfied.',
+        fields: [
+            f('expression', true, EXPR, 'The boolean invariant.'),
+            f('entityId', false, NODE_ID, 'When set, evaluated once per canonical instance of this entity, bound to ref(entityId). Without it, evaluated once in the root scope.', { referenceTargets: ['entity'] }),
+            f('severity', false, `'error' | 'warning'`, 'Defaults to error. A warning is advice and never blocks a write.', { closedEnum: ['error', 'warning'] }),
+            f('message', false, 'string', 'Human-readable explanation of a violation.'),
+        ],
+        template: { kind: 'constraint', id: '<id>', expression: { kind: 'literal', value: true } },
+    },
+    {
+        kind: 'transition-constraint',
+        purpose: 'A rule about how state may change, seeing the instance as it was at transaction entry and as proposed. Holds on every governed write path, not just one.',
+        fields: [
+            f('entityId', true, NODE_ID, 'The entity whose transitions are governed. Must declare identityFieldId, or this rule is silently skipped.', { referenceTargets: ['entity'] }),
+            f('previousScopeId', true, NODE_ID, 'Binds the instance as it was at the outermost transaction\'s start.'),
+            f('proposedScopeId', true, NODE_ID, 'Binds the instance as proposed. Bound to nothing when the instance is being removed.'),
+            f('expression', true, EXPR, 'Must hold for every governed transition.'),
+            f('severity', false, `'error' | 'warning'`, 'Defaults to error.', { closedEnum: ['error', 'warning'] }),
+            f('message', false, 'string', 'Human-readable explanation of a violation.'),
+        ],
+        template: {
+            kind: 'transition-constraint',
+            id: '<id>',
+            entityId: '<entity-id>',
+            previousScopeId: '<previous-scope>',
+            proposedScopeId: '<proposed-scope>',
+            expression: { kind: 'literal', value: true },
+        },
+    },
+    {
+        kind: 'route',
+        purpose: 'A URL path mapped to a view, with typed path parameters.',
+        fields: [
+            f('path', true, 'string', 'The route path, with `:name` placeholders.'),
+            f('viewId', true, NODE_ID, 'The view this route renders.'),
+            f('parameters', false, 'RouteParameter[]', 'Matches each `:name` placeholder to an id and type.'),
+        ],
+        template: { kind: 'route', id: '<id>', path: '/', viewId: '<view-id>' },
+    },
+    {
+        kind: 'expression',
+        purpose: 'A named, reusable calculation: this semantic calculation exists once. Its body is evaluated in an isolated scope — its own parameters and application state, nothing else.',
+        fields: [
+            f('parameters', false, 'ExpressionParameter[]', 'Bound only inside this definition\'s body.'),
+            f('expression', true, EXPR, 'The calculation.', { closedEnum: EXPRESSION_KINDS }),
+            f('valueType', false, 'TypeRef', 'The declared result type. Absent, inferred from the body.'),
+            f('description', false, 'string', 'Human documentation.'),
+        ],
+        template: { kind: 'expression', id: '<id>', expression: { kind: 'literal', value: null } },
+    },
+    {
+        kind: 'integration',
+        purpose: 'An external capability domain — a name for "the systems outside Axiom that do X" — with no host, credential or SDK reference.',
+        fields: [],
+        template: { kind: 'integration', id: '<id>' },
+    },
+    {
+        kind: 'integration-operation',
+        purpose: 'A typed operation an integration exposes: a query (ask, wait for a finite answer) or an effect (tell, no answer joins the transaction).',
+        fields: [
+            f('integrationId', true, NODE_ID, 'The integration this operation belongs to.', { referenceTargets: ['integration'] }),
+            f('mode', true, `'query' | 'effect'`, 'Query or effect.', { closedEnum: INTEGRATION_OPERATION_MODES }),
+            f('parameters', false, 'IntegrationOperationParameter[]', 'Named, typed inputs.'),
+            f('resultType', true, 'TypeRef', 'The result shape.'),
+            f('clientSafe', false, 'boolean', 'Whether client-executed code may invoke it. Absent means server-only.'),
+            f('idempotent', false, 'boolean', 'Whether invoking this effect twice with the same idempotency key has one effect.'),
+            f('retry', false, 'RetryPolicy', 'Retry policy for a failed effect. Meaningless for a query.'),
+        ],
+        template: { kind: 'integration-operation', id: '<id>', integrationId: '<integration-id>', mode: 'query', resultType: { kind: 'primitive', primitive: 'string' } },
+    },
+    {
+        kind: 'event',
+        purpose: 'A typed semantic fact this application can dispatch and react to, through the one inbound event pipeline.',
+        fields: [f('payloadType', true, 'TypeRef', 'The shape of the event\'s payload.')],
+        template: { kind: 'event', id: '<id>', payloadType: { kind: 'primitive', primitive: 'string' } },
+    },
+    {
+        kind: 'trigger',
+        purpose: 'Invokes an ordinary action under a system principal, on an interval, after a delay, on a lifecycle moment, or on an event.',
+        fields: [
+            f('actionId', true, NODE_ID, 'The action this trigger invokes.', { referenceTargets: ['action'] }),
+            f('when', true, 'TriggerSpec', 'interval | delay | lifecycle | event.', { closedEnum: ['interval', 'delay', 'lifecycle', 'event'] }),
+            f('arguments', false, 'Record<paramId, Expression>', 'Keyed by the target action\'s parameter id.'),
+            f('enabledWhen', false, EXPR, 'Dynamic enablement, evaluated each time the trigger would otherwise fire.'),
+        ],
+        template: { kind: 'trigger', id: '<id>', actionId: '<action-id>', when: { kind: 'interval', everyMs: 60000 } },
+    },
+    {
+        kind: 'subscription',
+        purpose: 'A long-lived external event source: the world tells Axiom, while Axiom is listening. Delivers into the ordinary EventDef -> TriggerDef -> ActionDef pipeline.',
+        fields: [
+            f('integrationId', true, NODE_ID, 'The capability domain whose adapter maintains the source.', { referenceTargets: ['integration'] }),
+            f('source', false, 'string', 'Which semantic source within that integration. Absent, the subscription\'s own id is the name.'),
+            f('arguments', false, 'Record<string, Expression>', 'Configuration evaluated once, at activation.'),
+            f('eventId', true, NODE_ID, 'The EventDef a delivery becomes.', { referenceTargets: ['event'] }),
+            f('lifecycle', false, 'SubscriptionLifecyclePolicy', 'autoStart, required, reconnect.'),
+            f('delivery', false, 'SubscriptionDeliveryPolicy', 'Queue depth, backpressure policy, deduplication, retry.', { closedEnum: ['block', 'drop-oldest', 'drop-newest'] }),
+        ],
+        template: { kind: 'subscription', id: '<id>', integrationId: '<integration-id>', eventId: '<event-id>' },
+    },
+    {
+        kind: 'storage',
+        purpose: 'A portable object store for binary attachments. Bytes never enter the graph; state holds a BlobRef of five scalars.',
+        fields: [
+            f('blobEntityId', true, NODE_ID, 'The entity every BlobRef of this store conforms to.', { referenceTargets: ['entity'] }),
+            f('readAuthorization', false, EXPR, 'Who may read bytes/metadata. Absent means no one.'),
+            f('uploadAuthorization', false, EXPR, 'Who may upload. Absent means no one.'),
+            f('acceptedMediaTypes', false, 'string[]', 'Absent accepts any.'),
+            f('maxSizeBytes', false, 'number', 'The largest accepted upload.'),
+            f('retry', false, 'RetryPolicy', 'For a failed blob-commit/blob-delete.'),
+        ],
+        template: { kind: 'storage', id: '<id>', blobEntityId: '<entity-id>' },
+    },
+    {
+        kind: 'query',
+        purpose: 'A demand-driven read over authoritative data too large to materialize: fixed named clauses, every leaf an ordinary Expression.',
+        fields: [
+            f('parameters', false, 'QueryParameter[]', 'Named, typed inputs.'),
+            f('source', true, NODE_ID, 'The authoritative row entity.', { referenceTargets: ['entity'] }),
+            f('rowScopeId', true, NODE_ID, 'Binds one source row for every clause expression.'),
+            f('filter', false, EXPR, 'Boolean predicate. AND-ed with the entity\'s ReadPolicyDef on the authority.'),
+            f('sort', false, 'QuerySortKey[]', 'Ordering keys, most significant first; canonical identity is appended as a tie-breaker.'),
+            f('relationships', false, 'QueryRelationshipUse[]', 'Explicit RelationshipDef traversals.', { referenceTargets: ['relationship'] }),
+            f('projection', false, 'QueryProjection', 'Projected result fields. Absent returns whole source rows.'),
+            f('groupBy', false, `${EXPR}[]`, 'Group keys, present only with aggregate.'),
+            f('aggregate', false, 'QueryAggregate[]', 'Reductions over groups or the whole result.'),
+            f('pagination', false, 'QueryPagination', 'Strategy and page-size ceiling.', { closedEnum: ['cursor', 'offset'] }),
+            f('readPolicyId', false, NODE_ID, 'The ReadPolicyDef AND-ed into filter before execution.', { referenceTargets: ['read-policy'] }),
+            f('authorizationPolicy', false, NODE_ID, 'The AuthorizationPolicyDef governing query.read (spec15) — whether the principal may run the query at all.', { referenceTargets: ['authorization-policy'] }),
+        ],
+        template: { kind: 'query', id: '<id>', source: '<entity-id>', rowScopeId: '<row-scope>' },
+    },
+    {
+        kind: 'relationship',
+        purpose: 'An explicit, never-inferred entity-to-entity link a query may traverse.',
+        fields: [
+            f('from', true, 'RelationshipEndpoint', 'The entity + field a traversal starts from.'),
+            f('to', true, 'RelationshipEndpoint', 'The entity + field a traversal reaches. For to-one this MUST be the target\'s identityFieldId.'),
+            f('cardinality', true, `'to-one' | 'to-many'`, 'Whether one `from` row reaches one or many `to` rows.', { closedEnum: RELATIONSHIP_CARDINALITIES }),
+        ],
+        template: {
+            kind: 'relationship',
+            id: '<id>',
+            from: { entityId: '<entity-id>', fieldId: '<field-id>' },
+            to: { entityId: '<entity-id>', fieldId: '<field-id>' },
+            cardinality: 'to-one',
+        },
+    },
+    {
+        kind: 'read-policy',
+        purpose: 'A row-level filter AND-ed into every query\'s effective filter on the authority. A failed predicate makes a row invisible, never disclosed.',
+        fields: [
+            f('entityId', true, NODE_ID, 'The entity whose rows this policy governs. At most one per entity.', { referenceTargets: ['entity'] }),
+            f('rowScopeId', true, NODE_ID, 'Binds one candidate row while predicate is evaluated.'),
+            f('predicate', true, EXPR, 'Boolean. A row is visible when this is true for it, with the caller bound to PRINCIPAL.'),
+        ],
+        template: { kind: 'read-policy', id: '<id>', entityId: '<entity-id>', rowScopeId: '<row-scope>', predicate: { kind: 'literal', value: true } },
+    },
+    {
+        kind: 'migration',
+        purpose: 'A semantic migration between two consecutive schema versions: a closed operation vocabulary and pure Expression transforms.',
+        fields: [
+            f('fromSchema', true, 'number', 'The schema version this migration upgrades from.'),
+            f('toSchema', true, 'number', 'Must equal fromSchema + 1.'),
+            f('operations', true, 'MigrationOperation[]', 'The transformations this migration applies.', { closedEnum: MIGRATION_OPERATION_KINDS }),
+            f('reversibility', false, `'irreversible' | 'reverse-supplied'`, 'Absent means irreversible — the honest default for anything that may discard information.', { closedEnum: ['irreversible', 'reverse-supplied'] }),
+            f('reverseOperations', false, 'MigrationOperation[]', 'An explicit down-migration, present only with reversibility \'reverse-supplied\'.'),
+        ],
+        template: { kind: 'migration', id: '<id>', fromSchema: 1, toSchema: 2, operations: [] },
+    },
+    {
+        kind: 'workflow',
+        purpose: 'A durable, portable multi-step process: six step kinds, no script body, typed single-assignment bindings, closed expression scope (inputs / bindings / EVENT / PRINCIPAL — never StateDef, QueryDef, now/uuid/random).',
+        fields: [
+            f('inputs', false, 'WorkflowInput[]', 'Typed inputs bound when the workflow starts.'),
+            f('bindings', false, 'WorkflowBinding[]', 'Single-assignment values, each produced by exactly one wait-event step.'),
+            f('entry', true, NODE_ID, 'The first step id.'),
+            f('steps', true, 'WorkflowStep[]', 'action | wait-event | timer | branch | complete | fail.', { closedEnum: WORKFLOW_STEP_TYPES }),
+            f('startPolicy', false, NODE_ID, 'The AuthorizationPolicyDef governing workflow.start. Absent means any principal may start it.', { referenceTargets: ['authorization-policy'] }),
+            f('instanceAccessPolicy', false, NODE_ID, 'The AuthorizationPolicyDef governing inspect/history/cancel on a running instance. Absent means the 0.14 owner-fingerprint rule.', { referenceTargets: ['authorization-policy'] }),
+        ],
+        template: {
+            kind: 'workflow',
+            id: '<id>',
+            entry: '<step-id>',
+            steps: [{ type: 'complete', id: '<step-id>' }],
+        },
+    },
+    {
+        kind: 'authorization-policy',
+        purpose: 'The one authorization language: a single boolean `allow` expression over the closed scope PRINCIPAL / RESOURCE / OPERATION. Exactly true is ALLOW; false, absence or any evaluation error is DENY.',
+        fields: [
+            f('allow', true, EXPR, 'Deterministic — no now/uuid/random, no StateDef/QueryDef reference.', { closedEnum: [...AUTHORIZATION_OPERATIONS] }),
+        ],
+        template: { kind: 'authorization-policy', id: '<id>', allow: { kind: 'literal', value: false } },
+    },
+];
+const BY_KIND = new Map(KINDS.map((d) => [d.kind, d]));
+/** Every graph-model semantic node kind an agent may author (spec16 §72). */
+export function listAuthorableKinds() {
+    return SEMANTIC_NODE_KINDS;
+}
+/** The structural authoring contract for one node kind, or `undefined` for an unknown kind. */
+export function describeAuthoringKind(kind) {
+    return BY_KIND.get(kind);
+}
+/** The complete authoring schema — one descriptor per authorable graph-model kind (spec16 §69, §70). */
+export function authoringSchema() {
+    return KINDS;
+}
+/** Every edge kind the graph can derive, for tooling that renders `getEdges` results. */
+export function authoringEdgeKinds() {
+    return EDGE_KINDS;
+}

package/dist/authority.js

@@ -1,5 +1,5 @@
 import { referencedIds } from './derive-edges.js';
-import { actionGuards, isMutationOperation } from './nodes.js';
+import { actionGuards, actionOperations, isMutationOperation, operationChildren } from './nodes.js';
 import { locationExpressions, locationProviderEntityId, locationRootStateId } from './location.js';
 import { queryExpressions } from './query.js';
 export const AUTHORITIES = ['client', 'server'];
@@ -121,7 +121,7 @@ function operationExpressions(operation) {
     switch (operation.kind) {
         case 'for-each':
             found.push(operation.collection);
-            for (const nested of operation.operations ?? []) {
+            for (const nested of operationChildren(operation)) {
                 found.push(...operationExpressions(nested));
             }
             break;
@@ -157,11 +157,11 @@ function operationExpressions(operation) {
 }
 /** Whether an action calls out to an integration anywhere in its top-level operations. */
 export function actionUsesIntegration(action) {
-    return (action.operations ?? []).some((operation) => operation.kind === 'integration-query' || operation.kind === 'integration-effect');
+    return actionOperations(action).some((operation) => operation.kind === 'integration-query' || operation.kind === 'integration-effect');
 }
 /** Whether an action reaches an object store anywhere in its top-level operations. */
 export function actionUsesStorage(action) {
-    return (action.operations ?? []).some((operation) => operation.kind === 'blob-metadata' ||
+    return actionOperations(action).some((operation) => operation.kind === 'blob-metadata' ||
         operation.kind === 'blob-commit' ||
         operation.kind === 'blob-delete');
 }
@@ -170,7 +170,7 @@ export function actionUsesStorage(action) {
  * data provider, so an action that reads authoritative data through a query executes there.
  */
 export function actionUsesQuery(action) {
-    return (action.operations ?? []).some((operation) => operation.kind === 'query');
+    return actionOperations(action).some((operation) => operation.kind === 'query');
 }
 /**
  * Whether an action writes a `provider-record` location anywhere in its operations
@@ -183,11 +183,11 @@ export function actionWritesProviderRecord(action) {
             return locationProviderEntityId(operation.target) !== undefined;
         }
         if (operation.kind === 'for-each') {
-            return targets(operation.operations);
+            return targets(operationChildren(operation));
         }
         return false;
     });
-    return targets(action.operations ?? []);
+    return targets(actionOperations(action));
 }
 /** The states an action writes, following `for-each`, `invoke` and declared native effects. */
 export function statesWrittenBy(action, context, visited = new Set()) {
@@ -204,7 +204,7 @@ export function statesWrittenBy(action, context, visited = new Set()) {
             }
             switch (operation.kind) {
                 case 'for-each':
-                    walk(operation.operations ?? []);
+                    walk(operationChildren(operation));
                     break;
                 case 'invoke': {
                     const target = context.actions.get(operation.actionId);
@@ -238,7 +238,7 @@ export function statesWrittenBy(action, context, visited = new Set()) {
             }
         }
     };
-    walk(action.operations ?? []);
+    walk(actionOperations(action));
     return found;
 }
 /** The states an action reads: its guards, its values, its selectors, its authorization. */
@@ -252,11 +252,11 @@ export function statesReadByAction(action, context, visited = new Set()) {
         ...(action.postconditions ?? []),
         ...(action.authorization ? [action.authorization] : []),
     ];
-    for (const operation of action.operations ?? []) {
+    for (const operation of actionOperations(action)) {
         expressions.push(...operationExpressions(operation));
     }
     const found = statesReadBy(expressions, context);
-    for (const operation of action.operations ?? []) {
+    for (const operation of actionOperations(action)) {
         if (operation.kind === 'invoke') {
             const target = context.actions.get(operation.actionId);
             if (target) {

package/dist/derive-edges.js

@@ -1,8 +1,11 @@
 import { constructedFieldIds, expressionDefsIn, expressionFieldIds, walkExpression } from './expressions.js';
+import { actionOperations, operationChildren } from './nodes.js';
 import { locationExpressions, locationFieldIds, locationRootStateId, locationSelectorFieldIds, } from './location.js';
 import { isGroupFieldId } from './group.js';
 import { isUINode } from './ui.js';
 import { queryExpressions } from './query.js';
+import { workflowActionIds, workflowEventIds } from './workflows.js';
+import { nodeAuthorizationPolicyRefs } from './authorization.js';
 /**
  * Ids a `ref` expression mentions anywhere in the tree.
  *
@@ -210,12 +213,34 @@ export function deriveEdges(nodes) {
                 link(node.id, node.entityId, 'constrains');
                 reads(node.id, node.predicate, new Map([...rootScope, [node.rowScopeId, statesByEntity.get(node.entityId) ?? []]]));
                 break;
+            case 'workflow':
+                // Workflow expressions are closed-scope (inputs / bindings / EVENT / PRINCIPAL —
+                // spec14 §—, never StateDef), so there is nothing to attribute as a state read here.
+                // What the graph *can* say is which actions a step may invoke and which events it
+                // waits on, which is exactly what dependency/impact analysis needs (spec16 §12).
+                for (const actionId of workflowActionIds(node)) {
+                    link(node.id, actionId, 'invokes');
+                }
+                for (const eventId of workflowEventIds(node)) {
+                    link(node.id, eventId, 'references');
+                }
+                break;
+            case 'authorization-policy':
             case 'integration':
             case 'event':
                 break;
             default:
         }
     }
+    // Any node that references an `AuthorizationPolicyDef` (an action's or query's
+    // `authorizationPolicy`, a workflow's `startPolicy` / `instanceAccessPolicy`) depends on
+    // it — one generic pass over the closed set of policy-reference fields (spec15,
+    // spec16 §12), rather than a hand-maintained case per node kind that references one.
+    for (const node of nodes) {
+        for (const policyId of nodeAuthorizationPolicyRefs(node)) {
+            link(node.id, policyId, 'references');
+        }
+    }
     return [...pending.values()].map((entry) => ({
         id: `${entry.from}:${entry.kind}:${entry.to}`,
         from: entry.from,
@@ -227,12 +252,22 @@ export function deriveEdges(nodes) {
         },
     }));
 }
+function isPlainObject(value) {
+    return !!value && typeof value === 'object' && !Array.isArray(value);
+}
 /**
  * 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.
+ *
+ * Total over malformed input (spec16pt2 §12-24): a candidate expression can be
+ * AI-generated, deserialized or hand-tampered.
  */
-function statesOf(expression, scope, states, defs = new Map()) {
+function statesOf(expressionInput, scope, states, defs = new Map()) {
+    if (!isPlainObject(expressionInput) || typeof expressionInput.kind !== 'string') {
+        return [];
+    }
+    const expression = expressionInput;
     switch (expression.kind) {
         case 'ref': {
             const bound = scope.get(expression.targetId);
@@ -340,7 +375,7 @@ function bind(scope, id, targets) {
  * 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(), defs = new Map()) {
+function collectReads(expressionInput, scope, states, found = new Map(), defs = new Map()) {
     const record = (stateId, fieldId) => {
         const entry = found.get(stateId) ?? new Set();
         if (fieldId) {
@@ -348,6 +383,10 @@ function collectReads(expression, scope, states, found = new Map(), defs = new M
         }
         found.set(stateId, entry);
     };
+    if (!isPlainObject(expressionInput) || typeof expressionInput.kind !== 'string') {
+        return found;
+    }
+    const expression = expressionInput;
     switch (expression.kind) {
         case 'ref':
             for (const stateId of statesOf(expression, scope, states, defs)) {
@@ -431,7 +470,7 @@ function linkAction(action, linker) {
     for (const expression of [...(action.preconditions ?? []), ...(action.postconditions ?? [])]) {
         linker.reads(action.id, expression, linker.scope);
     }
-    linkOperations(action.id, action.operations ?? [], linker, linker.scope);
+    linkOperations(action.id, actionOperations(action), linker, linker.scope);
 }
 function linkOperations(actionId, operations, linker, scope) {
     for (const operation of operations) {
@@ -452,7 +491,7 @@ function linkOperations(actionId, operations, linker, scope) {
             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);
+                linkOperations(actionId, operationChildren(operation), linker, inner);
                 break;
             }
             case 'invoke':

package/dist/diagnostics.d.ts

@@ -212,5 +212,9 @@ export declare const VALIDATION_CODES: {
     readonly authorizationUnknownPolicy: "AUTHORIZATION_UNKNOWN_POLICY";
     /** An `AuthorizationPolicyDef.allow` expression calls `now` / `uuid` / `random` — authorization must be deterministic (spec15 §34). */
     readonly authorizationNondeterministic: "AUTHORIZATION_NONDETERMINISTIC";
+    /** `ActionDef.operations`, or a `for-each`'s nested `operations`, is present but not an array. */
+    readonly invalidOperationCollection: "INVALID_OPERATION_COLLECTION";
+    /** An operation array entry that is not a plain object with a recognized `kind`. */
+    readonly invalidOperation: "INVALID_OPERATION";
 };
 //# sourceMappingURL=diagnostics.d.ts.map

package/dist/diagnostics.js

@@ -211,4 +211,11 @@ export const VALIDATION_CODES = {
     authorizationUnknownPolicy: 'AUTHORIZATION_UNKNOWN_POLICY',
     /** An `AuthorizationPolicyDef.allow` expression calls `now` / `uuid` / `random` — authorization must be deterministic (spec15 §34). */
     authorizationNondeterministic: 'AUTHORIZATION_NONDETERMINISTIC',
+    // Validation totality (0.16pt2, spec16pt2 §12-24). A candidate graph can be AI-generated,
+    // deserialized or hand-tampered, so `validateGraph` must reject a malformed runtime
+    // *shape* structurally — never assume TypeScript's compile-time types already hold.
+    /** `ActionDef.operations`, or a `for-each`'s nested `operations`, is present but not an array. */
+    invalidOperationCollection: 'INVALID_OPERATION_COLLECTION',
+    /** An operation array entry that is not a plain object with a recognized `kind`. */
+    invalidOperation: 'INVALID_OPERATION',
 };

package/dist/expressions.d.ts

@@ -203,15 +203,21 @@ export declare function groupItems(source: Expression): FieldExpression;
  */
 export declare function expressionRef(expressionId: NodeId, args?: Record<string, Expression>): ExpressionRefExpression;
 export declare function conditional(condition: Expression, whenTrue: Expression, whenFalse: Expression): ConditionalExpression;
-/** Visits every sub-expression, parents before children. */
-export declare function walkExpression(expression: Expression, visit: (node: Expression) => void): void;
+/**
+ * Visits every sub-expression, parents before children. Total over malformed input
+ * (spec16pt2 §12-24): a candidate expression tree can arrive from AI generation,
+ * deserialization or hand-tampering (a deleted field, a tampered array element), and this
+ * is the shared visitor most expression-derived analysis in the codebase is built on — a
+ * malformed node here simply is not visited, rather than throwing while reading `.kind`.
+ */
+export declare function walkExpression(expressionInput: unknown, visit: (node: Expression) => void): void;
 /**
  * Field ids a constructed record assigns. Only the record's own entries count: the
  * expressions that compute those values are reads, not writes.
  */
-export declare function constructedFieldIds(expression: Expression): FieldId[];
+export declare function constructedFieldIds(expression: unknown): FieldId[];
 /** Expression definitions an expression reaches directly, in tree order. */
-export declare function expressionDefsIn(expression: Expression): NodeId[];
+export declare function expressionDefsIn(expression: unknown): NodeId[];
 /** Field ids an expression reads, including nested sources and constructed records. */
-export declare function expressionFieldIds(expression: Expression): FieldId[];
+export declare function expressionFieldIds(expression: unknown): FieldId[];
 //# sourceMappingURL=expressions.d.ts.map

package/dist/expressions.js

@@ -128,8 +128,21 @@ export function expressionRef(expressionId, args) {
 export function conditional(condition, whenTrue, whenFalse) {
     return { kind: 'conditional', condition, whenTrue, whenFalse };
 }
-/** Visits every sub-expression, parents before children. */
-export function walkExpression(expression, visit) {
+function isPlainObject(value) {
+    return !!value && typeof value === 'object' && !Array.isArray(value);
+}
+/**
+ * Visits every sub-expression, parents before children. Total over malformed input
+ * (spec16pt2 §12-24): a candidate expression tree can arrive from AI generation,
+ * deserialization or hand-tampering (a deleted field, a tampered array element), and this
+ * is the shared visitor most expression-derived analysis in the codebase is built on — a
+ * malformed node here simply is not visited, rather than throwing while reading `.kind`.
+ */
+export function walkExpression(expressionInput, visit) {
+    if (!isPlainObject(expressionInput) || typeof expressionInput.kind !== 'string') {
+        return;
+    }
+    const expression = expressionInput;
     visit(expression);
     switch (expression.kind) {
         case 'field':
@@ -195,7 +208,12 @@ export function walkExpression(expression, visit) {
  * expressions that compute those values are reads, not writes.
  */
 export function constructedFieldIds(expression) {
-    return expression.kind === 'object' ? expression.entries.map((entry) => entry.fieldId) : [];
+    if (!isPlainObject(expression) || expression.kind !== 'object' || !Array.isArray(expression.entries)) {
+        return [];
+    }
+    return expression.entries
+        .filter((entry) => isPlainObject(entry) && typeof entry.fieldId === 'string')
+        .map((entry) => entry.fieldId);
 }
 /** Expression definitions an expression reaches directly, in tree order. */
 export function expressionDefsIn(expression) {