pyric 0.0.1 → 0.1.0-alpha.7

package/dist/sandbox/persistence/serialize.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Snapshot serialization for sandbox persistence.
+ *
+ * Goes in two directions:
+ *
+ *   serialize: SandboxSnapshot → string
+ *     `JSON.stringify` already does most of the work. Each wrapper
+ *     type (Timestamp, Bytes, LatLng, Duration, Reference, Path,
+ *     Vector) ships a `toJSON()` that emits a marker shape — those
+ *     come for free.
+ *
+ *   deserialize: string → SandboxSnapshot
+ *     Parse, then walk the tree and re-wrap any marker shape back into
+ *     its wrapper class instance. Rule evaluation depends on `instanceof
+ *     Timestamp` checks etc., so restored docs must carry the class
+ *     instances, not the marker objects.
+ *
+ * Schema version is captured in the blob so future format changes can
+ * be detected and reported (rather than corrupting silently).
+ */
+import { rehydrateDocValue } from '../../firestore-values/index.js';
+export { rehydrateDocValue };
+export declare class PersistenceSchemaError extends Error {
+    constructor(message: string);
+}
+/** Serialize a sandbox snapshot to a string blob ready for storage. */
+export declare function serializeSnapshot(firestore: Record<string, Record<string, unknown>>, services?: Record<string, unknown>): string;
+/**
+ * Parsed result of a persisted blob.
+ *
+ * `firestore` is the rehydrated Firestore document map — class
+ * instances (Timestamp, Bytes, etc.) are restored from their marker
+ * shapes. `services` is the raw (no rehydration needed) per-service
+ * state map; each entry is whatever the service's
+ * `PersistableService.snapshot()` emitted.
+ */
+export interface DeserializedSnapshot {
+    firestore: Record<string, Record<string, unknown>>;
+    services: Record<string, unknown>;
+}
+/**
+ * Parse a stored blob back into a snapshot. Throws
+ * {@link PersistenceSchemaError} on an unrecognized version or
+ * malformed input.
+ *
+ * **v1 compatibility:** v1 blobs (no `services` field) are accepted
+ * and treated as having an empty services map. This is the clean
+ * forward-compatible choice for a pre-release library: old dev blobs
+ * just don't have auth users, which is correct — the user hadn't opted
+ * into auth persistence yet. New writes always emit v2.
+ */
+export declare function deserializeSnapshot(raw: string): DeserializedSnapshot;
+//# sourceMappingURL=serialize.d.ts.map

package/dist/sandbox/persistence/serialize.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"serialize.d.ts","sourceRoot":"","sources":["../../../src/sandbox/persistence/serialize.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAOH,OAAO,EAAE,iBAAiB,EAAE,MAAM,iCAAiC,CAAC;AAKpE,OAAO,EAAE,iBAAiB,EAAE,CAAC;AAqB7B,qBAAa,sBAAuB,SAAQ,KAAK;gBACnC,OAAO,EAAE,MAAM;CAI5B;AAED,uEAAuE;AACvE,wBAAgB,iBAAiB,CAC/B,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,EAClD,QAAQ,GAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAM,GACrC,MAAM,CAQR;AAED;;;;;;;;GAQG;AACH,MAAM,WAAW,oBAAoB;IACnC,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;IACnD,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACnC;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,MAAM,GAAG,oBAAoB,CAgCrE"}

package/dist/sandbox/persistence/serialize.js

@@ -0,0 +1,98 @@
+/**
+ * Snapshot serialization for sandbox persistence.
+ *
+ * Goes in two directions:
+ *
+ *   serialize: SandboxSnapshot → string
+ *     `JSON.stringify` already does most of the work. Each wrapper
+ *     type (Timestamp, Bytes, LatLng, Duration, Reference, Path,
+ *     Vector) ships a `toJSON()` that emits a marker shape — those
+ *     come for free.
+ *
+ *   deserialize: string → SandboxSnapshot
+ *     Parse, then walk the tree and re-wrap any marker shape back into
+ *     its wrapper class instance. Rule evaluation depends on `instanceof
+ *     Timestamp` checks etc., so restored docs must carry the class
+ *     instances, not the marker objects.
+ *
+ * Schema version is captured in the blob so future format changes can
+ * be detected and reported (rather than corrupting silently).
+ */
+// The marker-based value codec lives in a STANDALONE leaf module
+// (`firestore-values`) so the SharedWorker client can rehydrate doc values
+// WITHOUT pulling the rules engine. `serialize.ts` re-uses that same codec so
+// there is exactly one rehydrate implementation — the IDB persistence format
+// and the MessagePort wire format can't drift.
+import { rehydrateDocValue } from '../../firestore-values/index.js';
+// Re-exported so existing consumers (`sandbox/persistence/index.ts` →
+// `pyric/sandbox`) keep their import path; the implementation now lives in the
+// leaf codec.
+export { rehydrateDocValue };
+/**
+ * Current on-disk format version.
+ *
+ * v1 → v2 (this release): added `services: Record<string, unknown>` to
+ * persist plugged-in service state (auth users, etc.). v1 blobs are
+ * accepted on read with `services` defaulted to `{}` — the forward-
+ * compatible choice for a pre-release library where old blobs are
+ * dev-only and disposable. New writes always emit v2.
+ */
+const SCHEMA_VERSION = 2;
+export class PersistenceSchemaError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'PersistenceSchemaError';
+    }
+}
+/** Serialize a sandbox snapshot to a string blob ready for storage. */
+export function serializeSnapshot(firestore, services = {}) {
+    const payload = {
+        version: SCHEMA_VERSION,
+        savedAt: Date.now(),
+        firestore,
+        services,
+    };
+    return JSON.stringify(payload);
+}
+/**
+ * Parse a stored blob back into a snapshot. Throws
+ * {@link PersistenceSchemaError} on an unrecognized version or
+ * malformed input.
+ *
+ * **v1 compatibility:** v1 blobs (no `services` field) are accepted
+ * and treated as having an empty services map. This is the clean
+ * forward-compatible choice for a pre-release library: old dev blobs
+ * just don't have auth users, which is correct — the user hadn't opted
+ * into auth persistence yet. New writes always emit v2.
+ */
+export function deserializeSnapshot(raw) {
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch (e) {
+        throw new PersistenceSchemaError(`Persisted blob is not valid JSON: ${e.message}`);
+    }
+    if (typeof parsed !== 'object' || parsed === null) {
+        throw new PersistenceSchemaError('Persisted blob is not an object');
+    }
+    // Accept v1 (no services) and v2 (with services). Any other version
+    // is unrecognized — quarantine it so we don't silently corrupt state.
+    if (parsed.version !== 1 && parsed.version !== 2) {
+        throw new PersistenceSchemaError(`Persisted blob has version ${String(parsed.version)}, expected 1 or 2`);
+    }
+    if (typeof parsed.firestore !== 'object' || parsed.firestore === null) {
+        throw new PersistenceSchemaError('Persisted blob has no firestore field');
+    }
+    const firestore = {};
+    for (const [path, data] of Object.entries(parsed.firestore)) {
+        firestore[path] = rehydrateDocValue(data);
+    }
+    // v1 blobs lack `services` — default to {} so the restore path
+    // proceeds without error. No auth users in the blob = no auth restore.
+    const services = (parsed.services !== undefined && typeof parsed.services === 'object' && parsed.services !== null)
+        ? parsed.services
+        : {};
+    return { firestore, services };
+}
+//# sourceMappingURL=serialize.js.map

package/dist/sandbox/persistence/serialize.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"serialize.js","sourceRoot":"","sources":["../../../src/sandbox/persistence/serialize.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,iEAAiE;AACjE,2EAA2E;AAC3E,8EAA8E;AAC9E,6EAA6E;AAC7E,+CAA+C;AAC/C,OAAO,EAAE,iBAAiB,EAAE,MAAM,iCAAiC,CAAC;AAEpE,sEAAsE;AACtE,+EAA+E;AAC/E,cAAc;AACd,OAAO,EAAE,iBAAiB,EAAE,CAAC;AAE7B;;;;;;;;GAQG;AACH,MAAM,cAAc,GAAG,CAAU,CAAC;AAUlC,MAAM,OAAO,sBAAuB,SAAQ,KAAK;IAC/C,YAAY,OAAe;QACzB,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,wBAAwB,CAAC;IACvC,CAAC;CACF;AAED,uEAAuE;AACvE,MAAM,UAAU,iBAAiB,CAC/B,SAAkD,EAClD,WAAoC,EAAE;IAEtC,MAAM,OAAO,GAAmB;QAC9B,OAAO,EAAE,cAAc;QACvB,OAAO,EAAE,IAAI,CAAC,GAAG,EAAE;QACnB,SAAS;QACT,QAAQ;KACT,CAAC;IACF,OAAO,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,CAAC;AACjC,CAAC;AAgBD;;;;;;;;;;GAUG;AACH,MAAM,UAAU,mBAAmB,CAAC,GAAW;IAC7C,IAAI,MAAsB,CAAC;IAC3B,IAAI,CAAC;QACH,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAmB,CAAC;IAC7C,CAAC;IAAC,OAAO,CAAC,EAAE,CAAC;QACX,MAAM,IAAI,sBAAsB,CAC9B,qCAAsC,CAAW,CAAC,OAAO,EAAE,CAC5D,CAAC;IACJ,CAAC;IACD,IAAI,OAAO,MAAM,KAAK,QAAQ,IAAI,MAAM,KAAK,IAAI,EAAE,CAAC;QAClD,MAAM,IAAI,sBAAsB,CAAC,iCAAiC,CAAC,CAAC;IACtE,CAAC;IACD,oEAAoE;IACpE,sEAAsE;IACtE,IAAI,MAAM,CAAC,OAAO,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,KAAK,CAAC,EAAE,CAAC;QACjD,MAAM,IAAI,sBAAsB,CAC9B,8BAA8B,MAAM,CAAC,MAAM,CAAC,OAAO,CAAC,mBAAmB,CACxE,CAAC;IACJ,CAAC;IACD,IAAI,OAAO,MAAM,CAAC,SAAS,KAAK,QAAQ,IAAI,MAAM,CAAC,SAAS,KAAK,IAAI,EAAE,CAAC;QACtE,MAAM,IAAI,sBAAsB,CAAC,uCAAuC,CAAC,CAAC;IAC5E,CAAC;IACD,MAAM,SAAS,GAA4C,EAAE,CAAC;IAC9D,KAAK,MAAM,CAAC,IAAI,EAAE,IAAI,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC,SAAS,CAAC,EAAE,CAAC;QAC5D,SAAS,CAAC,IAAI,CAAC,GAAG,iBAAiB,CAAC,IAAI,CAA4B,CAAC;IACvE,CAAC;IACD,+DAA+D;IAC/D,uEAAuE;IACvE,MAAM,QAAQ,GAAG,CAAC,MAAM,CAAC,QAAQ,KAAK,SAAS,IAAI,OAAO,MAAM,CAAC,QAAQ,KAAK,QAAQ,IAAI,MAAM,CAAC,QAAQ,KAAK,IAAI,CAAC;QACjH,CAAC,CAAE,MAAM,CAAC,QAAoC;QAC9C,CAAC,CAAC,EAAE,CAAC;IACP,OAAO,EAAE,SAAS,EAAE,QAAQ,EAAE,CAAC;AACjC,CAAC"}

package/dist/sandbox/persistence/types.d.ts

@@ -0,0 +1,118 @@
+/**
+ * Public types for `pyric/sandbox` persistence. The sandbox itself is
+ * an in-memory dev Firestore; persistence lets a host (browser
+ * playground, agent harness) snapshot the sandbox's data to a backend
+ * and restore it on next init — turning the sandbox into the local
+ * Firestore for a long-running app session.
+ *
+ * The IndexedDB backend is the default in browsers; `memory` is the
+ * opt-out (same as not enabling persistence at all, but useful for
+ * tests that exercise the controller). Future backends (filesystem,
+ * remote KV) plug in via the `PersistenceBackend` contract — `key` is
+ * always the bucket name.
+ */
+/**
+ * Minimal web-storage-like contract the session persistence controller
+ * reads/writes. Matches the `localStorage` / `sessionStorage` browser
+ * API subset that `pyric dev`'s `SessionStore` already uses, so
+ * browsers pass real storages and tests pass in-memory Map-backed fakes.
+ *
+ * Why the minimal subset (get/set/remove) instead of the full
+ * `Storage` interface: this library targets multiple environments
+ * (browser, Bun, Node) and the full `Storage` interface carries
+ * length + key() + clear() that aren't needed here — narrowing the
+ * contract keeps tests simple and Node/Bun hosts from having to
+ * implement a complete polyfill.
+ */
+export interface WebStorageLike {
+    getItem(key: string): string | null;
+    setItem(key: string, value: string): void;
+    removeItem(key: string): void;
+}
+/** Controller options. See {@link Sandbox.enablePersistence}. */
+export interface SandboxPersistenceOptions {
+    /**
+     * IndexedDB database name (or generic bucket key for other backends).
+     * Different keys persist to different storage locations — use one
+     * key per logical sandbox if you run several in parallel.
+     */
+    key: string;
+    /**
+     * Storage backend. `indexedDB` requires a browser environment; in
+     * non-browser hosts (Bun, Node, tests) the controller falls back to
+     * `memory` automatically unless an `injectedBackend` is supplied.
+     * Default: `indexedDB`.
+     */
+    backend?: 'indexedDB' | 'memory';
+    /**
+     * Debounce window before write events are flushed to the backend.
+     * Buffers rapid bursts (e.g., a batch of seed writes) into one flush.
+     * Default: 250ms.
+     */
+    flushIntervalMs?: number;
+    /**
+     * Override the backend with an injected implementation. Used by tests
+     * and hosts that have their own storage adapter. When set, `backend`
+     * is ignored.
+     */
+    injectedBackend?: PersistenceBackend;
+    /**
+     * Optional web-storage pair for current-session persistence.
+     *
+     * When provided, the controller reads and writes the signed-in uid
+     * here (honoring the auth `setPersistence` mode) so page reloads
+     * restore the signed-in user — exactly like `browserLocalPersistence`
+     * in prod Firebase.
+     *
+     * When omitted, the user DATABASE still persists (Phase 1), but the
+     * CURRENT SESSION is not restored on reload. This is the honest
+     * no-fake-durability choice for environments where web storage isn't
+     * available (Bun tests, Node servers, etc.).
+     *
+     * `local` maps to `localStorage` semantics (survives reload + restart);
+     * `session` maps to `sessionStorage` semantics (survives reload, cleared
+     * on tab close). The controller picks which store to write based on the
+     * auth `setPersistence` mode recorded on the backend:
+     *   LOCAL   → local  (default; matches Firebase's default)
+     *   SESSION → session
+     *   NONE    → neither (uid is not stored)
+     *
+     * Both storages are read on restore (mode-agnostic — a prior session
+     * may have used a different mode). Exactly one store holds the uid at
+     * any time; a mode change migrates the uid to the new store.
+     */
+    sessionStorage?: {
+        local: WebStorageLike;
+        session: WebStorageLike;
+    };
+}
+/**
+ * Backend contract: read/write/list/delete RECORDS under a key. The controller
+ * partitions a snapshot into structured-clone bucket records (chunk-format.ts) so
+ * the backend stores many small records natively, never one keyspace-sized blob.
+ * Record values are structured-clone-safe objects; the backend never interprets
+ * them. (v2 and earlier used a single string blob; v3 is record-shaped.)
+ */
+export interface PersistenceBackend {
+    /** Read one record by id under `key`. Resolves `null` when absent. */
+    getRecord(key: string, recordId: string): Promise<unknown | null>;
+    /** List all record ids under `key`, any order. */
+    listRecords(key: string): Promise<string[]>;
+    /** Write each `[recordId, value]` under `key`, replacing any prior value. */
+    putRecords(key: string, records: ReadonlyMap<string, unknown>): Promise<void>;
+    /** Delete the given record ids under `key`. No-op for ids that don't exist. */
+    deleteRecords(key: string, recordIds: readonly string[]): Promise<void>;
+    /** Remove ALL records under `key`. No-op if none exist. */
+    clear(key: string): Promise<void>;
+    /**
+     * Best-effort storage usage estimate (bytes used + the quota ceiling), or
+     * `null` when the backend can't report it. Surfaced by the metadata API so a
+     * host can show how close the sandbox is to its storage limit. Optional: a
+     * backend that can't estimate simply omits it.
+     */
+    estimate?(): Promise<{
+        usage: number;
+        quota: number;
+    } | null>;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/sandbox/persistence/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/sandbox/persistence/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH;;;;;;;;;;;;GAYG;AACH,MAAM,WAAW,cAAc;IAC7B,OAAO,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAAC;IACpC,OAAO,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1C,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;CAC/B;AAED,iEAAiE;AACjE,MAAM,WAAW,yBAAyB;IACxC;;;;OAIG;IACH,GAAG,EAAE,MAAM,CAAC;IACZ;;;;;OAKG;IACH,OAAO,CAAC,EAAE,WAAW,GAAG,QAAQ,CAAC;IACjC;;;;OAIG;IACH,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB;;;;OAIG;IACH,eAAe,CAAC,EAAE,kBAAkB,CAAC;IAErC;;;;;;;;;;;;;;;;;;;;;;;;OAwBG;IACH,cAAc,CAAC,EAAE;QACf,KAAK,EAAE,cAAc,CAAC;QACtB,OAAO,EAAE,cAAc,CAAC;KACzB,CAAC;CACH;AAED;;;;;;GAMG;AACH,MAAM,WAAW,kBAAkB;IACjC,sEAAsE;IACtE,SAAS,CAAC,GAAG,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,GAAG,IAAI,CAAC,CAAC;IAClE,kDAAkD;IAClD,WAAW,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC;IAC5C,6EAA6E;IAC7E,UAAU,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,WAAW,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC9E,+EAA+E;IAC/E,aAAa,CAAC,GAAG,EAAE,MAAM,EAAE,SAAS,EAAE,SAAS,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACxE,2DAA2D;IAC3D,KAAK,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAClC;;;;;OAKG;IACH,QAAQ,CAAC,IAAI,OAAO,CAAC;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI,CAAC,CAAC;CAC/D"}

package/dist/sandbox/persistence/types.js

@@ -0,0 +1,15 @@
+/**
+ * Public types for `pyric/sandbox` persistence. The sandbox itself is
+ * an in-memory dev Firestore; persistence lets a host (browser
+ * playground, agent harness) snapshot the sandbox's data to a backend
+ * and restore it on next init — turning the sandbox into the local
+ * Firestore for a long-running app session.
+ *
+ * The IndexedDB backend is the default in browsers; `memory` is the
+ * opt-out (same as not enabling persistence at all, but useful for
+ * tests that exercise the controller). Future backends (filesystem,
+ * remote KV) plug in via the `PersistenceBackend` contract — `key` is
+ * always the bucket name.
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/sandbox/persistence/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/sandbox/persistence/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG"}

package/dist/sandbox/remote.d.ts

@@ -0,0 +1,118 @@
+/**
+ * Remote-sandbox brand + channel contract (remote sandbox, slice 1).
+ *
+ * A REMOTE sandbox is a Node-side handle onto the browser-hosted
+ * SharedWorker sandbox, constructed by `pyric-tools`'s
+ * `connectRemoteSandbox()`. It satisfies {@link Sandbox} structurally, but
+ * its data plane lives in the browser worker — so consumers that keep
+ * process-local state keyed off the `Sandbox` object (`pyric-admin`'s RTDB
+ * and Auth sandbox backends) must NOT treat it like an in-process sandbox:
+ * doing so would create a private server-side data store that never reaches
+ * the browser.
+ *
+ * This module is the dependency seam that lets `pyric-admin` (which depends
+ * only on `pyric` + `firebase-admin`) recognize a handle constructed by
+ * `pyric-tools` (which depends on `pyric`):
+ *
+ *   - {@link REMOTE_SANDBOX} — a `Symbol.for` brand, so the stamp and the
+ *     check agree across package boundaries and duplicated module graphs.
+ *   - {@link RemoteSandboxChannel} — a STRUCTURALLY-typed minimal op/sub
+ *     relay interface matching `pyric-tools/remote`'s channel shape. The
+ *     concrete op/sub payload types live in `pyric-tools`' worker protocol;
+ *     this contract deliberately types them loosely (`method` + open
+ *     fields) so `pyric` carries no dependency on `pyric-tools`.
+ *
+ * No runtime imports beyond this package's own types — the only runtime
+ * export is the brand symbol and its guard.
+ */
+import type { Sandbox } from './types.js';
+/**
+ * Brand stamped (value `true`) on every remote sandbox handle.
+ * `Symbol.for` — registered globally so `pyric-admin`'s check matches the
+ * stamp even if two copies of `pyric` end up in one process.
+ */
+export declare const REMOTE_SANDBOX: unique symbol;
+/**
+ * The minimal worker-relay channel a remote sandbox handle carries.
+ *
+ * Structural mirror of `pyric-tools/remote`'s `RemoteSandboxChannel`: one
+ * method to dispatch any SharedWorker-protocol op, one to register a
+ * snap-delivering subscription. Payloads are typed openly here (the real
+ * discriminated unions live in `pyric-tools`' worker protocol); callers in
+ * `pyric-admin` spell the concrete op objects (`rtdb.set`, `auth.listUsers`,
+ * …) and pin their own `actAs` lens — nothing is pinned by the channel.
+ */
+export interface RemoteSandboxChannel {
+    /**
+     * Dispatch one worker op. Resolves with the worker's result value;
+     * rejects with an `Error` carrying a `.code` (including the fail-fast
+     * "no browser tab is connected — open <serve url>" guidance when no
+     * peer is registered).
+     */
+    op(op: {
+        method: string;
+    } & Record<string, unknown>): Promise<unknown>;
+    /**
+     * Register a worker subscription (e.g. an RTDB value listener:
+     * `{ target: { service: 'rtdb', path } }`). `onSnap` receives every snap
+     * value (initial + updates — and re-delivered fresh after peer
+     * replacement); an establishment failure routes to `onError` instead.
+     * Returns the unsubscribe function.
+     */
+    subscribe(sub: {
+        target: unknown;
+    } & Record<string, unknown>, onSnap: (value: unknown) => void, onError?: (err: Error & {
+        code: string;
+    }) => void): () => void;
+}
+/**
+ * A branded remote sandbox handle. Structurally a {@link Sandbox} — it can
+ * be passed anywhere a `Sandbox` is accepted (notably
+ * `pyric-admin/app`'s `initializeApp({ sandbox })`) — but sync-only members
+ * that cannot be mirrored over the wire (`admin`, `snapshot()`,
+ * `history()`, …) throw a remediating error. Consumers with a remote arm
+ * dispatch on {@link isRemoteSandbox} and use {@link channel} instead.
+ */
+export interface RemoteSandbox extends Sandbox {
+    readonly [REMOTE_SANDBOX]: true;
+    /** Base URL of the `pyric dev` this handle is attached to (used in
+     *  error guidance: "open <serveUrl> in a browser and retry"). */
+    readonly serveUrl: string;
+    /** The raw worker op/sub relay channel. */
+    readonly channel: RemoteSandboxChannel;
+}
+/**
+ * Well-known global key under which `pyric-tools/register` installs the
+ * remote-sandbox factory: `globalThis[REMOTE_SANDBOX_FACTORY]`.
+ *
+ * This is the AMBIENT-INIT seam (adoption experience, layer 3): when
+ * `pyric-admin/app`'s bare `initializeApp()` sees `PYRIC_SANDBOX=remote[:url]`
+ * it reads this global and calls the installed {@link RemoteSandboxFactory}
+ * to obtain the branded handle — without importing `pyric-tools` (which is
+ * a devDependency of the app, not of `pyric-admin`). `Symbol.for` so the
+ * installer and the reader agree even across duplicated copies of `pyric`.
+ */
+export declare const REMOTE_SANDBOX_FACTORY: unique symbol;
+/** Options accepted by the ambient remote-sandbox factory. */
+export interface RemoteSandboxFactoryOptions {
+    /** Explicit `pyric dev` base URL (from `PYRIC_SANDBOX=remote:<url>`).
+     *  When omitted the factory discovers the running host itself (the
+     *  `.pyric/serve.json` locator protocol). */
+    url?: string;
+}
+/**
+ * The factory `pyric-tools/register` installs at
+ * `globalThis[`{@link REMOTE_SANDBOX_FACTORY}`]`. SYNCHRONOUS by contract:
+ * `initializeApp()` is sync in firebase-admin, so the factory must return
+ * the branded handle without awaiting (connection establishment may be
+ * lazy inside the handle's channel).
+ */
+export type RemoteSandboxFactory = (opts?: RemoteSandboxFactoryOptions) => RemoteSandbox;
+/**
+ * Is this sandbox a remote handle? Backend dispatch guard for consumers
+ * (e.g. `pyric-admin`'s RTDB/Auth sandbox backends) that must route a
+ * remote sandbox's operations through {@link RemoteSandbox.channel} rather
+ * than into process-local state.
+ */
+export declare function isRemoteSandbox(sandbox: Sandbox): sandbox is RemoteSandbox;
+//# sourceMappingURL=remote.d.ts.map

package/dist/sandbox/remote.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"remote.d.ts","sourceRoot":"","sources":["../../src/sandbox/remote.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,YAAY,CAAC;AAE1C;;;;GAIG;AACH,eAAO,MAAM,cAAc,eAAqC,CAAC;AAEjE;;;;;;;;;GASG;AACH,MAAM,WAAW,oBAAoB;IACnC;;;;;OAKG;IACH,EAAE,CAAC,EAAE,EAAE;QAAE,MAAM,EAAE,MAAM,CAAA;KAAE,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IAEvE;;;;;;OAMG;IACH,SAAS,CACP,GAAG,EAAE;QAAE,MAAM,EAAE,OAAO,CAAA;KAAE,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAClD,MAAM,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,EAChC,OAAO,CAAC,EAAE,CAAC,GAAG,EAAE,KAAK,GAAG;QAAE,IAAI,EAAE,MAAM,CAAA;KAAE,KAAK,IAAI,GAChD,MAAM,IAAI,CAAC;CACf;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,aAAc,SAAQ,OAAO;IAC5C,QAAQ,CAAC,CAAC,cAAc,CAAC,EAAE,IAAI,CAAC;IAChC;qEACiE;IACjE,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,2CAA2C;IAC3C,QAAQ,CAAC,OAAO,EAAE,oBAAoB,CAAC;CACxC;AAED;;;;;;;;;;GAUG;AACH,eAAO,MAAM,sBAAsB,eAA4C,CAAC;AAEhF,8DAA8D;AAC9D,MAAM,WAAW,2BAA2B;IAC1C;;iDAE6C;IAC7C,GAAG,CAAC,EAAE,MAAM,CAAC;CACd;AAED;;;;;;GAMG;AACH,MAAM,MAAM,oBAAoB,GAAG,CACjC,IAAI,CAAC,EAAE,2BAA2B,KAC/B,aAAa,CAAC;AAEnB;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,IAAI,aAAa,CAW1E"}

package/dist/sandbox/remote.js

@@ -0,0 +1,60 @@
+/**
+ * Remote-sandbox brand + channel contract (remote sandbox, slice 1).
+ *
+ * A REMOTE sandbox is a Node-side handle onto the browser-hosted
+ * SharedWorker sandbox, constructed by `pyric-tools`'s
+ * `connectRemoteSandbox()`. It satisfies {@link Sandbox} structurally, but
+ * its data plane lives in the browser worker — so consumers that keep
+ * process-local state keyed off the `Sandbox` object (`pyric-admin`'s RTDB
+ * and Auth sandbox backends) must NOT treat it like an in-process sandbox:
+ * doing so would create a private server-side data store that never reaches
+ * the browser.
+ *
+ * This module is the dependency seam that lets `pyric-admin` (which depends
+ * only on `pyric` + `firebase-admin`) recognize a handle constructed by
+ * `pyric-tools` (which depends on `pyric`):
+ *
+ *   - {@link REMOTE_SANDBOX} — a `Symbol.for` brand, so the stamp and the
+ *     check agree across package boundaries and duplicated module graphs.
+ *   - {@link RemoteSandboxChannel} — a STRUCTURALLY-typed minimal op/sub
+ *     relay interface matching `pyric-tools/remote`'s channel shape. The
+ *     concrete op/sub payload types live in `pyric-tools`' worker protocol;
+ *     this contract deliberately types them loosely (`method` + open
+ *     fields) so `pyric` carries no dependency on `pyric-tools`.
+ *
+ * No runtime imports beyond this package's own types — the only runtime
+ * export is the brand symbol and its guard.
+ */
+/**
+ * Brand stamped (value `true`) on every remote sandbox handle.
+ * `Symbol.for` — registered globally so `pyric-admin`'s check matches the
+ * stamp even if two copies of `pyric` end up in one process.
+ */
+export const REMOTE_SANDBOX = Symbol.for('pyric.remote.sandbox');
+/**
+ * Well-known global key under which `pyric-tools/register` installs the
+ * remote-sandbox factory: `globalThis[REMOTE_SANDBOX_FACTORY]`.
+ *
+ * This is the AMBIENT-INIT seam (adoption experience, layer 3): when
+ * `pyric-admin/app`'s bare `initializeApp()` sees `PYRIC_SANDBOX=remote[:url]`
+ * it reads this global and calls the installed {@link RemoteSandboxFactory}
+ * to obtain the branded handle — without importing `pyric-tools` (which is
+ * a devDependency of the app, not of `pyric-admin`). `Symbol.for` so the
+ * installer and the reader agree even across duplicated copies of `pyric`.
+ */
+export const REMOTE_SANDBOX_FACTORY = Symbol.for('pyric.remote.sandboxFactory');
+/**
+ * Is this sandbox a remote handle? Backend dispatch guard for consumers
+ * (e.g. `pyric-admin`'s RTDB/Auth sandbox backends) that must route a
+ * remote sandbox's operations through {@link RemoteSandbox.channel} rather
+ * than into process-local state.
+ */
+export function isRemoteSandbox(sandbox) {
+    // Null-safe by contract: guard call sites probe values that may not be a
+    // Sandbox at all (e.g. legacy callers passing a raw Sandbox where a
+    // SandboxContext is expected leave `.sandbox` undefined). A brand check
+    // must classify, never throw.
+    return (sandbox != null &&
+        sandbox[REMOTE_SANDBOX] === true);
+}
+//# sourceMappingURL=remote.js.map

package/dist/sandbox/remote.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"remote.js","sourceRoot":"","sources":["../../src/sandbox/remote.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAIH;;;;GAIG;AACH,MAAM,CAAC,MAAM,cAAc,GAAG,MAAM,CAAC,GAAG,CAAC,sBAAsB,CAAC,CAAC;AAoDjE;;;;;;;;;;GAUG;AACH,MAAM,CAAC,MAAM,sBAAsB,GAAG,MAAM,CAAC,GAAG,CAAC,6BAA6B,CAAC,CAAC;AAqBhF;;;;;GAKG;AACH,MAAM,UAAU,eAAe,CAAC,OAAgB;IAC9C,yEAAyE;IACzE,oEAAoE;IACpE,wEAAwE;IACxE,8BAA8B;IAC9B,OAAO,CACL,OAAO,IAAI,IAAI;QACd,OAA2D,CAC1D,cAAc,CACf,KAAK,IAAI,CACX,CAAC;AACJ,CAAC"}

package/dist/sandbox/replay/index.d.ts

@@ -0,0 +1,106 @@
+/**
+ * Replay — capture a session via `sandbox.history()` and re-issue
+ * every write against a fresh sandbox; the engine classifies any
+ * divergences.
+ *
+ * Exported from the main `pyric/sandbox` entry. The file lives at
+ * `src/replay/index.ts` as an organizational unit; importers use
+ * the public bare-package import path.
+ *
+ * Usage:
+ * ```ts
+ * import { initializeSandbox, replay, type SandboxEvent } from 'pyric/sandbox';
+ *
+ * const original = initializeSandbox();
+ * // ... do work, capture events via original.history() ...
+ * const events = original.history();
+ *
+ * const { sandbox: replayed, divergences } = replay(events, rulesSource);
+ * // `replayed` is a fresh sandbox with every captured write re-applied.
+ * // `divergences` classifies any field-level differences.
+ * ```
+ *
+ * Each captured `WriteSandboxEvent` is re-issued on the fresh sandbox.
+ * The engine consults the captured `sentinels`, `autoId`, and
+ * `requestTime` fields so:
+ *   - `serverTimestamp()` sentinels re-resolve to the captured time
+ *     (when `pinRequestTime: true`, the default).
+ *   - `collection.add()` minted IDs alias to fresh mints on replay;
+ *     `pathAliases` maps the original path → the replayed path.
+ *   - rules that branch on `request.time` re-evaluate identically
+ *     (pinned time).
+ *
+ * Divergence classification (deterministic — no shape inference):
+ *   - `autoid-alias`    — path differs because of fresh ID minting,
+ *                          otherwise content matches.
+ *   - `sentinel-drift`  — a captured sentinel sits at this exact field
+ *                          path (e.g. an `increment` at `tags`) and the
+ *                          subtree differs.
+ *   - `time-drift`      — like `sentinel-drift` but specifically a
+ *                          captured `serverTimestamp`. Surfaces when
+ *                          `pinRequestTime: false` and the wall clock
+ *                          advanced between capture and replay.
+ *   - `real-divergence` — anything else. If the captured metadata
+ *                          doesn't license drift at this exact leaf,
+ *                          the engine flags it.
+ *
+ * Field-level diffs use a recursive walk producing dotted/bracket
+ * leaf paths (`profile.lastSeen`, `tags[0]`, `arr[2].nested`). A
+ * sentinel match is *exact-path*, not prefix — a sibling field
+ * changing inside a sentinel-bearing parent surfaces independently as
+ * `real-divergence`.
+ */
+import { type Sandbox, type SandboxEvent } from '../index.js';
+type DocData = Record<string, unknown>;
+export type Divergence = {
+    kind: 'sentinel-drift';
+    path: string;
+    field: string;
+    sentinelKind: 'serverTimestamp' | 'increment' | 'arrayUnion' | 'arrayRemove' | 'delete';
+    before: unknown;
+    after: unknown;
+} | {
+    kind: 'autoid-alias';
+    originalPath: string;
+    replayedPath: string;
+} | {
+    kind: 'time-drift';
+    path: string;
+    field: string;
+    before: unknown;
+    after: unknown;
+} | {
+    kind: 'real-divergence';
+    path: string;
+    field?: string;
+    before: unknown;
+    after: unknown;
+};
+export interface ReplayOptions {
+    /** When true (default), re-issue the captured `requestTime` so
+     *  `serverTimestamp()` sentinels resolve to the same value as
+     *  capture and `request.time`-gated rules evaluate identically. */
+    pinRequestTime?: boolean;
+}
+export interface ReplayResult {
+    /** Fresh sandbox with the captured writes re-applied. */
+    sandbox: Sandbox;
+    /** Field- and path-level differences between original and replayed
+     *  state, classified. */
+    divergences: Divergence[];
+    /** Maps captured auto-id paths → freshly-minted replay paths. The
+     *  diff classifier uses this to skip `autoid-alias` paths when
+     *  computing field-level differences. */
+    pathAliases: Map<string, string>;
+}
+/**
+ * Replay a captured SandboxEvent stream on a fresh sandbox.
+ *
+ * The `originalState` snapshot is optional — when provided, the engine
+ * diffs the replayed sandbox's final state against it and returns
+ * classified divergences. When omitted, divergences is `[]` (you still
+ * get the replayed sandbox; you can inspect its state manually).
+ */
+export declare function replay(events: readonly SandboxEvent[], rules: string, options?: ReplayOptions, originalState?: Record<string, DocData>): ReplayResult;
+export {};
+//# sourceMappingURL=index.d.ts.map

package/dist/sandbox/replay/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/sandbox/replay/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmDG;AACH,OAAO,EAEL,KAAK,OAAO,EACZ,KAAK,YAAY,EAElB,MAAM,aAAa,CAAC;AAIrB,KAAK,OAAO,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAEvC,MAAM,MAAM,UAAU,GAClB;IACE,IAAI,EAAE,gBAAgB,CAAC;IACvB,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,YAAY,EACR,iBAAiB,GACjB,WAAW,GACX,YAAY,GACZ,aAAa,GACb,QAAQ,CAAC;IACb,MAAM,EAAE,OAAO,CAAC;IAChB,KAAK,EAAE,OAAO,CAAC;CAChB,GACD;IAAE,IAAI,EAAE,cAAc,CAAC;IAAC,YAAY,EAAE,MAAM,CAAC;IAAC,YAAY,EAAE,MAAM,CAAA;CAAE,GACpE;IAAE,IAAI,EAAE,YAAY,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,OAAO,CAAC;IAAC,KAAK,EAAE,OAAO,CAAA;CAAE,GACpF;IAAE,IAAI,EAAE,iBAAiB,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,OAAO,CAAC;IAAC,KAAK,EAAE,OAAO,CAAA;CAAE,CAAC;AAE/F,MAAM,WAAW,aAAa;IAC5B;;uEAEmE;IACnE,cAAc,CAAC,EAAE,OAAO,CAAC;CAC1B;AAED,MAAM,WAAW,YAAY;IAC3B,yDAAyD;IACzD,OAAO,EAAE,OAAO,CAAC;IACjB;6BACyB;IACzB,WAAW,EAAE,UAAU,EAAE,CAAC;IAC1B;;6CAEyC;IACzC,WAAW,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAClC;AAED;;;;;;;GAOG;AACH,wBAAgB,MAAM,CACpB,MAAM,EAAE,SAAS,YAAY,EAAE,EAC/B,KAAK,EAAE,MAAM,EACb,OAAO,GAAE,aAAkB,EAC3B,aAAa,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GACtC,YAAY,CAuDd"}