@cynodia/axiom 0.13.0-alpha.1 → 0.14.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.13.0-alpha.1`.
+documentation in `docs/` describes this exact version, `0.14.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.13.0-alpha.1`.
+`npm install @cynodia/axiom@0.14.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
@@ -193,6 +193,7 @@ focused document when the reference is not specific enough for the question at h
 | Evolving a deployed schema: `MigrationDef`, fingerprint, the startup gate, `executeMigration`, providers | [`docs/MIGRATIONS.md`](docs/MIGRATIONS.md) |
 | Running N authority processes at once: ownership, leases, fencing, delivery guarantees, version skew | [`docs/DISTRIBUTED_AUTHORITY.md`](docs/DISTRIBUTED_AUTHORITY.md) |
 | Observing a `QueryDef` result over time: live deltas, reconnect, cursor, backpressure, transport | [`docs/LIVE_QUERIES.md`](docs/LIVE_QUERIES.md) |
+| Durable workflows: steps, bindings, event waits, timers, retries, cancellation, crash recovery | [`docs/WORKFLOWS.md`](docs/WORKFLOWS.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.13.0-alpha.1. An action is behavior expressed as data, executed as a transaction.
+Axiom 0.14.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.13.0-alpha.1. The machine-facing interface. Agents query semantics and apply
+Axiom 0.14.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.13.0-alpha.1. Compressed operational contract. Read this plus the `.d.ts`
+Axiom 0.14.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:
@@ -730,7 +730,8 @@ Portable artifacts, for a runtime written in another language:
 @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
 @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/server-ir.v7.schema.json JSON Schema for axiom.server.v7
+@cynodia/axiom-server/schema/server-ir.v8.schema.json JSON Schema for axiom.server.v8 (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)
@@ -1069,12 +1070,27 @@ insert/remove above. `insert`/`move` carry a target index into the final result.
 conformance oracle.
 
 Invalidation: conservative static dependency set (`queryDependencies`) — source entity, used
-relationship endpoints, read-policy entity, `StateDef`s read by any clause or the policy
-predicate; an unresolved `ref` → `broad` (re-evaluate on every commit). Local commits wake
-the engine synchronously; a **remote** commit is seen via `persistence.revision()` re-observed
-on an interval (`liveQueryPollMs`, default 250). No broadcast, no sticky routing. A
-non-Axiom write to the provider store is not observed until the next Axiom commit
-(documented limit).
+relationship endpoints, read-policy entity; an unresolved `ref` → `broad` (re-evaluate on
+every commit). Local commits wake the engine synchronously; a **remote** commit — a
+`StateDef` *or* a `provider-record` mutation — is seen through the **observable application
+revision**, projected from two durable sources re-observed on an interval (`liveQueryPollMs`,
+default 250): `stateRevision` (`persistence.revision()`, StateDef commits) and
+`dataGeneration` (Σ of each provider's `observedMutationGeneration()`, advanced **atomically
+inside `applyMutations`**). `server.revisionInspection()` → `{ applicationRevision,
+stateRevision, dataGeneration }` (kept distinct). No broadcast, no sticky routing, no Redis.
+Every `provider-record` mutation committed through an Axiom `ActionDef` (insert / update /
+delete) participates — a `StateDef` "sync pulse" is **not** required. A non-Axiom write
+straight to the provider store is not observed until the next Axiom commit (documented
+limit). `DataProvider.capabilities.mutationObservation` = `'durable'` (SQLite) /
+`'in-process'` (memory) / `'none'`; `openLiveQuery` on a writable `'none'` provider is
+refused `LIVE_QUERY_PROVIDER_NOT_OBSERVABLE`.
+
+QueryDef scope: a query clause (and a `ReadPolicy` predicate) may reference `ref(rowScopeId)`
+/ parameters / relationship binds / `PRINCIPAL` / nested iteration scopes — **not** a
+`StateDef`. A `StateDef` ref is `QUERY_STATE_REF_NOT_ALLOWED` at `validateGraph` /
+`compileToServerIR`; `analyzeLiveQuery` → `not-live-capable` +
+`dependencies.unsupportedStateRefs`; runtime guards a hand-built IR. Bind a runtime-varying
+value as a query **parameter**.
 
 Authorization: `ReadPolicy` + principal bound into every re-evaluation; a row that becomes
 invisible leaves as `remove` / `reset`; unauthorized data never retained past one
@@ -1101,7 +1117,90 @@ Portable tier: `axiom.conformance.v7` (`conformance/live/`), `runLiveQueryConfor
 / `runLiveQueryConformanceSuite`. Server IR stays `axiom.server.v7`.
 
 Diagnostics: `LIVE_QUERY_NOT_CAPABLE` `LIVE_QUERY_CURSOR_INVALID`
-`LIVE_QUERY_CURSOR_INCOMPATIBLE` `LIVE_QUERY_EVALUATION_FAILED`.
+`LIVE_QUERY_CURSOR_INCOMPATIBLE` `LIVE_QUERY_EVALUATION_FAILED`
+`LIVE_QUERY_PROVIDER_NOT_OBSERVABLE` `QUERY_STATE_REF_NOT_ALLOWED`.
+
+## DURABLE WORKFLOWS
+
+Full model: [`WORKFLOWS.md`](WORKFLOWS.md).
+
+A `WorkflowDef` (graph node kind `workflow`) is a long-running semantic computation with a
+**durable control position** — not a background promise, a persisted callback, a job-queue
+entry, a cron task, a mutable JSON blob or a process-local listener. No application script
+body. Server IR `axiom.server.v8`; a graph with no workflow compiles to the byte-identical
+v1–v7 it always did and its `semanticFingerprint` is unchanged.
+
+Steps (six, portable): `action` (invoke an `ActionDef` under the workflow principal;
+`onError` edge; `retry` policy), `wait-event` (wait for a matching canonical `EventDef`;
+`where` predicate, `bind` → single-assignment bindings, `timeout` + `onTimeout`), `timer`
+(`after: {seconds}` / `at: Expression`, target captured once), `branch` (deterministic
+`when` → `then`/`else`), `complete` (→ `completed`, `output`), `fail` (→ `failed`, `error`).
+Acyclic — `validateGraph` rejects a control-flow cycle.
+
+Expression scope (closed): `ref(<input id>)`, `ref(<binding id>)`, `ref('EVENT')` (only in a
+`wait-event` `where`/`bind`), `ref('PRINCIPAL')`. **Not** a `StateDef`
+(`WORKFLOW_EXPRESSION_SCOPE`), **not** a `QueryDef`, **not** `now`/`uuid`/`random`
+(`WORKFLOW_NONDETERMINISTIC`). Model dynamic state as an `ActionDef` before a branch.
+
+Start: `server.startWorkflow({ workflowId, arguments, credential, idempotencyKey })` →
+`{ instanceId, status }`. Idempotent on `(workflowId, principalFingerprint, idempotencyKey,
+compatibilityFingerprint)` — a retry after a lost response is one logical instance. The
+principal is bound; every action step runs as it and re-evaluates current authorization.
+
+Identity: `instanceRevision` (monotone durable) + a coordination `fence` — every transition
+is a CAS `R + fence → R+1`, atomic, check *inside* the write transaction. `activationId` =
+`"<stepId>#0"` (a future loop feature revisits without changing instance identity). Action
+invocation identity = `"<instanceId>/<activationId>"`, used as the `ActionDef` request id so
+a crash between "action committed" and "transition recorded" reconciles rather than
+double-executing. **Exactly-once logical transition** per activation; **not** exactly-once
+physical effect execution (effect system governs that; logical effect identity is stable
+across workflow retries).
+
+Event waits: the durable wait registration (`eventId`, correlation, `sinceEventSeq`) commits
+in the *same* transition — no "waiting then subscribe" gap. Driven by Axiom's single inbound
+event pipeline; startup/failover replays a match that landed in a crash window from
+`sinceEventSeq`; existing dedup means a wait transitions at most once; fanout (a match
+unblocks every independently-matching instance, never global consume). Event vs timeout:
+exactly one wins on `instanceRevision`.
+
+Timers: target instant computed once on activation and stored — a restart does not
+recompute `now + after`. Physically at-least-once firing, logically exactly-once transition.
+The waiting row *is* the timer.
+
+Retries: `retry: { maxAttempts, initialDelaySeconds, backoffMultiplier, maxDelaySeconds }`.
+Retryable vs terminal is structured, never message-string parsing. Attempt count +
+`nextEligibleAt` are durable (authority death does not reset). Lease/fencing → one current
+executor.
+
+Cancellation: `server.cancelWorkflow(instanceId, credential)` — idempotent, a fenced durable
+transition to `cancelled`. **Not** rollback (committed actions / dispatched effects stand;
+no auto-compensation). A later timer/event does not transition a terminal instance. Terminal
+states are durable and irreversible; a stale authority cannot resurrect one.
+
+Multi-authority: leaderless. Any compatible authority advances any eligible instance;
+per-instance lease+fence (reused 0.12 `CoordinationProvider`); stale owner refused. Startup
+discovers runnable / retry-due / timer-due / recoverably-waiting instances and advances them
+— the application does **not** scan stuck workflows, call `resumeWorkflow`, or re-register
+timers/waits. Same logical outcome at 1 or N authorities. Incompatible build refuses to
+advance an instance (fail-closed).
+
+Inspection: `server.getWorkflow(instanceId)` / `inspectWorkflows(limit)` — `status`,
+`currentStepId`, `activationId`, `attempt`, `waitingReason`, `nextEligibleAt`,
+`instanceRevision`, `failure`, `output` (no secrets). `server.workflowHistory(instanceId)`
+— the durable transition log. `AgentAPI.analyzeWorkflow(workflowId)` — static: inputs, steps
++ edges, action/event dependencies, terminal outcomes, acyclicity, possible wait reasons.
+
+`WorkflowStore`: `createMemoryWorkflowStore()` (single process), `createSqliteWorkflowStore({
+location })` (cross-process — `BEGIN IMMEDIATE`, check inside the transaction, `busy_timeout`,
+`CREATE TABLE IF NOT EXISTS` + `INSERT OR IGNORE` init). Portable tier
+`axiom.conformance.v8` (`conformance/workflow/`), `runWorkflowConformanceFixture` / `Suite`.
+
+Diagnostics (validation): `WORKFLOW_ENTRY_NOT_FOUND` `WORKFLOW_STEP_NOT_FOUND`
+`WORKFLOW_DUPLICATE_STEP_ID` `WORKFLOW_INVALID_STEP` `WORKFLOW_CYCLE_NOT_ALLOWED`
+`WORKFLOW_ACTION_NOT_FOUND` `WORKFLOW_EVENT_NOT_FOUND` `WORKFLOW_BINDING_NOT_FOUND`
+`WORKFLOW_DUPLICATE_BINDING` `WORKFLOW_INVALID_RETRY_POLICY` `WORKFLOW_INVALID_TIMER`
+`WORKFLOW_UNREACHABLE_STEP` `WORKFLOW_NO_TERMINAL` `WORKFLOW_EXPRESSION_SCOPE`
+`WORKFLOW_NONDETERMINISTIC`.
 
 ## Metadata classes
 

package/docs/ANTI_PATTERNS.md

@@ -1,6 +1,6 @@
 # Anti-patterns
 
-Axiom 0.13.0-alpha.1. Each of these compiles. Each is wrong. Each is followed by the correct
+Axiom 0.14.0-alpha.1. Each of these compiles. Each is wrong. Each is followed by the correct
 alternative.
 
 ## 1. Field names as entity runtime keys
@@ -908,3 +908,141 @@ A `QueryDef` whose filter / sort / projection reads a nondeterministic builtin i
 changed" has no meaning, and `openLiveQuery` returns `LIVE_QUERY_NOT_CAPABLE`. Express the
 window as a bound parameter (`ref(P_SINCE)`), or observe a status field that an action or a
 scheduled trigger maintains, and let *that* commit drive the live query.
+
+## 69. Assuming a provider-record commit only needs to wake the *local* live-query engine
+
+```ts
+// WRONG (the shape of the defect the 0.13.1 hardening fixed) — mutate provider data and rely on the
+// authority that did the write to notice.
+{ kind: 'set', target: providerRecordFieldLocation(E_ORDER, F_ID, ref(P_ID), F_STATUS), value: literal('shipped') }
+// … a live query served from a *different* authority never re-evaluates.
+```
+
+Why wrong: a `provider-record` mutation touches the `DataProvider`, not the
+`PersistenceAdapter`, so `persistence.revision()` does not move and a remote authority's
+poll sees nothing. A committed change stays permanently invisible where it is not observed,
+and the live result then depends on *which* authority happens to serve the query — a
+topology-dependent meaning.
+
+The framework closes this: the SQLite provider advances a durable `mutationGeneration`
+**inside** the same `applyMutations` transaction, and every authority's live-query poll
+re-reads it alongside `persistence.revision()`. There is nothing for the application to do —
+no revision bump, no `StateDef` "sync pulse", no broadcast. If your own custom `DataProvider`
+supports writes, it MUST implement `observedMutationGeneration()` (advanced atomically with
+`applyMutations`) or declare `mutationObservation: 'none'` and accept that
+`openLiveQuery` is refused for it.
+
+## 70. Bumping a `StateDef` counter so a provider-record change "syncs"
+
+```ts
+// WRONG — the audit counter is load-bearing for correctness, which it must never be.
+operations: [
+  { kind: 'set', target: providerRecordFieldLocation(E_ORDER, F_ID, ref(P_ID), F_STATUS), value: ref(P_STATUS) },
+  { kind: 'set', target: stateLocation(S_OPS), value: binary('add', ref(S_OPS), literal(1)) }, // "so remote live queries wake"
+]
+```
+
+Why wrong: it works by accident — the `StateDef` write moves `persistence.revision()`, which
+the poll observes — and it fails the moment an action legitimately mutates only provider
+records. Live-query invalidation observes the *provider's* durable generation directly; a
+provider-record-only action is fully observable on its own. Write the `StateDef` only if the
+application actually needs it.
+
+## 71. Referencing a `StateDef` from a `QueryDef` filter
+
+```ts
+// WRONG — `QUERY_STATE_REF_NOT_ALLOWED` at validateGraph / compileToServerIR.
+{
+  id: Q_LARGE_ORDERS, kind: 'query', source: E_ORDER, rowScopeId: ROW,
+  filter: binary('gte', field(ref(ROW), F_TOTAL), ref(S_THRESHOLD)),   // S_THRESHOLD is a StateDef
+}
+```
+
+Why wrong: a `QueryDef` clause is evaluated **by the `DataProvider`**, whose scope has no
+authority state — `ref(S_THRESHOLD)` would resolve to nothing and the query would silently
+return an empty (or wrong) result. Before 0.13.1, `validateGraph` accepted this,
+`queryDependencies` advertised the "dependency", and only execution disagreed. Now every
+layer rejects it consistently. Bind the threshold as a **query parameter** and pass it from
+the action, trigger or client that runs the query. (A `ReadPolicyDef` predicate shares the
+same state-free scope and the same rule.)
+
+## 72. A hand-rolled workflow state machine on top of `StateDef` + triggers + counters
+
+```ts
+// WRONG — semantic escape: the application reimplements durable orchestration.
+{ id: S_ORDER_STAGE, kind: 'state', authority: 'server', valueType: enumType(['reserving','awaiting_payment','shipping','done']) }
+// + a scheduler job to time out payment
+// + an event handler that flips the stage
+// + a manual retry counter field
+// + a "leader" flag so only one process advances it
+```
+
+Why wrong: every one of those pieces — state field, scheduler, event handler, retry counter,
+idempotency key, crash recovery, leader election — is orchestration infrastructure the
+framework already owns. Model it as a `WorkflowDef`: an `action` step, a `wait-event` step
+with a `timeout`, a `branch`, `complete` / `fail`. Exactly-once logical transition, no
+registration gap, durable retries, fenced ownership and crash recovery come for free.
+
+## 73. Generating your own job / activation ids
+
+```ts
+// WRONG — a random id per attempt makes a crash-recovered retry look like new work.
+const jobId = crypto.randomUUID();
+await chargeCard({ idempotencyKey: jobId });
+```
+
+Why wrong: a workflow action step already executes with a stable logical invocation identity
+(`<instanceId>/<activationId>`), reused across retries and across authority failover, and an
+effect it dispatches keeps a stable logical effect identity. Rolling your own id breaks
+double-execution reconciliation — the reclaiming authority cannot tell the action already
+committed.
+
+## 74. A process timer (`setTimeout` / cron) for a workflow wait
+
+```ts
+// WRONG — the wait is not durable; a crash loses it.
+setTimeout(() => advanceWorkflow(id), 7 * 24 * 3600 * 1000);
+```
+
+Why wrong: a `timer` step's target instant is captured once and stored in the durable
+transition record; the waiting row *is* the timer, rediscovered on startup. A `setTimeout`
+evaporates on restart, and a `now + delay` recomputed after a crash silently extends the
+wait.
+
+## 75. Subscribing to an event emitter *after* marking the workflow "waiting"
+
+```ts
+// WRONG — a crash between these two lines loses a matching event forever.
+await store.setStatus(id, 'waiting');
+emitter.on('payment_confirmed', () => resumeWorkflow(id));
+```
+
+Why wrong: the durable event-wait registration commits in the **same** transaction as the
+transition into the `wait-event` step, and a match that lands during a crash window is
+replayed from the durable `sinceEventSeq`. There is no in-memory-only registration window.
+
+## 76. Treating `cancelWorkflow` as an undo
+
+```ts
+// WRONG — cancellation does not reverse anything.
+await server.cancelWorkflow(id);   // "and now the charge is refunded and inventory released"
+```
+
+Why wrong: cancellation means *do not execute future steps*. It does not undo committed
+actions or dispatched external effects, and 0.14 has no automatic compensation. If a
+workflow needs to release a reservation on a timeout, that is an explicit `onTimeout` edge to
+a `release_inventory` action step.
+
+## 77. Sticky routing / a workflow leader / polling the workflow table
+
+```ts
+// WRONG — none of this is needed and all of it is fragile.
+route(`/wf/${id}`, toAuthority(ownerOf(id)));            // sticky routing
+if (isLeader) { for (const w of loadAllWorkflows()) advance(w); }  // leader + full scan
+setInterval(() => sql`SELECT * FROM workflows WHERE stuck = 1`, 1000);  // app polling
+```
+
+Why wrong: workflow execution is leaderless — any compatible authority advances any eligible
+instance under a fenced per-instance lease. Recovery discovery is bounded and indexed and
+runs on startup automatically. Reading status is safe through any authority. The application
+writes none of this.

package/docs/AUTHORITY.md

@@ -1,6 +1,6 @@
 # Authority
 
-Axiom 0.13.0-alpha.1. How an application crosses the trust boundary.
+Axiom 0.14.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
@@ -298,6 +298,7 @@ interface PersistenceAdapter {
 - A semantic transaction that writes several states MUST persist as **one unit**. An adapter must never apply a subset.
 - `commit` carries the revision each written state had when the transaction began. A mismatch MUST refuse the commit rather than overwrite.
 - Derived state is recomputed, never stored.
+- `commit` may also carry an optional `idempotency: { key, response, window }` written in the **same** transaction as the state (spec14pt2 F1); an adapter that also implements the optional `loadIdempotentResponse` / `recordIdempotentResponse` pair gives cross-restart, cross-authority exactly-once for a workflow's ActionDef step. `createMemoryPersistence` and `createSqlitePersistence` both do; an adapter that does not leaves that reconciliation to the (memory-only) request window, which is documented rather than assumed away.
 
 | Adapter | For |
 | --- | --- |
@@ -497,6 +498,8 @@ does for a local failure.
 | `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`). |
+| `QUERY_STATE_REF_NOT_ALLOWED` | A `QueryDef` clause or a `ReadPolicyDef` predicate references a `StateDef`. A query executes on the `DataProvider`, which binds no authority state, so the reference would evaluate to nothing. `compileToServerIR` rejects such a graph; this is the runtime guard if a hand-built IR bypasses validation (spec13.1 F2, §81). Bind a runtime-varying value through a query parameter. |
+| `LIVE_QUERY_PROVIDER_NOT_OBSERVABLE` | `openLiveQuery` for a query whose writable `DataProvider` reports `capabilities.mutationObservation === 'none'` — its committed mutations cannot be made observable to another authority, so a distributed live query is refused rather than served silently stale on a peer (spec13.1 F1, §33, §123). |
 | `LIVE_QUERY_NOT_CAPABLE` | `openLiveQuery` was called for a `QueryDef` that cannot be observed live — its filter / sort / projection reads a nondeterministic builtin (`now`, `uuid`). An aggregate or grouped query is *not* refused here: it is served live as whole-result `reset`s (spec13 §145, §146, §148). |
 | `LIVE_QUERY_CURSOR_INVALID` | An `axiom.live-query-cursor.v1` was tampered with, unsigned, or minted for a different query / principal / arguments / read policy. Fail-closed: continuing from it is refused and nothing is disclosed (spec13 §33-§35). |
 | `LIVE_QUERY_CURSOR_INCOMPATIBLE` | A live-query cursor was minted by an authority whose schema fingerprint, semantic fingerprint or server contract differs from this one's — the same fail-closed compatibility check the distributed work store applies. A presentation-only graph change does *not* trigger this (spec13 §79-§82). |
@@ -687,8 +690,9 @@ page plus the conformance fixtures.
 | `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 |
+| `axiom.server.v8` | `WorkflowDef` and the closed workflow-step vocabulary (`action`, `wait-event`, `timer`, `branch`, `complete`, `fail`) — durable, portable long-running orchestration | 0.14.0 |
 
-`SERVER_IR_CONTRACTS` enumerates all seven, and is the single source of truth this table is
+`SERVER_IR_CONTRACTS` enumerates all eight, 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:

package/docs/CONSTRAINTS.md

@@ -1,6 +1,6 @@
 # Constraints
 
-Axiom 0.13.0-alpha.1. Two constructs, answering different questions. They are not
+Axiom 0.14.0-alpha.1. 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.13.0-alpha.1`.*
+*This document describes Axiom `0.14.0-alpha.1`.*
 
 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.13.0-alpha.1. External effects are not rollback-capable state mutations. This file
+Axiom 0.14.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.13.0-alpha.1. An event is a typed fact — something that happened — never work
+Axiom 0.14.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.13.0-alpha.1. An expression describes **what value is computed**. It is a tree of
+Axiom 0.14.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.
 

package/docs/GRAPH_MODEL.md

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

@@ -1,6 +1,6 @@
 # Realtime — live canonical queries
 
-Axiom 0.13.0-alpha.1. The operational contract for **observing a `QueryDef` result over
+Axiom 0.14.0-alpha.1. 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).
@@ -111,20 +111,70 @@ the incremental changes is still correct, just chattier.
 
 A committed change wakes a live subscription when it may have moved that query's result. The
 dependency set is **conservative and static** (`queryDependencies`): the source entity,
-every entity a used relationship reaches, every entity a read policy governs, and every
-`StateDef` a query clause or the effective `ReadPolicy` predicate reads. A `ref` that cannot
-be resolved to a state, parameter, principal or iteration scope sets `broad` — that
-subscription re-evaluates on **every** commit. False negatives are forbidden: a missed
-invalidation is a release blocker; a redundant one only costs a re-evaluation that produces
-no client message.
-
-Local commits wake the engine synchronously. A commit made on **another authority** is
-observed through the shared durable revision: an authority serving live queries re-reads
-`persistence.revision()` on an interval (`AxiomServerOptions.liveQueryPollMs`, default 250;
-`0` disables it) and, on an advance it has not already processed, re-evaluates every live
-subscription. There is no broadcast, no pub/sub and no sticky routing. A change written
-directly to a provider's store **outside** an Axiom transaction does not advance the durable
-revision and is not observed until the next Axiom commit — this is a documented limitation.
+every entity a used relationship reaches, and every entity a read policy governs. A `ref`
+that cannot be resolved to a parameter, principal, relationship bind or iteration scope sets
+`broad` — that subscription re-evaluates on **every** commit. False negatives are forbidden:
+a missed invalidation is a release blocker; a redundant one only costs a re-evaluation that
+produces no client message. (A `QueryDef` clause cannot reference a `StateDef` — see
+[QueryDef expression scope](#querydef-expression-scope) — so there is no `StateDef`
+dependency for a query.)
+
+### The observable application revision
+
+Every committed **Axiom** mutation that can change canonical query meaning becomes
+observable to every compatible authority, **regardless of which persistence surface it
+touched** — a `StateDef` write, a `provider-record` write, or both. This is projected from
+two durable sources:
+
+| Source | Advanced by | Read with |
+| --- | --- | --- |
+| `stateRevision` | a committed `StateDef` write (`PersistenceAdapter`) | `server.revisionInspection().stateRevision` |
+| `dataGeneration` | a committed `applyMutations` batch, advanced **atomically inside the provider's write transaction** | `server.revisionInspection().dataGeneration` |
+
+`server.revisionInspection().applicationRevision` is this authority's local monotone count of
+distinct observed application-meaning changes, projected from both. It is not comparable
+across authorities, and nothing compares it across authorities.
+
+Local commits wake the engine synchronously. A commit made on **another authority** — a
+`StateDef` *or* a `provider-record` commit — is observed by the idle-authority poll: an
+authority serving live queries re-reads *both* durable sources on an interval
+(`AxiomServerOptions.liveQueryPollMs`, default 250; `0` disables it) and, on an advance it
+has not already folded in, re-evaluates every live subscription. There is no broadcast, no
+pub/sub and no sticky routing.
+
+Because a provider commit and its `dataGeneration` advance are one atomic transaction, a
+writer that crashes the instant after the commit returns leaves the change **and** its
+observable evidence both durable — a newly started authority reads the current
+`dataGeneration` and serves the correct result.
+
+**In scope:** every `provider-record` mutation committed through a canonical Axiom
+`ActionDef` (create, update, delete). **Out of scope:** a write made directly to a
+provider's store *outside* an Axiom transaction — it does not advance `dataGeneration` and
+is not observed until the next Axiom commit, unless the provider explicitly advertises
+external-change observation.
+
+### Provider capability
+
+`DataProvider.capabilities.mutationObservation` is `'durable'` (the SQLite reference — a
+generation any authority sharing the store can read), `'in-process'` (the memory reference —
+single process only), or `'none'`. `openLiveQuery` for a query whose **writable** provider
+reports `'none'` is refused with `LIVE_QUERY_PROVIDER_NOT_OBSERVABLE` rather than served
+silently stale on a peer. A custom provider implements `observedMutationGeneration(): Promise<number>`
+— a monotone counter advanced atomically with `applyMutations` — to support distributed live
+queries.
+
+## QueryDef expression scope
+
+A `QueryDef` clause (`filter`, `sort`, `projection`, `groupBy`, `aggregate`) is evaluated
+**by the `DataProvider`**, whose scope is: `ref(rowScopeId)`, `ref(<parameter id>)`,
+`ref(<relationship bindAs>)`, `PRINCIPAL`, and any nested iteration-scope id introduced
+inside a clause. It is **not** a `StateDef`. A `ref` to a `StateDef` in any query clause —
+or in a `ReadPolicyDef` predicate, which shares this scope — is a validation error
+(`QUERY_STATE_REF_NOT_ALLOWED`): `validateGraph` / `compileToServerIR` reject it,
+`analyzeLiveQuery` reports `not-live-capable` with the offending ref in
+`dependencies.unsupportedStateRefs`, and the runtime guards against a hand-built IR that
+bypasses validation. Bind a runtime-varying value (a threshold, a cutoff) as a **query
+parameter** and pass it from the action or trigger that opens the query.
 
 ---
 
@@ -223,6 +273,8 @@ transport prefers.
 | Code | When |
 | --- | --- |
 | `LIVE_QUERY_NOT_CAPABLE` | `openLiveQuery` for a `QueryDef` that reads `now` / `uuid`. |
+| `QUERY_STATE_REF_NOT_ALLOWED` | A `QueryDef` clause or `ReadPolicy` predicate references a `StateDef` (rejected at compile; this is the runtime guard for a hand-built IR). |
+| `LIVE_QUERY_PROVIDER_NOT_OBSERVABLE` | `openLiveQuery` for a query whose writable provider cannot make committed mutations observable across authorities (`mutationObservation: 'none'`). |
 | `LIVE_QUERY_CURSOR_INVALID` | A resume cursor that is tampered, unsigned, or minted for a different query / principal / arguments / policy. |
 | `LIVE_QUERY_CURSOR_INCOMPATIBLE` | A resume cursor minted under an incompatible schema / semantic build. |
 | `LIVE_QUERY_EVALUATION_FAILED` | Re-evaluating against the `DataProvider` failed; delivered as an `{ kind: 'error' }` message, last result stands. |

package/docs/LOCATIONS.md

@@ -1,6 +1,6 @@
 # Locations
 
-Axiom 0.13.0-alpha.1.
+Axiom 0.14.0-alpha.1.
 
 ```text
 Expression = a value

package/docs/MIGRATIONS.md

@@ -1,6 +1,6 @@
 # Schema evolution & semantic migrations
 
-Axiom 0.13.0-alpha.1. The operational contract for evolving a deployed application's
+Axiom 0.14.0-alpha.1. 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.13.0-alpha.1. Presentation is **semantic UX intent**, expressed as data on a UI
+Axiom 0.14.0-alpha.1. 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.13.0-alpha.1. The operational contract for demand-driven reads over authoritative
+Axiom 0.14.0-alpha.1. 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`.
 
@@ -58,6 +58,12 @@ Operators reuse `Expression` semantics: `binary('eq' | 'neq' | 'lt' | 'lte' | 'g
 | 'and' | 'or', …)`, `unary('not', …)`, and the `contains` built-in for substring/membership.
 There is one comparison language, not two.
 
+**Expression scope.** Every `QueryDef` clause (and a `ReadPolicyDef` predicate) is evaluated
+by the `DataProvider`. In scope: `ref(rowScopeId)`, `ref(<parameter id>)`, `ref(<relationship
+bindAs>)`, `PRINCIPAL`, and nested iteration scopes. **Not** a `StateDef` — the provider
+binds no authority state, so `ref(<state id>)` in a query clause is rejected
+(`QUERY_STATE_REF_NOT_ALLOWED`). Pass a runtime-varying value as a query parameter.
+
 ### Null semantics (frozen)
 
 | Situation | Behaviour |

package/docs/RUNTIME.md

@@ -1,6 +1,6 @@
 # Runtime
 
-Axiom 0.13.0-alpha.1. The runtime executes an `ApplicationIR`. It is domain-independent: it
+Axiom 0.14.0-alpha.1. 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.13.0-alpha.1. Runtime guarantees, stated formally. This file defines behavior; it
+Axiom 0.14.0-alpha.1. 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.13.0-alpha.1. A `StateDef` is a named application value: stored, or computed from
+Axiom 0.14.0-alpha.1. 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.13.0-alpha.1. How an application stores, references, serves and deletes binary data —
+Axiom 0.14.0-alpha.1. 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.13.0-alpha.1. How an application receives a stream of external events — an MQTT
+Axiom 0.14.0-alpha.1. 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.13.0-alpha.1. A `TriggerDef` says **when** an action should be invoked, without
+Axiom 0.14.0-alpha.1. 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.13.0-alpha.1. Eleven semantic UI node kinds describe **what exists and what it does**.
+Axiom 0.14.0-alpha.1. 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.13.0-alpha.1. Validation is authoring-time structural checking. It is not the same
+Axiom 0.14.0-alpha.1. 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.
 
@@ -36,7 +36,7 @@ non-numeric collections, and obviously incompatible assignments.
 
 ## Codes
 
-105 codes, exported as `VALIDATION_CODES`. Every one is reachable.
+121 codes, exported as `VALIDATION_CODES`. Every one is reachable.
 
 ### Ids and references
 
@@ -161,6 +161,7 @@ execute rather than letting it validate and then fail at the provider (spec 0.10
 | `INVALID_READ_POLICY` | A `ReadPolicyDef` with a non-boolean predicate, a missing entity, or a colliding row scope; also a query whose `readPolicyId` governs a different entity than the query's `source`. |
 | `DUPLICATE_READ_POLICY` | More than one `ReadPolicyDef` governing the same entity — the effective filter would depend on which the compiler picked. |
 | `INVALID_QUERY_PREDICATE` | A `QueryDef.filter` that is not a boolean expression. |
+| `QUERY_STATE_REF_NOT_ALLOWED` | A `QueryDef` clause (`filter`, `sort`, `projection`, `groupBy`, `aggregate`) or a `ReadPolicyDef` predicate references a `StateDef`. A query executes on the `DataProvider`, which binds no authority state, so the reference would evaluate to nothing at run time. Bind a runtime-varying value through a query parameter instead. |
 | `INVALID_QUERY_SORT` | A `QuerySortKey` whose projected key is not an orderable type (`string`, `number`, `boolean`, `date`, `datetime`, `enum`). |
 | `INVALID_QUERY_PROJECTION` | A projected field that is not on the projection entity, or whose value type is incompatible with the declared field type. |
 | `INVALID_QUERY_AGGREGATE` | A `sum`/`average` aggregate over a non-numeric key, a `min`/`max` over an unorderable key, a `count` that carries a key, or an aggregate with no result field. |
@@ -190,6 +191,30 @@ connect schema 1 to it. A migration transform reads the old record through the r
 | `MIGRATION_TRANSFORM_IMPURE` | A migration transform expression that calls `now` or `uuid`, or reads a scope other than the old record (`MIGRATION_OLD_SCOPE`) and the operation's declared constants (spec11 §25, §26). |
 | `MIGRATION_TRANSFORM_TYPE_MISMATCH` | A `transform-field` whose declared `toType` does not match the field's type in the target schema (spec11 §77). |
 
+### Durable workflows (0.14)
+
+`validateGraph` rejects an internally inconsistent `WorkflowDef` before it can be compiled
+to `axiom.server.v8` or executed. Every failure is a structured diagnostic — never a thrown
+`TypeError` on a malformed step.
+
+| Code | Raised when |
+| --- | --- |
+| `WORKFLOW_ENTRY_NOT_FOUND` | `WorkflowDef.entry` does not name a step of that workflow. |
+| `WORKFLOW_STEP_NOT_FOUND` | A control-flow edge (`next` / `onError` / `then` / `else` / `onTimeout`) or a binding's `producedBy` names a step that does not exist. |
+| `WORKFLOW_DUPLICATE_STEP_ID` | Two steps in one workflow share an id, or a step id collides with a graph node id. |
+| `WORKFLOW_INVALID_STEP` | A step with no id, or a `type` outside the six (`action`, `wait-event`, `timer`, `branch`, `complete`, `fail`). |
+| `WORKFLOW_CYCLE_NOT_ALLOWED` | The workflow control-flow graph contains a cycle. Retries are runtime policy, not graph edges. |
+| `WORKFLOW_ACTION_NOT_FOUND` | An `action` step references an `action` node that does not exist. |
+| `WORKFLOW_EVENT_NOT_FOUND` | A `wait-event` step references an `event` node that does not exist. |
+| `WORKFLOW_BINDING_NOT_FOUND` | A `bind` entry, or a `ref`, names a `WorkflowBinding` the workflow does not declare. |
+| `WORKFLOW_DUPLICATE_BINDING` | A binding is assigned by more than one step, or a `bind` targets a binding whose declared `producedBy` is a different step. |
+| `WORKFLOW_INVALID_RETRY_POLICY` | A `WorkflowRetryPolicy` with a non-positive `maxAttempts` / `initialDelaySeconds`, a `backoffMultiplier` below 1, or a `maxDelaySeconds` below `initialDelaySeconds`. |
+| `WORKFLOW_INVALID_TIMER` | A `timer` step with neither `after` nor `at`, with both, with a non-positive `after.seconds`, or a `wait-event` timeout that is non-positive. |
+| `WORKFLOW_UNREACHABLE_STEP` | A step not reachable from `entry` by control flow (an authoring mistake, so an error, not a warning). |
+| `WORKFLOW_NO_TERMINAL` | A reachable step from which no control-flow path can reach `complete` or `fail` (and which is not an intentional unbounded `wait-event`). |
+| `WORKFLOW_EXPRESSION_SCOPE` | A workflow expression references an id outside the workflow expression scope: `ref(<input id>)`, `ref(<binding id>)`, `ref('EVENT')` (only inside a `wait-event` `where` / `bind`), `ref('PRINCIPAL')`. Not a `StateDef`, not a `QueryDef`. |
+| `WORKFLOW_NONDETERMINISTIC` | A workflow expression calls `now` / `uuid` / `random`. Workflow decisions must be deterministic and replayable. |
+
 ### UI and routing
 
 | Code | Raised when | Severity |

package/docs/WORKFLOWS.md

@@ -0,0 +1,282 @@
+# Durable workflows
+
+Axiom 0.14.0-alpha.1. 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`.
+
+> The workflow graph owns durable orchestration meaning. The runtime owns scheduling,
+> persistence, retries, leases, fencing, crash recovery and physical execution.
+
+A durable workflow is **not** a background promise, a persisted callback, a job-queue entry,
+a cron task, a mutable JSON state blob, a process-local event listener, or a bag of retries.
+It is a `WorkflowDef` node: a closed step vocabulary and `Expression` trees over a closed
+scope. There is no application script body of any kind.
+
+---
+
+## `WorkflowDef`
+
+```ts
+interface WorkflowDef extends NodeBase {
+  kind: 'workflow';
+  inputs?: WorkflowInput[];      // { id, valueType: TypeRef, required?: boolean } — immutable after start
+  bindings?: WorkflowBinding[];  // { id, valueType, producedBy: <step id> } — single-assignment, read-only elsewhere
+  entry: NodeId;                 // the first step
+  steps: WorkflowStep[];
+}
+```
+
+Inputs use canonical portable value types only — no host objects, closures, file
+descriptors, sockets or class instances. Bindings replace a mutable workflow blob: each is
+assigned **once** by its producing step and only read afterwards, which is what keeps replay
+safe, static analysis strong and the model portable.
+
+### Step vocabulary — the six of 0.14
+
+| `type` | Fields | Meaning |
+| --- | --- | --- |
+| `action` | `action: NodeId`, `arguments?`, `next`, `onError?`, `retry?` | Invoke a canonical `ActionDef` under the workflow principal. |
+| `wait-event` | `event: NodeId`, `where?` (bool), `bind?` (→ binding ids), `next`, `timeout?`, `onTimeout?` | Wait for a matching canonical `EventDef` occurrence. |
+| `timer` | exactly one of `after: { seconds }` / `at: Expression`, `next` | Wait until a durable time. |
+| `branch` | `when` (bool), `then`, `else` | Deterministic edge choice over durable workflow context. |
+| `complete` | `output?` | Terminal → `completed`. |
+| `fail` | `error?` | Terminal → `failed`. |
+
+Deferred (a later release): `parallel`, `race`, `map`, `foreach`, child workflows,
+`wait-query`, human tasks, compensation / sagas, loops. The graph **should be acyclic**;
+`validateGraph` rejects a control-flow cycle (`WORKFLOW_CYCLE_NOT_ALLOWED`). Retries are
+runtime policy and are not graph edges.
+
+### Workflow expression scope
+
+Every workflow expression (an action argument, `wait-event.where` / `bind`, `branch.when`,
+`timer.at`, `complete.output`, `fail.error`) resolves against a **closed** scope:
+
+- `ref(<input id>)` — an immutable start input;
+- `ref(<binding id>)` — a durable single-assignment binding;
+- `ref('EVENT')` — the matched event payload, **only** inside a `wait-event` step's `where`
+  / `bind`;
+- `ref('PRINCIPAL')` — the bound workflow principal.
+
+**Not** a `StateDef` (`WORKFLOW_EXPRESSION_SCOPE`) — model dynamic application state as a
+canonical `ActionDef` *before* the branch. **Not** a `QueryDef` — a branch never hides a
+network/storage read. **Not** `now` / `uuid` / `random` (`WORKFLOW_NONDETERMINISTIC`) —
+workflow decisions must be replayable; time enters only through a `timer` step's
+captured-once target instant.
+
+---
+
+## Starting a workflow
+
+```ts
+const started = await server.startWorkflow({
+  workflowId, arguments, credential, idempotencyKey,
+});
+// { instanceId, status } | { error: { code, message } }
+```
+
+**Idempotent start.** `WorkflowStartIdentity = { workflowId, principalFingerprint,
+idempotencyKey, compatibilityFingerprint }`. Two `startWorkflow` calls with the same
+`(workflowId, principal, idempotencyKey)` return the **same** `instanceId` — a retry after a
+lost response is one logical instance, not two. Two different callers reusing the same
+textual key under different principals never collide. Omitting `idempotencyKey` starts a
+fresh instance every call.
+
+**Principal.** The canonical principal the workflow was started under is bound to the
+instance and every workflow-driven `ActionDef` executes as it — no authority-local service
+principal, no privilege escalation. Capturing the principal does not freeze authorization:
+each later action step re-evaluates current canonical authorization under that principal, and
+a step whose action is no longer authorized **fails semantically** (it follows `onError` if
+declared, else the workflow fails).
+
+---
+
+## Logical identity and exactly-once
+
+- **`instanceRevision`** — a monotone durable integer. Every logical transition is a fenced
+  compare-and-swap: `expected instanceRevision R + fence F → R+1`, atomically, with the
+  check *inside* the write transaction. This linearizes every race — event vs timeout,
+  cancel vs completion, two authorities on one step, stale owner vs new owner.
+- **`activationId`** — identifies *this arrival at this step*, distinct from the step id so a
+  future loop feature can revisit a step without changing instance identity. For 0.14
+  (acyclic) it is `"<stepId>#0"`.
+- **Action invocation identity** = `"<instanceId>/<activationId>"`. The workflow action step
+  invokes the `ActionDef` through the ordinary authority path with this as the idempotency
+  key. The authority commits a **durable idempotency record** in the *same* persistence
+  transaction as the ActionDef's state writes, so a crash between "action committed" and
+  "workflow transition recorded" — including a **full process restart** with no in-memory
+  state — is reconciled: a recovery authority proves the invocation already committed and
+  recovers its canonical outcome (`PersistenceAdapter.loadIdempotentResponse`) rather than
+  executing the action a second time. The record can never be present without the matching
+  durable state, and vice versa.
+- **Exactly-once logical transition** for each activated step is guaranteed.
+  **Exactly-once physical execution of an external effect is not** — that remains governed
+  by the effect system. The distinction is deliberate and load-bearing: an effect an action
+  dispatched from a workflow keeps a stable logical effect identity across workflow retries.
+
+---
+
+## Event waits — no gap
+
+When a workflow durably enters a `wait-event` step, the transition record **includes** the
+durable wait registration (`eventId`, correlation, `sinceEventSeq`, `activationId`),
+committed in the **same** transaction — there is no "state = waiting, then subscribe"
+window. Matching is driven by Axiom's single inbound event pipeline (the same one webhooks
+and effect outcomes use): every accepted event is offered to matching waits whose `where`
+predicate the payload satisfies. Every accepted event is first appended to a **durable
+`WorkflowStore` journal** with a store-global monotone `seq`; `sinceEventSeq` is captured
+from that journal's high-water mark. On startup / failover — and on every poll tick — every
+event-waiting instance is rediscovered and the journal is replayed against it from
+`sinceEventSeq`, so a matching event **survives the death of the authority that routed it**:
+another compatible authority replays it from the shared journal with no client resend, no
+manual replay, no sticky routing and no application polling. Existing external-event dedup
+is unchanged and runs upstream, so a redelivered physical event transitions a wait **at most
+once**; replaying the same journalled event any number of times yields **one** logical
+transition. A matching event unblocks *every* independently-matching waiting instance
+(fanout); a wait never globally consumes an event. An event that committed strictly before a
+wait became live is deterministically **not** matched (it is in the past); an event
+concurrent with wait activation is matched exactly once — no event is lost in the handoff.
+
+`bind: { <bindingId>: Expression }` assigns declared bindings from `ref('EVENT')` when the
+event matches and the transition commits. A `wait-event` step may declare a `timeout` and an
+`onTimeout` edge; if the event and the timeout are concurrent, **exactly one** logical
+transition wins (`instanceRevision` decides), never both.
+
+---
+
+## Timers
+
+`timer` waits until a durable time. On activation the **target instant is computed once**
+(`activationInstant + after.seconds`, or the resolved `at`) and stored in the transition
+record — a restart does not recompute `now + after` and extend the wait. Scheduler firing
+may be physically at-least-once; the workflow transition it causes is logically exactly-once.
+A firing after the target time is still valid — the guarantee is *not before* the target,
+*eventually after*, subject to scheduler availability. 0.14 does not promise hard real-time.
+Recovery needs nothing special: the waiting row *is* the timer.
+
+---
+
+## Retries
+
+An `action` step may declare `retry: { maxAttempts, initialDelaySeconds, backoffMultiplier,
+maxDelaySeconds }`. Automatic retries apply only to **runtime-classified retryable**
+failures (a transient infrastructure condition, a lease interruption before logical commit)
+— never to a semantic business refusal. `retryable` vs terminal is a structured distinction;
+workflow logic never parses an error-message string. Each physical attempt has its own
+attempt number; the logical action identity is constant across attempts. The attempt count
+and the next eligible execution time are **durable** — authority death does not reset
+`attempt = 4` back to `1`. Lease/fencing ensures one current executor, so multiple
+authorities never retry the same step as independent logical owners.
+
+---
+
+## Cancellation
+
+```ts
+await server.cancelWorkflow(instanceId, credential); // { ok: true, status } | { error }
+```
+
+Idempotent. Cancellation is a fenced durable transition to `cancelled`. It means **do not
+continue executing future workflow steps** — it is **not** rollback: it does not undo
+already-committed actions, it does not reverse dispatched external effects, and it is not a
+distributed transaction. 0.14 has no automatic compensation. A later timer or event delivery
+for a `cancelled` (or `completed` / `failed`) instance does not transition it. A
+cancel-versus-transition race linearizes on `instanceRevision`: whichever fenced CAS commits
+first wins.
+
+Terminal statuses — `completed`, `failed`, `cancelled` — are durable and irreversible under
+normal execution. A stale authority cannot resurrect a terminal workflow.
+
+---
+
+## Crash recovery and multi-authority behaviour
+
+Workflow execution is **leaderless** — any compatible authority may advance any eligible
+instance; there is no workflow leader, primary node or master process. A short per-instance
+lease + fence (reused from the 0.12 `CoordinationProvider`) gates execution ownership; every
+durable mutation under ownership is fenced, so a resumed stale owner is refused.
+
+After startup an authority discovers instances that are runnable / retry-due / timer-due /
+recoverably waiting and advances them — the application does **not** scan stuck workflows,
+call `resumeWorkflow`, re-register timers or re-register event waits for normal supported
+recovery. Discovery is bounded and indexed (`status, next_eligible_at`).
+
+**Topology transparency:** the logical workflow result of a valid `WorkflowDef` is identical
+whether one authority or N run it, for identical committed semantic history. A process
+crash, authority crash, retry, lease expiry or request-routing change does not change the
+logical outcome.
+
+---
+
+## Compatibility
+
+A running instance stores the `AuthorityCompatibilityKey` (`{ schemaVersion,
+schemaFingerprint, serverContract, semanticFingerprint }`) at start. An authority whose key
+differs **refuses to advance it**, fail-closed — the same mechanism the distributed work
+store applies. A presentation-only graph change moves no fingerprint and stays compatible. A
+semantic workflow change makes new instances incompatible with old authorities; old
+instances are not auto-migrated — they run to completion on a compatible authority or are
+surfaced as stranded. A graph with **no** `WorkflowDef` compiles to the byte-identical
+`axiom.server.v1`–`v7` document it always did, and its `semanticFingerprint` is unchanged.
+
+---
+
+## Inspection
+
+`server.getWorkflow(instanceId)` / `server.inspectWorkflows(limit)` return the semantic
+fields — `status`, `currentStepId`, `activationId`, `attempt`, `waitingReason`,
+`nextEligibleAt`, `createdAt`, `updatedAt`, `instanceRevision`, `failure`, `output` — and
+**no** secrets (no HMAC keys, database paths, raw SQL, credentials).
+`server.workflowHistory(instanceId)` is the durable semantic transition log (`started`,
+`step-activated`, `step-succeeded`, `step-failed`, `retry-scheduled`, `event-matched`,
+`timer-fired`, `timeout-fired`, `branch-chosen`, `completed`, `failed`, `cancelled`) — a
+bounded record, not an event-sourcing requirement.
+
+`AgentAPI.analyzeWorkflow(workflowId)` is the static, graph-derived view: inputs, entry,
+every step and its edges, the `ActionDef` / `EventDef` dependency sets, timer waits, branch
+conditions, retry policies, the reachable terminal outcomes, acyclicity, and the kinds of
+`waitingReason` an instance can produce.
+
+---
+
+## `WorkflowStore`
+
+A provider-independent durable persistence abstraction: `createIdempotent`, `load`,
+`loadByStart`, `transition` (fenced CAS), `recordActionOutcome` / `loadActionOutcome`,
+`recoverRunnable`, `findEventWaits`, `history`, `list`. `createMemoryWorkflowStore()` is the
+single-process reference; `createSqliteWorkflowStore({ location })` is the real cross-process
+reference — independent OS-process connections, `BEGIN IMMEDIATE` with the revision + fence
+check *inside* the transaction, `busy_timeout` + bounded retry so `SQLITE_BUSY` never
+surfaces as application semantics, and `CREATE TABLE IF NOT EXISTS` + `INSERT OR IGNORE`
+init so concurrent startup is safe. No SQLite path / table / rowid / WAL position appears in
+the contract or the graph.
+
+---
+
+## Portability
+
+`axiom.conformance.v8` (`conformance/workflow/`) is the portable tier. A fixture is a
+compiled `axiom.server.v8` Server IR + start arguments + a deterministic driver script
+(advance the virtual clock, deliver an event, mark an action outcome) + the **required
+ordered logical transition history** and terminal state. `runWorkflowConformanceFixture` /
+`runWorkflowConformanceSuite` run it over the in-memory store; physical attempts may be
+duplicated, the logical history must match exactly. A future independent runtime implements
+the fixtures from the contract alone.
+
+---
+
+## Limitations
+
+- The deferred step kinds above are not available.
+- 0.14 has no `wait-query` (a workflow does not wait on a `QueryDef` result).
+- Cancellation cannot interrupt an already-dispatched physical external effect; the
+  framework stays honest about uncertain physical execution.
+- **Physical** effect execution remains at-least-once (the effect system's contract); only
+  the *logical* ActionDef invocation and each workflow step transition are exactly-once.
+- The durable event journal and the durable idempotency table are **bounded** buffers
+  (default 8192 journal entries / an idempotency window per authority config). They cover
+  crash and failover windows, not indefinite history; a wait parked longer than the journal
+  is retained past its `sinceEventSeq` is an implementation-owned retention concern.
+- `WorkflowStore` bounded retention of terminal instances and history is
+  implementation-owned; an active workflow never expires.

package/llms.txt

@@ -1,6 +1,6 @@
 # Axiom
 
-> AI-native semantic application framework, version 0.13.0-alpha.1. An Axiom application is a
+> AI-native semantic application framework, version 0.14.0-alpha.1. 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.13.0-alpha.1",
+  "version": "0.14.0-alpha.1",
   "description": "AI-native semantic web application framework.",
   "license": "MIT",
   "author": "AskTech AS",
@@ -34,10 +34,10 @@
     }
   },
   "dependencies": {
-    "@cynodia/axiom-core": "0.13.0-alpha.1",
-    "@cynodia/axiom-runtime": "0.13.0-alpha.1",
-    "@cynodia/axiom-compiler": "0.13.0-alpha.1",
-    "@cynodia/axiom-agent-api": "0.13.0-alpha.1"
+    "@cynodia/axiom-core": "0.14.0-alpha.1",
+    "@cynodia/axiom-runtime": "0.14.0-alpha.1",
+    "@cynodia/axiom-compiler": "0.14.0-alpha.1",
+    "@cynodia/axiom-agent-api": "0.14.0-alpha.1"
   },
   "scripts": {
     "build": "tsc -b tsconfig.json"