@cello-protocol/daemon 0.0.227 → 0.0.229

package/dist/seal-upgrade.js

@@ -0,0 +1,200 @@
+/**
+ * The returning-absent-party seal upgrade. It lives outside daemon.ts so the KERNEL (content-
+ * possession gate) and the dual-attestation verify run under adversarial unit tests with the REAL
+ * bodies, not just the happy path.
+ *
+ * When the previously-ABSENT party B returns, it RATIFIES the existing unilateral sealed root R1 (it
+ * does NOT re-seal a new root). B signs an ack over CBOR([SEAL_UPGRADE_ACK_DOMAIN, session_id,
+ * sealed_root]) with its K_local. The directory verifies it and writes a SUPERSEDING bilateral
+ * notarization. Both parties verify the dual-attestation cert before accepting bilateral.
+ */
+import { encodeCbor } from "@cello-protocol/protocol-types";
+import { verify as ed25519Verify } from "@cello-protocol/crypto";
+import { verifyUnilateralCertificate } from "./session-ceremony.js";
+import { extractErrorMessage } from "./error-message.js";
+/**
+ * Domain separator for the upgrade-ack TBS. B's daemon and the directory MUST build byte-identical
+ * bytes — same domain string, same cbor-x encoder options (tagUint8Array:false); the directory side
+ * must be kept byte-identical. Domain separation prevents replay as any other CELLO signature.
+ */
+export const SEAL_UPGRADE_ACK_DOMAIN = "cello-seal-upgrade-ack-v1";
+/** The exact upgrade-ack TBS B signs / the directory + present party verify. */
+export function buildSealUpgradeAckTbs(sessionId, sealedRoot) {
+    return encodeCbor([SEAL_UPGRADE_ACK_DOMAIN, sessionId, sealedRoot]);
+}
+function toU8(v) {
+    return v instanceof Uint8Array ? v : Buffer.isBuffer(v) ? new Uint8Array(v) : null;
+}
+/**
+ * THE KERNEL DECISION. B may sign its ratification ONLY when it genuinely possesses + integrity-
+ * verified the content behind R1. A session B has no record of (content_unrecoverable) or whose
+ * content it could not verify is REFUSED. Verified-but-disliked content is NOT a refusal —
+ * disagreement ≠ unverifiable.
+ *
+ * ⚠️ THE REFUSAL IS THE SAME FOR BOTH CAUSES; ONLY THE NAME DIFFERS. Never ratify content you could
+ * not verify — that is binary and it is the kernel. But `content_tamper` is a SECURITY claim, and
+ * emitting it for an honest peer on a newer build is the defect this split exists to remove: an
+ * alarm that fires on the benign case teaches an operator to dismiss the one that matters.
+ */
+export function evaluateSealUpgrade(readiness) {
+    if (!readiness.known)
+        return { proceed: false, refuseReason: "content_unrecoverable" };
+    if (readiness.unverifiable === "tampered")
+        return { proceed: false, refuseReason: "content_tamper" };
+    if (readiness.unverifiable)
+        return { proceed: false, refuseReason: "content_verification_unavailable" };
+    return { proceed: true };
+}
+/**
+ * THE KERNEL, wired. Recover content → consult the gate → REFUSE (no signature, no request) on
+ * content_unrecoverable / content_tamper → else sign the ack over R1 with B's OWN K_local and send
+ * seal_upgrade_request. Returns whether a request was sent (and the refuse reason if not) so a unit
+ * test asserts the gate is genuinely consulted, not bypassed. Never throws.
+ */
+export async function attemptSealUpgrade(deps, sessionIdHex, frame) {
+    try {
+        const sessionId = toU8(frame["session_id"]);
+        const sealedRoot = toU8(frame["sealed_root"]);
+        const leafCount = typeof frame["leaf_count"] === "number" ? frame["leaf_count"] : null;
+        if (!sessionId || !sealedRoot || leafCount === null) {
+            deps.logger.warn("session.seal.upgrade.refused", { sessionId: sessionIdHex, reason: "malformed_notification" });
+            return { sent: false, reason: "malformed_notification" };
+        }
+        // B (responder) CANNOT channel-independently verify the unilateral cert's signature — that is the
+        // INITIATOR's group key, which B does not hold. B accepts R1 on the AUTHENTICATED daemon↔directory
+        // Noise channel (as the responder accepts session_sealed). Its real protection is the gate below;
+        // a wrong R1 yields a B-ack that doesn't match A's real seal → no coherent bilateral forms.
+        // Recover any parked content so B holds everything behind R1, THEN gate.
+        await deps.recoverContent(deps.agentName).catch(() => { });
+        const decision = evaluateSealUpgrade(deps.getReadiness(deps.agentName, sessionIdHex));
+        if (!decision.proceed) {
+            /**
+             * KERNEL refusal. ERROR is reserved for the SECURITY case (review F-A): `content_tamper` is
+             * the only one of the three that says someone altered something. A version skew and a missing
+             * salt are WARN — they refuse just as hard, and paging on them would be crying wolf.
+             */
+            const level = decision.refuseReason === "content_tamper" ? "error" : "warn";
+            deps.logger[level]("session.seal.upgrade.refused", {
+                sessionId: sessionIdHex,
+                reason: decision.refuseReason,
+                // The refusal used to carry a bare reason and nothing else, so an operator paging on
+                // `content_tamper` was sent hunting an attacker with no next step. Both fields are now
+                // present for every cause, and neither asserts what the counterparty did.
+                impact: "this side refused to countersign the other party's seal, because it could not verify the content behind it. Nothing was signed. The transcript you already hold is unaffected.",
+                guidance: decision.refuseReason === "content_tamper"
+                    ? "A message on this session failed its integrity check. Look for session.content.cross_check.failed with reason content_hash_mismatch. Do NOT ratify this seal; confirm out of band with your counterparty before starting a new session."
+                    : decision.refuseReason === "content_verification_unavailable"
+                        ? "A message on this session could not be checked — usually their CELLO build is newer than this one, sometimes the salt agreement had not completed. Look for session.content.cross_check.failed just above; its reason names which. Upgrading this daemon and starting a new session is the normal remedy. This is not evidence anyone did anything wrong."
+                        : "This side holds no record of the content behind their seal, so there is nothing to ratify against. Start a new session; nothing was signed.",
+            });
+            return { sent: false, reason: decision.refuseReason };
+        }
+        // KERNEL completeness: B must hold the FULL content behind R1, not merely a tamper-free subset.
+        // R1 = root over [content leaves..., A's SEAL ctrl leaf], so leaf_count counts the content leaves
+        // + 1; B's content tree must hold >= leaf_count-1. Refuse if B recovered an INCOMPLETE transcript —
+        // never over-attest to content B did not fully receive. This count gate is the bar until exact
+        // root-reproduction (canonical-sequence reconciliation) lands.
+        const contentLeaves = deps.getContentLeafCount(deps.agentName, sessionIdHex);
+        if (contentLeaves < leafCount - 1) {
+            deps.logger.warn("session.seal.upgrade.refused", {
+                sessionId: sessionIdHex, reason: "content_incomplete", have: contentLeaves, need: leafCount - 1,
+            });
+            return { sent: false, reason: "content_incomplete" };
+        }
+        // KERNEL passed — sign the ack over R1 with B's OWN K_local and request the upgrade.
+        const keyProvider = deps.getKeyProvider(deps.agentName);
+        if (!keyProvider) {
+            deps.logger.warn("session.seal.upgrade.refused", { sessionId: sessionIdHex, reason: "no_key_provider" });
+            return { sent: false, reason: "no_key_provider" };
+        }
+        const ackTbs = buildSealUpgradeAckTbs(sessionId, sealedRoot);
+        const ackSig = new Uint8Array(await keyProvider.sign(ackTbs));
+        const returningPubkey = new Uint8Array(Buffer.from(deps.agentPubkeyHex, "hex"));
+        const sent = await deps.sendRaw({
+            type: "seal_upgrade_request",
+            session_id: sessionId,
+            returning_pubkey: returningPubkey,
+            ack_signature: ackSig,
+            // forwarded (from the notification cert) so the directory relays it → the present party rebuilds
+            // the seal TBS and verifies its own attestation.
+            leaf_count: leafCount,
+        });
+        if (!sent.ok) {
+            deps.logger.warn("session.seal.upgrade.refused", { sessionId: sessionIdHex, reason: "request_send_failed" });
+            return { sent: false, reason: "request_send_failed" };
+        }
+        deps.logger.info("session.seal.upgrade.requested", { sessionId: sessionIdHex, agentName: deps.agentName });
+        return { sent: true };
+    }
+    catch (err) {
+        deps.logger.warn("session.seal.upgrade.refused", {
+            sessionId: sessionIdHex,
+            reason: extractErrorMessage(err),
+        });
+        return { sent: false, reason: "exception" };
+    }
+}
+/**
+ * Dual-attestation verify. NEVER trust the directory's "bilateral" claim.
+ *
+ *  - ALWAYS verify the RETURNING attestation (B's ack) over R1 — proves B genuinely ratified, catches
+ *    a directory that fabricated or swapped B's signature. The load-bearing check (anyone can do it).
+ *  - If THIS agent is the PRESENT party (A, holds its primary key), ALSO verify the present attestation
+ *    over the rebuilt seal TBS (leaf_count-bound). The responder (B) cannot (no initiator key).
+ *
+ * Returns { ok:false, reason } on any malformed/forged cert — the caller must NOT mark the session
+ * bilateral in that case. Returns the party so the caller can log accurately.
+ */
+export async function verifyUpgradeConfirmedCert(deps, sessionIdHex, frame) {
+    const sessionId = toU8(frame["session_id"]);
+    const sealedRoot = toU8(frame["sealed_root"]);
+    const leafCount = typeof frame["leaf_count"] === "number" ? frame["leaf_count"] : null;
+    const tsRaw = frame["close_timestamp"];
+    const closeTs = typeof tsRaw === "number" ? tsRaw : typeof tsRaw === "bigint" ? Number(tsRaw) : null;
+    const presentPubkey = toU8(frame["present_pubkey"]);
+    const presentSig = toU8(frame["present_signature"]);
+    const presentSigType = frame["present_signature_type"];
+    const returningPubkey = toU8(frame["returning_pubkey"]);
+    const returningSig = toU8(frame["returning_signature"]);
+    if (!sessionId || !sealedRoot || leafCount === null || closeTs === null || !presentPubkey ||
+        !presentSig || !returningPubkey || !returningSig ||
+        (presentSigType !== "frost" && presentSigType !== "single")) {
+        deps.logger.warn("session.seal.upgrade.cert.invalid", { sessionId: sessionIdHex, reason: "malformed_confirmed" });
+        return { ok: false, reason: "malformed_confirmed" };
+    }
+    // Bind the cert's present/returning pubkeys to the REAL participants of OUR session record.
+    // The pair {present, returning} must equal {self, our counterparty}; otherwise a single untrusted
+    // directory could sign the ack with an attacker-chosen key and drive a B-side state transition, or
+    // push a confirmed frame for a session we never had. We must hold the session locally to accept.
+    const presentHex = Buffer.from(presentPubkey).toString("hex");
+    const returningHex = Buffer.from(returningPubkey).toString("hex");
+    const selfHex = deps.agentPubkeyHex;
+    const counterpartyHex = deps.getCounterpartyHex(deps.agentName, sessionIdHex);
+    if (!counterpartyHex) {
+        deps.logger.warn("session.seal.upgrade.cert.invalid", { sessionId: sessionIdHex, reason: "unknown_session" });
+        return { ok: false, reason: "unknown_session" };
+    }
+    const expected = new Set([selfHex, counterpartyHex]);
+    if (presentHex === returningHex || !expected.has(presentHex) || !expected.has(returningHex)) {
+        deps.logger.warn("session.seal.upgrade.cert.invalid", { sessionId: sessionIdHex, reason: "participant_mismatch" });
+        return { ok: false, reason: "participant_mismatch" };
+    }
+    // 1. Returning attestation (the returning party's ack) over R1 — the kernel check. returningPubkey
+    //    is now proven to be a real participant of this session (self or counterparty), not attacker-chosen.
+    const ackTbs = buildSealUpgradeAckTbs(sessionId, sealedRoot);
+    if (!ed25519Verify(returningPubkey, ackTbs, returningSig)) {
+        deps.logger.warn("session.seal.upgrade.cert.invalid", { sessionId: sessionIdHex, reason: "returning_signature_invalid" });
+        return { ok: false, reason: "returning_signature_invalid" };
+    }
+    // 2. Present attestation (A's seal sig) — only the present party holds the key to verify it.
+    const isPresent = selfHex === presentHex;
+    if (isPresent) {
+        const presentResult = await verifyUnilateralCertificate({ persistence: deps.persistence, agentPubkeyHex: deps.agentPubkeyHex, logger: deps.logger }, { sessionId, sealedRoot, leafCount, closeTimestamp: closeTs, frostSignature: presentSig, signatureType: presentSigType });
+        if (!presentResult.ok) {
+            deps.logger.warn("session.seal.upgrade.cert.invalid", { sessionId: sessionIdHex, reason: `present_signature_invalid:${presentResult.reason}` });
+            return { ok: false, reason: `present_signature_invalid:${presentResult.reason}` };
+        }
+    }
+    return { ok: true, party: isPresent ? "present" : "returning" };
+}
+//# sourceMappingURL=seal-upgrade.js.map

package/dist/seal-upgrade.js.map

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

package/dist/sealed-conversation.d.ts

@@ -0,0 +1,36 @@
+import type { DaemonDatabase } from "./sqlcipher-db.js";
+import type { Logger } from "./types.js";
+export interface SealedLeaf {
+    /** The relay's sequence number (from 1). Null only for a message the relay never numbered. */
+    seq: number | null;
+    /** `unknown` only when this side holds no signed record of the leaf's kind. */
+    kind: "message" | "close" | "document" | "refusal" | "unknown";
+    from: string | null;
+    from_pubkey: string | null;
+    /** Messages only. Null when this side holds no text for it. */
+    text?: string | null;
+    content_hash: string;
+    /** When the relay numbered it (ISO 8601), the one independent time in the record. */
+    at: string | null;
+    /** The relay's signature over this position. */
+    relay_ack: string | null;
+    /** Messages only: the recipient's signature that their machine received it. */
+    delivery_ack?: string | null;
+}
+export type RootMismatchReason = "unnumbered_messages" | "sequence_gap" | "no_relay_record" | "root_differs";
+export interface SealedConversation {
+    leaves: SealedLeaf[];
+    closed_by: string[];
+    root_matches_my_transcript: boolean;
+    root_mismatch_reason?: RootMismatchReason;
+}
+export declare function readSealedConversation(db: DaemonDatabase, logger: Logger, a: {
+    agentId: string;
+    agentPubkey: string;
+    sessionId: string;
+    sealedRoot: string;
+    /** Transcript text by local sequence (already redacted for quarantined messages). */
+    texts: ReadonlyMap<number, string>;
+    nameFor: (pubkeyHex: string) => string;
+}): SealedConversation;
+//# sourceMappingURL=sealed-conversation.d.ts.map

package/dist/sealed-conversation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sealed-conversation.d.ts","sourceRoot":"","sources":["../src/sealed-conversation.ts"],"names":[],"mappings":"AAeA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AACxD,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,YAAY,CAAC;AAMzC,MAAM,WAAW,UAAU;IACzB,8FAA8F;IAC9F,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;IACnB,+EAA+E;IAC/E,IAAI,EAAE,SAAS,GAAG,OAAO,GAAG,UAAU,GAAG,SAAS,GAAG,SAAS,CAAC;IAC/D,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACpB,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,+DAA+D;IAC/D,IAAI,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,YAAY,EAAE,MAAM,CAAC;IACrB,qFAAqF;IACrF,EAAE,EAAE,MAAM,GAAG,IAAI,CAAC;IAClB,gDAAgD;IAChD,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,+EAA+E;IAC/E,YAAY,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CAC9B;AAED,MAAM,MAAM,kBAAkB,GAAG,qBAAqB,GAAG,cAAc,GAAG,iBAAiB,GAAG,cAAc,CAAC;AAE7G,MAAM,WAAW,kBAAkB;IACjC,MAAM,EAAE,UAAU,EAAE,CAAC;IACrB,SAAS,EAAE,MAAM,EAAE,CAAC;IACpB,0BAA0B,EAAE,OAAO,CAAC;IACpC,oBAAoB,CAAC,EAAE,kBAAkB,CAAC;CAC3C;AAED,wBAAgB,sBAAsB,CACpC,EAAE,EAAE,cAAc,EAClB,MAAM,EAAE,MAAM,EACd,CAAC,EAAE;IACD,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,EAAE,MAAM,CAAC;IACpB,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;IACnB,qFAAqF;IACrF,KAAK,EAAE,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACnC,OAAO,EAAE,CAAC,SAAS,EAAE,MAAM,KAAK,MAAM,CAAC;CACxC,GACA,kBAAkB,CAiJpB"}

package/dist/sealed-conversation.js

@@ -0,0 +1,171 @@
+/**
+ * The seal answer's conversation — every leaf the seal covers, in the relay's numbering.
+ *
+ * Three stores, each supplying what only it holds:
+ *   - `relay_ack_receipts`: the relay's countersignature for every numbered position, both sides'
+ *     leaves and both closes. This is the spine: one row per position.
+ *   - `session_seal_leaves`: the signed Structure 1 and leaf kind at each position — the AUTHOR.
+ *     Receipts never carry these, so the author must come from here.
+ *   - the transcript and the two acknowledgement tables: text, and the delivery signature for each
+ *     message, whichever side sent it.
+ *
+ * Matching a position to a message is done IN ORDER, never by hash alone: both sides can send
+ * identical bytes ("ok"), and a hash lookup would hand one side's message to the other.
+ */
+import { decodeStructure1 } from "@cello-protocol/protocol-types";
+import { SessionTree } from "./session-tree.js";
+/** Relay leaf kind bytes other than a message (session-relay-client.ts), named for an operator. */
+const NON_MESSAGE_KINDS = { 2: "close", 4: "document", 5: "refusal" };
+export function readSealedConversation(db, logger, a) {
+    const messages = db
+        .prepare(`SELECT l.leaf_index AS idx, l.leaf_hash_hex AS hash, t.direction AS direction
+         FROM session_tree_leaves l
+         JOIN transcript t
+           ON t.agent_id = l.agent_id AND t.session_id = l.session_id AND t.sequence = l.leaf_index
+        WHERE l.agent_id = ? AND l.session_id = ?
+        ORDER BY l.leaf_index ASC`)
+        .all(a.agentId, a.sessionId);
+    // The two relay stores are created by their own classes the first time a session goes through a
+    // relay, not by the session schema, so on a daemon that has never used one they do not exist yet.
+    // That is the same fact as holding no relay record, not a degraded read.
+    const receipts = tableExists(db, "relay_ack_receipts")
+        ? db
+            .prepare(`SELECT sequence_number AS seq, hash_hex AS hash, relay_timestamp AS ts, signature_hex AS sig
+             FROM relay_ack_receipts WHERE agent_pubkey = ? AND session_id = ?
+            ORDER BY sequence_number ASC`)
+            .all(a.agentPubkey, a.sessionId)
+        : [];
+    const signed = new Map();
+    if (tableExists(db, "session_seal_leaves")) {
+        for (const r of db
+            .prepare(`SELECT sequence_number AS seq, leaf_kind AS kind, structure1_cbor AS s1
+           FROM session_seal_leaves WHERE agent_pubkey = ? AND session_id = ?`)
+            .all(a.agentPubkey, a.sessionId)) {
+            // The author is read from the bytes they signed, not from the stored sender column.
+            const d = decodeStructure1(r.s1 instanceof Uint8Array ? r.s1 : new Uint8Array(r.s1));
+            signed.set(r.seq, { author: d.ok ? Buffer.from(d.fields.senderPubkey).toString("hex") : null, kind: r.kind });
+        }
+    }
+    /**
+     * POSITIONS FOR MESSAGES NO RELAY ACKNOWLEDGEMENT REACHED — see `recovered-position.ts`.
+     *
+     * Live 2026-09-15: a laptop slept while the counterparty sent two messages. The relay wrote both
+     * `leaf_deliver` frames onto the dead connection, and the text came later from the mailbox. Reading
+     * acknowledgements alone listed both as unnumbered and reported a mismatch on a correct seal.
+     *
+     * A recovered position is the SENDER's claim, not the relay's, so it fills only a position with no
+     * acknowledgement, carries `relay_ack: null`, and is trusted only as far as the root check below:
+     * the sealed root was computed from relay-signed leaves, so a wrong claim cannot reproduce it. One
+     * that disagrees with an acknowledgement at the same position is reported, never papered over.
+     */
+    const bySeq = new Map();
+    for (const r of receipts)
+        bySeq.set(r.seq, r);
+    let recoveredConflict = false;
+    const recoveredAuthor = new Map();
+    for (const p of db
+        .prepare("SELECT relay_seq AS seq, hash_hex AS hash, sender_hex AS sender FROM session_recovered_positions WHERE agent_id = ? AND session_id = ?")
+        .all(a.agentId, a.sessionId)) {
+        const acked = bySeq.get(p.seq);
+        if (acked === undefined) {
+            bySeq.set(p.seq, { seq: p.seq, hash: p.hash, ts: null, sig: null });
+            recoveredAuthor.set(p.seq, p.sender);
+        }
+        else if (acked.hash !== p.hash)
+            recoveredConflict = true;
+    }
+    const positions = [...bySeq.values()].sort((x, y) => x.seq - y.seq);
+    const acksReceived = ackMap(db, "delivery_acks", a.agentId, a.sessionId);
+    const acksGiven = ackMap(db, "delivery_acks_given", a.agentId, a.sessionId);
+    const messageLeaf = (m, r) => {
+        const received = m.direction !== "sent";
+        const pubkey = (r ? signed.get(r.seq)?.author ?? recoveredAuthor.get(r.seq) : null) ?? (received ? null : a.agentPubkey);
+        return {
+            seq: r?.seq ?? null,
+            kind: "message",
+            from: pubkey ? a.nameFor(pubkey) : null,
+            from_pubkey: pubkey,
+            text: a.texts.get(m.idx) ?? null,
+            content_hash: m.hash,
+            at: r?.ts != null ? new Date(r.ts).toISOString() : null,
+            relay_ack: r?.sig ?? null,
+            delivery_ack: (received ? acksGiven : acksReceived).get(m.hash) ?? null,
+        };
+    };
+    const leaves = [];
+    const unnumbered = [];
+    let next = 0;
+    for (const r of positions) {
+        const s = signed.get(r.seq);
+        let matched = -1;
+        if (s === undefined || NON_MESSAGE_KINDS[s.kind] === undefined) {
+            for (let i = next; i < messages.length; i++) {
+                if (messages[i].hash === r.hash) {
+                    matched = i;
+                    break;
+                }
+            }
+        }
+        if (matched >= 0) {
+            // Any message passed over here was never numbered by the relay.
+            for (let i = next; i < matched; i++)
+                unnumbered.push(messageLeaf(messages[i], null));
+            leaves.push(messageLeaf(messages[matched], r));
+            next = matched + 1;
+        }
+        else {
+            const author = s?.author ?? null;
+            leaves.push({
+                seq: r.seq,
+                kind: s ? (NON_MESSAGE_KINDS[s.kind] ?? "unknown") : "unknown",
+                from: author ? a.nameFor(author) : null,
+                from_pubkey: author,
+                content_hash: r.hash,
+                at: r.ts != null ? new Date(r.ts).toISOString() : null,
+                relay_ack: r.sig,
+            });
+        }
+    }
+    for (let i = next; i < messages.length; i++)
+        unnumbered.push(messageLeaf(messages[i], null));
+    const tree = SessionTree.empty();
+    for (const r of positions)
+        tree.appendLeafHash("msg", r.hash);
+    const computedRoot = tree.rootHex();
+    const reason = positions.length === 0 ? "no_relay_record"
+        : unnumbered.length > 0 ? "unnumbered_messages"
+            : !positions.every((r, i) => r.seq === i + 1) ? "sequence_gap"
+                : recoveredConflict || computedRoot !== a.sealedRoot ? "root_differs"
+                    : undefined;
+    if (reason) {
+        logger.warn("session.sealed_conversation.root_mismatch", {
+            sessionId: a.sessionId,
+            reason,
+            receiptCount: receipts.length,
+            unnumberedMessages: unnumbered.length,
+            computedRoot,
+            sealedRoot: a.sealedRoot,
+            impact: "the seal answer reports that the sealed root does not match this side's record of the conversation",
+        });
+    }
+    return {
+        leaves: [...leaves, ...unnumbered],
+        closed_by: leaves.filter((l) => l.kind === "close").map((l) => l.from ?? "unknown"),
+        root_matches_my_transcript: reason === undefined,
+        ...(reason ? { root_mismatch_reason: reason } : {}),
+    };
+}
+function tableExists(db, name) {
+    return db.prepare("SELECT 1 FROM sqlite_master WHERE type = 'table' AND name = ?").get(name) !== undefined;
+}
+/** Both acknowledgement tables are created by the session schema, so a missing one throws. */
+function ackMap(db, table, agentId, sessionId) {
+    const out = new Map();
+    for (const r of db
+        .prepare(`SELECT content_hash_hex AS hash, signature AS sig FROM ${table} WHERE agent_id = ? AND session_id = ?`)
+        .all(agentId, sessionId)) {
+        out.set(r.hash, Buffer.from(r.sig).toString("hex"));
+    }
+    return out;
+}
+//# sourceMappingURL=sealed-conversation.js.map

package/dist/sealed-conversation.js.map

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

package/dist/sealed-leaf-set.d.ts

@@ -0,0 +1,92 @@
+/**
+ * THE LEAF SET THE DIRECTORY NOTARIZED — recovered from the seal frame, checked against the signed
+ * root, and kept so a message can later be proved to sit under it.
+ *
+ * ─── WHY THIS EXISTS AND WHY THE LOCAL TREE CANNOT DO THE JOB ─────────────────────────────────
+ *
+ * The daemon's `SessionTree` is NOT the tree the certified root covers, and the difference is not a
+ * rounding error:
+ *
+ *   - the certified root is `merkleRoot` over **every** leaf's content hash in the relay's canonical
+ *     order, **control leaves included** (`directory-node.ts` — "THE CERTIFIED ROOT —
+ *     client-reproducible, and the one every signature below binds");
+ *   - `SessionTree` holds **content leaves only**. Nothing appends a SEAL ctrl leaf to it —
+ *     `submitSealLeaf` deliberately computes its root without mutating the durable tree, and the
+ *     inbound handler routes a counterparty ctrl leaf to the auto-acknowledge path, never to an
+ *     append.
+ *
+ * So `SessionTree.rootHex()` equals the SEAL payload's `final_root` (the root over the non-ctrl
+ * leaves, which is what each party signs), and it does **not** equal `sealed_root`. An audit path
+ * built from the local tree therefore lands on a root no certificate names — which is precisely the
+ * "a proof against your own root proves nothing" trap, reached by accident rather than by design.
+ *
+ * ─── WHAT MAKES THE STORED SET TRUSTWORTHY ────────────────────────────────────────────────────
+ *
+ * It is never stored on the directory's word. `recordSealedLeafSet` rebuilds the Merkle root over
+ * the hashes and refuses unless it reproduces the `sealed_root` the FROST signature covers. A
+ * directory that reorders, adds, drops or alters a single leaf produces a different root and the set
+ * is refused — so what lands on disk is, by construction, the leaf set the consortium signed.
+ *
+ * ⚠️ THE PARAGRAPH THAT USED TO SIT HERE OVERSTATED IT, and it is rewritten rather than deleted
+ * because it is what a future reader would have reasoned from. It said: *"the hashes come out of
+ * `structure1_cbor`, each leaf's participant-signed to-be-signed bytes; `reDeriveFrontiers` has
+ * already verified those signatures on this same array before we are called, so the content hashes
+ * are the senders' own, not the directory's."*
+ *
+ * **That holds on the BILATERAL path only.** There, `seal-coordinator.ts` returns outright when
+ * `reDeriveFrontiers` fails, so nothing unverified reaches this module. On the UNILATERAL path
+ * `checkUnilateralFrontier` deliberately never rejects — a forged or cross-session leaf yields
+ * `leaves_invalid`, the frontier is corrected DOWN to zero, and the seal proceeds rather than
+ * dead-ending — and those same leaves are then handed here.
+ *
+ * **What is true on EVERY path is the root comparison below, and it is the load-bearing one.** A
+ * leaf set only lands if it reproduces the FROST-signed `sealed_root`, so forged leaves cannot enter
+ * the store unless they hash to a root the consortium already signed. The per-leaf signature check is
+ * a second, path-dependent line of defence, not the guarantee — and stating it as the guarantee is
+ * exactly the shape `DOD-M15-CLAIM-COMMENTS-1` exists to catch.
+ *
+ * The hashes still come out of `structure1_cbor`, each leaf's to-be-signed bytes — that part was
+ * always accurate, and it is why the hashes are the ones a sender's signature would cover.
+ *
+ * Crypto refs: RFC 6962 §2.1 (Merkle hash trees).
+ */
+import type { SealFrontierLeaf } from "./seal-frontier-verify.js";
+/**
+ * Every leaf's content hash, hex, in the order the directory certified.
+ *
+ * Structure 1 TBS is `[version, content_hash, sender_pubkey, session_id, last_seen_seq, timestamp]`,
+ * plus `last_seen_hash` at index 6 on a v2 claim (020-ACKHASH). Index 1 is the content hash in both,
+ * and it is the same value the directory feeds to `buildMerkleTree`. Decoded here rather than taken
+ * from any other field so the hashes are the ones the sender's signature actually covers.
+ *
+ * Returns null on ANY undecodable or wrong-width leaf rather than skipping it. Skipping would build
+ * a SHORTER leaf set that still hashes to something, and that something would then be compared to
+ * the certified root — a comparison that fails for the right reason today and would silently start
+ * passing the moment a dropped leaf happened to be the last one.
+ */
+export declare function sealedLeafHashesFromSignedLeaves(leaves: readonly SealFrontierLeaf[]): string[] | null;
+/** Why a candidate leaf set was not accepted as the notarized one. */
+export declare const SEALED_LEAF_SET_REASONS: {
+    /** A leaf's Structure 1 bytes did not decode, or carried no 32-byte content hash. */
+    readonly LEAVES_MALFORMED: "sealed_leaves_malformed";
+    /** The Merkle root over these hashes is not the root the certificate is signed over. */
+    readonly ROOT_DISAGREES: "sealed_leaves_root_disagrees";
+};
+export type SealedLeafSetReason = (typeof SEALED_LEAF_SET_REASONS)[keyof typeof SEALED_LEAF_SET_REASONS];
+export type SealedLeafSetResult = {
+    ok: true;
+    leafHashes: string[];
+} | {
+    ok: false;
+    reason: SealedLeafSetReason;
+    detail: string;
+};
+/**
+ * Recover the certified leaf set from the seal frame's signed leaves, and prove it against the
+ * certified root before handing it back.
+ *
+ * The root comparison is the ONLY thing that makes the result usable, so it is not optional and not
+ * a warning: a set that does not reproduce `sealedRootHex` is refused outright.
+ */
+export declare function certifiedLeafSetFrom(leaves: readonly SealFrontierLeaf[], sealedRootHex: string): SealedLeafSetResult;
+//# sourceMappingURL=sealed-leaf-set.d.ts.map

package/dist/sealed-leaf-set.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sealed-leaf-set.d.ts","sourceRoot":"","sources":["../src/sealed-leaf-set.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmDG;AAIH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,2BAA2B,CAAC;AAElE;;;;;;;;;;;;GAYG;AACH,wBAAgB,gCAAgC,CAAC,MAAM,EAAE,SAAS,gBAAgB,EAAE,GAAG,MAAM,EAAE,GAAG,IAAI,CAiBrG;AAED,sEAAsE;AACtE,eAAO,MAAM,uBAAuB;IAClC,qFAAqF;;IAErF,wFAAwF;;CAEhF,CAAC;AAEX,MAAM,MAAM,mBAAmB,GAC7B,CAAC,OAAO,uBAAuB,CAAC,CAAC,MAAM,OAAO,uBAAuB,CAAC,CAAC;AAEzE,MAAM,MAAM,mBAAmB,GAC3B;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,UAAU,EAAE,MAAM,EAAE,CAAA;CAAE,GAClC;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,mBAAmB,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC;AAE/D;;;;;;GAMG;AACH,wBAAgB,oBAAoB,CAClC,MAAM,EAAE,SAAS,gBAAgB,EAAE,EACnC,aAAa,EAAE,MAAM,GACpB,mBAAmB,CAmBrB"}