@cello-protocol/daemon 0.0.225 → 0.0.227

package/dist/transport-selector.d.ts

@@ -1,202 +0,0 @@
-/**
- * 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

@@ -1 +0,0 @@
-{"version":3,"file":"transport-selector.d.ts","sourceRoot":"","sources":["../src/transport-selector.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyCG;AAEH,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,gCAAgC,CAAC;AACxE,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,YAAY,CAAC;AACzC,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,2BAA2B,CAAC;AAK7D,eAAO,MAAM,eAAe;IAC1B,uFAAuF;;IAEvF,wFAAwF;;IAExF,4DAA4D;;IAE5D,sEAAsE;;CAE9D,CAAC;AAMX,yFAAyF;AACzF,eAAO,MAAM,8BAA8B,OAAO,CAAC;AAInD;;;;;;;;;GASG;AACH,MAAM,MAAM,eAAe,GACvB;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,IAAI,EAAE,QAAQ,CAAA;CAAE,GAC5B;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,IAAI,EAAE,OAAO,CAAC;IAAC,YAAY,EAAE,OAAO,CAAC,OAAO,CAAC,CAAA;CAAE,GAC3D;IACE,EAAE,EAAE,KAAK,CAAC;IACV,MAAM,EAAE,OAAO,eAAe,CAAC,0BAA0B,CAAC;IAC1D,QAAQ,EAAE,MAAM,CAAC;CAClB,CAAC;AAEN,MAAM,WAAW,oBAAoB;IACnC,yEAAyE;IACzE,aAAa,EAAE,MAAM,CAAC;CACvB;AAID;;;;;GAKG;AACH,MAAM,WAAW,kBAAkB;IACjC,IAAI,CAAC,UAAU,EAAE,iBAAiB,EAAE,IAAI,EAAE,oBAAoB,GAAG,OAAO,CAAC,eAAe,CAAC,CAAC;CAC3F;AAID;;;;GAIG;AACH,MAAM,WAAW,yBAAyB;IACxC,SAAS,EAAE,MAAM,CAAC;IAClB,aAAa,EAAE,MAAM,CAAC;IACtB,iBAAiB,EAAE,iBAAiB,CAAC;IACrC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACjC;AAED;;;;GAIG;AACH,MAAM,MAAM,wBAAwB,GAChC;IACE,EAAE,EAAE,IAAI,CAAC;IACT,UAAU,EAAE,iBAAiB,CAAC;IAC9B;;;;;;;;;;;OAWG;IACH,sBAAsB,EAAE,MAAM,CAAC;CAChC,GACD;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,CAAC;AAEpD;;;;;;;;GAQG;AACH,MAAM,WAAW,iBAAiB;IAChC,SAAS,CAAC,GAAG,EAAE,yBAAyB,GAAG,OAAO,CAAC,wBAAwB,CAAC,CAAC;CAC9E;AAID;;;;GAIG;AACH,MAAM,WAAW,eAAe;IAC9B,6EAA6E;IAC7E,UAAU,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,EAAE,KAAK,EAAE,MAAM,EAAE,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC1F,8EAA8E;IAC9E,SAAS,CAAC,gBAAgB,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,SAAS,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC/E;;;;OAIG;IACH,gBAAgB,CAAC,UAAU,EAAE,iBAAiB,GAAG,MAAM,CAAC;IACxD,kFAAkF;IAClF,YAAY,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACzD;AAcD,qBAAa,iBAAkB,YAAW,kBAAkB;;gBAK9C,IAAI,EAAE;QAChB,MAAM,EAAE,eAAe,CAAC;QACxB,MAAM,EAAE,MAAM,CAAC;QACf,mBAAmB,CAAC,EAAE,MAAM,CAAC;KAC9B;IAMK,IAAI,CACR,UAAU,EAAE,iBAAiB,EAC7B,IAAI,EAAE,oBAAoB,GACzB,OAAO,CAAC,eAAe,CAAC;CAwF5B;AAID;;;;;;GAMG;AACH,qBAAa,0BAA2B,YAAW,kBAAkB;;gBAGvD,MAAM,CAAC,EAAE,eAAe;IAK9B,IAAI,CAAC,WAAW,EAAE,iBAAiB,EAAE,KAAK,EAAE,oBAAoB,GAAG,OAAO,CAAC,eAAe,CAAC;IAIjG,sDAAsD;IACtD,SAAS,CAAC,MAAM,EAAE,eAAe,GAAG,IAAI;CAGzC;AAID,MAAM,MAAM,iBAAiB,GACzB;IAAE,IAAI,EAAE,QAAQ,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GAChC;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC;AAEpC;;;;;;;;;GASG;AACH,wBAAgB,uBAAuB,CACrC,WAAW,EAAE,WAAW,EACxB,gBAAgB,EAAE,MAAM,GACvB,iBAAiB,CAKnB"}

package/dist/transport-selector.js

@@ -1,196 +0,0 @@
-/**
- * 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

@@ -1 +0,0 @@
-{"version":3,"file":"transport-selector.js","sourceRoot":"","sources":["../src/transport-selector.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyCG;AAKH,OAAO,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAC;AAEzD,iFAAiF;AAEjF,MAAM,CAAC,MAAM,eAAe,GAAG;IAC7B,uFAAuF;IACvF,mBAAmB,EAAE,qBAAqB;IAC1C,wFAAwF;IACxF,+BAA+B,EAAE,0CAA0C;IAC3E,4DAA4D;IAC5D,0BAA0B,EAAE,4BAA4B;IACxD,sEAAsE;IACtE,oBAAoB,EAAE,sBAAsB;CACpC,CAAC;AAEX,MAAM,uBAAuB,GAC3B,gFAAgF;IAChF,uFAAuF,CAAC;AAE1F,yFAAyF;AACzF,MAAM,CAAC,MAAM,8BAA8B,GAAG,IAAI,CAAC;AAkHnD,iFAAiF;AAEjF,SAAS,YAAY,CAAC,UAA6B;IACjD,OAAO,MAAM,CAAC,IAAI,CAAC,UAAU,CAAC,UAAU,CAAC,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC;AAC5D,CAAC;AAED,SAAS,UAAU,CAAC,GAAY;IAC9B,OAAO,mBAAmB,CAAC,GAAG,CAAC,CAAC;AAClC,CAAC;AAED,iFAAiF;AAEjF,MAAM,OAAO,iBAAiB;IACnB,OAAO,CAAkB;IACzB,OAAO,CAAS;IAChB,oBAAoB,CAAS;IAEtC,YAAY,IAIX;QACC,IAAI,CAAC,OAAO,GAAG,IAAI,CAAC,MAAM,CAAC;QAC3B,IAAI,CAAC,OAAO,GAAG,IAAI,CAAC,MAAM,CAAC;QAC3B,IAAI,CAAC,oBAAoB,GAAG,IAAI,CAAC,mBAAmB,IAAI,8BAA8B,CAAC;IACzF,CAAC;IAED,KAAK,CAAC,IAAI,CACR,UAA6B,EAC7B,IAA0B;QAE1B,MAAM,SAAS,GAAG,YAAY,CAAC,UAAU,CAAC,CAAC;QAC3C,MAAM,EAAE,aAAa,EAAE,GAAG,IAAI,CAAC;QAC/B,MAAM,MAAM,GAAG,UAAU,CAAC,4BAA4B,CAAC;QACvD,MAAM,WAAW,GAAG,UAAU,CAAC,0BAA0B,IAAI,EAAE,CAAC;QAChE,0EAA0E;QAC1E,MAAM,IAAI,GAAG,UAAU,CAAC,cAAc,CAAC;QAEvC,wDAAwD;QACxD,IAAI,IAAI,KAAK,QAAQ,EAAE,CAAC;YACtB,IAAI,CAAC;gBACH,MAAM,IAAI,CAAC,OAAO,CAAC,UAAU,CAAC,MAAM,EAAE,WAAW,EAAE,IAAI,CAAC,oBAAoB,CAAC,CAAC;gBAC9E,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,iCAAiC,EAAE;oBACnD,SAAS;oBACT,IAAI,EAAE,QAAQ;oBACd,aAAa;iBACd,CAAC,CAAC;gBACH,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,QAAQ,EAAE,CAAC;YACtC,CAAC;YAAC,OAAO,GAAG,EAAE,CAAC;gBACb,qEAAqE;gBACrE,8DAA8D;gBAC9D,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,sCAAsC,EAAE;oBACxD,SAAS;oBACT,kBAAkB,EAAE,MAAM;oBAC1B,aAAa,EAAE,UAAU,CAAC,GAAG,CAAC;oBAC9B,MAAM,EAAE,eAAe,CAAC,+BAA+B;oBACvD,aAAa;iBACd,CAAC,CAAC;YACL,CAAC;QACH,CAAC;QAED,8EAA8E;QAC9E,IAAI,CAAC;YACH,MAAM,SAAS,GAAG,IAAI,CAAC,OAAO,CAAC,gBAAgB,CAAC,UAAU,CAAC,CAAC;YAC5D,MAAM,IAAI,CAAC,OAAO,CAAC,SAAS,CAAC,SAAS,EAAE,MAAM,CAAC,CAAC;QAClD,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,6EAA6E;YAC7E,6EAA6E;YAC7E,sEAAsE;YACtE,0DAA0D;YAC1D,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,yCAAyC,EAAE;gBAC3D,SAAS;gBACT,kBAAkB,EAAE,MAAM;gBAC1B,aAAa,EAAE,UAAU,CAAC,GAAG,CAAC;gBAC9B,MAAM,EAAE,eAAe,CAAC,0BAA0B;gBAClD,aAAa;aACd,CAAC,CAAC;YACH,OAAO;gBACL,EAAE,EAAE,KAAK;gBACT,MAAM,EAAE,eAAe,CAAC,0BAA0B;gBAClD,QAAQ,EAAE,uBAAuB;aAClC,CAAC;QACJ,CAAC;QAED,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,iCAAiC,EAAE;YACnD,SAAS;YACT,IAAI,EAAE,OAAO;YACb,aAAa;SACd,CAAC,CAAC;QAEH,0EAA0E;QAC1E,4EAA4E;QAC5E,MAAM,YAAY,GAAG,IAAI,CAAC,aAAa,CAAC,MAAM,EAAE,SAAS,EAAE,aAAa,CAAC,CAAC;QAE1E,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,OAAO,EAAE,YAAY,EAAE,CAAC;IACnD,CAAC;IAED,KAAK,CAAC,aAAa,CACjB,MAA0B,EAC1B,SAAiB,EACjB,aAAqB;QAErB,IAAI,CAAC;YACH,MAAM,IAAI,CAAC,OAAO,CAAC,YAAY,CAAC,MAAM,CAAC,CAAC;YACxC,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,kCAAkC,EAAE,EAAE,SAAS,EAAE,aAAa,EAAE,CAAC,CAAC;YACpF,OAAO,IAAI,CAAC;QACd,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,sEAAsE;YACtE,uEAAuE;YACvE,IAAI,CAAC,OAAO,CAAC,KAAK,CAAC,gCAAgC,EAAE;gBACnD,SAAS;gBACT,aAAa,EAAE,UAAU,CAAC,GAAG,CAAC;gBAC9B,MAAM,EAAE,eAAe,CAAC,oBAAoB;gBAC5C,aAAa;aACd,CAAC,CAAC;YACH,OAAO,KAAK,CAAC;QACf,CAAC;IACH,CAAC;CACF;AAED,iFAAiF;AAEjF;;;;;;GAMG;AACH,MAAM,OAAO,0BAA0B;IACrC,OAAO,CAAkB;IAEzB,YAAY,MAAwB;QAClC,IAAI,CAAC,OAAO;YACV,MAAM,IAAI,EAAE,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,OAAO,EAAE,YAAY,EAAE,OAAO,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;IAChF,CAAC;IAED,KAAK,CAAC,IAAI,CAAC,WAA8B,EAAE,KAA2B;QACpE,OAAO,IAAI,CAAC,OAAO,CAAC;IACtB,CAAC;IAED,sDAAsD;IACtD,SAAS,CAAC,MAAuB;QAC/B,IAAI,CAAC,OAAO,GAAG,MAAM,CAAC;IACxB,CAAC;CACF;AAQD;;;;;;;;;GASG;AACH,MAAM,UAAU,uBAAuB,CACrC,WAAwB,EACxB,gBAAwB;IAExB,IAAI,WAAW,CAAC,QAAQ,IAAI,WAAW,CAAC,UAAU,EAAE,CAAC;QACnD,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,IAAI,EAAE,WAAW,CAAC,UAAU,EAAE,CAAC;IAC1D,CAAC;IACD,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,IAAI,EAAE,gBAAgB,EAAE,CAAC;AACnD,CAAC"}

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

@@ -1,43 +0,0 @@
-/**
- * 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

@@ -1 +0,0 @@
-{"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

@@ -1,48 +0,0 @@
-/**
- * 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

@@ -1 +0,0 @@
-{"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"}