@pyric/cli 0.1.0-alpha.9

package/dist/serve/docs-ui/docs/pyric-sandbox-reference-error-codes.md

@@ -0,0 +1,118 @@
+# `SandboxError` codes
+
+Every error the sandbox raises is a `SandboxError` carrying a `code`. Catch with `instanceof SandboxError`, switch on `code`.
+
+```ts
+import { SandboxError } from 'pyric/sandbox';
+
+try {
+  await aliceDb.collection('admin').doc('x').set({ value: 1 });
+} catch (e) {
+  if (e instanceof SandboxError && e.code === 'permission-denied') {
+    console.log('Rules said no:', e.denialContext);
+  }
+}
+```
+
+## Firebase-aligned codes
+
+These match Firebase / gRPC conventions so production-shaped `catch (e) { if (e.code === 'permission-denied') }` code keeps working.
+
+### `'invalid-argument'`
+
+Caller passed something the API does not accept. Common cases:
+
+- `sandbox.withAuth(undefined)`: say `withAuth(null)` explicitly.
+- `sandbox.withAuth({ uid: '' })`: UID must be non-empty.
+- `sandbox.withAuth({ uid: 'x', token: 'oops' })`: `token` must be an object.
+- Hand-rolled `Sandbox` handle passed to a service factory (via `getInternalEnv` from `/internal`).
+
+Errors of this kind carry `remediation` text explaining the fix.
+
+### `'permission-denied'`
+
+Rules denied the operation. The `denialContext` field is populated with:
+
+- `auth`: the identity that was active.
+- `reasons`: the simulator's debug messages (one per evaluated rule).
+- `request`: the eval-time `request.*` shape (method, path, resource data).
+- `resource`: the eval-time `resource.*` (existing doc, exists flag).
+- `rule` (best-effort): line and expression source.
+
+See the [`SandboxEvent` reference](../pyric-sandbox-reference-sandbox-event/). `DenialContext` mirrors the `kind: 'request' && result: 'deny'` event shape.
+
+### `'not-found'`
+
+Operation referenced a document that does not exist:
+
+- `update` against a non-existent document.
+- `transaction` reading a path that's gone.
+
+### `'already-exists'`
+
+`create` against a path that already has a document. (Plain `set` overwrites; `create` insists on absence.)
+
+### `'failed-precondition'`
+
+The operation could not run in the current state, for reasons other than missing/extra docs:
+
+- Read-after-write violation inside a transaction.
+- Ambiguous post-delete reference.
+
+### `'aborted'`
+
+A transaction was aborted, typically because its callback threw. The thrown error propagates synchronously; the event log marks the transaction as aborted and excludes it from undo.
+
+### `'unavailable'`
+
+Reserved. Not currently emitted; there is no network stream to drop. May appear if a future service has a transport.
+
+## Sandbox-specific codes
+
+These don't have a production analog. They exist so callers can distinguish "the sandbox doesn't model this" from "your rule is wrong" without parsing messages.
+
+### `'unimplemented'`
+
+The sandbox doesn't yet model a feature your rule uses. Returned from the simulator's `UnsupportedError` channel surfaced through this code. For most agent workflows the right response is to route the offending case to the live Firebase Rules Test API; see [`pyric/rules`](../pyric-rules-explanation-simulator-vs-rules-test-api/).
+
+### `'not-seeded'`
+
+An operation was issued before `LocalEnvironment.seed` provided rules. The default state is empty, with no rules. Most operations will deny under default-deny semantics, but some surfaces (admin reads, listing operations) raise this code instead so it's obvious the sandbox hasn't been initialised.
+
+### `'rules-not-loaded'`
+
+Similar to `'not-seeded'`, but specifically signals that rules haven't been deployed yet. Use `LocalEnvironment.deployRules(source)` or seed with `rules` before issuing operations that need to evaluate.
+
+## Constructing errors yourself
+
+Two forms:
+
+```ts
+// Positional — backwards-compatible.
+throw new SandboxError('permission-denied', 'Denied: …', denialContext);
+
+// Options bag — use when attaching remediation.
+throw new SandboxError({
+  code: 'invalid-argument',
+  message: 'withAuth() needs an explicit AuthState.',
+  remediation: 'For anonymous: withAuth(null). For users: withAuth({ uid: "…" }).',
+});
+```
+
+When `remediation` is set, it is appended to the error's `.message` with a blank-line separator so consumers that surface `.message` (logs, UIs) see the guidance without an API change. The structured form is also available on the instance as `error.remediation`.
+
+## What carries `denialContext`
+
+Only `'permission-denied'` errors. Every other code has `denialContext: undefined`. Consumers branching on `denialContext` should check the code first.
+
+The exact field set depends on the operation:
+
+| Operation | `request` | `resource` |
+|---|---|---|
+| `get` | method=`'get'`, path | data + exists for the existing doc |
+| `list` | method=`'list'`, path | none (collection ops; resource not modelled per-doc) |
+| `create` | method=`'create'`, path, resourceData | data=`null`, exists=`false` |
+| `update` | method=`'update'`, path, resourceData | data + exists for the existing doc |
+| `delete` | method=`'delete'`, path | data + exists for the existing doc |
+
+`resourceData` reflects the post-sentinel-resolution payload: what the rule actually saw on `request.resource.data`.

package/dist/serve/docs-ui/docs/pyric-sandbox-reference-internal-protocol/index.html

@@ -0,0 +1,72 @@
+<!DOCTYPE html><html lang="en"> <head><meta charset="UTF-8"><meta name="viewport" content="width=device-width, initial-scale=1.0"><title>The /internal adapter protocol · Pyric Studio</title><link rel="preconnect" href="https://fonts.googleapis.com"><link rel="preconnect" href="https://fonts.gstatic.com" crossorigin><link href="https://fonts.googleapis.com/css2?family=Inter:wght@300;400;500;600;700&family=JetBrains+Mono:wght@400;500;700&display=swap" rel="stylesheet"><link rel="stylesheet" href="/__pyric/ui/_astro/_slug_.CQYSemvw.css"></head> <body>  <header class="studio__bar"> <div class="studio__bar-inner"> <a class="studio__brand" href="/__pyric/ui/" aria-label="Pyric Studio">Pyric</a> <nav class="studio__nav" aria-label="Studio tabs"> <a class="studio__nav-tab" href="/__pyric/ui/"> Home </a><a class="studio__nav-tab" href="/__pyric/ui/firestore"> Firestore </a><a class="studio__nav-tab" href="/__pyric/ui/auth"> Auth </a><a class="studio__nav-tab" href="/__pyric/ui/rtdb"> RTDB </a><a class="studio__nav-tab" href="/__pyric/ui/storage"> Storage </a><a class="studio__nav-tab" href="/__pyric/ui/traffic"> Traffic </a><a class="studio__nav-tab" href="/__pyric/ui/settings"> Settings </a><a class="studio__nav-tab" href="/__pyric/ui/docs" aria-current="page"> Docs </a> </nav> </div> </header> <div class="docs-shell">  <details class="docs-nav-drawer"> <summary>Navigate</summary> <nav class="docs-nav" aria-label="Documentation"> <div class="docs-search" data-index-url="/__pyric/ui/docs/index.json"> <div class="docs-search-field"> <svg class="docs-search-icon" viewBox="0 0 16 16" width="14" height="14" aria-hidden="true"> <path d="M11.5 11.5 15 15M13 7A6 6 0 1 1 1 7a6 6 0 0 1 12 0Z" fill="none" stroke="currentColor" stroke-width="1.4" stroke-linecap="round"></path> </svg> <input type="text" class="docs-search-input" placeholder="Search docs" aria-label="Search docs" autocomplete="off" spellcheck="false"> <kbd class="docs-search-kbd">⌘K</kbd> </div> <ul class="docs-search-results" hidden></ul> </div> <script type="module">let i=null;function d(t){return i||(i=fetch(t).then(e=>e.json())),i}function l(t,e){return t.title.toLowerCase().includes(e)||t.excerpt.toLowerCase().includes(e)?!0:t.headings.some(r=>r.text.toLowerCase().includes(e))}function u(t,e,r){if(e.innerHTML="",t.length===0){e.hidden=!1;{const n=document.createElement("li");n.className="docs-search-empty",n.textContent="No matches",e.appendChild(n)}return}e.hidden=!1;for(const n of t.slice(0,8)){const s=document.createElement("li"),c=document.createElement("a");c.href=n.path;const o=document.createElement("span");o.className="docs-search-result-title",o.textContent=n.title;const a=document.createElement("span");a.className="docs-search-result-meta",a.textContent=[n.group,n.section].filter(Boolean).join(" / "),c.append(o,a),s.appendChild(c),e.appendChild(s)}}document.querySelectorAll(".docs-search").forEach(t=>{const e=t.dataset.indexUrl,r=t.querySelector(".docs-search-input"),n=t.querySelector(".docs-search-results");r.addEventListener("input",async()=>{const s=r.value.trim().toLowerCase();if(!s){n.hidden=!0,n.innerHTML="";return}const{pages:c}=await d(e);r.value.trim().toLowerCase()===s&&u(c.filter(o=>l(o,s)),n)}),r.addEventListener("focus",()=>{d(e),n.childElementCount>0&&(n.hidden=!1)}),r.addEventListener("keydown",s=>{s.key==="Escape"&&(r.value="",n.hidden=!0,n.innerHTML="",r.blur())}),r.addEventListener("blur",()=>{window.setTimeout(()=>{n.hidden=!0},150)})});document.addEventListener("keydown",t=>{if(!(t.metaKey||t.ctrlKey)||t.key.toLowerCase()!=="k")return;const e=[...document.querySelectorAll(".docs-search-input")].find(r=>r.offsetParent!==null);e&&(t.preventDefault(),e.focus(),e.select())});</script> <a class="docs-nav-toplink" href="/__pyric/ui/docs/overview/"> Overview </a><details class="docs-nav-group"> <summary>Run locally</summary> <div class="docs-nav-group-body"> <div class="docs-nav-section">  <ul> <li> <a href="/__pyric/ui/docs/start-building/"> Quickstart </a> </li><li> <a href="/__pyric/ui/docs/how-the-swap-works/"> How the swap works </a> </li><li> <a href="/__pyric/ui/docs/set-up-your-agent/"> Connect an agent </a> </li><li> <a href="/__pyric/ui/docs/test-in-node/"> Test in Node </a> </li> </ul> </div> </div> </details><details class="docs-nav-group"> <summary>Develop with Firebase APIs</summary> <div class="docs-nav-group-body"> <div class="docs-nav-section">  <ul> <li> <a href="/__pyric/ui/docs/sign-in-and-manage-users/"> Sign in and manage users </a> </li><li> <a href="/__pyric/ui/docs/store-and-query-data/"> Store and query data </a> </li><li> <a href="/__pyric/ui/docs/sync-realtime-data/"> Sync realtime data </a> </li><li> <a href="/__pyric/ui/docs/store-files/"> Store files </a> </li><li> <a href="/__pyric/ui/docs/receive-messages/"> Receive messages </a> </li><li> <a href="/__pyric/ui/docs/run-ai-logic-locally/"> Run AI Logic locally </a> </li><li> <a href="/__pyric/ui/docs/pyric-cli-how-to-run-rtdb-onvaluecreated/"> Run an RTDB function locally </a> </li><li> <a href="/__pyric/ui/docs/which-data-service/"> Which data service? </a> </li> </ul> </div> </div> </details><details class="docs-nav-group"> <summary>Inspect and correct</summary> <div class="docs-nav-group-body"> <div class="docs-nav-section"> <h2 class="docs-nav-heading"> Inspect the sandbox </h2> <ul> <li> <a href="/__pyric/ui/docs/see-whats-happening/"> Traffic &amp; rule verdicts </a> </li><li> <a href="/__pyric/ui/docs/read-a-denial/"> Read a denial and understand it </a> </li><li> <a href="/__pyric/ui/docs/shape-your-data/"> Seed, snapshot, replay </a> </li><li> <a href="/__pyric/ui/docs/watch-and-review/"> Review agent activity </a> </li> </ul> </div><div class="docs-nav-section"> <h2 class="docs-nav-heading"> Correct Security Rules </h2> <ul> <li> <a href="/__pyric/ui/docs/secure-it-with-rules/"> Security Rules </a> </li><li> <a href="/__pyric/ui/docs/simulate-and-lint/"> Simulate and lint before you deploy </a> </li><li> <a href="/__pyric/ui/docs/rules-patterns/"> Rules patterns </a> </li><li> <a href="/__pyric/ui/docs/rules-standard-library/"> The rules standard library </a> </li><li> <a href="/__pyric/ui/docs/rtdb-rules-in-typescript/"> RTDB rules in TypeScript </a> </li><li> <a href="/__pyric/ui/docs/firestore-rules-limits/"> Rules limits </a> </li><li> <a href="/__pyric/ui/docs/whats-possible/"> Case studies </a> </li> </ul> </div><div class="docs-nav-section"> <h2 class="docs-nav-heading"> Work with an agent </h2> <ul> <li> <a href="/__pyric/ui/docs/what-your-agent-can-do/"> Work through an agent </a> </li><li> <a href="/__pyric/ui/docs/skills/"> Agent skills </a> </li> </ul> </div> </div> </details><details class="docs-nav-group"> <summary>Verify the boundary</summary> <div class="docs-nav-group-body"> <div class="docs-nav-section">  <ul> <li> <a href="/__pyric/ui/docs/pyric-cli-how-to-verify-against-a-captured-session/"> Verify a captured session </a> </li><li> <a href="/__pyric/ui/docs/write-a-rules-test-suite/"> Write a rules test suite </a> </li><li> <a href="/__pyric/ui/docs/audit-your-rules/"> Audit rules and data </a> </li> </ul> </div> </div> </details><details class="docs-nav-group"> <summary>Ship unchanged</summary> <div class="docs-nav-group-body"> <div class="docs-nav-section">  <ul> <li> <a href="/__pyric/ui/docs/ship-to-production/"> Ship to production </a> </li><li> <a href="/__pyric/ui/docs/set-up-the-project/"> Set up the Firebase project </a> </li> </ul> </div> </div> </details><details class="docs-nav-group"> <summary>Conformance</summary> <div class="docs-nav-group-body"> <div class="docs-nav-section">  <ul> <li> <a href="/__pyric/ui/docs/how-we-know-it-matches-firebase/"> Conformance </a> </li><li> <a href="/__pyric/ui/docs/whats-experimental/"> What&#39;s experimental </a> </li><li> <a href="/__pyric/ui/docs/pyric-conformance-scores/"> Conformance scores </a> </li><li> <a href="/__pyric/ui/docs/pyric-app-compat/"> App </a> </li><li> <a href="/__pyric/ui/docs/pyric-firestore-compat/"> Firestore </a> </li><li> <a href="/__pyric/ui/docs/pyric-auth-compat/"> Auth </a> </li><li> <a href="/__pyric/ui/docs/pyric-database-compat/"> Realtime Database </a> </li><li> <a href="/__pyric/ui/docs/pyric-storage-compat/"> Storage </a> </li><li> <a href="/__pyric/ui/docs/pyric-rules-compat/"> Rules </a> </li><li> <a href="/__pyric/ui/docs/pyric-messaging-compat/"> Messaging </a> </li><li> <a href="/__pyric/ui/docs/pyric-ai-compat/"> AI Logic </a> </li><li> <a href="/__pyric/ui/docs/pyric-cli-functions-rtdb-compat/"> Functions · RTDB </a> </li> </ul> </div> </div> </details> <details class="docs-nav-group" open> <summary>Reference</summary> <div class="docs-nav-group-body"> <div class="docs-nav-section"> <ul> <li> <a href="/__pyric/ui/docs/pyric-cli/"> @pyric/cli </a> </li><li> <a href="/__pyric/ui/docs/pyric-explanation-versioning-and-compatibility/"> pyric </a> </li><li> <a href="/__pyric/ui/docs/pyric-firestore/"> pyric / firestore </a> </li><li> <a href="/__pyric/ui/docs/pyric-rules/"> pyric / rules </a> </li><li> <a href="/__pyric/ui/docs/pyric-sandbox/" aria-current="true"> pyric / sandbox </a> </li><li> <a href="/__pyric/ui/docs/pyric-storage/"> pyric / storage </a> </li><li> <a href="/__pyric/ui/docs/pyric-auth/"> pyric / auth </a> </li><li> <a href="/__pyric/ui/docs/pyric-database/"> pyric / database </a> </li><li> <a href="/__pyric/ui/docs/pyric-admin-app/"> pyric-admin / app </a> </li><li> <a href="/__pyric/ui/docs/pyric-admin-firestore/"> pyric-admin / firestore </a> </li><li> <a href="/__pyric/ui/docs/pyric-admin-auth/"> pyric-admin / auth </a> </li><li> <a href="/__pyric/ui/docs/pyric-admin-database/"> pyric-admin / database </a> </li><li> <a href="/__pyric/ui/docs/pyric-admin-storage/"> pyric-admin / storage </a> </li><li> <a href="/__pyric/ui/docs/ui/"> @pyric/ui </a> </li><li> <a href="/__pyric/ui/docs/api-reference/"> API reference </a> </li> </ul> </div> </div> </details> </nav> </details> <nav class="docs-nav" aria-label="Documentation"> <div class="docs-search" data-index-url="/__pyric/ui/docs/index.json"> <div class="docs-search-field"> <svg class="docs-search-icon" viewBox="0 0 16 16" width="14" height="14" aria-hidden="true"> <path d="M11.5 11.5 15 15M13 7A6 6 0 1 1 1 7a6 6 0 0 1 12 0Z" fill="none" stroke="currentColor" stroke-width="1.4" stroke-linecap="round"></path> </svg> <input type="text" class="docs-search-input" placeholder="Search docs" aria-label="Search docs" autocomplete="off" spellcheck="false"> <kbd class="docs-search-kbd">⌘K</kbd> </div> <ul class="docs-search-results" hidden></ul> </div>  <a class="docs-nav-toplink" href="/__pyric/ui/docs/overview/" id="nav-group-overview"> Overview </a><details class="docs-nav-group" id="nav-group-run-locally"> <summary>Run locally</summary> <div class="docs-nav-group-body"> <div class="docs-nav-section">  <ul> <li> <a href="/__pyric/ui/docs/start-building/"> Quickstart </a> </li><li> <a href="/__pyric/ui/docs/how-the-swap-works/"> How the swap works </a> </li><li> <a href="/__pyric/ui/docs/set-up-your-agent/"> Connect an agent </a> </li><li> <a href="/__pyric/ui/docs/test-in-node/"> Test in Node </a> </li> </ul> </div> </div> </details><details class="docs-nav-group" id="nav-group-develop-with-firebase-apis"> <summary>Develop with Firebase APIs</summary> <div class="docs-nav-group-body"> <div class="docs-nav-section">  <ul> <li> <a href="/__pyric/ui/docs/sign-in-and-manage-users/"> Sign in and manage users </a> </li><li> <a href="/__pyric/ui/docs/store-and-query-data/"> Store and query data </a> </li><li> <a href="/__pyric/ui/docs/sync-realtime-data/"> Sync realtime data </a> </li><li> <a href="/__pyric/ui/docs/store-files/"> Store files </a> </li><li> <a href="/__pyric/ui/docs/receive-messages/"> Receive messages </a> </li><li> <a href="/__pyric/ui/docs/run-ai-logic-locally/"> Run AI Logic locally </a> </li><li> <a href="/__pyric/ui/docs/pyric-cli-how-to-run-rtdb-onvaluecreated/"> Run an RTDB function locally </a> </li><li> <a href="/__pyric/ui/docs/which-data-service/"> Which data service? </a> </li> </ul> </div> </div> </details><details class="docs-nav-group" id="nav-group-inspect-and-correct"> <summary>Inspect and correct</summary> <div class="docs-nav-group-body"> <div class="docs-nav-section"> <h2 class="docs-nav-heading" id="nav-section-inspect-and-correct-inspect-the-sandbox"> Inspect the sandbox </h2> <ul> <li> <a href="/__pyric/ui/docs/see-whats-happening/"> Traffic &amp; rule verdicts </a> </li><li> <a href="/__pyric/ui/docs/read-a-denial/"> Read a denial and understand it </a> </li><li> <a href="/__pyric/ui/docs/shape-your-data/"> Seed, snapshot, replay </a> </li><li> <a href="/__pyric/ui/docs/watch-and-review/"> Review agent activity </a> </li> </ul> </div><div class="docs-nav-section"> <h2 class="docs-nav-heading" id="nav-section-inspect-and-correct-correct-security-rules"> Correct Security Rules </h2> <ul> <li> <a href="/__pyric/ui/docs/secure-it-with-rules/"> Security Rules </a> </li><li> <a href="/__pyric/ui/docs/simulate-and-lint/"> Simulate and lint before you deploy </a> </li><li> <a href="/__pyric/ui/docs/rules-patterns/"> Rules patterns </a> </li><li> <a href="/__pyric/ui/docs/rules-standard-library/"> The rules standard library </a> </li><li> <a href="/__pyric/ui/docs/rtdb-rules-in-typescript/"> RTDB rules in TypeScript </a> </li><li> <a href="/__pyric/ui/docs/firestore-rules-limits/"> Rules limits </a> </li><li> <a href="/__pyric/ui/docs/whats-possible/"> Case studies </a> </li> </ul> </div><div class="docs-nav-section"> <h2 class="docs-nav-heading" id="nav-section-inspect-and-correct-work-with-an-agent"> Work with an agent </h2> <ul> <li> <a href="/__pyric/ui/docs/what-your-agent-can-do/"> Work through an agent </a> </li><li> <a href="/__pyric/ui/docs/skills/"> Agent skills </a> </li> </ul> </div> </div> </details><details class="docs-nav-group" id="nav-group-verify-the-boundary"> <summary>Verify the boundary</summary> <div class="docs-nav-group-body"> <div class="docs-nav-section">  <ul> <li> <a href="/__pyric/ui/docs/pyric-cli-how-to-verify-against-a-captured-session/"> Verify a captured session </a> </li><li> <a href="/__pyric/ui/docs/write-a-rules-test-suite/"> Write a rules test suite </a> </li><li> <a href="/__pyric/ui/docs/audit-your-rules/"> Audit rules and data </a> </li> </ul> </div> </div> </details><details class="docs-nav-group" id="nav-group-ship-unchanged"> <summary>Ship unchanged</summary> <div class="docs-nav-group-body"> <div class="docs-nav-section">  <ul> <li> <a href="/__pyric/ui/docs/ship-to-production/"> Ship to production </a> </li><li> <a href="/__pyric/ui/docs/set-up-the-project/"> Set up the Firebase project </a> </li> </ul> </div> </div> </details><details class="docs-nav-group" id="nav-group-conformance"> <summary>Conformance</summary> <div class="docs-nav-group-body"> <div class="docs-nav-section">  <ul> <li> <a href="/__pyric/ui/docs/how-we-know-it-matches-firebase/"> Conformance </a> </li><li> <a href="/__pyric/ui/docs/whats-experimental/"> What&#39;s experimental </a> </li><li> <a href="/__pyric/ui/docs/pyric-conformance-scores/"> Conformance scores </a> </li><li> <a href="/__pyric/ui/docs/pyric-app-compat/"> App </a> </li><li> <a href="/__pyric/ui/docs/pyric-firestore-compat/"> Firestore </a> </li><li> <a href="/__pyric/ui/docs/pyric-auth-compat/"> Auth </a> </li><li> <a href="/__pyric/ui/docs/pyric-database-compat/"> Realtime Database </a> </li><li> <a href="/__pyric/ui/docs/pyric-storage-compat/"> Storage </a> </li><li> <a href="/__pyric/ui/docs/pyric-rules-compat/"> Rules </a> </li><li> <a href="/__pyric/ui/docs/pyric-messaging-compat/"> Messaging </a> </li><li> <a href="/__pyric/ui/docs/pyric-ai-compat/"> AI Logic </a> </li><li> <a href="/__pyric/ui/docs/pyric-cli-functions-rtdb-compat/"> Functions · RTDB </a> </li> </ul> </div> </div> </details> <details class="docs-nav-group" id="nav-group-reference" open> <summary>Reference</summary> <div class="docs-nav-group-body"> <div class="docs-nav-section"> <ul> <li> <a href="/__pyric/ui/docs/pyric-cli/"> @pyric/cli </a> </li><li> <a href="/__pyric/ui/docs/pyric-explanation-versioning-and-compatibility/"> pyric </a> </li><li> <a href="/__pyric/ui/docs/pyric-firestore/"> pyric / firestore </a> </li><li> <a href="/__pyric/ui/docs/pyric-rules/"> pyric / rules </a> </li><li> <a href="/__pyric/ui/docs/pyric-sandbox/" aria-current="true"> pyric / sandbox </a> </li><li> <a href="/__pyric/ui/docs/pyric-storage/"> pyric / storage </a> </li><li> <a href="/__pyric/ui/docs/pyric-auth/"> pyric / auth </a> </li><li> <a href="/__pyric/ui/docs/pyric-database/"> pyric / database </a> </li><li> <a href="/__pyric/ui/docs/pyric-admin-app/"> pyric-admin / app </a> </li><li> <a href="/__pyric/ui/docs/pyric-admin-firestore/"> pyric-admin / firestore </a> </li><li> <a href="/__pyric/ui/docs/pyric-admin-auth/"> pyric-admin / auth </a> </li><li> <a href="/__pyric/ui/docs/pyric-admin-database/"> pyric-admin / database </a> </li><li> <a href="/__pyric/ui/docs/pyric-admin-storage/"> pyric-admin / storage </a> </li><li> <a href="/__pyric/ui/docs/ui/"> @pyric/ui </a> </li><li> <a href="/__pyric/ui/docs/api-reference/"> API reference </a> </li> </ul> </div> </div> </details> </nav> <main class="doc-main"> <nav class="docs-breadcrumbs" aria-label="Breadcrumb"> <ol> <li>  <a href="/__pyric/ui/docs/pyric-sandbox/">pyric / sandbox</a> </li><li> <span class="docs-breadcrumbs-sep" aria-hidden="true">/</span> <span>Reference</span> </li><li> <span class="docs-breadcrumbs-sep" aria-hidden="true">/</span> <span aria-current="page">The /internal protocol</span> </li> </ol> </nav>  <article class="prose">  <h1 id="the-internal-adapter-protocol">The <code>/internal</code> adapter protocol</h1>
+<p>The <code>pyric/sandbox/internal</code> sub-path is the <strong>adapter-only</strong> surface. Service-adapter packages (<code>pyric-admin</code>, <code>pyric/firestore</code>, future <code>pyric/auth</code>) consume it to reach the underlying <code>LocalEnvironment</code> and related primitives.</p>
+<p>It is <strong>not</strong> part of the public API. The shape is subject to change without breaking-change semantics across <code>pyric/sandbox</code> versions. External adapter authors should not depend on it directly. When the protocol stabilises (after the multi-service architecture lands) it will be promoted.</p>
+<h2 id="what-lives-there">What lives there</h2>
+<pre class="astro-code one-dark-pro" style="background-color:#282c34;color:#abb2bf; overflow-x: auto;" tabindex="0" data-language="ts"><code><span class="line"><span style="color:#C678DD">import</span><span style="color:#ABB2BF"> { </span><span style="color:#E06C75">getInternalEnv</span><span style="color:#ABB2BF">, </span><span style="color:#E06C75">LocalEnvironment</span><span style="color:#ABB2BF">, </span><span style="color:#E06C75">EventLog</span><span style="color:#7F848E;font-style:italic"> /* … */</span><span style="color:#ABB2BF"> } </span><span style="color:#C678DD">from</span><span style="color:#98C379"> 'pyric/sandbox/internal'</span><span style="color:#ABB2BF">;</span></span></code></pre>
+<p>The major surfaces:</p>
+<h3 id="getinternalenvsandbox-localenvironment"><code>getInternalEnv(sandbox): LocalEnvironment</code></h3>
+<p>Given a <code>Sandbox</code> produced by <code>initializeSandbox()</code>, return its <code>LocalEnvironment</code>. Throws <code>SandboxError('invalid-argument')</code> for hand-rolled <code>Sandbox</code> handles, so adapters can rely on it to reject malformed input early.</p>
+<h3 id="localenvironment"><code>LocalEnvironment</code></h3>
+<p>The runtime substrate. Methods adapters use most:</p>
+<ul>
+<li><code>execute(operation)</code>: run a single operation, evaluating rules.</li>
+<li><code>executeBatch(operations)</code>: atomic batch.</li>
+<li><code>runTransaction(callback)</code>: transaction with read tracking.</li>
+<li><code>seed({ rules, documents })</code>: bulk-load state.</li>
+<li><code>deployRules(source)</code>: swap rules and re-evaluate live listeners.</li>
+<li><code>addSnapshotListener({ kind, path?, collection?, auth, onSnapshot, onError? })</code>: register a Firestore-shaped listener.</li>
+<li><code>getDocument</code>, <code>listDocuments</code>, <code>listRootCollections</code>, <code>listSubcollections</code>: admin reads.</li>
+<li><code>snapshot()</code>: Firestore-only state capture.</li>
+<li><code>onRequest</code>, <code>onWrite</code>, <code>onSnapshotDelivery</code>, <code>onSnapshotSuppressed</code>, <code>onListenerLifecycle</code>, <code>onSnapshotError</code>, <code>onDenial</code>: internal channels. <code>SandboxImpl</code> subscribes to each and re-emits the resulting payloads through the public <code>Sandbox.onEvent</code> as a <code>SandboxEvent</code> discriminated union. Adapters typically don’t tap these directly; consume through <code>Sandbox.onEvent</code> instead.</li>
+<li><code>dispose()</code>: drop listener registries.</li>
+</ul>
+<h3 id="eventlog"><code>EventLog</code></h3>
+<p>Append-only audit trail of every operation. Adapters that need to surface “what happened” to a UI (the playground does) consume <code>EventLog.getEvents()</code>. Carries <code>AgentEvent</code> records with <code>id</code>, <code>timestamp</code>, <code>method</code>, <code>path</code>, <code>auth</code>, <code>allowed</code>, <code>data</code>, <code>operations</code>, <code>reads</code>, <code>debugMessages</code>.</p>
+<h3 id="field-value-sentinels">Field-value sentinels</h3>
+<p>For <code>pyric-admin</code> and <code>pyric/firestore</code> to translate user-facing sentinels into the simulator’s shape:</p>
+<pre class="astro-code one-dark-pro" style="background-color:#282c34;color:#abb2bf; overflow-x: auto;" tabindex="0" data-language="ts"><code><span class="line"><span style="color:#C678DD">import</span><span style="color:#ABB2BF"> {</span></span>
+<span class="line"><span style="color:#E06C75">  INCREMENT</span><span style="color:#ABB2BF">,</span></span>
+<span class="line"><span style="color:#E06C75">  ARRAY_UNION</span><span style="color:#ABB2BF">,</span></span>
+<span class="line"><span style="color:#E06C75">  ARRAY_REMOVE</span><span style="color:#ABB2BF">,</span></span>
+<span class="line"><span style="color:#E06C75">  DELETE_FIELD</span><span style="color:#ABB2BF">,</span></span>
+<span class="line"><span style="color:#7F848E;font-style:italic">  // converter registry</span></span>
+<span class="line"><span style="color:#E06C75">  incrementConverter</span><span style="color:#ABB2BF">, </span><span style="color:#E06C75">arrayUnionConverter</span><span style="color:#ABB2BF">, </span><span style="color:#E06C75">arrayRemoveConverter</span><span style="color:#ABB2BF">, </span><span style="color:#E06C75">deleteFieldConverter</span><span style="color:#ABB2BF">,</span></span>
+<span class="line"><span style="color:#ABB2BF">} </span><span style="color:#C678DD">from</span><span style="color:#98C379"> 'pyric/sandbox/internal'</span><span style="color:#ABB2BF">;</span></span></code></pre>
+<h3 id="transaction-primitives">Transaction primitives</h3>
+<pre class="astro-code one-dark-pro" style="background-color:#282c34;color:#abb2bf; overflow-x: auto;" tabindex="0" data-language="ts"><code><span class="line"><span style="color:#C678DD">import</span><span style="color:#ABB2BF"> {</span></span>
+<span class="line"><span style="color:#E06C75">  Transaction</span><span style="color:#ABB2BF">,</span></span>
+<span class="line"><span style="color:#C678DD">  type</span><span style="color:#E06C75"> BatchOperation</span><span style="color:#ABB2BF">,</span></span>
+<span class="line"><span style="color:#C678DD">  type</span><span style="color:#E06C75"> CreateResult</span><span style="color:#ABB2BF">,</span></span>
+<span class="line"><span style="color:#C678DD">  type</span><span style="color:#E06C75"> UpdateResult</span><span style="color:#ABB2BF">,</span></span>
+<span class="line"><span style="color:#C678DD">  type</span><span style="color:#E06C75"> SetResult</span><span style="color:#ABB2BF">,</span></span>
+<span class="line"><span style="color:#C678DD">  type</span><span style="color:#E06C75"> DeleteResult</span><span style="color:#ABB2BF">,</span></span>
+<span class="line"><span style="color:#ABB2BF">} </span><span style="color:#C678DD">from</span><span style="color:#98C379"> 'pyric/sandbox/internal'</span><span style="color:#ABB2BF">;</span></span></code></pre>
+<p>These shapes describe the per-operation results inside a batch or transaction so adapters can map them onto upstream-SDK return types.</p>
+<h3 id="error-translation-helpers">Error translation helpers</h3>
+<pre class="astro-code one-dark-pro" style="background-color:#282c34;color:#abb2bf; overflow-x: auto;" tabindex="0" data-language="ts"><code><span class="line"><span style="color:#C678DD">import</span><span style="color:#ABB2BF"> {</span></span>
+<span class="line"><span style="color:#E06C75">  FirestoreSimError</span><span style="color:#ABB2BF">,</span></span>
+<span class="line"><span style="color:#E06C75">  firestoreErrorFromSimError</span><span style="color:#ABB2BF">,</span></span>
+<span class="line"><span style="color:#E06C75">  FIRESTORE_ERROR_CODES</span><span style="color:#ABB2BF">,</span></span>
+<span class="line"><span style="color:#ABB2BF">} </span><span style="color:#C678DD">from</span><span style="color:#98C379"> 'pyric/sandbox/internal'</span><span style="color:#ABB2BF">;</span></span></code></pre>
+<p>Adapters use these to translate simulator-shaped errors into upstream-SDK error shapes (<code>FirebaseError</code> with <code>firestore/permission-denied</code>-style codes).</p>
+<h3 id="value-resolver">Value resolver</h3>
+<pre class="astro-code one-dark-pro" style="background-color:#282c34;color:#abb2bf; overflow-x: auto;" tabindex="0" data-language="ts"><code><span class="line"><span style="color:#C678DD">import</span><span style="color:#ABB2BF"> {</span></span>
+<span class="line"><span style="color:#E06C75">  resolveValueTree</span><span style="color:#ABB2BF">,</span></span>
+<span class="line"><span style="color:#E06C75">  partitionDeletes</span><span style="color:#ABB2BF">,</span></span>
+<span class="line"><span style="color:#E06C75">  registerDefaultConverters</span><span style="color:#ABB2BF">,</span></span>
+<span class="line"><span style="color:#C678DD">  type</span><span style="color:#E06C75"> ResolveMethod</span><span style="color:#ABB2BF">,</span></span>
+<span class="line"><span style="color:#ABB2BF">} </span><span style="color:#C678DD">from</span><span style="color:#98C379"> 'pyric/sandbox/internal'</span><span style="color:#ABB2BF">;</span></span></code></pre>
+<p>Walk a payload tree, replacing sentinel values (<code>INCREMENT(1)</code>, <code>serverTimestamp()</code>, etc.) with their resolved equivalents under the current document state.</p>
+<h2 id="what-stays-out">What stays out</h2>
+<p>The <code>/internal</code> surface is for adapters to <em>reach into</em> the sandbox. It is not a place to wedge half-public APIs that should eventually be promoted. Two rules:</p>
+<ul>
+<li><strong>No application code imports from <code>/internal</code>.</strong> Application code uses the data-plane adapters (<code>pyric-admin</code>, <code>pyric/firestore</code>), not the substrate.</li>
+<li><strong>No business logic lives in <code>/internal</code>.</strong> Anything that translates user intent (e.g. “patch this update with <code>FieldValue.increment(1)</code>”) lives in the adapter, not in the substrate. The substrate stores documents and runs rules.</li>
+</ul>
+<p>When a method on <code>LocalEnvironment</code> starts to look like an application-facing API, the right move is to expose it through an adapter, not through <code>/internal</code>.</p>
+<h2 id="star-export-caveat">Star-export caveat</h2>
+<p>The <code>/internal</code> index uses <code>export * from '../firestore/local-environment.js'</code>
+and similar to forward every public symbol from the moved files. This is
+deliberate. <code>pyric-admin</code> reaches in for a long tail of helper symbols, and
+listing each one by hand creates maintenance churn.</p>
+<p>The downside is that adding a new export in a moved file silently propagates through <code>/internal</code>. Adapter packages should treat the <code>/internal</code> surface as “everything currently in those files” and not as “exactly these named symbols”.</p>  </article> </main> <aside class="doc-toc" aria-label="On this page"> <h2 class="doc-toc-heading">On this page</h2> <ul> <li data-depth="2"> <a href="#what-lives-there">What lives there</a> </li><li data-depth="3"> <a href="#getinternalenvsandbox-localenvironment">getInternalEnv(sandbox): LocalEnvironment</a> </li><li data-depth="3"> <a href="#localenvironment">LocalEnvironment</a> </li><li data-depth="3"> <a href="#eventlog">EventLog</a> </li><li data-depth="3"> <a href="#field-value-sentinels">Field-value sentinels</a> </li><li data-depth="3"> <a href="#transaction-primitives">Transaction primitives</a> </li><li data-depth="3"> <a href="#error-translation-helpers">Error translation helpers</a> </li><li data-depth="3"> <a href="#value-resolver">Value resolver</a> </li><li data-depth="2"> <a href="#what-stays-out">What stays out</a> </li><li data-depth="2"> <a href="#star-export-caveat">Star-export caveat</a> </li> </ul> </aside> </div> <script type="module">const a=document.querySelector("[data-api-symbol-filter]"),d=[...document.querySelectorAll("[data-api-symbol-group]")],n=document.querySelector("[data-api-symbol-empty]");a?.addEventListener("input",()=>{const t=a.value.trim().toLowerCase();let o=0;for(const i of d){let e=0;i.querySelectorAll("[data-api-symbol]").forEach(l=>{const r=!t||(l.dataset.apiSymbol??"").includes(t);l.hidden=!r,r&&e++}),i.hidden=e===0,o+=e}n&&(n.hidden=o>0)});</script> <script type="module">const s=new Map;document.querySelectorAll('.doc-toc a[href^="#"]').forEach(t=>s.set(decodeURIComponent(t.hash.slice(1)),t));if(s.size>0){const t=new Set,n=()=>{let o=null;for(const e of s.keys())if(t.has(e)){o=e;break}s.forEach((e,c)=>e.classList.toggle("active",c===o))},r=new IntersectionObserver(o=>{for(const e of o)e.isIntersecting?t.add(e.target.id):t.delete(e.target.id);n()},{rootMargin:"-72px 0px -60% 0px"});s.forEach((o,e)=>{const c=document.getElementById(e);c&&r.observe(c)})}</script> <script type="module">document.querySelector('.studio__nav [aria-current="page"]')?.scrollIntoView({block:"nearest",inline:"center"});</script> </body> </html>

package/dist/serve/docs-ui/docs/pyric-sandbox-reference-internal-protocol.md

@@ -0,0 +1,109 @@
+# The `/internal` adapter protocol
+
+The `pyric/sandbox/internal` sub-path is the **adapter-only** surface. Service-adapter packages (`pyric-admin`, `pyric/firestore`, future `pyric/auth`) consume it to reach the underlying `LocalEnvironment` and related primitives.
+
+It is **not** part of the public API. The shape is subject to change without breaking-change semantics across `pyric/sandbox` versions. External adapter authors should not depend on it directly. When the protocol stabilises (after the multi-service architecture lands) it will be promoted.
+
+## What lives there
+
+```ts
+import { getInternalEnv, LocalEnvironment, EventLog /* … */ } from 'pyric/sandbox/internal';
+```
+
+The major surfaces:
+
+### `getInternalEnv(sandbox): LocalEnvironment`
+
+Given a `Sandbox` produced by `initializeSandbox()`, return its `LocalEnvironment`. Throws `SandboxError('invalid-argument')` for hand-rolled `Sandbox` handles, so adapters can rely on it to reject malformed input early.
+
+### `LocalEnvironment`
+
+The runtime substrate. Methods adapters use most:
+
+- `execute(operation)`: run a single operation, evaluating rules.
+- `executeBatch(operations)`: atomic batch.
+- `runTransaction(callback)`: transaction with read tracking.
+- `seed({ rules, documents })`: bulk-load state.
+- `deployRules(source)`: swap rules and re-evaluate live listeners.
+- `addSnapshotListener({ kind, path?, collection?, auth, onSnapshot, onError? })`: register a Firestore-shaped listener.
+- `getDocument`, `listDocuments`, `listRootCollections`, `listSubcollections`: admin reads.
+- `snapshot()`: Firestore-only state capture.
+- `onRequest`, `onWrite`, `onSnapshotDelivery`, `onSnapshotSuppressed`, `onListenerLifecycle`, `onSnapshotError`, `onDenial`: internal channels. `SandboxImpl` subscribes to each and re-emits the resulting payloads through the public `Sandbox.onEvent` as a `SandboxEvent` discriminated union. Adapters typically don't tap these directly; consume through `Sandbox.onEvent` instead.
+- `dispose()`: drop listener registries.
+
+### `EventLog`
+
+Append-only audit trail of every operation. Adapters that need to surface "what happened" to a UI (the playground does) consume `EventLog.getEvents()`. Carries `AgentEvent` records with `id`, `timestamp`, `method`, `path`, `auth`, `allowed`, `data`, `operations`, `reads`, `debugMessages`.
+
+### Field-value sentinels
+
+For `pyric-admin` and `pyric/firestore` to translate user-facing sentinels into the simulator's shape:
+
+```ts
+import {
+  INCREMENT,
+  ARRAY_UNION,
+  ARRAY_REMOVE,
+  DELETE_FIELD,
+  // converter registry
+  incrementConverter, arrayUnionConverter, arrayRemoveConverter, deleteFieldConverter,
+} from 'pyric/sandbox/internal';
+```
+
+### Transaction primitives
+
+```ts
+import {
+  Transaction,
+  type BatchOperation,
+  type CreateResult,
+  type UpdateResult,
+  type SetResult,
+  type DeleteResult,
+} from 'pyric/sandbox/internal';
+```
+
+These shapes describe the per-operation results inside a batch or transaction so adapters can map them onto upstream-SDK return types.
+
+### Error translation helpers
+
+```ts
+import {
+  FirestoreSimError,
+  firestoreErrorFromSimError,
+  FIRESTORE_ERROR_CODES,
+} from 'pyric/sandbox/internal';
+```
+
+Adapters use these to translate simulator-shaped errors into upstream-SDK error shapes (`FirebaseError` with `firestore/permission-denied`-style codes).
+
+### Value resolver
+
+```ts
+import {
+  resolveValueTree,
+  partitionDeletes,
+  registerDefaultConverters,
+  type ResolveMethod,
+} from 'pyric/sandbox/internal';
+```
+
+Walk a payload tree, replacing sentinel values (`INCREMENT(1)`, `serverTimestamp()`, etc.) with their resolved equivalents under the current document state.
+
+## What stays out
+
+The `/internal` surface is for adapters to *reach into* the sandbox. It is not a place to wedge half-public APIs that should eventually be promoted. Two rules:
+
+- **No application code imports from `/internal`.** Application code uses the data-plane adapters (`pyric-admin`, `pyric/firestore`), not the substrate.
+- **No business logic lives in `/internal`.** Anything that translates user intent (e.g. "patch this update with `FieldValue.increment(1)`") lives in the adapter, not in the substrate. The substrate stores documents and runs rules.
+
+When a method on `LocalEnvironment` starts to look like an application-facing API, the right move is to expose it through an adapter, not through `/internal`.
+
+## Star-export caveat
+
+The `/internal` index uses `export * from '../firestore/local-environment.js'`
+and similar to forward every public symbol from the moved files. This is
+deliberate. `pyric-admin` reaches in for a long tail of helper symbols, and
+listing each one by hand creates maintenance churn.
+
+The downside is that adding a new export in a moved file silently propagates through `/internal`. Adapter packages should treat the `/internal` surface as "everything currently in those files" and not as "exactly these named symbols".

package/dist/serve/docs-ui/docs/pyric-sandbox-reference-sandbox-and-context/index.html

@@ -0,0 +1,90 @@
+<!DOCTYPE html><html lang="en"> <head><meta charset="UTF-8"><meta name="viewport" content="width=device-width, initial-scale=1.0"><title>Sandbox, SandboxContext, AuthState · Pyric Studio</title><link rel="preconnect" href="https://fonts.googleapis.com"><link rel="preconnect" href="https://fonts.gstatic.com" crossorigin><link href="https://fonts.googleapis.com/css2?family=Inter:wght@300;400;500;600;700&family=JetBrains+Mono:wght@400;500;700&display=swap" rel="stylesheet"><link rel="stylesheet" href="/__pyric/ui/_astro/_slug_.CQYSemvw.css"></head> <body>  <header class="studio__bar"> <div class="studio__bar-inner"> <a class="studio__brand" href="/__pyric/ui/" aria-label="Pyric Studio">Pyric</a> <nav class="studio__nav" aria-label="Studio tabs"> <a class="studio__nav-tab" href="/__pyric/ui/"> Home </a><a class="studio__nav-tab" href="/__pyric/ui/firestore"> Firestore </a><a class="studio__nav-tab" href="/__pyric/ui/auth"> Auth </a><a class="studio__nav-tab" href="/__pyric/ui/rtdb"> RTDB </a><a class="studio__nav-tab" href="/__pyric/ui/storage"> Storage </a><a class="studio__nav-tab" href="/__pyric/ui/traffic"> Traffic </a><a class="studio__nav-tab" href="/__pyric/ui/settings"> Settings </a><a class="studio__nav-tab" href="/__pyric/ui/docs" aria-current="page"> Docs </a> </nav> </div> </header> <div class="docs-shell">  <details class="docs-nav-drawer"> <summary>Navigate</summary> <nav class="docs-nav" aria-label="Documentation"> <div class="docs-search" data-index-url="/__pyric/ui/docs/index.json"> <div class="docs-search-field"> <svg class="docs-search-icon" viewBox="0 0 16 16" width="14" height="14" aria-hidden="true"> <path d="M11.5 11.5 15 15M13 7A6 6 0 1 1 1 7a6 6 0 0 1 12 0Z" fill="none" stroke="currentColor" stroke-width="1.4" stroke-linecap="round"></path> </svg> <input type="text" class="docs-search-input" placeholder="Search docs" aria-label="Search docs" autocomplete="off" spellcheck="false"> <kbd class="docs-search-kbd">⌘K</kbd> </div> <ul class="docs-search-results" hidden></ul> </div> <script type="module">let i=null;function d(t){return i||(i=fetch(t).then(e=>e.json())),i}function l(t,e){return t.title.toLowerCase().includes(e)||t.excerpt.toLowerCase().includes(e)?!0:t.headings.some(r=>r.text.toLowerCase().includes(e))}function u(t,e,r){if(e.innerHTML="",t.length===0){e.hidden=!1;{const n=document.createElement("li");n.className="docs-search-empty",n.textContent="No matches",e.appendChild(n)}return}e.hidden=!1;for(const n of t.slice(0,8)){const s=document.createElement("li"),c=document.createElement("a");c.href=n.path;const o=document.createElement("span");o.className="docs-search-result-title",o.textContent=n.title;const a=document.createElement("span");a.className="docs-search-result-meta",a.textContent=[n.group,n.section].filter(Boolean).join(" / "),c.append(o,a),s.appendChild(c),e.appendChild(s)}}document.querySelectorAll(".docs-search").forEach(t=>{const e=t.dataset.indexUrl,r=t.querySelector(".docs-search-input"),n=t.querySelector(".docs-search-results");r.addEventListener("input",async()=>{const s=r.value.trim().toLowerCase();if(!s){n.hidden=!0,n.innerHTML="";return}const{pages:c}=await d(e);r.value.trim().toLowerCase()===s&&u(c.filter(o=>l(o,s)),n)}),r.addEventListener("focus",()=>{d(e),n.childElementCount>0&&(n.hidden=!1)}),r.addEventListener("keydown",s=>{s.key==="Escape"&&(r.value="",n.hidden=!0,n.innerHTML="",r.blur())}),r.addEventListener("blur",()=>{window.setTimeout(()=>{n.hidden=!0},150)})});document.addEventListener("keydown",t=>{if(!(t.metaKey||t.ctrlKey)||t.key.toLowerCase()!=="k")return;const e=[...document.querySelectorAll(".docs-search-input")].find(r=>r.offsetParent!==null);e&&(t.preventDefault(),e.focus(),e.select())});</script> <a class="docs-nav-toplink" href="/__pyric/ui/docs/overview/"> Overview </a><details class="docs-nav-group"> <summary>Run locally</summary> <div class="docs-nav-group-body"> <div class="docs-nav-section">  <ul> <li> <a href="/__pyric/ui/docs/start-building/"> Quickstart </a> </li><li> <a href="/__pyric/ui/docs/how-the-swap-works/"> How the swap works </a> </li><li> <a href="/__pyric/ui/docs/set-up-your-agent/"> Connect an agent </a> </li><li> <a href="/__pyric/ui/docs/test-in-node/"> Test in Node </a> </li> </ul> </div> </div> </details><details class="docs-nav-group"> <summary>Develop with Firebase APIs</summary> <div class="docs-nav-group-body"> <div class="docs-nav-section">  <ul> <li> <a href="/__pyric/ui/docs/sign-in-and-manage-users/"> Sign in and manage users </a> </li><li> <a href="/__pyric/ui/docs/store-and-query-data/"> Store and query data </a> </li><li> <a href="/__pyric/ui/docs/sync-realtime-data/"> Sync realtime data </a> </li><li> <a href="/__pyric/ui/docs/store-files/"> Store files </a> </li><li> <a href="/__pyric/ui/docs/receive-messages/"> Receive messages </a> </li><li> <a href="/__pyric/ui/docs/run-ai-logic-locally/"> Run AI Logic locally </a> </li><li> <a href="/__pyric/ui/docs/pyric-cli-how-to-run-rtdb-onvaluecreated/"> Run an RTDB function locally </a> </li><li> <a href="/__pyric/ui/docs/which-data-service/"> Which data service? </a> </li> </ul> </div> </div> </details><details class="docs-nav-group"> <summary>Inspect and correct</summary> <div class="docs-nav-group-body"> <div class="docs-nav-section"> <h2 class="docs-nav-heading"> Inspect the sandbox </h2> <ul> <li> <a href="/__pyric/ui/docs/see-whats-happening/"> Traffic &amp; rule verdicts </a> </li><li> <a href="/__pyric/ui/docs/read-a-denial/"> Read a denial and understand it </a> </li><li> <a href="/__pyric/ui/docs/shape-your-data/"> Seed, snapshot, replay </a> </li><li> <a href="/__pyric/ui/docs/watch-and-review/"> Review agent activity </a> </li> </ul> </div><div class="docs-nav-section"> <h2 class="docs-nav-heading"> Correct Security Rules </h2> <ul> <li> <a href="/__pyric/ui/docs/secure-it-with-rules/"> Security Rules </a> </li><li> <a href="/__pyric/ui/docs/simulate-and-lint/"> Simulate and lint before you deploy </a> </li><li> <a href="/__pyric/ui/docs/rules-patterns/"> Rules patterns </a> </li><li> <a href="/__pyric/ui/docs/rules-standard-library/"> The rules standard library </a> </li><li> <a href="/__pyric/ui/docs/rtdb-rules-in-typescript/"> RTDB rules in TypeScript </a> </li><li> <a href="/__pyric/ui/docs/firestore-rules-limits/"> Rules limits </a> </li><li> <a href="/__pyric/ui/docs/whats-possible/"> Case studies </a> </li> </ul> </div><div class="docs-nav-section"> <h2 class="docs-nav-heading"> Work with an agent </h2> <ul> <li> <a href="/__pyric/ui/docs/what-your-agent-can-do/"> Work through an agent </a> </li><li> <a href="/__pyric/ui/docs/skills/"> Agent skills </a> </li> </ul> </div> </div> </details><details class="docs-nav-group"> <summary>Verify the boundary</summary> <div class="docs-nav-group-body"> <div class="docs-nav-section">  <ul> <li> <a href="/__pyric/ui/docs/pyric-cli-how-to-verify-against-a-captured-session/"> Verify a captured session </a> </li><li> <a href="/__pyric/ui/docs/write-a-rules-test-suite/"> Write a rules test suite </a> </li><li> <a href="/__pyric/ui/docs/audit-your-rules/"> Audit rules and data </a> </li> </ul> </div> </div> </details><details class="docs-nav-group"> <summary>Ship unchanged</summary> <div class="docs-nav-group-body"> <div class="docs-nav-section">  <ul> <li> <a href="/__pyric/ui/docs/ship-to-production/"> Ship to production </a> </li><li> <a href="/__pyric/ui/docs/set-up-the-project/"> Set up the Firebase project </a> </li> </ul> </div> </div> </details><details class="docs-nav-group"> <summary>Conformance</summary> <div class="docs-nav-group-body"> <div class="docs-nav-section">  <ul> <li> <a href="/__pyric/ui/docs/how-we-know-it-matches-firebase/"> Conformance </a> </li><li> <a href="/__pyric/ui/docs/whats-experimental/"> What&#39;s experimental </a> </li><li> <a href="/__pyric/ui/docs/pyric-conformance-scores/"> Conformance scores </a> </li><li> <a href="/__pyric/ui/docs/pyric-app-compat/"> App </a> </li><li> <a href="/__pyric/ui/docs/pyric-firestore-compat/"> Firestore </a> </li><li> <a href="/__pyric/ui/docs/pyric-auth-compat/"> Auth </a> </li><li> <a href="/__pyric/ui/docs/pyric-database-compat/"> Realtime Database </a> </li><li> <a href="/__pyric/ui/docs/pyric-storage-compat/"> Storage </a> </li><li> <a href="/__pyric/ui/docs/pyric-rules-compat/"> Rules </a> </li><li> <a href="/__pyric/ui/docs/pyric-messaging-compat/"> Messaging </a> </li><li> <a href="/__pyric/ui/docs/pyric-ai-compat/"> AI Logic </a> </li><li> <a href="/__pyric/ui/docs/pyric-cli-functions-rtdb-compat/"> Functions · RTDB </a> </li> </ul> </div> </div> </details> <details class="docs-nav-group" open> <summary>Reference</summary> <div class="docs-nav-group-body"> <div class="docs-nav-section"> <ul> <li> <a href="/__pyric/ui/docs/pyric-cli/"> @pyric/cli </a> </li><li> <a href="/__pyric/ui/docs/pyric-explanation-versioning-and-compatibility/"> pyric </a> </li><li> <a href="/__pyric/ui/docs/pyric-firestore/"> pyric / firestore </a> </li><li> <a href="/__pyric/ui/docs/pyric-rules/"> pyric / rules </a> </li><li> <a href="/__pyric/ui/docs/pyric-sandbox/" aria-current="true"> pyric / sandbox </a> </li><li> <a href="/__pyric/ui/docs/pyric-storage/"> pyric / storage </a> </li><li> <a href="/__pyric/ui/docs/pyric-auth/"> pyric / auth </a> </li><li> <a href="/__pyric/ui/docs/pyric-database/"> pyric / database </a> </li><li> <a href="/__pyric/ui/docs/pyric-admin-app/"> pyric-admin / app </a> </li><li> <a href="/__pyric/ui/docs/pyric-admin-firestore/"> pyric-admin / firestore </a> </li><li> <a href="/__pyric/ui/docs/pyric-admin-auth/"> pyric-admin / auth </a> </li><li> <a href="/__pyric/ui/docs/pyric-admin-database/"> pyric-admin / database </a> </li><li> <a href="/__pyric/ui/docs/pyric-admin-storage/"> pyric-admin / storage </a> </li><li> <a href="/__pyric/ui/docs/ui/"> @pyric/ui </a> </li><li> <a href="/__pyric/ui/docs/api-reference/"> API reference </a> </li> </ul> </div> </div> </details> </nav> </details> <nav class="docs-nav" aria-label="Documentation"> <div class="docs-search" data-index-url="/__pyric/ui/docs/index.json"> <div class="docs-search-field"> <svg class="docs-search-icon" viewBox="0 0 16 16" width="14" height="14" aria-hidden="true"> <path d="M11.5 11.5 15 15M13 7A6 6 0 1 1 1 7a6 6 0 0 1 12 0Z" fill="none" stroke="currentColor" stroke-width="1.4" stroke-linecap="round"></path> </svg> <input type="text" class="docs-search-input" placeholder="Search docs" aria-label="Search docs" autocomplete="off" spellcheck="false"> <kbd class="docs-search-kbd">⌘K</kbd> </div> <ul class="docs-search-results" hidden></ul> </div>  <a class="docs-nav-toplink" href="/__pyric/ui/docs/overview/" id="nav-group-overview"> Overview </a><details class="docs-nav-group" id="nav-group-run-locally"> <summary>Run locally</summary> <div class="docs-nav-group-body"> <div class="docs-nav-section">  <ul> <li> <a href="/__pyric/ui/docs/start-building/"> Quickstart </a> </li><li> <a href="/__pyric/ui/docs/how-the-swap-works/"> How the swap works </a> </li><li> <a href="/__pyric/ui/docs/set-up-your-agent/"> Connect an agent </a> </li><li> <a href="/__pyric/ui/docs/test-in-node/"> Test in Node </a> </li> </ul> </div> </div> </details><details class="docs-nav-group" id="nav-group-develop-with-firebase-apis"> <summary>Develop with Firebase APIs</summary> <div class="docs-nav-group-body"> <div class="docs-nav-section">  <ul> <li> <a href="/__pyric/ui/docs/sign-in-and-manage-users/"> Sign in and manage users </a> </li><li> <a href="/__pyric/ui/docs/store-and-query-data/"> Store and query data </a> </li><li> <a href="/__pyric/ui/docs/sync-realtime-data/"> Sync realtime data </a> </li><li> <a href="/__pyric/ui/docs/store-files/"> Store files </a> </li><li> <a href="/__pyric/ui/docs/receive-messages/"> Receive messages </a> </li><li> <a href="/__pyric/ui/docs/run-ai-logic-locally/"> Run AI Logic locally </a> </li><li> <a href="/__pyric/ui/docs/pyric-cli-how-to-run-rtdb-onvaluecreated/"> Run an RTDB function locally </a> </li><li> <a href="/__pyric/ui/docs/which-data-service/"> Which data service? </a> </li> </ul> </div> </div> </details><details class="docs-nav-group" id="nav-group-inspect-and-correct"> <summary>Inspect and correct</summary> <div class="docs-nav-group-body"> <div class="docs-nav-section"> <h2 class="docs-nav-heading" id="nav-section-inspect-and-correct-inspect-the-sandbox"> Inspect the sandbox </h2> <ul> <li> <a href="/__pyric/ui/docs/see-whats-happening/"> Traffic &amp; rule verdicts </a> </li><li> <a href="/__pyric/ui/docs/read-a-denial/"> Read a denial and understand it </a> </li><li> <a href="/__pyric/ui/docs/shape-your-data/"> Seed, snapshot, replay </a> </li><li> <a href="/__pyric/ui/docs/watch-and-review/"> Review agent activity </a> </li> </ul> </div><div class="docs-nav-section"> <h2 class="docs-nav-heading" id="nav-section-inspect-and-correct-correct-security-rules"> Correct Security Rules </h2> <ul> <li> <a href="/__pyric/ui/docs/secure-it-with-rules/"> Security Rules </a> </li><li> <a href="/__pyric/ui/docs/simulate-and-lint/"> Simulate and lint before you deploy </a> </li><li> <a href="/__pyric/ui/docs/rules-patterns/"> Rules patterns </a> </li><li> <a href="/__pyric/ui/docs/rules-standard-library/"> The rules standard library </a> </li><li> <a href="/__pyric/ui/docs/rtdb-rules-in-typescript/"> RTDB rules in TypeScript </a> </li><li> <a href="/__pyric/ui/docs/firestore-rules-limits/"> Rules limits </a> </li><li> <a href="/__pyric/ui/docs/whats-possible/"> Case studies </a> </li> </ul> </div><div class="docs-nav-section"> <h2 class="docs-nav-heading" id="nav-section-inspect-and-correct-work-with-an-agent"> Work with an agent </h2> <ul> <li> <a href="/__pyric/ui/docs/what-your-agent-can-do/"> Work through an agent </a> </li><li> <a href="/__pyric/ui/docs/skills/"> Agent skills </a> </li> </ul> </div> </div> </details><details class="docs-nav-group" id="nav-group-verify-the-boundary"> <summary>Verify the boundary</summary> <div class="docs-nav-group-body"> <div class="docs-nav-section">  <ul> <li> <a href="/__pyric/ui/docs/pyric-cli-how-to-verify-against-a-captured-session/"> Verify a captured session </a> </li><li> <a href="/__pyric/ui/docs/write-a-rules-test-suite/"> Write a rules test suite </a> </li><li> <a href="/__pyric/ui/docs/audit-your-rules/"> Audit rules and data </a> </li> </ul> </div> </div> </details><details class="docs-nav-group" id="nav-group-ship-unchanged"> <summary>Ship unchanged</summary> <div class="docs-nav-group-body"> <div class="docs-nav-section">  <ul> <li> <a href="/__pyric/ui/docs/ship-to-production/"> Ship to production </a> </li><li> <a href="/__pyric/ui/docs/set-up-the-project/"> Set up the Firebase project </a> </li> </ul> </div> </div> </details><details class="docs-nav-group" id="nav-group-conformance"> <summary>Conformance</summary> <div class="docs-nav-group-body"> <div class="docs-nav-section">  <ul> <li> <a href="/__pyric/ui/docs/how-we-know-it-matches-firebase/"> Conformance </a> </li><li> <a href="/__pyric/ui/docs/whats-experimental/"> What&#39;s experimental </a> </li><li> <a href="/__pyric/ui/docs/pyric-conformance-scores/"> Conformance scores </a> </li><li> <a href="/__pyric/ui/docs/pyric-app-compat/"> App </a> </li><li> <a href="/__pyric/ui/docs/pyric-firestore-compat/"> Firestore </a> </li><li> <a href="/__pyric/ui/docs/pyric-auth-compat/"> Auth </a> </li><li> <a href="/__pyric/ui/docs/pyric-database-compat/"> Realtime Database </a> </li><li> <a href="/__pyric/ui/docs/pyric-storage-compat/"> Storage </a> </li><li> <a href="/__pyric/ui/docs/pyric-rules-compat/"> Rules </a> </li><li> <a href="/__pyric/ui/docs/pyric-messaging-compat/"> Messaging </a> </li><li> <a href="/__pyric/ui/docs/pyric-ai-compat/"> AI Logic </a> </li><li> <a href="/__pyric/ui/docs/pyric-cli-functions-rtdb-compat/"> Functions · RTDB </a> </li> </ul> </div> </div> </details> <details class="docs-nav-group" id="nav-group-reference" open> <summary>Reference</summary> <div class="docs-nav-group-body"> <div class="docs-nav-section"> <ul> <li> <a href="/__pyric/ui/docs/pyric-cli/"> @pyric/cli </a> </li><li> <a href="/__pyric/ui/docs/pyric-explanation-versioning-and-compatibility/"> pyric </a> </li><li> <a href="/__pyric/ui/docs/pyric-firestore/"> pyric / firestore </a> </li><li> <a href="/__pyric/ui/docs/pyric-rules/"> pyric / rules </a> </li><li> <a href="/__pyric/ui/docs/pyric-sandbox/" aria-current="true"> pyric / sandbox </a> </li><li> <a href="/__pyric/ui/docs/pyric-storage/"> pyric / storage </a> </li><li> <a href="/__pyric/ui/docs/pyric-auth/"> pyric / auth </a> </li><li> <a href="/__pyric/ui/docs/pyric-database/"> pyric / database </a> </li><li> <a href="/__pyric/ui/docs/pyric-admin-app/"> pyric-admin / app </a> </li><li> <a href="/__pyric/ui/docs/pyric-admin-firestore/"> pyric-admin / firestore </a> </li><li> <a href="/__pyric/ui/docs/pyric-admin-auth/"> pyric-admin / auth </a> </li><li> <a href="/__pyric/ui/docs/pyric-admin-database/"> pyric-admin / database </a> </li><li> <a href="/__pyric/ui/docs/pyric-admin-storage/"> pyric-admin / storage </a> </li><li> <a href="/__pyric/ui/docs/ui/"> @pyric/ui </a> </li><li> <a href="/__pyric/ui/docs/api-reference/"> API reference </a> </li> </ul> </div> </div> </details> </nav> <main class="doc-main"> <nav class="docs-breadcrumbs" aria-label="Breadcrumb"> <ol> <li>  <a href="/__pyric/ui/docs/pyric-sandbox/">pyric / sandbox</a> </li><li> <span class="docs-breadcrumbs-sep" aria-hidden="true">/</span> <span>Reference</span> </li><li> <span class="docs-breadcrumbs-sep" aria-hidden="true">/</span> <span aria-current="page">Sandbox and context</span> </li> </ol> </nav>  <article class="prose">  <h1 id="sandbox-sandboxcontext-authstate"><code>Sandbox</code>, <code>SandboxContext</code>, <code>AuthState</code></h1>
+<p>The three core types. Every other surface in the package builds on them.</p>
+<h2 id="sandbox"><code>Sandbox</code></h2>
+<p>The data + rules + lifecycle handle.</p>
+<pre class="astro-code one-dark-pro" style="background-color:#282c34;color:#abb2bf; overflow-x: auto;" tabindex="0" data-language="ts"><code><span class="line"><span style="color:#C678DD">interface</span><span style="color:#E5C07B"> Sandbox</span><span style="color:#ABB2BF"> {</span></span>
+<span class="line"><span style="color:#61AFEF">  withAuth</span><span style="color:#ABB2BF">(</span><span style="color:#E06C75;font-style:italic">auth</span><span style="color:#ABB2BF">: </span><span style="color:#E5C07B">AuthState</span><span style="color:#ABB2BF">): </span><span style="color:#E5C07B">SandboxContext</span><span style="color:#ABB2BF">;</span></span>
+<span class="line"><span style="color:#61AFEF">  onEvent</span><span style="color:#ABB2BF">(</span><span style="color:#61AFEF">cb</span><span style="color:#ABB2BF">: (</span><span style="color:#E06C75;font-style:italic">event</span><span style="color:#ABB2BF">: </span><span style="color:#E5C07B">SandboxEvent</span><span style="color:#ABB2BF">) </span><span style="color:#C678DD">=></span><span style="color:#E5C07B"> void</span><span style="color:#ABB2BF">): () </span><span style="color:#C678DD">=></span><span style="color:#E5C07B"> void</span><span style="color:#ABB2BF">;</span></span>
+<span class="line"><span style="color:#61AFEF">  history</span><span style="color:#ABB2BF">(): </span><span style="color:#E5C07B">SandboxEvent</span><span style="color:#ABB2BF">[];</span></span>
+<span class="line"><span style="color:#C678DD">  readonly</span><span style="color:#E06C75"> admin</span><span style="color:#ABB2BF">: </span><span style="color:#E5C07B">SandboxAdmin</span><span style="color:#ABB2BF">;</span></span>
+<span class="line"><span style="color:#61AFEF">  reset</span><span style="color:#ABB2BF">(): </span><span style="color:#E5C07B">void</span><span style="color:#ABB2BF">;</span></span>
+<span class="line"><span style="color:#61AFEF">  dispose</span><span style="color:#ABB2BF">(): </span><span style="color:#E5C07B">void</span><span style="color:#ABB2BF">;</span></span>
+<span class="line"><span style="color:#61AFEF">  snapshot</span><span style="color:#ABB2BF">(): </span><span style="color:#E5C07B">SandboxSnapshot</span><span style="color:#ABB2BF">;</span></span>
+<span class="line"><span style="color:#ABB2BF">}</span></span></code></pre>
+<p>A <code>Sandbox</code> is <strong>identity-agnostic</strong>. It does not know who you are; that’s what <code>SandboxContext</code> is for. The <code>Sandbox</code> only holds:</p>
+<ul>
+<li>The current <code>LocalEnvironment</code> (documents, rules, listeners).</li>
+<li>The <code>onEvent</code> subscriber registry (survives <code>reset()</code>).</li>
+<li>Lifecycle methods (<code>reset</code>, <code>dispose</code>).</li>
+</ul>
+<p>Construct via <code>initializeSandbox()</code>. Custom implementations are not supported. Adapter packages use <code>instanceof</code> checks to route, and pass through <code>getInternalEnv</code> (from <code>pyric/sandbox/internal</code>) which throws on non-<code>SandboxImpl</code> handles.</p>
+<h3 id="withauthauth"><code>withAuth(auth)</code></h3>
+<p>Derive a <code>SandboxContext</code> bound to this sandbox under the given auth identity.</p>
+<pre class="astro-code one-dark-pro" style="background-color:#282c34;color:#abb2bf; overflow-x: auto;" tabindex="0" data-language="ts"><code><span class="line"><span style="color:#C678DD">const</span><span style="color:#E5C07B"> aliceCtx</span><span style="color:#56B6C2"> =</span><span style="color:#E5C07B"> sandbox</span><span style="color:#ABB2BF">.</span><span style="color:#61AFEF">withAuth</span><span style="color:#ABB2BF">({ </span><span style="color:#E06C75">uid</span><span style="color:#ABB2BF">: </span><span style="color:#98C379">'alice'</span><span style="color:#ABB2BF"> });</span></span>
+<span class="line"><span style="color:#C678DD">const</span><span style="color:#E5C07B"> adminCtx</span><span style="color:#56B6C2"> =</span><span style="color:#E5C07B"> sandbox</span><span style="color:#ABB2BF">.</span><span style="color:#61AFEF">withAuth</span><span style="color:#ABB2BF">({ </span><span style="color:#E06C75">uid</span><span style="color:#ABB2BF">: </span><span style="color:#98C379">'admin'</span><span style="color:#ABB2BF">, </span><span style="color:#E06C75">token</span><span style="color:#ABB2BF">: { </span><span style="color:#E06C75">role</span><span style="color:#ABB2BF">: </span><span style="color:#98C379">'admin'</span><span style="color:#ABB2BF"> } });</span></span>
+<span class="line"><span style="color:#C678DD">const</span><span style="color:#E5C07B"> anonCtx</span><span style="color:#56B6C2">  =</span><span style="color:#E5C07B"> sandbox</span><span style="color:#ABB2BF">.</span><span style="color:#61AFEF">withAuth</span><span style="color:#ABB2BF">(</span><span style="color:#D19A66">null</span><span style="color:#ABB2BF">);</span></span></code></pre>
+<p><code>undefined</code> is rejected: say <code>withAuth(null)</code> for anonymous explicitly so the call site is unambiguous. Empty UIDs are rejected. Non-object <code>token</code> is rejected. See the <a href="../pyric-sandbox-reference-error-codes/#invalid-argument">error-handling notes</a> for the exact rules.</p>
+<h3 id="oneventcb"><code>onEvent(cb)</code></h3>
+<p>Subscribe to every observable event the sandbox emits. See <a href="../pyric-sandbox-reference-sandbox-event/"><code>SandboxEvent</code></a> for the discriminated-union shape. One subscription covers requests, committed writes, snapshot deliveries, suppressed re-evals, listener lifecycle, and reset / dispose boundaries. Filter on <code>event.kind</code> to recover individual streams; see the <a href="../pyric-sandbox-reference-sandbox-event/#filter-cookbook">filter cookbook</a>.</p>
+<p>Survives <code>sandbox.reset()</code>. The registry lives on the sandbox, not on the underlying environment, so the env swap doesn’t invalidate live subscribers. A <code>session_boundary</code> event with <code>phase: 'reset'</code> fires immediately before the swap so consumers can segment a persisted stream.</p>
+<p>Returns an unsubscribe function. Listener throws (sync) and async-promise rejections are swallowed so a faulty subscriber can’t change rule semantics, hide other events, or crash the process via <code>unhandledRejection</code>.</p>
+<h3 id="history"><code>history()</code></h3>
+<p>Every <a href="../pyric-sandbox-reference-sandbox-event/"><code>SandboxEvent</code></a> this sandbox has emitted since init or the last <code>reset()</code>. Returns a defensive copy; mutating the result doesn’t affect future calls.</p>
+<p>Unlike <code>onEvent</code>, which is a live stream from the moment of subscribe, <code>history()</code> returns <em>every</em> event the sandbox has seen. Use it for:</p>
+<ul>
+<li><strong>Replay</strong>: hand the array to <code>replay(events, rules)</code> from <code>pyric/sandbox</code> and the engine re-issues every captured write against a fresh sandbox. See <a href="../pyric-sandbox-how-to-replay-events/">Replay a captured event stream</a>.</li>
+<li><strong>Late subscribers</strong>: consumers that load a saved session before subscribing read the full pre-subscribe history.</li>
+<li><strong>Snapshot-at-moment persistence</strong>: capture the array, persist it, hand it back to <code>replay()</code> later.</li>
+</ul>
+<p><code>reset()</code> emits a closing <code>session_boundary</code> event, then clears the internal history. Consumers that snapshotted <em>before</em> the reset retain the boundary as the final entry. <code>dispose()</code> leaves the boundary as the final entry and doesn’t clear (the sandbox is dead either way).</p>
+<p>v1 doesn’t cap the history. Long-running sandboxes accumulate; snapshot + <code>reset()</code> to roll over if memory becomes an issue.</p>
+<h3 id="admin"><code>admin</code></h3>
+<p>Rule-bypass reads for test assertions. See <a href="../pyric-sandbox-reference-snapshot-and-admin/"><code>SandboxSnapshot</code> and admin reads</a>. Surfaced only on the root sandbox. Admin reads are identity-agnostic, so presenting them on a context (which exists to carry identity) is conceptually muddled.</p>
+<h3 id="reset"><code>reset()</code></h3>
+<p>Wipe data, rules, and any service-specific configuration. Replaces the underlying environment with a fresh one.</p>
+<p>Snapshot listeners on the OLD environment are dropped at the swap. Their target docs have been wiped, so they can’t survive. <code>onEvent</code> subscribers DO survive: the registry lives on the sandbox itself, and a <code>session_boundary</code> event with <code>phase: 'reset'</code> fires before the swap so observers know the rollover happened. Existing <code>SandboxContext</code>s continue to work. Their sandbox reference is stable; subsequent operations resolve to the new environment.</p>
+<h3 id="dispose"><code>dispose()</code></h3>
+<p>Drop listener registries on this sandbox’s environment without replacing it. Use this when you’re about to discard the sandbox itself. Idempotent. Does not touch data.</p>
+<h3 id="snapshot"><code>snapshot()</code></h3>
+<p>Capture a typed snapshot of every service’s state. v1 carries only <code>firestore</code>; future services add their own keys.</p>
+<h2 id="sandboxcontext"><code>SandboxContext</code></h2>
+<pre class="astro-code one-dark-pro" style="background-color:#282c34;color:#abb2bf; overflow-x: auto;" tabindex="0" data-language="ts"><code><span class="line"><span style="color:#C678DD">interface</span><span style="color:#E5C07B"> SandboxContext</span><span style="color:#ABB2BF"> {</span></span>
+<span class="line"><span style="color:#C678DD">  readonly</span><span style="color:#E06C75"> sandbox</span><span style="color:#ABB2BF">: </span><span style="color:#E5C07B">Sandbox</span><span style="color:#ABB2BF">;</span></span>
+<span class="line"><span style="color:#C678DD">  readonly</span><span style="color:#E06C75"> auth</span><span style="color:#ABB2BF">: </span><span style="color:#E5C07B">AuthState</span><span style="color:#ABB2BF">;</span></span>
+<span class="line"><span style="color:#61AFEF">  withAuth</span><span style="color:#ABB2BF">(</span><span style="color:#E06C75;font-style:italic">auth</span><span style="color:#ABB2BF">: </span><span style="color:#E5C07B">AuthState</span><span style="color:#ABB2BF">): </span><span style="color:#E5C07B">SandboxContext</span><span style="color:#ABB2BF">;</span></span>
+<span class="line"><span style="color:#ABB2BF">}</span></span></code></pre>
+<p>A <code>(sandbox, auth)</code> pair. Cheap to create, immutable, freely shareable. Service factories require this; passing a bare <code>Sandbox</code> is a type error.</p>
+<p>Many contexts can coexist for one sandbox. Data is shared; rules evaluate per-context under the context’s auth identity.</p>
+<h3 id="chaining">Chaining</h3>
+<pre class="astro-code one-dark-pro" style="background-color:#282c34;color:#abb2bf; overflow-x: auto;" tabindex="0" data-language="ts"><code><span class="line"><span style="color:#C678DD">const</span><span style="color:#E5C07B"> adminCtx</span><span style="color:#56B6C2"> =</span><span style="color:#E5C07B"> sandbox</span><span style="color:#ABB2BF">.</span><span style="color:#61AFEF">withAuth</span><span style="color:#ABB2BF">({ </span><span style="color:#E06C75">uid</span><span style="color:#ABB2BF">: </span><span style="color:#98C379">'admin'</span><span style="color:#ABB2BF">, </span><span style="color:#E06C75">token</span><span style="color:#ABB2BF">: { </span><span style="color:#E06C75">admin</span><span style="color:#ABB2BF">: </span><span style="color:#D19A66">true</span><span style="color:#ABB2BF"> } });</span></span>
+<span class="line"><span style="color:#C678DD">const</span><span style="color:#E5C07B"> userCtx</span><span style="color:#56B6C2"> =</span><span style="color:#E5C07B"> adminCtx</span><span style="color:#ABB2BF">.</span><span style="color:#61AFEF">withAuth</span><span style="color:#ABB2BF">({ </span><span style="color:#E06C75">uid</span><span style="color:#ABB2BF">: </span><span style="color:#98C379">'alice'</span><span style="color:#ABB2BF"> });</span></span></code></pre>
+<p><code>SandboxContext.withAuth</code> <strong>replaces</strong> auth, it does not merge. The new context carries only the new auth.</p>
+<h2 id="authstate"><code>AuthState</code></h2>
+<pre class="astro-code one-dark-pro" style="background-color:#282c34;color:#abb2bf; overflow-x: auto;" tabindex="0" data-language="ts"><code><span class="line"><span style="color:#C678DD">type</span><span style="color:#E5C07B"> AuthState</span><span style="color:#56B6C2"> =</span></span>
+<span class="line"><span style="color:#ABB2BF">  | { </span><span style="color:#E06C75">uid</span><span style="color:#ABB2BF">: </span><span style="color:#E5C07B">string</span><span style="color:#ABB2BF">; </span><span style="color:#E06C75">token</span><span style="color:#C678DD">?</span><span style="color:#ABB2BF">: </span><span style="color:#E5C07B">Record</span><span style="color:#ABB2BF">&#x3C;</span><span style="color:#E5C07B">string</span><span style="color:#ABB2BF">, </span><span style="color:#E5C07B">unknown</span><span style="color:#ABB2BF">> }</span></span>
+<span class="line"><span style="color:#ABB2BF">  | </span><span style="color:#E5C07B">null</span><span style="color:#ABB2BF">;</span></span></code></pre>
+<ul>
+<li><code>null</code> → unauthenticated; <code>request.auth</code> evaluates to <code>null</code> in rules.</li>
+<li><code>{ uid }</code> → authenticated; <code>request.auth.uid</code> carries the value.</li>
+<li><code>{ uid, token }</code> → authenticated with custom claims; <code>request.auth.token.&#x3C;key></code> carries each entry.</li>
+</ul>
+<p>The same shape feeds the rules simulator’s <code>TestCase.auth</code> field (<code>pyric/rules</code>), so test data written against one surface works with the other.</p>
+<h2 id="lifecycle-in-pictures">Lifecycle in pictures</h2>
+<pre class="astro-code one-dark-pro" style="background-color:#282c34;color:#abb2bf; overflow-x: auto;" tabindex="0" data-language="plaintext"><code><span class="line"><span>initializeSandbox()</span></span>
+<span class="line"><span>       │</span></span>
+<span class="line"><span>       ▼</span></span>
+<span class="line"><span>   ┌───────┐  withAuth({uid: 'alice'})    ┌─────────────┐</span></span>
+<span class="line"><span>   │       │ ───────────────────────────▶ │ ctx (alice) │ ──▶ getFirestore(ctx) ──▶ FirestoreHandle</span></span>
+<span class="line"><span>   │ Sand- │                              └─────────────┘</span></span>
+<span class="line"><span>   │ box   │  withAuth(null)              ┌─────────────┐</span></span>
+<span class="line"><span>   │       │ ───────────────────────────▶ │ ctx (anon)  │ ──▶ getFirestore(ctx) ──▶ FirestoreHandle</span></span>
+<span class="line"><span>   └───────┘                              └─────────────┘</span></span>
+<span class="line"><span>       │</span></span>
+<span class="line"><span>       │  reset() — swaps env, drops listeners; contexts still work</span></span>
+<span class="line"><span>       │</span></span>
+<span class="line"><span>       ▼</span></span>
+<span class="line"><span>   ┌───────┐</span></span>
+<span class="line"><span>   │ Sand- │  ← same sandbox, new env underneath</span></span>
+<span class="line"><span>   │ box   │</span></span>
+<span class="line"><span>   └───────┘</span></span></code></pre>
+<p>The sandbox object identity is stable for the life of the consumer. Only the underlying environment swaps. Contexts holding references to the sandbox don’t need to be re-derived after a <code>reset</code>.</p>  </article> </main> <aside class="doc-toc" aria-label="On this page"> <h2 class="doc-toc-heading">On this page</h2> <ul> <li data-depth="2"> <a href="#sandbox">Sandbox</a> </li><li data-depth="3"> <a href="#withauthauth">withAuth(auth)</a> </li><li data-depth="3"> <a href="#oneventcb">onEvent(cb)</a> </li><li data-depth="3"> <a href="#history">history()</a> </li><li data-depth="3"> <a href="#admin">admin</a> </li><li data-depth="3"> <a href="#reset">reset()</a> </li><li data-depth="3"> <a href="#dispose">dispose()</a> </li><li data-depth="3"> <a href="#snapshot">snapshot()</a> </li><li data-depth="2"> <a href="#sandboxcontext">SandboxContext</a> </li><li data-depth="3"> <a href="#chaining">Chaining</a> </li><li data-depth="2"> <a href="#authstate">AuthState</a> </li><li data-depth="2"> <a href="#lifecycle-in-pictures">Lifecycle in pictures</a> </li> </ul> </aside> </div> <script type="module">const a=document.querySelector("[data-api-symbol-filter]"),d=[...document.querySelectorAll("[data-api-symbol-group]")],n=document.querySelector("[data-api-symbol-empty]");a?.addEventListener("input",()=>{const t=a.value.trim().toLowerCase();let o=0;for(const i of d){let e=0;i.querySelectorAll("[data-api-symbol]").forEach(l=>{const r=!t||(l.dataset.apiSymbol??"").includes(t);l.hidden=!r,r&&e++}),i.hidden=e===0,o+=e}n&&(n.hidden=o>0)});</script> <script type="module">const s=new Map;document.querySelectorAll('.doc-toc a[href^="#"]').forEach(t=>s.set(decodeURIComponent(t.hash.slice(1)),t));if(s.size>0){const t=new Set,n=()=>{let o=null;for(const e of s.keys())if(t.has(e)){o=e;break}s.forEach((e,c)=>e.classList.toggle("active",c===o))},r=new IntersectionObserver(o=>{for(const e of o)e.isIntersecting?t.add(e.target.id):t.delete(e.target.id);n()},{rootMargin:"-72px 0px -60% 0px"});s.forEach((o,e)=>{const c=document.getElementById(e);c&&r.observe(c)})}</script> <script type="module">document.querySelector('.studio__nav [aria-current="page"]')?.scrollIntoView({block:"nearest",inline:"center"});</script> </body> </html>