@cello-protocol/daemon 0.0.194 → 0.0.195

package/dist/session-leaf-records.d.ts

@@ -0,0 +1,132 @@
+/**
+ * CELLO Daemon — THE TWO DURABLE FACTS ABOUT A SESSION'S LEAVES
+ *
+ * Split out of `session-node-manager.ts` by 037-SESSIONCORE. Both are DURABLE PER-SESSION LEAF
+ * FACTS that outlive the process, which is why they are here together rather than with the
+ * in-memory tree:
+ *
+ * ⚠️ NOT "both are read at seal time" — that was the first wording and it is false of both halves.
+ * The genesis is read at session OPEN and at SEND (`#signOwnContentClaim`), never at seal; the
+ * certified leaf set is written at seal and read at PROOF time. The distinction matters because
+ * this header is the rule the next extraction obeys when deciding what belongs here.
+ *
+ *   - the GENESIS prev-root — where this two-party chain starts. It is a defined 32 bytes derived
+ *     from both keys, the session id and the session timestamp, NOT 32 zeros: a constant identical
+ *     across every session is one an attacker could present for any session, which would make the
+ *     one position most exposed to a forged acknowledgement the only one nobody could check.
+ *   - the CERTIFIED LEAF SET — which leaves the directory actually attested, and the state of that
+ *     answer when it could not be obtained.
+ *
+ * Moved verbatim, comments included.
+ */
+import type { Logger } from "./types.js";
+import type { SessionQueries } from "./session-queries.js";
+import type { ActiveSessionEntry } from "./session-node-types.js";
+import type { DaemonDatabase } from "./sqlcipher-db.js";
+import type { RelayAssignmentCarry } from "./session-relay-client.js";
+import type { SealFrontierLeaf } from "./seal-frontier-verify.js";
+/** What the leaf records need from the manager — six things, none of them session state. */
+export interface SessionLeafRecordContext {
+    readonly logger: Logger;
+    readonly queries: SessionQueries;
+    /** A function: the manager opens its database after construction. Re-exposed below as `#db`. */
+    db(): DaemonDatabase | null;
+    sessionKey(agentName: string, sessionId: string): string;
+    requireAgentId(agentName: string): string;
+    activeEntry(key: string): ActiveSessionEntry | undefined;
+}
+export declare class SessionLeafRecords {
+    #private;
+    constructor(ctx: SessionLeafRecordContext);
+    /**
+     * The session's genesis prev_root — what its FIRST message acknowledges, before anything has been
+     * received (033-ACKEMIT).
+     *
+     * DERIVED FIRST, STORED SECOND — and this docblock used to say "derived, never stored", which
+     * stopped being true inside this same unit. Rewritten rather than deleted: a reader who believed
+     * the first sentence would delete the column read below as redundant, and take the restart case
+     * with it.
+     *
+     * The live assignment is authoritative, because it is the thing the value is defined by. The
+     * stored column covers the one case the derivation cannot: a session restored after a restart
+     * re-registers with no assignment, and the session TIMESTAMP the genesis needs lives nowhere
+     * else.
+     *
+     * `undefined` when neither is available. The callers do not paper over that — they say, in the
+     * log and in the claim itself, that this session acknowledges nothing yet.
+     */
+    sessionGenesisPrevRoot(agentName: string, sessionId: string): Uint8Array | undefined;
+    persistGenesisPrevRoot(agentName: string, sessionId: string, assignment: RelayAssignmentCarry): void;
+    /**
+     * Persist the session's genesis prev_root, once, at the moment the assignment arrives.
+     *
+     * `WHERE genesis_prev_root IS NULL` rather than a plain update: the value cannot legitimately
+     * change for the life of a session, so the second writer is either redundant or wrong, and the
+     * first write is the one derived closest to the assignment that opened the session.
+     */
+    /**
+     * Record the session's starting point from the ASSIGNMENT — `DOD-M15-SELFCHAIN-1`.
+     *
+     * ⚠️ **CALL THIS BEFORE `createSessionNode` / `acceptSession`, NOT AFTER.** Registering the
+     * session is what seeds the relay client's acknowledgement state, so the value has to exist by
+     * then; recorded afterwards, the first message of the session has nothing to chain to and is
+     * refused. Both the initiator and the responder derive this from the same FROST-signed assignment
+     * before they build anything.
+     *
+     * ⚠️ THE ANCHOR BELONGS TO THE SESSION, NOT TO THE RELAY, and treating it as the relay's was a
+     * real gap. It was derived only when a relay assignment CARRY was present — and that carry is
+     * built only for a relay-mode assignment that also carries a per-node relay signature. So a
+     * direct-mode session, brokered and FROST-signed exactly like any other, recorded no starting
+     * point at all, and every message on it had nothing to chain to.
+     *
+     * Both transport modes get their assignment from the same ceremony and derive the same value from
+     * it. The relay is how the conversation travels; it is not what makes the conversation provable.
+     */
+    recordSessionGenesis(agentName: string, sessionId: string, participantA: Uint8Array, participantB: Uint8Array, sessionTimestamp: number): void;
+    /**
+     * Test seam: put the session's genesis prev_root where a completed session open leaves it —
+     * 033-ACKEMIT.
+     *
+     * ⚠️ THE STATE IS THE PRODUCTION ONE; ONLY HOW IT GOT THERE IS SHORT-CIRCUITED, exactly as
+     * `setSessionContentKeyForTest` short-circuits the key exchange next door.
+     *
+     * In production this value is derived from the directory-signed relay assignment and written to
+     * the session row the moment the session learns it, so every real session has one. A fixture that
+     * builds a session node directly never sees an assignment — so without this seam every content
+     * test built on the fixture would be exercising the "no starting point" REFUSAL path instead of
+     * the thing it was written for, and would report that as a pass or a mysterious failure depending
+     * on which side of the send it sat on.
+     */
+    setSessionGenesisForTest(agentName: string, sessionId: string, genesis: Uint8Array): void;
+    /**
+     * 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: string, sessionId: string, signedLeaves: readonly SealFrontierLeaf[], sealedRootHex: string, correlationId?: string): boolean;
+    /**
+     * 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: string, sessionId: string, state: "not_carried_absent_party" | "not_carried_present_party", detail: string): void;
+    getCertifiedLeafSet(agentName: string, sessionId: string): string[] | null;
+    getCertifiedLeafSetState(agentName: string, sessionId: string): {
+        state: string;
+        detail: string | null;
+    } | null;
+    /** The in-memory genesis prev-root for a session, when one has been recorded. */
+    genesisFor(agentName: string, sessionId: string): Uint8Array | undefined;
+}
+//# sourceMappingURL=session-leaf-records.d.ts.map

package/dist/session-leaf-records.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-leaf-records.d.ts","sourceRoot":"","sources":["../src/session-leaf-records.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,YAAY,CAAC;AACzC,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAC3D,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,yBAAyB,CAAC;AAClE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AACxD,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,2BAA2B,CAAC;AACtE,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,2BAA2B,CAAC;AAKlE,4FAA4F;AAC5F,MAAM,WAAW,wBAAwB;IACvC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,OAAO,EAAE,cAAc,CAAC;IACjC,gGAAgG;IAChG,EAAE,IAAI,cAAc,GAAG,IAAI,CAAC;IAC5B,UAAU,CAAC,SAAS,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM,CAAC;IACzD,cAAc,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAAC;IAC1C,WAAW,CAAC,GAAG,EAAE,MAAM,GAAG,kBAAkB,GAAG,SAAS,CAAC;CAC1D;AAED,qBAAa,kBAAkB;;gBAGjB,GAAG,EAAE,wBAAwB;IA6BzC;;;;;;;;;;;;;;;;OAgBG;IACH,sBAAsB,CAAC,SAAS,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,UAAU,GAAG,SAAS;IAsCpF,sBAAsB,CAAC,SAAS,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,UAAU,EAAE,oBAAoB,GAAG,IAAI;IAmDpG;;;;;;OAMG;IACH;;;;;;;;;;;;;;;;;OAiBG;IACH,oBAAoB,CAClB,SAAS,EAAE,MAAM,EACjB,SAAS,EAAE,MAAM,EACjB,YAAY,EAAE,UAAU,EACxB,YAAY,EAAE,UAAU,EACxB,gBAAgB,EAAE,MAAM,GACvB,IAAI;IAKP;;;;;;;;;;;;;OAaG;IACH,wBAAwB,CAAC,SAAS,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,OAAO,EAAE,UAAU,GAAG,IAAI;IA0BzF;;;;;;;;;;;;;OAaG;IACH,sBAAsB,CACpB,SAAS,EAAE,MAAM,EACjB,SAAS,EAAE,MAAM,EACjB,YAAY,EAAE,SAAS,gBAAgB,EAAE,EACzC,aAAa,EAAE,MAAM,EACrB,aAAa,CAAC,EAAE,MAAM,GACrB,OAAO;IAqFV;;;;;;OAMG;IACH,+BAA+B,CAC7B,SAAS,EAAE,MAAM,EACjB,SAAS,EAAE,MAAM,EACjB,KAAK,EAAE,0BAA0B,GAAG,2BAA2B,EAC/D,MAAM,EAAE,MAAM,GACb,IAAI;IAGP,mBAAmB,CAAC,SAAS,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,IAAI;IAC1E,wBAAwB,CAAC,SAAS,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAA;KAAE,GAAG,IAAI;IAE/G,iFAAiF;IACjF,UAAU,CAAC,SAAS,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,UAAU,GAAG,SAAS;CAGzE"}

package/dist/session-leaf-records.js

@@ -0,0 +1,320 @@
+import { computeGenesisPrevRoot } from "@cello-protocol/protocol-types";
+import { extractErrorMessage } from "./error-message.js";
+import { certifiedLeafSetFrom } from "./sealed-leaf-set.js";
+export class SessionLeafRecords {
+    #ctx;
+    constructor(ctx) {
+        this.#ctx = ctx;
+    }
+    /** A getter so the moved queries still read `this.#db` and narrow exactly as they did. */
+    get #db() {
+        return this.#ctx.db();
+    }
+    /**
+     * The starting point of each live session's chain, in memory.
+     *
+     * ⚠️ NOT A CACHE OF THE DATABASE — it is the only copy that exists at the moment the value is
+     * first needed. It is recorded before the session node is built, and the session ROW does not
+     * exist until that build inserts it (`#insertSessionRow` writes the column from here). The row is
+     * what survives a restart; this is what the session open itself reads.
+     *
+     * ⚠️ **DELIBERATELY NOT EVICTED, and this module ships no `evictSession` because of it.** Every
+     * other collaborator has one, so the absence reads as an oversight — it is not. Dropping this on
+     * teardown would lose the in-memory genesis for any session whose `UPDATE sessions SET
+     * genesis_prev_root` FAILED, which is exactly the case `persistGenesisPrevRoot`'s error log says
+     * survives until a restart. Adding an `evictSession` here for symmetry would delete the only copy.
+     *
+     * ⚠️ IT THEREFORE GROWS FOR THE LIFE OF THE PROCESS — pre-existing, and stated rather than fixed.
+     * "each live session's chain" above is what it is FOR, not what it holds: entries are set and read
+     * and never removed, so it is roughly 200 bytes per session ever opened. Bounding it is not
+     * obviously safe for the reason directly above, so it wants a decision rather than a tidy-up.
+     */
+    #sessionGenesis = new Map();
+    /**
+     * The session's genesis prev_root — what its FIRST message acknowledges, before anything has been
+     * received (033-ACKEMIT).
+     *
+     * DERIVED FIRST, STORED SECOND — and this docblock used to say "derived, never stored", which
+     * stopped being true inside this same unit. Rewritten rather than deleted: a reader who believed
+     * the first sentence would delete the column read below as redundant, and take the restart case
+     * with it.
+     *
+     * The live assignment is authoritative, because it is the thing the value is defined by. The
+     * stored column covers the one case the derivation cannot: a session restored after a restart
+     * re-registers with no assignment, and the session TIMESTAMP the genesis needs lives nowhere
+     * else.
+     *
+     * `undefined` when neither is available. The callers do not paper over that — they say, in the
+     * log and in the claim itself, that this session acknowledges nothing yet.
+     */
+    sessionGenesisPrevRoot(agentName, sessionId) {
+        const assignment = this.#ctx.activeEntry(this.#ctx.sessionKey(agentName, sessionId))?.relayAssignment;
+        if (assignment) {
+            return computeGenesisPrevRoot(assignment.participantA, assignment.participantB, Uint8Array.from(Buffer.from(sessionId, "hex")), assignment.sessionTimestamp);
+        }
+        /**
+         * ⚠️ THE IN-MEMORY RECORD, READ BEFORE THE DATABASE — and this ordering is the fix, not a
+         * cache.
+         *
+         * `recordSessionGenesis` is called BEFORE the session node exists, because registering the
+         * session is what seeds the relay client's acknowledgement state and the seed has to be
+         * available by then. At that moment there is no session ROW to write to — `createSessionNode`
+         * inserts it — so a database-only record would still be empty at the one moment it is read.
+         * The row is written from this map when the insert happens, and read back after a restart.
+         */
+        const recorded = this.#sessionGenesis.get(this.#ctx.sessionKey(agentName, sessionId));
+        if (recorded)
+            return recorded;
+        /**
+         * THE RESTART CASE. A session restored from the database re-registers with no assignment, so
+         * the derivation above has nothing to work from and the stored copy is the only answer. Read
+         * second, never first: the live assignment is authoritative, and a stored value that ever
+         * disagreed with it would be the more dangerous of the two to prefer.
+         */
+        const row = this.#db
+            ?.prepare("SELECT genesis_prev_root FROM sessions WHERE agent_id = ? AND session_id = ?")
+            .get(this.#ctx.requireAgentId(agentName), sessionId);
+        const stored = row?.genesis_prev_root;
+        const bytes = stored instanceof Uint8Array ? stored : Buffer.isBuffer(stored) ? new Uint8Array(stored) : null;
+        // A stored value of the wrong width is not a genesis. Refusing it here sends the caller down its
+        // own named refusal, which is a better outcome than signing an acknowledgement of 17 bytes.
+        if (bytes && bytes.length === 32)
+            return bytes;
+        return undefined;
+    }
+    persistGenesisPrevRoot(agentName, sessionId, assignment) {
+        let genesis;
+        try {
+            genesis = computeGenesisPrevRoot(assignment.participantA, assignment.participantB, Uint8Array.from(Buffer.from(sessionId, "hex")), assignment.sessionTimestamp);
+        }
+        catch (err) {
+            /**
+             * The DERIVATION failed, which is a different failure from the write below and must not be
+             * reported as one. It means the assignment's own fields are not what this function needs, and
+             * no amount of database health would help.
+             */
+            this.#ctx.logger.error("session.genesis.derive.failed", {
+                agentName, sessionId,
+                error: err instanceof Error ? err.message : String(err),
+                impact: "this session's starting point could not be computed from its assignment, so nothing " +
+                    "sent on it can be chained and every send will be refused by name. The session open " +
+                    "continues; the conversation cannot.",
+            });
+            return;
+        }
+        // The in-memory record FIRST, and unconditionally: it is what the session open reads, and it
+        // must not depend on a database write that may not have anywhere to land yet.
+        this.#sessionGenesis.set(this.#ctx.sessionKey(agentName, sessionId), genesis);
+        if (!this.#db)
+            return;
+        try {
+            this.#db
+                .prepare("UPDATE sessions SET genesis_prev_root = ? WHERE agent_id = ? AND session_id = ? AND genesis_prev_root IS NULL")
+                .run(Buffer.from(genesis), this.#ctx.requireAgentId(agentName), sessionId);
+        }
+        catch (err) {
+            /**
+             * LOUD, AND IT DOES NOT BLOCK. Losing this row costs the session its acknowledgements after a
+             * restart — sends are then refused by name until the counterparty speaks — and that is a far
+             * smaller harm than failing the session open that is in progress. Reported at ERROR because
+             * the failure is invisible until a restart that may be days away.
+             */
+            this.#ctx.logger.error("session.genesis.persist.failed", {
+                agentName, sessionId,
+                error: err instanceof Error ? err.message : String(err),
+                impact: "this session's starting point was not written to the database. Everything works until " +
+                    "this daemon restarts; after that, a send on this session is refused until the " +
+                    "counterparty has sent something, because the daemon cannot say what its first message " +
+                    "acknowledges.",
+            });
+        }
+    }
+    /**
+     * Persist the session's genesis prev_root, once, at the moment the assignment arrives.
+     *
+     * `WHERE genesis_prev_root IS NULL` rather than a plain update: the value cannot legitimately
+     * change for the life of a session, so the second writer is either redundant or wrong, and the
+     * first write is the one derived closest to the assignment that opened the session.
+     */
+    /**
+     * Record the session's starting point from the ASSIGNMENT — `DOD-M15-SELFCHAIN-1`.
+     *
+     * ⚠️ **CALL THIS BEFORE `createSessionNode` / `acceptSession`, NOT AFTER.** Registering the
+     * session is what seeds the relay client's acknowledgement state, so the value has to exist by
+     * then; recorded afterwards, the first message of the session has nothing to chain to and is
+     * refused. Both the initiator and the responder derive this from the same FROST-signed assignment
+     * before they build anything.
+     *
+     * ⚠️ THE ANCHOR BELONGS TO THE SESSION, NOT TO THE RELAY, and treating it as the relay's was a
+     * real gap. It was derived only when a relay assignment CARRY was present — and that carry is
+     * built only for a relay-mode assignment that also carries a per-node relay signature. So a
+     * direct-mode session, brokered and FROST-signed exactly like any other, recorded no starting
+     * point at all, and every message on it had nothing to chain to.
+     *
+     * Both transport modes get their assignment from the same ceremony and derive the same value from
+     * it. The relay is how the conversation travels; it is not what makes the conversation provable.
+     */
+    recordSessionGenesis(agentName, sessionId, participantA, participantB, sessionTimestamp) {
+        this.persistGenesisPrevRoot(agentName, sessionId, {
+            participantA, participantB, sessionTimestamp,
+        });
+    }
+    /**
+     * Test seam: put the session's genesis prev_root where a completed session open leaves it —
+     * 033-ACKEMIT.
+     *
+     * ⚠️ THE STATE IS THE PRODUCTION ONE; ONLY HOW IT GOT THERE IS SHORT-CIRCUITED, exactly as
+     * `setSessionContentKeyForTest` short-circuits the key exchange next door.
+     *
+     * In production this value is derived from the directory-signed relay assignment and written to
+     * the session row the moment the session learns it, so every real session has one. A fixture that
+     * builds a session node directly never sees an assignment — so without this seam every content
+     * test built on the fixture would be exercising the "no starting point" REFUSAL path instead of
+     * the thing it was written for, and would report that as a pass or a mysterious failure depending
+     * on which side of the send it sat on.
+     */
+    setSessionGenesisForTest(agentName, sessionId, genesis) {
+        /**
+         * ⚠️ WRITES THE SAME MAP PRODUCTION WRITES, deliberately — `DOD-M15-SELFCHAIN-1`.
+         *
+         * This seam exists because a fixture builds a session below the paths that derive a starting
+         * point from a directory assignment; it does NOT exist to install a second, quieter source of
+         * the value. Sharing the map means a fixture and a real session read through exactly the same
+         * lookup, so a change to that lookup cannot pass the tests while breaking production.
+         *
+         * ⚠️ CALL IT BEFORE `createSessionNode`, the same rule production follows: registering the
+         * session is what seeds the relay client's acknowledgement state, and a value recorded after
+         * that leaves the first send with nothing to chain to.
+         */
+        this.#sessionGenesis.set(this.#ctx.sessionKey(agentName, sessionId), Uint8Array.from(genesis));
+        /**
+         * The durable half is BEST EFFORT. Some fixtures run against a database whose schema was never
+         * created, and a seam that threw there would turn "this fixture has no sessions table" into a
+         * failure of whatever it was actually testing. Harmless when the row does not exist yet either:
+         * `#insertSessionRow` writes the column from the map above.
+         */
+        try {
+            this.#db
+                ?.prepare("UPDATE sessions SET genesis_prev_root = ? WHERE agent_id = ? AND session_id = ?")
+                .run(Buffer.from(genesis), this.#ctx.requireAgentId(agentName), sessionId);
+        }
+        catch { /* see above — the in-memory half is the load-bearing one */ }
+    }
+    /**
+     * 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.#ctx.queries.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.#ctx.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.#ctx.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.#ctx.queries.noteCertifiedLeafState(agentName, sessionId, "persist_failed", extractErrorMessage(err));
+            this.#ctx.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.#ctx.queries.noteCertifiedLeafState(agentName, sessionId, "stored", null);
+        this.#ctx.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.#ctx.queries.noteCertifiedLeafState(agentName, sessionId, state, detail);
+    }
+    getCertifiedLeafSet(agentName, sessionId) { return this.#ctx.queries.getCertifiedLeafSet(agentName, sessionId); }
+    getCertifiedLeafSetState(agentName, sessionId) { return this.#ctx.queries.getCertifiedLeafSetState(agentName, sessionId); }
+    /** The in-memory genesis prev-root for a session, when one has been recorded. */
+    genesisFor(agentName, sessionId) {
+        return this.#sessionGenesis.get(this.#ctx.sessionKey(agentName, sessionId));
+    }
+}
+//# sourceMappingURL=session-leaf-records.js.map

package/dist/session-leaf-records.js.map

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

package/dist/session-liveness.d.ts

@@ -0,0 +1,135 @@
+/**
+ * CELLO Daemon — IS THIS SESSION STILL ALIVE, AND IF NOT, WHY
+ *
+ * Split out of `session-node-manager.ts` by 037-SESSIONCORE. The connection-level liveness of a
+ * session, and the IMPAIRMENT that explains a degraded one — which matters more than it sounds,
+ * because "impaired, and here is the cause" is what an operator gets instead of silence when a
+ * session is half-working.
+ *
+ * Moved verbatim, comments included.
+ */
+import type { Logger } from "./types.js";
+import type { CelloNode } from "@cello-protocol/transport";
+import type { ActiveSessionEntry, SessionImpairment } from "./session-node-types.js";
+import type { SessionQueries } from "./session-queries.js";
+import type { RefusalNotices } from "./refusal-notices.js";
+import type { SessionEphemerals } from "./session-ephemerals.js";
+import type { SaltAgreementFrame } from "./session-salt-agreement.js";
+/** What liveness needs from the manager. */
+export interface SessionLivenessContext {
+    readonly logger: Logger;
+    readonly queries: SessionQueries;
+    readonly notices: RefusalNotices;
+    readonly ephemerals: SessionEphemerals;
+    readonly counterpartyAddrs: Map<string, string[]>;
+    sessionKey(agentName: string, sessionId: string): string;
+    activeEntry(key: string): ActiveSessionEntry | undefined;
+    sendSaltFrame(agentName: string, sessionId: string, correlationId?: string, override?: SaltAgreementFrame): Promise<void>;
+}
+export declare class SessionLiveness {
+    #private;
+    constructor(ctx: SessionLivenessContext);
+    /**
+     * M7-SESSION-003 AC-004: wire a session node's peer-connect / peer-disconnect
+     * events to per-session direct-path liveness. onPeerConnect → 'alive',
+     * onPeerDisconnect → 'gone', emitting session.liveness.changed at WARN. Combined
+     * with the transport keepalive (AC-005), a peer that vanished without a clean
+     * close still surfaces a disconnect and drives 'gone'.
+     *
+     * THE EVENT MUST BE FILTERED BY PEER (DOD-RELAY-KEEPALIVE-1 review, F2). The
+     * original wiring acted on EVERY peer event this node saw, justified by "the
+     * session node's gater restricts connections to the designated counterparty".
+     * That stopped being true: the session node also dials the RELAY as its
+     * Structure-2 witness (#connectSessionRelay), and the gater allows those peers
+     * outbound. So a relay link dropping declared the counterparty dead — at WARN,
+     * feeding the unilateral-seal gate — while the counterparty was sitting there
+     * perfectly alive. During the 2026-08-04 incident, when the relay link churned
+     * every 60-90 seconds, that fired continuously.
+     *
+     * `counterpartySessionPeerId` is the authority when known. When it is not (the
+     * peer id can be absent on a session whose assignment has not landed yet),
+     * every peer is honoured EXCEPT ones known to be relays for this session —
+     * degrading to the old over-eager behaviour minus its one known false positive,
+     * rather than to silence, because a liveness detector that never fires is worse
+     * than one that fires too often.
+     */
+    wireSessionLiveness(agentName: string, sessionId: string, node: CelloNode, counterpartyPubkey: string, correlationId: string, counterpartySessionPeerId?: string): void;
+    /**
+     * M7-SESSION-003: read the direct-path counterparty liveness for a session.
+     * 'unknown' when no session node observation has occurred yet.
+     *
+     * DOD-M12B-ACK-1: 'impaired' is DAEMON-LOCAL and deliberately not on the relay's
+     * SessionLiveness wire type — the relay answers a different question (does it hold the
+     * recipient's standing connection) and its three states are a deployed bilateral contract.
+     */
+    getSessionLiveness(agentName: string, sessionId: string): "alive" | "impaired" | "gone" | "unknown";
+    /**
+     * DOD-M12B-ACK-1 — the connection is up and delivery on it is not working.
+     *
+     * Liveness is otherwise driven ONLY by libp2p peer-connect/peer-disconnect, so it answers "is
+     * there a connection object?" while every surface that prints it is read as "can I talk to them?".
+     * Measured 2026-08-17: one session reported `alive` for 70 minutes after every write had started
+     * failing, another never stopped.
+     *
+     * ONLY 'gone' is protected, and 'gone' is NOT protected because a seal gate reads it — nothing in
+     * the code does. It is protected because the receive surface turns 'gone' into "call
+     * cello_close_session", and a failed write must never be able to produce that instruction.
+     *
+     * 'unknown' is DOWNGRADED just like 'alive', which is not obvious and is the point. A session
+     * whose recorded `counterpartySessionPeerId` has gone stale never sees a matching peer-connect,
+     * so it sits at 'unknown' while every send fails forever — the exact case documented at
+     * #wireSessionLiveness — and the receive surface renders 'unknown' as healthy-and-quiet, which is
+     * the 70-minute lie relocated one lane over. 'unknown' claims nothing; the surface built on it does.
+     */
+    markSessionImpaired(agentName: string, sessionId: string, opts: {
+        cause: "direct_send" | "delivery_ack" | "content_key";
+        error: string;
+        correlationId?: string;
+    }): void;
+    /**
+     * DOD-M12B-ACK-1 — what became of the content whose send caused the impairment.
+     *
+     * The receive surface has no memory of the last send, so without this it can only guess — and the
+     * guess it would make ("it was parked, do not resend") is FALSE in the two cases that matter
+     * most: a refused park whose durable enqueue was dropped, and one that threw. In both the message
+     * is gone and `cello_send` has already told the caller to send it again, so a receive that says
+     * "do not resend" contradicts it later, while the agent is sitting there waiting.
+     */
+    noteImpairmentRetention(agentName: string, sessionId: string, retained: "parked" | "durable" | "lost"): void;
+    /** DOD-M12B-ACK-1: why this session is impaired, for the surface that has to explain it. Null
+     *  when it is not impaired — a caller must not narrate a failure that is not current. */
+    getSessionImpairment(agentName: string, sessionId: string): SessionImpairment | null;
+    /**
+     * DOD-M12B-ACK-1 — a delivery landed, so the impairment is over.
+     *
+     * Without this an `impaired` flag is a one-way door: one bad write would make a session report a
+     * broken conversation for the rest of its life, which is the same class of lie in the other
+     * direction. Called from BOTH send paths — an agent that mostly listens sends content rarely and
+     * ACKs constantly, so clearing only on content would leave exactly those sessions impaired
+     * forever. Only clears 'impaired': a successful write says nothing about a connection libp2p has
+     * already declared 'gone'.
+     */
+    clearSessionImpairment(agentName: string, sessionId: string, observedBy: "direct_send" | "delivery_ack", correlationId?: string): void;
+    /** Test seam (same spirit as getDb()): seed per-session direct-path liveness, which is otherwise
+     *  only set by the live node's onPeerConnect/onPeerDisconnect (#wireSessionLiveness). Lets a
+     *  DB-seeded test exercise the CC-5 reaper's "alive counterparty must survive" gate without standing
+     *  up a real libp2p peer connection. */
+    markSessionLivenessForTest(agentName: string, sessionId: string, state: "alive" | "impaired" | "gone"): void;
+    /**
+     * Drop the liveness verdict for a torn-down session.
+     *
+     * The direct-path liveness flag goes because the seal gate has already read its verdict, so a
+     * destroyed or retired session must not retain a stale alive/gone state that a later read could
+     * mistake for a live one.
+     *
+     * ⚠️ **`#impairmentCause` IS DELIBERATELY LEFT ALONE — clearing it here loses an operator notice.**
+     * It was added for symmetry and reverted. `getSessionImpairment` gates on liveness, so the cause
+     * looks unreachable — but `noteImpairmentRetention` reads it UNGATED, and on the path where
+     * `markSessionImpaired` declines because liveness is already `gone`, the retained cause is what
+     * produces the `outbound_message_lost` notice: *"your message is gone, send it again."* Clearing
+     * it here means the operator is told nothing instead. The cause is cleared where it should be,
+     * in `clearSessionImpairment`.
+     */
+    evictSession(agentName: string, sessionId: string): void;
+}
+//# sourceMappingURL=session-liveness.d.ts.map

package/dist/session-liveness.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-liveness.d.ts","sourceRoot":"","sources":["../src/session-liveness.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,YAAY,CAAC;AACzC,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,2BAA2B,CAAC;AAG3D,OAAO,KAAK,EAAE,kBAAkB,EAAE,iBAAiB,EAAE,MAAM,yBAAyB,CAAC;AACrF,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAC3D,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAC3D,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,yBAAyB,CAAC;AACjE,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,6BAA6B,CAAC;AAEtE,4CAA4C;AAC5C,MAAM,WAAW,sBAAsB;IACrC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,OAAO,EAAE,cAAc,CAAC;IACjC,QAAQ,CAAC,OAAO,EAAE,cAAc,CAAC;IACjC,QAAQ,CAAC,UAAU,EAAE,iBAAiB,CAAC;IACvC,QAAQ,CAAC,iBAAiB,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,CAAC;IAClD,UAAU,CAAC,SAAS,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM,CAAC;IACzD,WAAW,CAAC,GAAG,EAAE,MAAM,GAAG,kBAAkB,GAAG,SAAS,CAAC;IACzD,aAAa,CAAC,SAAS,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,aAAa,CAAC,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,kBAAkB,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAC3H;AAED,qBAAa,eAAe;;gBAGd,GAAG,EAAE,sBAAsB;IAMvC;;;;;;;;;;;;;;;;;;;;;;;OAuBG;IACH,mBAAmB,CACjB,SAAS,EAAE,MAAM,EACjB,SAAS,EAAE,MAAM,EACjB,IAAI,EAAE,SAAS,EACf,kBAAkB,EAAE,MAAM,EAC1B,aAAa,EAAE,MAAM,EACrB,yBAAyB,CAAC,EAAE,MAAM,GACjC,IAAI;IA+IP;;;;;;;OAOG;IACH,kBAAkB,CAAC,SAAS,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,GAAG,UAAU,GAAG,MAAM,GAAG,SAAS;IAGnG;;;;;;;;;;;;;;;;;OAiBG;IACH,mBAAmB,CACjB,SAAS,EAAE,MAAM,EACjB,SAAS,EAAE,MAAM,EACjB,IAAI,EAAE;QAAE,KAAK,EAAE,aAAa,GAAG,cAAc,GAAG,aAAa,CAAC;QAAC,KAAK,EAAE,MAAM,CAAC;QAAC,aAAa,CAAC,EAAE,MAAM,CAAA;KAAE,GACrG,IAAI;IA+BP;;;;;;;;OAQG;IACH,uBAAuB,CAAC,SAAS,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,QAAQ,EAAE,QAAQ,GAAG,SAAS,GAAG,MAAM,GAAG,IAAI;IAuC5G;6FACyF;IACzF,oBAAoB,CAAC,SAAS,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,iBAAiB,GAAG,IAAI;IAKpF;;;;;;;;;OASG;IACH,sBAAsB,CAAC,SAAS,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,UAAU,EAAE,aAAa,GAAG,cAAc,EAAE,aAAa,CAAC,EAAE,MAAM,GAAG,IAAI;IAetI;;;4CAGwC;IACxC,0BAA0B,CAAC,SAAS,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,GAAG,UAAU,GAAG,MAAM,GAAG,IAAI;IAI5G;;;;;;;;;;;;;;OAcG;IACH,YAAY,CAAC,SAAS,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,IAAI;CAGzD"}