@cello-protocol/daemon 0.0.181 → 0.0.182

package/dist/session-node-manager.d.ts

@@ -14,6 +14,8 @@
  * Interrupted-session detection runs BEFORE the IPC socket opens, so a client cannot observe a
  * stale 'active' row from a previous process.
  */
+import { type ContentHashAlg } from "./wire-content-hash.js";
+import { type CapacityReason } from "./refusal-reasons.js";
 import { type DaemonDatabase } from "./sqlcipher-db.js";
 import type { Stream } from "@libp2p/interface";
 import type { Logger, SessionRecord, SealReadinessView } from "./types.js";
@@ -25,6 +27,7 @@ import { type ParkEnvelope } from "./park-envelope.js";
 import { AgentRelayClient, type RelayAssignmentCarry } from "./session-relay-client.js";
 import { RelayReceiptStore, type RelayReceipt } from "./relay-receipt-store.js";
 import { SessionSealLeafStore, type SealCarryLeaf } from "./session-seal-leaf-store.js";
+import type { SealUpgradeReadiness } from "./seal-upgrade.js";
 import { type SecurityGatewayClient } from "@cello-protocol/gateway";
 /**
  * DOD-CAP-SELF-HEAL-1 — how long an interrupted session keeps consuming a cap slot.
@@ -260,6 +263,15 @@ export declare class SessionNodeManager {
         receiptStore?: RelayReceiptStore;
         sealLeafStore?: SessionSealLeafStore;
     }) => AgentRelayClient | undefined): void;
+    /**
+     * Record that this session's tree and the relay's counter have provably parted.
+     *
+     * Idempotent, and deliberately does NOT touch `updated_at`: that column drives the inbox's
+     * last-spoke ordering, and divergence is not activity.
+     */
+    markSessionDiverged(agentName: string, sessionId: string): void;
+    /** Whether this session has provably parted from the relay's ordering. */
+    isSessionDiverged(agentName: string, sessionId: string): boolean;
     /** Arm the park-deposit fault. Returns the count now armed. */
     injectParkFault(count: number, cause?: string): number;
     /** Arm the direct-send fault — makes the next N sends take the dial-failure path. */
@@ -336,8 +348,8 @@ export declare class SessionNodeManager {
      */
     setAwaitingAckHooks(hooks: {
         onPersisted?: (agentName: string, sessionId: string, contentHashHex: string) => void;
-        onTtf?: (agentName: string, sessionId: string, contentHashHex: string, content: Uint8Array, structure1Cbor?: Uint8Array, structure2Cbor?: Uint8Array) => void;
-        onParkFailed?: (agentName: string, sessionId: string, contentHashHex: string, content: Uint8Array, structure1Cbor?: Uint8Array, structure2Cbor?: Uint8Array) => boolean;
+        onTtf?: (agentName: string, sessionId: string, contentHashHex: string, content: Uint8Array, structure1Cbor?: Uint8Array, structure2Cbor?: Uint8Array, contentHashAlg?: string) => void;
+        onParkFailed?: (agentName: string, sessionId: string, contentHashHex: string, content: Uint8Array, structure1Cbor?: Uint8Array, structure2Cbor?: Uint8Array, contentHashAlg?: string) => boolean;
     }): void;
     /**
      * DOD-RETRYQ-STRAND-1: wire the disposition of durable state a session can no longer drain.
@@ -368,6 +380,7 @@ export declare class SessionNodeManager {
         content: Uint8Array;
         structure1Cbor?: Uint8Array;
         structure2Cbor?: Uint8Array;
+        contentHashAlg: string | undefined;
     }) => Promise<{
         ok: true;
     } | {
@@ -417,6 +430,41 @@ export declare class SessionNodeManager {
      * directory for the OFFLINE tree rebuild. Empty when no leaves were logged (e.g. a direct-only session
      * with no relay witness) — the caller then has nothing to carry and the seal stays bilateral/pending.
      */
+    /**
+     * REBUILD THE CERTIFIED ROOT FROM THIS DAEMON'S OWN LEAVES — `DOD-M15-SEALWIRE-1` bullet 2.
+     *
+     * The receipt used to prove only that the directory signed SOMETHING: the client took the sealed
+     * root off the wire, confirmed the directory's signature over those bytes, stored it, and threw
+     * away the root it had computed a step earlier. At co-signing time that means **your key signs a
+     * root you never checked.**
+     *
+     * Bullet 1 moved the certified root into the content-hash domain, which is the domain this daemon
+     * can actually rebuild — each carry leaf's `content_hash` is the leaf hash (RFC 6962 §2.1 "hash"
+     * leaves are used as-is), and the carry is ordered by the relay's canonical `sequence_number`,
+     * which is the order the directory rebuilds in.
+     *
+     * ─── Why this returns "cannot judge" instead of always answering ───────────────────────────
+     *
+     * A root comparison that is WRONG makes every session unsealable, and force-abandon — no receipt —
+     * becomes the only exit. That failure is worse than the one being guarded, and this file already
+     * carries two comments saying so about other gates.
+     *
+     * The carry is this daemon's view, and it is not guaranteed complete at the instant a certificate
+     * arrives: the counterparty's SEAL ctrl leaf is what TRIGGERS the seal, so it may not have been
+     * witnessed here yet. So completeness is checked FIRST, against the certificate's own leaf count.
+     * A short carry means this daemon cannot judge — which is a different answer from "the roots
+     * disagree", and conflating them would turn a local timing gap into an accusation.
+     */
+    verifyCertifiedRoot(agentPubkeyHex: string, sessionIdHex: string, certifiedRoot: Uint8Array, certifiedLeafCount: number): {
+        verdict: "match";
+    } | {
+        verdict: "mismatch";
+        ownRootHex: string | null;
+        detail: string;
+    } | {
+        verdict: "cannot_judge";
+        reason: string;
+    };
     getSealCarry(agentPubkeyHex: string, sessionIdHex: string): SealCarryLeaf[];
     /**
      * DOD-LOG-1 / PERSIST-002 (AC-010): append one readable message to the durable transcript, keyed
@@ -429,7 +477,19 @@ export declare class SessionNodeManager {
      * lost row only cost the unread count. Delivery reads the transcript now, so a swallowed received
      * row is TOTAL content loss and the caller has to know.
      */
-    recordTranscriptMessage(agentName: string, sessionId: string, sequence: number, direction: "sent" | "received", plaintext: Uint8Array, correlationId?: string): boolean;
+    recordTranscriptMessage(agentName: string, sessionId: string, sequence: number, direction: "sent" | "received", plaintext: Uint8Array, correlationId?: string, 
+    /**
+     * DOD-M15-SEALWIRE-1 bullet 5: the VERIFIED authorship proof, when there is one.
+     *
+     * Optional because there legitimately is not always one — the ordering decode can fail SOFT and
+     * the message is still ingested via hash-dedup. Optional is NOT the same as unremarked: absence
+     * is written into the row as `attribution = 'local_session_state'`, so a reader can tell a row
+     * whose author was proven from one whose author was assumed. That distinction is the bullet.
+     */
+    authorship?: {
+        senderPubkey: Uint8Array;
+        senderSig: Uint8Array;
+    }): boolean;
     /**
      * DOD-LOG-1: read a session's durable transcript back (after a restart), decrypted and ordered by
      * canonical sequence then direction. A blob that fails to decrypt (tamper/wrong key) is skipped
@@ -621,6 +681,24 @@ export declare class SessionNodeManager {
     clearRenameNotice(agentName: string, pubkey: string): void;
     /** M8C-CONTACT-1: known stays known until explicitly removed. */
     removeContact(agentName: string, pubkey: string): boolean;
+    /**
+     * Forget the pinned threshold group key for a counterparty, so the next session re-pins.
+     *
+     * DOD-M15-OFFER-SIGNED-1 review F2 — WITHOUT THIS THE REFUSAL WAS PERMANENT. The identity-change
+     * check refuses a counterparty whose group key differs from the one recorded in an earlier
+     * session, and its guidance told the operator to confirm out of band and then remove the contact
+     * so the new identity is pinned afresh. `removeContact` deleted a row in `contacts`; the pin lives
+     * in `sessions.counterparty_primary_pubkey`, and nothing in the daemon ever cleared it.
+     *
+     * So an operator who did exactly as instructed — called their counterparty, confirmed the
+     * re-registration was genuine, removed the contact, retried — got the identical refusal, with no
+     * way out short of editing the database. A security control that cannot be reset by the person it
+     * protects is a lockout, and the printed remedy made it worse by reading as though it worked.
+     *
+     * Nulls the column rather than deleting the session rows: those rows are the transcript record,
+     * and a re-pin is not a reason to lose them.
+     */
+    clearPinnedCounterpartyPrimary(agentName: string, counterpartyPubkeyHex: string): number;
     /** MONIKER-4: the operator's pet name for a pubkey (whoLabel's top tier), or null. Read-only
      *  and tolerant of a not-yet-open DB (a missing label degrades the doorbell, never blocks it). */
     getContactMoniker(agentName: string, pubkey: string): string | null;
@@ -666,7 +744,7 @@ export declare class SessionNodeManager {
         ok: true;
     } | {
         ok: false;
-        reason: string;
+        reason: CapacityReason;
     };
     /** M8C-TGDOOR-1: the daemon-wide Telegram bot settings, or null if never configured. */
     getTelegramSettings(): {
@@ -737,10 +815,85 @@ export declare class SessionNodeManager {
         addrs: string[];
     } | null;
     /**
-     * The standing receiver's libp2p node — a general-purpose, OPEN-gater node usable for
-     * OUTBOUND dials that are not session-scoped (e.g. the content-park deposit/pull to the
-     * relay, MSG-001-3b). Session nodes have restrictive gaters; the standing receiver does not.
-     * Returns null until the receiver is ready.
+     * DOD-M15-ASSIGN-1 — name the one peer allowed to dial this agent's standing receiver, at the
+     * moment the directory's `session_offer` says who is coming.
+     *
+     * This is what makes the receiver's deny-by-default safe. The offer names
+     * `initiator_session_peer_id`, and the responder answers it by advertising its OWN address in
+     * `session_offer_accept`. Narrowing here — BEFORE that answer goes out — means the door opens to
+     * exactly one peer at the same instant the address that reaches them is published, and never
+     * before. The initiator cannot know where to dial until the accept it triggers has been sent.
+     *
+     * Returns WHICH failure it was, never a bare false (review F6). The caller reports a distinct
+     * reason per cause: "no receiver" and "the directory named nobody" are different subsystems, and
+     * collapsing them sent the operator to the directory for a local problem. This method never
+     * widens the gate to compensate.
+     *
+     * Narrows INBOUND ONLY. The receiver is still the daemon's general-purpose dialer at this point
+     * — no assignment exists yet — so revoking its outbound latitude here would break content
+     * parking and restart-seal submission (review F2).
+     */
+    admitOfferedDialer(agentName: string, initiatorSessionPeerId: string, sessionIdHex: string): "narrowed" | "no_receiver" | "no_peer_named";
+    /**
+     * What the UNSIGNED offer claimed, so the SIGNED assignment can be checked against it.
+     *
+     * DOD-M15-OFFER-SIGNED-1. Decision 2 rules that the listening socket is "gated on the
+     * assignment", and the gate is narrowed from `session_offer` — a frame carrying no signature —
+     * because that is the only thing that arrives early enough. Timing forced the offer; it does not
+     * excuse trusting it.
+     *
+     * Keeping what the offer said turns the two frames into a CHECK ON EACH OTHER. The assignment is
+     * FROST-signed by the initiator's own threshold group, which no single directory can produce, and
+     * it names the same peer id. A directory that says one peer in the offer and another in the
+     * assignment is naming two different dialers for one session — which a truthful directory never
+     * does, and which is exactly the move a compromised one would make to slip a peer past the gate
+     * before the signed document arrives.
+     */
+    getOfferedDialer(agentName: string, sessionIdHex: string): string | null;
+    /**
+     * Which peer this agent's standing receiver is currently admitting INBOUND — `null` for nobody.
+     *
+     * Read-only, and it answers a question the daemon otherwise cannot: *"whose dial would this
+     * receiver accept right now?"* The gate is narrowed and re-closed from several paths (an offer
+     * arrives, an assignment is refused, a session is promoted), and until now the only way to know
+     * where it had ended up was to reproduce the sequence in your head.
+     *
+     * Added for `DOD-M15-RESPONDER-VERIFY-1`, where a refusal for one session was closing the gate a
+     * DIFFERENT session had narrowed — a defect with no observable symptom short of the second
+     * session's initiator being refused with "nothing invited it".
+     */
+    getStandingReceiverAllowedPeer(agentName: string): string | null;
+    /** Forget the offered dialer for ONE session — called on BOTH the claim and the refusal paths. */
+    clearOfferedDialer(agentName: string, sessionIdHex: string): void;
+    /**
+     * RE-CLOSE the standing receiver — but ONLY if this session is still the one holding it.
+     *
+     * DOD-M15-OFFER-SIGNED-1 review F4, then N1. The first version closed the gate unconditionally,
+     * and that was worse than the defect it fixed: an agent has ONE standing receiver with ONE allowed
+     * peer, so a refusal for session P closed the gate that offer Q had narrowed. Q's initiator —
+     * invited, legitimate — was then refused with *"nothing invited it"*, which this daemon had.
+     *
+     * That is the same cross-session interference F1 was written to remove, moved one method along,
+     * and triggerable the same way: one bogus offer/assignment pair collapses a concurrent real
+     * session.
+     *
+     * So the gate is closed only when it still names the peer THIS session opened it to. If a later
+     * offer has already re-narrowed it, that offer owns the receiver and its narrowing stands.
+     *
+     * NO EVICTION SWEEP, deliberately (N4). The sweep evicts by "not the allowed peer", and
+     * `getConnections()` returns OUTBOUND connections too — including the content-park and
+     * restart-seal dials this node makes as the daemon's general-purpose dialer, whose targets are on
+     * no allowlist by construction. Sweeping here hung those up, and the failure surfaced as
+     * `relay_unavailable`: a transport label for a local decision, which is the exact substitution
+     * that comment was written to prevent. The load-bearing control is `DOD-M15-FRAME-1`'s frame gate,
+     * which refuses what an unauthorised peer sends; closing the door is enough here.
+     */
+    revokeOfferedDialer(agentName: string, sessionIdHex: string, offeredPeerId: string | null): void;
+    /**
+     * The standing receiver's libp2p node — a general-purpose node usable for OUTBOUND dials that
+     * are not session-scoped (e.g. the content-park deposit/pull to the relay, MSG-001-3b). Its
+     * gater admits nobody INBOUND until a session names them (DOD-M15-ASSIGN-1), but leaves these
+     * outbound errands open. Returns null until the receiver is ready.
      */
     getStandingReceiverNode(agentName?: string): CelloNode | null;
     /**
@@ -1040,14 +1193,6 @@ export declare class SessionNodeManager {
      * escalates to a unilateral seal. This column only withdraws the session from AUTOMATIC retries.
      */
     markRestartSealGaveUp(agentName: string, sessionId: string, reason: string): void;
-    /**
-     * cello_list_sessions: every persisted session for one agent, regardless of
-     * status (active, interrupted, sealed, seal_interrupted_pending). Ordered most
-     * recently updated first so the live session surfaces at the top. This is the
-     * discovery surface that the by-id reads (cello_get_transcript /
-     * cello_get_sealed_receipt) depend on — without it an agent has no way to learn
-     * its own session ids after a restart or from a fresh MCP connection.
-     */
     getSessionsForAgent(agentName: string): SessionRecord[];
     /**
      * Every persisted session across ALL agents, most-recently-updated first. Backs the daemon-wide
@@ -1102,6 +1247,26 @@ export declare class SessionNodeManager {
      * signature locally. Best-effort — a missing row (race) is a no-op; the seal then falls back to
      * accept-without-verify (still sound: the live frame arrives over the authenticated Noise channel).
      */
+    /**
+     * The counterparty's threshold group key as this agent has seen it BEFORE — trust on first use.
+     *
+     * DOD-M15-OFFER-SIGNED-1 / RESPONDER-VERIFY-1. The responder does not verify the assignment's
+     * signature (deferred to SESSION-004), so every field in it is whatever the directory said. That
+     * makes a same-frame check circular: a compromised directory just says the same thing twice.
+     *
+     * This is the one anchor the responder holds that a directory CANNOT retroactively change — its
+     * own memory of previous sessions with this counterparty. A directory that names a different
+     * threshold group key for someone you have already talked to is either substituting an identity
+     * or has been compromised since; neither is a session to accept quietly.
+     *
+     * THE BOUND, stated rather than glossed: this is worth nothing on FIRST contact, which is the
+     * definition of trust-on-first-use. It hardens every session after it, which is where a long-lived
+     * counterparty relationship actually lives.
+     *
+     * Keyed on `counterparty_pubkey` — the K_local IDENTITY, which is the stable thing — not on a
+     * session id or a display name.
+     */
+    getPinnedCounterpartyPrimary(agentName: string, counterpartyPubkeyHex: string): string | null;
     recordCounterpartyPrimary(agentName: string, sessionId: string, primaryPubkeyHex: string): void;
     /**
      * M7-SESSION-004 (AC-005/AC-006): read the persisted seal certificate for a session.
@@ -1276,14 +1441,45 @@ export declare class SessionNodeManager {
      *     cross-process ordering (and thus AC-002 root agreement under concurrent
      *     bidirectional traffic) requires the relay-assigned sequence from MSG-001.
      */
-    sendContent(agentName: string, sessionId: string, content: Uint8Array, contentHash: Uint8Array, correlationId?: string, 
+    sendContent(agentName: string, sessionId: string, content: Uint8Array, contentHash: Uint8Array, 
+    /**
+     * Required alongside the two below — every production caller already passes one, and an optional
+     * parameter in front of a required one is what TypeScript refuses. Making it explicit costs
+     * nothing and removes the last place a positional argument can silently shift.
+     */
+    correlationId: string | undefined, 
     /**
      * The DOMAIN this content belongs to, as the relay and the directory will see it. Defaults to
      * MESSAGE so `cello_send` is unchanged; the document path passes 0x04/0x05. Not cosmetic — the
      * directory computes `final_message` and `answered` from the witnessed kind, and both of its
      * document exclusions were dead while every document leaf arrived here as a message.
+     *
+     * ⚠️ ALSO REQUIRED NOW, and for the same reason as `contentHashAlg` below — this parameter is the
+     * precedent, not a bystander. It defaulted to MESSAGE, the document adapter in `daemon.ts`
+     * silently dropped it, and the wire was wrong for a whole release: *"0.0.145 shipped the fix
+     * everywhere except here."* A default that matches the common case makes the omission invisible
+     * at every call site and at typecheck. Every caller states its kind now.
+     */
+    leafKind: number, 
+    /**
+     * `DOD-M15-SEALWIRE-1` part B2b — the algorithm `contentHash` was produced under, taken from
+     * `contentHashForSession` by the caller that computed the hash.
+     *
+     * Passed rather than re-derived HERE, deliberately: re-deriving would ask "how would this
+     * session hash something now?", and the answer can differ from how THIS message was actually
+     * hashed. A hash and its label must travel together or the peer refuses a message nobody touched.
+     *
+     * ⚠️ REQUIRED, NOT DEFAULTED — review B2b-1 F4, and the default is what made four mutants
+     * unfalsifiable. It was `= CONTENT_HASH_ALGS.SHA256`, which equals the only value in play today,
+     * so DROPPING THE ARGUMENT AT ANY OF THE FIVE HOPS produced byte-identical output and the whole
+     * 2,800-test daemon suite stayed green. Measured at all four send sites individually.
+     *
+     * A default that equals the current value makes every threading edit invisible until the value
+     * changes — and the day it changes, the dropped argument mislabels the message and every peer
+     * refuses it as a tamper. Required makes a dropped argument a TYPECHECK failure instead of a
+     * test question nobody can answer.
      */
-    leafKind?: number): Promise<{
+    contentHashAlg: string): Promise<{
         ok: true;
         delivered: true;
         sequenceNumber?: number;
@@ -1334,27 +1530,55 @@ export declare class SessionNodeManager {
      * completeness check (the `desynced` reason) requires the deferred MSG-001-3b canonical-sequence
      * reconciliation — same documented limitation as the UP-2 gate above.
      */
-    getSealUpgradeReadiness(agentName: string, sessionId: string): {
-        known: boolean;
-        tampered: boolean;
-    };
+    getSealUpgradeReadiness(agentName: string, sessionId: string): SealUpgradeReadiness;
+    /** Record an inbound refusal for the operator. First of its kind per session is the signal. */
+    noteContentRefusal(agentName: string, sessionId: string, reason: string, detail?: {
+        impact?: string;
+        guidance?: string;
+    }): void;
     /**
-     * DAEMON-004: cross-check received content against its hash, append the
-     * verified leaf to the daemon-owned tree, and buffer it for cello_receive.
-     * A hash MISMATCH is genuine tamper — rejected without append or buffer.
+     * Drain the refusals a GIVEN CONSUMER has not been shown yet, and remember what it was shown.
+     *
+     * ─── Why this is keyed by connection, and not by a single flag ─────────────────────────────────
      *
-     * SCOPE / finding #5 — what this cross-check does and does NOT prove today:
-     * `contentHash` here is carried in the SAME content_frame as `content`, so this
-     * comparison only catches wire corruption of a single frame — it does NOT prove
-     * the content matches what the sender independently committed. Full tamper-
-     * evidence (EARS behavior #2) requires cross-checking against the K_local-signed
-     * content_hash leaf the sender submits to the RELAY on a separate channel; that
-     * relay hash-submit path is MSG-001's scope and does not exist yet. Until MSG-001
-     * lands, a malicious sender that sends matching (content, hash) in one frame is
-     * not detected here — only the relay-relayed signed leaf closes that gap.
+     * It used to set one `surfaced: boolean` on the notice. Two MCP windows attending the same agent
+     * is the ordinary case, and under that flag whoever read FIRST consumed the notice — the second
+     * window was told nothing, permanently. **That is the same defect `takeReceivedContent` had**, and
+     * the comment above the delivery loop in `session-content-handlers.ts` spells out why it was
+     * removed: *"reading is non-destructive by construction. Nothing one consumer does mutates state
+     * another consumer reads."* The whole `taken_by_sibling` apparatus exists because this was paid
+     * for once already; re-introducing it on a different surface makes it no less true.
      *
-     * @returns the appended leaf index (as sequenceNumber) on success.
+     * ─── Why the count now has a reader ────────────────────────────────────────────────────────────
+     *
+     * The old docstring claimed *"count still grows underneath, so a later reader can ask how many
+     * without being told again."* **There was no later reader.** After the first surfacing the count
+     * incremented under a flag the drain skipped unconditionally, so 3 refusals became 903 and nothing
+     * anywhere could say so — while the comment asserted the opposite.
+     *
+     * So a reason RE-ANNOUNCES to a consumer when its count has grown by an order of magnitude since
+     * that consumer last saw it (1 → 10 → 100 → …), marked `repeat: true`. That keeps the first
+     * refusal the signal and the ninetieth silent, which is the dedup's point, while still making a
+     * skew that has swallowed hundreds of messages visible — at a handful of announcements per
+     * session, not one per message.
      */
+    takeContentRefusals(agentName: string, sessionId: string, 
+    /**
+     * REQUIRED, deliberately — no default.
+     *
+     * It had one (`"default"`), and a default is the defect this method was rewritten to remove,
+     * lying in wait: any future call site that omits the argument silently shares ONE bucket across
+     * every window, the first reader consumes the notice for all the others, and nothing fails to
+     * compile and no test goes red. The parameter existing is not the protection; being unable to
+     * forget it is.
+     */
+    consumerId: string): Array<{
+        reason: string;
+        impact?: string;
+        guidance?: string;
+        count: number;
+        repeat?: boolean;
+    }>;
     ingestReceivedContent(agentName: string, sessionId: string, content: Uint8Array, contentHash: Uint8Array, correlationId?: string, 
     /**
      * DOD-FRONTIER-STRAND-1 AC1: the relay-assigned canonical position for THIS message, taken from
@@ -1363,7 +1587,29 @@ export declare class SessionNodeManager {
      * collapse in it before dedup is ever consulted, which is the whole defect. Absent when the
      * session has no relay witness (relay-degraded): see the announced fallback below.
      */
-    canonicalSeqIn?: number): Promise<{
+    canonicalSeqIn?: number, 
+    /**
+     * DOD-M15-SEALWIRE-1 part B1 — the algorithm the SENDER named on the frame, verbatim.
+     *
+     * `undefined` means the frame carried no name, which is a peer that predates the field and is
+     * the one case we may safely assume `sha256` for. It is threaded through rather than read off
+     * the session, because whether a hash is salted is a fact about the FRAME and its sender, never
+     * about what this side happens to hold.
+     */
+    contentHashAlgIn?: string | null, 
+    /**
+     * DOD-M15-SEALWIRE-1 bullet 5: the VERIFIED authorship proof for this message, when the caller
+     * has one. The caller is the only place that has it — `#recordFrameOrdering` verifies the
+     * signature against the key inside the sender's own signed bytes and matches the signer to this
+     * session's counterparty, and that result reaches here or nowhere.
+     *
+     * Optional, because the soft decode-failure path ingests without it. The row records which it
+     * was, so absence is never silent.
+     */
+    verifiedAuthorship?: {
+        senderPubkey: Uint8Array;
+        senderSig: Uint8Array;
+    }): Promise<{
         ok: true;
         leafIndex: number;
         sequenceNumber: number;
@@ -1435,6 +1681,16 @@ export declare class SessionNodeManager {
          *  counterparty's. They block a seal identically and mean completely different things. */
         heldOwn: number;
         heldReceived: number;
+        /**
+         * DOD-M15-DIVERGE-1 — this tree and the relay's counter have PROVABLY parted.
+         *
+         * The other two counters both measure the same direction: positions the relay committed that
+         * this tree has not appended. This is the OPPOSITE direction — this tree holds a leaf at a
+         * position the relay assigned to something else — and it is the direction an injected or forged
+         * leaf appears in. Without it `ready` was asymmetric, and a diverged session read as perfectly
+         * sealable right up until the counterparty answered `leaf_count_mismatch`, which is terminal.
+         */
+        diverged: boolean;
     };
     /**
      * DOD-M12B-SEAL-STUCK-1 — the operator-facing answer to "can this session be closed?".
@@ -1626,6 +1882,120 @@ export declare class SessionNodeManager {
      * record (the recover handler lives in daemon.ts, which has no access to the private method).
      */
     recordOrderingRecord(agentName: string, sessionId: string, structure1Cbor: Uint8Array, structure2Cbor: Uint8Array, contentHash: Uint8Array, correlationId?: string): number | null;
+    /**
+     * Test seam: force this session's own salt half, so the LOCAL-defect path is reachable.
+     *
+     * `generateSaltContribution` cannot produce a degenerate half, which is the point of it — so the
+     * only way to exercise "our own random source is broken" end-to-end is to stand in for the broken
+     * source. Named `…ForTest` like every other seam in this file, and it writes the same map
+     * production writes rather than a parallel one, so a test cannot pass against state the daemon
+     * never reads.
+     */
+    /**
+     * Test seam: run the auto-acknowledge gate, exactly as the counterparty's SEAL ctrl leaf does.
+     *
+     * `DOD-M15-SEALWIRE-1` part B1, review F-B. The gate has ONE production call site — inside the
+     * relay leaf handler, behind `leaf_kind === CTRL && !authored_by_us` — so reaching it from a test
+     * needs a live relay client delivering a real ctrl leaf. The consequence was measured: my
+     * "tampered never downgrades" test wrapped its decisive assertion in
+     * `if (skipped.length > 0)`, which was ALWAYS FALSE, so the whole `content_tamper` vs
+     * `content_verification_unavailable` branch had no coverage anywhere in the repo and two mutants
+     * on it survived the full gate.
+     *
+     * It calls the REAL private method rather than reproducing its logic, so a test cannot pass
+     * against a decision production does not make.
+     */
+    runAutoAcknowledgeGateForTest(agentName: string, sessionId: string, correlationId?: string): void;
+    setSaltContributionForTest(agentName: string, sessionId: string, contribution: Uint8Array): void;
+    /**
+     * Test seam: drop this session's own half while leaving the stored salt in place — the state every
+     * teardown produces, because `#evictSessionCaches` clears the map and the row survives.
+     *
+     * It clears the SAME map the eviction clears rather than a stand-in, so a test cannot pass against
+     * a state the daemon never reaches. Reproducing it through a real teardown/revive would also drag
+     * in node rebuild and relay reconnection, none of which this is about.
+     */
+    forgetSaltContributionForTest(agentName: string, sessionId: string): void;
+    /**
+     * THE ONE PLACE THAT DECIDES HOW A SESSION'S OUTBOUND CONTENT IS HASHED —
+     * `DOD-M15-SEALWIRE-1` part B2b.
+     *
+     * Returns the hash AND the algorithm that produced it, together, because the two must not be
+     * decided separately. `wire-content-hash.ts` exists for exactly this reason and says so in its own
+     * header: the expression was written out at five call sites, the two added last got it wrong, and
+     * the failure was invisible — *"the send succeeds, `parked: false`, the sender's log says the frame
+     * left, and the receiver discards it at the authenticity check."* It took two real daemons.
+     *
+     * There are FOUR outbound sites (`session-content-handlers.ts`, two in `daemon.ts`,
+     * `document-delivery-transport.ts`). Once salting is switchable, each of them independently
+     * deciding whether to salt is that defect again with a worse failure mode — a message hashed one
+     * way and LABELLED another is refused by every peer, including a correct one.
+     *
+     * ⚠️ ASYNC, AND THAT IS THE POINT — B2b-2 constraint 2, not an implementation detail.
+     *
+     * The agreement is in flight while the operator composes their first message. Hash without waiting
+     * and it comes out unsalted, and that first unsalted hash closes adoption for the LIFE of the
+     * session (Decision #8, unit 1). Every session would fall back permanently while every log line
+     * about it stayed true — the feature present, wired, tested, and never once reached.
+     *
+     * The wait lives HERE rather than at the four call sites for the same reason `contentHashAlg` is a
+     * required parameter rather than a defaulted one: a site that forgets it must fail to compile. A
+     * caller that drops the `await` gets a `Promise` where bytes belong, which is a typecheck error;
+     * a caller that forgot to call a separate `awaitSaltSettled()` would silently send unsalted.
+     */
+    contentHashForSession(agentName: string, sessionId: string, content: Uint8Array): Promise<{
+        hash: Uint8Array;
+        alg: ContentHashAlg;
+    }>;
+    /**
+     * THIS SESSION'S UNSALTED HASH NEVER BECAME A MESSAGE — release the permanent closure it caused.
+     *
+     * ⚠️ REVIEW FINDING 3, and it is the opposite of the direction the flag was written to defend.
+     * `#hashedWithoutSalt` closes adoption at hash time, because for a session's first message the
+     * leaf is a network round trip away and every frontier count reads zero in between. Correct — but
+     * `cello_send` has three paths that compute the hash and then produce NOTHING: a sibling send
+     * holding the in-flight claim, the frontier moving under the send, and a non-durable send failure
+     * whose bytes go to a queue with no production consumer.
+     *
+     * In all three the session was permanently unsalted for a message that exists nowhere: no leaf, no
+     * wire, no copy at the peer. And B2b-2 made two of them MORE likely on a first message, because
+     * the five-second wait widens the very window the frontier re-check is watching.
+     *
+     * Only safe because it is called on paths that provably sent nothing. It deliberately does NOT
+     * clear `#unsaltedAnnounced`: the announcement was true when it fired and re-announcing on the
+     * retry would be the per-message flood Decision #15 forbids.
+     *
+     * ─── THREE OTHER SITES HASH AND MAY SEND NOTHING, AND ARE EXEMPT ON PURPOSE (pass 2, F8) ──────
+     *
+     * `daemon.ts`'s one-shot rejection and away reply, and `document-delivery-transport.ts`'s frame
+     * send, can all fail after hashing. None of them needs to abandon, and the reason is the same in
+     * each: every one is a REPLY. The inbound message that triggered it has already been leafed on
+     * this side, so `#saltAdoptionClosed` is already closed by the leaf count and would stay closed
+     * whatever this flag said. Calling abandon there would be a no-op that looks like a guarantee.
+     *
+     * Written down rather than left to be re-derived: the next reader's first question is why the
+     * list is three and not six.
+     */
+    abandonUnsaltedHash(agentName: string, sessionId: string): void;
+    /**
+     * TEST SEAM — put a session into the state a real one is in between announcing and being answered.
+     *
+     * Reaching that state for real needs a live counterparty connection, which the daemon-level
+     * fixtures do not have; without a seam the wait could only be tested by not testing it. It calls
+     * the same private registration the announce path calls, so it cannot drift from it.
+     */
+    markSaltAgreementPendingForTest(agentName: string, sessionId: string, boundMs?: number): void;
+    /**
+     * PUBLIC read of a session's agreed salt — `DOD-M15-SEALWIRE-1` part B2a.
+     *
+     * `content-park.ts` runs a SECOND, independent content-hash verifier (the park signature does not
+     * cover the envelope content, so it checks before `ingestReceivedContent` is ever reached), and it
+     * hardcoded `sha256`. It needs the salt to verify a v3 envelope, and it is outside this class.
+     *
+     * Read-only and cache-backed, so exposing it adds no way to CHANGE the salt from outside — the
+     * only writer remains `#persistSessionSalt`, behind the one-salt-per-session predicate.
+     */
+    getSessionContentSalt(agentName: string, sessionId: string): Uint8Array | null;
     /**
      * M7-SESSION-001 AC-004/AC-005: Register a relay stream for an active session.
      * Starts a background reader that watches for session_interrupted frames and