@cello-protocol/daemon 0.0.132 → 0.0.134

package/dist/document-rejection.js

@@ -0,0 +1,407 @@
+/**
+ * DOD-DOC-REJECT-1 — rejection and supersession (§3.2, §16.7-2).
+ *
+ * ── WHY SUPERSESSION, AND NOT "BOTH SIDES ROLL BACK" ──────────────────────────────────────────
+ *
+ * The naive protocol is: the receiver discards, the sender undoes locally, and both return to the
+ * pre-update state. It does not work, and the reason is a property of CRDTs rather than a bug.
+ *
+ * **Yjs undo adds INVERSES; it does not erase.** The rejected operations stay in the sender's
+ * document. So every later update the sender computes against the receiver's state vector
+ * re-transmits them, and the receiver — which refuses to hold them — can never integrate the
+ * legitimate work stacked causally on top, because Yjs will not apply operations whose
+ * predecessors are missing. A permanent causal gap, from a protocol that looked symmetric.
+ *
+ * The protocol that works (§3.2):
+ *   1. The receiver rejects with a REASON — a protocol message and its own `0x05` leaf, never a
+ *      silent drop. The update goes to quarantine, held rather than discarded.
+ *   2. The sender rolls back locally, which emits inverses into its own log and leaves an
+ *      auditable "wrote X, was rejected, undid X" trail.
+ *   3. The sender publishes a SUPERSEDING update against the receiver's state vector, which
+ *      necessarily carries the rejected operations PLUS their inverses plus any new work.
+ *   4. The receiver validates the now-clean projected diff — the rejected content nets to zero —
+ *      admits it, and clears the quarantine. Causality intact, both parties converge, and the
+ *      rejected content survives only as inert tombstones.
+ *
+ * ── SCOPE ─────────────────────────────────────────────────────────────────────────────────────
+ *
+ * This proves the protocol against STORE-1's local envelope log. The CBOR wire encoding is
+ * DOD-DOC-ENVELOPE-1's job and the cross-daemon proof is DOD-DOC-E2E-REJECT-1's.
+ */
+import * as Y from "yjs";
+import { buildDocumentRejectionTbs, documentRejectionHash, encodeDocumentRejection, DOCUMENT_REJECTION_VERSION, } from "@cello-protocol/protocol-types";
+/**
+ * The document stalls on the THIRD rejected round: the original refusal, one superseding attempt,
+ * and no more (§16.7-2 "one retry, then freeze").
+ *
+ * Counted in rounds rather than retries because the previous spelling — a `REJECTION_RETRY_LIMIT`
+ * of 1 compared as `round > LIMIT + 1` — permitted two retries under a name that said one, which
+ * is the kind of thing the next edit gets wrong.
+ *
+ * Bounded at all because an unbounded retry loop between two daemons that disagree is not
+ * convergence, it is a hot loop neither operator can see. Stalling is the visible failure.
+ */
+export const MAX_REJECTED_ROUNDS = 3;
+export class DocumentRejections {
+    #store;
+    #logger;
+    constructor(store, logger) {
+        this.#store = store;
+        this.#logger = logger;
+    }
+    /**
+     * Record a rejection: a `0x05` row referencing the rejected envelope, the quarantined bytes
+     * held, and a policy record carrying the reason.
+     *
+     * The envelope log is append-only, so this is a NEW ROW — nothing is edited or removed.
+     *
+     * ── HOW A REFUSAL IS ACTUALLY REALIZED, AND WHY NOT THE WAY §9 SAYS ─────────────────────────
+     *
+     * §9 phrases effectiveness as a replay-time set property: "an update leaf is effective iff no
+     * rejection leaf references it". Implemented literally that is unsound, and it was measured
+     * rather than argued. Sender publishes a base, then a refused update, then rolls back and
+     * supersedes. Replaying the log while SKIPPING the refused leaf gives:
+     *
+     *     text "agreed base. "   pendingStructs PRESENT   pendingDs PRESENT
+     *
+     * The supersession is causally stacked on the refused operations — the rollback is a DELETION of
+     * those structs and the new work is positioned after them — so dropping them leaves everything
+     * later permanently pending. The document reads as complete and is silently missing the
+     * legitimate work. §16.7-5 already retired §9's "document-log order" phrasing; this retires its
+     * effectiveness phrasing on the same grounds.
+     *
+     * What is sound: the receiver NEVER WRITES the refused payload to its log. There is nothing to
+     * subtract at replay because it was never added, and the peer's supersession — computed against
+     * the RECEIVER's state vector per §3.2 step 3 — is self-contained. Measured on the same fixture:
+     *
+     *     text "agreed base. clean text. "   pendingStructs null   pendingDs null   converged true
+     *
+     * The refused bytes do travel again inside that supersession, carrying their own inverses, which
+     * is precisely "inverses, not erasure" (§3.2) — the content nets to zero and survives only as
+     * tombstones. The bytes we refused live in `document_quarantine`, and the chain bridges across
+     * the refused envelope so the peer's next link still resolves (see `verifyChainLinkage`).
+     */
+    async reject(agentId, documentId, input) {
+        // THE SIGNED PREIMAGE (DOD-DOC-REJECT-2). Until it existed, this method took a `signature` from
+        // its caller with nothing defining what that signature was OVER — so it could only ever be
+        // filled dishonestly, which is what writing the composition-root signer proved. The rejection
+        // is now built, signed, and its LEAF HASH derived from the same preimage: the leaf commits to
+        // exactly the bytes whose signature was verified.
+        // DUPLICATE DETECTION MOVED UP FRONT. It used to fall out of the leaf hash colliding, because
+        // that hash was sha256(envelope + reason + nonce) and a caller reusing the nonce produced the
+        // same row. The real preimage binds the ROUND and the TIMESTAMP, so two rejections of the same
+        // envelope for the same reason now hash differently and would each advance the round — driving
+        // a document to `stalled` on retries that never happened. The check has to be on what makes a
+        // rejection the SAME rejection: this envelope, refused for this reason, by us.
+        const already = this.#store
+            .listQuarantined(agentId, documentId)
+            .find((q) => q.rejectedEnvelopeHash === input.rejectedEnvelopeHash && q.reason === input.reason);
+        if (already) {
+            this.#logger.warn("document.rejection.duplicate", {
+                documentId,
+                rejectedEnvelopeHash: input.rejectedEnvelopeHash,
+                reason: input.reason,
+            });
+            return {
+                stalled: this.#isStalled(agentId, documentId),
+                round: this.#round(agentId, documentId),
+            };
+        }
+        const round = this.#round(agentId, documentId) + 1;
+        const envelope = {
+            type: "document_rejection",
+            rejection_version: DOCUMENT_REJECTION_VERSION,
+            document_id: documentId,
+            rejected_envelope_hash: input.rejectedEnvelopeHash,
+            rejecting_agent_id: agentId,
+            reason: input.reason,
+            ...(input.detail === undefined ? {} : { detail: input.detail }),
+            round,
+            rejected_at_ms: input.nowMs,
+            signature: new Uint8Array(0),
+        };
+        envelope.signature = await input.sign(buildDocumentRejectionTbs(envelope));
+        // CHAIN IT. Writing `docPrevHash: null` made every rejection a second GENESIS row for this
+        // agent, so two rejections forked the chain — and the retry protocol guarantees at least two
+        // before a stall. `verifyChainLinkage` then refuses, and since `rebuildSnapshot` is how a
+        // document survives a restart, the document rebuilt until the next daemon start and was
+        // permanently unopenable after it. Measured. A rejection is this agent's own authored act, so
+        // it belongs in this agent's own chain.
+        const rejectionEnvelopeHash = documentRejectionHash(envelope);
+        const appended = this.#store.appendEnvelope(agentId, {
+            envelopeHash: rejectionEnvelopeHash,
+            documentId,
+            senderAgentId: agentId, // WE authored the rejection, whoever authored the update
+            docPrevHash: this.#store.lastEnvelopeHashBySender(agentId, documentId, agentId),
+            epochId: 0,
+            signature: envelope.signature,
+            // The rejection's own state vector — what THIS agent had seen when it refused. Empty is
+            // honest here: a rejection asserts nothing about document state, and REJECT-1's requirement
+            // was that the SIGNATURE be real, not that every field be populated for its own sake.
+            stateVector: new Uint8Array(0),
+            payload: null, // an audit record carries no content
+            kind: "rejection",
+            referencesEnvelopeHash: input.rejectedEnvelopeHash,
+            createdAtMs: input.nowMs,
+        });
+        if (!appended) {
+            // The store tells callers whether a row was written precisely so this is not inferred. A
+            // duplicate must not advance the retry round, or a document reaches `stalled` with fewer
+            // rejection leaves than rounds and an auditor replaying the log cannot see why.
+            this.#logger.warn("document.rejection.duplicate", {
+                documentId,
+                rejectedEnvelopeHash: input.rejectedEnvelopeHash,
+                reason: input.reason,
+            });
+            return { stalled: this.#isStalled(agentId, documentId), round: this.#round(agentId, documentId) };
+        }
+        // PERSISTED, not remembered. The 0x05 leaf references these bytes; holding them in a Map
+        // meant the reference outlived the thing it referenced across a restart.
+        const held = this.#store.holdQuarantined(agentId, {
+            documentId,
+            rejectionEnvelopeHash,
+            rejectedEnvelopeHash: input.rejectedEnvelopeHash,
+            // The refused envelope's own author and chain link, so `verifyChainLinkage` can bridge it —
+            // the peer chains its supersession onto an envelope our log deliberately never holds.
+            rejectedSenderAgentId: input.senderAgentId,
+            rejectedDocPrevHash: input.rejectedDocPrevHash,
+            // COPY: the caller's buffer may be a pooled network read, and a 0x05 leaf must reference
+            // the bytes that were actually refused.
+            payload: new Uint8Array(input.quarantined),
+            reason: input.reason,
+            detail: input.detail,
+            // The gate produces these deliberately; dropping them leaves an operator unable to see
+            // WHICH rule refused or WHAT number was exceeded.
+            rule: input.rule,
+            limitName: input.limit?.name,
+            limitValue: input.limit?.limit,
+            limitActual: input.limit?.actual,
+            createdAtMs: input.nowMs,
+        });
+        if (!held) {
+            // Cannot happen while the leaf hash is unique per rejection, which the append above already
+            // established. Logged rather than assumed: the previous key silently dropped every round
+            // after the first, and the way that stayed invisible was precisely that nothing said so.
+            this.#logger.error("document.rejection.quarantine_not_written", {
+                documentId,
+                rejectionEnvelopeHash,
+                rejectedEnvelopeHash: input.rejectedEnvelopeHash,
+            });
+        }
+        // The policy record — on BOTH sides, per §3.2. This is the sending half; the receiving half
+        // is written when a rejection arrives.
+        this.#logger.warn("document.rejection.sent", {
+            documentId,
+            senderAgentId: input.senderAgentId,
+            reason: input.reason,
+            detail: input.detail,
+            // Carried, not merely stored: an operator asking "why was this refused" needs the rule and
+            // the number, and a column no surface reads is a column that is not there.
+            rule: input.rule,
+            limitName: input.limit?.name,
+            limitValue: input.limit?.limit,
+            limitActual: input.limit?.actual,
+            round,
+        });
+        const stalled = round >= MAX_REJECTED_ROUNDS;
+        const alreadyStalled = this.#store.getDocument(agentId, documentId)?.status === "stalled";
+        if (stalled && !alreadyStalled) {
+            this.#store.setDocumentStatus(agentId, documentId, "stalled");
+            // Once, not on every subsequent refusal — a stalled document that keeps shouting is noise
+            // an operator learns to filter.
+            this.#logger.error("document.stalled", {
+                documentId,
+                reason: input.reason,
+                detail: input.detail,
+                rounds: round,
+            });
+        }
+        // The bytes go back to the caller so the peer can actually be told. See `RejectionOutcome.wire`.
+        return { stalled, round, wire: encodeDocumentRejection(envelope) };
+    }
+    /**
+     * Record a rejection ARRIVING from the peer — the receiving half of §3.2's "both sides".
+     *
+     * ── THE ROUTING DECISION (the DoD requires it resolved in-unit) ─────────────────────────────
+     *
+     * A document rejection is written **daemon-side**, into this document's own log and quarantine,
+     * NOT through the gateway record store's `source` discriminator.
+     *
+     * The gateway's record store exists for SCREENING verdicts, and most V1 rejection reasons are
+     * not screening at all — `append_only`, the receiver-local limits, malformed updates, unresolved
+     * dependencies. Routing every document rejection through a screening store would file structural
+     * protocol events as policy verdicts, and it would couple this unit to a schema owned by a
+     * component that is not involved. DOD-DOC-SCREEN-1 is parked, so that coupling would also have
+     * to be built speculatively and unwound if screening lands differently.
+     *
+     * When SCREEN-1 does land, a rejection whose reason came from the screening rule can ADDITIONALLY
+     * write a gateway record — the discriminator exists for exactly that, and adding it later costs
+     * nothing, whereas removing a premature coupling costs a migration.
+     */
+    recordIncomingRejection(agentId, documentId, input) {
+        // DURABLE, not a log line. Everything the PUBLISHING operator needs depends on this surviving
+        // a restart: why their work was refused, and how many rounds remain before the document
+        // stalls. It also has to exist for the retry bound to bind at all — the round was counted from
+        // rejections this agent AUTHORED, which on a pure publisher is zero forever, so the loop the
+        // limit exists to stop was the one side that had no limit.
+        const written = this.#store.recordRejectionReceived(agentId, {
+            documentId,
+            rejectionEnvelopeHash: input.rejectionEnvelopeHash,
+            rejectedEnvelopeHash: input.rejectedEnvelopeHash,
+            fromAgentId: input.fromAgentId,
+            reason: input.reason,
+            detail: input.detail,
+            createdAtMs: Date.now(),
+        });
+        const round = this.#store.countRejectionsReceived(agentId, documentId);
+        if (!written) {
+            this.#logger.warn("document.rejection.received_duplicate", {
+                documentId,
+                rejectionEnvelopeHash: input.rejectionEnvelopeHash,
+                round,
+            });
+            return { stalled: this.#isStalled(agentId, documentId), round };
+        }
+        this.#logger.warn("document.rejection.received", {
+            documentId,
+            fromAgentId: input.fromAgentId,
+            rejectedEnvelopeHash: input.rejectedEnvelopeHash,
+            reason: input.reason,
+            detail: input.detail,
+            round,
+        });
+        // The publisher stops superseding on the same threshold the receiver stops accepting on. Two
+        // sides of one bound: without this, the receiver freezes and the sender keeps retrying into a
+        // document that will never take it.
+        const stalled = round >= MAX_REJECTED_ROUNDS;
+        if (stalled && !this.#isStalled(agentId, documentId)) {
+            this.#store.setDocumentStatus(agentId, documentId, "stalled");
+            this.#logger.error("document.stalled", {
+                documentId,
+                reason: input.reason,
+                detail: input.detail,
+                rounds: round,
+                side: "publisher",
+            });
+        }
+        return { stalled, round };
+    }
+    /** Entries held for this document — never admitted, never discarded (§3.2). From the store. */
+    quarantined(agentId, documentId) {
+        return this.#store.listQuarantined(agentId, documentId).map((r) => ({
+            rejectedEnvelopeHash: r.rejectedEnvelopeHash,
+            quarantined: r.payload,
+            reason: r.reason,
+            detail: r.detail,
+            rule: r.rule,
+            limitName: r.limitName,
+            limitValue: r.limitValue,
+            limitActual: r.limitActual,
+        }));
+    }
+    /** Clear one entry once its superseding update has been admitted (§3.2 step 4). */
+    clearQuarantine(agentId, documentId, rejectedEnvelopeHash) {
+        // Only announce an admission that actually happened — an event that fires on a no-op is a
+        // signal on the wrong case.
+        if (this.#store.releaseQuarantined(agentId, documentId, rejectedEnvelopeHash)) {
+            this.#logger.info("document.supersession.admitted", { documentId, rejectedEnvelopeHash });
+        }
+    }
+    /**
+     * Whether this document still accepts updates.
+     *
+     * A stalled document REFUSES, naming the reason it stalled — both operators need to see why,
+     * because a document that silently stops converging is the failure this exists to prevent.
+     */
+    acceptsUpdates(agentId, documentId) {
+        // Read the STORE, not memory. The status was persisted while the flag that gated this check
+        // was not, so after a restart the document row said `stalled` while the daemon happily
+        // accepted updates on it — the system reporting two contradictory states at once.
+        if (this.#isStalled(agentId, documentId)) {
+            const held = this.#store.listQuarantined(agentId, documentId);
+            const last = held[held.length - 1];
+            return {
+                ok: false,
+                reason: "document_stalled",
+                detail: `this document stopped accepting updates after ` +
+                    `${this.#round(agentId, documentId)} rejected rounds` +
+                    (last ? `; the most recent reason was ${last.reason}` : ""),
+            };
+        }
+        return { ok: true };
+    }
+    /**
+     * Start tracking local edits so a rejection can be rolled back.
+     *
+     * Yjs's own UndoManager, deliberately: rolling back by hand would mean computing inverses, and
+     * the inverse of a CRDT operation is not something to hand-roll — the whole reason supersession
+     * works is that Yjs's undo produces operations that compose correctly with everything stacked
+     * on top of them.
+     */
+    trackLocalEdits(doc) {
+        // The two roots this codebase's write path projects from, taken through their TYPED getters.
+        //
+        // Not the `doc.share` placeholders: `doc.get(name)` hands back the untyped AbstractType, and
+        // the typed getter later instantiates a DIFFERENT object — so the UndoManager would watch a
+        // root nobody edits and `undo()` would silently do nothing. Caught by the out-of-order guard
+        // below, which is the guard earning its keep on its first outing.
+        //
+        // Instantiating these two as Text and Map is not the guessed-type hazard GATE-1 measured:
+        // the write path DEFINES them as Text and Map. A document that puts content under any other
+        // root is not tracked here, and that is a real gap — recorded rather than papered over,
+        // because it belongs with whichever unit lets a document declare its own roots.
+        const undoManager = new Y.UndoManager([doc.getText("content"), doc.getMap("data")], {
+            captureTimeout: 0,
+        });
+        return {
+            doc,
+            undoManager,
+            depthAtTracking: undoManager.undoStack.length,
+            dispose: () => undoManager.destroy(),
+        };
+    }
+    /**
+     * Roll back the last tracked edit, as INVERSES.
+     *
+     * The sender's history grows rather than shrinking. That is not a limitation to work around: it
+     * is what leaves an auditable "wrote X, was rejected, undid X" trail, and what lets the
+     * superseding update carry the rejected operations plus their inverses so causality survives.
+     *
+     * **PRECONDITION: roll back before making further local edits.** Yjs's UndoManager undoes the
+     * most recent stack item, and it cannot undo one out of order — so a sender that keeps editing
+     * after a rejection arrives and then rolls back would undo the WRONG transaction. §3.2's
+     * ordering is steps 2 then 3 for exactly this reason: roll back, THEN do new work, THEN
+     * publish the supersession that carries all three. A caller that needs to interleave has a
+     * genuine design question, not a call-order detail, and it belongs in the unit that wires
+     * publish to the receive path.
+     */
+    rollback(tracked) {
+        // REFUSE rather than undo the wrong thing. Measured, the unguarded version had three failure
+        // modes that all reported success: nothing tracked (silent no-op), an untracked root (silent
+        // no-op), and — the damaging one — a sender that kept editing after the rejection arrived,
+        // where undo removed the agent's LEGITIMATE later work and KEPT the refused content. The
+        // supersession then re-ships the refused bytes, is rejected again, and the document stalls
+        // with a reason pointing at the peer while the operator's writing is gone.
+        const depth = tracked.undoManager.undoStack.length;
+        if (depth !== tracked.depthAtTracking + 1) {
+            throw new Error(`document_rollback_out_of_order: ${depth - tracked.depthAtTracking} local edit(s) are ` +
+                `stacked since tracking began, and Yjs can only undo the most recent — rolling back now ` +
+                `would discard the wrong work. Roll back before making further local edits (§3.2 step 2).`);
+        }
+        if (tracked.undoManager.undo() === null) {
+            throw new Error("document_rollback_nothing_tracked: no tracked edit to roll back — the rejected update " +
+                "was not produced through this tracker");
+        }
+    }
+    /** Derived from the log, not remembered — so it survives a restart. */
+    #round(agentId, documentId) {
+        // Scoped to the rejections THIS agent authored. A mutual exchange puts both directions' 0x05
+        // leaves in one document log, so an unscoped count conflated them and a document stalled at
+        // half the intended rounds the moment the peer also rejected something.
+        return this.#store.countRejections(agentId, documentId, agentId);
+    }
+    #isStalled(agentId, documentId) {
+        return this.#store.getDocument(agentId, documentId)?.status === "stalled";
+    }
+}
+//# sourceMappingURL=document-rejection.js.map

package/dist/document-rejection.js.map

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

package/dist/document-store.d.ts

@@ -40,14 +40,17 @@ export type DocumentStatus = "active" | "closed" | "killed" | "stalled";
  * to say "that one no longer counts" is to add a record saying so.
  */
 export type DocumentEnvelopeKind = "update" | "withdrawal" | "rejection";
-export interface DocumentProperties {
-    /** V1 accepts only `authenticated` — the Tier-2 seam (§16.1). */
-    assurance_tier?: string;
-    /** V1 accepts only `false` — the Tier-2 seam (§16.1). */
-    schema_enforcement?: boolean;
-    append_only?: boolean;
-    [key: string]: unknown;
-}
+/**
+ * RE-EXPORTED, not redefined.
+ *
+ * This was a second, structurally-similar interface declared here, and that is a drift risk with
+ * teeth: `properties` is inside the proposal's SIGNED preimage and `seamViolation` reads it, so two
+ * definitions of what a property is means two answers to what is admissible — one enforced at the
+ * signature and one at the store. They agreed by coincidence, and the first field added to one of
+ * them would have ended that quietly.
+ */
+export type { DocumentProperties } from "@cello-protocol/protocol-types";
+import type { DocumentProperties } from "@cello-protocol/protocol-types";
 export interface DocumentRow {
     documentId: string;
     ownerAgentId: string;
@@ -77,8 +80,33 @@ export interface DocumentEnvelopeRow {
     /** For a withdrawal or rejection: the envelope it concerns. */
     referencesEnvelopeHash?: string | null;
     createdAtMs: number;
+    /** The Yjs clientID this sender signed for — the gate's authorship binding. */
+    senderClientId?: number | null;
     /** Position in this document's log. Assigned on append; absent until then. */
     logIndex?: number;
+    /** DELIVERY bookkeeping, read back from the log. Absent on a row being appended. */
+    deliveredAtMs?: number | null;
+    ackedAtMs?: number | null;
+    attempts?: number;
+    nextAttemptAtMs?: number | null;
+}
+export interface QuarantineRow {
+    documentId: string;
+    /** The 0x05 leaf this row belongs to — the PK. One leaf, one row; see the table comment. */
+    rejectionEnvelopeHash: string;
+    rejectedEnvelopeHash: string;
+    /** The refused envelope's own author and chain link, so the chain verifier can bridge it. */
+    rejectedSenderAgentId: string;
+    rejectedDocPrevHash: string | null;
+    payload: Uint8Array;
+    reason: string;
+    detail?: string;
+    /** Which pluggable rule refused, when one did — the gate produces this and it must not be lost. */
+    rule?: string;
+    limitName?: string;
+    limitValue?: number;
+    limitActual?: number;
+    createdAtMs: number;
 }
 export interface DocumentSnapshot {
     binary: Uint8Array;
@@ -122,9 +150,24 @@ export type ReplayFn = (envelopes: DocumentEnvelopeRow[]) => {
 };
 export declare class DocumentStore {
     #private;
+    /**
+     * 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(): DaemonDatabase;
     constructor(db: DaemonDatabase, logger: Logger);
     createDocument(row: DocumentRow): void;
     getDocument(ownerAgentId: string, documentId: string): DocumentRow | null;
+    /**
+     * Does this daemon hold ANY document, under any owner?
+     *
+     * Deliberately unscoped, and that is the point: it is the only question that can tell a delivery
+     * sweep visiting zero agents apart from a daemon that simply has no documents. Without it the two
+     * look identical in the log, which is what let an owner-key mismatch hide.
+     */
+    anyDocumentExists(): boolean;
     listDocuments(ownerAgentId: string): DocumentRow[];
     setDocumentStatus(ownerAgentId: string, documentId: string, status: DocumentStatus): void;
     /**
@@ -165,6 +208,109 @@ export declare class DocumentStore {
      * caller must not read `ok: true` as authenticity — that belongs to the engine.
      */
     verifyChainLinkage(ownerAgentId: string, documentId: string): ChainVerdict;
+    /**
+     * 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: string, row: QuarantineRow): boolean;
+    listQuarantined(ownerAgentId: string, documentId: string): QuarantineRow[];
+    /**
+     * 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: string, documentId: string, rejectedEnvelopeHash: string): boolean;
+    /**
+     * Every envelope hash we hold from one sender. Hash-only on purpose: the caller needs a set for a
+     * membership test, and `getEnvelopeLog` selects `*` — including every payload BLOB — so building
+     * that set from it materialized the whole document's content on every inbound update.
+     */
+    knownEnvelopeHashesBySender(ownerAgentId: string, documentId: string, senderAgentId: string): Set<string>;
+    /** The clientIDs one sender has signed for on this document. Also hash-free — see above. */
+    senderClientIdsFor(ownerAgentId: string, documentId: string, senderAgentId: string): number[];
+    /**
+     * The state vector the PEER last told us they had — from their most recent envelope.
+     *
+     * This is what a publish diffs against (§3.2 step 3, §7): an update computed against what they
+     * have already seen carries exactly the operations they lack. Diffing against OUR OWN snapshot
+     * instead publishes what we have not yet snapshotted, which is a different question with an
+     * answer that happens to look plausible.
+     */
+    peerStateVector(ownerAgentId: string, documentId: string, peerAgentId: string): Uint8Array | null;
+    /**
+     * The state vector OUR last published envelope carried — what we had when we last spoke.
+     *
+     * Distinct from `peerStateVector`, and the distinction is the point: that one answers "what does
+     * the peer lack" (what to send), this one answers "has anything changed since I last published"
+     * (whether to send at all). Conflating them meant a republish with no edits still produced a
+     * non-empty update, because before the peer has ever published the diff is the whole document.
+     */
+    lastPublishedStateVector(ownerAgentId: string, documentId: string, senderAgentId: string): Uint8Array | null;
+    /** The rejecting agent's most recent envelope for this document, for chain linkage. */
+    lastEnvelopeHashBySender(ownerAgentId: string, documentId: string, senderAgentId: string): string | null;
+    /**
+     * 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: string, nowMs: number, 
+    /**
+     * OUR OWN sender id on the wire — the author's pubkey hex (M14-D5).
+     *
+     * Kept as a separate parameter, and separately named, even though the daemon now scopes the
+     * store by that same pubkey hex so the two coincide. They are different FACTS: the owner key
+     * says whose local store this row is in, the sender id says who signed the envelope. An
+     * earlier version of the daemon scoped by agent name, and the mismatch returned nothing
+     * pending — every published update sitting in the log undelivered, with no error anywhere.
+     * Collapsing them into one argument makes that class of bug unrepresentable in the call and
+     * invisible in the query.
+     */
+    senderAgentId?: string, limit?: number): DocumentEnvelopeRow[];
+    /** Mark an attempt: bumps the counter and schedules the next one. Returns the new count. */
+    recordDeliveryAttempt(ownerAgentId: string, documentId: string, envelopeHash: string, nextAttemptAtMs: number): number;
+    /** Record that the envelope left. Not an ack — the peer has not answered yet. */
+    markDelivered(ownerAgentId: string, documentId: string, envelopeHash: string, nowMs: number): boolean;
+    /** Record that the peer acknowledged. Idempotent — a redelivered ack must not move the clock. */
+    markAcked(ownerAgentId: string, documentId: string, envelopeHash: string, nowMs: number): boolean;
+    /** Record a rejection the PEER sent us. Returns whether a row was written (idempotent by leaf). */
+    recordRejectionReceived(ownerAgentId: string, row: {
+        documentId: string;
+        rejectionEnvelopeHash: string;
+        rejectedEnvelopeHash: string;
+        fromAgentId: string;
+        reason: string;
+        detail?: string;
+        createdAtMs: number;
+    }): boolean;
+    /** How many rejections this document has RECEIVED — the publishing side's retry round. */
+    countRejectionsReceived(ownerAgentId: string, documentId: string): number;
+    /**
+     * Was a rejection received for THIS envelope? Envelope-scoped on purpose: the document-scoped
+     * reader below answers a different question, and using it to decide whether one envelope was
+     * refused makes a rejection of any OTHER envelope in the document look like a rejection of this
+     * one.
+     */
+    rejectionReceivedFor(ownerAgentId: string, documentId: string, envelopeHash: string): boolean;
+    /** The most recently received rejection, for the reason an operator is shown on a stall. */
+    latestRejectionReceived(ownerAgentId: string, documentId: string): {
+        reason: string;
+        detail?: string;
+        fromAgentId: string;
+    } | null;
+    /**
+     * 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: string, documentId: string, rejectingAgentId: string): number;
     getSnapshot(ownerAgentId: string, documentId: string): DocumentSnapshot | null;
     /** REPLACES — a snapshot is a cache of the log, not a second log. */
     putSnapshot(ownerAgentId: string, documentId: string, snapshot: DocumentSnapshot): void;

package/dist/document-store.d.ts.map

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