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

package/README.md

@@ -33,7 +33,7 @@ Shorter forms of the same routing: [`AGENTS.md`](AGENTS.md) and [`llms.txt`](llm
 at this package's root.
 
 **Status: experimental / alpha.** The API may change between alpha releases. The
-documentation in `docs/` describes this exact version, `0.15.0-alpha.3`.
+documentation in `docs/` describes this exact version, `0.16.0-alpha.2`.
 
 ## Installation
 
@@ -47,10 +47,12 @@ Every release of this project is a pre-release and npm's `latest` tag points at
 plain command above installs the current version. **There is no `alpha` dist-tag** — the tag
 was removed once it stopped tracking releases, and `npm install @cynodia/axiom@alpha` now
 fails with a 404. Pin the exact version instead when one is needed:
-`npm install @cynodia/axiom@0.15.0-alpha.3`.
+`npm install @cynodia/axiom@0.16.0-alpha.2`.
 
-These are ES modules compiled to ES2022; import them with `import`, not `require`. There is
-no published Axiom CLI. `@cynodia/axiom-server`'s SQLite persistence adapter additionally
+These are ES modules compiled to ES2022; import them with `import`, not `require`.
+`@cynodia/axiom-cli` (`npm install -g @cynodia/axiom-cli`) publishes the `axiom` executable
+— `explain` / `analyze` / `diff` over `AgentAPI`, plus `inspect` / `validate` / `build` /
+`serve` — see that package's README. `@cynodia/axiom-server`'s SQLite persistence adapter additionally
 needs a Node build that provides `node:sqlite` (Node 22 or newer); `isSqliteAvailable()`
 reports its absence rather than failing at import.
 

package/docs/ACTIONS_TRANSACTIONS.md

@@ -1,6 +1,6 @@
 # Actions and transactions
 
-Axiom 0.15.0-alpha.3. An action is behavior expressed as data, executed as a transaction.
+Axiom 0.16.0-alpha.2. An action is behavior expressed as data, executed as a transaction.
 
 ```ts
 {

package/docs/AGENT_API.md

@@ -1,6 +1,6 @@
 # Agent API
 
-Axiom 0.15.0-alpha.3. The machine-facing interface. Agents query semantics and apply
+Axiom 0.16.0-alpha.2. The machine-facing interface. Agents query semantics and apply
 structural transformations; they never edit generated code.
 
 ```ts
@@ -31,6 +31,15 @@ agent.referencedBy(expression)         // ids an expression references
 Edge kinds: `contains` `reads` `writes` `invokes` `renders` `binds` `depends-on`
 `derives-from` `constrains` `routes-to` `references`.
 
+`getDependencies`/`getDependents` return **dependency edges resolved to nodes, not a
+deduplicated node set**: if two distinct edges of the requested kinds connect the same pair
+of nodes — an action that both reads and writes the same state, with no `kinds` filter
+narrowing it to one — the target node appears once per edge (spec16pt2 §112, intentional:
+provenance would otherwise be lost). De-duplicate by `id` where a unique node set is what
+you actually want. `getTransitiveDependencies`/`Dependents` (spec16) are the exception —
+they return a deduplicated id set by construction, since "reachable at all" is what a
+transitive closure answers.
+
 ## Dependency queries
 
 ```ts
@@ -257,6 +266,158 @@ diff**.
 
 Change sets are in memory and per `AgentAPI` instance. There is no semantic version control.
 
+## Semantic inventory, dependencies and explanation (spec16)
+
+Everything in this section is **static**: it answers what the graph represents, never what a
+running authority has observed. It requires no repository source, no runtime internals and
+no credential — see [`AGENT_REFERENCE.md`](AGENT_REFERENCE.md#explainability--ai-authoring-spec16)
+for the compressed reference and the discoverability contract.
+
+```ts
+agent.inventory({ kinds?, cursor?, limit? })
+// { countsByKind, entries: [{ id, kind, name?, dependencyCount, dependentCount }], nextCursor? }
+
+agent.getTransitiveDependencies(id, edgeKinds?)   // { root, ids: [...] } — cycle-safe
+agent.getTransitiveDependents(id, edgeKinds?)
+agent.explainDependency(fromId, toId)             // { edges, reasons } — why the edge exists, or undefined
+```
+
+`inventory()` covers every graph-model kind and every UI kind. `kinds` restricts it; `limit` +
+`cursor` page through a large graph deterministically (canonical order is by id).
+
+### Explaining one node
+
+```ts
+agent.explainAction(actionId)
+// { actionId, parameters, reads, writes, invokesActions, integrationQueries, integrationEffects,
+//   runsQueries, storages, nativeOperations, authorization, constraintsThatMayBlock, invokedBy,
+//   clientInvocable, systemOnly, destructive, analysisComplete, analysisGaps }
+
+agent.explainState(stateId)
+// { stateId, valueType, derived, draft, ephemeral, authority, serverOnly, persistence,
+//   hasInitialValue, readers, writers, entities, constraints, transitionConstraints }
+
+agent.explainQuery(queryId)     // explainQuery(id) + { authorization, liveCapability }
+agent.explainWorkflow(workflowId)  // analyzeWorkflow(id) + { startPolicyId, instanceAccessPolicyId,
+                                   //   actionAuthorization, privilegeReviewActions }
+agent.explainGraph()
+// { nodeCountsByKind, executableRoots, securityBoundaries, externalCapabilities, opaqueBoundaries }
+```
+
+`explainAction` returning `analysisComplete: false` means a `NativeOperation` with no
+declared effects prevents a complete answer — `analysisGaps` says which one. Never read the
+absence of a listed effect as proof no such effect exists past that boundary (spec16 §29,
+§102, §173).
+
+### Capabilities and the NativeOperation boundary
+
+```ts
+agent.analyzeCapabilities()
+// { requirements: [{ capability, required, reasons }], requiredCapabilities }
+```
+
+`capability` is one of `REQUIRED_CAPABILITIES`: `persistence` `coordination`
+`mutation-observation` `live-queries` `workflow-store` `event-journal` `scheduler`
+`effect-execution` `provider-transaction` `blob-storage` `subscription-adapter`. Each
+requirement carries `reasons` — which graph nodes make it necessary — never a bare list
+(spec16 §31). This names capability *domains*, never a provider brand (spec16 §51).
+
+```ts
+agent.listNativeOperations()        // every NativeOperation, with its action and declared effects
+agent.summarizeNativeOperations()   // { count, opaqueCount, occurrences }
+```
+
+`opaque: true` on an occurrence means it declares no effects at all — static analysis cannot
+see past it. Long-term framework direction is zero (spec16 §49).
+
+### Authorization decision explanation
+
+```ts
+agent.explainAuthorizationDecision({ actionId | queryId, principal?, resource? })
+// { operation, decision: 'ALLOW' | 'DENY', reason, policyId, policyResult, legacyResult } | undefined
+```
+
+Evaluated through the **same** evaluator the authority uses (`evaluateAuthorizationExpression`
+/ `decideAuthorization`, spec15pt3) — never a second interpretation. Performs zero mutation,
+zero effect, zero provider call. It is advisory: the real operation always re-authorizes on
+the authority, and a prior result here is never a token (spec16 §26, §136-138). A missing
+`PRINCIPAL`/`RESOURCE` field can never manufacture `ALLOW` — see [`AUTHORIZATION.md`](AUTHORIZATION.md).
+
+### Semantic diff
+
+```ts
+agent.semanticDiff(otherGraph)
+// {
+//   entries: [{ changeKind: 'added'|'removed'|'changed', nodeId, nodeKind, categories, message }],
+//   schema: SchemaDiff,          // the spec11 field-level diff — entities/states/relationships/read-policies
+//   compatibility: {
+//     semanticFingerprintChanged, schemaFingerprintChanged, authorityCompatibilityAffected,
+//     serverContractBefore, serverContractAfter, serverContractChanged, migrationRequired,
+//   },
+//   byCategory, isNoOp,
+// }
+agent.requiredServerContract()   // the Server IR contract this graph currently requires
+```
+
+`entries` covers every non-schema-owned node kind (actions, queries, workflows,
+authorization policies, triggers, UI, …); entity/field/state/relationship/read-policy changes
+are in `schema` instead — the one place spec11 already classifies them, not duplicated here
+(spec16 §159). `categories` is one or more of `semantic` `authorization` `schema` `provider`
+`workflow` `query` `presentation` `metadata` — a rename is `metadata` only, never
+`semantic` (spec16 §35, §154-155); attaching/detaching/editing a policy is always tagged
+`authorization`, even on an `ActionDef`/`QueryDef`/`WorkflowDef` node (spec16 §156). Diffing
+is pure: it reads both graphs and mutates neither.
+
+### Candidate graph edits
+
+```ts
+const result = agent.proposeEdit({ changes: GraphChange[], preconditions?: EditPrecondition[] });
+// { applied, conflict?, applyError?, validation?, diff?, candidate? }
+agent.acceptEdit(result, { reason?, actor? });   // commits a validated candidate; throws otherwise
+```
+
+`changes` is the same portable `GraphChange[]` vocabulary `Transaction` already records —
+`add-node` `remove-node` `update-node` `add-field` `remove-field` `add-edge` `remove-edge`
+`set-theme` — so a proposal is plain, serializable data, not a TypeScript closure (spec16
+§79-80, §184). `proposeGraphEdit`/`applyGraphChanges` (free functions, also exported) never
+touch the graph passed in: every change is replayed onto a private clone, which is then
+validated and diffed against the original (spec16 §81-83, §133, §145).
+
+`preconditions` (`{ nodeId, expect: 'exists' | 'absent' | { field, equals } }`) are checked
+**before** any change is applied; a stale one is reported as `conflict`, not silently merged
+or overwritten (spec16 §85-86). `applyError` means a change referenced something that does
+not exist or is the wrong kind — distinct from `conflict` (a stale precondition) and from an
+invalid `validation` result (a change set that applied but produced an invalid graph, e.g. an
+unresolved reference — `candidate` is still returned for inspection, per spec16 §100).
+Because only the **final** candidate is validated, an atomic multi-change set may pass through
+an intermediate state that would not validate on its own (spec16 §84).
+
+### Machine-readable authoring schema
+
+```ts
+import { authoringSchema, describeAuthoringKind, listAuthorableKinds } from '@cynodia/axiom';
+```
+
+One descriptor per graph-model semantic node kind (`entity` … `authorization-policy` — the
+eighteen `SEMANTIC_NODE_KINDS`): `purpose`, `fields` (name, required, type, reference
+targets, closed enum, description), and a minimal-valid `template`. A template is not a set
+of defaults — it never assigns security-sensitive semantics an author did not ask for
+(spec16 §69-78). UI node kinds are deliberately **not** duplicated here: `@cynodia/axiom-ui`'s
+generated `PATTERN_CATALOG.json` (`npm run toolkit:catalog`) and [`UI.md`](UI.md) already own
+that authoring contract.
+
+### Conformance
+
+`axiom.conformance.v10` (`runToolingConformanceFixture` / `runToolingConformanceSuite`,
+`packages/agent-api/src/tooling-conformance.ts`) checks the canonical inspection/analysis/
+authoring/editing entry points above against independently hand-specified expected results
+(spec16 §123-126) — inventory, dependencies, explain-action, explain-query,
+authorization-analysis, capabilities, semantic-diff, diagnostics, authoring-schema,
+graph-edit and the native-operation boundary. This is a separate, smaller tier from the
+Server-IR execution conformance (`axiom.conformance.v1`-`v9`, `packages/server/conformance/`):
+AgentAPI carries no execution semantics of its own to check against a persistence backend
+(spec16 §121).
+
 ## Scale of change
 
 Prefer the smallest semantic change that expresses the intent.
@@ -276,3 +437,8 @@ State these to yourself before acting on an answer:
 - Type inference is partial, so a type-dependent question may have no answer rather than a wrong one.
 - `getOpaquePresentationNodes()` lists nodes whose renderer-specific presentation is **not** analyzed. Semantic analysis makes no claim about them.
 - Change history is per instance and in memory.
+- `explainAuthorizationDecision` is advisory static analysis, never a token: it does not accept or produce a resolved principal identity, does not authenticate anyone, and the real operation always re-authorizes on the authority (spec16 §26, §138).
+- `analyzeCapabilities` names capability *domains* a runtime would need, derived from graph structure — it does not know which concrete provider a deployment will choose, and never should (spec16 §51).
+- `semanticDiff`'s `.entries` covers every node kind except entities, states, relationships and read policies, which are the already-detailed `.schema` sub-object instead — do not expect an entity/field change to appear in `.entries` too.
+- `authoringSchema()` covers the eighteen graph-model semantic node kinds only. UI node authoring remains `@cynodia/axiom-ui`'s job — see [`UI.md`](UI.md).
+- Axiom provides deterministic semantic validation and analysis of *represented* semantics. It does not prove an AI-authored graph is safe merely because it validates, and it cannot see past a `NativeOperation` that declares no effects (spec16 §221).

package/docs/AGENT_REFERENCE.md

@@ -1,6 +1,6 @@
 # Agent reference
 
-Axiom 0.15.0-alpha.3. Compressed operational contract. Read this plus the `.d.ts`
+Axiom 0.16.0-alpha.2. Compressed operational contract. Read this plus the `.d.ts`
 declarations before authoring or modifying an Axiom application.
 
 Formal guarantees: [`SEMANTIC_CONTRACT.md`](SEMANTIC_CONTRACT.md). Mistakes that compile:
@@ -663,9 +663,9 @@ await serveAxiomApplication({
 ```
 
 `GET /` is the page, `POST /axiom` the semantic endpoint. No route, controller, handler, SQL
-or client JavaScript is authored. **There is no published Axiom CLI.** The halves also run
-separately: `serveOverHttp({ server, port })` is the bare authority, and
-`createDirectTransport(server)` drives one in-process for tests.
+or client JavaScript is authored. `@cynodia/axiom-cli`'s `axiom serve` runs this same path
+ad hoc. The halves also run separately: `serveOverHttp({ server, port })` is the bare
+authority, and `createDirectTransport(server)` drives one in-process for tests.
 
 A remote invocation returns `{ ok: false, pending: true }` and its outcome arrives later,
 through the same action-outcome lifecycle a local refusal uses — so a `diagnostic` node
@@ -949,12 +949,12 @@ Providers: `createMemoryRowStore` + `createMemoryMigrationStore` (deterministic
 `runMigrationConformanceFixture` over the `axiom.conformance.v5` fixtures in
 `conformance/migrations/`.
 
-There is **no published Axiom CLI**. Every schema/migration operation is a public library
-function — `inspectSchema`, `diffSchema`, `explainSchemaDiff`, `migrationImpact` (from
+Every schema/migration operation is also a public library function —
+`inspectSchema`, `diffSchema`, `explainSchemaDiff`, `migrationImpact` (from
 `@cynodia/axiom-agent-api`); `planMigration`, `explainMigration`, `executeMigration`,
-`getMigrationStatus` (from `@cynodia/axiom-server`). A host builds its own command around
-them. (The Axiom repository has a private, unpublished CLI over the same functions for
-maintainer use.)
+`getMigrationStatus` (from `@cynodia/axiom-server`) — for a host that builds its own
+command around them. `@cynodia/axiom-cli` publishes `axiom schema status` / `schema diff` /
+`migrate plan` / `migrate` / `migrate status` over the same functions.
 
 Diagnostics: `SCHEMA_MIGRATION_REQUIRED` `SCHEMA_INCOMPATIBLE` `MIGRATION_IN_PROGRESS`
 `MIGRATION_STATE_CORRUPTED` `MIGRATION_PATH_NOT_FOUND` `MIGRATION_APPROVAL_REQUIRED`
@@ -1323,6 +1323,56 @@ inside an action surfaces as `QUERY_OPERATION_FAILED` with `details.code =
 'AUTHORIZATION_DENIED'` and rolls the action back. A denied `workflow.inspect` /
 `workflow.history` returns `undefined` / `[]` (no existence leak).
 
+## EXPLAINABILITY & AI AUTHORING (spec16)
+
+Full model: [`AGENT_API.md`](AGENT_API.md#semantic-inventory-dependencies-and-explanation-spec16).
+No new graph/IR vocabulary; Server IR stays `axiom.server.v9` — 0.16 adds inspection,
+analysis and authoring-metadata APIs over the existing graph, never new execution semantics.
+Everything below is **static**: it reads the graph, never a running authority, and performs
+zero mutation / zero effect / zero provider call (spec16 §133).
+
+```ts
+agent.inventory({ kinds?, cursor?, limit? })                 // every node, dependency/dependent counts
+agent.getTransitiveDependencies(id, edgeKinds?) / agent.getTransitiveDependents(id, edgeKinds?)
+agent.explainDependency(fromId, toId)                         // { edges, reasons } | undefined
+
+agent.explainAction(actionId)     // reads/writes/effects/authorization/invokedBy/analysisComplete
+agent.explainState(stateId)       // type/persistence/authority/readers/writers/constraints
+agent.explainQuery(queryId)       // explainQuery + { authorization, liveCapability }
+agent.explainWorkflow(workflowId) // analyzeWorkflow + { startPolicyId, instanceAccessPolicyId, … }
+agent.explainGraph()              // structural summary: counts, executable roots, security, opaque boundaries
+
+agent.analyzeCapabilities()          // { requirements: [{ capability, required, reasons }], requiredCapabilities }
+agent.listNativeOperations() / agent.summarizeNativeOperations()   // the one opaque boundary, made discoverable
+
+agent.explainAuthorizationDecision({ actionId | queryId, principal?, resource? })
+// same evaluator the authority uses; ALLOW/DENY + which mechanism decided it. Advisory only.
+
+agent.semanticDiff(otherGraph)    // { entries, schema, compatibility, byCategory, isNoOp }
+agent.requiredServerContract()    // the Server IR contract this graph currently needs
+
+agent.proposeEdit({ changes, preconditions? })   // { applied, conflict?, applyError?, validation?, diff?, candidate? }
+agent.acceptEdit(result, { reason?, actor? })    // commits a validated candidate
+
+authoringSchema() / describeAuthoringKind(kind) / listAuthorableKinds()   // free functions, core
+```
+
+`REQUIRED_CAPABILITIES`: `persistence` `coordination` `mutation-observation` `live-queries`
+`workflow-store` `event-journal` `scheduler` `effect-execution` `provider-transaction`
+`blob-storage` `subscription-adapter`. `SEMANTIC_DIFF_CATEGORIES`: `semantic` `authorization`
+`schema` `provider` `workflow` `query` `presentation` `metadata`.
+
+`explainAction`/`listNativeOperations`: a `NativeOperation` with no declared effects makes
+`analysisComplete: false` — never silently treated as "no further effects" (spec16 §29,
+§102). `explainAuthorizationDecision` runs through the same `evaluateAuthorizationExpression`
+/ `decideAuthorization` the authority uses (spec15pt3) — it is not a second evaluator, and a
+prior result is never a token; the real operation always re-authorizes (spec16 §138).
+`semanticDiff` reuses `diffSchema` for entity/state/relationship/read-policy changes (`.schema`)
+and classifies everything else (`.entries`) — a rename is `metadata` only, attaching/editing a
+policy is always tagged `authorization` even on an `ActionDef`/`QueryDef`/`WorkflowDef`.
+`proposeEdit` replays a portable `GraphChange[]` onto a private clone — the graph passed in is
+never mutated, whether or not the candidate validates.
+
 ## Metadata classes
 
 ```ts

package/docs/ANTI_PATTERNS.md

@@ -1,6 +1,6 @@
 # Anti-patterns
 
-Axiom 0.15.0-alpha.3. Each of these compiles. Each is wrong. Each is followed by the correct
+Axiom 0.16.0-alpha.2. Each of these compiles. Each is wrong. Each is followed by the correct
 alternative.
 
 ## 1. Field names as entity runtime keys

package/docs/AUTHORITY.md

@@ -1,6 +1,6 @@
 # Authority
 
-Axiom 0.15.0-alpha.3. How an application crosses the trust boundary.
+Axiom 0.16.0-alpha.2. How an application crosses the trust boundary.
 
 Until 0.5.x an Axiom application executed locally. 0.6 adds an **authority**: a generic
 runtime that owns state, decides mutations and persists them. The same semantic graph
@@ -596,8 +596,8 @@ The two halves also run separately. `serveOverHttp({ server, port })` is the bar
 and `createAxiomServer({ ir, persistence, host })` is the authority with no transport at all —
 which is what `createDirectTransport` drives in tests.
 
-**There is no published Axiom CLI.** `packages/cli` is a private development tool of this
-repository and is not on npm; the API above is the supported way to run an application.
+`@cynodia/axiom-cli` publishes an `axiom serve` command over this same API for ad hoc use;
+the API above remains the supported way to run an application from your own Node process.
 
 ## Conformance
 

package/docs/AUTHORIZATION.md

@@ -1,6 +1,6 @@
 # Authorization
 
-Axiom 0.15.0-alpha.3. The operational contract for **authorization completeness** — the 0.15
+Axiom 0.16.0-alpha.2. The operational contract for **authorization completeness** — the 0.15
 milestone (spec15). Whether a principal may perform a semantic operation is part of the
 graph's executable meaning — not a runtime concern, not UI visibility, not something that
 varies by transport, provider, process, retry path or authority topology. `axiom.server.v9`
@@ -11,8 +11,8 @@ prior contract.
 > outside portable application semantics. **Authorization** answers *may this principal
 > perform this semantic operation?* — that is what this document defines.
 
-0.15 landed in nine phases (A–I); `0.15.0-alpha.2` (spec15pt2) and `0.15.0-alpha.3`
-(spec15pt3) are corrective passes. **spec15pt2**: authorization **absent-value safety** (a
+0.15 landed in nine phases (A–I); spec15pt2 and spec15pt3 are corrective passes that
+followed. **spec15pt2**: authorization **absent-value safety** (a
 missing PRINCIPAL / RESOURCE field never grants authority), `validateGraph` totality over a
 malformed `allow` tree, a fail-closed `host.authenticate` exception boundary. **spec15pt3**:
 the same fail-closed absent-value semantics now also cover the **legacy

package/docs/CONSTRAINTS.md

@@ -1,6 +1,6 @@
 # Constraints
 
-Axiom 0.15.0-alpha.3. Two constructs, answering different questions. They are not
+Axiom 0.16.0-alpha.2. Two constructs, answering different questions. They are not
 interchangeable.
 
 | | Question | Sees |

package/docs/DISTRIBUTED_AUTHORITY.md

@@ -1,6 +1,6 @@
 # Distributed authority
 
-*This document describes Axiom `0.15.0-alpha.3`.*
+*This document describes Axiom `0.16.0-alpha.2`.*
 
 The authoritative runtime (`docs/AUTHORITY.md`) may run as **more than one process at the
 same time**, over one shared persistence provider, without any change to the

package/docs/EFFECTS.md

@@ -1,6 +1,6 @@
 # Effects
 
-Axiom 0.15.0-alpha.3. External effects are not rollback-capable state mutations. This file
+Axiom 0.16.0-alpha.2. External effects are not rollback-capable state mutations. This file
 is the delivery model; [`AUTHORITY.md`](AUTHORITY.md#external-effects) is the load-bearing
 statement of why, and [`INTEGRATIONS.md`](INTEGRATIONS.md) is the operation vocabulary this
 builds on.

package/docs/EVENTS.md

@@ -1,6 +1,6 @@
 # Events
 
-Axiom 0.15.0-alpha.3. An event is a typed fact — something that happened — never work
+Axiom 0.16.0-alpha.2. An event is a typed fact — something that happened — never work
 itself. [`AUTHORITY.md`](AUTHORITY.md#external-events) is the load-bearing statement;
 this file is the vocabulary and the webhook delivery mechanism. A **subscription** is the
 other way an external fact becomes an `EventDef` payload — see

package/docs/EXPRESSIONS.md

@@ -1,6 +1,6 @@
 # Expressions
 
-Axiom 0.15.0-alpha.3. An expression describes **what value is computed**. It is a tree of
+Axiom 0.16.0-alpha.2. An expression describes **what value is computed**. It is a tree of
 plain data, never source text and never a callback. Evaluation is pure: an expression MUST
 NOT change state.
 

package/docs/GRAPH_MODEL.md

@@ -1,6 +1,6 @@
 # Graph model
 
-Axiom 0.15.0-alpha.3. The `ApplicationGraph` is the authoritative representation of an
+Axiom 0.16.0-alpha.2. The `ApplicationGraph` is the authoritative representation of an
 application. Everything else — the IR, the page, the DOM — is derived from it and is never
 edited.
 

package/docs/INTEGRATIONS.md

@@ -1,6 +1,6 @@
 # Integrations
 
-Axiom 0.15.0-alpha.3. How an application declares and calls an external system, without
+Axiom 0.16.0-alpha.2. How an application declares and calls an external system, without
 embedding a transport, an SDK or a secret in the graph. The authority boundary this
 depends on is [`AUTHORITY.md`](AUTHORITY.md#external-systems); this file is the vocabulary.
 

package/docs/LIVE_QUERIES.md

@@ -1,6 +1,6 @@
 # Realtime — live canonical queries
 
-Axiom 0.15.0-alpha.3. The operational contract for **observing a `QueryDef` result over
+Axiom 0.16.0-alpha.2. The operational contract for **observing a `QueryDef` result over
 time**: subscribe once, receive an initial coherent result, then receive canonical changes
 as authoritative committed state moves — through any compatible authority, across
 reconnects. `axiom.server.v7` (0.13 adds no IR vocabulary).

package/docs/LOCATIONS.md

@@ -1,6 +1,6 @@
 # Locations
 
-Axiom 0.15.0-alpha.3.
+Axiom 0.16.0-alpha.2.
 
 ```text
 Expression = a value

package/docs/MIGRATIONS.md

@@ -1,6 +1,6 @@
 # Schema evolution & semantic migrations
 
-Axiom 0.15.0-alpha.3. The operational contract for evolving a deployed application's
+Axiom 0.16.0-alpha.2. The operational contract for evolving a deployed application's
 semantic model and its persisted canonical data over time — adding a required field,
 splitting one field into two, removing an obsolete one, migrating millions of
 provider-backed rows — **without** an application-authored SQL migration, an ORM migration,

package/docs/PRESENTATION.md

@@ -1,6 +1,6 @@
 # Presentation
 
-Axiom 0.15.0-alpha.3. Presentation is **semantic UX intent**, expressed as data on a UI
+Axiom 0.16.0-alpha.2. Presentation is **semantic UX intent**, expressed as data on a UI
 node. It names roles, tokens and device classes. It never names a colour, a length, a media
 query or a CSS property.
 

package/docs/QUERIES.md

@@ -1,6 +1,6 @@
 # Semantic data access & the query layer
 
-Axiom 0.15.0-alpha.3. The operational contract for demand-driven reads over authoritative
+Axiom 0.16.0-alpha.2. The operational contract for demand-driven reads over authoritative
 data that is too large to materialize as a `StateDef` — 500,000 orders, 5,000,000 order
 lines, years of audit rows. `axiom.server.v6`.
 

package/docs/RUNTIME.md

@@ -1,6 +1,6 @@
 # Runtime
 
-Axiom 0.15.0-alpha.3. The runtime executes an `ApplicationIR`. It is domain-independent: it
+Axiom 0.16.0-alpha.2. The runtime executes an `ApplicationIR`. It is domain-independent: it
 contains no knowledge of any application.
 
 ## Constructing

package/docs/SEMANTIC_CONTRACT.md

@@ -1,6 +1,6 @@
 # Semantic contract
 
-Axiom 0.15.0-alpha.3. Runtime guarantees, stated formally. This file defines behavior; it
+Axiom 0.16.0-alpha.2. Runtime guarantees, stated formally. This file defines behavior; it
 does not teach. Where this file and any specification in `../specs/` disagree, this file
 describes the implementation and is authoritative.
 

package/docs/STATE.md

@@ -1,6 +1,6 @@
 # State
 
-Axiom 0.15.0-alpha.3. A `StateDef` is a named application value: stored, or computed from
+Axiom 0.16.0-alpha.2. A `StateDef` is a named application value: stored, or computed from
 other state.
 
 ```ts

package/docs/STORAGE.md

@@ -1,6 +1,6 @@
 # Storage and blobs
 
-Axiom 0.15.0-alpha.3. How an application stores, references, serves and deletes binary data —
+Axiom 0.16.0-alpha.2. How an application stores, references, serves and deletes binary data —
 an attachment, a document, a photograph, a diagnostic log — with no filesystem path, no
 upload route and no download route anywhere in it.
 

package/docs/SUBSCRIPTIONS.md

@@ -1,6 +1,6 @@
 # Subscriptions
 
-Axiom 0.15.0-alpha.3. How an application receives a stream of external events — an MQTT
+Axiom 0.16.0-alpha.2. How an application receives a stream of external events — an MQTT
 topic, a WebSocket feed, a queue consumer, a filesystem watcher, a serial port — without a
 client, a socket or a callback anywhere in the graph.
 

package/docs/TRIGGERS.md

@@ -1,6 +1,6 @@
 # Triggers
 
-Axiom 0.15.0-alpha.3. A `TriggerDef` says **when** an action should be invoked, without
+Axiom 0.16.0-alpha.2. A `TriggerDef` says **when** an action should be invoked, without
 embedding callback code. `docs/AUTHORITY.md`
 [§ Triggers](AUTHORITY.md#triggers) is the load-bearing statement of the execution model;
 this file is the vocabulary.

package/docs/UI.md

@@ -1,6 +1,6 @@
 # UI
 
-Axiom 0.15.0-alpha.3. Eleven semantic UI node kinds describe **what exists and what it does**.
+Axiom 0.16.0-alpha.2. Eleven semantic UI node kinds describe **what exists and what it does**.
 How it looks is [presentation](PRESENTATION.md).
 
 All eleven share `UIBase`:

package/docs/VALIDATION.md

@@ -1,6 +1,6 @@
 # Validation
 
-Axiom 0.15.0-alpha.3. Validation is authoring-time structural checking. It is not the same
+Axiom 0.16.0-alpha.2. Validation is authoring-time structural checking. It is not the same
 as runtime constraint evaluation — see [`CONSTRAINTS.md`](CONSTRAINTS.md) for the four
 layers of correctness.
 
@@ -70,7 +70,7 @@ non-numeric collections, and obviously incompatible assignments.
 
 | Code | Raised when |
 | --- | --- |
-| `UNKNOWN_STATE_REF` | A location naming a state that does not exist, or an unknown location kind. |
+| `UNKNOWN_STATE_REF` | A location naming a state that does not exist, an unknown location kind, or a location/selector that is not even a plain object (spec16pt2 F2). |
 | `DERIVED_STATE_WRITE` | A write target rooted in derived state. |
 | `FIELD_ON_NON_ENTITY` | A field selected on a value that has no fields. |
 | `FIELD_NOT_ON_ENTITY` | A field that belongs to a different entity than the one addressed. |
@@ -107,6 +107,15 @@ Recursive, with a `path` naming the position.
 | `UNSUPPORTED_OPERATION` | An operation kind outside `OPERATION_KINDS`, or a `for-each` containing something other than a mutation. |
 | `INVALID_ACTION_REF` | A button or form naming something that is not an action. |
 | `INVALID_STATE_REF` | A reference that must be a state but is not. |
+| `INVALID_OPERATION_COLLECTION` | `ActionDef.operations`, or a `for-each`'s nested `operations`, is present but not an array (spec16pt2 F1). |
+| `INVALID_OPERATION` | An operation array entry that is not a plain object with a recognized `kind` — `null`, a primitive, or a malformed object (spec16pt2 F1/F2). |
+
+A candidate graph can arrive from AI generation, deserialization or hand-tampering, so
+`validateGraph` establishes shape before it ever traverses an action's operations or a
+location — `{}` where `operations` should be an array, or `null` where a `set`/`insert`/
+`remove` target should be a `Location`, is a structured diagnostic (`INVALID_OPERATION_COLLECTION`,
+`INVALID_OPERATION`, or `UNKNOWN_STATE_REF` for a malformed location/selector), never a
+native exception.
 
 ### Constraints
 

package/docs/WORKFLOWS.md

@@ -1,6 +1,6 @@
 # Durable workflows
 
-Axiom 0.15.0-alpha.3. The operational contract for **long-running semantic computations with
+Axiom 0.16.0-alpha.2. The operational contract for **long-running semantic computations with
 a durable control position** — orchestration that survives process death, authority
 failover, retries, timer delivery, event delivery and ordinary distributed contention
 without application-owned infrastructure. `axiom.server.v8`.
@@ -255,7 +255,7 @@ step's argument expressions / `retry` policy, a `wait-event` step's `where` / `b
   or binding migration, and none is inferred ("closest step" recovery never happens).
 - A graph with **no** `WorkflowDef` compiles to the byte-identical `axiom.server.v1`–`v7`
   document it always did, and its `semanticFingerprint` / `schemaFingerprint` are unchanged.
-- Pre-`0.15.0-alpha.3` instances carry a compatibility key computed before `WorkflowDef`
+- Pre-`0.16.0-alpha.2` instances carry a compatibility key computed before `WorkflowDef`
   participated; a corrected authority treats them as incompatible and fails closed (these
   are pre-freeze alpha releases — silent reinterpretation is the only unacceptable
   outcome).

package/llms.txt

@@ -1,6 +1,6 @@
 # Axiom
 
-> AI-native semantic application framework, version 0.15.0-alpha.3. An Axiom application is a
+> AI-native semantic application framework, version 0.16.0-alpha.2. An Axiom application is a
 > typed semantic graph — state, behavior, constraints, UI structure, presentation and
 > authority as structured data — executed by generic runtimes. The JavaScript, HTML and CSS
 > that reach a browser are compiler output and are never authored or edited. The primary

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cynodia/axiom",
-  "version": "0.15.0-alpha.3",
+  "version": "0.16.0-alpha.2",
   "description": "AI-native semantic web application framework.",
   "license": "MIT",
   "author": "AskTech AS",
@@ -34,10 +34,10 @@
     }
   },
   "dependencies": {
-    "@cynodia/axiom-core": "0.15.0-alpha.3",
-    "@cynodia/axiom-runtime": "0.15.0-alpha.3",
-    "@cynodia/axiom-compiler": "0.15.0-alpha.3",
-    "@cynodia/axiom-agent-api": "0.15.0-alpha.3"
+    "@cynodia/axiom-core": "0.16.0-alpha.2",
+    "@cynodia/axiom-runtime": "0.16.0-alpha.2",
+    "@cynodia/axiom-compiler": "0.16.0-alpha.2",
+    "@cynodia/axiom-agent-api": "0.16.0-alpha.2"
   },
   "scripts": {
     "build": "tsc -b tsconfig.json"