@cello-protocol/daemon 0.0.225 → 0.0.227

package/dist/session-relay-client.d.ts

@@ -1,659 +0,0 @@
-import { type SessionAttendance, type SessionLiveness } from "@cello-protocol/protocol-types";
-import type { Stream } from "@libp2p/interface";
-import type { CelloNode } from "@cello-protocol/transport";
-import { type KeyProvider } from "@cello-protocol/crypto";
-import type { Logger } from "./types.js";
-import { type RelayReceiptStore } from "./relay-receipt-store.js";
-import type { SessionSealLeafStore } from "./session-seal-leaf-store.js";
-import type { SessionOwnChainStore } from "./session-own-chain-store.js";
-export interface LivenessAnswer {
-    liveness: SessionLiveness;
-    /** Unix ms of the relay's most recent observation. 0 when it has none. */
-    observedAt: number;
-    /** The far daemon's own assertion. Absent unless `liveness` is 'alive'. */
-    attendance?: SessionAttendance;
-    /**
-     * When the far daemon made that assertion — NOT `observedAt`, which is when the relay last saw
-     * its connection change. The two are routinely hours apart: the relay sees you connect at 09:00
-     * and you step away at 11:30, and labelling the attendance with 09:00 reports a state as of a
-     * time before it was true. Absent whenever `attendance` is.
-     */
-    attendanceObservedAt?: number;
-    /** True when the relay refused to answer rather than answering "I don't know". */
-    refused?: true;
-}
-export declare const RELAY_PROTOCOL_ID = "/cello/relay/1.0.0";
-/**
- * How long to wait before re-proving after a transport-class failure.
- *
- * Sized against the measured event, not guessed: libp2p logged
- * `connection-manager closing 1 connections / stopped / started` inside 3ms, and the redial that
- * followed completed ~1s later. A second is comfortably past the restart while still being
- * invisible next to the ~5 minutes the previous behaviour cost (quarantine the relay, wait for the
- * next reachability sweep).
- */
-export declare const PROOF_RETRY_DELAY_MS = 1000;
-export declare const RELAY_AUTH_DOMAIN = "CELLO-RELAY-AUTH-v1";
-/**
- * DOD-WITNESS-STALL-1 — relay refusals that can NEVER resolve.
- *
- * `sendContent` treats a failed leaf-hash submit as a transient degradation: the content is real,
- * the peer still gets it, and the canonical sequence is recovered later. That is correct for a relay
- * that is briefly unreachable.
- *
- * It is WRONG for these two. They mean the relay has ended the session — there is no later, and
- * nothing sent from here can ever enter the record. Collapsing them into the transient case is what
- * let a conversation run for 68 minutes and 8 messages, every send reporting `delivered: true`,
- * against a chain that had stopped growing.
- *
- * ENUMERATED, never pattern-matched. A substring rule like `reason.includes("sealed")` would absorb
- * a future reason nobody has considered — which is the same collapse in a new coat.
- */
-export declare const TERMINAL_RELAY_REFUSALS: ReadonlySet<string>;
-/** True when the relay has ended this session and no later submit can succeed. */
-export declare function isTerminalRelayRefusal(reason: string | undefined): boolean;
-/**
- * DOD-M15-RELAYSLOTS-1 — why a relay refused to let this agent hold a reservation slot, in the
- * shape the daemon and the operator both need.
- *
- * `reason` is the relay's own code, unmodified. `advice` is what the person reading it should DO,
- * chosen for that specific cause. `tryAnotherRelay` is the machine half of the same question.
- */
-export interface RelayAuthRefusal {
-    reason: string;
-    advice: string;
-    tryAnotherRelay: boolean;
-    /** Present when the relay said how many slots are held and what its cap is. */
-    slotsHeld?: number;
-    slotCap?: number;
-    /** Present when the relay said when to come back. */
-    retryAfterMs?: number;
-}
-export declare function isLocalCredentialRefusal(reason: string): boolean;
-/**
- * Classify a relay's auth refusal: what to tell the operator, and whether another relay would help.
- *
- * Everything not in `RELAY_SIDE_REFUSALS` defaults to "do not try another", and that default is the
- * safe direction. A token problem reproduces identically on every relay in the fleet, so retrying
- * around the fleet spends real time turning a client fault into an apparent outage — and a slot cap
- * IS satisfiable elsewhere, but spreading to another relay papers over sessions that leaked and
- * brings the same wall back on the next one.
- */
-export declare function classifyRelayAuthRefusal(reason: string, extra?: {
-    slotsHeld?: number;
-    slotCap?: number;
-    retryAfterMs?: number;
-}): RelayAuthRefusal;
-/** Structure 1 leaf kind — these values match the relay's. Message leaf (the `cello_send` default). */
-export declare const LEAF_KIND_MSG = 0;
-/** Control leaf (SEAL etc.) — two distinct-sender ctrl leaves trigger directory notarization. */
-export declare const LEAF_KIND_CTRL = 2;
-/** Document-operation leaf (DOD-DOC-LEAF-1): a CRDT update riding the session tree. */
-export declare const LEAF_KIND_DOC = 4;
-/** Rejection leaf (DOD-DOC-LEAF-1): references the rejected update envelope's hash. */
-export declare const LEAF_KIND_REJECT = 5;
-/**
- * The Ed25519-signed payload that proves K_local ownership to the relay:
- * SHA-256("CELLO-RELAY-AUTH-v1" || nonce || pubkey). The relay verifies the
- * signature against exactly this hash (relay-node #handleRelayStream).
- */
-export declare function buildRelayAuthPayload(nonce: Uint8Array, pubkey: Uint8Array): Uint8Array;
-export interface LeafDeliverFrame {
-    sequence_number: number;
-    leaf_kind: number;
-    structure1_cbor: Uint8Array;
-    structure2_cbor: Uint8Array;
-    /**
-     * True when the relay echoed back OUR OWN submitted leaf (sender_pubkey ===
-     * our K_local), false when it is a genuine COUNTERPARTY leaf. The auto-acknowledge gate uses
-     * this to never auto-co-sign in response to its own SEAL ctrl leaf (which would loop). An
-     * explicit field — the consumer must not have to re-decode structure1_cbor to learn it.
-     */
-    authored_by_us: boolean;
-}
-/** Result of a single relay hash submission. */
-export type SubmitResult = {
-    ok: true;
-    sequence_number: number;
-    structure1_cbor?: Uint8Array;
-    structure2_cbor?: Uint8Array;
-    /**
-     * DOD-M15-SEALWIRE-1 bullet 5, SENT half — OUR signature over `structure1_cbor`.
-     *
-     * It is already computed on the submit path (`keyProvider.sign(structure1)`) and put on the
-     * wire as `sender_signature`; it simply was not handed back, so the transcript row for a
-     * message THIS agent sent stored no proof of authorship at all.
-     *
-     * Why that matters and is not symmetry for its own sake: a RECEIVED row carries the
-     * counterparty's pubkey and signature, so a third party can check it. A SENT row carried
-     * `attribution: "self_authored"` and nothing else — fine for its owner, who already knows, and
-     * **worth nothing to the auditor the bullet exists for.** Half a transcript was provable.
-     *
-     * Undefined on the relay-degraded path, where no submit happens and there is nothing to sign.
-     */
-    sender_signature?: Uint8Array;
-} | {
-    ok: false;
-    reason: string;
-    /**
-     * The relay's own words about what went wrong — `relay-types.ts`'s stated invariant is
-     * *"`reason` is the class, `detail` is what happened."*
-     *
-     * ⚠️ THAT INVARIANT HAD NEVER BEEN TRUE END TO END. The relay composed a `detail` on every
-     * `hash_submit_error`, and this client read `reason` and **dropped it on the floor** — so the
-     * only sentence naming a cause never reached an operator. It defeats two things at once:
-     * `DOD-M15-SEALWIRE-1`'s refusal detail (which rule, which leaf kind), and
-     * `DOD-M15-TERMINAL-REASON-1`'s F6, where `detail` exists specifically to carry the
-     * DIRECTORY's refusal cause out from behind a `seal_refused`.
-     *
-     * Optional, because an older relay sends none.
-     */
-    detail?: string;
-    /**
-     * DOD-M15-RELAYABUSE-1: milliseconds until the relay's rate-limit window clears, present only
-     * with `reason: "rate_limited"`. The relay computes it; nobody guesses it. `#doSubmit` waits
-     * this out and resubmits rather than surfacing a throttle — see the retry loop there.
-     */
-    retry_after_ms?: number;
-    /** On `seal_stale`: the position the relay needs this side to have seen before a close files. */
-    awaited_seq?: number;
-};
-export interface AgentRelayClientOpts {
-    relayPeerId: string;
-    relayAddrs: string[];
-    /** The agent's K_local signing key (relay auth + leaf signatures). */
-    keyProvider: KeyProvider;
-    /** The agent's K_local public key (32 bytes) — relay routes delivery by this. */
-    senderPubkey: Uint8Array;
-    logger: Logger;
-    /**
-     * Durable store for the relay's signed ordering-record receipts. When present, each
-     * verified `hash_submit_ack` is recorded immutably (the client's evidence of the relay's sequence
-     * attestation, carried to the directory at seal time). Optional — when absent, ACKs are not recorded.
-     */
-    receiptStore?: RelayReceiptStore;
-    /**
-     * The per-session leaf log a unilateral seal carries to the directory. When
-     * present, every leaf this client sees — its OWN submits (with the relay receipt) and the COUNTERPARTY's
-     * delivered leaves (no receipt) — is recorded so a later unilateral seal presents the full chain for the
-     * directory's OFFLINE tree rebuild. Optional — when absent, no leaf log is kept.
-     */
-    sealLeafStore?: SessionSealLeafStore;
-    /**
-     * `DOD-M15-SELFCHAIN-1` — what this agent last said in each session, so the next message links to
-     * it. Optional on the type because test harnesses construct a client without one; when it is
-     * absent this daemon cannot chain to itself and says so rather than signing an unlinked claim.
-     */
-    ownChainStore?: SessionOwnChainStore;
-    /**
-     * DOD-M15-RELAYSLOTS-1: the current directory-issued online token for this agent, or `undefined`
-     * when the directory has not issued one (not connected yet, or this key is not a registered
-     * agent). A relay refuses an auth without it, and refuses to let the peer hold a reservation slot.
-     *
-     * ⚠️ A FUNCTION, NOT A VALUE, and that is the whole point. The token is short-lived and reissued
-     * on every signaling reconnect — which happens far more often than a relay auth. A client
-     * constructed with a snapshot would work for the first hour of an agent's life and then present
-     * an expired token forever, losing its slot for a reason nothing on this side reports.
-     *
-     * Optional so a caller with no directory connection (tests of unrelated paths) compiles; production always supplies it.
-     */
-    onlineToken?: () => Uint8Array | undefined;
-    /**
-     * DOD-M15-CORROBORATE-1: the relay saw a leaf on one of this agent's sessions that verified
-     * against neither participant's key, and is telling us directly.
-     *
-     * Optional so a caller with no notice surface still compiles; production always supplies it. A
-     * client that decoded the frame and dropped it would leave the unit's whole point — a record the
-     * accused party's client cannot suppress — reaching nobody.
-     */
-    onWitnessAlert?: (alert: RelayWitnessAlert) => void;
-    /**
-     * DOD-M15-CORROBORATE-1 review F7: this relay sent a witness alert this build could not read or
-     * could not verify. Neutral by construction — a relay peer id and a machine-readable cause, never
-     * a session or a party.
-     */
-    onWitnessUnreadable?: (relayPeerId: string, why: string) => void;
-    /** First re-dial delay for a lost stream (doubles to a minute). Default `RELAY_RECONNECT_BASE_MS`. */
-    reconnectRetryMs?: number;
-}
-/**
- * What ONE relay observed. Deliberately not a verdict, and the field names say so: this establishes
- * that this relay saw and refused that submission, and nothing about who sent it. Verification is
- * proactive (`DOD-M15-CORROBORATE-1`); BREADTH is not — several relays on one hash sequence is
- * `DOD-M15-MULTIWITNESS-1`.
- */
-export interface RelayWitnessAlert {
-    sessionIdHex: string;
-    /**
-     * 034-CARRYLEAF — a second reason, and the two are NOT interchangeable to a reader.
-     *
-     * `leaf_signed_by_neither_participant` is a stranger's leaf reaching the relay.
-     * `leaf_witnessed_by_counterparty` is a participant putting a message in the record that its own
-     * author did not — which is the observable trace of the withholding attack, and also of an
-     * ordinary relay hiccup. Which of those it is depends on how often it happens, so the operator is
-     * told rather than the daemon deciding.
-     */
-    reason: "leaf_signed_by_neither_participant" | "leaf_witnessed_by_counterparty";
-    /** Which witness. Null when the relay runs without a signing identity and could not name itself. */
-    relayId: string | null;
-    observedAt: number;
-    /** True iff the relay says the submitter was our counterparty; false = a third party. */
-    submitterIsCounterparty: boolean;
-    /**
-     * The libp2p peer id of the relay that said it — always known, unlike `relayId`, which is absent
-     * for a relay that could not sign. Used to tell two unnamed witnesses apart.
-     */
-    witnessPeerId: string;
-    /**
-     * Whether the relay PROVED it said this — review F3.
-     *
-     * `true` means the signature verified against the key `relayId` names, so the operator holds
-     * something they can show a third party. `false` means the relay named no identity at all, so what
-     * they hold is our word that a relay told us — which is worth exactly as much as the accusation
-     * this is supposed to corroborate, and the inbox says so.
-     *
-     * There is no third state: a relay that DECLARES a `relayId` and fails to prove it is refused
-     * outright, never reported as an unverifiable alert.
-     */
-    verifiable: boolean;
-}
-/**
- * The directory-signed relay assignment a client presents to its chosen relay (a
- * `client_record_assignment` frame). The relay
- * reconstructs the relay TBS from these fields and verifies `assignmentSignature` (the directory's
- * per-node relayDirSig) against any consortium directory pubkey. Field order/presence MUST match the
- * directory producer (directory-node.ts) and the relay verifier (relay-node.ts recordAssignment).
- */
-/**
- * 034-CARRYLEAF — a leaf this agent RECEIVED, carried to the relay on its author's behalf.
- *
- * The author's own signed bytes and their signature over them, verbatim as they arrived on the
- * content frame. **Never re-encoded**: the signature is over the ENCODED BYTES, so a decode-and-
- * re-encode on this path would produce a claim the relay refuses and blame the wrong party for it.
- */
-export interface CarriedLeafClaim {
-    /** The AUTHOR's `structure1_cbor`, exactly as received. */
-    structure1Cbor: Uint8Array;
-    /** The AUTHOR's signature over those bytes, exactly as received. */
-    senderSignature: Uint8Array;
-}
-export interface RelayAssignmentCarry {
-    sessionSignature?: Uint8Array;
-    participantA: Uint8Array;
-    participantB: Uint8Array;
-    sessionTimestamp: number;
-    initiatorSessionPeerId?: string;
-    counterpartySessionPeerId?: string;
-    /**
-     * 64-byte per-node directory sig over the relay TBS (`relay_directory_signature`), presented to
-     * the relay as `client_record_assignment`.
-     *
-     * ⚠️ OPTIONAL SINCE 069-ORDERPROOF, and the split is real rather than defensive. A session can
-     * know WHICH relay may attest to it — `relay_id`, inside the FROST-signed assignment — while the
-     * directory issued no per-node relay signature to present. Those are two different facts and they
-     * were one field: folding them together would either make a session with nothing to present
-     * unable to verify anything, or make one that only knows its relay present an empty frame the
-     * relay refuses as forged.
-     */
-    assignmentSignature?: Uint8Array;
-    /**
-     * 069-ORDERPROOF — the assigned relay's ACK-SIGNING pubkey, hex, taken from `relay_id` on an
-     * assignment whose FROST signature has already been verified. **This is the only key a relay
-     * ordering attestation is checked against.** Absent means the directory named no relay for this
-     * session, and every attestation that arrives is then refused for want of an anchor — never
-     * accepted on the key the frame itself carries.
-     */
-    relayPubkeyHex?: string;
-}
-/**
- * Per-AGENT relay witness client. Shared across all of an agent's sessions; one
- * authenticated stream at a time (the relay keys by agent pubkey). Submits are FIFO and
- * single-in-flight on the stream; `leaf_deliver` is routed by session_id.
- */
-export declare class AgentRelayClient {
-    #private;
-    /** The cause of the most recent reader end, or null if it has not ended. */
-    getLastReaderError(): string | null;
-    /** The last classified auth refusal from this relay, or null if the last attempt succeeded. */
-    getLastAuthRefusal(): RelayAuthRefusal | null;
-    constructor(opts: AgentRelayClientOpts);
-    /** The agent's K_local public key as hex — the responder identity for auto-acknowledge. */
-    get senderPubkeyHex(): string;
-    /**
-     * Register a session's inbound leaf handler + a live node to (re)dial the relay from
-     * (idempotent). Storing the node per session lets a pure-receiver session re-establish
-     * the shared stream if the node that originally dialed is torn down.
-     */
-    registerSession(sessionIdHex: string, node: CelloNode, onLeafDeliver?: (frame: LeafDeliverFrame) => void, assignment?: RelayAssignmentCarry, 
-    /**
-     * 033-ACKEMIT — the session's genesis prev_root: what the FIRST message of this session
-     * acknowledges, before anything has been received.
-     *
-     * Supplied by the caller because `session-node-manager` is where the session record lives. When
-     * it is absent an ASSIGNMENT can still produce it (both participant keys and the session
-     * timestamp are on the carry), and that covers re-registration of a session whose row predates
-     * the column.
-     *
-     * ⚠️ WHEN NEITHER IS AVAILABLE THE SESSION CANNOT SUBMIT AT ALL — and this sentence used to say
-     * the opposite, that the first submit would claim position 0 with no hash. That shape no longer
-     * exists: `DOD-M15-SELFCHAIN-1` made both chain links required, so a session with no starting
-     * point has nothing for them to anchor to and every submit on it is refused by name. Registering
-     * without a seed is therefore a real fault, not a degraded mode.
-     */
-    genesisPrevRoot?: Uint8Array, 
-    /**
-     * 069-ORDERPROOF — the relay key this session's ordering attestations verify under, from
-     * `relay_id` on the directory-signed assignment. Supplied by the caller because
-     * `session-node-manager` is where the durable copy lives, exactly as with the genesis above.
-     *
-     * ⚠️ ABSENT IS NOT A DEGRADED MODE. A session with no anchor refuses every attestation that
-     * arrives on it, by name, because the only alternative is checking a signature against a key
-     * the signer handed us.
-     */
-    relayAnchorHex?: string): void;
-    /**
-     * DOD-M15-RELAYAUTH-1 review H1 — **present the assignment and WAIT for the relay to say it
-     * recorded it.**
-     *
-     * `registerSession` above presents eagerly and forgets: the record is queued onto the submit chain
-     * and nobody can observe when it lands. That is correct for the witness relay, where the only
-     * requirement is "before the first submit". It is NOT sufficient for the relay that GATES A DIAL,
-     * because there the record is a precondition of an action we are about to take on another thread
-     * of the protocol — and losing that race denies a legitimate dial (review H1).
-     *
-     * Chained on `#submitChain` exactly like `#doSubmit`, so it cannot interleave with a submit on the
-     * same stream. Idempotent by construction: `#doRecord` returns `true` immediately once the session
-     * is recorded, so calling this straight after `registerSession` waits for the record that call
-     * already queued rather than sending a second one.
-     *
-     * Returns whether the relay recorded it. NEVER throws — a caller must be free to proceed on false
-     * (a dial that might be denied still beats no dial at all).
-     */
-    recordAssignmentAndWait(node: CelloNode, sessionIdHex: string): Promise<boolean>;
-    /** Remove a session; caller closes the client when no sessions remain. */
-    unregisterSession(sessionIdHex: string): void;
-    hasSessions(): boolean;
-    /**
-     * Is THIS session already registered on this client?
-     *
-     * DOD-M15-RELAYLEAK-1 (review MEDIUM-5). The detached seal transport releases its registration
-     * when the submit finishes, and "did I register it, or did I find it already there?" is the
-     * difference between releasing my own and **pulling a live one out from under a concurrent
-     * caller** — which closes the client that caller is mid-`submitLeaf` on. `hasSessions()` cannot
-     * answer it: it is a count, and by then the id is in the set either way.
-     */
-    hasSession(sessionIdHex: string): boolean;
-    /**
-     * Proactively establish the authenticated stream from `node`. The RECEIVER must connect
-     * before the counterparty submits, so the relay has its stream to deliver `leaf_deliver`
-     * to (otherwise the relay queues until the recipient connects). Best-effort.
-     */
-    connect(node: CelloNode): Promise<boolean>;
-    /**
-     * DOD-M15-RELAYAUTH-1 review HIGH-1 — prove key possession FROM THIS NODE, on its own stream.
-     *
-     * ⚠️ **`connect()` CANNOT be used for this, and using it was the defect.** `#ensureConnected`
-     * returns `true` the moment `#stream` is non-null, and `#stream` belongs to whichever node
-     * connected FIRST. An agent legitimately runs several nodes against one relay — the node promoted
-     * into a live session, plus the replacement standing receiver built behind it — and they share
-     * one `AgentRelayClient` because the cache is keyed `${agent}::${relay}`. So calling `connect()`
-     * from the replacement receiver short-circuited on the session node's stream, sent nothing, and
-     * the relay never saw that receiver's transport identity: it revoked the reservation ~15s later,
-     * the watchdog rebuilt, and the agent churned on a ~45s loop holding no usable circuit address
-     * for as long as the conversation lasted. Any future "reuse the existing connection" optimisation
-     * here reintroduces exactly that.
-     *
-     * So this always opens its own short-lived stream from `node`, and marks it
-     * `purpose: "reservation"` so the relay proves possession WITHOUT rebinding the agent's delivery
-     * stream (which would steal the live session's inbound leaves — see the relay-side dispatch).
-     */
-    /**
-     * ⚠️ **THE FIRST ATTEMPT AFTER A COLD START IS EXPECTED TO FAIL, AND THAT IS NOT A FAULT ON
-     * EITHER SIDE.** Root-caused 2026-09-07 from libp2p's own debug log:
-     *
-     * ```
-     * circuit-relay listener: making reservation on relay
-     * reservation failed with status PERMISSION_DENIED     <- the relay's gate, working as designed
-     * could not add discovered relay
-     * connection-manager closing 1 connections / stopped / started
-     * ```
-     *
-     * libp2p's circuit-relay listener asks the relay for a reservation ON ITS OWN, before any CELLO
-     * code has proven anything. The relay's gate refuses an unproven peer — deliberately; its flow is
-     * *"asks, is refused, proves itself, and asks again"*. libp2p reacts to that refusal by discarding
-     * the relay and RESTARTING ITS CONNECTION MANAGER, which closes every connection — including the
-     * healthy one this proof is being opened on. Whichever lands first decides the outcome, so the
-     * failure is intermittent (measured 5/5, 2/4, 0/4, 1/6 across cold logins).
-     *
-     * **Both components are behaving as specified, so the refusal cannot be designed away from here** —
-     * removing it means either weakening the gate or reaching into libp2p's internal
-     * `transportManager.listen` to defer the circuit listener until after the proof. What the client
-     * CAN do is survive it: a transport-class failure is retried on a fresh connection, once.
-     *
-     * A REFUSAL IS NOT RETRIED. If the relay reached a verdict — no token, slot cap, misconfigured —
-     * the answer will be identical a second later, and retrying would spend the operator's reachability
-     * on a question already answered. Only a failure that never reached a verdict is retried.
-     */
-    proveReservation(node: CelloNode): Promise<boolean>;
-    /**
-     * 054-SRSPLIT — **TELL THE RELAY WE ARE DONE WITH OUR SLOT.**
-     *
-     * Resolves whether the relay confirmed it freed one. `false` covers "we held none" and "we could
-     * not reach the relay to say so" alike, and the caller must not read it as failure: releasing is
-     * tidy-up, and one that could not be delivered costs a slot until its TTL rather than breaking
-     * anything the agent is doing. Every path that returns false says why.
-     *
-     * ⚠️ **IT GOES ON THE LONG-LIVED DELIVERY STREAM, NOT A RESERVATION-PURPOSE ONE, AND THAT IS NOT
-     * A STYLE CHOICE.** The first version opened a fresh stream and authenticated with
-     * `purpose: "reservation"` — mirroring the proof. The relay's handler treats that purpose as a
-     * proof and nothing else: it answers `relay_auth_ok`, **closes the stream and returns without
-     * entering the message loop**. So the release frame went into a stream nobody was reading, the
-     * reply never came, and the verb was inert while every test passed. Found in review, not by the
-     * suite.
-     *
-     * ⚠️ **THE FRAME CARRIES NO PEER ID, deliberately.** The relay frees the peer this connection
-     * authenticated as. A peer id on the wire would let any registered agent free another's.
-     */
-    /**
-     * DOD-M15-AWAYSCOPE-1 — tell this relay whether anyone is attending this agent, for one session.
-     *
-     * ── WHY THIS EXISTS AT ALL ──────────────────────────────────────────────────────────────────────
-     *
-     * An unattended agent used to answer inbound messages with its away greeting. That greeting took a
-     * hash-chain leaf inside a live conversation, and on session `e7dd3f43…` it cost two operators a
-     * completed conversation's receipt, permanently. The fact itself is worth telling — a counterparty
-     * mid-exchange genuinely needs to know whether to wait — but it is a fact ABOUT the session, not a
-     * sentence IN it. So it rides here instead, and takes no leaf.
-     *
-     * ── FIRE AND FORGET, AND THAT IS THE DESIGN ─────────────────────────────────────────────────────
-     *
-     * Nothing is awaited and the relay sends no ack. The notice may be dropped, duplicated or arrive
-     * out of order; `observed_at` settles it, last-write-wins. A failure changes nothing the operator
-     * is doing — the counterparty reads "unknown" until the next notice, which is what is true.
-     *
-     * ⚠️ NO RETRY, NO QUEUE. Anything that made this reliable would want ordering, ordering wants a
-     * witness, and a witnessed position is how machine chatter reached the leaf set. A status hint
-     * that is allowed to be lost is the safe shape.
-     */
-    announceAttendance(node: CelloNode, sessionId: Uint8Array, attendance: SessionAttendance): void;
-    /**
-     * DOD-M15-AWAYSCOPE-1 — ask the relay about the counterparty: reachable, and attended?
-     *
-     * Two facts with two producers, which is why they are separate fields. `liveness` is the RELAY's
-     * observation — it holds that agent's standing connection or it does not. `attendance` is the far
-     * DAEMON's assertion about itself, which the relay was told and repeats; absent whenever
-     * `liveness` is not 'alive', because a daemon nobody can reach asserts nothing.
-     *
-     * ⚠️ EVERY FAILURE ANSWERS 'unknown', never 'gone'. A timeout, a dead stream, a refusal and an
-     * unparseable frame all mean "this side learned nothing"; reporting any as `gone` invents an
-     * observation nobody made, and `gone` is the value that tells an operator their peer has left.
-     */
-    /**
-     * Test-only seams for the liveness query path, which cannot be reached any other way.
-     *
-     * ⚠️ THEY EXIST BECAUSE A ONE-SESSION FAKE HID A REAL DEFECT. Every other test of this feature
-     * stubs `queryLiveness` outright, so the code that matches an ANSWER to its QUESTION never ran —
-     * and it was wrong: a single resolver slot handed one session's answer to another session's
-     * promise the moment an agent held two conversations through one relay, which is ordinary.
-     * Reaching that code needs a live stream and a dispatched frame, and both are private.
-     *
-     * Named `ForTest` like `__setLastActivityAtForTest` and `patchRelayClientForTest`, and doing
-     * nothing production does not: one installs the stream a dial would have produced, the other
-     * feeds the reader loop a frame the relay would have sent.
-     */
-    installStreamForTest(stream: Stream): void;
-    dispatchForTest(frame: Record<string, unknown>): void;
-    queryLiveness(sessionId: Uint8Array, counterpartyPubkey: Uint8Array): Promise<LivenessAnswer>;
-    releaseReservation(node: CelloNode): Promise<boolean>;
-    /**
-     * Submit a session's CONTENT-leaf hash to the relay. Connects/re-connects from `node` if needed.
-     * Globally FIFO across the agent's sessions (the ack has no session_id).
-     *
-     * `leafKind` defaults to MESSAGE, which is what `cello_send` wants. It is a PARAMETER because
-     * the document path needs 0x04/0x05: the seal certificate is computed by the directory from the
-     * leaves the RELAY witnessed, and `seal-legibility.ts` excludes doc/reject leaves from
-     * `final_message` and from `answered` — guards that could never fire while this method hardcoded
-     * MSG for every caller. See `document-leaf-kind-on-the-wire.test.ts` for what that cost.
-     */
-    submitMessageHash(node: CelloNode, sessionId: Uint8Array, contentHash: Uint8Array, 
-    /**
-     * REQUIRED — `DOD-M15-SEALWIRE-1` B2b-1 pass-2 F3. This default was the last one on the path,
-     * and it is the reason a test passing `undefined` for `leafKind` looked correct: the value was
-     * silently rebuilt as MESSAGE one hop below the parameter the fix had just made required. Its
-     * one production caller always passes explicitly, so the default was dead and misleading.
-     */
-    leafKind: number): Promise<SubmitResult>;
-    /**
-     * ─── WITNESS A LEAF THIS AGENT RECEIVED BUT DID NOT AUTHOR — 034-CARRYLEAF ────────────────────
-     *
-     * **This is what closes `DOD-M15-WITHHOLD-SEAL-1`.** Until it existed, `submitMessageHash` had
-     * one production caller on the SEND path, so nothing ever witnessed a message that was RECEIVED.
-     * A counterparty who delivered a message directly and never submitted its hash left the relay's
-     * account of the conversation one message short — permanently — and a unilateral seal then agreed
-     * with the witness. Every leaf validly signed, nothing false, the last thing said simply absent.
-     *
-     * **The teeth are the author's own signature.** It arrived on the content frame beside the bytes
-     * it signs, this daemon verified it before ingesting anything, and it cannot be forged here. The
-     * relay verifies it again against the session's assignment before sequencing — so what this hands
-     * over is a claim the author made and cannot disown.
-     *
-     * ⚠️ **THE BYTES ARE PASSED THROUGH, NEVER REBUILT.** A signature is over the encoded bytes, and
-     * the one measured cost of forgetting that on this exact structure was a daemon-local encoder
-     * emitting a timestamp as float64 where the published one promotes to uint64 — same value,
-     * different signed bytes, refused by everyone.
-     */
-    witnessReceivedLeaf(node: CelloNode, sessionId: Uint8Array, contentHash: Uint8Array, leafKind: number, carried: CarriedLeafClaim): Promise<SubmitResult>;
-    /**
-     * Submit a leaf hash of a given kind (0x00 message / 0x02 control) to the relay. The SEAL
-     * ctrl leaf rides this path: two distinct-sender ctrl leaves in the relay's
-     * log trigger the directory's FROST notarization (relay `#maybeProcessSeal`).
-     *
-     * ─── `contentBytes` — `DOD-M15-SEALWIRE-1` bullets 3+4, THE SENDER LEG ───────────────────────
-     *
-     * The SEAL leaf's own payload, carried alongside its hash. Without it the directory holds a
-     * SHA-256 pre-image and nothing else, so the client's SIGNED `final_root` — the one value in the
-     * whole seal that the relay cannot produce — is unrecoverable, and every root check the directory
-     * can make compares the relay against itself.
-     *
-     * ⚠️ THIS PARAMETER PUTS LEAF CONTENT ON THE RELAY, AND THE RELAY IS THE PARTY THIS PROTOCOL
-     * EXISTS TO KEEP CONTENT AWAY FROM (INV-3: a forwarding relay sees ciphertext).
-     *
-     * It is safe for a SEAL ctrl leaf and for nothing else. The payload is `[session_id, final_root,
-     * close_timestamp, "PENDING"]` and the relay already knows all four — it assigned the session,
-     * built the tree the root comes from, and stamped the leaf. Nothing is disclosed. That reasoning
-     * stops dead at the next leaf kind: a `msg` leaf's content is the operator's plaintext and a `doc`
-     * leaf's is their document.
-     *
-     * So both directions are REFUSED rather than tidied, and refused HERE rather than at the relay:
-     *
-     *   - content on a non-ctrl leaf → the relay would refuse the whole frame, but only after the
-     *     operator's words had already crossed the wire to the party that must not have them, and the
-     *     refusal would destroy their send rather than protect it.
-     *   - a ctrl leaf with NO payload → this was the actual defect. `submitSealLeaf` computed the
-     *     payload, hashed it, and had nowhere to put it, so it was dropped. The seal still succeeded,
-     *     the relay still acked, and three hops later the directory reported `not_carried` and blamed
-     *     the relay's build version — for a value the client never sent. Four reviewed legs shipped
-     *     over that silence. A dropped argument now fails on the machine that dropped it.
-     *
-     * ⚠️ REQUIRED, AND `| null` RATHER THAN `?` — THE TYPE IS THE GUARD.
-     *
-     * I first wrote this optional and covered it with tests. Then I ran the revert test that mattered:
-     * drop the argument at the one call site that must pass it, exactly reproducing the original
-     * defect. **All five new tests stayed green.** An optional parameter makes the defect a silent,
-     * type-legal omission — which is precisely how it shipped through four reviews the first time.
-     *
-     * Required means the omission is a COMPILE ERROR, caught by the gate on the machine that made it,
-     * before any test runs. Every caller must now say what this leaf carries, and `submitMessageHash`
-     * says `null` in one visible place instead of by saying nothing at all.
-     */
-    submitLeaf(node: CelloNode, sessionId: Uint8Array, contentHash: Uint8Array, leafKind: number, contentBytes: Uint8Array | null, 
-    /**
-     * 034-CARRYLEAF — a leaf THIS AGENT DID NOT AUTHOR, carried on its author's behalf.
-     *
-     * Absent for every ordinary send, where this client builds and signs its own claim. Present
-     * only when witnessing something received whose author never submitted it — see
-     * `witnessReceivedLeaf`.
-     */
-    carried?: CarriedLeafClaim): Promise<SubmitResult>;
-    /**
-     * Advance this session's acknowledgement from a message that ARRIVED — 033-ACKEMIT review F1.
-     *
-     * ⚠️ **`#bumpLastSeen` used to have exactly one caller, inside the `leaf_deliver` handler, so the
-     * acknowledgement tracked what the RELAY DELIVERED rather than what was RECEIVED.** On a direct
-     * session that is a real difference: the content arrives peer-to-peer and the relay's copy of the
-     * leaf follows separately, so until it did, this daemon signed an acknowledgement one message
-     * behind what it had actually read — and on a session where delivery never came back at all, the
-     * acknowledgement never moved.
-     *
-     * The order's own words are "the content hash of the last message this sender ACTUALLY RECEIVED".
-     * This is the caller that makes that true: the receive path calls it as soon as a message has been
-     * verified and ingested at a known canonical position.
-     *
-     * **THE POSITION IS STILL REQUIRED, and that is a real limit rather than an oversight.** The pair
-     * is (position, content-at-position), and the relay refuses a `last_seen_seq` that runs ahead of
-     * its counter — so a message that arrived with NO ordering record cannot be acknowledged by
-     * position at all, whatever we hold of it. That case is the withheld-submit attack itself, and it
-     * is closed by carrying the sender's signed leaf into the seal, not from here.
-     */
-    noteReceivedLeaf(sessionIdHex: string, relaySeq: number, contentHash: Uint8Array): void;
-    /**
-     * The POSITION and the CONTENT AT IT together — 033-ACKEMIT.
-     *
-     * ⚠️ **IT REPLACED `lastSeenSeq()`, WHICH IS DELETED RATHER THAN LEFT WIRED.** That accessor
-     * returned the position alone, and `session-node-manager`'s unwitnessed content claim was its
-     * only caller. Leaving it in place after this one took over would leave a second way to read half
-     * of a pair that must be read whole: a `last_seen_seq` paired with a `last_seen_hash` for a
-     * different message is worse than no acknowledgement at all, because it looks checkable and
-     * fails.
-     *
-     * `undefined` means this session has no acknowledgement to make, which the caller must handle
-     * rather than fill in.
-     */
-    lastSeenAck(sessionIdHex: string): {
-        seq: number;
-        hash: Uint8Array;
-    } | undefined;
-    /**
-     * This agent's OWN last message on a session — what its next message's self link must name.
-     *
-     * ⚠️ EXPOSED BECAUSE THERE MUST BE ONE CHAIN, NOT TWO. The unwitnessed send path lives in
-     * `session-node-manager` and was reading only the durable store, while the witnessed path reads
-     * this in-memory map first. A session that mixed the two — which is every session where the relay
-     * comes and goes — was walking two different chains, and the one that lagged produced a link the
-     * counterparty refuses.
-     *
-     * `undefined` means this agent has not spoken on this session yet, which is the session GENESIS
-     * and not an absence. The caller supplies it; this class does not guess.
-     */
-    lastOwnHash(sessionIdHex: string): Uint8Array | undefined;
-    /**
-     * Record what this agent just sent on a path this client did not carry — the UNWITNESSED send.
-     *
-     * The two paths share one chain (see `lastOwnHash`), so a direct send has to advance it here too.
-     * Without this, a conversation that ran while the relay was down advanced nothing, and the first
-     * witnessed message after it linked to something long superseded.
-     */
-    noteOwnLeaf(sessionIdHex: string, contentHash: Uint8Array): void;
-    close(): void;
-}
-//# sourceMappingURL=session-relay-client.d.ts.map