@pyric/cli 0.1.0-alpha.9

package/dist/serve/docs-ui/docs/pyric-sandbox-explanation-identity-is-a-context.md

@@ -0,0 +1,110 @@
+# Identity is a context, not a sandbox
+
+The most-visible architectural decision in `pyric/sandbox` is that `Sandbox` does not carry an identity. To do anything as a user, you derive a `SandboxContext` via `sandbox.withAuth(...)`. This page explains why.
+
+## What the alternative would look like
+
+A simpler API exposes `auth` as a field on the sandbox:
+
+```ts
+// Hypothetical, not the actual API.
+const sandbox = initializeSandbox({ auth: { uid: 'alice' } });
+sandbox.firestore.collection('notes').doc('n1').set(...);  // runs as alice
+sandbox.setAuth({ uid: 'bob' });
+sandbox.firestore.collection('notes').doc('n1').get();     // runs as bob
+```
+
+This is closest to how the Firebase client SDK works: the client knows who you are because you signed in earlier. It's intuitive. So why didn't we ship it?
+
+## Three problems with auth-on-sandbox
+
+### 1. Multi-tenant tests need many identities, often simultaneously
+
+A test that asserts "alice can read her own note but not bob's" needs two identities live at the same time. With auth-on-sandbox, the test has to swap auth back and forth:
+
+```ts
+sandbox.setAuth({ uid: 'alice' });
+await sandbox.firestore.collection('notes').doc('alice-1').set({ ownerId: 'alice' });
+sandbox.setAuth({ uid: 'bob' });
+try { await sandbox.firestore.collection('notes').doc('alice-1').get(); } catch { /* expected */ }
+sandbox.setAuth({ uid: 'alice' });  // restore
+```
+
+This is tedious and error-prone. Forget to restore and the next operation runs as `bob` accidentally. With contexts, the same test is straightforward:
+
+```ts
+const aliceDb = getFirestore(sandbox.withAuth({ uid: 'alice' }));
+const bobDb = getFirestore(sandbox.withAuth({ uid: 'bob' }));
+
+await aliceDb.collection('notes').doc('alice-1').set({ ownerId: 'alice' });
+try { await bobDb.collection('notes').doc('alice-1').get(); } catch { /* expected */ }
+```
+
+Two named variables, two identities, no swapping. The test reads like the assertion it's making.
+
+### 2. Concurrent operations from different identities
+
+Two simultaneous writes from different users:
+
+```ts
+// With auth-on-sandbox — concurrent setAuth calls race.
+await Promise.all([
+  (async () => { sandbox.setAuth({ uid: 'alice' }); await write(); })(),
+  (async () => { sandbox.setAuth({ uid: 'bob' }); await write(); })(),
+]);
+```
+
+The behaviour depends on event-loop scheduling. The same code passes most runs and fails sometimes. With contexts:
+
+```ts
+await Promise.all([
+  aliceDb.collection('notes').doc('a1').set({ ... }),
+  bobDb.collection('notes').doc('b1').set({ ... }),
+]);
+```
+
+Each operation's identity is captured in the handle it was issued through. No race.
+
+### 3. Identity-agnostic operations should be obvious
+
+Admin reads, listener subscribers, `reset`, `dispose`, `snapshot`: none of these are tied to a user. With auth-on-sandbox, where do they live? On the sandbox, alongside the user-bound operations? That blurs the line. With contexts, the identity-agnostic surface is exactly what's on `Sandbox`; everything else (data operations) requires a context. A reader of the type signature can tell at a glance.
+
+## The mental model
+
+```
+Sandbox          ← data, rules, lifecycle. Identity-agnostic.
+   │
+   │  withAuth(auth)
+   ▼
+SandboxContext   ← (sandbox, auth) pair. Cheap, immutable.
+   │
+   │  getFirestore(ctx)
+   ▼
+FirestoreHandle  ← data-plane API. Operations evaluate under ctx.auth.
+```
+
+Three layers, each with one job. Operations that mutate data flow down the chain. Operations that don't (listener subscriptions, admin reads, lifecycle) live at the top.
+
+## What about per-operation auth overrides?
+
+We considered exposing `db.collection('x').doc('y').get({ auth: { uid: 'alice' } })` as an override. Rejected because:
+
+- The service handle's whole shape would need to change. Every method gets an optional `OperationOptions { auth?: AuthState }` parameter, multiplying the surface area.
+- The handle's binding to its context becomes a lie. "This handle is bound to alice, except when it isn't."
+- Composition gets harder. A function that takes a `FirestoreHandle` can no longer assume it knows whose identity its operations run under.
+
+"Derive a different context" is cheaper than any of those costs.
+
+## What about implicit fallback?
+
+A different option: let auth-less handles exist, and have them default to anonymous. `getFirestore(sandbox)` (no context) returns a handle that evaluates as `request.auth == null`.
+
+Rejected because the call site is then ambiguous about whether anonymous was intended or forgotten. Service factories require a `SandboxContext` (`getFirestore(sandbox.withAuth(null))` for anonymous) so the intent is on the page.
+
+The same reasoning applies to `withAuth(undefined)`: it throws instead of treating `undefined` as anonymous. Explicit `null` is the only way to say "anonymous on purpose".
+
+## Where this design came from
+
+This split was originally `AuthContext` (the data type) and `Sandbox` (with `auth` baked in). The rename to `AuthState` + `SandboxContext` happened during the multi-context redesign, motivated by exactly the scenarios above. The history is in the design rationale if you want the full discussion.
+
+The key insight: identity is something operations have, not something sandboxes have. A sandbox is a *place* with documents and rules. An operation is an *action* with an actor. The context is the bridge that carries the actor in.

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

@@ -0,0 +1,71 @@
+<!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>Explanation</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><code>pyric/sandbox</code> ships a second sub-path: <code>pyric/sandbox/internal</code>. The public entry stays narrow: <code>Sandbox</code>, <code>SandboxContext</code>, <code>SandboxError</code>, listener channels, lifecycle. Anything an adapter needs but a consumer shouldn’t reach for lives behind the <code>/internal</code> gate.</p>
+<p>This page explains the gate and what it implies for adapter authors.</p>
+<h2 id="whats-behind-the-gate">What’s behind the gate</h2>
+<p>The substrate’s runtime types: <code>LocalEnvironment</code>, <code>EventLog</code>, transaction primitives, sentinel converters, error translation helpers. Adapter packages (<code>pyric-admin</code>, <code>pyric/firestore</code>) consume these to translate user-facing SDK calls into substrate operations.</p>
+<p>The full list is documented in <a href="../pyric-sandbox-reference-internal-protocol/">The <code>/internal</code> adapter protocol</a>.</p>
+<h2 id="why-a-gate-at-all">Why a gate at all</h2>
+<p>Three reasons to hide a surface behind a sub-path:</p>
+<ol>
+<li><strong>Discourage application use.</strong> App code that imports from <code>/internal</code> is reaching past the public API. The path name is the warning.</li>
+<li><strong>Permit breakage between minor versions.</strong> The public API is semver-stable. <code>/internal</code> is not. Its shape evolves with the substrate’s needs.</li>
+<li><strong>Document the dependency direction.</strong> Adapters depend on <code>/internal</code>; the substrate doesn’t depend on adapters. The gate makes the direction visible.</li>
+</ol>
+<p>The gate is by convention, not enforcement. <code>pyric/sandbox/internal</code> is a regular subpath export. TypeScript will happily resolve it from application code. The conventional discouragement is the point. The type name, the path name, and the documentation all say “this is for adapter authors”. Authors who reach past it accept the breakage risk.</p>
+<h2 id="how-adapters-use-it">How adapters use it</h2>
+<p>A typical adapter does three things with <code>/internal</code>:</p>
+<h3 id="1-resolve-the-runtime-substrate">1. Resolve the runtime substrate</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 style="color:#E06C75">getInternalEnv</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>
+<span class="line"><span style="color:#C678DD">import</span><span style="color:#C678DD"> type</span><span style="color:#ABB2BF"> { </span><span style="color:#E06C75">SandboxContext</span><span style="color:#ABB2BF"> } </span><span style="color:#C678DD">from</span><span style="color:#98C379"> 'pyric/sandbox'</span><span style="color:#ABB2BF">;</span></span>
+<span class="line"></span>
+<span class="line"><span style="color:#C678DD">function</span><span style="color:#61AFEF"> getFirestore</span><span style="color:#ABB2BF">(</span><span style="color:#E06C75;font-style:italic">ctx</span><span style="color:#ABB2BF">: </span><span style="color:#E5C07B">SandboxContext</span><span style="color:#ABB2BF">): </span><span style="color:#E5C07B">FirestoreHandle</span><span style="color:#ABB2BF"> {</span></span>
+<span class="line"><span style="color:#C678DD">  const</span><span style="color:#E5C07B"> env</span><span style="color:#56B6C2"> =</span><span style="color:#61AFEF"> getInternalEnv</span><span style="color:#ABB2BF">(</span><span style="color:#E5C07B">ctx</span><span style="color:#ABB2BF">.</span><span style="color:#E06C75">sandbox</span><span style="color:#ABB2BF">);</span></span>
+<span class="line"><span style="color:#C678DD">  return</span><span style="color:#61AFEF"> buildHandleAroundEnv</span><span style="color:#ABB2BF">(</span><span style="color:#E06C75">env</span><span style="color:#ABB2BF">, </span><span style="color:#E5C07B">ctx</span><span style="color:#ABB2BF">.</span><span style="color:#E06C75">auth</span><span style="color:#ABB2BF">);</span></span>
+<span class="line"><span style="color:#ABB2BF">}</span></span></code></pre>
+<p><code>getInternalEnv</code> throws if the <code>Sandbox</code> wasn’t produced by <code>initializeSandbox</code>, so adapters can rely on it to reject malformed input early.</p>
+<h3 id="2-translate-user-calls-to-substrate-operations">2. Translate user calls to substrate operations</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:#C678DD"> type</span><span style="color:#ABB2BF"> { </span><span style="color:#E06C75">Operation</span><span style="color:#ABB2BF">, </span><span style="color:#E06C75">OperationResult</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>
+<span class="line"></span>
+<span class="line"><span style="color:#C678DD">async</span><span style="color:#C678DD"> function</span><span style="color:#61AFEF"> set</span><span style="color:#ABB2BF">(</span><span style="color:#E06C75;font-style:italic">handle</span><span style="color:#ABB2BF">, </span><span style="color:#E06C75;font-style:italic">path</span><span style="color:#ABB2BF">, </span><span style="color:#E06C75;font-style:italic">data</span><span style="color:#ABB2BF">) {</span></span>
+<span class="line"><span style="color:#C678DD">  const</span><span style="color:#E5C07B"> operation</span><span style="color:#ABB2BF">: </span><span style="color:#E5C07B">Operation</span><span style="color:#56B6C2"> =</span><span style="color:#ABB2BF"> {</span></span>
+<span class="line"><span style="color:#E06C75">    method</span><span style="color:#ABB2BF">: </span><span style="color:#E06C75">data</span><span style="color:#C678DD"> ?</span><span style="color:#98C379"> 'set'</span><span style="color:#C678DD"> :</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>
+<span class="line"><span style="color:#E06C75">    auth</span><span style="color:#ABB2BF">: </span><span style="color:#E5C07B">handle</span><span style="color:#ABB2BF">.</span><span style="color:#E06C75">auth</span><span style="color:#ABB2BF">,</span></span>
+<span class="line"><span style="color:#E06C75">    data</span><span style="color:#ABB2BF">,</span></span>
+<span class="line"><span style="color:#ABB2BF">  };</span></span>
+<span class="line"><span style="color:#C678DD">  const</span><span style="color:#E5C07B"> result</span><span style="color:#ABB2BF">: </span><span style="color:#E5C07B">OperationResult</span><span style="color:#56B6C2"> =</span><span style="color:#E5C07B"> handle</span><span style="color:#ABB2BF">.</span><span style="color:#E5C07B">env</span><span style="color:#ABB2BF">.</span><span style="color:#61AFEF">execute</span><span style="color:#ABB2BF">(</span><span style="color:#E06C75">operation</span><span style="color:#ABB2BF">);</span></span>
+<span class="line"><span style="color:#C678DD">  if</span><span style="color:#ABB2BF"> (</span><span style="color:#56B6C2">!</span><span style="color:#E5C07B">result</span><span style="color:#ABB2BF">.</span><span style="color:#E06C75">allowed</span><span style="color:#ABB2BF">) </span><span style="color:#C678DD">throw</span><span style="color:#61AFEF"> translateError</span><span style="color:#ABB2BF">(</span><span style="color:#E5C07B">result</span><span style="color:#ABB2BF">.</span><span style="color:#E06C75">error</span><span style="color:#ABB2BF">);</span></span>
+<span class="line"><span style="color:#C678DD">  return</span><span style="color:#E06C75"> result</span><span style="color:#ABB2BF">;</span></span>
+<span class="line"><span style="color:#ABB2BF">}</span></span></code></pre>
+<p>Operations are plain shapes. Each adapter writes its own translation logic: <code>pyric-admin</code> translates chainable calls, <code>pyric/firestore</code> translates modular function calls. Both produce <code>Operation</code> and consume <code>OperationResult</code>.</p>
+<h3 id="3-resolve-sentinels">3. Resolve sentinels</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 style="color:#E06C75">resolveValueTree</span><span style="color:#ABB2BF">, </span><span style="color:#E06C75">registerDefaultConverters</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>Sentinels (<code>FieldValue.increment</code>, <code>serverTimestamp</code>, <code>arrayUnion</code>) are values the substrate doesn’t store directly. They describe an operation on the current document. The adapter resolves them via <code>resolveValueTree(payload, env, method)</code> before handing the payload to <code>LocalEnvironment.execute</code>.</p>
+<h2 id="what-adapters-shouldnt-do">What adapters shouldn’t do</h2>
+<h3 id="treat-internal-as-a-stable-api-surface">Treat <code>/internal</code> as a stable API surface</h3>
+<p>The shape changes when the substrate’s needs change. Methods get renamed. Types get widened. New parameters appear. The package’s semver does not protect <code>/internal</code>.</p>
+<p>In practice, the surface has been stable for months at a time. The substrate isn’t churning. But “stable in practice” is not “stable by contract”. Adapter authors should pin to specific versions of <code>pyric/sandbox</code> and update deliberately.</p>
+<h3 id="add-business-logic-to-the-substrate">Add business logic to the substrate</h3>
+<p>If a piece of behaviour translates user intent (“interpret this dot-path update as a nested-map patch”, “merge this batch’s writes by collection”, “schedule this snapshot listener fire after the current micro-task”), it belongs in the adapter, not in <code>/internal</code>. The substrate stores documents and runs rules. Anything beyond that is adapter responsibility.</p>
+<p>This rule keeps the substrate small. Adapters can differ in their merge semantics, their fire timing, their reference identity model. All of that lives in the adapter, and the substrate doesn’t care.</p>
+<h3 id="import-from-internal-in-application-code">Import from <code>/internal</code> in application code</h3>
+<p>Application code uses <code>pyric-admin</code> or <code>pyric/firestore</code>. The reason is forward-compatibility: if a future minor release changes a <code>/internal</code> type, the adapter absorbs the change and the application doesn’t notice. Application code that imports from <code>/internal</code> becomes a breakage liability the next time the substrate evolves.</p>
+<p>If an application needs something an adapter doesn’t expose, the right move is to file a request on the adapter, not to reach into <code>/internal</code> and add the wrapping itself.</p>
+<h2 id="the-star-export-decision">The star-export decision</h2>
+<p>The <code>/internal</code> index uses <code>export * from '../firestore/local-environment.js'</code> and similar wildcards. The alternative is a hand-maintained named-export list.</p>
+<p>We picked stars because:</p>
+<ul>
+<li><code>pyric-admin</code> reaches in for a long tail of helper symbols (<code>DELETE_MARKER</code>, <code>KEEP</code>, <code>FIRESTORE_ERROR_CODES</code>, etc.). The list is dozens of entries.</li>
+<li>Keeping the named-export list in sync with the moved files’ actual exports creates maintenance churn. Every new export needs two changes.</li>
+<li>Star exports propagate automatically. Add a new export to a moved file, it appears at <code>pyric/sandbox/internal</code>.</li>
+</ul>
+<p>The downside is that adding a new public export in a moved file silently appears on <code>/internal</code> without an explicit decision. We accept that: anything in those files is intended to be reachable by adapters; the gate isn’t there to filter, it’s there to label the surface.</p>
+<h2 id="will-internal-ever-be-promoted">Will <code>/internal</code> ever be promoted?</h2>
+<p>When the multi-service architecture lands (Auth, RTDB, Storage all sharing one <code>LocalEnvironment</code>) the substrate’s surface will need to stabilise. At that point parts of <code>/internal</code> will likely be promoted to the public API, probably the parts adapters need most (<code>Operation</code>, <code>OperationResult</code>, sentinel conversion).</p>
+<p>Promotion will be deliberate. Each symbol that moves to the public API gets:</p>
+<ul>
+<li>A documented contract on the public reference page.</li>
+<li>Semver protection going forward.</li>
+<li>A removal from <code>/internal</code> (or kept as a re-export for adapter compatibility).</li>
+</ul>
+<p>Until then, <code>/internal</code> is the place where the protocol evolves.</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="#whats-behind-the-gate">What’s behind the gate</a> </li><li data-depth="2"> <a href="#why-a-gate-at-all">Why a gate at all</a> </li><li data-depth="2"> <a href="#how-adapters-use-it">How adapters use it</a> </li><li data-depth="3"> <a href="#1-resolve-the-runtime-substrate">1. Resolve the runtime substrate</a> </li><li data-depth="3"> <a href="#2-translate-user-calls-to-substrate-operations">2. Translate user calls to substrate operations</a> </li><li data-depth="3"> <a href="#3-resolve-sentinels">3. Resolve sentinels</a> </li><li data-depth="2"> <a href="#what-adapters-shouldnt-do">What adapters shouldn’t do</a> </li><li data-depth="3"> <a href="#treat-internal-as-a-stable-api-surface">Treat /internal as a stable API surface</a> </li><li data-depth="3"> <a href="#add-business-logic-to-the-substrate">Add business logic to the substrate</a> </li><li data-depth="3"> <a href="#import-from-internal-in-application-code">Import from /internal in application code</a> </li><li data-depth="2"> <a href="#the-star-export-decision">The star-export decision</a> </li><li data-depth="2"> <a href="#will-internal-ever-be-promoted">Will /internal ever be promoted?</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-explanation-internal-adapter-protocol.md

@@ -0,0 +1,111 @@
+# The `/internal` adapter protocol
+
+`pyric/sandbox` ships a second sub-path: `pyric/sandbox/internal`. The public entry stays narrow: `Sandbox`, `SandboxContext`, `SandboxError`, listener channels, lifecycle. Anything an adapter needs but a consumer shouldn't reach for lives behind the `/internal` gate.
+
+This page explains the gate and what it implies for adapter authors.
+
+## What's behind the gate
+
+The substrate's runtime types: `LocalEnvironment`, `EventLog`, transaction primitives, sentinel converters, error translation helpers. Adapter packages (`pyric-admin`, `pyric/firestore`) consume these to translate user-facing SDK calls into substrate operations.
+
+The full list is documented in [The `/internal` adapter protocol](../pyric-sandbox-reference-internal-protocol/).
+
+## Why a gate at all
+
+Three reasons to hide a surface behind a sub-path:
+
+1. **Discourage application use.** App code that imports from `/internal` is reaching past the public API. The path name is the warning.
+2. **Permit breakage between minor versions.** The public API is semver-stable. `/internal` is not. Its shape evolves with the substrate's needs.
+3. **Document the dependency direction.** Adapters depend on `/internal`; the substrate doesn't depend on adapters. The gate makes the direction visible.
+
+The gate is by convention, not enforcement. `pyric/sandbox/internal` is a regular subpath export. TypeScript will happily resolve it from application code. The conventional discouragement is the point. The type name, the path name, and the documentation all say "this is for adapter authors". Authors who reach past it accept the breakage risk.
+
+## How adapters use it
+
+A typical adapter does three things with `/internal`:
+
+### 1. Resolve the runtime substrate
+
+```ts
+import { getInternalEnv } from 'pyric/sandbox/internal';
+import type { SandboxContext } from 'pyric/sandbox';
+
+function getFirestore(ctx: SandboxContext): FirestoreHandle {
+  const env = getInternalEnv(ctx.sandbox);
+  return buildHandleAroundEnv(env, ctx.auth);
+}
+```
+
+`getInternalEnv` throws if the `Sandbox` wasn't produced by `initializeSandbox`, so adapters can rely on it to reject malformed input early.
+
+### 2. Translate user calls to substrate operations
+
+```ts
+import type { Operation, OperationResult } from 'pyric/sandbox/internal';
+
+async function set(handle, path, data) {
+  const operation: Operation = {
+    method: data ? 'set' : 'delete',
+    path,
+    auth: handle.auth,
+    data,
+  };
+  const result: OperationResult = handle.env.execute(operation);
+  if (!result.allowed) throw translateError(result.error);
+  return result;
+}
+```
+
+Operations are plain shapes. Each adapter writes its own translation logic: `pyric-admin` translates chainable calls, `pyric/firestore` translates modular function calls. Both produce `Operation` and consume `OperationResult`.
+
+### 3. Resolve sentinels
+
+```ts
+import { resolveValueTree, registerDefaultConverters } from 'pyric/sandbox/internal';
+```
+
+Sentinels (`FieldValue.increment`, `serverTimestamp`, `arrayUnion`) are values the substrate doesn't store directly. They describe an operation on the current document. The adapter resolves them via `resolveValueTree(payload, env, method)` before handing the payload to `LocalEnvironment.execute`.
+
+## What adapters shouldn't do
+
+### Treat `/internal` as a stable API surface
+
+The shape changes when the substrate's needs change. Methods get renamed. Types get widened. New parameters appear. The package's semver does not protect `/internal`.
+
+In practice, the surface has been stable for months at a time. The substrate isn't churning. But "stable in practice" is not "stable by contract". Adapter authors should pin to specific versions of `pyric/sandbox` and update deliberately.
+
+### Add business logic to the substrate
+
+If a piece of behaviour translates user intent ("interpret this dot-path update as a nested-map patch", "merge this batch's writes by collection", "schedule this snapshot listener fire after the current micro-task"), it belongs in the adapter, not in `/internal`. The substrate stores documents and runs rules. Anything beyond that is adapter responsibility.
+
+This rule keeps the substrate small. Adapters can differ in their merge semantics, their fire timing, their reference identity model. All of that lives in the adapter, and the substrate doesn't care.
+
+### Import from `/internal` in application code
+
+Application code uses `pyric-admin` or `pyric/firestore`. The reason is forward-compatibility: if a future minor release changes a `/internal` type, the adapter absorbs the change and the application doesn't notice. Application code that imports from `/internal` becomes a breakage liability the next time the substrate evolves.
+
+If an application needs something an adapter doesn't expose, the right move is to file a request on the adapter, not to reach into `/internal` and add the wrapping itself.
+
+## The star-export decision
+
+The `/internal` index uses `export * from '../firestore/local-environment.js'` and similar wildcards. The alternative is a hand-maintained named-export list.
+
+We picked stars because:
+
+- `pyric-admin` reaches in for a long tail of helper symbols (`DELETE_MARKER`, `KEEP`, `FIRESTORE_ERROR_CODES`, etc.). The list is dozens of entries.
+- Keeping the named-export list in sync with the moved files' actual exports creates maintenance churn. Every new export needs two changes.
+- Star exports propagate automatically. Add a new export to a moved file, it appears at `pyric/sandbox/internal`.
+
+The downside is that adding a new public export in a moved file silently appears on `/internal` without an explicit decision. We accept that: anything in those files is intended to be reachable by adapters; the gate isn't there to filter, it's there to label the surface.
+
+## Will `/internal` ever be promoted?
+
+When the multi-service architecture lands (Auth, RTDB, Storage all sharing one `LocalEnvironment`) the substrate's surface will need to stabilise. At that point parts of `/internal` will likely be promoted to the public API, probably the parts adapters need most (`Operation`, `OperationResult`, sentinel conversion).
+
+Promotion will be deliberate. Each symbol that moves to the public API gets:
+
+- A documented contract on the public reference page.
+- Semver protection going forward.
+- A removal from `/internal` (or kept as a re-export for adapter compatibility).
+
+Until then, `/internal` is the place where the protocol evolves.

package/dist/serve/docs-ui/docs/pyric-sandbox-explanation-listener-re-evaluation/index.html

@@ -0,0 +1,56 @@
+<!DOCTYPE html><html lang="en"> <head><meta charset="UTF-8"><meta name="viewport" content="width=device-width, initial-scale=1.0"><title>Listener re-evaluation on deployRules · 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>Explanation</span> </li><li> <span class="docs-breadcrumbs-sep" aria-hidden="true">/</span> <span aria-current="page">Listener re-evaluation</span> </li> </ol> </nav>  <article class="prose">  <h1 id="listener-re-evaluation-on-deployrules">Listener re-evaluation on <code>deployRules</code></h1>
+<p>A snapshot listener attached before a <code>deployRules</code> call gets re-evaluated under the new rules. This is a deliberate departure from production Firestore behaviour. The reasoning matters; this page lays it out.</p>
+<h2 id="what-production-does">What production does</h2>
+<p>In production, a <code>cloud.firestore</code> ruleset change does <strong>not</strong> affect listeners that are already attached. The listener keeps using whatever rules were in force when it was created. Subsequent <code>deployRules</code> calls roll out for new listeners and new operations, but live streams continue with their original gating until the consumer detaches and re-attaches.</p>
+<p>This matches how production thinks about rules deployment: deploys are eventually-consistent, propagation takes seconds to minutes, and a listener’s evaluation context is captured at attach time.</p>
+<h2 id="what-the-sandbox-does">What the sandbox does</h2>
+<p><code>pyric/sandbox</code> re-evaluates every active listener immediately after <code>deployRules</code> succeeds. Three cases:</p>
+<ul>
+<li><strong>Allowed → denied</strong>: the listener is marked errored. Its <code>onError</code> callback fires (if provided); <code>onSnapshot</code> does not fire again. Once-per-stream error semantics.</li>
+<li><strong>Errored → allowed</strong>: the <code>errored</code> flag clears and the listener fires as an initial snapshot. The consumer sees a fresh baseline.</li>
+<li><strong>Allowed → allowed</strong>: behaves like a write-driven re-evaluation. Diff against the listener’s last delivered snapshot; suppress if unchanged; fire if it changed.</li>
+</ul>
+<p>For query listeners, the same logic applies per-doc: added / removed change entries surface as the readable doc set flips.</p>
+<h2 id="why-diverge">Why diverge</h2>
+<p>The playground is the driving consumer. A user editing rules in the playground UI wants to see their UI react. If a listener doesn’t re-evaluate when rules change:</p>
+<ul>
+<li>An over-permissive rule that the user is trying to tighten will still allow reads that should now deny.</li>
+<li>An over-restrictive rule that the user is loosening will still deny reads that should now allow.</li>
+</ul>
+<p>Either way the UI shows stale state until the user manually refreshes. That breaks the “edit rules, see the effect” feedback loop the playground exists for.</p>
+<p>For a unit-test consumer, the divergence rarely matters. Tests typically don’t reconfigure rules mid-listener. But when they do, the sandbox’s behaviour is what tests usually want. “Test that this rule blocks a read that was previously allowed” works without detach-reattach gymnastics.</p>
+<h2 id="when-this-hurts">When this hurts</h2>
+<p>Two situations where production parity would be nicer:</p>
+<ul>
+<li><strong>Reproducing a production bug</strong> where the symptom is “a listener kept its old gating”. The sandbox can’t reproduce this, because every rule change re-gates everything. You’d need the emulator or live Firestore.</li>
+<li><strong>Verifying eventual consistency</strong>. The sandbox is synchronous; rules apply immediately. Production isn’t; rules take propagation time. Tests that depend on the propagation window need a different tool.</li>
+</ul>
+<p>Both are edge cases. Document them, route them to the right tool, leave the default behaviour where it serves the common case.</p>
+<h2 id="what-dispose-does-differently">What dispose does differently</h2>
+<p><code>dispose</code> (called by <code>reset</code>) doesn’t re-evaluate. It drops every listener registry. Subscribers that were live against the outgoing environment are gone; the new environment starts with no listeners. This is correct because <code>reset</code> is “wipe everything”. Partial state would be confusing.</p>
+<p>The distinction:</p>
+<ul>
+<li><strong><code>deployRules</code></strong>: rules change, data stays, listeners stay (and re-evaluate).</li>
+<li><strong><code>reset</code></strong>: data, rules, listeners, subscribers, all wiped. Fresh environment.</li>
+<li><strong><code>dispose</code></strong>: keep data and rules, drop listeners and subscribers. Used when you’re about to discard the sandbox.</li>
+</ul>
+<h2 id="implementation-iterate-over-a-copy">Implementation: iterate over a copy</h2>
+<p>The re-evaluation loop walks every active listener. A callback may add or remove listeners during the loop (React StrictMode does this routinely; HMR likewise). Iterating the map directly while it mutates is a bug.</p>
+<p>The loop snapshots the listener IDs first, then checks <code>snapshotListeners.has(id)</code> per iteration:</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"> records</span><span style="color:#56B6C2"> =</span><span style="color:#E5C07B"> Array</span><span style="color:#ABB2BF">.</span><span style="color:#61AFEF">from</span><span style="color:#ABB2BF">(</span><span style="color:#E5C07B">this</span><span style="color:#ABB2BF">.</span><span style="color:#E5C07B">snapshotListeners</span><span style="color:#ABB2BF">.</span><span style="color:#61AFEF">values</span><span style="color:#ABB2BF">());</span></span>
+<span class="line"><span style="color:#C678DD">for</span><span style="color:#ABB2BF"> (</span><span style="color:#C678DD">const</span><span style="color:#E5C07B"> record</span><span style="color:#C678DD"> of</span><span style="color:#E06C75"> records</span><span style="color:#ABB2BF">) {</span></span>
+<span class="line"><span style="color:#C678DD">  if</span><span style="color:#ABB2BF"> (</span><span style="color:#56B6C2">!</span><span style="color:#E5C07B">this</span><span style="color:#ABB2BF">.</span><span style="color:#E5C07B">snapshotListeners</span><span style="color:#ABB2BF">.</span><span style="color:#61AFEF">has</span><span style="color:#ABB2BF">(</span><span style="color:#E5C07B">record</span><span style="color:#ABB2BF">.</span><span style="color:#E06C75">id</span><span style="color:#ABB2BF">)) </span><span style="color:#C678DD">continue</span><span style="color:#ABB2BF">;  </span><span style="color:#7F848E;font-style:italic">// unsubscribed mid-loop</span></span>
+<span class="line"><span style="color:#7F848E;font-style:italic">  // ... re-evaluate</span></span>
+<span class="line"><span style="color:#ABB2BF">}</span></span></code></pre>
+<p>The same pattern appears in write-driven listener notification. The mutating-during-iteration risk is the same in both cases; the fix is the same.</p>
+<h2 id="the-once-per-stream-error-contract">The “once-per-stream” error contract</h2>
+<p>Production: a snapshot listener that errors delivers the error exactly once, then receives no further snapshots. The listener stays subscribed from the consumer’s view; the stream is dead.</p>
+<p>The sandbox honours this. A listener that flips allowed → denied fires its <code>onError</code> once (if registered) and is marked <code>errored</code>. Subsequent re-evaluations under further rule changes that keep it denied don’t re-fire the error. Re-allowed listeners clear the flag and fire a fresh initial snapshot.</p>
+<p>This matters for UI code that displays “this listener failed”. Without the once-per-stream rule, the same error would re-fire on every subsequent rule change, spamming the consumer.</p>
+<h2 id="stream-errors-vs-one-shot-denials">Stream errors vs. one-shot denials</h2>
+<p>Both surface through <code>sandbox.onEvent</code>, on different <code>kind</code> discriminators. The targets differ, which is why the event shapes differ:</p>
+<ul>
+<li><code>kind: 'request' &#x26;&#x26; result: 'deny'</code> is “an operation the consumer issued was denied.” The consumer knows which operation; the event names <code>method</code>, <code>path</code>, <code>auth</code>, <code>reasons</code>.</li>
+<li><code>kind: 'listener_errored'</code> is “a listener died without anyone calling it.” The consumer might not know which listener, so the event carries a <code>listenerId</code> and a <code>target</code> discriminator (<code>doc</code> path or query collection) on top of the error payload.</li>
+</ul>
+<p>A host UI that wants to surface every kind of denial subscribes once to <code>onEvent</code> and dispatches on <code>event.kind</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="#what-production-does">What production does</a> </li><li data-depth="2"> <a href="#what-the-sandbox-does">What the sandbox does</a> </li><li data-depth="2"> <a href="#why-diverge">Why diverge</a> </li><li data-depth="2"> <a href="#when-this-hurts">When this hurts</a> </li><li data-depth="2"> <a href="#what-dispose-does-differently">What dispose does differently</a> </li><li data-depth="2"> <a href="#implementation-iterate-over-a-copy">Implementation: iterate over a copy</a> </li><li data-depth="2"> <a href="#the-once-per-stream-error-contract">The “once-per-stream” error contract</a> </li><li data-depth="2"> <a href="#stream-errors-vs-one-shot-denials">Stream errors vs. one-shot denials</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>