@cello-protocol/daemon 0.0.120 → 0.0.122

package/dist/document-delivery-transport.js

@@ -0,0 +1,109 @@
+/**
+ * DOD-DOC-DELIVERY-2 — the transport behind `DocumentDeliveryTransport` (§16.4).
+ *
+ * DELIVERY-1 built the scheduler and the bookkeeping against an injected seam. This is the seam's
+ * implementation: the first NON-HANDLER consumer of the session machinery, which is what makes it
+ * interesting — every other caller of `SessionNegotiator` runs because an agent asked for
+ * something, and this one runs because a document has a pending envelope and nobody is watching.
+ *
+ * ── REUSE BEFORE OPEN, AND WHY THAT ORDER ─────────────────────────────────────────────────────
+ *
+ * §16.4: "the daemon uses the most recent active session with that peer or opens one". Reuse first,
+ * because opening is the expensive half — a directory negotiation, a dial, and a seal — and a
+ * backlog of pending envelopes for one peer would otherwise pay it per envelope. It is also the
+ * behaviour an operator expects when they are mid-conversation about the document: the change lands
+ * in the same sealed record as the discussion, without anyone passing a session hint.
+ *
+ * An explicit `sessionHint` overrides the choice but NOT the validation — a hint naming a session
+ * that is not active with this peer is refused rather than silently replaced by the daemon's own
+ * pick, because the one reason to pass a hint is to control which sealed record the change lands
+ * in, and quietly choosing a different one defeats exactly that.
+ *
+ * ── WHAT AN ACK IS HERE, AND WHAT IT IS NOT ───────────────────────────────────────────────────
+ *
+ * `sendContent` reports that the content left, or was PARKED at the relay for an offline peer. That
+ * is a transport fact. The DoD's ack is a different one — "the peer's daemon confirms admission (or
+ * rejection)" — and it can only come from the peer's inbound document handler, which is its own
+ * line. So this adapter returns `admitted: null`: SENT, not acked.
+ *
+ * That third state is not hedging; both two-valued answers are dishonest here. `true` would mark
+ * the envelope acknowledged in the log while the peer may never have applied it, and the log being
+ * right about what the peer holds is the entire reason pending is derived from it. `false` would
+ * count a send that WORKED as a failure and re-send content already in flight — the
+ * permanent-redelivery shape this milestone has already fixed once. The worker records the envelope
+ * as delivered, leaves it unacked, and asks again on the capped backoff.
+ */
+import { reachabilityFromDiscovery, DiscoveryUnavailableError } from "./document-reachability.js";
+export function createDocumentDeliveryTransport(deps) {
+    return {
+        async isPeerReachable(peerAgentId) {
+            const outcome = await deps.lookupPeer(peerAgentId, `reach-${peerAgentId.slice(0, 8)}`);
+            // Throws on everything that is not an answer about the peer — see document-reachability.ts.
+            // The worker treats the throw as `lookup_failed` and keeps it out of the offline-peer count.
+            const { reachable, unknownAgent } = reachabilityFromDiscovery(outcome);
+            if (unknownAgent) {
+                // Distinct from "offline": the address does not resolve at all. Same consequence (do not
+                // dial), different thing to tell an operator, so it is said rather than folded in.
+                deps.logger.warn("document.delivery.peer_unknown", { peerAgentId });
+            }
+            return reachable;
+        },
+        async deliver(input) {
+            const { peerAgentId, documentId, envelope, sessionHint, correlationId } = input;
+            let sessionId;
+            let sessionOpened = false;
+            const active = deps.activeSessionsWith(deps.agentName, peerAgentId);
+            if (sessionHint !== undefined) {
+                if (!active.includes(sessionHint)) {
+                    // Refused, not replaced. The only reason to pass a hint is to control which sealed
+                    // record the change lands in; quietly substituting the daemon's own pick would defeat
+                    // exactly that, and it would do so silently.
+                    return {
+                        ok: false,
+                        reason: "document_session_hint_invalid",
+                        detail: `session ${sessionHint.slice(0, 16)}… is not an active session with ${peerAgentId}, ` +
+                            `so the change cannot be placed in that record`,
+                    };
+                }
+                sessionId = sessionHint;
+            }
+            else if (active.length > 0) {
+                sessionId = active[active.length - 1];
+            }
+            else {
+                const opened = await deps.openSession(deps.agentName, peerAgentId, correlationId);
+                if (!opened.ok) {
+                    // The upstream reason verbatim. `document_delivery_threw` is reserved for a genuine
+                    // programming fault; a dial that was refused should say it was refused.
+                    return { ok: false, reason: opened.reason, detail: opened.guidance };
+                }
+                sessionId = opened.sessionId;
+                sessionOpened = true;
+            }
+            const { bytes, hash } = deps.encodeEnvelope(envelope);
+            const sent = await deps.sendContent(deps.agentName, sessionId, bytes, hash, correlationId);
+            if (!sent.ok) {
+                return { ok: false, reason: sent.reason, detail: sent.error };
+            }
+            deps.logger.info("document.delivery.sent", {
+                documentId,
+                sessionId,
+                sessionOpened,
+                parked: sent.delivered === false,
+                correlationId,
+            });
+            // SENT, NOT ACKED — `admitted: null`. The content left (or was parked for an offline peer),
+            // which is a transport fact; the DoD's ack is the peer's daemon confirming admission, and
+            // that answer comes from the inbound document handler, which is its own line.
+            //
+            // Neither of the two-valued answers is available honestly. `true` would mark the envelope
+            // acknowledged in the log while the peer may never have applied it — and the log being right
+            // about what the peer holds is the entire reason pending is derived from it. `false` would
+            // count a send that WORKED as a failure and re-send content already in flight, which is the
+            // permanent-redelivery shape this milestone already fixed once.
+            return { ok: true, sessionId, sessionOpened, admitted: null };
+        },
+    };
+}
+export { DiscoveryUnavailableError };
+//# sourceMappingURL=document-delivery-transport.js.map

package/dist/document-delivery-transport.js.map

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

package/dist/document-delivery.d.ts

@@ -0,0 +1,130 @@
+/**
+ * DOD-DOC-DELIVERY-1 — daemon-autonomous delivery (§16.4).
+ *
+ * Publish writes the envelope to the log and returns. Delivery is somebody else's job, and that
+ * somebody is this worker: it derives what is pending FROM THE LOG, checks the peer is reachable
+ * before dialing, opens or reuses a session itself, delivers, and records the ack — with zero agent
+ * attention on either end. Two agents in opposite time zones sync overnight without either agent
+ * doing anything.
+ *
+ * ── PENDING IS DERIVED, NEVER HELD ────────────────────────────────────────────────────────────
+ *
+ * "Unacknowledged envelopes I authored" is a WHERE clause over the log, and that is the whole
+ * definition. A queue in memory does not survive a restart — the daemon is a long-running local
+ * process that gets restarted routinely — and a queue in its own table is a second source of truth
+ * that can disagree with the log about what was sent. The attempt counter and the next-attempt
+ * time live on the envelope row for the same reason: a backoff that resets on restart is not a
+ * backoff, and a daemon restarting in a reconnect loop would hammer an unreachable peer at full
+ * rate forever.
+ *
+ * ── WHY LOOKUP BEFORE DIAL ────────────────────────────────────────────────────────────────────
+ *
+ * §16.4's design is presence-driven push, but there is no presence subscription today (parked,
+ * M14-P4). Without one, the honest substitute is: ask the directory whether the peer is reachable,
+ * and if it is not, do not burn a dial — schedule a retry on a capped backoff. Dialing an offline
+ * peer to find out it is offline is the same information at much higher cost, and it is the cost
+ * that would be paid on every pending envelope, on every tick, for as long as the peer is away.
+ */
+import type { DocumentStore, DocumentEnvelopeRow } from "./document-store.js";
+import type { Logger } from "./types.js";
+/**
+ * The transport seam. Narrow on purpose (M4 rule: add to an interface only when a failing test or
+ * a production behaviour requires it) — the worker's job is scheduling and bookkeeping, and every
+ * dial-level concern belongs to the adapter behind this.
+ */
+export interface DocumentDeliveryTransport {
+    /**
+     * Is the peer reachable right now? `discovery_lookup` today. Returns false rather than throwing
+     * for an ordinary "not online"; a throw means the LOOKUP failed, which is a different fact and
+     * must not be recorded as the peer being away.
+     */
+    isPeerReachable(peerAgentId: string): Promise<boolean>;
+    /**
+     * Deliver one envelope over a session the transport opens or reuses (§16.4: daemon-chooses by
+     * default; `sessionHint` is the one case with audit value — the agent is mid-conversation about
+     * the document and wants the discussion and the change in one sealed record).
+     */
+    /**
+     * `ok` means the peer's daemon ANSWERED about this envelope — it is not "the peer liked it".
+     * `admitted: false` is a rejection (§3.2's `0x05`), and a rejection IS an ack for delivery
+     * purposes: the peer has decided, so there is nothing left to retry. Without the distinction the
+     * adapter has to map a rejection onto one of two lies — `ok: true` makes the delivery record say
+     * the peer admitted content it refused, and `ok: false` redelivers an envelope the peer has
+     * already ruled on, forever, re-triggering their gate and their retry counter until the document
+     * stalls for reasons the operator cannot see.
+     *
+     * `sessionOpened` distinguishes a session this delivery opened from one it reused — the audit
+     * distinction §16.4 cares about, and unrecoverable after the fact.
+     */
+    deliver(input: {
+        peerAgentId: string;
+        documentId: string;
+        envelope: DocumentEnvelopeRow;
+        sessionHint?: string;
+        correlationId: string;
+    }): Promise<{
+        ok: true;
+        sessionId: string;
+        sessionOpened: boolean;
+        /**
+         * `true` admitted, `false` rejected — both are ACKS, the peer has decided. `null` means the
+         * envelope LEFT (or was parked for an offline peer) and no answer has come back yet.
+         *
+         * The third state is not hedging; both two-valued answers are dishonest for a send whose
+         * outcome is unknown. `true` marks the envelope acknowledged in the log while the peer may
+         * never have applied it — and the log being right about what the peer holds is the entire
+         * reason pending is derived from it. `false` counts a send that WORKED as a failure and
+         * re-sends content already in flight.
+         */
+        admitted: boolean | null;
+        rejectionReason?: string;
+    } | {
+        ok: false;
+        reason: string;
+        detail?: string;
+    }>;
+}
+/**
+ * Backoff schedule in ms: ~1s, 5s, 30s, 2m, 10m, then the last entry repeats.
+ *
+ * The final entry IS the cap — there is no separate ceiling constant. There was one, set to 900s,
+ * and it was unreachable: the index clamp meant the schedule never produced a value above 600s, so
+ * the exported "cap" was a number the code could not emit and the tests were using it as a synonym
+ * for "much later". A documented limit the implementation cannot reach is worse than none.
+ *
+ * Capped at all because the peer coming back online is the event we are waiting for and it can
+ * happen at any moment — an uncapped curve leaves a peer that returned after a long absence waiting
+ * hours for a delivery that has been ready the whole time.
+ */
+export declare const DELIVERY_BACKOFF_MS: readonly [1000, 5000, 30000, 120000, 600000];
+export declare const DELIVERY_BACKOFF_CAP_MS: 5000 | 1000 | 30000 | 120000 | 600000;
+/**
+ * A document whose peer cannot be resolved is not transient, so it gets the cap immediately rather
+ * than climbing to it — but it DOES get scheduled. See the `no_peer` branch.
+ */
+export declare const DELIVERY_UNRESOLVABLE_RETRY_MS: 5000 | 1000 | 30000 | 120000 | 600000;
+export declare function backoffFor(attempts: number): number;
+export interface DeliveryTickResult {
+    attempted: number;
+    delivered: number;
+    /** Sent (or parked) with no answer yet — in flight, neither done nor failed. */
+    sent: number;
+    /** Answered but refused. Acked all the same — the peer has decided. */
+    rejected: number;
+    deferred: number;
+    failed: number;
+}
+export declare class DocumentDelivery {
+    #private;
+    constructor(store: DocumentStore, transport: DocumentDeliveryTransport, logger: Logger);
+    /**
+     * One pass over what is due. Returns counts rather than throwing on a per-envelope failure: one
+     * unreachable peer must not stop delivery to every other peer, which is precisely the "works
+     * only when all nodes are healthy" shape the project forbids.
+     */
+    tick(ownerAgentId: string, peerFor: (documentId: string) => string | null, nowMs: number, opts?: {
+        sessionHint?: string;
+        correlationId?: string;
+    }): Promise<DeliveryTickResult>;
+}
+//# sourceMappingURL=document-delivery.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"document-delivery.d.ts","sourceRoot":"","sources":["../src/document-delivery.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,mBAAmB,EAAE,MAAM,qBAAqB,CAAC;AAC9E,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,YAAY,CAAC;AAEzC;;;;GAIG;AACH,MAAM,WAAW,yBAAyB;IACxC;;;;OAIG;IACH,eAAe,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IACvD;;;;OAIG;IACH;;;;;;;;;;;OAWG;IACH,OAAO,CAAC,KAAK,EAAE;QACb,WAAW,EAAE,MAAM,CAAC;QACpB,UAAU,EAAE,MAAM,CAAC;QACnB,QAAQ,EAAE,mBAAmB,CAAC;QAC9B,WAAW,CAAC,EAAE,MAAM,CAAC;QACrB,aAAa,EAAE,MAAM,CAAC;KACvB,GAAG,OAAO,CACP;QACE,EAAE,EAAE,IAAI,CAAC;QACT,SAAS,EAAE,MAAM,CAAC;QAClB,aAAa,EAAE,OAAO,CAAC;QACvB;;;;;;;;;WASG;QACH,QAAQ,EAAE,OAAO,GAAG,IAAI,CAAC;QACzB,eAAe,CAAC,EAAE,MAAM,CAAC;KAC1B,GACD;QAAE,EAAE,EAAE,KAAK,CAAC;QAAC,MAAM,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAA;KAAE,CACjD,CAAC;CACH;AAED;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,mBAAmB,8CAAoD,CAAC;AACrF,eAAO,MAAM,uBAAuB,uCAAsD,CAAC;AAE3F;;;GAGG;AACH,eAAO,MAAM,8BAA8B,uCAA0B,CAAC;AAEtE,wBAAgB,UAAU,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAGnD;AAED,MAAM,WAAW,kBAAkB;IACjC,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,gFAAgF;IAChF,IAAI,EAAE,MAAM,CAAC;IACb,uEAAuE;IACvE,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,qBAAa,gBAAgB;;gBAMf,KAAK,EAAE,aAAa,EAAE,SAAS,EAAE,yBAAyB,EAAE,MAAM,EAAE,MAAM;IAMtF;;;;OAIG;IACG,IAAI,CACR,YAAY,EAAE,MAAM,EACpB,OAAO,EAAE,CAAC,UAAU,EAAE,MAAM,KAAK,MAAM,GAAG,IAAI,EAC9C,KAAK,EAAE,MAAM,EACb,IAAI,GAAE;QAAE,WAAW,CAAC,EAAE,MAAM,CAAC;QAAC,aAAa,CAAC,EAAE,MAAM,CAAA;KAAO,GAC1D,OAAO,CAAC,kBAAkB,CAAC;CA4M/B"}

package/dist/document-delivery.js

@@ -0,0 +1,246 @@
+/**
+ * DOD-DOC-DELIVERY-1 — daemon-autonomous delivery (§16.4).
+ *
+ * Publish writes the envelope to the log and returns. Delivery is somebody else's job, and that
+ * somebody is this worker: it derives what is pending FROM THE LOG, checks the peer is reachable
+ * before dialing, opens or reuses a session itself, delivers, and records the ack — with zero agent
+ * attention on either end. Two agents in opposite time zones sync overnight without either agent
+ * doing anything.
+ *
+ * ── PENDING IS DERIVED, NEVER HELD ────────────────────────────────────────────────────────────
+ *
+ * "Unacknowledged envelopes I authored" is a WHERE clause over the log, and that is the whole
+ * definition. A queue in memory does not survive a restart — the daemon is a long-running local
+ * process that gets restarted routinely — and a queue in its own table is a second source of truth
+ * that can disagree with the log about what was sent. The attempt counter and the next-attempt
+ * time live on the envelope row for the same reason: a backoff that resets on restart is not a
+ * backoff, and a daemon restarting in a reconnect loop would hammer an unreachable peer at full
+ * rate forever.
+ *
+ * ── WHY LOOKUP BEFORE DIAL ────────────────────────────────────────────────────────────────────
+ *
+ * §16.4's design is presence-driven push, but there is no presence subscription today (parked,
+ * M14-P4). Without one, the honest substitute is: ask the directory whether the peer is reachable,
+ * and if it is not, do not burn a dial — schedule a retry on a capped backoff. Dialing an offline
+ * peer to find out it is offline is the same information at much higher cost, and it is the cost
+ * that would be paid on every pending envelope, on every tick, for as long as the peer is away.
+ */
+/**
+ * Backoff schedule in ms: ~1s, 5s, 30s, 2m, 10m, then the last entry repeats.
+ *
+ * The final entry IS the cap — there is no separate ceiling constant. There was one, set to 900s,
+ * and it was unreachable: the index clamp meant the schedule never produced a value above 600s, so
+ * the exported "cap" was a number the code could not emit and the tests were using it as a synonym
+ * for "much later". A documented limit the implementation cannot reach is worse than none.
+ *
+ * Capped at all because the peer coming back online is the event we are waiting for and it can
+ * happen at any moment — an uncapped curve leaves a peer that returned after a long absence waiting
+ * hours for a delivery that has been ready the whole time.
+ */
+export const DELIVERY_BACKOFF_MS = [1_000, 5_000, 30_000, 120_000, 600_000];
+export const DELIVERY_BACKOFF_CAP_MS = DELIVERY_BACKOFF_MS[DELIVERY_BACKOFF_MS.length - 1];
+/**
+ * A document whose peer cannot be resolved is not transient, so it gets the cap immediately rather
+ * than climbing to it — but it DOES get scheduled. See the `no_peer` branch.
+ */
+export const DELIVERY_UNRESOLVABLE_RETRY_MS = DELIVERY_BACKOFF_CAP_MS;
+export function backoffFor(attempts) {
+    const idx = Math.min(Math.max(attempts, 0), DELIVERY_BACKOFF_MS.length - 1);
+    return DELIVERY_BACKOFF_MS[idx];
+}
+export class DocumentDelivery {
+    #store;
+    #transport;
+    #logger;
+    #inFlight = null;
+    constructor(store, transport, logger) {
+        this.#store = store;
+        this.#transport = transport;
+        this.#logger = logger;
+    }
+    /**
+     * One pass over what is due. Returns counts rather than throwing on a per-envelope failure: one
+     * unreachable peer must not stop delivery to every other peer, which is precisely the "works
+     * only when all nodes are healthy" shape the project forbids.
+     */
+    async tick(ownerAgentId, peerFor, nowMs, opts = {}) {
+        // NO RE-ENTRY. Nothing marks a row in-flight until its outcome lands, so a `deliver` slower
+        // than the tick interval — a dial to a distant peer is exactly that — would have the next tick
+        // return the same rows and dial again: two autonomous sessions and two seals for one envelope,
+        // and the loser's markAcked returning false, which logs as if the PEER had redelivered an ack.
+        if (this.#inFlight)
+            return this.#inFlight;
+        const run = this.#run(ownerAgentId, peerFor, nowMs, opts);
+        this.#inFlight = run;
+        try {
+            return await run;
+        }
+        finally {
+            this.#inFlight = null;
+        }
+    }
+    async #run(ownerAgentId, peerFor, nowMs, opts) {
+        // Minted once per pass and threaded through every event, so an operator can tie a failure back
+        // to the lookup that preceded it and the session that carried it. Delivery is precisely the
+        // async multi-step flow the convention exists for: lookup, dial, deliver, ack — across ticks
+        // and across restarts.
+        const correlationId = opts.correlationId ?? `dlv-${ownerAgentId.slice(0, 8)}-${nowMs}`;
+        const pending = this.#store.pendingDeliveries(ownerAgentId, nowMs);
+        const result = {
+            attempted: 0, delivered: 0, sent: 0, rejected: 0, deferred: 0, failed: 0,
+        };
+        // Group by document so one reachability lookup serves every pending envelope for that peer.
+        // Per-envelope lookups would multiply directory traffic by the size of the backlog, which is
+        // largest exactly when the peer has been away longest.
+        const byDocument = new Map();
+        for (const e of pending) {
+            const list = byDocument.get(e.documentId);
+            if (list)
+                list.push(e);
+            else
+                byDocument.set(e.documentId, [e]);
+        }
+        for (const [documentId, envelopes] of byDocument) {
+            const peerAgentId = peerFor(documentId);
+            if (peerAgentId === null) {
+                // No peer means the document row is gone or malformed, which is NOT transient — so it goes
+                // straight to the cap rather than climbing to it, and crucially it is SCHEDULED. Skipping
+                // the schedule made this the one exit that never self-corrects: the rows stayed due on
+                // every tick forever, emitting an error line each time, and — because the pending window
+                // is ordered and bounded — they filled it and starved every other document. The operator's
+                // work on an unrelated document would silently never leave the machine, with the only
+                // signal being an error naming a different one.
+                this.#logger.error("document.delivery.no_peer", {
+                    documentId,
+                    pending: envelopes.length,
+                    correlationId,
+                });
+                for (const e of envelopes) {
+                    this.#store.recordDeliveryAttempt(ownerAgentId, documentId, e.envelopeHash, nowMs + DELIVERY_UNRESOLVABLE_RETRY_MS);
+                }
+                result.failed += envelopes.length;
+                continue;
+            }
+            let reachable;
+            try {
+                reachable = await this.#transport.isPeerReachable(peerAgentId);
+            }
+            catch (err) {
+                // A FAILED LOOKUP IS NOT AN OFFLINE PEER. Recording it as "away" would report a directory
+                // outage to the operator as their collaborator being absent — an error substituted for a
+                // different error, and one that sends them to ask the wrong person.
+                this.#logger.warn("document.delivery.lookup_failed", {
+                    documentId,
+                    peerAgentId,
+                    correlationId,
+                    reason: err instanceof Error ? err.message : String(err),
+                });
+                this.#defer(ownerAgentId, documentId, envelopes, nowMs);
+                result.deferred += envelopes.length;
+                continue;
+            }
+            if (!reachable) {
+                this.#logger.info("document.delivery.peer_unreachable", {
+                    documentId,
+                    peerAgentId,
+                    pending: envelopes.length,
+                    correlationId,
+                });
+                this.#defer(ownerAgentId, documentId, envelopes, nowMs);
+                result.deferred += envelopes.length;
+                continue;
+            }
+            for (const envelope of envelopes) {
+                result.attempted += 1;
+                // CLAIM THE ROW BEFORE DIALING. Scheduling only on the outcome leaves the row due for the
+                // whole duration of the dial, and leaves it due FOREVER if the daemon dies mid-dial. The
+                // claim is corrected below when the outcome lands.
+                const attempts = this.#store.recordDeliveryAttempt(ownerAgentId, documentId, envelope.envelopeHash, nowMs + backoffFor(envelope.attempts ?? 0));
+                let outcome;
+                try {
+                    outcome = await this.#transport.deliver({
+                        peerAgentId,
+                        documentId,
+                        envelope,
+                        sessionHint: opts.sessionHint,
+                        correlationId,
+                    });
+                }
+                catch (err) {
+                    // A THROW IS A FAILURE, never a success. Wrapped here rather than left to propagate so
+                    // one envelope's transport fault does not abandon the rest of the backlog mid-pass.
+                    outcome = {
+                        ok: false,
+                        reason: "document_delivery_threw",
+                        detail: err instanceof Error ? err.message : String(err),
+                    };
+                }
+                if (outcome.ok && outcome.admitted === null) {
+                    // IN FLIGHT. The content left, and the peer has not answered. Recorded as DELIVERED so
+                    // the operator can see it went, and left unacked so the worker keeps asking — on the
+                    // capped backoff the claim above already scheduled, not at full rate.
+                    this.#store.markDelivered(ownerAgentId, documentId, envelope.envelopeHash, nowMs);
+                    this.#logger.info("document.delivery.sent", {
+                        documentId,
+                        envelopeHash: envelope.envelopeHash,
+                        sessionId: outcome.sessionId,
+                        sessionOpened: outcome.sessionOpened,
+                        correlationId,
+                    });
+                    result.sent += 1;
+                }
+                else if (outcome.ok) {
+                    // ACK = the peer's daemon ANSWERED, admitted or not. A rejection is an ack for delivery
+                    // purposes (§3.2's 0x05): the peer has decided, so there is nothing left to retry, and
+                    // retrying would re-trigger their gate and their retry counter until the document stalls
+                    // for reasons the operator cannot see. Supersession is REJECT-1's job, not the worker's.
+                    const first = this.#store.markAcked(ownerAgentId, documentId, envelope.envelopeHash, nowMs);
+                    this.#logger.info("document.delivery.session", {
+                        documentId,
+                        sessionId: outcome.sessionId,
+                        opened: outcome.sessionOpened,
+                        correlationId,
+                    });
+                    if (outcome.admitted) {
+                        this.#logger.info("document.delivery.acked", {
+                            documentId,
+                            envelopeHash: envelope.envelopeHash,
+                            sessionId: outcome.sessionId,
+                            firstAck: first,
+                            correlationId,
+                        });
+                        result.delivered += 1;
+                    }
+                    else {
+                        this.#logger.warn("document.delivery.rejected", {
+                            documentId,
+                            envelopeHash: envelope.envelopeHash,
+                            sessionId: outcome.sessionId,
+                            reason: outcome.rejectionReason,
+                            correlationId,
+                        });
+                        result.rejected += 1;
+                    }
+                }
+                else {
+                    this.#logger.warn("document.delivery.failed", {
+                        documentId,
+                        envelopeHash: envelope.envelopeHash,
+                        reason: outcome.reason,
+                        detail: outcome.detail,
+                        attempts,
+                        correlationId,
+                    });
+                    result.failed += 1;
+                }
+            }
+        }
+        return result;
+    }
+    #defer(ownerAgentId, documentId, envelopes, nowMs) {
+        for (const e of envelopes) {
+            this.#store.recordDeliveryAttempt(ownerAgentId, documentId, e.envelopeHash, nowMs + backoffFor(e.attempts ?? 0));
+        }
+    }
+}
+//# sourceMappingURL=document-delivery.js.map

package/dist/document-delivery.js.map

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

package/dist/document-engine.d.ts

@@ -0,0 +1,134 @@
+/**
+ * DOD-DOC-ENGINE-1 — the daemon's Y.Doc lifecycle.
+ *
+ * The engine owns HOW to apply; the store (DOD-DOC-STORE-1) owns what to replay and in what
+ * order. `replay` takes whole envelope rows rather than payload bytes so it can tell a
+ * payload-free AUDIT record (a withdrawal or rejection, which is expected and skipped) from a
+ * payload-free PURGED update (an operation whose bytes are gone, which must refuse). That is the
+ * only thing `kind` is read for — `referencesEnvelopeHash` is pure audit at replay time, never
+ * read, because a withdrawal excludes nothing (§16.4; see `replay`).
+ *
+ * EVERY GUARD BELOW IS A RESPONSE TO A MEASUREMENT, not to a guess. DOD-DOC-FUZZ-1 fuzzed
+ * `Y.applyUpdate` and found:
+ *
+ *   - Malformed input THROWS — so a wrapped apply genuinely contains it, and V1 needs no sandbox.
+ *   - But the dangerous class is what Yjs ACCEPTS. An update whose dependencies the receiver
+ *     lacks returns success, contributes nothing, and is RETAINED forever in
+ *     `doc.store.pendingStructs` — a peer streams those until the daemon dies, and a try/catch
+ *     sees only success. Hence the pending-set check after every apply.
+ *   - An empty or one-byte update throws a lib0 DECODER error ("Unexpected end of array"), which
+ *     names Yjs internals rather than a protocol fault. Hence a floor as well as a cap.
+ *   - Yjs does not bound nesting depth at all, and the size cap bounds it poorly (~16 bytes per
+ *     level, so roughly 65,000 levels fit in 1 MiB). Structural limits are DOD-DOC-GATE-1's job;
+ *     the engine's contract is only that a bad update is a typed error, never a crash.
+ *
+ * ONE TYPED REASON PER FAILURE CLASS. A lib0 string like "Integer out of Range" describes where
+ * the decoder gave up, not what the peer did wrong, so it travels as `detail` and never as the
+ * reason an operator or a policy log sees.
+ */
+import * as Y from "yjs";
+import type { DocumentEnvelopeRow } from "./document-store.js";
+import type { Logger } from "./types.js";
+export type DocumentUpdateFailure = "document_update_too_large" | "document_update_too_small" | "document_update_malformed" | "document_update_unresolved_dependencies" | "document_snapshot_malformed" | "document_snapshot_incomplete" | "document_envelope_purged";
+export type DocumentUpdateResult = {
+    ok: true;
+}
+/** `detail` is the underlying cause — never the reason itself. */
+ | {
+    ok: false;
+    reason: DocumentUpdateFailure;
+    detail?: string;
+};
+/** Thrown by the *OrThrow variants and by `replay`, where returning a verdict would let a caller
+ *  persist a state that was never fully applied. */
+export declare class DocumentUpdateError extends Error {
+    readonly reason: DocumentUpdateFailure;
+    readonly detail?: string;
+    constructor(reason: DocumentUpdateFailure, detail?: string);
+}
+export declare class DocumentEngine {
+    #private;
+    constructor(logger: Logger);
+    /** The pre-parse cap, exposed so callers and tests agree on one number. */
+    get maxUpdateBytes(): number;
+    /**
+     * A fresh live document.
+     *
+     * Yjs mints its own random clientID and NOTHING here touches it (§14). Deriving it from agent
+     * identity, or persisting and restoring one, means two live docs can share it — and
+     * DOD-DOC-FUZZ-1 measured that outcome: the colliding writer silently wins, the honest client's
+     * update is accepted-and-dropped, and the document becomes a splice of two authors with an
+     * empty pending set and no error on any path.
+     */
+    createDocument(startingContent?: string): Y.Doc;
+    /**
+     * Read the single text root a text-typed document uses.
+     *
+     * Named for the root it reads, not for "the document's content". `DocumentRow.documentType`
+     * admits markdown, json and xml; on the latter two the data does not live in this root, and an
+     * unnamed `readText` would return "" — indistinguishable from an empty document. Structured
+     * types get their own accessors when a unit needs them.
+     */
+    readTextRoot(doc: Y.Doc): string;
+    insertIntoTextRoot(doc: Y.Doc, index: number, text: string): void;
+    /** The full state, or just what a peer holding `sinceStateVector` is missing (§7). */
+    encodeState(doc: Y.Doc, sinceStateVector?: Uint8Array): Uint8Array;
+    encodeStateVector(doc: Y.Doc): Uint8Array;
+    snapshot(doc: Y.Doc): {
+        binary: Uint8Array;
+        stateVector: Uint8Array;
+    };
+    /**
+     * Materialize a document from a snapshot binary.
+     *
+     * The restored document mints a FRESH clientID — the binary carries the operations, never an
+     * identity to resume under. See `createDocument` for what sharing one costs.
+     */
+    restore(binary: Uint8Array): Y.Doc;
+    /**
+     * Apply one update, with every guard the fuzz pass motivated.
+     *
+     * Never throws and never leaves the document half-integrated: an update that cannot be fully
+     * resolved is applied to a THROWAWAY doc first, so the caller's document is untouched when the
+     * answer is no.
+     */
+    /**
+     * Apply one update to a caller's live document, leaving it untouched if the answer is no.
+     *
+     * The trial runs on a FRESH scratch document every time. Reusing one across calls is unsound:
+     * `Y.applyUpdate` MERGES, it does not reset, so a scratch doc seeded from an empty document
+     * still holds the previous trial's operations — and with that residue present, an update whose
+     * dependencies the target lacks reports an EMPTY pending set. The one guard that catches the
+     * accept class would go green on exactly the input it exists to refuse. (Measured, not
+     * reasoned: a shadow holding "AAA" re-seeded from an empty doc still reads "AAA".)
+     */
+    applyUpdate(doc: Y.Doc, update: Uint8Array): DocumentUpdateResult;
+    /** `applyUpdate` for callers that want the failure to be unmissable. */
+    applyUpdateOrThrow(doc: Y.Doc, update: Uint8Array): void;
+    /**
+     * Fold an ordered envelope log into a materialized state — the `ReplayFn` the store injects.
+     *
+     * **A WITHDRAWAL EXCLUDES NOTHING.** §16.4 is explicit: withdrawing rolls the change back with
+     * a *Yjs undo* and writes a record "beside the original envelope — marked withdrawn, never
+     * deleted, so the log stays intact". Rejection resolves the same way, by supersession —
+     * "inverses, not erasure" (§3.2). So the undo is itself an ordinary update in the log, and
+     * replay simply applies every payload in order.
+     *
+     * An earlier version of this method excluded the referenced envelope instead, which is
+     * unsound in a CRDT log and was measured to be so: Yjs operations are causally chained, so
+     * dropping any but the LAST envelope leaves every later one depending on structs that never
+     * arrive — the document rebuilds until the next daemon restart and is permanently unopenable
+     * after it. It also let ANY sender suppress ANY other sender's content by appending a
+     * payload-free row, since nothing upstream checks authorship of a reference. Both problems
+     * dissolve when the log is simply replayed, which is what the spec said to do.
+     *
+     * REFUSES rather than skipping. A payload that will not apply means the log is corrupt, and
+     * folding the rest would produce a document that reads as complete while missing operations —
+     * the silent divergence the whole two-layer design exists to prevent.
+     */
+    replay(envelopes: readonly DocumentEnvelopeRow[]): {
+        binary: Uint8Array;
+        stateVector: Uint8Array;
+    };
+}
+//# sourceMappingURL=document-engine.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"document-engine.d.ts","sourceRoot":"","sources":["../src/document-engine.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAEH,OAAO,KAAK,CAAC,MAAM,KAAK,CAAC;AACzB,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,qBAAqB,CAAC;AAC/D,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,YAAY,CAAC;AAEzC,MAAM,MAAM,qBAAqB,GAC7B,2BAA2B,GAC3B,2BAA2B,GAC3B,2BAA2B,GAC3B,yCAAyC,GACzC,6BAA6B,GAC7B,8BAA8B,GAC9B,0BAA0B,CAAC;AAE/B,MAAM,MAAM,oBAAoB,GAC5B;IAAE,EAAE,EAAE,IAAI,CAAA;CAAE;AACd,kEAAkE;GAChE;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,qBAAqB,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC;AAElE;oDACoD;AACpD,qBAAa,mBAAoB,SAAQ,KAAK;IAC5C,QAAQ,CAAC,MAAM,EAAE,qBAAqB,CAAC;IACvC,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;gBACb,MAAM,EAAE,qBAAqB,EAAE,MAAM,CAAC,EAAE,MAAM;CAM3D;AAcD,qBAAa,cAAc;;gBAGb,MAAM,EAAE,MAAM;IAI1B,2EAA2E;IAC3E,IAAI,cAAc,IAAI,MAAM,CAE3B;IAED;;;;;;;;OAQG;IACH,cAAc,CAAC,eAAe,SAAK,GAAG,CAAC,CAAC,GAAG;IAM3C;;;;;;;OAOG;IACH,YAAY,CAAC,GAAG,EAAE,CAAC,CAAC,GAAG,GAAG,MAAM;IAIhC,kBAAkB,CAAC,GAAG,EAAE,CAAC,CAAC,GAAG,EAAE,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI;IAIjE,sFAAsF;IACtF,WAAW,CAAC,GAAG,EAAE,CAAC,CAAC,GAAG,EAAE,gBAAgB,CAAC,EAAE,UAAU,GAAG,UAAU;IAIlE,iBAAiB,CAAC,GAAG,EAAE,CAAC,CAAC,GAAG,GAAG,UAAU;IAIzC,QAAQ,CAAC,GAAG,EAAE,CAAC,CAAC,GAAG,GAAG;QAAE,MAAM,EAAE,UAAU,CAAC;QAAC,WAAW,EAAE,UAAU,CAAA;KAAE;IAIrE;;;;;OAKG;IACH,OAAO,CAAC,MAAM,EAAE,UAAU,GAAG,CAAC,CAAC,GAAG;IA4BlC;;;;;;OAMG;IACH;;;;;;;;;OASG;IACH,WAAW,CAAC,GAAG,EAAE,CAAC,CAAC,GAAG,EAAE,MAAM,EAAE,UAAU,GAAG,oBAAoB;IAmFjE,wEAAwE;IACxE,kBAAkB,CAAC,GAAG,EAAE,CAAC,CAAC,GAAG,EAAE,MAAM,EAAE,UAAU,GAAG,IAAI;IAKxD;;;;;;;;;;;;;;;;;;;;OAoBG;IACH,MAAM,CAAC,SAAS,EAAE,SAAS,mBAAmB,EAAE,GAAG;QAAE,MAAM,EAAE,UAAU,CAAC;QAAC,WAAW,EAAE,UAAU,CAAA;KAAE;CA6CnG"}