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

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/derive-edges.js

@@ -3,6 +3,8 @@ import { locationExpressions, locationFieldIds, locationRootStateId, locationSel
 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 +212,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,

package/dist/graph.js

@@ -23,7 +23,7 @@ export class ApplicationGraph {
     /** Bumped by every change, so the derived edge index can never serve stale data. */
     revision = 0;
     semanticIndex;
-    constructor(id, name, version = '0.15.0') {
+    constructor(id, name, version = '0.16.0') {
         this.data = { id, name, version, nodes: {}, edges: {} };
     }
     get id() {

package/dist/index.d.ts

@@ -42,4 +42,6 @@ export * from './derive-edges.js';
 export * from './authority.js';
 export * from './ir.js';
 export * from './server-ir.js';
+export * from './authoring-schema.js';
+export * from './semantic-diff.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -42,3 +42,5 @@ export * from './derive-edges.js';
 export * from './authority.js';
 export * from './ir.js';
 export * from './server-ir.js';
+export * from './authoring-schema.js';
+export * from './semantic-diff.js';

package/dist/semantic-diff.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Canonical semantic graph diffing (spec16 §34-38, §150-160).
+ *
+ * `diffSchema` (spec11) already classifies changes to entities, fields, states,
+ * relationships and read policies — the *persistence-relevant* structure. `semanticDiff`
+ * is the superset spec16 asks for: every other executable and presentation node kind,
+ * classified into categories an agent or a reviewer can reason about (`semantic`,
+ * `authorization`, `provider`, `workflow`, `query`, `presentation`, `metadata`), plus the
+ * compatibility impact a change carries — does it move `semanticFingerprint`, does it move
+ * `schemaFingerprint`, does it raise the required Server IR contract. It embeds
+ * `diffSchema`'s result rather than re-deriving it, so there remains exactly one place that
+ * classifies a schema change (spec5.1 §26 "one canonical location per semantic rule").
+ *
+ * A node compared by full JSON identity **after** stripping human metadata is exactly the
+ * notion of "meaning" `semanticFingerprint` uses ({@link stripNonSemanticMetadata}), so a
+ * rename or a `metadata` edit is reported as `metadata`, never as `semantic` — and a
+ * presentation-only edit to a UI node or a route is `presentation`, never `authorization` or
+ * `schema` (spec16 §155).
+ */
+import type { SchemaDiff } from './schema-diff.js';
+import type { ServerIRContract } from './server-ir.js';
+import type { ApplicationGraph } from './graph.js';
+/** The classification vocabulary a semantic diff entry may belong to. A change may belong to more than one. */
+export declare const SEMANTIC_DIFF_CATEGORIES: readonly ["semantic", "authorization", "schema", "provider", "workflow", "query", "presentation", "metadata"];
+export type SemanticDiffCategory = (typeof SEMANTIC_DIFF_CATEGORIES)[number];
+export interface SemanticDiffEntry {
+    changeKind: 'added' | 'removed' | 'changed';
+    nodeId: string;
+    nodeKind: string;
+    /** One or more classifications this change belongs to (spec16 §36). */
+    categories: SemanticDiffCategory[];
+    message: string;
+}
+export interface SemanticDiffCompatibilityImpact {
+    semanticFingerprintChanged: boolean;
+    schemaFingerprintChanged: boolean;
+    /** Whether a mixed-build cluster could now disagree — either fingerprint moved. */
+    authorityCompatibilityAffected: boolean;
+    serverContractBefore: ServerIRContract;
+    serverContractAfter: ServerIRContract;
+    serverContractChanged: boolean;
+    /** Whether the embedded schema diff has any `migration-required` / `destructive` entry. */
+    migrationRequired: boolean;
+}
+export interface SemanticDiff {
+    /** Every non-schema-owned node kind's add/remove/change, classified. Canonically ordered by id. */
+    entries: SemanticDiffEntry[];
+    /** The detailed field-level diff for entities, fields, states, relationships and read policies. */
+    schema: SchemaDiff;
+    compatibility: SemanticDiffCompatibilityImpact;
+    /** Entry counts per category, `entries` only (the schema diff has its own `byClass`). */
+    byCategory: Record<SemanticDiffCategory, number>;
+    /** True when neither `entries` nor the schema diff found anything — a genuine no-op. */
+    isNoOp: boolean;
+}
+/**
+ * The canonical semantic difference between two graphs (spec16 §34-38). Pure and
+ * side-effect-free: it reads both graphs and computes, never mutates either (spec16 §133).
+ */
+export declare function semanticDiff(before: ApplicationGraph, after: ApplicationGraph): SemanticDiff;
+//# sourceMappingURL=semantic-diff.d.ts.map

package/dist/semantic-diff.js

@@ -0,0 +1,164 @@
+/**
+ * Canonical semantic graph diffing (spec16 §34-38, §150-160).
+ *
+ * `diffSchema` (spec11) already classifies changes to entities, fields, states,
+ * relationships and read policies — the *persistence-relevant* structure. `semanticDiff`
+ * is the superset spec16 asks for: every other executable and presentation node kind,
+ * classified into categories an agent or a reviewer can reason about (`semantic`,
+ * `authorization`, `provider`, `workflow`, `query`, `presentation`, `metadata`), plus the
+ * compatibility impact a change carries — does it move `semanticFingerprint`, does it move
+ * `schemaFingerprint`, does it raise the required Server IR contract. It embeds
+ * `diffSchema`'s result rather than re-deriving it, so there remains exactly one place that
+ * classifies a schema change (spec5.1 §26 "one canonical location per semantic rule").
+ *
+ * A node compared by full JSON identity **after** stripping human metadata is exactly the
+ * notion of "meaning" `semanticFingerprint` uses ({@link stripNonSemanticMetadata}), so a
+ * rename or a `metadata` edit is reported as `metadata`, never as `semantic` — and a
+ * presentation-only edit to a UI node or a route is `presentation`, never `authorization` or
+ * `schema` (spec16 §155).
+ */
+import { diffSchema } from './schema-diff.js';
+import { schemaFingerprint, canonicalJSON } from './schema-identity.js';
+import { semanticFingerprint, stripNonSemanticMetadata } from './semantic-identity.js';
+import { requiredServerContractForGraph } from './server-ir.js';
+import { SEMANTIC_NODE_KINDS } from './types.js';
+import { UI_NODE_KINDS } from './ui.js';
+/** The classification vocabulary a semantic diff entry may belong to. A change may belong to more than one. */
+export const SEMANTIC_DIFF_CATEGORIES = [
+    'semantic',
+    'authorization',
+    'schema',
+    'provider',
+    'workflow',
+    'query',
+    'presentation',
+    'metadata',
+];
+/** Kinds `diffSchema` already classifies in full field-level detail; excluded from the generic node loop. */
+const SCHEMA_OWNED_KINDS = new Set(['entity', 'state', 'relationship', 'read-policy']);
+const PROVIDER_KINDS = new Set(['integration', 'integration-operation', 'subscription', 'storage']);
+const PRESENTATION_KINDS = new Set([...UI_NODE_KINDS, 'route']);
+function kindCategory(kind) {
+    if (kind === 'authorization-policy')
+        return 'authorization';
+    if (kind === 'query')
+        return 'query';
+    if (kind === 'workflow')
+        return 'workflow';
+    if (kind === 'migration')
+        return 'schema';
+    if (PROVIDER_KINDS.has(kind))
+        return 'provider';
+    if (PRESENTATION_KINDS.has(kind))
+        return 'presentation';
+    return 'semantic';
+}
+/** Field names whose change on a node makes the change authorization-semantic too (spec16 §156). */
+const AUTHZ_FIELDS = ['authorizationPolicy', 'authorization', 'startPolicy', 'instanceAccessPolicy'];
+function isPlainObject(value) {
+    return !!value && typeof value === 'object' && !Array.isArray(value);
+}
+function equalJSON(a, b) {
+    return canonicalJSON(a) === canonicalJSON(b);
+}
+function describeChange(kind, id, changeKind) {
+    const verb = changeKind === 'added' ? 'added' : changeKind === 'removed' ? 'removed' : 'changed';
+    return `${kind} ${id} ${verb}`;
+}
+/**
+ * The canonical semantic difference between two graphs (spec16 §34-38). Pure and
+ * side-effect-free: it reads both graphs and computes, never mutates either (spec16 §133).
+ */
+export function semanticDiff(before, after) {
+    const schema = diffSchema(before, after);
+    const entries = [];
+    const kinds = [...SEMANTIC_NODE_KINDS, ...UI_NODE_KINDS, 'route'].filter((kind, index, all) => all.indexOf(kind) === index);
+    for (const kind of kinds) {
+        if (SCHEMA_OWNED_KINDS.has(kind)) {
+            continue;
+        }
+        const beforeById = new Map(before.getNodesByKind(kind).map((node) => [String(node.id), node]));
+        const afterById = new Map(after.getNodesByKind(kind).map((node) => [String(node.id), node]));
+        for (const [id, node] of afterById) {
+            if (!beforeById.has(id)) {
+                entries.push({
+                    changeKind: 'added',
+                    nodeId: id,
+                    nodeKind: kind,
+                    categories: [kindCategory(kind)],
+                    message: describeChange(kind, id, 'added'),
+                });
+                continue;
+            }
+            const previous = beforeById.get(id);
+            if (equalJSON(previous, node)) {
+                continue;
+            }
+            const strippedEqual = equalJSON(stripNonSemanticMetadata(previous), stripNonSemanticMetadata(node));
+            const categories = new Set();
+            if (strippedEqual) {
+                categories.add('metadata');
+            }
+            else if (isPlainObject(previous) && isPlainObject(node)) {
+                const changedFields = new Set([...Object.keys(previous), ...Object.keys(node)].filter((key) => !equalJSON(previous[key], node[key])));
+                const onlyAuthzFieldsChanged = changedFields.size > 0 && [...changedFields].every((key) => AUTHZ_FIELDS.includes(key));
+                if (onlyAuthzFieldsChanged) {
+                    categories.add('authorization');
+                }
+                else {
+                    categories.add(kindCategory(kind));
+                    if ([...changedFields].some((key) => AUTHZ_FIELDS.includes(key))) {
+                        categories.add('authorization');
+                    }
+                }
+            }
+            else {
+                categories.add(kindCategory(kind));
+            }
+            entries.push({
+                changeKind: 'changed',
+                nodeId: id,
+                nodeKind: kind,
+                categories: [...categories],
+                message: describeChange(kind, id, 'changed'),
+            });
+        }
+        for (const id of beforeById.keys()) {
+            if (!afterById.has(id)) {
+                entries.push({
+                    changeKind: 'removed',
+                    nodeId: id,
+                    nodeKind: kind,
+                    categories: [kindCategory(kind)],
+                    message: describeChange(kind, id, 'removed'),
+                });
+            }
+        }
+    }
+    entries.sort((a, b) => (a.nodeId < b.nodeId ? -1 : a.nodeId > b.nodeId ? 1 : a.changeKind.localeCompare(b.changeKind)));
+    const semanticFingerprintChanged = semanticFingerprint(before) !== semanticFingerprint(after);
+    const schemaFingerprintChanged = schemaFingerprint(before) !== schemaFingerprint(after);
+    const serverContractBefore = requiredServerContractForGraph(before);
+    const serverContractAfter = requiredServerContractForGraph(after);
+    const byCategory = Object.fromEntries(SEMANTIC_DIFF_CATEGORIES.map((c) => [c, 0]));
+    for (const entry of entries) {
+        for (const category of entry.categories) {
+            byCategory[category] += 1;
+        }
+    }
+    return {
+        entries,
+        schema,
+        compatibility: {
+            semanticFingerprintChanged,
+            schemaFingerprintChanged,
+            authorityCompatibilityAffected: semanticFingerprintChanged || schemaFingerprintChanged,
+            serverContractBefore,
+            serverContractAfter,
+            serverContractChanged: serverContractBefore !== serverContractAfter,
+            migrationRequired: schema.needsMigration.length > 0,
+        },
+        byCategory,
+        isNoOp: entries.length === 0 && schema.entries.length === 0,
+    };
+}

package/dist/semantic-identity.d.ts

@@ -73,6 +73,13 @@ export declare const SEMANTIC_FINGERPRINT_VERSION = 1;
  */
 export declare const EXECUTABLE_KINDS: readonly ["action", "integration", "integration-operation", "trigger", "event", "subscription", "read-policy", "query", "expression", "constraint", "transition-constraint", "storage", "relationship", "workflow", "authorization-policy"];
 export type ExecutableKind = (typeof EXECUTABLE_KINDS)[number];
+/**
+ * Removes human metadata (`name` / `description` / `label` / `metadata` / authoring
+ * provenance) from a value, recursively. Exported so tooling that needs "does this node's
+ * *meaning* differ" — `semanticDiff`, for one — shares the exact same notion of "meaning"
+ * the fingerprint uses, rather than reimplementing it (spec16 §35, §154).
+ */
+export declare function stripNonSemanticMetadata(value: unknown): unknown;
 export interface SemanticProjection {
     fingerprintVersion: number;
     schemaVersion: number;

package/dist/semantic-identity.js

@@ -93,6 +93,15 @@ export const EXECUTABLE_KINDS = [
 ];
 /** Keys removed everywhere in the tree — human metadata, never executable meaning. */
 const NON_SEMANTIC_KEYS = new Set(['name', 'description', 'label', 'metadata', AUTHORING_METADATA_KEY]);
+/**
+ * Removes human metadata (`name` / `description` / `label` / `metadata` / authoring
+ * provenance) from a value, recursively. Exported so tooling that needs "does this node's
+ * *meaning* differ" — `semanticDiff`, for one — shares the exact same notion of "meaning"
+ * the fingerprint uses, rather than reimplementing it (spec16 §35, §154).
+ */
+export function stripNonSemanticMetadata(value) {
+    return stripNonSemantic(value);
+}
 function stripNonSemantic(value) {
     if (Array.isArray(value)) {
         return value.map(stripNonSemantic);

package/dist/server-ir.d.ts

@@ -2,6 +2,7 @@ import type { FieldId, NodeId } from './ids.js';
 import type { ActionDef, ConstraintDef, EntityDef, ExpressionDef, StateDef, TransitionConstraintDef } from './nodes.js';
 import type { Expression } from './expressions.js';
 import type { FieldIndexEntry } from './graph.js';
+import type { ApplicationGraph } from './graph.js';
 import type { EventDef } from './events.js';
 import type { IntegrationDef, IntegrationOperationDef } from './integrations.js';
 import type { TriggerDef } from './triggers.js';
@@ -181,6 +182,14 @@ export declare function usesQueryVocabulary(ir: {
 }): boolean;
 /** The higher of two contracts, ordered by `SERVER_IR_CONTRACTS`. */
 export declare function maxContract(a: ServerIRContract, b: ServerIRContract): ServerIRContract;
+/**
+ * The Server IR contract this graph requires, computed straight from its nodes rather than
+ * from a compiled `ServerIR` (spec16 §32-33). This is the same "computed from the document,
+ * never asserted by hand" rule `compileToServerIR` applies, made available to static
+ * tooling that has only an `ApplicationGraph` — a semantic diff or a compatibility
+ * explanation should never need to run the compiler to answer "does this graph need v9".
+ */
+export declare function requiredServerContractForGraph(graph: ApplicationGraph): ServerIRContract;
 /** Every expression a Server IR document contains, in no particular order. */
 export declare function serverIRExpressions(ir: {
     states: readonly StateDef[];

package/dist/server-ir.js

@@ -227,6 +227,55 @@ export function usesQueryVocabulary(ir) {
 export function maxContract(a, b) {
     return SERVER_IR_CONTRACTS.indexOf(b) > SERVER_IR_CONTRACTS.indexOf(a) ? b : a;
 }
+/**
+ * The Server IR contract this graph requires, computed straight from its nodes rather than
+ * from a compiled `ServerIR` (spec16 §32-33). This is the same "computed from the document,
+ * never asserted by hand" rule `compileToServerIR` applies, made available to static
+ * tooling that has only an `ApplicationGraph` — a semantic diff or a compatibility
+ * explanation should never need to run the compiler to answer "does this graph need v9".
+ */
+export function requiredServerContractForGraph(graph) {
+    const actionsList = graph.getNodesByKind('action');
+    const actions = Object.fromEntries(actionsList.map((a) => [a.id, a]));
+    const ir = {
+        states: graph.getNodesByKind('state'),
+        actions,
+        constraints: graph.getNodesByKind('constraint'),
+        transitionConstraints: graph.getNodesByKind('transition-constraint'),
+        expressionDefs: Object.fromEntries(graph.getNodesByKind('expression').map((e) => [e.id, e])),
+        integrations: graph.getNodesByKind('integration'),
+        integrationOperations: Object.fromEntries(graph.getNodesByKind('integration-operation').map((o) => [o.id, o])),
+        events: graph.getNodesByKind('event'),
+        triggers: graph.getNodesByKind('trigger'),
+        subscriptions: graph.getNodesByKind('subscription'),
+        storages: graph.getNodesByKind('storage'),
+        queries: graph.getNodesByKind('query'),
+        readPolicies: graph.getNodesByKind('read-policy'),
+        authorizationPolicies: graph.getNodesByKind('authorization-policy'),
+        migrations: graph.getNodesByKind('migration'),
+        workflows: graph.getNodesByKind('workflow'),
+        schemaVersion: 1,
+    };
+    let required = requiredServerContract(serverIRExpressions(ir));
+    if (usesIntegrationVocabulary(ir))
+        required = maxContract(required, 'axiom.server.v3');
+    if (usesInvocationVocabulary(ir))
+        required = maxContract(required, 'axiom.server.v2');
+    if (usesV4Semantics(ir))
+        required = maxContract(required, 'axiom.server.v4');
+    if (usesExternalIOVocabulary(ir))
+        required = maxContract(required, 'axiom.server.v5');
+    if (usesQueryVocabulary(ir))
+        required = maxContract(required, 'axiom.server.v6');
+    if (usesMigrationVocabulary(ir))
+        required = maxContract(required, 'axiom.server.v7');
+    if (usesWorkflowVocabulary(ir))
+        required = maxContract(required, 'axiom.server.v8');
+    if (usesAuthorizationVocabulary(ir) || usesLegacyActionAuthorization(ir)) {
+        required = maxContract(required, 'axiom.server.v9');
+    }
+    return required;
+}
 /** Every expression a Server IR document contains, in no particular order. */
 export function serverIRExpressions(ir) {
     const found = [];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cynodia/axiom-core",
-  "version": "0.15.0-alpha.3",
+  "version": "0.16.0-alpha.1",
   "description": "Application Graph, semantic types, locations and validation for Axiom.",
   "license": "MIT",
   "author": "AskTech AS",