@vibesdotdev/platform 0.0.0-stage → 1.0.0-rc.2

package/dist/fleets/daemon/relay/connect-relay.js

@@ -0,0 +1,321 @@
+/**
+ * connectRelay — the daemon's outbound relay dial-out (fleet-relay §3.3, R3).
+ *
+ * Opens an outbound WebSocket to `{brokerOrigin}/api/relay/connect?hostId=<id>`
+ * with `Authorization: Bearer <hostToken>`. On a 101 upgrade the socket is handed
+ * to the relay server adapter (R1's seam) which dispatches inbound frames through
+ * the L5-gated `HttpListenTarget`. On close, reconnects with jittered exponential
+ * backoff.
+ *
+ * SECURITY: this function handles CONNECTION-level auth only (the Bearer upgrade).
+ * Per-invoke authz + friction are enforced by the `target.pipeline` the caller
+ * supplies — that pipeline MUST have L5 gates registered. `connectRelay` THROWS on
+ * start if the pipeline is ungated (no interceptors) — the relay daemon guard,
+ * matching the existing http bind-guard discipline (fleet.md §4.5).
+ *
+ * LIFETIME: the relay is long-lived. A broker blip (connection close / network
+ * interruption) is NOT a fatal error; `connectRelay` reconnects automatically.
+ * The returned `RelayConnection` tracks the current connection state so the CLI
+ * can display "relay-connected" vs "connecting" in `vibes fleet status`.
+ *
+ * IMPORTANT NOTE on `RelaySocket` / `RelayServerAdapter`:
+ * The `relayAdapter` parameter is the R1 seam. Post-Wave-1 reconciliation, the
+ * default is the REAL adapter (`createRealRelayServerAdapter`, backed by R1's
+ * `serveRelaySocket`) — inbound frames are dispatched through `target.pipeline`.
+ * The `createStubRelayServerAdapter` no-op is retained for isolated reconnect-loop
+ * tests that must not depend on R1's full dispatch.
+ */
+import { getLogger } from '@vibesdotdev/logging/contexts';
+import * as z from 'zod/v4';
+import { CapabilityError, settle, settleNow } from '@vibesdotdev/kernel';
+import { createRealRelayServerAdapter } from "./real-relay-server-adapter.js";
+// ---------------------------------------------------------------------------
+// Backoff helpers
+// ---------------------------------------------------------------------------
+/** Jittered exponential backoff (seconds capped at `maxSeconds`). */
+function nextBackoffMs(attempt, baseMs = 1000, maxMs = 30_000) {
+    const exp = Math.min(baseMs * Math.pow(2, attempt), maxMs);
+    // ±25% jitter
+    const jitter = exp * 0.25 * (Math.random() * 2 - 1);
+    return Math.max(500, Math.round(exp + jitter));
+}
+// ---------------------------------------------------------------------------
+// A no-op stub adapter used until R1's real export is injected
+// ---------------------------------------------------------------------------
+/**
+ * Stub relay adapter for use while R1 is building in parallel. Logs that it
+ * received frames and closes the socket after a brief window. This lets R3's
+ * reconnect loop, state machine, and tests run correctly without R1.
+ *
+ * Replace with R1's `createRelayServerAdapter()` at integration time.
+ */
+export function createStubRelayServerAdapter() {
+    return {
+        async serve(socket) {
+            // Wait until the socket closes (reconnect loop handles re-dial).
+            await socket.closed;
+        }
+    };
+}
+// ---------------------------------------------------------------------------
+// WebSocket adapter (adapts the global WebSocket to RelaySocket)
+// ---------------------------------------------------------------------------
+/**
+ * Wrap a standard WebSocket into the `RelaySocket` interface.
+ * Called once per open socket.
+ */
+function wrapWebSocket(ws) {
+    let closedResolve;
+    const closed = new Promise((resolve) => {
+        closedResolve = resolve;
+    });
+    const messageHandlers = [];
+    const binaryHandlers = [];
+    ws.addEventListener('message', (event) => {
+        const text = z.string().safeParse(event.data);
+        if (text.success) {
+            for (const h of messageHandlers)
+                h(text.data);
+        }
+        else if (event.data instanceof ArrayBuffer) {
+            const bytes = new Uint8Array(event.data);
+            for (const h of binaryHandlers)
+                h(bytes);
+        }
+        else if (event.data instanceof Uint8Array) {
+            for (const h of binaryHandlers)
+                h(event.data);
+        }
+    });
+    ws.addEventListener('close', () => closedResolve());
+    ws.addEventListener('error', closedResolve, { once: true });
+    return {
+        send(data) {
+            if (ws.readyState === ws.OPEN)
+                ws.send(data);
+        },
+        sendBinary(data) {
+            if (ws.readyState !== ws.OPEN)
+                return;
+            const ownedBytes = new Uint8Array(data.byteLength);
+            ownedBytes.set(data);
+            ws.send(ownedBytes.buffer);
+        },
+        onMessage(handler) {
+            messageHandlers.push(handler);
+        },
+        onBinary(handler) {
+            binaryHandlers.push(handler);
+        },
+        closed,
+        close() {
+            if (ws.readyState === ws.OPEN || ws.readyState === ws.CONNECTING)
+                ws.close();
+        }
+    };
+}
+// ---------------------------------------------------------------------------
+// connectRelay
+// ---------------------------------------------------------------------------
+/**
+ * Start the relay dial-out loop. Returns immediately with a `RelayConnection`
+ * handle (the loop runs in the background). Stop the relay by calling `.stop()`.
+ *
+ * SECURITY GATE: throws synchronously if `options.target.pipeline.size === 0`
+ * (ungated pipeline). The relay daemon guard — mirrors the http bind-guard.
+ */
+export function connectRelay(options) {
+    // THE RELAY SECURITY GATE (fleet-relay §4, R3 responsibility).
+    // An ungated relay pipeline is identical in risk to an ungated http remote bind:
+    // a consumer-sent frame would reach the daemon's execution surface without L5
+    // authz/friction. The pipeline MUST carry gates by construction.
+    if (options.target.pipeline.size === 0) {
+        throw new Error(`connectRelay: refusing to start relay with an ungated invoke pipeline. ` +
+            `The relay daemon MUST supply an invoke pipeline with L5 gates registered ` +
+            `(pipeline.size > 0) so the broker cannot authorize an invoke via connection auth. ` +
+            `Pass a pipeline with createAuthzInterceptor + createFrictionInterceptor (fleet-relay §4).`);
+    }
+    const { brokerOrigin, hostId, hostToken, target, 
+    // MISMATCH 3 RECONCILED: the REAL R1-backed adapter is the default. The stub
+    // is retained only for explicit opt-in in isolated reconnect-loop tests.
+    relayAdapter = createRealRelayServerAdapter(), 
+    // SAFETY: the consumer host provides Bun's WebSocket with the headers constructor overload.
+    WebSocketImpl = WebSocket, baseBackoffMs = 1000, maxBackoffMs = 30_000, onConnected, onDisconnected, onReconnecting } = options;
+    let lastFailure;
+    const reportFailure = (message, cause) => {
+        lastFailure = new CapabilityError(message, 'UNAVAILABLE', {
+            reason: 'relay-connection-failed', cause
+        });
+        options.logger?.warn(message, lastFailure);
+    };
+    let stopped = false;
+    let currentState = 'connecting';
+    const stopping = new AbortController();
+    let activeSocket;
+    let activeFailureListener;
+    const stop = () => {
+        stopped = true;
+        currentState = 'stopped';
+        stopping.abort();
+        if (activeSocket && activeFailureListener) {
+            activeSocket.removeEventListener('error', activeFailureListener);
+        }
+        if (activeSocket && (activeSocket.readyState === activeSocket.OPEN || activeSocket.readyState === activeSocket.CONNECTING)) {
+            activeSocket.close();
+        }
+    };
+    options.lifecycle.signal.addEventListener('abort', stop, { once: true });
+    const connection = {
+        get state() {
+            return currentState;
+        },
+        brokerOrigin,
+        hostId,
+        stop,
+        get settled() { return task; },
+        get lastFailure() { return lastFailure; }
+    };
+    // Build the WebSocket URL for the daemon→broker connect handshake (§3.3).
+    const wsUrl = (() => {
+        const base = brokerOrigin.replace(/^http(s?):\/\//, (_, s) => `ws${s}://`);
+        return `${base}/api/relay/connect?hostId=${encodeURIComponent(hostId)}`;
+    })();
+    // The reconnect loop runs as a background async task.
+    const task = options.lifecycle.own(async () => {
+        try {
+            let attempt = 0;
+            while (!stopped) {
+                currentState = attempt === 0 ? 'connecting' : 'reconnecting';
+                if (attempt > 0) {
+                    const delayMs = nextBackoffMs(attempt - 1, baseBackoffMs, maxBackoffMs);
+                    onReconnecting?.(attempt, delayMs);
+                    {
+                        const operation = await settle(async () => {
+                            if (delayMs > 0)
+                                await options.lifecycle.delay(delayMs, stopping.signal);
+                        });
+                        if (!operation.ok) {
+                            const error = operation.cause;
+                            options.logger?.error('Relay operation failed.', { error: error });
+                            // Stopped, or the daemon runtime is disposing: no further dial.
+                            // Any other refusal ends the loop loudly rather than spinning.
+                            if (!stopped && !options.lifecycle.signal.aborted) {
+                                reportFailure('Relay reconnect hold-off refused.', error);
+                            }
+                            break;
+                        }
+                    }
+                    if (stopped)
+                        break;
+                }
+                let ws;
+                {
+                    const operation = settleNow(() => {
+                        // SECURITY FIX (fleet-relay §3.3 model item 7): send Authorization: Bearer
+                        // on the WS upgrade request. Without this header the broker 401s every
+                        // connect attempt — the daemon token never reaches validateHostToken.
+                        // Bun's WebSocket supports `new WebSocket(url, { headers })` for this.
+                        ws = new WebSocketImpl(wsUrl, {
+                            headers: { 'Authorization': `Bearer ${hostToken}` }
+                        });
+                    });
+                    if (!operation.ok) {
+                        const err = operation.cause;
+                        options.logger?.error('Relay operation failed.', { error: err });
+                        reportFailure('Relay WebSocket constructor failed.', err);
+                        attempt++;
+                        continue;
+                    }
+                }
+                activeSocket = ws;
+                activeFailureListener = reportFailure.bind(undefined, 'Relay WebSocket opening failed.');
+                ws.addEventListener('error', activeFailureListener, { once: true });
+                // Stop settles even a socket that never emits open or close.
+                let finishOpening;
+                const opening = await settle(() => new Promise((resolve, reject) => {
+                    let finished = false;
+                    const aborted = () => finish(false);
+                    stopping.signal.addEventListener('abort', aborted, { once: true });
+                    const finish = (opened) => {
+                        if (finished)
+                            return;
+                        finished = true;
+                        stopping.signal.removeEventListener('abort', aborted);
+                        resolve(opened);
+                    };
+                    finishOpening = finish;
+                    if (stopping.signal.aborted) {
+                        finish(false);
+                        return;
+                    }
+                    ws.addEventListener('open', () => finish(true), { once: true });
+                    ws.addEventListener('error', reject, { once: true });
+                    ws.addEventListener('close', (ev) => {
+                        // A 401 close code means the broker rejected the token.
+                        // We still reconnect (token may be temporarily invalid or the
+                        // broker rolled; the daemon is long-lived and should keep trying).
+                        if (ev.code === 4401) {
+                            reportFailure('Relay broker rejected the host token.', ev);
+                        }
+                        finish(false);
+                    }, { once: true });
+                }));
+                finishOpening(false);
+                const opened = opening.ok && opening.value;
+                if (stopped) {
+                    if (ws.readyState === ws.OPEN || ws.readyState === ws.CONNECTING)
+                        ws.close();
+                    break;
+                }
+                if (!opened) {
+                    if (ws.readyState === ws.OPEN || ws.readyState === ws.CONNECTING)
+                        ws.close();
+                    activeSocket = undefined;
+                    attempt++;
+                    onDisconnected?.(`ws did not open on attempt ${attempt}`);
+                    continue;
+                }
+                // Socket opened. Hand it to the relay server adapter.
+                currentState = 'connected';
+                attempt = 0; // reset backoff on successful open
+                onConnected?.();
+                ws.removeEventListener('error', activeFailureListener);
+                activeFailureListener = reportFailure.bind(undefined, 'Relay WebSocket session failed.');
+                ws.addEventListener('error', activeFailureListener, { once: true });
+                const socket = wrapWebSocket(ws);
+                try {
+                    const operation = await settle(async () => {
+                        // The adapter serves the session until the socket closes.
+                        await relayAdapter.serve(socket, target);
+                    });
+                    if (!operation.ok) {
+                        const err = operation.cause;
+                        options.logger?.error('Relay operation failed.', { error: err });
+                        reportFailure('Relay adapter session failed.', err);
+                    }
+                }
+                finally {
+                    socket.close();
+                    activeSocket = undefined;
+                }
+                if (!stopped) {
+                    const reason = 'relay socket closed';
+                    currentState = 'reconnecting';
+                    onDisconnected?.(reason);
+                    attempt = 1; // start from attempt=1 so first reconnect has a delay
+                }
+            }
+        }
+        finally {
+            stop();
+            options.lifecycle.signal.removeEventListener('abort', stop);
+        }
+    });
+    void (async () => {
+        const result = await settle(() => task);
+        if (!result.ok)
+            reportFailure('Relay task failed.', result.cause);
+    })();
+    return connection;
+}
+//# sourceMappingURL=connect-relay.js.map

package/dist/fleets/daemon/relay/connect-relay.js.map

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

package/dist/fleets/daemon/relay/real-relay-server-adapter.d.ts

@@ -0,0 +1,26 @@
+/**
+ * The REAL relay server adapter — wraps R1's `serveRelaySocket` into the
+ * `RelayServerAdapter` seam shape the daemon's `connectRelay` injects.
+ *
+ * Post-Wave-1 reconciliation (MISMATCH 3): R3 coded against the seam
+ * `RelayServerAdapterFn = (socket, target) => Promise<void>` with a `RelaySocket`
+ * shaped `onMessage` / `onBinary` / `closed`. R1 now exports exactly that function
+ * (`serveRelaySocket`) and the SAME canonical socket shape (`RelayServerSocket`).
+ * The two `RelaySocket` interfaces are structurally identical, so this adapter is a
+ * thin pass-through — no bespoke re-implementation, no second dispatch path.
+ *
+ * SECURITY: this adapter receives ONLY authenticated sockets (connectRelay performs
+ * the Bearer host-token upgrade + 401 guard first) and dispatches every inbound
+ * invoke through `target.pipeline` (the L5 gates) inside R1's RelayListenSession.
+ * It adds NO ungated path; the `connectRelay`/`startFleetDaemon` guard still refuses
+ * to start when the pipeline is ungated (`pipeline.size === 0`).
+ */
+import type { RelayServerAdapter } from './relay-server-adapter.seam.ts';
+/**
+ * Build the real relay server adapter backed by R1's `serveRelaySocket`.
+ *
+ * Injected as the default `relayAdapter` in `connectRelay` / `startFleetDaemon`,
+ * replacing `createStubRelayServerAdapter`.
+ */
+export declare function createRealRelayServerAdapter(): RelayServerAdapter;
+//# sourceMappingURL=real-relay-server-adapter.d.ts.map

package/dist/fleets/daemon/relay/real-relay-server-adapter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"real-relay-server-adapter.d.ts","sourceRoot":"","sources":["../../../../src/fleets/daemon/relay/real-relay-server-adapter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAKH,OAAO,KAAK,EAAE,kBAAkB,EAAiC,MAAM,gCAAgC,CAAC;AAExG;;;;;GAKG;AACH,wBAAgB,4BAA4B,IAAI,kBAAkB,CAQjE"}

package/dist/fleets/daemon/relay/real-relay-server-adapter.js

@@ -0,0 +1,36 @@
+/**
+ * The REAL relay server adapter — wraps R1's `serveRelaySocket` into the
+ * `RelayServerAdapter` seam shape the daemon's `connectRelay` injects.
+ *
+ * Post-Wave-1 reconciliation (MISMATCH 3): R3 coded against the seam
+ * `RelayServerAdapterFn = (socket, target) => Promise<void>` with a `RelaySocket`
+ * shaped `onMessage` / `onBinary` / `closed`. R1 now exports exactly that function
+ * (`serveRelaySocket`) and the SAME canonical socket shape (`RelayServerSocket`).
+ * The two `RelaySocket` interfaces are structurally identical, so this adapter is a
+ * thin pass-through — no bespoke re-implementation, no second dispatch path.
+ *
+ * SECURITY: this adapter receives ONLY authenticated sockets (connectRelay performs
+ * the Bearer host-token upgrade + 401 guard first) and dispatches every inbound
+ * invoke through `target.pipeline` (the L5 gates) inside R1's RelayListenSession.
+ * It adds NO ungated path; the `connectRelay`/`startFleetDaemon` guard still refuses
+ * to start when the pipeline is ungated (`pipeline.size === 0`).
+ */
+// The `/server` subpath exports `serveRelaySocket` + its canonical `RelaySocket`
+// (onMessage/onBinary/closed). Alias it to avoid colliding with the seam's RelaySocket.
+import { serveRelaySocket } from '@vibesdotdev/kernel-rpc/relay/server';
+/**
+ * Build the real relay server adapter backed by R1's `serveRelaySocket`.
+ *
+ * Injected as the default `relayAdapter` in `connectRelay` / `startFleetDaemon`,
+ * replacing `createStubRelayServerAdapter`.
+ */
+export function createRealRelayServerAdapter() {
+    return {
+        serve(socket, target) {
+            // The seam's RelaySocket and R1's RelayServerSocket are the SAME shape
+            // (send / sendBinary / onMessage / onBinary / closed / close). Pass through.
+            return serveRelaySocket(socket, target);
+        }
+    };
+}
+//# sourceMappingURL=real-relay-server-adapter.js.map

package/dist/fleets/daemon/relay/real-relay-server-adapter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"real-relay-server-adapter.js","sourceRoot":"","sources":["../../../../src/fleets/daemon/relay/real-relay-server-adapter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,iFAAiF;AACjF,wFAAwF;AACxF,OAAO,EAAE,gBAAgB,EAAE,MAAM,sCAAsC,CAAC;AAGxE;;;;;GAKG;AACH,MAAM,UAAU,4BAA4B;IAC3C,OAAO;QACN,KAAK,CAAC,MAAmB,EAAE,MAAwB;YAClD,uEAAuE;YACvE,6EAA6E;YAC7E,OAAO,gBAAgB,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;QACzC,CAAC;KACD,CAAC;AACH,CAAC"}

package/dist/fleets/daemon/relay/relay-server-adapter.seam.d.ts

@@ -0,0 +1,75 @@
+/**
+ * Relay server adapter seam — the interface R3 (fleet-daemon relay dial-out) codes
+ * against for R1's server adapter.
+ *
+ * R1 (`runtime-rpc-relay`) owns this contract and provides a concrete
+ * `serveRelaySocket(socket, target)` that implements it. R3 injects the adapter
+ * at runtime so the orchestrator can point at R1's real export during integration
+ * without R3 importing `@vibesdotdev/kernel-rpc/relay` directly (R1 runs in
+ * parallel — its package may not be built when R3 compiles).
+ *
+ * Integration seam note (for the orchestrator):
+ *   - R1 must export a function matching `RelayServerAdapterFn` from its package
+ *     index (or a dedicated subpath, e.g. `@vibesdotdev/kernel-rpc/relay/server`).
+ *   - The fleet-daemon calls `options.relayAdapter(socket, listenTarget)` exactly once
+ *     per inbound WS open. The adapter dispatches inbound frames from `socket`
+ *     through R3's L5-gated `HttpListenTarget`-equivalent and sends responses back.
+ *   - `socket.closed` resolves when the WS closes; the adapter MUST handle that
+ *     cleanly (tear down its internal session, free refs) — the reconnect loop
+ *     outside is the daemon's concern.
+ *   - The adapter owns the per-connection reference table and stream channels
+ *     (per-connection isolation, §4 rule 3). The daemon never reaches into them.
+ *
+ * SECURITY NOTE: the adapter is NOT responsible for connect-level auth (the daemon's
+ * `connectRelay` function handles the broker handshake + 401 guard BEFORE the socket
+ * is handed to the adapter). The adapter receives only AUTHENTICATED sockets. Every
+ * inbound RpcRequest still passes the L5 pipeline wired into `RelayListenTarget`.
+ */
+import type { HttpListenTarget } from '@vibesdotdev/kernel-rpc/http';
+import type { RpcLifecycle } from '@vibesdotdev/kernel-rpc';
+/**
+ * A minimal duplex WebSocket abstraction the relay server adapter uses.
+ * Concrete implementations are:
+ *   - A real `WebSocket` (browser/Node/Bun global) on the daemon side.
+ *   - A mock for tests.
+ *
+ * The adapter MUST NOT import a concrete WS class; it receives this interface
+ * so both production and tests can drive it identically.
+ */
+export type { RelaySocket } from '@vibesdotdev/kernel-rpc/relay/server';
+import type { RelaySocket } from '@vibesdotdev/kernel-rpc/relay/server';
+/**
+ * The relay server adapter function signature.
+ *
+ * Called ONCE per inbound WS connection that has already passed connect-level auth.
+ * The adapter runs the session until `socket.closed`, dispatching all inbound frames
+ * through `target.pipeline` (the L5 gates). It returns a Promise that resolves when
+ * the session is fully torn down (all refs released, channels closed — no leak).
+ *
+ * R1 provides the concrete implementation:
+ * ```ts
+ * import { serveRelaySocket } from '@vibesdotdev/kernel-rpc/relay/server';
+ * // or re-exported from the package root
+ * ```
+ */
+export type RelayServerAdapterFn = (socket: RelaySocket, target: RelayServeTarget) => Promise<void>;
+/**
+ * The listen target a relay session serves, with the owning runtime's
+ * lifecycle, which bounds every reverse-leg invoke (RC07).
+ */
+export type RelayServeTarget = HttpListenTarget & {
+    readonly lifecycle: RpcLifecycle;
+};
+/**
+ * The seam object injected into `connectRelay` / `startFleetDaemon` when relay mode
+ * is active. Fleet-daemon has no compile-time dependency on runtime-rpc-relay;
+ * the orchestrator wires the real impl at integration time.
+ */
+export interface RelayServerAdapter {
+    /**
+     * Serve one authenticated relay socket session.
+     * Mirrors `RelayServerAdapterFn` but is a method for ergonomics.
+     */
+    serve(socket: RelaySocket, target: RelayServeTarget): Promise<void>;
+}
+//# sourceMappingURL=relay-server-adapter.seam.d.ts.map

package/dist/fleets/daemon/relay/relay-server-adapter.seam.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"relay-server-adapter.seam.d.ts","sourceRoot":"","sources":["../../../../src/fleets/daemon/relay/relay-server-adapter.seam.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAEH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,8BAA8B,CAAC;AACrE,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,yBAAyB,CAAC;AAE5D;;;;;;;;GAQG;AACH,YAAY,EAAE,WAAW,EAAE,MAAM,sCAAsC,CAAC;AACxE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,sCAAsC,CAAC;AAExE;;;;;;;;;;;;;GAaG;AACH,MAAM,MAAM,oBAAoB,GAAG,CAAC,MAAM,EAAE,WAAW,EAAE,MAAM,EAAE,gBAAgB,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;AAEpG;;;GAGG;AACH,MAAM,MAAM,gBAAgB,GAAG,gBAAgB,GAAG;IAAE,QAAQ,CAAC,SAAS,EAAE,YAAY,CAAA;CAAE,CAAC;AAEvF;;;;GAIG;AACH,MAAM,WAAW,kBAAkB;IAClC;;;OAGG;IACH,KAAK,CAAC,MAAM,EAAE,WAAW,EAAE,MAAM,EAAE,gBAAgB,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACpE"}

package/dist/fleets/daemon/relay/relay-server-adapter.seam.js

@@ -0,0 +1,29 @@
+/**
+ * Relay server adapter seam — the interface R3 (fleet-daemon relay dial-out) codes
+ * against for R1's server adapter.
+ *
+ * R1 (`runtime-rpc-relay`) owns this contract and provides a concrete
+ * `serveRelaySocket(socket, target)` that implements it. R3 injects the adapter
+ * at runtime so the orchestrator can point at R1's real export during integration
+ * without R3 importing `@vibesdotdev/kernel-rpc/relay` directly (R1 runs in
+ * parallel — its package may not be built when R3 compiles).
+ *
+ * Integration seam note (for the orchestrator):
+ *   - R1 must export a function matching `RelayServerAdapterFn` from its package
+ *     index (or a dedicated subpath, e.g. `@vibesdotdev/kernel-rpc/relay/server`).
+ *   - The fleet-daemon calls `options.relayAdapter(socket, listenTarget)` exactly once
+ *     per inbound WS open. The adapter dispatches inbound frames from `socket`
+ *     through R3's L5-gated `HttpListenTarget`-equivalent and sends responses back.
+ *   - `socket.closed` resolves when the WS closes; the adapter MUST handle that
+ *     cleanly (tear down its internal session, free refs) — the reconnect loop
+ *     outside is the daemon's concern.
+ *   - The adapter owns the per-connection reference table and stream channels
+ *     (per-connection isolation, §4 rule 3). The daemon never reaches into them.
+ *
+ * SECURITY NOTE: the adapter is NOT responsible for connect-level auth (the daemon's
+ * `connectRelay` function handles the broker handshake + 401 guard BEFORE the socket
+ * is handed to the adapter). The adapter receives only AUTHENTICATED sockets. Every
+ * inbound RpcRequest still passes the L5 pipeline wired into `RelayListenTarget`.
+ */
+export {};
+//# sourceMappingURL=relay-server-adapter.seam.js.map

package/dist/fleets/daemon/relay/relay-server-adapter.seam.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"relay-server-adapter.seam.js","sourceRoot":"","sources":["../../../../src/fleets/daemon/relay/relay-server-adapter.seam.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG"}

package/dist/fleets/discovery-contract.d.ts

@@ -0,0 +1,75 @@
+/**
+ * The fleet discovery adapter base contract (fleet.md §4.6).
+ *
+ * A discovery adapter *finds* an already-running reachable runtime and yields a
+ * `runtime/rpc` descriptor for it. It never creates or destroys anything —
+ * **discovery has no teardown obligation** (correction #4, the spine of L6b).
+ *
+ * The lifecycle distinction is enforced *in the type system*: this interface has
+ * NO `destroy`. The provisioning adapter (`@vibesdotdev/platform/fleets`
+ * `FleetProvisioningAdapter`) does — it owns a billable resource. Same output
+ * type (`RuntimeRpcDescriptor`), different obligation. Anything that adds a
+ * teardown method here re-collapses the two seams and is a regression.
+ *
+ * OWNERSHIP NOTE: the `RuntimeRpcDescriptor` shape is owned by L4a
+ * `@vibesdotdev/kernel-rpc` (the FROZEN `runtime/rpc` descriptor). Discovery
+ * adapters CONSTRUCT it; they never define or vary its shape. Every descriptor
+ * an adapter yields validates against `RuntimeRpcDescriptorSchema`.
+ */
+import { type RuntimeRpcDescriptor } from '@vibesdotdev/kernel-rpc';
+import type { ReachableRuntimeRegistry, ReachableRuntimeEntry } from './registry/reachable-runtime.ts';
+/**
+ * The discovery adapter base contract. Each adapter (`fleet/discovery/direct`,
+ * `fleet/discovery/platform`, `fleet/discovery/mdns`) implements this.
+ *
+ * Note: there is intentionally NO `destroy` / `teardown` member. Discovery is a
+ * pure read — it surfaces runtimes that already exist; their lifecycle belongs
+ * to whoever created them (an operator, the LAN host owner, or — for a
+ * provisioned target — `infra/sandbox`).
+ */
+export interface FleetDiscoveryAdapter {
+    /** Stable adapter id, e.g. `'fleet/discovery/direct'`. */
+    readonly id: string;
+    /**
+     * Find reachable runtimes and yield their `runtime/rpc` descriptors. Pure
+     * read — no teardown. An adapter may yield zero, one, or many descriptors; a
+     * long-lived adapter (mDNS) keeps yielding as it observes new advertisements
+     * until `signal` aborts.
+     */
+    discover(signal?: AbortSignal): AsyncIterable<RuntimeRpcDescriptor>;
+}
+/**
+ * Default staleness TTL (seconds) for a `discovered` registry entry when an
+ * adapter does not advertise its own. Discovered entries are evictable (the host
+ * may stop advertising); provisioned entries are sticky until explicit destroy
+ * (fleet.md §10 open-question 1). `0`/absent = no eviction.
+ */
+export declare const DEFAULT_DISCOVERED_TTL_SECONDS = 120;
+/**
+ * Wrap a `RuntimeRpcDescriptor` into a `discovered` registry entry.
+ *
+ * Validates the descriptor against L4a's frozen `RuntimeRpcDescriptorSchema`
+ * before it enters the registry — an adapter cannot register a malformed target.
+ * Throws (with the adapter id) if the descriptor does not validate.
+ */
+export declare function toDiscoveredEntry(sourceAdapterId: string, descriptor: RuntimeRpcDescriptor, options?: {
+    ttlSeconds?: number;
+    registeredAt?: string;
+}): ReachableRuntimeEntry;
+/**
+ * Drive an adapter's `discover()` stream into the reachable-runtime registry,
+ * registering each yielded descriptor as a `discovered` entry. Returns the
+ * descriptors registered (in yield order).
+ *
+ * This is the shared discovery→registry bridge: every adapter family funnels
+ * through it, so the registration discipline (schema-validate, `origin:
+ * 'discovered'`, TTL) is enforced in one place. The registry surface is L6a's
+ * (`@vibesdotdev/platform/fleets`); the resolver (L1/L4) walks it.
+ *
+ * `signal` aborts the stream; partial results already registered stay.
+ */
+export declare function registerDiscovered(adapter: FleetDiscoveryAdapter, registry: ReachableRuntimeRegistry, options?: {
+    signal?: AbortSignal;
+    ttlSeconds?: number;
+}): Promise<RuntimeRpcDescriptor[]>;
+//# sourceMappingURL=discovery-contract.d.ts.map

package/dist/fleets/discovery-contract.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"discovery-contract.d.ts","sourceRoot":"","sources":["../../src/fleets/discovery-contract.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,EAEN,KAAK,oBAAoB,EACzB,MAAM,yBAAyB,CAAC;AACjC,OAAO,KAAK,EACX,wBAAwB,EACxB,qBAAqB,EACrB,MAAM,iCAAiC,CAAC;AAEzC;;;;;;;;GAQG;AACH,MAAM,WAAW,qBAAqB;IACrC,0DAA0D;IAC1D,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IAEpB;;;;;OAKG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,WAAW,GAAG,aAAa,CAAC,oBAAoB,CAAC,CAAC;CACpE;AAED;;;;;GAKG;AACH,eAAO,MAAM,8BAA8B,MAAM,CAAC;AAElD;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAChC,eAAe,EAAE,MAAM,EACvB,UAAU,EAAE,oBAAoB,EAChC,OAAO,GAAE;IAAE,UAAU,CAAC,EAAE,MAAM,CAAC;IAAC,YAAY,CAAC,EAAE,MAAM,CAAA;CAAO,GAC1D,qBAAqB,CAcvB;AAED;;;;;;;;;;;GAWG;AACH,wBAAsB,kBAAkB,CACvC,OAAO,EAAE,qBAAqB,EAC9B,QAAQ,EAAE,wBAAwB,EAClC,OAAO,GAAE;IAAE,MAAM,CAAC,EAAE,WAAW,CAAC;IAAC,UAAU,CAAC,EAAE,MAAM,CAAA;CAAO,GACzD,OAAO,CAAC,oBAAoB,EAAE,CAAC,CASjC"}