@cello-protocol/daemon 0.0.227 → 0.0.229

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

@@ -0,0 +1 @@
+{"version":3,"file":"document-profile.d.ts","sourceRoot":"","sources":["../src/document-profile.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AAEH,uFAAuF;AACvF,MAAM,WAAW,gBAAgB;IAC/B,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,EAAE,CAAC;IACrB,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,EAAE,CAAC;CACnB;AA0BD;;;;;;GAMG;AACH,eAAO,MAAM,gBAAgB,EAAE,MAAM,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,OAAO,CAYpE,CAAC;AAEF,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,GAAG,OAAO,CAEhE;AAMD;;;;;;;;GAQG;AACH,wBAAgB,gBAAgB,CAC9B,OAAO,EAAE,MAAM,GAAG,SAAS,EAC3B,IAAI,EAAE,MAAM,GACX,gBAAgB,GAAG,IAAI,CAoBzB"}

package/dist/document-profile.js

@@ -0,0 +1,112 @@
+/**
+ * DOD-DOC-PROFILE-1 — the content profile: an ALLOWLIST, agreed at the handshake.
+ *
+ * ── WHY AN ALLOWLIST WHEN A DENYLIST ALREADY EXISTS ───────────────────────────────────────────
+ *
+ * `document-screen.ts` is the denylist: it argues about characters, one at a time, in an open-ended
+ * space, and every argument happens mid-document with whoever is working ambushed by it. A profile
+ * inverts that. Only this character space is permitted, so violations are unambiguous — and the
+ * decision moves to CONSENT, which is the real win. "Do I want a Devanagari document with this
+ * person" is a question an operator can answer once, with a human already engaged, about the whole
+ * document. "What is U+200D doing at offset 412" is not a question anyone can answer.
+ *
+ * ── THE THREE CONSTRAINTS ─────────────────────────────────────────────────────────────────────
+ *
+ *   NAMED AND CLOSED. A free-form profile is a negotiation again, and named profiles are what let
+ *   an operator hold a standing policy — "never auto-accept `unicode-text` from an unendorsed
+ *   contact". A sixth name is a protocol decision, not a caller's choice.
+ *
+ *   CODEPOINT SETS, NOT ADJECTIVES. A profile enforced by a heuristic is a promise we do not keep,
+ *   and "looks like markdown" is a heuristic. Every profile below is a predicate over code points.
+ *
+ *   ENFORCED IN BOTH PLACES, for different reasons (§16.7-14). At authoring, so a stray character
+ *   is caught where it was written and never becomes a rejection round — that is ERGONOMICS. At
+ *   receipt, because the sender's enforcement is unverifiable — that is SECURITY. The second is not
+ *   redundant with the first: a sender's client can be patched, or simply compromised while the
+ *   sender themselves is a good actor.
+ *
+ * ── NARROWING ONLY ────────────────────────────────────────────────────────────────────────────
+ *
+ * Every profile, including the widest, still refuses what `document-screen.ts` refuses. A profile
+ * may only narrow the space, never widen it — otherwise choosing `unicode-text` would be a way to
+ * opt OUT of screening, and a peer could ask for that at consent time in the same breath as asking
+ * for Japanese.
+ */
+/** Shape of text, in every profile: the two characters that are structure rather than content. */
+const TAB = 0x09;
+const NEWLINE = 0x0a;
+const CARRIAGE_RETURN = 0x0d;
+/**
+ * Refused by EVERY profile — the floor `document-screen.ts` sets, restated here so a profile cannot
+ * be used to bypass it. Kept as its own set rather than imported so the two can be read
+ * independently: this one is "no profile may admit these", which is a different claim from "the
+ * default rules refuse these".
+ */
+const NEVER = new Set([
+    0x200b, 0x202a, 0x202b, 0x202c, 0x202d, 0x202e, 0x2066, 0x2067, 0x2068, 0x2069,
+]);
+function isShapingChar(cp) {
+    return cp === TAB || cp === NEWLINE || cp === CARRIAGE_RETURN;
+}
+/** Printable ASCII. Control characters are not content — they address whatever renders them. */
+function isPrintableAscii(cp) {
+    return cp >= 0x20 && cp <= 0x7e;
+}
+/**
+ * The closed set. Each value answers one question: may this code point appear?
+ *
+ * `ascii-markdown` and `ascii-text` are the same space today — markdown's syntax is printable ASCII.
+ * They are kept distinct because the NAME is what an operator consents to and what a future diff
+ * renderer keys on, and collapsing them would make "this is a markdown document" unstateable.
+ */
+export const CONTENT_PROFILES = {
+    "ascii-text": (cp) => isShapingChar(cp) || isPrintableAscii(cp),
+    "ascii-markdown": (cp) => isShapingChar(cp) || isPrintableAscii(cp),
+    // JSON is ASCII-only BY DESIGN: `é` is how JSON carries `é`. Admitting the raw character too
+    // would mean two documents that parse identically have different bytes, and a CRDT replica's
+    // whole claim is that they do not.
+    json: (cp) => isShapingChar(cp) || isPrintableAscii(cp),
+    // The wide profiles admit anything that is not explicitly refused — including every sample the
+    // sanitizer audit destroyed. A profile that refused Devanagari orthography or a family emoji
+    // would be that same failure wearing a different name.
+    "unicode-text": (cp) => !NEVER.has(cp),
+    "unicode-markdown": (cp) => !NEVER.has(cp),
+};
+export function isKnownProfile(name) {
+    return typeof name === "string" && Object.hasOwn(CONTENT_PROFILES, name);
+}
+function formatCodepoint(cp) {
+    return `U+${cp.toString(16).toUpperCase().padStart(4, "0")}`;
+}
+/**
+ * Check text against a profile. Null admits.
+ *
+ * AN UNKNOWN OR ABSENT PROFILE ENFORCES NOTHING, and this is the one fail-open on the document
+ * path. A document agreed before profiles existed carries none, and refusing all of its updates
+ * would break a working document to enforce a rule its two parties never agreed to. The screening
+ * denylist still applies to it — that is the floor, and it is why failing open here is bounded
+ * rather than a hole.
+ */
+export function profileViolation(profile, text) {
+    if (!isKnownProfile(profile))
+        return null;
+    const allows = CONTENT_PROFILES[profile];
+    const codepoints = new Set();
+    const offsets = [];
+    let index = 0;
+    for (const ch of text) {
+        const cp = ch.codePointAt(0);
+        if (!allows(cp) || NEVER.has(cp)) {
+            codepoints.add(formatCodepoint(cp));
+            offsets.push(index);
+        }
+        // CODE POINTS, not UTF-16 units — the offsets exist for a human or an agent to find the
+        // character in their own editor, and one that lands mid-surrogate in a document containing an
+        // emoji is worse than none.
+        index++;
+    }
+    if (codepoints.size === 0)
+        return null;
+    return { profile: profile, codepoints: [...codepoints], count: offsets.length, offsets };
+}
+//# sourceMappingURL=document-profile.js.map

package/dist/document-profile.js.map

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

package/dist/document-publish.d.ts

@@ -0,0 +1,87 @@
+/**
+ * DOD-DOC-DELIVERY-1 (outbound half) — turning a local edit into a signed envelope in the log.
+ *
+ * Publish is fire-and-forget by design (§16.4): it writes the envelope and returns. Delivery is the
+ * worker's job, and pending is derived from the log, so the only thing publish has to get right is
+ * that what it writes is complete, signed, and correctly chained.
+ *
+ * ── WHAT IS PUBLISHED IS A DIFF AGAINST THE PEER'S STATE VECTOR ───────────────────────────────
+ *
+ * Not the whole document. §3.2 step 3 and §7: an update computed against what the peer has already
+ * seen carries exactly the operations they lack — including, after a rejection, the refused
+ * operations PLUS their inverses, which is what lets supersession converge. Publishing the full
+ * state instead would work but would re-send the entire document on every edit, and would lose the
+ * property that makes the rejection protocol terminate.
+ *
+ * The peer's state vector is the one they last told us about. Absent — before they have ever
+ * published — the diff is against an empty document, which is the whole state and correct.
+ *
+ * ── THE CHAIN LINK IS READ, NEVER GUESSED ─────────────────────────────────────────────────────
+ *
+ * `doc_prev_hash` is our own last envelope for this document, read from the log at publish time. A
+ * cached value would go stale the moment anything else appended — a rejection, a withdrawal — and a
+ * wrong link is not a soft failure: the peer refuses it and, if it is ever replayed locally, the
+ * document stops rebuilding.
+ */
+import type * as Y from "yjs";
+import type { DocumentStore } from "./document-store.js";
+import type { DocumentEngine } from "./document-engine.js";
+import type { Logger } from "./types.js";
+export type PublishResult = {
+    ok: true;
+    envelopeHash: string;
+    bytes: number;
+} | {
+    ok: false;
+    reason: string;
+    detail: string;
+};
+export interface DocumentPublishDeps {
+    /**
+     * SYNC-G1 — the author's governance frontier at publish time (entry hashes, the fold's
+     * heads). Stamped into the signed envelope as content's causal link to the governance that
+     * makes it admissible; receivers rule R20/R30 on it. Null when the frontier cannot be
+     * derived — the publish REFUSES rather than stamping a guess.
+     */
+    governanceFrontierFor(ownerAgentId: string, documentId: string): string[] | null;
+    store: DocumentStore;
+    engine: DocumentEngine;
+    logger: Logger;
+    /** Sign as the owning agent, over the update envelope's TBS. */
+    sign(ownerAgentId: string, tbs: Uint8Array): Promise<Uint8Array>;
+    /** The owning agent's own id — which is its pubkey hex (M14-D5) — for the envelope's sender. */
+    senderIdFor(ownerAgentId: string): string | null;
+    /** May this agent publish into this document right now? LIFECYCLE-1 owns the answer. */
+    canPublish(ownerAgentId: string, documentId: string): {
+        ok: true;
+    } | {
+        ok: false;
+        reason: string;
+        detail: string;
+    };
+    /**
+     * M14B / FANOUT-1 — the CURRENT derived holders. Null means the chain does not derive, and a
+     * publish that cannot name its targets REFUSES rather than appending an envelope nothing will
+     * ever deliver (an un-seeded envelope is invisible work — the exact silent failure the
+     * envelope-first rule exists to prevent, arriving through the other door).
+     */
+    holdersFor(ownerAgentId: string, documentId: string): string[] | null;
+    /**
+     * SYNC-P4 (R39's first trigger): a publish NUDGES every other seat by initiating a reconcile
+     * exchange with them — fire-and-forget, no ledger, no schedule. A nudge that does not land
+     * strands nothing: the difference it would have closed is recomputed at any later exchange.
+     */
+    nudgeSeats(ownerAgentId: string, documentId: string, seats: readonly string[]): void;
+}
+export declare class DocumentPublish {
+    #private;
+    constructor(deps: DocumentPublishDeps);
+    /**
+     * Publish the live document's state as an update the peer does not yet have.
+     *
+     * Returns the envelope hash so a caller can follow it — a publish that says only "ok" gives an
+     * operator nothing to correlate with what later lands or stalls.
+     */
+    publish(ownerAgentId: string, documentId: string, doc: Y.Doc, nowMs: number): Promise<PublishResult>;
+}
+//# sourceMappingURL=document-publish.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"document-publish.d.ts","sourceRoot":"","sources":["../src/document-publish.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAEH,OAAO,KAAK,KAAK,CAAC,MAAM,KAAK,CAAC;AAO9B,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACzD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAC3D,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,YAAY,CAAC;AAEzC,MAAM,MAAM,aAAa,GACrB;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,YAAY,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,GACjD;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC;AAElD,MAAM,WAAW,mBAAmB;IAClC;;;;;OAKG;IACH,qBAAqB,CAAC,YAAY,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,IAAI,CAAC;IACjF,KAAK,EAAE,aAAa,CAAC;IACrB,MAAM,EAAE,cAAc,CAAC;IACvB,MAAM,EAAE,MAAM,CAAC;IACf,gEAAgE;IAChE,IAAI,CAAC,YAAY,EAAE,MAAM,EAAE,GAAG,EAAE,UAAU,GAAG,OAAO,CAAC,UAAU,CAAC,CAAC;IACjE,gGAAgG;IAChG,WAAW,CAAC,YAAY,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAAC;IACjD,wFAAwF;IACxF,UAAU,CAAC,YAAY,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG;QAAE,EAAE,EAAE,IAAI,CAAA;KAAE,GAAG;QAAE,EAAE,EAAE,KAAK,CAAC;QAAC,MAAM,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC;IACnH;;;;;OAKG;IACH,UAAU,CAAC,YAAY,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,IAAI,CAAC;IACtE;;;;OAIG;IACH,UAAU,CAAC,YAAY,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,KAAK,EAAE,SAAS,MAAM,EAAE,GAAG,IAAI,CAAC;CACtF;AAQD,qBAAa,eAAe;;gBAGd,IAAI,EAAE,mBAAmB;IAIrC;;;;;OAKG;IACG,OAAO,CACX,YAAY,EAAE,MAAM,EACpB,UAAU,EAAE,MAAM,EAClB,GAAG,EAAE,CAAC,CAAC,GAAG,EACV,KAAK,EAAE,MAAM,GACZ,OAAO,CAAC,aAAa,CAAC;CAuI1B"}

package/dist/document-publish.js

@@ -0,0 +1,173 @@
+/**
+ * DOD-DOC-DELIVERY-1 (outbound half) — turning a local edit into a signed envelope in the log.
+ *
+ * Publish is fire-and-forget by design (§16.4): it writes the envelope and returns. Delivery is the
+ * worker's job, and pending is derived from the log, so the only thing publish has to get right is
+ * that what it writes is complete, signed, and correctly chained.
+ *
+ * ── WHAT IS PUBLISHED IS A DIFF AGAINST THE PEER'S STATE VECTOR ───────────────────────────────
+ *
+ * Not the whole document. §3.2 step 3 and §7: an update computed against what the peer has already
+ * seen carries exactly the operations they lack — including, after a rejection, the refused
+ * operations PLUS their inverses, which is what lets supersession converge. Publishing the full
+ * state instead would work but would re-send the entire document on every edit, and would lose the
+ * property that makes the rejection protocol terminate.
+ *
+ * The peer's state vector is the one they last told us about. Absent — before they have ever
+ * published — the diff is against an empty document, which is the whole state and correct.
+ *
+ * ── THE CHAIN LINK IS READ, NEVER GUESSED ─────────────────────────────────────────────────────
+ *
+ * `doc_prev_hash` is our own last envelope for this document, read from the log at publish time. A
+ * cached value would go stale the moment anything else appended — a rejection, a withdrawal — and a
+ * wrong link is not a soft failure: the peer refuses it and, if it is ever replayed locally, the
+ * document stops rebuilding.
+ */
+import { buildDocumentUpdateTbs, documentEnvelopeHash, DOCUMENT_UPDATE_ENCODING_V1, } from "@cello-protocol/protocol-types";
+function equalBytes(a, b) {
+    if (a.length !== b.length)
+        return false;
+    for (let i = 0; i < a.length; i++)
+        if (a[i] !== b[i])
+            return false;
+    return true;
+}
+export class DocumentPublish {
+    #d;
+    constructor(deps) {
+        this.#d = deps;
+    }
+    /**
+     * Publish the live document's state as an update the peer does not yet have.
+     *
+     * Returns the envelope hash so a caller can follow it — a publish that says only "ok" gives an
+     * operator nothing to correlate with what later lands or stalls.
+     */
+    async publish(ownerAgentId, documentId, doc, nowMs) {
+        const document = this.#d.store.getDocument(ownerAgentId, documentId);
+        if (!document) {
+            return {
+                ok: false,
+                reason: "document_unknown",
+                detail: `no document ${documentId.slice(0, 16)}… for this agent`,
+            };
+        }
+        // LIFECYCLE-1 decides. A closed, killed, stalled or platform-paused agent must not publish, and
+        // the reason it gives is the one the operator needs — not a generic refusal from here.
+        const allowed = this.#d.canPublish(ownerAgentId, documentId);
+        if (!allowed.ok)
+            return { ok: false, reason: allowed.reason, detail: allowed.detail };
+        const senderId = this.#d.senderIdFor(ownerAgentId);
+        if (senderId === null) {
+            return {
+                ok: false,
+                reason: "document_publish_no_identity",
+                detail: `no signing identity for ${ownerAgentId}, so an envelope cannot be authored`,
+            };
+        }
+        // THE PEER's state vector, from their most recent envelope — not our own snapshot. Our
+        // snapshot answers "what have we not yet materialized", which is a different question whose
+        // answer looks plausible: it produced an update every time, so a republish with no new edits
+        // appended a second envelope instead of reporting that there was nothing to say.
+        const peerStateVector = this.#d.store.peerStateVector(ownerAgentId, documentId, document.peerAgentId) ?? undefined;
+        const update = this.#d.engine.encodeState(doc, peerStateVector);
+        // NOTHING NEW is a different question from what to SEND, and conflating them was a bug. The
+        // update is a diff against the PEER's state vector, so before they have ever published it is
+        // the whole document — non-empty however long we have gone without editing. Whether there is
+        // anything new is a fact about US: compare our current state vector against the one our own
+        // last envelope carried.
+        const ourLast = this.#d.store.lastPublishedStateVector(ownerAgentId, documentId, senderId);
+        const ourNow = this.#d.engine.encodeStateVector(doc);
+        if (ourLast !== null && equalBytes(ourLast, ourNow)) {
+            // Publishing anyway would append a leaf, cost a delivery, and converge nothing.
+            return {
+                ok: false,
+                reason: "document_nothing_to_publish",
+                detail: "nothing has changed in this document since your last publish",
+            };
+        }
+        if (update.length === 0) {
+            return {
+                ok: false,
+                reason: "document_nothing_to_publish",
+                detail: "the peer already has everything in this document",
+            };
+        }
+        // SYNC-G1: the frontier is stamped, or the publish refuses — a guessed anchor would let
+        // this envelope claim governance its author never held.
+        const governanceParents = this.#d.governanceFrontierFor(ownerAgentId, documentId);
+        if (governanceParents === null) {
+            return {
+                ok: false,
+                reason: "document_frontier_underivable",
+                detail: "this document's governance could not be derived, so the envelope cannot name the " +
+                    "frontier it was authored under — fix the chain before publishing",
+            };
+        }
+        const envelope = {
+            type: "document_update",
+            document_id: documentId,
+            // READ, never cached. Anything else appended since — a rejection, a withdrawal — moves this,
+            // and a wrong link is refused by the peer and stops the document rebuilding locally.
+            doc_prev_hash: this.#d.store.lastEnvelopeHashBySender(ownerAgentId, documentId, senderId),
+            sender_agent_id: senderId,
+            sender_client_id: doc.clientID,
+            update_encoding: DOCUMENT_UPDATE_ENCODING_V1,
+            state_vector: ourNow,
+            update,
+            governance_parents: [...governanceParents].sort(),
+            signature: new Uint8Array(0),
+        };
+        // TARGETS BEFORE THE ENVELOPE: a publish that cannot name its holders refuses before it
+        // writes, because an appended-but-unseeded envelope is invisible work nothing will deliver.
+        const holders = this.#d.holdersFor(ownerAgentId, documentId);
+        if (holders === null) {
+            return {
+                ok: false,
+                reason: "document_chain_invalid",
+                detail: "this document's arrangement does not derive from its recorded chain — nothing can be " +
+                    "published until it does; see document.holders.underivable in the log",
+            };
+        }
+        envelope.signature = await this.#d.sign(ownerAgentId, buildDocumentUpdateTbs(envelope));
+        const envelopeHash = documentEnvelopeHash(envelope);
+        const appended = this.#d.store.appendEnvelope(ownerAgentId, {
+            envelopeHash,
+            documentId,
+            senderAgentId: senderId,
+            docPrevHash: envelope.doc_prev_hash,
+            governanceParents: [...envelope.governance_parents],
+            signature: envelope.signature,
+            stateVector: envelope.state_vector,
+            payload: update,
+            kind: "update",
+            referencesEnvelopeHash: null,
+            // Recorded so the peer's authorship binding is derived from what we SIGNED, matching what the
+            // inbound path stores for their envelopes.
+            senderClientId: doc.clientID,
+            createdAtMs: nowMs,
+        });
+        if (!appended) {
+            // The same content published twice hashes the same, so this is a genuine no-op rather than a
+            // fault — but it is reported, because a caller that believes it published something new and
+            // waits for it to deliver would wait forever.
+            return {
+                ok: false,
+                reason: "document_already_published",
+                detail: `this exact update is already in the log as ${envelopeHash.slice(0, 16)}…`,
+            };
+        }
+        this.#d.logger.info("document.published", {
+            documentId,
+            envelopeHash,
+            bytes: update.length,
+            senderClientId: doc.clientID,
+        });
+        // Fire and forget: the NUDGE (an initiated reconcile per seat) is how the envelope travels
+        // now — there is no delivery ledger and no worker. Nothing here waits for a peer, and a nudge
+        // that does not land is repaired by any later exchange.
+        this.#d.nudgeSeats(ownerAgentId, documentId, holders.filter((h) => h !== senderId));
+        return { ok: true, envelopeHash, bytes: update.length };
+    }
+}
+//# sourceMappingURL=document-publish.js.map

package/dist/document-publish.js.map

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

package/dist/document-reachability.d.ts

@@ -0,0 +1,42 @@
+/**
+ * DOD-DOC-DELIVERY-2 — binding the delivery worker's reachability check to `discovery_lookup`.
+ *
+ * The worker asks one question — "is this peer reachable right now?" — and its whole retry
+ * behaviour turns on the answer being about the PEER. `runDiscoveryLookup` deliberately returns
+ * five outcomes, only one of which is an answer about the peer at all, and this maps them:
+ *
+ *   result / offline | unknown_agent  ->  false   the peer is not reachable. A fact about them.
+ *   result / online                   ->  true
+ *   error | malformed | timeout | send_failed
+ *                                     ->  THROW   the lookup did not happen. A fact about US.
+ *
+ * The throw is the point. `isPeerReachable` returning false for a directory fault would record a
+ * directory outage — or our own signaling stream being down — as the operator's collaborator being
+ * absent, and send them to ask the wrong person why nothing is syncing. The worker already treats
+ * a throw as `lookup_failed` and keeps that distinction in the log; this is what feeds it.
+ *
+ * `unknown_agent` maps to false rather than throwing on purpose. It IS an answer from the
+ * directory about the peer — the address does not resolve — and the honest consequence is the same
+ * as offline: do not dial, retry later. It is a bad address rather than a transient absence, so it
+ * is surfaced distinctly by the caller rather than being collapsed into the same log line.
+ */
+import type { DiscoveryOutcome } from "./cross-node-negotiation.js";
+/** Why a lookup could not be performed. Carries the upstream reason verbatim. */
+export declare class DiscoveryUnavailableError extends Error {
+    readonly kind: string;
+    constructor(kind: string, reason: string);
+}
+export interface Reachability {
+    reachable: boolean;
+    /** Present when the directory answered but the address does not resolve to a known agent. */
+    unknownAgent: boolean;
+}
+/**
+ * Map a discovery outcome onto the worker's reachability question.
+ *
+ * Pure, so the mapping is testable without a directory — which matters, because the expensive way
+ * to discover this mapping is wrong is in production, where the symptom is an operator chasing a
+ * collaborator who was never offline.
+ */
+export declare function reachabilityFromDiscovery(outcome: DiscoveryOutcome): Reachability;
+//# sourceMappingURL=document-reachability.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"document-reachability.d.ts","sourceRoot":"","sources":["../src/document-reachability.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,6BAA6B,CAAC;AAEpE,iFAAiF;AACjF,qBAAa,yBAA0B,SAAQ,KAAK;IAClD,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;gBACV,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM;CAKzC;AAED,MAAM,WAAW,YAAY;IAC3B,SAAS,EAAE,OAAO,CAAC;IACnB,6FAA6F;IAC7F,YAAY,EAAE,OAAO,CAAC;CACvB;AAED;;;;;;GAMG;AACH,wBAAgB,yBAAyB,CAAC,OAAO,EAAE,gBAAgB,GAAG,YAAY,CA+CjF"}

package/dist/document-reachability.js

@@ -0,0 +1,80 @@
+/**
+ * DOD-DOC-DELIVERY-2 — binding the delivery worker's reachability check to `discovery_lookup`.
+ *
+ * The worker asks one question — "is this peer reachable right now?" — and its whole retry
+ * behaviour turns on the answer being about the PEER. `runDiscoveryLookup` deliberately returns
+ * five outcomes, only one of which is an answer about the peer at all, and this maps them:
+ *
+ *   result / offline | unknown_agent  ->  false   the peer is not reachable. A fact about them.
+ *   result / online                   ->  true
+ *   error | malformed | timeout | send_failed
+ *                                     ->  THROW   the lookup did not happen. A fact about US.
+ *
+ * The throw is the point. `isPeerReachable` returning false for a directory fault would record a
+ * directory outage — or our own signaling stream being down — as the operator's collaborator being
+ * absent, and send them to ask the wrong person why nothing is syncing. The worker already treats
+ * a throw as `lookup_failed` and keeps that distinction in the log; this is what feeds it.
+ *
+ * `unknown_agent` maps to false rather than throwing on purpose. It IS an answer from the
+ * directory about the peer — the address does not resolve — and the honest consequence is the same
+ * as offline: do not dial, retry later. It is a bad address rather than a transient absence, so it
+ * is surfaced distinctly by the caller rather than being collapsed into the same log line.
+ */
+/** Why a lookup could not be performed. Carries the upstream reason verbatim. */
+export class DiscoveryUnavailableError extends Error {
+    kind;
+    constructor(kind, reason) {
+        super(`document_discovery_unavailable: ${kind}${reason ? ` (${reason})` : ""}`);
+        this.name = "DiscoveryUnavailableError";
+        this.kind = kind;
+    }
+}
+/**
+ * Map a discovery outcome onto the worker's reachability question.
+ *
+ * Pure, so the mapping is testable without a directory — which matters, because the expensive way
+ * to discover this mapping is wrong is in production, where the symptom is an operator chasing a
+ * collaborator who was never offline.
+ */
+export function reachabilityFromDiscovery(outcome) {
+    switch (outcome.kind) {
+        case "result":
+            if (outcome.state === "online") {
+                if (outcome.owningNodeIds.length === 0) {
+                    // `classifyOnlineResult` calls exactly this shape malformed — "online but no owner named
+                    // … never dial a fabricated node" — and treats it as retry, not as availability. This
+                    // module's whole thesis is that only a RESULT is an answer about the peer; a result that
+                    // names no home answers nothing.
+                    throw new DiscoveryUnavailableError("online_without_owner", "no owning node named");
+                }
+                return { reachable: true, unknownAgent: false };
+            }
+            if (outcome.state === "unknown_agent")
+                return { reachable: false, unknownAgent: true };
+            return { reachable: false, unknownAgent: false };
+        case "error":
+            // A directory DB fault. Retryable, and emphatically not the counterparty being offline —
+            // the outcome type's own comment says so, and collapsing it here would undo that care.
+            throw new DiscoveryUnavailableError("directory_error", outcome.reason);
+        case "malformed":
+            // A reply that did not parse: a protocol or version anomaly on a directory that DID respond.
+            // Distinct from a clean directory error, and never availability.
+            throw new DiscoveryUnavailableError("malformed_reply", "");
+        case "timeout":
+            // No reply in the window — an old directory, or a slow or dropped reply on a new one. Either
+            // way we learned nothing about the peer.
+            throw new DiscoveryUnavailableError("timeout", "");
+        case "send_failed":
+            // Our OWN signaling stream is down. The most important one to keep separate: reporting our
+            // transport fault as the peer's absence points the operator at the wrong machine entirely.
+            throw new DiscoveryUnavailableError("signaling_unavailable", outcome.reason);
+        default: {
+            // Exhaustiveness, enforced by the compiler. A new outcome kind must be classified
+            // deliberately rather than defaulting into "reachable" or "offline", which are the two
+            // answers a silent default would have to invent.
+            const never = outcome;
+            throw new DiscoveryUnavailableError("unrecognized_outcome", `unhandled discovery outcome ${JSON.stringify(never)}`);
+        }
+    }
+}
+//# sourceMappingURL=document-reachability.js.map

package/dist/document-reachability.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"document-reachability.js","sourceRoot":"","sources":["../src/document-reachability.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAIH,iFAAiF;AACjF,MAAM,OAAO,yBAA0B,SAAQ,KAAK;IACzC,IAAI,CAAS;IACtB,YAAY,IAAY,EAAE,MAAc;QACtC,KAAK,CAAC,mCAAmC,IAAI,GAAG,MAAM,CAAC,CAAC,CAAC,KAAK,MAAM,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;QAChF,IAAI,CAAC,IAAI,GAAG,2BAA2B,CAAC;QACxC,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;IACnB,CAAC;CACF;AAQD;;;;;;GAMG;AACH,MAAM,UAAU,yBAAyB,CAAC,OAAyB;IACjE,QAAQ,OAAO,CAAC,IAAI,EAAE,CAAC;QACrB,KAAK,QAAQ;YACX,IAAI,OAAO,CAAC,KAAK,KAAK,QAAQ,EAAE,CAAC;gBAC/B,IAAI,OAAO,CAAC,aAAa,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;oBACvC,yFAAyF;oBACzF,sFAAsF;oBACtF,yFAAyF;oBACzF,iCAAiC;oBACjC,MAAM,IAAI,yBAAyB,CAAC,sBAAsB,EAAE,sBAAsB,CAAC,CAAC;gBACtF,CAAC;gBACD,OAAO,EAAE,SAAS,EAAE,IAAI,EAAE,YAAY,EAAE,KAAK,EAAE,CAAC;YAClD,CAAC;YACD,IAAI,OAAO,CAAC,KAAK,KAAK,eAAe;gBAAE,OAAO,EAAE,SAAS,EAAE,KAAK,EAAE,YAAY,EAAE,IAAI,EAAE,CAAC;YACvF,OAAO,EAAE,SAAS,EAAE,KAAK,EAAE,YAAY,EAAE,KAAK,EAAE,CAAC;QAEnD,KAAK,OAAO;YACV,yFAAyF;YACzF,uFAAuF;YACvF,MAAM,IAAI,yBAAyB,CAAC,iBAAiB,EAAE,OAAO,CAAC,MAAM,CAAC,CAAC;QAEzE,KAAK,WAAW;YACd,6FAA6F;YAC7F,iEAAiE;YACjE,MAAM,IAAI,yBAAyB,CAAC,iBAAiB,EAAE,EAAE,CAAC,CAAC;QAE7D,KAAK,SAAS;YACZ,6FAA6F;YAC7F,yCAAyC;YACzC,MAAM,IAAI,yBAAyB,CAAC,SAAS,EAAE,EAAE,CAAC,CAAC;QAErD,KAAK,aAAa;YAChB,2FAA2F;YAC3F,2FAA2F;YAC3F,MAAM,IAAI,yBAAyB,CAAC,uBAAuB,EAAE,OAAO,CAAC,MAAM,CAAC,CAAC;QAE/E,OAAO,CAAC,CAAC,CAAC;YACR,kFAAkF;YAClF,uFAAuF;YACvF,iDAAiD;YACjD,MAAM,KAAK,GAAU,OAAO,CAAC;YAC7B,MAAM,IAAI,yBAAyB,CACjC,sBAAsB,EACtB,+BAA+B,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,EAAE,CACvD,CAAC;QACJ,CAAC;IACH,CAAC;AACH,CAAC"}

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

@@ -0,0 +1,66 @@
+/**
+ * SYNC-P3 (R10, R17–R20, R36) — the responder half of the reconcile exchange.
+ *
+ * Given a peer's position for one document, decide from OUR OWN state alone whether they may be
+ * answered at all (the four entitlement classes, R17), and if so compute exactly what they lack:
+ * governance entries first, then content envelopes, never anything in their refusal set (R36).
+ * The reply carries our own position so the initiator can send step 3 if WE are behind — the
+ * exchange is symmetric by construction.
+ *
+ * Everything here is derived at the moment of the exchange from the entry set and the envelope
+ * log. There is no per-peer record consulted and none written (R8/R9): asked twice, we answer
+ * twice, identically — idempotence is not bookkeeping, it is the absence of bookkeeping.
+ */
+import { type DocumentReconcileBlock, type DocumentStateView } from "@cello-protocol/protocol-types";
+import type { DocumentEnvelopeRow } from "./document-store.js";
+import type { AuthorWatermark } from "./document-amendment-store.js";
+/** The reads the engine needs — a seam so the tests exercise decisions, not plumbing. */
+export interface ReconcileReads {
+    deriveState(documentId: string): {
+        ok: true;
+        state: DocumentStateView;
+    } | {
+        ok: false;
+        reason: string;
+    };
+    watermarks(documentId: string): Map<string, AuthorWatermark>;
+    entriesByAuthorAfter(documentId: string, author: string, afterSeq: number): Uint8Array[];
+    envelopeLog(documentId: string): DocumentEnvelopeRow[];
+    /** Hashes THIS holder has refused — its own decisions, surfaced into its position (R36). */
+    refusedHashes(documentId: string): string[];
+    /** SYNC-R35: this holder's own SIGNED refusal records (document_rejection wires). */
+    refusalRecords(documentId: string): Uint8Array[];
+    /** SYNC-D8 — the fold-derived standing; "removed" is the one verdict consulted here. */
+    standingOf(documentId: string, agentId: string): "participant" | "invited" | "removed" | "stranger" | "unknown";
+    /** The signed genesis proposal bytes — the anchor a joiner-with-nothing must be handed. */
+    genesisBytes(documentId: string): Uint8Array | null;
+    /**
+     * R32 — the LAST removal entry naming this agent plus its full ancestor closure, as wire
+     * bytes in a foldable order, or null when no removal names them. This is what a removed
+     * holder is owed: enough to derive their own removal and nothing authored after it.
+     */
+    removalClosure(documentId: string, agentId: string): Uint8Array[] | null;
+}
+export type ReconcileAnswer = {
+    block: DocumentReconcileBlock;
+    /** True when the peer's position shows them holding something we lack — step 3 is wanted. */
+    peerAhead: boolean;
+    /** True when the byte budget cut the payload short — the peer's next exchange gets the rest. */
+    truncated: boolean;
+};
+/** A mutable byte allowance shared across the blocks of one reply frame (P3 review F3). */
+export interface ReplyBudget {
+    remainingBytes: number;
+}
+/** Our own position for one document — step 1's payload, and the position half of every reply. */
+export declare function buildReconcileBlock(reads: ReconcileReads, documentId: string): DocumentReconcileBlock;
+/**
+ * Answer a peer's position for one document. The entitlement ruling comes FIRST and from our
+ * own state alone (R18); a refusal rides the BLOCK (never silenced by a batch, review F4), and
+ * a refusal-bearing block carries EMPTY positions — a stranger learns nothing about where this
+ * holder stands. The removed holder is the one refusal that also DELIVERS: their own removal
+ * and its ancestors travel with the terminal ruling (R32), so a holder who was offline at
+ * removal time can derive why the document went quiet.
+ */
+export declare function respondToReconcile(reads: ReconcileReads, peerAgentId: string, peerBlock: DocumentReconcileBlock, budget?: ReplyBudget): ReconcileAnswer;
+//# sourceMappingURL=document-reconcile-engine.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"document-reconcile-engine.d.ts","sourceRoot":"","sources":["../src/document-reconcile-engine.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,EAKL,KAAK,sBAAsB,EAG3B,KAAK,iBAAiB,EACvB,MAAM,gCAAgC,CAAC;AACxC,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,qBAAqB,CAAC;AAC/D,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,+BAA+B,CAAC;AAErE,yFAAyF;AACzF,MAAM,WAAW,cAAc;IAC7B,WAAW,CAAC,UAAU,EAAE,MAAM,GAAG;QAAE,EAAE,EAAE,IAAI,CAAC;QAAC,KAAK,EAAE,iBAAiB,CAAA;KAAE,GAAG;QAAE,EAAE,EAAE,KAAK,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC;IACxG,UAAU,CAAC,UAAU,EAAE,MAAM,GAAG,GAAG,CAAC,MAAM,EAAE,eAAe,CAAC,CAAC;IAC7D,oBAAoB,CAAC,UAAU,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,UAAU,EAAE,CAAC;IACzF,WAAW,CAAC,UAAU,EAAE,MAAM,GAAG,mBAAmB,EAAE,CAAC;IACvD,4FAA4F;IAC5F,aAAa,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC;IAC5C,qFAAqF;IACrF,cAAc,CAAC,UAAU,EAAE,MAAM,GAAG,UAAU,EAAE,CAAC;IACjD,wFAAwF;IACxF,UAAU,CAAC,UAAU,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,aAAa,GAAG,SAAS,GAAG,SAAS,GAAG,UAAU,GAAG,SAAS,CAAC;IAChH,2FAA2F;IAC3F,YAAY,CAAC,UAAU,EAAE,MAAM,GAAG,UAAU,GAAG,IAAI,CAAC;IACpD;;;;OAIG;IACH,cAAc,CAAC,UAAU,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,UAAU,EAAE,GAAG,IAAI,CAAC;CAC1E;AAED,MAAM,MAAM,eAAe,GAAG;IAC5B,KAAK,EAAE,sBAAsB,CAAC;IAC9B,6FAA6F;IAC7F,SAAS,EAAE,OAAO,CAAC;IACnB,gGAAgG;IAChG,SAAS,EAAE,OAAO,CAAC;CACpB,CAAC;AAEF,2FAA2F;AAC3F,MAAM,WAAW,WAAW;IAC1B,cAAc,EAAE,MAAM,CAAC;CACxB;AAED,kGAAkG;AAClG,wBAAgB,mBAAmB,CACjC,KAAK,EAAE,cAAc,EACrB,UAAU,EAAE,MAAM,GACjB,sBAAsB,CAmBxB;AAkBD;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CAChC,KAAK,EAAE,cAAc,EACrB,WAAW,EAAE,MAAM,EACnB,SAAS,EAAE,sBAAsB,EACjC,MAAM,CAAC,EAAE,WAAW,GACnB,eAAe,CA+KjB"}