@statewalker/cellb 0.0.0-stage → 0.1.0

package/dist/bucket/celld-cells.js

@@ -0,0 +1,273 @@
+import { bytesToHex } from "@noble/hashes/utils";
+import { scopeOf } from "../core/celld-schema.js";
+import { ltxLog } from "./ltx-log.js";
+import { PreconditionFailedError } from "./object-store.js";
+const enc = new TextEncoder();
+const dec = new TextDecoder();
+/** celld 0.6.3: how long a node refuses a cell whose ownership record it found lost. */
+export const LOST_RECORD_RECHECK_MS = 10_000;
+const lostRecordError = (scope) => Object.assign(new Error(`ownership record lost: cells/${scope}/own.json is missing, but the bucket holds LTX under ` +
+    `cells/${scope}/ltx/; refusing to claim ${scope} as a new cell (celld docs/guarantees.md: ` +
+    `write a released record {"node": "", "epoch": <newest epoch>} to restore it)`), { name: "OwnershipRecordLostError" });
+/** The bucket's `close()` also closes `store` (when it has a `close`): pass a store of its own. */
+export function celldBucket(store, opts) {
+    const now = opts.now ?? (() => Date.now());
+    const ttl = opts.leaseTtlMs ?? 10_000;
+    const lost = new AbortController();
+    let renew;
+    let deadline;
+    let leaseWritten;
+    /** nodes/<node>.json, renewed every ttl/3; a failed renewal stops every cell (self-fencing). */
+    // celld decodes every node record (ownership_store.rs NodeLeaseWire / NodeLoadWire): a record
+    // missing a required load field breaks its fleet posture repair. This one is complete. It
+    // reports pressure and zero placement weight, so celld never offers this node a cell — it
+    // takes cells only when a request arrives.
+    //
+    // The address must not be empty: celld treats a live owner WITHOUT an address as dead and
+    // takes its cells over (logic/lib.rs apply_node_lease_result) — a split brain. With an
+    // address celld routes a request for our cell to it; a node that does not accept celld's
+    // peer protocol (a browser) gets an unroutable placeholder, so the request fails instead.
+    let addr = opts.addr || `${opts.node}.cellb.invalid:9`;
+    // celld's per-process generation is its signed-probe public key (Ed25519, peer_probe.rs):
+    // `probe_public_key` = `ownership_index_generation`. A real key lets `celld diagnose --peer`
+    // verify that a probe reached this node.
+    let generation = bytesToHex(crypto.getRandomValues(new Uint8Array(32)));
+    let probeKey;
+    const probeKeyReady = (async () => {
+        try {
+            const pair = (await crypto.subtle.generateKey({ name: "Ed25519" }, true, [
+                "sign",
+                "verify",
+            ]));
+            probeKey = pair.privateKey;
+            generation = bytesToHex(new Uint8Array(await crypto.subtle.exportKey("raw", pair.publicKey)));
+        }
+        catch {
+            // no Ed25519 in this WebCrypto: the record keeps a random generation (probes then fail)
+        }
+    })();
+    let validUntil = 0;
+    const writeLease = async () => {
+        const t = now();
+        const body = {
+            node: opts.node,
+            expires_ms: t + ttl,
+            addr,
+            probe_public_key: generation,
+            peer_protocol: 5,
+            paced_handoff: false,
+            ownership_index_generation: generation,
+            load: {
+                sampled_ms: t,
+                owned_cells: owned.size,
+                placement_weight: 0,
+                bucket_format: 2,
+                resident_cells: owned.size,
+                host_websockets: 0,
+                rss_bytes: 0,
+                in_use_bytes: 0,
+                cpu_percent_x100: 0,
+                open_fds: 0,
+                fd_limit: 0,
+                pressured: true,
+                memory_headroom: false,
+                shed_cells: 0,
+                restoring: 0,
+                rebalance_paused: false,
+                draining: false,
+            },
+        };
+        await store.put(`nodes/${opts.node}.json`, enc.encode(JSON.stringify(body)));
+        // Our authority lasts until the record we just wrote expires — minus a margin, so a node
+        // that stalls (a paused process, a frozen tab) stops acknowledging before celld may take
+        // over: celld waits for expires_ms; we stop at expires_ms - margin.
+        validUntil = t + ttl - Math.min(1_000, ttl / 4);
+    };
+    const owned = new Set();
+    /** Cells whose ownership record was found lost, with the time their refusal ends. */
+    const lostRecords = new Map();
+    const ensureLease = () => {
+        leaseWritten ??= probeKeyReady.then(writeLease).then(() => {
+            const tick = () => {
+                renew = setTimeout(() => {
+                    writeLease().then(tick, (e) => lost.abort(e));
+                }, ttl / 3);
+                // If renewals stop arriving (a stalled process, an unreachable bucket), every cell
+                // stops at the local deadline — before celld may take it over.
+                if (deadline)
+                    clearTimeout(deadline);
+                deadline = setTimeout(() => {
+                    if (now() >= validUntil)
+                        lost.abort(new Error(`node ${opts.node}: lease deadline passed`));
+                }, Math.max(0, validUntil - now()));
+                deadline.unref?.();
+                renew.unref?.();
+            };
+            tick();
+        });
+        return leaseWritten;
+    };
+    const readJson = async (key) => {
+        const o = await store.get(key);
+        return o ? { value: JSON.parse(dec.decode(o.body)), etag: o.etag } : undefined;
+    };
+    // One LTX writer (ltx-log.ts) holds each cell's epoch, TXID and page mirror.
+    // A write is acknowledged only while our node lease is still ours (self-fencing).
+    const log = ltxLog(store, { now, authorized: () => now() < validUntil });
+    const ownership = {
+        async tryAcquire(cellKey) {
+            await ensureLease();
+            const scope = scopeOf(cellKey);
+            const key = `cells/${scope}/own.json`;
+            const t0 = now();
+            if ((lostRecords.get(scope) ?? 0) > t0)
+                throw lostRecordError(scope); // still refused
+            let cur = await readJson(key);
+            // celld 0.6.3 (actor.rs read_owner_for_claim): a missing record next to LTX means the
+            // record was LOST (e.g. a lifecycle rule) — claiming epoch 1 would start the cell empty.
+            // Read once more, then refuse the cell for 10 s without asking the bucket again.
+            if (!cur && (await store.list(`cells/${scope}/ltx`)).length > 0) {
+                cur = await readJson(key);
+                if (!cur) {
+                    lostRecords.set(scope, t0 + LOST_RECORD_RECHECK_MS);
+                    throw lostRecordError(scope);
+                }
+            }
+            let epoch;
+            try {
+                if (!cur) {
+                    epoch = 1;
+                    await store.put(key, enc.encode(JSON.stringify({ node: opts.node, epoch })), {
+                        ifNoneMatch: "*",
+                    });
+                }
+                else {
+                    const holder = cur.value.node;
+                    if (holder && holder !== opts.node) {
+                        const lease = await readJson(`nodes/${holder}.json`);
+                        if (lease && lease.value.expires_ms > now())
+                            return undefined; // a live owner
+                    }
+                    epoch = cur.value.epoch + 1; // every activation advances the epoch
+                    await store.put(key, enc.encode(JSON.stringify({ node: opts.node, epoch })), {
+                        ifMatch: cur.etag,
+                    });
+                }
+            }
+            catch (e) {
+                if (e instanceof PreconditionFailedError)
+                    return undefined; // another node won the race
+                throw e;
+            }
+            log.begin(cellKey, epoch); // a new owner epoch starts a new generation
+            owned.add(cellKey);
+            return {
+                name: cellKey,
+                epoch,
+                lost: lost.signal,
+                release: async () => {
+                    const now2 = await readJson(key);
+                    if (now2?.value.node === opts.node && now2.value.epoch === epoch)
+                        await store
+                            .put(key, enc.encode(JSON.stringify({ node: "", epoch })), { ifMatch: now2.etag })
+                            .catch(() => { });
+                    log.forget(cellKey);
+                    owned.delete(cellKey);
+                },
+            };
+        },
+    };
+    // celld's waker role (wake.rs try_hold_waker): one node per fleet wakes alarms of cells that
+    // nobody owns or whose owner is dead — an advisory CAS lease in wake/waker.json; every node
+    // wakes its own cells; a live owner's cells are never hinted.
+    const holdWaker = async (ttlMs) => {
+        const key = "wake/waker.json";
+        const cur = await readJson(key);
+        const t = now();
+        if (cur && cur.value.node !== opts.node && cur.value.expires_ms > t)
+            return false;
+        try {
+            await store.put(key, enc.encode(JSON.stringify({ node: opts.node, expires_ms: t + ttlMs })), cur ? { ifMatch: cur.etag } : { ifNoneMatch: "*" });
+            return true;
+        }
+        catch (e) {
+            if (!(e instanceof PreconditionFailedError))
+                return false;
+            const again = await readJson(key);
+            return again?.value.node === opts.node && again.value.expires_ms > t;
+        }
+    };
+    const allWakes = log.wakes.bind(log);
+    const durability = Object.assign(log, {
+        async wakes() {
+            const due = await allWakes();
+            let elected;
+            const out = [];
+            for (const w of due) {
+                const own = await readJson(`cells/${scopeOf(w.cellKey)}/own.json`);
+                const owner = own?.value.node;
+                if (owner === opts.node) {
+                    out.push(w); // our own cell: always
+                    continue;
+                }
+                let ownerExpires = 0;
+                if (owner) {
+                    const lease = await readJson(`nodes/${owner}.json`);
+                    ownerExpires = lease?.value.expires_ms ?? 0;
+                }
+                elected ??= await holdWaker(opts.wakerTtlMs ?? 90_000);
+                if (!elected)
+                    continue; // unowned or dead owners are the elected waker's job
+                // A live owner fires its own alarms; the waker looks again when that owner's lease
+                // would have run out (a stopped owner's cells are then due here).
+                out.push(ownerExpires > now() ? { ...w, at: Math.max(w.at, ownerExpires + 1) } : w);
+            }
+            return out;
+        },
+    });
+    return {
+        ownership,
+        durability,
+        backup: durability,
+        /** The fleet bucket itself (R2 objects live directly in it, under `r2/<bucket>/`). */
+        objects: store,
+        /**
+         * The address celld nodes reach this node at (its celld peer server): published in the
+         * node record now, so celld routes requests for our cells here instead of refusing them.
+         */
+        /**
+         * Answers celld's signed peer probe (peer_probe.rs): an Ed25519 signature over
+         * "cells-peer-probe-v1\n<node>\n<advertised addr>\n<challenge>" by this node's probe key.
+         */
+        async probe(challenge) {
+            await probeKeyReady;
+            if (!probeKey || !/^[0-9a-f]{64}$/.test(challenge))
+                throw new Error("cannot answer the probe");
+            const payload = `cells-peer-probe-v1\n${opts.node}\n${addr}\n${challenge}`;
+            const signature = new Uint8Array(await crypto.subtle.sign("Ed25519", probeKey, new TextEncoder().encode(payload)));
+            return {
+                version: 1,
+                node: opts.node,
+                advertise: addr,
+                challenge,
+                signature: bytesToHex(signature),
+            };
+        },
+        async advertise(address) {
+            addr = address;
+            if (leaseWritten)
+                await writeLease();
+        },
+        /** Clean shutdown: stop renewing, remove this node's lease record, close the store. */
+        async close() {
+            if (renew)
+                clearTimeout(renew);
+            if (deadline)
+                clearTimeout(deadline);
+            if (leaseWritten)
+                await store.delete(`nodes/${opts.node}.json`).catch(() => { });
+            store.close?.();
+        },
+    };
+}
+//# sourceMappingURL=celld-cells.js.map

package/dist/bucket/celld-cells.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"celld-cells.js","sourceRoot":"","sources":["../../src/bucket/celld-cells.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,qBAAqB,CAAC;AACjD,OAAO,EAAE,OAAO,EAAE,MAAM,yBAAyB,CAAC;AAIlD,OAAO,EAAE,MAAM,EAAE,MAAM,cAAc,CAAC;AACtC,OAAO,EAAoB,uBAAuB,EAAE,MAAM,mBAAmB,CAAC;AA0B9E,MAAM,GAAG,GAAG,IAAI,WAAW,EAAE,CAAC;AAC9B,MAAM,GAAG,GAAG,IAAI,WAAW,EAAE,CAAC;AAE9B,wFAAwF;AACxF,MAAM,CAAC,MAAM,sBAAsB,GAAG,MAAM,CAAC;AAC7C,MAAM,eAAe,GAAG,CAAC,KAAa,EAAE,EAAE,CACxC,MAAM,CAAC,MAAM,CACX,IAAI,KAAK,CACP,gCAAgC,KAAK,uDAAuD;IAC1F,SAAS,KAAK,4BAA4B,KAAK,4CAA4C;IAC3F,8EAA8E,CACjF,EACD,EAAE,IAAI,EAAE,0BAA0B,EAAE,CACrC,CAAC;AAEJ,mGAAmG;AACnG,MAAM,UAAU,WAAW,CAAC,KAAuC,EAAE,IAAwB;IAC3F,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC,CAAC;IAC3C,MAAM,GAAG,GAAG,IAAI,CAAC,UAAU,IAAI,MAAM,CAAC;IACtC,MAAM,IAAI,GAAG,IAAI,eAAe,EAAE,CAAC;IACnC,IAAI,KAAgD,CAAC;IACrD,IAAI,QAAmD,CAAC;IACxD,IAAI,YAAuC,CAAC;IAE5C,gGAAgG;IAChG,8FAA8F;IAC9F,0FAA0F;IAC1F,0FAA0F;IAC1F,2CAA2C;IAC3C,EAAE;IACF,0FAA0F;IAC1F,uFAAuF;IACvF,yFAAyF;IACzF,0FAA0F;IAC1F,IAAI,IAAI,GAAG,IAAI,CAAC,IAAI,IAAI,GAAG,IAAI,CAAC,IAAI,kBAAkB,CAAC;IACvD,0FAA0F;IAC1F,6FAA6F;IAC7F,yCAAyC;IACzC,IAAI,UAAU,GAAG,UAAU,CAAC,MAAM,CAAC,eAAe,CAAC,IAAI,UAAU,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC;IACxE,IAAI,QAA+B,CAAC;IACpC,MAAM,aAAa,GAAG,CAAC,KAAK,IAAI,EAAE;QAChC,IAAI,CAAC;YACH,MAAM,IAAI,GAAG,CAAC,MAAM,MAAM,CAAC,MAAM,CAAC,WAAW,CAAC,EAAE,IAAI,EAAE,SAAS,EAAE,EAAE,IAAI,EAAE;gBACvE,MAAM;gBACN,QAAQ;aACT,CAAC,CAAkB,CAAC;YACrB,QAAQ,GAAG,IAAI,CAAC,UAAU,CAAC;YAC3B,UAAU,GAAG,UAAU,CAAC,IAAI,UAAU,CAAC,MAAM,MAAM,CAAC,MAAM,CAAC,SAAS,CAAC,KAAK,EAAE,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC;QAChG,CAAC;QAAC,MAAM,CAAC;YACP,wFAAwF;QAC1F,CAAC;IACH,CAAC,CAAC,EAAE,CAAC;IACL,IAAI,UAAU,GAAG,CAAC,CAAC;IACnB,MAAM,UAAU,GAAG,KAAK,IAAI,EAAE;QAC5B,MAAM,CAAC,GAAG,GAAG,EAAE,CAAC;QAChB,MAAM,IAAI,GAAG;YACX,IAAI,EAAE,IAAI,CAAC,IAAI;YACf,UAAU,EAAE,CAAC,GAAG,GAAG;YACnB,IAAI;YACJ,gBAAgB,EAAE,UAAU;YAC5B,aAAa,EAAE,CAAC;YAChB,aAAa,EAAE,KAAK;YACpB,0BAA0B,EAAE,UAAU;YACtC,IAAI,EAAE;gBACJ,UAAU,EAAE,CAAC;gBACb,WAAW,EAAE,KAAK,CAAC,IAAI;gBACvB,gBAAgB,EAAE,CAAC;gBACnB,aAAa,EAAE,CAAC;gBAChB,cAAc,EAAE,KAAK,CAAC,IAAI;gBAC1B,eAAe,EAAE,CAAC;gBAClB,SAAS,EAAE,CAAC;gBACZ,YAAY,EAAE,CAAC;gBACf,gBAAgB,EAAE,CAAC;gBACnB,QAAQ,EAAE,CAAC;gBACX,QAAQ,EAAE,CAAC;gBACX,SAAS,EAAE,IAAI;gBACf,eAAe,EAAE,KAAK;gBACtB,UAAU,EAAE,CAAC;gBACb,SAAS,EAAE,CAAC;gBACZ,gBAAgB,EAAE,KAAK;gBACvB,QAAQ,EAAE,KAAK;aAChB;SACF,CAAC;QACF,MAAM,KAAK,CAAC,GAAG,CAAC,SAAS,IAAI,CAAC,IAAI,OAAO,EAAE,GAAG,CAAC,MAAM,CAAC,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;QAC7E,yFAAyF;QACzF,yFAAyF;QACzF,oEAAoE;QACpE,UAAU,GAAG,CAAC,GAAG,GAAG,GAAG,IAAI,CAAC,GAAG,CAAC,KAAK,EAAE,GAAG,GAAG,CAAC,CAAC,CAAC;IAClD,CAAC,CAAC;IACF,MAAM,KAAK,GAAG,IAAI,GAAG,EAAU,CAAC;IAChC,qFAAqF;IACrF,MAAM,WAAW,GAAG,IAAI,GAAG,EAAkB,CAAC;IAC9C,MAAM,WAAW,GAAG,GAAG,EAAE;QACvB,YAAY,KAAK,aAAa,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC,IAAI,CAAC,GAAG,EAAE;YACxD,MAAM,IAAI,GAAG,GAAG,EAAE;gBAChB,KAAK,GAAG,UAAU,CAAC,GAAG,EAAE;oBACtB,UAAU,EAAE,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC;gBAChD,CAAC,EAAE,GAAG,GAAG,CAAC,CAAC,CAAC;gBACZ,mFAAmF;gBACnF,+DAA+D;gBAC/D,IAAI,QAAQ;oBAAE,YAAY,CAAC,QAAQ,CAAC,CAAC;gBACrC,QAAQ,GAAG,UAAU,CACnB,GAAG,EAAE;oBACH,IAAI,GAAG,EAAE,IAAI,UAAU;wBACrB,IAAI,CAAC,KAAK,CAAC,IAAI,KAAK,CAAC,QAAQ,IAAI,CAAC,IAAI,yBAAyB,CAAC,CAAC,CAAC;gBACtE,CAAC,EACD,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,UAAU,GAAG,GAAG,EAAE,CAAC,CAChC,CAAC;gBACD,QAAmC,CAAC,KAAK,EAAE,EAAE,CAAC;gBAC9C,KAAgC,CAAC,KAAK,EAAE,EAAE,CAAC;YAC9C,CAAC,CAAC;YACF,IAAI,EAAE,CAAC;QACT,CAAC,CAAC,CAAC;QACH,OAAO,YAAY,CAAC;IACtB,CAAC,CAAC;IAEF,MAAM,QAAQ,GAAG,KAAK,EAAK,GAAW,EAAE,EAAE;QACxC,MAAM,CAAC,GAAG,MAAM,KAAK,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;QAC/B,OAAO,CAAC,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC,IAAI,CAAC,CAAM,EAAE,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC;IACtF,CAAC,CAAC;IAEF,6EAA6E;IAC7E,kFAAkF;IAClF,MAAM,GAAG,GAAG,MAAM,CAAC,KAAK,EAAE,EAAE,GAAG,EAAE,UAAU,EAAE,GAAG,EAAE,CAAC,GAAG,EAAE,GAAG,UAAU,EAAE,CAAC,CAAC;IAEzE,MAAM,SAAS,GAAG;QAChB,KAAK,CAAC,UAAU,CAAC,OAAe;YAC9B,MAAM,WAAW,EAAE,CAAC;YACpB,MAAM,KAAK,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;YAC/B,MAAM,GAAG,GAAG,SAAS,KAAK,WAAW,CAAC;YACtC,MAAM,EAAE,GAAG,GAAG,EAAE,CAAC;YACjB,IAAI,CAAC,WAAW,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,GAAG,EAAE;gBAAE,MAAM,eAAe,CAAC,KAAK,CAAC,CAAC,CAAC,gBAAgB;YACtF,IAAI,GAAG,GAAG,MAAM,QAAQ,CAAkC,GAAG,CAAC,CAAC;YAC/D,sFAAsF;YACtF,yFAAyF;YACzF,iFAAiF;YACjF,IAAI,CAAC,GAAG,IAAI,CAAC,MAAM,KAAK,CAAC,IAAI,CAAC,SAAS,KAAK,MAAM,CAAC,CAAC,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;gBAChE,GAAG,GAAG,MAAM,QAAQ,CAAkC,GAAG,CAAC,CAAC;gBAC3D,IAAI,CAAC,GAAG,EAAE,CAAC;oBACT,WAAW,CAAC,GAAG,CAAC,KAAK,EAAE,EAAE,GAAG,sBAAsB,CAAC,CAAC;oBACpD,MAAM,eAAe,CAAC,KAAK,CAAC,CAAC;gBAC/B,CAAC;YACH,CAAC;YACD,IAAI,KAAa,CAAC;YAClB,IAAI,CAAC;gBACH,IAAI,CAAC,GAAG,EAAE,CAAC;oBACT,KAAK,GAAG,CAAC,CAAC;oBACV,MAAM,KAAK,CAAC,GAAG,CAAC,GAAG,EAAE,GAAG,CAAC,MAAM,CAAC,IAAI,CAAC,SAAS,CAAC,EAAE,IAAI,EAAE,IAAI,CAAC,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC,EAAE;wBAC3E,WAAW,EAAE,GAAG;qBACjB,CAAC,CAAC;gBACL,CAAC;qBAAM,CAAC;oBACN,MAAM,MAAM,GAAG,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC;oBAC9B,IAAI,MAAM,IAAI,MAAM,KAAK,IAAI,CAAC,IAAI,EAAE,CAAC;wBACnC,MAAM,KAAK,GAAG,MAAM,QAAQ,CAAyB,SAAS,MAAM,OAAO,CAAC,CAAC;wBAC7E,IAAI,KAAK,IAAI,KAAK,CAAC,KAAK,CAAC,UAAU,GAAG,GAAG,EAAE;4BAAE,OAAO,SAAS,CAAC,CAAC,eAAe;oBAChF,CAAC;oBACD,KAAK,GAAG,GAAG,CAAC,KAAK,CAAC,KAAK,GAAG,CAAC,CAAC,CAAC,sCAAsC;oBACnE,MAAM,KAAK,CAAC,GAAG,CAAC,GAAG,EAAE,GAAG,CAAC,MAAM,CAAC,IAAI,CAAC,SAAS,CAAC,EAAE,IAAI,EAAE,IAAI,CAAC,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC,EAAE;wBAC3E,OAAO,EAAE,GAAG,CAAC,IAAI;qBAClB,CAAC,CAAC;gBACL,CAAC;YACH,CAAC;YAAC,OAAO,CAAC,EAAE,CAAC;gBACX,IAAI,CAAC,YAAY,uBAAuB;oBAAE,OAAO,SAAS,CAAC,CAAC,4BAA4B;gBACxF,MAAM,CAAC,CAAC;YACV,CAAC;YACD,GAAG,CAAC,KAAK,CAAC,OAAO,EAAE,KAAK,CAAC,CAAC,CAAC,4CAA4C;YACvE,KAAK,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;YACnB,OAAO;gBACL,IAAI,EAAE,OAAO;gBACb,KAAK;gBACL,IAAI,EAAE,IAAI,CAAC,MAAM;gBACjB,OAAO,EAAE,KAAK,IAAI,EAAE;oBAClB,MAAM,IAAI,GAAG,MAAM,QAAQ,CAAkC,GAAG,CAAC,CAAC;oBAClE,IAAI,IAAI,EAAE,KAAK,CAAC,IAAI,KAAK,IAAI,CAAC,IAAI,IAAI,IAAI,CAAC,KAAK,CAAC,KAAK,KAAK,KAAK;wBAC9D,MAAM,KAAK;6BACR,GAAG,CAAC,GAAG,EAAE,GAAG,CAAC,MAAM,CAAC,IAAI,CAAC,SAAS,CAAC,EAAE,IAAI,EAAE,EAAE,EAAE,KAAK,EAAE,CAAC,CAAC,EAAE,EAAE,OAAO,EAAE,IAAI,CAAC,IAAI,EAAE,CAAC;6BACjF,KAAK,CAAC,GAAG,EAAE,GAAE,CAAC,CAAC,CAAC;oBACrB,GAAG,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;oBACpB,KAAK,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;gBACxB,CAAC;aACF,CAAC;QACJ,CAAC;KACF,CAAC;IAEF,6FAA6F;IAC7F,4FAA4F;IAC5F,8DAA8D;IAC9D,MAAM,SAAS,GAAG,KAAK,EAAE,KAAa,EAAE,EAAE;QACxC,MAAM,GAAG,GAAG,iBAAiB,CAAC;QAC9B,MAAM,GAAG,GAAG,MAAM,QAAQ,CAAuC,GAAG,CAAC,CAAC;QACtE,MAAM,CAAC,GAAG,GAAG,EAAE,CAAC;QAChB,IAAI,GAAG,IAAI,GAAG,CAAC,KAAK,CAAC,IAAI,KAAK,IAAI,CAAC,IAAI,IAAI,GAAG,CAAC,KAAK,CAAC,UAAU,GAAG,CAAC;YAAE,OAAO,KAAK,CAAC;QAClF,IAAI,CAAC;YACH,MAAM,KAAK,CAAC,GAAG,CACb,GAAG,EACH,GAAG,CAAC,MAAM,CAAC,IAAI,CAAC,SAAS,CAAC,EAAE,IAAI,EAAE,IAAI,CAAC,IAAI,EAAE,UAAU,EAAE,CAAC,GAAG,KAAK,EAAE,CAAC,CAAC,EACtE,GAAG,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,GAAG,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,WAAW,EAAE,GAAG,EAAE,CACnD,CAAC;YACF,OAAO,IAAI,CAAC;QACd,CAAC;QAAC,OAAO,CAAC,EAAE,CAAC;YACX,IAAI,CAAC,CAAC,CAAC,YAAY,uBAAuB,CAAC;gBAAE,OAAO,KAAK,CAAC;YAC1D,MAAM,KAAK,GAAG,MAAM,QAAQ,CAAuC,GAAG,CAAC,CAAC;YACxE,OAAO,KAAK,EAAE,KAAK,CAAC,IAAI,KAAK,IAAI,CAAC,IAAI,IAAI,KAAK,CAAC,KAAK,CAAC,UAAU,GAAG,CAAC,CAAC;QACvE,CAAC;IACH,CAAC,CAAC;IACF,MAAM,QAAQ,GAAG,GAAG,CAAC,KAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IACtC,MAAM,UAAU,GAAG,MAAM,CAAC,MAAM,CAAC,GAAG,EAAE;QACpC,KAAK,CAAC,KAAK;YACT,MAAM,GAAG,GAAG,MAAM,QAAQ,EAAE,CAAC;YAC7B,IAAI,OAA4B,CAAC;YACjC,MAAM,GAAG,GAAe,EAAE,CAAC;YAC3B,KAAK,MAAM,CAAC,IAAI,GAAG,EAAE,CAAC;gBACpB,MAAM,GAAG,GAAG,MAAM,QAAQ,CAAmB,SAAS,OAAO,CAAC,CAAC,CAAC,OAAO,CAAC,WAAW,CAAC,CAAC;gBACrF,MAAM,KAAK,GAAG,GAAG,EAAE,KAAK,CAAC,IAAI,CAAC;gBAC9B,IAAI,KAAK,KAAK,IAAI,CAAC,IAAI,EAAE,CAAC;oBACxB,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,uBAAuB;oBACpC,SAAS;gBACX,CAAC;gBACD,IAAI,YAAY,GAAG,CAAC,CAAC;gBACrB,IAAI,KAAK,EAAE,CAAC;oBACV,MAAM,KAAK,GAAG,MAAM,QAAQ,CAAyB,SAAS,KAAK,OAAO,CAAC,CAAC;oBAC5E,YAAY,GAAG,KAAK,EAAE,KAAK,CAAC,UAAU,IAAI,CAAC,CAAC;gBAC9C,CAAC;gBACD,OAAO,KAAK,MAAM,SAAS,CAAC,IAAI,CAAC,UAAU,IAAI,MAAM,CAAC,CAAC;gBACvD,IAAI,CAAC,OAAO;oBAAE,SAAS,CAAC,qDAAqD;gBAC7E,mFAAmF;gBACnF,kEAAkE;gBAClE,GAAG,CAAC,IAAI,CAAC,YAAY,GAAG,GAAG,EAAE,CAAC,CAAC,CAAC,EAAE,GAAG,CAAC,EAAE,EAAE,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,YAAY,GAAG,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;YACtF,CAAC;YACD,OAAO,GAAG,CAAC;QACb,CAAC;KACF,CAAC,CAAC;IAEH,OAAO;QACL,SAAS;QACT,UAAU;QACV,MAAM,EAAE,UAAU;QAClB,sFAAsF;QACtF,OAAO,EAAE,KAAK;QACd;;;WAGG;QACH;;;WAGG;QACH,KAAK,CAAC,KAAK,CAAC,SAAiB;YAC3B,MAAM,aAAa,CAAC;YACpB,IAAI,CAAC,QAAQ,IAAI,CAAC,gBAAgB,CAAC,IAAI,CAAC,SAAS,CAAC;gBAChD,MAAM,IAAI,KAAK,CAAC,yBAAyB,CAAC,CAAC;YAC7C,MAAM,OAAO,GAAG,wBAAwB,IAAI,CAAC,IAAI,KAAK,IAAI,KAAK,SAAS,EAAE,CAAC;YAC3E,MAAM,SAAS,GAAG,IAAI,UAAU,CAC9B,MAAM,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,SAAS,EAAE,QAAQ,EAAE,IAAI,WAAW,EAAE,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,CACjF,CAAC;YACF,OAAO;gBACL,OAAO,EAAE,CAAC;gBACV,IAAI,EAAE,IAAI,CAAC,IAAI;gBACf,SAAS,EAAE,IAAI;gBACf,SAAS;gBACT,SAAS,EAAE,UAAU,CAAC,SAAS,CAAC;aACjC,CAAC;QACJ,CAAC;QACD,KAAK,CAAC,SAAS,CAAC,OAAe;YAC7B,IAAI,GAAG,OAAO,CAAC;YACf,IAAI,YAAY;gBAAE,MAAM,UAAU,EAAE,CAAC;QACvC,CAAC;QACD,uFAAuF;QACvF,KAAK,CAAC,KAAK;YACT,IAAI,KAAK;gBAAE,YAAY,CAAC,KAAK,CAAC,CAAC;YAC/B,IAAI,QAAQ;gBAAE,YAAY,CAAC,QAAQ,CAAC,CAAC;YACrC,IAAI,YAAY;gBAAE,MAAM,KAAK,CAAC,MAAM,CAAC,SAAS,IAAI,CAAC,IAAI,OAAO,CAAC,CAAC,KAAK,CAAC,GAAG,EAAE,GAAE,CAAC,CAAC,CAAC;YAChF,KAAK,CAAC,KAAK,EAAE,EAAE,CAAC;QAClB,CAAC;KACF,CAAC;AACJ,CAAC","sourcesContent":["import { bytesToHex } from \"@noble/hashes/utils\";\nimport { scopeOf } from \"../core/celld-schema.js\";\nimport { decodeLtx, encodeLtx, ltxFileName } from \"../ltx/ltx.js\";\nimport type { BackupInfo, CellBackup, CellDurability } from \"../ports.js\";\nimport { equal, pad16, pageSizeOf, toRollback } from \"./celld-format.js\";\nimport { ltxLog } from \"./ltx-log.js\";\nimport { type ObjectStore, PreconditionFailedError } from \"./object-store.js\";\n\n/**\n * Cells stored the way celld stores them (docs/guarantees.md, and the keys celld dev writes\n * in `.celld/dev/objects.sqlite3`), on any ObjectStore:\n *\n *   cells/<Class>:<idHex>/own.json                     {\"node\",\"epoch\"}: ownership record\n *   cells/<Class>:<idHex>/ltx/e<epoch>/0000/<min>-<max>.ltx   LTX v3, legacy LZ4 frames\n *   nodes/<node>.json                                  {\"node\",\"expires_ms\",\"addr\",…}: node lease\n *\n * Ownership: an activation creates the record (If-None-Match) or advances its epoch with a\n * compare-and-swap (If-Match), taking over only from a node whose lease expired. Durability:\n * each committed transaction becomes an LTX file in the cell's current epoch prefix — the\n * first one a snapshot (TXID 1), then the changed pages — and the output gate waits for the\n * PUT. Restore: the newest epoch that starts with a snapshot, its files in TXID order.\n */\nexport interface CelldBucketOptions {\n  /** This node's name (celld: `dev-…` / the fleet node name). */\n  node: string;\n  addr?: string;\n  leaseTtlMs?: number;\n  now?: () => number;\n  /** The waker-role lease (celld: 3 × its due-scan tick); match 3 × the runtime's wakePollMs. */\n  wakerTtlMs?: number;\n}\n\nconst enc = new TextEncoder();\nconst dec = new TextDecoder();\n\n/** celld 0.6.3: how long a node refuses a cell whose ownership record it found lost. */\nexport const LOST_RECORD_RECHECK_MS = 10_000;\nconst lostRecordError = (scope: string) =>\n  Object.assign(\n    new Error(\n      `ownership record lost: cells/${scope}/own.json is missing, but the bucket holds LTX under ` +\n        `cells/${scope}/ltx/; refusing to claim ${scope} as a new cell (celld docs/guarantees.md: ` +\n        `write a released record {\"node\": \"\", \"epoch\": <newest epoch>} to restore it)`,\n    ),\n    { name: \"OwnershipRecordLostError\" },\n  );\n\n/** The bucket's `close()` also closes `store` (when it has a `close`): pass a store of its own. */\nexport function celldBucket(store: ObjectStore & { close?(): void }, opts: CelldBucketOptions) {\n  const now = opts.now ?? (() => Date.now());\n  const ttl = opts.leaseTtlMs ?? 10_000;\n  const lost = new AbortController();\n  let renew: ReturnType<typeof setTimeout> | undefined;\n  let deadline: ReturnType<typeof setTimeout> | undefined;\n  let leaseWritten: Promise<void> | undefined;\n\n  /** nodes/<node>.json, renewed every ttl/3; a failed renewal stops every cell (self-fencing). */\n  // celld decodes every node record (ownership_store.rs NodeLeaseWire / NodeLoadWire): a record\n  // missing a required load field breaks its fleet posture repair. This one is complete. It\n  // reports pressure and zero placement weight, so celld never offers this node a cell — it\n  // takes cells only when a request arrives.\n  //\n  // The address must not be empty: celld treats a live owner WITHOUT an address as dead and\n  // takes its cells over (logic/lib.rs apply_node_lease_result) — a split brain. With an\n  // address celld routes a request for our cell to it; a node that does not accept celld's\n  // peer protocol (a browser) gets an unroutable placeholder, so the request fails instead.\n  let addr = opts.addr || `${opts.node}.cellb.invalid:9`;\n  // celld's per-process generation is its signed-probe public key (Ed25519, peer_probe.rs):\n  // `probe_public_key` = `ownership_index_generation`. A real key lets `celld diagnose --peer`\n  // verify that a probe reached this node.\n  let generation = bytesToHex(crypto.getRandomValues(new Uint8Array(32)));\n  let probeKey: CryptoKey | undefined;\n  const probeKeyReady = (async () => {\n    try {\n      const pair = (await crypto.subtle.generateKey({ name: \"Ed25519\" }, true, [\n        \"sign\",\n        \"verify\",\n      ])) as CryptoKeyPair;\n      probeKey = pair.privateKey;\n      generation = bytesToHex(new Uint8Array(await crypto.subtle.exportKey(\"raw\", pair.publicKey)));\n    } catch {\n      // no Ed25519 in this WebCrypto: the record keeps a random generation (probes then fail)\n    }\n  })();\n  let validUntil = 0;\n  const writeLease = async () => {\n    const t = now();\n    const body = {\n      node: opts.node,\n      expires_ms: t + ttl,\n      addr,\n      probe_public_key: generation,\n      peer_protocol: 5,\n      paced_handoff: false,\n      ownership_index_generation: generation,\n      load: {\n        sampled_ms: t,\n        owned_cells: owned.size,\n        placement_weight: 0,\n        bucket_format: 2,\n        resident_cells: owned.size,\n        host_websockets: 0,\n        rss_bytes: 0,\n        in_use_bytes: 0,\n        cpu_percent_x100: 0,\n        open_fds: 0,\n        fd_limit: 0,\n        pressured: true,\n        memory_headroom: false,\n        shed_cells: 0,\n        restoring: 0,\n        rebalance_paused: false,\n        draining: false,\n      },\n    };\n    await store.put(`nodes/${opts.node}.json`, enc.encode(JSON.stringify(body)));\n    // Our authority lasts until the record we just wrote expires — minus a margin, so a node\n    // that stalls (a paused process, a frozen tab) stops acknowledging before celld may take\n    // over: celld waits for expires_ms; we stop at expires_ms - margin.\n    validUntil = t + ttl - Math.min(1_000, ttl / 4);\n  };\n  const owned = new Set<string>();\n  /** Cells whose ownership record was found lost, with the time their refusal ends. */\n  const lostRecords = new Map<string, number>();\n  const ensureLease = () => {\n    leaseWritten ??= probeKeyReady.then(writeLease).then(() => {\n      const tick = () => {\n        renew = setTimeout(() => {\n          writeLease().then(tick, (e) => lost.abort(e));\n        }, ttl / 3);\n        // If renewals stop arriving (a stalled process, an unreachable bucket), every cell\n        // stops at the local deadline — before celld may take it over.\n        if (deadline) clearTimeout(deadline);\n        deadline = setTimeout(\n          () => {\n            if (now() >= validUntil)\n              lost.abort(new Error(`node ${opts.node}: lease deadline passed`));\n          },\n          Math.max(0, validUntil - now()),\n        );\n        (deadline as { unref?: () => void }).unref?.();\n        (renew as { unref?: () => void }).unref?.();\n      };\n      tick();\n    });\n    return leaseWritten;\n  };\n\n  const readJson = async <T>(key: string) => {\n    const o = await store.get(key);\n    return o ? { value: JSON.parse(dec.decode(o.body)) as T, etag: o.etag } : undefined;\n  };\n\n  // One LTX writer (ltx-log.ts) holds each cell's epoch, TXID and page mirror.\n  // A write is acknowledged only while our node lease is still ours (self-fencing).\n  const log = ltxLog(store, { now, authorized: () => now() < validUntil });\n\n  const ownership = {\n    async tryAcquire(cellKey: string) {\n      await ensureLease();\n      const scope = scopeOf(cellKey);\n      const key = `cells/${scope}/own.json`;\n      const t0 = now();\n      if ((lostRecords.get(scope) ?? 0) > t0) throw lostRecordError(scope); // still refused\n      let cur = await readJson<{ node: string; epoch: number }>(key);\n      // celld 0.6.3 (actor.rs read_owner_for_claim): a missing record next to LTX means the\n      // record was LOST (e.g. a lifecycle rule) — claiming epoch 1 would start the cell empty.\n      // Read once more, then refuse the cell for 10 s without asking the bucket again.\n      if (!cur && (await store.list(`cells/${scope}/ltx`)).length > 0) {\n        cur = await readJson<{ node: string; epoch: number }>(key);\n        if (!cur) {\n          lostRecords.set(scope, t0 + LOST_RECORD_RECHECK_MS);\n          throw lostRecordError(scope);\n        }\n      }\n      let epoch: number;\n      try {\n        if (!cur) {\n          epoch = 1;\n          await store.put(key, enc.encode(JSON.stringify({ node: opts.node, epoch })), {\n            ifNoneMatch: \"*\",\n          });\n        } else {\n          const holder = cur.value.node;\n          if (holder && holder !== opts.node) {\n            const lease = await readJson<{ expires_ms: number }>(`nodes/${holder}.json`);\n            if (lease && lease.value.expires_ms > now()) return undefined; // a live owner\n          }\n          epoch = cur.value.epoch + 1; // every activation advances the epoch\n          await store.put(key, enc.encode(JSON.stringify({ node: opts.node, epoch })), {\n            ifMatch: cur.etag,\n          });\n        }\n      } catch (e) {\n        if (e instanceof PreconditionFailedError) return undefined; // another node won the race\n        throw e;\n      }\n      log.begin(cellKey, epoch); // a new owner epoch starts a new generation\n      owned.add(cellKey);\n      return {\n        name: cellKey,\n        epoch,\n        lost: lost.signal,\n        release: async () => {\n          const now2 = await readJson<{ node: string; epoch: number }>(key);\n          if (now2?.value.node === opts.node && now2.value.epoch === epoch)\n            await store\n              .put(key, enc.encode(JSON.stringify({ node: \"\", epoch })), { ifMatch: now2.etag })\n              .catch(() => {});\n          log.forget(cellKey);\n          owned.delete(cellKey);\n        },\n      };\n    },\n  };\n\n  // celld's waker role (wake.rs try_hold_waker): one node per fleet wakes alarms of cells that\n  // nobody owns or whose owner is dead — an advisory CAS lease in wake/waker.json; every node\n  // wakes its own cells; a live owner's cells are never hinted.\n  const holdWaker = async (ttlMs: number) => {\n    const key = \"wake/waker.json\";\n    const cur = await readJson<{ node: string; expires_ms: number }>(key);\n    const t = now();\n    if (cur && cur.value.node !== opts.node && cur.value.expires_ms > t) return false;\n    try {\n      await store.put(\n        key,\n        enc.encode(JSON.stringify({ node: opts.node, expires_ms: t + ttlMs })),\n        cur ? { ifMatch: cur.etag } : { ifNoneMatch: \"*\" },\n      );\n      return true;\n    } catch (e) {\n      if (!(e instanceof PreconditionFailedError)) return false;\n      const again = await readJson<{ node: string; expires_ms: number }>(key);\n      return again?.value.node === opts.node && again.value.expires_ms > t;\n    }\n  };\n  const allWakes = log.wakes!.bind(log);\n  const durability = Object.assign(log, {\n    async wakes() {\n      const due = await allWakes();\n      let elected: boolean | undefined;\n      const out: typeof due = [];\n      for (const w of due) {\n        const own = await readJson<{ node: string }>(`cells/${scopeOf(w.cellKey)}/own.json`);\n        const owner = own?.value.node;\n        if (owner === opts.node) {\n          out.push(w); // our own cell: always\n          continue;\n        }\n        let ownerExpires = 0;\n        if (owner) {\n          const lease = await readJson<{ expires_ms: number }>(`nodes/${owner}.json`);\n          ownerExpires = lease?.value.expires_ms ?? 0;\n        }\n        elected ??= await holdWaker(opts.wakerTtlMs ?? 90_000);\n        if (!elected) continue; // unowned or dead owners are the elected waker's job\n        // A live owner fires its own alarms; the waker looks again when that owner's lease\n        // would have run out (a stopped owner's cells are then due here).\n        out.push(ownerExpires > now() ? { ...w, at: Math.max(w.at, ownerExpires + 1) } : w);\n      }\n      return out;\n    },\n  });\n\n  return {\n    ownership,\n    durability,\n    backup: durability,\n    /** The fleet bucket itself (R2 objects live directly in it, under `r2/<bucket>/`). */\n    objects: store,\n    /**\n     * The address celld nodes reach this node at (its celld peer server): published in the\n     * node record now, so celld routes requests for our cells here instead of refusing them.\n     */\n    /**\n     * Answers celld's signed peer probe (peer_probe.rs): an Ed25519 signature over\n     * \"cells-peer-probe-v1\\n<node>\\n<advertised addr>\\n<challenge>\" by this node's probe key.\n     */\n    async probe(challenge: string) {\n      await probeKeyReady;\n      if (!probeKey || !/^[0-9a-f]{64}$/.test(challenge))\n        throw new Error(\"cannot answer the probe\");\n      const payload = `cells-peer-probe-v1\\n${opts.node}\\n${addr}\\n${challenge}`;\n      const signature = new Uint8Array(\n        await crypto.subtle.sign(\"Ed25519\", probeKey, new TextEncoder().encode(payload)),\n      );\n      return {\n        version: 1,\n        node: opts.node,\n        advertise: addr,\n        challenge,\n        signature: bytesToHex(signature),\n      };\n    },\n    async advertise(address: string) {\n      addr = address;\n      if (leaseWritten) await writeLease();\n    },\n    /** Clean shutdown: stop renewing, remove this node's lease record, close the store. */\n    async close() {\n      if (renew) clearTimeout(renew);\n      if (deadline) clearTimeout(deadline);\n      if (leaseWritten) await store.delete(`nodes/${opts.node}.json`).catch(() => {});\n      store.close?.();\n    },\n  };\n}\n"]}

package/dist/bucket/celld-format.d.ts

@@ -0,0 +1,10 @@
+/** Byte and name helpers shared by the celld bucket layout (celld-cells) and its LTX log. */
+export declare const pad16: (n: bigint) => string;
+export declare const equal: (a: Uint8Array, b: Uint8Array) => boolean;
+export declare const pageSizeOf: (image: Uint8Array) => number;
+/**
+ * celld's cells run in WAL mode (header bytes 18–19 = 2); a restored image is switched to a
+ * rollback journal (1/1) so any driver can open it from memory; SQLite rewrites them when a
+ * runtime sets WAL again.
+ */
+export declare const toRollback: (image: Uint8Array) => Uint8Array<ArrayBufferLike>;

package/dist/bucket/celld-format.js

@@ -0,0 +1,27 @@
+/** Byte and name helpers shared by the celld bucket layout (celld-cells) and its LTX log. */
+export const pad16 = (n) => n.toString(16).padStart(16, "0");
+export const equal = (a, b) => {
+    if (a.length !== b.length)
+        return false;
+    for (let i = 0; i < a.length; i++)
+        if (a[i] !== b[i])
+            return false;
+    return true;
+};
+export const pageSizeOf = (image) => {
+    const v = (image[16] << 8) | image[17];
+    return v === 1 ? 65536 : v;
+};
+/**
+ * celld's cells run in WAL mode (header bytes 18–19 = 2); a restored image is switched to a
+ * rollback journal (1/1) so any driver can open it from memory; SQLite rewrites them when a
+ * runtime sets WAL again.
+ */
+export const toRollback = (image) => {
+    if (image.length > 19 && image[18] === 2) {
+        image[18] = 1;
+        image[19] = 1;
+    }
+    return image;
+};
+//# sourceMappingURL=celld-format.js.map

package/dist/bucket/celld-format.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"celld-format.js","sourceRoot":"","sources":["../../src/bucket/celld-format.ts"],"names":[],"mappings":"AAAA,6FAA6F;AAC7F,MAAM,CAAC,MAAM,KAAK,GAAG,CAAC,CAAS,EAAE,EAAE,CAAC,CAAC,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC,QAAQ,CAAC,EAAE,EAAE,GAAG,CAAC,CAAC;AACrE,MAAM,CAAC,MAAM,KAAK,GAAG,CAAC,CAAa,EAAE,CAAa,EAAE,EAAE;IACpD,IAAI,CAAC,CAAC,MAAM,KAAK,CAAC,CAAC,MAAM;QAAE,OAAO,KAAK,CAAC;IACxC,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,CAAC,CAAC,MAAM,EAAE,CAAC,EAAE;QAAE,IAAI,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;YAAE,OAAO,KAAK,CAAC;IACnE,OAAO,IAAI,CAAC;AACd,CAAC,CAAC;AACF,MAAM,CAAC,MAAM,UAAU,GAAG,CAAC,KAAiB,EAAE,EAAE;IAC9C,MAAM,CAAC,GAAG,CAAC,KAAK,CAAC,EAAE,CAAC,IAAI,CAAC,CAAC,GAAG,KAAK,CAAC,EAAE,CAAC,CAAC;IACvC,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC;AAC7B,CAAC,CAAC;AACF;;;;GAIG;AACH,MAAM,CAAC,MAAM,UAAU,GAAG,CAAC,KAAiB,EAAE,EAAE;IAC9C,IAAI,KAAK,CAAC,MAAM,GAAG,EAAE,IAAI,KAAK,CAAC,EAAE,CAAC,KAAK,CAAC,EAAE,CAAC;QACzC,KAAK,CAAC,EAAE,CAAC,GAAG,CAAC,CAAC;QACd,KAAK,CAAC,EAAE,CAAC,GAAG,CAAC,CAAC;IAChB,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC,CAAC","sourcesContent":["/** Byte and name helpers shared by the celld bucket layout (celld-cells) and its LTX log. */\nexport const pad16 = (n: bigint) => n.toString(16).padStart(16, \"0\");\nexport const equal = (a: Uint8Array, b: Uint8Array) => {\n  if (a.length !== b.length) return false;\n  for (let i = 0; i < a.length; i++) if (a[i] !== b[i]) return false;\n  return true;\n};\nexport const pageSizeOf = (image: Uint8Array) => {\n  const v = (image[16] << 8) | image[17];\n  return v === 1 ? 65536 : v;\n};\n/**\n * celld's cells run in WAL mode (header bytes 18–19 = 2); a restored image is switched to a\n * rollback journal (1/1) so any driver can open it from memory; SQLite rewrites them when a\n * runtime sets WAL again.\n */\nexport const toRollback = (image: Uint8Array) => {\n  if (image.length > 19 && image[18] === 2) {\n    image[18] = 1;\n    image[19] = 1;\n  }\n  return image;\n};\n"]}

package/dist/bucket/idb-object-store.d.ts

@@ -0,0 +1,9 @@
+/**
+ * A bucket in IndexedDB: an ObjectStore whose conditional writes are atomic across every tab
+ * and worker of the origin (each put checks its condition and writes in one readwrite
+ * transaction, and IndexedDB serializes overlapping readwrite transactions). No synchronous
+ * file handle is involved, so any number of workers can use it at once: with in-memory SQLite
+ * per cell and the bucket's page-level logs (LTX), cells are not bound to one OPFS pool.
+ */
+import { type ObjectStore } from "./object-store.js";
+export declare function idbObjectStore(name: string): ObjectStore;

package/dist/bucket/idb-object-store.js

@@ -0,0 +1,73 @@
+/**
+ * A bucket in IndexedDB: an ObjectStore whose conditional writes are atomic across every tab
+ * and worker of the origin (each put checks its condition and writes in one readwrite
+ * transaction, and IndexedDB serializes overlapping readwrite transactions). No synchronous
+ * file handle is involved, so any number of workers can use it at once: with in-memory SQLite
+ * per cell and the bucket's page-level logs (LTX), cells are not bound to one OPFS pool.
+ */
+import { PreconditionFailedError } from "./object-store.js";
+const STORE = "objects";
+function open(name) {
+    return new Promise((resolve, reject) => {
+        const r = indexedDB.open(name, 1);
+        r.onupgradeneeded = () => r.result.createObjectStore(STORE);
+        r.onsuccess = () => resolve(r.result);
+        r.onerror = () => reject(r.error);
+    });
+}
+const done = (tx) => new Promise((resolve, reject) => {
+    tx.oncomplete = () => resolve();
+    tx.onerror = () => reject(tx.error);
+    tx.onabort = () => reject(tx.error ?? new Error("IndexedDB transaction aborted"));
+});
+const req = (r) => new Promise((resolve, reject) => {
+    r.onsuccess = () => resolve(r.result);
+    r.onerror = () => reject(r.error);
+});
+export function idbObjectStore(name) {
+    let db;
+    const conn = () => (db ??= open(name));
+    return {
+        async get(key) {
+            const tx = (await conn()).transaction(STORE, "readonly");
+            return (await req(tx.objectStore(STORE).get(key)));
+        },
+        async put(key, body, cond, attrs) {
+            const tx = (await conn()).transaction(STORE, "readwrite");
+            const store = tx.objectStore(STORE);
+            const etag = crypto.randomUUID();
+            let failed = false;
+            // Condition and write in the same transaction: atomic for the whole origin.
+            store.get(key).onsuccess = (e) => {
+                const cur = e.target.result;
+                if ((cond?.ifNoneMatch === "*" && cur) ||
+                    (cond?.ifMatch !== undefined && cur?.etag !== cond.ifMatch)) {
+                    failed = true;
+                    tx.abort();
+                    return;
+                }
+                store.put({ body: body.slice(), etag, attrs, modifiedMs: Date.now() }, key);
+            };
+            try {
+                await done(tx);
+            }
+            catch (err) {
+                if (failed)
+                    throw new PreconditionFailedError(key);
+                throw err;
+            }
+            return etag;
+        },
+        async list(prefix) {
+            const tx = (await conn()).transaction(STORE, "readonly");
+            const range = IDBKeyRange.bound(prefix, `${prefix}\uffff`, false, false);
+            return (await req(tx.objectStore(STORE).getAllKeys(range))).sort();
+        },
+        async delete(key) {
+            const tx = (await conn()).transaction(STORE, "readwrite");
+            tx.objectStore(STORE).delete(key);
+            await done(tx);
+        },
+    };
+}
+//# sourceMappingURL=idb-object-store.js.map

package/dist/bucket/idb-object-store.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"idb-object-store.js","sourceRoot":"","sources":["../../src/bucket/idb-object-store.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * A bucket in IndexedDB: an ObjectStore whose conditional writes are atomic across every tab\n * and worker of the origin (each put checks its condition and writes in one readwrite\n * transaction, and IndexedDB serializes overlapping readwrite transactions). No synchronous\n * file handle is involved, so any number of workers can use it at once: with in-memory SQLite\n * per cell and the bucket's page-level logs (LTX), cells are not bound to one OPFS pool.\n */\nimport { type ObjectStore, PreconditionFailedError, type StoredObject } from \"./object-store.js\";\n\nconst STORE = \"objects\";\n\nfunction open(name: string): Promise<IDBDatabase> {\n  return new Promise((resolve, reject) => {\n    const r = indexedDB.open(name, 1);\n    r.onupgradeneeded = () => r.result.createObjectStore(STORE);\n    r.onsuccess = () => resolve(r.result);\n    r.onerror = () => reject(r.error);\n  });\n}\n\nconst done = (tx: IDBTransaction) =>\n  new Promise<void>((resolve, reject) => {\n    tx.oncomplete = () => resolve();\n    tx.onerror = () => reject(tx.error);\n    tx.onabort = () => reject(tx.error ?? new Error(\"IndexedDB transaction aborted\"));\n  });\nconst req = <T>(r: IDBRequest<T>) =>\n  new Promise<T>((resolve, reject) => {\n    r.onsuccess = () => resolve(r.result);\n    r.onerror = () => reject(r.error);\n  });\n\nexport function idbObjectStore(name: string): ObjectStore {\n  let db: Promise<IDBDatabase> | undefined;\n  const conn = () => (db ??= open(name));\n  return {\n    async get(key) {\n      const tx = (await conn()).transaction(STORE, \"readonly\");\n      return (await req(tx.objectStore(STORE).get(key))) as StoredObject | undefined;\n    },\n    async put(key, body, cond, attrs) {\n      const tx = (await conn()).transaction(STORE, \"readwrite\");\n      const store = tx.objectStore(STORE);\n      const etag = crypto.randomUUID();\n      let failed = false;\n      // Condition and write in the same transaction: atomic for the whole origin.\n      store.get(key).onsuccess = (e) => {\n        const cur = (e.target as IDBRequest<StoredObject | undefined>).result;\n        if (\n          (cond?.ifNoneMatch === \"*\" && cur) ||\n          (cond?.ifMatch !== undefined && cur?.etag !== cond.ifMatch)\n        ) {\n          failed = true;\n          tx.abort();\n          return;\n        }\n        store.put(\n          { body: body.slice(), etag, attrs, modifiedMs: Date.now() } satisfies StoredObject,\n          key,\n        );\n      };\n      try {\n        await done(tx);\n      } catch (err) {\n        if (failed) throw new PreconditionFailedError(key);\n        throw err;\n      }\n      return etag;\n    },\n    async list(prefix) {\n      const tx = (await conn()).transaction(STORE, \"readonly\");\n      const range = IDBKeyRange.bound(prefix, `${prefix}\\uffff`, false, false);\n      return ((await req(tx.objectStore(STORE).getAllKeys(range))) as string[]).sort();\n    },\n    async delete(key) {\n      const tx = (await conn()).transaction(STORE, \"readwrite\");\n      tx.objectStore(STORE).delete(key);\n      await done(tx);\n    },\n  };\n}\n"]}

package/dist/bucket/ltx-log.d.ts

@@ -0,0 +1,34 @@
+import type { CellBackup, CellDurability } from "../ports.js";
+import type { ObjectStore } from "./object-store.js";
+/**
+ * THE LTX writer of cellb, in celld's bucket layout, on any ObjectStore:
+ *
+ *   cells/<Class>:<idHex>/ltx/e<epoch>/<level>/<min>-<max>.ltx   LTX v3 (src/ltx)
+ *   wake/entries/…, wake/retired/…                               celld's alarm wake index
+ *
+ * Each committed transaction becomes one LTX file in the cell's epoch — the first one of an
+ * epoch a snapshot (TXID 1), then only the changed pages (from the SQLite WASM page hook, or a
+ * diff of the image) — and the output gate waits for the PUT; a cell's commits are written
+ * strictly in order. Restore: the newest epoch whose files form a chain from a snapshot.
+ * `compact` makes save() replace an epoch's files with one snapshot file 1..N.
+ *
+ * Used by celldBucket (with celld's ownership protocol: begin()/forget() per acquisition) and by
+ * filesApiLtxLog (a FilesApi, a fixed epoch).
+ */
+export interface LtxLogOptions {
+    now?: () => number;
+    /** Epoch used when a commit names none (no ownership). */
+    defaultEpoch?: number;
+    /** save() compacts an epoch into one snapshot file 1..N. */
+    compact?: boolean;
+    /** Checked before each write: false refuses it (this node's authority has lapsed). */
+    authorized?: () => boolean;
+}
+export declare function ltxLog(store: ObjectStore, o?: LtxLogOptions): CellDurability & CellBackup & {
+    logCommit: CellDurability["committed"];
+} & {
+    /** A new owner epoch for the cell: its next commit opens the generation with a snapshot. */
+    begin(cellKey: string, epoch: number): void;
+    /** The cell is no longer ours (lease lost): forget its writer state. */
+    forget(cellKey: string): void;
+};