@cello-protocol/daemon 0.0.166 → 0.0.168

package/dist/document-handlers.js

@@ -26,6 +26,7 @@
 import { randomBytes, randomUUID } from "node:crypto";
 import * as Y from "yjs";
 import { encodeDocumentProposal, deriveArrangement, documentGovernancePolicy, arrangementGenesisFromProposal, documentAmendmentHash, buildDocumentMultisigTbs, encodeDocumentAmendment, buildDocumentJoinOfferTbs, encodeDocumentJoinOffer, validateDocumentJoinOffer, encodeDocumentUpdateEnvelope, DOCUMENT_UPDATE_ENCODING_V1, buildDocumentProposalTbs, documentIdFromProposal, seamViolation, ASSURANCE_TIER_V1, TOPOLOGY_DEFAULT, DOCUMENT_FEATURE_VERSION, encodeDocumentProposalAck, buildDocumentProposalAckTbs, DOCUMENT_PROPOSAL_ACK_VERSION, MAX_PROPOSAL_REFUSAL_REASON_LENGTH, } from "@cello-protocol/protocol-types";
+import { DELIVERY_ACK_TIMEOUT_MS } from "./document-delivery.js";
 import { lineHunks, isSupportedDocumentType, SUPPORTED_DOCUMENT_TYPES } from "./document-write-path.js";
 import { openingNoticeFor, rootForDocumentType } from "./document-types.js";
 import { projectDocumentText, parseJsonDocument, applyJsonToMap } from "./document-json.js";
@@ -35,6 +36,10 @@ import { profileViolation } from "./document-profile.js";
 import { screenText, SCREEN_RULE_ID } from "./document-screen.js";
 /** Document types the notification/diff path understands. Anything else is stored, not diffed. */
 const DEFAULT_DOCUMENT_TYPE = "markdown";
+/** Ends a fragment with a full stop unless it already ends in one — see the refusal below. */
+function withStop(text) {
+    return /[.!?]$/.test(text.trimEnd()) ? text : `${text.trimEnd()}.`;
+}
 export function registerDocumentHandlers(deps) {
     const { handlers, logger, layer, publish } = deps;
     /**
@@ -579,6 +584,67 @@ export function registerDocumentHandlers(deps) {
                 : {}),
         };
     });
+    /**
+     * DOD-MP-INVITE-FANOUT-1 — fan a governance amendment to the CURRENT holders, durably.
+     *
+     * ONE implementation for every site that fans one. There were four — invite, re-invite, remove,
+     * and remove's re-send — each with its own copy of the same best-effort loop, and the review found
+     * that wiring durability into one of them left the other three losing membership changes exactly
+     * as before. The re-invite is the verb the tool's own guidance tells an operator to run when a
+     * holder is out of step, so it carrying the defect meant the documented cure did nothing.
+     *
+     * RECORD THE DEBT FIRST. The send below is a fast path, never the guarantee: a daemon that dies
+     * between here and the send still owes the amendment on restart.
+     *
+     * A successful send is recorded as SENT, not acked — their daemon received the frame, and whether
+     * it RECORDED it is a separate fact it can refuse. The row settles for real when that holder acks
+     * any envelope at this epoch or later, which proves they applied it.
+     */
+    const fanOutAmendment = async (args) => {
+        layer.store.seedAmendmentDeliveries(args.ownerAgentId, args.documentId, args.amendmentHashHex, args.holders, deps.now());
+        const told = {};
+        for (const holder of args.holders) {
+            try {
+                const sent = await deps.transportFor(args.agentName).sendBytes({
+                    peerAgentId: holder,
+                    documentId: args.documentId,
+                    bytes: args.amendmentBytes,
+                    correlationId: randomUUID(),
+                });
+                // PARKED IS NOT NOTIFIED. The relay took it because the holder had no live counterparty.
+                const landed = sent.ok && sent.parked !== true;
+                told[holder] = landed;
+                if (landed) {
+                    layer.store.markAmendmentSent(args.ownerAgentId, args.documentId, args.amendmentHashHex, holder, deps.now(), DELIVERY_ACK_TIMEOUT_MS);
+                }
+                else {
+                    // NAMED, NOT JUST COUNTED. This used to record `false` with no log line anywhere, so the
+                    // only trace of a lost membership change was a boolean inside an `ok: true` response.
+                    logger.warn("document.amendment.holder_unnotified", {
+                        documentId: args.documentId,
+                        holderAgentId: holder,
+                        verb: args.verb,
+                        reason: sent.ok ? "relay_parked" : sent.reason,
+                        detail: sent.ok
+                            ? "the relay is holding it — the holder had no live counterparty"
+                            : sent.detail,
+                    });
+                }
+            }
+            catch (err) {
+                told[holder] = false;
+                // A throw used to be swallowed whole.
+                logger.warn("document.amendment.holder_unnotified", {
+                    documentId: args.documentId,
+                    holderAgentId: holder,
+                    verb: args.verb,
+                    reason: "amendment_send_threw",
+                    detail: err instanceof Error ? err.message : String(err),
+                });
+            }
+        }
+        return told;
+    };
     /**
      * M14B / DOD-MP-JOIN-1 — invite a third party into an existing document.
      *
@@ -670,24 +736,20 @@ export function registerDocumentHandlers(deps) {
                 // re-sent the amendment. The re-invite is the healing verb: it re-fans the admitting
                 // amendment to every other current holder, best-effort, reported per holder.
                 const admittingBytes = outgoing.offer.amendments[outgoing.offer.amendments.length - 1];
-                const holdersNotified = {};
-                if (admittingBytes !== undefined) {
-                    for (const holder of derived.arrangement.participants) {
-                        if (holder === who.ownerAgentId || holder === invitee)
-                            continue;
-                        try {
-                            const sentAmend = await deps.transportFor(who.agentName).sendBytes({
-                                peerAgentId: holder,
-                                documentId,
-                                bytes: new Uint8Array(admittingBytes),
-                                correlationId: randomUUID(),
-                            });
-                            holdersNotified[holder] = sentAmend.ok;
-                        }
-                        catch {
-                            holdersNotified[holder] = false;
-                        }
-                    }
+                let holdersNotified = {};
+                // `priorHash` is non-null whenever `outgoing` is — the lookup is keyed by it — but the
+                // narrowing does not survive the branch, and an amendment seeded under a null key would be
+                // owed to a row nothing can ever join.
+                if (admittingBytes !== undefined && priorHash !== null) {
+                    holdersNotified = await fanOutAmendment({
+                        agentName: who.agentName,
+                        ownerAgentId: who.ownerAgentId,
+                        documentId,
+                        amendmentHashHex: priorHash,
+                        amendmentBytes: new Uint8Array(admittingBytes),
+                        holders: [...derived.arrangement.participants].filter((holder) => holder !== who.ownerAgentId && holder !== invitee),
+                        verb: "re-invite",
+                    });
                 }
                 return {
                     ok: true,
@@ -793,20 +855,25 @@ export function registerDocumentHandlers(deps) {
                 documentId, error: err instanceof Error ? err.message : String(err),
             });
         }
-        const holdersTold = {};
-        for (const holder of derived.arrangement.participants) {
-            if (holder === who.ownerAgentId || holder === invitee)
-                continue;
-            try {
-                const sent = await deps.transportFor(who.agentName).sendBytes({
-                    peerAgentId: holder, documentId, bytes: amendmentBytes, correlationId: randomUUID(),
-                });
-                holdersTold[holder] = sent.ok;
-            }
-            catch {
-                holdersTold[holder] = false;
-            }
-        }
+        // DOD-MP-INVITE-FANOUT-1 — RECORD WHAT IS OWED BEFORE TRYING TO SEND IT.
+        //
+        // The loop below is a fast path, not the guarantee. It used to be both, and that is the whole
+        // defect: one failed send lost a membership change permanently, because nothing remained owing
+        // anywhere. A content edit has always had a pending row, a retry schedule and restart survival;
+        // the governance act that decides who is a party to the document had none of them.
+        //
+        // Seeding first also makes the crash window safe: a daemon that dies between here and the send
+        // still owes the amendment on restart.
+        const owedHolders = [...derived.arrangement.participants].filter((holder) => holder !== who.ownerAgentId && holder !== invitee);
+        const holdersTold = await fanOutAmendment({
+            agentName: who.agentName,
+            ownerAgentId: who.ownerAgentId,
+            documentId,
+            amendmentHashHex: amendHashHex,
+            amendmentBytes,
+            holders: owedHolders,
+            verb: "invite",
+        });
         logger.info("document.join.invited", { documentId, invitee, epochId: body.epoch_id, offerSent });
         return {
             ok: true,
@@ -879,20 +946,31 @@ export function registerDocumentHandlers(deps) {
                 const removal = chain.find((e) => e.body.kind === "remove_holder" &&
                     e.body.subject_agent_id === holder &&
                     e.body.epoch_id === membership.epochId);
-                const resendTold = {};
+                let resendTold = {};
                 if (removal) {
                     const bytes = new Uint8Array(encodeDocumentAmendment(removal));
-                    const targets = new Set([...derived.arrangement.participants, holder]);
-                    targets.delete(who.ownerAgentId);
-                    for (const member of targets) {
+                    const remaining = [...derived.arrangement.participants].filter((m) => m !== who.ownerAgentId && m !== holder);
+                    // The healing re-send is durable for the holders who REMAIN, for the same reason the
+                    // re-invite is: it is the verb an operator runs precisely because someone is out of step,
+                    // so it must not be the one that gives up quietest.
+                    resendTold = await fanOutAmendment({
+                        agentName: who.agentName,
+                        ownerAgentId: who.ownerAgentId,
+                        documentId,
+                        amendmentHashHex: Buffer.from(documentAmendmentHash(removal.body)).toString("hex"),
+                        amendmentBytes: bytes,
+                        holders: remaining,
+                        verb: "remove-resend",
+                    });
+                    if (holder !== who.ownerAgentId) {
                         try {
                             const sent = await deps.transportFor(who.agentName).sendBytes({
-                                peerAgentId: member, documentId, bytes, correlationId: randomUUID(),
+                                peerAgentId: holder, documentId, bytes, correlationId: randomUUID(),
                             });
-                            resendTold[member] = sent.ok;
+                            resendTold[holder] = sent.ok && sent.parked !== true;
                         }
                         catch {
-                            resendTold[member] = false;
+                            resendTold[holder] = false;
                         }
                     }
                 }
@@ -957,29 +1035,43 @@ export function registerDocumentHandlers(deps) {
         // The amendment travels to EVERY current holder INCLUDING the removed one — being told is
         // how their daemon surfaces the removal to their operator. Best-effort at P1, per holder,
         // reported never assumed.
-        const holdersTold = {};
-        for (const member of withNew.arrangement.participants) {
-            if (member === who.ownerAgentId)
-                continue;
-            try {
-                const sent = await deps.transportFor(who.agentName).sendBytes({
-                    peerAgentId: member, documentId, bytes: amendmentBytes, correlationId: randomUUID(),
-                });
-                holdersTold[member] = sent.ok;
-            }
-            catch {
-                holdersTold[member] = false;
-            }
-        }
+        // DOD-MP-INVITE-FANOUT-1 — the REMAINING holders get the durable fan-out. A holder who misses
+        // a removal keeps delivering to, and accepting edits from, someone the chain has removed —
+        // silently and permanently, which is the same defect the invite had and is worse, because here
+        // the stale holder keeps honouring a membership that has been revoked.
+        const holdersTold = await fanOutAmendment({
+            agentName: who.agentName,
+            ownerAgentId: who.ownerAgentId,
+            documentId,
+            amendmentHashHex: Buffer.from(amendHash).toString("hex"),
+            amendmentBytes,
+            holders: [...withNew.arrangement.participants].filter((m) => m !== who.ownerAgentId),
+            verb: "remove",
+        });
+        // THE REMOVED HOLDER IS TOLD ONCE, and is deliberately NOT owed a durable retry: delivery to
+        // them stopping is what removal MEANS, so a queue that kept redialling them would contradict
+        // the act it is announcing. Forward-only cuts both ways — we tell them, we do not pursue them.
         if (holder !== who.ownerAgentId) {
             try {
                 const sent = await deps.transportFor(who.agentName).sendBytes({
                     peerAgentId: holder, documentId, bytes: amendmentBytes, correlationId: randomUUID(),
                 });
-                holdersTold[holder] = sent.ok;
+                holdersTold[holder] = sent.ok && sent.parked !== true;
+                if (!holdersTold[holder]) {
+                    logger.warn("document.amendment.holder_unnotified", {
+                        documentId, holderAgentId: holder, verb: "remove-subject",
+                        reason: sent.ok ? "relay_parked" : sent.reason,
+                        detail: sent.ok ? "the relay is holding it" : sent.detail,
+                    });
+                }
             }
-            catch {
+            catch (err) {
                 holdersTold[holder] = false;
+                logger.warn("document.amendment.holder_unnotified", {
+                    documentId, holderAgentId: holder, verb: "remove-subject",
+                    reason: "amendment_send_threw",
+                    detail: err instanceof Error ? err.message : String(err),
+                });
             }
         }
         logger.info("document.holder_removed", {
@@ -1113,8 +1205,47 @@ export function registerDocumentHandlers(deps) {
                 // actions.
                 const proposal = layer.handshake.get(who.ownerAgentId, d.documentId);
                 const peerAnswer = layer.handshake.peerAnswer(who.ownerAgentId, d.documentId);
+                const arrangement = arrangementFor(d.documentId, proposal);
+                // DOD-MP-REMOVE-FEEDBACK-1 — the SENTENCE for a fact the row already carried.
+                //
+                // The row has shipped `removed: true` since REMOVE-1. What was missing is that a bare flag
+                // is not feedback: it does not say when, it does not say the copy is still yours, and it
+                // does not say what actually stopped. So this completes the existing signal rather than
+                // adding a second name for it computed by a second walk of the same chain.
+                //
+                // NAMED `yourStanding`, NOT `yourAccess`: your access to the copy did not change — reading
+                // it still works and the file is still on disk, which the sentence itself says. A surface
+                // that renders a badge from the key alone would show "access: removed", which is the
+                // confiscation reading FORWARD-ONLY-REMOVAL exists to forbid.
+                //
+                // ALWAYS PRESENT, exactly as `participants` is: an absent key is read as "fine", so on a
+                // chain this build cannot decode — where `removedFromArrangement` honestly cannot tell —
+                // it says `unknown` rather than going quiet and rendering a removed holder as a holder.
+                const standing = arrangement["arrangementUnavailable"] !== undefined
+                    ? "unknown"
+                    : d.removed === true
+                        ? "removed"
+                        : "holder";
+                const removedAtEpoch = d.removedAtEpoch;
                 return {
                     ...d,
+                    yourStanding: standing,
+                    ...(standing === "removed"
+                        ? {
+                            standingGuidance: `You are no longer a holder of this document` +
+                                (removedAtEpoch === undefined ? `. ` : `, as of epoch ${removedAtEpoch}. `) +
+                                `Your copy and its full history remain yours, and you can still read it here or ` +
+                                `open the file. What changed is only the flow of edits: yours no longer publish ` +
+                                `to the other holders, and theirs no longer reach you.`,
+                        }
+                        : {}),
+                    ...(standing === "unknown"
+                        ? {
+                            standingGuidance: `This daemon cannot read this document's amendment chain, so it cannot tell ` +
+                                `whether you are still a holder. Nothing here should be taken as confirmation ` +
+                                `that you are.`,
+                        }
+                        : {}),
                     proposedByUs: proposal?.proposerAgentId === who.ownerAgentId,
                     // THE PEER'S OWN SIGNED ANSWER — true accepted, false refused, null not yet heard. This
                     // replaced an inference ("they have published into it") that could not tell refused from
@@ -1133,7 +1264,7 @@ export function registerDocumentHandlers(deps) {
                     // WHO HOLDS IT AND WHO GOVERNS IT — derived from THIS daemon's own chain (G0).
                     // `proposal` is passed rather than re-fetched: it is the same SQL read and the same
                     // CBOR decode of the same bytes, already in hand.
-                    ...arrangementFor(d.documentId, proposal),
+                    ...arrangement,
                     // DID OUR OFFER LEAVE? Only meaningful for a document WE proposed — for one we accepted
                     // there is no offer of ours to have sent. Without this, `peerAccepted: null` meant both
                     // "they are thinking" and "they were never asked", and the shipped guidance said WAIT,
@@ -1582,7 +1713,11 @@ export function registerDocumentHandlers(deps) {
             return {
                 ok: false,
                 reason: publishable.reason,
-                guidance: `${publishable.detail ?? "This document can no longer accept writes."} Nothing was ` +
+                guidance: 
+                // PUNCTUATED. `detail` comes from several producers and not all of them end in a stop,
+                // so the two sentences ran together — "…no longer publish to the other holders Nothing
+                // was changed locally…" — on the one line this DoD calls actionable.
+                `${withStop(publishable.detail ?? "This document can no longer accept writes.")} Nothing was ` +
                     `changed locally — an edit applied here could never be published or recovered, and would ` +
                     `disappear the next time the daemon restarted.`,
             };
@@ -1723,9 +1858,16 @@ export function registerDocumentHandlers(deps) {
      * network.
      */
     function notifyGuidance(verb, reason, detail, holdersNotified, holderFailures) {
+        // DOD-MP-CONTROL-DURABLE-1 — this said "A close is not retried", and that stopped being true
+        // when the ending became durable. A sentence telling the operator to do by hand what the daemon
+        // now does for them is not merely stale: it invites a second close for no reason, and it
+        // undersells the one case that still needs them — a holder we never manage to confirm.
         const tail = verb === "close"
-            ? `A close is not retried — run cello_doc_close again once this is cleared, or cello_doc_kill if you need it over now.`
-            : `The kill stands locally either way; run cello_doc_kill again once this is cleared so they stop editing.`;
+            ? `The ending is owed to anyone who did not take it and is re-sent when they return; you do ` +
+                `not need to run this again. If it still cannot be confirmed the daemon says so, naming ` +
+                `them — that one needs you.`
+            : `The kill stands locally either way, and is re-sent to anyone who did not take it until ` +
+                `they do or the daemon reports that it gave up on them.`;
         if (reason === "document_control_unsigned") {
             return (`Your ${verb} was recorded, but this agent's signing key could not be loaded, so nothing ` +
                 `could be sent to the peer${detail ? ` (${detail})` : ""}. Waiting will not help — the ` +
@@ -1778,7 +1920,14 @@ export function registerDocumentHandlers(deps) {
             // Waiting cannot reopen a sealed session. The cause is known per holder; it travels.
             const causes = [...new Set(Object.values(holderFailures ?? {}))].filter(Boolean);
             const because = causes.length > 0 ? ` (${causes.join(", ")})` : "";
-            const sealed = causes.some((c) => c.includes("sealed"));
+            // THE WHOLE FAMILY, not one substring. This tested `includes("sealed")`, so `session_sealed`
+            // got the useful sentence and every other way a session's record can be over —
+            // `relay_session_gone` (the relay restarted or swept it) and `session_not_found` — fell to
+            // generic wait-for-them advice, which is the one thing that cannot work when there is nothing
+            // left to wait for.
+            const sealed = causes.some((c) => c.includes("sealed") ||
+                c.includes("relay_session_gone") ||
+                c.includes("session_not_found"));
             return (`Your ${verb} was recorded but reached none of the ${missed.length} other ` +
                 `holder${missed.length > 1 ? "s" : ""} (${missed.join(", ")})${because}, so the document ` +
                 `cannot settle until they hear it. ` +