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

package/src/serve/worker/host-context.ts

@@ -0,0 +1,273 @@
+/**
+ * SharedWorker host — shared foundation (context + reply helpers).
+ *
+ * The `HostCtx` is the single per-worker context shared across ALL connected
+ * ports and across the auth + event-stream subsystems. `PortLike`, `post`,
+ * `ok`, and `fail` are the minimal port + reply primitives every subsystem
+ * uses. This module imports NOTHING from the sibling `host-*` files, so it is
+ * the dependency root (no circular imports).
+ */
+
+import type { Firestore } from 'pyric/firestore';
+import type { Database } from 'pyric/database';
+import type { LocalSandbox, PersistenceBackend } from 'pyric/sandbox';
+import type { Auth, MintedSession } from 'pyric/auth';
+import type { FirebaseStorage } from 'pyric/storage';
+import {
+  serializeError,
+  type OutboundMessage,
+  type AuthPersistenceMode,
+  type AiEngineConfigWire,
+} from './protocol.js';
+
+// ─── AI broker (structural view) ──────────────────────────────────────────
+
+/**
+ * The worker host's view of `pyric/ai`'s `AiBroker` — the in-process
+ * Gemini-wire answer seam (cdd-deltas #98.1: the broker lives with the
+ * sandbox, i.e. HERE in the serve worker host). Structural because the
+ * `AiBroker` class is not exported from `pyric/ai`'s public surface; the
+ * host recovers the instance from a `getAI(sandbox)` handle via
+ * `TARGET_SYMBOL` (see host-ai.ts). Requests/responses are the plain
+ * Gemini-wire JSON the protocol's ai ops carry.
+ */
+export interface AiBrokerLike {
+  generateContent(req: Record<string, unknown>, model: string): Promise<Record<string, unknown>>;
+  streamGenerateContent(req: Record<string, unknown>, model: string): AsyncIterable<Record<string, unknown>>;
+  countTokens(req: Record<string, unknown>, model: string): Promise<Record<string, unknown>>;
+}
+
+// ─── Port interface ───────────────────────────────────────────────────────
+
+/** Minimal postMessage interface. Fake ports in tests implement this. */
+export interface PortLike {
+  postMessage(msg: OutboundMessage): void;
+}
+
+/** Stable worker-lifetime activity identity for an app page/port. */
+export function activityJourneyId(ctx: HostCtx, port: PortLike): string {
+  const ids = (ctx.activityJourneyIds ??= new WeakMap());
+  const existing = ids.get(port);
+  if (existing) return existing;
+  const id = `page-${(ctx.activityJourneySequence = (ctx.activityJourneySequence ?? 0) + 1)}`;
+  ids.set(port, id);
+  return id;
+}
+
+// ─── Host context ─────────────────────────────────────────────────────────
+
+export interface HostCtx {
+  /** The single shared Firestore handle (sandbox-live — reads currentUser per op). */
+  db: Firestore;
+  /** The underlying Sandbox, for setRules + direct sandbox ops. */
+  sandbox: LocalSandbox;
+  /** Stable worker-lifetime activity identity for each page/app port. */
+  activityJourneyIds?: WeakMap<PortLike, string>;
+  activityJourneySequence?: number;
+  /** Stable per-SharedWorker instance id (see {@link INSTANCE_ID_KEY}). Reported
+   *  via `getVersion` so the UI can identify which sandbox instance this is. */
+  instanceId: string;
+  /** The shared Storage handle (Pyric Studio data browse). Lazily created on
+   *  the first storage op via `getStorageSandbox(sandbox)`. */
+  storage?: FirebaseStorage;
+  /** Shared RTDB handle. Lazily created for the playground shared-runtime path. */
+  rtdb?: Database;
+  /** Cached admin (rules-bypass) RTDB handle for Studio/Playground data inspection. */
+  adminRtdb?: Database;
+  /** Cached admin (rules-bypass) Storage handle for the `{ mode: 'admin' }`
+   *  lens — `pyric/storage/internal`'s `getAdminStorageSandbox`, the handle
+   *  the pyric-admin remote arm's storage ops resolve to. */
+  adminStorage?: FirebaseStorage;
+  /** Per-uid/token Storage handles for the impersonation lens (rules evaluate
+   *  as that user). Mirrors {@link HostCtx.lensRtdbs}. */
+  lensStorages?: Map<string, FirebaseStorage>;
+  /** Per-session Storage handles so app-session rules see the initiating
+   * port's authenticated identity. */
+  sessionStorages?: Map<string, FirebaseStorage>;
+  /** Cached genuinely-UNAUTHENTICATED Firestore handle for the
+   *  `{ mode: 'anon' }` lens — `getFirestore(sandbox.withAuth(null))`, so
+   *  rules evaluate with `request.auth == null`. The remote arm's
+   *  `withAuth(null)`; distinct from an absent lens (the port's session). */
+  anonDb?: Firestore;
+  /** Cached unauthenticated RTDB handle for the `{ mode: 'anon' }` lens. */
+  anonRtdb?: Database;
+  /** Cached unauthenticated Storage handle for the `{ mode: 'anon' }` lens. */
+  anonStorage?: FirebaseStorage;
+  /** Per-uid RTDB handles carrying a port session's real identity. */
+  sessionRtdbs?: Map<string, Database>;
+  /** Per-uid/token RTDB handles for the Studio impersonation lens. */
+  lensRtdbs?: Map<string, Database>;
+  /** Current active rules metadata for shared-runtime diagnostics and revert. */
+  activeRules?: {
+    firestore?: ActiveRulesState;
+    database?: ActiveRulesState;
+  };
+  /** Per-port subscription registry. Map<port, Map<subId, unsub>>. */
+  subs: Map<PortLike, Map<string, () => void>>;
+  /** Ports whose app containers completed explicit deletion. */
+  disconnectedPorts?: WeakSet<PortLike>;
+  /** Firebase options accepted by the first app-owned port. All named apps
+   * and tabs share this one backend, so later app ports must match it. */
+  appOptions?: Record<string, unknown>;
+  /** App ports that attempted to attach a different Firebase configuration. */
+  rejectedConfigPorts?: WeakSet<PortLike>;
+  /**
+   * The ONE shared auth handle for the worker — the USER POOL (who exists)
+   * and the admin surface. Lazily created on first auth op or auth
+   * subscription. Sessions (who a connection IS) are per-port: see
+   * {@link HostCtx.portSessions} (#754). The handle's own `currentUser`
+   * stays null in served mode.
+   */
+  auth?: Auth;
+  /**
+   * Per-connection identity (#754): each port's signed-in session, minted
+   * via `sandbox.mintSession` (an authentic session — validated
+   * credentials / a really-minted identity, NOT the impersonation lens).
+   * A port absent from the map, or mapped to null, is signed out. The
+   * user pool + data + rules stay shared across ports.
+   */
+  portSessions?: Map<PortLike, MintedSession | null>;
+  /**
+   * Re-establish a port's session-bound Firestore listeners under its NEW
+   * session (#754) — set lazily by host.ts (which owns subs) and invoked by
+   * host-auth.ts on every port session change, mirroring prod's stream
+   * re-establishment on auth transitions: a sign-out re-evaluates live
+   * listeners so an auth-gated stream loses access instead of leaking the
+   * previous user's data. (A ctx hook, not an import — host-auth must not
+   * import host.ts.)
+   */
+  resubscribePortSubs?: (port: PortLike) => void;
+  /**
+   * Per-session-token Firestore handles carrying a PORT SESSION's identity —
+   * `getFirestore(sandbox.withAuth(session.state))`, so rules see the
+   * session's uid AND its custom claims on `request.auth.token`. Keyed by
+   * uid + token so distinct claim snapshots never share a handle; forced
+   * refresh also clears the cache. Distinct from
+   * {@link HostCtx.lensHandles}, which is the Studio debugging lens
+   * (uid-only, caller-gated writes).
+   */
+  sessionDbs?: Map<string, Firestore>;
+  /**
+   * The backend used for named state branches (save/switch). Session
+   * persistence is NOT here anymore: per-tab sessions persist client-side
+   * in web storage (the page restores via `auth.restorePortSession`),
+   * mirroring how the real SDK owns persistence in the client (#754).
+   */
+  sessionBackend?: PersistenceBackend;
+  /**
+   * Accepted `auth.setPersistence` mode, kept for surface parity. The
+   * worker itself no longer writes a session record — the CLIENT's
+   * SessionStore honors the mode (which web storage slot, or none).
+   */
+  sessionMode?: AuthPersistenceMode;
+  /**
+   * Force an IMMEDIATE session-capture flush, bypassing the debounce — set
+   * by `applyServeInit` when `--capture` is on (see the capture block in
+   * serve-init.ts). The `resetAll` op invokes it so the server-persisted
+   * capture (`.pyric/last-session.json`) records the post-reset (empty)
+   * event history instead of the wiped session's traffic, which a rebooting
+   * worker would otherwise re-prime via `hydrateEventHistory` (issue #359
+   * extension). Absent when capture is off.
+   */
+  captureFlush?: () => Promise<void>;
+  /**
+   * Per-uid impersonation Firestore handles (Pyric Studio auth lens, T2).
+   * Keyed by the impersonated uid. Each is a FROZEN-identity
+   * `getFirestore(sandbox.withAuth({ uid }))` handle whose ops evaluate
+   * security rules AS that user — the rules-debugging primitive. Cached so
+   * repeated `{ mode: 'as', uid }` ops reuse one handle (and so the modular
+   * layer's per-ctx ref cache stays warm). Lazily populated by `lensDb`.
+   */
+  lensHandles?: Map<string, Firestore>;
+  /**
+   * Cached admin (rules-bypass) Firestore handle for the `{ mode: 'admin' }`
+   * lens (Pyric Studio, Gap #2). A modular `getAdminFirestore(sandbox)` handle
+   * whose ops skip security-rule evaluation — Studio's "edit anything as admin"
+   * (F2). Lazily populated by `lensDb`.
+   */
+  adminDb?: Firestore;
+  /**
+   * The sandbox's AiBroker (pyric/ai), lazily created on the first ai op /
+   * ai stream sub via `getAI(ctx.sandbox, …)` — so the worker's broker IS the
+   * mirror's per-sandbox broker (one instance, events land on the shared
+   * sandbox's unified stream). See `ensureAiBroker` in host-ai.ts.
+   */
+  aiBroker?: AiBrokerLike;
+  /**
+   * Host-construction engine config for the AI broker (cdd-deltas #98.4).
+   * When set (embedding/test hosts, or serve wiring), it WINS over any
+   * op-carried `engine` field; absent, the first ai op's `engine` field is
+   * honored; both absent ⇒ the zero-config scripted default.
+   */
+  aiEngine?: AiEngineConfigWire;
+  /**
+   * Lazily-built agent tool dispatcher (the canonical sandbox tool set) bound to
+   * THIS worker's sandbox. The bridge peer forwards `tool` messages here so the
+   * agent executes against the one shared sandbox, not a separate in-page
+   * backend. Cached so the handler array is built once.
+   */
+  toolDispatch?: (
+    name: string,
+    args: Record<string, unknown>,
+  ) => Promise<{ ok: boolean; summary: string; data?: unknown }>;
+  /**
+   * Messaging host capability. Normal serve producers enable it because
+   * Messaging is in the canonical SDK swap. Absent/false answers
+   * `messaging/disabled` for standalone host construction and focused tests.
+   */
+  messagingEnabled?: boolean;
+  /**
+   * Per-port broker client ids (the worker-host seam's visibility mapping):
+   * a port that reports `messaging.setVisibility` becomes ONE window client
+   * in the broker, so the captured routing rule — foreground iff ANY visible
+   * client — spans tabs. `cleanupPort` removes the client so a closed tab
+   * stops counting as visible. Lazily populated by host-messaging.ts.
+   */
+  messagingClients?: Map<PortLike, string>;
+}
+
+export interface ActiveRulesState {
+  source: unknown;
+  updatedAt: number;
+  status: 'active' | 'error';
+  messages: Array<{ severity: 'info' | 'warn' | 'error'; text: string; line?: number; column?: number }>;
+  lastKnownGood?: unknown;
+}
+
+// ─── Utility: post a typed reply to a port ───────────────────────────────
+
+export function post(port: PortLike, msg: OutboundMessage): void {
+  port.postMessage(msg);
+}
+
+export function ok(port: PortLike, id: string, value: unknown): void {
+  post(port, { t: 'res', id, ok: true, value });
+}
+
+export function fail(port: PortLike, id: string, err: unknown): void {
+  // The serialized error carries `denialContext` when present (spike gap 6) —
+  // post it whole so the structured denial frame reaches remote consumers.
+  post(port, { t: 'res', id, ok: false, error: serializeError(err) });
+}
+
+/**
+ * Await a persistence flush BEFORE acking a mutating op, so an acknowledged
+ * write is durable in IndexedDB when the reply reaches the client. This is
+ * the worker's ONLY durability mechanism: there is no beforeterminate-style
+ * event for a SharedWorker, so a teardown on last-tab close/reload can kill
+ * the worker inside the controller's debounce window — an un-flushed write
+ * would be silently lost (the reload-durability bug).
+ *
+ * "Best-effort" refers to the REPLY, not the flush: a flush failure (e.g.
+ * storage quota) must not turn a successful in-memory mutation into a wire
+ * error, but it IS logged — a silently swallowed flush failure is exactly
+ * how a broken flush contract stays invisible.
+ */
+export async function bestEffortFlush(ctx: HostCtx): Promise<void> {
+  try {
+    await ctx.sandbox.flush?.();
+  } catch (e) {
+    // eslint-disable-next-line no-console
+    console.warn('[pyric worker] persistence flush after acked write failed:', e);
+  }
+}

package/src/serve/worker/host-events.ts

@@ -0,0 +1,94 @@
+/**
+ * SharedWorker host — event-stream subsystem (Pyric Studio keystone).
+ *
+ * Surfaces the sandbox's unified cross-service `onEvent`/`history()` stream over
+ * the port so Studio's Action Center / traffic / rules-debug denial feed see
+ * real activity. Imports only from `./host-context.js` + external packages (no
+ * circular imports).
+ */
+
+import { type HostCtx, type PortLike, post } from './host-context.js';
+import type { SandboxEvent } from 'pyric/sandbox';
+import type { EventSubMessage } from './protocol.js';
+
+// ─── Event-stream subscription (Pyric Studio keystone) ─────────────────────
+//
+// Surfaces the sandbox's unified cross-service `onEvent`/`history()` stream over
+// the port so Studio's Action Center / traffic / rules-debug denial feed see
+// real activity. Architecture mirrors the AUTH fan-out: ONE real
+// `sandbox.onEvent` subscription per worker (lazily wired in {@link ensureEventStream}),
+// and a per-port routing registry telling the host which ports want events. On
+// any event the single sandbox subscription fires once and we fan it out to
+// EVERY subscribed port — so multiple Studio/app tabs share the one backend
+// stream. Events are plain JSON (no codec round-trip; see EventSubMessage).
+
+/** Per-port event-stream subscription registry. Map<port, Set<subId>>. The
+ *  WeakMap is keyed by ctx so multiple in-process hosts (tests) don't collide. */
+const _eventSubs = new WeakMap<HostCtx, Map<PortLike, Set<string>>>();
+
+/** Tracks whether the single real `sandbox.onEvent` subscription is wired. */
+const _eventStreamWired = new WeakSet<HostCtx>();
+
+export function eventSubsFor(ctx: HostCtx): Map<PortLike, Set<string>> {
+  let m = _eventSubs.get(ctx);
+  if (!m) {
+    m = new Map();
+    _eventSubs.set(ctx, m);
+  }
+  return m;
+}
+
+/**
+ * Lazily wire the ONE real `sandbox.onEvent` subscription for this ctx. On every
+ * sandbox event it fans the event out (as a single-element batch) to every port
+ * subscribed to the stream. Idempotent — only the first event sub wires it; the
+ * subscription then lives for the worker's lifetime (cheap, observational).
+ */
+function ensureEventStream(ctx: HostCtx): void {
+  if (_eventStreamWired.has(ctx)) return;
+  _eventStreamWired.add(ctx);
+  ctx.sandbox.onEvent((event) => {
+    broadcastEvents(ctx, [event]);
+  });
+}
+
+/** Fan a batch of events out to every port subscribed to the event stream. */
+function broadcastEvents(ctx: HostCtx, events: readonly SandboxEvent[]): void {
+  const subs = eventSubsFor(ctx);
+  for (const [port, subIds] of subs) {
+    for (const subId of subIds) {
+      post(port, { t: 'event', subId, events });
+    }
+  }
+}
+
+/**
+ * Register an event-stream subscription for a port (Pyric Studio keystone).
+ * Records the (port, subId) so live events reach it, ensures the single real
+ * sandbox subscription is wired, and immediately delivers `sandbox.history()`
+ * (every event so far) as the initial batch — so a late subscriber folds the
+ * full backlog then streams uniformly (mirrors `onEvent` + `history`).
+ */
+export function handleEventSub(ctx: HostCtx, port: PortLike, msg: EventSubMessage): void {
+  ensureEventStream(ctx);
+  const subs = eventSubsFor(ctx);
+  let subIds = subs.get(port);
+  if (!subIds) {
+    subIds = new Set();
+    subs.set(port, subIds);
+  }
+  if (subIds.has(msg.subId)) return; // idempotent
+  subIds.add(msg.subId);
+
+  // Initial fire: the full history snapshot (a defensive copy from the sandbox).
+  post(port, { t: 'event', subId: msg.subId, events: ctx.sandbox.history() });
+}
+
+export function handleEventUnsub(ctx: HostCtx, port: PortLike, subId: string): boolean {
+  const subs = eventSubsFor(ctx);
+  const subIds = subs.get(port);
+  if (!subIds || !subIds.has(subId)) return false;
+  subIds.delete(subId);
+  if (subIds.size === 0) subs.delete(port);
+  return true;
+}

package/src/serve/worker/host-messaging.ts

@@ -0,0 +1,240 @@
+/**
+ * SharedWorker host — messaging subsystem: the broker's documented
+ * worker-host seam, wired (see `pyric/src/messaging/broker/broker.ts`
+ * header — each public broker method is one `messaging.*` op here).
+ *
+ * ONE broker per sandbox (`getMessagingBroker`), shared by every port —
+ * production's one-service-worker-per-origin model. Two seams cross the
+ * transport:
+ *
+ *   OPS   token lifecycle (`getToken`/`deleteToken`), the send plane
+ *         (`send`, topic management), the delivery driver (`deliver`), and
+ *         visibility (`setVisibility`). Send-plane rejections carry the
+ *         broker's captured google.rpc envelope VERBATIM on
+ *         `error.envelope` (plain JSON, structured-clone-safe).
+ *
+ *   SUBS  `messaging.foreground` / `messaging.background` register real
+ *         broker handlers whose payloads forward to the subscribing port as
+ *         snaps. Unsubs ride the ordinary `ctx.subs` registry, so
+ *         `cleanupPort` tears them down like Firestore listeners.
+ *
+ * PER-PORT VISIBILITY — the captured routing rule crossing the transport:
+ * each port that reports `messaging.setVisibility` is ONE window client in
+ * the broker (`setClientVisibility(portId, state)` on the page's
+ * `visibilitychange`). A hidden tab's port marks its client not-visible;
+ * routing is foreground iff ANY visible client (oracle:
+ * `messaging-web-visibility-routing` — visibility, never focus). Port close
+ * removes the client so a dead tab cannot pin foreground routing.
+ *
+ * HOST CAPABILITY GATE: ops exist only when the ctx was built with
+ * `messagingEnabled: true`. Both serve producers enable it because Messaging
+ * is part of the canonical Firebase SDK swap. The disabled path remains for
+ * standalone host construction and focused tests.
+ *
+ * Imports only from `./host-context.js` + external packages (host-auth
+ * precedent — no circular imports).
+ */
+
+import { getMessagingBroker, BrokerSendError } from 'pyric/messaging/internal';
+import type { MessagingBroker } from 'pyric/messaging/internal';
+
+import { type HostCtx, type PortLike, post, ok, fail } from './host-context.js';
+import type { OpMessage, MessagingSubMessage } from './protocol.js';
+
+/** Registration id used when a `messaging.getToken`/`deleteToken` op names
+ *  none — the transport twin of the mirrors' module-default registration. */
+export const DEFAULT_WIRE_REGISTRATION_ID = 'swreg-port-default';
+
+const MESSAGING_METHODS = new Set([
+  'messaging.getToken',
+  'messaging.deleteToken',
+  'messaging.send',
+  'messaging.subscribeToTopic',
+  'messaging.unsubscribeFromTopic',
+  'messaging.deliver',
+  'messaging.setVisibility',
+]);
+
+/** Is this op method part of the messaging surface? (Routing predicate for
+ *  handleMessage — the auth-op precedent.) */
+export function isMessagingOp(method: string): boolean {
+  return MESSAGING_METHODS.has(method);
+}
+
+/** The error every messaging op/sub answers on a host without the capability. */
+function disabledError(): { code: string; message: string } {
+  return {
+    code: 'messaging/disabled',
+    message:
+      'pyric worker: this host was created without Messaging enabled. ' +
+      'Build the worker host ctx with `messagingEnabled: true`.',
+  };
+}
+
+function broker(ctx: HostCtx): MessagingBroker {
+  return getMessagingBroker(ctx.sandbox);
+}
+
+// Module-level mint so client ids never collide across delete/re-add on one
+// broker (a ctx-map-size mint would reuse ids after removal).
+let clientSeq = 0;
+
+/** The port's broker client id, minted on first visibility report. */
+function clientIdFor(ctx: HostCtx, port: PortLike): string {
+  const clients = (ctx.messagingClients ??= new Map());
+  let id = clients.get(port);
+  if (id === undefined) {
+    id = `port-client-${++clientSeq}`;
+    clients.set(port, id);
+  }
+  return id;
+}
+
+/**
+ * Fail a messaging op. A `BrokerSendError` crosses the wire as its captured
+ * envelope (the seam contract): `code` is the envelope's google.rpc status
+ * (`INVALID_ARGUMENT`, `NOT_FOUND`, …), `envelope` the full pinned value.
+ */
+function failMessaging(port: PortLike, id: string, err: unknown): void {
+  if (err instanceof BrokerSendError) {
+    post(port, {
+      t: 'res',
+      id,
+      ok: false,
+      error: {
+        code: err.envelope.error.status,
+        message: err.envelope.error.message,
+        envelope: err.envelope,
+      },
+    });
+    return;
+  }
+  fail(port, id, err);
+}
+
+export async function handleMessagingOp(
+  ctx: HostCtx,
+  port: PortLike,
+  msg: OpMessage,
+): Promise<void> {
+  if (ctx.messagingEnabled !== true) {
+    post(port, { t: 'res', id: msg.id, ok: false, error: disabledError() });
+    return;
+  }
+
+  switch (msg.method) {
+    case 'messaging.getToken': {
+      // Stable per registration (oracle: `messaging-web-token-stability`).
+      try {
+        const token = broker(ctx).getTokenFor(msg.registrationId ?? DEFAULT_WIRE_REGISTRATION_ID);
+        ok(port, msg.id, { token });
+      } catch (e) { failMessaging(port, msg.id, e); }
+      break;
+    }
+
+    case 'messaging.deleteToken': {
+      // Resolves truthy either way (oracle: `messaging-web-deletetoken-unregistered`).
+      try {
+        ok(port, msg.id, broker(ctx).deleteTokenFor(msg.registrationId ?? DEFAULT_WIRE_REGISTRATION_ID));
+      } catch (e) { failMessaging(port, msg.id, e); }
+      break;
+    }
+
+    case 'messaging.send': {
+      // AcceptedSend is plain JSON — replies verbatim. Rejections carry the
+      // captured envelope (see failMessaging).
+      try {
+        const accepted = broker(ctx).send(msg.message, {
+          ...(msg.validateOnly !== undefined ? { validateOnly: msg.validateOnly } : {}),
+        });
+        ok(port, msg.id, accepted);
+      } catch (e) { failMessaging(port, msg.id, e); }
+      break;
+    }
+
+    case 'messaging.subscribeToTopic': {
+      try {
+        ok(port, msg.id, broker(ctx).subscribeToTopic(msg.tokens, msg.topic));
+      } catch (e) { failMessaging(port, msg.id, e); }
+      break;
+    }
+
+    case 'messaging.unsubscribeFromTopic': {
+      try {
+        ok(port, msg.id, broker(ctx).unsubscribeFromTopic(msg.tokens, msg.topic));
+      } catch (e) { failMessaging(port, msg.id, e); }
+      break;
+    }
+
+    case 'messaging.deliver': {
+      // Test/Studio driver — DeliveryResult { route, handlerCount, payload }
+      // is plain JSON. `visibilityState` (the in-page driver's twin) sets THIS
+      // port's client visibility before routing, so `pyric/messaging`'s
+      // `sandbox.deliver(spec)` picks foreground/background over the transport
+      // exactly as in-page: visible → onMessage, hidden → onBackgroundMessage.
+      try {
+        const { visibilityState, ...payload } = msg.spec;
+        if (visibilityState !== undefined) {
+          broker(ctx).setClientVisibility(clientIdFor(ctx, port), visibilityState);
+        }
+        ok(port, msg.id, broker(ctx).deliver(payload));
+      } catch (e) { failMessaging(port, msg.id, e); }
+      break;
+    }
+
+    case 'messaging.setVisibility': {
+      // THE routing input crossing the transport: this port's tab is one
+      // window client; its visibility report updates the broker state the
+      // captured rule routes on.
+      try {
+        broker(ctx).setClientVisibility(clientIdFor(ctx, port), msg.state);
+        ok(port, msg.id, null);
+      } catch (e) { failMessaging(port, msg.id, e); }
+      break;
+    }
+
+    default:
+      fail(port, msg.id, new Error(`Unknown messaging method: ${String(msg.method)}`));
+  }
+}
+
+/**
+ * Register a foreground/background delivery listener for this port. The
+ * broker handler's unsub goes into the ordinary `ctx.subs` registry, so the
+ * generic unsub path and `cleanupPort` both tear it down. Payloads are plain
+ * JSON (`DeliveredPayload`) — no codec round-trip.
+ */
+export function handleMessagingSub(ctx: HostCtx, port: PortLike, msg: MessagingSubMessage): void {
+  if (ctx.messagingEnabled !== true) {
+    // Mirror handleSub's error path: deliver the gate as a snap-error so the
+    // client's error callback fires instead of the sub silently dying.
+    post(port, { t: 'snap', subId: msg.subId, value: { __error: disabledError() } });
+    return;
+  }
+
+  if (!ctx.subs.has(port)) ctx.subs.set(port, new Map());
+  const portSubs = ctx.subs.get(port)!;
+  if (portSubs.has(msg.subId)) return; // idempotent
+
+  const b = broker(ctx);
+  const forward = (payload: unknown): void =>
+    post(port, { t: 'snap', subId: msg.subId, value: payload });
+  const unsub =
+    msg.target === 'messaging.foreground'
+      ? b.onForegroundMessage(forward)
+      : b.onBackgroundMessage(forward);
+  portSubs.set(msg.subId, unsub);
+}
+
+/**
+ * Drop a disconnected port's broker client so its last-reported visibility
+ * stops feeding the routing rule (a closed visible tab must not pin
+ * foreground routing forever). Handler subs are NOT touched here — they
+ * live in `ctx.subs`, which `cleanupPort` already tears down.
+ */
+export function cleanupPortMessaging(ctx: HostCtx, port: PortLike): void {
+  const id = ctx.messagingClients?.get(port);
+  if (id === undefined) return;
+  ctx.messagingClients!.delete(port);
+  broker(ctx).removeClient(id);
+}

package/src/serve/worker/host.ts

@@ -0,0 +1,47 @@
+/**
+ * SharedWorker host — public barrel over the per-family modules under `host/`.
+ *
+ * The host is the SharedWorker's data plane: one `HostCtx` shared across ALL
+ * connected ports, driven per message by `handleMessage(ctx, port, msg)`. It is
+ * deliberately decoupled from `SharedWorkerGlobalScope` so unit tests can drive
+ * it with a REAL pyric sandbox + fake MessagePort objects — no browser or
+ * SharedWorker runtime required. The entry point (`entry.ts`) creates the real
+ * sandbox + db and wires the connecting ports to this module.
+ *
+ * This file re-exports only the host's PUBLIC surface; the implementation lives
+ * in the per-family modules (mirroring the client split under `client/`):
+ *   - `host/core`            shared lens/handle resolution, descriptor → ref
+ *                            resolution, snapshot serialization, op provenance
+ *   - `host/dispatch`        `handleMessage` seam + family routing + `cleanupPort`
+ *   - `host/firestore-reads` getDoc/getDocs/count/aggregate/keyspace ops
+ *   - `host/firestore-writes` set/update/delete/add/batch/txn ops (+ sentinels)
+ *   - `host/rules`           firestore/rtdb rules deploy + status
+ *   - `host/admin-firestore` admin-lens document ops (rules bypass)
+ *   - `host/rtdb`            RTDB modular ops + snapshot→wire shaping
+ *   - `host/storage`         worker-backed Cloud Storage ops + lens resolver
+ *   - `host/connection`      version / state transfer / branches + instance id
+ *   - `host/studio`          runtime confirm-policy + sandbox snapshot
+ *   - `host/subscriptions`   Firestore/RTDB value-subscription registry (#754)
+ *
+ * The already-extracted auth / AI / events / messaging families keep their
+ * sibling `host-*.ts` modules; `host/dispatch` routes to them.
+ *
+ * `HostCtx` + the shared reply/port primitives live in `host-context.ts` (the
+ * engine-free dependency root).
+ */
+
+// Auth surface used by serve-init (ensureAuth) + the per-port session accessor.
+export { ensureAuth, portSession } from './host-auth.js';
+export type { HostCtx, PortLike } from './host-context.js';
+// Instance-id + named-branch surface (part of the host's public shape:
+// serve-init imports getOrCreateInstanceId; tests import the rest).
+export {
+  INSTANCE_ID_KEY,
+  randomUuid,
+  getOrCreateInstanceId,
+  BRANCH_PREFIX,
+  BRANCH_REGISTRY_KEY,
+  listBranchNames,
+} from './host/connection.js';
+// The message dispatcher seam (entry.ts + tests) and per-port teardown.
+export { handleMessage, cleanupPort } from './host/dispatch.js';