@cello-protocol/daemon 0.0.161 → 0.0.163

package/dist/document-handlers.js

@@ -25,7 +25,7 @@
  */
 import { randomBytes, randomUUID } from "node:crypto";
 import * as Y from "yjs";
-import { encodeDocumentProposal, buildDocumentProposalTbs, documentIdFromProposal, seamViolation, ASSURANCE_TIER_V1, TOPOLOGY_V1, DOCUMENT_FEATURE_VERSION, encodeDocumentProposalAck, buildDocumentProposalAckTbs, DOCUMENT_PROPOSAL_ACK_VERSION, MAX_PROPOSAL_REFUSAL_REASON_LENGTH, } from "@cello-protocol/protocol-types";
+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 { 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";
@@ -232,11 +232,38 @@ export function registerDocumentHandlers(deps) {
             }
             startingContent = Y.encodeStateAsUpdate(seed);
         }
+        // THE ADMIN SET IS ALWAYS WRITTEN, NEVER SILENTLY ABSENT (GOVERN-1: the creation flow makes
+        // the choice legible). No `admins` param means EVERYONE — both genesis participants — and
+        // that default is recorded explicitly in the signed proposal rather than implied by an
+        // absent field, so the invitee consents to a stated rule, not a convention.
+        const rawAdmins = params?.admins;
+        if (rawAdmins !== undefined && (!Array.isArray(rawAdmins) || rawAdmins.length === 0)) {
+            return {
+                ok: false,
+                reason: "document_admins_invalid",
+                guidance: "admins must be a non-empty list of 64-hex pubkeys, or omitted for everyone-is-admin. " +
+                    "Nothing was created.",
+            };
+        }
+        const adminSet = rawAdmins === undefined
+            ? [who.ownerAgentId, peerAgentId]
+            : [...new Set(rawAdmins)];
+        for (const admin of adminSet) {
+            if (admin !== who.ownerAgentId && admin !== peerAgentId) {
+                return {
+                    ok: false,
+                    reason: "document_admins_invalid",
+                    guidance: `${String(admin).slice(0, 16)}… is not a party to this document — a creation admin ` +
+                        `must be you or the counterparty (admins are always holders). Nothing was created.`,
+                };
+            }
+        }
         const properties = {
             assurance_tier: ASSURANCE_TIER_V1,
             schema_enforcement: false,
-            topology: TOPOLOGY_V1,
+            topology: TOPOLOGY_DEFAULT,
             append_only: params?.append_only === true,
+            admin_set: adminSet,
         };
         const violation = seamViolation(properties);
         if (violation) {
@@ -402,8 +429,66 @@ export function registerDocumentHandlers(deps) {
                 hasStartingContent: p.envelope.starting_content !== null,
                 proposedAtMs: p.envelope.proposed_at_ms,
             })),
+            // M14B / DOD-MP-JOIN-1 — offers to join an EXISTING document, decided with the same
+            // accept/refuse verbs (route by document_id). THE RULES ARE SHOWN HERE, derived by replay
+            // of the carried bytes — the operator consents to what their own daemon computed — and
+            // cello_doc_accept re-derives at the moment of consequence. An entry whose stored bytes no
+            // longer validate says so, never silently omitted.
+            joins: layer.joins.pendingFor(who.ownerAgentId).map((j) => {
+                const derived = validateDocumentJoinOffer(j.offer, documentGovernancePolicy, layer.verifySignature);
+                return {
+                    documentId: j.documentId,
+                    inviterAgentId: j.inviterAgentId,
+                    amendmentHash: j.amendmentHash,
+                    offeredAtMs: j.offer.offered_at_ms,
+                    carriedEnvelopes: j.offer.envelope_log.length,
+                    ...(derived.ok
+                        ? {
+                            participants: [...derived.arrangement.participants].sort(),
+                            admins: [...derived.arrangement.admins].sort(),
+                            properties: derived.arrangement.properties,
+                            assuranceTier: derived.genesis.properties.assurance_tier,
+                            documentType: derived.genesis.document_type,
+                        }
+                        : { invalid: derived.reason }),
+                };
+            }),
+            // Auto-refused offers (version mismatch, chains that do not replay) — recorded with the
+            // sentence written for the operator, and listed so it actually reaches one.
+            refusedJoins: layer.joins.refusedFor(who.ownerAgentId).map((j) => ({
+                documentId: j.documentId,
+                inviterAgentId: j.inviterAgentId,
+                reason: j.reason,
+                offeredAtMs: j.offer.offered_at_ms,
+            })),
         };
     });
+    /**
+     * Tell the INVITER what was decided — the join twin of `tellProposer`, and the same doctrine:
+     * best-effort, because consent is local and final the moment the operator makes it, and an
+     * unreachable inviter must not get a veto over the invitee's choice.
+     */
+    async function tellInviter(who, documentId, inviterAgentId, answerBytes) {
+        try {
+            const sent = await deps.transportFor(who.agentName).sendBytes({
+                peerAgentId: inviterAgentId,
+                documentId,
+                bytes: answerBytes,
+                correlationId: randomUUID(),
+            });
+            if (!sent.ok) {
+                logger.warn("document.join.answer_unsent", { documentId, reason: sent.reason });
+            }
+            return sent.ok;
+        }
+        catch (err) {
+            logger.warn("document.join.answer_send_threw", {
+                documentId,
+                error: err instanceof Error ? err.message : String(err),
+            });
+            return false;
+        }
+    }
     handlers.set("cello_doc_accept", async (params, connectionId) => {
         const who = resolve(params, connectionId);
         if (isRefusal(who))
@@ -412,6 +497,31 @@ export function registerDocumentHandlers(deps) {
         if (documentId.length === 0) {
             return { ok: false, reason: "invalid_document_id", guidance: "Pass 'document_id' from cello_doc_inbox." };
         }
+        // A join offer decided with the SAME verb the inbox advertises. Routed first by exact
+        // pending match, so a proposal and a join for different documents can never shadow each
+        // other; an id that matches neither falls through to the proposal path's own refusal.
+        const pendingJoin = layer.joins
+            .pendingFor(who.ownerAgentId)
+            .find((j) => j.documentId === documentId);
+        if (pendingJoin) {
+            const joined = await layer.acceptJoin(who.ownerAgentId, pendingJoin.amendmentHash, deps.now());
+            if (!joined.ok)
+                return { ok: false, reason: joined.reason, guidance: joined.detail };
+            const joinFile = await materialize(who.ownerAgentId, documentId, joined.documentType);
+            const told = await tellInviter(who, documentId, joined.inviterAgentId, joined.answerBytes);
+            return {
+                ok: true,
+                documentId,
+                joined: true,
+                peerAgentId: joined.inviterAgentId,
+                inviterNotified: told,
+                appliedEnvelopes: joined.applied,
+                filePath: joinFile.path,
+                ...(joinFile.path !== null && openingNoticeFor(joined.documentType) !== undefined
+                    ? { fileNotice: openingNoticeFor(joined.documentType) }
+                    : {}),
+            };
+        }
         const outcome = layer.handshake.accept(who.ownerAgentId, documentId, deps.now());
         if (!outcome.ok)
             return { ok: false, reason: outcome.reason, guidance: outcome.detail };
@@ -469,6 +579,418 @@ export function registerDocumentHandlers(deps) {
                 : {}),
         };
     });
+    /**
+     * M14B / DOD-MP-JOIN-1 — invite a third party into an existing document.
+     *
+     * One admin's signature authors the admitting amendment (D2); the invitee's own consent makes
+     * the join real (their accept, on their daemon). VALIDATE-THEN-APPEND: the chain including the
+     * new amendment replays through the real policy before one byte lands — the AMEND-1 standing
+     * condition at its second production append site. The offer carries the genesis, the whole
+     * chain, and the update-log snapshot re-encoded from rows (lossless: the client id is a
+     * column, the encoding a pinned constant — the same re-encode the delivery path ships).
+     * Existing holders get the amendment frame BEST-EFFORT at P1; the epoch gate makes a missed
+     * one loud, and durable per-holder delivery is FANOUT-1.
+     */
+    handlers.set("cello_doc_invite", async (params, connectionId) => {
+        const who = resolve(params, connectionId);
+        if (isRefusal(who))
+            return who;
+        const documentId = typeof params?.document_id === "string" ? params.document_id : "";
+        const invitee = typeof params?.invitee_pubkey === "string" ? params.invitee_pubkey : "";
+        if (documentId.length === 0) {
+            return { ok: false, reason: "invalid_document_id", guidance: "Pass 'document_id' from cello_doc_list." };
+        }
+        if (!/^[0-9a-f]{64}$/.test(invitee)) {
+            return {
+                ok: false,
+                reason: "invalid_invitee_pubkey",
+                guidance: "invitee_pubkey must be the 64-hex agent id — see cello_contacts.",
+            };
+        }
+        const doc = layer.store.getDocument(who.ownerAgentId, documentId);
+        if (!doc) {
+            return { ok: false, reason: "document_unknown", guidance: `No document ${documentId.slice(0, 16)}… for this agent.` };
+        }
+        if (doc.status !== "active") {
+            return {
+                ok: false,
+                reason: "document_not_active",
+                guidance: `This document is ${doc.status} — only an active document can admit a holder.`,
+            };
+        }
+        const genesisRecord = layer.handshake.get(who.ownerAgentId, documentId);
+        if (!genesisRecord) {
+            return {
+                ok: false,
+                reason: "document_genesis_missing",
+                guidance: "The document has a row but no stored genesis proposal to replay from — this is a local-state fault, not the peer's.",
+            };
+        }
+        const genesisArr = arrangementGenesisFromProposal(genesisRecord.envelope);
+        const chain = layer.amendments.chain(who.ownerAgentId, documentId);
+        const derived = deriveArrangement(genesisArr, chain, documentGovernancePolicy, layer.verifySignature);
+        if (!derived.ok) {
+            return { ok: false, reason: "document_chain_invalid", guidance: derived.reason };
+        }
+        if (!derived.arrangement.admins.has(who.ownerAgentId)) {
+            return {
+                ok: false,
+                reason: "document_not_admin",
+                guidance: `Inviting takes an admin's signature and this agent holds no admin power here. ` +
+                    `Current admins: ${[...derived.arrangement.admins].join(", ")}.`,
+            };
+        }
+        if (derived.arrangement.participants.has(invitee)) {
+            // A RE-RUN after the amendment landed but the offer did not reach them: re-send the STORED
+            // offer bytes (the proposal --retry precedent) rather than refusing — authoring afresh
+            // would try to admit a holder the chain already admitted, which the replay refuses.
+            const admitting = chain.find((e) => e.body.kind === "add_holder" && e.body.subject_agent_id === invitee);
+            const priorHash = admitting
+                ? Buffer.from(documentAmendmentHash(admitting.body)).toString("hex")
+                : null;
+            const outgoing = priorHash ? layer.joins.get(who.ownerAgentId, priorHash) : null;
+            if (outgoing && outgoing.role === "inviter" && outgoing.state === "pending") {
+                let resent = false;
+                try {
+                    const sent = await deps.transportFor(who.agentName).sendBytes({
+                        peerAgentId: invitee,
+                        documentId,
+                        bytes: new Uint8Array(encodeDocumentJoinOffer(outgoing.offer)),
+                        correlationId: randomUUID(),
+                    });
+                    resent = sent.ok;
+                }
+                catch (err) {
+                    logger.warn("document.join.offer_resend_threw", {
+                        documentId, error: err instanceof Error ? err.message : String(err),
+                    });
+                }
+                // AND THE STALE HOLDERS. A holder who missed the amendment fan-out is wedged — their
+                // publishes refuse as epoch-stale with guidance they cannot follow, because no verb
+                // 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;
+                        }
+                    }
+                }
+                return {
+                    ok: true,
+                    documentId,
+                    inviteeAgentId: invitee,
+                    amendmentHash: priorHash,
+                    resent: true,
+                    offerSent: resent,
+                    holdersNotified,
+                };
+            }
+            return {
+                ok: false,
+                reason: "document_already_holder",
+                guidance: "That agent already holds this document — there is nothing to invite them to.",
+            };
+        }
+        const body = {
+            document_id: documentId,
+            epoch_id: derived.arrangement.epoch + 1,
+            prev_amendment_hash: derived.arrangement.lastAmendmentHash,
+            kind: "add_holder",
+            subject_agent_id: invitee,
+            property_change: null,
+            state_hash: null,
+            authored_at_ms: deps.now(),
+        };
+        const amendHash = documentAmendmentHash(body);
+        const multisigTbs = buildDocumentMultisigTbs({
+            document_id: documentId,
+            subject_kind: "document_amendment",
+            subject_hash: amendHash,
+            required_signers: [who.ownerAgentId],
+        });
+        const amendment = {
+            body,
+            collection: {
+                document_id: documentId,
+                subject_kind: "document_amendment",
+                subject_hash: amendHash,
+                required_signers: [who.ownerAgentId],
+                signatures: [
+                    { signer_agent_id: who.ownerAgentId, signature: await deps.sign(who.agentName, multisigTbs) },
+                ],
+            },
+        };
+        // VALIDATE-BEFORE-APPEND, on the exact bytes about to land.
+        const withNew = deriveArrangement(genesisArr, [...chain, amendment], documentGovernancePolicy, layer.verifySignature);
+        if (!withNew.ok) {
+            return { ok: false, reason: "document_amendment_invalid", guidance: withNew.reason };
+        }
+        const amendmentBytes = new Uint8Array(encodeDocumentAmendment(amendment));
+        layer.amendments.append(who.ownerAgentId, documentId, amendmentBytes, deps.now());
+        // The snapshot: update rows only, re-encoded losslessly. Rejection records stay local —
+        // quarantine bridging is receiver-side state, not shared history.
+        const log = layer.store.getEnvelopeLog(who.ownerAgentId, documentId);
+        const snapshot = [];
+        for (const row of log) {
+            if (row.kind !== "update" || row.payload === null)
+                continue;
+            snapshot.push(new Uint8Array(encodeDocumentUpdateEnvelope({
+                type: "document_update",
+                document_id: row.documentId,
+                epoch_id: row.epochId,
+                doc_prev_hash: row.docPrevHash,
+                sender_agent_id: row.senderAgentId,
+                sender_client_id: row.senderClientId ?? 0,
+                update_encoding: DOCUMENT_UPDATE_ENCODING_V1,
+                state_vector: row.stateVector,
+                update: row.payload,
+                signature: row.signature,
+            })));
+        }
+        const offer = {
+            type: "document_join_offer",
+            feature_version: DOCUMENT_FEATURE_VERSION,
+            inviter_agent_id: who.ownerAgentId,
+            invitee_agent_id: invitee,
+            document_id: documentId,
+            genesis: new Uint8Array(encodeDocumentProposal(genesisRecord.envelope)),
+            amendments: [...chain.map((e) => new Uint8Array(encodeDocumentAmendment(e))), amendmentBytes],
+            envelope_log: snapshot,
+            offered_at_ms: deps.now(),
+            signature: new Uint8Array(0),
+        };
+        offer.signature = await deps.sign(who.agentName, buildDocumentJoinOfferTbs(offer));
+        const wire = new Uint8Array(encodeDocumentJoinOffer(offer));
+        const amendHashHex = Buffer.from(amendHash).toString("hex");
+        layer.joins.recordOutgoing(who.ownerAgentId, wire, amendHashHex, deps.now());
+        // The offer to the invitee, then the amendment to every OTHER current holder — both
+        // best-effort at P1, each reported as a fact rather than assumed.
+        let offerSent = false;
+        try {
+            const sent = await deps.transportFor(who.agentName).sendBytes({
+                peerAgentId: invitee, documentId, bytes: wire, correlationId: randomUUID(),
+            });
+            offerSent = sent.ok;
+            if (!sent.ok)
+                logger.warn("document.join.offer_unsent", { documentId, reason: sent.reason });
+        }
+        catch (err) {
+            logger.warn("document.join.offer_send_threw", {
+                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;
+            }
+        }
+        logger.info("document.join.invited", { documentId, invitee, epochId: body.epoch_id, offerSent });
+        return {
+            ok: true,
+            documentId,
+            inviteeAgentId: invitee,
+            amendmentHash: amendHashHex,
+            epochId: body.epoch_id,
+            offerSent,
+            holdersNotified: holdersTold,
+            ...(offerSent
+                ? {}
+                : {
+                    guidance: "The amendment is recorded and the invitation exists, but the offer did not reach " +
+                        "the invitee — they may be offline. Re-run cello_doc_invite with the same invitee " +
+                        "once they are reachable: it re-sends this exact offer rather than authoring a " +
+                        "second amendment.",
+                }),
+        };
+    });
+    /**
+     * DOD-MP-REMOVE-1 — remove a holder, forward-only. Two shapes, one verb: an admin removing a
+     * non-admin holder, and a holder removing THEMSELVES (voluntary leave — always theirs, per
+     * D3). What removal means is exactly and only: delivery to them stops and their new edits
+     * refuse naming the removal. Their copy is theirs forever — no surface claims more. Removing
+     * a fellow ADMIN refuses here the way the policy refuses it everywhere (demote first, under
+     * remove_admin's all-others rule — whose cross-daemon signature gathering is a parked design
+     * note, Entry 10).
+     */
+    handlers.set("cello_doc_remove", async (params, connectionId) => {
+        const who = resolve(params, connectionId);
+        if (isRefusal(who))
+            return who;
+        const documentId = typeof params?.document_id === "string" ? params.document_id : "";
+        const holder = typeof params?.holder_pubkey === "string" ? params.holder_pubkey : "";
+        if (documentId.length === 0) {
+            return { ok: false, reason: "invalid_document_id", guidance: "Pass 'document_id' from cello_doc_list." };
+        }
+        if (!/^[0-9a-f]{64}$/.test(holder)) {
+            return {
+                ok: false,
+                reason: "invalid_holder_pubkey",
+                guidance: "holder_pubkey must be the 64-hex agent id of a current holder.",
+            };
+        }
+        const doc = layer.store.getDocument(who.ownerAgentId, documentId);
+        if (!doc) {
+            return { ok: false, reason: "document_unknown", guidance: `No document ${documentId.slice(0, 16)}… for this agent.` };
+        }
+        const genesisRecord = layer.handshake.get(who.ownerAgentId, documentId);
+        if (!genesisRecord) {
+            return {
+                ok: false,
+                reason: "document_genesis_missing",
+                guidance: "The document has a row but no stored genesis proposal to replay from.",
+            };
+        }
+        const genesisArr = arrangementGenesisFromProposal(genesisRecord.envelope);
+        const chain = layer.amendments.chain(who.ownerAgentId, documentId);
+        const derived = deriveArrangement(genesisArr, chain, documentGovernancePolicy, layer.verifySignature);
+        if (!derived.ok) {
+            return { ok: false, reason: "document_chain_invalid", guidance: derived.reason };
+        }
+        if (!derived.arrangement.participants.has(holder)) {
+            // ALREADY REMOVED is the HEALING path, not a refusal (REMOVE-1 review F3): a holder who
+            // was offline at removal time never learned, and no other verb can ever re-send the
+            // removal amendment — a second cello_doc_remove is the invite-retry precedent. A subject
+            // the chain never touched still refuses.
+            const membership = layer.amendments.membershipOf(who.ownerAgentId, documentId, holder);
+            if (membership.state === "removed") {
+                const removal = chain.find((e) => e.body.kind === "remove_holder" &&
+                    e.body.subject_agent_id === holder &&
+                    e.body.epoch_id === membership.epochId);
+                const 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) {
+                        try {
+                            const sent = await deps.transportFor(who.agentName).sendBytes({
+                                peerAgentId: member, documentId, bytes, correlationId: randomUUID(),
+                            });
+                            resendTold[member] = sent.ok;
+                        }
+                        catch {
+                            resendTold[member] = false;
+                        }
+                    }
+                }
+                return {
+                    ok: true,
+                    documentId,
+                    removedAgentId: holder,
+                    resent: true,
+                    epochId: membership.epochId,
+                    holdersNotified: resendTold,
+                };
+            }
+            return {
+                ok: false,
+                reason: "document_not_holder",
+                guidance: "That agent does not hold this document — there is nobody to remove.",
+            };
+        }
+        const body = {
+            document_id: documentId,
+            epoch_id: derived.arrangement.epoch + 1,
+            prev_amendment_hash: derived.arrangement.lastAmendmentHash,
+            kind: "remove_holder",
+            subject_agent_id: holder,
+            property_change: null,
+            state_hash: null,
+            authored_at_ms: deps.now(),
+        };
+        const amendHash = documentAmendmentHash(body);
+        const multisigTbs = buildDocumentMultisigTbs({
+            document_id: documentId,
+            subject_kind: "document_amendment",
+            subject_hash: amendHash,
+            required_signers: [who.ownerAgentId],
+        });
+        const amendment = {
+            body,
+            collection: {
+                document_id: documentId,
+                subject_kind: "document_amendment",
+                subject_hash: amendHash,
+                required_signers: [who.ownerAgentId],
+                signatures: [
+                    { signer_agent_id: who.ownerAgentId, signature: await deps.sign(who.agentName, multisigTbs) },
+                ],
+            },
+        };
+        // VALIDATE-BEFORE-APPEND — the policy rules here: a non-admin removing someone else, or any
+        // single admin trying to expel a fellow admin through the holder door, refuses with the
+        // policy's own sentence. Voluntary self-leave passes for anyone.
+        const withNew = deriveArrangement(genesisArr, [...chain, amendment], documentGovernancePolicy, layer.verifySignature);
+        if (!withNew.ok) {
+            return { ok: false, reason: "document_amendment_invalid", guidance: withNew.reason };
+        }
+        const amendmentBytes = new Uint8Array(encodeDocumentAmendment(amendment));
+        layer.amendments.append(who.ownerAgentId, documentId, amendmentBytes, deps.now());
+        // 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;
+            }
+        }
+        if (holder !== who.ownerAgentId) {
+            try {
+                const sent = await deps.transportFor(who.agentName).sendBytes({
+                    peerAgentId: holder, documentId, bytes: amendmentBytes, correlationId: randomUUID(),
+                });
+                holdersTold[holder] = sent.ok;
+            }
+            catch {
+                holdersTold[holder] = false;
+            }
+        }
+        logger.info("document.holder_removed", {
+            documentId, holder, epochId: body.epoch_id, voluntary: holder === who.ownerAgentId,
+        });
+        return {
+            ok: true,
+            documentId,
+            removedAgentId: holder,
+            voluntary: holder === who.ownerAgentId,
+            epochId: body.epoch_id,
+            holdersNotified: holdersTold,
+            guidance: "Removal is forward-only: their existing copy and its history remain theirs — new edits " +
+                "simply no longer flow either way.",
+        };
+    });
     handlers.set("cello_doc_refuse", async (params, connectionId) => {
         const who = resolve(params, connectionId);
         if (isRefusal(who))
@@ -482,6 +1004,16 @@ export function registerDocumentHandlers(deps) {
         if (documentId.length === 0) {
             return { ok: false, reason: "invalid_document_id", guidance: "Pass 'document_id' from cello_doc_inbox." };
         }
+        const pendingJoinRefusal = layer.joins
+            .pendingFor(who.ownerAgentId)
+            .find((j) => j.documentId === documentId);
+        if (pendingJoinRefusal) {
+            const refused = await layer.refuseJoin(who.ownerAgentId, pendingJoinRefusal.amendmentHash, reason, deps.now());
+            if (!refused.ok)
+                return { ok: false, reason: refused.reason, guidance: refused.detail };
+            const told = await tellInviter(who, documentId, refused.inviterAgentId, refused.answerBytes);
+            return { ok: true, documentId, joined: false, inviterNotified: told };
+        }
         const proposal = layer.handshake.get(who.ownerAgentId, documentId);
         const outcome = layer.handshake.refuse(who.ownerAgentId, documentId, reason, deps.now());
         if (!outcome.ok)
@@ -498,8 +1030,74 @@ export function registerDocumentHandlers(deps) {
         const who = resolve(params, connectionId);
         if (isRefusal(who))
             return who;
+        // M14B / DOD-MP-JOIN-1 — the inviter's view of every offer they authored: who has answered,
+        // who is still thinking, and the refusal prose when there is one. Without this the answer
+        // arrived, flipped a row, and reached nobody; a refused-but-admitted holder additionally
+        // needs removing (REMOVE-1) and nothing else prompts it.
+        // THE DERIVED ARRANGEMENT, per document (enforcer review G0). Until now nothing surfaced who
+        // holds a document or who governs it: an operator could not answer "who is in this?", and
+        // "all holders derive the same arrangement" — the governance line's headline claim — was
+        // unassertable from outside the process. DERIVED here, never stored: each daemon computes it
+        // from its OWN chain, which is exactly the property worth comparing across machines.
+        const unavailable = (reason) => ({
+            // THE KEYS ARE ALWAYS PRESENT, null on failure. Dropping them made `row.participants`
+            // undefined, which a consumer coerces to [] and reads as "nobody holds this" — a
+            // materially wrong answer to the question this surface exists to answer. `null` cannot
+            // be mistaken for an empty membership; an absent key already was, in this unit's own
+            // enforcer helper.
+            participants: null,
+            admins: null,
+            properties: null,
+            arrangementUnavailable: reason,
+        });
+        const arrangementFor = (documentId, genesisRecord) => {
+            // The SAME name the invite path uses for the same fault, carrying the same sentence —
+            // one condition should not have two names, and the one an operator reads should be the
+            // one that says whose fault it is.
+            if (!genesisRecord) {
+                return unavailable("document_genesis_missing: the document has a row but no stored genesis proposal to " +
+                    "replay from — this is a local-state fault, not the peer's");
+            }
+            // CONTAINED. `chain()` decodes every stored amendment and `documentIdFromProposal` parses
+            // the genesis — both THROW on bytes this build cannot read (a client downgrade past an
+            // amendment kind is the reachable case). Uncontained, that throw escapes the row, escapes
+            // the map, and the operator asking "what documents do I have?" gets NOTHING because one
+            // chain would not decode.
+            try {
+                const derived = deriveArrangement(arrangementGenesisFromProposal(genesisRecord.envelope), layer.amendments.chain(who.ownerAgentId, documentId), documentGovernancePolicy, layer.verifySignature);
+                if (!derived.ok)
+                    return unavailable(derived.reason);
+                return {
+                    participants: [...derived.arrangement.participants].sort(),
+                    admins: [...derived.arrangement.admins].sort(),
+                    properties: derived.arrangement.properties,
+                    // WAS THE ADMIN SET DECLARED, OR DEFAULTED? A genesis from before the admin slot
+                    // existed carries none, and the replay hands both parties admin power. Rendering that
+                    // identically to a declared set would have this surface state as agreed fact something
+                    // the code decided — so it says which it is.
+                    adminSetDefaulted: genesisRecord.envelope.properties.admin_set === undefined,
+                };
+            }
+            catch (err) {
+                return unavailable(`document_chain_undecodable: ${err instanceof Error ? err.message : String(err)}`);
+            }
+        };
+        const outgoingJoins = layer.joins.outgoingFor(who.ownerAgentId).map((j) => ({
+            documentId: j.documentId,
+            inviteeAgentId: j.inviteeAgentId,
+            state: j.state,
+            ...(j.reason ? { reason: j.reason } : {}),
+            ...(j.state === "refused"
+                ? {
+                    guidance: "The invitee declined but the admitting amendment is already in the chain — they " +
+                        "count as a holder until removed. The removal verb ships in the next unit of this " +
+                        "milestone; nothing needs doing meanwhile.",
+                }
+                : {}),
+        }));
         return {
             ok: true,
+            ...(outgoingJoins.length > 0 ? { joinOffers: outgoingJoins } : {}),
             documents: layer.lifecycle.list(who.ownerAgentId, deps.now()).map((d) => {
                 // WHOSE OFFER WAS IT, and has the other side actually shown up?
                 //
@@ -527,6 +1125,10 @@ export function registerDocumentHandlers(deps) {
                     // in it is a fine state; it is just not the same state.
                     peerHasPublished: layer.store.knownEnvelopeHashesBySender(who.ownerAgentId, d.documentId, d.peerAgentId).size > 0,
                     consentState: proposal?.consentState ?? null,
+                    // 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),
                     // 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,
@@ -1096,11 +1698,12 @@ export function registerDocumentHandlers(deps) {
             documentId,
             status,
             peerNotified: outcome.peerNotified,
+            holdersNotified: outcome.holdersNotified,
             ...(outcome.peerNotified
                 ? {}
                 : {
                     reason: outcome.notifyReason,
-                    guidance: notifyGuidance("close", outcome.notifyReason, outcome.notifyDetail),
+                    guidance: notifyGuidance("close", outcome.notifyReason, outcome.notifyDetail, outcome.holdersNotified),
                 }),
         };
     });
@@ -1113,7 +1716,7 @@ export function registerDocumentHandlers(deps) {
      * DOD-DOC-TOOLS-1 review: an exit-point label standing in for a local fault, pointing at the
      * network.
      */
-    function notifyGuidance(verb, reason, detail) {
+    function notifyGuidance(verb, reason, detail, holdersNotified) {
         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.`;
@@ -1126,6 +1729,46 @@ export function registerDocumentHandlers(deps) {
             return (`Your ${verb} was recorded, but this daemon does not hold the agent that owns the document, ` +
                 `so it could not tell the peer. That is a local wiring fault, not the peer being away. ${tail}`);
         }
+        // THE FOUR DERIVATION FAULTS (DOD-MP-CONTROL-N-1). Every one of these is a fact about THIS
+        // machine's record of the document, and not one of them is fixed by the counterparty coming
+        // online — which is what the generic sentence below tells the operator to wait for. That is the
+        // exact defect this function's header says it was written to remove, reintroduced by four new
+        // reasons that were never added to it.
+        if (reason === "document_holders_underivable" || reason === "document_genesis_missing") {
+            return (`Your ${verb} was recorded, but this daemon could not work out who currently holds the ` +
+                `document, so it sent nothing to anyone. Waiting will not help — the signed history on this ` +
+                `machine is the problem, not the network. Look for a "document.holders.underivable" line in ` +
+                `the daemon log, which names the specific cause. ${tail}`);
+        }
+        if (reason?.startsWith("document_chain_undecodable")) {
+            return (`Your ${verb} was recorded, but this build cannot read part of the document's signed ` +
+                `history${detail ? ` (${detail})` : ""}, so it could not work out who to tell. That is ` +
+                `usually a client older than the document — upgrading is the fix, not waiting. ${tail}`);
+        }
+        if (reason === "document_no_holders") {
+            return (`Your ${verb} was recorded, and there is nobody left to tell — the signed history shows no ` +
+                `other current holder of this document. Nothing is pending and nothing needs retrying.`);
+        }
+        // PARTIAL FAN-OUT is its own case and reads nothing like "the peer is offline". With three
+        // holders, two hearing you and one not is the ordinary outcome, and the operator needs to know
+        // WHICH one is still editing a document they think is live — a message saying "the peer" names
+        // nobody when there are several.
+        const missed = Object.entries(holdersNotified ?? {}).filter(([, told]) => !told).map(([h]) => h);
+        const reached = Object.values(holdersNotified ?? {}).filter(Boolean).length;
+        if (missed.length > 0 && reached > 0) {
+            return (`Your ${verb} was recorded and reached ${reached} of ${reached + missed.length} other ` +
+                `holders, but not ${missed.join(", ")} — they will keep editing a document the rest of you ` +
+                `have ended. ${tail}`);
+        }
+        if (missed.length > 0) {
+            // EVERY holder failed. This used to fall through to the generic sentence, which says "the
+            // peer" and names nobody — unusable when there are several, and the per-holder transport
+            // reasons live only in the log. It also arrives with no `reason` field at all, because the
+            // notifier returned ok: signing and addressing both worked, the sends did not.
+            return (`Your ${verb} was recorded but reached none of the ${missed.length} other ` +
+                `holder${missed.length > 1 ? "s" : ""} (${missed.join(", ")}), so the document cannot ` +
+                `settle until they hear it. They are most likely offline. ${tail}`);
+        }
         return (`Your ${verb} was recorded but did not reach the peer${detail ? ` (${detail})` : ""}, so the ` +
             `document cannot settle until they hear it. ${tail}`);
     }
@@ -1148,12 +1791,13 @@ export function registerDocumentHandlers(deps) {
             ok: true,
             documentId,
             peerNotified: outcome.peerNotified,
+            holdersNotified: outcome.holdersNotified,
             note: outcome.note,
             ...(outcome.peerNotified
                 ? {}
                 : {
                     reason: outcome.notifyReason,
-                    guidance: notifyGuidance("kill", outcome.notifyReason, outcome.notifyDetail),
+                    guidance: notifyGuidance("kill", outcome.notifyReason, outcome.notifyDetail, outcome.holdersNotified),
                 }),
         };
     });