@cello-protocol/daemon 0.0.227 → 0.0.229

package/dist/channel-log-store.js

@@ -0,0 +1,290 @@
+import { extractErrorMessage } from "./error-message.js";
+import { encodeBroadcastArtifact, decodeBroadcastArtifact, verifyBroadcastArtifact, encodeRelayPostReceipt, decodeRelayPostReceipt, verifyRelayPostReceipt, } from "@cello-protocol/protocol-types";
+export const CHANNEL_LOG_CREATE_SQL = `
+  -- \`post_cbor\` is AUTHORITATIVE: every read path decodes it. \`published_at\` and \`title\` are lifted
+  -- out of the signed bytes so a digest or an index query does not have to decode every row, and a
+  -- reader that needs certainty must still go through \`post_cbor\`.
+  CREATE TABLE IF NOT EXISTS channel_log (
+    channel_pubkey   TEXT    NOT NULL,
+    seq              INTEGER NOT NULL,
+    published_at     INTEGER NOT NULL,
+    title            TEXT    NOT NULL,
+    post_cbor        BLOB    NOT NULL,
+    PRIMARY KEY (channel_pubkey, seq)
+  );
+  CREATE TABLE IF NOT EXISTS channel_log_receipts (
+    channel_pubkey   TEXT    NOT NULL,
+    seq              INTEGER NOT NULL,
+    relay_pubkey     TEXT    NOT NULL,
+    received_at      INTEGER NOT NULL,
+    receipt_cbor     BLOB    NOT NULL,
+    PRIMARY KEY (channel_pubkey, seq, relay_pubkey)
+  );
+  CREATE TABLE IF NOT EXISTS channel_state (
+    channel_pubkey   TEXT    NOT NULL PRIMARY KEY,
+    next_seq         INTEGER NOT NULL,
+    pruned_through   INTEGER NOT NULL DEFAULT 0
+  );
+`;
+export class ChannelLogError extends Error {
+    code;
+    constructor(code, message) {
+        super(`${code}: ${message}`);
+        this.name = "ChannelLogError";
+        this.code = code;
+    }
+}
+const hexOf = (b) => Buffer.from(b).toString("hex");
+export class ChannelLogStore {
+    #db;
+    #logger;
+    constructor(db, logger) {
+        this.#db = db;
+        this.#logger = logger;
+        this.#db.exec(CHANNEL_LOG_CREATE_SQL);
+    }
+    /** Idempotent: creates the state row {next_seq 1, pruned_through 0}. */
+    ensureChannel(channelPubkeyHex) {
+        this.#db
+            .prepare(`INSERT OR IGNORE INTO channel_state (channel_pubkey, next_seq, pruned_through) VALUES (?, 1, 0)`)
+            .run(channelPubkeyHex);
+    }
+    /** What the NEXT append will be assigned — the publisher signs with this before appending. */
+    nextPosition(channelPubkeyHex) {
+        return { seq: Number(this.#state(channelPubkeyHex).next_seq) };
+    }
+    /** Append an already-signed post. Throws ChannelLogError — never silently skips. */
+    append(channelPubkeyHex, post, correlationId) {
+        this.#state(channelPubkeyHex);
+        this.#db.exec("BEGIN IMMEDIATE");
+        try {
+            // The position check runs UNDER the write lock: a second daemon on this DB could otherwise
+            // append between the read and the insert, and both posts would claim one number.
+            const nextSeq = Number(this.#state(channelPubkeyHex).next_seq);
+            if (post.seq !== nextSeq) {
+                throw new ChannelLogError("seq_not_next", `post seq ${post.seq}, next is ${nextSeq}`);
+            }
+            // Never trust the in-memory object: it must survive its own wire encoding, and it must carry
+            // both valid signatures — an unsigned post in the log is one a subscriber would reject.
+            let cbor;
+            try {
+                cbor = encodeBroadcastArtifact(post);
+            }
+            catch (err) {
+                throw new ChannelLogError("post_invalid", extractErrorMessage(err));
+            }
+            const decoded = decodeBroadcastArtifact(cbor);
+            if (!decoded.ok) {
+                throw new ChannelLogError("post_invalid", `${decoded.reason}: ${decoded.detail}`);
+            }
+            const verdict = verifyBroadcastArtifact(decoded.artifact);
+            if (!verdict.ok) {
+                throw new ChannelLogError("post_invalid", verdict.reason);
+            }
+            // Verification proves the post was signed by the keys it NAMES — it says nothing about which
+            // channel's log it was handed to. Without this, a post signed by channel A files cleanly under
+            // channel B: every check passes, and B's relay is later refilled with A's posts, which every
+            // subscriber of B rejects for a key mismatch with nothing in B's log saying why.
+            if (hexOf(post.channel_pubkey) !== channelPubkeyHex) {
+                throw new ChannelLogError("post_invalid", `the post is signed by channel ${hexOf(post.channel_pubkey).slice(0, 16)}, not ${channelPubkeyHex.slice(0, 16)}`);
+            }
+            const inserted = this.#db
+                .prepare(`INSERT OR IGNORE INTO channel_log (channel_pubkey, seq, published_at, title, post_cbor)
+           VALUES (?, ?, ?, ?, ?)`)
+                .run(channelPubkeyHex, post.seq, post.published_at, post.title, Buffer.from(cbor));
+            if (Number(inserted.changes) === 0) {
+                throw new ChannelLogError("position_taken", `seq ${post.seq} is already in this channel's log`);
+            }
+            this.#db.prepare(`UPDATE channel_state SET next_seq = ? WHERE channel_pubkey = ?`).run(nextSeq + 1, channelPubkeyHex);
+            this.#db.exec("COMMIT");
+        }
+        catch (err) {
+            this.#rollback(channelPubkeyHex, err);
+            throw err;
+        }
+        this.#logger.info("channel.post.appended", {
+            ...(correlationId !== undefined ? { correlationId } : {}),
+            channel_pubkey: channelPubkeyHex,
+            seq: post.seq,
+            published_at: post.published_at,
+        });
+        return { seq: post.seq };
+    }
+    /**
+     * Store one relay's receipt for a post this log holds. VERIFIES FIRST, against the stored post —
+     * not against whatever the caller passed alongside it — so a receipt for a different post at the
+     * same number is refused rather than filed as proof.
+     *
+     * WHAT THIS DOES NOT CHECK: that `relay_pubkey` is one of the relays this channel actually
+     * publishes to. Any keypair can sign a well-formed receipt for a post it has seen. The relay set
+     * lives with the channel's info record, so that check belongs to the publisher — order 018 —
+     * which knows which two relays it deposited on; here it would have nothing to compare against.
+     */
+    recordReceipt(channelPubkeyHex, receipt, correlationId) {
+        const state = this.#state(channelPubkeyHex);
+        // Same binding check as `append`: the receipt names its channel inside the relay's signature, and
+        // a receipt for another channel filed here would sit in this log looking like proof.
+        if (hexOf(receipt.channel_pubkey) !== channelPubkeyHex) {
+            throw new ChannelLogError("receipt_invalid", `the receipt names channel ${hexOf(receipt.channel_pubkey).slice(0, 16)}, not ${channelPubkeyHex.slice(0, 16)}`);
+        }
+        const post = this.#postAt(channelPubkeyHex, receipt.seq);
+        if (!post) {
+            // A pruned post is NOT an invalid receipt. Reporting one as the other sends an operator to
+            // debug a relay's signing key when the answer is that this log no longer holds the bytes.
+            if (receipt.seq <= Number(state.pruned_through)) {
+                throw new ChannelLogError("post_pruned", `post ${receipt.seq} was pruned (pruned_through is ${Number(state.pruned_through)}); the receipt itself was not checked`);
+            }
+            throw new ChannelLogError("receipt_invalid", `no post at seq ${receipt.seq} in this channel's log`);
+        }
+        if (!verifyRelayPostReceipt(receipt, post)) {
+            throw new ChannelLogError("receipt_invalid", `the receipt does not verify against the post at seq ${receipt.seq}`);
+        }
+        const cbor = encodeRelayPostReceipt(receipt);
+        const inserted = this.#db
+            .prepare(`INSERT OR IGNORE INTO channel_log_receipts (channel_pubkey, seq, relay_pubkey, received_at, receipt_cbor)
+         VALUES (?, ?, ?, ?, ?)`)
+            .run(channelPubkeyHex, receipt.seq, hexOf(receipt.relay_pubkey), receipt.received_at, Buffer.from(cbor));
+        if (Number(inserted.changes) === 0) {
+            // One relay, one post, one stored receipt: the row is keyed on exactly that. A REPEAT of the
+            // same receipt is a no-op and says so. A DIFFERENT one — the same relay re-acking after a
+            // reconnect with a later time — is dropped by the same statement, so reporting it as stored
+            // would put a `received_at` in the log that disagrees with the bytes actually kept.
+            const held = this.receiptsFor(channelPubkeyHex, receipt.seq).find((r) => hexOf(r.relay_pubkey) === hexOf(receipt.relay_pubkey));
+            const identical = held !== undefined && Buffer.from(encodeRelayPostReceipt(held)).equals(Buffer.from(cbor));
+            this.#logger.info("channel.receipt.duplicate", {
+                ...(correlationId !== undefined ? { correlationId } : {}),
+                channel_pubkey: channelPubkeyHex,
+                seq: receipt.seq,
+                relay_pubkey: hexOf(receipt.relay_pubkey),
+                identical,
+                held_received_at: held?.received_at ?? null,
+                offered_received_at: receipt.received_at,
+            });
+            return;
+        }
+        this.#logger.info("channel.receipt.stored", {
+            ...(correlationId !== undefined ? { correlationId } : {}),
+            channel_pubkey: channelPubkeyHex,
+            seq: receipt.seq,
+            relay_pubkey: hexOf(receipt.relay_pubkey),
+            received_at: receipt.received_at,
+        });
+    }
+    /** Every relay's receipt for one post, in relay order. Empty when none were stored. */
+    receiptsFor(channelPubkeyHex, seq) {
+        this.#state(channelPubkeyHex);
+        const rows = this.#db
+            .prepare(`SELECT receipt_cbor FROM channel_log_receipts WHERE channel_pubkey = ? AND seq = ? ORDER BY relay_pubkey ASC`)
+            .all(channelPubkeyHex, seq);
+        return rows.map((r) => {
+            const d = decodeRelayPostReceipt(new Uint8Array(r.receipt_cbor));
+            if (!d.ok) {
+                throw new ChannelLogError("log_row_corrupt", `a stored receipt for seq ${seq} does not decode: ${d.reason}`);
+            }
+            return d.receipt;
+        });
+    }
+    /** Range read, for refilling a relay and for verification. Inclusive, seq order. */
+    readRange(channelPubkeyHex, fromSeq, toSeq) {
+        this.#state(channelPubkeyHex);
+        const rows = this.#db
+            .prepare(`SELECT seq, post_cbor FROM channel_log WHERE channel_pubkey = ? AND seq BETWEEN ? AND ? ORDER BY seq ASC`)
+            .all(channelPubkeyHex, fromSeq, toSeq);
+        return rows.map((r) => this.#decodeRow(Number(r.seq), new Uint8Array(r.post_cbor)));
+    }
+    /**
+     * Delete every post at or below `throughSeq`, with its receipts. The OLDEST END ONLY: a prune
+     * below what is already pruned is refused rather than silently ignored, because a caller that
+     * believes it pruned something it did not would keep re-sending it.
+     */
+    pruneThrough(channelPubkeyHex, throughSeq) {
+        const state = this.#state(channelPubkeyHex);
+        const prunedThrough = Number(state.pruned_through);
+        if (!Number.isSafeInteger(throughSeq) || throughSeq < 0) {
+            throw new ChannelLogError("prune_regression", "throughSeq must be a safe integer >= 0");
+        }
+        if (throughSeq < prunedThrough) {
+            throw new ChannelLogError("prune_regression", `asked to prune through ${throughSeq}, but ${prunedThrough} is already pruned`);
+        }
+        this.#db.exec("BEGIN IMMEDIATE");
+        let pruned;
+        try {
+            pruned = Number(this.#db.prepare(`DELETE FROM channel_log WHERE channel_pubkey = ? AND seq <= ?`).run(channelPubkeyHex, throughSeq).changes);
+            // The receipts go with the posts: they are proof about bytes that no longer exist here.
+            this.#db.prepare(`DELETE FROM channel_log_receipts WHERE channel_pubkey = ? AND seq <= ?`).run(channelPubkeyHex, throughSeq);
+            this.#db.prepare(`UPDATE channel_state SET pruned_through = ? WHERE channel_pubkey = ?`).run(throughSeq, channelPubkeyHex);
+            this.#db.exec("COMMIT");
+        }
+        catch (err) {
+            this.#rollback(channelPubkeyHex, err);
+            throw err;
+        }
+        this.#logger.info("channel.log.pruned", {
+            channel_pubkey: channelPubkeyHex,
+            pruned_through: throughSeq,
+            posts_removed: pruned,
+        });
+        return { pruned };
+    }
+    /**
+     * What this log holds. `pruned_through` is NOT `first_seq`: posts can also be absent because the
+     * log is empty, and a caller that conflated them would report gaps that are not gaps.
+     */
+    head(channelPubkeyHex) {
+        const state = this.#state(channelPubkeyHex);
+        const row = this.#db
+            .prepare(`SELECT MIN(seq) AS first_seq, MAX(seq) AS last_seq FROM channel_log WHERE channel_pubkey = ?`)
+            .get(channelPubkeyHex);
+        return {
+            first_seq: row.first_seq === null ? null : Number(row.first_seq),
+            last_seq: row.last_seq === null ? null : Number(row.last_seq),
+            pruned_through: Number(state.pruned_through),
+        };
+    }
+    #postAt(channelPubkeyHex, seq) {
+        const row = this.#db
+            .prepare(`SELECT post_cbor FROM channel_log WHERE channel_pubkey = ? AND seq = ?`)
+            .get(channelPubkeyHex, seq);
+        if (!row)
+            return null;
+        return this.#decodeRow(seq, new Uint8Array(row.post_cbor));
+    }
+    /**
+     * A stored row that no longer decodes, or no longer carries both valid signatures, is corruption —
+     * never something to skip past or hand to a relay being refilled.
+     */
+    #decodeRow(seq, cbor) {
+        const d = decodeBroadcastArtifact(cbor);
+        if (!d.ok) {
+            throw new ChannelLogError("log_row_corrupt", `stored seq ${seq} does not decode: ${d.reason}`);
+        }
+        const verdict = verifyBroadcastArtifact(d.artifact);
+        if (!verdict.ok) {
+            throw new ChannelLogError("log_row_corrupt", `stored seq ${seq} no longer verifies: ${verdict.reason}`);
+        }
+        return d.artifact;
+    }
+    #rollback(channelPubkeyHex, original) {
+        try {
+            this.#db.exec("ROLLBACK");
+        }
+        catch (rollbackErr) {
+            // Usually harmless: the failing statement already ended the transaction. If it did not, the
+            // handle is still inside one, and the next write fails naming the wrong cause — so say so.
+            this.#logger.warn("channel.log.rollback_failed", {
+                channel_pubkey: channelPubkeyHex,
+                error: extractErrorMessage(rollbackErr),
+                original_error: extractErrorMessage(original),
+            });
+        }
+    }
+    #state(channelPubkeyHex) {
+        const row = this.#db
+            .prepare(`SELECT next_seq, pruned_through FROM channel_state WHERE channel_pubkey = ?`)
+            .get(channelPubkeyHex);
+        if (!row)
+            throw new ChannelLogError("channel_unknown", `no channel log for ${channelPubkeyHex.slice(0, 16)}; call ensureChannel first`);
+        return row;
+    }
+}
+//# sourceMappingURL=channel-log-store.js.map

package/dist/channel-log-store.js.map

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

package/dist/close-commitment.d.ts

@@ -0,0 +1,67 @@
+/**
+ * DOD-M15-CLOSEWAIT-1 — the answer a close gives at COMMITMENT, before notarization.
+ *
+ * ─── What this replaces ────────────────────────────────────────────────────────────────────────
+ *
+ * `cello_close_session` used to block until the seal ceremony finished. Measured 2026-08-17: leaf
+ * submitted 16:48:55, ceremony completed 17:00:01 — **11 minutes 6 seconds of a frozen command.**
+ *
+ * It was working the whole time: the SEAL leaf was submitted, and it was waiting for the
+ * counterparty to close too, escalating to a unilateral seal if they never did. But an operator
+ * watching a dead terminal concluded it was broken and force-abandoned **seventeen sessions** —
+ * which forfeits the exact receipt the wait was earning. A UX failure that destroys the artifact is
+ * worse than the wait it was protecting.
+ *
+ * ─── The contract (Decisions Carried #4, decided before this code) ─────────────────────────────
+ *
+ * ANSWER ON COMMITMENT, NOT ON NOTARIZATION. Nothing about what is signed, by whom, or in what
+ * order changes; only the response stops waiting for it.
+ *
+ * ─── Crash safety, CORRECTED after review ──────────────────────────────────────────────────────
+ *
+ * I wrote that a daemon dying mid-wait is covered because `RestartSealResolver` resolves
+ * `seal_interrupted_pending`. **The conclusion holds; that mechanism is not the one.** During the
+ * background wait the row is still `status = 'active'` — nothing writes `seal_interrupted_pending`
+ * on this path.
+ *
+ * What actually covers it: the boot sweep flips `active → interrupted, interrupted_by = 'local'`,
+ * which is branch (1) of `listRestartOrphanedSessions`, and the resolver seals it from there. Two
+ * preconditions ride along and are worth knowing: `message_count > 0` (a never-messaged session is
+ * a dead handshake and is deliberately not sealed) and `restart_seal_gave_up_at IS NULL` (a session
+ * already exhausted is not retried forever).
+ *
+ * ─── The counterbalance this file exists to hold ───────────────────────────────────────────────
+ *
+ * The danger in answering early is the opposite of the one it fixes: an operator who believes a
+ * COMMITTED session is a SEALED one is worse off than one who is merely kept waiting, because they
+ * will never fetch the receipt. So this response:
+ *
+ *   - carries NO `sealed_root` and NO `sealed` field — there is nothing notarized yet to name;
+ *   - says `seal_status: "committed"`, a word that is not "closed" and not "sealed";
+ *   - names `cello_sealed_receipt` — the TOOL, not the internal IPC method `cello_get_sealed_receipt`.
+ *     The vocabulary audit caught that slip here: naming the wrong one hands the operator a dead
+ *     command. Without the verb at all, "committed" is a status an agent can do nothing with;
+ *   - says the receipt is NOT YET available, so an agent polling immediately does not read an empty
+ *     answer as failure;
+ *   - warns what `force` costs, because that is the move the 11-minute freeze actually provoked.
+ *
+ * ONE definition, exported, used at every call site — a second copy is how two surfaces come to
+ * disagree after one of them is reworded.
+ */
+/** The guidance string for a committed-not-yet-notarized close. */
+export declare function CLOSE_COMMITTED_GUIDANCE(opts: {
+    sessionId: string;
+    deadlineMs: number;
+}): string;
+/**
+ * The full response body for a close that has committed but not yet notarized.
+ *
+ * Deliberately NOT `{ ok: true, sealed_root }`-shaped. `ok: true` is correct — the operation the
+ * caller asked for succeeded, their commitment is durable — but every field that would imply a
+ * finished seal is absent by construction rather than by remembering to omit it.
+ */
+export declare function describeSealCommitted(opts: {
+    sessionId: string;
+    deadlineMs: number;
+}): Record<string, unknown>;
+//# sourceMappingURL=close-commitment.d.ts.map

package/dist/close-commitment.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"close-commitment.d.ts","sourceRoot":"","sources":["../src/close-commitment.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiDG;AAEH,mEAAmE;AACnE,wBAAgB,wBAAwB,CAAC,IAAI,EAAE;IAAE,SAAS,EAAE,MAAM,CAAC;IAAC,UAAU,EAAE,MAAM,CAAA;CAAE,GAAG,MAAM,CAYhG;AAED;;;;;;GAMG;AACH,wBAAgB,qBAAqB,CAAC,IAAI,EAAE;IAC1C,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;CACpB,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAO1B"}

package/dist/close-commitment.js

@@ -0,0 +1,78 @@
+/**
+ * DOD-M15-CLOSEWAIT-1 — the answer a close gives at COMMITMENT, before notarization.
+ *
+ * ─── What this replaces ────────────────────────────────────────────────────────────────────────
+ *
+ * `cello_close_session` used to block until the seal ceremony finished. Measured 2026-08-17: leaf
+ * submitted 16:48:55, ceremony completed 17:00:01 — **11 minutes 6 seconds of a frozen command.**
+ *
+ * It was working the whole time: the SEAL leaf was submitted, and it was waiting for the
+ * counterparty to close too, escalating to a unilateral seal if they never did. But an operator
+ * watching a dead terminal concluded it was broken and force-abandoned **seventeen sessions** —
+ * which forfeits the exact receipt the wait was earning. A UX failure that destroys the artifact is
+ * worse than the wait it was protecting.
+ *
+ * ─── The contract (Decisions Carried #4, decided before this code) ─────────────────────────────
+ *
+ * ANSWER ON COMMITMENT, NOT ON NOTARIZATION. Nothing about what is signed, by whom, or in what
+ * order changes; only the response stops waiting for it.
+ *
+ * ─── Crash safety, CORRECTED after review ──────────────────────────────────────────────────────
+ *
+ * I wrote that a daemon dying mid-wait is covered because `RestartSealResolver` resolves
+ * `seal_interrupted_pending`. **The conclusion holds; that mechanism is not the one.** During the
+ * background wait the row is still `status = 'active'` — nothing writes `seal_interrupted_pending`
+ * on this path.
+ *
+ * What actually covers it: the boot sweep flips `active → interrupted, interrupted_by = 'local'`,
+ * which is branch (1) of `listRestartOrphanedSessions`, and the resolver seals it from there. Two
+ * preconditions ride along and are worth knowing: `message_count > 0` (a never-messaged session is
+ * a dead handshake and is deliberately not sealed) and `restart_seal_gave_up_at IS NULL` (a session
+ * already exhausted is not retried forever).
+ *
+ * ─── The counterbalance this file exists to hold ───────────────────────────────────────────────
+ *
+ * The danger in answering early is the opposite of the one it fixes: an operator who believes a
+ * COMMITTED session is a SEALED one is worse off than one who is merely kept waiting, because they
+ * will never fetch the receipt. So this response:
+ *
+ *   - carries NO `sealed_root` and NO `sealed` field — there is nothing notarized yet to name;
+ *   - says `seal_status: "committed"`, a word that is not "closed" and not "sealed";
+ *   - names `cello_sealed_receipt` — the TOOL, not the internal IPC method `cello_get_sealed_receipt`.
+ *     The vocabulary audit caught that slip here: naming the wrong one hands the operator a dead
+ *     command. Without the verb at all, "committed" is a status an agent can do nothing with;
+ *   - says the receipt is NOT YET available, so an agent polling immediately does not read an empty
+ *     answer as failure;
+ *   - warns what `force` costs, because that is the move the 11-minute freeze actually provoked.
+ *
+ * ONE definition, exported, used at every call site — a second copy is how two surfaces come to
+ * disagree after one of them is reworded.
+ */
+/** The guidance string for a committed-not-yet-notarized close. */
+export function CLOSE_COMMITTED_GUIDANCE(opts) {
+    const minutes = Math.max(1, Math.round(opts.deadlineMs / 60_000));
+    return (`Your SEAL commitment for session ${opts.sessionId} is recorded and the notarization is now ` +
+        `running in the background. The receipt is NOT YET available: the seal completes as soon as the ` +
+        `counterparty also closes, and if they never do it escalates to a unilateral seal after about ` +
+        `${minutes} minutes. Fetch it with cello_sealed_receipt (session_id ${opts.sessionId}) — an ` +
+        `empty answer before then means "still running", not "failed". Do NOT re-close with force:true ` +
+        `to hurry it: forcing ABANDONS the session and forfeits the receipt this is earning, which is ` +
+        `exactly how seventeen sessions were lost when this call used to block. If the daemon restarts ` +
+        `before the seal finishes, it resumes the notarization on its next start.`);
+}
+/**
+ * The full response body for a close that has committed but not yet notarized.
+ *
+ * Deliberately NOT `{ ok: true, sealed_root }`-shaped. `ok: true` is correct — the operation the
+ * caller asked for succeeded, their commitment is durable — but every field that would imply a
+ * finished seal is absent by construction rather than by remembering to omit it.
+ */
+export function describeSealCommitted(opts) {
+    return {
+        ok: true,
+        session_id: opts.sessionId,
+        seal_status: "committed",
+        guidance: CLOSE_COMMITTED_GUIDANCE(opts),
+    };
+}
+//# sourceMappingURL=close-commitment.js.map

package/dist/close-commitment.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"close-commitment.js","sourceRoot":"","sources":["../src/close-commitment.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiDG;AAEH,mEAAmE;AACnE,MAAM,UAAU,wBAAwB,CAAC,IAA+C;IACtF,MAAM,OAAO,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,UAAU,GAAG,MAAM,CAAC,CAAC,CAAC;IAClE,OAAO,CACL,oCAAoC,IAAI,CAAC,SAAS,2CAA2C;QAC7F,iGAAiG;QACjG,+FAA+F;QAC/F,GAAG,OAAO,4DAA4D,IAAI,CAAC,SAAS,SAAS;QAC7F,gGAAgG;QAChG,+FAA+F;QAC/F,gGAAgG;QAChG,0EAA0E,CAC3E,CAAC;AACJ,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,qBAAqB,CAAC,IAGrC;IACC,OAAO;QACL,EAAE,EAAE,IAAI;QACR,UAAU,EAAE,IAAI,CAAC,SAAS;QAC1B,WAAW,EAAE,WAAW;QACxB,QAAQ,EAAE,wBAAwB,CAAC,IAAI,CAAC;KACzC,CAAC;AACJ,CAAC"}

package/dist/close-session-handler.d.ts

@@ -0,0 +1,94 @@
+import { SignalingManager } from "@cello-protocol/transport";
+import type { KeyProvider } from "@cello-protocol/crypto";
+import type { IpcHandler } from "./ipc-server.js";
+import type { SessionNodeManager } from "./session-node-manager.js";
+import { type DiscoveryOutcome } from "./cross-node-negotiation.js";
+import type { Logger, SessionRecord } from "./types.js";
+import type { ConnState } from "./contact-handlers.js";
+import type { SealFlowResult, ActiveSealResult } from "./seal-flows.js";
+import type { SealCompletion, UnilateralResult } from "./seal-coordinator.js";
+import type { DirectoryEndpoint } from "./signaling-connect.js";
+import type { ConsortiumEndpoint } from "./directory-bootstrap.js";
+export interface CloseSessionDeps {
+    handlers: Map<string, IpcHandler>;
+    logger: Logger;
+    sessionNodeManager: SessionNodeManager;
+    /** M12-P14: drain this agent's parked mailbox before judging seal readiness (contentPark.autoRecoverForAgent). */
+    recoverParkedContent?: (agentName: string, trigger: string) => Promise<void>;
+    getConnState: (connectionId: string) => ConnState | undefined;
+    resolveCurrentAgent: (connState: ConnState | undefined, explicitAgent?: string) => string | null;
+    NO_CURRENT_AGENT_RESPONSE: unknown;
+    getKeyProvider: (agentName: string) => KeyProvider | undefined;
+    signalingFor: (agentName: string) => SignalingManager | undefined;
+    sendOver: (agentName: string, frame: Record<string, unknown>) => Promise<{
+        ok: boolean;
+        reason?: string;
+    }>;
+    waitForSignalingConnected: (mgr: SignalingManager, timeoutMs: number) => Promise<boolean>;
+    openVisitingConnection: (agentName: string, agentKeyProvider: KeyProvider, agentPubkeyHex: string, endpoint: DirectoryEndpoint, correlationId: string, nodeId: string) => {
+        mgr: SignalingManager;
+        stop: (reason: string) => Promise<void>;
+    };
+    /**
+     * ASK the directory for a seal certificate this daemon was never pushed
+     * (`DOD-TERMINAL-STATE-DIVERGENCE-1`).
+     *
+     * The `session_sealed` frame is pushed ONCE. If this daemon's stream was down at that instant it
+     * is gone — the re-delivery queue is per-node and clients roam. The session IS notarized and the
+     * counterparty holds a receipt; this side holds a non-terminal row and, without asking, can never
+     * produce one.
+     *
+     * Wired here because THIS is where the operator gets stuck: they run a close, it fails, and the
+     * failure is indistinguishable from "the seal has not happened". Asking turns that into "it
+     * happened, here is your receipt". The directory is not trusted for the answer — the certificate
+     * is re-verified against its FROST signature before anything is recorded.
+     */
+    pullSealCertificate?: (agentName: string, sessionIdHex: string) => Promise<{
+        ok: boolean;
+        reason?: string;
+    }>;
+    /**
+     * Ask the directory where an agent is homed RIGHT NOW. Needed because `crossNodeBrokerBySession`
+     * is in-memory and a restart empties it — and a restart is what makes a session interrupted.
+     */
+    runDiscoveryLookup?: (signaling: SignalingManager, targetHex: string, timeoutMs: number, correlationId: string) => Promise<DiscoveryOutcome>;
+    /** sessionId → the broker node id that brokered this cross-node session. */
+    crossNodeBrokerBySession: Map<string, string>;
+    /**
+     * DOD-M15-CLOSEWAIT-1 review MEDIUM-6: hand a detached seal tail to the daemon so `stop()` can
+     * drain it. Optional so an embedder or a test harness constructs without one — but when it is
+     * absent the tail is genuinely untracked, which is why the daemon always passes it.
+     */
+    registerBackgroundSeal?: (p: Promise<unknown>) => void;
+    /**
+     * DOD-M15-SEAL-FAILED-TERMINAL-1: record/clear the last background ceremony failure, so
+     * `cello_sealed_receipt` can tell a DEAD seal from a slow one.
+     *
+     * REQUIRED, not optional — review HIGH-3. Optionality made a missing wiring silent: deleting the
+     * daemon's `getSealFailure` line left tests, lint and typecheck all green while the whole unit was
+     * inert. There is exactly one composition root, so optionality buys nothing and costs the compiler
+     * the ability to catch a wiring that was never done. (`RestartSealResolverDeps.markGaveUp` makes
+     * the same argument in its own docstring.)
+     */
+    sealFailures: {
+        record: (a: string, s: string, reason: string, at: string, kind: "unresolved" | "threw") => void;
+        clear: (a: string, s: string) => void;
+    };
+    sealKey: (agentName: string, sessionId: string) => string;
+    sealInterruptedInProgress: Set<string>;
+    pendingSealWaiters: Map<string, (completion: SealCompletion) => void>;
+    pendingUnilateralWaiters: Map<string, (r: UnilateralResult) => void>;
+    /** The verified consortium roster, re-resolved at ceremony time. */
+    resolveConsortiumRoster: () => Promise<ConsortiumEndpoint[] | null>;
+    /**
+     * DOD-M12B-INTERRUPTED-ESCALATE-1: how long to wait for the directory's answer to a
+     * `seal_unilateral` request. Default 30_000. Injectable because this wait now sits on the
+     * INTERRUPTED close path too, and a suite that exercises it should not spend half a minute per
+     * case discovering that a stub never answers.
+     */
+    unilateralTimeoutMs?: number;
+    handleSealInterruptedFlow: (sessionId: string, record: SessionRecord, correlationId: string, merkleRootAtInterruption: string, via?: SignalingManager) => Promise<SealFlowResult>;
+    handleActiveSealFlow: (sessionId: string, record: SessionRecord, correlationId: string) => Promise<ActiveSealResult>;
+}
+export declare function registerCloseSessionHandler(deps: CloseSessionDeps): void;
+//# sourceMappingURL=close-session-handler.d.ts.map

package/dist/close-session-handler.d.ts.map

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