@pyric/cli 0.1.0-alpha.9

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

@@ -0,0 +1,140 @@
+# `Sandbox`, `SandboxContext`, `AuthState`
+
+The three core types. Every other surface in the package builds on them.
+
+## `Sandbox`
+
+The data + rules + lifecycle handle.
+
+```ts
+interface Sandbox {
+  withAuth(auth: AuthState): SandboxContext;
+  onEvent(cb: (event: SandboxEvent) => void): () => void;
+  history(): SandboxEvent[];
+  readonly admin: SandboxAdmin;
+  reset(): void;
+  dispose(): void;
+  snapshot(): SandboxSnapshot;
+}
+```
+
+A `Sandbox` is **identity-agnostic**. It does not know who you are; that's what `SandboxContext` is for. The `Sandbox` only holds:
+
+- The current `LocalEnvironment` (documents, rules, listeners).
+- The `onEvent` subscriber registry (survives `reset()`).
+- Lifecycle methods (`reset`, `dispose`).
+
+Construct via `initializeSandbox()`. Custom implementations are not supported. Adapter packages use `instanceof` checks to route, and pass through `getInternalEnv` (from `pyric/sandbox/internal`) which throws on non-`SandboxImpl` handles.
+
+### `withAuth(auth)`
+
+Derive a `SandboxContext` bound to this sandbox under the given auth identity.
+
+```ts
+const aliceCtx = sandbox.withAuth({ uid: 'alice' });
+const adminCtx = sandbox.withAuth({ uid: 'admin', token: { role: 'admin' } });
+const anonCtx  = sandbox.withAuth(null);
+```
+
+`undefined` is rejected: say `withAuth(null)` for anonymous explicitly so the call site is unambiguous. Empty UIDs are rejected. Non-object `token` is rejected. See the [error-handling notes](../pyric-sandbox-reference-error-codes/#invalid-argument) for the exact rules.
+
+### `onEvent(cb)`
+
+Subscribe to every observable event the sandbox emits. See [`SandboxEvent`](../pyric-sandbox-reference-sandbox-event/) for the discriminated-union shape. One subscription covers requests, committed writes, snapshot deliveries, suppressed re-evals, listener lifecycle, and reset / dispose boundaries. Filter on `event.kind` to recover individual streams; see the [filter cookbook](../pyric-sandbox-reference-sandbox-event/#filter-cookbook).
+
+Survives `sandbox.reset()`. The registry lives on the sandbox, not on the underlying environment, so the env swap doesn't invalidate live subscribers. A `session_boundary` event with `phase: 'reset'` fires immediately before the swap so consumers can segment a persisted stream.
+
+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 `unhandledRejection`.
+
+### `history()`
+
+Every [`SandboxEvent`](../pyric-sandbox-reference-sandbox-event/) this sandbox has emitted since init or the last `reset()`. Returns a defensive copy; mutating the result doesn't affect future calls.
+
+Unlike `onEvent`, which is a live stream from the moment of subscribe, `history()` returns *every* event the sandbox has seen. Use it for:
+
+- **Replay**: hand the array to `replay(events, rules)` from `pyric/sandbox` and the engine re-issues every captured write against a fresh sandbox. See [Replay a captured event stream](../pyric-sandbox-how-to-replay-events/).
+- **Late subscribers**: consumers that load a saved session before subscribing read the full pre-subscribe history.
+- **Snapshot-at-moment persistence**: capture the array, persist it, hand it back to `replay()` later.
+
+`reset()` emits a closing `session_boundary` event, then clears the internal history. Consumers that snapshotted *before* the reset retain the boundary as the final entry. `dispose()` leaves the boundary as the final entry and doesn't clear (the sandbox is dead either way).
+
+v1 doesn't cap the history. Long-running sandboxes accumulate; snapshot + `reset()` to roll over if memory becomes an issue.
+
+### `admin`
+
+Rule-bypass reads for test assertions. See [`SandboxSnapshot` and admin reads](../pyric-sandbox-reference-snapshot-and-admin/). 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.
+
+### `reset()`
+
+Wipe data, rules, and any service-specific configuration. Replaces the underlying environment with a fresh one.
+
+Snapshot listeners on the OLD environment are dropped at the swap. Their target docs have been wiped, so they can't survive. `onEvent` subscribers DO survive: the registry lives on the sandbox itself, and a `session_boundary` event with `phase: 'reset'` fires before the swap so observers know the rollover happened. Existing `SandboxContext`s continue to work. Their sandbox reference is stable; subsequent operations resolve to the new environment.
+
+### `dispose()`
+
+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.
+
+### `snapshot()`
+
+Capture a typed snapshot of every service's state. v1 carries only `firestore`; future services add their own keys.
+
+## `SandboxContext`
+
+```ts
+interface SandboxContext {
+  readonly sandbox: Sandbox;
+  readonly auth: AuthState;
+  withAuth(auth: AuthState): SandboxContext;
+}
+```
+
+A `(sandbox, auth)` pair. Cheap to create, immutable, freely shareable. Service factories require this; passing a bare `Sandbox` is a type error.
+
+Many contexts can coexist for one sandbox. Data is shared; rules evaluate per-context under the context's auth identity.
+
+### Chaining
+
+```ts
+const adminCtx = sandbox.withAuth({ uid: 'admin', token: { admin: true } });
+const userCtx = adminCtx.withAuth({ uid: 'alice' });
+```
+
+`SandboxContext.withAuth` **replaces** auth, it does not merge. The new context carries only the new auth.
+
+## `AuthState`
+
+```ts
+type AuthState =
+  | { uid: string; token?: Record<string, unknown> }
+  | null;
+```
+
+- `null` → unauthenticated; `request.auth` evaluates to `null` in rules.
+- `{ uid }` → authenticated; `request.auth.uid` carries the value.
+- `{ uid, token }` → authenticated with custom claims; `request.auth.token.<key>` carries each entry.
+
+The same shape feeds the rules simulator's `TestCase.auth` field (`pyric/rules`), so test data written against one surface works with the other.
+
+## Lifecycle in pictures
+
+```
+initializeSandbox()
+       │
+       ▼
+   ┌───────┐  withAuth({uid: 'alice'})    ┌─────────────┐
+   │       │ ───────────────────────────▶ │ ctx (alice) │ ──▶ getFirestore(ctx) ──▶ FirestoreHandle
+   │ Sand- │                              └─────────────┘
+   │ box   │  withAuth(null)              ┌─────────────┐
+   │       │ ───────────────────────────▶ │ ctx (anon)  │ ──▶ getFirestore(ctx) ──▶ FirestoreHandle
+   └───────┘                              └─────────────┘
+       │
+       │  reset() — swaps env, drops listeners; contexts still work
+       │
+       ▼
+   ┌───────┐
+   │ Sand- │  ← same sandbox, new env underneath
+   │ box   │
+   └───────┘
+```
+
+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 `reset`.

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

@@ -0,0 +1,146 @@
+<!DOCTYPE html><html lang="en"> <head><meta charset="UTF-8"><meta name="viewport" content="width=device-width, initial-scale=1.0"><title>SandboxEvent · 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">SandboxEvent</span> </li> </ol> </nav>  <article class="prose">  <h1 id="sandboxevent"><code>SandboxEvent</code></h1>
+<p>The discriminated union <code>sandbox.onEvent(cb)</code> delivers. Filter on <code>kind</code> to
+recover any individual event family. The unified channel replaces the prior
+<code>onRequest</code> / <code>onDenial</code> / <code>onSnapshotError</code> triplet.</p>
+<h2 id="the-union">The union</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"> SandboxEvent</span><span style="color:#56B6C2"> =</span></span>
+<span class="line"><span style="color:#ABB2BF">  | </span><span style="color:#E5C07B">RequestEvent</span><span style="color:#7F848E;font-style:italic">              // kind: 'request'</span></span>
+<span class="line"><span style="color:#ABB2BF">  | </span><span style="color:#E5C07B">WriteSandboxEvent</span><span style="color:#7F848E;font-style:italic">         // kind: 'write'</span></span>
+<span class="line"><span style="color:#ABB2BF">  | </span><span style="color:#E5C07B">SnapshotDeliveryEvent</span><span style="color:#7F848E;font-style:italic">     // kind: 'snapshot_delivery'</span></span>
+<span class="line"><span style="color:#ABB2BF">  | </span><span style="color:#E5C07B">SnapshotSuppressedEvent</span><span style="color:#7F848E;font-style:italic">   // kind: 'snapshot_suppressed'</span></span>
+<span class="line"><span style="color:#ABB2BF">  | </span><span style="color:#E5C07B">ListenerLifecycleEvent</span><span style="color:#7F848E;font-style:italic">    // kind: 'listener_attach' | 'listener_detach' | 'listener_errored'</span></span>
+<span class="line"><span style="color:#ABB2BF">  | </span><span style="color:#E5C07B">SessionBoundaryEvent</span><span style="color:#ABB2BF">;     </span><span style="color:#7F848E;font-style:italic">// kind: 'session_boundary'</span></span></code></pre>
+<p>Every event carries <code>kind: &#x3C;discriminator></code>, <code>id: string</code> (unique within the sandbox process; React-list-key safe), and <code>at: number</code> (<code>Date.now()</code> at emission).</p>
+<h2 id="kind-request-every-evaluated-op"><code>kind: 'request'</code>: every evaluated op</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"> RequestEvent</span><span style="color:#ABB2BF"> {</span></span>
+<span class="line"><span style="color:#E06C75">  kind</span><span style="color:#ABB2BF">: </span><span style="color:#98C379">'request'</span><span style="color:#ABB2BF">;</span></span>
+<span class="line"><span style="color:#E06C75">  id</span><span style="color:#ABB2BF">: </span><span style="color:#E5C07B">string</span><span style="color:#ABB2BF">;</span></span>
+<span class="line"><span style="color:#E06C75">  at</span><span style="color:#ABB2BF">: </span><span style="color:#E5C07B">number</span><span style="color:#ABB2BF">;</span></span>
+<span class="line"><span style="color:#E06C75">  evalMs</span><span style="color:#ABB2BF">: </span><span style="color:#E5C07B">number</span><span style="color:#ABB2BF">;</span></span>
+<span class="line"><span style="color:#E06C75">  method</span><span style="color:#ABB2BF">: </span><span style="color:#98C379">'get'</span><span style="color:#ABB2BF"> | </span><span style="color:#98C379">'list'</span><span style="color:#ABB2BF"> | </span><span style="color:#98C379">'create'</span><span style="color:#ABB2BF"> | </span><span style="color:#98C379">'update'</span><span style="color:#ABB2BF"> | </span><span style="color:#98C379">'set'</span><span style="color:#ABB2BF"> | </span><span style="color:#98C379">'delete'</span><span style="color:#ABB2BF">;</span></span>
+<span class="line"><span style="color:#E06C75">  path</span><span style="color:#ABB2BF">: </span><span style="color:#E5C07B">string</span><span style="color:#ABB2BF">;</span></span>
+<span class="line"><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:#E06C75">  result</span><span style="color:#ABB2BF">: </span><span style="color:#98C379">'allow'</span><span style="color:#ABB2BF"> | </span><span style="color:#98C379">'deny'</span><span style="color:#ABB2BF"> | </span><span style="color:#98C379">'unsupported'</span><span style="color:#ABB2BF">;</span></span>
+<span class="line"><span style="color:#E06C75">  reasons</span><span style="color:#ABB2BF">: </span><span style="color:#E5C07B">string</span><span style="color:#ABB2BF">[];</span></span>
+<span class="line"><span style="color:#E06C75">  request</span><span style="color:#C678DD">?</span><span style="color:#ABB2BF">: { </span><span style="color:#E06C75">resourceData</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:#E06C75">  resourceBefore</span><span style="color:#C678DD">?</span><span style="color:#ABB2BF">: { </span><span style="color:#E06C75">data</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 style="color:#E5C07B">null</span><span style="color:#ABB2BF">; </span><span style="color:#E06C75">exists</span><span style="color:#ABB2BF">: </span><span style="color:#E5C07B">boolean</span><span style="color:#ABB2BF"> };</span></span>
+<span class="line"><span style="color:#E06C75">  resourceAfter</span><span style="color:#C678DD">?</span><span style="color:#ABB2BF">: { </span><span style="color:#E06C75">data</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 style="color:#E5C07B">null</span><span style="color:#ABB2BF">; </span><span style="color:#E06C75">exists</span><span style="color:#ABB2BF">: </span><span style="color:#E5C07B">boolean</span><span style="color:#ABB2BF"> };</span></span>
+<span class="line"><span style="color:#E06C75">  matchedRule</span><span style="color:#C678DD">?</span><span style="color:#ABB2BF">: { </span><span style="color:#E06C75">ruleIndex</span><span style="color:#ABB2BF">: </span><span style="color:#E5C07B">number</span><span style="color:#ABB2BF">; </span><span style="color:#E06C75">operations</span><span style="color:#ABB2BF">: </span><span style="color:#E5C07B">string</span><span style="color:#ABB2BF">[] };</span></span>
+<span class="line"><span style="color:#E06C75">  origin</span><span style="color:#ABB2BF">: </span><span style="color:#98C379">'user'</span><span style="color:#ABB2BF"> | </span><span style="color:#98C379">'listener'</span><span style="color:#ABB2BF"> | </span><span style="color:#98C379">'transaction'</span><span style="color:#ABB2BF"> | </span><span style="color:#98C379">'batch'</span><span style="color:#ABB2BF">;</span></span>
+<span class="line"><span style="color:#E06C75">  groupId</span><span style="color:#C678DD">?</span><span style="color:#ABB2BF">: </span><span style="color:#E5C07B">string</span><span style="color:#ABB2BF">;</span></span>
+<span class="line"><span style="color:#E06C75">  groupKind</span><span style="color:#C678DD">?</span><span style="color:#ABB2BF">: </span><span style="color:#98C379">'batch'</span><span style="color:#ABB2BF"> | </span><span style="color:#98C379">'transaction'</span><span style="color:#ABB2BF">;</span></span>
+<span class="line"><span style="color:#E06C75">  triggeredBy</span><span style="color:#C678DD">?</span><span style="color:#ABB2BF">: { </span><span style="color:#E06C75">method</span><span style="color:#ABB2BF">: </span><span style="color:#E5C07B">string</span><span style="color:#ABB2BF">; </span><span style="color:#E06C75">path</span><span style="color:#ABB2BF">: </span><span style="color:#E5C07B">string</span><span style="color:#ABB2BF"> };</span></span>
+<span class="line"><span style="color:#ABB2BF">}</span></span></code></pre>
+<p>Fires once per simulator-evaluated op. Denials surface here with <code>result: 'deny'</code>; the previous <code>DenialEvent</code> shape lives on as a derived field-projection. Filter <code>kind === 'request' &#x26;&#x26; result === 'deny'</code> to recover it.</p>
+<p><strong><code>method</code></strong> preserves the caller’s verb. <code>set</code> stays <code>'set'</code> (the rule engine maps it internally to <code>'create'</code> or <code>'update'</code> based on whether the doc exists; that mapping appears on <code>matchedRule.operations</code>).</p>
+<p><strong><code>origin</code></strong> disambiguates user-driven single ops from batch / transaction sub-ops and from listener re-evals. <code>groupId</code> is shared across the sub-ops of a single batch or transaction; <code>groupKind</code> tells you which.</p>
+<p><strong><code>triggeredBy</code></strong> populates on <code>origin: 'listener'</code> events when the listener re-eval was caused by a user op (write, batch, or transaction). Initial-fire events and <code>deployRules</code>-driven re-evals carry no <code>triggeredBy</code>.</p>
+<p><strong><code>evalMs</code></strong> is the wall-clock duration of <code>simulator.simulate(...)</code>. Sub-millisecond for trivial rules; a traffic-monitor validation probe measured ~95ms p99 on connect-four’s deep boolean chains.</p>
+<h2 id="kind-write-committed-writes-only"><code>kind: 'write'</code>: committed writes only</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"> WriteSandboxEvent</span><span style="color:#ABB2BF"> {</span></span>
+<span class="line"><span style="color:#E06C75">  kind</span><span style="color:#ABB2BF">: </span><span style="color:#98C379">'write'</span><span style="color:#ABB2BF">;</span></span>
+<span class="line"><span style="color:#E06C75">  id</span><span style="color:#ABB2BF">: </span><span style="color:#E5C07B">string</span><span style="color:#ABB2BF">;</span></span>
+<span class="line"><span style="color:#E06C75">  at</span><span style="color:#ABB2BF">: </span><span style="color:#E5C07B">number</span><span style="color:#ABB2BF">;</span></span>
+<span class="line"><span style="color:#E06C75">  method</span><span style="color:#ABB2BF">: </span><span style="color:#98C379">'create'</span><span style="color:#ABB2BF"> | </span><span style="color:#98C379">'update'</span><span style="color:#ABB2BF"> | </span><span style="color:#98C379">'set'</span><span style="color:#ABB2BF"> | </span><span style="color:#98C379">'delete'</span><span style="color:#ABB2BF">;</span></span>
+<span class="line"><span style="color:#E06C75">  path</span><span style="color:#ABB2BF">: </span><span style="color:#E5C07B">string</span><span style="color:#ABB2BF">;</span></span>
+<span class="line"><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:#E06C75">  data</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:#E06C75">  priorState</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 style="color:#E5C07B">null</span><span style="color:#ABB2BF">;</span></span>
+<span class="line"><span style="color:#E06C75">  nextState</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 style="color:#E5C07B">null</span><span style="color:#ABB2BF">;</span></span>
+<span class="line"><span style="color:#E06C75">  groupId</span><span style="color:#C678DD">?</span><span style="color:#ABB2BF">: </span><span style="color:#E5C07B">string</span><span style="color:#ABB2BF">;</span></span>
+<span class="line"><span style="color:#E06C75">  groupKind</span><span style="color:#C678DD">?</span><span style="color:#ABB2BF">: </span><span style="color:#98C379">'batch'</span><span style="color:#ABB2BF"> | </span><span style="color:#98C379">'transaction'</span><span style="color:#ABB2BF">;</span></span>
+<span class="line"><span style="color:#E06C75">  sentinels</span><span style="color:#C678DD">?</span><span style="color:#ABB2BF">: </span><span style="color:#E5C07B">Array</span><span style="color:#ABB2BF">&#x3C;{ </span><span style="color:#E06C75">field</span><span style="color:#ABB2BF">: </span><span style="color:#E5C07B">string</span><span style="color:#ABB2BF">; </span><span style="color:#E06C75">kind</span><span style="color:#ABB2BF">: </span><span style="color:#98C379">'serverTimestamp'</span><span style="color:#ABB2BF"> | </span><span style="color:#98C379">'increment'</span><span style="color:#ABB2BF"> | </span><span style="color:#98C379">'arrayUnion'</span><span style="color:#ABB2BF"> | </span><span style="color:#98C379">'arrayRemove'</span><span style="color:#ABB2BF"> | </span><span style="color:#98C379">'delete'</span><span style="color:#ABB2BF"> }>;</span></span>
+<span class="line"><span style="color:#E06C75">  autoId</span><span style="color:#C678DD">?</span><span style="color:#ABB2BF">: </span><span style="color:#E5C07B">string</span><span style="color:#ABB2BF">;</span></span>
+<span class="line"><span style="color:#E06C75">  requestTime</span><span style="color:#ABB2BF">: { </span><span style="color:#E06C75">seconds</span><span style="color:#ABB2BF">: </span><span style="color:#E5C07B">number</span><span style="color:#ABB2BF">; </span><span style="color:#E06C75">nanoseconds</span><span style="color:#ABB2BF">: </span><span style="color:#E5C07B">number</span><span style="color:#ABB2BF"> };</span></span>
+<span class="line"><span style="color:#ABB2BF">}</span></span></code></pre>
+<p>Fires AFTER the corresponding <code>kind: 'request'</code> event for the same op, and ONLY for writes that the rule engine allowed AND the keyspace successfully applied. Denied or rolled-back writes don’t emit a write event. They surface as <code>kind: 'request' &#x26;&#x26; result: 'deny'</code> only.</p>
+<p><strong><code>data</code></strong> is the <strong>pre-resolution</strong> payload: the user’s intent. <code>FieldValue.*</code> sentinels are preserved as their marker shapes (<code>{ __type: 'serverTimestamp' }</code>, etc.); plain values pass through unchanged. The replay engine re-resolves the markers against a fresh sandbox so <code>pinRequestTime: false</code> actually drifts and <code>pinRequestTime: true</code> matches capture. Absent on <code>delete</code>. The materialized values the keyspace applied live on <code>nextState</code>.</p>
+<p><strong><code>priorState</code></strong> / <strong><code>nextState</code></strong> are full <strong>post-resolution</strong> doc snapshots, actual stored state. <code>null</code> when the doc is absent. Use these for diff rendering, undo, or forensic logging.</p>
+<p><strong><code>sentinels</code></strong> is a flat index of the markers in <code>data</code>, keyed by field path (dotted with bracket-indices, <code>a.b[0].c</code>). Redundant with <code>data</code> (you could walk it yourself), but cheap to consume and emitted unconditionally when sentinels are present. Absent when the write had none.</p>
+<p><strong><code>autoId</code></strong> is the minted document ID (the path’s last segment) when the write came from <code>collection.add()</code> / <code>LocalEnvironment.createWithAutoId</code>. The replay engine aliases this path to a fresh mint rather than reusing the original ID. Absent on explicit-ID writes.</p>
+<p><strong><code>requestTime</code></strong> pins the <code>request.time</code> the rule engine evaluated against. The shape mirrors the Firestore Web SDK Timestamp (<code>{ seconds, nanoseconds }</code>). Required. The replay engine re-issues this exact value when re-resolving <code>serverTimestamp()</code> sentinels so resolved fields are bit-identical on replay; rules that branch on <code>request.time</code> evaluate identically. Within a batch or transaction, all sub-ops share the same <code>requestTime</code>.</p>
+<h2 id="kind-snapshot_delivery-listener-callback-fired"><code>kind: 'snapshot_delivery'</code>: listener callback fired</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"> SnapshotDeliveryEvent</span><span style="color:#ABB2BF"> {</span></span>
+<span class="line"><span style="color:#E06C75">  kind</span><span style="color:#ABB2BF">: </span><span style="color:#98C379">'snapshot_delivery'</span><span style="color:#ABB2BF">;</span></span>
+<span class="line"><span style="color:#E06C75">  id</span><span style="color:#ABB2BF">: </span><span style="color:#E5C07B">string</span><span style="color:#ABB2BF">;</span></span>
+<span class="line"><span style="color:#E06C75">  at</span><span style="color:#ABB2BF">: </span><span style="color:#E5C07B">number</span><span style="color:#ABB2BF">;</span></span>
+<span class="line"><span style="color:#E06C75">  listenerId</span><span style="color:#ABB2BF">: </span><span style="color:#E5C07B">string</span><span style="color:#ABB2BF">;</span></span>
+<span class="line"><span style="color:#E06C75">  target</span><span style="color:#ABB2BF">: { </span><span style="color:#E06C75">kind</span><span style="color:#ABB2BF">: </span><span style="color:#98C379">'doc'</span><span style="color:#ABB2BF">; </span><span style="color:#E06C75">path</span><span style="color:#ABB2BF">: </span><span style="color:#E5C07B">string</span><span style="color:#ABB2BF"> } | { </span><span style="color:#E06C75">kind</span><span style="color:#ABB2BF">: </span><span style="color:#98C379">'query'</span><span style="color:#ABB2BF">; </span><span style="color:#E06C75">collection</span><span style="color:#ABB2BF">: </span><span style="color:#E5C07B">string</span><span style="color:#ABB2BF"> };</span></span>
+<span class="line"><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:#E06C75">  addedCount</span><span style="color:#ABB2BF">: </span><span style="color:#E5C07B">number</span><span style="color:#ABB2BF">;</span></span>
+<span class="line"><span style="color:#E06C75">  modifiedCount</span><span style="color:#ABB2BF">: </span><span style="color:#E5C07B">number</span><span style="color:#ABB2BF">;</span></span>
+<span class="line"><span style="color:#E06C75">  removedCount</span><span style="color:#ABB2BF">: </span><span style="color:#E5C07B">number</span><span style="color:#ABB2BF">;</span></span>
+<span class="line"><span style="color:#E06C75">  size</span><span style="color:#ABB2BF">: </span><span style="color:#E5C07B">number</span><span style="color:#ABB2BF">;</span></span>
+<span class="line"><span style="color:#E06C75">  sample</span><span style="color:#C678DD">?</span><span style="color:#ABB2BF">: {</span></span>
+<span class="line"><span style="color:#E06C75">    docs</span><span style="color:#ABB2BF">: </span><span style="color:#E5C07B">Array</span><span style="color:#ABB2BF">&#x3C;{ </span><span style="color:#E06C75">path</span><span style="color:#ABB2BF">: </span><span style="color:#E5C07B">string</span><span style="color:#ABB2BF">; </span><span style="color:#E06C75">data</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 style="color:#E5C07B">null</span><span style="color:#ABB2BF"> }>;</span></span>
+<span class="line"><span style="color:#ABB2BF">  };</span></span>
+<span class="line"><span style="color:#E06C75">  triggeredBy</span><span style="color:#C678DD">?</span><span style="color:#ABB2BF">: { </span><span style="color:#E06C75">method</span><span style="color:#ABB2BF">: </span><span style="color:#E5C07B">string</span><span style="color:#ABB2BF">; </span><span style="color:#E06C75">path</span><span style="color:#ABB2BF">: </span><span style="color:#E5C07B">string</span><span style="color:#ABB2BF"> };</span></span>
+<span class="line"><span style="color:#ABB2BF">}</span></span></code></pre>
+<p>Fires AFTER the user callback runs, corresponding 1:1 with actual snapshot deliveries.</p>
+<p><strong><code>addedCount</code> + <code>modifiedCount</code> + <code>removedCount</code></strong> match <code>QuerySnapshot.docChanges()</code>. Doc-target listeners report exactly one of (added=1, removed=1, modified=1) per fire. Query-target listeners can report any combination; the initial fire surfaces every doc as <code>added</code>.</p>
+<p><strong><code>size</code></strong> is the doc count surfaced to the listener: <code>1</code> (exists) / <code>0</code> (deleted) for doc-target, <code>n</code> for query-target.</p>
+<p><strong><code>sample.docs</code></strong> carries the docs as the user callback received them, serialization-ready. Consumers truncate before persisting if scenarios produce large snapshots; the sandbox doesn’t truncate itself.</p>
+<p><strong><code>triggeredBy</code></strong> absent on initial fire (no user op caused it) and on <code>deployRules</code>-driven re-evals.</p>
+<h2 id="kind-snapshot_suppressed-re-eval-ran-but-didnt-deliver"><code>kind: 'snapshot_suppressed'</code>: re-eval ran but didn’t deliver</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"> SnapshotSuppressedEvent</span><span style="color:#ABB2BF"> {</span></span>
+<span class="line"><span style="color:#E06C75">  kind</span><span style="color:#ABB2BF">: </span><span style="color:#98C379">'snapshot_suppressed'</span><span style="color:#ABB2BF">;</span></span>
+<span class="line"><span style="color:#E06C75">  id</span><span style="color:#ABB2BF">: </span><span style="color:#E5C07B">string</span><span style="color:#ABB2BF">;</span></span>
+<span class="line"><span style="color:#E06C75">  at</span><span style="color:#ABB2BF">: </span><span style="color:#E5C07B">number</span><span style="color:#ABB2BF">;</span></span>
+<span class="line"><span style="color:#E06C75">  listenerId</span><span style="color:#ABB2BF">: </span><span style="color:#E5C07B">string</span><span style="color:#ABB2BF">;</span></span>
+<span class="line"><span style="color:#E06C75">  target</span><span style="color:#ABB2BF">: { </span><span style="color:#E06C75">kind</span><span style="color:#ABB2BF">: </span><span style="color:#98C379">'doc'</span><span style="color:#ABB2BF">; </span><span style="color:#E06C75">path</span><span style="color:#ABB2BF">: </span><span style="color:#E5C07B">string</span><span style="color:#ABB2BF"> } | { </span><span style="color:#E06C75">kind</span><span style="color:#ABB2BF">: </span><span style="color:#98C379">'query'</span><span style="color:#ABB2BF">; </span><span style="color:#E06C75">collection</span><span style="color:#ABB2BF">: </span><span style="color:#E5C07B">string</span><span style="color:#ABB2BF"> };</span></span>
+<span class="line"><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:#E06C75">  reason</span><span style="color:#ABB2BF">: </span><span style="color:#98C379">'no-op'</span><span style="color:#ABB2BF">;</span></span>
+<span class="line"><span style="color:#E06C75">  triggeredBy</span><span style="color:#C678DD">?</span><span style="color:#ABB2BF">: { </span><span style="color:#E06C75">method</span><span style="color:#ABB2BF">: </span><span style="color:#E5C07B">string</span><span style="color:#ABB2BF">; </span><span style="color:#E06C75">path</span><span style="color:#ABB2BF">: </span><span style="color:#E5C07B">string</span><span style="color:#ABB2BF"> };</span></span>
+<span class="line"><span style="color:#ABB2BF">}</span></span></code></pre>
+<p>Fires when a listener wakes up on a write but the diff against the prior snapshot finds nothing observable changed (the no-op suppression). Useful for “why didn’t my listener fire” debugging.</p>
+<p><strong><code>reason</code></strong> is <code>'no-op'</code> in v1. The discriminator exists so future suppression sources (auth changes, rules changes mid-listen) can land without reshape.</p>
+<h2 id="kind-listener_attach--listener_detach--listener_errored"><code>kind: 'listener_attach' | 'listener_detach' | 'listener_errored'</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"> ListenerLifecycleEvent</span><span style="color:#ABB2BF"> {</span></span>
+<span class="line"><span style="color:#E06C75">  kind</span><span style="color:#ABB2BF">: </span><span style="color:#98C379">'listener_attach'</span><span style="color:#ABB2BF"> | </span><span style="color:#98C379">'listener_detach'</span><span style="color:#ABB2BF"> | </span><span style="color:#98C379">'listener_errored'</span><span style="color:#ABB2BF">;</span></span>
+<span class="line"><span style="color:#E06C75">  id</span><span style="color:#ABB2BF">: </span><span style="color:#E5C07B">string</span><span style="color:#ABB2BF">;</span></span>
+<span class="line"><span style="color:#E06C75">  at</span><span style="color:#ABB2BF">: </span><span style="color:#E5C07B">number</span><span style="color:#ABB2BF">;</span></span>
+<span class="line"><span style="color:#E06C75">  listenerId</span><span style="color:#ABB2BF">: </span><span style="color:#E5C07B">string</span><span style="color:#ABB2BF">;</span></span>
+<span class="line"><span style="color:#E06C75">  target</span><span style="color:#ABB2BF">: { </span><span style="color:#E06C75">kind</span><span style="color:#ABB2BF">: </span><span style="color:#98C379">'doc'</span><span style="color:#ABB2BF">; </span><span style="color:#E06C75">path</span><span style="color:#ABB2BF">: </span><span style="color:#E5C07B">string</span><span style="color:#ABB2BF"> } | { </span><span style="color:#E06C75">kind</span><span style="color:#ABB2BF">: </span><span style="color:#98C379">'query'</span><span style="color:#ABB2BF">; </span><span style="color:#E06C75">collection</span><span style="color:#ABB2BF">: </span><span style="color:#E5C07B">string</span><span style="color:#ABB2BF"> };</span></span>
+<span class="line"><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:#E06C75">  error</span><span style="color:#C678DD">?</span><span style="color:#ABB2BF">: {</span></span>
+<span class="line"><span style="color:#E06C75">    code</span><span style="color:#ABB2BF">: </span><span style="color:#98C379">'permission-denied'</span><span style="color:#ABB2BF">;</span></span>
+<span class="line"><span style="color:#E06C75">    message</span><span style="color:#ABB2BF">: </span><span style="color:#E5C07B">string</span><span style="color:#ABB2BF">;</span></span>
+<span class="line"><span style="color:#E06C75">    reasons</span><span style="color:#C678DD">?</span><span style="color:#ABB2BF">: </span><span style="color:#E5C07B">string</span><span style="color:#ABB2BF">[];</span></span>
+<span class="line"><span style="color:#ABB2BF">  };</span></span>
+<span class="line"><span style="color:#ABB2BF">}</span></span></code></pre>
+<p><strong><code>listener_attach</code></strong> fires once when <code>onSnapshot</code> registers a record, BEFORE the initial-snapshot delivery.</p>
+<p><strong><code>listener_detach</code></strong> fires once when the returned unsubscribe is called against a still-registered listener. Idempotent unsubscribes don’t double-emit. Listeners dropped by <code>sandbox.reset()</code> don’t emit detach; the <code>session_boundary</code> event covers the rollover.</p>
+<p><strong><code>listener_errored</code></strong> fires when a stream-level rule denial silently terminates the listener (initial-read denial, change-driven re-read denial, or <code>deployRules</code> flipping a listener allowed → denied). The listener stops delivering snapshots after this event and the user’s <code>errorCallback</code> fires once with the same error.</p>
+<p><strong><code>error</code></strong> is populated on <code>listener_errored</code> only. The shape mirrors what the previous <code>SnapshotErrorEvent</code> carried.</p>
+<h2 id="kind-session_boundary-reset--dispose"><code>kind: 'session_boundary'</code>: reset / dispose</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"> SessionBoundaryEvent</span><span style="color:#ABB2BF"> {</span></span>
+<span class="line"><span style="color:#E06C75">  kind</span><span style="color:#ABB2BF">: </span><span style="color:#98C379">'session_boundary'</span><span style="color:#ABB2BF">;</span></span>
+<span class="line"><span style="color:#E06C75">  id</span><span style="color:#ABB2BF">: </span><span style="color:#E5C07B">string</span><span style="color:#ABB2BF">;</span></span>
+<span class="line"><span style="color:#E06C75">  at</span><span style="color:#ABB2BF">: </span><span style="color:#E5C07B">number</span><span style="color:#ABB2BF">;</span></span>
+<span class="line"><span style="color:#E06C75">  phase</span><span style="color:#ABB2BF">: </span><span style="color:#98C379">'reset'</span><span style="color:#ABB2BF"> | </span><span style="color:#98C379">'dispose'</span><span style="color:#ABB2BF">;</span></span>
+<span class="line"><span style="color:#E06C75">  priorOpCount</span><span style="color:#ABB2BF">: </span><span style="color:#E5C07B">number</span><span style="color:#ABB2BF">;</span></span>
+<span class="line"><span style="color:#ABB2BF">}</span></span></code></pre>
+<p>Fires BEFORE the env swap on <code>sandbox.reset()</code> and BEFORE registry teardown on <code>sandbox.dispose()</code>. The subscription itself survives <code>reset()</code>; only <code>dispose()</code> clears it.</p>
+<p><strong><code>priorOpCount</code></strong> is the cumulative count of events emitted from this sandbox prior to the boundary. Useful for verifying a persisted stream’s segmentation against the sandbox’s own bookkeeping.</p>
+<h2 id="filter-cookbook">Filter cookbook</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:#7F848E;font-style:italic">// All denials (replaces the old onDenial channel).</span></span>
+<span class="line"><span style="color:#C678DD">const</span><span style="color:#61AFEF"> isDenial</span><span style="color:#56B6C2"> =</span><span style="color:#ABB2BF"> (</span><span style="color:#E06C75;font-style:italic">e</span><span style="color:#ABB2BF">: </span><span style="color:#E5C07B">SandboxEvent</span><span style="color:#ABB2BF">): </span><span style="color:#E06C75;font-style:italic">e</span><span style="color:#C678DD"> is</span><span style="color:#E5C07B"> RequestEvent</span><span style="color:#C678DD"> =></span></span>
+<span class="line"><span style="color:#E5C07B">  e</span><span style="color:#ABB2BF">.</span><span style="color:#E06C75">kind</span><span style="color:#56B6C2"> ===</span><span style="color:#98C379"> 'request'</span><span style="color:#56B6C2"> &#x26;&#x26;</span><span style="color:#E5C07B"> e</span><span style="color:#ABB2BF">.</span><span style="color:#E06C75">result</span><span style="color:#56B6C2"> ===</span><span style="color:#98C379"> 'deny'</span><span style="color:#ABB2BF">;</span></span>
+<span class="line"></span>
+<span class="line"><span style="color:#7F848E;font-style:italic">// Snapshot stream errors (replaces the old onSnapshotError channel).</span></span>
+<span class="line"><span style="color:#C678DD">const</span><span style="color:#61AFEF"> isStreamError</span><span style="color:#56B6C2"> =</span><span style="color:#ABB2BF"> (</span><span style="color:#E06C75;font-style:italic">e</span><span style="color:#ABB2BF">: </span><span style="color:#E5C07B">SandboxEvent</span><span style="color:#ABB2BF">): </span><span style="color:#E06C75;font-style:italic">e</span><span style="color:#C678DD"> is</span><span style="color:#E5C07B"> ListenerLifecycleEvent</span><span style="color:#C678DD"> =></span></span>
+<span class="line"><span style="color:#E5C07B">  e</span><span style="color:#ABB2BF">.</span><span style="color:#E06C75">kind</span><span style="color:#56B6C2"> ===</span><span style="color:#98C379"> 'listener_errored'</span><span style="color:#ABB2BF">;</span></span>
+<span class="line"></span>
+<span class="line"><span style="color:#7F848E;font-style:italic">// Every committed write (replaces tapping the internal EventLog).</span></span>
+<span class="line"><span style="color:#C678DD">const</span><span style="color:#61AFEF"> isCommittedWrite</span><span style="color:#56B6C2"> =</span><span style="color:#ABB2BF"> (</span><span style="color:#E06C75;font-style:italic">e</span><span style="color:#ABB2BF">: </span><span style="color:#E5C07B">SandboxEvent</span><span style="color:#ABB2BF">): </span><span style="color:#E06C75;font-style:italic">e</span><span style="color:#C678DD"> is</span><span style="color:#E5C07B"> WriteSandboxEvent</span><span style="color:#C678DD"> =></span></span>
+<span class="line"><span style="color:#E5C07B">  e</span><span style="color:#ABB2BF">.</span><span style="color:#E06C75">kind</span><span style="color:#56B6C2"> ===</span><span style="color:#98C379"> 'write'</span><span style="color:#ABB2BF">;</span></span>
+<span class="line"></span>
+<span class="line"><span style="color:#7F848E;font-style:italic">// Anything a listener delivered to user code.</span></span>
+<span class="line"><span style="color:#C678DD">const</span><span style="color:#61AFEF"> isLiveDelivery</span><span style="color:#56B6C2"> =</span><span style="color:#ABB2BF"> (</span><span style="color:#E06C75;font-style:italic">e</span><span style="color:#ABB2BF">: </span><span style="color:#E5C07B">SandboxEvent</span><span style="color:#ABB2BF">): </span><span style="color:#E06C75;font-style:italic">e</span><span style="color:#C678DD"> is</span><span style="color:#E5C07B"> SnapshotDeliveryEvent</span><span style="color:#C678DD"> =></span></span>
+<span class="line"><span style="color:#E5C07B">  e</span><span style="color:#ABB2BF">.</span><span style="color:#E06C75">kind</span><span style="color:#56B6C2"> ===</span><span style="color:#98C379"> 'snapshot_delivery'</span><span style="color:#ABB2BF">;</span></span></code></pre>
+<h2 id="see-also">See also</h2>
+<ul>
+<li><a href="../pyric-sandbox-how-to-observe-events/">Observe sandbox events</a>: usage patterns + subscriber contract.</li>
+<li><a href="../pyric-sandbox-reference-sandbox-and-context/"><code>Sandbox.onEvent</code></a>: the method docs.</li>
+<li>Design rationale: the reasoning for replacing the three-channel surface with one.</li>
+</ul>  </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="#the-union">The union</a> </li><li data-depth="2"> <a href="#kind-request-every-evaluated-op">kind: &#39;request&#39;: every evaluated op</a> </li><li data-depth="2"> <a href="#kind-write-committed-writes-only">kind: &#39;write&#39;: committed writes only</a> </li><li data-depth="2"> <a href="#kind-snapshot_delivery-listener-callback-fired">kind: &#39;snapshot_delivery&#39;: listener callback fired</a> </li><li data-depth="2"> <a href="#kind-snapshot_suppressed-re-eval-ran-but-didnt-deliver">kind: &#39;snapshot_suppressed&#39;: re-eval ran but didn’t deliver</a> </li><li data-depth="2"> <a href="#kind-listener_attach--listener_detach--listener_errored">kind: &#39;listener_attach&#39; | &#39;listener_detach&#39; | &#39;listener_errored&#39;</a> </li><li data-depth="2"> <a href="#kind-session_boundary-reset--dispose">kind: &#39;session_boundary&#39;: reset / dispose</a> </li><li data-depth="2"> <a href="#filter-cookbook">Filter cookbook</a> </li><li data-depth="2"> <a href="#see-also">See also</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>