@cello-protocol/daemon 0.0.120 → 0.0.122

package/dist/document-store.js

@@ -0,0 +1,752 @@
+/**
+ * DOD-DOC-STORE-1 — the daemon's three document tables (§16.7-12).
+ *
+ * TWO LAYERS, NOT ONE (§14). Storing only a merged Yjs binary would discard the signed envelope
+ * chain that makes a seal verifiable, so both are kept:
+ *
+ *   `document_envelopes`  — the IMMUTABLE log: signatures, provenance, the per-document chain.
+ *                           This is the truth.
+ *   `document_snapshots`  — a MATERIALIZATION for fast start. Disposable by construction:
+ *                           delete it and it rebuilds from the log, byte-identical.
+ *
+ * The distinction is load-bearing rather than stylistic. Live Yjs state deliberately does NOT
+ * survive a daemon restart — CELLO's invariant is daemon-up-is-CELLO-on — and that is only safe
+ * because the log makes rebuilding a lookup rather than an archaeology exercise.
+ *
+ * THIS MODULE PERSISTS; IT DOES NOT APPLY. Replay is INJECTED (`rebuildSnapshot`), so the store
+ * owns *what to replay and in what order* while the engine (DOD-DOC-ENGINE-1) owns *how to
+ * apply*. That keeps `yjs` out of this file's imports entirely and keeps the P0/P1 boundary
+ * honest — a store that quietly grew a Y.Doc would be the engine wearing a store's name.
+ *
+ * WHAT IS NEVER STORED HERE: a Yjs clientID. §14's one-line rule is "let Yjs mint its own per
+ * live Y.Doc; never derive it from agent identity, never persist and restore one." DOD-DOC-FUZZ-1
+ * measured the cost of getting this wrong — two live docs sharing a clientID means the colliding
+ * writer silently wins, the honest client's update is accepted-and-dropped, and the result is a
+ * splice of two authors with an EMPTY pending set and no error on any path. So the snapshot
+ * stores a binary and a state vector, and nothing that could be restored into a live document as
+ * an identity.
+ *
+ * KEYED ON STABLE IDS ONLY. `agent_id` and `document_id`, never `agent_name` — it is a mutable
+ * display label and reusable after retirement. The M7 session tables join on `agent_name`; that
+ * is a known defect (`DOD-AGENT-ID-JOINKEY-1`), not a precedent to copy.
+ */
+/** Thrown when a read path refuses to materialize over a chain that does not verify. */
+export class DocumentChainError extends Error {
+    reason;
+    detail;
+    constructor(reason, detail) {
+        super(`${reason}: ${detail}`);
+        this.name = "DocumentChainError";
+        this.reason = reason;
+        this.detail = detail;
+    }
+}
+const CREATE_DOCUMENTS_SQL = `
+  CREATE TABLE IF NOT EXISTS documents (
+    owner_agent_id  TEXT    NOT NULL,
+    document_id     TEXT    NOT NULL,
+    peer_agent_id   TEXT    NOT NULL,
+    document_type   TEXT    NOT NULL,
+    properties      TEXT    NOT NULL,
+    status          TEXT    NOT NULL CHECK (status IN ('active', 'closed', 'killed', 'stalled')),
+    created_at      INTEGER NOT NULL,
+    PRIMARY KEY (owner_agent_id, document_id)
+  );
+`;
+const CREATE_ENVELOPES_SQL = `
+  CREATE TABLE IF NOT EXISTS document_envelopes (
+    owner_agent_id  TEXT    NOT NULL,
+    document_id     TEXT    NOT NULL,
+    envelope_hash   TEXT    NOT NULL,
+    sender_agent_id TEXT    NOT NULL,
+    doc_prev_hash   TEXT,
+    epoch_id        INTEGER NOT NULL,
+    signature       BLOB    NOT NULL,
+    state_vector    BLOB    NOT NULL,
+    payload         BLOB,
+    kind            TEXT    NOT NULL CHECK (kind IN ('update', 'withdrawal', 'rejection')),
+    references_hash TEXT,
+    created_at      INTEGER NOT NULL,
+    log_index       INTEGER NOT NULL,
+    -- DELIVERY-1. Pending outbound is DERIVED from these columns rather than held in a queue:
+    -- a queue in memory does not survive a restart, and a queue in its own table is a second
+    -- source of truth that can disagree with the log about what was sent. "Unacknowledged
+    -- envelopes I authored" is the whole definition, and it is a WHERE clause.
+    -- TWO facts, and they are genuinely different: delivered_at is when the envelope LEFT (or was
+    -- parked for an offline peer), acked_at is when the peer's daemon said it admitted or rejected
+    -- it. An earlier version had delivered_at with no real writer — its only assignment was a
+    -- COALESCE inside the ack, so it always equalled acked_at and the distinction was one the
+    -- schema could not express. It has a writer now (markDelivered), so the distinction is real:
+    -- "sent, awaiting confirmation" is exactly the state a store-and-forward transport leaves an
+    -- envelope in, and an operator asking why something has not landed needs to tell it from
+    -- "never sent".
+    delivered_at    INTEGER,
+    acked_at        INTEGER,
+    -- How many times delivery has been attempted, and when the next attempt is due. On the row,
+    -- because a backoff that resets on restart is not a backoff — a daemon restarting in a
+    -- reconnect loop would hammer an unreachable peer at full rate forever.
+    attempts        INTEGER NOT NULL DEFAULT 0,
+    next_attempt_at INTEGER,
+    PRIMARY KEY (owner_agent_id, document_id, envelope_hash),
+    -- A duplicate index would make ORDER BY log_index non-deterministic, and this log's entire
+    -- value is deterministic replay. Two daemons on one DB file (the orphan-process case this
+    -- repo has been bitten by) would otherwise each compute the same next index and both insert.
+    UNIQUE (owner_agent_id, document_id, log_index),
+    -- An audit record carries no content, and replay SKIPS payload-free non-update rows on that
+    -- basis. Enforce it here rather than relying on the convention: if a withdrawal ever carried
+    -- a payload and were later purged, replay would skip it and rebuild SHORT — the exact
+    -- divergence the purged-update refusal exists to prevent.
+    CHECK (kind = 'update' OR payload IS NULL),
+    -- Rows cannot exist for a document that was never created. The reference store makes the
+    -- same call in writing: an unscoped row must be impossible to write, not merely discouraged
+    -- by a query convention every future caller has to remember.
+    FOREIGN KEY (owner_agent_id, document_id) REFERENCES documents (owner_agent_id, document_id)
+  );
+`;
+/**
+ * Quarantined updates (DOD-DOC-REJECT-1). A separate table, deliberately:
+ *
+ * `document_envelopes` cannot hold them — its CHECK forbids a payload on a non-update row — and
+ * putting the refused bytes in as an `update` row would be worse, because `replay` applies every
+ * payload in order and does not honour references. The refused content would come back on every
+ * rebuild, which is the opposite of quarantine.
+ *
+ * So the log stays clean and replay is untouched, while the bytes a `0x05` leaf references
+ * actually survive a restart — which is the whole point of "held, never discarded" (§3.2).
+ */
+const CREATE_QUARANTINE_SQL = `
+  CREATE TABLE IF NOT EXISTS document_quarantine (
+    owner_agent_id        TEXT    NOT NULL,
+    document_id           TEXT    NOT NULL,
+    rejected_envelope_hash TEXT   NOT NULL,
+    -- The 0x05 leaf THIS row belongs to. It is the PK because one refused envelope can be refused
+    -- MORE THAN ONCE, for different reasons, across retry rounds — the rejection protocol's normal
+    -- path. Keyed on the REFUSED envelope instead, the second round's bytes, reason, rule and limit
+    -- were dropped by ON CONFLICT DO NOTHING with no log line, and the stall message then told the
+    -- operator "the most recent reason was" and printed the OLDEST. One 0x05 leaf, one row.
+    rejection_envelope_hash TEXT  NOT NULL,
+    -- The refused envelope's OWN chain link and author, so verifyChainLinkage can bridge across
+    -- it. The refused payload is deliberately never written to the log (see the header), which
+    -- would otherwise leave the peer's supersession chaining onto a hash that is nowhere.
+    rejected_sender_agent_id TEXT NOT NULL,
+    rejected_doc_prev_hash TEXT,
+    payload               BLOB    NOT NULL,
+    reason                TEXT    NOT NULL,
+    detail                TEXT,
+    rule                  TEXT,
+    limit_name            TEXT,
+    limit_value           INTEGER,
+    limit_actual          INTEGER,
+    created_at            INTEGER NOT NULL,
+    PRIMARY KEY (owner_agent_id, document_id, rejection_envelope_hash),
+    FOREIGN KEY (owner_agent_id, document_id) REFERENCES documents (owner_agent_id, document_id)
+  );
+`;
+/**
+ * Rejections we RECEIVED (§3.2 "both sides"). A separate table from `document_quarantine` because
+ * the two hold different facts: quarantine holds bytes WE refused, this holds the peer's refusal of
+ * bytes we authored — we hold no payload of theirs to quarantine.
+ *
+ * It is durable rather than a log line because everything an operator needs on the publishing side
+ * depends on it surviving a restart: why their work was refused, and how many rounds remain before
+ * the document stalls. Without a row, the sending side counted its OWN rejections — which on a pure
+ * publisher is zero forever — so the retry bound existed only on the side that never loops.
+ */
+const CREATE_REJECTIONS_RECEIVED_SQL = `
+  CREATE TABLE IF NOT EXISTS document_rejections_received (
+    owner_agent_id         TEXT    NOT NULL,
+    document_id            TEXT    NOT NULL,
+    rejection_envelope_hash TEXT   NOT NULL,
+    rejected_envelope_hash TEXT    NOT NULL,
+    from_agent_id          TEXT    NOT NULL,
+    reason                 TEXT    NOT NULL,
+    detail                 TEXT,
+    created_at             INTEGER NOT NULL,
+    PRIMARY KEY (owner_agent_id, document_id, rejection_envelope_hash),
+    FOREIGN KEY (owner_agent_id, document_id) REFERENCES documents (owner_agent_id, document_id)
+  );
+`;
+/** Mirrors `DocumentLifecycle`'s definition exactly — see the note at the exec site. */
+const CREATE_WITHDRAWALS_SQL = `
+  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)
+  );
+`;
+const CREATE_SNAPSHOTS_SQL = `
+  CREATE TABLE IF NOT EXISTS document_snapshots (
+    owner_agent_id      TEXT    NOT NULL,
+    document_id         TEXT    NOT NULL,
+    binary              BLOB    NOT NULL,
+    state_vector        BLOB    NOT NULL,
+    last_applied_index  INTEGER NOT NULL,
+    PRIMARY KEY (owner_agent_id, document_id),
+    FOREIGN KEY (owner_agent_id, document_id) REFERENCES documents (owner_agent_id, document_id)
+  );
+`;
+export class DocumentStore {
+    #db;
+    #logger;
+    /**
+     * The underlying handle, for modules that own their OWN tables alongside this one
+     * (DocumentLifecycle). Deliberately not a licence to query this store's tables from outside —
+     * every one of them has a method here, and a second query path is a second set of rules about
+     * scoping that nobody remembers to keep in step.
+     */
+    get rawDb() {
+        return this.#db;
+    }
+    constructor(db, logger) {
+        this.#db = db;
+        this.#logger = logger;
+        this.#db.exec(CREATE_DOCUMENTS_SQL);
+        this.#db.exec(CREATE_ENVELOPES_SQL);
+        this.#db.exec(CREATE_QUARANTINE_SQL);
+        this.#db.exec(CREATE_REJECTIONS_RECEIVED_SQL);
+        // Owned by DocumentLifecycle, created HERE too because `pendingDeliveries` references it and a
+        // store used without the lifecycle module is a legitimate configuration. Both statements are
+        // CREATE TABLE IF NOT EXISTS over the same definition, so whichever runs first wins and the
+        // other is a no-op — the alternative is a query that throws on a missing table and takes an
+        // entire delivery pass down with it.
+        this.#db.exec(CREATE_WITHDRAWALS_SQL);
+        this.#db.exec(CREATE_SNAPSHOTS_SQL);
+        // Reading the log in arrival order is the only access pattern that matters.
+        this.#db.exec("CREATE INDEX IF NOT EXISTS idx_document_envelopes_order ON document_envelopes (owner_agent_id, document_id, log_index)");
+    }
+    // ─── documents ────────────────────────────────────────────────────────────
+    createDocument(row) {
+        this.#db
+            .prepare(
+        // Scoped to the identity conflict only — a bare OR IGNORE would also swallow the status
+        // CHECK, leaving the caller believing a document exists that was never stored, and the
+        // failure would surface later as a foreign-key error on the first append.
+        `INSERT INTO documents
+           (owner_agent_id, document_id, peer_agent_id, document_type, properties, status, created_at)
+         VALUES (?, ?, ?, ?, ?, ?, ?)
+         ON CONFLICT (owner_agent_id, document_id) DO NOTHING`)
+            .run(row.ownerAgentId, row.documentId, row.peerAgentId, row.documentType, JSON.stringify(row.properties), row.status, row.createdAtMs);
+    }
+    getDocument(ownerAgentId, documentId) {
+        const r = this.#db
+            .prepare("SELECT * FROM documents WHERE owner_agent_id = ? AND document_id = ?")
+            .get(ownerAgentId, documentId);
+        return r ? toDocumentRow(r) : null;
+    }
+    listDocuments(ownerAgentId) {
+        const rows = this.#db
+            .prepare("SELECT * FROM documents WHERE owner_agent_id = ? ORDER BY created_at ASC")
+            .all(ownerAgentId);
+        return rows.map(toDocumentRow);
+    }
+    setDocumentStatus(ownerAgentId, documentId, status) {
+        this.#db
+            .prepare("UPDATE documents SET status = ? WHERE owner_agent_id = ? AND document_id = ?")
+            .run(status, ownerAgentId, documentId);
+    }
+    // ─── the append-only envelope log ─────────────────────────────────────────
+    /**
+     * Append an envelope at the next log position.
+     *
+     * IMMUTABLE AT A HASH: the conflict clause is scoped to the envelope hash ALONE, so a
+     * re-delivery — or a peer replaying the same hash with different bytes — cannot overwrite what
+     * was recorded. Returns whether a new row was written, so the caller can tell a genuine append
+     * from a duplicate rather than inferring it.
+     *
+     * Scoped deliberately, not written as a bare `OR IGNORE`: that form suppresses CHECK, UNIQUE
+     * and NOT NULL as well, which on an append-only log means a malformed `kind` or a colliding
+     * `log_index` would be DROPPED and reported to the caller as an already-seen duplicate. Every
+     * constraint except the hash conflict must throw, or `false` means three different things the
+     * caller cannot tell apart.
+     */
+    appendEnvelope(ownerAgentId, envelope) {
+        // The log index is computed INSIDE the insert, not read first and passed in. A read-then-write
+        // is safe within one process (this API is synchronous throughout), but two daemons on one DB
+        // file — the orphan-process case this repo has hit before — would each read the same MAX and
+        // each insert it. A duplicate index makes ORDER BY log_index non-deterministic, and
+        // deterministic replay is this log's entire purpose. The UNIQUE constraint is the backstop.
+        let info;
+        try {
+            info = this.#db
+                .prepare(`INSERT INTO document_envelopes
+           (owner_agent_id, document_id, envelope_hash, sender_agent_id, doc_prev_hash, epoch_id,
+            signature, state_vector, payload, kind, references_hash, created_at, log_index)
+         SELECT ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?,
+                COALESCE((SELECT MAX(log_index) + 1 FROM document_envelopes
+                           WHERE owner_agent_id = ? AND document_id = ?), 0)
+         ON CONFLICT (owner_agent_id, document_id, envelope_hash) DO NOTHING`)
+                .run(ownerAgentId, envelope.documentId, envelope.envelopeHash, envelope.senderAgentId, envelope.docPrevHash, envelope.epochId, Buffer.from(envelope.signature), Buffer.from(envelope.stateVector), envelope.payload === null ? null : Buffer.from(envelope.payload), envelope.kind, envelope.referencesEnvelopeHash ?? null, envelope.createdAtMs, ownerAgentId, envelope.documentId);
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            // SQLite says "FOREIGN KEY constraint failed" and nothing else — not which document, not
+            // which owner, not that a `documents` row is missing. That is the message an operator meets
+            // when an envelope arrives before its document exists, so it has to name its own cause.
+            if (message.includes("FOREIGN KEY")) {
+                throw new Error(`document_envelope_unscoped: no document ${envelope.documentId.slice(0, 16)}… exists for ` +
+                    `owner ${ownerAgentId.slice(0, 16)}… — create the document before appending to its log`);
+            }
+            throw err;
+        }
+        return Number(info.changes) > 0;
+    }
+    /**
+     * Envelopes at or after `fromIndex`, in log order. This is what makes `lastAppliedIndex` the
+     * lookup §14 asks for: resume an incremental rebuild at `lastAppliedIndex + 1` without reading
+     * the whole log.
+     */
+    getEnvelopesSince(ownerAgentId, documentId, fromIndex) {
+        const rows = this.#db
+            .prepare(`SELECT * FROM document_envelopes
+          WHERE owner_agent_id = ? AND document_id = ? AND log_index >= ?
+          ORDER BY log_index ASC`)
+            .all(ownerAgentId, documentId, fromIndex);
+        return rows.map(toEnvelopeRow);
+    }
+    getEnvelopeLog(ownerAgentId, documentId) {
+        const rows = this.#db
+            .prepare(`SELECT * FROM document_envelopes
+          WHERE owner_agent_id = ? AND document_id = ? ORDER BY log_index ASC`)
+            .all(ownerAgentId, documentId);
+        return rows.map(toEnvelopeRow);
+    }
+    /**
+     * Verify each sender's `doc_prev_hash` chain independently.
+     *
+     * The log interleaves both parties' envelopes, so there is no single total order to check —
+     * §16.7-5 defines replay set-based per epoch for exactly this reason. What must hold is that
+     * every sender's own links form one unbroken chain from a single genesis.
+     *
+     * A break REFUSES and names the sender and the missing predecessor. Skipping the leaf and
+     * carrying on would leave a document that reads as complete while missing operations, which is
+     * the silent-divergence failure the chain exists to prevent.
+     *
+     * LINKAGE ONLY — the name says so deliberately. This verifies no signature and does not check
+     * that `envelope_hash` hashes the content; neither is possible here (no key, no encoder). A
+     * caller must not read `ok: true` as authenticity — that belongs to the engine.
+     */
+    verifyChainLinkage(ownerAgentId, documentId) {
+        const log = this.getEnvelopeLog(ownerAgentId, documentId);
+        // BRIDGE THE REFUSED ENVELOPES. A refused update's payload is never written to the log — that
+        // is what makes the refusal real across a restart — but the peer does not know it was refused
+        // when it authors the next envelope, so its supersession chains onto a hash the log does not
+        // contain. Without the bridge that reads as `document_chain_broken`, the document refuses to
+        // rebuild, and the operator is sent to debug the chain layer for a rejection-protocol event.
+        //
+        // These stubs exist ONLY for verification. They carry no payload and are never returned by
+        // `getEnvelopeLog`, so replay cannot see them and the refused content cannot come back.
+        const stubs = this.listQuarantined(ownerAgentId, documentId).map((q) => ({
+            envelopeHash: q.rejectedEnvelopeHash,
+            documentId: q.documentId,
+            senderAgentId: q.rejectedSenderAgentId,
+            docPrevHash: q.rejectedDocPrevHash,
+            epochId: 0,
+            signature: new Uint8Array(0),
+            stateVector: new Uint8Array(0),
+            payload: null,
+            kind: "rejection",
+            referencesEnvelopeHash: null,
+            createdAtMs: q.createdAtMs,
+        }));
+        // One refused envelope can carry several quarantine rows (one per retry round), and the chain
+        // has exactly one node for it.
+        const seenStub = new Set();
+        const bySender = new Map();
+        for (const stub of stubs) {
+            if (seenStub.has(stub.envelopeHash))
+                continue;
+            seenStub.add(stub.envelopeHash);
+            const list = bySender.get(stub.senderAgentId);
+            if (list)
+                list.push(stub);
+            else
+                bySender.set(stub.senderAgentId, [stub]);
+        }
+        for (const e of log) {
+            const list = bySender.get(e.senderAgentId);
+            if (list)
+                list.push(e);
+            else
+                bySender.set(e.senderAgentId, [e]);
+        }
+        for (const [sender, envelopes] of bySender) {
+            const present = new Set(envelopes.map((e) => e.envelopeHash));
+            const genesis = envelopes.filter((e) => e.docPrevHash === null);
+            if (genesis.length !== 1) {
+                return {
+                    ok: false,
+                    reason: "document_chain_forked",
+                    detail: `sender ${sender.slice(0, 16)}… has ${genesis.length} genesis envelopes for document ` +
+                        `${documentId.slice(0, 16)}… — a chain has exactly one`,
+                };
+            }
+            // Every link must resolve. Checked first so a missing predecessor reports as BROKEN rather
+            // than as the unreachability it would also cause.
+            for (const e of envelopes) {
+                if (e.docPrevHash !== null && !present.has(e.docPrevHash)) {
+                    return {
+                        ok: false,
+                        reason: "document_chain_broken",
+                        detail: `sender ${sender.slice(0, 16)}… envelope ${e.envelopeHash.slice(0, 16)}… links to ` +
+                            `${e.docPrevHash.slice(0, 16)}…, which is absent from the log and is not among this ` +
+                            `document's refused envelopes either — so this is a gap in the chain itself, not a ` +
+                            `rejection`,
+                    };
+                }
+            }
+            // REACHABILITY, not structural heuristics. Walk forward from the one genesis and require
+            // the walk to cover every envelope this sender authored. That single check subsumes the
+            // duplicate-genesis case, the duplicate-predecessor fork, AND every cycle shape — including
+            // a disjoint cycle sitting alongside a perfectly good genesis chain, which counting roots
+            // and predecessors cannot see. `doc_prev_hash` is peer-controlled, so this is a hostile
+            // input path and the verifier is the only thing between a crafted log and a persisted
+            // snapshot.
+            const childOf = new Map();
+            for (const e of envelopes) {
+                if (e.docPrevHash === null)
+                    continue;
+                const siblings = childOf.get(e.docPrevHash);
+                if (siblings)
+                    siblings.push(e);
+                else
+                    childOf.set(e.docPrevHash, [e]);
+            }
+            const reached = new Set();
+            let cursor = genesis[0];
+            while (cursor) {
+                if (reached.has(cursor.envelopeHash))
+                    break; // defensive; a cycle cannot include genesis
+                reached.add(cursor.envelopeHash);
+                const children = childOf.get(cursor.envelopeHash) ?? [];
+                if (children.length > 1) {
+                    return {
+                        ok: false,
+                        reason: "document_chain_forked",
+                        detail: `sender ${sender.slice(0, 16)}… has ${children.length} envelopes claiming predecessor ` +
+                            `${cursor.envelopeHash.slice(0, 16)}… — a chain branches nowhere`,
+                    };
+                }
+                cursor = children[0];
+            }
+            if (reached.size !== envelopes.length) {
+                return {
+                    ok: false,
+                    reason: "document_chain_forked",
+                    detail: `sender ${sender.slice(0, 16)}… has ${envelopes.length - reached.size} envelopes ` +
+                        `unreachable from its genesis for document ${documentId.slice(0, 16)}… — a detached ` +
+                        `cycle or branch, not a chain`,
+                };
+            }
+        }
+        return { ok: true };
+    }
+    // ─── quarantine (held, never discarded) ───────────────────────────────────
+    /**
+     * Hold a refused update's bytes. Idempotent per REJECTION (per 0x05 leaf), not per refused
+     * envelope — one envelope may be refused across several retry rounds and each round's reason,
+     * rule and limit are distinct facts an operator needs.
+     *
+     * Returns whether a row was written, so a caller never has to infer it. The previous signature
+     * returned void and the conflict clause silently dropped every round after the first.
+     */
+    holdQuarantined(ownerAgentId, row) {
+        const info = this.#db
+            .prepare(`INSERT INTO document_quarantine
+           (owner_agent_id, document_id, rejection_envelope_hash, rejected_envelope_hash,
+            rejected_sender_agent_id, rejected_doc_prev_hash, payload, reason, detail,
+            rule, limit_name, limit_value, limit_actual, created_at)
+         VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+         ON CONFLICT (owner_agent_id, document_id, rejection_envelope_hash) DO NOTHING`)
+            .run(ownerAgentId, row.documentId, row.rejectionEnvelopeHash, row.rejectedEnvelopeHash, row.rejectedSenderAgentId, row.rejectedDocPrevHash, Buffer.from(row.payload), row.reason, row.detail ?? null, row.rule ?? null, row.limitName ?? null, row.limitValue ?? null, row.limitActual ?? null, row.createdAtMs);
+        return Number(info.changes) > 0;
+    }
+    listQuarantined(ownerAgentId, documentId) {
+        const rows = this.#db
+            .prepare(
+        // rowid breaks the tie. Several rounds can land inside one millisecond, and `created_at`
+        // alone then leaves the order to SQLite — which is what an operator is shown as "the most
+        // recent reason". Insertion order is the real answer and rowid is it.
+        `SELECT * FROM document_quarantine
+          WHERE owner_agent_id = ? AND document_id = ?
+          ORDER BY created_at ASC, rowid ASC`)
+            .all(ownerAgentId, documentId);
+        return rows.map((r) => ({
+            documentId: r["document_id"],
+            rejectionEnvelopeHash: r["rejection_envelope_hash"],
+            rejectedEnvelopeHash: r["rejected_envelope_hash"],
+            rejectedSenderAgentId: r["rejected_sender_agent_id"],
+            rejectedDocPrevHash: r["rejected_doc_prev_hash"] ?? null,
+            payload: toU8(r["payload"]),
+            reason: r["reason"],
+            detail: r["detail"] ?? undefined,
+            rule: r["rule"] ?? undefined,
+            limitName: r["limit_name"] ?? undefined,
+            limitValue: r["limit_value"] ?? undefined,
+            limitActual: r["limit_actual"] ?? undefined,
+            createdAtMs: r["created_at"],
+        }));
+    }
+    /**
+     * Release every entry for a refused envelope once its superseding update has been admitted.
+     * Returns whether anything was released. Keyed by the REFUSED envelope rather than the rejection
+     * leaf, because admitting the supersession resolves all of that envelope's rounds at once.
+     */
+    releaseQuarantined(ownerAgentId, documentId, rejectedEnvelopeHash) {
+        const info = this.#db
+            .prepare(`DELETE FROM document_quarantine
+          WHERE owner_agent_id = ? AND document_id = ? AND rejected_envelope_hash = ?`)
+            .run(ownerAgentId, documentId, rejectedEnvelopeHash);
+        return Number(info.changes) > 0;
+    }
+    /** The rejecting agent's most recent envelope for this document, for chain linkage. */
+    lastEnvelopeHashBySender(ownerAgentId, documentId, senderAgentId) {
+        const r = this.#db
+            .prepare(`SELECT envelope_hash FROM document_envelopes
+          WHERE owner_agent_id = ? AND document_id = ? AND sender_agent_id = ?
+          ORDER BY log_index DESC LIMIT 1`)
+            .get(ownerAgentId, documentId, senderAgentId);
+        return r?.envelope_hash ?? null;
+    }
+    // ─── delivery (DELIVERY-1) ────────────────────────────────────────────────
+    /**
+     * Envelopes this agent authored that the peer has not acknowledged, and whose next attempt is
+     * due. DERIVED — there is no queue. Survives a restart because the log does.
+     *
+     * Scoped to `senderAgentId = ownerAgentId`: an envelope we RECEIVED is not ours to deliver, and
+     * without the scope a receiver would helpfully re-send the sender's own updates back at it.
+     */
+    pendingDeliveries(ownerAgentId, nowMs, limit = 100) {
+        const rows = this.#db
+            .prepare(`SELECT * FROM document_envelopes
+          WHERE owner_agent_id = ? AND sender_agent_id = ? AND acked_at IS NULL
+            -- UPDATES only. A withdrawal record is local audit — the update it concerns was never
+            -- delivered, so there is nothing for the peer to act on — and a rejection reaches the
+            -- peer through the rejection protocol, not this worker. Without the scope the worker
+            -- would ship both, and the withdrawal would arrive as a reference to an envelope the
+            -- peer has never seen.
+            AND kind = 'update'
+            -- An ENDED document does not deliver. A killed or closed document that kept shipping
+            -- would contradict the verb the operator just used, and the peer would receive updates
+            -- on a collaboration they were told had stopped.
+            AND EXISTS (
+              SELECT 1 FROM documents d
+               WHERE d.owner_agent_id = document_envelopes.owner_agent_id
+                 AND d.document_id = document_envelopes.document_id
+                 AND d.status NOT IN ('killed', 'closed')
+            )
+            AND (next_attempt_at IS NULL OR next_attempt_at <= ?)
+            -- A WITHDRAWN update is not pending. Derived from the withdrawal record rather than a
+            -- flag on the row, so there is one fact in one place: without this the delivery worker
+            -- ships the very update the operator just withdrew.
+            --
+            -- The table is created by DocumentLifecycle, which may not have run — a store used
+            -- without it is a legitimate configuration — so the reference is guarded rather than
+            -- assumed. A missing table would otherwise throw here and take the whole delivery pass
+            -- down with it.
+            AND NOT EXISTS (
+              SELECT 1 FROM document_withdrawals w
+               WHERE w.owner_agent_id = document_envelopes.owner_agent_id
+                 AND w.document_id = document_envelopes.document_id
+                 AND w.envelope_hash = document_envelopes.envelope_hash
+            )
+          -- log_index is PER DOCUMENT, so it alone is not a total order across documents and the
+          -- bounded window could be filled by one document's backlog forever. The tiebreaks make
+          -- the window deterministic; the no-peer branch scheduling its rows is what stops one
+          -- document monopolising it.
+          ORDER BY log_index ASC, document_id ASC, envelope_hash ASC LIMIT ?`)
+            .all(ownerAgentId, ownerAgentId, nowMs, limit);
+        return rows.map(toEnvelopeRow);
+    }
+    /** Mark an attempt: bumps the counter and schedules the next one. Returns the new count. */
+    recordDeliveryAttempt(ownerAgentId, documentId, envelopeHash, nextAttemptAtMs) {
+        this.#db
+            .prepare(`UPDATE document_envelopes
+            SET attempts = attempts + 1, next_attempt_at = ?
+          WHERE owner_agent_id = ? AND document_id = ? AND envelope_hash = ?`)
+            .run(nextAttemptAtMs, ownerAgentId, documentId, envelopeHash);
+        const r = this.#db
+            .prepare(`SELECT attempts FROM document_envelopes
+          WHERE owner_agent_id = ? AND document_id = ? AND envelope_hash = ?`)
+            .get(ownerAgentId, documentId, envelopeHash);
+        return r?.attempts ?? 0;
+    }
+    /** Record that the envelope left. Not an ack — the peer has not answered yet. */
+    markDelivered(ownerAgentId, documentId, envelopeHash, nowMs) {
+        const info = this.#db
+            .prepare(`UPDATE document_envelopes SET delivered_at = COALESCE(delivered_at, ?)
+          WHERE owner_agent_id = ? AND document_id = ? AND envelope_hash = ?`)
+            .run(nowMs, ownerAgentId, documentId, envelopeHash);
+        return Number(info.changes) > 0;
+    }
+    /** Record that the peer acknowledged. Idempotent — a redelivered ack must not move the clock. */
+    markAcked(ownerAgentId, documentId, envelopeHash, nowMs) {
+        const info = this.#db
+            .prepare(`UPDATE document_envelopes SET acked_at = ?, delivered_at = COALESCE(delivered_at, ?)
+          WHERE owner_agent_id = ? AND document_id = ? AND envelope_hash = ? AND acked_at IS NULL`)
+            .run(nowMs, nowMs, ownerAgentId, documentId, envelopeHash);
+        return Number(info.changes) > 0;
+    }
+    /** Record a rejection the PEER sent us. Returns whether a row was written (idempotent by leaf). */
+    recordRejectionReceived(ownerAgentId, row) {
+        const info = this.#db
+            .prepare(`INSERT INTO document_rejections_received
+           (owner_agent_id, document_id, rejection_envelope_hash, rejected_envelope_hash,
+            from_agent_id, reason, detail, created_at)
+         VALUES (?, ?, ?, ?, ?, ?, ?, ?)
+         ON CONFLICT (owner_agent_id, document_id, rejection_envelope_hash) DO NOTHING`)
+            .run(ownerAgentId, row.documentId, row.rejectionEnvelopeHash, row.rejectedEnvelopeHash, row.fromAgentId, row.reason, row.detail ?? null, row.createdAtMs);
+        return Number(info.changes) > 0;
+    }
+    /** How many rejections this document has RECEIVED — the publishing side's retry round. */
+    countRejectionsReceived(ownerAgentId, documentId) {
+        const r = this.#db
+            .prepare(`SELECT COUNT(*) AS n FROM document_rejections_received
+          WHERE owner_agent_id = ? AND document_id = ?`)
+            .get(ownerAgentId, documentId);
+        return r?.n ?? 0;
+    }
+    /** The most recently received rejection, for the reason an operator is shown on a stall. */
+    latestRejectionReceived(ownerAgentId, documentId) {
+        const r = this.#db
+            .prepare(`SELECT reason, detail, from_agent_id FROM document_rejections_received
+          WHERE owner_agent_id = ? AND document_id = ? ORDER BY created_at DESC, rowid DESC LIMIT 1`)
+            .get(ownerAgentId, documentId);
+        if (!r)
+            return null;
+        return {
+            reason: r["reason"],
+            detail: r["detail"] ?? undefined,
+            fromAgentId: r["from_agent_id"],
+        };
+    }
+    /**
+     * How many rejection records this document carries, PER REJECTING AGENT — the retry round.
+     *
+     * Scoped by author, because a mutual exchange puts both directions' 0x05 leaves in one document
+     * log. Counting across senders conflated them, so two peers each rejecting once read as round 2
+     * and the document stalled at half the intended rounds.
+     */
+    countRejections(ownerAgentId, documentId, rejectingAgentId) {
+        const r = this.#db
+            .prepare(`SELECT COUNT(*) AS n FROM document_envelopes
+          WHERE owner_agent_id = ? AND document_id = ? AND kind = 'rejection'
+            AND sender_agent_id = ?`)
+            .get(ownerAgentId, documentId, rejectingAgentId);
+        return r?.n ?? 0;
+    }
+    // ─── the snapshot (disposable) ────────────────────────────────────────────
+    getSnapshot(ownerAgentId, documentId) {
+        const r = this.#db
+            .prepare("SELECT * FROM document_snapshots WHERE owner_agent_id = ? AND document_id = ?")
+            .get(ownerAgentId, documentId);
+        if (!r)
+            return null;
+        return {
+            binary: toU8(r["binary"]),
+            stateVector: toU8(r["state_vector"]),
+            lastAppliedIndex: r["last_applied_index"],
+        };
+    }
+    /** REPLACES — a snapshot is a cache of the log, not a second log. */
+    putSnapshot(ownerAgentId, documentId, snapshot) {
+        this.#db
+            .prepare(`INSERT OR REPLACE INTO document_snapshots
+           (owner_agent_id, document_id, binary, state_vector, last_applied_index)
+         VALUES (?, ?, ?, ?, ?)`)
+            .run(ownerAgentId, documentId, Buffer.from(snapshot.binary), Buffer.from(snapshot.stateVector), snapshot.lastAppliedIndex);
+    }
+    deleteSnapshot(ownerAgentId, documentId) {
+        this.#db
+            .prepare("DELETE FROM document_snapshots WHERE owner_agent_id = ? AND document_id = ?")
+            .run(ownerAgentId, documentId);
+    }
+    /**
+     * Rebuild a snapshot from the envelope log alone, using the caller's replay function.
+     *
+     * Payload-stripped envelopes (purged, or withdrawal/rejection records that carry none)
+     * contribute nothing to replay but STILL COUNT toward `lastAppliedIndex` — otherwise the next
+     * incremental rebuild would start behind them and replay them forever.
+     */
+    rebuildSnapshot(ownerAgentId, documentId, replay) {
+        // VERIFY BEFORE REPLAY. Rebuilding over an unverified chain is the exact silent divergence
+        // the chain exists to prevent: a log with a missing predecessor folds into a state that is
+        // quietly short of operations, and putSnapshot would then persist it as authoritative.
+        // Refusing is loud; a short document is not.
+        const verdict = this.verifyChainLinkage(ownerAgentId, documentId);
+        if (!verdict.ok) {
+            this.#logger.warn("document.chain.broken", {
+                documentId,
+                reason: verdict.reason,
+                detail: verdict.detail,
+            });
+            throw new DocumentChainError(verdict.reason, verdict.detail);
+        }
+        const log = this.getEnvelopeLog(ownerAgentId, documentId);
+        // The WHOLE log, in order — including withdrawal and rejection records, which carry no
+        // payload. The engine needs those rows to tell an expected payload-free AUDIT record from a
+        // PURGED update whose bytes are gone; filtering here would hide that distinction and make the
+        // row-shaped signature pointless. The store decides ORDER; the engine decides WHAT COUNTS.
+        const { binary, stateVector } = replay(log);
+        this.#logger.info("document.snapshot.rebuilt", {
+            documentId,
+            envelopes: log.length,
+            withPayload: log.filter((e) => e.payload !== null).length,
+        });
+        // The LAST ROW'S log_index, not the array length. They coincide only while indices are dense,
+        // which is an accident of how they are assigned rather than a guarantee.
+        return { binary, stateVector, lastAppliedIndex: log.at(-1)?.logIndex ?? -1 };
+    }
+}
+function toDocumentRow(r) {
+    return {
+        documentId: r["document_id"],
+        ownerAgentId: r["owner_agent_id"],
+        peerAgentId: r["peer_agent_id"],
+        documentType: r["document_type"],
+        properties: JSON.parse(r["properties"]),
+        status: r["status"],
+        createdAtMs: r["created_at"],
+    };
+}
+function toEnvelopeRow(r) {
+    const payload = r["payload"];
+    return {
+        envelopeHash: r["envelope_hash"],
+        documentId: r["document_id"],
+        senderAgentId: r["sender_agent_id"],
+        docPrevHash: r["doc_prev_hash"] ?? null,
+        epochId: r["epoch_id"],
+        signature: toU8(r["signature"]),
+        stateVector: toU8(r["state_vector"]),
+        payload: payload === null || payload === undefined ? null : toU8(payload),
+        kind: r["kind"],
+        referencesEnvelopeHash: r["references_hash"] ?? null,
+        createdAtMs: r["created_at"],
+        logIndex: r["log_index"],
+        deliveredAtMs: r["delivered_at"] ?? null,
+        ackedAtMs: r["acked_at"] ?? null,
+        attempts: r["attempts"] ?? 0,
+        nextAttemptAtMs: r["next_attempt_at"] ?? null,
+    };
+}
+/**
+ * Normalize a SQLite BLOB (Buffer / Uint8Array / ArrayBuffer) to a Uint8Array.
+ *
+ * REFUSES anything else rather than substituting an empty array. This is the read path for
+ * `signature`, `state_vector` and `payload`: returning `new Uint8Array()` for an unexpected type
+ * would hand back a ZERO-LENGTH SIGNATURE as if it were the stored one, and the failure would
+ * surface downstream as "signature invalid" — sending an operator to the crypto layer for what
+ * is a storage-read defect. Nothing legitimate reaches this branch; `null` is handled by callers.
+ */
+function toU8(v) {
+    if (v instanceof Uint8Array)
+        return v;
+    if (Buffer.isBuffer(v))
+        return new Uint8Array(v);
+    if (v instanceof ArrayBuffer)
+        return new Uint8Array(v);
+    throw new Error(`document_store_blob_decode_failed: expected a BLOB, got ${v === null ? "null" : typeof v}`);
+}
+//# sourceMappingURL=document-store.js.map