@rivalis/fleet 8.0.0

package/lib/main.d.ts

@@ -0,0 +1,592 @@
+import { Broadcast } from '@toolcase/base';
+import { Logger } from '@toolcase/logging';
+import { Rivalis, Client } from '@rivalis/core';
+import { EndpointError } from '@toolcase/node';
+
+/**
+ * Orchestrator configuration normalization and defaults (§9). Consumed by the
+ * Orchestrator (§9) and the CLI (§12).
+ *
+ * Scope note: this resolves option shapes and defaults and normalizes the
+ * `string | string[]` key surface for rotation (§13). The §13 *security* checks
+ * — key-strength enforcement, agent/admin audience separation, the production
+ * refuse-to-start rules — live in {@link enforceSecurityPolicy} below, called by
+ * the Orchestrator constructor: structural normalization and security hardening
+ * stay separate, but both have their home in this module.
+ */
+
+/**
+ * Public orchestrator option surface (§9). Lives next to its primary consumer
+ * (config resolution) rather than in the pure data model — it is consumer
+ * configuration, not a read-model type. Re-exported from `main.ts`.
+ */
+interface OrchestratorOptions {
+    /** Bind address (default 0.0.0.0). */
+    host?: string;
+    port: number;
+    /** Agent auth key(s) — agents connect with any listed key. */
+    agentKey: string | string[];
+    /** REST admin key(s) — required when `api: true`. */
+    adminKey?: string | string[];
+    /** Serve REST /v1 (default true). */
+    api?: boolean;
+    heartbeatMs?: number;
+    commandTimeoutMs?: number;
+    /** CORS allow-origins, or false (default) for same-origin only. */
+    cors?: false | {
+        origins: string[];
+    };
+    /** Allow `?key=` auth on /v1/events for browser EventSource (§10, §13). */
+    sseQueryAuth?: boolean;
+    /**
+     * Trust `X-Forwarded-For` from a front proxy (default `false`, §13). When a
+     * TLS-terminating reverse proxy / service mesh sits in front, enable this so the
+     * per-IP failed-auth throttle and audit logs key on the real client IP (`req.ip`,
+     * resolved from the forwarded header) instead of collapsing every client into the
+     * proxy's single socket address. Leave off for direct exposure — a spoofable
+     * header must not be trusted from an untrusted network.
+     */
+    trustProxy?: boolean;
+}
+
+/**
+ * Internal Rivalis Room (type `@rivalis/fleet`) that hosts connected agents as
+ * actors — the orchestrator dogfoods Rivalis for agent transport (§7). Each
+ * agent socket is an actor in this single room; the room binds the agent → orch
+ * reply topics (`fleet/state`, `fleet/ack`) and forwards every frame, join, and
+ * leave to the {@link FleetController} (the Orchestrator).
+ *
+ * `unknownTopicPolicy = 'kick'` (task 011): under strict orchestrator-driven
+ * request/reply, every agent frame must be a reply to an outstanding request — an
+ * unbound topic is an unsolicited frame and the agent is kicked. This supersedes
+ * the pre-011 `'drop'` forward-compat stance (a major bump now guards
+ * compatibility, §7). A frame on a *bound* reply topic still flows to the
+ * controller, which checks the correlation id and kicks if it matches no
+ * outstanding request.
+ *
+ * The class is produced by a **factory** rather than declared statically so that
+ * `@rivalis/core` is required lazily (the orchestrator loads core inside
+ * `listen()`; importing `@rivalis/fleet` must not eagerly drag core's ESM build
+ * in — mirrors `FleetAgent`'s lazy `loadCore`). The factory closes over the
+ * controller, so the room needs no per-instance wiring after construction.
+ */
+/**
+ * A connected agent as seen by the control plane — an abstraction over the
+ * core `Actor`. The orchestrator never touches `Actor`/`Room` directly; it sends
+ * JSON frames and closes wedged sockets through this seam, which also makes the
+ * control plane unit-testable without a live WebSocket (§15).
+ */
+interface AgentLink {
+    /** Connection-scoped instance id — the actor id assigned by core (§6). */
+    readonly instanceId: string;
+    /** Send a topic frame to this agent; payloads are binary-encoded (§7, task 005). */
+    send(topic: string, payload: unknown): void;
+    /** Kick the agent's socket (used to evict a wedged-but-connected instance, §7). */
+    close(): void;
+}
+/** What the FleetRoom forwards into the Orchestrator. Implemented by the Orchestrator. */
+interface FleetController {
+    handleAgentJoin(link: AgentLink): void;
+    handleAgentLeave(instanceId: string): void;
+    handleAgentMessage(instanceId: string, topic: string, payload: Uint8Array): void;
+}
+
+/**
+ * Pure fleet data model (§6) — the read-model rows surfaced over the library and
+ * REST APIs and the placement-request shape. No I/O, no wire-format concerns:
+ * the agent builds `fleet/state` payloads (see `../wire`) which the orchestrator
+ * validates into these `InstanceInfo`/`RoomInfo` rows.
+ */
+/** Lifecycle status of an instance (§6). The agent owns this value (§7). */
+type InstanceStatus = 'active' | 'draining';
+/** Resolved capacity declaration; `null` means "unlimited" for that dimension. */
+interface Capacity {
+    maxConnections: number | null;
+    maxRooms: number | null;
+}
+type PlacementStrategy = 'least-loaded' | 'most-loaded' | 'random';
+interface PlacementRequest {
+    /** Pin to a connection-scoped instance id (see §9 pinning caveat). */
+    instanceId?: string;
+    /** Pin to an instance by its stable process id. */
+    processUid?: string;
+    strategy?: PlacementStrategy;
+    /** Only instances matching all listed labels are candidates. */
+    labels?: Record<string, string>;
+    /** Pinning to a draining instance requires `force: true`. */
+    force?: boolean;
+}
+interface InstanceInfo {
+    id: string;
+    name: string;
+    processUid: string;
+    endpointUrl: string;
+    labels: Record<string, string>;
+    roomTypes: string[];
+    rooms: RoomInfo[];
+    connections: number;
+    capacity: Capacity;
+    autoCreate: boolean;
+    status: InstanceStatus;
+    lastSyncAt: number;
+    agentVersion: string;
+    protocolVersion: number;
+}
+interface RoomInfo {
+    id: string;
+    type: string;
+    connections: number;
+    instanceId: string;
+    endpointUrl: string;
+    local: boolean;
+}
+interface FleetStats {
+    instances: number;
+    rooms: number;
+    connections: number;
+    roomTypes: string[];
+    stateHash: string;
+}
+/** Stable, machine-readable error codes surfaced over REST (§10) and control APIs. */
+type FleetErrorCode = 'VALIDATION' | 'UNAUTHORIZED' | 'INSTANCE_NOT_FOUND' | 'ROOM_NOT_FOUND' | 'NO_CANDIDATE' | 'ROOM_EXISTS' | 'INSTANCE_DRAINING' | 'PAYLOAD_TOO_LARGE' | 'INSTANCE_BUSY' | 'AUTH_THROTTLED' | 'SSE_LIMIT' | 'COMMAND_FAILED' | 'INSTANCE_DISCONNECTED' | 'COMMAND_TIMEOUT';
+type FleetEventType = 'instance:join' | 'instance:leave' | 'instance:stale' | 'room:create' | 'room:destroy' | 'sync';
+interface FleetEvent {
+    type: FleetEventType;
+    data?: unknown;
+}
+
+/**
+ * The fleet's coded error hierarchy (task 004) — `FleetError extends
+ * EndpointError`, with the HTTP status carried **on the error class** instead of
+ * a side table in the REST router. The node-service blueprint puts domain errors
+ * here in `src/domain/errors.ts` and maps them with `errorMeta(e)`, so the router
+ * no longer owns a parallel `code → status` table that could drift from the throw
+ * sites (spec §10 codes are unchanged; only the mapping *mechanism* moves).
+ *
+ * ──────────────────────────────────────────────────────────────────────────────
+ * `@toolcase/node` adoption (task 006)
+ *
+ * `EndpointError`, `errorMeta`, and `isLibError` now come from **`@toolcase/node`**
+ * (the local port that stood in until task 006 — while `@toolcase/node` was not
+ * loadable here — is deleted). The package is listed in `tsup.config.ts`'s
+ * `external`, so the one `EndpointError` class identity is shared across every
+ * bundle: a {@link FleetError} thrown in the `FleetState`/`Orchestrator` bundle is
+ * recognized by the router bundle's `errorMeta` via `instanceof EndpointError`
+ * (the *base* is externalized; `FleetError` itself is still bundled per-entry, but
+ * the mapping checks the shared base, never `FleetError`). That is exactly the
+ * cross-bundle correctness the earlier structural port was working around.
+ * ──────────────────────────────────────────────────────────────────────────────
+ */
+
+/**
+ * Coded error surfaced by placement, the command engine, and REST validation
+ * (§9/§10). Extends `@toolcase/node`'s {@link EndpointError}, resolving its HTTP
+ * `statusCode` from the §10 table at construction — so `errorMeta` maps it (via
+ * `instanceof EndpointError`) without the router knowing the table. The public
+ * `code` contract (a {@link FleetErrorCode}) is the documented REST envelope `cause`
+ * (spec §10) and is unchanged.
+ */
+declare class FleetError extends EndpointError {
+    readonly code: FleetErrorCode;
+    constructor(code: FleetErrorCode, message: string);
+}
+
+/**
+ * Shared default timer scheduler (task 002). One definition of the `unref`-ing
+ * `setTimeout`/`setInterval` wrapper that the orchestrator and the agent each
+ * carried. `unref` so a lingering timer never pins the process.
+ *
+ * Typed as a structural superset — timeouts *and* intervals — so the single
+ * value satisfies both the orchestrator's timeouts-only `OrchestratorScheduler`
+ * seam and the agent's `AgentScheduler` (which also drives heartbeat/poll
+ * intervals). The injectable scheduler seams in each consumer are unchanged;
+ * tests still pass their own fakes.
+ */
+/**
+ * Timeouts-only timer seam shared by the orchestrator and every collaborator it
+ * injects ({@link CommandEngine}, {@link Poller}). One definition so the
+ * decomposed pieces (and their unit tests) take the same fake clock the
+ * Orchestrator does (§15).
+ */
+interface TimerScheduler {
+    setTimeout(fn: () => void, ms: number): unknown;
+    clearTimeout(handle: unknown): void;
+}
+
+/**
+ * Wire-protocol constants (§7) — protocol versioning, the in-flight command cap,
+ * and the topic name table exchanged between agent and orchestrator. Per-topic
+ * JSON payload shapes live in `./payloads`.
+ */
+/**
+ * Protocol MAJOR spoken by agent and orchestrator — a single integer (§7).
+ *
+ * Bumped 1 → 2 by task 005: the wire format changed from JSON to binary
+ * (`@toolcase/serializer`), a breaking change within the major.
+ *
+ * Bumped 2 → 3 by task 011: the protocol was inverted to strict
+ * orchestrator-driven request/reply. Agent push topics (`fleet/sync`,
+ * `fleet/ping`, `fleet/resync`, `fleet/status`, `fleet/status-ack`) are gone;
+ * the orchestrator now polls (`fleet/poll`) and the agent replies (`fleet/state`).
+ * A v2 (push) peer and a v3 (poll) peer cannot interoperate — both halves must be
+ * upgraded in lockstep. The 2-byte version header on every frame
+ * (`wire/serializer`) is what makes the mismatch fail loudly at `fleet/hello`.
+ */
+declare const PROTOCOL_VERSION = 3;
+
+/**
+ * Embeddable fleet orchestrator (§9) — the dogfooded control plane (§7). After the
+ * task-008 decomposition this is the **facade** wiring its collaborators, each a
+ * separately unit-tested concern: {@link AgentAuthenticator} (agent-key match),
+ * {@link CommandEngine} (pending commands + cap + settle), {@link Poller}
+ * (orchestrator-driven polling + missed-reply stale/evict, task 011),
+ * {@link EventReconciler} (read-model diffs → events), {@link FleetControl}
+ * (create/destroy/drain), and `transport.ts` (control-plane bootstrap). The
+ * Orchestrator retains config resolution, the `FleetApi` facade, poll dispatch +
+ * per-agent outstanding-request enforcement, and lifecycle (`listen`/`shutdown`).
+ *
+ * `listen()` is the only method that touches core / the network; constructing an
+ * Orchestrator loads no core, so the control plane is exercised directly in unit
+ * tests against the {@link AgentLink} seams and an injectable scheduler (§15).
+ */
+
+/** Minimal timer surface (timeouts only); tests inject a virtual-time fake (§15). */
+type OrchestratorScheduler = TimerScheduler;
+/** Test/advanced seams kept off the public option surface (§9). */
+interface OrchestratorInternals {
+    scheduler?: OrchestratorScheduler;
+    /** Wall clock for `lastSyncAt`; default `Date.now`. */
+    now?: () => number;
+    logger?: Logger;
+    /** `NODE_ENV` override for the §13 production refuse-to-start rules; default sourced from `src/env.ts`. */
+    env?: string;
+}
+/** Read-model + control surface exposed as `orchestrator.fleet` (§9). */
+interface FleetApi {
+    readonly stats: FleetStats;
+    readonly instances: InstanceInfo[];
+    readonly rooms: RoomInfo[];
+    getInstance(id: string): InstanceInfo | null;
+    getRoom(roomId: string): RoomInfo | null;
+    findRooms(filter?: {
+        type?: string;
+        instanceId?: string;
+        labels?: Record<string, string>;
+    }): RoomInfo[];
+    createRoom(request: {
+        type: string;
+        roomId?: string;
+        placement?: PlacementRequest;
+    }): Promise<RoomInfo>;
+    destroyRoom(roomId: string): Promise<void>;
+    drainInstance(instanceId: string): Promise<void>;
+    undrainInstance(instanceId: string): Promise<void>;
+}
+declare class Orchestrator extends Broadcast implements FleetController {
+    readonly fleet: FleetApi;
+    private readonly config;
+    private readonly state;
+    private readonly now;
+    private logger;
+    /** `fleet:http` logger; NOOP until `listen()` loads core's logging factory. */
+    private httpLogger;
+    /** Fastify-based REST /v1 surface over the same `node:http` server (§10, task 006). */
+    private readonly httpApi;
+    private readonly auth;
+    private readonly commands;
+    private readonly poller;
+    private readonly reconciler;
+    private readonly control;
+    /** Live agent links keyed by connection-scoped instance id. */
+    private readonly links;
+    private rivalis;
+    private httpServer;
+    private listening;
+    private transportAttached;
+    constructor(options: OrchestratorOptions, internals?: OrchestratorInternals);
+    /**
+     * Bridge every {@link FleetEventType} broadcast (§9) into one SSE listener as a
+     * {@link FleetEvent} `{ type, data }`; returns an unsubscribe (called on stream close, §10).
+     */
+    private subscribeFleetEvents;
+    /** True once HTTP is listening and the WS transport is attached (drives `/readyz`, task 010). */
+    get ready(): boolean;
+    /** Start the HTTP/WS server, attach the internal Rivalis room, begin accepting agents (§9). */
+    listen(): Promise<void>;
+    /** Gracefully stop: reject in-flight commands, destroy rooms, dispose transport, close HTTP (§9). */
+    shutdown(): Promise<void>;
+    /** @internal Agent joined: assign id, send `fleet/hello`, start polling (§7, task 011). */
+    handleAgentJoin(link: AgentLink): void;
+    /** @internal Agent socket closed: evict instantly, rejecting any in-flight commands (§7). */
+    handleAgentLeave(instanceId: string): void;
+    /**
+     * @internal Inbound agent frame (task 011). Every agent frame must be a reply to
+     * an outstanding orchestrator request — `fleet/state` to a `fleet/poll`,
+     * `fleet/ack` to a `fleet/cmd`. A well-formed frame whose correlation id matches
+     * no outstanding request (spontaneous, duplicate, or post-settle) is an
+     * unsolicited frame → kick. A malformed / version-incompatible frame is logged
+     * and dropped (the lockstep-mismatch path is evicted by missed polls, §7/§8).
+     */
+    handleAgentMessage(instanceId: string, topic: string, payload: Uint8Array | string): void;
+    /** Build and send a `fleet/poll`: knownHash drives dedup, status echoes for drain confirmation. */
+    private sendPoll;
+    /**
+     * Ingest a `fleet/state` poll reply (task 011). The reply must match the
+     * outstanding poll's `reqId` (consumed via the poller); an unmatched reply is
+     * unsolicited → kick. A full reply is bounds-checked (§13) and applied; a
+     * hash-only reply just refreshes liveness (the snapshot is unchanged).
+     */
+    private handleState;
+    private handleAck;
+    /**
+     * Kick an agent that broke the request/reply contract (task 011): tear it down
+     * (rejecting in-flight commands, removing it from the read model) and close the
+     * socket so it reconnects fresh. The log line names the cause and the instance —
+     * never the offending payload's contents (§13).
+     */
+    private kick;
+    private onStale;
+    private onEvict;
+    /**
+     * Remove an instance from every table, reject its in-flight commands immediately
+     * with `INSTANCE_DISCONNECTED` (§7), and reconcile (its rooms → `room:destroy`, `sync`).
+     */
+    private teardownInstance;
+    /**
+     * Decode a binary agent frame for `topic` (§7). Returns `null` on any failure —
+     * never throws into the host (§8): a protocol-incompatible frame (e.g. a legacy
+     * JSON agent against this v2 orchestrator) or a malformed/truncated one is logged
+     * and dropped, and the read model keeps its last good state.
+     */
+    private decode;
+    private emitEvent;
+    /**
+     * Run a timer- / transport- / core-dispatch-driven callback, swallowing and
+     * logging any throw so it never escapes into a raw `setTimeout` (an
+     * `uncaughtException` that would crash the whole control plane) or back into
+     * core's room dispatch (§14 failure modes). Mirrors the agent's host-safety
+     * `guard` (§8): the orchestrator is the single point of coordination, so one
+     * unhandled throw on a poll tick, a snapshot application, or a liveness deadline
+     * must degrade to a logged failure on one instance, never an orchestrator-wide
+     * outage. Never rethrows.
+     */
+    private guard;
+}
+
+/**
+ * Instance-side fleet client (§8). Attaches a `Rivalis` instance to an
+ * orchestrator over core's hardened `WSClient` (task 002, `ticketSource:
+ * 'protocol'` so the agent key never lands in a URL — §13): it reports the
+ * instance's rooms/connections and executes orchestrator-pushed room commands.
+ *
+ * Strict orchestrator-driven request/reply (task 011): the agent never pushes
+ * state spontaneously. The orchestrator polls (`fleet/poll`) on its own cadence
+ * and the agent answers with `fleet/state` — a full snapshot when its hash differs
+ * from the poll's `knownHash`, a hash-only reply otherwise. `drain()`/`undrain()`
+ * flip the agent-owned status locally and resolve when a subsequent poll echoes the
+ * target status (an acknowledged confirmation, no unsolicited frame).
+ *
+ * The load-bearing contract (§8): **never throws into the host process from
+ * network failures**. Every transport callback is wrapped, failures are logged
+ * via `rivalis.logging.getLogger('fleet:agent')`, and the agent reconnects with
+ * exponential backoff (0.5 s → 30 s cap, full jitter — §7). This is what forces
+ * the §4 `WSClient` hardening: the unhardened client crashes the host on the
+ * first `ECONNREFUSED`.
+ */
+
+/**
+ * Public agent option surface (§8). Lives next to its sole consumer rather than
+ * in the pure data model — it is consumer configuration, not a read-model type.
+ * Re-exported from `main.ts`. Note: no `heartbeatMs` — the interval is assigned
+ * by the orchestrator in `fleet/hello` (single source of truth, §7).
+ */
+interface FleetAgentOptions {
+    /** Orchestrator WS endpoint. */
+    url: string;
+    /** Agent key (sent via WS subprotocol, never query string — §13). */
+    key: string;
+    /** Public URL game clients use to connect to this instance. */
+    endpointUrl: string;
+    /** Human-readable instance name. */
+    name: string;
+    labels?: Record<string, string>;
+    capacity?: {
+        maxConnections?: number | null;
+        maxRooms?: number | null;
+    };
+    /** Allow orchestrator-initiated `rooms.create` (default true). */
+    autoCreate?: boolean;
+    /** Reject `connect()` after this deadline instead of retrying forever. */
+    connectTimeoutMs?: number;
+}
+/** Lifecycle status surfaced by `agent.status` (§8). Distinct from the snapshot's `active`/`draining`. */
+type AgentLifecycleStatus = 'connecting' | 'connected' | 'draining' | 'closed';
+/** Opaque timer handle — `unknown` so an injected fake scheduler can return anything. */
+type TimerHandle = unknown;
+/** Injectable timer surface so tests drive heartbeat/debounce/backoff deterministically. */
+interface AgentScheduler {
+    setTimeout(fn: () => void, ms: number): TimerHandle;
+    clearTimeout(handle: TimerHandle): void;
+    setInterval(fn: () => void, ms: number): TimerHandle;
+    clearInterval(handle: TimerHandle): void;
+}
+/**
+ * Test/advanced seams kept off the public `FleetAgentOptions` surface (§8 keeps
+ * the documented constructor to `(rivalis, options)`). Mirrors the third-param
+ * convention the Snapshot builder uses for its logger.
+ */
+interface AgentInternals {
+    createClient?: (url: string) => Client;
+    scheduler?: AgentScheduler;
+    backoff?: {
+        baseMs?: number;
+        capMs?: number;
+    };
+    random?: () => number;
+    awaitEmptyPollMs?: number;
+    /** Wire process-signal handlers for `enableGracefulShutdown`; returns an uninstaller. */
+    installSignalHandlers?: (handler: () => void) => () => void;
+}
+declare class FleetAgent extends Broadcast {
+    private readonly rivalis;
+    private readonly logger;
+    private readonly snapshot;
+    private readonly url;
+    private readonly key;
+    private readonly autoCreate;
+    private readonly maxRooms;
+    private readonly connectTimeoutMs;
+    private readonly client;
+    private readonly scheduler;
+    private readonly random;
+    private readonly backoffBaseMs;
+    private readonly backoffCapMs;
+    private readonly awaitEmptyPollMs;
+    private readonly installSignalHandlers;
+    private lifecycle;
+    private instanceId;
+    /** Set once `connect()`/reconnects should stop (intentional `disconnect()` or fatal error). */
+    private closed;
+    /** Distinguishes an operator-driven close from a transport drop that should reconnect. */
+    private intentionalClose;
+    private reconnectTimer;
+    private connectDeadline;
+    private reconnectAttempt;
+    private connectResolve;
+    private connectReject;
+    /**
+     * Pending `drain()` / `undrain()` promises (task 011): each waits for a
+     * `fleet/poll` echoing its target status — the orchestrator's acknowledged
+     * confirmation that it recorded the agent-owned status flip. No unsolicited frame.
+     */
+    private pendingStatus;
+    private uninstallSignals;
+    /**
+     * Whether the room/transport listeners are currently attached (task 008). The
+     * subscription lifecycle tracks the connection lifecycle: attached on construct
+     * and on every `connect()`, detached on the terminal paths (`disconnect()`,
+     * `failConnect()`) so a discarded/replaced agent stops reacting to room events
+     * and the host can drop it (otherwise `RoomManager`'s broadcast retains it).
+     */
+    private listenersAttached;
+    /**
+     * Drop provenance when a room is destroyed so a future id reuse is not mis-stamped
+     * (§7). Room create/destroy/define no longer trigger a push — changes surface at
+     * the next orchestrator poll (task 011).
+     */
+    private readonly onRoomDestroy;
+    constructor(rivalis: Rivalis, options: FleetAgentOptions, internals?: AgentInternals);
+    /** Lifecycle status (§8): `'connecting' | 'connected' | 'draining' | 'closed'`. */
+    get status(): AgentLifecycleStatus;
+    /** Stable per-process id (§6), constant across reconnects. */
+    get processUid(): string;
+    /**
+     * Connect to the orchestrator; resolves on the first `fleet/hello`. Default:
+     * retries forever (backoff per §7) — the promise stays pending while the
+     * orchestrator is unreachable. With `connectTimeoutMs` set, rejects after the
+     * deadline and transitions to `'closed'` with no background retry loop (§8).
+     */
+    connect(): Promise<void>;
+    /**
+     * Mark this instance draining (§7, task 011): flips the agent-owned status
+     * immediately (so the next `fleet/state` reply carries it) and resolves only when
+     * a subsequent `fleet/poll` echoes `status: 'draining'` — the orchestrator's
+     * acknowledged confirmation that it recorded the flip. No unsolicited frame.
+     */
+    drain(): Promise<void>;
+    /** Reverse of `drain()` — restore the instance to `active`; resolves on the poll echo (§7). */
+    undrain(): Promise<void>;
+    /** Resolve once every local room is empty (zero connections), or reject on `timeoutMs` (§8). */
+    awaitEmpty({ timeoutMs }?: {
+        timeoutMs?: number;
+    }): Promise<void>;
+    /** Detach cleanly: stop all timers, close the transport, no further reconnects (§8). */
+    disconnect(): Promise<void>;
+    /**
+     * Wire `SIGTERM`/`SIGINT` to the graceful sequence (§8):
+     * drain → awaitEmpty → disconnect → `rivalis.shutdown()`.
+     */
+    enableGracefulShutdown({ emptyTimeoutMs }?: {
+        emptyTimeoutMs?: number;
+    }): void;
+    private gracefulShutdown;
+    /**
+     * Attach the room-provenance and transport listeners (task 008). Idempotent —
+     * re-`connect()` after a `disconnect()` calls this again but it no-ops while
+     * already attached, so listeners are never doubled.
+     */
+    private attachListeners;
+    /**
+     * Detach every listener on the terminal paths (task 008): the rooms broadcast
+     * stops retaining this agent (no more `forgetRoom` on room destroy) and the
+     * transport handlers are removed. Without this a discarded agent leaks — the
+     * `RoomManager` broadcast keeps it alive for the host process's lifetime.
+     */
+    private detachListeners;
+    private wireClient;
+    private subscribeRooms;
+    private unsubscribeRooms;
+    private openConnection;
+    private onTransportOpen;
+    private onTransportClose;
+    private onTransportError;
+    private scheduleReconnect;
+    /** Full-jitter exponential backoff: random in `[0, min(cap, base·2^attempt)]` (§7). */
+    private backoffDelay;
+    private onHello;
+    /**
+     * Answer an orchestrator `fleet/poll` with a `fleet/state` reply (§7, task 011):
+     * full snapshot when our hash differs from the poll's `knownHash`, hash-only
+     * otherwise. A poll echoing a pending `drain()`/`undrain()` target status also
+     * resolves that promise (the acknowledged confirmation, no unsolicited frame).
+     */
+    private onPoll;
+    private onCmd;
+    private execCreate;
+    private execDestroy;
+    private execStatusCmd;
+    private requestStatus;
+    /** Resolve every pending drain()/undrain() whose target matches the poll-echoed status. */
+    private resolveStatusOnEcho;
+    private sendState;
+    private sendAck;
+    private send;
+    /** Fatal connect failure (timeout or protocol mismatch): reject, close, stop retrying (§8). */
+    private failConnect;
+    private rejectPendingStatus;
+    private clearReconnect;
+    private clearConnectDeadline;
+    private clearAllTimers;
+    /** Run a transport/timer callback, swallowing+logging any throw (§8 host-safety contract). */
+    private guard;
+    /**
+     * Decode an inbound binary frame for a non-hello topic (§7, task 005). Logs +
+     * returns `null` on any failure — never throws into the host (§8). A
+     * protocol-incompatible frame is logged as a version mismatch; a
+     * malformed/truncated frame is logged and dropped. (`fleet/hello` handles a
+     * version mismatch itself — a loud connect failure — so it does not use this.)
+     */
+    private decodeInbound;
+}
+
+export { FleetAgent, type FleetAgentOptions, type FleetApi, FleetError, type FleetErrorCode, type FleetEvent, type FleetEventType, type FleetStats, type InstanceInfo, Orchestrator, type OrchestratorOptions, PROTOCOL_VERSION, type PlacementRequest, type PlacementStrategy, type RoomInfo };