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

package/dist/serve/docs-ui/docs/pyric-sandbox-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. -->
 
 ## Classes
 
@@ -43,7 +42,7 @@ Error.constructor
 
 ### SandboxContextImpl
 
-Identity-bearing handle on a [Sandbox](#sandbox-3). A
+Identity-bearing handle on a [Sandbox](pyric-firestore-reference-api.md#sandbox). A
 `(sandbox, auth, operationContext)`
 tuple — cheap to create, immutable, freely shareable. Service
 factories require a `SandboxContext`; bare `Sandbox` is a type
@@ -56,7 +55,7 @@ factories; consumers don't construct it directly.
 
 #### Implements
 
-- [`SandboxContext`](#sandboxcontext)
+- [`SandboxContext`](pyric-firestore-reference-api.md#sandboxcontext)
 
 #### Constructors
 
@@ -78,7 +77,7 @@ new SandboxContextImpl(
 
 | Parameter | Type |
 | :------ | :------ |
-| `sandbox` | [`Sandbox`](#sandbox-3) |
+| `sandbox` | [`Sandbox`](pyric-firestore-reference-api.md#sandbox) |
 | `auth` | \{ `token?`: `Record`\<`string`, `unknown`\>; `uid`: `string`; \} |
 | `auth.token?` | `Record`\<`string`, `unknown`\> |
 | `auth.uid?` | `string` |
@@ -96,7 +95,7 @@ new SandboxContextImpl(
 | `auth.token?` | `public` | `Record`\<`string`, `unknown`\> | - |
 | `auth.uid` | `public` | `string` | - |
 | <a id="operationcontext"></a> `operationContext` | `readonly` | [`OperationContext`](#operationcontext-2) | Immutable provenance bound to every operation issued through this handle. |
-| <a id="sandbox"></a> `sandbox` | `readonly` | [`Sandbox`](#sandbox-3) | The data foundation this context operates against. |
+| <a id="sandbox"></a> `sandbox` | `readonly` | [`Sandbox`](pyric-firestore-reference-api.md#sandbox) | The data foundation this context operates against. |
 
 #### Methods
 
@@ -125,101 +124,37 @@ optional plan identity.
 
 ###### Returns
 
-[`SandboxContext`](#sandboxcontext)
+[`SandboxContext`](pyric-firestore-reference-api.md#sandboxcontext)
 
 ###### Implementation of
 
-[`SandboxContext`](#sandboxcontext).[`withAuth`](#withauth-8)
-
-***
-
-<a id="sandboxerror"></a>
-
-### SandboxError
-
-Sandbox-layer error. Catch with `instanceof SandboxError` and switch
-on `code`. `denialContext` is populated for `permission-denied` only
-(and only after Slice 4 wires it through).
-
-Two construction forms are supported:
-  - Positional: `new SandboxError(code, message, denialContext?)` —
-    the original signature, kept for backward compatibility with
-    existing internal call sites.
-  - Options bag: `new SandboxError({ code, message, remediation? })` —
-    used when attaching remediation guidance.
-
-#### Extends
-
-- `Error`
-
-#### Constructors
-
-<a id="constructor-2"></a>
-
-##### Constructor
-
-```ts
-new SandboxError(
-   code: SandboxErrorCode,
-   message: string,
-   denialContext?: DenialContext): SandboxError;
-```
-
-###### Parameters
-
-| Parameter | Type |
-| :------ | :------ |
-| `code` | [`SandboxErrorCode`](#sandboxerrorcode-1) |
-| `message` | `string` |
-| `denialContext?` | [`DenialContext`](#denialcontext-1) |
-
-###### Returns
-
-[`SandboxError`](#sandboxerror)
-
-###### Overrides
-
-```ts
-Error.constructor
-```
-
-##### Constructor
-
-```ts
-new SandboxError(options: SandboxErrorOptions): SandboxError;
-```
-
-###### Parameters
-
-| Parameter | Type |
-| :------ | :------ |
-| `options` | `SandboxErrorOptions` |
+[`SandboxContext`](pyric-firestore-reference-api.md#sandboxcontext).[`withAuth`](pyric-firestore-reference-api.md#withauth-2)
 
-###### Returns
+## Interfaces
 
-[`SandboxError`](#sandboxerror)
+<a id="activityeventprovenance"></a>
 
-###### Overrides
+### ActivityEventProvenance
 
-```ts
-Error.constructor
-```
+Provenance consumed only by the firestore activity diagnostics. Bundled in
+one optional record so the shared operation type carries a single
+activity-owned seam rather than loose per-feature fields.
 
 #### Properties
 
-| Property | Modifier | Type |
+| Property | Type | Description |
 | :------ | :------ | :------ |
-| <a id="code"></a> `code` | `readonly` | [`SandboxErrorCode`](#sandboxerrorcode-1) |
-| <a id="denialcontext"></a> `denialContext?` | `readonly` | [`DenialContext`](#denialcontext-1) |
-| <a id="remediation"></a> `remediation?` | `readonly` | `string` |
+| <a id="groupkind"></a> `groupKind?` | `"transaction"` | Marks worker-split operations that belong to a transaction for activity diagnostics. |
+| <a id="listenerid"></a> `listenerId?` | `string` | Stable host subscription identity used only by activity diagnostics. |
+| <a id="listenerlifecycle"></a> `listenerLifecycle?` | `"reauthorize"` | Marks lifecycle caused by transparent auth reauthorization, not app code. |
 
-## Interfaces
+***
 
 <a id="branch"></a>
 
 ### Branch
 
-An isolated, in-memory experiment seeded from a [SandboxSnapshot](#sandboxsnapshot-2).
+An isolated, in-memory experiment seeded from a [SandboxSnapshot](#sandboxsnapshot).
 
 A branch owns its own [LocalSandbox](#localsandbox) (fully isolated from the source —
 separate `LocalEnvironment`, separate event history) plus the
@@ -230,7 +165,7 @@ applied events are what [promote](#promote) replays onto the target.
 
 | Property | Modifier | Type | Description |
 | :------ | :------ | :------ | :------ |
-| <a id="base"></a> `base` | `readonly` | [`SandboxSnapshot`](#sandboxsnapshot-2) | The snapshot this branch was forked from. Retained so [diff](#diff) and [promote](#promote) can reason about the baseline. |
+| <a id="base"></a> `base` | `readonly` | [`SandboxSnapshot`](#sandboxsnapshot) | The snapshot this branch was forked from. Retained so [diff](#diff) and [promote](#promote) can reason about the baseline. |
 | <a id="discarded"></a> `discarded` | `public` | `boolean` | Flipped by [discard](#discard); subsequent [apply](#apply)/[promote](#promote) calls throw. |
 | <a id="events"></a> `events` | `readonly` | [`SandboxEvent`](#sandboxevent)[] | Write/op events applied to this branch since fork, in order. These are replayed onto the target by [promote](#promote). |
 | <a id="rules"></a> `rules` | `readonly` | `string` | Rules the branch was forked with — carried so [promote](#promote) can re-seed a replay target identically. |
@@ -335,7 +270,7 @@ removeEventListener(type: "message", listener: (ev: {
 
 ***
 
-<a id="denialcontext-1"></a>
+<a id="denialcontext"></a>
 
 ### DenialContext
 
@@ -358,9 +293,14 @@ reference traces.
 | `auth.token?` | `Record`\<`string`, `unknown`\> | - |
 | `auth.uid` | `string` | - |
 | <a id="failedfields"></a> `failedFields?` | `string`[] | Field paths in `request.resource.data` that the rule referenced and that failed. |
+| <a id="query"></a> `query?` | \{ `limit?`: `number`; `offset?`: `number`; `orderBy?`: `string`; `where?`: \{ `field`: `string`; `op`: `string`; `value`: `string` \| `number` \| `boolean`; \}[]; \} | Machine-readable descriptor of the denied query's where/orderBy/limit shape (RULES-B11). Populated when a `list`/query is denied as statically unprovable ("rules are not filters"), so consumers can render the exact query the engine rejected without re-deriving it. Absent for single-doc and non-query denials. |
+| `query.limit?` | `number` | - |
+| `query.offset?` | `number` | - |
+| `query.orderBy?` | `string` | - |
+| `query.where?` | \{ `field`: `string`; `op`: `string`; `value`: `string` \| `number` \| `boolean`; \}[] | - |
 | <a id="reasons"></a> `reasons?` | `string`[] | Raw simulator reasoning lines (the underlying engine's `debugMessages`). Always present on `permission-denied`. Stable enough for log surfacing; not stable as machine-parseable data. |
-| <a id="request"></a> `request?` | \{ `method`: `"get"` \| `"list"` \| `"create"` \| `"update"` \| `"delete"`; `path`: `string`; `resourceData?`: `Record`\<`string`, `unknown`\>; \} | Eval-time request shape — what the rule saw on `request.*`. Lets callers render a "why did this deny" frame (auth, method, path, `request.resource.data` with sentinels resolved) without re-deriving any of it from out-of-band state. |
-| `request.method` | `"get"` \| `"list"` \| `"create"` \| `"update"` \| `"delete"` | - |
+| <a id="request"></a> `request?` | \{ `method`: `"delete"` \| `"get"` \| `"list"` \| `"create"` \| `"update"`; `path`: `string`; `resourceData?`: `Record`\<`string`, `unknown`\>; \} | Eval-time request shape — what the rule saw on `request.*`. Lets callers render a "why did this deny" frame (auth, method, path, `request.resource.data` with sentinels resolved) without re-deriving any of it from out-of-band state. |
+| `request.method` | `"delete"` \| `"get"` \| `"list"` \| `"create"` \| `"update"` | - |
 | `request.path` | `string` | - |
 | `request.resourceData?` | `Record`\<`string`, `unknown`\> | The user's proposed `request.resource.data` — pre-resolution. `FieldValue.*` sentinels are preserved as their marker shapes (`{ __type: 'serverTimestamp' }`, etc.). The rule engine evaluated against the resolved form; what surfaces here is the caller's INTENT so consumers see what they tried to write. Absent for reads (no proposed write) and for `delete` (no payload). |
 | <a id="resource"></a> `resource?` | \{ `data`: `Record`\<`string`, `unknown`\>; `exists`: `boolean`; \} | Eval-time existing-document snapshot — what the rule saw on `resource.data`. `null` data with `exists: false` mirrors how the rule sees an absent doc. Absent for collection ops (`list`). |
@@ -378,7 +318,7 @@ reference traces.
 
 Eval-time payload emitted to Sandbox.onDenial subscribers.
 
-Mirrors the structured fields [DenialContext](#denialcontext-1) carries (`request`
+Mirrors the structured fields [DenialContext](#denialcontext) carries (`request`
 + `resource` + `reasons` + `auth`) so a host environment that wants
 to surface denials independent of try/catch behavior gets the same
 frame either way.
@@ -390,11 +330,11 @@ frame either way.
 | <a id="auth-2"></a> `auth?` | \{ `token?`: `Record`\<`string`, `unknown`\>; `uid`: `string`; \} |
 | `auth.token?` | `Record`\<`string`, `unknown`\> |
 | `auth.uid` | `string` |
-| <a id="code-1"></a> `code` | `"permission-denied"` |
+| <a id="code"></a> `code` | `"permission-denied"` |
 | <a id="message"></a> `message` | `string` |
 | <a id="reasons-1"></a> `reasons?` | `string`[] |
-| <a id="request-1"></a> `request?` | \{ `method`: `"get"` \| `"list"` \| `"create"` \| `"update"` \| `"delete"`; `path`: `string`; `resourceData?`: `Record`\<`string`, `unknown`\>; \} |
-| `request.method` | `"get"` \| `"list"` \| `"create"` \| `"update"` \| `"delete"` |
+| <a id="request-1"></a> `request?` | \{ `method`: `"delete"` \| `"get"` \| `"list"` \| `"create"` \| `"update"`; `path`: `string`; `resourceData?`: `Record`\<`string`, `unknown`\>; \} |
+| `request.method` | `"delete"` \| `"get"` \| `"list"` \| `"create"` \| `"update"` |
 | `request.path` | `string` |
 | `request.resourceData?` | `Record`\<`string`, `unknown`\> |
 | <a id="resource-1"></a> `resource?` | \{ `data`: `Record`\<`string`, `unknown`\>; `exists`: `boolean`; \} |
@@ -414,6 +354,7 @@ consumers migrate to the canonical `operationContext`.
 
 | Property | Type | Description |
 | :------ | :------ | :------ |
+| <a id="activity"></a> `activity?` | [`ActivityEventProvenance`](#activityeventprovenance) | Firestore activity-diagnostics provenance; absent outside that flow. |
 | <a id="actor"></a> `actor?` | [`EventActor`](#eventactor) | - |
 | <a id="authlens"></a> `authLens?` | [`AuthLens`](#authlens-2) | - |
 | <a id="operationcontext-1"></a> `operationContext?` | [`OperationContext`](#operationcontext-2) | - |
@@ -444,8 +385,8 @@ on the errored phase only.
 | `error.reasons?` | `string`[] | - |
 | <a id="id"></a> `id` | `string` | - |
 | <a id="kind"></a> `kind` | `"listener_attach"` \| `"listener_detach"` \| `"listener_errored"` | - |
-| <a id="listenerid"></a> `listenerId` | `string` | - |
-| <a id="target"></a> `target` | \| \{ `kind`: `"doc"`; `path`: `string`; \} \| \{ `collection`: `string`; `kind`: `"query"`; \} | - |
+| <a id="listenerid-1"></a> `listenerId` | `string` | - |
+| <a id="target"></a> `target` | \| \{ `kind`: `"doc"`; `path`: `string`; \} \| \{ `collection`: `string`; `kind`: `"query"`; `query?`: `unknown`; \} | - |
 
 ***
 
@@ -456,12 +397,12 @@ on the errored phase only.
 An in-process sandbox created by [initializeSandbox](#initializesandbox).
 
 Service controls whose implementation requires synchronous access to local
-state accept this type. Remote worker handles remain [Sandbox](#sandbox-3)s, but
+state accept this type. Remote worker handles remain [Sandbox](pyric-firestore-reference-api.md#sandbox)s, but
 are deliberately not assignable to this local-only interface.
 
 #### Extends
 
-- [`Sandbox`](#sandbox-3)
+- [`Sandbox`](pyric-firestore-reference-api.md#sandbox)
 
 #### Properties
 
@@ -469,7 +410,7 @@ are deliberately not assignable to this local-only interface.
 | :------ | :------ | :------ | :------ |
 | <a id="local_sandbox"></a> `[LOCAL_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="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](#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. |
+| <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` | - |
 
@@ -495,7 +436,7 @@ No-op when persistence is not enabled.
 
 ###### Inherited from
 
-[`Sandbox`](#sandbox-3).[`clearPersistence`](#clearpersistence-4)
+[`Sandbox`](pyric-firestore-reference-api.md#sandbox).[`clearPersistence`](pyric-firestore-reference-api.md#clearpersistence)
 
 <a id="dispose"></a>
 
@@ -517,7 +458,7 @@ outgoing instance defensively. Idempotent. Does not touch data.
 
 ###### Inherited from
 
-[`Sandbox`](#sandbox-3).[`dispose`](#dispose-6)
+[`Sandbox`](pyric-firestore-reference-api.md#sandbox).[`dispose`](pyric-firestore-reference-api.md#dispose)
 
 <a id="enablepersistence"></a>
 
@@ -561,7 +502,7 @@ tuning.
 
 ###### Inherited from
 
-[`Sandbox`](#sandbox-3).[`enablePersistence`](#enablepersistence-4)
+[`Sandbox`](pyric-firestore-reference-api.md#sandbox).[`enablePersistence`](pyric-firestore-reference-api.md#enablepersistence)
 
 <a id="enabletabsync"></a>
 
@@ -621,7 +562,7 @@ disableSync();
 
 ###### Inherited from
 
-[`Sandbox`](#sandbox-3).[`enableTabSync`](#enabletabsync-4)
+[`Sandbox`](pyric-firestore-reference-api.md#sandbox).[`enableTabSync`](pyric-firestore-reference-api.md#enabletabsync)
 
 <a id="flush"></a>
 
@@ -644,7 +585,7 @@ Throws if persistence is not enabled.
 
 ###### Inherited from
 
-[`Sandbox`](#sandbox-3).[`flush`](#flush-6)
+[`Sandbox`](pyric-firestore-reference-api.md#sandbox).[`flush`](pyric-firestore-reference-api.md#flush)
 
 <a id="history"></a>
 
@@ -661,7 +602,7 @@ 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](#onevent-4) (live stream from the moment of subscribe),
+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.
@@ -676,7 +617,7 @@ snapshot *before* reset retain the boundary in their copy.
 
 ###### Inherited from
 
-[`Sandbox`](#sandbox-3).[`history`](#history-4)
+[`Sandbox`](pyric-firestore-reference-api.md#sandbox).[`history`](pyric-firestore-reference-api.md#history)
 
 <a id="loadsnapshot"></a>
 
@@ -686,17 +627,17 @@ snapshot *before* reset retain the boundary in their copy.
 loadSnapshot(data: SandboxSnapshot): void;
 ```
 
-CLOBBER-restore the sandbox's entire state from a prior [snapshot](#snapshot-6):
+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](#snapshot-6). It is what makes "transfer (clobber) one instance's data
+[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](#snapshot-6) always includes every registered
+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).
 
@@ -704,7 +645,7 @@ a service this one lacks).
 
 | Parameter | Type |
 | :------ | :------ |
-| `data` | [`SandboxSnapshot`](#sandboxsnapshot-2) |
+| `data` | [`SandboxSnapshot`](#sandboxsnapshot) |
 
 ###### Returns
 
@@ -712,7 +653,7 @@ a service this one lacks).
 
 ###### Inherited from
 
-[`Sandbox`](#sandbox-3).[`loadSnapshot`](#loadsnapshot-4)
+[`Sandbox`](pyric-firestore-reference-api.md#sandbox).[`loadSnapshot`](pyric-firestore-reference-api.md#loadsnapshot)
 
 <a id="oncurrentuserchanged"></a>
 
@@ -755,7 +696,7 @@ their errors.
 
 ###### Inherited from
 
-[`Sandbox`](#sandbox-3).[`onCurrentUserChanged`](#oncurrentuserchanged-4)
+[`Sandbox`](pyric-firestore-reference-api.md#sandbox).[`onCurrentUserChanged`](pyric-firestore-reference-api.md#oncurrentuserchanged)
 
 <a id="onevent"></a>
 
@@ -805,7 +746,7 @@ sandbox doesn't await them and doesn't propagate their errors.
 
 ###### Inherited from
 
-[`Sandbox`](#sandbox-3).[`onEvent`](#onevent-4)
+[`Sandbox`](pyric-firestore-reference-api.md#sandbox).[`onEvent`](pyric-firestore-reference-api.md#onevent)
 
 <a id="registerpersistableservice"></a>
 
@@ -854,7 +795,7 @@ not need to call this directly.
 
 ###### Inherited from
 
-[`Sandbox`](#sandbox-3).[`registerPersistableService`](#registerpersistableservice-4)
+[`Sandbox`](pyric-firestore-reference-api.md#sandbox).[`registerPersistableService`](pyric-firestore-reference-api.md#registerpersistableservice)
 
 <a id="reset"></a>
 
@@ -872,7 +813,7 @@ 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](#sandboxcontext)s continue to work — their sandbox
+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
@@ -881,7 +822,41 @@ reference is stable; subsequent operations resolve to the new env.
 
 ###### Inherited from
 
-[`Sandbox`](#sandbox-3).[`reset`](#reset-4)
+[`Sandbox`](pyric-firestore-reference-api.md#sandbox).[`reset`](pyric-firestore-reference-api.md#reset)
+
+<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](#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
+
+[`Sandbox`](pyric-firestore-reference-api.md#sandbox).[`resetAll`](pyric-firestore-reference-api.md#resetall)
 
 <a id="runwithprovenance"></a>
 
@@ -934,7 +909,7 @@ spell `sandbox.runWithProvenance?.(prov, fn) ?? fn()`.
 
 ###### Inherited from
 
-[`Sandbox`](#sandbox-3).[`runWithProvenance`](#runwithprovenance-4)
+[`Sandbox`](pyric-firestore-reference-api.md#sandbox).[`runWithProvenance`](pyric-firestore-reference-api.md#runwithprovenance)
 
 <a id="snapshot"></a>
 
@@ -950,11 +925,11 @@ paths to data. Future services will add their own keys.
 
 ###### Returns
 
-[`SandboxSnapshot`](#sandboxsnapshot-2)
+[`SandboxSnapshot`](#sandboxsnapshot)
 
 ###### Inherited from
 
-[`Sandbox`](#sandbox-3).[`snapshot`](#snapshot-6)
+[`Sandbox`](pyric-firestore-reference-api.md#sandbox).[`snapshot`](pyric-firestore-reference-api.md#snapshot)
 
 <a id="withauth-2"></a>
 
@@ -987,7 +962,7 @@ unambiguous.
 
 ###### Returns
 
-[`SandboxContext`](#sandboxcontext)
+[`SandboxContext`](pyric-firestore-reference-api.md#sandboxcontext)
 
 ###### Example
 
@@ -999,7 +974,7 @@ const dbAnon  = getFirestore(sandbox.withAuth(null));
 
 ###### Inherited from
 
-[`Sandbox`](#sandbox-3).[`withAuth`](#withauth-6)
+[`Sandbox`](pyric-firestore-reference-api.md#sandbox).[`withAuth`](pyric-firestore-reference-api.md#withauth)
 
 ***
 
@@ -1038,7 +1013,7 @@ as a user, while an app or agent may use an admin lens.
 | <a id="id-1"></a> `id` | `readonly` | `string` |
 | <a id="method"></a> `method` | `readonly` | `string` |
 | <a id="path"></a> `path?` | `readonly` | `string` |
-| <a id="result"></a> `result` | `readonly` | `"allow"` \| `"deny"` \| `"unsupported"` \| `"error"` \| `"not-applicable"` |
+| <a id="result"></a> `result` | `readonly` | `"unsupported"` \| `"error"` \| `"allow"` \| `"deny"` \| `"not-applicable"` |
 | <a id="rules-1"></a> `rules` | `readonly` | [`RulesDisposition`](#rulesdisposition-2) |
 | <a id="service-1"></a> `service` | `readonly` | [`EventService`](#eventservice) |
 
@@ -1050,7 +1025,7 @@ as a user, while an app or agent may use an admin lens.
 
 Contract for a service that can contribute its state to the sandbox
 persistence layer. Services (auth, storage, database) register
-themselves via [Sandbox.registerPersistableService](#registerpersistableservice-4) so the
+themselves via [Sandbox.registerPersistableService](pyric-firestore-reference-api.md#registerpersistableservice) so the
 sandbox core stays service-agnostic — the sandbox doesn't know what
 auth or storage look like; it just calls `snapshot()` / `restore()`.
 
@@ -1064,15 +1039,37 @@ as Firestore writes.
 
 | Property | Type | Description |
 | :------ | :------ | :------ |
-| <a id="session"></a> `session?` | \{ `currentUid`: `string`; `mode`: `"LOCAL"` \| `"SESSION"` \| `"NONE"`; `restore`: `void`; `subscribe`: () => `void`; \} | Optional: session-level persistence hooks. When provided, the persistence controller uses these to save and restore the CURRENTLY SIGNED-IN user (not the user database — that's `snapshot`/`restore`). The controller calls `session.subscribe` so it hears every sign-in / sign-out, then writes the uid to the appropriate web-storage slot (determined by `session.mode()`). On init, the controller reads the stored uid and its storage-derived mode, then calls `session.restore(uid, mode)` to re-establish both before firing `onAuthStateChanged` as if the user just signed in. Only active when `SandboxPersistenceOptions.sessionStorage` is provided; omitting `sessionStorage` causes the controller to skip session persistence entirely (no fake durability). Auth is the only service that provides session hooks today. The field is on the generic interface so the controller stays service-agnostic — if a second service ever needs session-style semantics it can add its own hooks without changing the controller. |
+| <a id="session"></a> `session?` | \{ `currentUid`: `string`; `mode`: `"NONE"` \| `"SESSION"` \| `"LOCAL"`; `restore`: `void`; `subscribe`: () => `void`; \} | Optional: session-level persistence hooks. When provided, the persistence controller uses these to save and restore the CURRENTLY SIGNED-IN user (not the user database — that's `snapshot`/`restore`). The controller calls `session.subscribe` so it hears every sign-in / sign-out, then writes the uid to the appropriate web-storage slot (determined by `session.mode()`). On init, the controller reads the stored uid and its storage-derived mode, then calls `session.restore(uid, mode)` to re-establish both before firing `onAuthStateChanged` as if the user just signed in. Only active when `SandboxPersistenceOptions.sessionStorage` is provided; omitting `sessionStorage` causes the controller to skip session persistence entirely (no fake durability). Auth is the only service that provides session hooks today. The field is on the generic interface so the controller stays service-agnostic — if a second service ever needs session-style semantics it can add its own hooks without changing the controller. |
 | `session.currentUid` | `string` | - |
-| `session.mode` | `"LOCAL"` \| `"SESSION"` \| `"NONE"` | - |
+| `session.mode` | `"NONE"` \| `"SESSION"` \| `"LOCAL"` | - |
 | `session.restore` | `void` | - |
 | `session.subscribe` | () => `void` | - |
 | <a id="subscribe"></a> `subscribe?` | (`onChange`: () => `void`) => () => `void` | Optional: subscribe to changes in this service's state. When provided, the persistence controller hooks it up and schedules a debounced flush on each change — ensuring auth-user edits reach the backend promptly, not only on the next Firestore write. Must return an unsubscribe function. The controller unsubscribes on `dispose()`. |
 
 #### Methods
 
+<a id="reset-2"></a>
+
+##### reset()?
+
+```ts
+optional reset(): void | Promise<void>;
+```
+
+Optional: clear this service's state to empty. Called by
+[Sandbox.resetAll](pyric-firestore-reference-api.md#resetall) after the Firestore environment swap, so a
+single sandbox-owned call wipes EVERY registered service (auth users,
+RTDB tree, storage objects) — a consumer (Pyric Studio's reset) can't
+forget a service it never knew about. May be async (storage clears an
+IndexedDB store); `resetAll` awaits it. A service that omits `reset`
+is skipped — its state deliberately survives `resetAll` (e.g. the
+per-app auth-session hooks, whose signed-in identity the sandbox core
+already clears in `reset()`).
+
+###### Returns
+
+`void` \| `Promise`\<`void`\>
+
 <a id="restore"></a>
 
 ##### restore()
@@ -1316,7 +1313,7 @@ Force a flush of the current sandbox state to the backend.
 
 ### RemoteSandbox
 
-A branded remote sandbox handle. Structurally a [Sandbox](#sandbox-3) — it can
+A branded remote sandbox handle. Structurally a [Sandbox](pyric-firestore-reference-api.md#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()`,
@@ -1325,7 +1322,11 @@ dispatch on [isRemoteSandbox](#isremotesandbox) and use [channel](#channel) inst
 
 #### Extends
 
-- [`Sandbox`](#sandbox-3)
+- [`Sandbox`](pyric-firestore-reference-api.md#sandbox)
+
+#### Extended by
+
+- [`RemoteSandbox`](pyric-cli-remote-reference-api.md#remotesandbox)
 
 #### Properties
 
@@ -1334,7 +1335,7 @@ dispatch on [isRemoteSandbox](#isremotesandbox) and use [channel](#channel) inst
 | <a id="remote_sandbox"></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="channel"></a> `channel` | `readonly` | [`RemoteSandboxChannel`](#remotesandboxchannel-1) | The raw worker op/sub relay 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](#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. |
+| <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="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"). |
@@ -1361,7 +1362,7 @@ No-op when persistence is not enabled.
 
 ###### Inherited from
 
-[`Sandbox`](#sandbox-3).[`clearPersistence`](#clearpersistence-4)
+[`Sandbox`](pyric-firestore-reference-api.md#sandbox).[`clearPersistence`](pyric-firestore-reference-api.md#clearpersistence)
 
 <a id="dispose-4"></a>
 
@@ -1383,7 +1384,7 @@ outgoing instance defensively. Idempotent. Does not touch data.
 
 ###### Inherited from
 
-[`Sandbox`](#sandbox-3).[`dispose`](#dispose-6)
+[`Sandbox`](pyric-firestore-reference-api.md#sandbox).[`dispose`](pyric-firestore-reference-api.md#dispose)
 
 <a id="enablepersistence-2"></a>
 
@@ -1427,7 +1428,7 @@ tuning.
 
 ###### Inherited from
 
-[`Sandbox`](#sandbox-3).[`enablePersistence`](#enablepersistence-4)
+[`Sandbox`](pyric-firestore-reference-api.md#sandbox).[`enablePersistence`](pyric-firestore-reference-api.md#enablepersistence)
 
 <a id="enabletabsync-2"></a>
 
@@ -1487,7 +1488,7 @@ disableSync();
 
 ###### Inherited from
 
-[`Sandbox`](#sandbox-3).[`enableTabSync`](#enabletabsync-4)
+[`Sandbox`](pyric-firestore-reference-api.md#sandbox).[`enableTabSync`](pyric-firestore-reference-api.md#enabletabsync)
 
 <a id="flush-4"></a>
 
@@ -1510,7 +1511,7 @@ Throws if persistence is not enabled.
 
 ###### Inherited from
 
-[`Sandbox`](#sandbox-3).[`flush`](#flush-6)
+[`Sandbox`](pyric-firestore-reference-api.md#sandbox).[`flush`](pyric-firestore-reference-api.md#flush)
 
 <a id="history-2"></a>
 
@@ -1527,7 +1528,7 @@ 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](#onevent-4) (live stream from the moment of subscribe),
+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.
@@ -1542,7 +1543,7 @@ snapshot *before* reset retain the boundary in their copy.
 
 ###### Inherited from
 
-[`Sandbox`](#sandbox-3).[`history`](#history-4)
+[`Sandbox`](pyric-firestore-reference-api.md#sandbox).[`history`](pyric-firestore-reference-api.md#history)
 
 <a id="loadsnapshot-2"></a>
 
@@ -1552,17 +1553,17 @@ snapshot *before* reset retain the boundary in their copy.
 loadSnapshot(data: SandboxSnapshot): void;
 ```
 
-CLOBBER-restore the sandbox's entire state from a prior [snapshot](#snapshot-6):
+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](#snapshot-6). It is what makes "transfer (clobber) one instance's data
+[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](#snapshot-6) always includes every registered
+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).
 
@@ -1570,7 +1571,7 @@ a service this one lacks).
 
 | Parameter | Type |
 | :------ | :------ |
-| `data` | [`SandboxSnapshot`](#sandboxsnapshot-2) |
+| `data` | [`SandboxSnapshot`](#sandboxsnapshot) |
 
 ###### Returns
 
@@ -1578,7 +1579,7 @@ a service this one lacks).
 
 ###### Inherited from
 
-[`Sandbox`](#sandbox-3).[`loadSnapshot`](#loadsnapshot-4)
+[`Sandbox`](pyric-firestore-reference-api.md#sandbox).[`loadSnapshot`](pyric-firestore-reference-api.md#loadsnapshot)
 
 <a id="oncurrentuserchanged-2"></a>
 
@@ -1621,7 +1622,7 @@ their errors.
 
 ###### Inherited from
 
-[`Sandbox`](#sandbox-3).[`onCurrentUserChanged`](#oncurrentuserchanged-4)
+[`Sandbox`](pyric-firestore-reference-api.md#sandbox).[`onCurrentUserChanged`](pyric-firestore-reference-api.md#oncurrentuserchanged)
 
 <a id="onevent-2"></a>
 
@@ -1671,7 +1672,7 @@ sandbox doesn't await them and doesn't propagate their errors.
 
 ###### Inherited from
 
-[`Sandbox`](#sandbox-3).[`onEvent`](#onevent-4)
+[`Sandbox`](pyric-firestore-reference-api.md#sandbox).[`onEvent`](pyric-firestore-reference-api.md#onevent)
 
 <a id="registerpersistableservice-2"></a>
 
@@ -1720,9 +1721,9 @@ not need to call this directly.
 
 ###### Inherited from
 
-[`Sandbox`](#sandbox-3).[`registerPersistableService`](#registerpersistableservice-4)
+[`Sandbox`](pyric-firestore-reference-api.md#sandbox).[`registerPersistableService`](pyric-firestore-reference-api.md#registerpersistableservice)
 
-<a id="reset-2"></a>
+<a id="reset-4"></a>
 
 ##### reset()
 
@@ -1738,7 +1739,7 @@ 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](#sandboxcontext)s continue to work — their sandbox
+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
@@ -1747,7 +1748,41 @@ reference is stable; subsequent operations resolve to the new env.
 
 ###### Inherited from
 
-[`Sandbox`](#sandbox-3).[`reset`](#reset-4)
+[`Sandbox`](pyric-firestore-reference-api.md#sandbox).[`reset`](pyric-firestore-reference-api.md#reset)
+
+<a id="resetall-2"></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](#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
+
+[`Sandbox`](pyric-firestore-reference-api.md#sandbox).[`resetAll`](pyric-firestore-reference-api.md#resetall)
 
 <a id="runwithprovenance-2"></a>
 
@@ -1800,7 +1835,7 @@ spell `sandbox.runWithProvenance?.(prov, fn) ?? fn()`.
 
 ###### Inherited from
 
-[`Sandbox`](#sandbox-3).[`runWithProvenance`](#runwithprovenance-4)
+[`Sandbox`](pyric-firestore-reference-api.md#sandbox).[`runWithProvenance`](pyric-firestore-reference-api.md#runwithprovenance)
 
 <a id="snapshot-4"></a>
 
@@ -1816,11 +1851,11 @@ paths to data. Future services will add their own keys.
 
 ###### Returns
 
-[`SandboxSnapshot`](#sandboxsnapshot-2)
+[`SandboxSnapshot`](#sandboxsnapshot)
 
 ###### Inherited from
 
-[`Sandbox`](#sandbox-3).[`snapshot`](#snapshot-6)
+[`Sandbox`](pyric-firestore-reference-api.md#sandbox).[`snapshot`](pyric-firestore-reference-api.md#snapshot)
 
 <a id="withauth-4"></a>
 
@@ -1853,7 +1888,7 @@ unambiguous.
 
 ###### Returns
 
-[`SandboxContext`](#sandboxcontext)
+[`SandboxContext`](pyric-firestore-reference-api.md#sandboxcontext)
 
 ###### Example
 
@@ -1865,7 +1900,7 @@ const dbAnon  = getFirestore(sandbox.withAuth(null));
 
 ###### Inherited from
 
-[`Sandbox`](#sandbox-3).[`withAuth`](#withauth-6)
+[`Sandbox`](pyric-firestore-reference-api.md#sandbox).[`withAuth`](pyric-firestore-reference-api.md#withauth)
 
 ***
 
@@ -2033,16 +2068,16 @@ traffic-monitor-decision.md for the field-by-field rationale.
 | `auth.uid` | `string` | - |
 | <a id="detail"></a> `detail?` | \{ `admin?`: `boolean`; \} & `Record`\<`string`, `unknown`\> | Free-form operation metadata. `admin: true` marks a rules-bypassing setup/admin operation so fixture tooling can exclude it from protected behavior while still preserving it as replay context. |
 | <a id="evalms"></a> `evalMs` | `number` | Wall-clock duration of the simulator.simulate(...) call, in ms. |
-| <a id="evaluatedrule"></a> `evaluatedRule?` | `EvaluatedRuleInfo` | The DECIDING rule's verdict + 1-indexed source line + full sub-expression trace, projected from the simulator's structured `RuleEvaluation` (additive: present on `result: 'allow' | 'deny'` Firestore events when the simulator produced a per-rule trace — the allowing rule on an allow, the denying rule on a deny). Studio's rules inspector reads this to mark the deciding line and render the evaluation step-through ("show the work"). Absent on an implicit deny (no rule evaluated), a simulator-error deny, and unsupported results. |
+| <a id="evaluatedrule"></a> `evaluatedRule?` | [`EvaluatedRuleInfo`](pyric-rules-reference-api.md#evaluatedruleinfo) | The DECIDING rule's verdict + 1-indexed source line + full sub-expression trace, projected from the simulator's structured `RuleEvaluation` (additive: present on `result: 'allow' | 'deny'` Firestore events when the simulator produced a per-rule trace — the allowing rule on an allow, the denying rule on a deny). Studio's rules inspector reads this to mark the deciding line and render the evaluation step-through ("show the work"). Absent on an implicit deny (no rule evaluated), a simulator-error deny, and unsupported results. |
 | <a id="groupid"></a> `groupId?` | `string` | Shared across ops in one batch or transaction. Opaque to consumers. |
-| <a id="groupkind"></a> `groupKind?` | `"transaction"` \| `"batch"` | Disambiguates `origin: 'transaction' | 'batch'` cases when consumers need to tell them apart without inspecting `origin` directly. |
+| <a id="groupkind-1"></a> `groupKind?` | `"transaction"` \| `"batch"` | Disambiguates `origin: 'transaction' | 'batch'` cases when consumers need to tell them apart without inspecting `origin` directly. |
 | <a id="id-2"></a> `id` | `string` | Unique within a sandbox process. Useful for React list keys. |
 | <a id="kind-1"></a> `kind` | `"request"` | Discriminator. |
 | <a id="matchedrule"></a> `matchedRule?` | \{ `operations`: `string`[]; `ruleIndex`: `number`; \} | Parsed from the simulator's "Rule #N → …" debug line. Absent when no rule matched (e.g. no allow rules at the path — implicit deny). |
 | `matchedRule.operations` | `string`[] | - |
 | `matchedRule.ruleIndex` | `number` | - |
-| <a id="method-1"></a> `method` | `"get"` \| `"list"` \| `"create"` \| `"update"` \| `"delete"` \| `"set"` | - |
-| <a id="origin"></a> `origin` | `"user"` \| `"listener"` \| `"transaction"` \| `"batch"` | - |
+| <a id="method-1"></a> `method` | `"delete"` \| `"get"` \| `"list"` \| `"create"` \| `"update"` \| `"set"` | - |
+| <a id="origin"></a> `origin` | `"user"` \| `"transaction"` \| `"listener"` \| `"batch"` | - |
 | <a id="path-1"></a> `path` | `string` | - |
 | <a id="reasons-2"></a> `reasons` | `string`[] | Simulator debug messages — the per-rule trace (`Rule #0 (read) → ALLOW`). Same shape as `DenialEvent.reasons` so consumer code can share rendering. |
 | <a id="request-2"></a> `request?` | \{ `resourceData?`: `Record`\<`string`, `unknown`\>; \} | Proposed write payload, for create/update/set. Absent on reads + delete. Pre-resolution: `FieldValue.*` sentinels are preserved as their marker shapes (`{ __type: 'serverTimestamp' }`, etc.) so the replay engine can re-resolve them. The rule engine evaluated against the resolved form internally; that resolved form lives on [WriteSandboxEvent.nextState](#nextstate-1), not here. |
@@ -2053,7 +2088,7 @@ traffic-monitor-decision.md for the field-by-field rationale.
 | <a id="resourcebefore"></a> `resourceBefore?` | \{ `data`: `Record`\<`string`, `unknown`\>; `exists`: `boolean`; \} | Existing document state before the write (or read target for get). |
 | `resourceBefore.data` | `Record`\<`string`, `unknown`\> | - |
 | `resourceBefore.exists` | `boolean` | - |
-| <a id="result-1"></a> `result` | `"allow"` \| `"deny"` \| `"unsupported"` | `'unsupported'` fires when the simulator hit an unmodelled feature and the sandbox upgraded it (today: thrown as SimulatorUnsupportedError, surfaced here as a discrete result so the panel can show it distinctly from a real denial). |
+| <a id="result-1"></a> `result` | `"unsupported"` \| `"allow"` \| `"deny"` | `'unsupported'` fires when the simulator hit an unmodelled feature and the sandbox upgraded it (today: thrown as SimulatorUnsupportedError, surfaced here as a discrete result so the panel can show it distinctly from a real denial). |
 | <a id="rulesdisposition"></a> `rulesDisposition?` | [`RulesDisposition`](#rulesdisposition-2) | Canonical statement of whether Security Rules evaluated this request. Added by the sandbox event recorder when an older emitter omits it. |
 | <a id="triggeredby"></a> `triggeredBy?` | \{ `method`: `string`; `path`: `string`; \} | For listener re-evals: the originating user op that triggered this re-evaluation. Absent on the initial-snapshot fire. |
 | `triggeredBy.method` | `string` | - |
@@ -2061,719 +2096,163 @@ traffic-monitor-decision.md for the field-by-field rationale.
 
 ***
 
-<a id="sandbox-3"></a>
+<a id="sandboxcommitevent"></a>
 
-### Sandbox
+### SandboxCommitEvent
 
-A Firebase sandbox — an isolated environment with one auth identity.
+Canonical committed mutation event. Unlike `operation`, this fires only when
+state actually changed. Replay and branch tooling should eventually consume
+these service adapters instead of filtering Firestore-only `write` events.
 
-Created via `initializeSandbox(config)`. Use `fork({ auth })` to
-derive a new sandbox with a different identity that shares the
-underlying environment (rules, data, state). Fork is the only
-identity-switching mechanism — there are no per-op auth overrides
-and no in-place mutation.
+#### Properties
 
-#### Extended by
+| Property | Type |
+| :------ | :------ |
+| <a id="at-3"></a> `at` | `number` |
+| <a id="auth-6"></a> `auth` | \{ `token?`: `Record`\<`string`, `unknown`\>; `uid`: `string`; \} |
+| `auth.token?` | `Record`\<`string`, `unknown`\> |
+| `auth.uid` | `string` |
+| <a id="data"></a> `data?` | `unknown` |
+| <a id="detail-1"></a> `detail?` | `Record`\<`string`, `unknown`\> |
+| <a id="groupid-1"></a> `groupId?` | `string` |
+| <a id="groupkind-2"></a> `groupKind?` | `"transaction"` \| `"batch"` |
+| <a id="id-3"></a> `id` | `string` |
+| <a id="kind-2"></a> `kind` | `"commit"` |
+| <a id="method-2"></a> `method` | `string` |
+| <a id="nextstate"></a> `nextState?` | `unknown` |
+| <a id="path-2"></a> `path?` | `string` |
+| <a id="priorstate"></a> `priorState?` | `unknown` |
+| <a id="replay"></a> `replay?` | \{ `autoId?`: `string`; `requestTime?`: `number`; `sentinels?`: \{ `field`: `string`; `kind`: `string`; \}[]; \} |
+| `replay.autoId?` | `string` |
+| `replay.requestTime?` | `number` |
+| `replay.sentinels?` | \{ `field`: `string`; `kind`: `string`; \}[] |
+| <a id="service-2"></a> `service` | [`EventService`](#eventservice) |
 
-- [`LocalSandbox`](#localsandbox)
-- [`RemoteSandbox`](#remotesandbox)
+***
 
-#### Properties
+<a id="sandboxconfig"></a>
 
-| Property | Modifier | Type | Description |
-| :------ | :------ | :------ | :------ |
-| <a id="admin-2"></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="currentuser-2"></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](#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` | - |
+### SandboxConfig
 
-#### Methods
+Initialization config for a sandbox. All fields are optional; an
+empty config produces a sandbox with no rules and no seeded data.
 
-<a id="clearpersistence-4"></a>
+**No `auth` field.** Identity belongs to [SandboxContext](pyric-firestore-reference-api.md#sandboxcontext), not
+the sandbox. Service handles always require an explicit context.
 
-##### clearPersistence()
+***
 
-```ts
-clearPersistence(): Promise<void>;
-```
+<a id="sandboxlistenerevent"></a>
 
-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.
+### SandboxListenerEvent
 
-No-op when persistence is not enabled.
+Canonical listener lifecycle/delivery event. Firestore's existing snapshot
+delivery/lifecycle variants are preserved; this shape gives RTDB and future
+service listeners the same debuggable surface.
 
-###### Returns
+#### Properties
 
-`Promise`\<`void`\>
+| Property | Type |
+| :------ | :------ |
+| <a id="at-4"></a> `at` | `number` |
+| <a id="auth-7"></a> `auth` | \{ `token?`: `Record`\<`string`, `unknown`\>; `uid`: `string`; \} |
+| `auth.token?` | `Record`\<`string`, `unknown`\> |
+| `auth.uid` | `string` |
+| <a id="detail-2"></a> `detail?` | `Record`\<`string`, `unknown`\> |
+| <a id="error-1"></a> `error?` | \{ `code?`: `string`; `message`: `string`; `reasons?`: `string`[]; \} |
+| `error.code?` | `string` |
+| `error.message` | `string` |
+| `error.reasons?` | `string`[] |
+| <a id="id-4"></a> `id` | `string` |
+| <a id="kind-3"></a> `kind` | `"listener"` |
+| <a id="listenerid-2"></a> `listenerId` | `string` |
+| <a id="phase"></a> `phase` | `"attach"` \| `"detach"` \| `"delivery"` \| `"suppressed"` \| `"errored"` |
+| <a id="reason"></a> `reason?` | `string` |
+| <a id="result-2"></a> `result?` | `"unsupported"` \| `"error"` \| `"allow"` \| `"deny"` |
+| <a id="sample"></a> `sample?` | `unknown` |
+| <a id="service-3"></a> `service` | [`EventService`](#eventservice) |
+| <a id="size"></a> `size?` | `number` |
+| <a id="target-1"></a> `target` | \{ `kind`: `string`; `path?`: `string`; `query?`: `unknown`; \} |
+| `target.kind` | `string` |
+| `target.path?` | `string` |
+| `target.query?` | `unknown` |
+| <a id="triggeredby-1"></a> `triggeredBy?` | \{ `method`: `string`; `path?`: `string`; \} |
+| `triggeredBy.method` | `string` |
+| `triggeredBy.path?` | `string` |
 
-<a id="dispose-6"></a>
+***
 
-##### dispose()
+<a id="sandboxoperationevent"></a>
 
-```ts
-dispose(): void;
-```
+### SandboxOperationEvent
 
-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.
+Canonical service operation event. This is the service-neutral successor to
+Firestore's `request` traffic shape: every user-visible operation can be
+represented here, whether it is backed by security rules (Firestore/RTDB/
+Storage) or by a service control plane (Auth).
 
-###### Returns
+Existing Firestore `request` events remain for compatibility. New cross-
+service consumers should prefer `operation` because it carries an explicit
+`service` discriminator and does not require RTDB/Storage/Auth to pretend
+their state is a Firestore document.
 
-`void`
+#### Properties
 
-<a id="enablepersistence-4"></a>
+| Property | Type | Description |
+| :------ | :------ | :------ |
+| <a id="at-5"></a> `at` | `number` | - |
+| <a id="auth-8"></a> `auth` | \{ `token?`: `Record`\<`string`, `unknown`\>; `uid`: `string`; \} | - |
+| `auth.token?` | `Record`\<`string`, `unknown`\> | - |
+| `auth.uid` | `string` | - |
+| <a id="detail-3"></a> `detail?` | `Record`\<`string`, `unknown`\> | - |
+| <a id="durationms"></a> `durationMs?` | `number` | - |
+| <a id="groupid-2"></a> `groupId?` | `string` | - |
+| <a id="groupkind-3"></a> `groupKind?` | `"transaction"` \| `"batch"` | - |
+| <a id="id-5"></a> `id` | `string` | - |
+| <a id="kind-4"></a> `kind` | `"operation"` | - |
+| <a id="method-3"></a> `method` | `string` | - |
+| <a id="origin-1"></a> `origin` | `"admin"` \| `"user"` \| `"system"` \| `"transaction"` \| `"listener"` \| `"batch"` | - |
+| <a id="path-3"></a> `path?` | `string` | - |
+| <a id="reasons-3"></a> `reasons?` | `string`[] | - |
+| <a id="request-3"></a> `request?` | \{ `data?`: `unknown`; `query?`: `unknown`; `resourceData?`: `unknown`; \} | - |
+| `request.data?` | `unknown` | - |
+| `request.query?` | `unknown` | - |
+| `request.resourceData?` | `unknown` | - |
+| <a id="resourceafter-1"></a> `resourceAfter?` | \{ `data`: `unknown`; `exists`: `boolean`; \} | - |
+| `resourceAfter.data` | `unknown` | - |
+| `resourceAfter.exists` | `boolean` | - |
+| <a id="resourcebefore-1"></a> `resourceBefore?` | \{ `data`: `unknown`; `exists`: `boolean`; \} | - |
+| `resourceBefore.data` | `unknown` | - |
+| `resourceBefore.exists` | `boolean` | - |
+| <a id="result-3"></a> `result` | `"unsupported"` \| `"error"` \| `"allow"` \| `"deny"` \| `"not-applicable"` | - |
+| <a id="rules-2"></a> `rules?` | \{ `engine`: `"firestore"` \| `"rtdb"` \| `"storage"`; `errorCode?`: `string`; `matchedPath?`: `string`; `matchedRule?`: `string`; `operations?`: `string`[]; `pathVariableBindings?`: `Record`\<`string`, `string`\>; `reason?`: `string`; `ruleIndex?`: `number`; \} | - |
+| `rules.engine` | `"firestore"` \| `"rtdb"` \| `"storage"` | - |
+| `rules.errorCode?` | `string` | - |
+| `rules.matchedPath?` | `string` | - |
+| `rules.matchedRule?` | `string` | - |
+| `rules.operations?` | `string`[] | - |
+| `rules.pathVariableBindings?` | `Record`\<`string`, `string`\> | - |
+| `rules.reason?` | `string` | - |
+| `rules.ruleIndex?` | `number` | - |
+| <a id="rulesdisposition-1"></a> `rulesDisposition?` | [`RulesDisposition`](#rulesdisposition-2) | Canonical statement of whether Security Rules evaluated this operation. Service emitters may provide it directly; the recorder normalizes legacy operation shapes at the unified stream seam. |
+| <a id="service-4"></a> `service` | [`EventService`](#eventservice) | - |
+| <a id="triggeredby-2"></a> `triggeredBy?` | \{ `method`: `string`; `path?`: `string`; \} | - |
+| `triggeredBy.method` | `string` | - |
+| `triggeredBy.path?` | `string` | - |
 
-##### 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](#sandboxpersistenceoptions) for backend selection and
-tuning.
-
-###### Parameters
-
-| Parameter | Type |
-| :------ | :------ |
-| `options` | [`SandboxPersistenceOptions`](#sandboxpersistenceoptions) |
-
-###### Returns
-
-`Promise`\<`void`\>
-
-<a id="enabletabsync-4"></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`](#tabsyncoptions) |
-
-###### Returns
-
-```ts
-(): void;
-```
-
-###### Returns
-
-`void`
-
-###### See
-
-[TabSyncOptions](#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();
-```
-
-<a id="flush-6"></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`\>
-
-<a id="history-4"></a>
-
-##### history()
-
-```ts
-history(): SandboxEvent[];
-```
-
-Every [SandboxEvent](#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](#onevent-4) (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`](#sandboxevent)[]
-
-<a id="loadsnapshot-4"></a>
-
-##### loadSnapshot()
-
-```ts
-loadSnapshot(data: SandboxSnapshot): void;
-```
-
-CLOBBER-restore the sandbox's entire state from a prior [snapshot](#snapshot-6):
-`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](#snapshot-6). 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](#snapshot-6) 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`](#sandboxsnapshot-2) |
-
-###### Returns
-
-`void`
-
-<a id="oncurrentuserchanged-4"></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`
-
-<a id="onevent-4"></a>
-
-##### onEvent()
-
-```ts
-onEvent(cb: (event: SandboxEvent) => void): () => void;
-```
-
-Subscribe to every event the sandbox emits — see [SandboxEvent](#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`](#sandboxevent)) => `void` |
-
-###### Returns
-
-```ts
-(): void;
-```
-
-###### Returns
-
-`void`
-
-<a id="registerpersistableservice-4"></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`](#persistableservice) |
-
-###### Returns
-
-```ts
-(): void;
-```
-
-###### Returns
-
-`void`
-
-<a id="reset-4"></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](#sandboxcontext)s continue to work — their sandbox
-reference is stable; subsequent operations resolve to the new env.
-
-###### Returns
-
-`void`
-
-<a id="runwithprovenance-4"></a>
-
-##### runWithProvenance()?
-
-```ts
-optional runWithProvenance<T>(provenance: EventProvenance, fn: () => T): T;
-```
-
-Run `fn` with ambient [EventProvenance](#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`](#eventprovenance) |
-| `fn` | () => `T` |
-
-###### Returns
-
-`T`
-
-<a id="snapshot-6"></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`](#sandboxsnapshot-2)
-
-<a id="withauth-6"></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`](#sandboxcontext)
-
-###### Example
-
-```ts
-const sandbox = initializeSandbox();
-const dbAlice = getFirestore(sandbox.withAuth({ uid: 'alice' }));
-const dbAnon  = getFirestore(sandbox.withAuth(null));
-```
-
-***
-
-<a id="sandboxcommitevent"></a>
-
-### SandboxCommitEvent
-
-Canonical committed mutation event. Unlike `operation`, this fires only when
-state actually changed. Replay and branch tooling should eventually consume
-these service adapters instead of filtering Firestore-only `write` events.
-
-#### Properties
-
-| Property | Type |
-| :------ | :------ |
-| <a id="at-3"></a> `at` | `number` |
-| <a id="auth-6"></a> `auth` | \{ `token?`: `Record`\<`string`, `unknown`\>; `uid`: `string`; \} |
-| `auth.token?` | `Record`\<`string`, `unknown`\> |
-| `auth.uid` | `string` |
-| <a id="data"></a> `data?` | `unknown` |
-| <a id="detail-1"></a> `detail?` | `Record`\<`string`, `unknown`\> |
-| <a id="groupid-1"></a> `groupId?` | `string` |
-| <a id="groupkind-1"></a> `groupKind?` | `"transaction"` \| `"batch"` |
-| <a id="id-3"></a> `id` | `string` |
-| <a id="kind-2"></a> `kind` | `"commit"` |
-| <a id="method-2"></a> `method` | `string` |
-| <a id="nextstate"></a> `nextState?` | `unknown` |
-| <a id="path-2"></a> `path?` | `string` |
-| <a id="priorstate"></a> `priorState?` | `unknown` |
-| <a id="replay"></a> `replay?` | \{ `autoId?`: `string`; `requestTime?`: `number`; `sentinels?`: \{ `field`: `string`; `kind`: `string`; \}[]; \} |
-| `replay.autoId?` | `string` |
-| `replay.requestTime?` | `number` |
-| `replay.sentinels?` | \{ `field`: `string`; `kind`: `string`; \}[] |
-| <a id="service-2"></a> `service` | [`EventService`](#eventservice) |
-
-***
-
-<a id="sandboxconfig"></a>
-
-### SandboxConfig
-
-Initialization config for a sandbox. All fields are optional; an
-empty config produces a sandbox with no rules and no seeded data.
-
-**No `auth` field.** Identity belongs to [SandboxContext](#sandboxcontext), not
-the sandbox. Service handles always require an explicit context.
-
-***
-
-<a id="sandboxcontext"></a>
-
-### SandboxContext
-
-Identity-bearing handle on a [Sandbox](#sandbox-3). A
-`(sandbox, auth, operationContext)`
-tuple — cheap to create, immutable, freely shareable. Service
-factories require a `SandboxContext`; bare `Sandbox` is a type
-error so every call site states identity explicitly.
-
-Constructed via `Sandbox.withAuth(auth)` or chained via
-`SandboxContext.withAuth(auth)`. The concrete class is exported
-from `pyric/sandbox` for `instanceof` routing in service
-factories; consumers don't construct it directly.
-
-#### Properties
-
-| Property | Modifier | Type | Description |
-| :------ | :------ | :------ | :------ |
-| <a id="auth-7"></a> `auth` | `readonly` | \{ `token?`: `Record`\<`string`, `unknown`\>; `uid`: `string`; \} | The identity rules evaluate under for operations through this context. |
-| `auth.token?` | `public` | `Record`\<`string`, `unknown`\> | - |
-| `auth.uid` | `public` | `string` | - |
-| <a id="operationcontext-3"></a> `operationContext` | `readonly` | [`OperationContext`](#operationcontext-2) | Immutable provenance bound to every operation issued through this handle. |
-| <a id="sandbox-4"></a> `sandbox` | `readonly` | [`Sandbox`](#sandbox-3) | The data foundation this context operates against. |
-
-#### Methods
-
-<a id="withauth-8"></a>
-
-##### withAuth()
-
-```ts
-withAuth(auth: {
-  token?: Record<string, unknown>;
-  uid: string;
-}): SandboxContext;
-```
-
-Derive a sibling context on the same sandbox with different auth.
-Replaces auth and its lens while preserving the operation source and
-optional plan identity.
-
-###### Parameters
-
-| Parameter | Type |
-| :------ | :------ |
-| `auth` | \{ `token?`: `Record`\<`string`, `unknown`\>; `uid`: `string`; \} |
-| `auth.token?` | `Record`\<`string`, `unknown`\> |
-| `auth.uid` | `string` |
-
-###### Returns
-
-[`SandboxContext`](#sandboxcontext)
-
-***
-
-<a id="sandboxlistenerevent"></a>
-
-### SandboxListenerEvent
-
-Canonical listener lifecycle/delivery event. Firestore's existing snapshot
-delivery/lifecycle variants are preserved; this shape gives RTDB and future
-service listeners the same debuggable surface.
-
-#### Properties
-
-| Property | Type |
-| :------ | :------ |
-| <a id="at-4"></a> `at` | `number` |
-| <a id="auth-8"></a> `auth` | \{ `token?`: `Record`\<`string`, `unknown`\>; `uid`: `string`; \} |
-| `auth.token?` | `Record`\<`string`, `unknown`\> |
-| `auth.uid` | `string` |
-| <a id="detail-2"></a> `detail?` | `Record`\<`string`, `unknown`\> |
-| <a id="error-1"></a> `error?` | \{ `code?`: `string`; `message`: `string`; `reasons?`: `string`[]; \} |
-| `error.code?` | `string` |
-| `error.message` | `string` |
-| `error.reasons?` | `string`[] |
-| <a id="id-4"></a> `id` | `string` |
-| <a id="kind-3"></a> `kind` | `"listener"` |
-| <a id="listenerid-1"></a> `listenerId` | `string` |
-| <a id="phase"></a> `phase` | `"attach"` \| `"detach"` \| `"delivery"` \| `"suppressed"` \| `"errored"` |
-| <a id="reason"></a> `reason?` | `string` |
-| <a id="result-2"></a> `result?` | `"allow"` \| `"deny"` \| `"unsupported"` \| `"error"` |
-| <a id="sample"></a> `sample?` | `unknown` |
-| <a id="service-3"></a> `service` | [`EventService`](#eventservice) |
-| <a id="size"></a> `size?` | `number` |
-| <a id="target-1"></a> `target` | \{ `kind`: `string`; `path?`: `string`; `query?`: `unknown`; \} |
-| `target.kind` | `string` |
-| `target.path?` | `string` |
-| `target.query?` | `unknown` |
-| <a id="triggeredby-1"></a> `triggeredBy?` | \{ `method`: `string`; `path?`: `string`; \} |
-| `triggeredBy.method` | `string` |
-| `triggeredBy.path?` | `string` |
-
-***
-
-<a id="sandboxoperationevent"></a>
-
-### SandboxOperationEvent
-
-Canonical service operation event. This is the service-neutral successor to
-Firestore's `request` traffic shape: every user-visible operation can be
-represented here, whether it is backed by security rules (Firestore/RTDB/
-Storage) or by a service control plane (Auth).
-
-Existing Firestore `request` events remain for compatibility. New cross-
-service consumers should prefer `operation` because it carries an explicit
-`service` discriminator and does not require RTDB/Storage/Auth to pretend
-their state is a Firestore document.
-
-#### Properties
-
-| Property | Type | Description |
-| :------ | :------ | :------ |
-| <a id="at-5"></a> `at` | `number` | - |
-| <a id="auth-9"></a> `auth` | \{ `token?`: `Record`\<`string`, `unknown`\>; `uid`: `string`; \} | - |
-| `auth.token?` | `Record`\<`string`, `unknown`\> | - |
-| `auth.uid` | `string` | - |
-| <a id="detail-3"></a> `detail?` | `Record`\<`string`, `unknown`\> | - |
-| <a id="durationms"></a> `durationMs?` | `number` | - |
-| <a id="groupid-2"></a> `groupId?` | `string` | - |
-| <a id="groupkind-2"></a> `groupKind?` | `"transaction"` \| `"batch"` | - |
-| <a id="id-5"></a> `id` | `string` | - |
-| <a id="kind-4"></a> `kind` | `"operation"` | - |
-| <a id="method-3"></a> `method` | `string` | - |
-| <a id="origin-1"></a> `origin` | `"admin"` \| `"user"` \| `"listener"` \| `"transaction"` \| `"batch"` \| `"system"` | - |
-| <a id="path-3"></a> `path?` | `string` | - |
-| <a id="reasons-3"></a> `reasons?` | `string`[] | - |
-| <a id="request-3"></a> `request?` | \{ `data?`: `unknown`; `query?`: `unknown`; `resourceData?`: `unknown`; \} | - |
-| `request.data?` | `unknown` | - |
-| `request.query?` | `unknown` | - |
-| `request.resourceData?` | `unknown` | - |
-| <a id="resourceafter-1"></a> `resourceAfter?` | \{ `data`: `unknown`; `exists`: `boolean`; \} | - |
-| `resourceAfter.data` | `unknown` | - |
-| `resourceAfter.exists` | `boolean` | - |
-| <a id="resourcebefore-1"></a> `resourceBefore?` | \{ `data`: `unknown`; `exists`: `boolean`; \} | - |
-| `resourceBefore.data` | `unknown` | - |
-| `resourceBefore.exists` | `boolean` | - |
-| <a id="result-3"></a> `result` | `"allow"` \| `"deny"` \| `"unsupported"` \| `"error"` \| `"not-applicable"` | - |
-| <a id="rules-2"></a> `rules?` | \{ `engine`: `"firestore"` \| `"storage"` \| `"rtdb"`; `errorCode?`: `string`; `matchedPath?`: `string`; `matchedRule?`: `string`; `operations?`: `string`[]; `pathVariableBindings?`: `Record`\<`string`, `string`\>; `reason?`: `string`; `ruleIndex?`: `number`; \} | - |
-| `rules.engine` | `"firestore"` \| `"storage"` \| `"rtdb"` | - |
-| `rules.errorCode?` | `string` | - |
-| `rules.matchedPath?` | `string` | - |
-| `rules.matchedRule?` | `string` | - |
-| `rules.operations?` | `string`[] | - |
-| `rules.pathVariableBindings?` | `Record`\<`string`, `string`\> | - |
-| `rules.reason?` | `string` | - |
-| `rules.ruleIndex?` | `number` | - |
-| <a id="rulesdisposition-1"></a> `rulesDisposition?` | [`RulesDisposition`](#rulesdisposition-2) | Canonical statement of whether Security Rules evaluated this operation. Service emitters may provide it directly; the recorder normalizes legacy operation shapes at the unified stream seam. |
-| <a id="service-4"></a> `service` | [`EventService`](#eventservice) | - |
-| <a id="triggeredby-2"></a> `triggeredBy?` | \{ `method`: `string`; `path?`: `string`; \} | - |
-| `triggeredBy.method` | `string` | - |
-| `triggeredBy.path?` | `string` | - |
-
-***
-
-<a id="sandboxpersistenceoptions"></a>
+<a id="sandboxpersistenceoptions"></a>
 
 ### SandboxPersistenceOptions
 
-Controller options. See [Sandbox.enablePersistence](#enablepersistence-4).
+Controller options. See [Sandbox.enablePersistence](pyric-firestore-reference-api.md#enablepersistence).
 
 #### Properties
 
 | Property | Type | Description |
 | :------ | :------ | :------ |
-| <a id="backend"></a> `backend?` | `"indexedDB"` \| `"memory"` | 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`. |
+| <a id="backend"></a> `backend?` | `"memory"` \| `"indexedDB"` | 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`. |
 | <a id="flushintervalms"></a> `flushIntervalMs?` | `number` | 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. |
 | <a id="injectedbackend"></a> `injectedBackend?` | [`PersistenceBackend`](#persistencebackend) | Override the backend with an injected implementation. Used by tests and hosts that have their own storage adapter. When set, `backend` is ignored. |
 | <a id="key"></a> `key` | `string` | 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. |
@@ -2794,7 +2273,7 @@ Canonical non-rules operational failure.
 | Property | Type |
 | :------ | :------ |
 | <a id="at-6"></a> `at` | `number` |
-| <a id="auth-10"></a> `auth` | \{ `token?`: `Record`\<`string`, `unknown`\>; `uid`: `string`; \} |
+| <a id="auth-9"></a> `auth` | \{ `token?`: `Record`\<`string`, `unknown`\>; `uid`: `string`; \} |
 | `auth.token?` | `Record`\<`string`, `unknown`\> |
 | `auth.uid` | `string` |
 | <a id="detail-4"></a> `detail?` | `Record`\<`string`, `unknown`\> |
@@ -2809,7 +2288,7 @@ Canonical non-rules operational failure.
 
 ***
 
-<a id="sandboxsnapshot-2"></a>
+<a id="sandboxsnapshot"></a>
 
 ### SandboxSnapshot
 
@@ -2865,7 +2344,7 @@ diff `before`→`after` when both are present.
 | :------ | :------ | :------ |
 | <a id="after"></a> `after?` | `unknown` | Best-effort serializable snapshot of the state AFTER the mutation. Absent on deletes / sign-outs (nothing remains). |
 | <a id="at-7"></a> `at` | `number` | - |
-| <a id="auth-11"></a> `auth` | \{ `token?`: `Record`\<`string`, `unknown`\>; `uid`: `string`; \} | Identity in effect when the op ran (the service's `request.auth` equivalent). `null` for admin/anonymous-driven mutations (e.g. `sandbox.createUser`, an unauthenticated RTDB write). |
+| <a id="auth-10"></a> `auth` | \{ `token?`: `Record`\<`string`, `unknown`\>; `uid`: `string`; \} | Identity in effect when the op ran (the service's `request.auth` equivalent). `null` for admin/anonymous-driven mutations (e.g. `sandbox.createUser`, an unauthenticated RTDB write). |
 | `auth.token?` | `Record`\<`string`, `unknown`\> | - |
 | `auth.uid` | `string` | - |
 | <a id="before"></a> `before?` | `unknown` | Best-effort serializable snapshot of the state BEFORE the mutation. Absent when there was no prior state (a create) or it isn't cheap to capture. |
@@ -2874,7 +2353,7 @@ diff `before`→`after` when both are present.
 | <a id="kind-6"></a> `kind` | `"service_mutation"` | - |
 | <a id="op-2"></a> `op` | `string` | Service-scoped operation name. Stable, lowercase, snake/kebab-free: - auth: `user_create` | `user_update` | `user_delete` | `users_clear` | `sign_in` | `sign_out` - storage: `object_put` | `object_delete` | `metadata_update` - rtdb: `set` | `update` | `remove` | `transaction` - ai: `generate_content` | `stream_generate_content` | `count_tokens` | `request_rejected` New ops can be added without a breaking change (consumers switch with a default branch). |
 | <a id="path-5"></a> `path?` | `string` | The thing mutated, in the service's own addressing scheme: - auth: the user `uid` (or `'*'` for a clear-all). Absent for a sign-out with no prior user. - storage: the object `fullPath` (e.g. `avatars/alice.png`). - rtdb: the database path (e.g. `/rooms/r1/messages`), or for a multi-path `update` the ref path the call targeted. |
-| <a id="service-6"></a> `service` | `"auth"` \| `"storage"` \| `"rtdb"` \| `"messaging"` \| `"ai"` | Which service performed the mutation. Always one of the non-Firestore services — Firestore rides its own `request`/`write` path. (The provenance `service` field on the stamped event mirrors this; it is set redundantly here so a consumer matching purely on `kind` still gets the discriminator without reaching into provenance.) |
+| <a id="service-6"></a> `service` | `"rtdb"` \| `"auth"` \| `"storage"` \| `"messaging"` \| `"ai"` | Which service performed the mutation. Always one of the non-Firestore services — Firestore rides its own `request`/`write` path. (The provenance `service` field on the stamped event mirrors this; it is set redundantly here so a consumer matching purely on `kind` still gets the discriminator without reaching into provenance.) |
 
 ***
 
@@ -2920,12 +2399,12 @@ scenario produces large snapshots.
 | :------ | :------ | :------ |
 | <a id="addedcount"></a> `addedCount` | `number` | - |
 | <a id="at-9"></a> `at` | `number` | - |
-| <a id="auth-12"></a> `auth` | \{ `token?`: `Record`\<`string`, `unknown`\>; `uid`: `string`; \} | - |
+| <a id="auth-11"></a> `auth` | \{ `token?`: `Record`\<`string`, `unknown`\>; `uid`: `string`; \} | - |
 | `auth.token?` | `Record`\<`string`, `unknown`\> | - |
 | `auth.uid` | `string` | - |
 | <a id="id-9"></a> `id` | `string` | - |
 | <a id="kind-8"></a> `kind` | `"snapshot_delivery"` | - |
-| <a id="listenerid-2"></a> `listenerId` | `string` | Opaque listener id assigned at attach time. |
+| <a id="listenerid-3"></a> `listenerId` | `string` | Opaque listener id assigned at attach time. |
 | <a id="modifiedcount"></a> `modifiedCount` | `number` | - |
 | <a id="removedcount"></a> `removedCount` | `number` | - |
 | <a id="sample-1"></a> `sample?` | \{ `docs`: \{ `data`: `Record`\<`string`, `unknown`\>; `path`: `string`; \}[]; \} | Doc payloads, in the order the user callback saw them. |
@@ -2962,20 +2441,20 @@ scenario surfaces them.
 
 | Property | Type |
 | :------ | :------ |
-| <a id="auth-13"></a> `auth?` | \{ `token?`: `Record`\<`string`, `unknown`\>; `uid`: `string`; \} |
+| <a id="auth-12"></a> `auth?` | \{ `token?`: `Record`\<`string`, `unknown`\>; `uid`: `string`; \} |
 | `auth.token?` | `Record`\<`string`, `unknown`\> |
 | `auth.uid` | `string` |
-| <a id="code-2"></a> `code` | `"permission-denied"` |
+| <a id="code-1"></a> `code` | `"permission-denied"` |
 | <a id="message-1"></a> `message` | `string` |
 | <a id="reasons-4"></a> `reasons?` | `string`[] |
-| <a id="request-4"></a> `request?` | \{ `method`: `"get"` \| `"list"` \| `"create"` \| `"update"` \| `"delete"`; `path`: `string`; `resourceData?`: `Record`\<`string`, `unknown`\>; \} |
-| `request.method` | `"get"` \| `"list"` \| `"create"` \| `"update"` \| `"delete"` |
+| <a id="request-4"></a> `request?` | \{ `method`: `"delete"` \| `"get"` \| `"list"` \| `"create"` \| `"update"`; `path`: `string`; `resourceData?`: `Record`\<`string`, `unknown`\>; \} |
+| `request.method` | `"delete"` \| `"get"` \| `"list"` \| `"create"` \| `"update"` |
 | `request.path` | `string` |
 | `request.resourceData?` | `Record`\<`string`, `unknown`\> |
 | <a id="resource-2"></a> `resource?` | \{ `data`: `Record`\<`string`, `unknown`\>; `exists`: `boolean`; \} |
 | `resource.data` | `Record`\<`string`, `unknown`\> |
 | `resource.exists` | `boolean` |
-| <a id="target-3"></a> `target` | \| \{ `kind`: `"doc"`; `path`: `string`; \} \| \{ `collection`: `string`; `kind`: `"query"`; \} |
+| <a id="target-3"></a> `target` | \| \{ `kind`: `"doc"`; `path`: `string`; \} \| \{ `collection`: `string`; `kind`: `"query"`; `query?`: `unknown`; \} |
 
 ***
 
@@ -2996,12 +2475,12 @@ them.
 | Property | Type | Description |
 | :------ | :------ | :------ |
 | <a id="at-10"></a> `at` | `number` | - |
-| <a id="auth-14"></a> `auth` | \{ `token?`: `Record`\<`string`, `unknown`\>; `uid`: `string`; \} | - |
+| <a id="auth-13"></a> `auth` | \{ `token?`: `Record`\<`string`, `unknown`\>; `uid`: `string`; \} | - |
 | `auth.token?` | `Record`\<`string`, `unknown`\> | - |
 | `auth.uid` | `string` | - |
 | <a id="id-10"></a> `id` | `string` | - |
 | <a id="kind-9"></a> `kind` | `"snapshot_suppressed"` | - |
-| <a id="listenerid-3"></a> `listenerId` | `string` | - |
+| <a id="listenerid-4"></a> `listenerId` | `string` | - |
 | <a id="reason-1"></a> `reason` | `"no-op"` | Why this re-eval was suppressed. v1 only emits `'no-op'`. |
 | <a id="target-4"></a> `target` | \| \{ `kind`: `"doc"`; `path`: `string`; \} \| \{ `collection`: `string`; `kind`: `"query"`; \} | - |
 | <a id="triggeredby-4"></a> `triggeredBy?` | \{ `method`: `string`; `path`: `string`; \} | - |
@@ -3124,17 +2603,17 @@ sentinel/auto-id capture lands.
 | Property | Type | Description |
 | :------ | :------ | :------ |
 | <a id="at-11"></a> `at` | `number` | - |
-| <a id="auth-15"></a> `auth` | \{ `token?`: `Record`\<`string`, `unknown`\>; `uid`: `string`; \} | - |
+| <a id="auth-14"></a> `auth` | \{ `token?`: `Record`\<`string`, `unknown`\>; `uid`: `string`; \} | - |
 | `auth.token?` | `Record`\<`string`, `unknown`\> | - |
 | `auth.uid` | `string` | - |
 | <a id="autoid"></a> `autoId?` | `string` | Minted document ID when this write came from `collection.add()` / `LocalEnvironment.createWithAutoId`. The replay engine aliases the path's last segment to a fresh mint on replay (rather than preserving the original auto-ID). |
 | <a id="data-1"></a> `data?` | `Record`\<`string`, `unknown`\> | Pre-resolution write payload — `FieldValue.*` sentinels preserved as marker shapes (`{ __type: 'serverTimestamp' }`, etc.) so the replay engine can re-resolve them. The rule engine evaluated against the resolved form internally; the resolved form lives on [nextState](#nextstate-1). Absent on `delete`. |
 | <a id="detail-6"></a> `detail?` | \{ `admin?`: `boolean`; \} & `Record`\<`string`, `unknown`\> | Free-form write metadata. `admin: true` marks a rules-bypassing setup/admin commit so replay can apply it as context without asking candidate rules to permit it. |
 | <a id="groupid-3"></a> `groupId?` | `string` | - |
-| <a id="groupkind-3"></a> `groupKind?` | `"transaction"` \| `"batch"` | - |
+| <a id="groupkind-4"></a> `groupKind?` | `"transaction"` \| `"batch"` | - |
 | <a id="id-11"></a> `id` | `string` | - |
 | <a id="kind-10"></a> `kind` | `"write"` | - |
-| <a id="method-5"></a> `method` | `"create"` \| `"update"` \| `"delete"` \| `"set"` | - |
+| <a id="method-5"></a> `method` | `"delete"` \| `"create"` \| `"update"` \| `"set"` | - |
 | <a id="nextstate-1"></a> `nextState` | `Record`\<`string`, `unknown`\> | State AFTER this write. `null` on `delete`. |
 | <a id="path-6"></a> `path` | `string` | - |
 | <a id="priorstate-1"></a> `priorState` | `Record`\<`string`, `unknown`\> | State BEFORE this write. `null` for a non-existent doc. |
@@ -3171,32 +2650,6 @@ The identity/rules lens an operation actually ran under.
 
 ***
 
-<a id="authstate"></a>
-
-### AuthState
-
-```ts
-type AuthState =
-  | {
-  token?: Record<string, unknown>;
-  uid: string;
-}
-  | null;
-```
-
-A signed-in identity for sandbox operations. `null` is anonymous.
-
-`token` is the Firebase Auth token claims map (custom claims plus
-standard ones). It surfaces the same way it does in production rules
-via `request.auth.token.*`. Omit it for plain UID-only auth.
-
-Renamed from `AuthContext` (pre-multi-context) so the data type
-doesn't visually collide with `SandboxContext` (the identity-bearing
-handle). They sit at different layers — payload vs. handle — and the
-names should reflect that.
-
-***
-
 <a id="difftarget"></a>
 
 ### DiffTarget
@@ -3257,6 +2710,7 @@ type Divergence =
 ```ts
 type EventActor =
   | {
+  journeyId?: string;
   kind: "app";
 }
   | {
@@ -3342,7 +2796,7 @@ the rules disposition.
 
 ***
 
-<a id="sandboxerrorcode-1"></a>
+<a id="sandboxerrorcode"></a>
 
 ### SandboxErrorCode
 
@@ -3390,7 +2844,7 @@ type SandboxEvent =
 ```
 
 Discriminated union of every event the sandbox emits to
-[Sandbox.onEvent](#onevent-4) subscribers.
+[Sandbox.onEvent](pyric-firestore-reference-api.md#onevent) subscribers.
 
 Issue #307 — replaces the prior three-channel surface
 (`onRequest` / `onDenial` / `onSnapshotError`). Filter on `kind`
@@ -3500,7 +2954,7 @@ We handle this in two parts:
 
 | Parameter | Type |
 | :------ | :------ |
-| `sandbox` | [`Sandbox`](#sandbox-3) |
+| `sandbox` | [`Sandbox`](pyric-firestore-reference-api.md#sandbox) |
 | `rawOptions` | [`SandboxPersistenceOptions`](#sandboxpersistenceoptions) |
 
 #### Returns
@@ -3715,7 +3169,7 @@ touch the source sandbox.
 
 | Parameter | Type | Description |
 | :------ | :------ | :------ |
-| `snapshot` | [`SandboxSnapshot`](#sandboxsnapshot-2) | Baseline state — typically `liveSandbox.snapshot()`. |
+| `snapshot` | [`SandboxSnapshot`](#sandboxsnapshot) | Baseline state — typically `liveSandbox.snapshot()`. |
 | `rules?` | `string` | Rules source for the branch. Pass the live rules to reproduce production behaviour, or an *edited* ruleset to test a rules change in isolation (Studio F4). |
 
 #### Returns
@@ -3735,7 +3189,7 @@ function initializeSandbox(_config?: SandboxConfig): LocalSandbox;
 Create a sandbox.
 
 Identity is **not** part of init — call `sandbox.withAuth(...)` to
-derive a [SandboxContext](#sandboxcontext) for service operations. Service-
+derive a [SandboxContext](pyric-firestore-reference-api.md#sandboxcontext) for service operations. Service-
 specific configuration (rules, seed data) happens through service-specific
 sandbox controls — for example, `setRules(sandbox, source)` from
 `pyric/sandbox/firestore`.
@@ -3800,7 +3254,7 @@ than into process-local state.
 
 | Parameter | Type |
 | :------ | :------ |
-| `sandbox` | [`Sandbox`](#sandbox-3) |
+| `sandbox` | [`Sandbox`](pyric-firestore-reference-api.md#sandbox) |
 
 #### Returns
 
@@ -3924,34 +3378,6 @@ cached, so a restore (list + per-record get) costs one read, not one per record.
 
 ***
 
-<a id="rehydratedocvalue"></a>
-
-### rehydrateDocValue()
-
-```ts
-function rehydrateDocValue(value: unknown): unknown;
-```
-
-Walk a parsed JSON tree and re-wrap any marker shape back into its real
-wrapper-class instance. Visits arrays and plain objects recursively. Plain
-values (and plain objects without a recognized discriminator) pass through.
-
-This is the canonical rehydrate used by BOTH the sandbox persistence
-serializer and the SharedWorker wire protocol, so the IDB format and the
-MessagePort wire format are guaranteed identical.
-
-#### Parameters
-
-| Parameter | Type |
-| :------ | :------ |
-| `value` | `unknown` |
-
-#### Returns
-
-`unknown`
-
-***
-
 <a id="replay-1"></a>
 
 ### replay()
@@ -4058,3 +3484,43 @@ Project either traffic event family into the canonical record.
 #### Returns
 
 [`OperationRecord`](#operationrecord)
+
+## References
+
+<a id="authstate"></a>
+
+### AuthState
+
+Re-exports [AuthState](pyric-firestore-reference-api.md#authstate)
+
+***
+
+<a id="rehydratedocvalue"></a>
+
+### rehydrateDocValue
+
+Re-exports [rehydrateDocValue](pyric-firestore-values-reference-api.md#rehydratedocvalue)
+
+***
+
+<a id="sandbox-3"></a>
+
+### Sandbox
+
+Re-exports [Sandbox](pyric-firestore-reference-api.md#sandbox)
+
+***
+
+<a id="sandboxcontext"></a>
+
+### SandboxContext
+
+Re-exports [SandboxContext](pyric-firestore-reference-api.md#sandboxcontext)
+
+***
+
+<a id="sandboxerror"></a>
+
+### SandboxError
+
+Re-exports [SandboxError](pyric-firestore-reference-api.md#sandboxerror)