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

package/dist/serve/docs-ui/docs/pyric-firestore-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
 
@@ -177,13 +176,113 @@ isEqual(other: FieldPath): boolean;
 
 ***
 
+<a id="fieldvalue"></a>
+
+### FieldValue
+
+#### Constructors
+
+<a id="constructor-1"></a>
+
+##### Constructor
+
+```ts
+new FieldValue(): FieldValue;
+```
+
+###### Returns
+
+[`FieldValue`](#fieldvalue)
+
+#### Methods
+
+<a id="arrayremove"></a>
+
+##### arrayRemove()
+
+```ts
+static arrayRemove(...values: unknown[]): FieldValueSentinel;
+```
+
+###### Parameters
+
+| Parameter | Type |
+| :------ | :------ |
+| ...`values` | `unknown`[] |
+
+###### Returns
+
+[`FieldValueSentinel`](#fieldvaluesentinel)
+
+<a id="arrayunion"></a>
+
+##### arrayUnion()
+
+```ts
+static arrayUnion(...values: unknown[]): FieldValueSentinel;
+```
+
+###### Parameters
+
+| Parameter | Type |
+| :------ | :------ |
+| ...`values` | `unknown`[] |
+
+###### Returns
+
+[`FieldValueSentinel`](#fieldvaluesentinel)
+
+<a id="delete"></a>
+
+##### delete()
+
+```ts
+static delete(): FieldValueSentinel;
+```
+
+###### Returns
+
+[`FieldValueSentinel`](#fieldvaluesentinel)
+
+<a id="increment"></a>
+
+##### increment()
+
+```ts
+static increment(n: number): FieldValueSentinel;
+```
+
+###### Parameters
+
+| Parameter | Type |
+| :------ | :------ |
+| `n` | `number` |
+
+###### Returns
+
+[`FieldValueSentinel`](#fieldvaluesentinel)
+
+<a id="servertimestamp"></a>
+
+##### serverTimestamp()
+
+```ts
+static serverTimestamp(): FieldValueSentinel;
+```
+
+###### Returns
+
+[`FieldValueSentinel`](#fieldvaluesentinel)
+
+***
+
 <a id="geopoint"></a>
 
 ### GeoPoint
 
 #### Constructors
 
-<a id="constructor-1"></a>
+<a id="constructor-2"></a>
 
 ##### Constructor
 
@@ -312,193 +411,476 @@ static fromJSON(json: object): GeoPoint;
 
 ***
 
-<a id="vectorvalue"></a>
+<a id="sandboxerror"></a>
 
-### VectorValue
+### SandboxError
 
-#### Methods
+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).
 
-<a id="isequal-6"></a>
+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.
 
-##### isEqual()
+#### Extends
+
+- `Error`
+
+#### Constructors
+
+<a id="constructor-3"></a>
+
+##### Constructor
 
 ```ts
-isEqual(other: VectorValue): boolean;
+new SandboxError(
+   code: SandboxErrorCode,
+   message: string,
+   denialContext?: DenialContext): SandboxError;
 ```
 
 ###### Parameters
 
 | Parameter | Type |
 | :------ | :------ |
-| `other` | [`VectorValue`](#vectorvalue) |
+| `code` | [`SandboxErrorCode`](pyric-sandbox-reference-api.md#sandboxerrorcode) |
+| `message` | `string` |
+| `denialContext?` | [`DenialContext`](pyric-sandbox-reference-api.md#denialcontext) |
 
 ###### Returns
 
-`boolean`
+[`SandboxError`](#sandboxerror)
 
-<a id="toarray"></a>
+###### Overrides
 
-##### toArray()
+```ts
+Error.constructor
+```
+
+##### Constructor
 
 ```ts
-toArray(): number[];
+new SandboxError(options: SandboxErrorOptions): SandboxError;
 ```
 
-###### Returns
+###### Parameters
 
-`number`[]
+| Parameter | Type |
+| :------ | :------ |
+| `options` | `SandboxErrorOptions` |
 
-<a id="tojson-4"></a>
+###### Returns
 
-##### toJSON()
+[`SandboxError`](#sandboxerror)
+
+###### Overrides
 
 ```ts
-toJSON(): object;
+Error.constructor
 ```
 
-###### Returns
+#### Properties
 
-`object`
+| Property | Modifier | Type |
+| :------ | :------ | :------ |
+| <a id="code"></a> `code` | `readonly` | [`SandboxErrorCode`](pyric-sandbox-reference-api.md#sandboxerrorcode) |
+| <a id="denialcontext"></a> `denialContext?` | `readonly` | [`DenialContext`](pyric-sandbox-reference-api.md#denialcontext) |
+| <a id="remediation"></a> `remediation?` | `readonly` | `string` |
 
-<a id="create"></a>
+***
 
-##### create()
+<a id="timestamp"></a>
+
+### Timestamp
+
+#### Constructors
+
+<a id="constructor-4"></a>
+
+##### Constructor
 
 ```ts
-static create(values: number[]): VectorValue;
+new Timestamp(seconds: number, nanoseconds: number): Timestamp;
 ```
 
 ###### Parameters
 
 | Parameter | Type |
 | :------ | :------ |
-| `values` | `number`[] |
+| `seconds` | `number` |
+| `nanoseconds` | `number` |
 
 ###### Returns
 
-[`VectorValue`](#vectorvalue)
+[`Timestamp`](#timestamp)
 
-<a id="fromjson-4"></a>
+#### Properties
 
-##### fromJSON()
+| Property | Modifier | Type |
+| :------ | :------ | :------ |
+| <a id="nanoseconds"></a> `nanoseconds` | `readonly` | `number` |
+| <a id="seconds"></a> `seconds` | `readonly` | `number` |
+
+#### Methods
+
+<a id="isequal-6"></a>
+
+##### isEqual()
 
 ```ts
-static fromJSON(json: object): VectorValue;
+isEqual(other: Timestamp): boolean;
 ```
 
+FS-B12 — value equality, mirroring `fb.Timestamp.isEqual`.
+
 ###### Parameters
 
 | Parameter | Type |
 | :------ | :------ |
-| `json` | `object` |
+| `other` | [`Timestamp`](#timestamp) |
 
 ###### Returns
 
-[`VectorValue`](#vectorvalue)
+`boolean`
 
-## Interfaces
+<a id="todate"></a>
 
-<a id="aggregatequerysnapshot"></a>
+##### toDate()
 
-### AggregateQuerySnapshot
+```ts
+toDate(): Date;
+```
 
-Snapshot returned by `getCountFromServer` /
-`getAggregateFromServer`. `.data()` returns the computed numbers
-keyed by the spec's aliases (or `{ count: number }` for the
-count-only entry point).
+###### Returns
 
-#### Type Parameters
+`Date`
 
-| Type Parameter | Default type |
-| :------ | :------ |
-| `T` *extends* `Record`\<`string`, `number` \| `null`\> | `Record`\<`string`, `number` \| `null`\> |
+<a id="tojson-4"></a>
 
-#### Methods
+##### toJSON()
 
-<a id="data"></a>
+```ts
+toJSON(): {
+  nanoseconds: number;
+  seconds: number;
+  type: string;
+};
+```
 
-##### data()
+FS-B12 — JSON form, mirroring `fb.Timestamp.toJSON`.
+
+###### Returns
 
 ```ts
-data(): T;
+{
+  nanoseconds: number;
+  seconds: number;
+  type: string;
+}
 ```
 
-###### Returns
+###### nanoseconds
 
-`T`
+```ts
+nanoseconds: number;
+```
 
-***
+###### seconds
 
-<a id="collectionreference"></a>
+```ts
+seconds: number;
+```
 
-### CollectionReference
+###### type
 
-A reference to a Firestore collection. Backend-opaque.
+```ts
+type: string;
+```
 
-#### Type Parameters
+<a id="tomillis"></a>
 
-| Type Parameter | Default type |
-| :------ | :------ |
-| `_T` | [`AuthState`](#authstate) |
+##### toMillis()
 
-#### Properties
+```ts
+toMillis(): number;
+```
 
-| Property | Modifier | Type |
-| :------ | :------ | :------ |
-| <a id="id"></a> `id` | `readonly` | `string` |
-| <a id="path"></a> `path` | `readonly` | `string` |
+###### Returns
 
-***
+`number`
 
-<a id="documentreference"></a>
+<a id="tostring-2"></a>
 
-### DocumentReference
+##### toString()
 
-A reference to a Firestore document. Backend-opaque.
+```ts
+toString(): string;
+```
 
-#### Type Parameters
+FS-B12 — textual form, mirroring `fb.Timestamp.toString`.
 
-| Type Parameter | Default type |
-| :------ | :------ |
-| `_T` | [`AuthState`](#authstate) |
+###### Returns
 
-#### Properties
+`string`
 
-| Property | Modifier | Type |
-| :------ | :------ | :------ |
-| <a id="id-1"></a> `id` | `readonly` | `string` |
-| <a id="path-1"></a> `path` | `readonly` | `string` |
+<a id="valueof"></a>
 
-***
+##### valueOf()
 
-<a id="documentsnapshot"></a>
+```ts
+valueOf(): string;
+```
 
-### DocumentSnapshot
+FS-B12 — primitive coercion for `<`/`<=`/`>=`/`>` comparisons, mirroring
+`fb.Timestamp.valueOf`: a zero-padded `<seconds>.<nanoseconds>` string
+(seconds offset by MIN_SECONDS so it stays non-negative and lexically
+ordered).
 
-A point-in-time view of one document.
+###### Returns
 
-#### Extended by
+`string`
 
-- [`QueryDocumentSnapshot`](#querydocumentsnapshot)
+<a id="fromdate"></a>
 
-#### Type Parameters
+##### fromDate()
 
-| Type Parameter | Default type |
-| :------ | :------ |
-| `T` | [`AuthState`](#authstate) |
+```ts
+static fromDate(d: Date): Timestamp;
+```
 
-#### Properties
+###### Parameters
 
-| Property | Modifier | Type |
-| :------ | :------ | :------ |
-| <a id="exists"></a> `exists` | `readonly` | `boolean` \| () => `boolean` |
-| <a id="id-2"></a> `id` | `readonly` | `string` |
+| Parameter | Type |
+| :------ | :------ |
+| `d` | `Date` |
 
-#### Methods
+###### Returns
 
-<a id="data-2"></a>
+[`Timestamp`](#timestamp)
 
-##### data()
+<a id="frommillis"></a>
+
+##### fromMillis()
+
+```ts
+static fromMillis(ms: number): Timestamp;
+```
+
+###### Parameters
+
+| Parameter | Type |
+| :------ | :------ |
+| `ms` | `number` |
+
+###### Returns
+
+[`Timestamp`](#timestamp)
+
+<a id="now"></a>
+
+##### now()
+
+```ts
+static now(): Timestamp;
+```
+
+###### Returns
+
+[`Timestamp`](#timestamp)
+
+***
+
+<a id="vectorvalue"></a>
+
+### VectorValue
+
+#### Methods
+
+<a id="isequal-8"></a>
+
+##### isEqual()
+
+```ts
+isEqual(other: VectorValue): boolean;
+```
+
+###### Parameters
+
+| Parameter | Type |
+| :------ | :------ |
+| `other` | [`VectorValue`](#vectorvalue) |
+
+###### Returns
+
+`boolean`
+
+<a id="toarray"></a>
+
+##### toArray()
+
+```ts
+toArray(): number[];
+```
+
+###### Returns
+
+`number`[]
+
+<a id="tojson-6"></a>
+
+##### toJSON()
+
+```ts
+toJSON(): object;
+```
+
+###### Returns
+
+`object`
+
+<a id="create"></a>
+
+##### create()
+
+```ts
+static create(values: number[]): VectorValue;
+```
+
+###### Parameters
+
+| Parameter | Type |
+| :------ | :------ |
+| `values` | `number`[] |
+
+###### Returns
+
+[`VectorValue`](#vectorvalue)
+
+<a id="fromjson-4"></a>
+
+##### fromJSON()
+
+```ts
+static fromJSON(json: object): VectorValue;
+```
+
+###### Parameters
+
+| Parameter | Type |
+| :------ | :------ |
+| `json` | `object` |
+
+###### Returns
+
+[`VectorValue`](#vectorvalue)
+
+## Interfaces
+
+<a id="aggregatequerysnapshot"></a>
+
+### AggregateQuerySnapshot
+
+Snapshot returned by `getCountFromServer` /
+`getAggregateFromServer`. `.data()` returns the computed numbers
+keyed by the spec's aliases (or `{ count: number }` for the
+count-only entry point).
+
+#### Type Parameters
+
+| Type Parameter | Default type |
+| :------ | :------ |
+| `T` *extends* `Record`\<`string`, `number` \| `null`\> | `Record`\<`string`, `number` \| `null`\> |
+
+#### Methods
+
+<a id="data"></a>
+
+##### data()
+
+```ts
+data(): T;
+```
+
+###### Returns
+
+`T`
+
+***
+
+<a id="collectionreference"></a>
+
+### CollectionReference
+
+A reference to a Firestore collection. Backend-opaque.
+
+#### Type Parameters
+
+| Type Parameter | Default type |
+| :------ | :------ |
+| `_T` | [`DocumentData`](#documentdata) |
+
+#### Properties
+
+| Property | Modifier | Type |
+| :------ | :------ | :------ |
+| <a id="id"></a> `id` | `readonly` | `string` |
+| <a id="path"></a> `path` | `readonly` | `string` |
+
+***
+
+<a id="documentreference"></a>
+
+### DocumentReference
+
+A reference to a Firestore document. Backend-opaque.
+
+#### Type Parameters
+
+| Type Parameter | Default type |
+| :------ | :------ |
+| `_T` | [`DocumentData`](#documentdata) |
+
+#### Properties
+
+| Property | Modifier | Type |
+| :------ | :------ | :------ |
+| <a id="id-1"></a> `id` | `readonly` | `string` |
+| <a id="path-1"></a> `path` | `readonly` | `string` |
+
+***
+
+<a id="documentsnapshot"></a>
+
+### DocumentSnapshot
+
+A point-in-time view of one document.
+
+#### Extended by
+
+- [`QueryDocumentSnapshot`](#querydocumentsnapshot)
+
+#### Type Parameters
+
+| Type Parameter | Default type |
+| :------ | :------ |
+| `T` | [`DocumentData`](#documentdata) |
+
+#### Properties
+
+| Property | Modifier | Type |
+| :------ | :------ | :------ |
+| <a id="exists"></a> `exists` | `readonly` | `boolean` \| () => `boolean` |
+| <a id="id-2"></a> `id` | `readonly` | `string` |
+
+#### Methods
+
+<a id="data-2"></a>
+
+##### data()
 
 ```ts
 data(): T;
@@ -521,7 +903,7 @@ Opaque sandbox handle carrying its owner via [TARGET\_SYMBOL](#target_symbol-1).
 | Property | Modifier | Type |
 | :------ | :------ | :------ |
 | <a id="target_symbol"></a> `[TARGET_SYMBOL]` | `readonly` | `Target` |
-| <a id="app"></a> `app?` | `readonly` | `FirebaseApp` |
+| <a id="app"></a> `app?` | `readonly` | [`FirebaseApp`](pyric-app-reference-api.md#firebaseapp) |
 
 ***
 
@@ -544,7 +926,7 @@ underlying Firestore representation. Mirrors `firebase/firestore`'s
 | Type Parameter | Default type |
 | :------ | :------ |
 | `AppModelType` | - |
-| `DbModelType` *extends* [`AuthState`](#authstate) | [`AuthState`](#authstate) |
+| `DbModelType` *extends* [`DocumentData`](#documentdata) | [`DocumentData`](#documentdata) |
 
 #### Methods
 
@@ -632,14 +1014,17 @@ confirm-gate admin writes (see the bridge's prod confirm-policy).
 ##### resolveSandbox()
 
 ```ts
-resolveSandbox(): any;
+resolveSandbox():
+  | LocalSandbox
+| Promise<LocalSandbox>;
 ```
 
 Resolve the sandbox whose Firestore state should be inspected.
 
 ###### Returns
 
-`any`
+  \| [`LocalSandbox`](pyric-sandbox-reference-api.md#localsandbox)
+  \| `Promise`\<[`LocalSandbox`](pyric-sandbox-reference-api.md#localsandbox)\>
 
 ***
 
@@ -664,6 +1049,20 @@ Client-cache/network settings `initializeFirestore` accepts but no-ops
 
 ***
 
+<a id="lintresult"></a>
+
+### LintResult
+
+#### Properties
+
+| Property | Type | Description |
+| :------ | :------ | :------ |
+| <a id="metrics"></a> `metrics` | [`RulesMetrics`](pyric-admin-firestore-reference-api.md#rulesmetrics) | - |
+| <a id="parseerror"></a> `parseError?` | `ParseError` | Structured parse failure when the source did not parse. When defined, `metrics` (except `sourceSize`) and `warnings` carry no signal — budget checks were skipped. Callers should branch on `parseError` before interpreting warnings or metrics. Why this isn't a new `severity` value: a parse failure means "this isn't a rule yet" rather than "this rule will fail at runtime", which is a categorically different question from anything `warnings` answers. Adding a new severity would force every consumer to handle a third branch they don't care about; a separate field lets old code keep working and gives new code a clean signal to check. |
+| <a id="warnings"></a> `warnings` | [`LintWarning`](pyric-admin-firestore-reference-api.md#lintwarning)[] | - |
+
+***
+
 <a id="localcache-1"></a>
 
 ### LocalCache
@@ -679,157 +1078,743 @@ Opaque local-cache config token accepted by [initializeFirestore](#initializefir
 | <a id="garbagecollector"></a> `garbageCollector?` | `readonly` | [`MemoryGarbageCollector`](#memorygarbagecollector) |
 | <a id="tabmanager"></a> `tabManager?` | `readonly` | [`PersistentTabManager`](#persistenttabmanager) |
 
-***
+***
+
+<a id="memorygarbagecollector"></a>
+
+### MemoryGarbageCollector
+
+Opaque garbage-collector config token. Inert for the same reason —
+ there is no memory cache tier with GC pressure to tune.
+
+#### Properties
+
+| Property | Modifier | Type |
+| :------ | :------ | :------ |
+| <a id="gc_symbol"></a> `[GC_SYMBOL]` | `readonly` | `"eager"` \| `"lru"` |
+
+***
+
+<a id="persistencesettings"></a>
+
+### PersistenceSettings
+
+#### Properties
+
+| Property | Type |
+| :------ | :------ |
+| <a id="forceownership"></a> `forceOwnership?` | `boolean` |
+
+***
+
+<a id="persistenttabmanager"></a>
+
+### PersistentTabManager
+
+Opaque tab-manager config token. Inert — persistence is always on,
+ and the SharedWorker/`pyric dev` path already is the one shared
+ store every tab talks to, so there is no separate multi-tab mode
+ to opt into. Carries the requested kind only for debugging.
+
+#### Properties
+
+| Property | Modifier | Type |
+| :------ | :------ | :------ |
+| <a id="tab_manager_symbol"></a> `[TAB_MANAGER_SYMBOL]` | `readonly` | `"single"` \| `"multiple"` |
+
+***
+
+<a id="query"></a>
+
+### Query
+
+A Firestore query (a collection ref or one with where/orderBy/limit applied).
+
+#### Type Parameters
+
+| Type Parameter | Default type |
+| :------ | :------ |
+| `_T` | [`DocumentData`](#documentdata) |
+
+***
+
+<a id="queryconstraint"></a>
+
+### QueryConstraint
+
+#### Methods
+
+<a id="applysandbox"></a>
+
+##### applySandbox()
+
+```ts
+applySandbox(q: Query): Query;
+```
+
+###### Parameters
+
+| Parameter | Type |
+| :------ | :------ |
+| `q` | [`Query`](pyric-admin-firestore-reference-api.md#query) |
+
+###### Returns
+
+[`Query`](pyric-admin-firestore-reference-api.md#query)
+
+***
+
+<a id="querydocumentsnapshot"></a>
+
+### QueryDocumentSnapshot
+
+`QueryDocumentSnapshot` is a `DocumentSnapshot` known to exist —
+`.data()` always returns the typed model, never `undefined`. Yielded
+by `QuerySnapshot.docs` and passed to converter `fromFirestore`
+callbacks. Mirrors the JS SDK's narrowing.
+
+#### Extends
+
+- [`DocumentSnapshot`](#documentsnapshot)\<`T`\>
+
+#### Type Parameters
+
+| Type Parameter | Default type |
+| :------ | :------ |
+| `T` | [`DocumentData`](#documentdata) |
+
+#### Properties
+
+| Property | Modifier | Type |
+| :------ | :------ | :------ |
+| <a id="exists-1"></a> `exists` | `readonly` | `boolean` \| () => `boolean` |
+| <a id="id-3"></a> `id` | `readonly` | `string` |
+
+#### Methods
+
+<a id="data-4"></a>
+
+##### data()
+
+```ts
+data(): T;
+```
+
+###### Returns
+
+`T`
+
+###### Overrides
+
+[`DocumentSnapshot`](#documentsnapshot).[`data`](#data-2)
+
+***
+
+<a id="querysnapshot"></a>
+
+### QuerySnapshot
+
+A point-in-time view of a query result.
+
+#### Type Parameters
+
+| Type Parameter | Default type |
+| :------ | :------ |
+| `T` | [`DocumentData`](#documentdata) |
+
+#### Properties
+
+| Property | Modifier | Type |
+| :------ | :------ | :------ |
+| <a id="docs"></a> `docs` | `readonly` | readonly [`QueryDocumentSnapshot`](#querydocumentsnapshot)\<`T`\>[] |
+| <a id="empty"></a> `empty` | `readonly` | `boolean` |
+| <a id="size"></a> `size` | `readonly` | `number` |
+
+***
+
+<a id="sandbox"></a>
+
+### Sandbox
+
+A Firebase sandbox — an isolated environment with one auth identity.
+
+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.
+
+#### Extended by
+
+- [`LocalSandbox`](pyric-sandbox-reference-api.md#localsandbox)
+- [`RemoteSandbox`](pyric-sandbox-reference-api.md#remotesandbox)
+
+#### Properties
+
+| Property | Modifier | Type | Description |
+| :------ | :------ | :------ | :------ |
+| <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. |
+| `currentUser.token?` | `public` | `Record`\<`string`, `unknown`\> | - |
+| `currentUser.uid` | `public` | `string` | - |
+
+#### Methods
+
+<a id="clearpersistence"></a>
+
+##### clearPersistence()
+
+```ts
+clearPersistence(): Promise<void>;
+```
+
+Wipe the persisted blob for this sandbox's `key`. In-memory state
+is left intact — call `reset()` if you want both. Useful for
+"sign out and forget" flows.
+
+No-op when persistence is not enabled.
+
+###### Returns
+
+`Promise`\<`void`\>
+
+<a id="dispose"></a>
+
+##### dispose()
+
+```ts
+dispose(): void;
+```
+
+Tear down listener registries on this sandbox's environment without
+replacing it. Use this when you're about to discard the sandbox
+itself (e.g. `runner.reseed()` builds a fresh sandbox rather than
+calling `reset()`) and want to drop callback references on the
+outgoing instance defensively. Idempotent. Does not touch data.
+
+###### Returns
+
+`void`
+
+<a id="enablepersistence"></a>
+
+##### enablePersistence()
+
+```ts
+enablePersistence(options: SandboxPersistenceOptions): Promise<void>;
+```
+
+Persist the sandbox's data to a backend and restore it on next
+`enablePersistence` call. The default `'indexedDB'` backend turns
+the sandbox into the host page's local Firestore — writes flush
+automatically and a fresh `initializeSandbox()` rehydrates from
+the prior session.
+
+Restoration happens before the promise resolves; awaiting this
+call is sufficient to guarantee in-memory state matches the
+persisted blob.
+
+Idempotent across the same `key` — calling twice in one process
+is a no-op on the second call. Different keys are rejected as an
+error (a sandbox can persist to at most one backend at a time).
+
+Listener semantics: every write event the sandbox emits triggers
+a debounced flush (default 250ms). Browser hosts additionally
+flush on `beforeunload` so a page navigation doesn't lose the
+tail of the debounce window.
+
+See [SandboxPersistenceOptions](pyric-sandbox-reference-api.md#sandboxpersistenceoptions) for backend selection and
+tuning.
+
+###### Parameters
+
+| Parameter | Type |
+| :------ | :------ |
+| `options` | [`SandboxPersistenceOptions`](pyric-sandbox-reference-api.md#sandboxpersistenceoptions) |
+
+###### Returns
+
+`Promise`\<`void`\>
+
+<a id="enabletabsync"></a>
+
+##### enableTabSync()
+
+```ts
+enableTabSync(options?: TabSyncOptions): () => void;
+```
+
+Enable cross-tab realtime sync via `BroadcastChannel`. A write in
+this tab will propagate to every OTHER tab of the same origin that
+also called `enableTabSync`, causing their `onSnapshot` listeners to
+re-evaluate — restoring production's cross-client realtime behavior.
+
+**Opt-in, OFF by default.** Firestore only (RTDB is a follow-on).
+
+Returns a disable function. Calling it removes the `onEvent`
+subscription, the channel message listener, and closes the channel
+(when it was created internally). After disable, no further propagation
+occurs in either direction.
+
+**Multi-writer note:** concurrent writes from two tabs to the same doc
+produce last-write-wins divergence — there is no conflict resolution.
+The intended model is one active writer (one user, one tab) with
+observers in other tabs; this covers the overwhelming majority of
+local development scenarios.
+
+###### Parameters
+
+| Parameter | Type |
+| :------ | :------ |
+| `options?` | [`TabSyncOptions`](pyric-sandbox-reference-api.md#tabsyncoptions) |
+
+###### Returns
+
+```ts
+(): void;
+```
+
+###### Returns
+
+`void`
+
+###### See
+
+[TabSyncOptions](pyric-sandbox-reference-api.md#tabsyncoptions) for channel injection (tests) and originId.
+
+###### Example
+
+```ts
+// In every tab that should participate in realtime:
+const sandbox = initializeSandbox();
+const disableSync = sandbox.enableTabSync();
+// Later, to stop syncing:
+disableSync();
+```
+
+<a id="flush"></a>
+
+##### flush()
+
+```ts
+flush(): Promise<void>;
+```
+
+Force a snapshot to the configured persistence backend right now.
+Useful before a manual navigation, or in tests that need
+deterministic ordering against the debounce window. Resolves once
+the write hits the backend.
+
+Throws if persistence is not enabled.
+
+###### Returns
+
+`Promise`\<`void`\>
+
+<a id="history"></a>
+
+##### history()
+
+```ts
+history(): SandboxEvent[];
+```
+
+Every [SandboxEvent](pyric-sandbox-reference-api.md#sandboxevent) this sandbox has emitted since init or
+the last `reset()`. Returns a defensive copy.
+
+Use this for replay: hand the array to `replay(events, rules)`
+from `pyric/sandbox` and the engine re-issues every
+captured write against a fresh sandbox.
+
+Unlike [onEvent](#onevent) (live stream from the moment of subscribe),
+`history()` returns *every* event the sandbox has seen — useful
+for consumers that attach late (e.g., loading a saved session
+before subscribing) or that need a snapshot at a particular moment.
+
+`reset()` and `dispose()` each append a closing `session_boundary`
+event; `reset()` then clears the history. Consumers that took a
+snapshot *before* reset retain the boundary in their copy.
+
+###### Returns
+
+[`SandboxEvent`](pyric-sandbox-reference-api.md#sandboxevent)[]
+
+<a id="loadsnapshot"></a>
+
+##### loadSnapshot()
+
+```ts
+loadSnapshot(data: SandboxSnapshot): void;
+```
+
+CLOBBER-restore the sandbox's entire state from a prior [snapshot](#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). 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) always includes every registered
+service, so this only affects cross-instance imports from a sandbox that had
+a service this one lacks).
+
+###### Parameters
+
+| Parameter | Type |
+| :------ | :------ |
+| `data` | [`SandboxSnapshot`](pyric-sandbox-reference-api.md#sandboxsnapshot) |
+
+###### Returns
+
+`void`
+
+<a id="oncurrentuserchanged"></a>
+
+##### onCurrentUserChanged()
+
+```ts
+onCurrentUserChanged(cb: (user: {
+  token?: Record<string, unknown>;
+  uid: string;
+}) => void): () => void;
+```
+
+Subscribe to `currentUser` changes. Fires on every mutation —
+sign-in, sign-out, user swap. Does NOT fire on subscribe.
+
+Survives `reset()` and `dispose()` only as a no-op: a disposed
+sandbox emits nothing further; a reset sandbox clears
+`currentUser` to `null` (and fires the change) before swapping
+the env.
+
+Returns an unsubscribe function. Listener errors are swallowed —
+subscribers are observational, the sandbox does not propagate
+their errors.
+
+###### Parameters
+
+| Parameter | Type |
+| :------ | :------ |
+| `cb` | (`user`: \{ `token?`: `Record`\<`string`, `unknown`\>; `uid`: `string`; \}) => `void` |
+
+###### Returns
+
+```ts
+(): void;
+```
+
+###### Returns
+
+`void`
+
+<a id="onevent"></a>
+
+##### onEvent()
+
+```ts
+onEvent(cb: (event: SandboxEvent) => void): () => void;
+```
+
+Subscribe to every event the sandbox emits — see [SandboxEvent](pyric-sandbox-reference-api.md#sandboxevent)
+for the discriminated-union shape. One subscription covers
+request/denial/snapshot-error/listener-lifecycle/session-boundary;
+filter on `event.kind` to recover individual streams.
+
+Replaces the prior three-channel surface (`onRequest` / `onDenial`
+/ `onSnapshotError`) — see issue #307. Filter cookbook:
+  - All denials:    `event.kind === 'request' && event.result === 'deny'`
+  - Stream errors:  `event.kind === 'listener_errored'`
+  - Per-op traffic: `event.kind === 'request'`
+
+Survives `sandbox.reset()` — the subscription is held on the
+sandbox, not on the underlying environment. A `session_boundary`
+event with `phase: 'reset'` fires before the env swap so consumers
+can segment their stream.
+
+Returns an unsubscribe function. Listener errors are swallowed so a
+faulty subscriber can't change rule semantics or hide other events.
+Both synchronous throws and rejected Promises from async callbacks
+are silently discarded — subscribers are **observational**, the
+sandbox doesn't await them and doesn't propagate their errors.
+
+###### Parameters
+
+| Parameter | Type |
+| :------ | :------ |
+| `cb` | (`event`: [`SandboxEvent`](pyric-sandbox-reference-api.md#sandboxevent)) => `void` |
+
+###### Returns
+
+```ts
+(): void;
+```
+
+###### Returns
 
-<a id="memorygarbagecollector"></a>
+`void`
 
-### MemoryGarbageCollector
+<a id="registerpersistableservice"></a>
 
-Opaque garbage-collector config token. Inert for the same reason —
- there is no memory cache tier with GC pressure to tune.
+##### registerPersistableService()
 
-#### Properties
+```ts
+registerPersistableService(name: string, hooks: PersistableService): () => void;
+```
 
-| Property | Modifier | Type |
-| :------ | :------ | :------ |
-| <a id="gc_symbol"></a> `[GC_SYMBOL]` | `readonly` | `"eager"` \| `"lru"` |
+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).
 
-<a id="persistencesettings"></a>
+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.
 
-### PersistenceSettings
+**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.
 
-#### Properties
+###### Parameters
 
-| Property | Type |
+| Parameter | Type |
 | :------ | :------ |
-| <a id="forceownership"></a> `forceOwnership?` | `boolean` |
+| `name` | `string` |
+| `hooks` | [`PersistableService`](pyric-sandbox-reference-api.md#persistableservice) |
 
-***
+###### Returns
 
-<a id="persistenttabmanager"></a>
+```ts
+(): void;
+```
 
-### PersistentTabManager
+###### Returns
 
-Opaque tab-manager config token. Inert — persistence is always on,
- and the SharedWorker/`pyric dev` path already is the one shared
- store every tab talks to, so there is no separate multi-tab mode
- to opt into. Carries the requested kind only for debugging.
+`void`
 
-#### Properties
+<a id="reset"></a>
 
-| Property | Modifier | Type |
-| :------ | :------ | :------ |
-| <a id="tab_manager_symbol"></a> `[TAB_MANAGER_SYMBOL]` | `readonly` | `"single"` \| `"multiple"` |
+##### reset()
 
-***
+```ts
+reset(): void;
+```
 
-<a id="query"></a>
+Reset the underlying environment to a fresh state — wipes data,
+rules, and any service-specific configuration.
 
-### Query
+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.
 
-A Firestore query (a collection ref or one with where/orderBy/limit applied).
+###### Returns
 
-#### Type Parameters
+`void`
 
-| Type Parameter | Default type |
-| :------ | :------ |
-| `_T` | [`AuthState`](#authstate) |
+<a id="resetall"></a>
 
-***
+##### resetAll()
 
-<a id="queryconstraint"></a>
+```ts
+resetAll(): Promise<{
+  errors: string[];
+}>;
+```
 
-### QueryConstraint
+Reset the WHOLE sandbox: [reset](#reset) (Firestore env + signed-in
+session), then clear every registered persistable service that
+provides a [PersistableService.reset](pyric-sandbox-reference-api.md#reset-2) hook — auth users, the
+RTDB tree, storage objects. This is the one sandbox-owned "wipe
+everything" path: because it iterates the service registry, a new
+service that registers with a `reset` hook is cleared automatically,
+and a consumer (Pyric Studio's reset) cannot forget one.
 
-#### Methods
+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.
 
-<a id="applysandbox"></a>
+###### Returns
 
-##### applySandbox()
+`Promise`\<\{
+  `errors`: `string`[];
+\}\>
+
+<a id="runwithprovenance"></a>
+
+##### runWithProvenance()?
 
 ```ts
-applySandbox(q: ChainQuery): ChainQuery;
+optional runWithProvenance<T>(provenance: EventProvenance, fn: () => T): T;
 ```
 
+Run `fn` with ambient [EventProvenance](pyric-sandbox-reference-api.md#eventprovenance) defaults: every event
+emitted SYNCHRONOUSLY during `fn` that doesn't already carry a
+provenance field (on the event itself or via an explicit per-emit
+override) is stamped with these values instead of the global
+defaults. This is the mechanical "who issued this op" seam the
+serve worker uses to tag Studio-issued ops (`actor: { kind:
+'studio' }`) and to stamp the auth lens an op ran under
+(`authLens`) — declared by the caller that issues the op, never
+inferred from the op's shape.
+
+SYNCHRONOUS WINDOW: the ambient values apply only until `fn`
+returns (for an async `fn`, its synchronous prefix — which covers
+the local environment's rules eval + event emission, since those
+run before the op's promise is handed back). Work an op DEFERS
+(snapshot-listener deliveries and re-evals drain on a microtask,
+off-stack) is intentionally OUTSIDE the window: a listener re-eval
+belongs to the listener's owner, not to whoever's write triggered
+it. Nested calls stack — the innermost window wins per field, and
+each window restores the previous one on exit (including on throw).
+
+OPTIONAL because remote sandbox proxies can't provide an ambient
+emit window (events are emitted in the worker they front). Callers
+spell `sandbox.runWithProvenance?.(prov, fn) ?? fn()`.
+
+###### Type Parameters
+
+| Type Parameter |
+| :------ |
+| `T` |
+
 ###### Parameters
 
 | Parameter | Type |
 | :------ | :------ |
-| `q` | `ChainQuery` |
+| `provenance` | [`EventProvenance`](pyric-sandbox-reference-api.md#eventprovenance) |
+| `fn` | () => `T` |
 
 ###### Returns
 
-`ChainQuery`
+`T`
 
-***
+<a id="snapshot"></a>
 
-<a id="querydocumentsnapshot"></a>
+##### snapshot()
 
-### QueryDocumentSnapshot
+```ts
+snapshot(): SandboxSnapshot;
+```
 
-`QueryDocumentSnapshot` is a `DocumentSnapshot` known to exist —
-`.data()` always returns the typed model, never `undefined`. Yielded
-by `QuerySnapshot.docs` and passed to converter `fromFirestore`
-callbacks. Mirrors the JS SDK's narrowing.
+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.
 
-#### Extends
+###### Returns
 
-- [`DocumentSnapshot`](#documentsnapshot)\<`T`\>
+[`SandboxSnapshot`](pyric-sandbox-reference-api.md#sandboxsnapshot)
 
-#### Type Parameters
+<a id="withauth"></a>
 
-| Type Parameter | Default type |
-| :------ | :------ |
-| `T` | [`AuthState`](#authstate) |
+##### withAuth()
 
-#### Properties
+```ts
+withAuth(auth: {
+  token?: Record<string, unknown>;
+  uid: string;
+}): SandboxContext;
+```
 
-| Property | Modifier | Type |
-| :------ | :------ | :------ |
-| <a id="exists-1"></a> `exists` | `readonly` | `boolean` \| () => `boolean` |
-| <a id="id-3"></a> `id` | `readonly` | `string` |
+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.
 
-#### Methods
+`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.
 
-<a id="data-4"></a>
+###### Parameters
 
-##### data()
+| Parameter | Type |
+| :------ | :------ |
+| `auth` | \{ `token?`: `Record`\<`string`, `unknown`\>; `uid`: `string`; \} |
+| `auth.token?` | `Record`\<`string`, `unknown`\> |
+| `auth.uid` | `string` |
+
+###### Returns
+
+[`SandboxContext`](#sandboxcontext)
+
+###### Example
 
 ```ts
-data(): T;
+const sandbox = initializeSandbox();
+const dbAlice = getFirestore(sandbox.withAuth({ uid: 'alice' }));
+const dbAnon  = getFirestore(sandbox.withAuth(null));
 ```
 
-###### Returns
+***
 
-`T`
+<a id="sandboxcontext"></a>
 
-###### Overrides
+### SandboxContext
 
-[`DocumentSnapshot`](#documentsnapshot).[`data`](#data-2)
+Identity-bearing handle on a [Sandbox](#sandbox). 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.
 
-<a id="querysnapshot"></a>
+#### Properties
 
-### QuerySnapshot
+| Property | Modifier | Type | Description |
+| :------ | :------ | :------ | :------ |
+| <a id="auth"></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"></a> `operationContext` | `readonly` | [`OperationContext`](pyric-sandbox-reference-api.md#operationcontext-2) | Immutable provenance bound to every operation issued through this handle. |
+| <a id="sandbox-1"></a> `sandbox` | `readonly` | [`Sandbox`](#sandbox) | The data foundation this context operates against. |
 
-A point-in-time view of a query result.
+#### Methods
 
-#### Type Parameters
+<a id="withauth-2"></a>
 
-| Type Parameter | Default type |
+##### 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 |
 | :------ | :------ |
-| `T` | [`AuthState`](#authstate) |
+| `auth` | \{ `token?`: `Record`\<`string`, `unknown`\>; `uid`: `string`; \} |
+| `auth.token?` | `Record`\<`string`, `unknown`\> |
+| `auth.uid` | `string` |
 
-#### Properties
+###### Returns
 
-| Property | Modifier | Type |
-| :------ | :------ | :------ |
-| <a id="docs"></a> `docs` | `readonly` | readonly [`QueryDocumentSnapshot`](#querydocumentsnapshot)\<`T`\>[] |
-| <a id="empty"></a> `empty` | `readonly` | `boolean` |
-| <a id="size"></a> `size` | `readonly` | `number` |
+[`SandboxContext`](#sandboxcontext)
 
 ***
 
@@ -986,7 +1971,56 @@ of omitting an auth field, and acting-as-a-user is named too.
 ### AuthState
 
 ```ts
-type AuthState = any;
+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="documentdata"></a>
+
+### DocumentData
+
+```ts
+type DocumentData = Record<string, unknown>;
+```
+
+***
+
+<a id="fieldvaluesentinel"></a>
+
+### FieldValueSentinel
+
+```ts
+type FieldValueSentinel =
+  | {
+}
+  | {
+  value: number;
+}
+  | {
+  values: unknown[];
+}
+  | {
+  values: unknown[];
+}
+  | {
+};
 ```
 
 ***
@@ -1003,12 +2037,22 @@ Mirrors `firebase/firestore`'s `LogLevel` union.
 
 ***
 
+<a id="orderdirection"></a>
+
+### OrderDirection
+
+```ts
+type OrderDirection = "asc" | "desc";
+```
+
+***
+
 <a id="transaction"></a>
 
 ### Transaction
 
 ```ts
-type Transaction = AuthState;
+type Transaction = Transaction;
 ```
 
 ***
@@ -1027,12 +2071,32 @@ type Unsubscribe = () => void;
 
 ***
 
+<a id="wherefilterop"></a>
+
+### WhereFilterOp
+
+```ts
+type WhereFilterOp =
+  | "<"
+  | "<="
+  | "=="
+  | "!="
+  | ">="
+  | ">"
+  | "in"
+  | "not-in"
+  | "array-contains"
+  | "array-contains-any";
+```
+
+***
+
 <a id="writebatch"></a>
 
 ### WriteBatch
 
 ```ts
-type WriteBatch = AuthState;
+type WriteBatch = WriteBatch;
 ```
 
 ## Variables
@@ -1055,7 +2119,10 @@ the sandbox backend so free functions can recover their owner.
 ### actingAs()
 
 ```ts
-function actingAs(sandbox: Sandbox, identity: AuthState): Firestore;
+function actingAs(sandbox: Sandbox, identity: {
+  token?: Record<string, unknown>;
+  uid: string;
+}): Firestore;
 ```
 
 A Firestore handle scoped to a specific identity, for multi-user testing.
@@ -1070,8 +2137,10 @@ delivered to another's `onSnapshot`: the basis for multi-user sync testing.
 
 | Parameter | Type |
 | :------ | :------ |
-| `sandbox` | `Sandbox` |
-| `identity` | `AuthState` |
+| `sandbox` | [`Sandbox`](#sandbox) |
+| `identity` | \{ `token?`: `Record`\<`string`, `unknown`\>; `uid`: `string`; \} |
+| `identity.token?` | `Record`\<`string`, `unknown`\> |
+| `identity.uid` | `string` |
 
 #### Returns
 
@@ -1109,7 +2178,7 @@ function addDoc<T>(coll: CollectionReference<T>, data: T): Promise<DocumentRefer
 
 | Type Parameter | Default type |
 | :------ | :------ |
-| `T` | `DocumentData` |
+| `T` | [`DocumentData`](#documentdata) |
 
 #### Parameters
 
@@ -1148,7 +2217,7 @@ would otherwise be at the top level.
 
 ***
 
-<a id="arrayremove"></a>
+<a id="arrayremove-2"></a>
 
 ### arrayRemove()
 
@@ -1164,11 +2233,11 @@ function arrayRemove(...values: unknown[]): FieldValueSentinel;
 
 #### Returns
 
-`FieldValueSentinel`
+[`FieldValueSentinel`](#fieldvaluesentinel)
 
 ***
 
-<a id="arrayunion"></a>
+<a id="arrayunion-2"></a>
 
 ### arrayUnion()
 
@@ -1184,7 +2253,7 @@ function arrayUnion(...values: unknown[]): FieldValueSentinel;
 
 #### Returns
 
-`FieldValueSentinel`
+[`FieldValueSentinel`](#fieldvaluesentinel)
 
 ***
 
@@ -1260,7 +2329,7 @@ function collection(parent:
 
 | Parameter | Type |
 | :------ | :------ |
-| `parent` | \| [`Firestore`](#firestore) \| [`DocumentReference`](#documentreference)\<`DocumentData`\> |
+| `parent` | \| [`Firestore`](#firestore) \| [`DocumentReference`](#documentreference)\<[`DocumentData`](#documentdata)\> |
 | ...`pathSegments` | `string`[] |
 
 #### Returns
@@ -1448,7 +2517,7 @@ function deleteField(): FieldValueSentinel;
 
 #### Returns
 
-`FieldValueSentinel`
+[`FieldValueSentinel`](#fieldvaluesentinel)
 
 ***
 
@@ -1495,7 +2564,7 @@ function doc<T>(parent:
 
 | Type Parameter | Default type |
 | :------ | :------ |
-| `T` | `DocumentData` |
+| `T` | [`DocumentData`](#documentdata) |
 
 #### Parameters
 
@@ -1729,7 +2798,7 @@ uid }))` instead.
 
 | Parameter | Type |
 | :------ | :------ |
-| `sandbox` | `Sandbox` |
+| `sandbox` | [`Sandbox`](#sandbox) |
 
 ##### Returns
 
@@ -1777,7 +2846,7 @@ uid }))` instead.
 
 | Parameter | Type |
 | :------ | :------ |
-| `ctx` | `SandboxContext` |
+| `ctx` | [`SandboxContext`](#sandboxcontext) |
 
 ##### Returns
 
@@ -1825,7 +2894,7 @@ uid }))` instead.
 
 | Parameter | Type |
 | :------ | :------ |
-| `app` | `FirebaseApp` |
+| `app` | [`FirebaseApp`](pyric-app-reference-api.md#firebaseapp) |
 
 ##### Returns
 
@@ -1869,7 +2938,7 @@ The sandbox target dispatches straight into the chainable adapter.
 
 | Parameter | Type |
 | :------ | :------ |
-| `source` | \| [`Query`](#query)\<`DocumentData`\> \| [`CollectionReference`](#collectionreference)\<`DocumentData`\> |
+| `source` | \| [`Query`](#query)\<[`DocumentData`](#documentdata)\> \| [`CollectionReference`](#collectionreference)\<[`DocumentData`](#documentdata)\> |
 | `spec` | `S` |
 
 #### Returns
@@ -1898,7 +2967,7 @@ Count documents matching the query. Returns a snapshot whose
 
 | Parameter | Type |
 | :------ | :------ |
-| `source` | \| [`Query`](#query)\<`DocumentData`\> \| [`CollectionReference`](#collectionreference)\<`DocumentData`\> |
+| `source` | \| [`Query`](#query)\<[`DocumentData`](#documentdata)\> \| [`CollectionReference`](#collectionreference)\<[`DocumentData`](#documentdata)\> |
 
 #### Returns
 
@@ -1920,7 +2989,7 @@ function getDoc<T>(ref: DocumentReference<T>): Promise<DocumentSnapshot<T>>;
 
 | Type Parameter | Default type |
 | :------ | :------ |
-| `T` | `DocumentData` |
+| `T` | [`DocumentData`](#documentdata) |
 
 #### Parameters
 
@@ -1952,7 +3021,7 @@ not a claim of parity.
 
 | Type Parameter | Default type |
 | :------ | :------ |
-| `T` | `DocumentData` |
+| `T` | [`DocumentData`](#documentdata) |
 
 #### Parameters
 
@@ -1983,7 +3052,7 @@ same honest thing.
 
 | Type Parameter | Default type |
 | :------ | :------ |
-| `T` | `DocumentData` |
+| `T` | [`DocumentData`](#documentdata) |
 
 #### Parameters
 
@@ -2009,7 +3078,7 @@ function getDocs<T>(query: Query<T>): Promise<QuerySnapshot<T>>;
 
 | Type Parameter | Default type |
 | :------ | :------ |
-| `T` | `DocumentData` |
+| `T` | [`DocumentData`](#documentdata) |
 
 #### Parameters
 
@@ -2037,7 +3106,7 @@ Query-plural form of [getDocFromCache](#getdocfromcache) — same cache-miss div
 
 | Type Parameter | Default type |
 | :------ | :------ |
-| `T` | `DocumentData` |
+| `T` | [`DocumentData`](#documentdata) |
 
 #### Parameters
 
@@ -2065,7 +3134,7 @@ Query-plural form of [getDocFromServer](#getdocfromserver).
 
 | Type Parameter | Default type |
 | :------ | :------ |
-| `T` | `DocumentData` |
+| `T` | [`DocumentData`](#documentdata) |
 
 #### Parameters
 
@@ -2105,7 +3174,7 @@ input's shape:
 
 | Parameter | Type |
 | :------ | :------ |
-| `ctx` | `SandboxContext` |
+| `ctx` | [`SandboxContext`](#sandboxcontext) |
 
 ##### Returns
 
@@ -2157,7 +3226,7 @@ input's shape:
 
 | Parameter | Type |
 | :------ | :------ |
-| `sandbox` | `Sandbox` |
+| `sandbox` | [`Sandbox`](#sandbox) |
 
 ##### Returns
 
@@ -2209,7 +3278,7 @@ input's shape:
 
 | Parameter | Type |
 | :------ | :------ |
-| `app` | `FirebaseApp` |
+| `app` | [`FirebaseApp`](pyric-app-reference-api.md#firebaseapp) |
 
 ##### Returns
 
@@ -2288,7 +3357,10 @@ const db = getFirestore(app);
 #### Call Signature
 
 ```ts
-function getFirestore(target?: any): Firestore;
+function getFirestore(target?:
+  | FirebaseApp
+  | Sandbox
+  | SandboxContext): Firestore;
 ```
 
 Construct a Firestore handle. Three overloads dispatch by the
@@ -2307,7 +3379,7 @@ input's shape:
 
 | Parameter | Type |
 | :------ | :------ |
-| `target?` | `any` |
+| `target?` | \| [`FirebaseApp`](pyric-app-reference-api.md#firebaseapp) \| [`Sandbox`](#sandbox) \| [`SandboxContext`](#sandboxcontext) |
 
 ##### Returns
 
@@ -2339,7 +3411,7 @@ const db = getFirestore(app);
 
 ***
 
-<a id="increment"></a>
+<a id="increment-2"></a>
 
 ### increment()
 
@@ -2355,7 +3427,7 @@ function increment(n: number): FieldValueSentinel;
 
 #### Returns
 
-`FieldValueSentinel`
+[`FieldValueSentinel`](#fieldvaluesentinel)
 
 ***
 
@@ -2365,7 +3437,10 @@ function increment(n: number): FieldValueSentinel;
 
 ```ts
 function initializeFirestore(
-   app: any,
+   app:
+  | FirebaseApp
+  | Sandbox
+  | SandboxContext,
    _settings?: FirestoreSettings,
    _databaseId?: string): Firestore;
 ```
@@ -2381,7 +3456,7 @@ configure into existence.
 
 | Parameter | Type |
 | :------ | :------ |
-| `app` | `any` |
+| `app` | \| [`FirebaseApp`](pyric-app-reference-api.md#firebaseapp) \| [`Sandbox`](#sandbox) \| [`SandboxContext`](#sandboxcontext) |
 | `_settings?` | [`FirestoreSettings`](#firestoresettings) |
 | `_databaseId?` | `string` |
 
@@ -2520,7 +3595,7 @@ function onSnapshot<T>(
 
 | Type Parameter |
 | :------ |
-| `T` *extends* \| [`DocumentReference`](#documentreference)\<`DocumentData`\> \| [`Query`](#query)\<`DocumentData`\> |
+| `T` *extends* \| [`DocumentReference`](#documentreference)\<[`DocumentData`](#documentdata)\> \| [`Query`](#query)\<[`DocumentData`](#documentdata)\> |
 
 ##### Parameters
 
@@ -2550,7 +3625,7 @@ function onSnapshot<T>(
 
 | Type Parameter |
 | :------ |
-| `T` *extends* \| [`DocumentReference`](#documentreference)\<`DocumentData`\> \| [`Query`](#query)\<`DocumentData`\> |
+| `T` *extends* \| [`DocumentReference`](#documentreference)\<[`DocumentData`](#documentdata)\> \| [`Query`](#query)\<[`DocumentData`](#documentdata)\> |
 
 ##### Parameters
 
@@ -2641,7 +3716,7 @@ function orderBy(field: string | FieldPath, direction?: OrderDirection): QueryCo
 | Parameter | Type |
 | :------ | :------ |
 | `field` | `string` \| [`FieldPath`](#fieldpath) |
-| `direction?` | `OrderDirection` |
+| `direction?` | [`OrderDirection`](#orderdirection) |
 
 #### Returns
 
@@ -2734,7 +3809,7 @@ function query<T>(source:
 
 | Type Parameter | Default type |
 | :------ | :------ |
-| `T` | `DocumentData` |
+| `T` | [`DocumentData`](#documentdata) |
 
 #### Parameters
 
@@ -2796,7 +3871,7 @@ function refEqual(a: DocumentReference, b: DocumentReference): boolean;
 ### runTransaction()
 
 ```ts
-function runTransaction<R>(db: Firestore, fn: (tx: ChainTransaction) => R | Promise<R>): Promise<R>;
+function runTransaction<R>(db: Firestore, fn: (tx: Transaction) => R | Promise<R>): Promise<R>;
 ```
 
 #### Type Parameters
@@ -2810,7 +3885,7 @@ function runTransaction<R>(db: Firestore, fn: (tx: ChainTransaction) => R | Prom
 | Parameter | Type |
 | :------ | :------ |
 | `db` | [`Firestore`](#firestore) |
-| `fn` | (`tx`: `ChainTransaction`) => `R` \| `Promise`\<`R`\> |
+| `fn` | (`tx`: [`Transaction`](pyric-admin-firestore-reference-api.md#transaction)) => `R` \| `Promise`\<`R`\> |
 
 #### Returns
 
@@ -2818,7 +3893,7 @@ function runTransaction<R>(db: Firestore, fn: (tx: ChainTransaction) => R | Prom
 
 ***
 
-<a id="servertimestamp"></a>
+<a id="servertimestamp-2"></a>
 
 ### serverTimestamp()
 
@@ -2828,7 +3903,7 @@ function serverTimestamp(): FieldValueSentinel;
 
 #### Returns
 
-`FieldValueSentinel`
+[`FieldValueSentinel`](#fieldvaluesentinel)
 
 ***
 
@@ -2847,7 +3922,7 @@ options?: SetOptions): Promise<void>;
 
 | Type Parameter | Default type |
 | :------ | :------ |
-| `T` | `DocumentData` |
+| `T` | [`DocumentData`](#documentdata) |
 
 #### Parameters
 
@@ -2905,8 +3980,8 @@ function snapshotEqual(a:
 
 | Parameter | Type |
 | :------ | :------ |
-| `a` | \| [`DocumentSnapshot`](#documentsnapshot)\<`DocumentData`\> \| [`QuerySnapshot`](#querysnapshot)\<`DocumentData`\> |
-| `b` | \| [`DocumentSnapshot`](#documentsnapshot)\<`DocumentData`\> \| [`QuerySnapshot`](#querysnapshot)\<`DocumentData`\> |
+| `a` | \| [`DocumentSnapshot`](#documentsnapshot)\<[`DocumentData`](#documentdata)\> \| [`QuerySnapshot`](#querysnapshot)\<[`DocumentData`](#documentdata)\> |
+| `b` | \| [`DocumentSnapshot`](#documentsnapshot)\<[`DocumentData`](#documentdata)\> \| [`QuerySnapshot`](#querysnapshot)\<[`DocumentData`](#documentdata)\> |
 
 #### Returns
 
@@ -3091,7 +4166,7 @@ against the same path.
 | Parameter | Type |
 | :------ | :------ |
 | `ref` | [`DocumentReference`](#documentreference) |
-| `data` | `DocumentData` |
+| `data` | [`DocumentData`](#documentdata) |
 
 #### Returns
 
@@ -3162,7 +4237,7 @@ function where(
 | Parameter | Type |
 | :------ | :------ |
 | `field` | `string` \| [`FieldPath`](#fieldpath) |
-| `op` | `WhereFilterOp` |
+| `op` | [`WhereFilterOp`](#wherefilterop) |
 | `value` | `unknown` |
 
 #### Returns
@@ -3186,13 +4261,13 @@ function withConverter<AppModel, DbModel>(ref: DocumentReference<DocumentData>,
 | Type Parameter | Default type |
 | :------ | :------ |
 | `AppModel` | - |
-| `DbModel` *extends* `DocumentData` | `DocumentData` |
+| `DbModel` *extends* [`DocumentData`](#documentdata) | [`DocumentData`](#documentdata) |
 
 ##### Parameters
 
 | Parameter | Type |
 | :------ | :------ |
-| `ref` | [`DocumentReference`](#documentreference)\<`DocumentData`\> |
+| `ref` | [`DocumentReference`](#documentreference)\<[`DocumentData`](#documentdata)\> |
 | `converter` | [`FirestoreDataConverter`](#firestoredataconverter)\<`AppModel`, `DbModel`\> |
 
 ##### Returns
@@ -3214,7 +4289,7 @@ function withConverter(ref: DocumentReference<unknown>, converter: null): Docume
 
 ##### Returns
 
-[`DocumentReference`](#documentreference)\<`DocumentData`\>
+[`DocumentReference`](#documentreference)\<[`DocumentData`](#documentdata)\>
 
 #### Call Signature
 
@@ -3227,13 +4302,13 @@ function withConverter<AppModel, DbModel>(ref: CollectionReference<DocumentData>
 | Type Parameter | Default type |
 | :------ | :------ |
 | `AppModel` | - |
-| `DbModel` *extends* `DocumentData` | `DocumentData` |
+| `DbModel` *extends* [`DocumentData`](#documentdata) | [`DocumentData`](#documentdata) |
 
 ##### Parameters
 
 | Parameter | Type |
 | :------ | :------ |
-| `ref` | [`CollectionReference`](#collectionreference)\<`DocumentData`\> |
+| `ref` | [`CollectionReference`](#collectionreference)\<[`DocumentData`](#documentdata)\> |
 | `converter` | [`FirestoreDataConverter`](#firestoredataconverter)\<`AppModel`, `DbModel`\> |
 
 ##### Returns
@@ -3255,7 +4330,7 @@ function withConverter(ref: CollectionReference<unknown>, converter: null): Coll
 
 ##### Returns
 
-[`CollectionReference`](#collectionreference)\<`DocumentData`\>
+[`CollectionReference`](#collectionreference)\<[`DocumentData`](#documentdata)\>
 
 #### Call Signature
 
@@ -3268,13 +4343,13 @@ function withConverter<AppModel, DbModel>(q: Query<DocumentData>, converter: Fir
 | Type Parameter | Default type |
 | :------ | :------ |
 | `AppModel` | - |
-| `DbModel` *extends* `DocumentData` | `DocumentData` |
+| `DbModel` *extends* [`DocumentData`](#documentdata) | [`DocumentData`](#documentdata) |
 
 ##### Parameters
 
 | Parameter | Type |
 | :------ | :------ |
-| `q` | [`Query`](#query)\<`DocumentData`\> |
+| `q` | [`Query`](#query)\<[`DocumentData`](#documentdata)\> |
 | `converter` | [`FirestoreDataConverter`](#firestoredataconverter)\<`AppModel`, `DbModel`\> |
 
 ##### Returns
@@ -3296,7 +4371,7 @@ function withConverter(q: Query<unknown>, converter: null): Query<DocumentData>;
 
 ##### Returns
 
-[`Query`](#query)\<`DocumentData`\>
+[`Query`](#query)\<[`DocumentData`](#documentdata)\>
 
 ***
 
@@ -3305,7 +4380,7 @@ function withConverter(q: Query<unknown>, converter: null): Query<DocumentData>;
 ### writeBatch()
 
 ```ts
-function writeBatch(db: Firestore): ChainWriteBatch;
+function writeBatch(db: Firestore): WriteBatch;
 ```
 
 #### Parameters
@@ -3316,84 +4391,4 @@ function writeBatch(db: Firestore): ChainWriteBatch;
 
 #### Returns
 
-`ChainWriteBatch`
-
-## References
-
-<a id="documentdata"></a>
-
-### DocumentData
-
-Renames and re-exports [AuthState](#authstate)
-
-***
-
-<a id="fieldvalue"></a>
-
-### FieldValue
-
-Renames and re-exports [AuthState](#authstate)
-
-***
-
-<a id="fieldvaluesentinel"></a>
-
-### FieldValueSentinel
-
-Renames and re-exports [AuthState](#authstate)
-
-***
-
-<a id="lintresult"></a>
-
-### LintResult
-
-Renames and re-exports [AuthState](#authstate)
-
-***
-
-<a id="orderdirection"></a>
-
-### OrderDirection
-
-Renames and re-exports [AuthState](#authstate)
-
-***
-
-<a id="sandbox"></a>
-
-### Sandbox
-
-Renames and re-exports [AuthState](#authstate)
-
-***
-
-<a id="sandboxcontext"></a>
-
-### SandboxContext
-
-Renames and re-exports [AuthState](#authstate)
-
-***
-
-<a id="sandboxerror"></a>
-
-### SandboxError
-
-Renames and re-exports [AuthState](#authstate)
-
-***
-
-<a id="timestamp"></a>
-
-### Timestamp
-
-Renames and re-exports [AuthState](#authstate)
-
-***
-
-<a id="wherefilterop"></a>
-
-### WhereFilterOp
-
-Renames and re-exports [AuthState](#authstate)
+[`WriteBatch`](pyric-admin-firestore-reference-api.md#writebatch)