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-why-this-package-exists/index.html ADDED Viewed

@@ -0,0 +1,69 @@
+<!DOCTYPE html><html lang="en"> <head><meta charset="UTF-8"><meta name="viewport" content="width=device-width, initial-scale=1.0"><title>Why this package exists · 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">Why this package exists</span> </li> </ol> </nav>  <article class="prose">  <h1 id="why-this-package-exists">Why this package exists</h1>
+<p>The Firebase Emulator Suite is a Google-provided tool that runs a local copy of Firestore (and other services) in a sub-process. It’s the canonical answer to “I want to test without hitting production.” It works, but only in environments that can spawn an emulator. <code>pyric/sandbox</code> is what happens when you can’t.</p>
+<h2 id="what-the-emulator-does-well">What the emulator does well</h2>
+<p>The Firebase Emulator Suite is bit-for-bit production. Same Firestore engine, same rules engine, same wire protocols. Tests written against the emulator and tests written against production differ only in their connection URL. If you have an environment that can run it (a developer laptop, a CI runner with Java installed, a container), it’s a perfectly good choice.</p>
+<p>It also covers more than this package does: full Auth flows, Realtime Database, Storage, Cloud Functions emulation. <code>pyric/sandbox</code> doesn’t try to match that breadth.</p>
+<h2 id="where-the-emulator-stops-working">Where the emulator stops working</h2>
+<p>A handful of contexts don’t have an emulator option:</p>
+<ul>
+<li><strong>Browser-side tools.</strong> The playground we ship is a browser app. It needs to evaluate Firestore writes and rules in-page; spawning Java isn’t possible.</li>
+<li><strong>Long-lived agent processes.</strong> Spinning up an emulator per agent session is expensive (~5 seconds to boot, tens of MB of memory, port allocation). For an agent loop that runs hundreds of micro-sessions, this overhead dominates everything else the agent does.</li>
+<li><strong>Lightweight test suites.</strong> A unit test that asserts “this rule denies this request” shouldn’t need to boot a 250 MB JVM. The cost-benefit is bad when there are thousands of tests.</li>
+<li><strong>Environments with no sub-processes.</strong> Some sandboxed CI runners, edge runtimes, and serverless contexts can run Node or a browser but can’t spawn arbitrary binaries.</li>
+</ul>
+<p>For each of these, <code>pyric/sandbox</code> is the alternative. In-process, browser-safe, ~1 ms cold start, single megabytes of memory.</p>
+<h2 id="what-pyricsandbox-is">What <code>pyric/sandbox</code> is</h2>
+<p>A re-implementation of the data + rules portion of Firestore, in TypeScript, sized to fit the agent / playground / unit-test use cases:</p>
+<ul>
+<li>The document store is an in-memory <code>LocalState</code> map.</li>
+<li>The rules engine is <code>pyric/rules</code>’ engine-internal <code>SimulateFirestoreRulesHandler</code> (<code>pyric/rules/internal</code>), also browser-safe.</li>
+<li>The transaction system tracks reads and writes per-tx, detects read-after-write violations, projects post-write state for <code>getAfter()</code>.</li>
+<li>Snapshot listeners are first-class: doc and query listeners both implemented, including the production behaviour where stream errors silently terminate the listener.</li>
+<li>Field-value sentinels (<code>increment</code>, <code>serverTimestamp</code>, <code>arrayUnion</code>) are honoured by the rules engine and the data plane.</li>
+</ul>
+<p>What it isn’t:</p>
+<ul>
+<li>It isn’t bit-for-bit production. The simulator has gaps (some namespace methods on wrapper types aren’t modelled yet). It returns <code>'unsupported'</code> on those, distinct from <code>'denied'</code>. See the <code>UnsupportedError</code> discussion in <code>pyric/rules</code>.</li>
+<li>It isn’t a network. There’s no transport, no quota, no concurrent-connection model. Tests that need to exercise transport-level error codes (<code>'unavailable'</code>, <code>'aborted'</code> from contention) belong on the emulator or live Firestore.</li>
+<li>It isn’t multi-service yet. Firestore is the only data plane today. Auth state is modelled (because rules need it) but no Auth API is exposed. Realtime Database, Storage, and Functions emulation are out of scope.</li>
+</ul>
+<h2 id="why-a-separate-package-not-bundled-with-an-adapter">Why a separate package, not bundled with an adapter</h2>
+<p>The substrate is shared between <code>pyric-admin</code> (Admin-SDK-shaped) and <code>pyric/firestore</code> (modular Web-SDK-shaped). Bundling it into either one would force consumers of the other to pull in surface they don’t use. Splitting it lets each adapter stay narrowly-scoped to its own API shape, and lets a hypothetical third adapter (RTDB, Auth) plug in without disturbing the existing two.</p>
+<p>The split also makes the surface boundary explicit. <code>pyric/sandbox</code>’s public API is <code>Sandbox</code>, <code>SandboxContext</code>, <code>SandboxError</code>, and the listener channels, nothing else. The data-plane operations (<code>getDoc</code>, <code>setDoc</code>, <code>collection</code>, etc.) belong to the adapters. The adapters reach into <code>pyric/sandbox/internal</code> for the substrate; consumers don’t.</p>
+<p>See <a href="../pyric-sandbox-explanation-why-adapters-are-siblings/">Why service adapters live in sibling packages</a> for the longer version.</p>
+<h2 id="when-to-reach-for-which">When to reach for which</h2>
+<div class="table-scroll">
+<table><thead><tr><th>Need</th><th>Reach for</th></tr></thead><tbody><tr><td>Test rules in a unit test, no emulator allowed</td><td><code>pyric/sandbox</code> + <code>pyric-admin</code> or <code>pyric/firestore</code></td></tr><tr><td>Run an agent loop that evaluates many rules per second</td><td><code>pyric/sandbox</code></td></tr><tr><td>Render a sandboxed Firestore in a browser playground</td><td><code>pyric/sandbox</code></td></tr><tr><td>Test full Firestore semantics including transport behaviour</td><td>Firebase Emulator Suite</td></tr><tr><td>Cover Auth flows, RTDB, Storage, or Functions</td><td>Firebase Emulator Suite</td></tr><tr><td>Production execution</td><td>Firebase, loaded directly with Pyric activation absent</td></tr></tbody></table></div>
+<p>For most of the use cases this stack targets, the sandbox is the right call. For the cases it doesn’t cover, the emulator or live Firestore are the right call. The two coexist. Nothing about <code>pyric/sandbox</code> makes the emulator harder to use.</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-emulator-does-well">What the emulator does well</a> </li><li data-depth="2"> <a href="#where-the-emulator-stops-working">Where the emulator stops working</a> </li><li data-depth="2"> <a href="#what-pyricsandbox-is">What pyric/sandbox is</a> </li><li data-depth="2"> <a href="#why-a-separate-package-not-bundled-with-an-adapter">Why a separate package, not bundled with an adapter</a> </li><li data-depth="2"> <a href="#when-to-reach-for-which">When to reach for which</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-why-this-package-exists.md ADDED Viewed

@@ -0,0 +1,57 @@
+# Why this package exists
+The Firebase Emulator Suite is a Google-provided tool that runs a local copy of Firestore (and other services) in a sub-process. It's the canonical answer to "I want to test without hitting production." It works, but only in environments that can spawn an emulator. `pyric/sandbox` is what happens when you can't.
+## What the emulator does well
+The Firebase Emulator Suite is bit-for-bit production. Same Firestore engine, same rules engine, same wire protocols. Tests written against the emulator and tests written against production differ only in their connection URL. If you have an environment that can run it (a developer laptop, a CI runner with Java installed, a container), it's a perfectly good choice.
+It also covers more than this package does: full Auth flows, Realtime Database, Storage, Cloud Functions emulation. `pyric/sandbox` doesn't try to match that breadth.
+## Where the emulator stops working
+A handful of contexts don't have an emulator option:
+- **Browser-side tools.** The playground we ship is a browser app. It needs to evaluate Firestore writes and rules in-page; spawning Java isn't possible.
+- **Long-lived agent processes.** Spinning up an emulator per agent session is expensive (~5 seconds to boot, tens of MB of memory, port allocation). For an agent loop that runs hundreds of micro-sessions, this overhead dominates everything else the agent does.
+- **Lightweight test suites.** A unit test that asserts "this rule denies this request" shouldn't need to boot a 250 MB JVM. The cost-benefit is bad when there are thousands of tests.
+- **Environments with no sub-processes.** Some sandboxed CI runners, edge runtimes, and serverless contexts can run Node or a browser but can't spawn arbitrary binaries.
+For each of these, `pyric/sandbox` is the alternative. In-process, browser-safe, ~1 ms cold start, single megabytes of memory.
+## What `pyric/sandbox` is
+A re-implementation of the data + rules portion of Firestore, in TypeScript, sized to fit the agent / playground / unit-test use cases:
+- The document store is an in-memory `LocalState` map.
+- The rules engine is `pyric/rules`' engine-internal `SimulateFirestoreRulesHandler` (`pyric/rules/internal`), also browser-safe.
+- The transaction system tracks reads and writes per-tx, detects read-after-write violations, projects post-write state for `getAfter()`.
+- Snapshot listeners are first-class: doc and query listeners both implemented, including the production behaviour where stream errors silently terminate the listener.
+- Field-value sentinels (`increment`, `serverTimestamp`, `arrayUnion`) are honoured by the rules engine and the data plane.
+What it isn't:
+- It isn't bit-for-bit production. The simulator has gaps (some namespace methods on wrapper types aren't modelled yet). It returns `'unsupported'` on those, distinct from `'denied'`. See the `UnsupportedError` discussion in `pyric/rules`.
+- It isn't a network. There's no transport, no quota, no concurrent-connection model. Tests that need to exercise transport-level error codes (`'unavailable'`, `'aborted'` from contention) belong on the emulator or live Firestore.
+- It isn't multi-service yet. Firestore is the only data plane today. Auth state is modelled (because rules need it) but no Auth API is exposed. Realtime Database, Storage, and Functions emulation are out of scope.
+## Why a separate package, not bundled with an adapter
+The substrate is shared between `pyric-admin` (Admin-SDK-shaped) and `pyric/firestore` (modular Web-SDK-shaped). Bundling it into either one would force consumers of the other to pull in surface they don't use. Splitting it lets each adapter stay narrowly-scoped to its own API shape, and lets a hypothetical third adapter (RTDB, Auth) plug in without disturbing the existing two.
+The split also makes the surface boundary explicit. `pyric/sandbox`'s public API is `Sandbox`, `SandboxContext`, `SandboxError`, and the listener channels, nothing else. The data-plane operations (`getDoc`, `setDoc`, `collection`, etc.) belong to the adapters. The adapters reach into `pyric/sandbox/internal` for the substrate; consumers don't.
+See [Why service adapters live in sibling packages](../pyric-sandbox-explanation-why-adapters-are-siblings/) for the longer version.
+## When to reach for which
+| Need | Reach for |
+|---|---|
+| Test rules in a unit test, no emulator allowed | `pyric/sandbox` + `pyric-admin` or `pyric/firestore` |
+| Run an agent loop that evaluates many rules per second | `pyric/sandbox` |
+| Render a sandboxed Firestore in a browser playground | `pyric/sandbox` |
+| Test full Firestore semantics including transport behaviour | Firebase Emulator Suite |
+| Cover Auth flows, RTDB, Storage, or Functions | Firebase Emulator Suite |
+| Production execution | Firebase, loaded directly with Pyric activation absent |
+For most of the use cases this stack targets, the sandbox is the right call. For the cases it doesn't cover, the emulator or live Firestore are the right call. The two coexist. Nothing about `pyric/sandbox` makes the emulator harder to use.

package/dist/serve/docs-ui/docs/pyric-sandbox-firestore-reference-api/index.html ADDED Viewed

@@ -0,0 +1,202 @@
+<!DOCTYPE html><html lang="en"> <head><meta charset="UTF-8"><meta name="viewport" content="width=device-width, initial-scale=1.0"><title>API reference: pyric/sandbox/firestore · Pyric Studio</title><meta name="description" content="Published declarations for pyric/sandbox/firestore."><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/"> 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/" aria-current="true"> 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/"> 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/" aria-current="true"> 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/api-reference/">API reference</a> </li><li> <span class="docs-breadcrumbs-sep" aria-hidden="true">/</span> <span>pyric</span> </li><li> <span class="docs-breadcrumbs-sep" aria-hidden="true">/</span> <span aria-current="page">pyric/sandbox/firestore</span> </li> </ol> </nav> <header class="api-reference-header"> <p class="api-reference-kicker">API reference</p> <h1><code>pyric/sandbox/firestore</code></h1> <p class="api-reference-meta"> 6 published symbols from <code>pyric</code> </p> <p class="api-reference-source">
+Generated from the TypeScript declarations shipped at this import path.
+</p>  </header> <article class="prose api-reference-body">  <!-- Generated from published package declarations via TypeDoc. Do not edit by hand; run bun run docs:api:generate. -->
+<h2 id="interfaces">Interfaces</h2>
+<p><a id="firestoreinspectoptions"></a></p>
+<h3 id="firestoreinspectoptions">FirestoreInspectOptions</h3>
+<h4 id="properties">Properties</h4>
+<div class="table-scroll">
+<table><thead><tr><th align="left">Property</th><th align="left">Type</th><th align="left">Description</th></tr></thead><tbody><tr><td align="left"><a id="recenteventlimit"></a> <code>recentEventLimit?</code></td><td align="left"><code>number</code></td><td align="left">Maximum number of recent requests and denials to return. Defaults to 10.</td></tr></tbody></table></div>
+<hr>
+<p><a id="firestoreinspectreport"></a></p>
+<h3 id="firestoreinspectreport">FirestoreInspectReport</h3>
+<p>Stable JSON-serializable Firestore diagnostic used by Studio and tools.</p>
+<h4 id="properties-1">Properties</h4>
+<div class="table-scroll">
+<table><thead><tr><th align="left">Property</th><th align="left">Type</th></tr></thead><tbody><tr><td align="left"><a id="documents"></a> <code>documents</code></td><td align="left">{ <code>byCollection</code>: <code>Record</code>&#x3C;<code>string</code>, <code>number</code>>; <code>totalCount</code>: <code>number</code>; }</td></tr><tr><td align="left"><code>documents.byCollection</code></td><td align="left"><code>Record</code>&#x3C;<code>string</code>, <code>number</code>></td></tr><tr><td align="left"><code>documents.totalCount</code></td><td align="left"><code>number</code></td></tr><tr><td align="left"><a id="events"></a> <code>events</code></td><td align="left">{ <code>recentDenials</code>: { <code>auth</code>: <code>unknown</code>; <code>debugMessage?</code>: <code>string</code>; <code>method</code>: <code>string</code>; <code>path</code>: <code>string</code>; }[]; <code>recentRequests</code>: { <code>auth</code>: <code>unknown</code>; <code>method</code>: <code>string</code>; <code>path</code>: <code>string</code>; <code>result</code>: <code>string</code>; }[]; <code>totalCount</code>: <code>number</code>; }</td></tr><tr><td align="left"><code>events.recentDenials</code></td><td align="left">{ <code>auth</code>: <code>unknown</code>; <code>debugMessage?</code>: <code>string</code>; <code>method</code>: <code>string</code>; <code>path</code>: <code>string</code>; }[]</td></tr><tr><td align="left"><code>events.recentRequests</code></td><td align="left">{ <code>auth</code>: <code>unknown</code>; <code>method</code>: <code>string</code>; <code>path</code>: <code>string</code>; <code>result</code>: <code>string</code>; }[]</td></tr><tr><td align="left"><code>events.totalCount</code></td><td align="left"><code>number</code></td></tr><tr><td align="left"><a id="rules"></a> <code>rules</code></td><td align="left">{ <code>isEmpty</code>: <code>boolean</code>; <code>lint</code>: { <code>errors</code>: <code>number</code>; <code>findings</code>: { <code>message</code>: <code>string</code>; <code>rule</code>: <code>string</code>; <code>severity</code>: <code>string</code>; }[]; <code>info</code>: <code>number</code>; <code>warnings</code>: <code>number</code>; }; <code>sizeBytes</code>: <code>number</code>; <code>source</code>: <code>string</code>; }</td></tr><tr><td align="left"><code>rules.isEmpty</code></td><td align="left"><code>boolean</code></td></tr><tr><td align="left"><code>rules.lint</code></td><td align="left">{ <code>errors</code>: <code>number</code>; <code>findings</code>: { <code>message</code>: <code>string</code>; <code>rule</code>: <code>string</code>; <code>severity</code>: <code>string</code>; }[]; <code>info</code>: <code>number</code>; <code>warnings</code>: <code>number</code>; }</td></tr><tr><td align="left"><code>rules.lint.errors</code></td><td align="left"><code>number</code></td></tr><tr><td align="left"><code>rules.lint.findings</code></td><td align="left">{ <code>message</code>: <code>string</code>; <code>rule</code>: <code>string</code>; <code>severity</code>: <code>string</code>; }[]</td></tr><tr><td align="left"><code>rules.lint.info</code></td><td align="left"><code>number</code></td></tr><tr><td align="left"><code>rules.lint.warnings</code></td><td align="left"><code>number</code></td></tr><tr><td align="left"><code>rules.sizeBytes</code></td><td align="left"><code>number</code></td></tr><tr><td align="left"><code>rules.source</code></td><td align="left"><code>string</code></td></tr></tbody></table></div>
+<h2 id="functions">Functions</h2>
+<p><a id="inspect"></a></p>
+<h3 id="inspect">inspect()</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">function</span><span style="color:#61AFEF"> inspect</span><span style="color:#ABB2BF">(</span><span style="color:#E06C75;font-style:italic">sandbox</span><span style="color:#ABB2BF">: </span><span style="color:#E5C07B">LocalSandbox</span><span style="color:#ABB2BF">, </span><span style="color:#E06C75;font-style:italic">options</span><span style="color:#C678DD">?</span><span style="color:#ABB2BF">: </span><span style="color:#E5C07B">FirestoreInspectOptions</span><span style="color:#ABB2BF">): </span><span style="color:#E5C07B">FirestoreInspectReport</span><span style="color:#ABB2BF">;</span></span></code></pre>
+<p>Inspect Firestore rules, documents, and recent requests in one sandbox.</p>
+<h4 id="parameters">Parameters</h4>
+<div class="table-scroll">
+<table><thead><tr><th align="left">Parameter</th><th align="left">Type</th></tr></thead><tbody><tr><td align="left"><code>sandbox</code></td><td align="left"><code>LocalSandbox</code></td></tr><tr><td align="left"><code>options?</code></td><td align="left"><a href="#firestoreinspectoptions"><code>FirestoreInspectOptions</code></a></td></tr></tbody></table></div>
+<h4 id="returns">Returns</h4>
+<p><a href="#firestoreinspectreport"><code>FirestoreInspectReport</code></a></p>
+<hr>
+<p><a id="seeddocuments"></a></p>
+<h3 id="seeddocuments">seedDocuments()</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">function</span><span style="color:#61AFEF"> seedDocuments</span><span style="color:#ABB2BF">(</span><span style="color:#E06C75;font-style:italic">sandbox</span><span style="color:#ABB2BF">: </span><span style="color:#E5C07B">LocalSandbox</span><span style="color:#ABB2BF">, </span><span style="color:#E06C75;font-style:italic">documents</span><span style="color:#ABB2BF">: </span><span style="color:#E5C07B">Record</span><span style="color:#ABB2BF">&#x3C;</span><span style="color:#E5C07B">string</span><span style="color:#ABB2BF">, </span><span style="color:#E5C07B">DocumentData</span><span style="color:#ABB2BF">>): </span><span style="color:#E5C07B">LintResult</span><span style="color:#ABB2BF">;</span></span></code></pre>
+<p>Replace Firestore documents in bulk, preserving rules and bypassing evaluation.</p>
+<h4 id="parameters-1">Parameters</h4>
+<div class="table-scroll">
+<table><thead><tr><th align="left">Parameter</th><th align="left">Type</th></tr></thead><tbody><tr><td align="left"><code>sandbox</code></td><td align="left"><code>LocalSandbox</code></td></tr><tr><td align="left"><code>documents</code></td><td align="left"><code>Record</code>&#x3C;<code>string</code>, <code>DocumentData</code>></td></tr></tbody></table></div>
+<h4 id="returns-1">Returns</h4>
+<p><code>LintResult</code></p>
+<hr>
+<p><a id="setrules"></a></p>
+<h3 id="setrules">setRules()</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">function</span><span style="color:#61AFEF"> setRules</span><span style="color:#ABB2BF">(</span><span style="color:#E06C75;font-style:italic">sandbox</span><span style="color:#ABB2BF">: </span><span style="color:#E5C07B">LocalSandbox</span><span style="color:#ABB2BF">, </span><span style="color:#E06C75;font-style:italic">source</span><span style="color:#ABB2BF">: </span><span style="color:#E5C07B">string</span><span style="color:#ABB2BF">): </span><span style="color:#E5C07B">LintResult</span><span style="color:#ABB2BF">;</span></span></code></pre>
+<p>Load Firestore Rules into one sandbox and notify its live listeners.</p>
+<h4 id="parameters-2">Parameters</h4>
+<div class="table-scroll">
+<table><thead><tr><th align="left">Parameter</th><th align="left">Type</th></tr></thead><tbody><tr><td align="left"><code>sandbox</code></td><td align="left"><code>LocalSandbox</code></td></tr><tr><td align="left"><code>source</code></td><td align="left"><code>string</code></td></tr></tbody></table></div>
+<h4 id="returns-2">Returns</h4>
+<p><code>LintResult</code></p>
+<hr>
+<p><a id="snapshotdocuments"></a></p>
+<h3 id="snapshotdocuments">snapshotDocuments()</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">function</span><span style="color:#61AFEF"> snapshotDocuments</span><span style="color:#ABB2BF">(</span><span style="color:#E06C75;font-style:italic">sandbox</span><span style="color:#ABB2BF">: </span><span style="color:#E5C07B">LocalSandbox</span><span style="color:#ABB2BF">): </span><span style="color:#E5C07B">Record</span><span style="color:#ABB2BF">&#x3C;</span><span style="color:#E5C07B">string</span><span style="color:#ABB2BF">, </span><span style="color:#E5C07B">DocumentData</span><span style="color:#ABB2BF">>;</span></span></code></pre>
+<p>Snapshot only Firestore documents without traversing other sandbox services.</p>
+<h4 id="parameters-3">Parameters</h4>
+<div class="table-scroll">
+<table><thead><tr><th align="left">Parameter</th><th align="left">Type</th></tr></thead><tbody><tr><td align="left"><code>sandbox</code></td><td align="left"><code>LocalSandbox</code></td></tr></tbody></table></div>
+<h4 id="returns-3">Returns</h4>
+<p><code>Record</code>&#x3C;<code>string</code>, <code>DocumentData</code>></p>  </article> </main> <aside class="doc-toc api-symbols" aria-label="API symbols"> <h2 class="doc-toc-heading">Symbols</h2> <input class="api-symbol-filter" type="search" placeholder="Filter symbols" aria-label="Filter API symbols" data-api-symbol-filter> <div class="api-symbol-groups" data-api-symbol-groups> <section class="api-symbol-group" data-api-symbol-group> <a class="api-symbol-kind" href="#interfaces"> Interfaces </a> <ul> <li data-api-symbol="firestoreinspectoptions"> <a href="#firestoreinspectoptions">FirestoreInspectOptions</a> </li><li data-api-symbol="firestoreinspectreport"> <a href="#firestoreinspectreport">FirestoreInspectReport</a> </li> </ul> </section><section class="api-symbol-group" data-api-symbol-group> <a class="api-symbol-kind" href="#functions"> Functions </a> <ul> <li data-api-symbol="inspect()"> <a href="#inspect">inspect()</a> </li><li data-api-symbol="seeddocuments()"> <a href="#seeddocuments">seedDocuments()</a> </li><li data-api-symbol="setrules()"> <a href="#setrules">setRules()</a> </li><li data-api-symbol="snapshotdocuments()"> <a href="#snapshotdocuments">snapshotDocuments()</a> </li> </ul> </section> <p class="api-symbol-empty" data-api-symbol-empty hidden>No matching symbols</p> </div> </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-firestore-reference-api.md ADDED Viewed

@@ -0,0 +1,134 @@
+<!-- Generated from published package declarations via TypeDoc. Do not edit by hand; run bun run docs:api:generate. -->
+## Interfaces
+<a id="firestoreinspectoptions"></a>
+### FirestoreInspectOptions
+#### Properties
+| Property | Type | Description |
+| :------ | :------ | :------ |
+| <a id="recenteventlimit"></a> `recentEventLimit?` | `number` | Maximum number of recent requests and denials to return. Defaults to 10. |
+***
+<a id="firestoreinspectreport"></a>
+### FirestoreInspectReport
+Stable JSON-serializable Firestore diagnostic used by Studio and tools.
+#### Properties
+| Property | Type |
+| :------ | :------ |
+| <a id="documents"></a> `documents` | \{ `byCollection`: `Record`\<`string`, `number`\>; `totalCount`: `number`; \} |
+| `documents.byCollection` | `Record`\<`string`, `number`\> |
+| `documents.totalCount` | `number` |
+| <a id="events"></a> `events` | \{ `recentDenials`: \{ `auth`: `unknown`; `debugMessage?`: `string`; `method`: `string`; `path`: `string`; \}[]; `recentRequests`: \{ `auth`: `unknown`; `method`: `string`; `path`: `string`; `result`: `string`; \}[]; `totalCount`: `number`; \} |
+| `events.recentDenials` | \{ `auth`: `unknown`; `debugMessage?`: `string`; `method`: `string`; `path`: `string`; \}[] |
+| `events.recentRequests` | \{ `auth`: `unknown`; `method`: `string`; `path`: `string`; `result`: `string`; \}[] |
+| `events.totalCount` | `number` |
+| <a id="rules"></a> `rules` | \{ `isEmpty`: `boolean`; `lint`: \{ `errors`: `number`; `findings`: \{ `message`: `string`; `rule`: `string`; `severity`: `string`; \}[]; `info`: `number`; `warnings`: `number`; \}; `sizeBytes`: `number`; `source`: `string`; \} |
+| `rules.isEmpty` | `boolean` |
+| `rules.lint` | \{ `errors`: `number`; `findings`: \{ `message`: `string`; `rule`: `string`; `severity`: `string`; \}[]; `info`: `number`; `warnings`: `number`; \} |
+| `rules.lint.errors` | `number` |
+| `rules.lint.findings` | \{ `message`: `string`; `rule`: `string`; `severity`: `string`; \}[] |
+| `rules.lint.info` | `number` |
+| `rules.lint.warnings` | `number` |
+| `rules.sizeBytes` | `number` |
+| `rules.source` | `string` |
+## Functions
+<a id="inspect"></a>
+### inspect()
+```ts
+function inspect(sandbox: LocalSandbox, options?: FirestoreInspectOptions): FirestoreInspectReport;
+```
+Inspect Firestore rules, documents, and recent requests in one sandbox.
+#### Parameters
+| Parameter | Type |
+| :------ | :------ |
+| `sandbox` | `LocalSandbox` |
+| `options?` | [`FirestoreInspectOptions`](#firestoreinspectoptions) |
+#### Returns
+[`FirestoreInspectReport`](#firestoreinspectreport)
+***
+<a id="seeddocuments"></a>
+### seedDocuments()
+```ts
+function seedDocuments(sandbox: LocalSandbox, documents: Record<string, DocumentData>): LintResult;
+```
+Replace Firestore documents in bulk, preserving rules and bypassing evaluation.
+#### Parameters
+| Parameter | Type |
+| :------ | :------ |
+| `sandbox` | `LocalSandbox` |
+| `documents` | `Record`\<`string`, `DocumentData`\> |
+#### Returns
+`LintResult`
+***
+<a id="setrules"></a>
+### setRules()
+```ts
+function setRules(sandbox: LocalSandbox, source: string): LintResult;
+```
+Load Firestore Rules into one sandbox and notify its live listeners.
+#### Parameters
+| Parameter | Type |
+| :------ | :------ |
+| `sandbox` | `LocalSandbox` |
+| `source` | `string` |
+#### Returns
+`LintResult`
+***
+<a id="snapshotdocuments"></a>
+### snapshotDocuments()
+```ts
+function snapshotDocuments(sandbox: LocalSandbox): Record<string, DocumentData>;
+```
+Snapshot only Firestore documents without traversing other sandbox services.
+#### Parameters
+| Parameter | Type |
+| :------ | :------ |
+| `sandbox` | `LocalSandbox` |
+#### Returns
+`Record`\<`string`, `DocumentData`\>