@cello-protocol/daemon 0.0.132 → 0.0.133

package/dist/document-lifecycle.js

@@ -0,0 +1,433 @@
+/**
+ * DOD-DOC-LIFECYCLE-1 — the verbs (§3.5 + §16.4).
+ *
+ * Three ways a document can end, and they are not interchangeable. Conflating any two of them
+ * makes a promise the protocol cannot keep:
+ *
+ *   close     BILATERAL. Both sides ack and the document is complete by agreement. One side's
+ *             close is a REQUEST — treating it as a conclusion would tell this operator the
+ *             collaboration ended while the peer is still writing into it.
+ *   kill      UNILATERAL. Stop accepting and publishing, notify the peer, and KEEP the local copy
+ *             and the log. The peer keeps what it holds, and that is said out loud: it is the one
+ *             thing an operator is most likely to assume a kill undoes, and the one thing it
+ *             cannot.
+ *   withdraw  ONE UNDELIVERED update. A local rollback plus a withdrawal record BESIDE the
+ *             original — marked, never deleted, because a hole in an append-only log is
+ *             indistinguishable from tampering. Once the peer has it, withdrawal is refused rather
+ *             than faked.
+ *
+ * ── THE KILL SWITCH (§16.7-11) ────────────────────────────────────────────────────────────────
+ *
+ * A platform-paused agent refuses OUTBOUND publishes loudly, still admits INBOUND mechanically,
+ * and suppresses notifications. The asymmetry is deliberate. Refusing inbound would surface the
+ * pause to the peer as a protocol fault and force a rejection round for something that is not
+ * their doing; refusing outbound silently would leave the operator writing into a document that is
+ * going nowhere, with their work piling up locally and no sign anything is wrong.
+ */
+const CREATE_LIFECYCLE_SQL = `
+  CREATE TABLE IF NOT EXISTS document_closes (
+    owner_agent_id TEXT    NOT NULL,
+    document_id    TEXT    NOT NULL,
+    -- WHO closed, not how many closes there were. Counting would let one party close a document
+    -- unilaterally by asking twice, which is precisely the bilateral guarantee gone.
+    closed_by      TEXT    NOT NULL,
+    created_at     INTEGER NOT NULL,
+    PRIMARY KEY (owner_agent_id, document_id, closed_by)
+  );
+
+  -- WITHDRAWALS live here, NOT in document_envelopes, and that placement is the fix for three
+  -- separate defects rather than a filing preference.
+  --
+  -- 1. CHAIN. A withdrawal is local-only by design: it is never delivered (the update it concerns
+  --    was never delivered, so the peer has nothing to act on). As an envelope it still advanced
+  --    our per-sender chain, so our NEXT update chained onto a node the peer will never hold and
+  --    the peer refused it with document_chain_broken — sending an operator to the chain layer for
+  --    a withdrawal-scoping bug, and leaving the document unopenable after their next restart.
+  --    Chaining it to the last DELIVERABLE envelope instead would fork our chain, since the next
+  --    update claims the same predecessor. It cannot be a node in that chain at all.
+  -- 2. CRYPTO. As an envelope it needed a signature and a state vector, and it had neither of its
+  --    own — the first version copied the ORIGINAL's, putting a real Ed25519 signature made over a
+  --    different record onto a permanent append-only row. document-rejection.ts states the rule
+  --    this violated in writing: required, never fabricated.
+  -- 3. REPLAY. An envelope row is something rebuildSnapshot must reason about; an audit row is not.
+  --
+  -- Same shape as document_quarantine, for the same reason: audit that must survive, must not be
+  -- replayed, and must not be chained.
+  CREATE TABLE IF NOT EXISTS document_withdrawals (
+    owner_agent_id TEXT    NOT NULL,
+    document_id    TEXT    NOT NULL,
+    envelope_hash  TEXT    NOT NULL,
+    created_at     INTEGER NOT NULL,
+    PRIMARY KEY (owner_agent_id, document_id, envelope_hash)
+  );
+
+  CREATE TABLE IF NOT EXISTS agent_platform_pause (
+    agent_id   TEXT    NOT NULL PRIMARY KEY,
+    paused     INTEGER NOT NULL,
+    updated_at INTEGER NOT NULL
+  );
+`;
+export class DocumentLifecycle {
+    #store;
+    #logger;
+    #notifier;
+    /**
+     * Our own wire sender id for an agent. M14-D5 makes it the pubkey hex, which is NOT the local
+     * owner key this store is otherwise keyed by — and passing the wrong one here reports every
+     * pending update as delivered.
+     */
+    #senderAgentId;
+    #rollback;
+    constructor(store, logger, notifier, 
+    /**
+     * Undo one envelope's operations on the LIVE document, as inverses. Injected because the live
+     * `Y.Doc` and its UndoManager belong to the engine, not here — and REQUIRED, because a default
+     * that quietly did nothing would restore exactly the defect this argument exists to fix.
+     */
+    rollback, senderAgentId = (id) => id) {
+        this.#store = store;
+        this.#logger = logger;
+        this.#notifier = notifier;
+        this.#rollback = rollback;
+        this.#senderAgentId = senderAgentId;
+        this.#store.rawDb.exec(CREATE_LIFECYCLE_SQL);
+    }
+    list(ownerAgentId, nowMs) {
+        // Every pending envelope regardless of schedule: the operator is asking "what has not reached
+        // my peer", not "what is due for a retry in the next few seconds".
+        const pending = this.#store.pendingDeliveries(ownerAgentId, Number.MAX_SAFE_INTEGER, this.#senderAgentId(ownerAgentId));
+        const pendingByDocument = new Map();
+        for (const e of pending) {
+            const c = pendingByDocument.get(e.documentId) ?? { total: 0, sent: 0 };
+            c.total += 1;
+            // SPLIT, because "sent, awaiting confirmation" and "never left this machine" are different
+            // things to tell an operator asking why their work has not landed — and the column that
+            // records the difference had a writer but no reader, which is how it got deleted once.
+            if (e.deliveredAtMs != null)
+                c.sent += 1;
+            pendingByDocument.set(e.documentId, c);
+        }
+        void nowMs;
+        return this.#store.listDocuments(ownerAgentId).map((d) => ({
+            documentId: d.documentId,
+            peerAgentId: d.peerAgentId,
+            documentType: d.documentType,
+            assuranceTier: "authenticated",
+            epochId: 0,
+            status: d.status,
+            pendingDeliveries: pendingByDocument.get(d.documentId)?.total ?? 0,
+            pendingSent: pendingByDocument.get(d.documentId)?.sent ?? 0,
+            pendingUnsent: (pendingByDocument.get(d.documentId)?.total ?? 0) -
+                (pendingByDocument.get(d.documentId)?.sent ?? 0),
+            closePending: this.#hasClosed(ownerAgentId, d.documentId, ownerAgentId) &&
+                !this.#hasClosed(ownerAgentId, d.documentId, d.peerAgentId),
+        }));
+    }
+    /** Our half of a bilateral close. Completes only when the peer's half is also on record. */
+    async close(ownerAgentId, documentId, nowMs) {
+        const doc = this.#store.getDocument(ownerAgentId, documentId);
+        if (!doc) {
+            return { ok: false, reason: "document_unknown", detail: `no document ${documentId.slice(0, 16)}…` };
+        }
+        this.#recordClose(ownerAgentId, documentId, ownerAgentId, nowMs);
+        const notified = await this.#notifier.notifyPeer(documentId, "close");
+        if (!notified.ok) {
+            // RAISED to error, and RETURNED, matching `kill`. This was a warn whose outcome went nowhere:
+            // the caller answered `{ok: true, status: "active"}`, which is indistinguishable from "sent
+            // fine, they have not answered yet". Control frames are fire-once — not in the log, never
+            // swept — so a close the peer never received means the document can never settle, and neither
+            // operator has anything to look at.
+            this.#logger.error("document.close.peer_not_notified", { documentId, reason: notified.reason });
+        }
+        this.#settleClose(ownerAgentId, documentId, doc.peerAgentId);
+        this.#logger.info("document.close.requested", { documentId, peerNotified: notified.ok });
+        return { ok: true, peerNotified: notified.ok };
+    }
+    /** The peer's half, arriving over the session. */
+    recordPeerClose(ownerAgentId, documentId, peerAgentId, nowMs) {
+        const doc = this.#store.getDocument(ownerAgentId, documentId);
+        if (!doc) {
+            // Without this the row is written for a document that does not exist — there is no foreign
+            // key on this table — and `setDocumentStatus` updates zero rows and returns silently.
+            return {
+                ok: false,
+                reason: "document_unknown",
+                detail: `no document ${documentId.slice(0, 16)}… for this agent`,
+            };
+        }
+        if (peerAgentId !== doc.peerAgentId) {
+            // THE BILATERAL GUARANTEE. The closer id came from the caller and was written as `closed_by`
+            // and settled against ITSELF, so any second distinct string — a stale contact id, a
+            // pubkey-vs-name mismatch, a hostile session — plus our own close flipped the document to
+            // closed. The whole point of recording WHO closed is defeated if who is never checked.
+            this.#logger.warn("document.close.not_peer", {
+                documentId,
+                claimedBy: peerAgentId,
+                peerAgentId: doc.peerAgentId,
+            });
+            return {
+                ok: false,
+                reason: "document_close_not_peer",
+                detail: `${peerAgentId} is not this document's peer (${doc.peerAgentId}), so their close is not ` +
+                    `the other half of a bilateral close`,
+            };
+        }
+        this.#recordClose(ownerAgentId, documentId, doc.peerAgentId, nowMs);
+        this.#settleClose(ownerAgentId, documentId, doc.peerAgentId);
+        this.#logger.info("document.close.peer_requested", { documentId, peerAgentId: doc.peerAgentId });
+        return { ok: true };
+    }
+    /**
+     * The peer KILLED the document. Their half of the unilateral end.
+     *
+     * Terminal immediately, and there is no reciprocal step: a kill is one-sided by definition, which
+     * is what separates it from a close. Continuing to publish afterwards would send updates to a
+     * party who has stopped listening — refused at their end forever, with nothing on this screen
+     * explaining why.
+     *
+     * The SENDER IS CHECKED against the document's peer for the same reason `recordPeerClose` checks
+     * it: without that, any string plus a valid-looking frame ends someone else's document.
+     */
+    recordPeerKill(ownerAgentId, documentId, peerAgentId, nowMs) {
+        const doc = this.#store.getDocument(ownerAgentId, documentId);
+        if (!doc) {
+            return {
+                ok: false,
+                reason: "document_unknown",
+                detail: `no document ${documentId.slice(0, 16)}… for this agent`,
+            };
+        }
+        if (peerAgentId !== doc.peerAgentId) {
+            this.#logger.warn("document.kill.not_peer", {
+                documentId,
+                claimedBy: peerAgentId,
+                peerAgentId: doc.peerAgentId,
+            });
+            return {
+                ok: false,
+                reason: "document_kill_not_peer",
+                detail: `${peerAgentId} is not this document's peer (${doc.peerAgentId}), so their kill is not theirs to make`,
+            };
+        }
+        void nowMs;
+        if (doc.status !== "active" && doc.status !== "stalled") {
+            // ONLY FROM ACTIVE, the same guard `#settleClose` carries and for the mirror reason. The
+            // transport WILL redeliver, and nothing bounds a control frame's freshness — `sent_at_ms` is
+            // signed and never checked. Unconditional, a kill arriving after a bilateral close rewrote a
+            // settled agreement as a unilateral end.
+            this.#logger.info("document.kill.peer_requested.ignored", {
+                documentId,
+                status: doc.status,
+            });
+            return { ok: true };
+        }
+        this.#store.setDocumentStatus(ownerAgentId, documentId, "killed");
+        this.#logger.info("document.kill.peer_requested", { documentId, peerAgentId: doc.peerAgentId });
+        return { ok: true };
+    }
+    /**
+     * Unilateral end. Local, and deliberately not contingent on the peer hearing about it — a
+     * decision to stop that depends on the other party being online is not a decision to stop.
+     */
+    async kill(ownerAgentId, documentId, nowMs) {
+        const doc = this.#store.getDocument(ownerAgentId, documentId);
+        if (!doc) {
+            return { ok: false, reason: "document_unknown", detail: `no document ${documentId.slice(0, 16)}…` };
+        }
+        void nowMs;
+        this.#store.setDocumentStatus(ownerAgentId, documentId, "killed");
+        const notified = await this.#notifier.notifyPeer(documentId, "kill");
+        if (!notified.ok) {
+            // Reported, not swallowed: a kill the peer never heard about leaves them publishing into a
+            // document that will never answer, and the operator is the one who needs to know that.
+            this.#logger.error("document.kill.peer_not_notified", {
+                documentId,
+                peerAgentId: doc.peerAgentId,
+                reason: notified.reason,
+            });
+        }
+        this.#logger.info("document.killed", { documentId, peerNotified: notified.ok });
+        return {
+            ok: true,
+            peerNotified: notified.ok,
+            note: "this document no longer accepts or publishes updates, and your local copy and log are " +
+                "retained. Your peer keeps what it holds — a kill stops the collaboration, it does not " +
+                "retract content they already have.",
+        };
+    }
+    /**
+     * Withdraw ONE undelivered update: a withdrawal record beside the original.
+     *
+     * Every refusal here is the same shape — say no rather than produce a record that claims
+     * something untrue about the log.
+     */
+    withdraw(ownerAgentId, documentId, envelopeHash, nowMs) {
+        const log = this.#store.getEnvelopeLog(ownerAgentId, documentId);
+        const original = log.find((e) => e.envelopeHash === envelopeHash);
+        if (!original) {
+            // A withdrawal record pointing at nothing is worse than a refusal: it is a permanent claim
+            // in an append-only store about an envelope that never existed.
+            return {
+                ok: false,
+                reason: "document_envelope_unknown",
+                detail: `no envelope ${envelopeHash.slice(0, 16)}… in this document's log`,
+            };
+        }
+        if (original.senderAgentId !== ownerAgentId) {
+            return {
+                ok: false,
+                reason: "document_not_author",
+                detail: `envelope ${envelopeHash.slice(0, 16)}… was authored by ${original.senderAgentId}, not by you`,
+            };
+        }
+        if (original.ackedAtMs != null) {
+            // The honest refusal. Withdrawing a delivered update would tell the operator their content
+            // was retracted while the peer is holding it — the promise this module refuses to make.
+            return {
+                ok: false,
+                reason: "document_already_delivered",
+                detail: `envelope ${envelopeHash.slice(0, 16)}… has already been delivered and acknowledged — ` +
+                    `your peer holds it, so it cannot be withdrawn. Publish a superseding update instead.`,
+            };
+        }
+        // THE LOCAL ROLLBACK — the half that was missing. Writing only the record left the original in
+        // the log WITH its payload, and replay applies every update payload in order, so the withdrawn
+        // text stayed in the operator's own document and came back on every rebuild. The operator was
+        // told their update was withdrawn while their file still contained it.
+        //
+        // Rolled back as INVERSES through the same undo path a rejection uses, never by dropping the
+        // payload: our own later work may be causally stacked on these operations, and REJECT-1
+        // measured what removing them costs — everything after stays pending forever and the document
+        // silently loses the legitimate work. The inverse enters the log on the next ordinary publish,
+        // computed from the live document, which is also why neither the original nor the inverse is
+        // ever delivered: the peer holds neither, and the next publish carries the net effect.
+        const rolledBack = this.#rollback(ownerAgentId, documentId, envelopeHash);
+        if (!rolledBack.ok) {
+            return {
+                ok: false,
+                reason: "document_withdraw_rollback_failed",
+                detail: `the local rollback did not happen (${rolledBack.reason}), so nothing was withdrawn — ` +
+                    `reporting success here would tell you your update was retracted while your file still ` +
+                    `contains it`,
+            };
+        }
+        const info = this.#store.rawDb
+            .prepare(`INSERT INTO document_withdrawals (owner_agent_id, document_id, envelope_hash, created_at)
+         VALUES (?, ?, ?, ?)
+         ON CONFLICT (owner_agent_id, document_id, envelope_hash) DO NOTHING`)
+            .run(ownerAgentId, documentId, envelopeHash, nowMs);
+        if (Number(info.changes) === 0) {
+            // Already withdrawn. Reported rather than inferred — the earlier version ignored the write's
+            // outcome and returned success for a no-op.
+            return {
+                ok: false,
+                reason: "document_already_withdrawn",
+                detail: `envelope ${envelopeHash.slice(0, 16)}… was already withdrawn`,
+            };
+        }
+        this.#logger.info("document.withdrawn", { documentId, envelopeHash });
+        return { ok: true };
+    }
+    // ─── the kill switch (§16.7-11) ───────────────────────────────────────────
+    setPlatformPaused(agentId, paused, nowMs) {
+        this.#store.rawDb
+            .prepare(`INSERT INTO agent_platform_pause (agent_id, paused, updated_at) VALUES (?, ?, ?)
+         ON CONFLICT (agent_id) DO UPDATE SET paused = excluded.paused, updated_at = excluded.updated_at`)
+            // Hard-wired to 0 before, so every row read 1970 — on the KILL SWITCH, where "when was this
+            // agent paused by the platform" is the audit fact of the whole feature. The tell was that it
+            // was the only method in the class taking no clock.
+            .run(agentId, paused ? 1 : 0, nowMs);
+        this.#logger.warn("agent.platform_pause.changed", { agentId, paused });
+    }
+    isPlatformPaused(agentId) {
+        const r = this.#store.rawDb
+            .prepare("SELECT paused FROM agent_platform_pause WHERE agent_id = ?")
+            .get(agentId);
+        return (r?.paused ?? 0) === 1;
+    }
+    /** Outbound. Refused loudly while paused, and while the document has ended. */
+    canPublish(ownerAgentId, documentId) {
+        if (this.isPlatformPaused(ownerAgentId)) {
+            return {
+                ok: false,
+                reason: "agent_platform_paused",
+                detail: `this agent is paused by the platform, so nothing can be published. Your work is kept ` +
+                    `locally and will publish once the agent is unpaused.`,
+            };
+        }
+        const doc = this.#store.getDocument(ownerAgentId, documentId);
+        if (!doc) {
+            return { ok: false, reason: "document_unknown", detail: `no document ${documentId.slice(0, 16)}…` };
+        }
+        if (doc.status === "closed") {
+            return { ok: false, reason: "document_closed", detail: "this document was closed by agreement" };
+        }
+        if (doc.status === "killed") {
+            return { ok: false, reason: "document_killed", detail: "this document was ended locally" };
+        }
+        if (doc.status === "stalled") {
+            // REJECT-1 stalls a document after its retry rounds. A stalled document has stopped
+            // converging, so publishing into it is the same lie as publishing into a killed one — and
+            // two partial gates that each know half the terminal states is how a caller ends up wrong
+            // about the other half.
+            return {
+                ok: false,
+                reason: "document_stalled",
+                detail: "this document stopped accepting updates after repeated rejections",
+            };
+        }
+        return { ok: true };
+    }
+    /** Inbound. A pause does NOT refuse it — see the header. */
+    canAdmit(ownerAgentId, documentId) {
+        const doc = this.#store.getDocument(ownerAgentId, documentId);
+        if (!doc) {
+            return { ok: false, reason: "document_unknown", detail: `no document ${documentId.slice(0, 16)}…` };
+        }
+        if (doc.status === "killed") {
+            return { ok: false, reason: "document_killed", detail: "this document was ended locally" };
+        }
+        if (doc.status === "closed") {
+            return { ok: false, reason: "document_closed", detail: "this document was closed by agreement" };
+        }
+        if (doc.status === "stalled") {
+            return {
+                ok: false,
+                reason: "document_stalled",
+                detail: "this document stopped accepting updates after repeated rejections",
+            };
+        }
+        return { ok: true };
+    }
+    shouldNotify(agentId) {
+        return !this.isPlatformPaused(agentId);
+    }
+    // ─── internals ────────────────────────────────────────────────────────────
+    #recordClose(ownerAgentId, documentId, closedBy, nowMs) {
+        this.#store.rawDb
+            .prepare(`INSERT INTO document_closes (owner_agent_id, document_id, closed_by, created_at)
+         VALUES (?, ?, ?, ?)
+         ON CONFLICT (owner_agent_id, document_id, closed_by) DO NOTHING`)
+            .run(ownerAgentId, documentId, closedBy, nowMs);
+    }
+    #hasClosed(ownerAgentId, documentId, who) {
+        const r = this.#store.rawDb
+            .prepare(`SELECT 1 AS present FROM document_closes
+          WHERE owner_agent_id = ? AND document_id = ? AND closed_by = ?`)
+            .get(ownerAgentId, documentId, who);
+        return r?.present === 1;
+    }
+    #settleClose(ownerAgentId, documentId, peerAgentId) {
+        // ONLY FROM ACTIVE. Unconditional, a peer close arriving after a unilateral kill overwrote
+        // `killed` with `closed` — the operator's own decision replaced by "closed by agreement", which
+        // is a different fact and the one they did not choose. Same for `stalled`.
+        if (this.#store.getDocument(ownerAgentId, documentId)?.status !== "active")
+            return;
+        if (this.#hasClosed(ownerAgentId, documentId, ownerAgentId) &&
+            this.#hasClosed(ownerAgentId, documentId, peerAgentId)) {
+            this.#store.setDocumentStatus(ownerAgentId, documentId, "closed");
+            this.#logger.info("document.closed", { documentId });
+        }
+    }
+}
+//# sourceMappingURL=document-lifecycle.js.map

package/dist/document-lifecycle.js.map

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

package/dist/document-live-docs.d.ts

@@ -0,0 +1,58 @@
+/**
+ * DOD-DOC-INBOUND-2 — the live `Y.Doc` cache.
+ *
+ * The inbound path needs a document to apply an update to, and it must be THE document — the same
+ * object every subsequent update sees. Materializing a fresh one per frame would make each update
+ * land on an empty doc and converge with nothing.
+ *
+ * ── WHY THIS IS A UNIT AND NOT A `Map` IN THE COMPOSITION ROOT ────────────────────────────────
+ *
+ * Three properties, and each is a defect if it goes the other way:
+ *
+ *   RESTORED FROM THE LOG, not created empty. A daemon restart must not lose the document — the
+ *   log is what makes it survivable, and a cache that starts blank silently discards everything
+ *   the operator and their peer have written. `rebuildSnapshot` verifies the chain before replaying,
+ *   so a document that cannot be rebuilt REFUSES rather than coming back partial.
+ *
+ *   BOUNDED. A daemon attends many agents over a long life and a `Y.Doc` holds the whole document
+ *   plus its history. An unbounded map is a leak whose symptom is the daemon dying days later with
+ *   no obvious cause — the shape `session-node-manager.ts` already had to fix once for received
+ *   content. Eviction is safe here in a way it usually is not: the log is the truth, so an evicted
+ *   document is rebuilt on next use rather than lost.
+ *
+ *   EVICTION IS NEVER SILENT DATA LOSS, which is only true because the two above hold together. If
+ *   eviction existed without log-backed restore it would be exactly the silent loss it looks like.
+ */
+import * as Y from "yjs";
+import type { DocumentStore } from "./document-store.js";
+import type { DocumentEngine } from "./document-engine.js";
+import type { Logger } from "./types.js";
+/**
+ * How many documents stay resident. Small on purpose: an operator collaborates on a handful at a
+ * time, and the cost of a miss is a rebuild from the log, not a failure.
+ */
+export declare const LIVE_DOC_CACHE_SIZE = 32;
+export declare class LiveDocuments {
+    #private;
+    constructor(store: DocumentStore, engine: DocumentEngine, logger: Logger, startingContentFor?: (ownerAgentId: string, documentId: string) => Uint8Array | null);
+    /**
+     * The live document, restored from the log on a miss.
+     *
+     * THROWS rather than returning an empty document when the log cannot be rebuilt. An empty doc
+     * here would be applied to, published from, and would converge the peer's real content away — a
+     * silent whole-document loss originating in a cache miss.
+     *
+     * PRECISION, measured 2026-08-05: that covers a log that EXISTS and does not verify. An id this
+     * daemon has never heard of has no log to fail on, so it comes back as a legitimately empty
+     * document. Harmless only because every caller checks `documents` first — the operator surface
+     * refuses with `document_unknown`, and the inbound path refuses before materializing anything.
+     * A future caller that skips that check gets an empty document and no signal, so the check is
+     * part of the contract rather than an incidental habit of the current callers.
+     */
+    get(ownerAgentId: string, documentId: string): Y.Doc;
+    /** Drop one document — after a kill or close, where keeping it resident buys nothing. */
+    release(ownerAgentId: string, documentId: string): void;
+    /** Resident count, for tests and for an operator-facing surface that wants to show it. */
+    size(): number;
+}
+//# sourceMappingURL=document-live-docs.d.ts.map

package/dist/document-live-docs.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"document-live-docs.d.ts","sourceRoot":"","sources":["../src/document-live-docs.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAEH,OAAO,KAAK,CAAC,MAAM,KAAK,CAAC;AACzB,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACzD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAC3D,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,YAAY,CAAC;AAEzC;;;GAGG;AACH,eAAO,MAAM,mBAAmB,KAAK,CAAC;AAEtC,qBAAa,aAAa;;gBAWtB,KAAK,EAAE,aAAa,EACpB,MAAM,EAAE,cAAc,EACtB,MAAM,EAAE,MAAM,EACd,kBAAkB,GAAE,CAAC,YAAY,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,KAAK,UAAU,GAAG,IAAiB;IAQlG;;;;;;;;;;;;;OAaG;IACH,GAAG,CAAC,YAAY,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,CAAC,CAAC,GAAG;IA0CpD,yFAAyF;IACzF,OAAO,CAAC,YAAY,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,IAAI;IAQvD,0FAA0F;IAC1F,IAAI,IAAI,MAAM;CAiBf"}

package/dist/document-live-docs.js

@@ -0,0 +1,126 @@
+/**
+ * DOD-DOC-INBOUND-2 — the live `Y.Doc` cache.
+ *
+ * The inbound path needs a document to apply an update to, and it must be THE document — the same
+ * object every subsequent update sees. Materializing a fresh one per frame would make each update
+ * land on an empty doc and converge with nothing.
+ *
+ * ── WHY THIS IS A UNIT AND NOT A `Map` IN THE COMPOSITION ROOT ────────────────────────────────
+ *
+ * Three properties, and each is a defect if it goes the other way:
+ *
+ *   RESTORED FROM THE LOG, not created empty. A daemon restart must not lose the document — the
+ *   log is what makes it survivable, and a cache that starts blank silently discards everything
+ *   the operator and their peer have written. `rebuildSnapshot` verifies the chain before replaying,
+ *   so a document that cannot be rebuilt REFUSES rather than coming back partial.
+ *
+ *   BOUNDED. A daemon attends many agents over a long life and a `Y.Doc` holds the whole document
+ *   plus its history. An unbounded map is a leak whose symptom is the daemon dying days later with
+ *   no obvious cause — the shape `session-node-manager.ts` already had to fix once for received
+ *   content. Eviction is safe here in a way it usually is not: the log is the truth, so an evicted
+ *   document is rebuilt on next use rather than lost.
+ *
+ *   EVICTION IS NEVER SILENT DATA LOSS, which is only true because the two above hold together. If
+ *   eviction existed without log-backed restore it would be exactly the silent loss it looks like.
+ */
+/**
+ * How many documents stay resident. Small on purpose: an operator collaborates on a handful at a
+ * time, and the cost of a miss is a rebuild from the log, not a failure.
+ */
+export const LIVE_DOC_CACHE_SIZE = 32;
+export class LiveDocuments {
+    #store;
+    #engine;
+    #logger;
+    /** Insertion-ordered, so the oldest key is the eviction candidate. */
+    #live = new Map();
+    /** Epoch zero for a document, from its stored proposal. See `get`. */
+    #startingContentFor;
+    constructor(store, engine, logger, startingContentFor = () => null) {
+        this.#store = store;
+        this.#engine = engine;
+        this.#logger = logger;
+        this.#startingContentFor = startingContentFor;
+    }
+    /**
+     * The live document, restored from the log on a miss.
+     *
+     * THROWS rather than returning an empty document when the log cannot be rebuilt. An empty doc
+     * here would be applied to, published from, and would converge the peer's real content away — a
+     * silent whole-document loss originating in a cache miss.
+     *
+     * PRECISION, measured 2026-08-05: that covers a log that EXISTS and does not verify. An id this
+     * daemon has never heard of has no log to fail on, so it comes back as a legitimately empty
+     * document. Harmless only because every caller checks `documents` first — the operator surface
+     * refuses with `document_unknown`, and the inbound path refuses before materializing anything.
+     * A future caller that skips that check gets an empty document and no signal, so the check is
+     * part of the contract rather than an incidental habit of the current callers.
+     */
+    get(ownerAgentId, documentId) {
+        // `\0` as the ESCAPE, not a literal NUL byte. Written raw, git classifies the whole file as
+        // binary — `git diff` reports `Bin 4508 -> 5084` and shows nothing — so every change to this
+        // file is invisible to code review. Caught by a reviewer who had to strip the bytes to read it.
+        const key = `${ownerAgentId}\0${documentId}`;
+        const hit = this.#live.get(key);
+        if (hit) {
+            // Refresh recency: delete and re-insert so the Map's insertion order is a true LRU rather
+            // than a first-in-first-out queue that evicts the document being actively edited.
+            this.#live.delete(key);
+            this.#live.set(key, hit);
+            return hit;
+        }
+        const snapshot = this.#store.rebuildSnapshot(ownerAgentId, documentId, (rows) => this.#engine.replay(rows));
+        const doc = this.#engine.restore(snapshot.binary);
+        // EPOCH ZERO FIRST, and it is not in the envelope log.
+        //
+        // A document's starting content is agreed in the PROPOSAL — both sides apply the same bytes, so
+        // neither has to author it and there is no first envelope carrying it. That is correct on the
+        // wire and it left the content living only in the `Y.Doc` the propose/accept handler happened to
+        // be holding: restart the daemon and the document came back EMPTY, on both sides, with the row
+        // still present and the log still valid. An operator would open a document they had been
+        // working in and find nothing there — and then write into it, publishing the deletion of
+        // everything the peer still had.
+        //
+        // Re-applied here rather than logged at accept time because the proposal is already stored and
+        // `document_id` is the hash of it: taking epoch zero from the proposal is deterministic on both
+        // sides forever, while an envelope written at accept would be one side's authored operation and
+        // the two would not match.
+        //
+        // Applying to a rebuilt doc is safe and idempotent — a Yjs update already present is a no-op,
+        // which is the property the whole replay depends on.
+        const starting = this.#startingContentFor(ownerAgentId, documentId);
+        if (starting)
+            this.#engine.applyUpdate(doc, starting);
+        this.#live.set(key, doc);
+        this.#evictIfNeeded();
+        return doc;
+    }
+    /** Drop one document — after a kill or close, where keeping it resident buys nothing. */
+    release(ownerAgentId, documentId) {
+        const key = `${ownerAgentId}\0${documentId}`;
+        const doc = this.#live.get(key);
+        if (!doc)
+            return;
+        this.#live.delete(key);
+        doc.destroy();
+    }
+    /** Resident count, for tests and for an operator-facing surface that wants to show it. */
+    size() {
+        return this.#live.size;
+    }
+    #evictIfNeeded() {
+        while (this.#live.size > LIVE_DOC_CACHE_SIZE) {
+            const oldest = this.#live.keys().next();
+            if (oldest.done === true)
+                return;
+            const doc = this.#live.get(oldest.value);
+            this.#live.delete(oldest.value);
+            // DESTROYED, not just dropped. A Y.Doc holds observers; releasing the reference without
+            // destroying it leaves them attached and the memory reachable, which is the leak this cache
+            // exists to prevent wearing a different shape.
+            doc?.destroy();
+            this.#logger.debug("document.live.evicted", { resident: this.#live.size });
+        }
+    }
+}
+//# sourceMappingURL=document-live-docs.js.map

package/dist/document-live-docs.js.map

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