@cello-protocol/daemon 0.0.227 → 0.0.228

package/dist/document-reconcile-engine.js

@@ -0,0 +1,225 @@
+/**
+ * SYNC-P3 (R10, R17–R20, R36) — the responder half of the reconcile exchange.
+ *
+ * Given a peer's position for one document, decide from OUR OWN state alone whether they may be
+ * answered at all (the four entitlement classes, R17), and if so compute exactly what they lack:
+ * governance entries first, then content envelopes, never anything in their refusal set (R36).
+ * The reply carries our own position so the initiator can send step 3 if WE are behind — the
+ * exchange is symmetric by construction.
+ *
+ * Everything here is derived at the moment of the exchange from the entry set and the envelope
+ * log. There is no per-peer record consulted and none written (R8/R9): asked twice, we answer
+ * twice, identically — idempotence is not bookkeeping, it is the absence of bookkeeping.
+ */
+import { decodeDocumentAmendment, documentAmendmentHash, encodeDocumentUpdateEnvelope, DOCUMENT_UPDATE_ENCODING_V1, } from "@cello-protocol/protocol-types";
+/** Our own position for one document — step 1's payload, and the position half of every reply. */
+export function buildReconcileBlock(reads, documentId) {
+    const governance = [...reads.watermarks(documentId)]
+        .map(([author, mark]) => ({
+        author,
+        seq: mark.seq,
+        head_hashes: [...mark.headHashes].sort(),
+    }))
+        .sort((a, b) => (a.author < b.author ? -1 : 1));
+    const content = contentPositions(reads.envelopeLog(documentId));
+    return {
+        document_id: documentId,
+        governance,
+        content,
+        refused: [...reads.refusedHashes(documentId)].sort(),
+        entries: [],
+        envelopes: [],
+    };
+}
+function contentPositions(log) {
+    const bySender = new Map();
+    for (const row of log) {
+        const rows = bySender.get(row.senderAgentId);
+        if (rows)
+            rows.push(row);
+        else
+            bySender.set(row.senderAgentId, [row]);
+    }
+    return [...bySender]
+        .map(([author, rows]) => ({
+        author,
+        count: rows.length,
+        head_hash: rows[rows.length - 1].envelopeHash,
+    }))
+        .sort((a, b) => (a.author < b.author ? -1 : 1));
+}
+/**
+ * Answer a peer's position for one document. The entitlement ruling comes FIRST and from our
+ * own state alone (R18); a refusal rides the BLOCK (never silenced by a batch, review F4), and
+ * a refusal-bearing block carries EMPTY positions — a stranger learns nothing about where this
+ * holder stands. The removed holder is the one refusal that also DELIVERS: their own removal
+ * and its ancestors travel with the terminal ruling (R32), so a holder who was offline at
+ * removal time can derive why the document went quiet.
+ */
+export function respondToReconcile(reads, peerAgentId, peerBlock, budget) {
+    const documentId = peerBlock.document_id;
+    const refusalBlock = (reason, terminal, entries = []) => ({
+        block: {
+            document_id: documentId,
+            governance: [],
+            content: [],
+            refused: [],
+            entries,
+            envelopes: [],
+            refusal: { reason, terminal },
+        },
+        peerAhead: false,
+        truncated: false,
+    });
+    const derived = reads.deriveState(documentId);
+    if (!derived.ok) {
+        return refusalBlock(`document_reconcile_underivable: ${derived.reason}`, false);
+    }
+    const state = derived.state;
+    // R17 — the four classes, from OUR state, never a stored flag.
+    const isParticipant = state.participants.has(peerAgentId);
+    const isInvited = state.invited.has(peerAgentId);
+    if (!isParticipant && !isInvited) {
+        if (reads.standingOf(documentId, peerAgentId) === "removed") {
+            // R32: the ruling is terminal, but it DELIVERS — the removal entry and its ancestors,
+            // so the removed holder can derive their own removal, surface it with its reason, and
+            // stop asking. Idempotent like everything here: asking again gets the same closure.
+            const closure = reads.removalClosure(documentId, peerAgentId) ?? [];
+            return refusalBlock(`document_reconcile_removed: this holder was removed — the removal is forward-only ` +
+                `(the copy is theirs); the removal entry and its ancestors are attached so their own ` +
+                `derivation can say so, and there is nothing further to reconcile`, true, closure);
+        }
+        // R18 + R19: refused by name, NON-terminal, and the sentence says why it is not final — a
+        // legitimate joiner is exactly this refusal whenever their inviter's admission has not yet
+        // reached us, and a terminal answer here would strand them (the failure R19 names).
+        return refusalBlock(`document_reconcile_stranger: ${peerAgentId} is not a party to this document AS THIS ` +
+            `HOLDER CURRENTLY DERIVES IT — non-terminal: if you were admitted, the admission may ` +
+            `not have reached us yet; reconcile again after your inviter's entries spread`, false);
+    }
+    const peerRefused = new Set(peerBlock.refused);
+    const block = buildReconcileBlock(reads, documentId);
+    let truncated = false;
+    const spend = (wire) => {
+        if (!budget)
+            return true;
+        if (budget.remainingBytes < wire.length) {
+            truncated = true;
+            return false;
+        }
+        budget.remainingBytes -= wire.length;
+        return true;
+    };
+    // Governance difference — R12 says these apply first, so they are FIRST in the frame.
+    const peerGov = new Map(peerBlock.governance.map((g) => [g.author, g]));
+    const entries = [];
+    for (const mine of block.governance) {
+        const theirs = peerGov.get(mine.author);
+        // Behind: everything past their contiguous seq. Fork at the SAME seq (heads differ):
+        // re-offer from one before the fork point, so both branches reach them and their fold —
+        // like ours — rules on the fork (the Entry 48 §3 detection path).
+        let fromSeq = null;
+        if (!theirs)
+            fromSeq = 0;
+        else if (theirs.seq < mine.seq)
+            fromSeq = theirs.seq;
+        else if (theirs.seq === mine.seq &&
+            [...theirs.head_hashes].sort().join(",") !== mine.head_hashes.join(",")) {
+            fromSeq = Math.max(0, mine.seq - 1);
+        }
+        if (fromSeq === null)
+            continue;
+        for (const wire of reads.entriesByAuthorAfter(documentId, mine.author, fromSeq)) {
+            const hash = Buffer.from(documentAmendmentHash(decodeDocumentAmendment(wire).body)).toString("hex");
+            if (peerRefused.has(hash))
+                continue; // R36: nothing refused is ever re-offered
+            if (!spend(wire))
+                break;
+            entries.push(wire);
+        }
+        if (truncated)
+            break;
+    }
+    // Content difference — the sender-chain suffix past the peer's count, re-encoded losslessly
+    // from the log rows (the join-offer snapshot precedent). Refused rows carry no payload and
+    // cannot be re-offered; the hole they leave is named by OUR refusal set in the block.
+    const peerContent = new Map(peerBlock.content.map((c) => [c.author, c]));
+    const log = reads.envelopeLog(documentId);
+    const bySender = new Map();
+    for (const row of log) {
+        const rows = bySender.get(row.senderAgentId);
+        if (rows)
+            rows.push(row);
+        else
+            bySender.set(row.senderAgentId, [row]);
+    }
+    const envelopes = [];
+    for (const [author, rows] of [...bySender].sort((a, b) => (a[0] < b[0] ? -1 : 1))) {
+        if (truncated)
+            break;
+        const theirs = peerContent.get(author);
+        const from = theirs ? theirs.count : 0;
+        for (const row of rows.slice(from)) {
+            if (row.kind !== "update" || row.payload === null)
+                continue;
+            if (peerRefused.has(row.envelopeHash))
+                continue;
+            const wire = new Uint8Array(encodeDocumentUpdateEnvelope({
+                type: "document_update",
+                document_id: row.documentId,
+                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,
+                governance_parents: [...row.governanceParents],
+                update: row.payload,
+                signature: row.signature,
+            }));
+            if (!spend(wire))
+                break;
+            envelopes.push(wire);
+        }
+    }
+    // Is the PEER ahead of us anywhere? Then the initiator owes step 3.
+    const myGov = new Map(block.governance.map((g) => [g.author, g]));
+    const myContent = new Map(block.content.map((c) => [c.author, c]));
+    const peerAhead = peerBlock.governance.some((g) => {
+        const mine = myGov.get(g.author);
+        if (!mine)
+            return g.seq > 0;
+        if (g.seq > mine.seq)
+            return true;
+        return (g.seq === mine.seq &&
+            [...g.head_hashes].sort().join(",") !== mine.head_hashes.join(","));
+    }) ||
+        peerBlock.content.some((c) => {
+            const mine = myContent.get(c.author);
+            return mine ? c.count > mine.count : c.count > 0;
+        });
+    // A peer whose position is EMPTY holds nothing — a joiner (spec §4: "simply very far
+    // behind"). Hand them the anchor everything derives from; it is the one record that is not an
+    // entry, and the bootstrap on their side is idempotent.
+    const peerHoldsNothing = peerBlock.governance.length === 0 && peerBlock.content.length === 0;
+    const genesis = peerHoldsNothing ? reads.genesisBytes(documentId) : null;
+    // SYNC-R35: our own signed refusal records ride every reply, whole — few by construction
+    // (each one is a retry round), deduplicated on the receiving side, and the only way a THIRD
+    // holder wedged behind a refused hash ever learns its name and reason (P3 review F5/F8).
+    const refusals = [];
+    for (const wire of reads.refusalRecords(documentId)) {
+        if (!spend(wire))
+            break;
+        refusals.push(wire);
+    }
+    return {
+        block: {
+            ...block,
+            entries,
+            envelopes,
+            ...(refusals.length > 0 ? { refusals } : {}),
+            ...(genesis ? { genesis } : {}),
+        },
+        peerAhead,
+        truncated,
+    };
+}
+//# sourceMappingURL=document-reconcile-engine.js.map

package/dist/document-reconcile-engine.js.map

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

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

@@ -0,0 +1,163 @@
+/**
+ * SYNC-P5 (R39–R43) — WHEN reconciling is attempted. The exchange itself (P3) is stateless and
+ * idempotent; this module only decides moments, and every piece of state it holds is VOLATILE
+ * scheduling state in the R41 sense: it may delay an exchange, it must never forbid one, gate
+ * admissibility, or survive a restart as authority. Losing all of it costs at most one sweep
+ * interval of latency.
+ *
+ * The three triggers (R39):
+ *  1. committing an entry / publishing — the layer nudges directly (P4's `nudgeSeats` and the
+ *     entry fan-out); not this module's job.
+ *  2. a party becoming reachable — `onReachable`, wired to session establishment. An explicit
+ *     reachability signal RESETS backoff: the backoff modeled "they do not answer", and here
+ *     they demonstrably just did.
+ *  3. the periodic sweep — `sweep`, wired to a timer. Bounded per R43: batched per party (R16's
+ *     cap is the exchange's own), and — DOD-DOC-PUSH-NOT-POLL-1 — it speaks only for a party we
+ *     HOLD something for. A timer is not a reason to speak.
+ *
+ * R42: the in-flight mark is TIME-BOUNDED and released LOUDLY on expiry. An unbounded in-flight
+ * mark is the stall this milestone already paid for twice.
+ *
+ * DOD-DOC-PUSH-NOT-POLL-1 (Andre, 2026-08-18) — WHAT THE TIMER MAY NO LONGER DO, and what it cost.
+ * The suppressor used to be a BELIEF with an expiry: a party was skipped only while every shared
+ * document read in_sync AND had been exchanged within ten minutes. Past the window it asked again
+ * whether or not anything had changed. Measured live: three agents, thirty documents, the freshest
+ * exchange days old, and one stale timestamp kept a whole party — fourteen documents — sweeping
+ * every 120 seconds forever. Each of those frames takes a position in the CONVERSATION's hash
+ * chain, so a quiet document spends a real conversation's sequence numbers: 34 positions on one
+ * live session, 2 of them actual messages, and the seal refused `session_incomplete`.
+ *
+ * The rule now: WE SPEAK WHEN WE HOLD SOMETHING THE PARTY HAS NOT CONFIRMED RECEIVING, and an
+ * unchanged holding is offered once, not on every tick. Nothing pending, no frame, no position.
+ *
+ * THE GATE IS ON THE DECISION, NOT ON THE FRAME'S CONTENTS (review F2). Once one document has
+ * justified speaking to a party, the frame carries every document shared with them: a block is
+ * POSITIONS ONLY, and the responder replies solely for a document where one side is actually
+ * ahead — so a quiet document rides along for bytes, never for a frame or a position. Narrowing
+ * the list would have dropped the pull for those documents and saved nothing.
+ *
+ * THE TRADE, STATED RATHER THAN HIDDEN: `pendingFor` can only see what we hold that they lack —
+ * never what they hold that we lack — so removing the expiry removes the timer-driven PULL. The
+ * pull moves onto the two triggers that are events rather than clocks: their publish nudges us
+ * (R39 trigger 1), and a session with them coming up sweeps everything (`onReachable`, which
+ * deliberately does NOT inherit the pending gate).
+ *
+ * THE THIRD TRADE, WHICH IS A REMOVAL CASE (review F4). A removed holder is in neither the
+ * participants nor the invited set of the remover's derived state, so the REMOVER never sweeps to
+ * them — there is no push and no nudge in that direction. Their primary notice is the parked frame
+ * the relay holds; when that is gone, the backstop was their own belief expiring and asking, which
+ * earned the terminal `document_reconcile_removed` answer. That backstop now waits for them to
+ * hold something pending — their next write, or their next session. This WIDENS a gap the M14B
+ * board already names (DOD-SYNC-P6, "R32's terminal-refusal delivery is not exercised by the
+ * enforcers"); it does not open a new one, and nothing here forbids the exchange.
+ */
+import type { Logger } from "./types.js";
+/** How long one attempt may hold the in-flight mark before the sweep stops honoring it. */
+export declare const RECONCILE_INFLIGHT_BOUND_MS = 60000;
+/** First back-off step for a party that did not answer; doubles per consecutive failure. */
+export declare const RECONCILE_BACKOFF_BASE_MS = 30000;
+export declare const RECONCILE_BACKOFF_CAP_MS: number;
+/** R16's per-frame batching ceiling, honored by chunking a party's documents. */
+export declare const RECONCILE_BATCH_CAP = 32;
+export interface ReconcileSchedulerDeps {
+    now(): number;
+    logger: Logger;
+    /**
+     * Every (party → shared ACTIVE documents) pair one owner's sweep should consider. DERIVED by
+     * the caller from the fold — the scheduler never decides who is a party.
+     */
+    sweepTargets(ownerAgentId: string): Map<string, string[]>;
+    /**
+     * DOD-DOC-PUSH-NOT-POLL-1 — WHAT we hold on this document that this party has not confirmed
+     * receiving, as a comparable fingerprint; `null` when there is nothing. Derived by the caller
+     * from the same comparison that answers "are they behind" on the list surface — two copies of
+     * that question is two daemons disagreeing about who needs an exchange.
+     *
+     * Compared, never interpreted: the scheduler only asks whether it changed since it last spoke.
+     */
+    pendingFor(ownerAgentId: string, documentId: string, partyAgentId: string): string | null;
+    initiateReconcile(ownerAgentId: string, peerAgentId: string, documentIds: readonly string[]): Promise<{
+        ok: true;
+    } | {
+        ok: false;
+        reason?: string;
+    }>;
+    /**
+     * Test-pace override for the failure backoff (the enforcers' lesson: a restarted daemon's
+     * first attempts can fail while its own signaling settles, and the production 30s-doubling
+     * ladder walks a fast-sweep test out of its window). Omitted = the production constants.
+     */
+    backoffBaseMs?: number;
+}
+export interface SweepResult {
+    attempted: number;
+    /** Held back because this peer FAILED or REFUSED us. Look at the peer. */
+    skippedBackoff: number;
+    skippedInFlight: number;
+    /**
+     * Held back because we had nothing NEW to say — we already offered this exact holding. Kept
+     * apart from `skippedBackoff` (review F5) because this unit exists to make sweep traffic
+     * diagnosable from these very logs, and one counter for two causes sends the reader to the
+     * wrong subsystem.
+     */
+    skippedQuiet: number;
+    /** Nothing pending at all: no frame was owed to this party. */
+    skippedNothingPending: number;
+    failed: number;
+}
+export declare class ReconcileScheduler {
+    #private;
+    constructor(deps: ReconcileSchedulerDeps);
+    /**
+     * DOD-M12B-SHUTDOWN-1 — refuse all further work. Idempotent, and one-way on purpose.
+     *
+     * Clearing the sweep timer stops the NEXT tick and nothing else: the pass already running walks
+     * every agent, and each step dials a peer and opens a session. Measured 2026-08-17 — `cello
+     * logout` reported the daemon down, the socket was already gone, and the process ran on for 30+
+     * seconds still logging `document.reconcile.sweep`, dialling on its way out. It took a signal to
+     * exit. A shutdown that keeps starting new outbound work is not draining.
+     *
+     * Guarded at the top of the two entry points that START work — `sweep` and `onReachable` — so
+     * `sweepTargets`, a database read, is not run either, AND inside the sweep's own party loop so a
+     * pass already running stops at the next party rather than finishing its round. `noteRefusal`
+     * deliberately still runs: it records an outcome and starts nothing.
+     *
+     * Never un-set: a reachability trigger firing from a session tearing down during shutdown must
+     * not be able to restart the sweeper on the way out.
+     */
+    stop(): void;
+    /**
+     * R39's second trigger: this party is demonstrably reachable RIGHT NOW — a session with them
+     * just came up. Backoff is reset (it modeled silence; they answered) and the attempt fires
+     * for every shared document, in R16-capped batches.
+     *
+     * DELIBERATELY EXEMPT FROM THE PENDING GATE (DOD-DOC-PUSH-NOT-POLL-1). The gate can only see
+     * what we hold that they lack; the exchange is the only thing that sees the other direction.
+     * Take the gate off the timer and this becomes where the PULL lives, so gating it here too
+     * would leave nothing that ever asks.
+     *
+     * It DOES record what it just offered (review F3). Nulling that instead cost one guaranteed
+     * duplicate frame per session establishment — the sweep tick minutes later would find no
+     * record of the offer, treat an unchanged holding as new, and spend another position in the
+     * conversation's hash chain. That is the exact currency this unit defends.
+     */
+    onReachable(ownerAgentId: string, peerAgentId: string): Promise<void>;
+    /**
+     * A PEER ANSWERED "NO". That is an answer, and it must slow the asking down.
+     *
+     * `#attempt` can only see whether the FRAME WAS SENT — the refusal arrives later, on its own
+     * inbound frame, and until now it was logged and dropped. So a peer refusing every exchange was
+     * indistinguishable from a peer answering fine: `failures` reset to 0, `nextAttemptMs` to now,
+     * and the sweep asked again immediately. Measured 321 attempts against two documents in 85
+     * minutes, refused every time, zero successes.
+     *
+     * R41 IS PRESERVED: this DELAYS an exchange, it never forbids one. A terminal refusal jumps
+     * straight to the cap rather than retiring the party, because "terminal" is one holder's current
+     * derivation — a later entry can make the same exchange admissible again, and scheduling state
+     * must never be the thing that forbids it. `onReachable` still clears it outright.
+     */
+    noteRefusal(ownerAgentId: string, peerAgentId: string, terminal: boolean): void;
+    /** R39's third trigger — one bounded pass for one owner. */
+    sweep(ownerAgentId: string): Promise<SweepResult>;
+}
+//# sourceMappingURL=document-reconcile-scheduler.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"document-reconcile-scheduler.d.ts","sourceRoot":"","sources":["../src/document-reconcile-scheduler.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoDG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,YAAY,CAAC;AAGzC,2FAA2F;AAC3F,eAAO,MAAM,2BAA2B,QAAS,CAAC;AAClD,4FAA4F;AAC5F,eAAO,MAAM,yBAAyB,QAAS,CAAC;AAChD,eAAO,MAAM,wBAAwB,QAAc,CAAC;AACpD,iFAAiF;AACjF,eAAO,MAAM,mBAAmB,KAAK,CAAC;AAEtC,MAAM,WAAW,sBAAsB;IACrC,GAAG,IAAI,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf;;;OAGG;IACH,YAAY,CAAC,YAAY,EAAE,MAAM,GAAG,GAAG,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,CAAC;IAC1D;;;;;;;OAOG;IACH,UAAU,CAAC,YAAY,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAAC;IAC1F,iBAAiB,CACf,YAAY,EAAE,MAAM,EACpB,WAAW,EAAE,MAAM,EACnB,WAAW,EAAE,SAAS,MAAM,EAAE,GAC7B,OAAO,CAAC;QAAE,EAAE,EAAE,IAAI,CAAA;KAAE,GAAG;QAAE,EAAE,EAAE,KAAK,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAC1D;;;;OAIG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAkBD,MAAM,WAAW,WAAW;IAC1B,SAAS,EAAE,MAAM,CAAC;IAClB,0EAA0E;IAC1E,cAAc,EAAE,MAAM,CAAC;IACvB,eAAe,EAAE,MAAM,CAAC;IACxB;;;;;OAKG;IACH,YAAY,EAAE,MAAM,CAAC;IACrB,+DAA+D;IAC/D,qBAAqB,EAAE,MAAM,CAAC;IAC9B,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,qBAAa,kBAAkB;;gBAOjB,IAAI,EAAE,sBAAsB;IAIxC;;;;;;;;;;;;;;;;OAgBG;IACH,IAAI,IAAI,IAAI;IA+CZ;;;;;;;;;;;;;;OAcG;IACG,WAAW,CAAC,YAAY,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAmB3E;;;;;;;;;;;;;OAaG;IACH,WAAW,CAAC,YAAY,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,EAAE,QAAQ,EAAE,OAAO,GAAG,IAAI;IAe/E,4DAA4D;IACtD,KAAK,CAAC,YAAY,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,CAAC;CAiHxD"}