@cynodia/axiom 0.9.0-alpha.2 → 0.11.0-alpha.1

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.9.0-alpha.2`.
+documentation in `docs/` describes this exact version, `0.11.0-alpha.1`.
 
 ## Installation
 
@@ -47,7 +47,7 @@ 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.9.0-alpha.2`.
+`npm install @cynodia/axiom@0.11.0-alpha.1`.
 
 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
@@ -189,6 +189,8 @@ focused document when the reference is not specific enough for the question at h
 | Timed and lifecycle execution, event-invoked actions | [`docs/TRIGGERS.md`](docs/TRIGGERS.md) |
 | Live inbound streams: lifecycle, delivery, deduplication, backpressure | [`docs/SUBSCRIPTIONS.md`](docs/SUBSCRIPTIONS.md) |
 | Binary data: `BlobRef`, upload, download, authorization, orphans | [`docs/STORAGE.md`](docs/STORAGE.md) |
+| Large authoritative datasets: `QueryDef`, relationships, read policy, providers, cursors, cache | [`docs/QUERIES.md`](docs/QUERIES.md) |
+| Evolving a deployed schema: `MigrationDef`, fingerprint, the startup gate, `executeMigration`, providers | [`docs/MIGRATIONS.md`](docs/MIGRATIONS.md) |
 | Machine queries, mutation impact and graph transformations | [`docs/AGENT_API.md`](docs/AGENT_API.md) |
 
 `docs/AGENT_REFERENCE.md` plus the `.d.ts` declarations are intended to be sufficient on

package/docs/ACTIONS_TRANSACTIONS.md

@@ -1,6 +1,6 @@
 # Actions and transactions
 
-Axiom 0.9.0-alpha.2. An action is behavior expressed as data, executed as a transaction.
+Axiom 0.11.0-alpha.1. 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.9.0-alpha.2. The machine-facing interface. Agents query semantics and apply
+Axiom 0.11.0-alpha.1. The machine-facing interface. Agents query semantics and apply
 structural transformations; they never edit generated code.
 
 ```ts

package/docs/AGENT_REFERENCE.md

@@ -1,6 +1,6 @@
 # Agent reference
 
-Axiom 0.9.0-alpha.2. Compressed operational contract. Read this plus the `.d.ts`
+Axiom 0.11.0-alpha.1. 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:
@@ -65,7 +65,7 @@ One canonical term per concept. These are not interchangeable.
 ## Graph construction
 
 ```ts
-const graph = new ApplicationGraph(id, name);      // version defaults to '0.9.0'
+const graph = new ApplicationGraph(id, name);      // version defaults to '0.11.0'
 graph.addNode<StateDef>({ id, kind: 'state', ... }); // returns NodeId; throws if id exists
 graph.getNode<StateDef>(id);                        // deep clone, or undefined
 graph.updateNode(node);                             // write a modified node back
@@ -140,8 +140,10 @@ group(src, scopeId, by) expressionRef(expressionId, args?)
 - `group` partitions a collection: `Collection<A>` → `Collection<Group<K, A>>`, read with `groupKey(g)` and `groupItems(g)`. Groups appear in **first-seen key order**, members keep source order, keys compare structurally. Nothing is sorted — use `sort` for that.
 - `expressionRef` evaluates a named `ExpressionDef` node: the calculation exists **once** in the graph and every consumer references it. Arguments are evaluated in the calling scope; **the body is evaluated in an isolated scope** that sees its parameters and application state and nothing else, so a definition means the same thing everywhere and its scope ids can never collide with a caller's.
 
-Builtins (14): `required` `is-empty` `non-empty` `length` `contains` `concat` `coalesce`
-`one-of` `count` `sum` `lowercase` `to-string` `now` `uuid`.
+Builtins (17): `required` `is-empty` `non-empty` `length` `contains` `concat` `coalesce`
+`one-of` `count` `sum` `lowercase` `to-string` `trim` `substring-before` `substring-after`
+`now` `uuid`. `trim` / `substring-before` / `substring-after` are `axiom.server.v7`
+vocabulary.
 
 Binary operators: `eq` `neq` `gt` `gte` `lt` `lte` `and` `or` `add` `subtract` `multiply`
 `divide`. Unary: `not` `negate`.
@@ -726,8 +728,12 @@ Portable artifacts, for a runtime written in another language:
 @cynodia/axiom-server/schema/server-ir.v2.schema.json JSON Schema for axiom.server.v2
 @cynodia/axiom-server/schema/server-ir.v3.schema.json JSON Schema for axiom.server.v3
 @cynodia/axiom-server/schema/server-ir.v4.schema.json JSON Schema for axiom.server.v4
-@cynodia/axiom-server/schema/server-ir.v5.schema.json JSON Schema for axiom.server.v5 (latest)
+@cynodia/axiom-server/schema/server-ir.v5.schema.json JSON Schema for axiom.server.v5
+@cynodia/axiom-server/schema/server-ir.v6.schema.json JSON Schema for axiom.server.v6
+@cynodia/axiom-server/schema/server-ir.v7.schema.json JSON Schema for axiom.server.v7 (latest)
 @cynodia/axiom-server/schema/protocol.v1.schema.json  JSON Schema for the protocol
+@cynodia/axiom-server/conformance/queries/<name>.json one query conformance fixture (axiom.conformance.v4)
+@cynodia/axiom-server/conformance/migrations/<name>.json one migration conformance fixture (axiom.conformance.v5)
 ```
 
 This list is generated/tested content, not hand-maintained prose: `packages/demo/test
@@ -820,6 +826,140 @@ Diagnostics: `SUBSCRIPTION_ADAPTER_MISSING` `SUBSCRIPTION_START_FAILED`
 `BLOB_NOT_FOUND` `BLOB_ACCESS_DENIED` `BLOB_TOO_LARGE` `BLOB_MEDIA_TYPE_REJECTED`
 `BLOB_OPERATION_FAILED` `BLOB_STORAGE_UNAVAILABLE` `BLOB_METADATA_FAILED`.
 
+## SEMANTIC DATA ACCESS & QUERY LAYER
+
+Full model: [`QUERIES.md`](QUERIES.md). For authoritative data too large to materialize as a
+`StateDef` — 500,000 orders, years of audit rows. The graph owns the meaning; a
+`DataProvider` owns execution. `axiom.server.v6`.
+
+```ts
+// A registered query: one node, fixed named clauses, every leaf an ordinary Expression.
+graph.addNode<QueryDef>({
+  id: QUERY_RECENT_ORDERS, kind: 'query',
+  source: ENTITY_ORDER, rowScopeId: SC_ROW,
+  parameters: [{ id: P_STATUS, valueType: enumType([...]) }],
+  filter: binary('eq', field(ref(SC_ROW), F_STATUS), ref(P_STATUS)),   // boolean; PRINCIPAL, params in scope
+  sort: [{ key: field(ref(SC_ROW), F_CREATED_AT), direction: 'desc' }], // canonical identity appended as tie-breaker
+  relationships: [{ relationshipId: REL_ORDER_ACCOUNT, bindAs: SC_ACCOUNT }],
+  projection: { entityId: ENTITY_ORDER_SUMMARY, fields: [{ id: F_S_NAME, value: field(ref(SC_ACCOUNT), F_ACCOUNT_NAME) }, ...] },
+  aggregate: [{ function: 'count' | 'sum' | 'min' | 'max' | 'average', key?: Expression, as: FieldId }],
+  groupBy: [Expression],                                               // first-seen key order; present only with aggregate
+  pagination: { strategy: 'cursor' | 'offset', maxPageSize, defaultPageSize },
+  readPolicyId: POLICY_ORDER,
+});
+
+graph.addNode<RelationshipDef>({ id, kind: 'relationship', cardinality: 'to-one' | 'to-many',
+  from: { entityId, fieldId }, to: { entityId, fieldId } });           // explicit, never inferred
+
+graph.addNode<ReadPolicyDef>({ id, kind: 'read-policy', entityId, rowScopeId,
+  predicate });   // boolean over row + PRINCIPAL; AND-ed into every query's filter, server-side
+
+// Inside an action, before the transaction opens; makes the action server-authority:
+{ kind: 'query', queryId, arguments?, bindAs }
+
+// Mutate a provider-backed row by identity, no collection materialized:
+{ kind: 'set', target: providerRecordFieldLocation(ENTITY_ORDER, F_ID, ref(P_ID), F_STATUS), value: literal('confirmed') }
+```
+
+Client protocol: `{ kind: 'query', queryId, arguments?, cursor?, pageSize?, offset? }` →
+`{ kind: 'query-result', ok, diagnostics, page? | aggregate?, revision }`. The client
+invokes a query **by id**, never a query language. `page.nextCursor` is opaque — store it
+and hand it back; never parse it.
+
+Client lifecycle: `createQueryStore(fetcher)` — a `QueryView` per `{queryId, arguments}` key
+with `load` / `refresh` / `loadMore` / `reset` / `subscribe`. States:
+`idle | loading | ready | refreshing | error` (`QUERY_LIFECYCLE_STATES`). A failed first
+load → `error` with no data; a failed refresh → `error` with the last good data still
+visible.
+
+Server: `createAxiomServer({ ir, dataProvider | dataProviders, cursorSecret?, queryCache? })`.
+`createMemoryDataProvider({ rows })` and `createSqliteDataProvider({ location, entities, seed })`
+are the reference providers, semantically identical. Cache identity includes a principal and
+read-policy fingerprint; any committed mutation clears it. `server.clearQueryCache()` /
+`server.queryCacheStats()`.
+
+AgentAPI: `listQueries()` `getQuery(id)` `explainQuery(id)` `getQueryEntities(id)`
+`getQueryFields(id)` `getQueryRelationships(id)` `getReadPolicyForQuery(id)`
+`getActionsInvalidatingQuery(id)` `getQueriesInvalidatedByAction(actionId)` `listRelationships()`
+`listReadPolicies()`; `getMutationImpact(location).affectedQueries`.
+
+Portable: `runQueryConformanceFixture` / `runQueryConformanceSuite` over the
+`axiom.conformance.v4` fixtures in `conformance/queries/`.
+
+Diagnostics: `QUERY_NOT_FOUND` `QUERY_ARGUMENT_TYPE_MISMATCH` `QUERY_CAPABILITY_UNSUPPORTED`
+`QUERY_CURSOR_INVALID` `QUERY_PAGE_SIZE_EXCEEDED` `QUERY_PROVIDER_FAILURE`
+`QUERY_RESULT_TYPE_MISMATCH` `QUERY_PROVIDER_MISSING` (boundary); `QUERY_RESOLVER_UNAVAILABLE`
+`QUERY_OPERATION_FAILED` (a `query` operation in the runtime). Validation:
+`UNKNOWN_QUERY_ENTITY` `UNKNOWN_RELATIONSHIP` `INVALID_RELATIONSHIP` `UNKNOWN_READ_POLICY`
+`INVALID_READ_POLICY` `DUPLICATE_READ_POLICY` `INVALID_QUERY_PREDICATE` `INVALID_QUERY_SORT`
+`INVALID_QUERY_PROJECTION` `INVALID_QUERY_AGGREGATE` `INVALID_QUERY_GROUPING`
+`INVALID_QUERY_PARAMETER` `UNSTABLE_PAGINATION` `INVALID_QUERY_OPERATION`
+`INVALID_PROVIDER_RECORD_LOCATION`.
+
+## SCHEMA EVOLUTION & SEMANTIC MIGRATIONS
+
+Full model: [`MIGRATIONS.md`](MIGRATIONS.md).
+
+A deployed application evolves its semantic model and persisted data through
+**`MigrationDef`** nodes — never application SQL, an ORM migration, a callback or a manual
+schema-version check. `graph.schemaVersion` is a monotonic integer (default `1`), distinct
+from the npm version and the Server IR contract. `schemaFingerprint(graph)` is a
+deterministic hash of every persistence-relevant fact and nothing else — renaming a `label`
+does not change it.
+
+A `MigrationDef` has `fromSchema` / `toSchema` (differ by one), and `operations` from a
+closed set of ten: `add-entity` `remove-entity` `add-field` `remove-field` `change-field`
+`populate-field` `transform-field` `transform-record` `add-relationship`
+`remove-relationship` (`MIGRATION_OPERATION_KINDS`). The set of migrations must form a
+contiguous chain `1 → … → schemaVersion`. `transform-record` is the split/merge primitive.
+
+Transform expressions (`populate` / `value` / `expression` / `produce`) are ordinary
+`Expression` trees read in an isolated scope: `field(ref(MIGRATION_OLD_SCOPE), fieldId)`,
+declared constants, and nested iteration scopes only. They MUST be pure — `now` / `uuid` /
+any other scope read throw. The string builtins `trim` `substring-before` `substring-after`
+(v7 vocabulary) exist for record transforms like splitting a name.
+
+Any `MigrationDef`, or a `schemaVersion > 1`, makes the Server IR **`axiom.server.v7`**,
+carrying `schemaVersion`, `schemaFingerprint` and `migrations`.
+
+Authoring-time: `validateGraph` rejects a broken chain, an unmarked destructive op, an
+impure or mistyped transform, an add-required-without-populate. `diffSchema(prev, next)`
+(core) classifies each change; `migrationCoversDiff` proves the chain covers the diff.
+AgentAPI: `inspectSchema()` `diffSchema(previous)` `migrationImpact(previous)`
+`explainSchemaDiff(diff)`.
+
+Runtime (`@cynodia/axiom-server`): `planMigration(ir, { fromVersion })` (pure) →
+`SemanticMigrationPlan`; `explainMigration(plan)` (the §56 account); `executeMigration({ ir,
+metadata, rows, principal: migrationAuthority('id'), approveDestructive })` — **host-only**,
+no `ServerRequest` branch; `getMigrationStatus(metadata)`. Row transforms are keyset-batched
+and checkpointed — a crash resumes to the identical result, a re-run is a no-op, a 2M-row
+migration is bounded memory. Destructive operations need explicit `approveDestructive` or
+zero writes occur. The target version commits only after post-migration validation.
+
+Startup gate: `createAxiomServer({ ir, migrationMetadata })` → `start()` refuses on anything
+but `compatible` / `fresh` — `SCHEMA_MIGRATION_REQUIRED` / `SCHEMA_INCOMPATIBLE` /
+`MIGRATION_IN_PROGRESS` / `MIGRATION_FINGERPRINT_MISMATCH`. `server.schemaGate()` reports
+without starting. While a migration runs, all requests get `MIGRATION_IN_PROGRESS`.
+
+Providers: `createMemoryRowStore` + `createMemoryMigrationStore` (deterministic reference);
+`createSqliteRowStore` + `createSqliteMigrationStore` (real `ALTER TABLE`, batched keyset
+`UPDATE`, `_axiom_migration_*` tables). Both derive equivalent target data. Portable:
+`runMigrationConformanceFixture` over the `axiom.conformance.v5` fixtures in
+`conformance/migrations/`.
+
+CLI (private): `axiom schema status` / `schema diff --against=<prev>` / `migrate plan
+--from=N` / `migrate --sqlite=<path> --approve=op,op` / `migrate status --sqlite=<path>`.
+
+Diagnostics: `SCHEMA_MIGRATION_REQUIRED` `SCHEMA_INCOMPATIBLE` `MIGRATION_IN_PROGRESS`
+`MIGRATION_STATE_CORRUPTED` `MIGRATION_PATH_NOT_FOUND` `MIGRATION_APPROVAL_REQUIRED`
+`MIGRATION_DESTRUCTIVE` `MIGRATION_PROVIDER_UNSUPPORTED` `MIGRATION_TRANSFORM_FAILED`
+`MIGRATION_VALIDATION_FAILED` `MIGRATION_CHECKPOINT_INVALID` `MIGRATION_FINGERPRINT_MISMATCH`
+`MIGRATION_NOT_AUTHORIZED` `MIGRATION_FAILED` (boundary). Validation:
+`INVALID_MIGRATION_VERSION` `MIGRATION_PATH_NOT_FOUND` `MIGRATION_CHAIN_FORK`
+`DUPLICATE_MIGRATION_OPERATION_ID` `MIGRATION_REQUIRED_FIELD_WITHOUT_DEFAULT`
+`MIGRATION_DESTRUCTIVE_UNMARKED` `INVALID_MIGRATION_OPERATION` `MIGRATION_TRANSFORM_IMPURE`
+`MIGRATION_TRANSFORM_TYPE_MISMATCH`.
+
 ## Metadata classes
 
 ```ts

package/docs/ANTI_PATTERNS.md

@@ -1,6 +1,6 @@
 # Anti-patterns
 
-Axiom 0.9.0-alpha.2. Each of these compiles. Each is wrong. Each is followed by the correct
+Axiom 0.11.0-alpha.1. Each of these compiles. Each is wrong. Each is followed by the correct
 alternative.
 
 ## 1. Field names as entity runtime keys
@@ -499,3 +499,186 @@ The second is also a path traversal waiting to happen, and neither can be reache
 and `GET /axiom/blob/<storageId>/<key>` already exist, for every Axiom application, with
 `StorageDef.uploadAuthorization` and `StorageDef.readAuthorization` enforced by the
 authority. Application-authored upload/download routes: zero.
+
+## 37. Bulk-loading a large collection into `StateDef`
+
+```ts
+// WRONG — every order in the browser, so the app can filter and sort them itself.
+graph.addNode<StateDef>({ id: STATE_ALL_ORDERS, kind: 'state',
+  valueType: collectionType(entityType(ENTITY_ORDER)), authority: 'server' });
+```
+
+At any real scale this is a non-starter, and it makes the client the enforcement point for
+filtering, sorting, pagination and visibility — all four of which then have to be re-done,
+correctly, on the authority anyway. A `QueryDef` says *what data is required*; the provider
+decides how to retrieve it. `StateDef` is for values that can reasonably be held as a whole.
+
+## 38. `SELECT`, a repository call, or `fetch('/api/orders')` in application code
+
+```ts
+// WRONG — the semantic boundary has leaked.
+const rows = await db.query('SELECT * FROM orders WHERE status = $1 ORDER BY created_at DESC LIMIT 50', [status]);
+const orders = await orderRepository.findMany({ where: { status }, take: 50 });
+const page = await fetch(`/api/orders?status=${status}&cursor=${cursor}`).then((r) => r.json());
+```
+
+The target is: the application says *"I need these orders"*; Axiom understands what that
+means, who may see them, and which mutations affect them; the provider decides how to
+retrieve them efficiently. Handwritten SQL, ORM calls, repository classes, application data
+endpoints and canonical-data `fetch()` in a reference application: zero. If the reference
+provider generates SQL, that SQL is provider infrastructure — values are parameters, and raw
+input never becomes a table name, a column name or a fragment.
+
+## 39. A second comparison or arithmetic language inside the query system
+
+```ts
+// WRONG — `{ op: 'eq', field, value }` is almost, but not exactly, what `binary('eq', …)` means.
+filter: { op: 'and', operands: [{ op: 'eq', field: F_STATUS, value: { param: 'status' } }] }
+```
+
+Every leaf of every query clause is an ordinary Axiom `Expression`. One `eq`, one null
+truth table, one arithmetic, one dependency walker. A parallel predicate language is two
+truth tables that must be kept identical by hand forever — which is `INVALID_QUERY_PREDICATE`
+waiting to be a subtle divergence between two runtimes.
+
+## 40. `visibleWhen`, a hidden column, or client-side filtering as read authorization
+
+```ts
+// WRONG — the rows still crossed the wire; a hostile client just asked for them raw.
+const visible = allOrders.filter((order) => order.customerId === session.customerId);
+```
+
+Presentation does not authorize behaviour (spec 5 §75), and the query layer does not change
+that. Row visibility is a `ReadPolicyDef` whose predicate is AND-ed into the effective
+filter on the authority — it scopes rows, aggregates and relationship traversals uniformly,
+and no client argument can remove it. `filterUnauthorizedRows(...)` in application code:
+zero.
+
+## 41. Parsing, forging, or hand-building a cursor string
+
+```ts
+// WRONG — a cursor is opaque application data, not a structure to construct.
+const next = btoa(JSON.stringify({ afterId: lastRow.id, page: page + 1 }));
+```
+
+A cursor carries a signed fingerprint of the query, the arguments, the principal and the
+read policy. Parsing it, or building your own, breaks continuation the moment the fingerprint
+does not match — `QUERY_CURSOR_INVALID`. Store `page.nextCursor` and hand it back
+unmodified; the client store's `loadMore` does exactly that. Manual cursor manipulation in
+application code: zero.
+
+## 42. A hand-written SQL migration, an ORM migration, or a repository script
+
+```ts
+// WRONG — the migration lives outside the graph, drifts from it, and is not portable.
+await db.exec('ALTER TABLE t_order ADD COLUMN status TEXT NOT NULL DEFAULT "draft"');
+```
+
+Express the *semantic* change as a `MigrationDef` operation:
+`{ kind: 'add-field', entityId: E_ORDER, field: F_STATUS, populate: literal('draft') }`.
+The provider turns it into `ALTER TABLE` (SQLite), a record transform (memory), or its own
+plan (a future Postgres). Handwritten migration SQL in application code: zero.
+
+## 43. An arbitrary migration callback
+
+```ts
+// WRONG — a stored closure is not serializable, not portable, and not inspectable.
+{ kind: 'transform-record', run: (old) => ({ given: old.name.split(' ')[0] }) }
+```
+
+A transform is an `Expression` tree read in an isolated scope — `object([{ fieldId: F_GIVEN,
+value: call('substring-before', field(ref(MIGRATION_OLD_SCOPE), F_NAME), literal(' ')) }])`.
+It is typed, deterministic and analyzable. `run: fn` does not exist and will not be added.
+
+## 44. Changing a `FieldId` to perform a rename
+
+```ts
+// WRONG — the diff sees a removed field and an added one, not a rename.
+fields: [{ id: fieldId('field_account_name'), /* was field_customer_name */ ... }]
+```
+
+`FieldId` is identity. Changing it makes the migration planner classify `-customer_name`
+`+account_name` as `incompatible-ambiguous` — and if you had wired a `remove-field`, it
+would drop the data. Keep the `FieldId`; change the `label`. That is a presentation-only
+change and needs no migration.
+
+## 45. Silently adding a required field
+
+```ts
+// WRONG — existing rows have no value for it, and none is invented.
+{ kind: 'add-field', entityId: E_ORDER, field: { id: F_STATUS, required: true } }
+```
+
+`validateGraph` rejects this (`MIGRATION_REQUIRED_FIELD_WITHOUT_DEFAULT`). Supply a
+`populate` expression, an explicit `populate-field`, or provider proof that every row
+already satisfies it. Axiom does not invent a zero / empty / null value.
+
+## 46. Deleting a populated field without approval
+
+```ts
+// WRONG — the migration exists, but nobody approved data loss.
+await executeMigration({ ir, metadata, rows, principal });   // no approveDestructive
+```
+
+A destructive operation is refused (`MIGRATION_APPROVAL_REQUIRED`) with **zero writes**
+until every destructive operation id appears in `approveDestructive`. "A migration exists"
+is never "the operator approved data loss."
+
+## 47. Assuming the package version is the schema version
+
+```ts
+// WRONG — three independent version concepts, conflated.
+if (pkg.version === persisted.axiomVersion) startNormally();
+```
+
+`@cynodia/axiom` `0.11.0`, `axiom.server.v7`, and `graph.schemaVersion` `14` are unrelated.
+Compare `schemaFingerprint(graph)` and `graph.schemaVersion` against what the provider
+durably recorded — which is exactly what the startup gate does.
+
+## 48. Starting an application against a mismatched persisted schema
+
+```ts
+// WRONG — the server starts, then queries and actions fail in arbitrary ways.
+const server = createAxiomServer({ ir });   // no migrationMetadata, schema has moved on
+await server.start();
+```
+
+Pass `migrationMetadata`. `start()` then refuses on anything but `compatible` / `fresh`
+with a specific diagnostic (`SCHEMA_MIGRATION_REQUIRED`, `SCHEMA_INCOMPATIBLE`, …). There is
+no hopeful startup.
+
+## 49. Loading the whole provider dataset into JS to migrate it
+
+```ts
+// WRONG — a 2,000,000-row table does not fit in a JS array.
+const all = await provider.loadAll(E_ORDER_LINE);
+for (const row of all) row.gross = row.total * 1.25;
+await provider.writeAll(E_ORDER_LINE, all);
+```
+
+`executeMigration` reads a **keyset-ordered batch**, transforms it, writes it back,
+checkpoints, and moves on. Peak memory is one batch, whatever the table size. Unbounded
+load-all transformations: zero.
+
+## 50. Wall-clock time or randomness inside a transform
+
+```ts
+// WRONG — the migration result depends on when it ran.
+{ kind: 'populate-field', value: call('now') }
+```
+
+`now` and `uuid` throw inside a migration transform (`MIGRATION_TRANSFORM_IMPURE`). A
+migration must be reproducible: the same source record and the same operation produce the
+same target record on every run, on every provider, in every language.
+
+## 51. Editing the provider's stored migration metadata by hand
+
+```sql
+-- WRONG — the schema version and the data no longer agree.
+UPDATE _axiom_migration_schema SET version = 7;
+```
+
+The stored version, fingerprint and step history are written only by the migration
+executor, atomically with the work they describe. Hand-editing them produces
+`MIGRATION_FINGERPRINT_MISMATCH` or `MIGRATION_STATE_CORRUPTED` at startup — the gate's
+whole purpose is to catch exactly this.

package/docs/AUTHORITY.md

@@ -1,6 +1,6 @@
 # Authority
 
-Axiom 0.9.0-alpha.2. How an application crosses the trust boundary.
+Axiom 0.11.0-alpha.1. 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
@@ -488,6 +488,48 @@ does for a local failure.
 | `BLOB_MEDIA_TYPE_REJECTED` | An upload's media type is not in the store's declared `acceptedMediaTypes`. |
 | `BLOB_OPERATION_FAILED` | A `blob-commit` or `blob-delete` failed at the store, after its retry policy. |
 | `INVOCATION_SOURCE_NOT_ALLOWED` | The action's `invocation.allowedSources` does not include this invocation's source (spec 8.1 §3-9) — refused before `authorization` is even evaluated, because no caller reaching the authority this way may invoke the action at all. |
+| `QUERY_NOT_FOUND` | The `QueryRequest` named a `QueryDef` this authority does not execute. |
+| `QUERY_ARGUMENT_TYPE_MISMATCH` | A query argument was missing, unknown, or did not conform to its declared `QueryParameter` type. Rejected before the provider is touched. |
+| `QUERY_UNAUTHORIZED` | The caller may not run this query — reserved for a future explicit query-authorization rule; row visibility today is enforced by the read policy AND-ed into the filter, not by refusal. |
+| `QUERY_CAPABILITY_UNSUPPORTED` | The configured `DataProvider` cannot push down a semantic this query requires, or the query's expression subset contains a leaf the provider cannot translate. Never approximated in memory. |
+| `QUERY_CURSOR_INVALID` | The cursor was tampered with, truncated, or minted for a different query / principal / read policy / contract. Continuing from it is refused; nothing is disclosed. |
+| `QUERY_PAGE_SIZE_EXCEEDED` | The requested page size exceeds the ceiling for this query (`min(QueryDef.pagination.maxPageSize, provider.maxPageSize)`). Refused, never silently truncated. |
+| `QUERY_PROVIDER_FAILURE` | The provider reported a failure executing the query or applying a provider-record mutation. Carries no state value. |
+| `QUERY_RESULT_TYPE_MISMATCH` | The provider returned rows that do not conform to the query's declared result shape. |
+| `QUERY_PROVIDER_MISSING` | No `DataProvider` is registered for this query's source entity (`AxiomServerOptions.dataProvider` / `dataProviders`). |
+| `SCHEMA_MIGRATION_REQUIRED` | Persisted canonical data is at an older semantic schema than the graph requires; a migration must run before the authority will serve traffic (spec11 §12). |
+| `SCHEMA_INCOMPATIBLE` | Persisted data cannot be reconciled with the graph — a stored schema version ahead of the graph's, or no migration path to it. |
+| `MIGRATION_IN_PROGRESS` | A migration is already running: a migration lock is held with a valid lease, by this instance or another (spec11 §66). |
+| `MIGRATION_STATE_CORRUPTED` | The provider's stored migration metadata is internally inconsistent — a fingerprint or completed-step history that does not add up. |
+| `MIGRATION_PATH_NOT_FOUND` | No contiguous `MigrationDef` chain connects the persisted schema version to the required one (spec11 §13). |
+| `MIGRATION_APPROVAL_REQUIRED` | The plan contains destructive operations and the `executeMigration` call did not name them in `approveDestructive` (spec11 §21). |
+| `MIGRATION_DESTRUCTIVE` | Reported by planning for each operation that discards persisted information — surfaced before execution (spec11 §20). |
+| `MIGRATION_PROVIDER_UNSUPPORTED` | The configured provider cannot execute a capability the plan requires. Refused before any write (spec11 §79). |
+| `MIGRATION_TRANSFORM_FAILED` | A migration transform expression threw, or produced a value that does not satisfy the target field. The target schema version was not committed. |
+| `MIGRATION_VALIDATION_FAILED` | Post-migration validation found persisted data that does not satisfy the target semantic schema (spec11 §37). |
+| `MIGRATION_CHECKPOINT_INVALID` | A resume was attempted from a checkpoint that does not match the current plan or schema fingerprint. |
+| `MIGRATION_FINGERPRINT_MISMATCH` | The persisted schema fingerprint does not match the origin of the resolved migration path — the stored data is not the shape the chain expects. |
+| `MIGRATION_NOT_AUTHORIZED` | The caller is not the host-controlled migration principal. Naming a migration id over the client protocol does nothing (spec11 §73, §74). |
+| `MIGRATION_FAILED` | A migration failed for a reason with no more specific code; the target schema version was not committed and the recovery state is defined. |
+
+**Migration execution is host-controlled.** `executeMigration()` is a standalone function,
+not a `ServerRequest` branch — there is no path from a client through the semantic protocol
+that runs a migration (spec11 §73). It requires a `MigrationPrincipal` minted by the host
+with `migrationAuthority(grantedBy)`; a call without one is `MIGRATION_NOT_AUTHORIZED`.
+Destructive operations additionally require each operation id in `approveDestructive`
+(spec11 §21) — "a migration exists" is never "the operator approved data loss", and an
+unapproved destructive migration performs **zero** writes (spec11 §106).
+
+**Which correctness layers apply during a migration** (spec11 §37-40). Only **schema
+conformance** — required fields present, identity present, declared field types — is checked,
+at the target-record boundary, before the new schema version is committed
+(`MIGRATION_VALIDATION_FAILED`). Entity `ConstraintDef`s are **not** evaluated during a
+migration: a valid migration may pass through representations that are not valid application
+states (spec11 §38), and the target record is what must be valid, expressed by the transform
+itself. `TransitionConstraintDef`s are **never** applied to historical-data migration — a
+migration is not a user edit and must not pretend to be one (spec11 §40). A host that needs
+a business invariant re-checked after a migration does so by starting the authority and
+running its own audit query.
 
 Two client-side codes belong to the boundary as well:
 
@@ -637,8 +679,10 @@ page plus the conformance fixtures.
 | `axiom.server.v3` | integrations, integration operations, events, triggers, and the `integration-query`/`integration-effect` operation kinds | 0.8.0 |
 | `axiom.server.v4` | `ActionDef.invocation.allowedSources` invocation-source restriction, and the structured effect-outcome envelope (`effectOutcomeEntity`, `EFFECT_ID_FIELD` and its sibling reserved fields) that every effect dispatch uses from 8.1 onward | 0.8.1 |
 | `axiom.server.v5` | `SubscriptionDef` and `StorageDef`, and the `blob-metadata`/`blob-commit`/`blob-delete` operation kinds — the inbound external-I/O direction and binary object storage | 0.9.0 |
+| `axiom.server.v6` | `QueryDef`, `RelationshipDef` and `ReadPolicyDef`, the `query` operation kind, and the `provider-record` location — the semantic data-access & query layer over large authoritative datasets | 0.10.0 |
+| `axiom.server.v7` | `MigrationDef` and the closed migration-operation vocabulary, plus the top-level `schemaVersion` and `schemaFingerprint` fields — semantic schema evolution over persisted canonical data | 0.11.0 |
 
-`SERVER_IR_CONTRACTS` enumerates all five, and is the single source of truth this table is
+`SERVER_IR_CONTRACTS` enumerates all seven, and is the single source of truth this table is
 tested against — `packages/demo/test/documentation.test.ts` fails if a contract in
 `SERVER_IR_CONTRACTS` has no row here, or a row here names a contract the code does not
 declare (spec 8.2 §7-8). The rules:
@@ -646,11 +690,12 @@ declare (spec 8.2 §7-8). The rules:
 - **A document declares the oldest contract that can carry it.** `compileToServerIR` computes the label from the vocabulary the document actually uses, so an application that uses nothing from 0.7 or 0.8 produces a byte-identical `axiom.server.v1` document, and the committed v1 conformance fixtures are unchanged. `usesV4Semantics` computes the v4 case specifically: an action's `invocation.allowedSources` genuinely restricting the default two-source set, or any `integration-operation` with `mode: 'effect'` (since every effect dispatch uses the structured v4 envelope) — a document that merely mentions `invocation` without restricting it only needs `axiom.server.v2`, the same tier `group`/`expression-ref` occupy.
 - **A runtime MUST refuse a contract it does not implement**, and MUST refuse a document whose vocabulary exceeds its declared contract. A v2 runtime executing a v1-labelled document that uses `group` would accept what a conforming v1 runtime elsewhere refuses, and the two would then disagree about the same file. `createAxiomServer` raises rather than executing one — including refusing a document that **understates** its own contract (`understatedContract`).
 - **A frozen contract gains nothing.** `axiom.server.v1` does not contain `group`, `expression-ref`, `expressionDefs`, an integration, a trigger, an event, the `integration-query`/`integration-effect` operation kinds, `invocation`, or the structured effect-outcome envelope, and `server-ir.v1.schema.json` is byte-frozen. Vocabulary arrives under a new identifier or not at all.
-- **`axiom.server.v5` is the latest contract as of 0.9.0** (`SERVER_IR_LATEST_CONTRACT`). `usesExternalIOVocabulary` computes it from the document: any `subscriptions`, any `storages`, or any of the three blob operation kinds. The reason it is an incompatible change rather than an additive one is exact — a v4 runtime that ignored `subscriptions` would start an application whose declared live event source never activates, and one that ignored a `blob-commit` would leave state referencing an object that stays staged forever. Both are silent divergence, which is what a contract label exists to prevent.
+- **`axiom.server.v6` is the latest contract as of 0.10.0** (`SERVER_IR_LATEST_CONTRACT`). `usesQueryVocabulary` computes it from the document: any `queries`, any `relationships`, any `readPolicies`, or any `query` operation. It is incompatible rather than additive for the same reason every prior tier is — a v5 runtime that ignored `queries` would accept an application that promises demand-driven, read-authorized, paginated access to a large dataset and silently execute none of it, and one that ignored a `provider-record` mutation would silently skip a canonical write. Both are the divergence a label exists to prevent.
 
 There is one JSON Schema per contract, each generated from the runtime's own vocabulary and
 each shipped: `server-ir.v1.schema.json`, `server-ir.v2.schema.json`, `server-ir.v3.schema.json`,
-`server-ir.v4.schema.json`, `server-ir.v5.schema.json`.
+`server-ir.v4.schema.json`, `server-ir.v5.schema.json`, `server-ir.v6.schema.json`,
+`server-ir.v7.schema.json`.
 
 **`SubscriptionDef`, `StorageDef` and the blob operations.** Their normative semantics —
 lifecycle states and transitions, at-least-once delivery, per-subscription ordering and the

package/docs/CONSTRAINTS.md

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

package/docs/EFFECTS.md

@@ -1,6 +1,6 @@
 # Effects
 
-Axiom 0.9.0-alpha.2. External effects are not rollback-capable state mutations. This file
+Axiom 0.11.0-alpha.1. 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.9.0-alpha.2. An event is a typed fact — something that happened — never work
+Axiom 0.11.0-alpha.1. 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.9.0-alpha.2. An expression describes **what value is computed**. It is a tree of
+Axiom 0.11.0-alpha.1. 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.
 
@@ -31,7 +31,7 @@ Three coercions decide most edge cases. They are shared by every kind.
 A collection is truthy only when non-empty. This is the one coercion most likely to
 surprise: use `count(...) > 0` when you mean "has members" and want it to read that way.
 
-**Text** (`concat`, `to-string`, `lowercase`, comparison of non-numbers, rendering):
+**Text** (`concat`, `to-string`, `lowercase`, `trim`, `substring-before`, `substring-after`, comparison of non-numbers, rendering):
 `null`/`undefined` → `''`; string → itself; number/boolean → `String(v)`; anything else →
 `JSON.stringify(v)`.
 
@@ -210,7 +210,7 @@ Validation: `UNKNOWN_EXPRESSION_DEF` for a reference to something that is not on
 
 ## Built-in functions
 
-14 names, enumerated by `BUILTIN_FUNCTIONS`. `AGGREGATE_FUNCTIONS` lists those that reduce
+17 names, enumerated by `BUILTIN_FUNCTIONS`. `AGGREGATE_FUNCTIONS` lists those that reduce
 a collection of numbers (`sum`).
 
 | Function | Arity | Input | Output | Notes |
@@ -227,6 +227,9 @@ a collection of numbers (`sum`).
 | `sum` | 1 | `Collection<number>` | `number` | **Fails on `null`, and on any non-finite or non-numeric member.** `[]` → `0`. |
 | `lowercase` | 1 | any | `string` | Text form, lower-cased. |
 | `to-string` | 1 | any | `string` | Text form. |
+| `trim` | 1 | any | `string` | Text form with leading/trailing whitespace removed. |
+| `substring-before` | 2 | text, separator | `string` | Text before the first occurrence of `separator`; the whole string if it does not occur (empty separator → whole string). |
+| `substring-after` | 2 | text, separator | `string` | Text after the first occurrence of `separator`; `''` if it does not occur. |
 | `now` | 0 | — | `string` | ISO timestamp from the host. |
 | `uuid` | 0 | — | `string` | Identifier from the host. |
 

package/docs/GRAPH_MODEL.md

@@ -1,6 +1,6 @@
 # Graph model
 
-Axiom 0.9.0-alpha.2. The `ApplicationGraph` is the authoritative representation of an
+Axiom 0.11.0-alpha.1. 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.9.0-alpha.2. How an application declares and calls an external system, without
+Axiom 0.11.0-alpha.1. 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/LOCATIONS.md

@@ -1,6 +1,6 @@
 # Locations
 
-Axiom 0.9.0-alpha.2.
+Axiom 0.11.0-alpha.1.
 
 ```text
 Expression = a value