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

package/dist/serve/docs-ui/docs/pyric-cli-remote-reference-api.md

@@ -1,5 +1,4 @@
-
-<!-- Generated from published package declarations via TypeDoc. Do not edit by hand; run bun run docs:api:generate. -->
+<!-- Generated from published package declarations via TypeDoc. Rendered by the api-reference content loader. -->
 
 ## Interfaces
 
@@ -26,23 +25,929 @@ eager checkers. `ready` kicks off the connection when first accessed and
 settles with the same fail-fast errors [connectRemoteSandbox](#connectremotesandbox) throws
 (no serve discovered / no browser tab connected).
 
-#### Extends
+#### Extends
+
+- [`RemoteSandbox`](#remotesandbox)
+
+#### Properties
+
+| Property | Modifier | Type | Description |
+| :------ | :------ | :------ | :------ |
+| <a id="remote_sandbox"></a> `[REMOTE_SANDBOX]` | `readonly` | `true` | - |
+| <a id="admin"></a> `admin` | `readonly` | `SandboxAdmin` | Admin-plane access (rule-bypass reads). Identity-agnostic by design — admin reads aren't gated on auth, so they live on the sandbox, not on a context. See SandboxAdmin. |
+| <a id="auth"></a> `auth` | `readonly` | [`RemoteAuthAdmin`](#remoteauthadmin) | Admin auth user CRUD. |
+| <a id="channel"></a> `channel` | `readonly` | [`RemoteSandboxChannel`](#remotesandboxchannel-1) | The raw worker op/sub relay channel (narrowed to the wire payload types). |
+| <a id="currentuser"></a> `currentUser` | `public` | \{ `token?`: `Record`\<`string`, `unknown`\>; `uid`: `string`; \} | Current authenticated user across the sandbox. Mutated by `pyric/auth`'s `signInAnonymously` / `signInWithEmailAndPassword` / `signOut` / `sandbox.setUser`. Read per-call by service factories (e.g. a future `getFirestore(sandbox)` overload) so they see auth state changes without re-binding handles. Defaults to `null` (anonymous / signed out). **Independent of `withAuth({uid})`** — `withAuth` still produces a frozen [SandboxContext](pyric-firestore-reference-api.md#sandboxcontext) that carries its own identity for the runner's test code (the existing pattern: explicit identity per service call). `currentUser` exists for the `pyric/auth` mirror, where consumer app code drives identity through a stateful `Auth` handle rather than naming it per call. |
+| `currentUser.token?` | `public` | `Record`\<`string`, `unknown`\> | - |
+| `currentUser.uid` | `public` | `string` | - |
+| <a id="ready"></a> `ready` | `readonly` | `Promise`\<`void`\> | - |
+| <a id="rtdb"></a> `rtdb` | `readonly` | [`RemoteRtdb`](#remotertdb) | RTDB conveniences (admin lens pinned). |
+| <a id="serveurl"></a> `serveUrl` | `readonly` | `string` | Base URL of the `pyric dev` this handle is attached to (used in error guidance: "open <serveUrl> in a browser and retry"). |
+| <a id="storage"></a> `storage` | `readonly` | [`RemoteStorage`](#remotestorage) | Storage conveniences (admin lens pinned; 8 MiB per-op byte cap). |
+
+#### Methods
+
+<a id="clearpersistence"></a>
+
+##### clearPersistence()
+
+```ts
+clearPersistence(): Promise<void>;
+```
+
+Wipe the persisted blob for this sandbox's `key`. In-memory state
+is left intact — call `reset()` if you want both. Useful for
+"sign out and forget" flows.
+
+No-op when persistence is not enabled.
+
+###### Returns
+
+`Promise`\<`void`\>
+
+###### Inherited from
+
+[`RemoteSandbox`](#remotesandbox).[`clearPersistence`](#clearpersistence-2)
+
+<a id="close"></a>
+
+##### close()
+
+```ts
+close(): void;
+```
+
+Close the connection. In-flight ops reject; subscriptions stop.
+
+###### Returns
+
+`void`
+
+###### Inherited from
+
+[`RemoteSandbox`](#remotesandbox).[`close`](#close-2)
+
+<a id="dispose"></a>
+
+##### dispose()
+
+```ts
+dispose(): void;
+```
+
+Tear down listener registries on this sandbox's environment without
+replacing it. Use this when you're about to discard the sandbox
+itself (e.g. `runner.reseed()` builds a fresh sandbox rather than
+calling `reset()`) and want to drop callback references on the
+outgoing instance defensively. Idempotent. Does not touch data.
+
+###### Returns
+
+`void`
+
+###### Inherited from
+
+[`RemoteSandbox`](#remotesandbox).[`dispose`](#dispose-2)
+
+<a id="enablepersistence"></a>
+
+##### enablePersistence()
+
+```ts
+enablePersistence(options: SandboxPersistenceOptions): Promise<void>;
+```
+
+Persist the sandbox's data to a backend and restore it on next
+`enablePersistence` call. The default `'indexedDB'` backend turns
+the sandbox into the host page's local Firestore — writes flush
+automatically and a fresh `initializeSandbox()` rehydrates from
+the prior session.
+
+Restoration happens before the promise resolves; awaiting this
+call is sufficient to guarantee in-memory state matches the
+persisted blob.
+
+Idempotent across the same `key` — calling twice in one process
+is a no-op on the second call. Different keys are rejected as an
+error (a sandbox can persist to at most one backend at a time).
+
+Listener semantics: every write event the sandbox emits triggers
+a debounced flush (default 250ms). Browser hosts additionally
+flush on `beforeunload` so a page navigation doesn't lose the
+tail of the debounce window.
+
+See [SandboxPersistenceOptions](pyric-sandbox-reference-api.md#sandboxpersistenceoptions) for backend selection and
+tuning.
+
+###### Parameters
+
+| Parameter | Type |
+| :------ | :------ |
+| `options` | [`SandboxPersistenceOptions`](pyric-sandbox-reference-api.md#sandboxpersistenceoptions) |
+
+###### Returns
+
+`Promise`\<`void`\>
+
+###### Inherited from
+
+[`RemoteSandbox`](#remotesandbox).[`enablePersistence`](#enablepersistence-2)
+
+<a id="enabletabsync"></a>
+
+##### enableTabSync()
+
+```ts
+enableTabSync(options?: TabSyncOptions): () => void;
+```
+
+Enable cross-tab realtime sync via `BroadcastChannel`. A write in
+this tab will propagate to every OTHER tab of the same origin that
+also called `enableTabSync`, causing their `onSnapshot` listeners to
+re-evaluate — restoring production's cross-client realtime behavior.
+
+**Opt-in, OFF by default.** Firestore only (RTDB is a follow-on).
+
+Returns a disable function. Calling it removes the `onEvent`
+subscription, the channel message listener, and closes the channel
+(when it was created internally). After disable, no further propagation
+occurs in either direction.
+
+**Multi-writer note:** concurrent writes from two tabs to the same doc
+produce last-write-wins divergence — there is no conflict resolution.
+The intended model is one active writer (one user, one tab) with
+observers in other tabs; this covers the overwhelming majority of
+local development scenarios.
+
+###### Parameters
+
+| Parameter | Type |
+| :------ | :------ |
+| `options?` | [`TabSyncOptions`](pyric-sandbox-reference-api.md#tabsyncoptions) |
+
+###### Returns
+
+```ts
+(): void;
+```
+
+###### Returns
+
+`void`
+
+###### See
+
+[TabSyncOptions](pyric-sandbox-reference-api.md#tabsyncoptions) for channel injection (tests) and originId.
+
+###### Example
+
+```ts
+// In every tab that should participate in realtime:
+const sandbox = initializeSandbox();
+const disableSync = sandbox.enableTabSync();
+// Later, to stop syncing:
+disableSync();
+```
+
+###### Inherited from
+
+[`RemoteSandbox`](#remotesandbox).[`enableTabSync`](#enabletabsync-2)
+
+<a id="flush"></a>
+
+##### flush()
+
+```ts
+flush(): Promise<void>;
+```
+
+Force a snapshot to the configured persistence backend right now.
+Useful before a manual navigation, or in tests that need
+deterministic ordering against the debounce window. Resolves once
+the write hits the backend.
+
+Throws if persistence is not enabled.
+
+###### Returns
+
+`Promise`\<`void`\>
+
+###### Inherited from
+
+[`RemoteSandbox`](#remotesandbox).[`flush`](#flush-2)
+
+<a id="history"></a>
+
+##### history()
+
+```ts
+history(): SandboxEvent[];
+```
+
+Every [SandboxEvent](pyric-sandbox-reference-api.md#sandboxevent) this sandbox has emitted since init or
+the last `reset()`. Returns a defensive copy.
+
+Use this for replay: hand the array to `replay(events, rules)`
+from `pyric/sandbox` and the engine re-issues every
+captured write against a fresh sandbox.
+
+Unlike [onEvent](pyric-firestore-reference-api.md#onevent) (live stream from the moment of subscribe),
+`history()` returns *every* event the sandbox has seen — useful
+for consumers that attach late (e.g., loading a saved session
+before subscribing) or that need a snapshot at a particular moment.
+
+`reset()` and `dispose()` each append a closing `session_boundary`
+event; `reset()` then clears the history. Consumers that took a
+snapshot *before* reset retain the boundary in their copy.
+
+###### Returns
+
+[`SandboxEvent`](pyric-sandbox-reference-api.md#sandboxevent)[]
+
+###### Inherited from
+
+[`RemoteSandbox`](#remotesandbox).[`history`](#history-2)
+
+<a id="loadsnapshot"></a>
+
+##### loadSnapshot()
+
+```ts
+loadSnapshot(data: SandboxSnapshot): void;
+```
+
+CLOBBER-restore the sandbox's entire state from a prior [snapshot](pyric-firestore-reference-api.md#snapshot):
+`reset()` (clears firestore + the signed-in session), then rebuild firestore
+from `data` and restore each registered service. This is a TOTAL replace —
+documents absent from `data` do NOT survive — and is the counterpart to
+[snapshot](pyric-firestore-reference-api.md#snapshot). It is what makes "transfer (clobber) one instance's data
+into another" and named-branch switching possible.
+
+Fires a `session_boundary` (reset phase), re-evaluates live listeners against
+the loaded state, and the next persistence flush writes the loaded state.
+Services present in `data` but not currently registered are skipped (a
+snapshot taken via [snapshot](pyric-firestore-reference-api.md#snapshot) always includes every registered
+service, so this only affects cross-instance imports from a sandbox that had
+a service this one lacks).
+
+###### Parameters
+
+| Parameter | Type |
+| :------ | :------ |
+| `data` | [`SandboxSnapshot`](pyric-sandbox-reference-api.md#sandboxsnapshot) |
+
+###### Returns
+
+`void`
+
+###### Inherited from
+
+[`RemoteSandbox`](#remotesandbox).[`loadSnapshot`](#loadsnapshot-2)
+
+<a id="oncurrentuserchanged"></a>
+
+##### onCurrentUserChanged()
+
+```ts
+onCurrentUserChanged(cb: (user: {
+  token?: Record<string, unknown>;
+  uid: string;
+}) => void): () => void;
+```
+
+Subscribe to `currentUser` changes. Fires on every mutation —
+sign-in, sign-out, user swap. Does NOT fire on subscribe.
+
+Survives `reset()` and `dispose()` only as a no-op: a disposed
+sandbox emits nothing further; a reset sandbox clears
+`currentUser` to `null` (and fires the change) before swapping
+the env.
+
+Returns an unsubscribe function. Listener errors are swallowed —
+subscribers are observational, the sandbox does not propagate
+their errors.
+
+###### Parameters
+
+| Parameter | Type |
+| :------ | :------ |
+| `cb` | (`user`: \{ `token?`: `Record`\<`string`, `unknown`\>; `uid`: `string`; \}) => `void` |
+
+###### Returns
+
+```ts
+(): void;
+```
+
+###### Returns
+
+`void`
+
+###### Inherited from
+
+[`RemoteSandbox`](#remotesandbox).[`onCurrentUserChanged`](#oncurrentuserchanged-2)
+
+<a id="onevent"></a>
+
+##### onEvent()
+
+```ts
+onEvent(cb: (event: SandboxEvent) => void): () => void;
+```
+
+Subscribe to every event the sandbox emits — see [SandboxEvent](pyric-sandbox-reference-api.md#sandboxevent)
+for the discriminated-union shape. One subscription covers
+request/denial/snapshot-error/listener-lifecycle/session-boundary;
+filter on `event.kind` to recover individual streams.
+
+Replaces the prior three-channel surface (`onRequest` / `onDenial`
+/ `onSnapshotError`) — see issue #307. Filter cookbook:
+  - All denials:    `event.kind === 'request' && event.result === 'deny'`
+  - Stream errors:  `event.kind === 'listener_errored'`
+  - Per-op traffic: `event.kind === 'request'`
+
+Survives `sandbox.reset()` — the subscription is held on the
+sandbox, not on the underlying environment. A `session_boundary`
+event with `phase: 'reset'` fires before the env swap so consumers
+can segment their stream.
+
+Returns an unsubscribe function. Listener errors are swallowed so a
+faulty subscriber can't change rule semantics or hide other events.
+Both synchronous throws and rejected Promises from async callbacks
+are silently discarded — subscribers are **observational**, the
+sandbox doesn't await them and doesn't propagate their errors.
+
+###### Parameters
+
+| Parameter | Type |
+| :------ | :------ |
+| `cb` | (`event`: [`SandboxEvent`](pyric-sandbox-reference-api.md#sandboxevent)) => `void` |
+
+###### Returns
+
+```ts
+(): void;
+```
+
+###### Returns
+
+`void`
+
+###### Inherited from
+
+[`RemoteSandbox`](#remotesandbox).[`onEvent`](#onevent-2)
+
+<a id="registerpersistableservice"></a>
+
+##### registerPersistableService()
+
+```ts
+registerPersistableService(name: string, hooks: PersistableService): () => void;
+```
+
+Register a service (auth, storage, …) as a persistence participant.
+The sandbox calls `hooks.snapshot()` on every flush and
+`hooks.restore(data)` on restore. If `hooks.subscribe` is provided,
+the persistence controller subscribes and schedules a debounced
+flush on each change — so auth-user edits flush promptly, not only
+on the next Firestore write.
+
+Returns an unregister function — call it if the service is torn
+down before the sandbox is disposed (uncommon in practice; the
+sandbox's `dispose()` clears the registry anyway).
+
+Throws `failed-precondition` when a service with the same `name` is
+already registered — the auth package registers `'auth'` once when
+`getAuth(sandbox)` first creates a backend, so accidental double-
+registration is a caller bug, not a no-op.
+
+**Advanced / internal API.** Service packages (auth, storage) call
+this when they first attach to a sandbox. Consumer app code should
+not need to call this directly.
+
+###### Parameters
+
+| Parameter | Type |
+| :------ | :------ |
+| `name` | `string` |
+| `hooks` | [`PersistableService`](pyric-sandbox-reference-api.md#persistableservice) |
+
+###### Returns
+
+```ts
+(): void;
+```
+
+###### Returns
+
+`void`
+
+###### Inherited from
+
+[`RemoteSandbox`](#remotesandbox).[`registerPersistableService`](#registerpersistableservice-2)
+
+<a id="reset"></a>
+
+##### reset()
+
+```ts
+reset(): void;
+```
+
+Reset the underlying environment to a fresh state — wipes data,
+rules, and any service-specific configuration.
+
+Snapshot listeners attached to the OLD environment are dropped at
+the swap — they can't survive because their target docs have been
+wiped. `onEvent` subscribers DO survive — the registry lives on
+the sandbox, and a `session_boundary` event with `phase: 'reset'`
+fires before the swap so subscribers know the rollover happened.
+Existing [SandboxContext](pyric-firestore-reference-api.md#sandboxcontext)s continue to work — their sandbox
+reference is stable; subsequent operations resolve to the new env.
+
+###### Returns
+
+`void`
+
+###### Inherited from
+
+[`RemoteSandbox`](#remotesandbox).[`reset`](#reset-2)
+
+<a id="resetall"></a>
+
+##### resetAll()
+
+```ts
+resetAll(): Promise<{
+  errors: string[];
+}>;
+```
+
+Reset the WHOLE sandbox: [reset](pyric-firestore-reference-api.md#reset) (Firestore env + signed-in
+session), then clear every registered persistable service that
+provides a [PersistableService.reset](pyric-sandbox-reference-api.md#reset-2) hook — auth users, the
+RTDB tree, storage objects. This is the one sandbox-owned "wipe
+everything" path: because it iterates the service registry, a new
+service that registers with a `reset` hook is cleared automatically,
+and a consumer (Pyric Studio's reset) cannot forget one.
+
+Service resets may be async (storage clears IndexedDB stores); the
+returned promise resolves when every service has finished clearing.
+A service whose `reset` throws is isolated (others still clear) and
+REPORTED in the returned `errors` (as `name: message`) — a reset that
+leaves data behind must never look successful to the caller.
+
+###### Returns
+
+`Promise`\<\{
+  `errors`: `string`[];
+\}\>
+
+###### Inherited from
+
+[`RemoteSandbox`](#remotesandbox).[`resetAll`](#resetall-2)
+
+<a id="runwithprovenance"></a>
+
+##### runWithProvenance()?
+
+```ts
+optional runWithProvenance<T>(provenance: EventProvenance, fn: () => T): T;
+```
+
+Run `fn` with ambient [EventProvenance](pyric-sandbox-reference-api.md#eventprovenance) defaults: every event
+emitted SYNCHRONOUSLY during `fn` that doesn't already carry a
+provenance field (on the event itself or via an explicit per-emit
+override) is stamped with these values instead of the global
+defaults. This is the mechanical "who issued this op" seam the
+serve worker uses to tag Studio-issued ops (`actor: { kind:
+'studio' }`) and to stamp the auth lens an op ran under
+(`authLens`) — declared by the caller that issues the op, never
+inferred from the op's shape.
+
+SYNCHRONOUS WINDOW: the ambient values apply only until `fn`
+returns (for an async `fn`, its synchronous prefix — which covers
+the local environment's rules eval + event emission, since those
+run before the op's promise is handed back). Work an op DEFERS
+(snapshot-listener deliveries and re-evals drain on a microtask,
+off-stack) is intentionally OUTSIDE the window: a listener re-eval
+belongs to the listener's owner, not to whoever's write triggered
+it. Nested calls stack — the innermost window wins per field, and
+each window restores the previous one on exit (including on throw).
+
+OPTIONAL because remote sandbox proxies can't provide an ambient
+emit window (events are emitted in the worker they front). Callers
+spell `sandbox.runWithProvenance?.(prov, fn) ?? fn()`.
+
+###### Type Parameters
+
+| Type Parameter |
+| :------ |
+| `T` |
+
+###### Parameters
+
+| Parameter | Type |
+| :------ | :------ |
+| `provenance` | [`EventProvenance`](pyric-sandbox-reference-api.md#eventprovenance) |
+| `fn` | () => `T` |
+
+###### Returns
+
+`T`
+
+###### Inherited from
+
+[`RemoteSandbox`](#remotesandbox).[`runWithProvenance`](#runwithprovenance-2)
+
+<a id="snapshot"></a>
+
+##### snapshot()
+
+```ts
+snapshot(): SandboxSnapshot;
+```
+
+Capture a snapshot of every service's state. For v1 with only
+Firestore, the return value carries a `firestore` key mapping doc
+paths to data. Future services will add their own keys.
+
+###### Returns
+
+[`SandboxSnapshot`](pyric-sandbox-reference-api.md#sandboxsnapshot)
+
+###### Inherited from
+
+[`RemoteSandbox`](#remotesandbox).[`snapshot`](#snapshot-2)
+
+<a id="withauth"></a>
+
+##### withAuth()
+
+```ts
+withAuth(auth: {
+  token?: Record<string, unknown>;
+  uid: string;
+}): SandboxContext;
+```
+
+Derive a context bound to this sandbox under the given auth
+identity. Operations through services attached to the returned
+context evaluate rules under that identity. Many contexts can
+coexist for one sandbox; data is shared.
+
+`null` is anonymous; an `AuthState` object names the user (and
+optional custom claims). Passing `undefined` is a deliberate
+error — say `withAuth(null)` for anonymous so the call site is
+unambiguous.
+
+###### Parameters
+
+| Parameter | Type |
+| :------ | :------ |
+| `auth` | \{ `token?`: `Record`\<`string`, `unknown`\>; `uid`: `string`; \} |
+| `auth.token?` | `Record`\<`string`, `unknown`\> |
+| `auth.uid` | `string` |
+
+###### Returns
+
+[`SandboxContext`](pyric-firestore-reference-api.md#sandboxcontext)
+
+###### Example
+
+```ts
+const sandbox = initializeSandbox();
+const dbAlice = getFirestore(sandbox.withAuth({ uid: 'alice' }));
+const dbAnon  = getFirestore(sandbox.withAuth(null));
+```
+
+###### Inherited from
+
+[`RemoteSandbox`](#remotesandbox).[`withAuth`](#withauth-2)
+
+***
+
+<a id="remoteauthadmin"></a>
+
+### RemoteAuthAdmin
+
+Admin auth user-CRUD passthrough (never lensed — auth ops operate the
+ worker's user pool directly, mirroring `pyric/auth`'s sandbox ops).
+
+#### Methods
+
+<a id="clearusers"></a>
+
+##### clearUsers()
+
+```ts
+clearUsers(): Promise<void>;
+```
+
+###### Returns
+
+`Promise`\<`void`\>
+
+<a id="createuser"></a>
+
+##### createUser()
+
+```ts
+createUser(request: CreateUserRequest): Promise<AuthUserRecord>;
+```
+
+###### Parameters
+
+| Parameter | Type |
+| :------ | :------ |
+| `request` | [`CreateUserRequest`](pyric-auth-reference-api.md#createuserrequest) |
+
+###### Returns
+
+`Promise`\<[`AuthUserRecord`](pyric-auth-reference-api.md#authuserrecord)\>
+
+<a id="deleteuser"></a>
+
+##### deleteUser()
+
+```ts
+deleteUser(uid: string): Promise<void>;
+```
+
+###### Parameters
+
+| Parameter | Type |
+| :------ | :------ |
+| `uid` | `string` |
+
+###### Returns
+
+`Promise`\<`void`\>
+
+<a id="listusers"></a>
+
+##### listUsers()
+
+```ts
+listUsers(): Promise<AuthUserRecord[]>;
+```
+
+###### Returns
+
+`Promise`\<[`AuthUserRecord`](pyric-auth-reference-api.md#authuserrecord)[]\>
+
+<a id="updateuser"></a>
+
+##### updateUser()
+
+```ts
+updateUser(uid: string, request: UpdateUserRequest): Promise<AuthUserRecord>;
+```
+
+###### Parameters
+
+| Parameter | Type |
+| :------ | :------ |
+| `uid` | `string` |
+| `request` | [`UpdateUserRequest`](pyric-auth-reference-api.md#updateuserrequest) |
+
+###### Returns
+
+`Promise`\<[`AuthUserRecord`](pyric-auth-reference-api.md#authuserrecord)\>
+
+***
+
+<a id="remotertdb"></a>
+
+### RemoteRtdb
+
+Thin RTDB conveniences over the channel. Every call pins
+`actAs: { mode: 'admin' }` — firebase-admin's rules-bypass semantics,
+matching what `pyric-admin`'s database backend needs. Use the raw
+`channel` for lensed (rules-evaluated) access.
+
+#### Methods
+
+<a id="get"></a>
+
+##### get()
+
+```ts
+get(path: string): Promise<unknown>;
+```
+
+Read the value at `path` (null when absent).
+
+###### Parameters
+
+| Parameter | Type |
+| :------ | :------ |
+| `path` | `string` |
+
+###### Returns
+
+`Promise`\<`unknown`\>
+
+<a id="onvalue"></a>
+
+##### onValue()
+
+```ts
+onValue(
+   path: string,
+   callback: (snapshot: RemoteRtdbSnapshot) => void,
+   onError?: (err: Error & {
+  code: string;
+}) => void): () => void;
+```
+
+Subscribe to the value at `path` (initial snapshot + every change).
+
+###### Parameters
+
+| Parameter | Type |
+| :------ | :------ |
+| `path` | `string` |
+| `callback` | (`snapshot`: [`RemoteRtdbSnapshot`](#remotertdbsnapshot)) => `void` |
+| `onError?` | (`err`: `Error` & \{ `code`: `string`; \}) => `void` |
+
+###### Returns
+
+```ts
+(): void;
+```
+
+###### Returns
+
+`void`
+
+<a id="push"></a>
+
+##### push()
+
+```ts
+push(path: string, value?: unknown): Promise<{
+  key: string;
+  path: string;
+}>;
+```
+
+Push `value` under a CLIENT-minted 20-char push id (the worker-protocol
+ contract: `rtdb.push` carries the key, so `.key` is known synchronously
+ on the pyric-admin side). Resolves with the minted key + full path.
+
+###### Parameters
+
+| Parameter | Type |
+| :------ | :------ |
+| `path` | `string` |
+| `value?` | `unknown` |
+
+###### Returns
+
+`Promise`\<\{
+  `key`: `string`;
+  `path`: `string`;
+\}\>
+
+<a id="remove"></a>
+
+##### remove()
+
+```ts
+remove(path: string): Promise<void>;
+```
+
+###### Parameters
+
+| Parameter | Type |
+| :------ | :------ |
+| `path` | `string` |
+
+###### Returns
+
+`Promise`\<`void`\>
+
+<a id="set"></a>
+
+##### set()
+
+```ts
+set(path: string, value: unknown): Promise<void>;
+```
+
+###### Parameters
+
+| Parameter | Type |
+| :------ | :------ |
+| `path` | `string` |
+| `value` | `unknown` |
+
+###### Returns
+
+`Promise`\<`void`\>
+
+<a id="update"></a>
+
+##### update()
+
+```ts
+update(path: string, values: Record<string, unknown>): Promise<void>;
+```
+
+###### Parameters
+
+| Parameter | Type |
+| :------ | :------ |
+| `path` | `string` |
+| `values` | `Record`\<`string`, `unknown`\> |
+
+###### Returns
+
+`Promise`\<`void`\>
+
+***
+
+<a id="remotertdbsnapshot"></a>
+
+### RemoteRtdbSnapshot
+
+Wire shape of an RTDB snapshot as the worker host serializes it.
+
+#### Properties
+
+| Property | Type |
+| :------ | :------ |
+| <a id="exists"></a> `exists` | `boolean` |
+| <a id="key"></a> `key` | `string` |
+| <a id="size"></a> `size` | `number` |
+| <a id="value"></a> `value` | `unknown` |
+
+***
+
+<a id="remotesandbox"></a>
+
+### RemoteSandbox
+
+The Node-side remote sandbox handle. Extends `pyric/sandbox`'s branded
+[RemoteSandboxBase](pyric-sandbox-reference-api.md#remotesandbox) — structurally a full `Sandbox`, so it can be
+passed to `pyric-admin/app`'s `initializeApp({ sandbox })`, whose RTDB and
+Auth backends dispatch on the brand and route through [channel](#channel-1).
+
+Sandbox members that are genuinely sync-only (`admin`, `snapshot()`,
+`history()`, `onEvent`, `currentUser`, …) cannot be mirrored over the
+wire in slice 1 and throw a remediating `unimplemented` error naming
+what to do instead. Implemented members: `withAuth` (pure local pair
+construction) and `dispose` (aliases [close](#close-2)).
+
+#### Extends
+
+- [`RemoteSandbox`](pyric-sandbox-reference-api.md#remotesandbox)
+
+#### Extended by
+
+- [`LazyRemoteSandbox`](#lazyremotesandbox)
+
+#### Properties
+
+| Property | Modifier | Type | Description | Overrides |
+| :------ | :------ | :------ | :------ | :------ |
+| <a id="remote_sandbox-1"></a> `[REMOTE_SANDBOX]` | `readonly` | `true` | - | - |
+| <a id="admin-1"></a> `admin` | `readonly` | `SandboxAdmin` | Admin-plane access (rule-bypass reads). Identity-agnostic by design — admin reads aren't gated on auth, so they live on the sandbox, not on a context. See SandboxAdmin. | - |
+| <a id="auth-1"></a> `auth` | `readonly` | [`RemoteAuthAdmin`](#remoteauthadmin) | Admin auth user CRUD. | - |
+| <a id="channel-1"></a> `channel` | `readonly` | [`RemoteSandboxChannel`](#remotesandboxchannel-1) | The raw worker op/sub relay channel (narrowed to the wire payload types). | [`RemoteSandbox`](pyric-sandbox-reference-api.md#remotesandbox).[`channel`](pyric-sandbox-reference-api.md#channel) |
+| <a id="currentuser-1"></a> `currentUser` | `public` | \{ `token?`: `Record`\<`string`, `unknown`\>; `uid`: `string`; \} | Current authenticated user across the sandbox. Mutated by `pyric/auth`'s `signInAnonymously` / `signInWithEmailAndPassword` / `signOut` / `sandbox.setUser`. Read per-call by service factories (e.g. a future `getFirestore(sandbox)` overload) so they see auth state changes without re-binding handles. Defaults to `null` (anonymous / signed out). **Independent of `withAuth({uid})`** — `withAuth` still produces a frozen [SandboxContext](pyric-firestore-reference-api.md#sandboxcontext) that carries its own identity for the runner's test code (the existing pattern: explicit identity per service call). `currentUser` exists for the `pyric/auth` mirror, where consumer app code drives identity through a stateful `Auth` handle rather than naming it per call. | - |
+| `currentUser.token?` | `public` | `Record`\<`string`, `unknown`\> | - | - |
+| `currentUser.uid` | `public` | `string` | - | - |
+| <a id="rtdb-1"></a> `rtdb` | `readonly` | [`RemoteRtdb`](#remotertdb) | RTDB conveniences (admin lens pinned). | - |
+| <a id="serveurl-1"></a> `serveUrl` | `readonly` | `string` | Base URL of the `pyric dev` this handle is attached to (used in error guidance: "open <serveUrl> in a browser and retry"). | - |
+| <a id="storage-1"></a> `storage` | `readonly` | [`RemoteStorage`](#remotestorage) | Storage conveniences (admin lens pinned; 8 MiB per-op byte cap). | - |
+
+#### Methods
+
+<a id="clearpersistence-2"></a>
+
+##### clearPersistence()
+
+```ts
+clearPersistence(): Promise<void>;
+```
+
+Wipe the persisted blob for this sandbox's `key`. In-memory state
+is left intact — call `reset()` if you want both. Useful for
+"sign out and forget" flows.
 
-- [`RemoteSandbox`](#remotesandbox)
+No-op when persistence is not enabled.
 
-#### Properties
+###### Returns
 
-| Property | Modifier | Type | Description |
-| :------ | :------ | :------ | :------ |
-| <a id="auth"></a> `auth` | `readonly` | [`RemoteAuthAdmin`](#remoteauthadmin) | Admin auth user CRUD. |
-| <a id="channel"></a> `channel` | `readonly` | [`RemoteSandboxChannel`](#remotesandboxchannel-1) | The raw worker op/sub relay channel (narrowed to the wire payload types). |
-| <a id="ready"></a> `ready` | `readonly` | `Promise`\<`void`\> | - |
-| <a id="rtdb"></a> `rtdb` | `readonly` | [`RemoteRtdb`](#remotertdb) | RTDB conveniences (admin lens pinned). |
-| <a id="storage"></a> `storage` | `readonly` | [`RemoteStorage`](#remotestorage) | Storage conveniences (admin lens pinned; 8 MiB per-op byte cap). |
+`Promise`\<`void`\>
 
-#### Methods
+###### Inherited from
 
-<a id="close"></a>
+[`RemoteSandbox`](pyric-sandbox-reference-api.md#remotesandbox).[`clearPersistence`](pyric-sandbox-reference-api.md#clearpersistence-2)
+
+<a id="close-2"></a>
 
 ##### close()
 
@@ -56,155 +961,251 @@ Close the connection. In-flight ops reject; subscriptions stop.
 
 `void`
 
-###### Inherited from
+<a id="dispose-2"></a>
 
-[`RemoteSandbox`](#remotesandbox).[`close`](#close-2)
+##### dispose()
 
-***
+```ts
+dispose(): void;
+```
 
-<a id="remoteauthadmin"></a>
+Tear down listener registries on this sandbox's environment without
+replacing it. Use this when you're about to discard the sandbox
+itself (e.g. `runner.reseed()` builds a fresh sandbox rather than
+calling `reset()`) and want to drop callback references on the
+outgoing instance defensively. Idempotent. Does not touch data.
 
-### RemoteAuthAdmin
+###### Returns
 
-Admin auth user-CRUD passthrough (never lensed — auth ops operate the
- worker's user pool directly, mirroring `pyric/auth`'s sandbox ops).
+`void`
 
-#### Methods
+###### Inherited from
 
-<a id="clearusers"></a>
+[`RemoteSandbox`](pyric-sandbox-reference-api.md#remotesandbox).[`dispose`](pyric-sandbox-reference-api.md#dispose-4)
 
-##### clearUsers()
+<a id="enablepersistence-2"></a>
+
+##### enablePersistence()
 
 ```ts
-clearUsers(): Promise<void>;
+enablePersistence(options: SandboxPersistenceOptions): Promise<void>;
 ```
 
-###### Returns
+Persist the sandbox's data to a backend and restore it on next
+`enablePersistence` call. The default `'indexedDB'` backend turns
+the sandbox into the host page's local Firestore — writes flush
+automatically and a fresh `initializeSandbox()` rehydrates from
+the prior session.
 
-`Promise`\<`void`\>
+Restoration happens before the promise resolves; awaiting this
+call is sufficient to guarantee in-memory state matches the
+persisted blob.
 
-<a id="createuser"></a>
+Idempotent across the same `key` — calling twice in one process
+is a no-op on the second call. Different keys are rejected as an
+error (a sandbox can persist to at most one backend at a time).
 
-##### createUser()
+Listener semantics: every write event the sandbox emits triggers
+a debounced flush (default 250ms). Browser hosts additionally
+flush on `beforeunload` so a page navigation doesn't lose the
+tail of the debounce window.
 
-```ts
-createUser(request: CreateUserRequest): Promise<AuthUserRecord>;
-```
+See [SandboxPersistenceOptions](pyric-sandbox-reference-api.md#sandboxpersistenceoptions) for backend selection and
+tuning.
 
 ###### Parameters
 
 | Parameter | Type |
 | :------ | :------ |
-| `request` | `CreateUserRequest` |
+| `options` | [`SandboxPersistenceOptions`](pyric-sandbox-reference-api.md#sandboxpersistenceoptions) |
 
 ###### Returns
 
-`Promise`\<`AuthUserRecord`\>
+`Promise`\<`void`\>
 
-<a id="deleteuser"></a>
+###### Inherited from
 
-##### deleteUser()
+[`RemoteSandbox`](pyric-sandbox-reference-api.md#remotesandbox).[`enablePersistence`](pyric-sandbox-reference-api.md#enablepersistence-2)
+
+<a id="enabletabsync-2"></a>
+
+##### enableTabSync()
 
 ```ts
-deleteUser(uid: string): Promise<void>;
+enableTabSync(options?: TabSyncOptions): () => void;
 ```
 
+Enable cross-tab realtime sync via `BroadcastChannel`. A write in
+this tab will propagate to every OTHER tab of the same origin that
+also called `enableTabSync`, causing their `onSnapshot` listeners to
+re-evaluate — restoring production's cross-client realtime behavior.
+
+**Opt-in, OFF by default.** Firestore only (RTDB is a follow-on).
+
+Returns a disable function. Calling it removes the `onEvent`
+subscription, the channel message listener, and closes the channel
+(when it was created internally). After disable, no further propagation
+occurs in either direction.
+
+**Multi-writer note:** concurrent writes from two tabs to the same doc
+produce last-write-wins divergence — there is no conflict resolution.
+The intended model is one active writer (one user, one tab) with
+observers in other tabs; this covers the overwhelming majority of
+local development scenarios.
+
 ###### Parameters
 
 | Parameter | Type |
 | :------ | :------ |
-| `uid` | `string` |
+| `options?` | [`TabSyncOptions`](pyric-sandbox-reference-api.md#tabsyncoptions) |
 
 ###### Returns
 
-`Promise`\<`void`\>
+```ts
+(): void;
+```
 
-<a id="listusers"></a>
+###### Returns
 
-##### listUsers()
+`void`
+
+###### See
+
+[TabSyncOptions](pyric-sandbox-reference-api.md#tabsyncoptions) for channel injection (tests) and originId.
+
+###### Example
 
 ```ts
-listUsers(): Promise<AuthUserRecord[]>;
+// In every tab that should participate in realtime:
+const sandbox = initializeSandbox();
+const disableSync = sandbox.enableTabSync();
+// Later, to stop syncing:
+disableSync();
 ```
 
-###### Returns
+###### Inherited from
 
-`Promise`\<`AuthUserRecord`[]\>
+[`RemoteSandbox`](pyric-sandbox-reference-api.md#remotesandbox).[`enableTabSync`](pyric-sandbox-reference-api.md#enabletabsync-2)
 
-<a id="updateuser"></a>
+<a id="flush-2"></a>
 
-##### updateUser()
+##### flush()
 
 ```ts
-updateUser(uid: string, request: UpdateUserRequest): Promise<AuthUserRecord>;
+flush(): Promise<void>;
 ```
 
-###### Parameters
+Force a snapshot to the configured persistence backend right now.
+Useful before a manual navigation, or in tests that need
+deterministic ordering against the debounce window. Resolves once
+the write hits the backend.
 
-| Parameter | Type |
-| :------ | :------ |
-| `uid` | `string` |
-| `request` | `UpdateUserRequest` |
+Throws if persistence is not enabled.
 
 ###### Returns
 
-`Promise`\<`AuthUserRecord`\>
+`Promise`\<`void`\>
 
-***
+###### Inherited from
 
-<a id="remotertdb"></a>
+[`RemoteSandbox`](pyric-sandbox-reference-api.md#remotesandbox).[`flush`](pyric-sandbox-reference-api.md#flush-4)
 
-### RemoteRtdb
+<a id="history-2"></a>
 
-Thin RTDB conveniences over the channel. Every call pins
-`actAs: { mode: 'admin' }` — firebase-admin's rules-bypass semantics,
-matching what `pyric-admin`'s database backend needs. Use the raw
-`channel` for lensed (rules-evaluated) access.
+##### history()
 
-#### Methods
+```ts
+history(): SandboxEvent[];
+```
 
-<a id="get"></a>
+Every [SandboxEvent](pyric-sandbox-reference-api.md#sandboxevent) this sandbox has emitted since init or
+the last `reset()`. Returns a defensive copy.
 
-##### get()
+Use this for replay: hand the array to `replay(events, rules)`
+from `pyric/sandbox` and the engine re-issues every
+captured write against a fresh sandbox.
+
+Unlike [onEvent](pyric-firestore-reference-api.md#onevent) (live stream from the moment of subscribe),
+`history()` returns *every* event the sandbox has seen — useful
+for consumers that attach late (e.g., loading a saved session
+before subscribing) or that need a snapshot at a particular moment.
+
+`reset()` and `dispose()` each append a closing `session_boundary`
+event; `reset()` then clears the history. Consumers that took a
+snapshot *before* reset retain the boundary in their copy.
+
+###### Returns
+
+[`SandboxEvent`](pyric-sandbox-reference-api.md#sandboxevent)[]
+
+###### Inherited from
+
+[`RemoteSandbox`](pyric-sandbox-reference-api.md#remotesandbox).[`history`](pyric-sandbox-reference-api.md#history-2)
+
+<a id="loadsnapshot-2"></a>
+
+##### loadSnapshot()
 
 ```ts
-get(path: string): Promise<unknown>;
+loadSnapshot(data: SandboxSnapshot): void;
 ```
 
-Read the value at `path` (null when absent).
+CLOBBER-restore the sandbox's entire state from a prior [snapshot](pyric-firestore-reference-api.md#snapshot):
+`reset()` (clears firestore + the signed-in session), then rebuild firestore
+from `data` and restore each registered service. This is a TOTAL replace —
+documents absent from `data` do NOT survive — and is the counterpart to
+[snapshot](pyric-firestore-reference-api.md#snapshot). It is what makes "transfer (clobber) one instance's data
+into another" and named-branch switching possible.
+
+Fires a `session_boundary` (reset phase), re-evaluates live listeners against
+the loaded state, and the next persistence flush writes the loaded state.
+Services present in `data` but not currently registered are skipped (a
+snapshot taken via [snapshot](pyric-firestore-reference-api.md#snapshot) always includes every registered
+service, so this only affects cross-instance imports from a sandbox that had
+a service this one lacks).
 
 ###### Parameters
 
 | Parameter | Type |
 | :------ | :------ |
-| `path` | `string` |
+| `data` | [`SandboxSnapshot`](pyric-sandbox-reference-api.md#sandboxsnapshot) |
 
 ###### Returns
 
-`Promise`\<`unknown`\>
+`void`
 
-<a id="onvalue"></a>
+###### Inherited from
 
-##### onValue()
+[`RemoteSandbox`](pyric-sandbox-reference-api.md#remotesandbox).[`loadSnapshot`](pyric-sandbox-reference-api.md#loadsnapshot-2)
+
+<a id="oncurrentuserchanged-2"></a>
+
+##### onCurrentUserChanged()
 
 ```ts
-onValue(
-   path: string,
-   callback: (snapshot: RemoteRtdbSnapshot) => void,
-   onError?: (err: Error & {
-  code: string;
+onCurrentUserChanged(cb: (user: {
+  token?: Record<string, unknown>;
+  uid: string;
 }) => void): () => void;
 ```
 
-Subscribe to the value at `path` (initial snapshot + every change).
+Subscribe to `currentUser` changes. Fires on every mutation —
+sign-in, sign-out, user swap. Does NOT fire on subscribe.
+
+Survives `reset()` and `dispose()` only as a no-op: a disposed
+sandbox emits nothing further; a reset sandbox clears
+`currentUser` to `null` (and fires the change) before swapping
+the env.
+
+Returns an unsubscribe function. Listener errors are swallowed —
+subscribers are observational, the sandbox does not propagate
+their errors.
 
 ###### Parameters
 
 | Parameter | Type |
 | :------ | :------ |
-| `path` | `string` |
-| `callback` | (`snapshot`: [`RemoteRtdbSnapshot`](#remotertdbsnapshot)) => `void` |
-| `onError?` | (`err`: `Error` & \{ `code`: `string`; \}) => `void` |
+| `cb` | (`user`: \{ `token?`: `Record`\<`string`, `unknown`\>; `uid`: `string`; \}) => `void` |
 
 ###### Returns
 
@@ -216,157 +1217,287 @@ Subscribe to the value at `path` (initial snapshot + every change).
 
 `void`
 
-<a id="push"></a>
+###### Inherited from
 
-##### push()
+[`RemoteSandbox`](pyric-sandbox-reference-api.md#remotesandbox).[`onCurrentUserChanged`](pyric-sandbox-reference-api.md#oncurrentuserchanged-2)
+
+<a id="onevent-2"></a>
+
+##### onEvent()
 
 ```ts
-push(path: string, value?: unknown): Promise<{
-  key: string;
-  path: string;
-}>;
+onEvent(cb: (event: SandboxEvent) => void): () => void;
 ```
 
-Push `value` under a CLIENT-minted 20-char push id (the worker-protocol
- contract: `rtdb.push` carries the key, so `.key` is known synchronously
- on the pyric-admin side). Resolves with the minted key + full path.
+Subscribe to every event the sandbox emits — see [SandboxEvent](pyric-sandbox-reference-api.md#sandboxevent)
+for the discriminated-union shape. One subscription covers
+request/denial/snapshot-error/listener-lifecycle/session-boundary;
+filter on `event.kind` to recover individual streams.
+
+Replaces the prior three-channel surface (`onRequest` / `onDenial`
+/ `onSnapshotError`) — see issue #307. Filter cookbook:
+  - All denials:    `event.kind === 'request' && event.result === 'deny'`
+  - Stream errors:  `event.kind === 'listener_errored'`
+  - Per-op traffic: `event.kind === 'request'`
+
+Survives `sandbox.reset()` — the subscription is held on the
+sandbox, not on the underlying environment. A `session_boundary`
+event with `phase: 'reset'` fires before the env swap so consumers
+can segment their stream.
+
+Returns an unsubscribe function. Listener errors are swallowed so a
+faulty subscriber can't change rule semantics or hide other events.
+Both synchronous throws and rejected Promises from async callbacks
+are silently discarded — subscribers are **observational**, the
+sandbox doesn't await them and doesn't propagate their errors.
 
 ###### Parameters
 
 | Parameter | Type |
 | :------ | :------ |
-| `path` | `string` |
-| `value?` | `unknown` |
+| `cb` | (`event`: [`SandboxEvent`](pyric-sandbox-reference-api.md#sandboxevent)) => `void` |
 
 ###### Returns
 
-`Promise`\<\{
-  `key`: `string`;
-  `path`: `string`;
-\}\>
+```ts
+(): void;
+```
 
-<a id="remove"></a>
+###### Returns
 
-##### remove()
+`void`
+
+###### Inherited from
+
+[`RemoteSandbox`](pyric-sandbox-reference-api.md#remotesandbox).[`onEvent`](pyric-sandbox-reference-api.md#onevent-2)
+
+<a id="registerpersistableservice-2"></a>
+
+##### registerPersistableService()
 
 ```ts
-remove(path: string): Promise<void>;
+registerPersistableService(name: string, hooks: PersistableService): () => void;
 ```
 
+Register a service (auth, storage, …) as a persistence participant.
+The sandbox calls `hooks.snapshot()` on every flush and
+`hooks.restore(data)` on restore. If `hooks.subscribe` is provided,
+the persistence controller subscribes and schedules a debounced
+flush on each change — so auth-user edits flush promptly, not only
+on the next Firestore write.
+
+Returns an unregister function — call it if the service is torn
+down before the sandbox is disposed (uncommon in practice; the
+sandbox's `dispose()` clears the registry anyway).
+
+Throws `failed-precondition` when a service with the same `name` is
+already registered — the auth package registers `'auth'` once when
+`getAuth(sandbox)` first creates a backend, so accidental double-
+registration is a caller bug, not a no-op.
+
+**Advanced / internal API.** Service packages (auth, storage) call
+this when they first attach to a sandbox. Consumer app code should
+not need to call this directly.
+
 ###### Parameters
 
 | Parameter | Type |
 | :------ | :------ |
-| `path` | `string` |
+| `name` | `string` |
+| `hooks` | [`PersistableService`](pyric-sandbox-reference-api.md#persistableservice) |
 
 ###### Returns
 
-`Promise`\<`void`\>
+```ts
+(): void;
+```
 
-<a id="set"></a>
+###### Returns
 
-##### set()
+`void`
+
+###### Inherited from
+
+[`RemoteSandbox`](pyric-sandbox-reference-api.md#remotesandbox).[`registerPersistableService`](pyric-sandbox-reference-api.md#registerpersistableservice-2)
+
+<a id="reset-2"></a>
+
+##### reset()
 
 ```ts
-set(path: string, value: unknown): Promise<void>;
+reset(): void;
 ```
 
-###### Parameters
+Reset the underlying environment to a fresh state — wipes data,
+rules, and any service-specific configuration.
 
-| Parameter | Type |
-| :------ | :------ |
-| `path` | `string` |
-| `value` | `unknown` |
+Snapshot listeners attached to the OLD environment are dropped at
+the swap — they can't survive because their target docs have been
+wiped. `onEvent` subscribers DO survive — the registry lives on
+the sandbox, and a `session_boundary` event with `phase: 'reset'`
+fires before the swap so subscribers know the rollover happened.
+Existing [SandboxContext](pyric-firestore-reference-api.md#sandboxcontext)s continue to work — their sandbox
+reference is stable; subsequent operations resolve to the new env.
 
 ###### Returns
 
-`Promise`\<`void`\>
+`void`
 
-<a id="update"></a>
+###### Inherited from
 
-##### update()
+[`RemoteSandbox`](pyric-sandbox-reference-api.md#remotesandbox).[`reset`](pyric-sandbox-reference-api.md#reset-4)
+
+<a id="resetall-2"></a>
+
+##### resetAll()
 
 ```ts
-update(path: string, values: Record<string, unknown>): Promise<void>;
+resetAll(): Promise<{
+  errors: string[];
+}>;
 ```
 
-###### Parameters
+Reset the WHOLE sandbox: [reset](pyric-firestore-reference-api.md#reset) (Firestore env + signed-in
+session), then clear every registered persistable service that
+provides a [PersistableService.reset](pyric-sandbox-reference-api.md#reset-2) hook — auth users, the
+RTDB tree, storage objects. This is the one sandbox-owned "wipe
+everything" path: because it iterates the service registry, a new
+service that registers with a `reset` hook is cleared automatically,
+and a consumer (Pyric Studio's reset) cannot forget one.
 
-| Parameter | Type |
-| :------ | :------ |
-| `path` | `string` |
-| `values` | `Record`\<`string`, `unknown`\> |
+Service resets may be async (storage clears IndexedDB stores); the
+returned promise resolves when every service has finished clearing.
+A service whose `reset` throws is isolated (others still clear) and
+REPORTED in the returned `errors` (as `name: message`) — a reset that
+leaves data behind must never look successful to the caller.
 
 ###### Returns
 
-`Promise`\<`void`\>
+`Promise`\<\{
+  `errors`: `string`[];
+\}\>
 
-***
+###### Inherited from
 
-<a id="remotertdbsnapshot"></a>
+[`RemoteSandbox`](pyric-sandbox-reference-api.md#remotesandbox).[`resetAll`](pyric-sandbox-reference-api.md#resetall-2)
 
-### RemoteRtdbSnapshot
+<a id="runwithprovenance-2"></a>
 
-Wire shape of an RTDB snapshot as the worker host serializes it.
+##### runWithProvenance()?
 
-#### Properties
+```ts
+optional runWithProvenance<T>(provenance: EventProvenance, fn: () => T): T;
+```
 
-| Property | Type |
+Run `fn` with ambient [EventProvenance](pyric-sandbox-reference-api.md#eventprovenance) defaults: every event
+emitted SYNCHRONOUSLY during `fn` that doesn't already carry a
+provenance field (on the event itself or via an explicit per-emit
+override) is stamped with these values instead of the global
+defaults. This is the mechanical "who issued this op" seam the
+serve worker uses to tag Studio-issued ops (`actor: { kind:
+'studio' }`) and to stamp the auth lens an op ran under
+(`authLens`) — declared by the caller that issues the op, never
+inferred from the op's shape.
+
+SYNCHRONOUS WINDOW: the ambient values apply only until `fn`
+returns (for an async `fn`, its synchronous prefix — which covers
+the local environment's rules eval + event emission, since those
+run before the op's promise is handed back). Work an op DEFERS
+(snapshot-listener deliveries and re-evals drain on a microtask,
+off-stack) is intentionally OUTSIDE the window: a listener re-eval
+belongs to the listener's owner, not to whoever's write triggered
+it. Nested calls stack — the innermost window wins per field, and
+each window restores the previous one on exit (including on throw).
+
+OPTIONAL because remote sandbox proxies can't provide an ambient
+emit window (events are emitted in the worker they front). Callers
+spell `sandbox.runWithProvenance?.(prov, fn) ?? fn()`.
+
+###### Type Parameters
+
+| Type Parameter |
+| :------ |
+| `T` |
+
+###### Parameters
+
+| Parameter | Type |
 | :------ | :------ |
-| <a id="exists"></a> `exists` | `boolean` |
-| <a id="key"></a> `key` | `string` |
-| <a id="size"></a> `size` | `number` |
-| <a id="value"></a> `value` | `unknown` |
+| `provenance` | [`EventProvenance`](pyric-sandbox-reference-api.md#eventprovenance) |
+| `fn` | () => `T` |
 
-***
+###### Returns
 
-<a id="remotesandbox"></a>
+`T`
 
-### RemoteSandbox
+###### Inherited from
 
-The Node-side remote sandbox handle. Extends `pyric/sandbox`'s branded
-RemoteSandboxBase — structurally a full `Sandbox`, so it can be
-passed to `pyric-admin/app`'s `initializeApp({ sandbox })`, whose RTDB and
-Auth backends dispatch on the brand and route through [channel](#channel-1).
+[`RemoteSandbox`](pyric-sandbox-reference-api.md#remotesandbox).[`runWithProvenance`](pyric-sandbox-reference-api.md#runwithprovenance-2)
 
-Sandbox members that are genuinely sync-only (`admin`, `snapshot()`,
-`history()`, `onEvent`, `currentUser`, …) cannot be mirrored over the
-wire in slice 1 and throw a remediating `unimplemented` error naming
-what to do instead. Implemented members: `withAuth` (pure local pair
-construction) and `dispose` (aliases [close](#close-2)).
+<a id="snapshot-2"></a>
 
-#### Extends
+##### snapshot()
 
-- `unknown`
+```ts
+snapshot(): SandboxSnapshot;
+```
 
-#### Extended by
+Capture a snapshot of every service's state. For v1 with only
+Firestore, the return value carries a `firestore` key mapping doc
+paths to data. Future services will add their own keys.
 
-- [`LazyRemoteSandbox`](#lazyremotesandbox)
+###### Returns
 
-#### Properties
+[`SandboxSnapshot`](pyric-sandbox-reference-api.md#sandboxsnapshot)
 
-| Property | Modifier | Type | Description |
-| :------ | :------ | :------ | :------ |
-| <a id="auth-1"></a> `auth` | `readonly` | [`RemoteAuthAdmin`](#remoteauthadmin) | Admin auth user CRUD. |
-| <a id="channel-1"></a> `channel` | `readonly` | [`RemoteSandboxChannel`](#remotesandboxchannel-1) | The raw worker op/sub relay channel (narrowed to the wire payload types). |
-| <a id="rtdb-1"></a> `rtdb` | `readonly` | [`RemoteRtdb`](#remotertdb) | RTDB conveniences (admin lens pinned). |
-| <a id="storage-1"></a> `storage` | `readonly` | [`RemoteStorage`](#remotestorage) | Storage conveniences (admin lens pinned; 8 MiB per-op byte cap). |
+###### Inherited from
 
-#### Methods
+[`RemoteSandbox`](pyric-sandbox-reference-api.md#remotesandbox).[`snapshot`](pyric-sandbox-reference-api.md#snapshot-4)
 
-<a id="close-2"></a>
+<a id="withauth-2"></a>
 
-##### close()
+##### withAuth()
 
 ```ts
-close(): void;
+withAuth(auth: {
+  token?: Record<string, unknown>;
+  uid: string;
+}): SandboxContext;
 ```
 
-Close the connection. In-flight ops reject; subscriptions stop.
+Derive a context bound to this sandbox under the given auth
+identity. Operations through services attached to the returned
+context evaluate rules under that identity. Many contexts can
+coexist for one sandbox; data is shared.
+
+`null` is anonymous; an `AuthState` object names the user (and
+optional custom claims). Passing `undefined` is a deliberate
+error — say `withAuth(null)` for anonymous so the call site is
+unambiguous.
+
+###### Parameters
+
+| Parameter | Type |
+| :------ | :------ |
+| `auth` | \{ `token?`: `Record`\<`string`, `unknown`\>; `uid`: `string`; \} |
+| `auth.token?` | `Record`\<`string`, `unknown`\> |
+| `auth.uid` | `string` |
 
 ###### Returns
 
-`void`
+[`SandboxContext`](pyric-firestore-reference-api.md#sandboxcontext)
+
+###### Example
+
+```ts
+const sandbox = initializeSandbox();
+const dbAlice = getFirestore(sandbox.withAuth({ uid: 'alice' }));
+const dbAnon  = getFirestore(sandbox.withAuth(null));
+```
+
+###### Inherited from
+
+[`RemoteSandbox`](pyric-sandbox-reference-api.md#remotesandbox).[`withAuth`](pyric-sandbox-reference-api.md#withauth-4)
 
 ***
 
@@ -452,7 +1583,7 @@ to `onError` instead. Returns the unsubscribe function.
 
 #### Methods
 
-<a id="dispose"></a>
+<a id="dispose-4"></a>
 
 ##### dispose()
 
@@ -486,7 +1617,7 @@ Feed one parsed message from the transport into the core.
 
 | Parameter | Type |
 | :------ | :------ |
-| `msg` | `BridgeMessage` |
+| `msg` | [`BridgeMessage`](pyric-cli-bridge-client-reference-api.md#bridgemessage) |
 
 ###### Returns
 
@@ -600,7 +1731,7 @@ Read the object's `FullMetadata`.
 
 ###### Returns
 
-`Promise`\<`FullMetadata`\>
+`Promise`\<[`FullMetadata`](pyric-storage-reference-api.md#fullmetadata)\>
 
 <a id="listall"></a>
 
@@ -669,7 +1800,7 @@ Upload `data` at `path` (replaces any existing object). Resolves with
 
 ###### Returns
 
-`Promise`\<`FullMetadata`\>
+`Promise`\<[`FullMetadata`](pyric-storage-reference-api.md#fullmetadata)\>
 
 ***
 
@@ -713,7 +1844,7 @@ send(msg: BridgeMessage): void;
 
 | Parameter | Type |
 | :------ | :------ |
-| `msg` | `BridgeMessage` |
+| `msg` | [`BridgeMessage`](pyric-cli-bridge-client-reference-api.md#bridgemessage) |
 
 ###### Returns