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

package/src/serve/entries/runtime.ts

@@ -0,0 +1,540 @@
+/**
+ * `pyric dev` in-page runtime — the shared chunk every served SDK bundle
+ * closes over. One sandbox per page; init payload (rules, future bridge URL)
+ * fetched from `/__pyric/init.json` at module init.
+ *
+ * TOP-LEVEL AWAIT IS LOAD-BEARING: every importer (the auth/firestore bundles,
+ * and therefore the user's app module) is deferred until this module resolves,
+ * so by the time app code runs the rules are deployed — no
+ * "first write raced the ruleset" class of bugs.
+ *
+ * This file is BUNDLED FOR THE BROWSER by `../bundler.ts` (esbuild) — it is
+ * never imported by node-side @pyric/cli code. Bundle splitting must keep it
+ * a single shared chunk: two copies would mean two sandboxes (P0 validation
+ * constraint, design rationale section 9).
+ */
+import {
+  recordBackendOverBlob,
+  serializeToBuckets,
+  bundleRecords,
+} from 'pyric/sandbox';
+import { getFirestore } from 'pyric/firestore';
+import { seedDocuments, setRules, snapshotDocuments } from 'pyric/sandbox/firestore';
+import { getDatabase, sandbox as rtdbSandbox } from 'pyric/database';
+import { getStorageSandbox } from 'pyric/storage';
+import { getAuth, onAuthStateChanged, signOut, sandbox as authOps, type SeedUser } from 'pyric/auth';
+import {
+  callTool as workerCallTool,
+  relayWorkerOp,
+  relayWorkerSub,
+} from '../worker/client.js';
+import { useWorker, workerDb } from './worker-runtime.js';
+import { keepaliveSafe } from './keepalive.js';
+import { toPageOriginWsUrl } from './bridge-url.js';
+import { buildVerifyFixture } from '../../verify/fixture.js';
+import type { InitPayload } from '../init-payload.js';
+import { setupFirebaseActivityGuard } from '../activity-guard.js';
+export { sandbox } from './app-backend.js';
+import { sandbox } from './app-backend.js';
+
+/**
+ * The DEFAULT-ON worker path (Phase 3c): when SharedWorker is available the
+ * `firebase/*` entry adapters route to the worker-hosted sandbox instead of
+ * the in-page one. The worker owns rules/seed/persist/capture/session (it
+ * fetches the SAME `/__pyric/init.json`), so on this path the page MUST NOT
+ * re-run that backend init below — doing so would double-POST captures and
+ * fight the worker over `/__pyric/state`. Unsupported browsers fall back to
+ * the in-page sandbox + the shipped BroadcastChannel sync (strict enhancement).
+ *
+ * `globalThis.__PYRIC_FORCE_INPAGE__` is an explicit opt-out: a host that does
+ * NOT serve the worker bundle (`/__pyric/sdk/worker.js`) sets it before this
+ * module evaluates so the page takes the in-page path instead of trying to load
+ * a worker that 404s. `pyric dev` always serves the worker and never sets it;
+ * the `@pyric/cli/vite` plugin sets it until it serves the worker (M2).
+ */
+/**
+ * The in-page sandbox. On the worker path it is NOT the data backend — it
+ * stays mounted as the FALLBACK primitive. Worker-mode provider UI reads the
+ * worker user directory directly and never constructs a page-local Auth
+ * backend.
+ */
+
+interface ServeDiagnostics {
+  sandboxReady: boolean;
+  rulesDeployed: boolean;
+  databaseRulesDeployed: boolean;
+  storageRulesDeployed: boolean;
+  rulesHash: string | null;
+  databaseRulesHash: string | null;
+  storageRulesHash: string | null;
+  initError: string | null;
+  bridgeConnected: boolean;
+  seededDocs: number;
+  persistEnabled: boolean;
+  /** Epoch ms of the last successful state flush to the server. */
+  lastFlushAt: number | null;
+  /** True when another tab holds the writer lock — this tab won't persist. */
+  persistReadOnly: boolean;
+  /** True when a `--seed` fixture was withheld because the sandbox already
+   *  held restored/lived data (see the seed-docs block below). */
+  seedSkipped: boolean;
+}
+
+declare global {
+  // eslint-disable-next-line no-var
+  var __pyricServe: ServeDiagnostics;
+}
+
+const diagnostics: ServeDiagnostics = {
+  sandboxReady: true,
+  rulesDeployed: false,
+  databaseRulesDeployed: false,
+  storageRulesDeployed: false,
+  rulesHash: null,
+  databaseRulesHash: null,
+  storageRulesHash: null,
+  initError: null,
+  bridgeConnected: false,
+  seededDocs: 0,
+  persistEnabled: false,
+  lastFlushAt: null,
+  persistReadOnly: false,
+  seedSkipped: false,
+};
+globalThis.__pyricServe = diagnostics;
+
+let bridgeUrlFromPayload: string | null = null;
+let activityTokenFromPayload: string | null = null;
+
+// ── init payload: fetch + apply (top-level await — see header) ────────
+// WORKER PATH: skipped — the worker fetches the same init.json and owns
+// rules/seed/persist/capture/session. Running it here too would double-POST
+// captures and fight the worker over the /__pyric/state writer lock.
+if (!useWorker) try {
+  const res = await fetch('/__pyric/init.json');
+  if (!res.ok) throw new Error(`/__pyric/init.json → ${res.status}`);
+  const payload = (await res.json()) as InitPayload;
+  bridgeUrlFromPayload = payload.bridgeUrl;
+  activityTokenFromPayload = payload.activityToken ?? null;
+  // Register RTDB with the persistence registry BEFORE enablePersistence
+  // (below) so the restored tree rides the controller blob and is applied
+  // during restore-on-attach — same eager-registration reasoning as the
+  // worker path (serve-init.ts). `getDatabase(sandbox)` is idempotent
+  // (one backend per sandbox) so a later rules/op call reuses it.
+  getDatabase(sandbox);
+  if (payload.rules) {
+    const lint = setRules(sandbox, payload.rules);
+    if (lint.parseError) {
+      // The server lints before serving, so this is a defensive surface —
+      // loud, but don't brick the page: the sandbox keeps its default rules.
+      throw new Error(
+        `firestore.rules failed to parse in the sandbox: ${JSON.stringify(lint.parseError)}`,
+      );
+    }
+    diagnostics.rulesDeployed = true;
+    diagnostics.rulesHash = payload.rulesHash;
+  }
+  if (payload.databaseRules) {
+    rtdbSandbox.setRules(getDatabase(sandbox), payload.databaseRules);
+    diagnostics.databaseRulesDeployed = true;
+    diagnostics.databaseRulesHash = payload.databaseRulesHash ?? null;
+  }
+  // Open the ONE per-sandbox storage service eagerly: the FIRST open wins the
+  // rules AND the project-scoped IDB name (`pyric-storage:<projectKey>`,
+  // issue #359) — a lazy first open from app code would land on the legacy
+  // shared database. `projectKey` is absent on older servers → legacy name.
+  getStorageSandbox(sandbox, {
+    ...(payload.storageRules ? { rules: payload.storageRules } : {}),
+    ...(payload.projectKey ? { projectId: payload.projectKey } : {}),
+  });
+  if (payload.storageRules) {
+    diagnostics.storageRulesDeployed = true;
+    diagnostics.storageRulesHash = payload.storageRulesHash;
+  }
+  // Auth users land first in either mode (persist restore or state-file
+  // fixture) so restored docs' owner uids resolve in rules and the session
+  // restore below has a DB to restore into.
+  if (payload.authUsers && payload.authUsers.length > 0) {
+    authOps.seedUsers(getAuth(sandbox), payload.authUsers as unknown as SeedUser[]);
+  }
+  if (!payload.persist && payload.seedState) {
+    // ── ephemeral fixture (`--seed <state-file>`): restore the blob through
+    // the persistence controller's OWN deserializer (wrapper re-hydration —
+    // seedDocuments on raw marker JSON would break instanceof in rules) via
+    // a read-only backend. Writes go nowhere: ephemeral stays ephemeral.
+    const seedSnap = payload.seedState as {
+      firestore?: Record<string, Record<string, unknown>>;
+      services?: Record<string, unknown>;
+    };
+    const fixtureBundle = bundleRecords(
+      serializeToBuckets(seedSnap.firestore ?? {}, seedSnap.services ?? {}, 0),
+    );
+    // NOTE (pre-mortem #6b): this attaches a PERMANENT controller whose
+    // write() is a no-op — so every later mutation in this page pays the
+    // whole-state serialize cost to feed a sink. pyric exposes no
+    // `disablePersistence`/dispose, so a one-shot restore isn't possible from
+    // here without a pyric change (tracked as a pyric follow-up). Accepted:
+    // fixture pages are demo-sized; the cost is bounded and invisible to
+    // correctness.
+    await sandbox.enablePersistence({
+      key: 'pyric-serve-fixture',
+      injectedBackend: recordBackendOverBlob({
+        read: async () => fixtureBundle,
+        write: async () => {},
+        clear: async () => {},
+      }),
+    });
+    const docs = (payload.seedState as { firestore?: Record<string, unknown> }).firestore;
+    diagnostics.seededDocs = docs ? Object.keys(docs).length : 0;
+  }
+  if (payload.persist) {
+    // ── persist mode (flow doc section 3c): the substrate is durable. The
+    // sandbox's OWN persistence controller with an HTTP backend over
+    // /__pyric/state — it owns restore-on-attach (wrapper re-hydration),
+    // debounced auto-flush, and the beforeunload safety flush.
+    const section = (name: string): string => `/__pyric/state?section=${name}`;
+    // Single-writer lock (pre-mortem #3): a per-page id claims the writer
+    // role on first flush; a second tab gets 423 and drops to read-only so
+    // it can't erase this tab's world. The server frees a stale lock, so a
+    // reload after the writer closed can reclaim it.
+    const writerId =
+      typeof crypto !== 'undefined' && crypto.randomUUID ? crypto.randomUUID() : `w-${Date.now()}`;
+    const writerHeaders = { 'content-type': 'application/json', 'x-pyric-writer': writerId };
+    let readOnly = false;
+    const lostWriterLock = (): void => {
+      if (readOnly) return;
+      readOnly = true;
+      diagnostics.persistReadOnly = true;
+      console.warn(
+        '[pyric dev] another tab is the persist writer — THIS tab is read-only ' +
+          '(your changes here will NOT be saved). Close the other tab and reload to take over.',
+      );
+    };
+    await sandbox.enablePersistence({
+      key: 'pyric-serve',
+      injectedBackend: recordBackendOverBlob({
+        async read() {
+          const res = await fetch(section('firestore'));
+          return res.status === 200 ? await res.text() : null;
+        },
+        async write(value) {
+          if (readOnly) return; // a non-writer tab silently no-ops its flushes
+          const res = await fetch(section('firestore'), {
+            method: 'POST',
+            headers: writerHeaders,
+            body: value,
+            // The controller's beforeunload flush fires THIS write as the
+            // page is leaving; a plain fetch is aborted on unload (pre-mortem
+            // #1 — the "crash-only" claim was wrong). `keepalive` lets a
+            // small final flush survive unload. It's capped (~64KB across
+            // all keepalive requests), so large states skip it and warn
+            // once — those lose the final unsaved delta on tab close
+            // (reload-based flushes are unaffected).
+            keepalive: keepaliveSafe(value),
+          });
+          if (res.status === 423) return lostWriterLock();
+          if (!res.ok) throw new Error(`state flush → ${res.status}`);
+          diagnostics.lastFlushAt = Date.now();
+        },
+        async clear() {
+          if (readOnly) return;
+          await fetch(section('firestore'), { method: 'POST', headers: writerHeaders, body: 'null' });
+        },
+      }),
+    });
+    diagnostics.persistEnabled = true;
+
+    // Heartbeat: keep an alive-but-idle writer's lock fresh. PUT refreshes
+    // the lock WITHOUT writing state (a POST would clobber). Release on
+    // pagehide so another tab can take over promptly.
+    const heartbeat = setInterval(() => {
+      if (readOnly) return;
+      void fetch('/__pyric/state', { method: 'PUT', headers: writerHeaders }).then((res) => {
+        if (res.status === 423) {
+          lostWriterLock();
+          clearInterval(heartbeat);
+        }
+      }, () => {});
+    }, 20_000);
+    if (typeof window !== 'undefined') {
+      window.addEventListener('pagehide', () => {
+        clearInterval(heartbeat);
+        if (!readOnly) {
+          fetch('/__pyric/state', { method: 'DELETE', headers: writerHeaders, keepalive: true }).catch(() => {});
+        }
+      });
+    }
+
+    // Auth user-DB changes flush separately (the controller's blob is
+    // firestore-only). Debounced; exportUsers→seedUsers round-trips.
+    const auth = getAuth(sandbox);
+    let authFlushTimer: ReturnType<typeof setTimeout> | null = null;
+    authOps.subscribeUsers(auth, () => {
+      if (readOnly) return;
+      if (authFlushTimer) clearTimeout(authFlushTimer);
+      authFlushTimer = setTimeout(() => {
+        void fetch(section('auth'), {
+          method: 'POST',
+          headers: writerHeaders,
+          body: JSON.stringify({ users: authOps.exportUsers(auth) }),
+        }).then(
+          (res) => {
+            if (res.status === 423) lostWriterLock();
+            else if (res.ok) diagnostics.lastFlushAt = Date.now();
+          },
+          (e) => console.warn('[pyric dev] auth state flush failed:', e),
+        );
+      }, 500);
+    });
+  }
+  if (payload.capture) {
+    // ── capture mode (the write-side of the pyric verify loop): whenever
+    // the sandbox changes, push a snapshot of the full session fixture
+    // (rules + history + firestore state) to /__pyric/capture. The server
+    // writes it verbatim to `.pyric/last-session.json` so `pyric verify`
+    // can replay without any extra arguments. This is independent of
+    // --persist — capture is about the verify loop, persist is about
+    // cross-reload durability.
+    const flushCapture = (): void => {
+      const rtdbState =
+        payload.databaseRules || sandbox.history().some((event) => event.service === 'rtdb')
+          ? rtdbSandbox.snapshotState(getDatabase(sandbox))
+          : undefined;
+      const auth = getAuth(sandbox);
+      const body = JSON.stringify(buildVerifyFixture({
+        sandbox,
+        firestoreRules: payload.rules,
+        rtdbRules: payload.databaseRules ?? null,
+        rtdbState,
+        rtdbDatabaseUrl: payload.databaseUrl ?? null,
+        authState: {
+          users: authOps.exportUsers(auth),
+          currentUser: auth.currentUser,
+        },
+      }));
+      fetch('/__pyric/capture', {
+        method: 'POST',
+        headers: { 'content-type': 'application/json' },
+        body,
+        keepalive: keepaliveSafe(body),
+      }).catch(() => {});
+    };
+
+    // Debounced flush on every sandbox event — coalesces rapid writes (e.g.
+    // seeding multiple docs) into a single push. 400ms matches the cadence
+    // of the persist auth flush; small enough to feel live, large enough to
+    // avoid one-POST-per-write on bulk ops.
+    let captureTimer: ReturnType<typeof setTimeout> | null = null;
+    sandbox.onEvent(() => {
+      if (captureTimer) clearTimeout(captureTimer);
+      captureTimer = setTimeout(flushCapture, 400);
+    });
+
+    // Unload flush — best-effort, keepalive. Separate from any persist
+    // pagehide listener so they don't interfere.
+    if (typeof window !== 'undefined') {
+      window.addEventListener('pagehide', () => {
+        flushCapture();
+      });
+    }
+  }
+  if (payload.seed && Object.keys(payload.seed).length > 0) {
+    // A seed fixture applies only into an empty home — mirrors the worker's
+    // guard (serve/worker/serve-init.ts): by this point any --persist restore
+    // above has already run, so an existing document means lived/restored
+    // data, not a blank slate. Never stomp it with a fixture.
+    const existing = Object.keys(snapshotDocuments(sandbox)).length > 0;
+    if (existing) {
+      diagnostics.seedSkipped = true;
+      console.info(
+        '[pyric dev] --seed skipped: the sandbox already has restored data — the fixture would ' +
+          'have overwritten it. Use `--persist --fresh` to discard existing state and re-seed.',
+      );
+    } else {
+      // Admin-style fixture load (bypasses rules) — runs before app code
+      // (top-level await), so the app's first render sees the seeded state.
+      seedDocuments(sandbox, payload.seed);
+      diagnostics.seededDocs = Object.keys(payload.seed).length;
+    }
+  }
+} catch (e) {
+  diagnostics.initError = e instanceof Error ? e.message : String(e);
+  console.error(
+    '[pyric dev] init failed — the sandbox is running WITHOUT your project rules:',
+    diagnostics.initError,
+  );
+}
+
+// Unsupported/forced-in-page browsers own a real page-local sandbox rather
+// than the SharedWorker backend, so they install the same default-on guard at
+// this feed seam. Top-level await keeps this in place before application code.
+if (!useWorker && activityTokenFromPayload) {
+  setupFirebaseActivityGuard(
+    {
+      history: () => sandbox.history(),
+      subscribe: (listener) => sandbox.onEvent(listener),
+    },
+    fetch,
+    activityTokenFromPayload,
+  );
+}
+
+// ── provenance (flow doc section 3a): make the shim's presence unmistakable.
+// Source says `firebase/*`; what runs is the pyric sandbox — say so loudly
+// once, and explain any stack frame that points into /__pyric/sdk/. ────────
+console.info(
+  `[pyric dev] firebase/* on this page is served by the pyric sandbox` +
+    (useWorker
+      ? ' in a SharedWorker (one backend for all tabs; rules/seed/persist owned by the worker)'
+      : diagnostics.rulesHash || diagnostics.databaseRulesHash || diagnostics.storageRulesHash
+        ? ' (project rules loaded)'
+        : ' (no project rules)') +
+    ` — diagnostics: globalThis.__pyricServe`,
+);
+
+let provenanceHintShown = false;
+function explainSandboxFrame(stackOrUrl: string | undefined): void {
+  if (provenanceHintShown || !stackOrUrl || !stackOrUrl.includes('/__pyric/sdk/')) return;
+  provenanceHintShown = true;
+  console.info(
+    '[pyric dev] the error above originates in the pyric sandbox shim serving firebase/*, ' +
+      'not the real Firebase SDK — behavior can differ where COMPAT coverage is incomplete.',
+  );
+}
+if (typeof window !== 'undefined') {
+  window.addEventListener('error', (e) =>
+    explainSandboxFrame(e.error instanceof Error ? (e.error.stack ?? e.filename) : e.filename),
+  );
+  window.addEventListener('unhandledrejection', (e) =>
+    explainSandboxFrame(e.reason instanceof Error ? e.reason.stack : undefined),
+  );
+}
+
+// ── bridge peer (only when `pyric dev --bridge` put a URL in the payload;
+//    dynamic import so bridge-less pages never load the client chunk) ─────
+async function connectBridgePeer(rawUrl: string): Promise<void> {
+  // Re-anchor the bridge WS to THIS page's origin so it reaches the server the
+  // page was actually served from over Tailscale / a LAN IP / https, not the
+  // server's baked-in localhost. See bridge-url.ts.
+  const url = toPageOriginWsUrl(rawUrl, window.location);
+  const { connectBridge } = await import('../../bridge/client/bridge.js');
+  // On the worker path, route agent tool-calls THROUGH the SharedWorker so the
+  // agent shares the one sandbox the app + Studio use (no separate in-page
+  // backend). Off the worker path (in-page fallback), dispatch in-page as before.
+  if (useWorker && workerDb) {
+    const wdb = workerDb;
+    connectBridge(sandbox, {
+      url,
+      dispatcher: (_sandbox, name, args) => workerCallTool(wdb, name, args),
+      // Generic worker relay (remote sandbox, slice 1): server-side Node code
+      // (`connectRemoteSandbox`) reaches THIS page's SharedWorker through the
+      // bridge — ops and snap-delivering subscriptions pass straight through
+      // to the one sandbox the app + Studio + agent share.
+      workerRelay: {
+        op: (op) => relayWorkerOp(wdb, op),
+        subscribe: (sub, onValue) => relayWorkerSub(wdb, sub, onValue),
+      },
+    });
+  } else {
+    connectBridge(sandbox, { url });
+  }
+  diagnostics.bridgeConnected = true;
+  console.info('[pyric dev] sandbox registered with the MCP bridge at', url);
+}
+if (bridgeUrlFromPayload) {
+  // In-page path: bridgeUrlFromPayload came from the (already-blocking) init
+  // block above, so connect inline.
+  try {
+    await connectBridgePeer(bridgeUrlFromPayload);
+  } catch (e) {
+    console.error('[pyric dev] bridge connect failed:', e instanceof Error ? e.message : String(e));
+  }
+} else if (useWorker) {
+  // Worker path: the worker owns serve-init, so the page skipped the init.json
+  // fetch. Discover the bridge URL (the agent routes its tool-calls THROUGH the
+  // worker) in a FIRE-AND-FORGET task so app boot is NEVER blocked — runtime.ts
+  // is on the load-bearing top-level-await path, and the agent connecting a beat
+  // later is fine. Bridge-less pages just read a null bridgeUrl and stop.
+  void (async () => {
+    try {
+      const res = await fetch('/__pyric/init.json');
+      const url = res.ok ? ((await res.json()) as InitPayload).bridgeUrl : null;
+      if (url) await connectBridgePeer(url);
+    } catch (e) {
+      console.error('[pyric dev] bridge connect failed:', e instanceof Error ? e.message : String(e));
+    }
+  })();
+}
+
+// ── cross-tab realtime sync — wire AFTER sandbox + auth are fully set up ──────
+//
+// Two independent channels, two independent kinds of state:
+//
+//   Channel 1 — Firestore writes (`pyric:serve:tabsync`):
+//     `sandbox.enableTabSync` owns the channel entirely. It broadcasts every
+//     committed Firestore write event to peer tabs and runs the hello/state
+//     late-join handshake so a freshly-opened tab inherits the current
+//     Firestore documents. A write in Tab A fires `onSnapshot` listeners in Tab B
+//     — restoring production's cross-client realtime without a server.
+//
+//   Channel 2 — Auth state (`pyric:serve:auth-sync`):
+//     Auth lives outside the Firestore environment so `enableTabSync` can't
+//     carry it. `wireAuthTabSync` bridges sign-in/sign-out/user-DB changes
+//     over its own BroadcastChannel using a full-state protocol (see
+//     `tab-sync-wiring.ts` for the detailed protocol + echo-guard rationale).
+//
+// Both are no-ops in non-browser environments (`BroadcastChannel` absent).
+//
+// WORKER PATH: retired. The SharedWorker IS the single backend for all tabs, so
+// cross-tab Firestore + auth are automatic — the in-page sandbox these channels
+// would sync isn't the data backend here. Kept ONLY for the in-page fallback
+// (the tier the plan designates for browsers without SharedWorker).
+if (!useWorker && typeof BroadcastChannel !== 'undefined') {
+  // 1. Firestore cross-tab — library primitive does the heavy lifting.
+  sandbox.enableTabSync({
+    channel: new BroadcastChannel('pyric:serve:tabsync'),
+  });
+
+  // 2. Auth cross-tab — our own bridge (see tab-sync-wiring.ts).
+  //    Dynamic import keeps the module out of the critical path; the channel
+  //    is opened synchronously above so `hello` is posted as soon as the
+  //    listener is wired (wireAuthTabSync handles ordering internally).
+  void import('./tab-sync-wiring.js').then(({ wireAuthTabSync }) => {
+    wireAuthTabSync(
+      getAuth(sandbox),
+      // Cast: authOps's generics are narrowed to `Auth` which is exactly what
+      // wireAuthTabSync expects; `as` here avoids a deep generic unification
+      // that TypeScript can't resolve across module boundaries.
+      authOps as import('./tab-sync-wiring.js').AuthOps,
+      onAuthStateChanged,
+      signOut,
+    );
+  });
+}
+
+// ── rules hot-reload (SSE) — `pyric dev` watches firestore.rules and
+//    broadcasts; we re-deploy in place, no page refresh. EventSource is
+//    browser-only; guarded so the bundle stays inert under other runtimes. ──
+// IN-PAGE PATH ONLY: open a per-tab SSE to re-deploy rules to the in-page
+// sandbox. On the WORKER path the SharedWorker owns ONE hot-reload stream for
+// the whole origin (see entry.ts), so tabs open NO SSE connection — multi-tab
+// pages would otherwise exhaust Chrome's ~6-connections-per-origin cap and a
+// later tab's navigation would hang until an earlier tab closed.
+if (!useWorker && typeof EventSource !== 'undefined') {
+  const events = new EventSource('/__pyric/events');
+  events.addEventListener('rules-changed', (e) => {
+    try {
+      const { rules, rulesHash } = JSON.parse((e as MessageEvent).data as string) as {
+        rules: string;
+        rulesHash: string;
+      };
+      const lint = setRules(sandbox, rules);
+      if (lint.parseError) throw new Error(JSON.stringify(lint.parseError));
+      diagnostics.rulesDeployed = true;
+      diagnostics.rulesHash = rulesHash;
+      console.info(`[pyric dev] firestore.rules hot-reloaded (hash ${rulesHash})`);
+    } catch (err) {
+      console.error('[pyric dev] rules hot-reload failed:', err instanceof Error ? err.message : String(err));
+    }
+  });
+}

package/src/serve/entries/session-store.ts

@@ -0,0 +1,97 @@
+/**
+ * Auth session persistence for `pyric dev` — the one genuine
+ * client-fidelity item in the persistence model (flow doc section 3c): real
+ * Firebase keeps you signed in across reloads by DEFAULT
+ * (`browserLocalPersistence`), so the served sandbox does too.
+ *
+ * The user *database* persists with the substrate (`--persist`); the
+ * *session* persists like the real client — independent of data mode, in
+ * web storage, honoring `setPersistence` semantics:
+ *
+ *   LOCAL  (default) → localStorage     (survives reload + browser restart)
+ *   SESSION          → sessionStorage   (survives reload, not the tab)
+ *   NONE             → nothing stored
+ *
+ * A restored session only resolves when the referenced uid still exists in
+ * the sandbox user DB — so ephemeral mode drops helper-created sessions on
+ * reload, consistently (`sandbox.restoreSession` throws, we clear).
+ *
+ * Pure over injected Storage objects so the logic is bun-testable; the
+ * browser wiring (real storages, `onAuthStateChanged` recording, restore at
+ * init) lives in the entries that import this.
+ */
+
+export type SessionMode = 'LOCAL' | 'SESSION' | 'NONE';
+
+const DEFAULT_KEY = 'pyric:serve:auth-session';
+
+export interface SessionStores {
+  local: Pick<Storage, 'getItem' | 'setItem' | 'removeItem'>;
+  session: Pick<Storage, 'getItem' | 'setItem' | 'removeItem'>;
+}
+
+export interface StoredSession {
+  uid: string;
+}
+
+export class SessionStore {
+  private mode: SessionMode = 'LOCAL'; // firebase's default persistence
+  private readonly key: string;
+
+  constructor(
+    private readonly stores: SessionStores,
+    appName = '[DEFAULT]',
+  ) {
+    this.key = appName === '[DEFAULT]'
+      ? DEFAULT_KEY
+      : `${DEFAULT_KEY}:${encodeURIComponent(appName)}`;
+  }
+
+  /** `setPersistence` parity: switch the backing store and MIGRATE any
+   *  current session into it (the real SDK carries the session over). */
+  setMode(mode: SessionMode): void {
+    const current = this.load();
+    this.clear();
+    this.mode = mode;
+    if (current) this.save(current.uid);
+  }
+
+  save(uid: string): void {
+    this.clear(); // a session lives in exactly one store
+    if (this.mode === 'NONE') return;
+    this.backing().setItem(this.key, JSON.stringify({ uid } satisfies StoredSession));
+  }
+
+  /** Reads BOTH storages (localStorage first — matches lookup order when a
+   *  prior page used a different mode). Restoring also restores the mode:
+   *  the initial Auth observer resaves the user, and must not migrate a
+   *  SESSION record into the default LOCAL slot. */
+  load(): StoredSession | null {
+    for (const [mode, store] of [
+      ['LOCAL', this.stores.local],
+      ['SESSION', this.stores.session],
+    ] as const) {
+      const raw = store.getItem(this.key);
+      if (!raw) continue;
+      try {
+        const parsed = JSON.parse(raw) as StoredSession;
+        if (parsed && typeof parsed.uid === 'string') {
+          this.mode = mode;
+          return parsed;
+        }
+      } catch {
+        store.removeItem(this.key); // corrupt → drop, never throw at page init
+      }
+    }
+    return null;
+  }
+
+  clear(): void {
+    this.stores.local.removeItem(this.key);
+    this.stores.session.removeItem(this.key);
+  }
+
+  private backing(): SessionStores['local'] {
+    return this.mode === 'SESSION' ? this.stores.session : this.stores.local;
+  }
+}