@cello-protocol/daemon 0.0.227 → 0.0.229

package/dist/session-queries.d.ts

@@ -0,0 +1,476 @@
+/**
+ * CELLO Daemon — READS AND WRITES AGAINST THE SESSION STORE
+ *
+ * Split out of `session-node-manager.ts` by 037-SESSIONCORE. Fifty methods that are SQL and nothing
+ * else: they need the database, the logger, and the agent-id lookup, and they hold no state of their
+ * own. Grouped by that shape rather than by subject, because "needs only the database" is the
+ * property that made them safe to move together.
+ *
+ * Moved verbatim, comments included.
+ *
+ * ⚠️ EVERY QUERY JOINS ON `agent_id`, NEVER `agent_name`. The name is a mutable display label and is
+ * reusable after retirement, so joining on it silently attaches one agent's rows to another's.
+ * `requireAgentId` is how a name becomes an id, and it THROWS rather than returning a default —
+ * a query that silently read no rows for an unknown agent would look like an empty inbox.
+ */
+import type { DaemonDatabase } from "./sqlcipher-db.js";
+import type { Logger, SessionRecord } from "./types.js";
+import { SessionTree, type WritableSessionTreeLeafKind } from "./session-tree.js";
+import { type QuarantinedRecord } from "./session-node-types.js";
+/** What these queries need from the manager. Four things, none of them session state. */
+export interface SessionQueryContext {
+    readonly logger: Logger;
+    /** A function: the manager opens its database after construction. Re-exposed below as `#db`. */
+    db(): DaemonDatabase | null;
+    requireAgentId(agentName: string): string;
+    sessionKey(agentName: string, sessionId: string): string;
+    /** The session id inside a composite key, when it belongs to this agent; null otherwise. */
+    unkey(key: string, agentName: string): string | null;
+}
+export declare class SessionQueries {
+    #private;
+    constructor(ctx: SessionQueryContext);
+    /**
+     * DOD-M12B-REVIVAL-BOUND-1 — interrupted sessions that can no longer be revived, and must close.
+     *
+     * Andre, 2026-08-18: *"after that, those peer IDs and that peer connection needs to be shut down.
+     * It is an open connection that a malicious agent can farm for."* The tenet is **leave nothing
+     * open that is no longer needed**, and the threat model is a daemon that has been reprogrammed —
+     * so the guarantee has to hold on the side that is not the attacker.
+     *
+     * WHAT IS OPEN. `ingestReceivedContent` refuses `sealed`, `seal_interrupted_pending` and
+     * `abandoned`, but deliberately ACCEPTS `interrupted` — that acceptance is the only reason
+     * recovery can work. Nothing else ever leaves `interrupted`, so it means accepts FOREVER.
+     *
+     * **THIS IS THE BACKSTOP, NOT THE COMPLEMENT.** The seal path gets first refusal on every
+     * local-cause session, because a session whose ending we can describe truthfully earns a
+     * notarized receipt. But "the seal path owns it" is not the same as "the seal path will finish
+     * it", and two populations fall through the gap between those:
+     *
+     *   - **The resolver gave up.** `markRestartSealGaveUp` writes only `restart_seal_gave_up_at`;
+     *     the status stays `interrupted`, and `listRestartOrphanedSessions` then excludes the row by
+     *     `restart_seal_gave_up_at IS NULL` so it is never retried. `TERMINAL_SEAL_REFUSALS` has ten
+     *     entries and the measured figure is that 59% of seals that start never finish, so this is
+     *     the common case, not a corner.
+     *   - **Zero-message local sessions.** The resolver requires `message_count > 0` — a dead
+     *     handshake is not worth a ceremony. It is still an open write surface.
+     *
+     * Excluding those left them permanently interrupted and permanently writable, which is the exact
+     * condition this line exists to end. And the population is about to become the majority: no row
+     * has ever carried `interrupted_by = 'local'` yet, and from the next shutdown onward every
+     * shutdown-orphaned session will. So the sweep takes a local-cause session once the seal path
+     * has either declined it or exhausted it — never before.
+     *
+     * **THE CLOCK MUST BE ONE THE COUNTERPARTY CANNOT MOVE.** The obvious fallback for a row with no
+     * `interrupted_at` is `updated_at` — and it is exactly wrong. `ingestReceivedContent` accepts
+     * content into an `interrupted` session (that acceptance is this whole line's premise), and a
+     * successful ingest runs `UPDATE sessions SET message_count = ?, updated_at = <now>`. So
+     * `updated_at` is a clock the reprogrammed peer holds: one message every 24 hours and the session
+     * never expires, forever. The fallback would have handed the attacker the off switch for the
+     * control built to stop them.
+     *
+     * Instead the missing timestamps are STAMPED ONCE, by `#stampMissingInterruptedAt` immediately
+     * before this query runs, and this query reads `interrupted_at` and nothing else. The stamp is
+     * written under `WHERE interrupted_at IS NULL`, so it is monotone — set once, never moved, by us
+     * and not by a peer. A legacy row therefore gets its full window starting from the first sweep
+     * that sees it, which is later than the true interruption but is the only bound that is sound.
+     *
+     * Same retired-agent INNER JOIN as the sibling query: a retired agent's rows are kept for
+     * accountability, are not resumable, and are not writable either.
+     *
+     * **THE TIME ARITHMETIC IS LOAD-BEARING, AND BOTH OBVIOUS FORMS OF IT ARE WRONG.** These two
+     * columns do not hold the same kind of value:
+     *
+     *   `interrupted_at`  TEXT,    an ISO-8601 string — `new Date(now).toISOString()`.
+     *   `updated_at`      INTEGER, epoch milliseconds.
+     *
+     * There are FOUR writers of `status = 'interrupted'`, not three. The fourth is
+     * `destroySessionNode` → `#updateSessionStatus(…, "interrupted", "local")`, which historically
+     * wrote `interrupted_by` and **no timestamp at all** — and it is the path that produced the two
+     * rows in Entry 41. It now stamps `interrupted_at` like the others, so NULL is a legacy state
+     * rather than one production keeps creating.
+     *
+     * So a bare `interrupted_at <= ?` against a numeric bound is **always false** — the column has
+     * TEXT affinity and the bound parameter has none, so SQLite applies TEXT affinity to the
+     * parameter and compares them as STRINGS (`'2026-08-18T05:32:04.183Z' <= 1755000000000` → 0).
+     * The query silently returns nothing forever and reads as "nothing has expired yet". And
+     * `CAST(interrupted_at AS
+     * INTEGER)` is worse than useless: SQLite casts by taking the leading digits, so
+     * `'2026-08-18T05:32:04Z'` becomes **2026**, which is older than any epoch bound. That form
+     * abandons every interrupted session on the next boot, immediately, whatever its age. It was
+     * written, and `session-001`/`cello-list-sessions` failed on it in the gate.
+     *
+     * `strftime('%s', …) * 1000` parses the ISO string properly and returns NULL for anything it
+     * cannot parse — so a malformed or differently-formatted value falls through the COALESCE to
+     * `updated_at` rather than being read as the year 2026.
+     */
+    listExpiredUnrevivableSessions(nowMs: number, windowMs: number): Array<{
+        agentName: string;
+        sessionId: string;
+        cause: string | null;
+    }>;
+    /**
+     * DOD-M12B-RESTART-SEAL-1 / DOD-M12B-PENDING-RESOLVE-1 — sessions that need a receipt and have
+     * nobody asking for one. TWO populations, one queue, each with its own safety argument.
+     *
+     * **(2) `seal_interrupted_pending` — a seal commitment nobody notarized.** Measured 2026-08-18 on
+     * the live store: 28 sessions, aged 0.3 to 12.8 days, one of them 14 messages long, 26 holding
+     * relay-witnessed seal leaves, and **not one with a sealed root**.
+     *
+     * **HALF OF THEM ARE NOT BILATERAL, and the first version of this comment claimed they were.**
+     * Measured split: 14 initiator rows, each carrying the counterparty's signed leaf — and 14
+     * responder rows with `counterparty_leaf = NULL`. A responder row is written by
+     * `inbound-seal-request.ts` from an UNSIGNED `seal_interrupted_request` frame, before its ack is
+     * even sent, so an ordinary send failure produces a one-sided pending row.
+     *
+     * So the licence is NOT "both parties signed". It is **somebody chose to end this**, on two
+     * branches: an initiator row carries the counterparty's signature, and a responder row exists
+     * because the counterparty sent a request to seal. And what makes the result VERIFIABLE is
+     * neither — it is that the directory rebuilds the tree from relay-witnessed leaves and checks
+     * their signatures, never consulting the commitment at all. The commitment is what makes it
+     * legitimate to ASK. (`close-session-handler.ts` states this in full; the first draft of this
+     * header contradicted it 200 lines away.) `PENDING-EXIT-1` built their exit and it works — but only when an operator runs
+     * `cello_close_session` on that session by hand, having somehow deduced they should. Nothing
+     * enumerated them, because both sweeps filtered `status = 'interrupted'`. An exit nobody is told
+     * about is not an exit.
+     *
+     * `interrupted_by` is deliberately NOT consulted for that population. It answers "did WE cause
+     * this, and may we therefore describe it" — and that is the wrong question once a seal was
+     * requested or signed. **SI-001 is not weakened:** it forbids notarizing *"a conversation nobody
+     * chose to end"*, and every row here was chosen to be ended by one side or the other. The only
+     * thing missing is the request to notarize it.
+     *
+     * **(1) `interrupted` — sessions our own stop orphaned, and only those.** Here `interrupted_by` is
+     * the whole safety argument. `'local'` means the boot sweep, the shutdown
+     * sweep, or the operator's own kill switch ended this session — nobody else did, and it cannot be
+     * resumed because the transport keypairs died with the process. Those are the ones the resolver
+     * may seal on its own.
+     *
+     * Everything else is excluded and must stay excluded:
+     *   'counterparty'        — they hung up. SI-001: the operator may still want to wait.
+     *   'relay_stream_close'  — our relay witness link ended; the session itself may be fine.
+     *   NULL                  — written before the column existed, so the cause is UNKNOWN. An
+     *                           unknown cause is not a licence to notarize; it is the reason not to.
+     *
+     * Same INNER JOIN discipline as getSessionsByStatus: a retired agent's rows are kept for
+     * accountability and are not resumable, so they are not offered for sealing either.
+     */
+    listRestartOrphanedSessions(): Array<{
+        agentName: string;
+        sessionId: string;
+        messageCount: number;
+        status: "interrupted" | "seal_interrupted_pending";
+    }>;
+    /**
+     * DOD-M12B-STRAND-1 — write one held frame to the durable store.
+     *
+     * LOGS LOUD, does not refuse. The caller answers `held: true` either way, and that is correct:
+     * held content is never `persisted`-acked, so the sender keeps its copy and retries whether or
+     * not this row lands. What a failure costs is the restart case — the frame is memory-only again,
+     * exactly as it was before this unit — so it is reported at ERROR here and counted again by the
+     * teardown alarm, and never allowed to look like a success.
+     */
+    persistHeldContent(agentName: string, sessionId: string, canonicalSeq: number, deliverContent: Uint8Array, originalContent: Uint8Array, contentHashHex: string, screenedOut: boolean, correlationId?: string, origin?: "received" | "sent", leafKind?: WritableSessionTreeLeafKind): void;
+    /**
+     * DOD-M15-REFUSEDEVIDENCE-1: read retained refused messages back — all of a session's, or the one
+     * at `sequence`.
+     *
+     * Returns the RAW payload. Every caller that hands it to a reader must frame it first
+     * (`frameQuarantinedPayload`); nothing else in the tree may read this without doing so.
+     */
+    readQuarantined(agentName: string, sessionId: string, sequence?: number): QuarantinedRecord[];
+    /**
+     * DOD-M12B-REVIVAL-BOUND-1 — give every timestamp-less interrupted session a clock, once.
+     *
+     * A row with `interrupted_at IS NULL` has no bound that can be evaluated, and skipping such rows
+     * would exempt the oldest sessions in the store from the control permanently — the same "open
+     * forever" failure wearing a different NULL. The two rows measured in Entry 41 are exactly this
+     * shape, written by a `destroySessionNode` path that set the cause and no timestamp.
+     *
+     * **`WHERE interrupted_at IS NULL` is the security property, not an optimisation.** It makes the
+     * stamp write-once: this can run on every sweep forever and a row's clock still cannot be moved
+     * after the first one. That is what disqualifies `updated_at`, which a peer moves with every
+     * message it sends into the still-accepting session.
+     *
+     * The cost is honest and bounded: a legacy row's window starts at the first sweep that sees it
+     * rather than at its true interruption, so it survives up to one window longer than it should.
+     * A late close is recoverable; a clock the counterparty winds is not.
+     *
+     * @returns how many rows were stamped.
+     */
+    stampMissingInterruptedAt(nowMs: number): number;
+    /**
+     * 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).
+     */
+    /**
+     * 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;
+    /**
+     * M7-SESSION-001 (H-1): read back the persisted bilateral commitment artifacts
+     * for a session. Returns null when none exist.
+     */
+    /**
+     * M12-P17: durably record verified content that arrived for an ALREADY-ENDED session.
+     *
+     * Returns true only when the row is committed — the caller confirm-deletes the relay copy on the
+     * strength of this answer, and the ORDER is load-bearing: annex first, delete second. A crash
+     * between them must lose nothing, so a failure here MUST report false and leave the relay copy
+     * alone. Getting that backwards converts a noisy re-pull loop into permanent silent loss, which is
+     * the outcome this whole unit exists to prevent.
+     */
+    recordSealedAnnex(agentName: string, sessionId: string, contentHashHex: string, content: Uint8Array, senderPubkeyHex: string | null): boolean;
+    /**
+     * DOD-COATTEND-1 (review F5) — the single next RECEIVED message after `afterSeq`, or null.
+     *
+     * The delivery path asks this question inside a 20 ms poll, so it is asked ~47 times a second per
+     * blocked connection — ~1,400 times over a default 30 s receive. Answering it with
+     * `readTranscript()` meant, every single time: SELECT every row of the session with no predicate
+     * and no limit, `TextDecoder().decode()` every blob in it, build the array, then `.find()` one
+     * row and discard the rest. On a 200-message session with three co-attending connections blocking
+     * — which is the M8D use case, not a worst case — that is tens of thousands of blob decodes per
+     * second on the daemon's single synchronous SQLCipher handle, contending with the write path.
+     *
+     * The predicate belongs in SQL. This is O(1) on the existing (agent_id, session_id, sequence)
+     * key and decodes exactly the one blob it returns.
+     */
+    findNextReceivedAfter(agentName: string, sessionId: string, afterSeq: number): {
+        sequence: number;
+        text: string;
+    } | null;
+    getSealInterruptedArtifacts(agentName: string, sessionId: string): {
+        role: string;
+        ownLeaf: unknown;
+        counterpartyLeaf: unknown;
+        merkleRoot: string;
+        nonce: string;
+    } | null;
+    /**
+     * Return all sessions with a given status from SQLite.
+     * Used by cello status to surface interrupted sessions.
+     */
+    getSessionsByStatus(status: "active" | "sealed" | "interrupted"): SessionRecord[];
+    loadTreeFromDb(agentName: string, sessionId: string): SessionTree;
+    /**
+     * M12-P18: record that this agent refused a session, so parked content that later arrives for it
+     * (and fails `counterparty_unknown`, because no session row exists) can be swept instead of
+     * re-pulled forever. Keeps the most recent REFUSED_SESSIONS_CAP per agent.
+     */
+    recordRefusedSession(agentName: string, sessionId: string, reason: string): void;
+    /**
+     * 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[];
+    }>;
+    /** M8C-ABUSE-1 (anti-swarm) + DOD-TIER-2: non-terminal sessions this agent holds with UNKNOWN-tier
+     *  counterparties — the global cap counts across the whole stranger pool. A sender is exempt from
+     *  THIS pool iff it is a KNOWN+ contact (tier >= KNOWN); a bare stranger (no row → UNKNOWN) or an
+     *  explicitly UNKNOWN-tier contact both count. Keying on `tier >= KNOWN` (bounded to <= VIP so a
+     *  corrupt high value cannot grant pool-exemption) replaces the old row-existence proxy, which
+     *  would have let a merely-recorded UNKNOWN contact escape the anti-swarm cap. Same
+     *  'interrupted'-status fix as countActiveSessionsForCounterparty above. */
+    countActiveSessionsFromUnknownSenders(agentName: string): number;
+    /**
+     * 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 per-party frontiers,
+     * attestation modes, and whether the final message was answered.
+     */
+    getSealCertificate(agentName: string, sessionId: string): {
+        sealed_root: string;
+        legibility: unknown;
+    } | null;
+    /**
+     * M8C-ABUSE-1: cumulative inbound byte total for a session (anti-drip-feed accounting).
+     *
+     * ⚠️ DOD-M15-REFUSEDEVIDENCE-1 — QUARANTINED BYTES COUNT, and the bound depends on it.
+     *
+     * Retaining refused messages puts real bytes on the operator's disk. Left out of this sum,
+     * retention would be an UNBOUNDED SIDE CHANNEL: a counterparty who can get messages refused —
+     * anyone who can trip the screener, which is anyone — stores against a budget that cannot see
+     * what they spent. Counting them makes total retention per session bounded by the same tier cap
+     * that bounds delivery, which is the bound the unit's no-truncation rule rests on.
+     *
+     * No new capability reaches an attacker from this: the counterparty already spends the session's
+     * byte budget by sending ordinary messages. Spending it with refused ones costs them the same.
+     */
+    getReceivedBytesTotal(agentName: string, sessionId: string): number;
+    ownPubkeyHex(agentName: string): string | null;
+    /**
+     * DOD-SESSION-NAME-1: set (string) or clear (null) THIS agent's name for a session.
+     *
+     * Returns false when the (agent_id, session_id) row does not exist — i.e. the session is not this
+     * agent's — so the caller refuses with session_not_found rather than reporting a silent success on
+     * a write that landed nowhere. Same contract as setContactMoniker.
+     *
+     * Ownership is the ONLY scope: the composite key IS the ownership check, and status is deliberately
+     * not consulted. A sealed session can be named — naming one long after the fact is the point — and
+     * a name is a local column, so writing it cannot touch the seal, a Merkle leaf, or the wire.
+     *
+     * The caller validates (validateSessionName) before calling; this stores what it is given.
+     */
+    setSessionName(agentName: string, sessionId: string, sessionName: string | null): boolean;
+    /** DOD-M12B-ABANDON-NOTIFY-1 — durable "they hung up" marker. Not a status: the session stays
+     *  sealable, which is the whole point of not making this terminal. */
+    markCounterpartyAbandoned(agentName: string, sessionId: string): boolean;
+    /**
+     * 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;
+    /** Best-effort: a failure to record WHY must never be the thing that breaks a seal. */
+    noteCertifiedLeafState(agentName: string, sessionId: string, state: string, detail: string | null): void;
+    /**
+     * DOD-M12B-RESTART-SEAL-1 — record that automatic sealing has exhausted this session.
+     *
+     * Durable on purpose. The resolver's attempt budget is in memory, so without this the budget
+     * resets on every boot and a session that can never seal costs five directory ceremonies a day
+     * for the life of the machine.
+     *
+     * IT IS NOT A DEAD END FOR THE OPERATOR. The row keeps status `interrupted`, so a manual
+     * `cello_close_session` still works on it and — since DOD-M12B-INTERRUPTED-ESCALATE-1 — still
+     * escalates to a unilateral seal. This column only withdraws the session from AUTOMATIC retries.
+     */
+    markRestartSealGaveUp(agentName: string, sessionId: string, reason: string): void;
+    /** DOD-SEALED-INBOX-1: mark a terminal session as dismissed — sets read_at to now.
+     *  Only valid for terminal sessions; active/interrupted sessions return session_not_terminal. */
+    dismissSession(agentName: string, sessionId: string): {
+        ok: true;
+    } | {
+        ok: false;
+        reason: string;
+    };
+    /**
+     * Reverse lookup: the display name of a stable agent_id, or null if no such agent.
+     *
+     * Deliberately INCLUDES retired agents. Its caller (the startup awaiting-content re-park) holds an
+     * agent_id read off a durable row and needs a name to find that agent's standing receiver. A
+     * retired agent resolves to its name and then has no standing receiver, so the park fails cleanly
+     * and loudly — which is correct. Filtering retired agents out here would instead make the row
+     * unattributable and the failure mute.
+     */
+    agentNameForId(agentId: string): string | null;
+    /** DOD-M12B-SEAL-STUCK-1 — how long the oldest held frame for this session has been waiting, or
+     *  null when nothing is held. This is what separates "stuck since this morning" from "in flight
+     *  40 ms ago", and without it a healthy mid-conversation window reads as a stranded session. */
+    oldestHeldMs(agentName: string, sessionId: string): number | null;
+    /** DOD-M12B-STRAND-1 — drop one held frame from the durable store, on release or on a refusal
+     *  that supersedes it. A row that outlives its release re-appends on the next boot. */
+    deleteHeldContent(agentName: string, sessionId: string, canonicalSeq: number): void;
+    /** DOD-RENAME-1: pending rename notices for an agent, oldest first (surfaced in
+     *  cello_check_notifications — an INBOX pull, never a real-time push). */
+    getRenameNotices(agentName: string): Array<{
+        pubkey: string;
+        offered_name: string;
+        noticed_at: number;
+        moniker: string | null;
+    }>;
+    /**
+     * The certified leaf set, in order, or null when none was stored for this session.
+     *
+     * Null is a REFUSAL upstream, never a fallback to the local tree: the two cover different leaves
+     * and substituting one for the other is how a proof comes to land on a root nobody signed.
+     */
+    getCertifiedLeafSet(agentName: string, sessionId: string): string[] | null;
+    /** DOD-CAP-SELF-HEAL-1: the sessions with this counterparty that are consuming cap slots, oldest
+     *  first. The operator is told to close some — this is WHICH, because "close three of them" with
+     *  no list is not an instruction they can follow. */
+    sessionsConsumingCap(agentName: string, counterpartyPubkey: string, limit?: number): string[];
+    /** Advance the read watermark (delivery marks read). MONOTONIC — never lowers, so a replayed or
+     *  out-of-order cello_receive cannot un-read already-read messages. */
+    advanceLastDeliveredSeq(agentName: string, sessionId: string, seq: number): void;
+    /** M8C-ABUSE-1: non-terminal sessions this agent currently holds with the given counterparty.
+     *  Reviewer HIGH fix (aeffb82f, D18): counting `status = 'active'` ONLY let a counterparty
+     *  evade the bound for free by disconnecting (a trivial, attacker-controlled action that flips
+     *  a session to 'interrupted' — markInterruptedWithDetails) and opening a fresh session,
+     *  repeated indefinitely. 'interrupted' sessions still accept content (ingestReceivedContent
+     *  explicitly allows both statuses) and are NOT terminal (sealed/seal_interrupted_pending are),
+     *  so they must still count against the bound. */
+    countActiveSessionsForCounterparty(agentName: string, counterpartyPubkey: string): number;
+    /**
+     * The last thing that happened to this session's certified leaf set, or null if nothing has.
+     *
+     * Null here and a null from `getCertifiedLeafSet` together mean "no seal has been processed on
+     * this side yet" — which is a different sentence again from any of the recorded states.
+     */
+    getCertifiedLeafSetState(agentName: string, sessionId: string): {
+        state: string;
+        detail: string | null;
+    } | 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;
+    evictOldestReads(agentId: string, sessionId: string, reason: string): void;
+    /**
+     * DOD-M15-RELAYONLY-1: is the settings store readable RIGHT NOW?
+     *
+     * ⚠️ Exists because `getSetting` cannot answer it. That method returns `null` for BOTH "the key is
+     * unset" and "there is no database", and a security setting must tell those apart: unset-means-off
+     * is correct, db-gone-means-off publishes the operator's real address during the shutdown window.
+     * `getDb()` cannot stand in either — it THROWS when there is no database, which on a catch-less
+     * ceremony path is worse than the wrong answer.
+     */
+    hasDatabase(): boolean;
+    /** M12-P17: read the annex. Operator-initiated ONLY — never wired to a wake path or inbox count. */
+    readSealedAnnex(agentName: string, sessionId?: string): Array<{
+        session_id: string;
+        content_hash: string;
+        sender_pubkey: string | null;
+        text: string;
+        arrived_at: number;
+    }>;
+    /** DOD-M12B-ABANDON-NOTIFY-1: has the counterparty told us they hung up? */
+    counterpartyAbandonedAt(agentName: string, sessionId: string): number | null;
+    /**
+     * F1-b: the durable sealed root hex for a session (written by recordSealCertificate on the
+     * bilateral path), or null if not recorded. Lets cello_receive echo the sealed root in its
+     * terminal answer without threading it through destroySessionNode.
+     */
+    getSealedRootHex(agentName: string, sessionId: string): string | null;
+    /** The highest RECEIVED transcript sequence delivered to the operator for (agent, session).
+     *  -1 when nothing has been delivered yet (so a seq-0 message reads as unread). */
+    getLastDeliveredSeq(agentName: string, sessionId: string): number;
+    /** DOD-CAP-SELF-HEAL-1 test seam: the shutdown sweep's effect, without a shutdown. Mirrors the
+     *  real UPDATE at gracefulShutdown so a test cannot pass against a label production never sets. */
+    markSessionsInterruptedByLocalShutdownForTest(): void;
+    /** M12-P18: did this agent refuse this session? Consulted at drain to sweep orphaned parked content. */
+    wasSessionRefused(agentName: string, sessionId: string): boolean;
+    countReceivedMessages(agentName: string, sessionId: string): number;
+    /** DOD-CAP-SELF-HEAL-1 test seam: the counterparty's stream closing, without a real peer. */
+    markInterruptedByCounterpartyForTest(agentName: string, sessionId: string): void;
+    recordSealCertificate(agentName: string, sessionId: string, sealedRootHex: string, legibilityJson: string): void;
+    recordCounterpartyPrimary(agentName: string, sessionId: string, primaryPubkeyHex: string): void;
+}
+//# sourceMappingURL=session-queries.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"session-queries.d.ts","sourceRoot":"","sources":["../src/session-queries.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AACH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AACxD,OAAO,KAAK,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAExD,OAAO,EAAE,WAAW,EAA6B,KAAK,2BAA2B,EAAE,MAAM,mBAAmB,CAAC;AAE7G,OAAO,EACL,KAAK,iBAAiB,EAMvB,MAAM,yBAAyB,CAAC;AAEjC,yFAAyF;AACzF,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,gGAAgG;IAChG,EAAE,IAAI,cAAc,GAAG,IAAI,CAAC;IAC5B,cAAc,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAAC;IAC1C,UAAU,CAAC,SAAS,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM,CAAC;IACzD,4FAA4F;IAC5F,KAAK,CAAC,GAAG,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAAC;CACtD;AAED,qBAAa,cAAc;;gBAGb,GAAG,EAAE,mBAAmB;IASpC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAyEG;IACH,8BAA8B,CAC5B,KAAK,EAAE,MAAM,EACb,QAAQ,EAAE,MAAM,GACf,KAAK,CAAC;QAAE,SAAS,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAA;KAAE,CAAC;IA0BxE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA6CG;IACH,2BAA2B,IAAI,KAAK,CAAC;QAAE,SAAS,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,CAAC;QAAC,YAAY,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,aAAa,GAAG,0BAA0B,CAAA;KAAE,CAAC;IA6CxJ;;;;;;;;OAQG;IACH,kBAAkB,CAChB,SAAS,EAAE,MAAM,EACjB,SAAS,EAAE,MAAM,EACjB,YAAY,EAAE,MAAM,EACpB,cAAc,EAAE,UAAU,EAC1B,eAAe,EAAE,UAAU,EAC3B,cAAc,EAAE,MAAM,EACtB,WAAW,EAAE,OAAO,EACpB,aAAa,CAAC,EAAE,MAAM,EACtB,MAAM,GAAE,UAAU,GAAG,MAAmB,EACxC,QAAQ,GAAE,2BAAmC,GAC5C,IAAI;IAiCP;;;;;;OAMG;IACH,eAAe,CAAC,SAAS,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,MAAM,GAAG,iBAAiB,EAAE;IAkC7F;;;;;;;;;;;;;;;;;;OAkBG;IACH,yBAAyB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM;IAsBhD;;;;;OAKG;IACH;;;;;;;;;;;;;;;;;;OAkBG;IACH,4BAA4B,CAAC,SAAS,EAAE,MAAM,EAAE,qBAAqB,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI;IAa7F;;;OAGG;IACH;;;;;;;;OAQG;IACH,iBAAiB,CAAC,SAAS,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,cAAc,EAAE,MAAM,EAAE,OAAO,EAAE,UAAU,EAAE,eAAe,EAAE,MAAM,GAAG,IAAI,GAAG,OAAO;IAoB7I;;;;;;;;;;;;;OAaG;IACH,qBAAqB,CACnB,SAAS,EAAE,MAAM,EACjB,SAAS,EAAE,MAAM,EACjB,QAAQ,EAAE,MAAM,GACf;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI;IAa5C,2BAA2B,CAAC,SAAS,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG;QACjE,IAAI,EAAE,MAAM,CAAC;QACb,OAAO,EAAE,OAAO,CAAC;QACjB,gBAAgB,EAAE,OAAO,CAAC;QAC1B,UAAU,EAAE,MAAM,CAAC;QACnB,KAAK,EAAE,MAAM,CAAC;KACf,GAAG,IAAI;IAsBR;;;OAGG;IACH,mBAAmB,CAAC,MAAM,EAAE,QAAQ,GAAG,QAAQ,GAAG,aAAa,GAAG,aAAa,EAAE;IAsBjF,cAAc,CAAC,SAAS,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,WAAW;IAyBjE;;;;OAIG;IACH,oBAAoB,CAAC,SAAS,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,IAAI;IAmBhF;;;;;OAKG;IACH,sBAAsB,CAAC,SAAS,EAAE,MAAM,GAAG,KAAK,CAAC;QAAE,WAAW,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,MAAM,EAAE,CAAA;KAAE,CAAC;IAmB/F;;;;;;gFAM4E;IAC5E,qCAAqC,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM;IAgBhE;;;;;;;OAOG;IACH,kBAAkB,CAAC,SAAS,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG;QAAE,WAAW,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,OAAO,CAAA;KAAE,GAAG,IAAI;IAc7G;;;;;;;;;;;;;OAaG;IACH,qBAAqB,CAAC,SAAS,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM;IAOnE,YAAY,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI;IAqB9C;;;;;;;;;;;;OAYG;IACH,cAAc,CAAC,SAAS,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,IAAI,GAAG,OAAO;IAOzF;0EACsE;IACtE,yBAAyB,CAAC,SAAS,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO;IAkBxE;;;;OAIG;IACH,yBAAyB,CAAC,SAAS,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG;QAAE,WAAW,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,MAAM,EAAE,CAAA;KAAE,GAAG,IAAI;IAcrH,uFAAuF;IACvF,sBAAsB,CAAC,SAAS,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,IAAI,GAAG,IAAI;IAiBxG;;;;;;;;;;OAUG;IACH,qBAAqB,CAAC,SAAS,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,IAAI;IAMjF;qGACiG;IACjG,cAAc,CAAC,SAAS,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG;QAAE,EAAE,EAAE,IAAI,CAAA;KAAE,GAAG;QAAE,EAAE,EAAE,KAAK,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE;IAclG;;;;;;;;OAQG;IACH,cAAc,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI;IAO9C;;oGAEgG;IAChG,YAAY,CAAC,SAAS,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI;IAajE;2FACuF;IACvF,iBAAiB,CAAC,SAAS,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,GAAG,IAAI;IAcnF;8EAC0E;IAC1E,gBAAgB,CAAC,SAAS,EAAE,MAAM,GAAG,KAAK,CAAC;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,YAAY,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAA;KAAE,CAAC;IAahI;;;;;OAKG;IACH,mBAAmB,CAAC,SAAS,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,IAAI;IAS1E;;yDAEqD;IACrD,oBAAoB,CAAC,SAAS,EAAE,MAAM,EAAE,kBAAkB,EAAE,MAAM,EAAE,KAAK,SAAK,GAAG,MAAM,EAAE;IAYzF;2EACuE;IACvE,uBAAuB,CAAC,SAAS,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,IAAI;IAYhF;;;;;;sDAMkD;IAClD,kCAAkC,CAAC,SAAS,EAAE,MAAM,EAAE,kBAAkB,EAAE,MAAM,GAAG,MAAM;IAOzF;;;;;OAKG;IACH,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;IAO/G;;;OAGG;IACH,gBAAgB,CAAC,SAAS,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,aAAa,GAAG,IAAI;IAS5E,gBAAgB,CAAC,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,IAAI;IAa1E;;;;;;;;OAQG;IACH,WAAW,IAAI,OAAO;IAGtB,oGAAoG;IACpG,eAAe,CAAC,SAAS,EAAE,MAAM,EAAE,SAAS,CAAC,EAAE,MAAM,GAAG,KAAK,CAAC;QAAE,UAAU,EAAE,MAAM,CAAC;QAAC,YAAY,EAAE,MAAM,CAAC;QAAC,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,MAAM,CAAA;KAAE,CAAC;IAW3K,4EAA4E;IAC5E,uBAAuB,CAAC,SAAS,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI;IAW5E;;;;OAIG;IACH,gBAAgB,CAAC,SAAS,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI;IAOrE;uFACmF;IACnF,mBAAmB,CAAC,SAAS,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM;IAOjE;uGACmG;IACnG,6CAA6C,IAAI,IAAI;IAMrD,wGAAwG;IACxG,iBAAiB,CAAC,SAAS,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO;IAOhE,qBAAqB,CAAC,SAAS,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM;IAOnE,6FAA6F;IAC7F,oCAAoC,CAAC,SAAS,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,IAAI;IAKhF,qBAAqB,CAAC,SAAS,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,EAAE,cAAc,EAAE,MAAM,GAAG,IAAI;IAMhH,yBAAyB,CAAC,SAAS,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,gBAAgB,EAAE,MAAM,GAAG,IAAI;CAMhG"}