@pyric/cli 0.1.0-alpha.20 → 0.1.0-alpha.21

package/dist/serve/site-ui/docs/pyric-sandbox-reference-api.md

@@ -67,6 +67,7 @@ factories; consumers don't construct it directly.
 new SandboxContextImpl(
    sandbox: Sandbox,
    auth: {
+  tenant?: string;
   token?: Record<string, unknown>;
   uid: string;
 },
@@ -78,7 +79,8 @@ new SandboxContextImpl(
 | Parameter | Type |
 | :------ | :------ |
 | `sandbox` | [`Sandbox`](pyric-firestore-reference-api.md#sandbox) |
-| `auth` | \{ `token?`: `Record`\<`string`, `unknown`\>; `uid`: `string`; \} |
+| `auth` | \{ `tenant?`: `string`; `token?`: `Record`\<`string`, `unknown`\>; `uid`: `string`; \} |
+| `auth.tenant?` | `string` |
 | `auth.token?` | `Record`\<`string`, `unknown`\> |
 | `auth.uid?` | `string` |
 | `operationContext?` | [`OperationContext`](#operationcontext-2) |
@@ -91,7 +93,8 @@ new SandboxContextImpl(
 
 | 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. |
+| <a id="auth"></a> `auth` | `readonly` | \{ `tenant?`: `string`; `token?`: `Record`\<`string`, `unknown`\>; `uid`: `string`; \} | The identity rules evaluate under for operations through this context. |
+| `auth.tenant?` | `public` | `string` | - |
 | `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. |
@@ -105,6 +108,7 @@ new SandboxContextImpl(
 
 ```ts
 withAuth(auth: {
+  tenant?: string;
   token?: Record<string, unknown>;
   uid: string;
 }): SandboxContext;
@@ -118,7 +122,8 @@ optional plan identity.
 
 | Parameter | Type |
 | :------ | :------ |
-| `auth` | \{ `token?`: `Record`\<`string`, `unknown`\>; `uid`: `string`; \} |
+| `auth` | \{ `tenant?`: `string`; `token?`: `Record`\<`string`, `unknown`\>; `uid`: `string`; \} |
+| `auth.tenant?` | `string` |
 | `auth.token?` | `Record`\<`string`, `unknown`\> |
 | `auth.uid` | `string` |
 
@@ -289,7 +294,8 @@ reference traces.
 
 | Property | Modifier | Type | Description |
 | :------ | :------ | :------ | :------ |
-| <a id="auth-1"></a> `auth?` | `public` | \{ `token?`: `Record`\<`string`, `unknown`\>; `uid`: `string`; \} | Auth identity that was active when the denial fired. |
+| <a id="auth-1"></a> `auth?` | `public` | \{ `tenant?`: `string`; `token?`: `Record`\<`string`, `unknown`\>; `uid`: `string`; \} | Auth identity that was active when the denial fired. |
+| `auth.tenant?` | `public` | `string` | - |
 | `auth.token?` | `public` | `Record`\<`string`, `unknown`\> | - |
 | `auth.uid` | `public` | `string` | - |
 | <a id="failedfields"></a> `failedFields?` | `public` | `string`[] | Field paths in `request.resource.data` that the rule referenced and that failed. |
@@ -331,7 +337,8 @@ frame either way.
 
 | Property | Type |
 | :------ | :------ |
-| <a id="auth-2"></a> `auth?` | \{ `token?`: `Record`\<`string`, `unknown`\>; `uid`: `string`; \} |
+| <a id="auth-2"></a> `auth?` | \{ `tenant?`: `string`; `token?`: `Record`\<`string`, `unknown`\>; `uid`: `string`; \} |
+| `auth.tenant?` | `string` |
 | `auth.token?` | `Record`\<`string`, `unknown`\> |
 | `auth.uid` | `string` |
 | <a id="code"></a> `code` | `"permission-denied"` |
@@ -380,7 +387,8 @@ on the errored phase only.
 | Property | Type | Description |
 | :------ | :------ | :------ |
 | <a id="at"></a> `at` | `number` | - |
-| <a id="auth-3"></a> `auth` | \{ `token?`: `Record`\<`string`, `unknown`\>; `uid`: `string`; \} | - |
+| <a id="auth-3"></a> `auth` | \{ `tenant?`: `string`; `token?`: `Record`\<`string`, `unknown`\>; `uid`: `string`; \} | - |
+| `auth.tenant?` | `string` | - |
 | `auth.token?` | `Record`\<`string`, `unknown`\> | - |
 | `auth.uid` | `string` | - |
 | <a id="error"></a> `error?` | \{ `code`: `"permission-denied"`; `message`: `string`; `reasons?`: `string`[]; \} | Populated on `listener_errored` only. |
@@ -414,7 +422,8 @@ 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](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. |
+| <a id="currentuser"></a> `currentUser` | `public` | \{ `tenant?`: `string`; `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.tenant?` | `public` | `string` | - |
 | `currentUser.token?` | `public` | `Record`\<`string`, `unknown`\> | - |
 | `currentUser.uid` | `public` | `string` | - |
 
@@ -665,6 +674,7 @@ a service this one lacks).
 
 ```ts
 onCurrentUserChanged(cb: (user: {
+  tenant?: string;
   token?: Record<string, unknown>;
   uid: string;
 }) => void): () => void;
@@ -686,7 +696,7 @@ their errors.
 
 | Parameter | Type |
 | :------ | :------ |
-| `cb` | (`user`: \{ `token?`: `Record`\<`string`, `unknown`\>; `uid`: `string`; \}) => `void` |
+| `cb` | (`user`: \{ `tenant?`: `string`; `token?`: `Record`\<`string`, `unknown`\>; `uid`: `string`; \}) => `void` |
 
 ###### Returns
 
@@ -941,6 +951,7 @@ paths to data. Future services will add their own keys.
 
 ```ts
 withAuth(auth: {
+  tenant?: string;
   token?: Record<string, unknown>;
   uid: string;
 }): SandboxContext;
@@ -960,7 +971,8 @@ unambiguous.
 
 | Parameter | Type |
 | :------ | :------ |
-| `auth` | \{ `token?`: `Record`\<`string`, `unknown`\>; `uid`: `string`; \} |
+| `auth` | \{ `tenant?`: `string`; `token?`: `Record`\<`string`, `unknown`\>; `uid`: `string`; \} |
+| `auth.tenant?` | `string` |
 | `auth.token?` | `Record`\<`string`, `unknown`\> |
 | `auth.uid` | `string` |
 
@@ -1009,7 +1021,8 @@ as a user, while an app or agent may use an admin lens.
 | Property | Modifier | Type |
 | :------ | :------ | :------ |
 | <a id="at-1"></a> `at` | `readonly` | `number` |
-| <a id="auth-4"></a> `auth` | `readonly` | \{ `token?`: `Record`\<`string`, `unknown`\>; `uid`: `string`; \} |
+| <a id="auth-4"></a> `auth` | `readonly` | \{ `tenant?`: `string`; `token?`: `Record`\<`string`, `unknown`\>; `uid`: `string`; \} |
+| `auth.tenant?` | `public` | `string` |
 | `auth.token?` | `public` | `Record`\<`string`, `unknown`\> |
 | `auth.uid` | `public` | `string` |
 | <a id="context"></a> `context` | `readonly` | [`OperationContext`](#operationcontext-2) |
@@ -1017,7 +1030,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` | `"unsupported"` \| `"error"` \| `"allow"` \| `"deny"` \| `"not-applicable"` |
+| <a id="result"></a> `result?` | `readonly` | `"allow"` \| `"deny"` \| `"unsupported"` \| `"error"` \| `"not-applicable"` |
 | <a id="rules-1"></a> `rules` | `readonly` | [`RulesDisposition`](#rulesdisposition-3) |
 | <a id="service-1"></a> `service` | `readonly` | [`EventService`](#eventservice) |
 
@@ -1339,10 +1352,11 @@ 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](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. |
+| <a id="currentuser-1"></a> `currentUser` | `public` | \{ `tenant?`: `string`; `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.tenant?` | `public` | `string` | - |
 | `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"). |
+| <a id="serveurl"></a> `serveUrl` | `readonly` | `string` | Base URL of the `pyric sandbox` this handle is attached to (used in error guidance: "open <serveUrl> in a browser and retry"). |
 
 #### Methods
 
@@ -1591,6 +1605,7 @@ a service this one lacks).
 
 ```ts
 onCurrentUserChanged(cb: (user: {
+  tenant?: string;
   token?: Record<string, unknown>;
   uid: string;
 }) => void): () => void;
@@ -1612,7 +1627,7 @@ their errors.
 
 | Parameter | Type |
 | :------ | :------ |
-| `cb` | (`user`: \{ `token?`: `Record`\<`string`, `unknown`\>; `uid`: `string`; \}) => `void` |
+| `cb` | (`user`: \{ `tenant?`: `string`; `token?`: `Record`\<`string`, `unknown`\>; `uid`: `string`; \}) => `void` |
 
 ###### Returns
 
@@ -1867,6 +1882,7 @@ paths to data. Future services will add their own keys.
 
 ```ts
 withAuth(auth: {
+  tenant?: string;
   token?: Record<string, unknown>;
   uid: string;
 }): SandboxContext;
@@ -1886,7 +1902,8 @@ unambiguous.
 
 | Parameter | Type |
 | :------ | :------ |
-| `auth` | \{ `token?`: `Record`\<`string`, `unknown`\>; `uid`: `string`; \} |
+| `auth` | \{ `tenant?`: `string`; `token?`: `Record`\<`string`, `unknown`\>; `uid`: `string`; \} |
+| `auth.tenant?` | `string` |
 | `auth.token?` | `Record`\<`string`, `unknown`\> |
 | `auth.uid` | `string` |
 
@@ -1999,7 +2016,7 @@ Options accepted by the ambient remote-sandbox factory.
 
 | Property | Type | Description |
 | :------ | :------ | :------ |
-| <a id="url"></a> `url?` | `string` | Explicit `pyric dev` base URL (from `PYRIC_SANDBOX=remote:<url>`). When omitted the factory discovers the running host itself (the `.pyric/serve.json` locator protocol). |
+| <a id="url"></a> `url?` | `string` | Explicit `pyric sandbox` base URL (from `PYRIC_SANDBOX=remote:<url>`). When omitted the factory discovers the running host itself (the `.pyric/serve.json` locator protocol). |
 
 ***
 
@@ -2067,7 +2084,8 @@ traffic-monitor-decision.md for the field-by-field rationale.
 | Property | Type | Description |
 | :------ | :------ | :------ |
 | <a id="at-2"></a> `at` | `number` | Wall-clock at op start, ms since epoch. |
-| <a id="auth-5"></a> `auth` | \{ `token?`: `Record`\<`string`, `unknown`\>; `uid`: `string`; \} | - |
+| <a id="auth-5"></a> `auth` | \{ `tenant?`: `string`; `token?`: `Record`\<`string`, `unknown`\>; `uid`: `string`; \} | - |
+| `auth.tenant?` | `string` | - |
 | `auth.token?` | `Record`\<`string`, `unknown`\> | - |
 | `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. |
@@ -2092,7 +2110,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` | `"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="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="rulesdisposition"></a> `rulesDisposition?` | [`RulesDisposition`](#rulesdisposition-3) | 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` | - |
@@ -2113,7 +2131,8 @@ these service adapters instead of filtering Firestore-only `write` events.
 | Property | Type |
 | :------ | :------ |
 | <a id="at-3"></a> `at` | `number` |
-| <a id="auth-6"></a> `auth` | \{ `token?`: `Record`\<`string`, `unknown`\>; `uid`: `string`; \} |
+| <a id="auth-6"></a> `auth` | \{ `tenant?`: `string`; `token?`: `Record`\<`string`, `unknown`\>; `uid`: `string`; \} |
+| `auth.tenant?` | `string` |
 | `auth.token?` | `Record`\<`string`, `unknown`\> |
 | `auth.uid` | `string` |
 | <a id="data"></a> `data?` | `unknown` |
@@ -2159,7 +2178,8 @@ service listeners the same debuggable surface.
 | Property | Type |
 | :------ | :------ |
 | <a id="at-4"></a> `at` | `number` |
-| <a id="auth-7"></a> `auth` | \{ `token?`: `Record`\<`string`, `unknown`\>; `uid`: `string`; \} |
+| <a id="auth-7"></a> `auth` | \{ `tenant?`: `string`; `token?`: `Record`\<`string`, `unknown`\>; `uid`: `string`; \} |
+| `auth.tenant?` | `string` |
 | `auth.token?` | `Record`\<`string`, `unknown`\> |
 | `auth.uid` | `string` |
 | <a id="detail-2"></a> `detail?` | `Record`\<`string`, `unknown`\> |
@@ -2173,7 +2193,7 @@ service listeners the same debuggable surface.
 | <a id="phase"></a> `phase` | `"attach"` \| `"detach"` \| `"delivery"` \| `"suppressed"` \| `"errored"` |
 | <a id="reason"></a> `reason?` | `string` |
 | <a id="reasons-3"></a> `reasons?` | `string`[] |
-| <a id="result-2"></a> `result?` | `"unsupported"` \| `"error"` \| `"allow"` \| `"deny"` |
+| <a id="result-2"></a> `result?` | `"allow"` \| `"deny"` \| `"unsupported"` \| `"error"` |
 | <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` |
@@ -2216,7 +2236,8 @@ their state is a Firestore document.
 | Property | Type | Description |
 | :------ | :------ | :------ |
 | <a id="at-5"></a> `at` | `number` | - |
-| <a id="auth-8"></a> `auth` | \{ `token?`: `Record`\<`string`, `unknown`\>; `uid`: `string`; \} | - |
+| <a id="auth-8"></a> `auth` | \{ `tenant?`: `string`; `token?`: `Record`\<`string`, `unknown`\>; `uid`: `string`; \} | - |
+| `auth.tenant?` | `string` | - |
 | `auth.token?` | `Record`\<`string`, `unknown`\> | - |
 | `auth.uid` | `string` | - |
 | <a id="detail-3"></a> `detail?` | `Record`\<`string`, `unknown`\> | - |
@@ -2239,7 +2260,7 @@ their state is a Firestore document.
 | <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="result-3"></a> `result` | `"allow"` \| `"deny"` \| `"unsupported"` \| `"error"` \| `"not-applicable"` | - |
 | <a id="rules-3"></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` | - |
@@ -2288,7 +2309,8 @@ Canonical non-rules operational failure.
 | Property | Type |
 | :------ | :------ |
 | <a id="at-6"></a> `at` | `number` |
-| <a id="auth-9"></a> `auth` | \{ `token?`: `Record`\<`string`, `unknown`\>; `uid`: `string`; \} |
+| <a id="auth-9"></a> `auth` | \{ `tenant?`: `string`; `token?`: `Record`\<`string`, `unknown`\>; `uid`: `string`; \} |
+| `auth.tenant?` | `string` |
 | `auth.token?` | `Record`\<`string`, `unknown`\> |
 | `auth.uid` | `string` |
 | <a id="detail-4"></a> `detail?` | `Record`\<`string`, `unknown`\> |
@@ -2359,14 +2381,15 @@ 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-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). |
+| <a id="auth-10"></a> `auth` | \{ `tenant?`: `string`; `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.tenant?` | `string` | - |
 | `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. |
 | <a id="detail-5"></a> `detail?` | `Record`\<`string`, `unknown`\> | Free-form, service-specific extras a consumer may surface without re-deriving (e.g. storage `{ size, contentType }`, rtdb `{ committed }` for a transaction). Kept loose on purpose — it's a display hint, not a contract. |
 | <a id="id-7"></a> `id` | `string` | - |
 | <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="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` | `response_blocked` | `model_substituted` 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` | `"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.) |
 
@@ -2414,7 +2437,8 @@ scenario produces large snapshots.
 | :------ | :------ | :------ |
 | <a id="addedcount"></a> `addedCount` | `number` | - |
 | <a id="at-9"></a> `at` | `number` | - |
-| <a id="auth-11"></a> `auth` | \{ `token?`: `Record`\<`string`, `unknown`\>; `uid`: `string`; \} | - |
+| <a id="auth-11"></a> `auth` | \{ `tenant?`: `string`; `token?`: `Record`\<`string`, `unknown`\>; `uid`: `string`; \} | - |
+| `auth.tenant?` | `string` | - |
 | `auth.token?` | `Record`\<`string`, `unknown`\> | - |
 | `auth.uid` | `string` | - |
 | <a id="id-9"></a> `id` | `string` | - |
@@ -2456,7 +2480,8 @@ scenario surfaces them.
 
 | Property | Type |
 | :------ | :------ |
-| <a id="auth-12"></a> `auth?` | \{ `token?`: `Record`\<`string`, `unknown`\>; `uid`: `string`; \} |
+| <a id="auth-12"></a> `auth?` | \{ `tenant?`: `string`; `token?`: `Record`\<`string`, `unknown`\>; `uid`: `string`; \} |
+| `auth.tenant?` | `string` |
 | `auth.token?` | `Record`\<`string`, `unknown`\> |
 | `auth.uid` | `string` |
 | <a id="code-1"></a> `code` | `"permission-denied"` |
@@ -2490,7 +2515,8 @@ them.
 | Property | Type | Description |
 | :------ | :------ | :------ |
 | <a id="at-10"></a> `at` | `number` | - |
-| <a id="auth-13"></a> `auth` | \{ `token?`: `Record`\<`string`, `unknown`\>; `uid`: `string`; \} | - |
+| <a id="auth-13"></a> `auth` | \{ `tenant?`: `string`; `token?`: `Record`\<`string`, `unknown`\>; `uid`: `string`; \} | - |
+| `auth.tenant?` | `string` | - |
 | `auth.token?` | `Record`\<`string`, `unknown`\> | - |
 | `auth.uid` | `string` | - |
 | <a id="id-10"></a> `id` | `string` | - |
@@ -2526,7 +2552,7 @@ the defaults provide a ready-to-use configuration for browser environments.
 
 Minimal web-storage-like contract the session persistence controller
 reads/writes. Matches the `localStorage` / `sessionStorage` browser
-API subset that `pyric dev`'s `SessionStore` already uses, so
+API subset that `pyric sandbox`'s `SessionStore` already uses, so
 browsers pass real storages and tests pass in-memory Map-backed fakes.
 
 Why the minimal subset (get/set/remove) instead of the full
@@ -2618,7 +2644,8 @@ sentinel/auto-id capture lands.
 | Property | Type | Description |
 | :------ | :------ | :------ |
 | <a id="at-11"></a> `at` | `number` | - |
-| <a id="auth-14"></a> `auth` | \{ `token?`: `Record`\<`string`, `unknown`\>; `uid`: `string`; \} | - |
+| <a id="auth-14"></a> `auth` | \{ `tenant?`: `string`; `token?`: `Record`\<`string`, `unknown`\>; `uid`: `string`; \} | - |
+| `auth.tenant?` | `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). |
@@ -2650,6 +2677,7 @@ type AuthLens =
 }
   | {
   mode: "as";
+  tenant?: string;
   token?: Record<string, unknown>;
   uid: string;
 }
@@ -3277,6 +3305,66 @@ than into process-local state.
 
 ***
 
+<a id="normalizeauthstate"></a>
+
+### normalizeAuthState()
+
+```ts
+function normalizeAuthState(auth: {
+  tenant?: string;
+  token?: Record<string, unknown>;
+  uid: string;
+}): {
+  tenant?: string;
+  token?: Record<string, unknown>;
+  uid: string;
+};
+```
+
+Normalize AuthState during SandboxContextImpl context assembly.
+Automatically projects top-level `tenant` into `token.firebase.tenant`
+while preserving custom claims and explicit nested token overrides.
+Never mutates original input.
+
+#### Parameters
+
+| Parameter | Type |
+| :------ | :------ |
+| `auth` | \{ `tenant?`: `string`; `token?`: `Record`\<`string`, `unknown`\>; `uid`: `string`; \} |
+| `auth.tenant?` | `string` |
+| `auth.token?` | `Record`\<`string`, `unknown`\> |
+| `auth.uid` | `string` |
+
+#### Returns
+
+```ts
+{
+  tenant?: string;
+  token?: Record<string, unknown>;
+  uid: string;
+}
+```
+
+##### tenant?
+
+```ts
+optional tenant: string;
+```
+
+##### token?
+
+```ts
+optional token: Record<string, unknown>;
+```
+
+##### uid
+
+```ts
+uid: string;
+```
+
+***
+
 <a id="operationcontextfor"></a>
 
 ### operationContextFor()
@@ -3528,6 +3616,35 @@ Project either traffic event family into the canonical record.
 
 [`OperationRecord`](#operationrecord)
 
+***
+
+<a id="validateauthstate"></a>
+
+### validateAuthState()
+
+```ts
+function validateAuthState(auth: unknown): asserts auth is { tenant?: string; token?: Record<string, unknown>; uid: string };
+```
+
+Reject `undefined` and other clearly-malformed inputs at the
+`withAuth` call site. `null` is valid (anonymous);
+`{ uid: 'someUid' }` is valid; everything else throws so the
+mistake surfaces at the boundary instead of leaking into rule
+eval as a confusing denial.
+
+Shared between `Sandbox.withAuth` and `SandboxContext.withAuth`
+so both entries enforce the same validation.
+
+#### Parameters
+
+| Parameter | Type |
+| :------ | :------ |
+| `auth` | `unknown` |
+
+#### Returns
+
+`asserts auth is { tenant?: string; token?: Record<string, unknown>; uid: string }`
+
 ## References
 
 <a id="authstate"></a>