@cello-protocol/daemon 0.0.194 → 0.0.195

package/dist/session-schema.js.map

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

package/dist/standing-receivers.d.ts

@@ -0,0 +1,280 @@
+/**
+ * CELLO Daemon — THE STANDING RECEIVER: THE NODE THAT IS ALWAYS LISTENING
+ *
+ * Split out of `session-node-manager.ts` by 037-SESSIONCORE. One pre-created node per agent, kept
+ * alive at all times and handed to the first inbound session — then immediately replaced, so there
+ * is always one waiting.
+ *
+ * ⚠️ **ITS GATER IS NOT OPEN, and this sentence used to say it was.** `DOD-M15-ASSIGN-1` closed
+ * exactly that: the gater admits NOBODY inbound until a session offer names the dialer, while
+ * leaving this node's own outbound errands open (`allowedPeerId: null` — see the construction
+ * below, which says the same thing in the imperative).
+ *
+ * The wrong version is called out rather than quietly corrected because of what believing it costs:
+ * a reader who thinks the gater is open reads an unnamed-dialer rejection as a BUG and opens it, or
+ * waves off the hardening as already done. It was inherited from the manager's own header, which is
+ * corrected in the same commit.
+ *
+ * Moved verbatim, comments included.
+ *
+ * ⚠️ ITS ABSENCE IS THE FIRST SUSPECT WHEN A LIVE SESSION FAILS. `standing_receiver_unavailable`,
+ * an empty counterparty peer id, `Invalid peer ID: ""` — all of them start here. The receiver is
+ * created when the agent is STARTED, not at daemon boot, so an agent that was never started has no
+ * receiver and nothing to hand an inbound session.
+ */
+import type { Logger } from "./types.js";
+import { NodeAutoNatService, type CelloNode, type IAutoNatService } from "@cello-protocol/transport";
+import { SessionConnectionGater } from "./session-connection-gater.js";
+import type { DaemonDatabase } from "./sqlcipher-db.js";
+import type { ISessionNodeFactory } from "./session-node-types.js";
+import { type SessionNodeConfig } from "./session-node-types.js";
+import type { SessionRecords } from "./session-records.js";
+import type { ParkRecovery } from "./park-recovery.js";
+/** What the standing receiver needs from the manager. */
+export interface StandingReceiverContext {
+    readonly logger: Logger;
+    readonly records: SessionRecords;
+    readonly park: ParkRecovery;
+    readonly factory: ISessionNodeFactory;
+    /** A function: the manager opens its database after construction. Re-exposed below as `#db`. */
+    db(): DaemonDatabase | null;
+    shuttingDown(): boolean;
+    sessionKey(agentName: string, sessionId: string): string;
+    /**
+     * ⚠️ THESE MAPS ARE SHARED BY REFERENCE, NOT OWNED HERE. The reservation watchdog, the relay
+     * paths and session creation all read them and all stayed behind, so giving this module its own
+     * copies would create two answers to "which agents have a receiver". Each is assigned exactly
+     * once, at construction, so there is one object and no divergence.
+     */
+    readonly standingReceivers: Map<string, {
+        node: CelloNode;
+        gater: SessionConnectionGater;
+        autoNat: NodeAutoNatService;
+        seed: Uint8Array;
+        relayPeerIds: string[];
+    }>;
+    readonly standingReceiverCreating: Set<string>;
+    readonly agentsWantingReceiver: Set<string>;
+    readonly standingReceiverRemoving: Set<string>;
+    readonly srReservationRetry: Map<string, {
+        attempts: number;
+        nextAt: number;
+        correlationId: string;
+        lastReason?: string;
+    }>;
+    readonly srLastRejectionReason: Map<string, string>;
+    readonly srLastRespreadAt: Map<string, number>;
+    readonly directoryRelayEndpoints: Map<string, Array<{
+        relayPeerId: string;
+        relayAddrs: string[];
+    }>>;
+    readonly srRetryDelaysMs: number[];
+    readonly srReservationTimeoutMs: number;
+    /** The AutoNAT prober list, injected by the composition root. */
+    autoNatProbers(): string[];
+    proveToRelay(agentName: string, circuitAddr: string, node: CelloNode, correlationId: string, surfaceAsReceiverRefusal: boolean): Promise<"proven" | "refused_try_another_relay" | "refused_this_agent" | "unavailable">;
+    reservationCircuitAddrs(agentName: string): {
+        addrs: string[];
+        relayPeerIds: string[];
+    };
+    authenticateStandingReceiver(agentName: string, node: CelloNode, relayPeerId: string, heldCircuitAddr: string, correlationId: string): Promise<void>;
+}
+export declare class StandingReceivers {
+    #private;
+    constructor(ctx: StandingReceiverContext);
+    /**
+     * DOD-LOOP-1: ensure the given agent has a standing receiver node (idempotent). Created when an
+     * agent comes online (cello_start_agent) and replaced after it is handed off to a session. The
+     * `#standingReceiverCreating` guard prevents two concurrent ensure() calls (e.g. the
+     * cello_start_agent hook racing a consume-site retry) from building two nodes for one agent.
+     *
+     * M8B F14: a create failure no longer strands the agent deaf. Each ensure runs a BOUNDED
+     * retry loop (`standingReceiverRetryDelaysMs`, default 1s/5s/15s) — covering the fixed-port
+     * race where the consumed receiver still holds the port until its session node is torn down —
+     * and when every attempt fails, fires the alarm-worthy `session.standing_receiver.dead`
+     * (error level), distinct from the per-attempt `session.node.create.failed`. Re-arm is also
+     * kicked from destroySessionNode/retireSessionNode (the moment the port frees) and from the
+     * inbound accept path (ensure on demand), so one failure can never leave the agent deaf forever.
+     */
+    ensureStandingReceiver(agentName: string, correlationId?: string): Promise<void>;
+    /**
+     * Replace an agent's reservation-less standing receiver with one that reserves.
+     *
+     * Deliberately NOT removeStandingReceiverForAgent()+ensureStandingReceiverForAgent():
+     * the public remove CLEARS #agentsWantingReceiver, so a cello_set_agent_offline landing in
+     * the window while node.stop() is awaited would find no map entry and no creating
+     * marker, leave no tombstone, and the re-ensure would then RESURRECT a receiver for
+     * an agent that asked to go dark — accepting inbound sessions for an offline agent.
+     * Here the want-flag is left intact and re-checked after the stop: a concurrent stop
+     * clears it, and the rebuild correctly no-ops.
+     */
+    rebuildStandingReceiver(agentName: string): Promise<void>;
+    /**
+     * DOD-M12B-SESSION-SEED-1 — build a revived session node that is REACHABLE, without ever hanging.
+     *
+     * MEASURED 2026-08-18, live, three ways:
+     *   - handed 2 relay addrs at once, no deadline:  `start()` never completes (10,002ms and counting)
+     *   - handed none:                                `start()` in 1ms, but NOBODY can dial the node —
+     *                                                 the counterparty's re-dial fails
+     *                                                 `counterparty_dial_failed` and every message in
+     *                                                 both directions has to go the relay park route
+     *   - this:                                       one candidate at a time, each raced against its
+     *                                                 own deadline, plain node as the floor
+     *
+     * The middle option is what shipped for one test run and it made the session half-dead: revived,
+     * `active`, and unreachable. The first is what shipped before that and it hung. Neither is a
+     * choice between "fast" and "reliable" — the per-candidate race is how `#startReceiverNode` has
+     * always done it, and it is the shape that works in production every day.
+     *
+     * A FAILED CANDIDATE IS TORN DOWN AT SETTLEMENT. The first version awaited `stop()` immediately
+     * and claimed that made seed reuse safe; it did not — `libp2p.stop()` returns at once unless the
+     * node is `'started'`, and during the timeout window it is `'starting'` (review HIGH-3, verified
+     * against libp2p 3.3.2). The teardown is now chained onto the candidate's OWN start promise, so it
+     * runs whenever that settles, however late.
+     *
+     * A BRIEF OVERLAP IS THEREFORE POSSIBLE and is stated rather than denied: a candidate that grants
+     * at 4s comes up on this session's peer id and is stopped immediately after. What is guaranteed is
+     * that it dies, not that it never lives. The receiver path avoids even that by minting a seed per
+     * candidate; here the identity is fixed, which is the whole point of a revival, so that option
+     * does not exist.
+     *
+     * The floor is a plain node: a session that is usable over the relay park route beats no session.
+     */
+    buildRevivedNode(sessionId: string, gater: SessionConnectionGater, seed: Uint8Array, candidateAddrs: string[], agentName: string): Promise<CelloNode>;
+    /**
+     * DOD-M15-RELAYONLY-1: build a transport node for THIS AGENT, with its privacy posture applied.
+     *
+     * ⚠️ THE CHOKE POINT FOR NODE CREATION, and it exists for the same reason as the one around
+     * `getStandingReceiverInfo`. Five call sites construct nodes; passing `relayOnly` at each would be
+     * a hand-kept list, and the SIXTH — added next month by someone who has never read this line —
+     * would build a node that hole-punches its way to a direct connection for an operator who asked
+     * never to be directly reachable. Here, a new caller inherits the posture instead of being told.
+     *
+     * `unknown` counts as ON, matching the publish and dial halves: a node that declines to hole-punch
+     * is reachable over the relay, while a disclosed address cannot be recalled.
+     */
+    createAgentNode(agentName: string, config: SessionNodeConfig): Promise<CelloNode>;
+    /**
+     * DOD-PARK-DRAIN-1 (review F6): why there is no standing-receiver node to dial from — named
+     * precisely, because `standing_receiver_unavailable` is the exit-point label that stood in for
+     * four different causes and misnamed this very incident 102 times.
+     *
+     * Only meaningful once `getStandingReceiverNode()` has returned null, which means NO agent on
+     * this daemon has a ready receiver — the dial node is not agent-scoped.
+     */
+    standingReceiverAbsenceReason(agentName: string): "daemon_shutting_down" | "standing_receiver_creating" | "agent_offline" | "no_standing_receiver";
+    getStandingReceiverInfo(agentName: string): {
+        peerId: string;
+        addrs: string[];
+    } | null;
+    /** DOD-LOOP-1: whether the given agent has a standing receiver ready (any agent if omitted). */
+    getStandingReceiverReady(agentName?: string): boolean;
+    /**
+     * The standing receiver's libp2p node — a general-purpose node usable for OUTBOUND dials that
+     * are not session-scoped (e.g. the content-park deposit/pull to the relay, MSG-001-3b). Its
+     * gater admits nobody INBOUND until a session names them (DOD-M15-ASSIGN-1), but leaves these
+     * outbound errands open. Returns null until the receiver is ready.
+     */
+    getStandingReceiverNode(agentName?: string): CelloNode | null;
+    /**
+     * DOD-M12B-RESERVATION-RETRY-1 — whether a NAT'd peer can actually DIAL this agent.
+     *
+     * `standing_receiver_ready` answers "is there a receiver?", which is true for a plain TCP node
+     * that no relay would give a circuit reservation to. Behind NAT that node is reachable by nobody,
+     * and the difference was visible only in the log — where it was visible 481 times and nobody
+     * acted. `"retrying"` and `"unreachable"` are the states an operator can do something about.
+     *
+     *   reserved    — holds a circuit reservation; a NAT'd peer can dial it.
+     *   retrying    — no reservation yet, still re-asking on a backoff.
+     *   unreachable — no circuit reservation and the automatic re-attempts are spent, so only peers
+     *                 that can connect DIRECTLY will get in. It is not permanent: a directory
+     *                 reconnect carrying a DIFFERENT relay pool re-arms the budget, because a relay we
+     *                 have never tried is new information.
+     *   absent      — no receiver at all (the agent is not online).
+     */
+    getStandingReceiverReachability(agentName: string): "reserved" | "retrying" | "unreachable" | "absent";
+    /**
+     * 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;
+    /**
+     * Which peer this agent's standing receiver is currently admitting INBOUND — `null` for nobody.
+     *
+     * Read-only, and it answers a question the daemon otherwise cannot: *"whose dial would this
+     * receiver accept right now?"* The gate is narrowed and re-closed from several paths (an offer
+     * arrives, an assignment is refused, a session is promoted), and until now the only way to know
+     * where it had ended up was to reproduce the sequence in your head.
+     *
+     * Added for `DOD-M15-RESPONDER-VERIFY-1`, where a refusal for one session was closing the gate a
+     * DIFFERENT session had narrowed — a defect with no observable symptom short of the second
+     * session's initiator being refused with "nothing invited it".
+     */
+    getStandingReceiverAllowedPeer(agentName: string): string | null;
+    /**
+     * DOD-M15-ASSIGN-1 — name the one peer allowed to dial this agent's standing receiver, at the
+     * moment the directory's `session_offer` says who is coming.
+     *
+     * This is what makes the receiver's deny-by-default safe. The offer names
+     * `initiator_session_peer_id`, and the responder answers it by advertising its OWN address in
+     * `session_offer_accept`. Narrowing here — BEFORE that answer goes out — means the door opens to
+     * exactly one peer at the same instant the address that reaches them is published, and never
+     * before. The initiator cannot know where to dial until the accept it triggers has been sent.
+     *
+     * Returns WHICH failure it was, never a bare false (review F6). The caller reports a distinct
+     * reason per cause: "no receiver" and "the directory named nobody" are different subsystems, and
+     * collapsing them sent the operator to the directory for a local problem. This method never
+     * widens the gate to compensate.
+     *
+     * Narrows INBOUND ONLY. The receiver is still the daemon's general-purpose dialer at this point
+     * — no assignment exists yet — so revoking its outbound latitude here would break content
+     * parking and restart-seal submission (review F2).
+     */
+    admitOfferedDialer(agentName: string, initiatorSessionPeerId: string, sessionIdHex: string): "narrowed" | "no_receiver" | "no_peer_named";
+    /**
+     * What the UNSIGNED offer claimed, so the SIGNED assignment can be checked against it.
+     *
+     * DOD-M15-OFFER-SIGNED-1. Decision 2 rules that the listening socket is "gated on the
+     * assignment", and the gate is narrowed from `session_offer` — a frame carrying no signature —
+     * because that is the only thing that arrives early enough. Timing forced the offer; it does not
+     * excuse trusting it.
+     *
+     * Keeping what the offer said turns the two frames into a CHECK ON EACH OTHER. The assignment is
+     * FROST-signed by the initiator's own threshold group, which no single directory can produce, and
+     * it names the same peer id. A directory that says one peer in the offer and another in the
+     * assignment is naming two different dialers for one session — which a truthful directory never
+     * does, and which is exactly the move a compromised one would make to slip a peer past the gate
+     * before the signed document arrives.
+     */
+    getOfferedDialer(agentName: string, sessionIdHex: string): string | null;
+    /** Forget the offered dialer for ONE session — called on BOTH the claim and the refusal paths. */
+    clearOfferedDialer(agentName: string, sessionIdHex: string): void;
+    /**
+     * RE-CLOSE the standing receiver — but ONLY if this session is still the one holding it.
+     *
+     * DOD-M15-OFFER-SIGNED-1 review F4, then N1. The first version closed the gate unconditionally,
+     * and that was worse than the defect it fixed: an agent has ONE standing receiver with ONE allowed
+     * peer, so a refusal for session P closed the gate that offer Q had narrowed. Q's initiator —
+     * invited, legitimate — was then refused with *"nothing invited it"*, which this daemon had.
+     *
+     * That is the same cross-session interference F1 was written to remove, moved one method along,
+     * and triggerable the same way: one bogus offer/assignment pair collapses a concurrent real
+     * session.
+     *
+     * So the gate is closed only when it still names the peer THIS session opened it to. If a later
+     * offer has already re-narrowed it, that offer owns the receiver and its narrowing stands.
+     *
+     * NO EVICTION SWEEP, deliberately (N4). The sweep evicts by "not the allowed peer", and
+     * `getConnections()` returns OUTBOUND connections too — including the content-park and
+     * restart-seal dials this node makes as the daemon's general-purpose dialer, whose targets are on
+     * no allowlist by construction. Sweeping here hung those up, and the failure surfaced as
+     * `relay_unavailable`: a transport label for a local decision, which is the exact substitution
+     * that comment was written to prevent. The load-bearing control is `DOD-M15-FRAME-1`'s frame gate,
+     * which refuses what an unauthorised peer sends; closing the door is enough here.
+     */
+    revokeOfferedDialer(agentName: string, sessionIdHex: string, offeredPeerId: string | null): void;
+}
+//# sourceMappingURL=standing-receivers.d.ts.map

package/dist/standing-receivers.d.ts.map

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