@cello-protocol/daemon 0.0.227 → 0.0.229

package/dist/document-wiring.d.ts

@@ -0,0 +1,53 @@
+import { type SecurityGatewayClient } from "@cello-protocol/gateway";
+import type { IpcHandler } from "./ipc-server.js";
+import type { SessionNodeManager } from "./session-node-manager.js";
+import type { Logger } from "./types.js";
+import type { LoadedAgent } from "./agent-loader.js";
+import type { KeyProvider } from "@cello-protocol/crypto";
+import type { SignalingManager } from "@cello-protocol/transport";
+import type { NotificationDispatcher } from "./notification-dispatcher.js";
+import type { DiscoveryOutcome } from "./cross-node-negotiation.js";
+export interface DocumentWiringDeps {
+    logger: Logger;
+    sessionNodeManager: SessionNodeManager;
+    /** The LIVE registry — `cello_create_agent` pushes into it, so a new agent works without a restart. */
+    loadedAgents: ReadonlyArray<LoadedAgent>;
+    keyProviders: Map<string, KeyProvider>;
+    /** The gateway itself, not the config that holds it. */
+    securityGateway: SecurityGatewayClient;
+    /** Where the daemon keeps its data; documents live under it. */
+    celloDir: string;
+    deliveryOpens: {
+        begin: (openerPubkey: string, targetPubkey: string) => () => void;
+    };
+    pubkeyOfAgent: (name: string) => string;
+    openSessionFor: (agentName: string, opts: {
+        targetPubkey: string;
+    }) => Promise<unknown>;
+    perAgentSignaling: Map<string, {
+        signaling: SignalingManager;
+    }>;
+    runDiscoveryLookup: (signaling: SignalingManager, targetHex: string, timeoutMs: number, correlationId: string) => Promise<DiscoveryOutcome>;
+    /**
+     * ⚠️ A GETTER, NOT THE VALUE. The scheduler is constructed AFTER this wiring — it consumes the
+     * layer's sweep targets — so at the moment this module is built the binding is `undefined`.
+     * Passing the value captures that `undefined` for the life of the process and
+     * `reconcileScheduler?.noteRefusal(...)` becomes a permanent no-op: refusals still log, backoff
+     * never applies, and the sweep re-asks immediately. Measured cost of that state, from the
+     * scheduler's own notes: 321 attempts against two documents in 85 minutes, refused every time.
+     * Optional chaining makes it silent and the `| undefined` in the type makes it legal, so nothing
+     * but this comment and the test beside it stands between here and that behaviour.
+     */
+    getReconcileScheduler: () => {
+        noteRefusal: (ownerAgentId: string, peerAgentId: string, terminal: boolean) => void;
+    } | undefined;
+    notificationDispatcher: NotificationDispatcher;
+    /** ONE other handler, not the map it lives in. */
+    getCloseSessionHandler: () => IpcHandler | undefined;
+}
+export declare function createDocumentWiring(deps: DocumentWiringDeps): {
+    documentLayer: import("./document-layer.js").DocumentLayer;
+    documentOwnerKeyFor: (agentName: string) => string | null;
+    documentTransportFor: (agentName: string) => import("./document-delivery-transport.js").DocumentDeliveryTransport;
+};
+//# sourceMappingURL=document-wiring.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"document-wiring.d.ts","sourceRoot":"","sources":["../src/document-wiring.ts"],"names":[],"mappings":"AAyBA,OAAO,EAA6B,KAAK,qBAAqB,EAAE,MAAM,yBAAyB,CAAC;AAChG,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAClD,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,2BAA2B,CAAC;AACpE,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,YAAY,CAAC;AACzC,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AACrD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,wBAAwB,CAAC;AAC1D,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,2BAA2B,CAAC;AAClE,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,8BAA8B,CAAC;AAC3E,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,6BAA6B,CAAC;AAEpE,MAAM,WAAW,kBAAkB;IACjC,MAAM,EAAE,MAAM,CAAC;IACf,kBAAkB,EAAE,kBAAkB,CAAC;IACvC,uGAAuG;IACvG,YAAY,EAAE,aAAa,CAAC,WAAW,CAAC,CAAC;IACzC,YAAY,EAAE,GAAG,CAAC,MAAM,EAAE,WAAW,CAAC,CAAC;IACvC,wDAAwD;IACxD,eAAe,EAAE,qBAAqB,CAAC;IACvC,gEAAgE;IAChE,QAAQ,EAAE,MAAM,CAAC;IACjB,aAAa,EAAE;QAAE,KAAK,EAAE,CAAC,YAAY,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,KAAK,MAAM,IAAI,CAAA;KAAE,CAAC;IACrF,aAAa,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,MAAM,CAAC;IACxC,cAAc,EAAE,CAAC,SAAS,EAAE,MAAM,EAAE,IAAI,EAAE;QAAE,YAAY,EAAE,MAAM,CAAA;KAAE,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;IACxF,iBAAiB,EAAE,GAAG,CAAC,MAAM,EAAE;QAAE,SAAS,EAAE,gBAAgB,CAAA;KAAE,CAAC,CAAC;IAChE,kBAAkB,EAAE,CAClB,SAAS,EAAE,gBAAgB,EAC3B,SAAS,EAAE,MAAM,EACjB,SAAS,EAAE,MAAM,EACjB,aAAa,EAAE,MAAM,KAClB,OAAO,CAAC,gBAAgB,CAAC,CAAC;IAC/B;;;;;;;;;OASG;IACH,qBAAqB,EAAE,MAAM;QAAE,WAAW,EAAE,CAAC,YAAY,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,EAAE,QAAQ,EAAE,OAAO,KAAK,IAAI,CAAA;KAAE,GAAG,SAAS,CAAC;IACjI,sBAAsB,EAAE,sBAAsB,CAAC;IAC/C,kDAAkD;IAClD,sBAAsB,EAAE,MAAM,UAAU,GAAG,SAAS,CAAC;CACtD;AAED,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,kBAAkB;;qCAuBnB,MAAM,KAAG,MAAM,GAAG,IAAI;sCAgJrB,MAAM;EAqJhD"}

package/dist/document-wiring.js

@@ -0,0 +1,323 @@
+/**
+ * The document layer, and the per-agent carrier that moves its frames.
+ *
+ * Built as ONE thing on purpose — every half-wiring is a distinct silent failure. An inbound path
+ * with no ack producer leaves the peer retrying until their document dies; a delivery worker with no
+ * inbound counterpart publishes envelopes nobody can answer. So this module returns the layer, the
+ * owner-key resolver and the transport factory together, or it returns nothing.
+ *
+ * ⚠️ FOURTEEN DEPENDENCIES, TWO OVER THE ORDER'S BOUND, RECORDED RATHER THAN HIDDEN — and the same
+ * answer as `signal-handlers.ts`. The seam a reader will look for is "inbound layer" versus
+ * "delivery transport", and it is not there: both need the session manager, the logger, the signing
+ * keys and the agent registry, so splitting produces two contexts of ten that share eight members.
+ * The order's own rule is that two modules needing the same values are one module.
+ *
+ * ⚠️ THREE VALUES WERE NARROWED ON THE WAY OUT, and each replaced a reach for something wider.
+ * `config.securityGateway` and `config.celloDir` became the two values themselves, so this module
+ * cannot read the rest of the daemon's configuration; and the handler map became
+ * `getCloseSessionHandler`, because the delivery path calls exactly one other handler and holding
+ * the whole map would let it call — or replace — any of them.
+ */
+import { join } from "node:path";
+import { randomUUID } from "node:crypto";
+import { createDocumentLayer, agentPublicKeyFromId } from "./document-layer.js";
+import { isDocumentFrame } from "./document-frame-router.js";
+import { createDocumentDeliveryTransport } from "./document-delivery-transport.js";
+import { INBOUND_INJECTION_BLOCKED } from "@cello-protocol/gateway";
+export function createDocumentWiring(deps) {
+    const { logger, sessionNodeManager, loadedAgents, keyProviders, securityGateway, celloDir, deliveryOpens, pubkeyOfAgent, openSessionFor, perAgentSignaling, runDiscoveryLookup, getReconcileScheduler, notificationDispatcher, getCloseSessionHandler, } = deps;
+    // M14 / DOD-DOC-INBOUND-2: the document layer, wired to the session content path.
+    //
+    // Built as ONE thing (see `document-layer.ts`): every half-wiring is a distinct silent failure —
+    // an inbound path with no ack producer leaves the peer retrying until their document stalls, a
+    // delivery worker with no inbound counterpart publishes envelopes nobody can answer.
+    //
+    // It shares the daemon's SQLCipher handle rather than opening its own. One encrypted database,
+    // one key, one file to back up — and a second opener is a second thing that has to agree about
+    // the key, which is how a store ends up plaintext.
+    // THE owner key. One function, used by the inbound router and the delivery sweep alike, because
+    // the two halves scoping differently is a silent-empty-query bug rather than a visible one.
+    //
+    // Reads `loadedAgents`, which is the live registry — `cello_create_agent` pushes into it at
+    // runtime — rather than the boot-time snapshot, so an agent registered after startup resolves
+    // without a restart. Lower-cased because the store compares owner keys as strings and a peer's
+    // id arrives off the wire in whatever case they sent.
+    const documentOwnerKeyFor = (agentName) => loadedAgents.find((a) => a.name === agentName)?.pubkey?.toLowerCase() ?? null;
+    const documentLayer = createDocumentLayer({
+        db: sessionNodeManager.getDb(),
+        logger,
+        // DOD-DOC-SCREEN-CONTENT-1 — the gateway, reached with TEXT for once.
+        //
+        // The same program that screens conversation messages, called from the document gate's shadow
+        // with the readable projected text instead of the signed binary envelope the wire carries.
+        //
+        // ── WHICH VERDICTS REFUSE, AND WHY IT IS NOT "ALL OF THEM" ────────────────────────────────
+        //
+        // ONLY the injection verdict. The gateway runs its whole inbound composition, and two of its
+        // other terminal blocks must not refuse a document:
+        //
+        //   - the LANGUAGE ALLOWLIST (default: Latin only). A shared document written in Japanese,
+        //     Arabic or Russian is ordinary use, and every update would be refused — permanently, since
+        //     the same bytes are the same language on redelivery. The allowlist exists so a jailbreak
+        //     phrased in a low-resource language cannot dodge English-trained screening; refusing a
+        //     colleague's document outright is a far worse trade than that gap, and the character
+        //     denylist still runs on every script.
+        //   - the SIZE CAP, which is the sanitizer's per-message cap and not this path's limit. The
+        //     gate already bounds an update and the whole document by its own numbers.
+        //
+        // A REDACT verdict is never honoured: rewriting one holder's replica is permanent divergence
+        // both sides converge on and neither can see.
+        //
+        // A TRANSIENT block means the gateway is DOWN or its screener faulted. The update is admitted —
+        // holding document convergence hostage to an optional layer breaks a layer that degrades by
+        // design — but it is LOGGED BY NAME, because a weaker guarantee that looks identical to the
+        // stronger one at every surface is how this whole class of defect survives.
+        screenProjected: async (text, ctx) => {
+            const verdict = await securityGateway.screenInbound(new TextEncoder().encode(text), {
+                direction: "inbound",
+                agentName: ctx.ownerAgentId,
+                sessionId: ctx.documentId,
+                ...(ctx.correlationId !== undefined ? { correlationId: ctx.correlationId } : {}),
+            });
+            if (verdict.disposition !== "block")
+                return { block: false };
+            if (verdict.terminal !== true) {
+                logger.warn("document.inbound.screen.unavailable", {
+                    documentId: ctx.documentId,
+                    senderAgentId: ctx.senderAgentId,
+                    reason: verdict.reason,
+                    consequence: "the update was admitted WITHOUT a semantic screen",
+                    correlationId: ctx.correlationId,
+                });
+                return { block: false };
+            }
+            if (verdict.reason !== INBOUND_INJECTION_BLOCKED) {
+                logger.info("document.inbound.screen.not_applicable", {
+                    documentId: ctx.documentId,
+                    senderAgentId: ctx.senderAgentId,
+                    reason: verdict.reason,
+                    consequence: "a terminal block this path does not apply to documents — admitted",
+                    correlationId: ctx.correlationId,
+                });
+                return { block: false };
+            }
+            return { block: true, reason: verdict.reason };
+        },
+        // M14-D5: a remote agent's id IS its K_local pubkey hex, so this needs no lookup — and a lookup
+        // on the critical path of every signature check is precisely what it must not have.
+        publicKeyFor: agentPublicKeyFromId,
+        ownerKeyFor: documentOwnerKeyFor,
+        // Documents materialize as files under the operator's CELLO_DIR, alongside the database that
+        // is their source of truth. Not the current working directory: a daemon serves many agents and
+        // outlives any shell, so a relative root would scatter one operator's documents across
+        // wherever they happened to launch it from.
+        workspaceRoot: join(celloDir, "documents"),
+        // The ack's road to the peer — the same open-or-reuse-then-seal path every other document frame
+        // takes. Resolved from the owner KEY back to the agent name, because the transport is per agent.
+        sendFrame: async (ownerAgentId, peerAgentId, bytes, leafKind) => {
+            const agentName = loadedAgents.find((a) => a.pubkey?.toLowerCase() === ownerAgentId)?.name;
+            if (!agentName)
+                return { ok: false, reason: "document_ack_no_agent" };
+            const sent = await documentTransportFor(agentName).sendBytes({
+                peerAgentId,
+                documentId: "ack",
+                bytes,
+                correlationId: randomUUID(),
+                ...(leafKind === undefined ? {} : { leafKind }),
+            });
+            return sent.ok ? { ok: true } : { ok: false, reason: sent.reason };
+        },
+        // Read LAZILY: the scheduler is constructed after this layer (it consumes the layer's sweep
+        // targets), so the binding must be resolved at call time rather than captured here.
+        onPeerRefusal: (ownerAgentId, peerAgentId, terminal) => getReconcileScheduler()?.noteRefusal(ownerAgentId, peerAgentId, terminal),
+        // ONE implementation, shared with the two-party test. It was a closure here, and that is exactly
+        // how the surface tests passed while the feature did nothing: the test wired this seam to
+        // `async () => ({ ok: true })`, which reported success, sent nothing, and agreed with whatever
+        // the near side did.
+        // DOD-DOC-WATCH-1 — the ONLY doorbell a document update can ring, and only for an agent that
+        // asked for it by naming the paths. §11.3's no-doorbell-on-update rule is otherwise untouched.
+        nudge: (ownerAgentId, documentId, paths) => {
+            const agentName = loadedAgents.find((a) => a.pubkey?.toLowerCase() === ownerAgentId)?.name;
+            if (!agentName)
+                return;
+            notificationDispatcher.dispatchDocumentWatch(agentName, documentId, paths);
+        },
+        sign: async (ownerAgentId, tbs) => {
+            // Signs as the OWNING agent, over the rejection's canonical preimage (DOD-DOC-REJECT-2).
+            //
+            // `ownerAgentId` here is the OWNER KEY — pubkey hex — because that is what the layer is
+            // scoped by, and `keyProviders` is keyed by agent NAME. This did `keyProviders.get(ownerAgentId)`
+            // and the comment above it asserted the two were the same thing. They are not: the lookup
+            // missed on every call, so every auto-rejection threw `document_rejection_unsigned` and NO
+            // rejection was ever signed or sent. A peer whose update we refused was never told why —
+            // their sender retried into a gate that would refuse it every time, until the document
+            // stalled for a reason neither operator could see.
+            //
+            // Invisible to every test: the unit and e2e fixtures alike wire `sign: (_o, tbs) => keys.sign(tbs)`,
+            // discarding the agent argument, so nothing could disagree about which key was resolved.
+            const agentName = loadedAgents.find((a) => a.pubkey?.toLowerCase() === ownerAgentId)?.name;
+            const provider = agentName ? keyProviders.get(agentName) : undefined;
+            if (!provider) {
+                // Still throws rather than substituting another agent's key — an earlier version took no
+                // agent at all and reached for whichever provider was first in the map, which is fabricated
+                // crypto wearing a real signature.
+                throw new Error(`document_rejection_unsigned: no key provider for owner ${ownerAgentId.slice(0, 16)}…, ` +
+                    `so its rejection cannot be signed — refusing rather than writing an unsigned leaf ` +
+                    `into an append-only log`);
+            }
+            return provider.sign(tbs);
+        },
+    });
+    // The classify-only half rides the same setter so the router and the ingest cannot disagree
+    // about what a document frame is (DOD-DOC-SCREEN-CLASSIFY-1).
+    sessionNodeManager.setOnDocumentFrame(documentLayer.onDocumentFrame, isDocumentFrame);
+    // M14 / DOD-DOC-DELIVERY-2 — the outbound half, wired only now that INBOUND-2 is. The ordering
+    // constraint on the DoD line is real and this is where it is honoured: a delivery worker with no
+    // inbound counterpart publishes envelopes nobody can answer, so every document would stall at the
+    // unacked ceiling.
+    //
+    // PER AGENT, because every capability below is: the signaling stream is authenticated as one
+    // agent, sessions belong to one agent, and `openSessionFor` signs as one agent. A single worker
+    // with an agent-shaped hole in it is how a delivery ends up sent under the wrong identity.
+    //
+    // The frame carrier, cached per agent (SYNC-P4: the delivery worker and its sweep are deleted —
+    // scheduling returns as the P5 reconcile triggers).
+    const documentTransports = new Map();
+    const documentTransportFor = (agentName) => {
+        const cached = documentTransports.get(agentName);
+        if (cached)
+            return cached;
+        const transport = createDocumentDeliveryTransport({
+            agentName,
+            logger,
+            // The SAME 3-state discovery answer cello_initiate_session uses, from the same closure —
+            // online / offline / unknown_agent, kept distinct from "the lookup itself failed". A second
+            // implementation of that distinction drifts until one of them reports a directory outage as
+            // the peer being offline.
+            lookupPeer: async (peerAgentId, correlationId) => {
+                const entry = perAgentSignaling.get(agentName);
+                if (!entry) {
+                    // Our OWN stream is not up. A transport fault, never the peer being away — the
+                    // reachability mapper turns this into a throw, which the worker logs as lookup_failed.
+                    return { kind: "send_failed", reason: "signaling_unavailable" };
+                }
+                return runDiscoveryLookup(entry.signaling, peerAgentId, 10_000, correlationId);
+            },
+            // Most recent LAST — §16.4 reuses the most recent active session, and getSessionsForAgent
+            // returns newest first.
+            activeSessionsWith: (agent, peerAgentId) => sessionNodeManager
+                .getSessionsForAgent(agent)
+                .filter((row) => row.status === "active" && row.counterparty_pubkey === peerAgentId)
+                .map((row) => row.session_id)
+                .reverse(),
+            openSession: async (agent, peerAgentId, correlationId) => {
+                // DOD-M12B-DELIVERY-QUIET-1: THIS is the only place the delivery worker opens a session,
+                // so bracketing it is what makes "who opened this" knowable everywhere else. The window
+                // must cover the whole open — the inbound doorbell on a co-resident pair fires DURING
+                // negotiation, and the initiator-side reachability hook fires just before this returns.
+                // Released in `finally`: a throw that left the intent registered would silence this
+                // peer's doorbell for the life of the process, which is a worse outage than the storm.
+                const releaseDeliveryOpen = deliveryOpens.begin(pubkeyOfAgent(agent), peerAgentId);
+                try {
+                    // The same path `cello_initiate_session` takes, now callable without an IPC connection.
+                    const res = (await openSessionFor(agent, { targetPubkey: peerAgentId }));
+                    if (res.ok !== true || typeof res.sessionId !== "string") {
+                        return { ok: false, reason: res.reason ?? "session_open_failed", guidance: res.guidance };
+                    }
+                    logger.info("document.delivery.session_opened", { agent, peerAgentId, sessionId: res.sessionId, correlationId });
+                    return { ok: true, sessionId: res.sessionId };
+                }
+                finally {
+                    releaseDeliveryOpen();
+                }
+            },
+            sealSession: async (agent, sessionId, correlationId) => {
+                // §16.4: the autonomous session still carries the seal — the ceremony goes to zero, the
+                // seal does not. Only ever called for a session this worker OPENED; one it reused belongs
+                // to whoever started that conversation.
+                const close = getCloseSessionHandler();
+                if (!close) {
+                    // Reported, not swallowed. The outcome of a missing handler is a live session node the
+                    // operator never started, with no sealed record — the exact thing the seal exists to
+                    // prevent, and previously indistinguishable from a clean seal.
+                    logger.error("document.delivery.seal_failed", { agent, sessionId, reason: "close_handler_missing", correlationId });
+                    return;
+                }
+                /**
+                 * `wait_for_seal: true` — DOD-M15-CLOSEWAIT-1 review MEDIUM-5.
+                 *
+                 * This is NOT an IPC caller. It is an in-process worker awaiting the close for a session
+                 * it opened itself, and the `ok !== true` check below is the only thing that ever reports
+                 * a failed document-delivery seal. The new default answers `ok: true` at COMMITMENT, so
+                 * without this flag that check could never fire for a ceremony failure again — §16.4's
+                 * "the autonomous session still carries the seal" would rest on a detached task nobody
+                 * awaited, retried or reported on.
+                 *
+                 * The whole point of answering early is that a human is watching a terminal. Nobody is
+                 * watching this one, so it takes the blocking form — which also stops each delivery
+                 * leaving a detached ceremony holding a visiting connection for up to eleven minutes,
+                 * overlapping instead of serialising.
+                 */
+                const sealed = (await close({ session_id: sessionId, agent, wait_for_seal: true }, `doc-delivery-${correlationId}`));
+                if (sealed?.ok !== true) {
+                    // `cello_close_session` has distinct failure codes — session_already_sealed,
+                    // seal_interrupted_*, signaling_reconnecting — and every one of them landed nowhere.
+                    logger.warn("document.delivery.seal_failed", { agent, sessionId, reason: sealed?.reason ?? "unknown", correlationId });
+                }
+            },
+            // `leafKind` IS LOAD-BEARING AND MUST BE FORWARDED. This adapter took five parameters and
+            // dropped the sixth, which TypeScript accepts without a word — a function of lower arity is
+            // assignable to one of higher arity, and the dep declares `leafKind?: number`. So the
+            // transport asked for 0x04, the composition root threw it away, and every document leaf
+            // still reached the relay as a MESSAGE. Verified on live traffic: daemon 0.0.145 shipped
+            // the fix everywhere except here and the wire was unchanged.
+            //
+            // ⚠️ AND `contentHashAlg` IS THE SECOND PARAMETER THIS ADAPTER MUST NOT DROP. The note above
+            // is about `leafKind`, which this wrapper silently swallowed while every other caller passed
+            // it — a thin pass-through is exactly where a new argument goes missing, because nothing
+            // about the call site looks wrong afterwards. B2b's failure mode if it happens again: the
+            // document path sends a salted hash labelled `sha256`, and every peer refuses it.
+            sendContent: (agent, sessionId, content, contentHash, correlationId, leafKind, contentHashAlg) => sessionNodeManager.sendContent(agent, sessionId, content, contentHash, correlationId, leafKind, contentHashAlg),
+            contentHashForSession: (agent, sessionId, content) => sessionNodeManager.contentHashForSession(agent, sessionId, content),
+            // The `0x04` doc leaf for a frame WE sent — the same step `cello_send` takes after its own
+            // successful send. See the comment at the call site for why this is delivery-critical and
+            // not audit bookkeeping.
+            appendLeaf: (agent, sessionId, contentHash, frameBytes, correlationId, assignedSeq) => {
+                // DOD-M12B-INDEX-1: a document leaf takes a position in the CONVERSATION's sequence space
+                // (deliberate — f75ea09), so it obeys the same discipline a message does — including
+                // being HELD when the position is ahead of the tail, which is why the real frame bytes
+                // have to travel with it.
+                const placed = sessionNodeManager.placeOwnLeaf(agent, sessionId, Buffer.from(contentHash).toString("hex"), frameBytes, assignedSeq, correlationId, "doc", 
+                /**
+                 * No proof — and the reason I first wrote here was FALSE, which review traced rather
+                 * than read.
+                 *
+                 * ⚠️ IT SAID *"the document transport does not go through `sendContent`, so no Structure-1
+                 * was signed."* Both halves are wrong. `document-delivery-transport.ts` calls
+                 * `deps.sendContent(...)`, wired straight to `sessionNodeManager.sendContent` a few lines
+                 * above this; and `session-relay-client.ts` signs the Structure-1 with no `leafKind` gate
+                 * at all, so a `0x04` doc leaf is signed exactly like a message. **A proof exists and is
+                 * discarded here.**
+                 *
+                 * That matters more than a wrong comment usually would, because this unit's whole thesis
+                 * is *"`undefined` is a claim the author made rather than one the signature made for
+                 * them"* — and the first claim made under the new signature was untrue.
+                 *
+                 * THE TRUE REASON, which is a better one: **no consumer.** A doc leaf released from a
+                 * hold writes no transcript row — `#releaseHeld` skips `recordTranscriptMessage` for
+                 * `kind === "doc"` — so there is nothing for the proof to reach. Discarding it is
+                 * no-consumer-no-ship, deliberately.
+                 *
+                 * **If doc rows ever reach the transcript, `appendLeaf` needs an authorship parameter**
+                 * and this `undefined` becomes a defect rather than a decision.
+                 */
+                undefined);
+                return { placed: placed.placed, leafIndex: placed.placed ? placed.leafIndex : null };
+            },
+        });
+        documentTransports.set(agentName, transport);
+        return transport;
+    };
+    return { documentLayer, documentOwnerKeyFor, documentTransportFor };
+}
+//# sourceMappingURL=document-wiring.js.map

package/dist/document-wiring.js.map

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

package/dist/document-write-guard.d.ts

@@ -0,0 +1,66 @@
+/**
+ * DOD-DOC-STALE-WRITE-1 — telling an accidental deletion apart from a deliberate one.
+ *
+ * ── WHY THIS EXISTS ──────────────────────────────────────────────────────────────────────────────
+ *
+ * `cello_doc_write` takes the COMPLETE text, so anything absent from what you send is a deletion.
+ * That contract is deliberate and correct — a patch API means stale offsets, which in a CRDT is
+ * permanent corruption both sides converge on. What it cannot express is the difference between:
+ *
+ *   - *"I read their paragraph and I do not want it"* — a real editorial act, and
+ *   - *"their paragraph arrived while I was typing and I have never seen it"* — an accident.
+ *
+ * Both are the same bytes on the wire. Measured live on 2026-08-09 between two machines: a peer's
+ * paragraph was admitted at 12:35:41.807 and destroyed by a write published at 12:35:42.033. A 226ms
+ * window, hit on the first two-machine test anyone ran.
+ *
+ * **The lost text is the smaller harm.** The signed record cannot tell the two apart either, so an
+ * accident is permanently attributed to you as a deliberate rejection of your counterparty's work —
+ * in the one system whose selling point is that the trail cannot be disputed later.
+ *
+ * ── WHAT MAKES THE DISTINCTION AVAILABLE ─────────────────────────────────────────────────────────
+ *
+ * The read mark (`document_read_marks.seen_text`) stores the exact text you last read, durably. So
+ * the question "could you have seen this?" is answerable without asking you.
+ *
+ * ── THE RULE ─────────────────────────────────────────────────────────────────────────────────────
+ *
+ * **Refusal is conditioned on REMOVAL in every branch.** A write that only adds is never refused,
+ * whatever the read mark says — otherwise proposing a document and writing to it before reading it
+ * would be refused for no safety benefit.
+ *
+ * Given a removal: seen it → allowed, and recorded as deliberate. Not seen it (or no read mark at
+ * all) → refused, with what changed handed back.
+ *
+ * ── WHY LINES ────────────────────────────────────────────────────────────────────────────────────
+ *
+ * Both document roots project to canonical text — JSON through the deterministic serialiser, which
+ * sorts keys at every depth — so a removed key IS a removed line. One implementation covers both.
+ *
+ * Counted, not set-matched: a document with two identical lines that loses one has genuinely lost a
+ * line, and set logic would report nothing removed.
+ */
+/** What a proposed write would take out of the document, split by whether the author could have seen it. */
+export interface RemovalVerdict {
+    /** Every line the write removes, seen or not. */
+    readonly removed: readonly string[];
+    /** Removed lines that were present in the text the author last read — a deliberate act. */
+    readonly deliberate: readonly string[];
+    /** Removed lines the author has no record of having seen — the accident. */
+    readonly unseen: readonly string[];
+    /** Whether the write must be refused. True exactly when `unseen` is non-empty. */
+    readonly refuse: boolean;
+}
+/**
+ * Decide whether `proposed` may replace `current`, given the text the author last read.
+ *
+ * `known` is every text this author demonstrably held — what they last read, what they last wrote,
+ * and what they were given at propose/accept. Empty means nothing is known, and every removal is
+ * treated as an accident.
+ *
+ * Whitespace-only lines are ignored throughout. Reflowing blank lines is not content destruction,
+ * and refusing a write over one would make the guard fire constantly on ordinary editing — a guard
+ * that cries wolf is a guard that gets worked around.
+ */
+export declare function classifyRemovals(current: string, proposed: string, known: readonly string[]): RemovalVerdict;
+//# sourceMappingURL=document-write-guard.d.ts.map

package/dist/document-write-guard.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"document-write-guard.d.ts","sourceRoot":"","sources":["../src/document-write-guard.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyCG;AAEH,4GAA4G;AAC5G,MAAM,WAAW,cAAc;IAC7B,iDAAiD;IACjD,QAAQ,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,CAAC;IACpC,2FAA2F;IAC3F,QAAQ,CAAC,UAAU,EAAE,SAAS,MAAM,EAAE,CAAC;IACvC,4EAA4E;IAC5E,QAAQ,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,CAAC;IACnC,kFAAkF;IAClF,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;CAC1B;AAaD;;;;;;;;;;GAUG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,SAAS,MAAM,EAAE,GAAG,cAAc,CA+B5G"}

package/dist/document-write-guard.js

@@ -0,0 +1,98 @@
+/**
+ * DOD-DOC-STALE-WRITE-1 — telling an accidental deletion apart from a deliberate one.
+ *
+ * ── WHY THIS EXISTS ──────────────────────────────────────────────────────────────────────────────
+ *
+ * `cello_doc_write` takes the COMPLETE text, so anything absent from what you send is a deletion.
+ * That contract is deliberate and correct — a patch API means stale offsets, which in a CRDT is
+ * permanent corruption both sides converge on. What it cannot express is the difference between:
+ *
+ *   - *"I read their paragraph and I do not want it"* — a real editorial act, and
+ *   - *"their paragraph arrived while I was typing and I have never seen it"* — an accident.
+ *
+ * Both are the same bytes on the wire. Measured live on 2026-08-09 between two machines: a peer's
+ * paragraph was admitted at 12:35:41.807 and destroyed by a write published at 12:35:42.033. A 226ms
+ * window, hit on the first two-machine test anyone ran.
+ *
+ * **The lost text is the smaller harm.** The signed record cannot tell the two apart either, so an
+ * accident is permanently attributed to you as a deliberate rejection of your counterparty's work —
+ * in the one system whose selling point is that the trail cannot be disputed later.
+ *
+ * ── WHAT MAKES THE DISTINCTION AVAILABLE ─────────────────────────────────────────────────────────
+ *
+ * The read mark (`document_read_marks.seen_text`) stores the exact text you last read, durably. So
+ * the question "could you have seen this?" is answerable without asking you.
+ *
+ * ── THE RULE ─────────────────────────────────────────────────────────────────────────────────────
+ *
+ * **Refusal is conditioned on REMOVAL in every branch.** A write that only adds is never refused,
+ * whatever the read mark says — otherwise proposing a document and writing to it before reading it
+ * would be refused for no safety benefit.
+ *
+ * Given a removal: seen it → allowed, and recorded as deliberate. Not seen it (or no read mark at
+ * all) → refused, with what changed handed back.
+ *
+ * ── WHY LINES ────────────────────────────────────────────────────────────────────────────────────
+ *
+ * Both document roots project to canonical text — JSON through the deterministic serialiser, which
+ * sorts keys at every depth — so a removed key IS a removed line. One implementation covers both.
+ *
+ * Counted, not set-matched: a document with two identical lines that loses one has genuinely lost a
+ * line, and set logic would report nothing removed.
+ */
+/** Line multiset. Blank and whitespace-only lines are excluded — see `classifyRemovals`. */
+function lineCounts(text) {
+    const counts = new Map();
+    for (const raw of text.split("\n")) {
+        const line = raw.trim();
+        if (line.length === 0)
+            continue;
+        counts.set(line, (counts.get(line) ?? 0) + 1);
+    }
+    return counts;
+}
+/**
+ * Decide whether `proposed` may replace `current`, given the text the author last read.
+ *
+ * `known` is every text this author demonstrably held — what they last read, what they last wrote,
+ * and what they were given at propose/accept. Empty means nothing is known, and every removal is
+ * treated as an accident.
+ *
+ * Whitespace-only lines are ignored throughout. Reflowing blank lines is not content destruction,
+ * and refusing a write over one would make the guard fire constantly on ordinary editing — a guard
+ * that cries wolf is a guard that gets worked around.
+ */
+export function classifyRemovals(current, proposed, known) {
+    const before = lineCounts(current);
+    const after = lineCounts(proposed);
+    // EVERY text this author is known to have held, unioned. There is more than one source and
+    // omitting any of them refuses ordinary work:
+    //   - what they last READ,
+    //   - what they last WROTE (you have obviously seen your own text), and
+    //   - what they were handed when they proposed or accepted the document.
+    // The first version took only the read, and refused every EDIT of an existing line by an author
+    // who had not called read — because changing a line removes the old line's text. Two existing
+    // tests caught it. A guard that fires on ordinary editing is worse than no guard: it gets removed.
+    const seenCounts = new Map();
+    for (const text of known) {
+        for (const [line, n] of lineCounts(text))
+            seenCounts.set(line, Math.max(seenCounts.get(line) ?? 0, n));
+    }
+    const removed = [];
+    const deliberate = [];
+    const unseen = [];
+    for (const [line, count] of before) {
+        const gone = count - (after.get(line) ?? 0);
+        if (gone <= 0)
+            continue;
+        removed.push(line);
+        // Seen ANY occurrence is enough. The author read this text; which copy of a duplicated line they
+        // meant to drop is not something the record can or should adjudicate.
+        if ((seenCounts.get(line) ?? 0) > 0)
+            deliberate.push(line);
+        else
+            unseen.push(line);
+    }
+    return { removed, deliberate, unseen, refuse: unseen.length > 0 };
+}
+//# sourceMappingURL=document-write-guard.js.map

package/dist/document-write-guard.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"document-write-guard.js","sourceRoot":"","sources":["../src/document-write-guard.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyCG;AAcH,4FAA4F;AAC5F,SAAS,UAAU,CAAC,IAAY;IAC9B,MAAM,MAAM,GAAG,IAAI,GAAG,EAAkB,CAAC;IACzC,KAAK,MAAM,GAAG,IAAI,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC;QACnC,MAAM,IAAI,GAAG,GAAG,CAAC,IAAI,EAAE,CAAC;QACxB,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC;YAAE,SAAS;QAChC,MAAM,CAAC,GAAG,CAAC,IAAI,EAAE,CAAC,MAAM,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC;IAChD,CAAC;IACD,OAAO,MAAM,CAAC;AAChB,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,UAAU,gBAAgB,CAAC,OAAe,EAAE,QAAgB,EAAE,KAAwB;IAC1F,MAAM,MAAM,GAAG,UAAU,CAAC,OAAO,CAAC,CAAC;IACnC,MAAM,KAAK,GAAG,UAAU,CAAC,QAAQ,CAAC,CAAC;IACnC,2FAA2F;IAC3F,8CAA8C;IAC9C,2BAA2B;IAC3B,wEAAwE;IACxE,yEAAyE;IACzE,gGAAgG;IAChG,8FAA8F;IAC9F,mGAAmG;IACnG,MAAM,UAAU,GAAG,IAAI,GAAG,EAAkB,CAAC;IAC7C,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QACzB,KAAK,MAAM,CAAC,IAAI,EAAE,CAAC,CAAC,IAAI,UAAU,CAAC,IAAI,CAAC;YAAE,UAAU,CAAC,GAAG,CAAC,IAAI,EAAE,IAAI,CAAC,GAAG,CAAC,UAAU,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC;IACzG,CAAC;IAED,MAAM,OAAO,GAAa,EAAE,CAAC;IAC7B,MAAM,UAAU,GAAa,EAAE,CAAC;IAChC,MAAM,MAAM,GAAa,EAAE,CAAC;IAE5B,KAAK,MAAM,CAAC,IAAI,EAAE,KAAK,CAAC,IAAI,MAAM,EAAE,CAAC;QACnC,MAAM,IAAI,GAAG,KAAK,GAAG,CAAC,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC;QAC5C,IAAI,IAAI,IAAI,CAAC;YAAE,SAAS;QACxB,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QACnB,iGAAiG;QACjG,sEAAsE;QACtE,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC;YAAE,UAAU,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;;YACtD,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IACzB,CAAC;IAED,OAAO,EAAE,OAAO,EAAE,UAAU,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;AACpE,CAAC"}