@bjornpagen/bumbledb-log 0.20.0 → 0.20.2

package/dist/tenants.js

@@ -0,0 +1,333 @@
+/**
+ * Per-tenant replicas (50, case 4): an LRU of replicas keyed by tenant
+ * id — a tenant is a prefix (`<root>/t/<tenant>`), eviction closes and
+ * deletes the local dir (the disposable law), and `t/_shared` is
+ * pinned. Braids shard within a tenant; tenants shard the world. A
+ * tenant id is one StoreKey segment. `get` returns a live handle whose
+ * refcount pins it against eviction for the duration of the borrow
+ * (findings 38, 71) — the pin outlives `get` and drops only on
+ * `release`; a disposed handle is a distinct type. One fenced lease
+ * owns each replica directory and is CAS-renewed while the slot is
+ * open, so a second live replica on that dir is unrepresentable
+ * (findings 39, 48).
+ */
+import * as fs from "node:fs/promises";
+import * as path from "node:path";
+import * as errors from "@superbuilders/errors";
+import { regex } from "arkregex";
+import { TEMP_NAMESPACE, tenantPrefix } from "#keys.ts";
+import { openReplica } from "#replica.ts";
+import { acquireFsLease, encodeLease, parseLease, releaseFsLease, sweepStaleTemps, syncedTemp } from "#store.ts";
+const PINNED_TENANT = "_shared";
+const TENANT_ID = regex("^[A-Za-z0-9._-]+$");
+/** Directory-lease lifetime: one owner per replica directory. The pool
+ *  CAS-extends `expires` at one-third this TTL while the slot is open,
+ *  so expiry cannot mint a second owner under a live replica. */
+const DIR_LEASE_MS = 300_000;
+const liveHandleBrand = Symbol("liveHandle");
+const disposedHandleBrand = Symbol("disposedHandle");
+function codeOf(error) {
+    return error.code;
+}
+async function fsyncDir(dir) {
+    const handle = await fs.open(dir, "r");
+    const synced = await errors.try(handle.sync());
+    await handle.close();
+    if (synced.error) {
+        throw errors.wrap(synced.error, `fsync directory ${dir}`);
+    }
+}
+/** CAS-extend `expires` of a token we already hold. A new token would
+ *  be a second owner; we rewrite the same path so identity does not
+ *  change. */
+async function renewDirLease(held, ttlMs) {
+    const read = await errors.try(fs.readFile(held.path, "utf8"));
+    if (read.error) {
+        if (codeOf(read.error) === "ENOENT") {
+            return;
+        }
+        throw read.error;
+    }
+    const lease = parseLease(read.data);
+    if (lease === null || lease.holder !== held.holder || lease.token !== held.token) {
+        throw errors.new("directory lease is no longer ours");
+    }
+    const body = encodeLease({ holder: held.holder, token: held.token, expires: BigInt(Date.now() + ttlMs) });
+    // The temp lives under the reserved `{root}/~tmp` namespace, where a
+    // crash strands sweepable litter — never beside the lease path.
+    const temp = await syncedTemp(held.root, body);
+    const replaced = await errors.try(fs.rename(temp, held.path));
+    if (replaced.error) {
+        await fs.rm(temp, { force: true });
+        if (codeOf(replaced.error) === "ENOENT") {
+            return;
+        }
+        throw replaced.error;
+    }
+    await fsyncDir(held.dir);
+}
+async function directoryBytes(dir) {
+    let total = 0;
+    const listed = await errors.try(fs.readdir(dir, { withFileTypes: true, recursive: true }));
+    if (listed.error) {
+        return 0;
+    }
+    for (const entry of listed.data) {
+        if (entry.isFile()) {
+            const stat = await errors.try(fs.stat(path.join(entry.parentPath, entry.name)));
+            if (stat.error === undefined) {
+                total += stat.data.size;
+            }
+        }
+    }
+    return total;
+}
+function checkTenantId(tenant) {
+    if (!TENANT_ID.test(tenant)) {
+        throw errors.new(`tenant id is not a single path segment: ${tenant}`);
+    }
+}
+function asDisposed() {
+    return { [disposedHandleBrand]: disposedHandleBrand };
+}
+async function disposeSlot(slot) {
+    await slot.replica[Symbol.asyncDispose]();
+    await fs.rm(slot.dir, { recursive: true, force: true });
+    await releaseFsLease(slot.lease);
+}
+function openTenants(options) {
+    const budgetBytes = options.budgetBytes ?? 400_000_000;
+    const maxOpen = options.maxOpen ?? 32;
+    const dirLeaseMs = options.dirLeaseMs ?? DIR_LEASE_MS;
+    if (dirLeaseMs <= 0) {
+        throw errors.new("dirLeaseMs must be positive");
+    }
+    const renewEveryMs = Math.max(1, Math.floor(dirLeaseMs / 3));
+    const open = new Map();
+    const opening = new Map();
+    /** The pool root's `~tmp` holds lease mint/renew/release temps; stale
+     *  ones are crash litter swept once per pool open, best-effort. */
+    const swept = errors.try(sweepStaleTemps(path.join(options.dir, TEMP_NAMESPACE)));
+    let tick = 0;
+    let closed = false;
+    let renewTimer;
+    let leaseGate = Promise.resolve();
+    function withLeaseGate(body) {
+        const run = leaseGate.then(body, body);
+        leaseGate = run.then(function absorb() {
+            return undefined;
+        }, function absorbFailure() {
+            return undefined;
+        });
+        return run;
+    }
+    function dropBorrow(tenant) {
+        if (closed) {
+            throw errors.new("tenants pool is disposed");
+        }
+        const slot = open.get(tenant);
+        if (slot === undefined || slot.refs <= 0) {
+            throw errors.new(`no live borrow for tenant ${tenant}`);
+        }
+        slot.refs -= 1;
+    }
+    function brandLive(replica, tenant) {
+        const handle = replica;
+        Object.defineProperty(handle, liveHandleBrand, { value: liveHandleBrand });
+        Object.defineProperty(handle, "release", {
+            value: function release() {
+                dropBorrow(tenant);
+            },
+            enumerable: false
+        });
+        return handle;
+    }
+    function armRenew() {
+        if (renewTimer !== undefined) {
+            return;
+        }
+        renewTimer = setInterval(function tickRenew() {
+            void errors.try(renewAllOpen());
+        }, renewEveryMs);
+    }
+    function disarmRenew() {
+        if (open.size > 0 || renewTimer === undefined) {
+            return;
+        }
+        clearInterval(renewTimer);
+        renewTimer = undefined;
+    }
+    async function renewAllOpen() {
+        await withLeaseGate(async function renewHeld() {
+            for (const [tenant, slot] of open) {
+                const result = await errors.try(renewDirLease(slot.lease, dirLeaseMs));
+                if (result.error !== undefined && open.get(tenant) === slot) {
+                    slot.leaseLost = result.error;
+                }
+            }
+        });
+    }
+    async function evictUntilWithin(keep) {
+        for (;;) {
+            let bytes = 0;
+            for (const slot of open.values()) {
+                bytes += slot.bytes;
+            }
+            if (open.size <= maxOpen && bytes <= budgetBytes) {
+                return;
+            }
+            let victim = null;
+            let oldest = Number.POSITIVE_INFINITY;
+            for (const [tenant, slot] of open) {
+                if (tenant === PINNED_TENANT || tenant === keep || slot.refs > 0) {
+                    continue;
+                }
+                if (slot.lastUsed < oldest) {
+                    oldest = slot.lastUsed;
+                    victim = tenant;
+                }
+            }
+            if (victim === null) {
+                return;
+            }
+            const slot = open.get(victim);
+            open.delete(victim);
+            if (slot !== undefined) {
+                await withLeaseGate(function disposeVictim() {
+                    return disposeSlot(slot);
+                });
+            }
+        }
+    }
+    /** Increment the borrow. The pin outlives `get` — a `finally`
+     *  decrement here would make LRU/`evict` legal while the caller
+     *  still holds the LiveHandle (finding 38). Decrement only if this
+     *  `get` fails before the handle is in the caller's hands. */
+    async function pin(slot, tenant) {
+        if (slot.leaseLost !== undefined) {
+            throw slot.leaseLost;
+        }
+        slot.refs += 1;
+        slot.lastUsed = tick;
+        try {
+            await evictUntilWithin(tenant);
+            const kept = open.get(tenant);
+            if (kept === undefined) {
+                throw errors.new("tenants pool evicted the handle it is returning");
+            }
+            await withLeaseGate(function renewOnPin() {
+                return renewDirLease(kept.lease, dirLeaseMs);
+            });
+            return kept.replica;
+        }
+        catch (error) {
+            slot.refs -= 1;
+            throw error;
+        }
+    }
+    async function openOne(tenant) {
+        await swept;
+        const dir = path.join(options.dir, tenant);
+        /** The dir-lease mirrors Rust `acquire_named`: tokens live at
+         *  `{options.dir}/~lease/{tenant}`, outside the disposable replica
+         *  directory `{options.dir}/{tenant}` — the replica-open sweep
+         *  rm-rfs the replica dir's own `~lease` and must not touch the
+         *  held tenant lease. */
+        const lease = await acquireFsLease(options.dir, tenant, dirLeaseMs, "refuse");
+        let replica;
+        try {
+            replica = brandLive(await openReplica({
+                store: options.store,
+                prefix: tenantPrefix(options.root, tenant),
+                dir,
+                theory: options.theory
+            }), tenant);
+        }
+        catch (error) {
+            await releaseFsLease(lease);
+            throw error;
+        }
+        const slot = {
+            replica,
+            dir,
+            lease,
+            bytes: await directoryBytes(dir),
+            lastUsed: tick,
+            refs: 0
+        };
+        open.set(tenant, slot);
+        armRenew();
+        return await pin(slot, tenant);
+    }
+    return {
+        async get(tenant) {
+            if (closed) {
+                throw errors.new("tenants pool is disposed");
+            }
+            checkTenantId(tenant);
+            tick += 1;
+            const hit = open.get(tenant);
+            if (hit !== undefined) {
+                return await pin(hit, tenant);
+            }
+            const inflight = opening.get(tenant);
+            if (inflight !== undefined) {
+                const ran = await errors.try(inflight);
+                if (ran.error) {
+                    throw ran.error;
+                }
+                const slot = open.get(tenant);
+                if (slot === undefined) {
+                    throw errors.new("tenants pool dropped the tenant during open");
+                }
+                return await pin(slot, tenant);
+            }
+            const pending = openOne(tenant);
+            opening.set(tenant, pending);
+            const ran = await errors.try(pending);
+            opening.delete(tenant);
+            if (ran.error) {
+                throw ran.error;
+            }
+            return ran.data;
+        },
+        async evict(tenant) {
+            if (closed) {
+                throw errors.new("tenants pool is disposed");
+            }
+            checkTenantId(tenant);
+            if (tenant === PINNED_TENANT) {
+                return null;
+            }
+            const slot = open.get(tenant);
+            if (slot === undefined || slot.refs > 0) {
+                return null;
+            }
+            open.delete(tenant);
+            await withLeaseGate(function disposeEvicted() {
+                return disposeSlot(slot);
+            });
+            disarmRenew();
+            return asDisposed();
+        },
+        release(tenant) {
+            dropBorrow(tenant);
+        },
+        async [Symbol.asyncDispose]() {
+            closed = true;
+            if (renewTimer !== undefined) {
+                clearInterval(renewTimer);
+                renewTimer = undefined;
+            }
+            await withLeaseGate(async function disposePool() {
+                for (const slot of open.values()) {
+                    await releaseFsLease(slot.lease);
+                    await slot.replica[Symbol.asyncDispose]();
+                }
+                open.clear();
+            });
+        }
+    };
+}
+export { openTenants };
+//# sourceMappingURL=tenants.js.map

package/dist/tenants.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tenants.js","sourceRoot":"","sources":["../src/tenants.ts"],"names":[],"mappings":"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"}

package/dist/tilde-family.json

@@ -0,0 +1,21 @@
+{
+  "surface": "key-grammar/tilde-family",
+  "rule": "a segment whose first code point is in this set is reserved; the set is ASCII tilde, its lookalikes, and the NFKC preimage of U+007E, one closed table both drivers consume",
+  "codePoints": [
+    "U+007E",
+    "U+02DC",
+    "U+02F7",
+    "U+1FC0",
+    "U+2053",
+    "U+223C",
+    "U+223D",
+    "U+223F",
+    "U+2E1E",
+    "U+2E1F",
+    "U+301C",
+    "U+3030",
+    "U+FE4B",
+    "U+FE4F",
+    "U+FF5E"
+  ]
+}

package/dist/vector.d.ts

@@ -0,0 +1,31 @@
+/**
+ * The per-braid generation map. Sum, domination, checkpoint order, and
+ * apply's increment live here. Overflow is a refusal of `sum` and of
+ * nowhere else.
+ */
+import type { Braid } from "./descriptor.js";
+import type { Generation } from "./keys.js";
+declare const Overflow: {
+    readonly tag: "overflow";
+};
+type Overflow = typeof Overflow;
+type CheckpointOrder = "before" | "equal" | "after";
+/** Applied counts keyed by braid. Any vector is a legal restore point. */
+declare class Vector {
+    #private;
+    constructor(entries?: Iterable<readonly [Braid, bigint]>);
+    static from(map: ReadonlyMap<Braid, bigint>): Vector;
+    /** The wholeness arithmetic. The one overflow site. */
+    sum(): bigint | Overflow;
+    /** Pointwise `this[braid] >= other[braid]`; an absent braid is zero. */
+    dominates(other: Vector): boolean;
+    /** The total order the manifest CAS installs. */
+    order(other: Vector): CheckpointOrder;
+    /** The applied count for `braid`; absent is zero. */
+    at(braid: Braid): Generation;
+    /** Apply's one mutation: this braid's count advances by one. */
+    advance(braid: Braid): Vector;
+}
+export type { CheckpointOrder };
+export { Overflow, Vector };
+//# sourceMappingURL=vector.d.ts.map

package/dist/vector.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"vector.d.ts","sourceRoot":"","sources":["../src/vector.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAGH,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,gBAAgB,CAAA;AAC3C,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,UAAU,CAAA;AAG1C,QAAA,MAAM,QAAQ;aAAK,GAAG,EAAE,UAAU;CAAW,CAAA;AAC7C,KAAK,QAAQ,GAAG,OAAO,QAAQ,CAAA;AAE/B,KAAK,eAAe,GAAG,QAAQ,GAAG,OAAO,GAAG,OAAO,CAAA;AAEnD,0EAA0E;AAC1E,cAAM,MAAM;;IAGX,YAAY,OAAO,GAAE,QAAQ,CAAC,SAAS,CAAC,KAAK,EAAE,MAAM,CAAC,CAAM,EAc3D;IAED,MAAM,CAAC,IAAI,CAAC,GAAG,EAAE,WAAW,CAAC,KAAK,EAAE,MAAM,CAAC,GAAG,MAAM,CAEnD;IAED,uDAAuD;IACvD,GAAG,IAAI,MAAM,GAAG,QAAQ,CAUvB;IAED,wEAAwE;IACxE,SAAS,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAOhC;IAED,iDAAiD;IACjD,KAAK,CAAC,KAAK,EAAE,MAAM,GAAG,eAAe,CAqBpC;IAED,qDAAqD;IACrD,EAAE,CAAC,KAAK,EAAE,KAAK,GAAG,UAAU,CAE3B;IAED,gEAAgE;IAChE,OAAO,CAAC,KAAK,EAAE,KAAK,GAAG,MAAM,CAK5B;CACD;AAED,YAAY,EAAE,eAAe,EAAE,CAAA;AAC/B,OAAO,EAAE,QAAQ,EAAE,MAAM,EAAE,CAAA"}

package/dist/vector.js

@@ -0,0 +1,87 @@
+/**
+ * The per-braid generation map. Sum, domination, checkpoint order, and
+ * apply's increment live here. Overflow is a refusal of `sum` and of
+ * nowhere else.
+ */
+import { U64_MAX } from "#bytes.ts";
+import { generation } from "#keys.ts";
+const Overflow = { tag: "overflow" };
+/** Applied counts keyed by braid. Any vector is a legal restore point. */
+class Vector {
+    #counts;
+    constructor(entries = []) {
+        const counts = new Map();
+        for (const [braid, g] of [...entries].sort(function byBraid(left, right) {
+            if (left[0] < right[0]) {
+                return -1;
+            }
+            if (left[0] > right[0]) {
+                return 1;
+            }
+            return 0;
+        })) {
+            counts.set(braid, g);
+        }
+        this.#counts = counts;
+    }
+    static from(map) {
+        return new Vector(map);
+    }
+    /** The wholeness arithmetic. The one overflow site. */
+    sum() {
+        let acc = 0n;
+        for (const g of this.#counts.values()) {
+            const next = acc + g;
+            if (next > U64_MAX) {
+                return Overflow;
+            }
+            acc = next;
+        }
+        return acc;
+    }
+    /** Pointwise `this[braid] >= other[braid]`; an absent braid is zero. */
+    dominates(other) {
+        for (const [braid, g] of other.#counts) {
+            if (this.at(braid) < g) {
+                return false;
+            }
+        }
+        return true;
+    }
+    /** The total order the manifest CAS installs. */
+    order(other) {
+        const left = this.sum();
+        const right = other.sum();
+        const leftOverflow = typeof left !== "bigint";
+        const rightOverflow = typeof right !== "bigint";
+        if (leftOverflow && rightOverflow) {
+            return "equal";
+        }
+        if (leftOverflow) {
+            return "after";
+        }
+        if (rightOverflow) {
+            return "before";
+        }
+        if (left < right) {
+            return "before";
+        }
+        if (left > right) {
+            return "after";
+        }
+        return "equal";
+    }
+    /** The applied count for `braid`; absent is zero. */
+    at(braid) {
+        return generation(this.#counts.get(braid) ?? 0n);
+    }
+    /** Apply's one mutation: this braid's count advances by one. */
+    advance(braid) {
+        const next = new Map(this.#counts);
+        const current = next.get(braid) ?? 0n;
+        next.set(braid, current === U64_MAX ? U64_MAX : current + 1n);
+        return new Vector(next);
+    }
+}
+export { Overflow, Vector };
+//# sourceMappingURL=vector.js.map

package/dist/vector.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"vector.js","sourceRoot":"","sources":["../src/vector.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAA;AAGnC,OAAO,EAAE,UAAU,EAAE,MAAM,UAAU,CAAA;AAErC,MAAM,QAAQ,GAAG,EAAE,GAAG,EAAE,UAAU,EAAW,CAAA;AAK7C,0EAA0E;AAC1E,MAAM,MAAM;IACF,OAAO,CAAoB;IAEpC,YAAY,OAAO,GAAuC,EAAE;QAC3D,MAAM,MAAM,GAAG,IAAI,GAAG,EAAiB,CAAA;QACvC,KAAK,MAAM,CAAC,KAAK,EAAE,CAAC,CAAC,IAAI,CAAC,GAAG,OAAO,CAAC,CAAC,IAAI,CAAC,SAAS,OAAO,CAAC,IAAI,EAAE,KAAK;YACtE,IAAI,IAAI,CAAC,CAAC,CAAC,GAAG,KAAK,CAAC,CAAC,CAAC,EAAE,CAAC;gBACxB,OAAO,CAAC,CAAC,CAAA;YACV,CAAC;YACD,IAAI,IAAI,CAAC,CAAC,CAAC,GAAG,KAAK,CAAC,CAAC,CAAC,EAAE,CAAC;gBACxB,OAAO,CAAC,CAAA;YACT,CAAC;YACD,OAAO,CAAC,CAAA;QACT,CAAC,CAAC,EAAE,CAAC;YACJ,MAAM,CAAC,GAAG,CAAC,KAAK,EAAE,CAAC,CAAC,CAAA;QACrB,CAAC;QACD,IAAI,CAAC,OAAO,GAAG,MAAM,CAAA;IACtB,CAAC;IAED,MAAM,CAAC,IAAI,CAAC,GAA+B;QAC1C,OAAO,IAAI,MAAM,CAAC,GAAG,CAAC,CAAA;IACvB,CAAC;IAED,uDAAuD;IACvD,GAAG;QACF,IAAI,GAAG,GAAG,EAAE,CAAA;QACZ,KAAK,MAAM,CAAC,IAAI,IAAI,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC;YACvC,MAAM,IAAI,GAAG,GAAG,GAAG,CAAC,CAAA;YACpB,IAAI,IAAI,GAAG,OAAO,EAAE,CAAC;gBACpB,OAAO,QAAQ,CAAA;YAChB,CAAC;YACD,GAAG,GAAG,IAAI,CAAA;QACX,CAAC;QACD,OAAO,GAAG,CAAA;IACX,CAAC;IAED,wEAAwE;IACxE,SAAS,CAAC,KAAa;QACtB,KAAK,MAAM,CAAC,KAAK,EAAE,CAAC,CAAC,IAAI,KAAK,CAAC,OAAO,EAAE,CAAC;YACxC,IAAI,IAAI,CAAC,EAAE,CAAC,KAAK,CAAC,GAAG,CAAC,EAAE,CAAC;gBACxB,OAAO,KAAK,CAAA;YACb,CAAC;QACF,CAAC;QACD,OAAO,IAAI,CAAA;IACZ,CAAC;IAED,iDAAiD;IACjD,KAAK,CAAC,KAAa;QAClB,MAAM,IAAI,GAAG,IAAI,CAAC,GAAG,EAAE,CAAA;QACvB,MAAM,KAAK,GAAG,KAAK,CAAC,GAAG,EAAE,CAAA;QACzB,MAAM,YAAY,GAAG,OAAO,IAAI,KAAK,QAAQ,CAAA;QAC7C,MAAM,aAAa,GAAG,OAAO,KAAK,KAAK,QAAQ,CAAA;QAC/C,IAAI,YAAY,IAAI,aAAa,EAAE,CAAC;YACnC,OAAO,OAAO,CAAA;QACf,CAAC;QACD,IAAI,YAAY,EAAE,CAAC;YAClB,OAAO,OAAO,CAAA;QACf,CAAC;QACD,IAAI,aAAa,EAAE,CAAC;YACnB,OAAO,QAAQ,CAAA;QAChB,CAAC;QACD,IAAI,IAAI,GAAG,KAAK,EAAE,CAAC;YAClB,OAAO,QAAQ,CAAA;QAChB,CAAC;QACD,IAAI,IAAI,GAAG,KAAK,EAAE,CAAC;YAClB,OAAO,OAAO,CAAA;QACf,CAAC;QACD,OAAO,OAAO,CAAA;IACf,CAAC;IAED,qDAAqD;IACrD,EAAE,CAAC,KAAY;QACd,OAAO,UAAU,CAAC,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC,CAAA;IACjD,CAAC;IAED,gEAAgE;IAChE,OAAO,CAAC,KAAY;QACnB,MAAM,IAAI,GAAG,IAAI,GAAG,CAAC,IAAI,CAAC,OAAO,CAAC,CAAA;QAClC,MAAM,OAAO,GAAG,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,EAAE,CAAA;QACrC,IAAI,CAAC,GAAG,CAAC,KAAK,EAAE,OAAO,KAAK,OAAO,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,OAAO,GAAG,EAAE,CAAC,CAAA;QAC7D,OAAO,IAAI,MAAM,CAAC,IAAI,CAAC,CAAA;IACxB,CAAC;CACD;AAGD,OAAO,EAAE,QAAQ,EAAE,MAAM,EAAE,CAAA"}

package/dist/writer.d.ts

@@ -0,0 +1,106 @@
+/**
+ * The writer (60): a replica plus the right to create log objects. Role
+ * is a field on the handle. `openWriter(options)` births the store;
+ * `openWriter(replica)` wraps a born replica and settles an inherited
+ * pending without drawing id leases. A replica never births —
+ * ManifestMissing is its refusal. One commit path and one loss path: a
+ * lost slot's byte-equal occupant is an ambiguous PUT absorbed; anything
+ * else discards the local directory, re-opens through the replica to the
+ * current tip, and re-judges the recorded ops once — the verdict IS a
+ * serial execution, performed. Each loop iteration races once at the
+ * then-tip, so a historical loss is structurally uncountable, and bounded
+ * live-tip losses surface as ErrContention carrying the terminal
+ * re-judgment's own violation or the racing tip.
+ */
+import { type Admission, type Fact, type FreshKeys, type FreshRange, type MemberRelation, type MutationReport, type SchemaRelations } from "@bjornpagen/bumbledb";
+import type { Digest32 } from "./bytes.js";
+import type { Braid, Theory } from "./descriptor.js";
+import type { Generation } from "./keys.js";
+import type { CheckpointFacts } from "./manifest.js";
+import type { OpenReplicaOptions, Replica } from "./replica.js";
+import type { ObjectStore } from "./store.js";
+type Durability = "published" | "local-pending";
+/** Where an accepted commit landed on its braid: the slot (the braid
+ *  position — never the store-wide sum) and how durable the batch is. */
+interface Landing {
+    readonly slot: Generation;
+    readonly durability: Durability;
+}
+/** The accepted payload of `commit`: the body's value plus the landing. */
+interface CommitReceipt<R> extends Landing {
+    readonly value: R;
+    readonly braid: Braid;
+}
+/** The empty commit is not a commit: a body that records no ops names no
+ *  braid, so the refusal is its own outcome — never a slot, never a
+ *  thrown surprise. The body's value rides out, the way an abandoned
+ *  write's payload does in the engine. */
+interface EmptyCommit<R> {
+    readonly tag: "empty";
+    readonly value: R;
+}
+/** The engine's Admission sum carrying the log's receipt in its accepted
+ *  arm; the rejected arm is the engine's violations, shell and payload. */
+type Commit<Rels extends SchemaRelations, R> = Admission<Rels, CommitReceipt<R>> | EmptyCommit<R>;
+/** One braid's verdict inside a split commit: the engine's Admission
+ *  carrying the landing, beside the braid it judged. */
+interface BraidOutcome<Rels extends SchemaRelations> {
+    readonly braid: Braid;
+    readonly admission: Admission<Rels, Landing>;
+}
+type CommitSplit<Rels extends SchemaRelations, R> = {
+    readonly tag: "split";
+    readonly value: R;
+    readonly outcomes: readonly BraidOutcome<Rels>[];
+} | EmptyCommit<R>;
+/**
+ * The recorder: the engine `WriteTx`'s write surface, verbatim — insert,
+ * delete, and reserve carry the engine's own signatures, so a write-only
+ * body typechecks against both dialects. `contains`/`get` are absent by
+ * law: the journaled dialect is a pure recorder, and change is judged at
+ * commit, so a report's `changed` is 0n at record time. Reservations
+ * never appear in the log; the resulting inserts carry concrete values.
+ */
+interface Batch<Rels extends SchemaRelations> {
+    insert<Rel extends MemberRelation<Rels>>(relation: Rel, facts: Iterable<Fact<Rel>>): MutationReport;
+    delete<Rel extends MemberRelation<Rels>>(relation: Rel, facts: Iterable<Fact<Rel>>): MutationReport;
+    reserve<Rel extends MemberRelation<Rels>>(relation: Rel, field: FreshKeys<Rel> & string, count: bigint): FreshRange;
+}
+/** Ownership of a slot, read from the winner's header. */
+interface Deposition {
+    readonly braid: Braid;
+    readonly slot: Generation;
+    readonly resident: bigint;
+    readonly usurper: bigint;
+}
+interface Writer<Rels extends SchemaRelations> {
+    readonly role: "writer";
+    readonly replica: Replica<Rels>;
+    deposition(): Deposition | null;
+    commit<R>(body: (batch: Batch<Rels>) => R | Promise<R>): Promise<Commit<Rels, R>>;
+    commitSplit<R>(body: (batch: Batch<Rels>) => R | Promise<R>): Promise<CommitSplit<Rels, R>>;
+}
+type PublishRefusal = "manifest-missing" | "manifest" | "checkpoint-doc-missing" | "checkpoint";
+type Published = {
+    readonly tag: "replaced";
+} | {
+    readonly tag: "kept";
+    readonly incumbent: Digest32;
+} | {
+    readonly tag: "refused";
+    readonly reason: PublishRefusal;
+};
+/**
+ * Publishes `candidate` under the checkpoint order. The digest is the
+ * blake3 of the full bytes, `prev` included. A scratch lease
+ * `{dir}/~lease/ckpt-scratch` names the candidate for the publish
+ * window; a crash leaves that lease and a successor sweep reclaims
+ * it. `Kept` and every refused publish delete the candidate's `ckpt`
+ * pair.
+ */
+declare function publishCheckpoint(store: ObjectStore, prefix: string, dir: string, theory: Theory, candidate: CheckpointFacts, mdb: Uint8Array): Promise<Published>;
+declare function openWriter<Rels extends SchemaRelations>(replica: Replica<Rels>): Promise<Writer<Rels>>;
+declare function openWriter<Rels extends SchemaRelations>(options: OpenReplicaOptions<Rels>): Promise<Writer<Rels>>;
+export type { Batch, BraidOutcome, Commit, CommitReceipt, CommitSplit, Deposition, Durability, EmptyCommit, Landing, Writer };
+export { openWriter, publishCheckpoint };
+//# sourceMappingURL=writer.d.ts.map

package/dist/writer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"writer.d.ts","sourceRoot":"","sources":["../src/writer.ts"],"names":[],"mappings":"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"}