@cynodia/axiom-server 0.12.0-alpha.1 → 0.12.1-alpha.1

package/dist/server.d.ts

@@ -201,10 +201,25 @@ export interface AxiomServer {
     start(): Promise<void>;
     /** The one entry point. Every transport funnels through here. */
     handle(request: ServerRequest): Promise<ServerResponse>;
-    /** Authoritative values of every observable state. */
+    /**
+     * This authority's **local view** of every observable state — the state as of the most
+     * recently handled request (spec12.1 §6, §39, §40). It is a synchronous read of the
+     * authority-local cache and does not itself reconcile with persistence. In a multi-authority
+     * deployment, read authoritative state through `handle(SnapshotRequest)` or an action, both
+     * of which reconcile to the durable revision first; or call {@link coherentSnapshot}.
+     */
     snapshot(): StateSnapshot;
+    /** A single state's value from the authority-local view. See {@link snapshot} for the coherence contract. */
     getState(id: NodeId): unknown;
+    /** The durable store revision this authority's local view is at (spec12.1 §22, monotonic). */
     revision(): number;
+    /**
+     * Reconcile to the durable revision (reloading persisted state if another authority has
+     * committed) and return a revision-coherent snapshot (spec12.1 §7, §38, §40). This is the
+     * async counterpart of {@link snapshot}; `handle(SnapshotRequest)` performs the same
+     * reconciliation for the protocol path.
+     */
+    coherentSnapshot(): Promise<StateSnapshot>;
     /** Every mutation this authority has applied, with its outcome. */
     mutationLog(): MutationLogEntry[];
     /**
@@ -295,6 +310,8 @@ export interface AxiomServer {
 export interface DistributedWorkInspection {
     authority: AuthorityInfo;
     effects: import('./durable-work.js').DurableWorkItemView[];
+    /** Logical scheduled firings this authority knows about, with their lease liveness (spec12.1 §53). */
+    schedules: import('./durable-work.js').DurableWorkItemView[];
     incompatibleEffects: import('./durable-work.js').DurableWorkItem[];
 }
 export declare function createAxiomServer(options: AxiomServerOptions): AxiomServer;

package/dist/server.js

@@ -458,6 +458,54 @@ export function createAxiomServer(options) {
         }
         return { revision: storeRevision, states, ...(incremental ? { partial: true } : {}) };
     }
+    /**
+     * Distributed state coherence (spec12.1 §6-§9, §11, §17-§22).
+     *
+     * The in-memory `StateDef` representation inside a running authority is an **authority-local
+     * cache** of persisted authoritative state — never an independent store. Before any
+     * operation whose semantic result depends on authoritative `StateDef` state, this
+     * re-observes the durable revision; if another authority has committed since, it reloads
+     * the persisted state so execution proceeds from a coherent revision.
+     *
+     * - The correctness mechanism is durable-revision observation, never a broadcast: a lost
+     *   notification cannot leave this authority indefinitely stale (§17).
+     * - A refresh always corresponds to one coherent persisted revision — if the store moves
+     *   while loading, it repeats (bounded) rather than mixing revisions (§19, §20).
+     * - `storeRevision` is monotonic: this never publishes local state at a revision below one
+     *   already observed (§22).
+     *
+     * Everything that calls this runs inside the server's single serialized queue, so there is
+     * never a concurrent refresh within one authority.
+     */
+    async function ensureStateCoherent() {
+        let observed = await persistence.revision();
+        if (observed <= storeRevision) {
+            return;
+        }
+        for (let attempt = 0; attempt < 8; attempt += 1) {
+            const rows = await persistence.load();
+            const after = await persistence.revision();
+            if (after !== observed && attempt < 7) {
+                observed = after;
+                continue;
+            }
+            for (const row of rows) {
+                const state = statesById.get(row.stateId);
+                if (!state || state.derivation) {
+                    continue;
+                }
+                runtime.hydrateState(row.stateId, row.value);
+                revisions.set(row.stateId, row.revision);
+            }
+            if (observed > storeRevision) {
+                storeRevision = observed;
+            }
+            // A reload may change any cached query result (a principal/policy-scoped entry
+            // included); the query cache already invalidates blindly on any commit (spec 0.10 §72).
+            invalidateQueryCache();
+            return;
+        }
+    }
     /**
      * The key an idempotency record is filed under.
      *
@@ -858,6 +906,12 @@ export function createAxiomServer(options) {
      */
     async function invokeCore(actionId, args, context, requestId, replayKey, depth) {
         const startedAt = Date.now();
+        // spec12.1 §9, §41-§44: an ActionDef transaction MUST begin from a StateDef snapshot
+        // corresponding to the persistence revision it will attempt to commit against — for a
+        // client request, a trigger, a scheduled firing, an event-invoked action or an
+        // effect-outcome action alike. Reconcile to the durable revision before any
+        // state-dependent semantics (guards, authorization, constraints, operations) run.
+        await ensureStateCoherent();
         // The caller is bound for the whole invocation, not only for the authorization check.
         // An operation that records who acted — `field(ref(PRINCIPAL), F_USER_ID)` — must resolve
         // whether or not the action also happens to carry an authorization rule. It is also what
@@ -991,6 +1045,13 @@ export function createAxiomServer(options) {
             for (const stateId of writes) {
                 runtime.hydrateState(stateId, before.get(stateId));
             }
+            // spec12.1 §11, §14, §15: this authority lost an optimistic concurrency race. The
+            // losing invocation returns CONCURRENCY_CONFLICT (no silent replay, §12) — but the
+            // authority itself MUST recover: its local StateDef is now known invalid, so reload
+            // the winning durable state before it processes any subsequent request. Without this,
+            // the base revision stays stale and every future commit fails the same way (the F1
+            // wedge).
+            await ensureStateCoherent();
             const diagnostics = [
                 diagnostic(SERVER_DIAGNOSTIC_CODES.CONCURRENCY_CONFLICT, `${action.name ?? action.id} was not committed: ${outcome.conflicts.join(', ')} changed while it ran`, { actionId: action.id, conflicts: outcome.conflicts }),
             ];
@@ -1367,13 +1428,27 @@ export function createAxiomServer(options) {
                 const gate = schemaGateWithoutStore(ir);
                 throw new Error(`${gate.code}: ${gate.message}`);
             }
-            for (const entry of persisted) {
+            // spec12.1 §37: publish a coherent (state, revision) pair. `persisted` above may be a
+            // read behind by now (the migration gate did async work); re-load so the hydrated
+            // state and `storeRevision` identify the same durable revision, repeating if a
+            // concurrent authority commits during the load (§19, §20).
+            let coherent;
+            let coherentAt;
+            for (let attempt = 0;; attempt += 1) {
+                coherentAt = await persistence.revision();
+                coherent = await persistence.load();
+                const after = await persistence.revision();
+                if (after === coherentAt || attempt >= 7) {
+                    break;
+                }
+            }
+            for (const entry of coherent) {
                 if (statesById.has(entry.stateId)) {
                     runtime.hydrateState(entry.stateId, entry.value);
                     revisions.set(entry.stateId, entry.revision);
                 }
             }
-            storeRevision = await persistence.revision();
+            storeRevision = coherentAt;
             // A crash between an effect intent's commit and its dispatch must not lose it: every
             // pending intent found on restart resumes dispatch here (spec §19,96,140).
             const pending = (await persistence.loadPendingEffects?.()) ?? [];
@@ -1491,6 +1566,12 @@ export function createAxiomServer(options) {
                             ],
                         };
                     }
+                    // spec12.1 §8.1, §13, §38, §64: a SnapshotRequest arriving after another
+                    // authority's commit MUST observe state at least as new as that commit. Reconcile
+                    // to the durable revision before answering — this is the protocol path a real
+                    // consumer reads authoritative state through, and it is a permanent regression
+                    // requirement.
+                    await ensureStateCoherent();
                     report({ kind: 'snapshot', revision: storeRevision });
                     const response = {
                         kind: 'snapshot',
@@ -1524,9 +1605,15 @@ export function createAxiomServer(options) {
                 };
             });
         },
-        snapshot: snapshotOf,
+        snapshot: () => snapshotOf(),
         getState: (id) => runtime.getState(id),
         revision: () => storeRevision,
+        async coherentSnapshot() {
+            return serialize(async () => {
+                await ensureStateCoherent();
+                return snapshotOf();
+            });
+        },
         mutationLog: () => runtime.getMutationLog(),
         effectLog: () => [...effectRecords.values()].map((entry) => ({ ...entry })),
         subscriptionLog: () => subscriptionRuntime.status(),
@@ -1574,11 +1661,12 @@ export function createAxiomServer(options) {
                 compatibilityKey,
             };
             if (!distributedWorkStore) {
-                return { authority: authorityInfo, effects: [], incompatibleEffects: [] };
+                return { authority: authorityInfo, effects: [], schedules: [], incompatibleEffects: [] };
             }
             return {
                 authority: authorityInfo,
                 effects: await distributedWorkStore.list('effect'),
+                schedules: await distributedWorkStore.list(SCHEDULE_FIRING_WORK_CLASS),
                 incompatibleEffects: await distributedWorkStore.listIncompatible('effect'),
             };
         },

package/dist/sqlite-persistence.d.ts

@@ -9,11 +9,29 @@ import type { PersistenceAdapter } from './persistence.js';
  *
  * The whole semantic transaction is written inside one SQL transaction, so a crash cannot
  * leave half of an action committed.
+ *
+ * **Multi-process contention (spec12.1 §27-§34).** This adapter is part of the supported
+ * SQLite multi-authority reference path: independent OS processes, independent connections,
+ * one database file. SQLite's single-writer file lock surfaces physical contention as
+ * `SQLITE_BUSY` / `SQLITE_LOCKED`; that MUST NOT escape as a semantic result during ordinary
+ * operation. Every statement runs behind a short `PRAGMA busy_timeout` plus the bounded
+ * {@link runWithBusyHandling} retry shared with the migration and coordination providers —
+ * physical contention is absorbed, a genuine constraint / corruption / IO / programmer error
+ * passes straight through, and a semantic optimistic `CONCURRENCY_CONFLICT` is never
+ * manufactured from a lock wait (§32). Waiting is always bounded (§28).
  */
 export interface SqlitePersistenceOptions {
     /** A file path, or `':memory:'`. */
     location: string;
     table?: string;
+    /**
+     * The SQLite native busy wait, in ms (spec12.1 §30). Infrastructure tuning, never
+     * application semantics. `0` disables the native wait; the bounded retry still applies.
+     * Defaults to the value the migration / coordination providers use.
+     */
+    busyTimeoutMs?: number;
+    /** Test seam — deterministic sleep for the bounded busy retry. */
+    sleep?: (ms: number) => Promise<void>;
 }
 /** Whether this Node build offers `node:sqlite` at all. */
 export declare function isSqliteAvailable(): Promise<boolean>;

package/dist/sqlite-persistence.js

@@ -1,3 +1,4 @@
+import { DEFAULT_BUSY_TIMEOUT_MS, SqliteContentionError, runWithBusyHandling, } from './sqlite-contention.js';
 /** Whether this Node build offers `node:sqlite` at all. */
 export async function isSqliteAvailable() {
     try {
@@ -12,23 +13,33 @@ export async function createSqlitePersistence(options) {
     const module = (await import('node:sqlite'));
     const table = options.table ?? 'axiom_state';
     const database = new module.DatabaseSync(options.location);
+    const busyMs = Math.max(0, Math.floor(options.busyTimeoutMs ?? DEFAULT_BUSY_TIMEOUT_MS));
+    const guard = (context, fn) => runWithBusyHandling(fn, {
+        context,
+        ...(options.sleep !== undefined ? { sleep: options.sleep } : {}),
+    });
     const effectsTable = `${table}_effects`;
-    database.exec(`
-    CREATE TABLE IF NOT EXISTS ${table} (
-      state_id TEXT PRIMARY KEY,
-      revision INTEGER NOT NULL,
-      value TEXT NOT NULL
-    );
-    CREATE TABLE IF NOT EXISTS ${table}_meta (
-      key TEXT PRIMARY KEY,
-      value INTEGER NOT NULL
-    );
-    CREATE TABLE IF NOT EXISTS ${effectsTable} (
-      effect_id TEXT PRIMARY KEY,
-      record TEXT NOT NULL,
-      status TEXT NOT NULL
-    );
-  `);
+    // Schema creation is itself a write and can hit a concurrent initializer's lock (spec12.1
+    // §33) — run it behind the same bounded handling as everything else.
+    await guard('sqlitePersistence.init', () => {
+        database.exec(`PRAGMA busy_timeout = ${busyMs};`);
+        database.exec(`
+      CREATE TABLE IF NOT EXISTS ${table} (
+        state_id TEXT PRIMARY KEY,
+        revision INTEGER NOT NULL,
+        value TEXT NOT NULL
+      );
+      CREATE TABLE IF NOT EXISTS ${table}_meta (
+        key TEXT PRIMARY KEY,
+        value INTEGER NOT NULL
+      );
+      CREATE TABLE IF NOT EXISTS ${effectsTable} (
+        effect_id TEXT PRIMARY KEY,
+        record TEXT NOT NULL,
+        status TEXT NOT NULL
+      );
+    `);
+    });
     const readAll = database.prepare(`SELECT state_id, revision, value FROM ${table}`);
     const readRevision = database.prepare(`SELECT value FROM ${table}_meta WHERE key = 'revision'`);
     const readOne = database.prepare(`SELECT revision FROM ${table} WHERE state_id = ?`);
@@ -43,54 +54,79 @@ export async function createSqlitePersistence(options) {
     const currentRevision = () => Number(readRevision.get()?.value ?? 0);
     return {
         async load() {
-            return readAll.all().map((row) => ({
+            return guard('sqlitePersistence.load', () => readAll.all().map((row) => ({
                 stateId: String(row.state_id),
                 revision: Number(row.revision),
                 value: JSON.parse(String(row.value)),
-            }));
+            })));
         },
         async commit(commit) {
-            const conflicts = commit.writes
-                .map((write) => write.stateId)
-                .filter((stateId) => Number(readOne.get(stateId)?.revision ?? 0) !== (commit.expected[stateId] ?? 0));
-            if (conflicts.length > 0) {
-                return { committed: false, revision: currentRevision(), conflicts };
-            }
-            const revision = currentRevision() + 1;
-            // One SQL transaction for one semantic transaction — the state writes and the effect
-            // intents this transaction recorded commit atomically, which is the outbox invariant
-            // (spec §18): a crash right after this call cannot lose an intent that was here.
-            database.exec('BEGIN IMMEDIATE');
+            // The whole commit — the conflict check and the atomic write — runs behind bounded
+            // busy handling. A physical lock we wait out then re-checks conflicts against the
+            // now-current revisions, so a concurrent writer's commit becomes a legitimate
+            // CONCURRENCY_CONFLICT rather than a leaked SQLITE_BUSY (spec12.1 §32).
             try {
-                for (const write of commit.writes) {
-                    upsert.run(write.stateId, revision, JSON.stringify(write.value ?? null));
-                }
-                setRevision.run(revision);
-                for (const effect of commit.effects ?? []) {
-                    insertEffect.run(effect.id, JSON.stringify(effect), effect.status);
-                }
-                database.exec('COMMIT');
+                return await guard('sqlitePersistence.commit', () => {
+                    const conflicts = commit.writes
+                        .map((write) => write.stateId)
+                        .filter((stateId) => Number(readOne.get(stateId)?.revision ?? 0) !== (commit.expected[stateId] ?? 0));
+                    if (conflicts.length > 0) {
+                        return { committed: false, revision: currentRevision(), conflicts };
+                    }
+                    const revision = currentRevision() + 1;
+                    database.exec('BEGIN IMMEDIATE');
+                    try {
+                        for (const write of commit.writes) {
+                            upsert.run(write.stateId, revision, JSON.stringify(write.value ?? null));
+                        }
+                        setRevision.run(revision);
+                        for (const effect of commit.effects ?? []) {
+                            insertEffect.run(effect.id, JSON.stringify(effect), effect.status);
+                        }
+                        database.exec('COMMIT');
+                    }
+                    catch (error) {
+                        try {
+                            database.exec('ROLLBACK');
+                        }
+                        catch {
+                            /* nothing open */
+                        }
+                        throw error;
+                    }
+                    return { committed: true, revision, conflicts: [] };
+                });
             }
             catch (error) {
-                database.exec('ROLLBACK');
+                if (error instanceof SqliteContentionError) {
+                    // Physical contention outlasted the bounded window. Report a refused commit (like
+                    // an optimistic conflict) so the authority reconciles and the caller may retry —
+                    // never a raw provider error (spec12.1 §27, §67).
+                    return {
+                        committed: false,
+                        revision: await guard('sqlitePersistence.revision', currentRevision),
+                        conflicts: commit.writes.map((write) => write.stateId),
+                    };
+                }
                 throw error;
             }
-            return { committed: true, revision, conflicts: [] };
         },
         async revision() {
-            return currentRevision();
+            return guard('sqlitePersistence.revision', currentRevision);
         },
         async loadPendingEffects() {
-            return readPendingEffects.all().map((row) => JSON.parse(String(row.record)));
+            return guard('sqlitePersistence.loadPendingEffects', () => readPendingEffects.all().map((row) => JSON.parse(String(row.record))));
         },
         async recordEffectAttempt(id, update) {
-            const row = readEffect.get(id);
-            if (!row) {
-                return;
-            }
-            const existing = JSON.parse(String(row.record));
-            const updated = { ...existing, ...update };
-            updateEffect.run(JSON.stringify(updated), updated.status, id);
+            await guard('sqlitePersistence.recordEffectAttempt', () => {
+                const row = readEffect.get(id);
+                if (!row) {
+                    return;
+                }
+                const existing = JSON.parse(String(row.record));
+                const updated = { ...existing, ...update };
+                updateEffect.run(JSON.stringify(updated), updated.status, id);
+            });
         },
         async close() {
             database.close();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cynodia/axiom-server",
-  "version": "0.12.0-alpha.1",
+  "version": "0.12.1-alpha.1",
   "description": "Authoritative server runtime that executes an Axiom Server IR.",
   "license": "MIT",
   "author": "AskTech AS",
@@ -37,8 +37,8 @@
     "./schema/*": "./schema/*"
   },
   "dependencies": {
-    "@cynodia/axiom-core": "0.12.0-alpha.1",
-    "@cynodia/axiom-runtime": "0.12.0-alpha.1"
+    "@cynodia/axiom-core": "0.12.1-alpha.1",
+    "@cynodia/axiom-runtime": "0.12.1-alpha.1"
   },
   "scripts": {
     "build": "tsc -b tsconfig.json tsconfig.test.json",