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-firestore-reference-tool-factories/index.html ADDED Viewed

@@ -0,0 +1,51 @@
+<!DOCTYPE html><html lang="en"> <head><meta charset="UTF-8"><meta name="viewport" content="width=device-width, initial-scale=1.0"><title>Tool factories · 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/" aria-current="true"> 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/"> 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/" aria-current="true"> 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/"> 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-firestore/">pyric / firestore</a> </li><li> <span class="docs-breadcrumbs-sep" aria-hidden="true">/</span> <span>Reference</span> </li><li> <span class="docs-breadcrumbs-sep" aria-hidden="true">/</span> <span aria-current="page">Tool factories</span> </li> </ol> </nav>  <article class="prose">  <h1 id="tool-factories">Tool factories</h1>
+<p><code>createFirestoreDataTools(deps)</code> wraps the modular Firestore data plane as <code>@inbrowser/agent</code> tool handlers.</p>
+<pre class="astro-code one-dark-pro" style="background-color:#282c34;color:#abb2bf; overflow-x: auto;" tabindex="0" data-language="ts"><code><span class="line"><span style="color:#C678DD">import</span><span style="color:#ABB2BF"> { </span><span style="color:#E06C75">createFirestoreDataTools</span><span style="color:#ABB2BF"> } </span><span style="color:#C678DD">from</span><span style="color:#98C379"> 'pyric/firestore'</span><span style="color:#ABB2BF">;</span></span>
+<span class="line"><span style="color:#C678DD">import</span><span style="color:#ABB2BF"> { </span><span style="color:#E06C75">createToolRegistry</span><span style="color:#ABB2BF"> } </span><span style="color:#C678DD">from</span><span style="color:#98C379"> '@inbrowser/agent'</span><span style="color:#ABB2BF">;</span></span>
+<span class="line"></span>
+<span class="line"><span style="color:#C678DD">const</span><span style="color:#E5C07B"> tools</span><span style="color:#56B6C2"> =</span><span style="color:#61AFEF"> createFirestoreDataTools</span><span style="color:#ABB2BF">({</span></span>
+<span class="line"><span style="color:#61AFEF">  resolveDb</span><span style="color:#ABB2BF">: </span><span style="color:#C678DD">async</span><span style="color:#ABB2BF"> (</span><span style="color:#E06C75;font-style:italic">actor</span><span style="color:#ABB2BF">) </span><span style="color:#C678DD">=></span><span style="color:#7F848E;font-style:italic"> /* return a Firestore handle for this identity */</span><span style="color:#ABB2BF">,</span></span>
+<span class="line"><span style="color:#ABB2BF">});</span></span>
+<span class="line"></span>
+<span class="line"><span style="color:#C678DD">const</span><span style="color:#E5C07B"> registry</span><span style="color:#56B6C2"> =</span><span style="color:#61AFEF"> createToolRegistry</span><span style="color:#ABB2BF">();</span></span>
+<span class="line"><span style="color:#C678DD">for</span><span style="color:#ABB2BF"> (</span><span style="color:#C678DD">const</span><span style="color:#E5C07B"> h</span><span style="color:#C678DD"> of</span><span style="color:#E06C75"> tools</span><span style="color:#ABB2BF">) </span><span style="color:#E5C07B">registry</span><span style="color:#ABB2BF">.</span><span style="color:#61AFEF">register</span><span style="color:#ABB2BF">(</span><span style="color:#E06C75">h</span><span style="color:#ABB2BF">);</span></span></code></pre>
+<h2 id="firestoredatatooldeps"><code>FirestoreDataToolDeps</code></h2>
+<pre class="astro-code one-dark-pro" style="background-color:#282c34;color:#abb2bf; overflow-x: auto;" tabindex="0" data-language="ts"><code><span class="line"><span style="color:#C678DD">interface</span><span style="color:#E5C07B"> FirestoreDataToolDeps</span><span style="color:#ABB2BF"> {</span></span>
+<span class="line"><span style="color:#61AFEF">  resolveDb</span><span style="color:#ABB2BF">: (</span><span style="color:#E06C75;font-style:italic">as</span><span style="color:#C678DD">?</span><span style="color:#ABB2BF">: </span><span style="color:#E5C07B">As</span><span style="color:#ABB2BF">) </span><span style="color:#C678DD">=></span><span style="color:#E5C07B"> Promise</span><span style="color:#ABB2BF">&#x3C;</span><span style="color:#E5C07B">Firestore</span><span style="color:#ABB2BF">> | </span><span style="color:#E5C07B">Firestore</span><span style="color:#ABB2BF">;</span></span>
+<span class="line"><span style="color:#ABB2BF">}</span></span></code></pre>
+<p>The resolver fires per-dispatch with the op’s <code>as</code> value. Hosts decide what backend to return:</p>
+<ul>
+<li><strong><code>'admin'</code> (or omitted)</strong>: an admin-mode handle that BYPASSES rules. The default, for sandbox seeding.</li>
+<li><strong><code>{ uid, claims? }</code></strong>: a rules-enforcing handle acting as that user, e.g. <code>getFirestore(sandbox.withAuth({ uid, token: claims }))</code> or a <code>FirebaseServerApp</code>-backed Firestore.</li>
+</ul>
+<p>A sandbox resolver may default to admin. A resolver wired to a promoted/real backend MUST reject <code>'admin'</code> and require an explicit identity.</p>
+<h2 id="as"><code>As</code></h2>
+<pre class="astro-code one-dark-pro" style="background-color:#282c34;color:#abb2bf; overflow-x: auto;" tabindex="0" data-language="ts"><code><span class="line"><span style="color:#C678DD">type</span><span style="color:#E5C07B"> As</span><span style="color:#56B6C2"> =</span><span style="color:#98C379"> 'admin'</span><span style="color:#ABB2BF"> | </span><span style="color:#E5C07B">UserAuth</span><span style="color:#ABB2BF">;</span></span>
+<span class="line"></span>
+<span class="line"><span style="color:#C678DD">interface</span><span style="color:#E5C07B"> UserAuth</span><span style="color:#ABB2BF"> {</span></span>
+<span class="line"><span style="color:#E06C75">  uid</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">  claims</span><span style="color:#C678DD">?</span><span style="color:#ABB2BF">: </span><span style="color:#E5C07B">Record</span><span style="color:#ABB2BF">&#x3C;</span><span style="color:#E5C07B">string</span><span style="color:#ABB2BF">, </span><span style="color:#E5C07B">unknown</span><span style="color:#ABB2BF">>;</span></span>
+<span class="line"><span style="color:#ABB2BF">}</span></span></code></pre>
+<p>The value passed to <code>resolveDb</code> from a tool call’s <code>as</code> field. The explicit <code>'admin'</code> literal makes bypass <strong>named</strong> (you opt into it by writing <code>as: 'admin'</code> rather than it being the silent consequence of omitting an auth field), and <code>{ uid }</code> names the user to act as. Omitting <code>as</code> is treated as <code>'admin'</code>.</p>
+<h2 id="what-the-factory-exposes">What the factory exposes</h2>
+<p>Each call to <code>createFirestoreDataTools</code> returns these tool handlers:</p>
+<ul>
+<li><code>firestore_get_document</code>, <code>firestore_list_documents</code>, <code>firestore_query_where</code>: reads.</li>
+<li><code>firestore_create_document</code> (explicit path), <code>firestore_add_document</code> (auto-id, mirrors <code>addDoc</code>), <code>firestore_update_document</code>, <code>firestore_delete_document</code>: writes.</li>
+<li><code>firestore_batch_write</code>: many <code>set</code> / <code>update</code> / <code>delete</code> in one call (seed / bulk-edit).</li>
+</ul>
+<p>Every tool takes the optional <code>as</code> arg above (admin by default). The exact parameter schemas are surfaced through <code>@inbrowser/agent</code>’s standard <code>ToolHandler.parameters</code> (JSON Schema).</p>
+<h2 id="why-a-resolver-not-a-single-firestore-handle">Why a resolver, not a single Firestore handle</h2>
+<p>The resolver fires per-dispatch. A single Firestore handle baked into the factory would:</p>
+<ul>
+<li>Pin every tool call to one identity. The tool layer’s <code>as</code> field would be ignored.</li>
+<li>Survive <code>sandbox.reset()</code> only if the handle is per-call-resolved through the sandbox (which <code>pyric/firestore</code>’s opaque handle doesn’t expose).</li>
+<li>Force the host to re-register tools whenever the backend changes.</li>
+</ul>
+<p>The resolver dodges all three. Hosts that only ever write as admin wire <code>() => adminDb</code> and the cost is one function call per dispatch.</p>
+<h2 id="schema-clarity">Schema clarity</h2>
+<p>The <code>as</code> argument has a proper JSONSchema shape (<code>'admin'</code> OR <code>{ uid, claims? }</code>), so an agent sees the contract in the tool description: bypass is <code>as: 'admin'</code>, rules-enforcement is <code>as: { uid }</code>. Without this, agents discover the auth model by trial and error: calling the rules-enforced path, getting denied, then inferring the admin path.</p>
+<h2 id="where-to-look-next">Where to look next</h2>
+<ul>
+<li>For tool registry and dispatch, see the <code>@inbrowser/agent</code> package.</li>
+</ul>  </article> </main> <aside class="doc-toc" aria-label="On this page"> <h2 class="doc-toc-heading">On this page</h2> <ul> <li data-depth="2"> <a href="#firestoredatatooldeps">FirestoreDataToolDeps</a> </li><li data-depth="2"> <a href="#as">As</a> </li><li data-depth="2"> <a href="#what-the-factory-exposes">What the factory exposes</a> </li><li data-depth="2"> <a href="#why-a-resolver-not-a-single-firestore-handle">Why a resolver, not a single Firestore handle</a> </li><li data-depth="2"> <a href="#schema-clarity">Schema clarity</a> </li><li data-depth="2"> <a href="#where-to-look-next">Where to look next</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-firestore-reference-tool-factories.md ADDED Viewed

@@ -0,0 +1,71 @@
+# Tool factories
+`createFirestoreDataTools(deps)` wraps the modular Firestore data plane as `@inbrowser/agent` tool handlers.
+```ts
+import { createFirestoreDataTools } from 'pyric/firestore';
+import { createToolRegistry } from '@inbrowser/agent';
+const tools = createFirestoreDataTools({
+  resolveDb: async (actor) => /* return a Firestore handle for this identity */,
+});
+const registry = createToolRegistry();
+for (const h of tools) registry.register(h);
+```
+## `FirestoreDataToolDeps`
+```ts
+interface FirestoreDataToolDeps {
+  resolveDb: (as?: As) => Promise<Firestore> | Firestore;
+}
+```
+The resolver fires per-dispatch with the op's `as` value. Hosts decide what backend to return:
+- **`'admin'` (or omitted)**: an admin-mode handle that BYPASSES rules. The default, for sandbox seeding.
+- **`{ uid, claims? }`**: a rules-enforcing handle acting as that user, e.g. `getFirestore(sandbox.withAuth({ uid, token: claims }))` or a `FirebaseServerApp`-backed Firestore.
+A sandbox resolver may default to admin. A resolver wired to a promoted/real backend MUST reject `'admin'` and require an explicit identity.
+## `As`
+```ts
+type As = 'admin' | UserAuth;
+interface UserAuth {
+  uid: string;
+  claims?: Record<string, unknown>;
+}
+```
+The value passed to `resolveDb` from a tool call's `as` field. The explicit `'admin'` literal makes bypass **named** (you opt into it by writing `as: 'admin'` rather than it being the silent consequence of omitting an auth field), and `{ uid }` names the user to act as. Omitting `as` is treated as `'admin'`.
+## What the factory exposes
+Each call to `createFirestoreDataTools` returns these tool handlers:
+- `firestore_get_document`, `firestore_list_documents`, `firestore_query_where`: reads.
+- `firestore_create_document` (explicit path), `firestore_add_document` (auto-id, mirrors `addDoc`), `firestore_update_document`, `firestore_delete_document`: writes.
+- `firestore_batch_write`: many `set` / `update` / `delete` in one call (seed / bulk-edit).
+Every tool takes the optional `as` arg above (admin by default). The exact parameter schemas are surfaced through `@inbrowser/agent`'s standard `ToolHandler.parameters` (JSON Schema).
+## Why a resolver, not a single Firestore handle
+The resolver fires per-dispatch. A single Firestore handle baked into the factory would:
+- Pin every tool call to one identity. The tool layer's `as` field would be ignored.
+- Survive `sandbox.reset()` only if the handle is per-call-resolved through the sandbox (which `pyric/firestore`'s opaque handle doesn't expose).
+- Force the host to re-register tools whenever the backend changes.
+The resolver dodges all three. Hosts that only ever write as admin wire `() => adminDb` and the cost is one function call per dispatch.
+## Schema clarity
+The `as` argument has a proper JSONSchema shape (`'admin'` OR `{ uid, claims? }`), so an agent sees the contract in the tool description: bypass is `as: 'admin'`, rules-enforcement is `as: { uid }`. Without this, agents discover the auth model by trial and error: calling the rules-enforced path, getting denied, then inferring the admin path.
+## Where to look next
+- For tool registry and dispatch, see the `@inbrowser/agent` package.

package/dist/serve/docs-ui/docs/pyric-firestore-tutorials-01-write-a-sandbox-demo/index.html ADDED Viewed

@@ -0,0 +1,130 @@
+<!DOCTYPE html><html lang="en"> <head><meta charset="UTF-8"><meta name="viewport" content="width=device-width, initial-scale=1.0"><title>Write a sandbox-backed demo · 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/" aria-current="true"> 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/"> 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/" aria-current="true"> 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/"> 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-firestore/">pyric / firestore</a> </li><li> <span class="docs-breadcrumbs-sep" aria-hidden="true">/</span> <span>Tutorials</span> </li><li> <span class="docs-breadcrumbs-sep" aria-hidden="true">/</span> <span aria-current="page">Sandbox-backed demo</span> </li> </ol> </nav>  <article class="prose">  <h1 id="write-a-sandbox-backed-demo">Write a sandbox-backed demo</h1>
+<p>Build a tiny notes app with <code>pyric/firestore</code> against the sandbox backend. By the end you’ll have set rules, seeded data, written, read, watched a query, and seen a denial, all in-process.</p>
+<h2 id="set-up">Set up</h2>
+<pre class="astro-code one-dark-pro" style="background-color:#282c34;color:#abb2bf; overflow-x: auto;" tabindex="0" data-language="bash"><code><span class="line"><span style="color:#61AFEF">mkdir</span><span style="color:#98C379"> notes-demo</span><span style="color:#ABB2BF"> &#x26;&#x26; </span><span style="color:#56B6C2">cd</span><span style="color:#98C379"> notes-demo</span></span>
+<span class="line"><span style="color:#61AFEF">bun</span><span style="color:#98C379"> init</span><span style="color:#D19A66"> -y</span></span>
+<span class="line"><span style="color:#61AFEF">bun</span><span style="color:#98C379"> add</span><span style="color:#98C379"> pyric</span></span></code></pre>
+<h2 id="step-1-boot-the-sandbox-and-a-firestore-handle">Step 1: Boot the sandbox and a Firestore handle</h2>
+<p>Create <code>demo.ts</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">import</span><span style="color:#ABB2BF"> { </span><span style="color:#E06C75">initializeSandbox</span><span style="color:#ABB2BF">, </span><span style="color:#E06C75">SandboxError</span><span style="color:#ABB2BF"> } </span><span style="color:#C678DD">from</span><span style="color:#98C379"> 'pyric/sandbox'</span><span style="color:#ABB2BF">;</span></span>
+<span class="line"><span style="color:#C678DD">import</span><span style="color:#ABB2BF"> {</span></span>
+<span class="line"><span style="color:#E06C75">  getFirestore</span><span style="color:#ABB2BF">,</span></span>
+<span class="line"><span style="color:#E06C75">  doc</span><span style="color:#ABB2BF">,</span></span>
+<span class="line"><span style="color:#E06C75">  setDoc</span><span style="color:#ABB2BF">,</span></span>
+<span class="line"><span style="color:#E06C75">  getDoc</span><span style="color:#ABB2BF">,</span></span>
+<span class="line"><span style="color:#E06C75">  collection</span><span style="color:#ABB2BF">,</span></span>
+<span class="line"><span style="color:#E06C75">  query</span><span style="color:#ABB2BF">,</span></span>
+<span class="line"><span style="color:#E06C75">  where</span><span style="color:#ABB2BF">,</span></span>
+<span class="line"><span style="color:#E06C75">  onSnapshot</span><span style="color:#ABB2BF">,</span></span>
+<span class="line"><span style="color:#ABB2BF">} </span><span style="color:#C678DD">from</span><span style="color:#98C379"> 'pyric/firestore'</span><span style="color:#ABB2BF">;</span></span>
+<span class="line"><span style="color:#C678DD">import</span><span style="color:#ABB2BF"> { </span><span style="color:#E06C75">setRules</span><span style="color:#ABB2BF">, </span><span style="color:#E06C75">snapshotDocuments</span><span style="color:#ABB2BF"> } </span><span style="color:#C678DD">from</span><span style="color:#98C379"> 'pyric/sandbox/firestore'</span><span style="color:#ABB2BF">;</span></span>
+<span class="line"></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>
+<span class="line"><span style="color:#C678DD">const</span><span style="color:#E5C07B"> db</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>
+<span class="line"><span style="color:#E5C07B">console</span><span style="color:#ABB2BF">.</span><span style="color:#61AFEF">log</span><span style="color:#ABB2BF">(</span><span style="color:#98C379">'Sandbox-backed Firestore ready.'</span><span style="color:#ABB2BF">);</span></span></code></pre>
+<p>Run with <code>bun run demo.ts</code>. You should see the line and nothing else.</p>
+<h2 id="step-2-deploy-rules">Step 2: Deploy rules</h2>
+<pre class="astro-code one-dark-pro" style="background-color:#282c34;color:#abb2bf; overflow-x: auto;" tabindex="0" data-language="ts"><code><span class="line"><span style="color:#C678DD">const</span><span style="color:#E5C07B"> lint</span><span style="color:#56B6C2"> =</span><span style="color:#61AFEF"> setRules</span><span style="color:#ABB2BF">(</span><span style="color:#E06C75">sandbox</span><span style="color:#ABB2BF">, </span><span style="color:#98C379">`rules_version = '2';</span></span>
+<span class="line"><span style="color:#98C379">service cloud.firestore {</span></span>
+<span class="line"><span style="color:#98C379">  match /databases/{db}/documents {</span></span>
+<span class="line"><span style="color:#98C379">    match /notes/{id} {</span></span>
+<span class="line"><span style="color:#98C379">      allow read: if request.auth != null;</span></span>
+<span class="line"><span style="color:#98C379">      allow write: if request.auth.uid == request.resource.data.ownerId;</span></span>
+<span class="line"><span style="color:#98C379">    }</span></span>
+<span class="line"><span style="color:#98C379">  }</span></span>
+<span class="line"><span style="color:#98C379">}`</span><span style="color:#ABB2BF">);</span></span>
+<span class="line"></span>
+<span class="line"><span style="color:#C678DD">if</span><span style="color:#ABB2BF"> (</span><span style="color:#E5C07B">lint</span><span style="color:#ABB2BF">.</span><span style="color:#E5C07B">warnings</span><span style="color:#ABB2BF">.</span><span style="color:#61AFEF">some</span><span style="color:#ABB2BF">((</span><span style="color:#E06C75;font-style:italic">w</span><span style="color:#ABB2BF">) </span><span style="color:#C678DD">=></span><span style="color:#E5C07B"> w</span><span style="color:#ABB2BF">.</span><span style="color:#E06C75">severity</span><span style="color:#56B6C2"> ===</span><span style="color:#98C379"> 'error'</span><span style="color:#ABB2BF">)) {</span></span>
+<span class="line"><span style="color:#C678DD">  throw</span><span style="color:#C678DD"> new</span><span style="color:#61AFEF"> Error</span><span style="color:#ABB2BF">(</span><span style="color:#98C379">'rules failed to lint'</span><span style="color:#ABB2BF">);</span></span>
+<span class="line"><span style="color:#ABB2BF">}</span></span>
+<span class="line"><span style="color:#E5C07B">console</span><span style="color:#ABB2BF">.</span><span style="color:#61AFEF">log</span><span style="color:#ABB2BF">(</span><span style="color:#98C379">'Rules deployed.'</span><span style="color:#ABB2BF">);</span></span></code></pre>
+<p>Firestore controls receive the owning <code>Sandbox</code>, while data-plane functions
+receive <code>db</code>. Lint warnings are visible. Surface them if any are errors.</p>
+<h2 id="step-3-write-and-read">Step 3: Write and read</h2>
+<pre class="astro-code one-dark-pro" style="background-color:#282c34;color:#abb2bf; overflow-x: auto;" tabindex="0" data-language="ts"><code><span class="line"><span style="color:#C678DD">await</span><span style="color:#61AFEF"> setDoc</span><span style="color:#ABB2BF">(</span><span style="color:#61AFEF">doc</span><span style="color:#ABB2BF">(</span><span style="color:#E06C75">db</span><span style="color:#ABB2BF">, </span><span style="color:#98C379">'notes'</span><span style="color:#ABB2BF">, </span><span style="color:#98C379">'n1'</span><span style="color:#ABB2BF">), {</span></span>
+<span class="line"><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:#E06C75">  title</span><span style="color:#ABB2BF">: </span><span style="color:#98C379">'My first note'</span><span style="color:#ABB2BF">,</span></span>
+<span class="line"><span style="color:#ABB2BF">});</span></span>
+<span class="line"></span>
+<span class="line"><span style="color:#C678DD">const</span><span style="color:#E5C07B"> snap</span><span style="color:#56B6C2"> =</span><span style="color:#C678DD"> await</span><span style="color:#61AFEF"> getDoc</span><span style="color:#ABB2BF">(</span><span style="color:#61AFEF">doc</span><span style="color:#ABB2BF">(</span><span style="color:#E06C75">db</span><span style="color:#ABB2BF">, </span><span style="color:#98C379">'notes'</span><span style="color:#ABB2BF">, </span><span style="color:#98C379">'n1'</span><span style="color:#ABB2BF">));</span></span>
+<span class="line"><span style="color:#E5C07B">console</span><span style="color:#ABB2BF">.</span><span style="color:#61AFEF">log</span><span style="color:#ABB2BF">(</span><span style="color:#98C379">'Read back:'</span><span style="color:#ABB2BF">, </span><span style="color:#E5C07B">snap</span><span style="color:#ABB2BF">.</span><span style="color:#61AFEF">data</span><span style="color:#ABB2BF">());</span></span></code></pre>
+<p>Output: <code>Read back: { ownerId: "alice", title: "My first note" }</code>.</p>
+<h2 id="step-4-query">Step 4: Query</h2>
+<pre class="astro-code one-dark-pro" style="background-color:#282c34;color:#abb2bf; overflow-x: auto;" tabindex="0" data-language="ts"><code><span class="line"><span style="color:#C678DD">import</span><span style="color:#ABB2BF"> { </span><span style="color:#E06C75">getDocs</span><span style="color:#ABB2BF"> } </span><span style="color:#C678DD">from</span><span style="color:#98C379"> 'pyric/firestore'</span><span style="color:#ABB2BF">;</span></span>
+<span class="line"></span>
+<span class="line"><span style="color:#C678DD">await</span><span style="color:#61AFEF"> setDoc</span><span style="color:#ABB2BF">(</span><span style="color:#61AFEF">doc</span><span style="color:#ABB2BF">(</span><span style="color:#E06C75">db</span><span style="color:#ABB2BF">, </span><span style="color:#98C379">'notes'</span><span style="color:#ABB2BF">, </span><span style="color:#98C379">'n2'</span><span style="color:#ABB2BF">), {</span></span>
+<span class="line"><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:#E06C75">  title</span><span style="color:#ABB2BF">: </span><span style="color:#98C379">'Second note'</span><span style="color:#ABB2BF">,</span></span>
+<span class="line"><span style="color:#E06C75">  archived</span><span style="color:#ABB2BF">: </span><span style="color:#D19A66">true</span><span style="color:#ABB2BF">,</span></span>
+<span class="line"><span style="color:#ABB2BF">});</span></span>
+<span class="line"><span style="color:#C678DD">await</span><span style="color:#61AFEF"> setDoc</span><span style="color:#ABB2BF">(</span><span style="color:#61AFEF">doc</span><span style="color:#ABB2BF">(</span><span style="color:#E06C75">db</span><span style="color:#ABB2BF">, </span><span style="color:#98C379">'notes'</span><span style="color:#ABB2BF">, </span><span style="color:#98C379">'n3'</span><span style="color:#ABB2BF">), {</span></span>
+<span class="line"><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:#E06C75">  title</span><span style="color:#ABB2BF">: </span><span style="color:#98C379">'Third note'</span><span style="color:#ABB2BF">,</span></span>
+<span class="line"><span style="color:#ABB2BF">});</span></span>
+<span class="line"></span>
+<span class="line"><span style="color:#C678DD">const</span><span style="color:#E5C07B"> q</span><span style="color:#56B6C2"> =</span><span style="color:#61AFEF"> query</span><span style="color:#ABB2BF">(</span></span>
+<span class="line"><span style="color:#61AFEF">  collection</span><span style="color:#ABB2BF">(</span><span style="color:#E06C75">db</span><span style="color:#ABB2BF">, </span><span style="color:#98C379">'notes'</span><span style="color:#ABB2BF">),</span></span>
+<span class="line"><span style="color:#61AFEF">  where</span><span style="color:#ABB2BF">(</span><span style="color:#98C379">'archived'</span><span style="color:#ABB2BF">, </span><span style="color:#98C379">'!='</span><span style="color:#ABB2BF">, </span><span style="color:#D19A66">true</span><span style="color:#ABB2BF">),  </span><span style="color:#7F848E;font-style:italic">// null and false both qualify</span></span>
+<span class="line"><span style="color:#ABB2BF">);</span></span>
+<span class="line"><span style="color:#C678DD">const</span><span style="color:#E5C07B"> results</span><span style="color:#56B6C2"> =</span><span style="color:#C678DD"> await</span><span style="color:#61AFEF"> getDocs</span><span style="color:#ABB2BF">(</span><span style="color:#E06C75">q</span><span style="color:#ABB2BF">);</span></span>
+<span class="line"><span style="color:#E5C07B">console</span><span style="color:#ABB2BF">.</span><span style="color:#61AFEF">log</span><span style="color:#ABB2BF">(</span><span style="color:#98C379">`Found </span><span style="color:#C678DD">${</span><span style="color:#E5C07B">results</span><span style="color:#ABB2BF">.</span><span style="color:#E06C75">size</span><span style="color:#C678DD">}</span><span style="color:#98C379"> unarchived notes:`</span><span style="color:#ABB2BF">);</span></span>
+<span class="line"><span style="color:#E5C07B">results</span><span style="color:#ABB2BF">.</span><span style="color:#61AFEF">forEach</span><span style="color:#ABB2BF">((</span><span style="color:#E06C75;font-style:italic">d</span><span style="color:#ABB2BF">) </span><span style="color:#C678DD">=></span><span style="color:#E5C07B"> console</span><span style="color:#ABB2BF">.</span><span style="color:#61AFEF">log</span><span style="color:#ABB2BF">(</span><span style="color:#98C379">' '</span><span style="color:#ABB2BF">, </span><span style="color:#E5C07B">d</span><span style="color:#ABB2BF">.</span><span style="color:#E06C75">id</span><span style="color:#ABB2BF">, </span><span style="color:#E5C07B">d</span><span style="color:#ABB2BF">.</span><span style="color:#61AFEF">data</span><span style="color:#ABB2BF">().</span><span style="color:#E06C75">title</span><span style="color:#ABB2BF">));</span></span></code></pre>
+<p>Output:</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>Found 2 unarchived notes:</span></span>
+<span class="line"><span>  n1 My first note</span></span>
+<span class="line"><span>  n3 Third note</span></span></code></pre>
+<p>The query runs against the sandbox’s <code>LocalEnvironment</code>, no network. The filter evaluates correctly on <code>getDocs</code>.</p>
+<h2 id="step-5-watch-with-onsnapshot">Step 5: Watch with <code>onSnapshot</code></h2>
+<pre class="astro-code one-dark-pro" style="background-color:#282c34;color:#abb2bf; overflow-x: auto;" tabindex="0" data-language="ts"><code><span class="line"><span style="color:#C678DD">const</span><span style="color:#E5C07B"> changes</span><span style="color:#ABB2BF">: </span><span style="color:#E5C07B">string</span><span style="color:#ABB2BF">[] </span><span style="color:#56B6C2">=</span><span style="color:#ABB2BF"> [];</span></span>
+<span class="line"><span style="color:#C678DD">const</span><span style="color:#E5C07B"> unsubscribe</span><span style="color:#56B6C2"> =</span><span style="color:#61AFEF"> onSnapshot</span><span style="color:#ABB2BF">(</span></span>
+<span class="line"><span style="color:#61AFEF">  query</span><span style="color:#ABB2BF">(</span><span style="color:#61AFEF">collection</span><span style="color:#ABB2BF">(</span><span style="color:#E06C75">db</span><span style="color:#ABB2BF">, </span><span style="color:#98C379">'notes'</span><span style="color:#ABB2BF">)),</span></span>
+<span class="line"><span style="color:#ABB2BF">  (</span><span style="color:#E06C75;font-style:italic">snap</span><span style="color:#ABB2BF">) </span><span style="color:#C678DD">=></span><span style="color:#ABB2BF"> {</span></span>
+<span class="line"><span style="color:#C678DD">    for</span><span style="color:#ABB2BF"> (</span><span style="color:#C678DD">const</span><span style="color:#E5C07B"> change</span><span style="color:#C678DD"> of</span><span style="color:#E5C07B"> snap</span><span style="color:#ABB2BF">.</span><span style="color:#61AFEF">docChanges</span><span style="color:#ABB2BF">()) {</span></span>
+<span class="line"><span style="color:#E5C07B">      changes</span><span style="color:#ABB2BF">.</span><span style="color:#61AFEF">push</span><span style="color:#ABB2BF">(</span><span style="color:#98C379">`</span><span style="color:#C678DD">${</span><span style="color:#E5C07B">change</span><span style="color:#ABB2BF">.</span><span style="color:#E06C75">type</span><span style="color:#C678DD">}</span><span style="color:#C678DD"> ${</span><span style="color:#E5C07B">change</span><span style="color:#ABB2BF">.</span><span style="color:#E5C07B">doc</span><span style="color:#ABB2BF">.</span><span style="color:#E06C75">id</span><span style="color:#C678DD">}</span><span style="color:#98C379">`</span><span style="color:#ABB2BF">);</span></span>
+<span class="line"><span style="color:#ABB2BF">    }</span></span>
+<span class="line"><span style="color:#ABB2BF">  },</span></span>
+<span class="line"><span style="color:#ABB2BF">);</span></span>
+<span class="line"></span>
+<span class="line"><span style="color:#C678DD">await</span><span style="color:#61AFEF"> setDoc</span><span style="color:#ABB2BF">(</span><span style="color:#61AFEF">doc</span><span style="color:#ABB2BF">(</span><span style="color:#E06C75">db</span><span style="color:#ABB2BF">, </span><span style="color:#98C379">'notes'</span><span style="color:#ABB2BF">, </span><span style="color:#98C379">'n4'</span><span style="color:#ABB2BF">), {</span></span>
+<span class="line"><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:#E06C75">  title</span><span style="color:#ABB2BF">: </span><span style="color:#98C379">'Watched note'</span><span style="color:#ABB2BF">,</span></span>
+<span class="line"><span style="color:#ABB2BF">});</span></span>
+<span class="line"></span>
+<span class="line"><span style="color:#C678DD">await</span><span style="color:#C678DD"> new</span><span style="color:#E5C07B"> Promise</span><span style="color:#ABB2BF">((</span><span style="color:#E06C75;font-style:italic">resolve</span><span style="color:#ABB2BF">) </span><span style="color:#C678DD">=></span><span style="color:#61AFEF"> setTimeout</span><span style="color:#ABB2BF">(</span><span style="color:#E06C75">resolve</span><span style="color:#ABB2BF">, </span><span style="color:#D19A66">10</span><span style="color:#ABB2BF">));  </span><span style="color:#7F848E;font-style:italic">// let the listener fire</span></span>
+<span class="line"></span>
+<span class="line"><span style="color:#E5C07B">console</span><span style="color:#ABB2BF">.</span><span style="color:#61AFEF">log</span><span style="color:#ABB2BF">(</span><span style="color:#98C379">'Saw changes:'</span><span style="color:#ABB2BF">, </span><span style="color:#E06C75">changes</span><span style="color:#ABB2BF">);</span></span>
+<span class="line"><span style="color:#61AFEF">unsubscribe</span><span style="color:#ABB2BF">();</span></span></code></pre>
+<p>Output something like:</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>Saw changes: [</span></span>
+<span class="line"><span>  'added n1', 'added n2', 'added n3',  // initial fire</span></span>
+<span class="line"><span>  'added n4',                          // write</span></span>
+<span class="line"><span>]</span></span></code></pre>
+<h2 id="step-6-try-a-denied-write">Step 6: Try a denied write</h2>
+<pre class="astro-code one-dark-pro" style="background-color:#282c34;color:#abb2bf; overflow-x: auto;" tabindex="0" data-language="ts"><code><span class="line"><span style="color:#C678DD">const</span><span style="color:#E5C07B"> bob</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">try</span><span style="color:#ABB2BF"> {</span></span>
+<span class="line"><span style="color:#C678DD">  await</span><span style="color:#61AFEF"> setDoc</span><span style="color:#ABB2BF">(</span><span style="color:#61AFEF">doc</span><span style="color:#ABB2BF">(</span><span style="color:#E06C75">bob</span><span style="color:#ABB2BF">, </span><span style="color:#98C379">'notes'</span><span style="color:#ABB2BF">, </span><span style="color:#98C379">'b1'</span><span style="color:#ABB2BF">), {</span></span>
+<span class="line"><span style="color:#E06C75">    ownerId</span><span style="color:#ABB2BF">: </span><span style="color:#98C379">'alice'</span><span style="color:#ABB2BF">,  </span><span style="color:#7F848E;font-style:italic">// Bob lies about ownership</span></span>
+<span class="line"><span style="color:#E06C75">    title</span><span style="color:#ABB2BF">: </span><span style="color:#98C379">'tamper'</span><span style="color:#ABB2BF">,</span></span>
+<span class="line"><span style="color:#ABB2BF">  });</span></span>
+<span class="line"><span style="color:#ABB2BF">} </span><span style="color:#C678DD">catch</span><span style="color:#ABB2BF"> (</span><span style="color:#E06C75">e</span><span style="color:#ABB2BF">) {</span></span>
+<span class="line"><span style="color:#C678DD">  if</span><span style="color:#ABB2BF"> (</span><span style="color:#E06C75">e</span><span style="color:#C678DD"> instanceof</span><span style="color:#E5C07B"> SandboxError</span><span style="color:#56B6C2"> &#x26;&#x26;</span><span style="color:#E5C07B"> e</span><span style="color:#ABB2BF">.</span><span style="color:#E06C75">code</span><span style="color:#56B6C2"> ===</span><span style="color:#98C379"> 'permission-denied'</span><span style="color:#ABB2BF">) {</span></span>
+<span class="line"><span style="color:#E5C07B">    console</span><span style="color:#ABB2BF">.</span><span style="color:#61AFEF">log</span><span style="color:#ABB2BF">(</span><span style="color:#98C379">'Bob was denied:'</span><span style="color:#ABB2BF">, </span><span style="color:#E5C07B">e</span><span style="color:#ABB2BF">.</span><span style="color:#E5C07B">denialContext</span><span style="color:#ABB2BF">?.</span><span style="color:#E06C75">reasons</span><span style="color:#ABB2BF">?.[</span><span style="color:#D19A66">0</span><span style="color:#ABB2BF">]);</span></span>
+<span class="line"><span style="color:#ABB2BF">  }</span></span>
+<span class="line"><span style="color:#ABB2BF">}</span></span></code></pre>
+<p>Output: <code>Bob was denied: Rule #1 (write) → deny</code>. The write rule checks <code>request.auth.uid == request.resource.data.ownerId</code>. Bob’s UID doesn’t match Alice’s, so the rule denies and <code>SandboxError</code> surfaces with full context.</p>
+<h2 id="step-7-dump-the-state">Step 7: Dump the state</h2>
+<pre class="astro-code one-dark-pro" style="background-color:#282c34;color:#abb2bf; overflow-x: auto;" tabindex="0" data-language="ts"><code><span class="line"><span style="color:#E5C07B">console</span><span style="color:#ABB2BF">.</span><span style="color:#61AFEF">log</span><span style="color:#ABB2BF">(</span><span style="color:#98C379">'Final state:'</span><span style="color:#ABB2BF">, </span><span style="color:#61AFEF">snapshotDocuments</span><span style="color:#ABB2BF">(</span><span style="color:#E06C75">sandbox</span><span style="color:#ABB2BF">));</span></span></code></pre>
+<p>Every stored document, including Alice’s writes and excluding Bob’s denied one.</p>
+<h2 id="what-you-have-learned">What you have learned</h2>
+<ul>
+<li><code>getFirestore(sandbox.withAuth(...))</code> produces a sandbox-backed handle.</li>
+<li>The function shape (<code>doc</code>, <code>setDoc</code>, <code>getDoc</code>, <code>onSnapshot</code>) matches <code>firebase/firestore</code>.</li>
+<li>Firestore controls such as <code>setRules</code> and <code>snapshotDocuments</code> are sandbox-only and live at <code>pyric/sandbox/firestore</code>.</li>
+<li><code>SandboxError</code> with <code>denialContext</code> is the same shape you see from <code>pyric-admin</code> and from <code>Sandbox.onDenial</code>.</li>
+</ul>
+<h2 id="what-to-do-next">What to do next</h2>
+<p>The same canonical Firebase imports can select this mirror in development and
+remain Firebase in production. Follow <a href="../pyric-firestore-tutorials-02-swap-to-prod-backend/">Run the demo against production</a>
+to see how package resolution controls that boundary.</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="#set-up">Set up</a> </li><li data-depth="2"> <a href="#step-1-boot-the-sandbox-and-a-firestore-handle">Step 1: Boot the sandbox and a Firestore handle</a> </li><li data-depth="2"> <a href="#step-2-deploy-rules">Step 2: Deploy rules</a> </li><li data-depth="2"> <a href="#step-3-write-and-read">Step 3: Write and read</a> </li><li data-depth="2"> <a href="#step-4-query">Step 4: Query</a> </li><li data-depth="2"> <a href="#step-5-watch-with-onsnapshot">Step 5: Watch with onSnapshot</a> </li><li data-depth="2"> <a href="#step-6-try-a-denied-write">Step 6: Try a denied write</a> </li><li data-depth="2"> <a href="#step-7-dump-the-state">Step 7: Dump the state</a> </li><li data-depth="2"> <a href="#what-you-have-learned">What you have learned</a> </li><li data-depth="2"> <a href="#what-to-do-next">What to do next</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>