@cello-protocol/daemon 0.0.167 → 0.0.169

package/dist/document-ack-inbound.js

@@ -1,210 +0,0 @@
-/**
- * DOD-DOC-INBOUND-2 — consuming an arriving ACK. This is what closes DELIVERY-2's loop.
- *
- * Without it a sent envelope's outcome is `admitted: null` forever: the worker knows the content
- * left and nothing more, so it re-sends on the ack timeout and eventually stalls the document at
- * the unacked ceiling.
- *
- * ── EVERY CHECK HERE GUARDS ONE OF TWO IRREVERSIBLE CONSEQUENCES ──────────────────────────────
- *
- * An ack SETTLES an envelope. Admitted, it stops being redelivered; rejected, the sender rolls back
- * local work and supersedes. Both are things an unauthenticated party must not be able to cause, so
- * the order is:
- *
- *   1. DECODE            — refuse malformed input before interpreting any of it.
- *   2. KNOW the document — an ack for a document we do not hold settles nothing that exists.
- *   3. ACKER is the peer — a document is a pairwise agreement; nobody else's answer settles it.
- *   4. VERIFY            — before any write. An unsigned ack that silenced a delivery would drop
- *                          the content from the pending set with neither operator ever learning it
- *                          was never applied — the silent divergence the two-layer design exists to
- *                          prevent.
- *   5. THE ENVELOPE IS OURS — we authored it, and it is in the log. An ack for a peer-authored
- *                          envelope settles a delivery that was never ours to make; an ack for an
- *                          envelope that is not there is a bug or a probe, and recording it would
- *                          put a claim about a nonexistent delivery into a permanent record.
- *   6. SETTLE            — mark acked; on a rejection also record it durably on the publishing side,
- *                          because an operator needs to know WHY their work was refused after a
- *                          restart, not merely that it was.
- */
-import { decodeDocumentAck, buildDocumentAckTbs } from "@cello-protocol/protocol-types";
-export class DocumentAckInbound {
-    #d;
-    constructor(deps) {
-        this.#d = deps;
-    }
-    receive(ownerAgentId, wire, nowMs, correlationId = "ack") {
-        // 1. DECODE.
-        let ack;
-        try {
-            ack = decodeDocumentAck(wire);
-        }
-        catch (err) {
-            const detail = err instanceof Error ? err.message : String(err);
-            this.#d.logger.warn("document.ack.malformed", { detail, correlationId });
-            // One reason code with the upstream message in the detail — the decoder's named refusals and
-            // raw CBOR errors both arrive here, and building a code out of the message turns the second
-            // kind into English prose nothing can match on.
-            return { ok: false, reason: "document_ack_malformed", detail };
-        }
-        // 2. KNOW the document.
-        const doc = this.#d.store.getDocument(ownerAgentId, ack.document_id);
-        if (!doc) {
-            return {
-                ok: false,
-                reason: "document_unknown",
-                detail: `no document ${ack.document_id.slice(0, 16)}… for this agent`,
-            };
-        }
-        // 3. The acker must be a party. When the chain DERIVES, derived membership is the WHOLE
-        // gate — a removed genesis peer's ack refuses like any outsider's (review H2). Only when the
-        // chain cannot answer (bilateral legacy, no genesis record) does the genesis-peer column
-        // stand in.
-        const holders = this.#d.currentHolders(ownerAgentId, ack.document_id);
-        const isParty = holders === null
-            ? ack.acker_agent_id === doc.peerAgentId
-            : holders.includes(ack.acker_agent_id);
-        if (!isParty) {
-            this.#d.logger.warn("document.ack.not_peer", {
-                documentId: ack.document_id,
-                ackerAgentId: ack.acker_agent_id,
-                peerAgentId: doc.peerAgentId,
-                correlationId,
-            });
-            return {
-                ok: false,
-                reason: "document_ack_not_peer",
-                // The peer's identity is not disclosed to a party that has not authenticated.
-                detail: "you are not a party to this document",
-            };
-        }
-        // 4. VERIFY, before any write.
-        if (!this.#d.verifySignature(ack.acker_agent_id, buildDocumentAckTbs(ack), ack.signature)) {
-            this.#d.logger.error("document.ack.signature_invalid", {
-                documentId: ack.document_id,
-                ackerAgentId: ack.acker_agent_id,
-                envelopeHash: ack.envelope_hash,
-                correlationId,
-            });
-            return {
-                ok: false,
-                reason: "document_ack_signature_invalid",
-                detail: `the ack claims to come from ${ack.acker_agent_id} but its signature does not verify ` +
-                    `against that agent — nothing was settled`,
-            };
-        }
-        // 5. The envelope must be one WE authored, and it must exist.
-        const row = this.#d.store
-            .getEnvelopeLog(ownerAgentId, ack.document_id)
-            .find((e) => e.envelopeHash === ack.envelope_hash);
-        if (!row) {
-            return {
-                ok: false,
-                reason: "document_ack_envelope_unknown",
-                detail: `envelope ${ack.envelope_hash.slice(0, 16)}… is not in this document's log`,
-            };
-        }
-        if (row.senderAgentId !== ownerAgentId) {
-            return {
-                ok: false,
-                reason: "document_ack_not_author",
-                detail: `envelope ${ack.envelope_hash.slice(0, 16)}… was authored by ${row.senderAgentId}, not by ` +
-                    `you — there is no delivery of ours for this ack to settle`,
-            };
-        }
-        // 6. SETTLE ONCE. The wire type's own header states this contract: nothing binds an ack to the
-        // acker's chain, so one acker can produce a valid ADMISSION and a valid REJECTION for the same
-        // envelope. Applying the later one would let a peer that admitted an envelope later claim it
-        // refused it — and the sender would roll back work the peer already holds. A second,
-        // CONTRADICTING ack is an error; a second identical one is an ordinary redelivery.
-        // SETTLE-ONCE, PER ACKER (review M4). The envelope-level column stays null until ALL
-        // holders answer, so an envelope-scoped check let a holder that ADMITTED later send a
-        // REJECTION mid-fan-out — processed, rounds advanced, work rolled back that they already
-        // hold. The acker's own per-holder row is the record; the envelope-level check remains only
-        // for the zero-row bilateral legacy.
-        const holderPrior = this.#d.store.holderSettlement(ownerAgentId, ack.envelope_hash, ack.acker_agent_id);
-        const alreadyAcked = holderPrior !== null || row.ackedAtMs != null;
-        if (alreadyAcked) {
-            // ENVELOPE-scoped. The document-scoped reader answers a different question, and using it
-            // here would make a rejection of any OTHER envelope in this document read as a rejection of
-            // this one — so an honest redelivered admission would be refused as a contradiction the
-            // moment anything else in the document had ever been refused.
-            const previouslyRejected = holderPrior !== null
-                ? !holderPrior.admitted
-                : this.#d.store.rejectionReceivedFor(ownerAgentId, ack.document_id, ack.envelope_hash);
-            const contradicts = ack.admitted === previouslyRejected;
-            if (contradicts) {
-                this.#d.logger.error("document.ack.contradiction", {
-                    documentId: ack.document_id,
-                    envelopeHash: ack.envelope_hash,
-                    ackerAgentId: ack.acker_agent_id,
-                    nowSays: ack.admitted ? "admitted" : "rejected",
-                    correlationId,
-                });
-                return {
-                    ok: false,
-                    reason: "document_ack_contradiction",
-                    detail: `${ack.acker_agent_id} already settled envelope ${ack.envelope_hash.slice(0, 16)}… and ` +
-                        `now says the opposite — this envelope stays settled as it was, and both claims are ` +
-                        `retained`,
-                };
-            }
-            // An identical redelivery. Nothing to do, and nothing to complain about.
-            return { ok: true, admitted: ack.admitted, envelopeHash: ack.envelope_hash };
-        }
-        // FANOUT-1: the ACKING HOLDER settles THEIR row; the envelope-level record follows the ONE
-        // deterministic terminal rule (`reconcileEnvelopeSettlement` — review M3), identical from
-        // every reconciliation site. Bilateral legacy (zero rows) stays byte-identical: the
-        // reconcile no-ops and markAcked below still runs through it.
-        this.#d.store.ackHolderDelivery(ownerAgentId, ack.document_id, ack.envelope_hash, ack.acker_agent_id, nowMs);
-        const before = row.ackedAtMs != null;
-        this.#d.store.reconcileEnvelopeSettlement(ownerAgentId, ack.document_id, ack.envelope_hash, nowMs);
-        const legacy = this.#d.store.holderSettlement(ownerAgentId, ack.envelope_hash, ack.acker_agent_id) === null;
-        const first = legacy
-            ? this.#d.store.markAcked(ownerAgentId, ack.document_id, ack.envelope_hash, nowMs)
-            : !before;
-        // ANNOUNCE THE SETTLE, before the admitted/rejected split — both outcomes end the delivery, and
-        // a waiter that only heard about admissions would keep a session open through every rejection.
-        this.#d.onSettled?.(ownerAgentId, ack.envelope_hash, ack.acker_agent_id, ack.admitted);
-        if (!ack.admitted) {
-            // Durable on the publishing side. A log line would not survive the restart after which the
-            // operator asks why their work never landed — and this is also what bounds the retry on the
-            // side that actually loops.
-            this.#d.rejections.recordIncomingRejection(ownerAgentId, ack.document_id, {
-                rejectionEnvelopeHash: ackRecordHash(ack.envelope_hash),
-                rejectedEnvelopeHash: ack.envelope_hash,
-                reason: ack.rejection_reason ?? "document_rejected",
-                fromAgentId: ack.acker_agent_id,
-            });
-            return { ok: true, admitted: false, envelopeHash: ack.envelope_hash };
-        }
-        this.#d.logger.info("document.ack.admitted", {
-            documentId: ack.document_id,
-            envelopeHash: ack.envelope_hash,
-            firstAck: first,
-            correlationId,
-        });
-        return { ok: true, admitted: true, envelopeHash: ack.envelope_hash };
-    }
-}
-/**
- * The identity of the RECEIVED-rejection row: the REFUSED ENVELOPE, and nothing else.
- *
- * ONE REFUSED ENVELOPE IS ONE ROUND, however many acks for it arrive.
- *
- * This used to mix in the acker's `acked_at_ms` on the reasoning that both fields are signed, so a
- * redelivered ack would collapse onto the same row. That reasoning had a false premise: acks are
- * not stored and redelivered — `sendAck` builds a fresh `DocumentAck` with `acked_at_ms: Date.now()`
- * every time it answers. So two acks for the SAME envelope carried two different timestamps and
- * became two rows, advancing the round twice.
- *
- * That is not hypothetical. Delivery re-sends on a 1s first backoff, so an ordinary in-flight
- * overlap — the sender re-sends while the first ack is still on the wire, both land — produced two
- * rounds from one refusal. `MAX_REJECTED_ROUNDS` is 3, so routine delivery overlap could stall a
- * shared document with no hostility involved. That is the same denial of service the 5b
- * already-rejected guard in `document-inbound.ts` was written to close, arriving through the other
- * side of the same loop.
- */
-function ackRecordHash(envelopeHash) {
-    return envelopeHash;
-}
-//# sourceMappingURL=document-ack-inbound.js.map

package/dist/document-ack-inbound.js.map

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

package/dist/document-control-notifier.d.ts

@@ -1,107 +0,0 @@
-/**
- * DOD-DOC-TOOLS-1 — telling the peer a document has ended.
- *
- * `DocumentLifecycle` ends a document locally without asking anyone, deliberately: a kill is a
- * safety verb, and a safety verb that needs the counterparty's cooperation is not one. But a peer
- * who is never told keeps publishing into a document that will never answer — their updates refused
- * at the far end forever, with nothing on their screen explaining why. So the notification is
- * REQUIRED to be attempted, ALLOWED to fail, and the operator is told which happened.
- *
- * ── WHY THIS IS A MODULE AND NOT A CLOSURE IN THE COMPOSITION ROOT ────────────────────────────
- *
- * It was one, and that is precisely how the surface tests passed while the feature did nothing.
- * `createDocumentLayer` takes `notifyPeer` as an injected seam, so the two-party test wired it to
- * `async () => ({ ok: true })` — which reported success, sent nothing, and agreed with whatever the
- * near side did. Kill "worked" on both sides of the assertion and on neither side of the wire.
- *
- * That is the same shape as the two defects the DELIVERY-2 review found: a stub on the far side
- * cannot disagree with you. So the construction lives here, and both the daemon and the test build
- * it from this function — the test can still substitute the TRANSPORT, which is the part that has
- * to be substituted, without also substituting the logic under test.
- *
- * ── WHY THE DOCUMENT IS FOUND BY SCANNING ─────────────────────────────────────────────────────
- *
- * `notifyPeer`'s signature carries no owner: lifecycle calls it knowing only the document id, and
- * widening that interface would push a multi-agent daemon concern into a unit that deliberately has
- * none. So the owner is resolved here, by asking each agent this daemon holds whether the document
- * is theirs. A document id is a hash committing to both parties and a nonce, so at most one agent
- * can answer.
- *
- * ── DOD-MP-CONTROL-N-1 — WHY THE TARGET IS DERIVED, NOT `peerAgentId` ─────────────────────────
- *
- * This addressed `doc.peerAgentId` and returned after one send. That column is the GENESIS
- * counterparty, frozen at creation, and multiplayer made it wrong in two ways at once: with three
- * holders only one was told, and after a removal the genesis counterparty can BE the removed
- * holder — so the frame went to the one party it must not reach while the remaining co-author was
- * never told, under a reported `peerNotified: true`. Found by the M14B live fleet smoke.
- *
- * The target is now the DERIVED participant set, the same source FANOUT-1 established for update
- * envelopes; control frames were simply never migrated to it. Deriving needs the genesis proposal,
- * the amendment chain and signature verification — all of which live above this module, so it
- * arrives as an injected `holders()` rather than by widening this unit into the replay engine.
- *
- * A derivation failure REFUSES. It must never fall back to `peerAgentId`: that is the old bug, and
- * it aims the frame at exactly the wrong party in the case that motivated the change.
- */
-import { type DocumentControlVerb } from "@cello-protocol/protocol-types";
-import type { DocumentStore } from "./document-store.js";
-export interface DocumentControlNotifierDeps {
-    store: DocumentStore;
-    /** The agents this daemon holds — name for signing and sending, owner key for scoping the store. */
-    owners(): ReadonlyArray<{
-        agentName: string;
-        ownerAgentId: string;
-    }>;
-    /**
-     * The CURRENT holders of this document OTHER than the owner, derived from the genesis proposal
-     * plus the amendment chain — the same set that governs update delivery. A failure to derive is
-     * returned, not swallowed: this unit refuses rather than guessing a recipient.
-     */
-    holders(ownerAgentId: string, documentId: string): {
-        ok: true;
-        holders: readonly string[];
-    } | {
-        ok: false;
-        reason: string;
-    };
-    /** Sign as the named agent. A miss must REFUSE, not substitute another agent's key. */
-    sign(agentName: string, tbs: Uint8Array): Promise<Uint8Array>;
-    send(agentName: string, input: {
-        peerAgentId: string;
-        documentId: string;
-        bytes: Uint8Array;
-        correlationId: string;
-    }): Promise<{
-        ok: true;
-    } | {
-        ok: false;
-        reason: string;
-    }>;
-    now(): number;
-    /**
-     * Optional, and only for reporting a LOCAL fault. This module used to swallow the signing error
-     * entirely, so the one description of "your key could not be loaded" existed nowhere — not in the
-     * return value, not in a log line — and the operator was sent to wait for a peer who was already
-     * there.
-     */
-    logger?: {
-        warn(event: string, ctx: Record<string, unknown>): void;
-    };
-}
-export type NotifyPeer = (documentId: string, verb: DocumentControlVerb) => Promise<{
-    ok: true;
-    holdersNotified: Record<string, boolean>;
-    /**
-     * WHY each holder did not get it, per holder. The boolean alone throws the cause away, and
-     * the operator's sentence then has to guess — it guessed "most likely offline" for a
-     * `session_sealed`, which waiting can never fix. That is the exact substitution
-     * `notifyGuidance` exists to prevent, reintroduced one layer up.
-     */
-    holderFailures: Record<string, string>;
-} | {
-    ok: false;
-    reason: string;
-    detail?: string;
-}>;
-export declare function createDocumentControlNotifier(deps: DocumentControlNotifierDeps): NotifyPeer;
-//# sourceMappingURL=document-control-notifier.d.ts.map

package/dist/document-control-notifier.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"document-control-notifier.d.ts","sourceRoot":"","sources":["../src/document-control-notifier.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4CG;AAGH,OAAO,EAKL,KAAK,mBAAmB,EACzB,MAAM,gCAAgC,CAAC;AACxC,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAEzD,MAAM,WAAW,2BAA2B;IAC1C,KAAK,EAAE,aAAa,CAAC;IACrB,oGAAoG;IACpG,MAAM,IAAI,aAAa,CAAC;QAAE,SAAS,EAAE,MAAM,CAAC;QAAC,YAAY,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IACrE;;;;OAIG;IACH,OAAO,CACL,YAAY,EAAE,MAAM,EACpB,UAAU,EAAE,MAAM,GACjB;QAAE,EAAE,EAAE,IAAI,CAAC;QAAC,OAAO,EAAE,SAAS,MAAM,EAAE,CAAA;KAAE,GAAG;QAAE,EAAE,EAAE,KAAK,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC;IAC5E,uFAAuF;IACvF,IAAI,CAAC,SAAS,EAAE,MAAM,EAAE,GAAG,EAAE,UAAU,GAAG,OAAO,CAAC,UAAU,CAAC,CAAC;IAC9D,IAAI,CACF,SAAS,EAAE,MAAM,EACjB,KAAK,EAAE;QAAE,WAAW,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,UAAU,CAAC;QAAC,aAAa,EAAE,MAAM,CAAA;KAAE,GAC3F,OAAO,CAAC;QAAE,EAAE,EAAE,IAAI,CAAA;KAAE,GAAG;QAAE,EAAE,EAAE,KAAK,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IACzD,GAAG,IAAI,MAAM,CAAC;IACd;;;;;OAKG;IACH,MAAM,CAAC,EAAE;QAAE,IAAI,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAA;KAAE,CAAC;CACtE;AAED,MAAM,MAAM,UAAU,GAAG,CACvB,UAAU,EAAE,MAAM,EAClB,IAAI,EAAE,mBAAmB,KACtB,OAAO,CACR;IACE,EAAE,EAAE,IAAI,CAAC;IACT,eAAe,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACzC;;;;;OAKG;IACH,cAAc,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACxC,GACD;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAA;CAAE,CACjD,CAAC;AAEF,wBAAgB,6BAA6B,CAAC,IAAI,EAAE,2BAA2B,GAAG,UAAU,CAwF3F"}

package/dist/document-control-notifier.js

@@ -1,137 +0,0 @@
-/**
- * DOD-DOC-TOOLS-1 — telling the peer a document has ended.
- *
- * `DocumentLifecycle` ends a document locally without asking anyone, deliberately: a kill is a
- * safety verb, and a safety verb that needs the counterparty's cooperation is not one. But a peer
- * who is never told keeps publishing into a document that will never answer — their updates refused
- * at the far end forever, with nothing on their screen explaining why. So the notification is
- * REQUIRED to be attempted, ALLOWED to fail, and the operator is told which happened.
- *
- * ── WHY THIS IS A MODULE AND NOT A CLOSURE IN THE COMPOSITION ROOT ────────────────────────────
- *
- * It was one, and that is precisely how the surface tests passed while the feature did nothing.
- * `createDocumentLayer` takes `notifyPeer` as an injected seam, so the two-party test wired it to
- * `async () => ({ ok: true })` — which reported success, sent nothing, and agreed with whatever the
- * near side did. Kill "worked" on both sides of the assertion and on neither side of the wire.
- *
- * That is the same shape as the two defects the DELIVERY-2 review found: a stub on the far side
- * cannot disagree with you. So the construction lives here, and both the daemon and the test build
- * it from this function — the test can still substitute the TRANSPORT, which is the part that has
- * to be substituted, without also substituting the logic under test.
- *
- * ── WHY THE DOCUMENT IS FOUND BY SCANNING ─────────────────────────────────────────────────────
- *
- * `notifyPeer`'s signature carries no owner: lifecycle calls it knowing only the document id, and
- * widening that interface would push a multi-agent daemon concern into a unit that deliberately has
- * none. So the owner is resolved here, by asking each agent this daemon holds whether the document
- * is theirs. A document id is a hash committing to both parties and a nonce, so at most one agent
- * can answer.
- *
- * ── DOD-MP-CONTROL-N-1 — WHY THE TARGET IS DERIVED, NOT `peerAgentId` ─────────────────────────
- *
- * This addressed `doc.peerAgentId` and returned after one send. That column is the GENESIS
- * counterparty, frozen at creation, and multiplayer made it wrong in two ways at once: with three
- * holders only one was told, and after a removal the genesis counterparty can BE the removed
- * holder — so the frame went to the one party it must not reach while the remaining co-author was
- * never told, under a reported `peerNotified: true`. Found by the M14B live fleet smoke.
- *
- * The target is now the DERIVED participant set, the same source FANOUT-1 established for update
- * envelopes; control frames were simply never migrated to it. Deriving needs the genesis proposal,
- * the amendment chain and signature verification — all of which live above this module, so it
- * arrives as an injected `holders()` rather than by widening this unit into the replay engine.
- *
- * A derivation failure REFUSES. It must never fall back to `peerAgentId`: that is the old bug, and
- * it aims the frame at exactly the wrong party in the case that motivated the change.
- */
-import { randomUUID } from "node:crypto";
-import { encodeDocumentControl, buildDocumentControlTbs, DOCUMENT_CONTROL_VERSION, } from "@cello-protocol/protocol-types";
-export function createDocumentControlNotifier(deps) {
-    return async (documentId, verb) => {
-        for (const { agentName, ownerAgentId } of deps.owners()) {
-            const doc = deps.store.getDocument(ownerAgentId, documentId);
-            if (!doc)
-                continue;
-            const targets = deps.holders(ownerAgentId, documentId);
-            if (!targets.ok) {
-                deps.logger?.warn("document.control.holders_underivable", {
-                    documentId, verb, agentName, reason: targets.reason,
-                });
-                return { ok: false, reason: targets.reason };
-            }
-            if (targets.holders.length === 0) {
-                // Distinct from a failed send, and reported rather than returned as a vacuous success: an
-                // empty map behind `ok: true` reads as "everyone was told" to a caller that checks only ok.
-                return { ok: false, reason: "document_no_holders" };
-            }
-            const control = {
-                type: "document_control",
-                control_version: DOCUMENT_CONTROL_VERSION,
-                document_id: documentId,
-                sender_agent_id: ownerAgentId,
-                verb,
-                sent_at_ms: deps.now(),
-                signature: new Uint8Array(0),
-            };
-            let signature;
-            try {
-                signature = await deps.sign(agentName, buildDocumentControlTbs(control));
-            }
-            catch (err) {
-                // REFUSED, not skipped and not sent unsigned. The peer must reject an unsigned control
-                // frame, so shipping one would report a notification that cannot possibly land — and the
-                // caller reports `peerNotified` straight to the operator.
-                //
-                // THE MESSAGE IS KEPT. A bare `catch {}` here threw away the only description of a LOCAL
-                // fault — a key file that moved, a locked keychain, an agent with no provider — and the
-                // operator was then told their peer had not heard them and to try again when the peer was
-                // back. Waiting cannot fix a signing failure. The reason travels up so the caller can say
-                // which of the two it is.
-                const detail = err instanceof Error ? err.message : String(err);
-                deps.logger?.warn("document.control.unsigned", { documentId, verb, agentName, reason: detail });
-                return { ok: false, reason: "document_control_unsigned", detail };
-            }
-            control.signature = signature;
-            // Signed ONCE. The TBS commits to the document, the sender and the verb — never to a
-            // recipient — so every holder receives byte-identical evidence and cannot be handed a
-            // frame that differs from their co-holders'.
-            const bytes = encodeDocumentControl(control);
-            const holdersNotified = {};
-            const holderFailures = {};
-            for (const holder of targets.holders) {
-                // Sequential and independent: one unreachable holder must neither block nor abort the
-                // others (availability is a first-class protocol concern), and a throw from the transport
-                // is that holder's failure alone, not the fan-out's.
-                try {
-                    const sent = await deps.send(agentName, {
-                        peerAgentId: holder,
-                        documentId,
-                        bytes,
-                        correlationId: randomUUID(),
-                    });
-                    holdersNotified[holder] = sent.ok;
-                    if (!sent.ok) {
-                        holderFailures[holder] = sent.reason;
-                        deps.logger?.warn("document.control.holder_not_notified", {
-                            documentId, verb, holderAgentId: holder, reason: sent.reason,
-                        });
-                    }
-                }
-                catch (err) {
-                    holdersNotified[holder] = false;
-                    holderFailures[holder] = err instanceof Error ? err.message : String(err);
-                    deps.logger?.warn("document.control.holder_not_notified", {
-                        documentId, verb, holderAgentId: holder,
-                        reason: err instanceof Error ? err.message : String(err),
-                    });
-                }
-            }
-            // `ok` means SIGNED AND ATTEMPTED TO EVERY CURRENT HOLDER. Who actually took it is the map's
-            // job — collapsing that into one boolean is how a partial fan-out reads as a clean one.
-            return { ok: true, holdersNotified, holderFailures };
-        }
-        // No agent on this daemon holds it. Named as such rather than reported as a transport failure:
-        // the two want different things from whoever reads the log.
-        return { ok: false, reason: "document_unknown" };
-    };
-}
-//# sourceMappingURL=document-control-notifier.js.map

package/dist/document-control-notifier.js.map

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