@cello-protocol/daemon 0.0.3 → 0.0.5

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

@@ -0,0 +1,585 @@
+/**
+ * CELLO Daemon — SessionNodeManager
+ *
+ * Manages the lifecycle of all ephemeral session nodes:
+ *   1. Per-session nodes: fresh transport key + Peer ID, connectionGater allows
+ *      only the designated counterparty. Created during cello_initiate_session
+ *      (outbound) or cello_await_session (inbound, via standing receiver handoff).
+ *   2. Standing receiver node: pre-created, open gater, kept alive at all times.
+ *      Handed to the first inbound session; immediately replaced.
+ *   3. 32-node cap: enforced before any new node is created.
+ *   4. Session status in SQLite: active → sealed (on close) or interrupted
+ *      (on graceful shutdown or SIGKILL-restart detection).
+ *
+ * Pseudocode (SPARC Phase P):
+ *
+ * initialize():
+ *   1. Open SQLite (node:sqlite), create sessions table if not exists
+ *   2. Detect interrupted sessions: SELECT * FROM sessions WHERE status='active'
+ *      → batch-update to 'interrupted', log session.interrupted.detected for each
+ *      (source: 'daemon_restart') — runs before IPC socket opens so no race
+ *   3. Create standing receiver node (fresh libp2p, open gater, sentinel agentName)
+ *   4. Start standing receiver, set standingReceiverReady=true
+ *   5. Log session.node.created for the standing receiver
+ *
+ * createSessionNode(sessionId, agentName, counterpartyPubkey, counterpartyPeerId, correlationId):
+ *   Pseudocode:
+ *   1. Check activeNodes.size >= MAX_SESSION_NODES → log cap.reached, return error
+ *   2. Create SessionConnectionGater(counterpartyPeerId) — restricted from birth
+ *   3. nodeFactory.createNode({gater}) → fresh libp2p node
+ *   4. node.start() — bind TCP ephemeral port
+ *   5. Insert SQLite row status='active'
+ *   6. Log session.node.created
+ *   7. Add to activeNodes map
+ *   8. Return {ok:true, peerId, addrs}
+ *   On libp2p error: extract error.message (never ${error}), log create.failed, return error
+ *
+ * acceptSession(sessionId, agentName, counterpartyPubkey, initiatorPeerId, correlationId):
+ *   Pseudocode:
+ *   1. If !standingReceiverReady → return standing_receiver_unavailable
+ *   2. Take standing receiver from slot (clear slot atomically)
+ *   3. gater.setAllowedPeer(initiatorPeerId) ← BEFORE returning multiaddr (AC-015)
+ *   4. Insert SQLite row status='active'
+ *   5. Log session.node.created
+ *   6. Add to activeNodes map
+ *   7. Trigger async replacement of standing receiver (do NOT await)
+ *   8. Return {ok:true, peerId, addrs}
+ *
+ * destroySessionNode(sessionId, reason):
+ *   Pseudocode:
+ *   1. Find node in activeNodes
+ *   2. stop node
+ *   3. Update SQLite status to sealed/interrupted/error
+ *   4. Remove from activeNodes
+ *   5. Log session.node.destroyed
+ *
+ * gracefulShutdown():
+ *   Pseudocode:
+ *   1. Get all activeNodes
+ *   2. For each: update SQLite 'interrupted', log destroyed(reason:'interrupted')
+ *   3. Stop all nodes
+ *   4. Stop standing receiver
+ *
+ * getStatus(): { standingReceiverReady: boolean }
+ */
+import { DatabaseSync } from "node:sqlite";
+import { TranscriptCipher } from "./transcript-cipher.js";
+import type { Stream } from "@libp2p/interface";
+import type { Logger, SessionRecord } from "./types.js";
+import { SessionConnectionGater } from "./session-connection-gater.js";
+import { SessionTree, type SessionTreeLeafKind } from "./session-tree.js";
+import { type CelloNode, type IAutoNatService } from "@cello-protocol/transport";
+import type { KeyProvider } from "@cello-protocol/crypto";
+/**
+ * M7 DOD-SPINE-6 / MSG-001-3b: the inputs a session node needs to connect to the relay
+ * as the Structure-2 witness (relay endpoint from the FROST-signed assignment + the
+ * agent's K_local identity + the 16-byte session id). Optional on node creation: when
+ * absent (or connect fails), the session still works over the direct content path — the
+ * relay just doesn't witness the leaf yet.
+ */
+export interface RelayConnectParams {
+    relayPeerId: string;
+    relayAddrs: string[];
+    keyProvider: KeyProvider;
+    senderPubkey: Uint8Array;
+    sessionIdBytes: Uint8Array;
+}
+/**
+ * Adapter interface for session node creation. Allows test injection of a
+ * failing factory (AC-007) without touching the real libp2p stack.
+ * The adapter pattern is mandatory per outline.md constraints.
+ */
+export interface ISessionNodeFactory {
+    createNode(config: SessionNodeConfig): Promise<CelloNode>;
+}
+export interface SessionNodeConfig {
+    sessionId: string;
+    connectionGater?: SessionConnectionGater;
+    /**
+     * CELLO-M7-TRANSPORT-001: role of the node, forwarded to createNode to tune the
+     * libp2p service set (dcutr is included for 'session' dialers, omitted for the
+     * 'standing_receiver'). AutoNAT is present for both.
+     */
+    nodeType?: "session" | "standing_receiver";
+    /**
+     * M7-SESSION-003 (AC-005): keepalive ping interval for the session node so a
+     * counterparty that vanishes without a clean close is detected within a bounded
+     * window. Factories should forward this to createNode({ keepAliveIntervalMs }).
+     */
+    keepAliveIntervalMs?: number;
+}
+/** DAEMON-004: a piece of content received and verified, awaiting cello_receive. */
+interface ReceivedContentEntry {
+    contentHex: string;
+    senderPubkey: string;
+    sequenceNumber: number;
+}
+type CreateSessionResult = {
+    ok: true;
+    peerId: string;
+    addrs: string[];
+} | {
+    ok: false;
+    reason: string;
+    guidance: string;
+};
+export declare class SessionNodeManager {
+    #private;
+    constructor(opts: {
+        factory: ISessionNodeFactory;
+        logger: Logger;
+        dbPath: string;
+        contentTtfMs?: number;
+        /**
+         * CELLO-M7-TRANSPORT-001: provider for the AutoNAT directory-node prober set
+         * (SI-002). Defaults to () => [] (reconnecting — no probers), which makes
+         * dialability the conservative default and fires transport.autonat.unavailable.
+         */
+        autoNatProbers?: () => string[];
+    });
+    /**
+     * CELLO-M7-MSG-001: wire the durable-backstop side effects of the awaiting-ACK
+     * lifecycle. `onPersisted` clears the durable retry_queue entry when a persisted ACK
+     * arrives; `onTtf` records/parks the un-acked content when the TTF timer fires.
+     * Injected by the composition root (daemon.ts) after the RetryQueue exists.
+     */
+    setAwaitingAckHooks(hooks: {
+        onPersisted?: (agentName: string, sessionId: string, contentHashHex: string) => void;
+        onTtf?: (agentName: string, sessionId: string, contentHashHex: string, content: Uint8Array) => void;
+    }): void;
+    /**
+     * MSG-001-3b (2b): inject the live content-park deposit (seal + ContentParkClient.deposit).
+     * Injected by the composition root (daemon.ts). When absent, a not-confirmed send still records
+     * the durable awaiting entry (crash backstop) but does not deposit live.
+     */
+    setContentParkHook(fn: (args: {
+        sessionId: string;
+        recipientPubkeyHex: string;
+        relayPeerId: string;
+        relayAddrs: readonly string[];
+        contentHashHex: string;
+        content: Uint8Array;
+        structure1Cbor?: Uint8Array;
+        structure2Cbor?: Uint8Array;
+    }) => Promise<void>): void;
+    initialize(): Promise<void>;
+    /**
+     * Get the underlying DatabaseSync handle.
+     * Used by the composition root (daemon.ts) to pass to RetryQueue and
+     * NonceDedupStore — they share the same SQLCipher DB file (DAEMON-003 AC-008).
+     */
+    getDb(): DatabaseSync;
+    /**
+     * DOD-LOG-1: the at-rest cipher, shared with the RetryQueue so its content_blob is encrypted with
+     * the SAME key as the transcript. Available after initialize().
+     */
+    getTranscriptCipher(): TranscriptCipher;
+    /**
+     * DOD-LOG-1: append one readable message to the durable, encrypted-at-rest transcript, keyed by
+     * the canonical leaf `sequence` so it joins to the committed hash chain. Idempotent on replay
+     * (INSERT OR IGNORE — the same (session, sequence, direction) is written at most once). Never
+     * throws into the caller's content path: a transcript-write failure is logged, not fatal.
+     */
+    recordTranscriptMessage(agentName: string, sessionId: string, sequence: number, direction: "sent" | "received", plaintext: Uint8Array, correlationId?: string): void;
+    /**
+     * 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
+     * with a loud log rather than crashing the read.
+     */
+    readTranscript(agentName: string, sessionId: string): {
+        messages: Array<{
+            sequence: number;
+            direction: "sent" | "received";
+            text: string;
+            createdAt: number;
+        }>;
+        undecryptable: number;
+    };
+    /** DOD-LOOP-1: whether the given agent has a standing receiver ready (any agent if omitted). */
+    getStandingReceiverReady(agentName?: string): boolean;
+    /**
+     * The current standing receiver node's session-transport coordinates (peer id +
+     * listen multiaddrs), or null if it is not ready. These are the addresses a local
+     * SessionNegotiator advertises as this node's counterparty endpoint so the initiator
+     * can dial it, and the value an inbound session_assignment carries in its
+     * counterparty_session_* fields. Read-only — does NOT consume the standing receiver
+     * (unlike acceptSession, which hands it off).
+     */
+    getStandingReceiverInfo(agentName: string): {
+        peerId: string;
+        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.
+     */
+    getStandingReceiverNode(agentName?: string): CelloNode | null;
+    /**
+     * The libp2p Peer ID of an active session's node (N_A for an initiated session), or
+     * null if no active node exists for it. This is the initiator's session peer id that an
+     * inbound session_assignment must carry to the counterparty (so the counterparty gates
+     * its handed-off receiver to it). Read-only.
+     */
+    getSessionNodePeerId(agentName: string, sessionId: string): string | null;
+    /**
+     * CELLO-M7-TRANSPORT-001: the AutoNAT service wrapping the current standing
+     * receiver node, or null if the standing receiver is not ready. The composition
+     * root uses this as the daemon's runtime IAutoNatService — its getDialability()
+     * drives the SessionAssignment advertised address (AC-004/AC-019), and it is the
+     * source of the transport.autonat.result / transport.autonat.unavailable events.
+     */
+    getStandingReceiverAutoNat(): IAutoNatService | null;
+    /**
+     * M7-SESSION-001 (M-1 PUSH): register the session-state-change callback.
+     * Called by the composition root (daemon.ts) after the NotificationDispatcher
+     * exists. Setter injection avoids a construction-order/circular dependency.
+     */
+    setOnSessionStateChanged(cb: (agentName: string, sessionId: string, state: string, counterpartyPubkey: string | null) => void): void;
+    /**
+     * Create a new outbound session node.
+     * Called during cello_initiate_session.
+     *
+     * @param sessionId      Unique session ID (hex string)
+     * @param agentName      Name of the initiating agent
+     * @param counterpartyPubkey  Counterparty's K_local public key (hex)
+     * @param counterpartyPeerId  Counterparty's session-layer Peer ID (for gater)
+     * @param correlationId  Correlation ID minted at session initiation
+     */
+    createSessionNode(sessionId: string, agentName: string, counterpartyPubkey: string, counterpartyPeerId: string, correlationId: string, reuseStandingReceiver?: boolean, relay?: RelayConnectParams): Promise<CreateSessionResult>;
+    /**
+     * M7-SESSION-003: read the direct-path counterparty liveness for a session.
+     * 'unknown' when no session node observation has occurred yet.
+     */
+    getSessionLiveness(agentName: string, sessionId: string): "alive" | "gone" | "unknown";
+    /**
+     * Hand the standing receiver to an inbound session.
+     * Called during cello_await_session.
+     *
+     * CRITICAL (AC-015): gater.setAllowedPeer() is called BEFORE returning
+     * the node's multiaddr to the caller. This closes the window where an
+     * unexpected peer could connect during the hand-off.
+     */
+    acceptSession(sessionId: string, agentName: string, counterpartyPubkey: string, initiatorPeerId: string, correlationId: string, relay?: RelayConnectParams): Promise<CreateSessionResult>;
+    /**
+     * Destroy a session node after seal or on error teardown.
+     * Status written to SQLite.
+     */
+    destroySessionNode(agentName: string, sessionId: string, reason: "sealed" | "interrupted" | "error"): Promise<void>;
+    /**
+     * round-2 finding #5: retire a session's live libp2p node WITHOUT changing its
+     * DB status. Used after the active-session bilateral seal commitment has already
+     * advanced the row to 'seal_interrupted_pending': the session is frozen, so we
+     * stop the node and unregister its /cello/content handler (no more inbound leaves,
+     * no leaked node per active close) but must NOT overwrite the pending/sealed status
+     * the way destroySessionNode would. The durable tree stays in SQLite (getSessionTree
+     * reloads it); the in-memory plaintext buffer is evicted.
+     */
+    retireSessionNode(agentName: string, sessionId: string): Promise<void>;
+    /**
+     * Graceful shutdown: mark all active sessions as interrupted, stop all nodes.
+     * Called from the SIGTERM / cello logout path (AC-009).
+     * SQLite writes complete before this method returns.
+     */
+    gracefulShutdown(): Promise<void>;
+    /**
+     * Return all sessions with a given status from SQLite.
+     * Used by cello status to surface interrupted sessions.
+     */
+    getSessionsByStatus(status: "active" | "sealed" | "interrupted"): SessionRecord[];
+    /**
+     * M7-SESSION-004 (AC-005): persist the seal certificate's legibility object with the
+     * sealed record. Stored as a JSON string (hex-encoded pubkeys) so it round-trips a
+     * daemon restart and is returned intact on the cert-read surface. The caller normalises
+     * the raw wire legibility (Uint8Array pubkeys) into a JSON-safe shape before storing.
+     * Best-effort: a session row may not yet exist (the seal arrived before the row was
+     * persisted); in that case we no-op rather than throw — the cert still flows through the
+     * live return path. The legibility content is identical regardless of delivery timing.
+     */
+    recordSealCertificate(agentName: string, sessionId: string, sealedRootHex: string, legibilityJson: string): void;
+    /**
+     * M7 legibility-TBS-binding (responder verify): record the counterparty's FROST primary (group)
+     * pubkey from the FROST-signed SessionAssignment, so the responder can VERIFY the bilateral seal
+     * 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).
+     */
+    recordCounterpartyPrimary(agentName: string, sessionId: string, primaryPubkeyHex: string): void;
+    /**
+     * M7-SESSION-004 (AC-005/AC-006): read the persisted seal certificate for a session.
+     * Returns the sealed root and the parsed legibility object (JSON-safe, hex pubkeys), or
+     * null if the session is unknown or not yet sealed. This is the cert-read surface a
+     * reader (operator, agent, arbitrator) — possibly in a DIFFERENT process than the one
+     * that built the certificate — uses to determine receipt-not-assent, per-party frontiers,
+     * attestation modes, and whether the final message was answered.
+     */
+    getSealCertificate(agentName: string, sessionId: string): {
+        sealed_root: string;
+        legibility: unknown;
+    } | 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.
+     * Also tears down the in-memory session node if one exists for this sessionId.
+     *
+     * @param sessionId The hex session ID from the relay frame
+     * @param messageCount Number of message leaves at interruption
+     * @param source 'relay_frame' | 'stream_close'
+     */
+    markInterruptedWithDetails(agentName: string, sessionId: string, messageCount: number, source: "relay_frame" | "stream_close"): Promise<void>;
+    /**
+     * M7-SESSION-001 (H-1): persist a verified bilateral SEAL-INTERRUPTED
+     * commitment and transition the session to 'seal_interrupted_pending'.
+     *
+     * This is NOT a seal. It records that both parties produced and exchanged
+     * K_local-signed SEAL-INTERRUPTED leaves over the same {leafCount, merkleRoot}.
+     * The FROST threshold notarization is a separate, currently-unwired step (see
+     * daemon.ts handleSealInterruptedFlow H-1 note), which is precisely why the
+     * status is 'seal_interrupted_pending' and never 'sealed'.
+     *
+     * The status update is guarded so it only advances a session out of the
+     * 'interrupted' state — it will not overwrite a 'sealed' row.
+     *
+     * @returns true if the session row was advanced to seal_interrupted_pending.
+     */
+    persistSealInterruptedCommitment(opts: {
+        agentName: string;
+        sessionId: string;
+        role: "initiator" | "responder";
+        ownLeaf: unknown;
+        counterpartyLeaf: unknown;
+        merkleRoot: string;
+        nonce: string;
+    }): boolean;
+    /**
+     * M7-SESSION-001 (H-1): read back the persisted bilateral commitment artifacts
+     * for a session. Returns null when none exist.
+     */
+    getSealInterruptedArtifacts(agentName: string, sessionId: string): {
+        role: string;
+        ownLeaf: unknown;
+        counterpartyLeaf: unknown;
+        merkleRoot: string;
+        nonce: string;
+    } | null;
+    /**
+     * Return the session record for a specific sessionId, regardless of status.
+     * Used by cello_close_session to inspect session state.
+     */
+    getSessionRecord(agentName: string, sessionId: string): SessionRecord | null;
+    /**
+     * MSG-2 startup-flush: the persisted relay endpoint for a session, or null if none was
+     * recorded. Used by the crash-backstop flush, which runs at startup BEFORE the in-memory
+     * session entries exist, so it cannot use `entry.relayPeerId`.
+     */
+    getPersistedRelayEndpoint(agentName: string, sessionId: string): {
+        relayPeerId: string;
+        relayAddrs: string[];
+    } | null;
+    /**
+     * DOD-MSG-4 (auto-recover): the DISTINCT relay endpoints this agent has sessions on, so the daemon
+     * can pull the agent's parked mailbox from each on reconnect (the relay mailbox is keyed by recipient
+     * pubkey, so one pull per relay drains all of the agent's parked content there). Distinct by relay
+     * peer id.
+     */
+    getAgentRelayEndpoints(agentName: string): Array<{
+        relayPeerId: string;
+        relayAddrs: string[];
+    }>;
+    /**
+     * Return the daemon-owned Merkle tree for a session, loading it from SQLite
+     * on first access (so it survives a restart — AC-007). Never returns null;
+     * an unknown session yields an empty tree.
+     */
+    getSessionTree(agentName: string, sessionId: string): SessionTree;
+    /** Current daemon-owned tree root for a session, as hex. */
+    getSessionTreeRootHex(agentName: string, sessionId: string): string;
+    /**
+     * Append a leaf (by its 32-byte leaf-hash hex) to the daemon-owned tree,
+     * persist it, advance the root, and fire session.tree.appended.
+     *
+     * @returns the new leaf index and the recomputed root hex.
+     */
+    appendSessionLeaf(agentName: string, sessionId: string, kind: SessionTreeLeafKind, leafHashHex: string, correlationId?: string): {
+        leafIndex: number;
+        newRootHex: string;
+    };
+    /**
+     * SEAM 1b (dialer ⇄ session-node reconciliation): dial the counterparty THROUGH
+     * this session's OWN node, so the session node N_A holds the connection its content
+     * newStream actually rides. TRANSPORT-001's transport selector dialed on a separate
+     * (composition-root) node whose connection N_A could not use — the per-session node
+     * must be the dialer. Direct mode only here (the default content path, Part 4 D-a);
+     * relay-circuit + dcutr strategy via N_A is a later seam. Tries each addr in turn;
+     * succeeds on the first connection, returns a named failure if none connect.
+     */
+    connectToCounterparty(agentName: string, sessionId: string, addrs: string[]): Promise<{
+        ok: true;
+    } | {
+        ok: false;
+        reason: string;
+        error: string;
+    }>;
+    /**
+     * DAEMON-004: send content over the session node's direct P2P content stream.
+     * On a dead/missing stream this returns a NAMED, diagnosable failure — never a
+     * silent success and never a desync (closing the old silent fire-and-forget
+     * content catch in the retired in-process client send path).
+     *
+     * SCOPE / findings #3 + #4 — what this send path does and does NOT do today:
+     *   - #4: it delivers the content over the direct /cello/content/1.0.0 P2P
+     *     stream only. It does NOT also submit a K_local-SIGNED content_hash leaf to
+     *     the RELAY on /cello/relay/1.0.0 (EARS behavior #1). That relay hash-submit
+     *     is MSG-001's scope; AC-001's "relay log shows a hash_submit" evidence is
+     *     produced once MSG-001 lands.
+     *   - #3: because there is no relay yet, the sequence number cello_send returns
+     *     is the LOCAL leaf index, not a relay-assigned canonical global sequence.
+     *     Each daemon appends leaves in its own LOCAL observation order, so two
+     *     daemons' roots agree only under perfectly ping-ponged traffic. Canonical
+     *     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): Promise<{
+        ok: true;
+    } | {
+        ok: false;
+        reason: string;
+        error: string;
+    }>;
+    /**
+     * M7 DOD-SPINE-7: submit THIS party's SEAL ctrl leaf (0x02) to the relay witness.
+     * Structure: content_hash = SHA-256(0x02 || encodeSealPayload({session_id, final_root,
+     * close_timestamp, "PENDING"})), where final_root is the daemon's OWN tree root. Two
+     * distinct-sender SEAL leaves in the relay's log trigger the relay's #maybeProcessSeal
+     * → directory processSeal (rebuild + verify the signed chain) → FROST notarization →
+     * session_sealed. Requires an active relay client; the caller falls back to the
+     * directory-mediated path when this returns relay_unavailable.
+     */
+    submitSealLeaf(agentName: string, sessionId: string, correlationId?: string): Promise<{
+        ok: true;
+        sequenceNumber: number;
+        reportedRootHex: string;
+    } | {
+        ok: false;
+        reason: string;
+    }>;
+    /**
+     * CELLO-M7-UPGRADE-001 (DOD-UP-1): readiness of a session for B to RATIFY a unilateral seal
+     * (the returning absent party). This is the SAME verifiability bar as the UP-2 auto-ack gate:
+     *
+     *  - `known`: the session exists locally with its content (B has a transcript to ratify). After a
+     *    restart B reloads it from SQLite, and autoRecoverForAgent re-pulls any parked content first.
+     *  - `tampered`: the content cross-check flagged a content_hash mismatch (#contentDesynced) — B
+     *    must NEVER ratify content it could not integrity-verify (the KERNEL refusal, AC-003).
+     *
+     * The directory separately verifies B's ack signature is genuine; B separately verifies the
+     * unilateral cert signature (R1 is authentic). NOTE: a full "B's frontier covers R1's tail"
+     * 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;
+    };
+    /**
+     * 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.
+     *
+     * 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.
+     *
+     * @returns the appended leaf index (as sequenceNumber) on success.
+     */
+    ingestReceivedContent(agentName: string, sessionId: string, content: Uint8Array, contentHash: Uint8Array, correlationId?: string): {
+        ok: true;
+        leafIndex: number;
+        sequenceNumber: number;
+        held?: boolean;
+        appendedCount?: number;
+    } | {
+        ok: false;
+        reason: string;
+    };
+    /**
+     * DOD-MSG-4: record the relay-witnessed canonical sequence for a content hash. The relay is the
+     * ordering authority (Structure 2): it assigns each message a sequence from its hash and delivers
+     * B the (content_hash -> sequence) binding via leaf_deliver. The strict-in-order gate orders the
+     * transcript by THIS — never a sender-stamped field. Also advances the per-session high-water mark
+     * (the largest witnessed sequence) reserved for the future catch-up-before-live increment. Idempotent.
+     */
+    recordWitnessedSequence(agentName: string, sessionId: string, contentHashHex: string, sequenceNumber: number): void;
+    /**
+     * DOD-MSG-4: the relay's high-water canonical sequence for this session (largest witnessed leaf),
+     * or -1 if none. Exposed for the next sub-increment (catch-up-before-live — on reconnect B holds
+     * live arrivals until its tree reaches this, because it has more to recover than it has appended);
+     * NOT yet consumed by the gate. Also `recordWitnessedSequence` maintains it.
+     */
+    getHighWaterSeq(agentName: string, sessionId: string): number;
+    /** DAEMON-004: pop the oldest verified received content for cello_receive. */
+    takeReceivedContent(agentName: string, sessionId: string): ReceivedContentEntry | null;
+    /**
+     * DOD-MSG-4 (self-ordering content frame): verify the relay's signed ordering record carried IN the
+     * content frame and record the canonical sequence for the strict-in-order gate — so ordering does
+     * not depend on the separate leaf_deliver witness arriving first. Best-effort: any failure (malformed,
+     * hash mismatch, bad signature, wrong signer) is logged and ignored — the content still ingests and
+     * orders via the witness stream / arrival, so a bad record cannot block delivery.
+     *
+     * structure1_cbor = [1, content_hash(32), sender_pubkey(32), session_id(16), last_seen_seq, ts] —
+     *   the EXACT bytes the sender signed (needed to verify; Structure2 omits session_id/last_seen/ts).
+     * structure2_cbor = [seq, sender_pubkey, content_hash, sender_signature, scan_result, prev_root].
+     */
+    /**
+     * DOD-MSG-4 (2b): encode the pre-seal park envelope `[1, content, structure1_cbor|null,
+     * structure2_cbor|null]`. The daemon seals THIS (not the bare content) so a parked entry carries
+     * its own signed ordering record — recover then orders it the same way the direct frame does. The
+     * relay still only ever holds the sealed ciphertext (INV-3 preserved).
+     */
+    encodeParkEnvelope(content: Uint8Array, structure1Cbor?: Uint8Array, structure2Cbor?: Uint8Array): Uint8Array;
+    /**
+     * DOD-MSG-4 (2b): decode a park envelope produced by encodeParkEnvelope. Falls back to treating the
+     * whole plaintext as raw content (no ordering record) for entries sealed the old way (e.g. test
+     * fixtures that seal bare content) — so recover stays backward-compatible.
+     */
+    decodeParkEnvelope(plaintext: Uint8Array): {
+        content: Uint8Array;
+        structure1Cbor?: Uint8Array;
+        structure2Cbor?: Uint8Array;
+    };
+    /**
+     * DOD-MSG-4 (2b): public entry for the recover path to verify + record a parked entry's ordering
+     * 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): void;
+    /**
+     * 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
+     * stream close events. Both detection paths call markInterruptedWithDetails().
+     *
+     * The reader runs for the lifetime of the relay stream. If the stream closes
+     * without delivering a session_interrupted frame (AC-005 / 'stream_close' path),
+     * the session is still marked interrupted.
+     *
+     * @param sessionId The hex session ID
+     * @param stream The relay stream to monitor
+     * @param messageCount Number of message leaves at the time of registration
+     *   (used as the count at interruption — best effort since exact count at frame
+     *   receipt may differ, but this is the value available at stream setup time)
+     */
+    registerRelayStream(agentName: string, sessionId: string, stream: Stream, messageCount?: number): void;
+    /**
+     * DOD-LOOP-1: public hook for the composition root to create an agent's standing receiver when
+     * the agent comes online (cello_start_agent), and to tear it down when it goes offline.
+     */
+    ensureStandingReceiverForAgent(agentName: string): Promise<void>;
+    removeStandingReceiverForAgent(agentName: string): Promise<void>;
+}
+export {};
+//# sourceMappingURL=session-node-manager.d.ts.map

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

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