@cello-protocol/daemon 0.0.227 → 0.0.228

package/dist/transport-selector.d.ts

@@ -0,0 +1,202 @@
+/**
+ * CELLO Daemon — transport-selector.ts (CELLO-M7-TRANSPORT-001)
+ *
+ * Direct-P2P-by-default transport selection with relay fallback and a best-effort
+ * dcutr hole-punch upgrade.
+ *
+ * ─── Specification (Phase S) ──────────────────────────────────────────────────
+ * Given a FROST-signed SessionAssignment (produced by WIRE-001), choose how to
+ * dial the counterparty's session node:
+ *   1. Read transport_mode from the assignment. This is the ONLY authority for
+ *      the dial strategy (SI-001 / AC-015) — NEVER infer mode from address format.
+ *   2. transport_mode === 'direct' → dial counterparty_session_addrs directly.
+ *   3. direct dial fails OR transport_mode === 'relay' → dial the relay circuit
+ *      address (from the daemon's relay registry, independent of transport_mode —
+ *      AC-006).
+ *   4. After a relay connection is established → attempt a dcutr hole-punch upgrade
+ *      (non-blocking, best-effort). Failure is non-fatal (SI-003).
+ *   5. If BOTH direct and relay fail → terminal 'relay_fallback_also_failed' (AC-008).
+ *
+ * Error code registry (fixed strings — also in CONTEXT.md):
+ *   'autonat_unavailable'                       — internal; no probers reachable.
+ *   'direct_dial_failed_falling_back_to_relay'  — WARN; intermediate, non-fatal.
+ *   'relay_fallback_also_failed'                — terminal session failure.
+ *   'dcutr_upgrade_failed'                      — DEBUG; non-fatal.
+ *
+ * ─── Pseudocode (Phase P) ─────────────────────────────────────────────────────
+ * dial(assignment, { correlationId }):
+ *   mode = assignment.transport_mode            // authoritative
+ *   sessionId = hex(assignment.session_id)
+ *   peerId = assignment.counterparty_session_peer_id
+ *   directAddrs = assignment.counterparty_session_addrs ?? []
+ *   if mode === 'direct':
+ *     try { dialer.dialDirect(peerId, directAddrs); log mode.selected('direct'); return {ok, 'direct'} }
+ *     catch e { log direct_dial.failed(WARN, e.message) }   // fall through
+ *   try { dialer.dialRelay(dialer.relayCircuitAddr(assignment), peerId) }
+ *   catch { return {ok:false, 'relay_fallback_also_failed', guidance} }   // NO mode.selected
+ *   log mode.selected('relay')
+ *   dcutrSettled = (async () => {
+ *     try { dialer.attemptDcutr(peerId); log dcutr.upgraded(INFO); return true }
+ *     catch e { log dcutr.failed(DEBUG, e.message); return false } })()
+ *   return {ok:true, 'relay', dcutrSettled}             // dial does NOT await dcutr
+ */
+import type { SessionAssignment } from "@cello-protocol/protocol-types";
+import type { Logger } from "./types.js";
+import type { Dialability } from "@cello-protocol/transport";
+export declare const TRANSPORT_ERROR: {
+    /** Internal: AutoNAT could not run because no directory-node probers are reachable. */
+    readonly AUTONAT_UNAVAILABLE: "autonat_unavailable";
+    /** WARN-level intermediate, non-fatal: direct dial failed, relay fallback initiated. */
+    readonly DIRECT_DIAL_FAILED_FALLING_BACK: "direct_dial_failed_falling_back_to_relay";
+    /** Terminal: both direct dial and relay fallback failed. */
+    readonly RELAY_FALLBACK_ALSO_FAILED: "relay_fallback_also_failed";
+    /** DEBUG-level non-fatal: dcutr hole-punch upgrade attempt failed. */
+    readonly DCUTR_UPGRADE_FAILED: "dcutr_upgrade_failed";
+};
+/** Default direct-dial timeout (ms). Not a user-facing option (implementation_notes). */
+export declare const DEFAULT_DIRECT_DIAL_TIMEOUT_MS = 5000;
+/**
+ * The outcome of a transport selection. Discriminated by `ok` so the failure
+ * branch is exactly the `{ ok:false, reason, guidance }` shape the MCP layer
+ * surfaces to the caller (AC-008).
+ *
+ * For the relay branch, `dcutrSettled` resolves when the background dcutr attempt
+ * settles — `true` if the connection was hole-punch upgraded to direct, `false`
+ * otherwise. dial() does NOT await it: the session is usable immediately upon the
+ * relay connection (AC-007). Production callers may ignore `dcutrSettled`.
+ */
+export type TransportResult = {
+    ok: true;
+    mode: "direct";
+} | {
+    ok: true;
+    mode: "relay";
+    dcutrSettled: Promise<boolean>;
+} | {
+    ok: false;
+    reason: typeof TRANSPORT_ERROR.RELAY_FALLBACK_ALSO_FAILED;
+    guidance: string;
+};
+export interface TransportDialOptions {
+    /** Correlation ID threaded through every event for this session flow. */
+    correlationId: string;
+}
+/**
+ * Adapter interface for choosing and performing the transport dial.
+ * Real implementation: TransportSelector (drives a TransportDialer + Logger).
+ * Stub: LocalTransportSelectorStub (returns configurable canned results — used by
+ * the composition root when CELLO_ENV is 'local'|'test').
+ */
+export interface ITransportSelector {
+    dial(assignment: SessionAssignment, opts: TransportDialOptions): Promise<TransportResult>;
+}
+/**
+ * The advertised address this daemon offers to the directory for a new session,
+ * derived from the standing receiver's AutoNAT dialability (AC-004 / AC-019):
+ * a direct multiaddr when dialable, the relay circuit address otherwise.
+ */
+export interface SessionNegotiationContext {
+    agentName: string;
+    correlationId: string;
+    advertisedAddress: AdvertisedAddress;
+    params: Record<string, unknown>;
+}
+/**
+ * Outcome of directory session negotiation. On success it carries the
+ * FROST-signed SessionAssignment (transport_mode + counterparty_session_addrs)
+ * that the TransportSelector then consumes.
+ */
+export type SessionNegotiationResult = {
+    ok: true;
+    assignment: SessionAssignment;
+    /**
+     * 038-KEYBIND. The COUNTERPARTY's FROST group public key, hex — the value the initiator
+     * records so a responder-first seal can be verified locally instead of accepted
+     * `signer_key_not_held`.
+     *
+     * IT TRAVELS AS ITS OWN FIELD RATHER THAN BEING READ OFF `assignment` at the call site, and
+     * that is deliberate. The same bytes ride on the frame, but the frame carries them whether or
+     * not anyone checked them. This field only exists on a result that came through
+     * `verifyAssignmentSignature`, which refuses unless the counterparty's own identity key signed
+     * for the key. Pinning a counterparty's permanent trust anchor is exactly the operation that
+     * must not be reachable from an unchecked field.
+     */
+    counterpartyPrimaryHex: string;
+} | {
+    ok: false;
+    reason: string;
+    guidance: string;
+};
+/**
+ * Adapter that performs directory session negotiation and returns the
+ * FROST-signed SessionAssignment. The real implementation is owned by
+ * WIRE-001/SIGNAL-001 (directory signaling); it is injected into the daemon
+ * composition root. When absent, cello_initiate_session reports
+ * directory_signaling_not_configured (it does NOT crash — the transport adapters
+ * are still wired). This is the seam that lets cello_initiate_session drive the
+ * transport selector once an assignment exists (AC-010(c)).
+ */
+export interface SessionNegotiator {
+    negotiate(ctx: SessionNegotiationContext): Promise<SessionNegotiationResult>;
+}
+/**
+ * The low-level dial operations the selector composes. The real implementation
+ * wraps a CelloNode (direct dial + relay circuit dial) plus the daemon's relay
+ * registry. Each operation throws on failure; the selector catches and routes.
+ */
+export interface TransportDialer {
+    /** Dial the counterparty directly. Throws on timeout/refused/unreachable. */
+    dialDirect(peerId: string | undefined, addrs: string[], timeoutMs: number): Promise<void>;
+    /** Dial the counterparty via the relay circuit address. Throws on failure. */
+    dialRelay(relayCircuitAddr: string, peerId: string | undefined): Promise<void>;
+    /**
+     * The relay circuit address for this assignment. Sourced from the daemon's relay
+     * registry (populated during directory connection) — NOT parsed from the
+     * assignment's address fields, and available regardless of transport_mode (AC-006).
+     */
+    relayCircuitAddr(assignment: SessionAssignment): string;
+    /** Attempt a dcutr hole-punch upgrade. Throws on failure (non-fatal — SI-003). */
+    attemptDcutr(peerId: string | undefined): Promise<void>;
+}
+export declare class TransportSelector implements ITransportSelector {
+    #private;
+    constructor(opts: {
+        dialer: TransportDialer;
+        logger: Logger;
+        directDialTimeoutMs?: number;
+    });
+    dial(assignment: SessionAssignment, opts: TransportDialOptions): Promise<TransportResult>;
+}
+/**
+ * In-process transport selector stub. Returns a configurable canned result with
+ * no network access. Selected by the composition root when CELLO_ENV is
+ * 'local' | 'test', so the daemon's session establishment path is wired and does
+ * not crash with "adapter not wired" (AC-010). Defaults to a successful relay
+ * selection (the conservative, always-available transport).
+ */
+export declare class LocalTransportSelectorStub implements ITransportSelector {
+    #private;
+    constructor(result?: TransportResult);
+    dial(_assignment: SessionAssignment, _opts: TransportDialOptions): Promise<TransportResult>;
+    /** Test/composition driver: set the canned result. */
+    setResult(result: TransportResult): void;
+}
+export type AdvertisedAddress = {
+    kind: "direct";
+    addr: string;
+} | {
+    kind: "relay";
+    addr: string;
+};
+/**
+ * Decide what address a node advertises in its SessionAssignment negotiation,
+ * given its AutoNAT dialability and its relay circuit address.
+ *
+ * dialable with a publicAddr → advertise the direct address (transport_mode will
+ * be 'direct'). Otherwise (behind NAT, or AutoNAT unavailable because the
+ * directory is reconnecting) → advertise the relay circuit address (conservative
+ * fallback; transport_mode will be 'relay'). This decision is made once at
+ * session establishment and is immutable for that session (AC-019).
+ */
+export declare function selectAdvertisedAddress(dialability: Dialability, relayCircuitAddr: string): AdvertisedAddress;
+//# sourceMappingURL=transport-selector.d.ts.map

package/dist/transport-selector.d.ts.map

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

package/dist/transport-selector.js

@@ -0,0 +1,196 @@
+/**
+ * CELLO Daemon — transport-selector.ts (CELLO-M7-TRANSPORT-001)
+ *
+ * Direct-P2P-by-default transport selection with relay fallback and a best-effort
+ * dcutr hole-punch upgrade.
+ *
+ * ─── Specification (Phase S) ──────────────────────────────────────────────────
+ * Given a FROST-signed SessionAssignment (produced by WIRE-001), choose how to
+ * dial the counterparty's session node:
+ *   1. Read transport_mode from the assignment. This is the ONLY authority for
+ *      the dial strategy (SI-001 / AC-015) — NEVER infer mode from address format.
+ *   2. transport_mode === 'direct' → dial counterparty_session_addrs directly.
+ *   3. direct dial fails OR transport_mode === 'relay' → dial the relay circuit
+ *      address (from the daemon's relay registry, independent of transport_mode —
+ *      AC-006).
+ *   4. After a relay connection is established → attempt a dcutr hole-punch upgrade
+ *      (non-blocking, best-effort). Failure is non-fatal (SI-003).
+ *   5. If BOTH direct and relay fail → terminal 'relay_fallback_also_failed' (AC-008).
+ *
+ * Error code registry (fixed strings — also in CONTEXT.md):
+ *   'autonat_unavailable'                       — internal; no probers reachable.
+ *   'direct_dial_failed_falling_back_to_relay'  — WARN; intermediate, non-fatal.
+ *   'relay_fallback_also_failed'                — terminal session failure.
+ *   'dcutr_upgrade_failed'                      — DEBUG; non-fatal.
+ *
+ * ─── Pseudocode (Phase P) ─────────────────────────────────────────────────────
+ * dial(assignment, { correlationId }):
+ *   mode = assignment.transport_mode            // authoritative
+ *   sessionId = hex(assignment.session_id)
+ *   peerId = assignment.counterparty_session_peer_id
+ *   directAddrs = assignment.counterparty_session_addrs ?? []
+ *   if mode === 'direct':
+ *     try { dialer.dialDirect(peerId, directAddrs); log mode.selected('direct'); return {ok, 'direct'} }
+ *     catch e { log direct_dial.failed(WARN, e.message) }   // fall through
+ *   try { dialer.dialRelay(dialer.relayCircuitAddr(assignment), peerId) }
+ *   catch { return {ok:false, 'relay_fallback_also_failed', guidance} }   // NO mode.selected
+ *   log mode.selected('relay')
+ *   dcutrSettled = (async () => {
+ *     try { dialer.attemptDcutr(peerId); log dcutr.upgraded(INFO); return true }
+ *     catch e { log dcutr.failed(DEBUG, e.message); return false } })()
+ *   return {ok:true, 'relay', dcutrSettled}             // dial does NOT await dcutr
+ */
+import { extractErrorMessage } from "./error-message.js";
+// ─── Error codes (fixed) ──────────────────────────────────────────────────────
+export const TRANSPORT_ERROR = {
+    /** Internal: AutoNAT could not run because no directory-node probers are reachable. */
+    AUTONAT_UNAVAILABLE: "autonat_unavailable",
+    /** WARN-level intermediate, non-fatal: direct dial failed, relay fallback initiated. */
+    DIRECT_DIAL_FAILED_FALLING_BACK: "direct_dial_failed_falling_back_to_relay",
+    /** Terminal: both direct dial and relay fallback failed. */
+    RELAY_FALLBACK_ALSO_FAILED: "relay_fallback_also_failed",
+    /** DEBUG-level non-fatal: dcutr hole-punch upgrade attempt failed. */
+    DCUTR_UPGRADE_FAILED: "dcutr_upgrade_failed",
+};
+const RELAY_FALLBACK_GUIDANCE = "Both direct P2P connection and relay fallback failed. The counterparty may be " +
+    "offline or unreachable from any path. Try again later, or check network connectivity.";
+/** Default direct-dial timeout (ms). Not a user-facing option (implementation_notes). */
+export const DEFAULT_DIRECT_DIAL_TIMEOUT_MS = 5000;
+// ─── Helpers ──────────────────────────────────────────────────────────────────
+function sessionIdHex(assignment) {
+    return Buffer.from(assignment.session_id).toString("hex");
+}
+function errMessage(err) {
+    return extractErrorMessage(err);
+}
+// ─── TransportSelector (real) ─────────────────────────────────────────────────
+export class TransportSelector {
+    #dialer;
+    #logger;
+    #directDialTimeoutMs;
+    constructor(opts) {
+        this.#dialer = opts.dialer;
+        this.#logger = opts.logger;
+        this.#directDialTimeoutMs = opts.directDialTimeoutMs ?? DEFAULT_DIRECT_DIAL_TIMEOUT_MS;
+    }
+    async dial(assignment, opts) {
+        const sessionId = sessionIdHex(assignment);
+        const { correlationId } = opts;
+        const peerId = assignment.counterparty_session_peer_id;
+        const directAddrs = assignment.counterparty_session_addrs ?? [];
+        // transport_mode is the ONLY authority (SI-001 / AC-015). Never inferred.
+        const mode = assignment.transport_mode;
+        // Step 1: direct dial when transport_mode === 'direct'.
+        if (mode === "direct") {
+            try {
+                await this.#dialer.dialDirect(peerId, directAddrs, this.#directDialTimeoutMs);
+                this.#logger.info("session.transport.mode.selected", {
+                    sessionId,
+                    mode: "direct",
+                    correlationId,
+                });
+                return { ok: true, mode: "direct" };
+            }
+            catch (err) {
+                // Recoverable: log WARN and fall through to relay fallback (AC-006).
+                // failureReason is the actual error message — never ${error}.
+                this.#logger.warn("session.transport.direct_dial.failed", {
+                    sessionId,
+                    counterpartyPeerId: peerId,
+                    failureReason: errMessage(err),
+                    reason: TRANSPORT_ERROR.DIRECT_DIAL_FAILED_FALLING_BACK,
+                    correlationId,
+                });
+            }
+        }
+        // Step 2: relay fallback (transport_mode === 'relay', or direct dial failed).
+        try {
+            const relayAddr = this.#dialer.relayCircuitAddr(assignment);
+            await this.#dialer.dialRelay(relayAddr, peerId);
+        }
+        catch (err) {
+            // Terminal: both direct and relay failed. session.transport.mode.selected is
+            // NOT logged (no mode was selected — AC-008). We DO log the underlying relay
+            // failure reason at WARN so the on-call engineer can diagnose why the
+            // fallback failed (never swallow the exception silently).
+            this.#logger.warn("session.transport.relay_fallback.failed", {
+                sessionId,
+                counterpartyPeerId: peerId,
+                failureReason: errMessage(err),
+                reason: TRANSPORT_ERROR.RELAY_FALLBACK_ALSO_FAILED,
+                correlationId,
+            });
+            return {
+                ok: false,
+                reason: TRANSPORT_ERROR.RELAY_FALLBACK_ALSO_FAILED,
+                guidance: RELAY_FALLBACK_GUIDANCE,
+            };
+        }
+        this.#logger.info("session.transport.mode.selected", {
+            sessionId,
+            mode: "relay",
+            correlationId,
+        });
+        // Step 3: best-effort dcutr upgrade — non-blocking. The session is usable
+        // immediately upon relay connection (AC-007); dcutr runs in the background.
+        const dcutrSettled = this.#attemptDcutr(peerId, sessionId, correlationId);
+        return { ok: true, mode: "relay", dcutrSettled };
+    }
+    async #attemptDcutr(peerId, sessionId, correlationId) {
+        try {
+            await this.#dialer.attemptDcutr(peerId);
+            this.#logger.info("session.transport.dcutr.upgraded", { sessionId, correlationId });
+            return true;
+        }
+        catch (err) {
+            // Non-fatal (SI-003). DEBUG because dcutr failure is expected in many
+            // network topologies. failureReason is error.message — never ${error}.
+            this.#logger.debug("session.transport.dcutr.failed", {
+                sessionId,
+                failureReason: errMessage(err),
+                reason: TRANSPORT_ERROR.DCUTR_UPGRADE_FAILED,
+                correlationId,
+            });
+            return false;
+        }
+    }
+}
+// ─── LocalTransportSelectorStub ───────────────────────────────────────────────
+/**
+ * In-process transport selector stub. Returns a configurable canned result with
+ * no network access. Selected by the composition root when CELLO_ENV is
+ * 'local' | 'test', so the daemon's session establishment path is wired and does
+ * not crash with "adapter not wired" (AC-010). Defaults to a successful relay
+ * selection (the conservative, always-available transport).
+ */
+export class LocalTransportSelectorStub {
+    #result;
+    constructor(result) {
+        this.#result =
+            result ?? { ok: true, mode: "relay", dcutrSettled: Promise.resolve(false) };
+    }
+    async dial(_assignment, _opts) {
+        return this.#result;
+    }
+    /** Test/composition driver: set the canned result. */
+    setResult(result) {
+        this.#result = result;
+    }
+}
+/**
+ * Decide what address a node advertises in its SessionAssignment negotiation,
+ * given its AutoNAT dialability and its relay circuit address.
+ *
+ * dialable with a publicAddr → advertise the direct address (transport_mode will
+ * be 'direct'). Otherwise (behind NAT, or AutoNAT unavailable because the
+ * directory is reconnecting) → advertise the relay circuit address (conservative
+ * fallback; transport_mode will be 'relay'). This decision is made once at
+ * session establishment and is immutable for that session (AC-019).
+ */
+export function selectAdvertisedAddress(dialability, relayCircuitAddr) {
+    if (dialability.dialable && dialability.publicAddr) {
+        return { kind: "direct", addr: dialability.publicAddr };
+    }
+    return { kind: "relay", addr: relayCircuitAddr };
+}
+//# sourceMappingURL=transport-selector.js.map

package/dist/transport-selector.js.map

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

package/dist/trust-signal-pickup-listener.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Registering the trust-signal pickup handler on a signaling stream — the ONE place it happens.
+ *
+ * ─── WHY THIS IS A SHARED REGISTRAR AND NOT AN INLINE `registerInboundHandler` ─────────────────
+ *
+ * A directory drains its pickup queue down ANY stream that authenticates, and the daemon opens two
+ * kinds: the agent's own per-agent manager, and a transient VISITING connection to another node
+ * when a counterparty lives there. The handler was registered only on the first, so a visited node
+ * pushed its pickups and the daemon dropped every frame — re-sent and re-dropped on every visit,
+ * silently, while the operator's wallet read "No trust signals in wallet".
+ *
+ * `outbound-sessions.ts` already states the rule in its own header — "Anything a home stream must
+ * handle, a visiting stream must handle too" — and `registerSealListeners` exists precisely because
+ * the seal frames hit this failure first, and the fix there was to make them "a single bundle and
+ * not three separate registrations". This is the same shape for the same reason: an inline
+ * registration is a thing the next connection type will forget.
+ */
+import type { SignalingManager } from "@cello-protocol/transport";
+import type { KeyProvider } from "@cello-protocol/crypto";
+/** What `createInboundSessions` supplies: open the seal, verify, store, then ACK. */
+export type TrustSignalPickupHandler = (frame: Record<string, unknown>, agentKeyProvider: KeyProvider, signaling: SignalingManager, agentName: string, 
+/** "home", or the node id of the visited directory whose drain sent this. */
+origin?: string) => Promise<void>;
+/**
+ * Registers the listener and hands back a way to wait for whatever it is still doing.
+ *
+ * `origin` names the stream so the pickup logs can tell a home arrival from a visited node's drain.
+ * Until there was more than one stream type that was unambiguous; now the same five log events fire
+ * from two places and nothing said which, which is also the data the fan-out's "collected from node
+ * X" reporting will need.
+ */
+export type PickupListenerRegistrar = (signaling: SignalingManager, agentName: string, agentKeyProvider: KeyProvider, origin: string) => {
+    settle: (timeoutMs: number) => Promise<void>;
+};
+/**
+ * Build the registrar.
+ *
+ * `getHandler` is resolved at FRAME time, not at registration time: the daemon builds its signaling
+ * wiring before the inbound-session handlers exist, so capturing the handler when the listener is
+ * registered would bind whatever was there at boot — which for this frame type is nothing.
+ */
+export declare function createPickupListenerRegistrar(getHandler: () => TrustSignalPickupHandler): PickupListenerRegistrar;
+//# sourceMappingURL=trust-signal-pickup-listener.d.ts.map

package/dist/trust-signal-pickup-listener.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"trust-signal-pickup-listener.d.ts","sourceRoot":"","sources":["../src/trust-signal-pickup-listener.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AACH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,2BAA2B,CAAC;AAClE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,wBAAwB,CAAC;AAE1D,qFAAqF;AACrF,MAAM,MAAM,wBAAwB,GAAG,CACrC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC9B,gBAAgB,EAAE,WAAW,EAC7B,SAAS,EAAE,gBAAgB,EAC3B,SAAS,EAAE,MAAM;AACjB,6EAA6E;AAC7E,MAAM,CAAC,EAAE,MAAM,KACZ,OAAO,CAAC,IAAI,CAAC,CAAC;AAEnB;;;;;;;GAOG;AACH,MAAM,MAAM,uBAAuB,GAAG,CACpC,SAAS,EAAE,gBAAgB,EAC3B,SAAS,EAAE,MAAM,EACjB,gBAAgB,EAAE,WAAW,EAC7B,MAAM,EAAE,MAAM,KACX;IAAE,MAAM,EAAE,CAAC,SAAS,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAA;CAAE,CAAC;AAEtD;;;;;;GAMG;AACH,wBAAgB,6BAA6B,CAC3C,UAAU,EAAE,MAAM,wBAAwB,GACzC,uBAAuB,CAqCzB"}

package/dist/trust-signal-pickup-listener.js

@@ -0,0 +1,48 @@
+/**
+ * Build the registrar.
+ *
+ * `getHandler` is resolved at FRAME time, not at registration time: the daemon builds its signaling
+ * wiring before the inbound-session handlers exist, so capturing the handler when the listener is
+ * registered would bind whatever was there at boot — which for this frame type is nothing.
+ */
+export function createPickupListenerRegistrar(getHandler) {
+    return (signaling, agentName, agentKeyProvider, origin) => {
+        // WHY IN-FLIGHT WORK IS TRACKED RATHER THAN FLOATED AND FORGOTTEN.
+        //
+        // A visiting connection is transient: `openVisitingConnection`'s caller stops it the moment the
+        // session handoff finishes. The handler is asynchronous — it opens the seal, decodes, writes to
+        // the wallet, and only THEN acks — so a teardown can win the race and the ACK never lands. The
+        // signal itself is safe (the wallet write already happened and is content-addressed), but the
+        // directory keeps the row and re-sends the same pickup on every future visit, and the log names
+        // the failed send rather than the teardown that caused it.
+        //
+        // It also matters for what comes next: the fan-out closes each visiting connection on a terminal
+        // end-of-drain frame or a bounded ceiling, and a ceiling that fires mid-handler would truncate
+        // the drain the terminal frame exists to complete. Tracked here so that comes for free.
+        const inFlight = new Set();
+        signaling.registerInboundHandler((frame) => {
+            if (frame["type"] !== "trust_signal_pickup")
+                return;
+            // `signaling` is the stream the frame ARRIVED on, and that is what the handler ACKs down.
+            // Acking a visiting node's pickup down the home stream would leave the visited node's row
+            // unacked forever — re-sent on every visit, which is this bug wearing a different hat.
+            const p = getHandler()(frame, agentKeyProvider, signaling, agentName, origin)
+                .catch(() => { })
+                .finally(() => { inFlight.delete(p); });
+            inFlight.add(p);
+        });
+        return {
+            settle: async (timeoutMs) => {
+                if (inFlight.size === 0)
+                    return;
+                // BOUNDED. A handler wedged on a slow database must delay a teardown, never prevent one —
+                // an unbounded wait here would turn a stuck pickup into a stuck session close.
+                await Promise.race([
+                    Promise.allSettled([...inFlight]),
+                    new Promise((r) => setTimeout(r, timeoutMs)),
+                ]);
+            },
+        };
+    };
+}
+//# sourceMappingURL=trust-signal-pickup-listener.js.map

package/dist/trust-signal-pickup-listener.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"trust-signal-pickup-listener.js","sourceRoot":"","sources":["../src/trust-signal-pickup-listener.ts"],"names":[],"mappings":"AA6CA;;;;;;GAMG;AACH,MAAM,UAAU,6BAA6B,CAC3C,UAA0C;IAE1C,OAAO,CAAC,SAAS,EAAE,SAAS,EAAE,gBAAgB,EAAE,MAAM,EAAE,EAAE;QACxD,mEAAmE;QACnE,EAAE;QACF,gGAAgG;QAChG,gGAAgG;QAChG,+FAA+F;QAC/F,8FAA8F;QAC9F,gGAAgG;QAChG,2DAA2D;QAC3D,EAAE;QACF,iGAAiG;QACjG,+FAA+F;QAC/F,wFAAwF;QACxF,MAAM,QAAQ,GAAG,IAAI,GAAG,EAAiB,CAAC;QAC1C,SAAS,CAAC,sBAAsB,CAAC,CAAC,KAAK,EAAE,EAAE;YACzC,IAAI,KAAK,CAAC,MAAM,CAAC,KAAK,qBAAqB;gBAAE,OAAO;YACpD,0FAA0F;YAC1F,0FAA0F;YAC1F,uFAAuF;YACvF,MAAM,CAAC,GAAG,UAAU,EAAE,CAAC,KAAgC,EAAE,gBAAgB,EAAE,SAAS,EAAE,SAAS,EAAE,MAAM,CAAC;iBACrG,KAAK,CAAC,GAAG,EAAE,GAAE,CAAC,CAAC;iBACf,OAAO,CAAC,GAAG,EAAE,GAAG,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;YAC1C,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;QAClB,CAAC,CAAC,CAAC;QACH,OAAO;YACL,MAAM,EAAE,KAAK,EAAE,SAAiB,EAAE,EAAE;gBAClC,IAAI,QAAQ,CAAC,IAAI,KAAK,CAAC;oBAAE,OAAO;gBAChC,0FAA0F;gBAC1F,+EAA+E;gBAC/E,MAAM,OAAO,CAAC,IAAI,CAAC;oBACjB,OAAO,CAAC,UAAU,CAAC,CAAC,GAAG,QAAQ,CAAC,CAAC;oBACjC,IAAI,OAAO,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,UAAU,CAAC,CAAC,EAAE,SAAS,CAAC,CAAC;iBAC7C,CAAC,CAAC;YACL,CAAC;SACF,CAAC;IACJ,CAAC,CAAC;AACJ,CAAC"}