@cello-protocol/daemon 0.0.227 → 0.0.229

package/dist/outbound-sessions.d.ts

@@ -0,0 +1,126 @@
+/**
+ * The OUTBOUND session path: discovery, the session request, and cross-node setup.
+ *
+ * DOD-SPINE-5. The initiator asks the directory to find the counterparty, requests a session, and —
+ * when the counterparty lives on a DIFFERENT directory node — opens a transient VISITING connection
+ * to that node to broker the handshake.
+ *
+ * The visiting connection is the subtle part, and it has already produced one serious bug: it is a
+ * fully authenticated stream, so the directory will drain its DURABLE notification queue down it.
+ * Anything a home stream must handle, a visiting stream must handle too (see registerSealListeners,
+ * which is why the seal listeners are a single bundle and not three separate registrations).
+ */
+import { SignalingManager, type CelloNode } from "@cello-protocol/transport";
+import type { KeyProvider } from "@cello-protocol/crypto";
+import type { PickupListenerRegistrar } from "./trust-signal-pickup-listener.js";
+import type { SessionNodeManager } from "./session-node-manager.js";
+import type { Logger } from "./types.js";
+import type { DirectoryEndpoint } from "./signaling-connect.js";
+import type { DbRegistrationPersistence } from "./db-identity-store.js";
+import type { ConsortiumEndpoint } from "./directory-bootstrap.js";
+import type { SessionNegotiator } from "./transport-selector.js";
+import { type DiscoveryOutcome } from "./cross-node-negotiation.js";
+import type { IDirectoryChallengeVerifier } from "@cello-protocol/transport";
+export interface OutboundSessionDeps {
+    logger: Logger;
+    sessionNodeManager: SessionNodeManager;
+    getKeyProvider: (agentName: string) => KeyProvider | undefined;
+    getPersistence: (agentName: string) => DbRegistrationPersistence;
+    getAgentSignaling: (agentName: string, keyProvider: KeyProvider, pubkeyHex: string) => {
+        signaling: SignalingManager;
+        getNode: () => CelloNode | null;
+    };
+    waitForSignalingConnected: (mgr: SignalingManager, timeoutMs: number) => Promise<boolean>;
+    getFailoverEndpoint: () => Promise<DirectoryEndpoint | null>;
+    resolveConsortiumRoster: () => Promise<ConsortiumEndpoint[] | null>;
+    /**
+     * DOD-M15-ERRSTRING-1 — the nodes whose bootstrap probe failed in the last sweep.
+     *
+     * Needed here because a SHORT ROSTER is the cause the DoD line asks these errors to name ("a
+     * roster below threshold says so"), and the negotiator otherwise sees only the reachable subset —
+     * it cannot tell three-of-three from three-of-five. Reachable + unresolved is the declared count,
+     * and majority(declared) is the threshold a ceremony needs.
+     */
+    getUnresolvedNodes?: () => ReadonlyArray<{
+        nodeId: string;
+        reason: string;
+    }>;
+    /**
+     * How many nodes the VERIFIED MANIFEST declares. Review MEDIUM-2: deriving this as
+     * `reachable + unresolved` undercounts, because a node dropped for an invalid endpoint or a
+     * peer-id mismatch appears in neither term — and the note would then affirm that ceremonies can
+     * complete when the true threshold is unmet.
+     */
+    getDeclaredNodeCount?: () => number | null;
+    /**
+     * 048-SWEEPTICK: which agents are ONLINE, read fresh on every tick.
+     *
+     * A getter over the live set rather than a value, because the set is built in the composition
+     * root AFTER this factory is called — and because the answer changes while the tick is running,
+     * which is the whole reason it is asked per tick rather than once.
+     *
+     * REQUIRED. It was optional with an "assume online" default, and review was right that the
+     * default pointed the wrong way: absent would have meant "sweep for everyone", while this dep's
+     * whole purpose is that collecting for an agent the operator switched off is the kill switch
+     * failing to switch something off. A future second composition root must not be able to omit it
+     * quietly.
+     */
+    getOnlineAgents: () => ReadonlySet<string>;
+    /**
+     * DOD-M15-SEALPARTIES-1: where a dead seal ceremony leaves its mark. A VISITING stream runs the
+     * seal ceremony too (the cross-node close), so it needs the same sink as a home stream — a
+     * refusal recorded on only one of the two paths is a refusal an operator meets at random.
+     */
+    recordSealFailure: (agentName: string, sessionId: string, reason: string, kind: "unresolved" | "refused") => void;
+    /** The WHOLE seal listener bundle — a visiting stream needs every one of them. */
+    registerSealListeners: (signaling: SignalingManager, agentName: string, agentPubkeyHex: string) => () => void;
+    /**
+     * 043-SIGNALDELIVERY C. Same bundle-not-inline reasoning as registerSealListeners, and the same
+     * bug: a frame type handled only on the home stream is a frame type the visiting stream drops.
+     */
+    registerPickupListener: PickupListenerRegistrar;
+    sessionNegotiator?: SessionNegotiator;
+    /** Step-6 directory identity proof (undefined on the in-process test path). */
+    challengeVerifier?: IDirectoryChallengeVerifier;
+    getManifestVersion: () => number;
+    /** The agents loaded from the encrypted store at boot. */
+    loadedAgents: ReadonlyArray<{
+        name: string;
+        pubkey: string;
+    }>;
+}
+/**
+ * How long a session initiation waits for signaling before giving up.
+ *
+ * EXPORTED because it is a CONSTRAINT ON SOMETHING ELSE, not just a local number: every probe
+ * budget on the reconnect path has to fit inside it. `DOD-M15-BOOTSTRAP-1` learned that the hard
+ * way — a retry budget chosen in isolation pushed the resolver past this wait and would have made
+ * `cello_initiate_session` fail on exactly the lossy links the retry was added to help.
+ *
+ * `dod-m15-bootstrap-1.test.ts` asserts the budgets against this value, so changing it here breaks
+ * that test rather than silently breaking the behaviour.
+ */
+export declare const SIGNALING_CONNECT_WAIT_MS = 10000;
+export declare function createOutboundSessions(deps: OutboundSessionDeps): {
+    openVisitingConnection: (agentName: string, agentKeyProvider: import("@cello-protocol/crypto").KeyProvider, agentPubkeyHex: string, endpoint: DirectoryEndpoint, correlationId: string, nodeId: string) => {
+        mgr: SignalingManager;
+        stop: (reason: string) => Promise<void>;
+    };
+    crossNodeBrokerBySession: Map<string, string>;
+    resolvedSessionNegotiator: SessionNegotiator;
+    runDiscoveryLookup: (signaling: SignalingManager, targetHex: string, timeoutMs: number, correlationId: string) => Promise<DiscoveryOutcome>;
+    /**
+     * 048-SWEEPTICK: the ONLY sweep that escapes this module, and deliberately so. It sweeps
+     * immediately on connect — the 043 C2 behaviour, unchanged — and arms the five-minute tick that
+     * covers a connection which never drops.
+     *
+     * The bare `sweepTrustSignals` used to be exported beside this "for anything that wants one
+     * collection without arming a timer". Nothing wanted one, and its only live effect was to keep
+     * the exact revert this unit exists to prevent — wiring the un-ticked sweep into
+     * `getSweepTrustSignals` — a one-word edit that a source-text guard then had to defend. Removing
+     * it makes that revert impossible to write rather than checked for.
+     */
+    sweepTrustSignalsAndTick: import("./trust-signal-sweep.js").TrustSignalSweep;
+    trustSignalSweepTicker: import("./trust-signal-sweep-tick.js").TrustSignalSweepTicker;
+};
+//# sourceMappingURL=outbound-sessions.d.ts.map

package/dist/outbound-sessions.d.ts.map

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