@cynodia/axiom 0.11.2-alpha.1 → 0.12.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.11.2-alpha.1`.
+documentation in `docs/` describes this exact version, `0.12.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.11.2-alpha.1`.
+`npm install @cynodia/axiom@0.12.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
@@ -191,6 +191,7 @@ focused document when the reference is not specific enough for the question at h
 | 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) |
+| Running N authority processes at once: ownership, leases, fencing, delivery guarantees, version skew | [`docs/DISTRIBUTED_AUTHORITY.md`](docs/DISTRIBUTED_AUTHORITY.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.11.2-alpha.1. An action is behavior expressed as data, executed as a transaction.
+Axiom 0.12.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.11.2-alpha.1. The machine-facing interface. Agents query semantics and apply
+Axiom 0.12.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.11.2-alpha.1. Compressed operational contract. Read this plus the `.d.ts`
+Axiom 0.12.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:
@@ -964,6 +964,76 @@ Diagnostics: `SCHEMA_MIGRATION_REQUIRED` `SCHEMA_INCOMPATIBLE` `MIGRATION_IN_PRO
 `MIGRATION_DESTRUCTIVE_UNMARKED` `INVALID_MIGRATION_OPERATION` `MIGRATION_TRANSFORM_IMPURE`
 `MIGRATION_TRANSFORM_TYPE_MISMATCH`.
 
+## DISTRIBUTED AUTHORITY
+
+Full model: [`DISTRIBUTED_AUTHORITY.md`](DISTRIBUTED_AUTHORITY.md).
+
+The authoritative runtime may run as **N processes at once** over one shared persistence
+provider, with **no graph change and no application code that knows a cluster exists**. One
+authority and N authorities produce the same committed state and the same framework-owned
+async work. Deployment topology is not application semantics.
+
+Quick answers:
+
+| Question | Answer |
+| --- | --- |
+| Do I write locking code? | **No.** Never an application lock, never `SETNX` in a `native` op. |
+| Do I need Redis? | **No.** `memory` and `SQLite` reference providers ship; 0.12 semantics use no provider's vocabulary. |
+| Are external effects generically exactly-once? | **No.** Exactly-once *logical* creation and *durable completion*; at-least-once *physical* execution unless the provider is idempotent. |
+| Can multiple authorities race work safely? | **Yes**, with a capable `coordination` provider — activated automatically, no flag. |
+| Can a stale owner commit after losing ownership? | **No.** Every durable-work write is fenced on a per-resource generation; a reclaim advances it. |
+| Is deployment topology graph semantics? | **No.** No node kind, operation or IR field is added; a distributed graph compiles byte-identically. |
+
+`createAxiomServer({ coordination, workStorage, distributed: { instanceId, leaseDurationMs,
+renewIntervalMs, workerConcurrency, claimBatchSize, pollIntervalMs } })` — an unsafe combo
+(`renewIntervalMs >= leaseDurationMs`) **throws**. `server.authority()` →
+`{ instanceId, distributed, coordination: capabilities|null, config, compatibilityKey }`;
+`server.inspectDistributedWork()` → live effect work items + incompatible items.
+
+Every framework-owned async unit — outbox effect, scheduled firing, subscription cursor — is
+a leased, fenced, per-item ownership claim: `pending → claimed(ownerId, generation) →
+succeeded/failed/retry`. Lease expiry authorises nothing; only a reclaim (which mints a
+higher generation) fences the prior owner (`WORK_FENCED`). `logicalEffectId` (= the effect
+intent id) never changes across retries; `idempotencyKey` defaults to it (§7 of the full
+doc). Retry backoff is durable, not a process timer. An attempt whose outcome was never
+recorded increments `uncertainAttempts` and is retried with the same key — Axiom never
+claims physical exactly-once.
+
+Scheduled `interval` / `delay` firings are gated on a fenced claim keyed by
+`"<scheduleId>@<dueInstant>"` (epoch-aligned for intervals; the constant `afterMs` for a
+delay), so N pollers cause one firing. Missed firings: `catchUp` = `latest` (default) / `all`
+/ N, always caught up by one authority.
+
+External event ingestion deduplicates on `source + externalEventId` (durable payload
+fingerprint): `accepted` / `duplicate` / `EVENT_ID_CONFLICT` (same id, different payload) /
+`unidentified` (no stable id → at-least-once). An id is **never synthesised** from a
+timestamp, an instance id or a UUID.
+
+Subscription cursors: per-subscription monotonic `sequence` (no cross-subscription order),
+fenced + monotonic advancement (`fenced` / `stale-sequence`), reconnect from the durable
+cursor through any authority.
+
+Cache coherence: durable revision observation — each entry records `observedRevision`,
+re-checked against `persistence.revision()` before every authoritative read → staleness
+bound **0** revisions; correctness does not depend on broadcast. `CACHE_COHERENCE` states it.
+
+Version skew: the **compatibility key** is `{ schemaVersion, schemaFingerprint,
+serverContract, semanticFingerprint }`, compared **fail-closed**. `semanticFingerprint`
+(core, versioned) hashes executable meaning — action bodies, operations, triggers, policies,
+queries, expression defs — and excludes names / UI / routes / themes / metadata / order;
+distinct from `schemaFingerprint`. Durable work is stamped with its creator's key; an
+authority whose key differs refuses to claim it (`INCOMPATIBLE_AUTHORITY`). Migration
+ownership stays 0.11 host-controlled — no second coordination system.
+
+Providers advertise capabilities (`distributed-lease`, `fencing`, `atomic-work-claim`,
+`durable-retry`, `event-dedup`, `durable-subscription-cursor`, `revision-observation`); a
+missing one **fails explicitly**, never a silent single-node fallback. Portable
+`axiom.conformance.v6` fixtures (`conformance/distributed/`) + `runCoordinationConformanceSuite`.
+Server IR stays `axiom.server.v7`.
+
+Diagnostics: `WORK_IN_PROGRESS` `WORK_FENCED` `WORK_NOT_CLAIMABLE` `INCOMPATIBLE_AUTHORITY`
+`EVENT_ID_CONFLICT`.
+
 ## Metadata classes
 
 ```ts

package/docs/ANTI_PATTERNS.md

@@ -1,6 +1,6 @@
 # Anti-patterns
 
-Axiom 0.11.2-alpha.1. Each of these compiles. Each is wrong. Each is followed by the correct
+Axiom 0.12.0-alpha.1. Each of these compiles. Each is wrong. Each is followed by the correct
 alternative.
 
 ## 1. Field names as entity runtime keys
@@ -682,3 +682,130 @@ The stored version, fingerprint and step history are written only by the migrati
 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.
+
+## 52. An application-written distributed lock (or `SETNX` in a `native` operation)
+
+```ts
+// WRONG — the graph now encodes a deployment fact, and a second lock system exists.
+{ kind: 'native', name: 'acquireRedisLock', arguments: { key: literal('reboot:dev-1') } }
+```
+
+Multi-authority safety is the framework's job, not the application's. `createAxiomServer` is
+given a `coordination` provider and every class of framework-owned async work is leased and
+fenced automatically. There is no `native` operation for locking and there will not be one;
+`SETNX` / `Redlock` / a Postgres advisory lock are provider techniques that never appear in
+a graph. See [`DISTRIBUTED_AUTHORITY.md`](DISTRIBUTED_AUTHORITY.md).
+
+## 53. A process-local "already executed" `Set` as deduplication
+
+```ts
+// WRONG — resets on restart, and authority B has never heard of it.
+const done = new Set<string>();
+if (done.has(effectId)) return;
+done.add(effectId);
+```
+
+Deduplication for an authoritative server must be durable and shared. The outbox keys the
+logical effect by its committed intent id and claims it with a fenced lease; external event
+ingestion deduplicates on `source + externalEventId` against a durable payload fingerprint.
+An in-memory set is neither durable nor cross-authority.
+
+## 54. `leader`-only application branches
+
+```ts
+// WRONG — "am I the leader?" is not a question the graph may ask.
+conditional(call('isLeaderInstance'), doTheWork, doNothing)
+```
+
+Axiom is leaderless: ownership is per work item, and any healthy compatible authority may
+claim any item. There is no leader for an application to branch on. If work should happen
+once, model it as framework-owned async work (an effect, a trigger) and let the claim make
+it once.
+
+## 55. A random UUID (or timestamp, or instance id) as an external-event dedup key
+
+```ts
+// WRONG — every "duplicate" gets a fresh id, so nothing is ever deduplicated.
+fireEvent(EVENT_STATUS, { ...payload, dedupKey: crypto.randomUUID() })
+```
+
+Deduplication needs the *provider's* stable delivery id. If the source has no stable id,
+ingestion is honestly at-least-once (`unidentified`) — synthesising uniqueness from a
+receive timestamp, a random UUID or the authority instance id is not deduplication, it just
+hides the fact that duplicates get through.
+
+## 56. A retry that creates a new logical effect
+
+```ts
+// WRONG — every attempt is a new effect, so the external system is hit N times with N keys.
+async function retry(effect) {
+  await outbox.enqueue({ ...effect, id: createNodeId() });
+}
+```
+
+`logicalEffectId` is the committed intent id and is stable for the life of the effect. A
+retry re-claims the *same* work item under a new fencing generation and re-runs the physical
+attempt with the *same* idempotency key. A new id defeats provider idempotency entirely.
+
+## 57. A completion write that is not conditional on the fencing generation
+
+```ts
+// WRONG — a stalled owner that wakes after a reclaim overwrites the new owner's result.
+await store.markComplete(effectId, result);
+```
+
+Every durable-work completion / retry / cursor write must be conditional on the current
+`(ownerId, generation)`. Lease expiry alone does not fence — but once another authority
+reclaims (advancing the generation), the old owner's write must be rejected (`WORK_FENCED`).
+Unconditional completion is a release-blocking defect.
+
+## 58. Assuming a global order across unrelated entities or events
+
+```ts
+// WRONG — there is no total order to observe.
+assert(eventA.sequence < eventB.sequence); // eventA and eventB from different subscriptions
+```
+
+Ordering is **per semantic stream** only: monotonic `sequence` within one subscription.
+There is no ordering across subscriptions, and none between a subscription and any other
+event source. Code that depends on a global order is depending on an accident of which
+authority happened to process what first.
+
+## 59. Relying on pub/sub delivery for cache correctness
+
+```ts
+// WRONG — a dropped invalidation message leaves this authority serving stale data forever.
+bus.on('invalidate', (key) => cache.delete(key));
+// ...and nothing else checks freshness.
+```
+
+Cache coherence is a *durable revision* mechanism, not a broadcast: each cache entry records
+the store revision it was computed at, and every authoritative read re-checks the persisted
+revision before serving. A broadcast invalidation is a latency optimisation; correctness
+must survive it being lost entirely.
+
+## 60. Swallowing an uncertain external effect outcome
+
+```ts
+// WRONG — "we didn't see a success, so it didn't happen" — then a non-idempotent retry.
+if (!recordedSuccess) await chargeCardAgain(amount);
+```
+
+If an authority sent the request and crashed before recording completion, Axiom cannot know
+whether the effect happened. The contract is: retry per the delivery policy **reusing the
+same idempotency key**, and mark the attempt uncertain (`uncertainAttempts`). Never assume
+not-done, and never claim the physical side effect is exactly-once — with a non-idempotent
+provider it may occur twice, and that must be visible, not hidden.
+
+## 61. Executing durable work under an incompatible build
+
+```ts
+// WRONG — authority B, running an older graph, claims and runs work authority A queued.
+await workStore.claim('effect', { ignoreCompatibilityKey: true });
+```
+
+Durable work records the **compatibility key** of the build that created it —
+`{ schemaVersion, schemaFingerprint, serverContract, semanticFingerprint }`. An authority
+whose key differs refuses to claim it (`INCOMPATIBLE_AUTHORITY`); the item waits for a
+compatible authority. A rolling deploy that lets an old build run new-schema work is exactly
+the mixed-semantic execution the fail-closed check exists to prevent.

package/docs/AUTHORITY.md

@@ -1,6 +1,6 @@
 # Authority
 
-Axiom 0.11.2-alpha.1. How an application crosses the trust boundary.
+Axiom 0.12.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

package/docs/CONSTRAINTS.md

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

package/docs/DISTRIBUTED_AUTHORITY.md

@@ -0,0 +1,370 @@
+# Distributed authority
+
+*This document describes Axiom `0.12.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
+`ApplicationGraph` and without any application code that knows a cluster exists. This is the
+0.12 "distributed authority" layer.
+
+The whole of it is one sentence:
+
+> **One authority instance and N authority instances produce the same committed state and
+> the same framework-owned asynchronous work.** Deployment topology is not application
+> semantics.
+
+`docs/AGENT_REFERENCE.md` has the compressed Q&A. This is the full contract.
+
+---
+
+## 1. Topology transparency
+
+An application is a graph. Running it on one process or on eight is an operational choice,
+made entirely outside the graph. There is:
+
+- no cluster-mode toggle an application calls, no `distributed: true` in the graph, no
+  leader election an application can observe;
+- no node kind, operation, expression kind or Server IR field added by 0.12 — a distributed
+  graph compiles to the exact same `axiom.server.vN` document a single-authority one does;
+- no `NativeOperation` for locking, and none will be added.
+
+Distributed execution **activates automatically** when `createAxiomServer` is given a
+`coordination` provider together with a durable `persistence` adapter. Given neither, the
+authority runs exactly as it did before — single writer, in-process outbox.
+
+## 2. Ownership
+
+Every unit of **framework-owned asynchronous work** — a transactional-outbox effect, a
+scheduled trigger firing, a subscription delivery cursor — is executed by **exactly one
+authority at a time** through a durable, leased, fenced, per-work-item ownership claim:
+
+```
+work item
+    ↓  created once by a committed transaction
+durable "pending" state
+    ↓  an authority acquires a lease
+"claimed" by (ownerId, generation)
+    ↓  the authority performs one physical attempt
+durable "completion" / "retry" state   (written only while the claim is still current)
+```
+
+Ownership is **exclusive, leased, recoverable, observable, bounded in time and crash-safe**.
+There is no global leader; any healthy, compatible authority may reclaim an expired claim.
+A process crash never permanently owns work.
+
+## 3. Leases
+
+A lease is portable plain data:
+
+```
+Lease { resourceId, ownerId, token, generation, acquiredAt, expiresAt }
+```
+
+Operations: `acquire`, `renew`, `release`, `inspect`, `checkOwnership`, `list`.
+
+- `acquire` succeeds when the resource is unclaimed or the current lease window has closed.
+  It never grants while a live lease is held — an owner that wants to keep working calls
+  `renew`.
+- `renew` and `release` are **owner-specific**: they require the opaque per-acquisition
+  `token`, so they are safe even between two claims by the same `ownerId`.
+- Lease timing uses the wall clock of whichever authority (or the coordination provider)
+  performs the operation. A safe renew cadence — `renewIntervalMs <= leaseDurationMs / 2`,
+  enforced by config validation — tolerates one lost renewal and bounded clock skew. Axiom
+  does **not** attempt distributed clock synchronisation; a deployment with unbounded skew
+  across authority hosts is unsupported and must be rejected operationally.
+
+## 4. Fencing
+
+**Lease expiry authorises nothing.** It only makes a claim reclaimable. The stale-owner
+problem —
+
+```
+A owns the work → A pauses → A's lease expires → B acquires → A wakes up → A keeps writing
+```
+
+— is solved by a **fencing generation**: a strictly-increasing, per-resource, crash-durable
+integer minted on every acquisition. Every durable-work mutation carries the generation it
+was claimed under. A mutation whose generation is not the current one is **rejected**
+(`WORK_FENCED`). A stale authority can never commit a semantic completion after ownership
+has moved.
+
+A lease that merely expired without anyone reclaiming it does **not** fence its owner: if B
+never took over, A's own completion still applies. Only a reclaim advances the generation.
+
+## 5. Logical effect vs physical attempt
+
+```
+LogicalEffect   — the semantic work a committed transaction created. Stable identity.
+EffectAttempt   — one physical attempt to perform it. Numbered; may repeat.
+```
+
+`logicalEffectId` is the committed effect-intent id and **never changes across retries**. A
+retry never creates a second logical effect. `attemptNumber` counts physical attempts;
+`ownerGeneration` is the fencing generation of the current attempt.
+
+## 6. Delivery guarantees
+
+The contract is precise, documented and machine-inspectable — not "exactly-once", which is
+impossible for a generic external side effect:
+
+| Layer | Guarantee |
+| --- | --- |
+| Logical effect creation | **exactly-once** — one committed transaction, one logical effect; idempotent enqueue collapses duplicates. |
+| Physical execution | **at-least-once**, unless the external provider is idempotent. The Axiom-supplied idempotency key (`= logicalEffectId`, see §7) is what lets an idempotent provider collapse retries to one side effect. |
+| Durable Axiom completion transition | **exactly-once** — fenced; only the current owner's generation moves the item to `succeeded` / `failed`, so the declared success/failure event fires once. |
+
+A follow-up: dispatching that declared event after the completion commit is at-most-once
+across a crash in the sub-window between the two — unchanged from single-authority 0.8+,
+where the event dispatch was always post-commit and non-durable.
+
+## 7. Effect idempotency
+
+An external effect provider *should* accept an Axiom-supplied stable idempotency key. Axiom
+supplies `effect.idempotencyKey = logicalEffectId` whenever the graph declares none; an
+author-declared key (a payment reference, say) is preserved. The application never invents a
+distributed execution id. An adapter maps the key to an HTTP `Idempotency-Key`, a
+payment-provider idempotency key, a message-deduplication id, and so on.
+
+## 8. Effect claiming, retry and uncertain outcomes
+
+Multiple authorities may race to claim a pending effect. Exactly one wins the active attempt
+generation; the others observe it as unavailable (`WORK_IN_PROGRESS`) and move on. If the
+owner crashes, its lease expires and another authority claims a **new** generation and
+retries.
+
+Retry state is **durable** (`attemptNumber`, last-attempt time, `nextEligibleAt` backoff
+floor, last failure classification, completion state). The backoff floor lives in the store,
+never in a process-local timer — a restart or failover resumes it. The graph-owned retry
+policy (`maxAttempts`, backoff shape, `retryable`) is honoured exactly; infrastructure only
+chooses poll cadence, claim batch size and lease-renew interval.
+
+**Uncertain external effect outcome (important).** Suppose an authority sends the external
+request, the external system processes it, and the authority crashes *before* recording
+completion. Axiom cannot generally know whether the effect happened. Required behaviour:
+retry according to the delivery contract, reusing the **same** idempotency key —
+`uncertainAttempts` on the durable work item is incremented so the reclaim is observably a
+retry-after-uncertainty. Axiom never pretends this collapses to a physical exactly-once
+side effect; with a non-idempotent provider the effect may happen twice.
+
+## 9. Crash recovery
+
+For a crash at **every** ownership boundary the recovery is defined:
+
+| Crash point | Durable state after | Reclaimable | Duplication boundary | Stale owner if it resumes |
+| --- | --- | --- | --- | --- |
+| before claim | pending | yes (claimable) | excluded | n/a |
+| during claim | pending / claimed(dead gen) | after lease expiry | excluded | fenced |
+| after claim, before work | claimed | after lease expiry | excluded (no effect ran) | fenced |
+| during work / after physical effect, before completion | claimed | after lease expiry | **at-least-once** | fenced |
+| before completion commit | claimed | after lease expiry | excluded (no partial completion) | fenced |
+| after completion commit, before release | succeeded / failed (durable) | no (terminal) | excluded | `already-terminal` |
+| during lease renewal | claimed | after lease expiry | excluded | fenced |
+| after lease expiry, before anyone reclaims | claimed | yes | excluded | **self-recovers** — expiry alone does not fence |
+
+Durable work has no sub-attempt checkpoint: the unit of progress is the whole attempt.
+
+## 10. Scheduling
+
+A scheduled trigger (`interval` / `delay`) fires on a host timer, and every authority runs
+its own timers. Each **logical firing** is a durable work item with a derived, stable id:
+
+```
+workId = "<scheduleId>@<dueInstant>"
+```
+
+`dueInstant` is a wall-clock millisecond every authority derives identically — an `interval`
+boundary is epoch-aligned to a multiple of `everyMs`; a `delay` fires once, so its instant
+is the constant `afterMs`. Because the id is derived, not minted, two authorities observing
+the same due schedule converge on **one** firing. Exactly one authority claims it (fenced);
+a crash permits reclaim of *the same* firing id — no second firing identity is ever created.
+
+Missed firings (an outage): a `catchUp` policy (`latest` (default), `all`, or a number)
+decides how many elapsed boundaries are enqueued. Whichever it is, the claim lease
+guarantees each missed firing is caught up by **one** authority, never N. Catch-up state
+vocabulary: `due`, `late`, `currently-owned`, `expired-owner`, `already-fired`,
+`terminally-completed`.
+
+## 11. Event deduplication
+
+When more than one authority can receive the same external delivery **and the provider
+contract says it carries a stable id**, ingestion deduplicates on `source + externalEventId`
+against a durable record of a payload fingerprint (a canonical-JSON SHA-256):
+
+| Input | Outcome |
+| --- | --- |
+| first `(source, externalEventId)` | `accepted` — dispatch one semantic event |
+| same, byte-equal payload | `duplicate` — dispatch nothing |
+| same id, different payload | **`EVENT_ID_CONFLICT`** — never a silent second event |
+| no `externalEventId` | `unidentified` — at-least-once ingestion, dedup impossible |
+
+A stable id is **never synthesised** from a receive timestamp, an authority instance id or a
+random UUID. The window per source is bounded; an id that has fallen out of the window is
+treated as new (bounded, not exactly-once).
+
+## 12. Subscriptions
+
+A `SubscriptionDef` separates three things: the semantic subscription (durable), the
+physical client connection (belongs to whichever authority the client reached, may drop),
+and the **delivery cursor** (durable, owned by exactly one authority at a time via a fenced
+lease).
+
+- **Ordering** is per subscription only: `sequence` is monotonic within one subscription.
+  There is deliberately **no** ordering across subscriptions or against any other event
+  source. `subscriptionOrderingGuarantee()` states this machine-readably.
+- **Cursor advancement is fenced and monotonic**: a write carries the generation its owner
+  was claimed under; a lower-generation write is rejected (`fenced`), a lower-sequence write
+  is rejected (`stale-sequence`). A stalled owner that resumes after takeover can never move
+  the cursor.
+- **Reconnect** follows the durable cursor, not process memory: a new authority `acquire`s
+  ownership and is handed the durable position to resume from. Reconnect does not depend on
+  reaching the same authority instance.
+- Delivery is **at-least-once**; duplicate delivery is possible.
+
+## 13. Cache coherence
+
+A cached authoritative read must never be served stale indefinitely because *another*
+authority committed. The correctness mechanism is **durable revision observation**, not
+broadcast:
+
+- persistence exposes a monotonic store `revision` that every committed transaction advances
+  (on any authority);
+- each cache entry records the `observedRevision` it was computed at;
+- before serving a cached authoritative read, the authority re-observes the persisted
+  revision; a behind entry is dropped and the result recomputed.
+
+Because the check happens on every authoritative read and any commit advances the revision,
+the **staleness bound is zero revisions** — a read after a committed write, on any
+authority, never observes the pre-write state. A local broadcast invalidation (an authority
+clearing its own cache on its own commit) is a latency optimisation only; a dropped
+notification changes nothing about correctness.
+
+`CACHE_COHERENCE` = `{ mechanism: 'durable-revision-observation', stalenessBoundRevisions:
+0, requiresBroadcast: false, checkPerRead: true }`.
+
+## 14. Version skew
+
+Two authorities with different application builds may temporarily coexist during a rolling
+deploy. Axiom **fails closed** when semantic compatibility cannot be established.
+
+An authority's **compatibility key** is four fields:
+
+```
+{ schemaVersion, schemaFingerprint, serverContract, semanticFingerprint }
+```
+
+- `schemaVersion` / `schemaFingerprint` — the 0.11 persistence-relevant identity. A schema
+  mismatch is already fatal per 0.11 migration safety.
+- `serverContract` — the Server IR contract the document declares.
+- `semanticFingerprint` — a **new**, versioned, deterministic hash over the *executable
+  server-side meaning*: action bodies, guards and operations, integration operation
+  definitions, triggers, events, subscription policy, read-policy predicates, query
+  semantics, expression definitions, constraints. It **excludes** everything a rename
+  touches — names, descriptions, labels, free-form metadata, all UI / routes / themes /
+  presentation, and declaration order. It is distinct from `schemaFingerprint`, which
+  deliberately excludes executable meaning: two graphs whose actions do entirely different
+  things but store the same shapes have the same `schemaFingerprint` and different
+  `semanticFingerprint`s.
+
+Durable work records the compatibility key of the build that created it. An authority whose
+key differs **refuses to claim** that work (`INCOMPATIBLE_AUTHORITY` / the item is simply
+not claimed and stays visible as incompatible). A compatible authority runs it. During a
+schema migration, incompatible workers stop claiming new work, ordinary serving is refused
+per 0.11, the migration completes, and compatible new authorities resume — migration
+ownership stays host-controlled and separate from ordinary distributed-work ownership; there
+is no second migration coordination system.
+
+`AgentAPI.inspectDistributedSemantics()` exposes the compatibility key and, per work class,
+the guarantee, the provider capability it needs, and where the live runtime state is —
+keeping the semantic guarantee, the runtime state, the provider capability and the
+operational tuning separate.
+
+## 15. Provider capabilities
+
+A `CoordinationProvider` advertises capabilities:
+
+```
+distributed-lease · fencing · atomic-work-claim · durable-retry ·
+event-dedup · durable-subscription-cursor · revision-observation
+```
+
+A runtime that needs a capability the provider does not advertise **fails explicitly** with
+a capability diagnostic. There is no silent single-node fallback and no "works as long as
+only one server is running".
+
+Two reference providers ship:
+
+- **memory** — a full *semantic* reference: every fencing, reclaim and ownership rule holds,
+  deterministic with an injected clock and token source, able to simulate an N-authority
+  cluster in one process. `physicalDurability: false` — it does not survive across OS
+  processes.
+- **SQLite** — the real cross-process reference: independent OS processes, independent
+  connections, one database file. `physicalDurability: true`. SQLite provides no independent
+  server clock (§3); physical `SQLITE_BUSY` / `SQLITE_LOCKED` contention is absorbed and, if
+  sustained, surfaces as a typed contention error — never as a coordination outcome.
+
+A future production provider may use PostgreSQL, Redis, DynamoDB, etc. 0.12 semantics are
+**not** defined in any provider's terminology: `SETNX`, `Redlock`, "Redis TTL", "conditional
+check failed" and the like are provider techniques, never Axiom vocabulary.
+
+## 16. Failure semantics — release invariants
+
+The following always hold, and each is covered by a real-OS-process test:
+
+- Two authorities never validly own the same `(resourceId, generation)`.
+- A stale owner cannot commit completion / retry / cursor state after the generation
+  advances.
+- One logical schedule firing never becomes two because N authorities poll.
+- A duplicate stable external event never becomes two semantic events; a same-id /
+  different-payload event is an explicit `EVENT_ID_CONFLICT`.
+- An effect retry never creates a second `logicalEffectId`.
+- A crash never permanently strands durable work; failover never loses committed work.
+- An incompatible / older-build authority never executes new-schema work.
+- Ordinary multi-authority operation needs no application SQL, locks or `NativeOperation`.
+- Provider-native contention never leaks as a semantic result.
+- The authoritative cache is never stale past the declared bound (one revision check).
+- A subscription's stale owner never overwrites a newer cursor.
+- Physical external-effect exactly-once is never claimed.
+
+## 17. Host configuration
+
+Infrastructure knobs, passed as `createAxiomServer({ distributed: { … } })`. None changes a
+semantic guarantee.
+
+| Knob | Meaning | Default |
+| --- | --- | --- |
+| `instanceId` | This authority's identity. | `host.uuid()` at startup |
+| `leaseDurationMs` | Lease window; an unrenewed claim becomes reclaimable after this. | 30000 |
+| `renewIntervalMs` | Renew cadence. MUST be `< leaseDurationMs`; `<= /2` recommended. | 10000 |
+| `workerConcurrency` | Max in-flight durable work items per authority. | 4 |
+| `claimBatchSize` | Max items claimed per poll. | 32 |
+| `pollIntervalMs` | Durable-state re-observation cadence. | 1000 |
+
+`createAxiomServer` **throws** on an unsafe combination (e.g. `renewIntervalMs >=
+leaseDurationMs`) rather than start with probabilistically-unsafe fencing.
+
+## 18. Conformance
+
+The portable `axiom.conformance.v6` fixture tier (`packages/server/conformance/distributed/`)
+covers lease acquisition, lease fencing, effect claiming, effect reclaim, effect completion,
+schedule firing, schedule reclaim, event deduplication, subscription cursor fencing, cache
+revision visibility and mixed-build refusal. Each fixture is a deterministic step list
+against the memory reference providers with a fixed clock and token sequence; the public
+`runCoordinationConformanceFixture` / `runCoordinationConformanceSuite` runner executes them.
+Server IR stays `axiom.server.v7` — 0.12 adds no IR vocabulary.
+
+## 19. Anti-patterns
+
+See `docs/ANTI_PATTERNS.md` for the full list with fixes. In short, none of these belongs in
+an application graph or in application code:
+
+- an application-written distributed lock, or Redis `SETNX` in a `native` operation;
+- a process-local "already executed" `Set` used as deduplication;
+- `leader`-only application branches;
+- a random UUID (or a timestamp, or an instance id) used as an external-event dedup key;
+- a retry that constructs a new logical effect id;
+- a completion write that is not conditional on the current fencing generation;
+- assuming a global order across unrelated entities or events;
+- relying on pub/sub delivery for cache correctness;
+- treating an uncertain external effect outcome as definitely-not-done;
+- claiming physical exactly-once for a generic external side effect;
+- executing durable work under a build whose compatibility key does not match.

package/docs/EFFECTS.md

@@ -1,6 +1,6 @@
 # Effects
 
-Axiom 0.11.2-alpha.1. External effects are not rollback-capable state mutations. This file
+Axiom 0.12.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.11.2-alpha.1. An event is a typed fact — something that happened — never work
+Axiom 0.12.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.11.2-alpha.1. An expression describes **what value is computed**. It is a tree of
+Axiom 0.12.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.11.2-alpha.1. The `ApplicationGraph` is the authoritative representation of an
+Axiom 0.12.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.11.2-alpha.1. How an application declares and calls an external system, without
+Axiom 0.12.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.11.2-alpha.1.
+Axiom 0.12.0-alpha.1.
 
 ```text
 Expression = a value

package/docs/MIGRATIONS.md

@@ -1,6 +1,6 @@
 # Schema evolution & semantic migrations
 
-Axiom 0.11.2-alpha.1. The operational contract for evolving a deployed application's
+Axiom 0.12.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.11.2-alpha.1. Presentation is **semantic UX intent**, expressed as data on a UI
+Axiom 0.12.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.11.2-alpha.1. The operational contract for demand-driven reads over authoritative
+Axiom 0.12.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`.
 

package/docs/RUNTIME.md

@@ -1,6 +1,6 @@
 # Runtime
 
-Axiom 0.11.2-alpha.1. The runtime executes an `ApplicationIR`. It is domain-independent: it
+Axiom 0.12.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.11.2-alpha.1. Runtime guarantees, stated formally. This file defines behavior; it
+Axiom 0.12.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.11.2-alpha.1. A `StateDef` is a named application value: stored, or computed from
+Axiom 0.12.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.11.2-alpha.1. How an application stores, references, serves and deletes binary data —
+Axiom 0.12.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.11.2-alpha.1. How an application receives a stream of external events — an MQTT
+Axiom 0.12.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.11.2-alpha.1. A `TriggerDef` says **when** an action should be invoked, without
+Axiom 0.12.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.11.2-alpha.1. Eleven semantic UI node kinds describe **what exists and what it does**.
+Axiom 0.12.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.11.2-alpha.1. Validation is authoring-time structural checking. It is not the same
+Axiom 0.12.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.
 

package/llms.txt

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