@pyric/cli 0.1.0-alpha.11 → 0.1.0-alpha.13

package/src/serve/worker/client/connection.ts

@@ -0,0 +1,227 @@
+/**
+ * Worker-client connection + lifecycle — open the SharedWorker port, query the
+ * worker's version/instance, drive state export/import + named branches, forward
+ * agent tool-calls, and relay raw worker-protocol frames from the bridge peer.
+ */
+
+import type { InboundMessage } from '../protocol.js';
+import type { WorkerOpPayload, WorkerSubPayload } from '../../../bridge/protocol.js';
+import {
+  nextId,
+  nextSubId,
+  wirePort,
+  rpc,
+  rpcWithTimeout,
+  rawRpc,
+  openSnapshotSubscription,
+  closeSubscription,
+} from './core.js';
+import type { ClientDb } from './handles.js';
+
+// ─── Public API ────────────────────────────────────────────────────────────
+
+/**
+ * Connect to the SharedWorker and return a client Firestore handle.
+ *
+ * Pass the URL of the SharedWorker script as `workerUrl`. Under `pyric dev`
+ * this is `/__pyric/sdk/worker.js`; for tests or standalone use, pass the path
+ * explicitly.
+ *
+ * `getFirestore` mirrors `pyric/firestore`'s `getFirestore(sandbox)` shape
+ * but returns a `ClientDb` backed by a `MessagePort` instead of a sandbox.
+ */
+export interface SharedWorkerConnectionOptions {
+  onError?: (error: Error) => void;
+}
+
+export function getFirestore(
+  workerUrl: string | URL,
+  name?: string,
+  options: SharedWorkerConnectionOptions = {},
+): ClientDb {
+  if (typeof SharedWorker === 'undefined') {
+    throw new Error(
+      'SharedWorker is not available. ' +
+      'Open this page over http:// (not file://) and use a supported browser ' +
+      '(Chrome 4+, Firefox 29+, Safari 16.4+).',
+    );
+  }
+  const worker = new SharedWorker(workerUrl, {
+    type: 'classic',
+    name: name ?? 'pyric-shared-worker',
+  });
+  if (options.onError) {
+    worker.addEventListener('error', (event) => {
+      const detail = event.message || `failed to load ${String(workerUrl)}`;
+      options.onError?.(new Error(`Pyric SharedWorker error: ${detail}`));
+    });
+  }
+  const port = worker.port;
+  wirePort(port);
+  port.start();
+  return { __kind: 'client-db', port };
+}
+
+/**
+ * Ask the worker for its baked build version (staleness guard). The page
+ * compares it to the served bundle version and warns when a still-running OLD
+ * worker is older than what's served (a SharedWorker can't hot-update).
+ */
+export async function getWorkerVersion(
+  db: ClientDb,
+  options: { timeoutMs?: number } = {},
+): Promise<string> {
+  const id = nextId();
+  const timeoutMs = options.timeoutMs ?? 2_000;
+  const r = (await rpcWithTimeout(
+    db.port,
+    { t: 'op', id, method: 'getRuntimeEpoch' },
+    timeoutMs,
+    `Timed out waiting for the Pyric SharedWorker version handshake after ${timeoutMs}ms.`,
+  )) as { version: string };
+  return r.version;
+}
+
+/**
+ * Ask the worker for its stable per-instance id (see host `INSTANCE_ID_KEY`).
+ * Studio renders a human-friendly form so a user can tell which sandbox instance
+ * they're looking at — the same `localhost:<port>` in a different browser profile
+ * is a SEPARATE sandbox (a separate SharedWorker + IndexedDB), and this is how
+ * the two are told apart.
+ */
+export async function getWorkerInstanceId(db: ClientDb): Promise<string> {
+  const r = (await rpc(db.port, { t: 'op', id: nextId(), method: 'getVersion' })) as { instanceId?: string };
+  return r.instanceId ?? '';
+}
+
+/**
+ * Phase 2 (transfer): export the FULL sandbox state as a portable bundle string
+ * (the chunk format the persist layer uses, so wrapper types round-trip). Save
+ * it to a file and {@link importWorkerState} it into another instance.
+ */
+export async function exportWorkerState(db: ClientDb): Promise<string> {
+  const r = (await rpc(db.port, { t: 'op', id: nextId(), method: 'exportState' })) as { bundle: string };
+  return r.bundle;
+}
+
+/** Phase 2 (clobber): replace this sandbox's ENTIRE state with `bundle`. */
+export async function importWorkerState(db: ClientDb, bundle: string): Promise<void> {
+  await rpc(db.port, { t: 'op', id: nextId(), method: 'importState', bundle });
+}
+
+/** Phase 3: save the live sandbox as a named branch (a saved state bundle). */
+export async function saveWorkerBranch(db: ClientDb, name: string): Promise<void> {
+  await rpc(db.port, { t: 'op', id: nextId(), method: 'saveBranch', name });
+}
+
+/** Phase 3: list this instance's saved branch names. */
+export async function listWorkerBranches(db: ClientDb): Promise<string[]> {
+  const r = (await rpc(db.port, { t: 'op', id: nextId(), method: 'listBranches' })) as { branches?: string[] };
+  return r.branches ?? [];
+}
+
+/** Phase 3 (clobber): switch the live sandbox to a named branch's state. */
+export async function switchWorkerBranch(db: ClientDb, name: string): Promise<void> {
+  await rpc(db.port, { t: 'op', id: nextId(), method: 'switchBranch', name });
+}
+
+/** Phase 3: delete a named branch. */
+export async function deleteWorkerBranch(db: ClientDb, name: string): Promise<void> {
+  await rpc(db.port, { t: 'op', id: nextId(), method: 'deleteBranch', name });
+}
+
+/**
+ * Forward an agent tool-call to the worker so it executes against the SAME
+ * sandbox the app + Studio use. The worker runs the canonical tool dispatcher
+ * (`buildSandboxDispatcher`) and replies with the `{ ok, summary, data }`
+ * result. Used by the bridge peer on the worker path (`connectBridgePeer` in
+ * `entries/runtime.ts`) so the agent shares the one authoritative sandbox.
+ */
+export async function callTool(
+  db: ClientDb,
+  name: string,
+  args: Record<string, unknown>,
+): Promise<{ ok: boolean; summary: string; data?: unknown }> {
+  return (await rpc(db.port, { t: 'tool', id: nextId(), name, args })) as {
+    ok: boolean;
+    summary: string;
+    data?: unknown;
+  };
+}
+
+// ─── Generic worker relay (remote sandbox, slice 1) ────────────────────────
+//
+// The bridge peer forwards `worker-op` / `worker-sub` frames from the Node
+// side (`connectRemoteSandbox`) into the SharedWorker through these two
+// functions (see `workerRelay` in `bridge/client/bridge.ts` + the wiring in
+// `entries/runtime.ts`). Ids are re-minted LOCALLY (`nextId`/`nextSubId`) so
+// relayed traffic shares this page's pending/sub maps without any chance of
+// colliding with the page's own ids — the bridge correlates by ITS frame id.
+
+/**
+ * Relay one raw worker-protocol op into the SharedWorker. `op` is the op
+ * message minus `t`/`id` (the `WorkerOpPayload` wire shape); resolves with
+ * the worker's `res.value`, rejects with an Error carrying `.code`.
+ */
+export function relayWorkerOp(db: ClientDb, op: WorkerOpPayload): Promise<unknown> {
+  // rawRpc, NOT rpc: the relay owns provenance and must not inherit this
+  // browser page's Studio issuer. Override any untrusted incoming marker so
+  // Node/agent/system traffic can never be attributed to page app activity.
+  return rawRpc(db.port, {
+    ...op,
+    issuer: undefined,
+    relaySource: 'remote',
+    t: 'op',
+    id: nextId(),
+  } as InboundMessage);
+}
+
+/**
+ * Relay a raw worker-protocol subscription into the SharedWorker. `sub` is
+ * the sub message minus `t`/`subId` (the `WorkerSubPayload` wire shape).
+ * `onValue` receives every snap value VERBATIM — including the worker host's
+ * `{ __error: { code, message } }` establishment-failure convention (listener
+ * errors are re-wrapped into the same shape so the far side sees one form).
+ * Returns the unsubscribe function.
+ *
+ * The unified event stream (`target: 'events'`) is NOT relayable yet — its
+ * history batches aren't coalescible, so it needs bounded backpressure first
+ * (slice 2).
+ */
+export function relayWorkerSub(
+  db: ClientDb,
+  sub: WorkerSubPayload,
+  onValue: (value: unknown) => void,
+): () => void {
+  if (sub.target === 'events') {
+    throw new Error(
+      'event-stream subscriptions cannot be relayed over the bridge yet (needs bounded backpressure — slice 2)',
+    );
+  }
+  const subId = nextSubId();
+  const opened = openSnapshotSubscription(db.port, subId, {
+    port: db.port,
+    next: onValue,
+    error: (err) =>
+      onValue({
+        __error: {
+          code: (err as { code?: string }).code ?? 'unknown',
+          message: err instanceof Error ? err.message : String(err),
+        },
+      }),
+  }, {
+    ...sub,
+    issuer: undefined,
+    relaySource: 'remote',
+    t: 'sub',
+    subId,
+  } as InboundMessage);
+  if (!opened) {
+    queueMicrotask(() => onValue({
+      __error: { code: 'app/app-deleted', message: 'Firebase App was deleted' },
+    }));
+  }
+  return () => {
+    closeSubscription(db.port, subId);
+  };
+}

package/src/serve/worker/client/core.ts

@@ -0,0 +1,384 @@
+/**
+ * Worker-client transport core — the shared singleton machinery every API
+ * family (firestore, auth, rtdb, storage) rides on: port wiring, RPC
+ * correlation, the pending/subscriber maps, the Pyric Studio auth-lens default,
+ * and the op-source (issuer) stamp.
+ *
+ * This module owns the client's mutable module state. Because ES module
+ * bindings are live, family modules import `_defaultLens` (and the maps) and
+ * observe every `setLens(...)` update through the same singleton — exactly as
+ * they did when all of this lived inline in `client.ts`.
+ */
+import type { InboundMessage, OutboundMessage } from '../protocol.js';
+import type { RuntimeReloadMessage } from '../protocol.js';
+// TYPE-ONLY — the auth-lens contract + the cross-service event envelope, shared
+// with the worker host + the sandbox's event provenance. Erased at build, so the
+// leaf client bundle stays engine-free.
+import type { AuthLens, SandboxEvent } from 'pyric/sandbox';
+import { FirebaseError } from 'pyric/app';
+import type { ClientPort } from './handles.js';
+
+// ─── Port + correlation machinery ─────────────────────────────────────────
+
+let _opCounter = 0;
+let _subCounter = 0;
+
+export function nextId(): string { return `op-${++_opCounter}`; }
+export function nextSubId(): string { return `sub-${++_subCounter}`; }
+
+/**
+ * Pending RPC resolvers. Keyed by correlation id.
+ * Resolves with the `value` field on success; rejects with a typed error
+ * on failure.
+ */
+export const _pending = new Map<string, {
+  port: ClientPort;
+  resolve: (v: unknown) => void;
+  reject: (e: Error & { code: string }) => void;
+}>();
+
+/**
+ * Active snapshot subscribers. Keyed by subId.
+ * `next` is the user-supplied callback; `error` is the optional error handler.
+ */
+export const _snapSubs = new Map<string, {
+  port: ClientPort;
+  next: (snap: unknown) => void;
+  error?: (err: unknown) => void;
+  /** Firestore listeners abort on app deletion; RTDB/Auth stop silently. */
+  service?: 'firestore';
+}>();
+
+/**
+ * Active event-stream subscribers (Pyric Studio keystone). Keyed by subId.
+ * `next` receives each delivered BATCH of `SandboxEvent`s — the first batch is
+ * the initial `history()` snapshot, subsequent batches are single live events.
+ */
+export const _eventSubs = new Map<string, {
+  port: ClientPort;
+  next: (events: readonly SandboxEvent[]) => void;
+}>();
+const disconnectedPorts = new WeakSet<ClientPort>();
+const runtimeReloadListeners = new Set<(message: RuntimeReloadMessage) => void>();
+
+export function subscribeRuntimeReload(
+  listener: (message: RuntimeReloadMessage) => void,
+): () => void {
+  runtimeReloadListeners.add(listener);
+  return () => runtimeReloadListeners.delete(listener);
+}
+
+function appDeletedError(): Error & { code: string } {
+  return Object.assign(new Error('Firebase App was deleted'), { code: 'app/app-deleted' });
+}
+
+export function isDisconnectedPort(port: ClientPort): boolean {
+  return disconnectedPorts.has(port);
+}
+
+/** Atomically register and post a subscription unless its app port is closed. */
+export function openSnapshotSubscription(
+  port: ClientPort,
+  subId: string,
+  subscription: (typeof _snapSubs extends Map<string, infer T> ? T : never),
+  message: InboundMessage,
+): boolean {
+  if (disconnectedPorts.has(port)) return false;
+  _snapSubs.set(subId, subscription);
+  port.postMessage(message);
+  return true;
+}
+
+/** Atomically register an event-stream subscription unless its port is closed. */
+export function openEventSubscription(
+  port: ClientPort,
+  subId: string,
+  next: (events: readonly SandboxEvent[]) => void,
+  message: InboundMessage,
+): boolean {
+  if (disconnectedPorts.has(port)) return false;
+  _eventSubs.set(subId, { port, next });
+  port.postMessage(message);
+  return true;
+}
+
+/** Remove a local subscription and notify only a live app port. */
+export function closeSubscription(port: ClientPort, subId: string): void {
+  _snapSubs.delete(subId);
+  _eventSubs.delete(subId);
+  if (!disconnectedPorts.has(port)) {
+    port.postMessage({ t: 'unsub', subId } satisfies InboundMessage);
+  }
+}
+
+/** Drop every client-side correlation owned by a closing app port. */
+export function disconnectPort(port: ClientPort): void {
+  disconnectedPorts.add(port);
+  const error = appDeletedError();
+  for (const [id, pending] of [..._pending]) {
+    if (pending.port !== port) continue;
+    _pending.delete(id);
+    pending.reject(error);
+  }
+  for (const [id, subscription] of [..._snapSubs]) {
+    if (subscription.port !== port) continue;
+    _snapSubs.delete(id);
+    if (subscription.service === 'firestore') {
+      subscription.error?.(new FirebaseError('aborted', 'The operation was aborted.'));
+    }
+  }
+  for (const [id, subscription] of [..._eventSubs]) {
+    if (subscription.port !== port) continue;
+    _eventSubs.delete(id);
+  }
+  port.onmessage = null;
+}
+
+// ─── Denial relay (headless dev visibility) ────────────────────────────────
+//
+// An agent driving `pyric dev` headlessly never sees the browser console, so
+// a rules denial is otherwise invisible to it. Relay every denial (an error
+// carrying `denialContext`) to the dev server, which prints it to the
+// terminal — regardless of whether the app itself catches/handles the
+// error. Fire-and-forget: never throws, never awaited into app flow, and a
+// relay failure (dev server down, no `fetch`, non-pyric host) is swallowed
+// silently — this is a diagnostics side channel, not a correctness path.
+
+/** Shape POSTed to the dev server's `/__pyric/denials` endpoint. */
+interface DenialRelayPayload {
+  kind: 'listener' | 'read';
+  code: string;
+  message: string;
+  denialContext: unknown;
+  /** Sibling of denialContext on the sandbox error (query-proof denials
+   *  attach the suggested where() fix there); forwarded when present. */
+  remediation?: string;
+}
+
+/** POST a denial to the dev server for terminal visibility. No-op when the
+ *  error carries no `denialContext` (only rules denials are relayed) or when
+ *  `fetch` isn't available (non-browser host). */
+function relayDenial(
+  kind: 'listener' | 'read',
+  err: { message: string; code: string; denialContext?: unknown; remediation?: unknown },
+): void {
+  if (err.denialContext === undefined) return;
+  if (typeof fetch !== 'function') return;
+  const payload: DenialRelayPayload = {
+    kind,
+    code: err.code,
+    message: err.message,
+    denialContext: err.denialContext,
+    ...(typeof err.remediation === 'string' ? { remediation: err.remediation } : {}),
+  };
+  try {
+    void fetch('/__pyric/denials', {
+      method: 'POST',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify(payload),
+    }).catch(() => {});
+  } catch {
+    /* fire-and-forget — never let the relay disturb app flow */
+  }
+}
+
+/** Wire up the port's onmessage handler (idempotent per-port). */
+export function wirePort(port: ClientPort): void {
+  port.onmessage = (ev: MessageEvent<OutboundMessage>) => {
+    const msg = ev.data;
+    if (msg.t === 'res') {
+      const pending = _pending.get(msg.id);
+      if (!pending) return;
+      _pending.delete(msg.id);
+      if (msg.ok) {
+        pending.resolve(msg.value);
+      } else {
+        const err = new Error(msg.error.message) as Error & {
+          code: string;
+          denialContext?: unknown;
+          aiEnvelope?: unknown;
+        };
+        err.code = msg.error.code;
+        // Structured denial context (spike gap 6): re-attach so consumers —
+        // and the bridge relay, which re-serializes thrown errors — see the
+        // same shape a local SandboxError carries.
+        if (msg.error.denialContext !== undefined) {
+          err.denialContext = msg.error.denialContext;
+        }
+        // AI wire error envelope (pyric/ai): re-attach so the served
+        // `firebase/ai` entry can mint the exact SDK AIError decoration the
+        // in-process plane applies (see entries/ai.ts).
+        if (msg.error.aiEnvelope !== undefined) {
+          err.aiEnvelope = msg.error.aiEnvelope;
+        }
+        relayDenial('read', err);
+        pending.reject(err);
+      }
+    } else if (msg.t === 'snap') {
+      const sub = _snapSubs.get(msg.subId);
+      if (!sub) return;
+      // Auth snaps carry `SerializedUser | null` — a null value is a valid
+      // "signed out" payload, not an error, so guard the __error sniff.
+      const value = (msg.value ?? {}) as Record<string, unknown>;
+      if (value.__error) {
+        const errPayload = value.__error as { code: string; message: string; denialContext?: unknown; aiEnvelope?: unknown };
+        const err = new Error(errPayload.message) as Error & { code: string; denialContext?: unknown; aiEnvelope?: unknown };
+        err.code = errPayload.code;
+        if (errPayload.denialContext !== undefined) err.denialContext = errPayload.denialContext;
+        if (errPayload.aiEnvelope !== undefined) err.aiEnvelope = errPayload.aiEnvelope;
+        relayDenial('listener', err);
+        // Surface an unobserved listener error instead of swallowing it — the
+        // worker-path twin of the in-page default (a denied listener after a
+        // rules change / sign-out must not fail silently on the page console).
+        if (sub.error) sub.error(err);
+        else console.error('pyric/firestore: Uncaught Error in snapshot listener:', err);
+        return;
+      }
+      sub.next(msg.value);
+    } else if (msg.t === 'event') {
+      // Event-stream batch (Pyric Studio keystone). Plain JSON SandboxEvents —
+      // no rehydration. Deliver the whole batch to the registered subscriber.
+      const subscription = _eventSubs.get(msg.subId);
+      if (subscription) subscription.next(msg.events);
+    } else if (msg.t === 'runtime-reload') {
+      for (const listener of runtimeReloadListeners) listener(msg);
+    }
+  };
+}
+
+// ─── Auth lens (Pyric Studio) ──────────────────────────────────────────────
+//
+// The default per-op auth lens carried on every FIRESTORE DATA op this client
+// sends. The host resolves a data handle from it (`lensDb` in host.ts):
+//   - `{ mode: 'app-session' }` (the default): the served app's own session.
+//   - `{ mode: 'as', uid }`: impersonate — rules evaluate as that user.
+//   - `{ mode: 'admin' }`: admin lens (rule bypass; see host.ts gap note).
+//
+// Studio sets this so its data grids / rules-debug "re-run as user" views run
+// under the chosen identity without threading `actAs` through every call. AUTH
+// ops (`auth.*`) and `getVersion` are NEVER lensed — they operate the worker's
+// session, not data — so the lens is stamped only on the data-op path.
+
+/** Module-level default lens. `undefined` ⇒ the worker treats the op as the
+ *  app's session (the additive default — existing senders omit `actAs`).
+ *
+ *  Exported as a LIVE binding: family modules read it to stamp the lens onto
+ *  subscriptions (`onSnapshot`, `rtdbOnValue`), and see `setLens(...)` updates
+ *  through this one singleton. */
+export let _defaultLens: AuthLens | undefined;
+
+/**
+ * Set the default auth lens applied to subsequent Firestore DATA ops from this
+ * client (Pyric Studio). Pass `{ mode: 'as', uid }` to read/write AS a user
+ * (rules apply), `{ mode: 'admin' }` for the admin lens, or
+ * `{ mode: 'app-session' }` / `undefined` to revert to the app's own session.
+ *
+ * The lens is process-wide for this client module (one served page = one
+ * worker port), mirroring how Studio drives a single active identity at a time.
+ * Auth ops are unaffected — they always operate the real session.
+ */
+export function setLens(lens: AuthLens | undefined): void {
+  _defaultLens = lens && lens.mode === 'app-session' ? undefined : lens;
+}
+
+/** The active default lens (read-only view), for Studio UI to reflect state. */
+export function getLens(): AuthLens | undefined {
+  return _defaultLens;
+}
+
+/**
+ * Module-level op-source declaration (Pyric Studio traffic attribution).
+ * When set, every op/sub message THIS CLIENT MODULE CONSTRUCTS is stamped
+ * `source: 'studio'` on the wire; the host maps that onto the unified
+ * event stream's `actor` field so Traffic can filter Studio's own
+ * viewer/editor ops out of the app's stream.
+ *
+ * Studio's live plane sets this once at connect (`connectWorkerLive`);
+ * the served APP page never calls it (its service handles remain the source
+ * of app attribution), and RELAYED frames bypass Studio stamping entirely —
+ * the bridge relay ({@link relayWorkerOp} / {@link relayWorkerSub}) clears the
+ * Studio issuer and marks remote frames through {@link rawRpc} / a direct postMessage, so a
+ * user's own admin-SDK traffic through the remote bridge is never
+ * mislabeled as Studio's even though it rides the same port.
+ */
+let _opIssuer: 'studio' | undefined;
+
+/** Declare who issues the ops this client module constructs. See {@link _opIssuer}. */
+export function setOpIssuer(source: 'studio' | undefined): void {
+  _opIssuer = source;
+}
+
+/** Stamp the declared op source onto a client-constructed message. Ops and
+ *  subscriptions only — control frames (`tool`, `unsub`) never carry it
+ *  (agent tool-calls dispatched through this port must not inherit
+ *  Studio's source; their inner ops are attributed by the host). */
+export function stampIssuer<T extends { t?: string }>(msg: T): T {
+  return _opIssuer && (msg.t === 'op' || msg.t === 'sub')
+    ? { ...msg, issuer: _opIssuer }
+    : msg;
+}
+
+/**
+ * Send an already-final message and return a promise for its result — no
+ * implicit stamping. The RELAY path ({@link relayWorkerOp}) explicitly owns
+ * the final remote provenance fields before sending through this function.
+ */
+export function rawRpc(port: ClientPort, msg: InboundMessage): Promise<unknown> {
+  if (disconnectedPorts.has(port)) return Promise.reject(appDeletedError());
+  return new Promise<unknown>((resolve, reject) => {
+    const opMsg = msg as { id: string };
+    _pending.set(opMsg.id, {
+      port,
+      resolve,
+      reject: reject as (e: Error & { code: string }) => void,
+    });
+    port.postMessage(msg);
+  });
+}
+
+/** Send a CLIENT-CONSTRUCTED message: stamps the declared op source, then sends. */
+export function rpc(port: ClientPort, msg: InboundMessage): Promise<unknown> {
+  return rawRpc(port, stampIssuer(msg));
+}
+
+/**
+ * Send a client RPC with a bounded wait, while keeping correlation cleanup
+ * inside the transport module that owns the pending-request registry.
+ */
+export function rpcWithTimeout(
+  port: ClientPort,
+  msg: InboundMessage,
+  timeoutMs: number,
+  timeoutMessage: string,
+): Promise<unknown> {
+  const id = (msg as { id: string }).id;
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  const timeout = new Promise<never>((_, reject) => {
+    timer = setTimeout(() => {
+      if (!_pending.delete(id)) return;
+      reject(new Error(timeoutMessage));
+    }, timeoutMs);
+  });
+  return Promise.race([rpc(port, msg), timeout]).finally(() => {
+    if (timer) clearTimeout(timer);
+  });
+}
+
+/**
+ * Like {@link rpc} but stamps the active default auth lens onto the op message
+ * (Pyric Studio). Used by data-service ops so a `setLens(...)` choice
+ * carries per op without every call site threading `actAs`. Auth ops + version
+ * use the bare {@link rpc} so they never carry a lens.
+ *
+ * `actAs` is only attached when a lens is active — when none is set the wire
+ * message is byte-identical to before, preserving the additive contract.
+ */
+export function dataRpc(port: ClientPort, msg: InboundMessage & { t: 'op' }): Promise<unknown> {
+  if (disconnectedPorts.has(port) && !msg.method.startsWith('rtdb.')) {
+    return Promise.reject(
+      new FirebaseError('failed-precondition', 'The client has already been terminated.'),
+    );
+  }
+  const withLens = _defaultLens ? { ...msg, actAs: _defaultLens } : msg;
+  return rpc(port, withLens);
+}

package/src/serve/worker/client/disconnect.ts

@@ -0,0 +1,45 @@
+/** Internal app-port teardown; intentionally absent from the public worker-client barrel. */
+import type { InboundMessage } from '../protocol.js';
+import { disconnectPort, nextId, rawRpc } from './core.js';
+import type { ClientDb } from './handles.js';
+
+export interface DisconnectClientOptions {
+  /** Bound version-skew and worker-crash cases where no disconnect reply arrives. */
+  ackTimeoutMs?: number;
+}
+
+const DEFAULT_ACK_TIMEOUT_MS = 5_000;
+
+function deleteTimeoutError(): Error & { code: string } {
+  return Object.assign(
+    new Error(
+      'Timed out waiting for SharedWorker app cleanup acknowledgment. ' +
+      'Close all tabs using this pyric dev origin so the worker can restart.',
+    ),
+    { code: 'app/delete-timeout' },
+  );
+}
+
+export async function disconnectClient(
+  db: ClientDb,
+  options: DisconnectClientOptions = {},
+): Promise<void> {
+  let timeout: ReturnType<typeof setTimeout> | undefined;
+  try {
+    const acknowledged = rawRpc(db.port, {
+      t: 'disconnect',
+      id: nextId(),
+    } satisfies InboundMessage);
+    const timedOut = new Promise<never>((_resolve, reject) => {
+      timeout = setTimeout(
+        () => reject(deleteTimeoutError()),
+        options.ackTimeoutMs ?? DEFAULT_ACK_TIMEOUT_MS,
+      );
+    });
+    await Promise.race([acknowledged, timedOut]);
+  } finally {
+    if (timeout !== undefined) clearTimeout(timeout);
+    disconnectPort(db.port);
+    db.port.close();
+  }
+}