@cynodia/axiom-core 0.15.0-alpha.2 → 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/authorization.d.ts

@@ -21,6 +21,17 @@
  * equivalent to an inline `allow` over `PRINCIPAL`; `ReadPolicyDef` (spec10) remains the
  * row-level read mechanism, unified into query authorization by spec15 Phase D.
  *
+ * **spec15pt3 — one security-absence-aware evaluator for *every* authorization expression.**
+ * `AuthorizationPolicyDef.allow` and the legacy `ActionDef.authorization` expression share
+ * {@link evaluateAuthorizationExpression}: a `field(ref(PRINCIPAL), …)` / `field(ref(RESOURCE),
+ * …)` read of a key the scope object does not carry is **security-scope absence**, not an
+ * ordinary `undefined`, and `neq` / `not` / `or` / any comparison whose truth would depend on
+ * that absence is *not satisfied* — so a missing principal attribute can never manufacture
+ * authority through either surface (spec15pt3 §5, §7, §32). The two modes differ only in
+ * their *final interpretation* (a policy allows on exactly `true`; legacy keeps its historical
+ * truthiness), which `decideAuthorization` applies downstream — never in how absence, boolean
+ * composition or errors propagate.
+ *
  * This module is portable plain data + `Expression` trees; it carries no enforcement (that
  * is Phases C–F). The accessors are **total over any input** so a hand-tampered policy fails
  * closed with a structured diagnostic, never a native exception (spec15 §37).
@@ -122,6 +133,10 @@ export interface AuthorizationCheckInput {
     /**
      * The legacy `ActionDef.authorization` expression outcome, when that expression is present.
      * Its historical truthiness rule is kept: a non-empty array or any truthy value allows.
+     * spec15pt3 — this part MUST be produced by {@link evaluateAuthorizationExpression} (mode
+     * `'legacy-action'`), so `{ ok: true, value: false }` for a decision that depended on a
+     * missing security-scope field: absence reaches this combiner as a plain DENY, never as a
+     * truthy value.
      */
     legacy?: AuthorizationCheckPart;
 }
@@ -152,21 +167,57 @@ export interface AuthorizationPolicyScope {
     operation: string;
 }
 /**
- * spec15pt2 F1 — the **canonical** three-valued `AuthorizationPolicyDef.allow` evaluator,
- * used by every policy-bearing surface (spec15pt2 §33). Returns the `{ ok, value }` shape
- * `decideAuthorization` already consumes:
+ * Which authorization surface an expression is evaluated for (spec15pt3 §32). Both modes
+ * share {@link evaluateAuthorizationExpression}'s security-absence, boolean-composition and
+ * error propagation; they differ only downstream, in `decideAuthorization` — a `'policy'`
+ * result allows on exactly `true`, a `'legacy-action'` result keeps the historical
+ * `ActionDef.authorization` truthiness rule.
+ */
+export type AuthorizationEvaluationMode = 'policy' | 'legacy-action';
+/**
+ * The evaluation context for {@link evaluateAuthorizationExpression}. `'policy'` mode uses the
+ * closed `{ principal, resource, operation }` scope only. `'legacy-action'` mode additionally
+ * honours the historical `ActionDef.authorization` scope, which could also read an ordinary
+ * `StateDef`: {@link resolveExternalRef} resolves such a `ref` through the caller's ordinary
+ * evaluator, and an id it cannot resolve fails **closed** (never silently allows), exactly as
+ * a throwing `runtime.evaluate` did pre-pt3.
+ */
+export interface AuthorizationExpressionContext {
+    principal: Record<string, unknown> | null | undefined;
+    resource?: Record<string, unknown> | null | undefined;
+    operation?: string;
+    resolveExternalRef?: (refId: string) => {
+        found: boolean;
+        value?: unknown;
+    };
+}
+/**
+ * spec15pt3 §32 — the **one** canonical security-absence-aware authorization-expression
+ * evaluator, shared by `AuthorizationPolicyDef.allow` (`mode: 'policy'`) and the legacy
+ * `ActionDef.authorization` expression (`mode: 'legacy-action'`). Returns the `{ ok, value }`
+ * shape `decideAuthorization` consumes:
  *
- * - `allow` reduces to **exactly `true`** (with every required security input present) ⇒
- *   `{ ok: true, value: true }` — the only ALLOW;
- * - `allow` reduces to any other concrete value ⇒ `{ ok: true, value: false }`;
- * - the truth of `allow` depends on a **missing PRINCIPAL / RESOURCE field**
- *   (`AbsentSecurityValue`) ⇒ `{ ok: true, value: false }` — absence never creates authority
- *   through `eq` / `neq` / `not` / `or` (spec15pt2 §8-§12);
- * - an evaluation error (malformed node reaching the runtime, unsupported builtin) ⇒
- *   `{ ok: false }`.
+ * - the expression reduces to a concrete value ⇒ `{ ok: true, value }` — for `'policy'` only
+ *   an exact `true` is ALLOW; for `'legacy-action'` the historical truthiness rule (a truthy
+ *   value / non-empty array) applies, both in `decideAuthorization`;
+ * - its truth depends on a **missing PRINCIPAL / RESOURCE field** ⇒ `{ ok: true, value: false }`
+ *   — absence never creates authority through `eq` / `neq` / `not` / `lt` / `contains` /
+ *   `or` / any composition (spec15pt2 §8-§12, spec15pt3 §11-§16, §79-§82);
+ * - an evaluation error (malformed node reaching the runtime, unsupported builtin, an
+ *   unresolvable legacy `ref`) ⇒ `{ ok: false }` — fail closed, and the error keeps its
+ *   provenance through `not` / `or` so it cannot be negated back to ALLOW (spec15pt3 §84).
  *
  * A constant `literal(true)` is `{ ok: true, value: true }` regardless of principal — an
- * explicitly public policy still admits an anonymous caller (spec15pt2 §13, §14).
+ * explicitly public rule still admits an anonymous caller; the invariant is "missing
+ * referenced security fields cannot create authority", not "anonymous is forbidden"
+ * (spec15pt2 §13, §14; spec15pt3 §17). A `literal` nullish value stays a concrete value,
+ * never security absence (spec15pt3 §58).
+ */
+export declare function evaluateAuthorizationExpression(expression: unknown, context: AuthorizationExpressionContext, mode: AuthorizationEvaluationMode): AuthorizationCheckPart;
+/**
+ * spec15pt2 F1 — the three-valued `AuthorizationPolicyDef.allow` evaluator. A thin, stable
+ * wrapper over {@link evaluateAuthorizationExpression} in `'policy'` mode, kept for every
+ * existing policy-bearing call site (spec15pt2 §33).
  */
 export declare function evaluateAuthorizationPolicyAllow(allow: unknown, scope: AuthorizationPolicyScope): AuthorizationCheckPart;
 /**

package/dist/authorization.js

@@ -21,6 +21,17 @@
  * equivalent to an inline `allow` over `PRINCIPAL`; `ReadPolicyDef` (spec10) remains the
  * row-level read mechanism, unified into query authorization by spec15 Phase D.
  *
+ * **spec15pt3 — one security-absence-aware evaluator for *every* authorization expression.**
+ * `AuthorizationPolicyDef.allow` and the legacy `ActionDef.authorization` expression share
+ * {@link evaluateAuthorizationExpression}: a `field(ref(PRINCIPAL), …)` / `field(ref(RESOURCE),
+ * …)` read of a key the scope object does not carry is **security-scope absence**, not an
+ * ordinary `undefined`, and `neq` / `not` / `or` / any comparison whose truth would depend on
+ * that absence is *not satisfied* — so a missing principal attribute can never manufacture
+ * authority through either surface (spec15pt3 §5, §7, §32). The two modes differ only in
+ * their *final interpretation* (a policy allows on exactly `true`; legacy keeps its historical
+ * truthiness), which `decideAuthorization` applies downstream — never in how absence, boolean
+ * composition or errors propagate.
+ *
  * This module is portable plain data + `Expression` trees; it carries no enforcement (that
  * is Phases C–F). The accessors are **total over any input** so a hand-tampered policy fails
  * closed with a structured diagnostic, never a native exception (spec15 §37).
@@ -377,6 +388,14 @@ function evalAuthz(expression, scope, seen) {
                 return C(scope.resource ?? null);
             if (t === AUTHZ_OPERATION_SCOPE)
                 return C(scope.operation);
+            // spec15pt3 — a legacy `ActionDef.authorization` expression's historical scope also
+            // reaches ordinary `StateDef` refs. Resolve them through the caller's ordinary
+            // evaluator; an unresolved ref fails closed (`E` ⇒ DENY), never silently allows. A
+            // policy expression's scope is closed, so this branch is unreachable in `'policy'` mode.
+            if (scope.mode === 'legacy-action' && scope.resolveExternalRef) {
+                const resolved = scope.resolveExternalRef(t);
+                return resolved.found ? C(resolved.value) : E;
+            }
             return E; // out of the closed scope — validation rejects it; be total
         }
         case 'field': {
@@ -541,26 +560,37 @@ function applyPolicyBuiltin(fn, args) {
     }
 }
 /**
- * spec15pt2 F1 — the **canonical** three-valued `AuthorizationPolicyDef.allow` evaluator,
- * used by every policy-bearing surface (spec15pt2 §33). Returns the `{ ok, value }` shape
- * `decideAuthorization` already consumes:
+ * spec15pt3 §32 — the **one** canonical security-absence-aware authorization-expression
+ * evaluator, shared by `AuthorizationPolicyDef.allow` (`mode: 'policy'`) and the legacy
+ * `ActionDef.authorization` expression (`mode: 'legacy-action'`). Returns the `{ ok, value }`
+ * shape `decideAuthorization` consumes:
  *
- * - `allow` reduces to **exactly `true`** (with every required security input present) ⇒
- *   `{ ok: true, value: true }` — the only ALLOW;
- * - `allow` reduces to any other concrete value ⇒ `{ ok: true, value: false }`;
- * - the truth of `allow` depends on a **missing PRINCIPAL / RESOURCE field**
- *   (`AbsentSecurityValue`) ⇒ `{ ok: true, value: false }` — absence never creates authority
- *   through `eq` / `neq` / `not` / `or` (spec15pt2 §8-§12);
- * - an evaluation error (malformed node reaching the runtime, unsupported builtin) ⇒
- *   `{ ok: false }`.
+ * - the expression reduces to a concrete value ⇒ `{ ok: true, value }` — for `'policy'` only
+ *   an exact `true` is ALLOW; for `'legacy-action'` the historical truthiness rule (a truthy
+ *   value / non-empty array) applies, both in `decideAuthorization`;
+ * - its truth depends on a **missing PRINCIPAL / RESOURCE field** ⇒ `{ ok: true, value: false }`
+ *   — absence never creates authority through `eq` / `neq` / `not` / `lt` / `contains` /
+ *   `or` / any composition (spec15pt2 §8-§12, spec15pt3 §11-§16, §79-§82);
+ * - an evaluation error (malformed node reaching the runtime, unsupported builtin, an
+ *   unresolvable legacy `ref`) ⇒ `{ ok: false }` — fail closed, and the error keeps its
+ *   provenance through `not` / `or` so it cannot be negated back to ALLOW (spec15pt3 §84).
  *
  * A constant `literal(true)` is `{ ok: true, value: true }` regardless of principal — an
- * explicitly public policy still admits an anonymous caller (spec15pt2 §13, §14).
+ * explicitly public rule still admits an anonymous caller; the invariant is "missing
+ * referenced security fields cannot create authority", not "anonymous is forbidden"
+ * (spec15pt2 §13, §14; spec15pt3 §17). A `literal` nullish value stays a concrete value,
+ * never security absence (spec15pt3 §58).
  */
-export function evaluateAuthorizationPolicyAllow(allow, scope) {
+export function evaluateAuthorizationExpression(expression, context, mode) {
     let result;
     try {
-        result = evalAuthz(allow, scope, new Set());
+        result = evalAuthz(expression, {
+            principal: context.principal ?? null,
+            resource: context.resource ?? null,
+            operation: context.operation ?? 'action.invoke',
+            mode,
+            ...(context.resolveExternalRef ? { resolveExternalRef: context.resolveExternalRef } : {}),
+        }, new Set());
     }
     catch {
         return { ok: false };
@@ -571,6 +601,14 @@ export function evaluateAuthorizationPolicyAllow(allow, scope) {
         return { ok: true, value: false };
     return { ok: true, value: result.v };
 }
+/**
+ * spec15pt2 F1 — the three-valued `AuthorizationPolicyDef.allow` evaluator. A thin, stable
+ * wrapper over {@link evaluateAuthorizationExpression} in `'policy'` mode, kept for every
+ * existing policy-bearing call site (spec15pt2 §33).
+ */
+export function evaluateAuthorizationPolicyAllow(allow, scope) {
+    return evaluateAuthorizationExpression(allow, { principal: scope.principal, resource: scope.resource, operation: scope.operation }, 'policy');
+}
 /**
  * The distinct policy ids a graph node references for authorization — for dependency
  * analysis and `validateGraph` reference resolution. Total over malformed input.

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;
@@ -101,12 +108,15 @@ export interface AuthorityCompatibilityKey {
     serverContract: string;
     semanticFingerprint: string;
     /**
-     * spec15pt2 §35 — the runtime authorization-evaluator semantics version. `0.15.0-alpha.1`
-     * and `0.15.0-alpha.2` evaluate the *same* Server IR authorization policy differently
-     * (absent-value safety, F1), yet the graph — and therefore `semanticFingerprint` — is
-     * identical. This discriminator, present only when the IR carries authorization
-     * vocabulary, keeps the two builds from silently co-participating in one authority domain.
-     * Absent on a graph with no authorization policy (its evaluation is unchanged).
+     * spec15pt2 §35, spec15pt3 §37-§39 — the runtime authorization-evaluator semantics
+     * version. Successive builds evaluate the *same* Server IR authorization expression
+     * differently — `alpha.1` → `alpha.2` for `AuthorizationPolicyDef.allow` (absent-value
+     * safety, F1), `alpha.2` → `alpha.3` for the legacy `ActionDef.authorization` expression
+     * (F1-legacy) — yet the graph, and therefore `semanticFingerprint`, is identical. This
+     * discriminator, present whenever the IR carries an authorization *decision* (a policy
+     * reference or a legacy `authorization` expression), keeps builds that disagree from
+     * silently co-participating in one authority domain. Absent on a graph with no
+     * authorization decision (its evaluation is unchanged across every build).
      */
     authorizationRuntime?: string;
 }

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';
@@ -141,6 +142,18 @@ export declare function usesAuthorizationVocabulary(ir: {
         instanceAccessPolicy?: unknown;
     }[];
 }): boolean;
+/**
+ * Whether a document carries any legacy `ActionDef.authorization` expression (spec15pt3
+ * §39). This is not 0.15 *vocabulary* — it predates the milestone — but its runtime meaning
+ * changed in `0.15.0-alpha.3` (security-absence-aware evaluation, F1-legacy), so a mixed
+ * `alpha.2` / `alpha.3` cluster over a graph that can exercise it must fail closed. Total
+ * over a tampered IR.
+ */
+export declare function usesLegacyActionAuthorization(ir: {
+    actions?: Record<string, {
+        authorization?: unknown;
+    }>;
+}): boolean;
 /**
  * Authorization vocabulary whose *enforcement* has not shipped yet — the admission gate a
  * build uses to fail closed rather than run a declared policy as a silent no-op (spec4 §4,
@@ -169,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

@@ -177,6 +177,21 @@ export function usesAuthorizationVocabulary(ir) {
     }
     return false;
 }
+/**
+ * Whether a document carries any legacy `ActionDef.authorization` expression (spec15pt3
+ * §39). This is not 0.15 *vocabulary* — it predates the milestone — but its runtime meaning
+ * changed in `0.15.0-alpha.3` (security-absence-aware evaluation, F1-legacy), so a mixed
+ * `alpha.2` / `alpha.3` cluster over a graph that can exercise it must fail closed. Total
+ * over a tampered IR.
+ */
+export function usesLegacyActionAuthorization(ir) {
+    for (const action of Object.values(ir.actions ?? {})) {
+        if (action && typeof action === 'object' && action.authorization !== undefined) {
+            return true;
+        }
+    }
+    return false;
+}
 /**
  * Authorization vocabulary whose *enforcement* has not shipped yet — the admission gate a
  * build uses to fail closed rather than run a declared policy as a silent no-op (spec4 §4,
@@ -212,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.2",
+  "version": "0.16.0-alpha.1",
   "description": "Application Graph, semantic types, locations and validation for Axiom.",
   "license": "MIT",
   "author": "AskTech AS",