@cello-protocol/daemon 0.0.183 → 0.0.185

package/dist/session-node-manager.js

@@ -55,6 +55,7 @@ import { AgentRelayClient, LEAF_KIND_CTRL, isTerminalRelayRefusal, extractErrorM
 import { terminalRelayRefusal } from "./session-terminal-refusal.js";
 import { RelayReceiptStore } from "./relay-receipt-store.js";
 import { SessionSealLeafStore } from "./session-seal-leaf-store.js";
+import { certifiedLeafSetFrom } from "./sealed-leaf-set.js";
 import { addColumnIfMissing } from "./column-birth.js";
 import { GATEWAY_UNAVAILABLE, GOVERNANCE_TIMEOUT, } from "@cello-protocol/gateway";
 /** SEC-1 / review M4: cap on the refused-parked-entry memo (remote-fed → must be bounded). */
@@ -365,6 +366,34 @@ export const LEAF_FETCH_GRACE_MS = 2_000;
 function relayPeerIdOf(circuitAddr) {
     return /\/p2p\/([^/]+)\/p2p-circuit/.exec(circuitAddr)?.[1] ?? null;
 }
+/**
+ * The Merkle leaf inputs for a seal carry: each leaf's `content_hash`, read out of the bytes its
+ * SENDER SIGNED (`structure1_cbor`), never out of an envelope field somebody else filled in.
+ *
+ * `null` when any leaf is unreadable — the caller must then answer "I cannot judge", never "we
+ * disagree". A decode failure is this daemon's limitation, not evidence against anyone.
+ *
+ * Canonical Structure 1 is
+ * `[protocol_version, content_hash, sender_pubkey, session_id, last_seen_seq, timestamp]`, and the
+ * content hash is used AS the leaf hash (RFC 6962 §2.1 "hash" leaves are taken as-is), which is the
+ * domain the certified root lives in.
+ */
+function carryContentHashInputs(carry) {
+    const inputs = [];
+    for (const leaf of carry) {
+        let contentHash;
+        try {
+            contentHash = decode(leaf.structure1Cbor)[1];
+        }
+        catch {
+            return null;
+        }
+        if (!(contentHash instanceof Uint8Array) || contentHash.length !== 32)
+            return null;
+        inputs.push({ kind: "hash", data: contentHash });
+    }
+    return inputs;
+}
 export class SessionNodeManager {
     #factory;
     #logger;
@@ -656,6 +685,129 @@ export class SessionNodeManager {
             correlationId,
         });
     }
+    /**
+     * DOD-M15-CORROBORATE-1: witness alerts this agent's relays have reported, oldest first, capped.
+     *
+     * ⚠️ **IN MEMORY, AND A DAEMON RESTART LOSES THEM** — review F4. This comment used to say a relay
+     * that still holds the observation re-delivers it on the next connection. It does not:
+     * `drainWitnessAlerts` splices, so once an alert has been delivered the relay no longer holds it.
+     * Nothing here is a durable record of anything; the relay operator's own log is, and so is the
+     * signature on the alert, which the operator can keep. Said plainly rather than left as an implied
+     * guarantee.
+     *
+     * Nothing clears the list before that restart, and that is deliberate: an alert an operator can
+     * silence is one an attacker can wait out.
+     */
+    #witnessAlerts = new Map();
+    /**
+     * ⚠️ **THE CAP KEEPS THE FIRST, NOT THE LAST** — review F1, and the direction is the whole point.
+     *
+     * The relay's own queue drops the NEWEST when full, precisely so a flood cannot push the first
+     * real observation out. This list did the opposite (`slice(-20)`), which handed the mute button
+     * straight back one layer up: at the relay's 120-submits-per-minute limit, about ten seconds of
+     * fabricated alerts evicted the genuine one before any operator read it. Repeats of one event also
+     * collapse — see the dedupe in `recordRelayWitnessAlert` — so a flood cannot even fill it.
+     */
+    static #WITNESS_ALERT_CAP = 20;
+    /**
+     * Review F7: relays that sent a witness alert this build could not read or verify, per agent.
+     * Peer id → cause + count. NO session and NO party: it reports that our witness layer is not
+     * working, never anything about a participant.
+     */
+    #witnessUnreadable = new Map();
+    /**
+     * Agents whose alert list hit the cap — fallback-finder LOW 2. Without this the inbox renders a
+     * full list that looks complete, and "twenty alerts" is indistinguishable from "twenty of some
+     * larger number". A marker the operator can see costs one boolean.
+     */
+    #witnessTruncated = new Set();
+    /**
+     * Record what one relay says it saw on one of this agent's sessions, for the operator to read.
+     *
+     * ⚠️ **IT DOES NOT FREEZE THE SESSION, AND THAT IS THE DESIGN.** A client freezing on its OWN
+     * verification is safe: it limits only what that client trusts. Freezing on a REMOTE party's
+     * say-so hands any single relay the power to end any conversation it carries, and to write an
+     * accusatory record about a counterparty who did nothing. The identity freeze stays where it is —
+     * on this daemon's own check of an inbound frame — and this surfaces a second, independent
+     * observation next to it. One witness reports; it does not rule.
+     */
+    recordRelayWitnessAlert(agentName, alert) {
+        const list = this.#witnessAlerts.get(agentName) ?? [];
+        /**
+         * ONE ROW PER (WITNESS, SESSION) — review F1's second half. A relay reports every refused
+         * submission, and a determined submitter can produce a great many; twenty rows saying the same
+         * thing is not twenty facts, it is one fact and nineteen ways to push another one off the list.
+         * The repeat updates the count and the last-seen time and leaves the row where it is.
+         */
+        /**
+         * Keyed on the relay's PEER ID, not on `relayId` — fallback-finder LOW 1. `relayId` is absent
+         * for any relay that could not sign, so two DIFFERENT such relays reporting on one session
+         * collapsed into a single row and the operator read one witness where there were two. The peer
+         * id is the transport identity this client is actually talking to and is always known.
+         */
+        const key = `${alert.witnessPeerId}::${alert.sessionIdHex}`;
+        const existing = list.find((n) => n.key === key);
+        if (existing) {
+            existing.occurrences += 1;
+            existing.lastObservedAt = alert.observedAt;
+            // A later repeat that IS verifiable upgrades the row: the operator should end up holding the
+            // strongest form of the claim they were sent, never the weakest one that arrived first.
+            existing.alert = alert.verifiable ? alert : existing.alert;
+            // `firstObservedAt` is deliberately untouched — see its note on the type.
+        }
+        else if (list.length >= SessionNodeManager.#WITNESS_ALERT_CAP) {
+            // Keep the first. See the cap's own note for why this direction is load-bearing.
+            this.#witnessTruncated.add(agentName);
+            this.#logger.warn("session.witness.alert.list_full", {
+                agentName, held: list.length,
+                impact: "this alert was not recorded; the earlier ones are kept and still shown, and the " +
+                    "inbox now says the list is incomplete rather than looking whole",
+            });
+            return;
+        }
+        else {
+            list.push({ key, alert, occurrences: 1, firstObservedAt: alert.observedAt, lastObservedAt: alert.observedAt });
+        }
+        this.#witnessAlerts.set(agentName, list);
+        this.#logger.error("session.witness.alert.recorded", {
+            agentName,
+            sessionId: alert.sessionIdHex,
+            relayId: alert.relayId ?? "(unnamed)",
+            submitterIsCounterparty: alert.submitterIsCounterparty,
+            verifiable: alert.verifiable,
+            impact: "surfaced to the operator on the next cello_inbox; the session is NOT frozen by it",
+        });
+    }
+    /** The witness alerts an agent has been told about, oldest first, one row per witness+session. */
+    getWitnessAlerts(agentName) {
+        return this.#witnessAlerts.get(agentName) ?? [];
+    }
+    /** Whether this agent's alert list hit its cap, so the inbox can say the list is incomplete. */
+    witnessAlertsTruncated(agentName) {
+        return this.#witnessTruncated.has(agentName);
+    }
+    /**
+     * Review F7: a relay sent a witness alert this build could not read or could not verify.
+     *
+     * Recorded so a version skew that silently kills the witness layer is visible to the operator
+     * instead of living only in a log file. Carries no session and no party by construction.
+     */
+    recordRelayWitnessUnreadable(agentName, relayPeerId, why) {
+        const byRelay = this.#witnessUnreadable.get(agentName) ?? new Map();
+        const prior = byRelay.get(relayPeerId);
+        byRelay.set(relayPeerId, { why, count: (prior?.count ?? 0) + 1 });
+        this.#witnessUnreadable.set(agentName, byRelay);
+        this.#logger.error("session.witness.unreadable.recorded", {
+            agentName, relayPeerId, why,
+            impact: "this agent's witness layer is not working against that relay — no observation it " +
+                "sends can be read, and nothing has been concluded about any participant",
+        });
+    }
+    /** Relays whose witness alerts this build could not read, for the agent's inbox. */
+    getWitnessUnreadable(agentName) {
+        return [...(this.#witnessUnreadable.get(agentName) ?? new Map()).entries()]
+            .map(([relayPeerId, v]) => ({ relayPeerId, why: v.why, count: v.count }));
+    }
     /**
      * DOD-M15-RELAYSLOTS-1: the last relay refusal per agent, with the advice that goes with it.
      * Written where the refusal is actually known; read by whatever tells the operator.
@@ -1801,6 +1953,52 @@ export class SessionNodeManager {
         -- DOD-LOOP-1: composite key so each agent's end has its own append-ordered tree.
         PRIMARY KEY (agent_id, session_id, leaf_index)
       )
+    `);
+        // DOD-M15-INCLUSION-1: the leaf set the DIRECTORY certified — a different tree from the one
+        // above, and the distinction is the whole reason this table exists.
+        //
+        // `session_tree_leaves` holds this agent's CONTENT leaves. The certified root covers every leaf
+        // the relay ordered, CONTROL leaves included, and nothing appends a ctrl leaf to the local tree
+        // (`submitSealLeaf` computes its root without mutating it). So an audit path built from
+        // `session_tree_leaves` lands on a root no certificate names — it proves this machine agrees
+        // with itself, which is worth nothing to the third party a proof is FOR.
+        //
+        // Rows land only after the Merkle root over them reproduces the FROST-signed `sealed_root`
+        // (`certifiedLeafSetFrom`), so what is stored here is the consortium's leaf set and not the
+        // directory's word for it. Written once at seal time; read only by the inclusion-proof surface,
+        // ORDER BY leaf_index.
+        this.#db.exec(`
+      CREATE TABLE IF NOT EXISTS session_certified_leaves (
+        agent_id TEXT NOT NULL,
+        session_id TEXT NOT NULL,
+        leaf_index INTEGER NOT NULL,
+        content_hash_hex TEXT NOT NULL,
+        recorded_at INTEGER NOT NULL,
+        -- DOD-LOOP-1: composite key so each agent's end of a loopback session keeps its own set.
+        PRIMARY KEY (agent_id, session_id, leaf_index)
+      )
+    `);
+        // WHY a session has no certified leaf set — fallback-finder finding 1, and the reason it is a
+        // TABLE rather than a log line.
+        //
+        // `getCertifiedLeafSet` returns null for four different situations: no seal frame ever carried
+        // the leaves, the directory shipped a set that does not reproduce the root it signed, a leaf was
+        // malformed, or the write failed. The worst of those — a directory contradicting its own FROST
+        // signature — is the strongest misbehaviour signal this client can produce, and it was going to
+        // one ERROR line while the operator was told the most benign of the four: "normal for the party
+        // that was absent at seal time." A detection whose only consumer is a log is not a control.
+        //
+        // One row per session, replaced on every attempt, so the state is the LAST thing that happened
+        // rather than a history. Read only by the inclusion-proof surface, to name the cause.
+        this.#db.exec(`
+      CREATE TABLE IF NOT EXISTS session_certified_leaves_state (
+        agent_id TEXT NOT NULL,
+        session_id TEXT NOT NULL,
+        state TEXT NOT NULL,
+        detail TEXT,
+        recorded_at INTEGER NOT NULL,
+        PRIMARY KEY (agent_id, session_id)
+      )
     `);
         // DOD-M12B-STRAND-1 — content we RECEIVED and VERIFIED but cannot append yet.
         //
@@ -2264,6 +2462,35 @@ export class SessionNodeManager {
         const contiguousFromOne = sequences.every((n, i) => n === i + 1);
         const ctrlSenders = new Set(carry.filter((l) => l.leafKind === LEAF_KIND_CTRL).map((l) => l.senderPubkeyHex));
         const selfEvidentlyComplete = contiguousFromOne && ctrlSenders.size === 2;
+        /**
+         * 🚨 THE CERTIFICATE MAY COVER EXACTLY WHAT THIS SIDE HOLDS — ASK THAT FIRST.
+         *
+         * `DOD-M15-UNILATERAL-1`. The completeness predicate below describes a BILATERAL leaf set: two
+         * SEAL ctrl leaves, from two distinct senders. **A solo seal can never satisfy it**, because the
+         * counterparty is gone and never posts one — that is the entire premise. So on the solo path
+         * this returned `cannot_judge` every time, `session-ceremony.ts` refuses to co-sign on anything
+         * that is not `match`, and **the sealing party refused to co-sign its own unilateral seal.** The
+         * FROST ceremony never reached threshold, the directory never completed, and the close came back
+         * `seal_unilateral_timeout` — the label that names our own wait. Measured against the real
+         * binaries: `j-unilateral` failed on exactly this, with the directory having already verified the
+         * chain and recorded the counterparty ABSENT.
+         *
+         * Completeness was only ever needed to tell TWO KINDS OF DISAGREEMENT apart — "the roots differ
+         * because my carry is behind" (cannot judge) from "the roots differ because the directory
+         * certified something else" (mismatch). It answers nothing when the roots AGREE: a certificate
+         * whose root and leaf count are exactly what this daemon holds is, by construction, over this
+         * daemon's own leaves. Nothing is taken on trust — both values are recomputed here from the
+         * carry, and an adversary who could satisfy them would have to have produced this leaf set.
+         *
+         * Deliberately BOTH values. A count that disagreed while the root matched would be a certificate
+         * contradicting itself, and this is not the place to wave that through.
+         */
+        const carryInputs = carryContentHashInputs(carry);
+        if (carryInputs !== null &&
+            carry.length === certifiedLeafCount &&
+            Buffer.compare(Buffer.from(merkleRoot(buildMerkleTree(carryInputs))), Buffer.from(certifiedRoot)) === 0) {
+            return { verdict: "match" };
+        }
         if (!selfEvidentlyComplete) {
             return {
                 verdict: "cannot_judge",
@@ -2281,26 +2508,62 @@ export class SessionNodeManager {
                 detail: `leaf_count_disagrees: this daemon holds a provably complete ${carry.length}-leaf set, the certificate claims ${certifiedLeafCount}`,
             };
         }
-        const inputs = [];
+        if (carryInputs === null) {
+            // A leaf this daemon cannot decode is a leaf it cannot judge. Never an accusation.
+            return { verdict: "cannot_judge", reason: "structure1_content_hash_unreadable" };
+        }
+        const ownRoot = merkleRoot(buildMerkleTree(carryInputs));
+        const ownRootHex = Buffer.from(ownRoot).toString("hex");
+        return Buffer.compare(Buffer.from(ownRoot), Buffer.from(certifiedRoot)) === 0
+            ? { verdict: "match" }
+            : { verdict: "mismatch", ownRootHex, detail: "root_disagrees: same leaf count, different leaves or different order" };
+    }
+    /**
+     * WHERE THE MUTUALLY-SIGNED PREFIX ENDS, DERIVED FROM THIS DAEMON'S OWN LEAVES —
+     * `DOD-M15-UNILATERAL-1`, review F2.
+     *
+     * ⚠️ **THE FIRST VERSION COMPUTED THIS FROM THE CERTIFICATE'S OWN PARTICIPANT LIST, AND CALLED
+     * THAT "recomputed, cannot be steered".** It could be steered. On the SOLO path the certificate's
+     * TBS binds no legibility at all, and the client verifies only the *live* party's frontier — so
+     * the absent party's `content_frontier_seq` and every `last_authored_seq` arrived unchecked. One
+     * directory node could publish the absent party's frontier as 3 and the receipt would say
+     * "mutually signed through 3" over a transcript that party never signed for. That is the precise
+     * conflation this field exists to prevent, reintroduced by the field itself.
+     *
+     * The carry answers it without trusting anybody. This daemon holds the counterparty's own leaves,
+     * each carrying, inside the bytes THEY signed, both the sequence they authored and the
+     * `last_seen_seq` they acknowledged. So a party's commitment reaches
+     * `max(highest sequence they authored, highest sequence they acknowledged)`, and the transcript is
+     * mutually signed only as far as the LEAST-committed party reaches.
+     *
+     * Fewer than two distinct authors ⇒ `0`: nobody countersigned anything, which is the honest floor
+     * for a conversation where the other side only ever received. `null` when the carry is empty or
+     * unreadable — the caller must then publish NO boundary rather than fall back to a number
+     * somebody else supplied.
+     */
+    countersignedThroughSeqFromCarry(agentPubkeyHex, sessionIdHex) {
+        const carry = this.getSealCarry(agentPubkeyHex, sessionIdHex);
+        if (carry.length === 0)
+            return null;
+        const reach = new Map();
         for (const leaf of carry) {
-            let contentHash;
+            let signedLastSeen = 0;
             try {
-                // Canonical Structure 1 is [version, content_hash, sender_pubkey, session_id, last_seen_seq, timestamp].
-                contentHash = decode(leaf.structure1Cbor)[1];
+                // Structure 1 = [version, content_hash, sender_pubkey, session_id, last_seen_seq, timestamp].
+                const raw = decode(leaf.structure1Cbor)[4];
+                const n = typeof raw === "bigint" ? Number(raw) : raw;
+                if (typeof n === "number" && Number.isFinite(n))
+                    signedLastSeen = n;
             }
             catch {
-                return { verdict: "cannot_judge", reason: "structure1_decode_failed" };
-            }
-            if (!(contentHash instanceof Uint8Array) || contentHash.length !== 32) {
-                return { verdict: "cannot_judge", reason: "structure1_content_hash_missing" };
+                return null; // unreadable: publish no boundary rather than a half-derived one
             }
-            inputs.push({ kind: "hash", data: contentHash });
+            const prior = reach.get(leaf.senderPubkeyHex) ?? 0;
+            reach.set(leaf.senderPubkeyHex, Math.max(prior, leaf.sequenceNumber, signedLastSeen));
         }
-        const ownRoot = merkleRoot(buildMerkleTree(inputs));
-        const ownRootHex = Buffer.from(ownRoot).toString("hex");
-        return Buffer.compare(Buffer.from(ownRoot), Buffer.from(certifiedRoot)) === 0
-            ? { verdict: "match" }
-            : { verdict: "mismatch", ownRootHex, detail: "root_disagrees: same leaf count, different leaves or different order" };
+        if (reach.size < 2)
+            return 0;
+        return Math.min(...reach.values());
     }
     getSealCarry(agentPubkeyHex, sessionIdHex) {
         if (!this.#sealLeafStore && this.#db) {
@@ -3740,6 +4003,10 @@ export class SessionNodeManager {
                     sealLeafStore: this.#sealLeafStore ?? undefined,
                     // DOD-M15-RELAYSLOTS-1: read at each auth, never snapshotted — the token expires hourly.
                     onlineToken: () => this.getDirectoryOnlineToken(agentName),
+                    // DOD-M15-CORROBORATE-1: a relay's witness alert reaches the operator's inbox from here.
+                    // The DETACHED clients get the same callback from the builder in daemon.ts.
+                    onWitnessAlert: (alert) => { this.recordRelayWitnessAlert(agentName, alert); },
+                    onWitnessUnreadable: (relayPeerId, why) => { this.recordRelayWitnessUnreadable(agentName, relayPeerId, why); },
                 });
                 this.#relayClients.set(clientKey, client);
             }
@@ -5535,6 +5802,162 @@ export class SessionNodeManager {
         }
         return { sealed_root: row.sealed_root_hex, legibility };
     }
+    /**
+     * DOD-M15-INCLUSION-1: keep the leaf set the certificate is signed over, so one message can later
+     * be proved to sit under it.
+     *
+     * REFUSES unless the hashes reproduce `sealedRootHex` — `certifiedLeafSetFrom` does that check and
+     * this method never bypasses it. That is what separates "the leaves the directory sent" from "the
+     * leaves the consortium signed", and only the second is worth storing: a proof built on the first
+     * would inherit whatever the directory chose to say.
+     *
+     * Idempotent (INSERT OR REPLACE keyed on leaf_index) so a re-delivered seal frame, or a unilateral
+     * seal later upgraded to bilateral, rewrites the same rows instead of failing or doubling them.
+     *
+     * @returns whether the set was accepted and stored.
+     */
+    recordCertifiedLeafSet(agentName, sessionId, signedLeaves, sealedRootHex, correlationId) {
+        if (!this.#db)
+            return false;
+        const resolved = certifiedLeafSetFrom(signedLeaves, sealedRootHex);
+        if (!resolved.ok) {
+            // The CAUSE is written where the proof surface can read it — fallback-finder finding 1. Without
+            // this row, `sealed_leaves_root_disagrees` (a directory contradicting its own FROST signature)
+            // and "this side was simply absent" are the same `null` downstream, and the operator is told
+            // the second.
+            this.#noteCertifiedLeafState(agentName, sessionId, resolved.reason, resolved.detail);
+            // LOUD, and it names which of the two it is. `sealed_leaves_root_disagrees` in particular is
+            // the directory shipping a leaf set that is not the one it signed — the receipt still stands
+            // (its own signature is checked elsewhere), but nothing in this session can be proved at
+            // message granularity until a set that reproduces the root arrives.
+            this.#logger.error("seal.certified_leaves.refused", {
+                agentName,
+                sessionId,
+                reason: resolved.reason,
+                detail: resolved.detail,
+                correlationId,
+                impact: "the leaf set shipped with this seal is not the one the certificate is signed over, so no " +
+                    "inclusion proof can be issued for this session; the sealed receipt itself is unaffected",
+                guidance: "cello_get_inclusion_proof will refuse this session by name (certified_leaves_unavailable). " +
+                    "Nothing local repairs it — the set has to arrive with a seal frame that reproduces the " +
+                    "signed root.",
+            });
+            return false;
+        }
+        const now = Date.now();
+        try {
+            const agentId = this.#requireAgentId(agentName);
+            /**
+             * DELETE THEN INSERT, INSIDE A TRANSACTION — fallback-finder finding 5.
+             *
+             * `INSERT OR REPLACE` alone is idempotent only for a set of the SAME length: a shorter
+             * re-delivery overwrites 0..k-1 and leaves stale rows at k..n-1, and an un-transacted loop that
+             * throws halfway leaves a truncated set that `getCertifiedLeafSet` still returns (it tests
+             * `rows.length > 0`, not completeness). Both produce a set that no longer hashes to the
+             * certified root — caught on read, but reported to the operator as *"the local copy has
+             * changed since the seal"*, which points at tampering for a write that never finished.
+             */
+            // `BEGIN` / `COMMIT` / `ROLLBACK` via exec — this file's and `db-identity-store.ts`'s idiom.
+            // `DaemonDatabase` has no `transaction()` helper (node:sqlite's handle does not provide one),
+            // and reaching for better-sqlite3's would compile against the adapter and fail on the other.
+            this.#db.exec("BEGIN");
+            try {
+                this.#db.prepare("DELETE FROM session_certified_leaves WHERE agent_id = ? AND session_id = ?")
+                    .run(agentId, sessionId);
+                const stmt = this.#db.prepare(`INSERT INTO session_certified_leaves
+             (agent_id, session_id, leaf_index, content_hash_hex, recorded_at)
+           VALUES (?, ?, ?, ?, ?)`);
+                for (let i = 0; i < resolved.leafHashes.length; i++) {
+                    stmt.run(agentId, sessionId, i, resolved.leafHashes[i], now);
+                }
+                this.#db.exec("COMMIT");
+            }
+            catch (err) {
+                try {
+                    this.#db.exec("ROLLBACK");
+                }
+                catch { /* the failing statement may have aborted it already */ }
+                throw err;
+            }
+        }
+        catch (err) {
+            this.#noteCertifiedLeafState(agentName, sessionId, "persist_failed", extractErrorMessage(err));
+            this.#logger.error("seal.certified_leaves.persist.failed", {
+                agentName,
+                sessionId,
+                reason: extractErrorMessage(err),
+                correlationId,
+                impact: "this session's certified leaf set was verified but not written, so cello_get_inclusion_proof " +
+                    "will refuse it by name until a later seal frame re-delivers the set",
+            });
+            return false;
+        }
+        this.#noteCertifiedLeafState(agentName, sessionId, "stored", null);
+        this.#logger.info("seal.certified_leaves.recorded", {
+            agentName,
+            sessionId,
+            leafCount: resolved.leafHashes.length,
+            sealedRoot: sealedRootHex,
+            correlationId,
+        });
+        return true;
+    }
+    /**
+     * Record WHY this session does or does not have a certified leaf set.
+     *
+     * Public for the one case the manager cannot see: a seal frame that carried no signed leaves at
+     * all never reaches `recordCertifiedLeafSet`, and that absence is a permanent fact about the
+     * session for the party that observed it.
+     */
+    noteCertifiedLeafSetUnavailable(agentName, sessionId, state, detail) {
+        this.#noteCertifiedLeafState(agentName, sessionId, state, detail);
+    }
+    /**
+     * The last thing that happened to this session's certified leaf set, or null if nothing has.
+     *
+     * Null here and a null from `getCertifiedLeafSet` together mean "no seal has been processed on
+     * this side yet" — which is a different sentence again from any of the recorded states.
+     */
+    getCertifiedLeafSetState(agentName, sessionId) {
+        if (!this.#db)
+            return null;
+        const row = this.#db
+            .prepare("SELECT state, detail FROM session_certified_leaves_state WHERE agent_id = ? AND session_id = ?")
+            .get(this.#requireAgentId(agentName), sessionId);
+        return row ? { state: row.state, detail: row.detail } : null;
+    }
+    /** Best-effort: a failure to record WHY must never be the thing that breaks a seal. */
+    #noteCertifiedLeafState(agentName, sessionId, state, detail) {
+        if (!this.#db)
+            return;
+        try {
+            this.#db
+                .prepare(`INSERT OR REPLACE INTO session_certified_leaves_state
+             (agent_id, session_id, state, detail, recorded_at)
+           VALUES (?, ?, ?, ?, ?)`)
+                .run(this.#requireAgentId(agentName), sessionId, state, detail, Date.now());
+        }
+        catch (err) {
+            this.#logger.warn("seal.certified_leaves.state.write.failed", {
+                agentName, sessionId, state, reason: extractErrorMessage(err),
+                impact: "the inclusion-proof surface will not be able to name WHY this session has no certified leaf set; it still refuses rather than proving anything",
+            });
+        }
+    }
+    /**
+     * The certified leaf set, in order, or null when none was stored for this session.
+     *
+     * Null is a REFUSAL upstream, never a fallback to the local tree: the two cover different leaves
+     * and substituting one for the other is how a proof comes to land on a root nobody signed.
+     */
+    getCertifiedLeafSet(agentName, sessionId) {
+        if (!this.#db)
+            return null;
+        const rows = this.#db
+            .prepare("SELECT content_hash_hex FROM session_certified_leaves WHERE agent_id = ? AND session_id = ? ORDER BY leaf_index ASC")
+            .all(this.#requireAgentId(agentName), sessionId);
+        return rows.length > 0 ? rows.map((r) => r.content_hash_hex) : null;
+    }
     /**
      * M7-SESSION-001: Mark a session as interrupted with message count and timestamp.
      * Called when a relay session_interrupted frame arrives or a relay stream closes.
@@ -8739,7 +9162,22 @@ export class SessionNodeManager {
                     "because sealing on a record the counterparty cannot match produces a receipt only one " +
                     "side can verify.",
             });
-            return { placed: true, leafIndex };
+            /**
+             * ─── `016-RELAYLOSS`: CARRIED TO THE CALLER, because the log is not a consumer ────────────
+             *
+             * Measured with a real relay black-holed mid-conversation: the send stalls for the submit
+             * timeout, then returns `{ok: true, sequence_number: N, delivered: true}` — BYTE-IDENTICAL to
+             * the witnessed send that preceded it. The error above is correct, complete, and read by
+             * nobody the operator can ask.
+             *
+             * Its two siblings twenty lines below already do this: `diverged` and the held case both
+             * refuse to return an ordinary success, on the stated grounds that doing so "reports a
+             * healthy send on a conversation that has silently lost the one thing the protocol exists to
+             * produce." This branch is where that loss OCCURS — `position_behind_frontier`'s own comment
+             * says the seal "was already lost at the unwitnessed append, not here" — so it is the branch
+             * that most needed to say so, and it was the one that said nothing.
+             */
+            return { placed: true, leafIndex, unwitnessed: true };
         }
         if (assignedSeq === nextExpected) {
             const { leafIndex } = this.appendSessionLeaf(agentName, sessionId, kind, contentHashHex, correlationId);
@@ -10795,6 +11233,49 @@ export class SessionNodeManager {
     getSessionContentSalt(agentName, sessionId) {
         return this.#getSessionSalt(agentName, sessionId);
     }
+    /**
+     * THE SALT, OR WHY THERE ISN'T ONE — `DOD-M15-INCLUSION-1`, fallback-finder finding 2.
+     *
+     * `getSessionContentSalt` above answers `null` for THREE different situations, and a caller that
+     * turns that null into a sentence for an operator gets two of them wrong:
+     *
+     *   `none`       — no salt was ever agreed. The session really is unsalted.
+     *   `unreadable` — a salt row EXISTS and could not be used: the wrong width (corruption on this
+     *                  operator's own disk), or the read threw.
+     *
+     * The distinction is not cosmetic. `unreadable` means the session's leaves WERE hashed under a
+     * salt, so telling its operator *"this session's content hashes are UNSALTED … start a session
+     * while you are both connected"* is an affirmatively false statement about a security property
+     * their session has, and it points them at their counterparty over damage to their own database.
+     * That is the same defect `#getSessionSalt`'s own F8 note was written to end, re-committed one
+     * surface out.
+     *
+     * ⚠️ IT DELEGATES — there is no second read here. Calling `#getSessionSalt` first means the salt
+     * this reports is the salt the hashing path uses, including its cache and its wrong-width refusal.
+     * A parallel query would be free to disagree with it, which is the whole failure this returns a
+     * reason to prevent.
+     */
+    getSessionContentSaltState(agentName, sessionId) {
+        const salt = this.#getSessionSalt(agentName, sessionId);
+        if (salt)
+            return { salt };
+        if (!this.#db)
+            return { salt: null, reason: "unreadable" };
+        try {
+            const row = this.#db
+                .prepare("SELECT length(content_salt) AS n FROM sessions WHERE agent_id = ? AND session_id = ?")
+                .get(this.#requireAgentId(agentName), sessionId);
+            // A row with a non-empty blob that `#getSessionSalt` still refused is the corruption case: the
+            // bytes are there and they are not a salt. NULL or zero-length is a genuine absence.
+            const stored = row?.n ?? 0;
+            return { salt: null, reason: stored > 0 ? "unreadable" : "none" };
+        }
+        catch {
+            // The read that would tell us which case it is has itself failed, so "no salt was agreed" is
+            // exactly the thing we cannot assert.
+            return { salt: null, reason: "unreadable" };
+        }
+    }
     /**
      * This session's agreed salt, or null. Reads the durable row through a cache, because Decision #8
      * persists it for exactly one reason: *"a restart silently splits the transcript"* if the lookup