@feltdb/core 0.6.9 → 0.6.11

package/dist/file-db.js

@@ -1,6 +1,7 @@
 import { validateOperationAdmissionInput, operationsConflict, generateOperationId, validateTransitionInput, isValidTransition, isTerminalStatus, isIdempotentTerminalTransition, } from './operation-admission.js';
 import * as nodeFs from 'fs';
 import * as nodePath from 'path';
+import { decideTransaction, embeddedResult, EmbeddedTransactionRejected, } from './embedded-transaction.js';
 // Synchronous versions for sync API (will throw if called in browser)
 function getFsSync() {
     if (typeof nodeFs.existsSync === 'function')
@@ -16,6 +17,7 @@ export class FileJsDb {
     constructor(path) {
         this.peers = new Set();
         this.lockFd = null;
+        this.applied = new Set();
         const nodePath = getPathSync();
         const nodeFs = getFsSync();
         // Normalize and resolve the path to prevent directory traversal
@@ -38,6 +40,9 @@ export class FileJsDb {
         // Load or initialize state
         this.state = this.loadState();
         this.restorePeers();
+        for (const transactionId of this.state.applied_transactions ?? []) {
+            this.applied.add(transactionId);
+        }
     }
     loadState() {
         const nodeFs = getFsSync();
@@ -58,7 +63,8 @@ export class FileJsDb {
                     rows: snapshot.rows,
                     events: snapshot.events,
                     peers: snapshot.meta.peers ?? [],
-                    sequences: snapshot.meta.sequences ?? {}
+                    sequences: snapshot.meta.sequences ?? {},
+                    applied_transactions: snapshot.applied_transactions ?? []
                 };
             }
             catch (error) {
@@ -76,7 +82,8 @@ export class FileJsDb {
             rows: {},
             events: [],
             peers: [],
-            sequences: {}
+            sequences: {},
+            applied_transactions: []
         };
     }
     restorePeers() {
@@ -155,6 +162,7 @@ export class FileJsDb {
     }
     saveState() {
         const nodeFs = getFsSync();
+        const nodePathModule = getPathSync();
         try {
             // Update peers in state
             this.state.peers = [...this.peers];
@@ -169,14 +177,39 @@ export class FileJsDb {
                     sequences: this.state.sequences
                 },
                 rows: this.state.rows,
-                events: this.state.events
+                events: this.state.events,
+                applied_transactions: [...this.applied]
             };
             const content = JSON.stringify(snapshot, null, 2);
             // Write to temporary file
             const tempPath = this.statePath + '.tmp';
-            nodeFs.writeFileSync(tempPath, content, 'utf-8');
+            const handle = nodeFs.openSync(tempPath, 'w');
+            try {
+                nodeFs.writeFileSync(handle, content, 'utf-8');
+                // Force the contents to disk before the rename publishes them.
+                // A rename is a metadata operation: without this, a crash can leave
+                // the new name pointing at a file whose contents never landed.
+                nodeFs.fsyncSync(handle);
+            }
+            finally {
+                nodeFs.closeSync(handle);
+            }
             // Atomic rename commits the new state
             nodeFs.renameSync(tempPath, this.statePath);
+            // Persist the rename itself, so the commit survives power loss.
+            try {
+                const directory = nodeFs.openSync(nodePathModule.dirname(this.statePath), 'r');
+                try {
+                    nodeFs.fsyncSync(directory);
+                }
+                finally {
+                    nodeFs.closeSync(directory);
+                }
+            }
+            catch {
+                // Directory fsync is not available on every platform. The rename is
+                // still atomic; only the durability of the rename itself is weaker.
+            }
         }
         catch (error) {
             throw new Error(`Failed to save FeltDB state: ${error}`);
@@ -196,6 +229,71 @@ export class FileJsDb {
             id: `${this.origin}:${timestamp}:${this.state.sequence}`
         });
     }
+    /**
+     * Commit several operations atomically and durably.
+     *
+     * The snapshot is published by writing a temporary file, fsyncing it, and
+     * renaming it over the previous one. The rename is atomic, so a reader sees
+     * either the whole transaction or none of it, and a crash at any point
+     * leaves one of those two states on disk — never a mixture.
+     *
+     * Order matters here. The next state is built and persisted *before* it is
+     * adopted in memory, so a failed write cannot leave memory ahead of disk.
+     */
+    async commit_transaction(request) {
+        const before = this.state.sequence;
+        const plan = decideTransaction(request, {
+            exists: key => key in this.state.rows,
+            hasApplied: transactionId => this.applied.has(transactionId),
+        });
+        if (plan.kind === 'duplicate') {
+            return embeddedResult(request, true, before, this.state.sequence);
+        }
+        if (plan.kind === 'reject') {
+            throw new EmbeddedTransactionRejected(plan.reason);
+        }
+        // Build the post-transaction state without touching the live one.
+        const rows = { ...this.state.rows };
+        const events = [...this.state.events];
+        let sequence = this.state.sequence;
+        const timestamp = Date.now();
+        for (const mutation of plan.mutations) {
+            sequence += 1;
+            if (mutation.value === undefined) {
+                delete rows[mutation.key];
+            }
+            else {
+                rows[mutation.key] = mutation.value;
+            }
+            events.push({
+                sequence,
+                collection: mutation.collection,
+                key: mutation.key,
+                type: mutation.value === undefined ? 'delete' : 'put',
+                value: mutation.value,
+                timestamp,
+                origin: this.origin,
+                id: `${this.origin}:${timestamp}:${sequence}`,
+            });
+        }
+        const previous = this.state;
+        this.state = { ...this.state, rows, events, sequence };
+        // The transaction id has to be part of the snapshot being written, not
+        // added after it. Recording it afterwards would leave a committed
+        // transaction whose identity did not survive a restart, and redelivery
+        // would then apply it a second time.
+        this.applied.add(request.transactionId);
+        try {
+            this.saveState();
+        }
+        catch (error) {
+            // The commit did not become durable, so it must not be visible either.
+            this.state = previous;
+            this.applied.delete(request.transactionId);
+            throw error;
+        }
+        return embeddedResult(request, false, before, sequence);
+    }
     insert(key, value) {
         try {
             const parsed = JSON.parse(value);
@@ -283,6 +381,32 @@ export class FileJsDb {
     get_sequence() {
         return this.state.sequence;
     }
+    /**
+     * The file runtime declines revision validation, and this is the honest answer
+     * rather than a missing feature.
+     *
+     * A shared directory has no serialization authority over its writers.
+     * `insert`, `update`, `delete`, and `commit_transaction` do not take the
+     * cross-process lock, and publication is a whole-snapshot rename, so two
+     * processes writing the same directory lose data. `state.sequence` therefore
+     * cannot distinguish "one writer committed 50" from "two writers committed 50
+     * each and one snapshot won" — it produces a plausible but false answer,
+     * which is worse than producing none.
+     *
+     * Measured in tools/cli/test/file-runtime-concurrency.test.mjs and analysed in
+     * docs/architecture/freshness-revision-investigation.md. Making this runtime
+     * revision-capable requires fixing lock discipline and publication together;
+     * advertising `refresh` is correct until then, not a placeholder.
+     */
+    freshness() {
+        return {
+            domain: 'multi-process-file',
+            validation: 'refresh',
+            invalidation: false,
+            reason: 'a shared directory has no serialization authority over its writers, '
+                + 'so state.sequence cannot be an authoritative revision',
+        };
+    }
     audit_events() {
         return [...this.state.events];
     }

package/dist/freshness.d.ts

@@ -0,0 +1,119 @@
+/**
+ * The FeltDB freshness capability.
+ *
+ * FeltDB does not require every runtime to produce a revision number, because
+ * not every runtime has a serialization boundary that could make one
+ * authoritative. `get_sequence()` looked like that number and is not: it is a
+ * hardcoded `0` in the authority runtime and counts only this handle's writes
+ * elsewhere, so a cache built on it would look correct with one writer and
+ * serve stale data the moment a second one exists.
+ *
+ * The contract instead makes freshness a capability a runtime advertises, and
+ * holds it to one rule:
+ *
+ *   A runtime may advertise revision-based cache validation only if its
+ *   revision is authoritative for the consistency domain it represents.
+ *
+ * A runtime that cannot say that says so, and callers fall back to explicit
+ * refresh. Declining is a correct answer here; fabricating a scalar is not.
+ *
+ * See docs/architecture/collection-freshness.md for the decision and
+ * docs/architecture/freshness-revision-investigation.md for the evidence.
+ */
+import type { JsDb } from './feltdb.js';
+/**
+ * The consistency domain a runtime is operating in.
+ *
+ * This is a property of the deployment, not of the storage engine: the same
+ * runtime moves between domains when replication is switched on.
+ */
+export type ConsistencyDomain = 
+/** One process, one handle graph. Nothing writes this state from outside. */
+'single-process'
+/** A single server serializes every commit behind one lock. */
+ | 'single-authority'
+/** One storage engine serializes competing local writers (IndexedDB across tabs). */
+ | 'local-first'
+/** A shared directory with no serialization authority over its writers. */
+ | 'multi-process-file'
+/** Causally ordered replicas. There is no global sequencer, by design. */
+ | 'replicated'
+/** The runtime did not declare one. Treated as the least trustworthy case. */
+ | 'undeclared';
+/**
+ * A committed-state revision.
+ *
+ * `value` is meaningful **only** against another revision carrying the same
+ * `scope`. That restriction is the whole point: it is what stops a scalar from
+ * being compared across replicas, where the authoritative order is partial and
+ * two replicas can each reach "revision 7" holding different state.
+ */
+export interface Revision {
+    value: number;
+    scope: string;
+}
+export interface FreshnessCapability {
+    domain: ConsistencyDomain;
+    /**
+     * How a cache holder is permitted to decide its copy is current.
+     *
+     * - `revision`: ask for the current revision and compare it against the one
+     *   the cache was built from. Cheap, and it answers "am I stale?".
+     * - `refresh`: re-read the state. It is the only honest answer when no
+     *   authoritative revision exists.
+     */
+    validation: 'revision' | 'refresh';
+    /**
+     * Whether the runtime pushes a change signal.
+     *
+     * Invalidation tells a cache that it *might* be stale. It is never proof
+     * that a cache *is* current, and it never upgrades `validation`.
+     */
+    invalidation: boolean;
+    /** Comparison scope for revisions. Present exactly when validation is `revision`. */
+    revisionScope?: string;
+    /** Why revision validation is not offered. Present exactly when validation is `refresh`. */
+    reason?: string;
+}
+export declare class FreshnessContractViolation extends Error {
+    constructor(message: string);
+}
+/**
+ * Check a capability against the rule before anyone acts on it.
+ *
+ * A runtime that claims revision validation without being able to produce a
+ * revision is worse than one that claims nothing, so this throws rather than
+ * degrading quietly. The failure belongs to whoever wrote the runtime.
+ */
+export declare function assertFreshnessCapability(capability: FreshnessCapability, db: Pick<JsDb, 'revision'>): FreshnessCapability;
+/** Ask a runtime what freshness it can honestly support, and hold it to the rule. */
+export declare function describeFreshness(db: Pick<JsDb, 'freshness' | 'revision'>): Promise<FreshnessCapability>;
+/**
+ * Read a revision, but only from a runtime that advertised one.
+ *
+ * The capability is consulted on every read rather than cached, because a
+ * runtime's domain can change underneath a caller: switching on replication
+ * revokes revision authority, and a cache that had already captured the
+ * capability would keep trusting a number that stopped meaning anything.
+ *
+ * This is the accessor callers should use. Calling `db.revision()` directly
+ * skips the check that makes the answer trustworthy.
+ */
+export declare function readRevision(db: Pick<JsDb, 'freshness' | 'revision'>): Promise<Revision>;
+/**
+ * Compare two revisions from the same scope.
+ *
+ * Throws on a scope mismatch instead of returning a comparison. Two revisions
+ * from different scopes are not ordered, and silently picking an answer is
+ * exactly the mistake a scalar revision invites once replication exists.
+ */
+export declare function isNewer(candidate: Revision, baseline: Revision): boolean;
+/**
+ * Whether a cache built at `cached` is still current against `current`.
+ *
+ * Deliberately not "is it newer": equal revisions mean current, and anything
+ * else — including a revision that moved backwards, which should not happen —
+ * means refetch.
+ */
+export declare function isCacheCurrent(cached: Revision, current: Revision): boolean;
+//# sourceMappingURL=freshness.d.ts.map

package/dist/freshness.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"freshness.d.ts","sourceRoot":"","sources":["../src/freshness.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,aAAa,CAAC;AAExC;;;;;GAKG;AACH,MAAM,MAAM,iBAAiB;AAC3B,6EAA6E;AAC3E,gBAAgB;AAClB,+DAA+D;GAC7D,kBAAkB;AACpB,qFAAqF;GACnF,aAAa;AACf,2EAA2E;GACzE,oBAAoB;AACtB,0EAA0E;GACxE,YAAY;AACd,8EAA8E;GAC5E,YAAY,CAAC;AAEjB;;;;;;;GAOG;AACH,MAAM,WAAW,QAAQ;IACvB,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,mBAAmB;IAClC,MAAM,EAAE,iBAAiB,CAAC;IAE1B;;;;;;;OAOG;IACH,UAAU,EAAE,UAAU,GAAG,SAAS,CAAC;IAEnC;;;;;OAKG;IACH,YAAY,EAAE,OAAO,CAAC;IAEtB,qFAAqF;IACrF,aAAa,CAAC,EAAE,MAAM,CAAC;IAEvB,4FAA4F;IAC5F,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAUD,qBAAa,0BAA2B,SAAQ,KAAK;gBACvC,OAAO,EAAE,MAAM;CAI5B;AAED;;;;;;GAMG;AACH,wBAAgB,yBAAyB,CACvC,UAAU,EAAE,mBAAmB,EAC/B,EAAE,EAAE,IAAI,CAAC,IAAI,EAAE,UAAU,CAAC,GACzB,mBAAmB,CA4BrB;AAED,qFAAqF;AACrF,wBAAsB,iBAAiB,CAAC,EAAE,EAAE,IAAI,CAAC,IAAI,EAAE,WAAW,GAAG,UAAU,CAAC,GAAG,OAAO,CAAC,mBAAmB,CAAC,CAK9G;AAED;;;;;;;;;;GAUG;AACH,wBAAsB,YAAY,CAAC,EAAE,EAAE,IAAI,CAAC,IAAI,EAAE,WAAW,GAAG,UAAU,CAAC,GAAG,OAAO,CAAC,QAAQ,CAAC,CAc9F;AAED;;;;;;GAMG;AACH,wBAAgB,OAAO,CAAC,SAAS,EAAE,QAAQ,EAAE,QAAQ,EAAE,QAAQ,GAAG,OAAO,CAOxE;AAED;;;;;;GAMG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,QAAQ,EAAE,OAAO,EAAE,QAAQ,GAAG,OAAO,CAG3E"}

package/dist/freshness.js

@@ -0,0 +1,115 @@
+/**
+ * The FeltDB freshness capability.
+ *
+ * FeltDB does not require every runtime to produce a revision number, because
+ * not every runtime has a serialization boundary that could make one
+ * authoritative. `get_sequence()` looked like that number and is not: it is a
+ * hardcoded `0` in the authority runtime and counts only this handle's writes
+ * elsewhere, so a cache built on it would look correct with one writer and
+ * serve stale data the moment a second one exists.
+ *
+ * The contract instead makes freshness a capability a runtime advertises, and
+ * holds it to one rule:
+ *
+ *   A runtime may advertise revision-based cache validation only if its
+ *   revision is authoritative for the consistency domain it represents.
+ *
+ * A runtime that cannot say that says so, and callers fall back to explicit
+ * refresh. Declining is a correct answer here; fabricating a scalar is not.
+ *
+ * See docs/architecture/collection-freshness.md for the decision and
+ * docs/architecture/freshness-revision-investigation.md for the evidence.
+ */
+/** A runtime that has not declared a capability gets the safe answer, not a guess. */
+const UNDECLARED = Object.freeze({
+    domain: 'undeclared',
+    validation: 'refresh',
+    invalidation: false,
+    reason: 'the runtime does not declare a freshness capability',
+});
+export class FreshnessContractViolation extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'FreshnessContractViolation';
+    }
+}
+/**
+ * Check a capability against the rule before anyone acts on it.
+ *
+ * A runtime that claims revision validation without being able to produce a
+ * revision is worse than one that claims nothing, so this throws rather than
+ * degrading quietly. The failure belongs to whoever wrote the runtime.
+ */
+export function assertFreshnessCapability(capability, db) {
+    const hasRevision = typeof db.revision === 'function';
+    if (capability.validation === 'revision') {
+        if (!hasRevision) {
+            throw new FreshnessContractViolation('a runtime advertising revision validation must implement revision()');
+        }
+        if (!capability.revisionScope) {
+            throw new FreshnessContractViolation('a runtime advertising revision validation must name the scope its revisions are comparable within');
+        }
+        if (capability.domain === 'replicated' || capability.domain === 'multi-process-file') {
+            throw new FreshnessContractViolation(`the ${capability.domain} domain has no serialization boundary that can make a scalar revision authoritative`);
+        }
+        return capability;
+    }
+    if (!capability.reason) {
+        throw new FreshnessContractViolation('a runtime that cannot validate by revision must say why');
+    }
+    return capability;
+}
+/** Ask a runtime what freshness it can honestly support, and hold it to the rule. */
+export async function describeFreshness(db) {
+    if (typeof db.freshness !== 'function') {
+        return assertFreshnessCapability(UNDECLARED, db);
+    }
+    return assertFreshnessCapability(await db.freshness(), db);
+}
+/**
+ * Read a revision, but only from a runtime that advertised one.
+ *
+ * The capability is consulted on every read rather than cached, because a
+ * runtime's domain can change underneath a caller: switching on replication
+ * revokes revision authority, and a cache that had already captured the
+ * capability would keep trusting a number that stopped meaning anything.
+ *
+ * This is the accessor callers should use. Calling `db.revision()` directly
+ * skips the check that makes the answer trustworthy.
+ */
+export async function readRevision(db) {
+    const capability = await describeFreshness(db);
+    if (capability.validation !== 'revision') {
+        throw new FreshnessContractViolation(`this runtime does not offer revision validation: ${capability.reason}`);
+    }
+    const revision = await db.revision();
+    if (revision.scope !== capability.revisionScope) {
+        throw new FreshnessContractViolation(`revision scope ${revision.scope} does not match the advertised scope ${capability.revisionScope}`);
+    }
+    return revision;
+}
+/**
+ * Compare two revisions from the same scope.
+ *
+ * Throws on a scope mismatch instead of returning a comparison. Two revisions
+ * from different scopes are not ordered, and silently picking an answer is
+ * exactly the mistake a scalar revision invites once replication exists.
+ */
+export function isNewer(candidate, baseline) {
+    if (candidate.scope !== baseline.scope) {
+        throw new FreshnessContractViolation(`revisions from different scopes are not comparable: ${baseline.scope} vs ${candidate.scope}`);
+    }
+    return candidate.value > baseline.value;
+}
+/**
+ * Whether a cache built at `cached` is still current against `current`.
+ *
+ * Deliberately not "is it newer": equal revisions mean current, and anything
+ * else — including a revision that moved backwards, which should not happen —
+ * means refetch.
+ */
+export function isCacheCurrent(cached, current) {
+    if (cached.scope !== current.scope)
+        return false;
+    return cached.value === current.value;
+}

package/dist/http-db.d.ts

@@ -1,4 +1,5 @@
 import type { JsDb } from './feltdb.js';
+import type { FreshnessCapability, Revision } from './freshness.js';
 interface JsResult {
     success: boolean;
     data?: string;
@@ -19,6 +20,27 @@ export declare class HttpJsDb implements JsDb {
     query(collection: string): Promise<JsResult>;
     insert(key: string, value: string): Promise<JsResult>;
     update(key: string, value: string): Promise<JsResult>;
+    /**
+     * Commit a multi-operation transaction through the authority.
+     *
+     * The whole transaction travels as one request and is committed as one
+     * durable record on the server. A refusal means nothing was applied.
+     */
+    commit_transaction(request: {
+        transactionId: string;
+        operations: Array<{
+            collection: string;
+            id: string;
+            value?: Record<string, unknown>;
+            expectedVersion?: number;
+        }>;
+    }): Promise<{
+        transactionId: string;
+        duplicate: boolean;
+        operations: number;
+        stateBefore: number;
+        stateAfter: number;
+    }>;
     cas(params: {
         key: string;
         expectedVersion: number;
@@ -57,7 +79,33 @@ export declare class HttpJsDb implements JsDb {
     get_pending_for_peer(): JsResult;
     acknowledge_peer_operations(): JsResult;
     instance_id(): string;
+    /**
+     * `get_sequence()` is a hardcoded `0` here, and that is why it could never be
+     * the freshness contract: the client has no local counter worth reporting.
+     *
+     * The authority does have one. A single process advances `inner.sequence`
+     * inside the same critical section that writes the durable transaction
+     * record, so concurrent clients are serialized by the server and the revision
+     * is totally ordered. `GET /revision` reads it without performing a write.
+     */
     get_sequence(): number;
+    /**
+     * The scope is the store's own instance id, reported by the server, not this
+     * client's URL.
+     *
+     * That distinction matters behind a load balancer or after a failover: the
+     * URL would stay the same across two different stores and make their counters
+     * look comparable. The store's identity changes, so the mismatch surfaces as
+     * a refusal in `readRevision` instead of a silently wrong comparison.
+     *
+     * It is remembered after the first read so the common path is one request,
+     * and a later disagreement is exactly the signal worth raising.
+     */
+    private advertisedScope?;
+    freshness(): Promise<FreshnessCapability>;
+    revision(): Promise<Revision>;
+    private body;
+    private absorb;
 }
 export {};
 //# sourceMappingURL=http-db.d.ts.map

package/dist/http-db.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"http-db.d.ts","sourceRoot":"","sources":["../src/http-db.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,aAAa,CAAC;AAExC,UAAU,QAAQ;IAChB,OAAO,EAAE,OAAO,CAAC;IACjB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,UAAU,kBAAkB;IAC1B,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,MAAM,CAAC;CACf;AAED,iFAAiF;AACjF,qBAAa,QAAS,YAAW,IAAI;IACnC,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAS;IAC7B,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAS;gBAEnB,OAAO,EAAE,kBAAkB;IAKvC,OAAO,CAAC,OAAO;IAQf,OAAO,CAAC,QAAQ;IAQV,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,QAAQ,CAAC;IAenC,KAAK,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,QAAQ,CAAC;IAa5C,MAAM,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,QAAQ,CAAC;IAgBrD,MAAM,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,QAAQ,CAAC;IAerD,GAAG,CAAC,MAAM,EAAE;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,eAAe,EAAE,MAAM,CAAC;QAAC,aAAa,CAAC,EAAE,MAAM,CAAC;QAAC,eAAe,CAAC,EAAE,MAAM,CAAC;QAAC,gBAAgB,CAAC,EAAE,OAAO,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC;QAAE,OAAO,EAAE,OAAO,CAAC;QAAC,cAAc,EAAE,MAAM,CAAC;QAAC,YAAY,CAAC,EAAE,MAAM,CAAC;QAAC,YAAY,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IA8CvP,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,QAAQ,CAAC;IAa5C,mEAAmE;IAC7D,OAAO,CAAC,UAAU,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,GAAG,IAAI,CAAC;IAOtE,qEAAqE;IAC/D,MAAM,CAAC,UAAU,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,KAAK,SAAK,GAAG,OAAO,CAAC,OAAO,EAAE,CAAC;IAQzE,UAAU,CAAC,UAAU,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,GAAG,CAAC;IAMxD,YAAY,CAAC,OAAO,EAAE,UAAU,GAAG,OAAO,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,MAAM,CAAA;KAAE,CAAC;IAMxF,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,GAAG,IAAI,CAAC;IAOxD,OAAO,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,GAAG,OAAO,CAAC,GAAG,CAAC;IAQxD,iBAAiB,CAAC,QAAQ,EAAE,CAAC,UAAU,EAAE,MAAM,KAAK,IAAI,GAAG,MAAM,IAAI;YAMvD,aAAa;YA+Bb,OAAO;IASrB,sBAAsB,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,QAAQ,CAAC;IAC7D,UAAU,IAAI,QAAQ;IACtB,SAAS,IAAI,QAAQ;IACrB,QAAQ,IAAI,QAAQ;IACpB,aAAa,IAAI,QAAQ;IACzB,gBAAgB,IAAI,QAAQ;IAC5B,oBAAoB,IAAI,QAAQ;IAChC,2BAA2B,IAAI,QAAQ;IACvC,WAAW,IAAI,MAAM;IACrB,YAAY,IAAI,MAAM;CACvB"}
+{"version":3,"file":"http-db.d.ts","sourceRoot":"","sources":["../src/http-db.ts"],"names":[],"mappings":"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"}

package/dist/http-db.js

@@ -82,6 +82,25 @@ export class HttpJsDb {
             return { success: false, error: String(error) };
         }
     }
+    /**
+     * Commit a multi-operation transaction through the authority.
+     *
+     * The whole transaction travels as one request and is committed as one
+     * durable record on the server. A refusal means nothing was applied.
+     */
+    async commit_transaction(request) {
+        const response = await fetch(`${this.url}/transactions`, {
+            method: 'POST',
+            headers: this.headers(true),
+            body: JSON.stringify(request),
+        });
+        if (!response.ok) {
+            const failure = await this.failure(response);
+            throw new Error(failure.error || `transaction failed with HTTP ${response.status}`);
+        }
+        const body = await response.json();
+        return body;
+    }
     async cas(params) {
         try {
             const [collection, id] = this.splitKey(params.key);
@@ -220,7 +239,16 @@ export class HttpJsDb {
                 if (controller.signal.aborted)
                     return;
             }
-            await new Promise(resolve => setTimeout(resolve, 1000));
+            if (controller.signal.aborted)
+                return;
+            // The retry timer must not keep a Node process alive on its own. An
+            // authority that has shut down would otherwise stop its clients from
+            // ever exiting, because this loop reconnects forever.
+            await new Promise(resolve => {
+                const timer = setTimeout(resolve, 1000);
+                timer?.unref?.();
+                controller.signal.addEventListener('abort', () => { clearTimeout(timer); resolve(); }, { once: true });
+            });
         }
     }
     async failure(response) {
@@ -242,5 +270,53 @@ export class HttpJsDb {
     get_pending_for_peer() { return { success: false, error: 'Operation transport is server-managed' }; }
     acknowledge_peer_operations() { return { success: false, error: 'Operation transport is server-managed' }; }
     instance_id() { return `remote:${this.url}`; }
+    /**
+     * `get_sequence()` is a hardcoded `0` here, and that is why it could never be
+     * the freshness contract: the client has no local counter worth reporting.
+     *
+     * The authority does have one. A single process advances `inner.sequence`
+     * inside the same critical section that writes the durable transaction
+     * record, so concurrent clients are serialized by the server and the revision
+     * is totally ordered. `GET /revision` reads it without performing a write.
+     */
     get_sequence() { return 0; }
+    async freshness() {
+        if (this.advertisedScope === undefined) {
+            // An authority that predates `/revision` cannot validate a cache by
+            // revision, and saying so is a real answer rather than a failure: the
+            // caller falls back to refresh, which is always correct. Only a 404
+            // degrades — a network error or a 500 is not evidence about what the
+            // server supports, so it is raised rather than reported as a capability.
+            const probe = await fetch(`${this.url}/revision`, { headers: this.headers() });
+            if (probe.status === 404) {
+                return {
+                    domain: 'single-authority',
+                    validation: 'refresh',
+                    invalidation: true,
+                    reason: 'this authority does not serve GET /revision, so it cannot report a committed revision',
+                };
+            }
+            this.absorb(await this.body(probe));
+        }
+        return {
+            domain: 'single-authority',
+            validation: 'revision',
+            invalidation: true,
+            revisionScope: this.advertisedScope,
+        };
+    }
+    async revision() {
+        const body = this.absorb(await this.body(await fetch(`${this.url}/revision`, { headers: this.headers() })));
+        return { value: body.revision, scope: body.scope };
+    }
+    async body(response) {
+        if (!response.ok) {
+            throw new Error(`revision request failed: ${response.status} ${response.statusText}`);
+        }
+        return await response.json();
+    }
+    absorb(body) {
+        this.advertisedScope ?? (this.advertisedScope = body.scope);
+        return body;
+    }
 }

package/dist/index-backend.d.ts

@@ -19,6 +19,14 @@ export declare class IndexBackend implements IIndexBackend {
     initializeWasm(): Promise<void>;
     createIndex(config: IndexConfig): void;
     updateRecord(recordId: string, oldValue: Record<string, any> | null, newValue: Record<string, any>): void;
+    /**
+     * Discard indexed entries, keeping definitions. Reports whether it worked.
+     *
+     * The WASM backend exposes no reset, so a caller that needs the index to
+     * reflect a specific snapshot must treat `false` as "do not trust the index"
+     * rather than assuming the reset happened.
+     */
+    resetEntries(): boolean;
     queryIndex(name: string, query: IndexQuery): string[];
     queryCompoundIndex(name: string, values: Record<string, any>): string[];
     listIndexes(): IndexConfig[];

package/dist/index-backend.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index-backend.d.ts","sourceRoot":"","sources":["../src/index-backend.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAEhE,MAAM,WAAW,aAAa;IAC5B,WAAW,CAAC,MAAM,EAAE,WAAW,GAAG,IAAI,CAAC;IACvC,YAAY,CAAC,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,IAAI,EAAE,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,IAAI,CAAC;IAC1G,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,UAAU,GAAG,MAAM,EAAE,CAAC;IACtD,kBAAkB,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,MAAM,EAAE,CAAC;IACxE,WAAW,IAAI,WAAW,EAAE,CAAC;CAC9B;AAyBD,qBAAa,YAAa,YAAW,aAAa;IAChD,OAAO,CAAC,SAAS,CAA+B;IAChD,OAAO,CAAC,WAAW,CAAa;IAChC,OAAO,CAAC,OAAO,CAAkB;;IAM3B,cAAc,IAAI,OAAO,CAAC,IAAI,CAAC;IAcrC,WAAW,CAAC,MAAM,EAAE,WAAW,GAAG,IAAI;IAYtC,YAAY,CAAC,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,IAAI,EAAE,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,IAAI;IAezG,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,UAAU,GAAG,MAAM,EAAE;IAYrD,kBAAkB,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,MAAM,EAAE;IAgBvE,WAAW,IAAI,WAAW,EAAE;CAW7B"}
+{"version":3,"file":"index-backend.d.ts","sourceRoot":"","sources":["../src/index-backend.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAEhE,MAAM,WAAW,aAAa;IAC5B,WAAW,CAAC,MAAM,EAAE,WAAW,GAAG,IAAI,CAAC;IACvC,YAAY,CAAC,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,IAAI,EAAE,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,IAAI,CAAC;IAC1G,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,UAAU,GAAG,MAAM,EAAE,CAAC;IACtD,kBAAkB,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,MAAM,EAAE,CAAC;IACxE,WAAW,IAAI,WAAW,EAAE,CAAC;CAC9B;AAyBD,qBAAa,YAAa,YAAW,aAAa;IAChD,OAAO,CAAC,SAAS,CAA+B;IAChD,OAAO,CAAC,WAAW,CAAa;IAChC,OAAO,CAAC,OAAO,CAAkB;;IAM3B,cAAc,IAAI,OAAO,CAAC,IAAI,CAAC;IAcrC,WAAW,CAAC,MAAM,EAAE,WAAW,GAAG,IAAI;IAYtC,YAAY,CAAC,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,IAAI,EAAE,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,IAAI;IAezG;;;;;;OAMG;IACH,YAAY,IAAI,OAAO;IAMvB,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,UAAU,GAAG,MAAM,EAAE;IAYrD,kBAAkB,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,MAAM,EAAE;IAgBvE,WAAW,IAAI,WAAW,EAAE;CAW7B"}

package/dist/index-backend.js

@@ -72,6 +72,19 @@ export class IndexBackend {
         }
         this.tsBackend?.updateRecord(recordId, oldValue, newValue);
     }
+    /**
+     * Discard indexed entries, keeping definitions. Reports whether it worked.
+     *
+     * The WASM backend exposes no reset, so a caller that needs the index to
+     * reflect a specific snapshot must treat `false` as "do not trust the index"
+     * rather than assuming the reset happened.
+     */
+    resetEntries() {
+        if (this.useWasm && this.wasmBackend)
+            return false;
+        this.tsBackend?.resetEntries();
+        return this.tsBackend !== null;
+    }
     queryIndex(name, query) {
         if (this.useWasm && this.wasmBackend) {
             try {