npm - @pyric/cli - Versions diffs - 0.1.0-alpha.9 - Mend

@pyric/cli 0.1.0-alpha.9

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (1169) hide show

package/dist/serve/docs-ui/docs/pyric-sandbox-explanation-every-op-is-a-request/index.html ADDED Viewed

@@ -0,0 +1,141 @@
+<!DOCTYPE html><html lang="en"> <head><meta charset="UTF-8"><meta name="viewport" content="width=device-width, initial-scale=1.0"><title>Every operation is a request · 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">Every operation is a request</span> </li> </ol> </nav>  <article class="prose">  <h1 id="every-operation-is-a-request">Every operation is a request</h1>
+<p>The sandbox started with one observation channel, <code>onDenial</code>, and it surfaced the wrong subset of the truth. We expanded the surface to <code>onRequest</code>, then to a per-channel triplet (<code>onRequest</code> / <code>onDenial</code> / <code>onSnapshotError</code>), and finally collapsed them into one unified <a href="../pyric-sandbox-how-to-observe-events/"><code>onEvent</code></a>. This page explains the conceptual arc, what it implies about how to think about sandbox traffic, and the trade-offs we made along the way.</p>
+<h2 id="the-original-framing-was-too-narrow">The original framing was too narrow</h2>
+<p><code>onDenial</code> was built when the playground’s most-visible failure mode was “the user wrote a rule that denied their own app.” Showing the rejected operations was actionable: the agent could read the denial, see why, fix the rule. Allowed traffic was framed as <em>the happy path</em>: invisible, because everything was fine.</p>
+<p>That framing held only as long as the sandbox was used for rule debugging. Two things broke it:</p>
+<ul>
+<li><strong>Listeners.</strong> Once <code>onSnapshot</code> was wired in, every write fanned out into N listener re-evaluations. A listener silently dropping a doc because the read rule denied it had no surface. <code>onDenial</code> fired, but the consumer couldn’t tell it from a “user-issued get denied” event.</li>
+<li><strong>Performance.</strong> When connect-four’s rules turned into 95ms eval p99 in validation, the question shifted from “did anything deny?” to “what’s the rule engine doing with my time?” Allowed ops needed a surface too.</li>
+</ul>
+<p>The reframe: <strong>every op the simulator evaluates is a request worth seeing.</strong> Denials are one filtered view. The full stream is the substrate; everything else (the denials panel, an audit log, a perf inspector) is a projection over it.</p>
+<h2 id="denials-are-now-a-filter-not-a-channel">Denials are now a filter, not a channel</h2>
+<p>The unified-channel rollout collapsed the prior three channels into one:</p>
+<pre class="astro-code one-dark-pro" style="background-color:#282c34;color:#abb2bf; overflow-x: auto;" tabindex="0" data-language="plaintext"><code><span class="line"><span>sandbox.onEvent         — every observable event</span></span>
+<span class="line"><span>  ├ kind: 'request'</span></span>
+<span class="line"><span>  │   └ filter result==='deny'  →  what onDenial used to deliver</span></span>
+<span class="line"><span>  ├ kind: 'write'                  (committed writes only)</span></span>
+<span class="line"><span>  ├ kind: 'snapshot_delivery'</span></span>
+<span class="line"><span>  ├ kind: 'snapshot_suppressed'</span></span>
+<span class="line"><span>  ├ kind: 'listener_attach' | 'listener_detach' | 'listener_errored'</span></span>
+<span class="line"><span>  │   └ filter kind === 'listener_errored'  →  what onSnapshotError used to deliver</span></span>
+<span class="line"><span>  └ kind: 'session_boundary'</span></span></code></pre>
+<p>One subscription, one mental model. A consumer that wants only denials filters <code>kind === 'request' &#x26;&#x26; result === 'deny'</code>. The event carries strictly more information than the old <code>DenialEvent</code> did (<code>evalMs</code>, <code>origin</code>, <code>matchedRule</code>, <code>groupKind</code>, <code>groupId</code>).</p>
+<h2 id="the-substrate-sits-at-the-right-layer">The substrate sits at the right layer</h2>
+<p>A reasonable alternative would have been to put the request channel in <code>pyric-admin</code>. That’s where the data-plane operations live, after all. We rejected it. The reason: every adapter (<code>pyric-admin</code>, <code>pyric/firestore</code>, future <code>pyric/database</code>) bottoms out at <code>LocalEnvironment.execute</code>. Putting the channel on the substrate means:</p>
+<ul>
+<li>One subscription works regardless of which adapter the consumer uses.</li>
+<li>The data-plane adapters stay shape-faithful to their upstream SDKs. Neither <code>firebase-admin/firestore</code> nor <code>firebase/firestore</code> has an <code>onRequest</code>-like surface, and adding one would muddy the swap-in contract.</li>
+<li>A consumer that uses both adapters in one project doesn’t have to wire two streams.</li>
+</ul>
+<p>This is the same reasoning that put <code>onDenial</code> on the sandbox originally, and the same reasoning that kept <code>onEvent</code> there when the three channels collapsed. We’re following the existing precedent.</p>
+<h2 id="the-listener-suppression-trade-off">The listener-suppression trade-off</h2>
+<p>The single most consequential design decision in this work was about query listener fires.</p>
+<p>When a query listener re-evaluates, the rules engine runs a <code>list</code> rule against the collection, then runs a <code>get</code> rule against each candidate doc to filter the visible set. Production Firestore does the same thing: unreadable docs silently never appear in the snapshot. A validation probe measured <strong>252× amplification per write</strong> in a worst-case load test. 500 writes against a query listener spawned 126,251 events, because each write triggered a query re-eval which internally re-evaluated each of N existing docs.</p>
+<p>Two designs were on the table:</p>
+<ol>
+<li><strong>Faithful.</strong> Emit one <code>RequestEvent</code> per inner per-doc eval. The consumer sees every individual filter decision. Useful for “why was doc X filtered out?” debugging. Bad for the panel’s volume.</li>
+<li><strong>Suppressed.</strong> Emit one event per outer <code>list</code> call; the inner per-doc evals are invisible. Matches the user’s mental model: they issued one <code>onSnapshot</code>, they should see one event per fire. Good for the panel; loses the per-doc debugging signal.</li>
+</ol>
+<p>We picked (2) for v1 with an instance-field flag (<code>insideListFilter</code>) suppressing the inner emits. Reasoning:</p>
+<ul>
+<li>The default panel UX is “see what’s happening.” Volume kills it. Without suppression, the 500-write load test would put 126k rows in the buffer, which no one can read.</li>
+<li>The signal that suppression hides (“doc X was visible to Alice but invisible to Bob”) is a niche debugging case. Most consumers don’t need it most of the time.</li>
+<li>The suppression is reversible. A future opt-in flag (<code>{ includeFilterEvents: true }</code> on the subscription) could expose them without breaking the default.</li>
+</ul>
+<p>The asymmetry that remains: write-driven listener re-evals are visible (one <code>list</code> event per fire), but the per-doc decisions inside are not. The decision doc records this; the reference page notes it; the inner-doc filter visibility is on the v2 list.</p>
+<h2 id="what-about-transactions">What about transactions?</h2>
+<p>Transactions get the <code>origin: 'transaction'</code> tag and shared <code>groupId</code>, the same as batches. But there’s a subtler issue with transactions that’s currently unmodelled.</p>
+<p>Inside a <code>runTransaction</code> callback, the consumer calls <code>tx.get(ref)</code> to read docs. Those reads happen against the live state but don’t currently flow through <code>LocalEnvironment.execute</code>. They go through a separate read path inside the <code>TransactionContext</code>. So a <code>tx.get(ref)</code> doesn’t fire a <code>RequestEvent</code> today.</p>
+<p>For v1 that’s acceptable: transactions are rare in playground scenarios, and the <em>commit</em> (which does flow through the request channel as <code>origin: 'transaction'</code> events) gives the most useful signal. But it’s a gap. The follow-up either threads the transaction read path through <code>execute</code> or adds a parallel emit site in the transaction context.</p>
+<p>This is one of those decisions where the substrate’s internal layering shows through the public API. The pragmatic call for v1 was “ship the writes-side of transactions, fix reads in a follow-up.” A purist version would have done both at once.</p>
+<h2 id="the-buffer-lives-at-the-consumer">The buffer lives at the consumer</h2>
+<p>The sandbox doesn’t keep history. <code>onEvent</code> is fire-and-forget. If no subscriber is attached, the event is never built. If a subscriber attaches mid-session, it only sees events from that point forward.</p>
+<p>The decision-doc-locked design says: the <strong>consumer</strong> keeps a ring buffer (default 5000 events). The probe measured worst-case per-event size at ~625 bytes, so a 5000-cap buffer is ~3 MB in browser heap, comfortable. Pause/resume is a consumer concern: pause = stop appending; resume = re-attach.</p>
+<p>Putting buffering in the sandbox would have meant:</p>
+<ul>
+<li>Memory shape baked into the substrate. Different consumers (a CLI logger vs. a browser UI vs. a test that records to NDJSON) want different cap sizes.</li>
+<li>A history-replay API surface. “Give me everything from event id #N” is a meaningful capability but it’s distinct from “live stream”; baking both into one API conflates two concerns.</li>
+<li>A pause/resume semantics question with no good answer at the substrate level: does pause drop incoming, queue them, or block the simulator? Consumer-side, the answer is “drop them; we know we lost data during pause.” Substrate-side, it would be a bug if the simulator blocked.</li>
+</ul>
+<p>By keeping the substrate purely fire-and-forget, we kept it simple and let consumers compose the behaviour they need on top.</p>
+<h2 id="relationship-to-mutationevent">Relationship to <code>MutationEvent</code></h2>
+<p><code>@inbrowser/agent</code> has its own append-only event log at <code>~/.pyric/projects/&#x3C;id>/events.ndjson</code>, populated by <code>wrapMutating</code>. The shape there is <code>MutationEvent</code>:</p>
+<pre class="astro-code one-dark-pro" style="background-color:#282c34;color:#abb2bf; overflow-x: auto;" tabindex="0" data-language="ts"><code><span class="line"><span style="color:#C678DD">interface</span><span style="color:#E5C07B"> MutationEvent</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">  timestamp</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">  agentId</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">  toolName</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">  phase</span><span style="color:#ABB2BF">: </span><span style="color:#98C379">'pre'</span><span style="color:#ABB2BF"> | </span><span style="color:#98C379">'committed'</span><span style="color:#ABB2BF"> | </span><span style="color:#98C379">'rolled-back'</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:#98C379">'rules'</span><span style="color:#ABB2BF"> | </span><span style="color:#98C379">'seed'</span><span style="color:#ABB2BF"> | ... };</span></span>
+<span class="line"><span style="color:#E06C75">  input</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">  output</span><span style="color:#C678DD">?</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">  reverse</span><span style="color:#C678DD">?</span><span style="color:#ABB2BF">: </span><span style="color:#E5C07B">ReverseOp</span><span style="color:#ABB2BF">;</span></span>
+<span class="line"><span style="color:#ABB2BF">}</span></span></code></pre>
+<p><code>RequestEvent</code> and <code>MutationEvent</code> aren’t the same thing, even though they overlap in spirit.</p>
+<div class="table-scroll">
+<table><thead><tr><th></th><th><code>RequestEvent</code></th><th><code>MutationEvent</code></th></tr></thead><tbody><tr><td><strong>Granularity</strong></td><td>Per simulator eval</td><td>Per agent tool call</td></tr><tr><td><strong>Storage</strong></td><td>In-memory only</td><td>Append-only NDJSON</td></tr><tr><td><strong>Lifetime</strong></td><td>Session-local</td><td>Persistent across sessions</td></tr><tr><td><strong>Purpose</strong></td><td>Live observability</td><td>Rollback + audit</td></tr><tr><td><strong>Generator</strong></td><td><code>LocalEnvironment.execute</code></td><td><code>wrapMutating</code></td></tr></tbody></table></div>
+<p>A single agent tool call (e.g. <code>write_firestore_seed</code>) produces one <code>MutationEvent</code> but possibly many <code>RequestEvent</code>s, one per simulator op the underlying write fanned out into. The two channels are complementary: <code>RequestEvent</code> answers “what did the rules engine see?”, <code>MutationEvent</code> answers “what did the agent do?”</p>
+<p>Don’t try to unify them. They serve different consumers, sit at different layers, and would lose precision if merged.</p>
+<h2 id="the-probe-driven-design">The probe-driven design</h2>
+<p>This shape didn’t fall out of a whiteboard session. Validation called out six empirical questions (V1-V6) about volume, eval cost, get-call density, allow/deny ratio, event size, and listener re-eval frequency, then instrumented the sandbox to produce the numbers.</p>
+<p>The numbers drove specific design choices:</p>
+<ul>
+<li><strong>5000-event default buffer</strong>: V5 said max 625 bytes per event, so 5000 caps at ~3 MB.</li>
+<li><strong>Drop <code>getCalls</code> from v1</strong>: V3 said most rules don’t <code>get()</code> at all, and rules that do average ≤1 call per evaluation. The runtime tracing cost wasn’t worth the marginal data.</li>
+<li><strong><code>evalMs</code> is a first-class column, not a details field</strong>: V2 said connect-four sits at 95ms p99. That’s user-perceptible. The column earns its place.</li>
+<li><strong>Default-hide listener traffic</strong>: V1 and V6 said listener events are 94% to 99.6% of total volume in listener-heavy scenarios. Default-on would drown the user-origin signal.</li>
+</ul>
+<p>If you’re working on a related feature and need to make a similar call (“should we measure X?”), the lesson is: write a probe before writing a plan. The probe’s numbers will rule out half the options you were considering.</p>
+<h2 id="limits-worth-knowing">Limits worth knowing</h2>
+<p>A few specifics about what <code>RequestEvent</code> does and doesn’t carry, useful when the panel surprises you.</p>
+<h3 id="authtoken-visibility"><code>auth.token</code> visibility</h3>
+<p><code>event.auth</code> is whatever was passed into the simulator’s <code>request.auth</code>. If a consumer set custom token claims on the op (<code>{ uid: 'alice', token: { admin: true } }</code>), <code>auth.token</code> shows up on the event. If the op was unauthenticated (<code>auth: null</code> at the substrate), <code>event.auth</code> is <code>null</code>, not an empty object. A rule that branches on <code>request.auth.token.x</code> and sees <code>undefined</code> produces a denial whose <code>reasons</code> will mention the token expression; the event itself doesn’t separately surface “the token didn’t have x.” If you need claim-level audit, snapshot <code>auth.token</code> at op-issuance time before the request fires; the sandbox doesn’t reconstruct it.</p>
+<p>The flip side: a consumer that subscribes for security-audit purposes shouldn’t assume <code>auth.token</code> is sanitised. The sandbox passes through whatever was set. If the consumer logs <code>RequestEvent</code>s long-term, claim contents (which may include PII) go with them.</p>
+<h3 id="multi-listener-fanout-multiplies-events">Multi-listener fanout multiplies events</h3>
+<p><code>onSnapshot</code> listeners are independent registrations. Two doc listeners on the same path produce <strong>two</strong> listener-origin events per triggering write, not one. The reasoning: each listener has its own <code>auth</code> context and could see a different result (Alice’s listener gets <code>allow</code>, Bob’s gets <code>deny</code> for the same doc). Coalescing them would hide that. But it means a UI subscribing to “all writes to this collection” five times, perhaps by accident, multiplies its listener-event volume by 5.</p>
+<p>If you’re seeing more listener events than you expected, count distinct registrations first. The probe’s <code>listener-storm</code> scenario (1 doc + 1 query listener, 50 writes = 802 events) shows what one-of-each looks like; double the listeners, double that number.</p>
+<h2 id="what-wed-revisit-in-v2">What we’d revisit in v2</h2>
+<p>A few things in this v1 shape that we’d reconsider once consumers exist:</p>
+<ul>
+<li><strong>Inner per-doc filter visibility.</strong> Opt-in flag for the “why was doc X filtered out” use case.</li>
+<li><strong>Transaction reads.</strong> Plumb the transaction read path through the request channel.</li>
+<li><strong>Rule source positions.</strong> <code>matchedRule.line</code> and <code>matchedRule.column</code> require upstream AST work in <code>pyric/rules</code>. The biggest single ergonomic win available, and the most invasive.</li>
+<li><strong><code>getCalls</code> runtime tracing.</strong> If a consumer says “I need to see the actual paths the rule visited,” this is mechanical to add: patch the simulator’s <code>resolveGet</code> to thread an array through <code>SimulationContext</code>. Currently skipped because no consumer asked.</li>
+</ul>
+<p>None of these are blocking. They’re notes for when someone needs them.</p>
+<h2 id="mental-model">Mental model</h2>
+<p>The shortest version of everything above: <strong>the simulator evaluates ops; we made the evaluations observable.</strong> The substrate fires one event per eval. Filtered views (denials, batches, transactions, listeners) are consumer-side projections. The shape is what the data is.</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="#the-original-framing-was-too-narrow">The original framing was too narrow</a> </li><li data-depth="2"> <a href="#denials-are-now-a-filter-not-a-channel">Denials are now a filter, not a channel</a> </li><li data-depth="2"> <a href="#the-substrate-sits-at-the-right-layer">The substrate sits at the right layer</a> </li><li data-depth="2"> <a href="#the-listener-suppression-trade-off">The listener-suppression trade-off</a> </li><li data-depth="2"> <a href="#what-about-transactions">What about transactions?</a> </li><li data-depth="2"> <a href="#the-buffer-lives-at-the-consumer">The buffer lives at the consumer</a> </li><li data-depth="2"> <a href="#relationship-to-mutationevent">Relationship to MutationEvent</a> </li><li data-depth="2"> <a href="#the-probe-driven-design">The probe-driven design</a> </li><li data-depth="2"> <a href="#limits-worth-knowing">Limits worth knowing</a> </li><li data-depth="3"> <a href="#authtoken-visibility">auth.token visibility</a> </li><li data-depth="3"> <a href="#multi-listener-fanout-multiplies-events">Multi-listener fanout multiplies events</a> </li><li data-depth="2"> <a href="#what-wed-revisit-in-v2">What we’d revisit in v2</a> </li><li data-depth="2"> <a href="#mental-model">Mental model</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-every-op-is-a-request.md ADDED Viewed

@@ -0,0 +1,161 @@
+# Every operation is a request
+The sandbox started with one observation channel, `onDenial`, and it surfaced the wrong subset of the truth. We expanded the surface to `onRequest`, then to a per-channel triplet (`onRequest` / `onDenial` / `onSnapshotError`), and finally collapsed them into one unified [`onEvent`](../pyric-sandbox-how-to-observe-events/). This page explains the conceptual arc, what it implies about how to think about sandbox traffic, and the trade-offs we made along the way.
+## The original framing was too narrow
+`onDenial` was built when the playground's most-visible failure mode was "the user wrote a rule that denied their own app." Showing the rejected operations was actionable: the agent could read the denial, see why, fix the rule. Allowed traffic was framed as *the happy path*: invisible, because everything was fine.
+That framing held only as long as the sandbox was used for rule debugging. Two things broke it:
+- **Listeners.** Once `onSnapshot` was wired in, every write fanned out into N listener re-evaluations. A listener silently dropping a doc because the read rule denied it had no surface. `onDenial` fired, but the consumer couldn't tell it from a "user-issued get denied" event.
+- **Performance.** When connect-four's rules turned into 95ms eval p99 in validation, the question shifted from "did anything deny?" to "what's the rule engine doing with my time?" Allowed ops needed a surface too.
+The reframe: **every op the simulator evaluates is a request worth seeing.** Denials are one filtered view. The full stream is the substrate; everything else (the denials panel, an audit log, a perf inspector) is a projection over it.
+## Denials are now a filter, not a channel
+The unified-channel rollout collapsed the prior three channels into one:
+```
+sandbox.onEvent         — every observable event
+  ├ kind: 'request'
+  │   └ filter result==='deny'  →  what onDenial used to deliver
+  ├ kind: 'write'                  (committed writes only)
+  ├ kind: 'snapshot_delivery'
+  ├ kind: 'snapshot_suppressed'
+  ├ kind: 'listener_attach' | 'listener_detach' | 'listener_errored'
+  │   └ filter kind === 'listener_errored'  →  what onSnapshotError used to deliver
+  └ kind: 'session_boundary'
+```
+One subscription, one mental model. A consumer that wants only denials filters `kind === 'request' && result === 'deny'`. The event carries strictly more information than the old `DenialEvent` did (`evalMs`, `origin`, `matchedRule`, `groupKind`, `groupId`).
+## The substrate sits at the right layer
+A reasonable alternative would have been to put the request channel in `pyric-admin`. That's where the data-plane operations live, after all. We rejected it. The reason: every adapter (`pyric-admin`, `pyric/firestore`, future `pyric/database`) bottoms out at `LocalEnvironment.execute`. Putting the channel on the substrate means:
+- One subscription works regardless of which adapter the consumer uses.
+- The data-plane adapters stay shape-faithful to their upstream SDKs. Neither `firebase-admin/firestore` nor `firebase/firestore` has an `onRequest`-like surface, and adding one would muddy the swap-in contract.
+- A consumer that uses both adapters in one project doesn't have to wire two streams.
+This is the same reasoning that put `onDenial` on the sandbox originally, and the same reasoning that kept `onEvent` there when the three channels collapsed. We're following the existing precedent.
+## The listener-suppression trade-off
+The single most consequential design decision in this work was about query listener fires.
+When a query listener re-evaluates, the rules engine runs a `list` rule against the collection, then runs a `get` rule against each candidate doc to filter the visible set. Production Firestore does the same thing: unreadable docs silently never appear in the snapshot. A validation probe measured **252× amplification per write** in a worst-case load test. 500 writes against a query listener spawned 126,251 events, because each write triggered a query re-eval which internally re-evaluated each of N existing docs.
+Two designs were on the table:
+1. **Faithful.** Emit one `RequestEvent` per inner per-doc eval. The consumer sees every individual filter decision. Useful for "why was doc X filtered out?" debugging. Bad for the panel's volume.
+2. **Suppressed.** Emit one event per outer `list` call; the inner per-doc evals are invisible. Matches the user's mental model: they issued one `onSnapshot`, they should see one event per fire. Good for the panel; loses the per-doc debugging signal.
+We picked (2) for v1 with an instance-field flag (`insideListFilter`) suppressing the inner emits. Reasoning:
+- The default panel UX is "see what's happening." Volume kills it. Without suppression, the 500-write load test would put 126k rows in the buffer, which no one can read.
+- The signal that suppression hides ("doc X was visible to Alice but invisible to Bob") is a niche debugging case. Most consumers don't need it most of the time.
+- The suppression is reversible. A future opt-in flag (`{ includeFilterEvents: true }` on the subscription) could expose them without breaking the default.
+The asymmetry that remains: write-driven listener re-evals are visible (one `list` event per fire), but the per-doc decisions inside are not. The decision doc records this; the reference page notes it; the inner-doc filter visibility is on the v2 list.
+## What about transactions?
+Transactions get the `origin: 'transaction'` tag and shared `groupId`, the same as batches. But there's a subtler issue with transactions that's currently unmodelled.
+Inside a `runTransaction` callback, the consumer calls `tx.get(ref)` to read docs. Those reads happen against the live state but don't currently flow through `LocalEnvironment.execute`. They go through a separate read path inside the `TransactionContext`. So a `tx.get(ref)` doesn't fire a `RequestEvent` today.
+For v1 that's acceptable: transactions are rare in playground scenarios, and the *commit* (which does flow through the request channel as `origin: 'transaction'` events) gives the most useful signal. But it's a gap. The follow-up either threads the transaction read path through `execute` or adds a parallel emit site in the transaction context.
+This is one of those decisions where the substrate's internal layering shows through the public API. The pragmatic call for v1 was "ship the writes-side of transactions, fix reads in a follow-up." A purist version would have done both at once.
+## The buffer lives at the consumer
+The sandbox doesn't keep history. `onEvent` is fire-and-forget. If no subscriber is attached, the event is never built. If a subscriber attaches mid-session, it only sees events from that point forward.
+The decision-doc-locked design says: the **consumer** keeps a ring buffer (default 5000 events). The probe measured worst-case per-event size at ~625 bytes, so a 5000-cap buffer is ~3 MB in browser heap, comfortable. Pause/resume is a consumer concern: pause = stop appending; resume = re-attach.
+Putting buffering in the sandbox would have meant:
+- Memory shape baked into the substrate. Different consumers (a CLI logger vs. a browser UI vs. a test that records to NDJSON) want different cap sizes.
+- A history-replay API surface. "Give me everything from event id #N" is a meaningful capability but it's distinct from "live stream"; baking both into one API conflates two concerns.
+- A pause/resume semantics question with no good answer at the substrate level: does pause drop incoming, queue them, or block the simulator? Consumer-side, the answer is "drop them; we know we lost data during pause." Substrate-side, it would be a bug if the simulator blocked.
+By keeping the substrate purely fire-and-forget, we kept it simple and let consumers compose the behaviour they need on top.
+## Relationship to `MutationEvent`
+`@inbrowser/agent` has its own append-only event log at `~/.pyric/projects/<id>/events.ndjson`, populated by `wrapMutating`. The shape there is `MutationEvent`:
+```ts
+interface MutationEvent {
+  id: string;
+  timestamp: string;
+  agentId: string;
+  toolName: string;
+  phase: 'pre' | 'committed' | 'rolled-back';
+  target: { kind: 'doc' | 'rules' | 'seed' | ... };
+  input: unknown;
+  output?: unknown;
+  reverse?: ReverseOp;
+}
+```
+`RequestEvent` and `MutationEvent` aren't the same thing, even though they overlap in spirit.
+| | `RequestEvent` | `MutationEvent` |
+|---|---|---|
+| **Granularity** | Per simulator eval | Per agent tool call |
+| **Storage** | In-memory only | Append-only NDJSON |
+| **Lifetime** | Session-local | Persistent across sessions |
+| **Purpose** | Live observability | Rollback + audit |
+| **Generator** | `LocalEnvironment.execute` | `wrapMutating` |
+A single agent tool call (e.g. `write_firestore_seed`) produces one `MutationEvent` but possibly many `RequestEvent`s, one per simulator op the underlying write fanned out into. The two channels are complementary: `RequestEvent` answers "what did the rules engine see?", `MutationEvent` answers "what did the agent do?"
+Don't try to unify them. They serve different consumers, sit at different layers, and would lose precision if merged.
+## The probe-driven design
+This shape didn't fall out of a whiteboard session. Validation called out six empirical questions (V1-V6) about volume, eval cost, get-call density, allow/deny ratio, event size, and listener re-eval frequency, then instrumented the sandbox to produce the numbers.
+The numbers drove specific design choices:
+- **5000-event default buffer**: V5 said max 625 bytes per event, so 5000 caps at ~3 MB.
+- **Drop `getCalls` from v1**: V3 said most rules don't `get()` at all, and rules that do average ≤1 call per evaluation. The runtime tracing cost wasn't worth the marginal data.
+- **`evalMs` is a first-class column, not a details field**: V2 said connect-four sits at 95ms p99. That's user-perceptible. The column earns its place.
+- **Default-hide listener traffic**: V1 and V6 said listener events are 94% to 99.6% of total volume in listener-heavy scenarios. Default-on would drown the user-origin signal.
+If you're working on a related feature and need to make a similar call ("should we measure X?"), the lesson is: write a probe before writing a plan. The probe's numbers will rule out half the options you were considering.
+## Limits worth knowing
+A few specifics about what `RequestEvent` does and doesn't carry, useful when the panel surprises you.
+### `auth.token` visibility
+`event.auth` is whatever was passed into the simulator's `request.auth`. If a consumer set custom token claims on the op (`{ uid: 'alice', token: { admin: true } }`), `auth.token` shows up on the event. If the op was unauthenticated (`auth: null` at the substrate), `event.auth` is `null`, not an empty object. A rule that branches on `request.auth.token.x` and sees `undefined` produces a denial whose `reasons` will mention the token expression; the event itself doesn't separately surface "the token didn't have x." If you need claim-level audit, snapshot `auth.token` at op-issuance time before the request fires; the sandbox doesn't reconstruct it.
+The flip side: a consumer that subscribes for security-audit purposes shouldn't assume `auth.token` is sanitised. The sandbox passes through whatever was set. If the consumer logs `RequestEvent`s long-term, claim contents (which may include PII) go with them.
+### Multi-listener fanout multiplies events
+`onSnapshot` listeners are independent registrations. Two doc listeners on the same path produce **two** listener-origin events per triggering write, not one. The reasoning: each listener has its own `auth` context and could see a different result (Alice's listener gets `allow`, Bob's gets `deny` for the same doc). Coalescing them would hide that. But it means a UI subscribing to "all writes to this collection" five times, perhaps by accident, multiplies its listener-event volume by 5.
+If you're seeing more listener events than you expected, count distinct registrations first. The probe's `listener-storm` scenario (1 doc + 1 query listener, 50 writes = 802 events) shows what one-of-each looks like; double the listeners, double that number.
+## What we'd revisit in v2
+A few things in this v1 shape that we'd reconsider once consumers exist:
+- **Inner per-doc filter visibility.** Opt-in flag for the "why was doc X filtered out" use case.
+- **Transaction reads.** Plumb the transaction read path through the request channel.
+- **Rule source positions.** `matchedRule.line` and `matchedRule.column` require upstream AST work in `pyric/rules`. The biggest single ergonomic win available, and the most invasive.
+- **`getCalls` runtime tracing.** If a consumer says "I need to see the actual paths the rule visited," this is mechanical to add: patch the simulator's `resolveGet` to thread an array through `SimulationContext`. Currently skipped because no consumer asked.
+None of these are blocking. They're notes for when someone needs them.
+## Mental model
+The shortest version of everything above: **the simulator evaluates ops; we made the evaluations observable.** The substrate fires one event per eval. Filtered views (denials, batches, transactions, listeners) are consumer-side projections. The shape is what the data is.

package/dist/serve/docs-ui/docs/pyric-sandbox-explanation-identity-is-a-context/index.html ADDED Viewed

@@ -0,0 +1,66 @@
+<!DOCTYPE html><html lang="en"> <head><meta charset="UTF-8"><meta name="viewport" content="width=device-width, initial-scale=1.0"><title>Identity is a context, not a sandbox · 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">Identity is a context</span> </li> </ol> </nav>  <article class="prose">  <h1 id="identity-is-a-context-not-a-sandbox">Identity is a context, not a sandbox</h1>
+<p>The most-visible architectural decision in <code>pyric/sandbox</code> is that <code>Sandbox</code> does not carry an identity. To do anything as a user, you derive a <code>SandboxContext</code> via <code>sandbox.withAuth(...)</code>. This page explains why.</p>
+<h2 id="what-the-alternative-would-look-like">What the alternative would look like</h2>
+<p>A simpler API exposes <code>auth</code> as a field on the sandbox:</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:#7F848E;font-style:italic">// Hypothetical, not the actual API.</span></span>
+<span class="line"><span style="color:#C678DD">const</span><span style="color:#E5C07B"> sandbox</span><span style="color:#56B6C2"> =</span><span style="color:#61AFEF"> initializeSandbox</span><span style="color:#ABB2BF">({ </span><span style="color:#E06C75">auth</span><span style="color:#ABB2BF">: { </span><span style="color:#E06C75">uid</span><span style="color:#ABB2BF">: </span><span style="color:#98C379">'alice'</span><span style="color:#ABB2BF"> } });</span></span>
+<span class="line"><span style="color:#E5C07B">sandbox</span><span style="color:#ABB2BF">.</span><span style="color:#E5C07B">firestore</span><span style="color:#ABB2BF">.</span><span style="color:#61AFEF">collection</span><span style="color:#ABB2BF">(</span><span style="color:#98C379">'notes'</span><span style="color:#ABB2BF">).</span><span style="color:#61AFEF">doc</span><span style="color:#ABB2BF">(</span><span style="color:#98C379">'n1'</span><span style="color:#ABB2BF">).</span><span style="color:#61AFEF">set</span><span style="color:#ABB2BF">(...);  </span><span style="color:#7F848E;font-style:italic">// runs as alice</span></span>
+<span class="line"><span style="color:#E5C07B">sandbox</span><span style="color:#ABB2BF">.</span><span style="color:#61AFEF">setAuth</span><span style="color:#ABB2BF">({ </span><span style="color:#E06C75">uid</span><span style="color:#ABB2BF">: </span><span style="color:#98C379">'bob'</span><span style="color:#ABB2BF"> });</span></span>
+<span class="line"><span style="color:#E5C07B">sandbox</span><span style="color:#ABB2BF">.</span><span style="color:#E5C07B">firestore</span><span style="color:#ABB2BF">.</span><span style="color:#61AFEF">collection</span><span style="color:#ABB2BF">(</span><span style="color:#98C379">'notes'</span><span style="color:#ABB2BF">).</span><span style="color:#61AFEF">doc</span><span style="color:#ABB2BF">(</span><span style="color:#98C379">'n1'</span><span style="color:#ABB2BF">).</span><span style="color:#61AFEF">get</span><span style="color:#ABB2BF">();     </span><span style="color:#7F848E;font-style:italic">// runs as bob</span></span></code></pre>
+<p>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?</p>
+<h2 id="three-problems-with-auth-on-sandbox">Three problems with auth-on-sandbox</h2>
+<h3 id="1-multi-tenant-tests-need-many-identities-often-simultaneously">1. Multi-tenant tests need many identities, often simultaneously</h3>
+<p>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:</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:#E5C07B">sandbox</span><span style="color:#ABB2BF">.</span><span style="color:#61AFEF">setAuth</span><span style="color:#ABB2BF">({ </span><span style="color:#E06C75">uid</span><span style="color:#ABB2BF">: </span><span style="color:#98C379">'alice'</span><span style="color:#ABB2BF"> });</span></span>
+<span class="line"><span style="color:#C678DD">await</span><span style="color:#E5C07B"> sandbox</span><span style="color:#ABB2BF">.</span><span style="color:#E5C07B">firestore</span><span style="color:#ABB2BF">.</span><span style="color:#61AFEF">collection</span><span style="color:#ABB2BF">(</span><span style="color:#98C379">'notes'</span><span style="color:#ABB2BF">).</span><span style="color:#61AFEF">doc</span><span style="color:#ABB2BF">(</span><span style="color:#98C379">'alice-1'</span><span style="color:#ABB2BF">).</span><span style="color:#61AFEF">set</span><span style="color:#ABB2BF">({ </span><span style="color:#E06C75">ownerId</span><span style="color:#ABB2BF">: </span><span style="color:#98C379">'alice'</span><span style="color:#ABB2BF"> });</span></span>
+<span class="line"><span style="color:#E5C07B">sandbox</span><span style="color:#ABB2BF">.</span><span style="color:#61AFEF">setAuth</span><span style="color:#ABB2BF">({ </span><span style="color:#E06C75">uid</span><span style="color:#ABB2BF">: </span><span style="color:#98C379">'bob'</span><span style="color:#ABB2BF"> });</span></span>
+<span class="line"><span style="color:#C678DD">try</span><span style="color:#ABB2BF"> { </span><span style="color:#C678DD">await</span><span style="color:#E5C07B"> sandbox</span><span style="color:#ABB2BF">.</span><span style="color:#E5C07B">firestore</span><span style="color:#ABB2BF">.</span><span style="color:#61AFEF">collection</span><span style="color:#ABB2BF">(</span><span style="color:#98C379">'notes'</span><span style="color:#ABB2BF">).</span><span style="color:#61AFEF">doc</span><span style="color:#ABB2BF">(</span><span style="color:#98C379">'alice-1'</span><span style="color:#ABB2BF">).</span><span style="color:#61AFEF">get</span><span style="color:#ABB2BF">(); } </span><span style="color:#C678DD">catch</span><span style="color:#ABB2BF"> { </span><span style="color:#7F848E;font-style:italic">/* expected */</span><span style="color:#ABB2BF"> }</span></span>
+<span class="line"><span style="color:#E5C07B">sandbox</span><span style="color:#ABB2BF">.</span><span style="color:#61AFEF">setAuth</span><span style="color:#ABB2BF">({ </span><span style="color:#E06C75">uid</span><span style="color:#ABB2BF">: </span><span style="color:#98C379">'alice'</span><span style="color:#ABB2BF"> });  </span><span style="color:#7F848E;font-style:italic">// restore</span></span></code></pre>
+<p>This is tedious and error-prone. Forget to restore and the next operation runs as <code>bob</code> accidentally. With contexts, the same test is straightforward:</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"> aliceDb</span><span style="color:#56B6C2"> =</span><span style="color:#61AFEF"> getFirestore</span><span style="color:#ABB2BF">(</span><span style="color:#E5C07B">sandbox</span><span style="color:#ABB2BF">.</span><span style="color:#61AFEF">withAuth</span><span style="color:#ABB2BF">({ </span><span style="color:#E06C75">uid</span><span style="color:#ABB2BF">: </span><span style="color:#98C379">'alice'</span><span style="color:#ABB2BF"> }));</span></span>
+<span class="line"><span style="color:#C678DD">const</span><span style="color:#E5C07B"> bobDb</span><span style="color:#56B6C2"> =</span><span style="color:#61AFEF"> getFirestore</span><span style="color:#ABB2BF">(</span><span style="color:#E5C07B">sandbox</span><span style="color:#ABB2BF">.</span><span style="color:#61AFEF">withAuth</span><span style="color:#ABB2BF">({ </span><span style="color:#E06C75">uid</span><span style="color:#ABB2BF">: </span><span style="color:#98C379">'bob'</span><span style="color:#ABB2BF"> }));</span></span>
+<span class="line"></span>
+<span class="line"><span style="color:#C678DD">await</span><span style="color:#E5C07B"> aliceDb</span><span style="color:#ABB2BF">.</span><span style="color:#61AFEF">collection</span><span style="color:#ABB2BF">(</span><span style="color:#98C379">'notes'</span><span style="color:#ABB2BF">).</span><span style="color:#61AFEF">doc</span><span style="color:#ABB2BF">(</span><span style="color:#98C379">'alice-1'</span><span style="color:#ABB2BF">).</span><span style="color:#61AFEF">set</span><span style="color:#ABB2BF">({ </span><span style="color:#E06C75">ownerId</span><span style="color:#ABB2BF">: </span><span style="color:#98C379">'alice'</span><span style="color:#ABB2BF"> });</span></span>
+<span class="line"><span style="color:#C678DD">try</span><span style="color:#ABB2BF"> { </span><span style="color:#C678DD">await</span><span style="color:#E5C07B"> bobDb</span><span style="color:#ABB2BF">.</span><span style="color:#61AFEF">collection</span><span style="color:#ABB2BF">(</span><span style="color:#98C379">'notes'</span><span style="color:#ABB2BF">).</span><span style="color:#61AFEF">doc</span><span style="color:#ABB2BF">(</span><span style="color:#98C379">'alice-1'</span><span style="color:#ABB2BF">).</span><span style="color:#61AFEF">get</span><span style="color:#ABB2BF">(); } </span><span style="color:#C678DD">catch</span><span style="color:#ABB2BF"> { </span><span style="color:#7F848E;font-style:italic">/* expected */</span><span style="color:#ABB2BF"> }</span></span></code></pre>
+<p>Two named variables, two identities, no swapping. The test reads like the assertion it’s making.</p>
+<h3 id="2-concurrent-operations-from-different-identities">2. Concurrent operations from different identities</h3>
+<p>Two simultaneous writes from different users:</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:#7F848E;font-style:italic">// With auth-on-sandbox — concurrent setAuth calls race.</span></span>
+<span class="line"><span style="color:#C678DD">await</span><span style="color:#E5C07B"> Promise</span><span style="color:#ABB2BF">.</span><span style="color:#61AFEF">all</span><span style="color:#ABB2BF">([</span></span>
+<span class="line"><span style="color:#ABB2BF">  (</span><span style="color:#C678DD">async</span><span style="color:#ABB2BF"> () </span><span style="color:#C678DD">=></span><span style="color:#ABB2BF"> { </span><span style="color:#E5C07B">sandbox</span><span style="color:#ABB2BF">.</span><span style="color:#61AFEF">setAuth</span><span style="color:#ABB2BF">({ </span><span style="color:#E06C75">uid</span><span style="color:#ABB2BF">: </span><span style="color:#98C379">'alice'</span><span style="color:#ABB2BF"> }); </span><span style="color:#C678DD">await</span><span style="color:#61AFEF"> write</span><span style="color:#ABB2BF">(); })(),</span></span>
+<span class="line"><span style="color:#ABB2BF">  (</span><span style="color:#C678DD">async</span><span style="color:#ABB2BF"> () </span><span style="color:#C678DD">=></span><span style="color:#ABB2BF"> { </span><span style="color:#E5C07B">sandbox</span><span style="color:#ABB2BF">.</span><span style="color:#61AFEF">setAuth</span><span style="color:#ABB2BF">({ </span><span style="color:#E06C75">uid</span><span style="color:#ABB2BF">: </span><span style="color:#98C379">'bob'</span><span style="color:#ABB2BF"> }); </span><span style="color:#C678DD">await</span><span style="color:#61AFEF"> write</span><span style="color:#ABB2BF">(); })(),</span></span>
+<span class="line"><span style="color:#ABB2BF">]);</span></span></code></pre>
+<p>The behaviour depends on event-loop scheduling. The same code passes most runs and fails sometimes. With contexts:</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">await</span><span style="color:#E5C07B"> Promise</span><span style="color:#ABB2BF">.</span><span style="color:#61AFEF">all</span><span style="color:#ABB2BF">([</span></span>
+<span class="line"><span style="color:#E5C07B">  aliceDb</span><span style="color:#ABB2BF">.</span><span style="color:#61AFEF">collection</span><span style="color:#ABB2BF">(</span><span style="color:#98C379">'notes'</span><span style="color:#ABB2BF">).</span><span style="color:#61AFEF">doc</span><span style="color:#ABB2BF">(</span><span style="color:#98C379">'a1'</span><span style="color:#ABB2BF">).</span><span style="color:#61AFEF">set</span><span style="color:#ABB2BF">({ ... }),</span></span>
+<span class="line"><span style="color:#E5C07B">  bobDb</span><span style="color:#ABB2BF">.</span><span style="color:#61AFEF">collection</span><span style="color:#ABB2BF">(</span><span style="color:#98C379">'notes'</span><span style="color:#ABB2BF">).</span><span style="color:#61AFEF">doc</span><span style="color:#ABB2BF">(</span><span style="color:#98C379">'b1'</span><span style="color:#ABB2BF">).</span><span style="color:#61AFEF">set</span><span style="color:#ABB2BF">({ ... }),</span></span>
+<span class="line"><span style="color:#ABB2BF">]);</span></span></code></pre>
+<p>Each operation’s identity is captured in the handle it was issued through. No race.</p>
+<h3 id="3-identity-agnostic-operations-should-be-obvious">3. Identity-agnostic operations should be obvious</h3>
+<p>Admin reads, listener subscribers, <code>reset</code>, <code>dispose</code>, <code>snapshot</code>: 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 <code>Sandbox</code>; everything else (data operations) requires a context. A reader of the type signature can tell at a glance.</p>
+<h2 id="the-mental-model">The mental model</h2>
+<pre class="astro-code one-dark-pro" style="background-color:#282c34;color:#abb2bf; overflow-x: auto;" tabindex="0" data-language="plaintext"><code><span class="line"><span>Sandbox          ← data, rules, lifecycle. Identity-agnostic.</span></span>
+<span class="line"><span>   │</span></span>
+<span class="line"><span>   │  withAuth(auth)</span></span>
+<span class="line"><span>   ▼</span></span>
+<span class="line"><span>SandboxContext   ← (sandbox, auth) pair. Cheap, immutable.</span></span>
+<span class="line"><span>   │</span></span>
+<span class="line"><span>   │  getFirestore(ctx)</span></span>
+<span class="line"><span>   ▼</span></span>
+<span class="line"><span>FirestoreHandle  ← data-plane API. Operations evaluate under ctx.auth.</span></span></code></pre>
+<p>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.</p>
+<h2 id="what-about-per-operation-auth-overrides">What about per-operation auth overrides?</h2>
+<p>We considered exposing <code>db.collection('x').doc('y').get({ auth: { uid: 'alice' } })</code> as an override. Rejected because:</p>
+<ul>
+<li>The service handle’s whole shape would need to change. Every method gets an optional <code>OperationOptions { auth?: AuthState }</code> parameter, multiplying the surface area.</li>
+<li>The handle’s binding to its context becomes a lie. “This handle is bound to alice, except when it isn’t.”</li>
+<li>Composition gets harder. A function that takes a <code>FirestoreHandle</code> can no longer assume it knows whose identity its operations run under.</li>
+</ul>
+<p>“Derive a different context” is cheaper than any of those costs.</p>
+<h2 id="what-about-implicit-fallback">What about implicit fallback?</h2>
+<p>A different option: let auth-less handles exist, and have them default to anonymous. <code>getFirestore(sandbox)</code> (no context) returns a handle that evaluates as <code>request.auth == null</code>.</p>
+<p>Rejected because the call site is then ambiguous about whether anonymous was intended or forgotten. Service factories require a <code>SandboxContext</code> (<code>getFirestore(sandbox.withAuth(null))</code> for anonymous) so the intent is on the page.</p>
+<p>The same reasoning applies to <code>withAuth(undefined)</code>: it throws instead of treating <code>undefined</code> as anonymous. Explicit <code>null</code> is the only way to say “anonymous on purpose”.</p>
+<h2 id="where-this-design-came-from">Where this design came from</h2>
+<p>This split was originally <code>AuthContext</code> (the data type) and <code>Sandbox</code> (with <code>auth</code> baked in). The rename to <code>AuthState</code> + <code>SandboxContext</code> 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.</p>
+<p>The key insight: identity is something operations have, not something sandboxes have. A sandbox is a <em>place</em> with documents and rules. An operation is an <em>action</em> with an actor. The context is the bridge that carries the actor in.</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-the-alternative-would-look-like">What the alternative would look like</a> </li><li data-depth="2"> <a href="#three-problems-with-auth-on-sandbox">Three problems with auth-on-sandbox</a> </li><li data-depth="3"> <a href="#1-multi-tenant-tests-need-many-identities-often-simultaneously">1. Multi-tenant tests need many identities, often simultaneously</a> </li><li data-depth="3"> <a href="#2-concurrent-operations-from-different-identities">2. Concurrent operations from different identities</a> </li><li data-depth="3"> <a href="#3-identity-agnostic-operations-should-be-obvious">3. Identity-agnostic operations should be obvious</a> </li><li data-depth="2"> <a href="#the-mental-model">The mental model</a> </li><li data-depth="2"> <a href="#what-about-per-operation-auth-overrides">What about per-operation auth overrides?</a> </li><li data-depth="2"> <a href="#what-about-implicit-fallback">What about implicit fallback?</a> </li><li data-depth="2"> <a href="#where-this-design-came-from">Where this design came from</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>