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

@@ -0,0 +1,40 @@
+<!DOCTYPE html><html lang="en"> <head><meta charset="UTF-8"><meta name="viewport" content="width=device-width, initial-scale=1.0"><title>SandboxFirestore surface · 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/"> 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/" aria-current="true"> 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/"> 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/" aria-current="true"> 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-admin-firestore/">pyric-admin / 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">SandboxFirestore surface</span> </li> </ol> </nav>  <article class="prose">  <h1 id="sandboxfirestore-surface"><code>SandboxFirestore</code> surface</h1>
+<p>The handle returned from <code>getFirestore(ctx)</code>. Extends <code>Firestore</code> from <code>firebase-admin/firestore</code> (via the simulator’s compat impl) and adds three sandbox-only methods.</p>
+<h2 id="production-shaped-methods">Production-shaped methods</h2>
+<p>These mirror <code>firebase-admin/firestore</code> exactly. The production docs and types apply.</p>
+<h3 id="collectionpath-string-collectionreference"><code>collection(path: string): CollectionReference</code></h3>
+<p>Get a <code>CollectionReference</code> for the given path. Chain <code>.doc</code>, <code>.where</code>, <code>.orderBy</code>, <code>.limit</code>, <code>.get</code>, <code>.add</code>, etc.</p>
+<h3 id="docpath-string-documentreference"><code>doc(path: string): DocumentReference</code></h3>
+<p>Get a <code>DocumentReference</code> for the given path. Chain <code>.get</code>, <code>.set</code>, <code>.update</code>, <code>.delete</code>, <code>.collection</code> (subcollection).</p>
+<h3 id="collectiongroupcollectionid-string-query"><code>collectionGroup(collectionId: string): Query</code></h3>
+<p>Build a collection-group query: matches every collection named <code>collectionId</code> anywhere in the database.</p>
+<h3 id="batch-writebatch"><code>batch(): WriteBatch</code></h3>
+<p>Construct a write batch. Chain <code>.set</code>, <code>.update</code>, <code>.delete</code>, <code>.commit</code>.</p>
+<h3 id="runtransactionrfn-opts-promiser"><code>runTransaction&#x3C;R>(fn, opts?): Promise&#x3C;R></code></h3>
+<p>Run a transaction. The callback receives a <code>Transaction</code> object with <code>.get</code> (ref or query), <code>.set</code>, <code>.update</code>, <code>.delete</code>. Reads inside the callback are tracked for read-after-write detection.</p>
+<p><code>opts</code> is accepted for shape parity with <code>firebase-admin/firestore</code>’s <code>OperationOptions</code>. The sandbox ignores per-op options that don’t apply.</p>
+<h2 id="sandbox-only-methods">Sandbox-only methods</h2>
+<p>These have no production analog and use sandbox-specific verbs so they can’t be confused with deployment operations.</p>
+<h3 id="setrulesrules-string-lintresult"><code>setRules(rules: string): LintResult</code></h3>
+<p>Replace the active ruleset. Returns the lint result from <code>pyric/rules</code>: surface the warnings if any. If the source has parse-level errors, the rules are not swapped (consistent with <code>LocalEnvironment.deployRules</code>).</p>
+<p>After a successful <code>setRules</code>, every active snapshot listener is re-evaluated under the new rules. See <a href="../pyric-sandbox-explanation-listener-re-evaluation/">Listener re-evaluation on <code>deployRules</code></a> in <code>pyric/sandbox</code>.</p>
+<h3 id="seedoptions-lintresult"><code>seed(options?): LintResult</code></h3>
+<p>Replace stored documents with a new seed map. Active rules are preserved.</p>
+<pre class="astro-code one-dark-pro" style="background-color:#282c34;color:#abb2bf; overflow-x: auto;" tabindex="0" data-language="ts"><code><span class="line"><span style="color:#E5C07B">db</span><span style="color:#ABB2BF">.</span><span style="color:#61AFEF">seed</span><span style="color:#ABB2BF">({</span></span>
+<span class="line"><span style="color:#E06C75">  documents</span><span style="color:#ABB2BF">: {</span></span>
+<span class="line"><span style="color:#98C379">    'notes/n1'</span><span style="color:#ABB2BF">: { </span><span style="color:#E06C75">ownerId</span><span style="color:#ABB2BF">: </span><span style="color:#98C379">'alice'</span><span style="color:#ABB2BF">, </span><span style="color:#E06C75">title</span><span style="color:#ABB2BF">: </span><span style="color:#98C379">'first'</span><span style="color:#ABB2BF"> },</span></span>
+<span class="line"><span style="color:#98C379">    'notes/n2'</span><span style="color:#ABB2BF">: { </span><span style="color:#E06C75">ownerId</span><span style="color:#ABB2BF">: </span><span style="color:#98C379">'bob'</span><span style="color:#ABB2BF">,   </span><span style="color:#E06C75">title</span><span style="color:#ABB2BF">: </span><span style="color:#98C379">'second'</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>Pass an empty <code>documents</code> map (or omit it) to clear data without touching rules.</p>
+<p>Returns the lint of the preserved ruleset for consistency with <code>setRules</code>: the same <code>LintResult</code> shape across both methods means the caller can check warnings the same way after either call.</p>
+<h3 id="snapshot-recordstring-documentdata"><code>snapshot(): Record&#x3C;string, DocumentData></code></h3>
+<p>Capture every stored document as a <code>{ [path]: data }</code> map. Reads from the live state and is independent of rules (same idea as <code>sandbox.admin.getDocument(...)</code> but for the whole database in one call).</p>
+<pre class="astro-code one-dark-pro" style="background-color:#282c34;color:#abb2bf; overflow-x: auto;" tabindex="0" data-language="ts"><code><span class="line"><span style="color:#C678DD">const</span><span style="color:#E5C07B"> state</span><span style="color:#56B6C2"> =</span><span style="color:#E5C07B"> db</span><span style="color:#ABB2BF">.</span><span style="color:#61AFEF">snapshot</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:#E06C75">state</span><span style="color:#ABB2BF">[</span><span style="color:#98C379">'notes/n1'</span><span style="color:#ABB2BF">]);  </span><span style="color:#7F848E;font-style:italic">// { ownerId: 'alice', title: 'first' }</span></span></code></pre>
+<p>The returned object is a structural clone. Mutating it does not affect the sandbox.</p>
+<h2 id="what-this-handle-ignores">What this handle ignores</h2>
+<p>The handle accepts but does not act on the production <code>OperationOptions.auth</code> field. Auth is captured at handle construction from <code>ctx.auth</code>: it cannot be overridden per call. To act as a different user, derive a new context via <code>sandbox.withAuth(...)</code> and call <code>getFirestore</code> again.</p>
+<p>This is per the <a href="../pyric-sandbox-explanation-identity-is-a-context/">identity-is-a-context</a> design: identity lives on the context, not on individual operations.</p>
+<h2 id="per-call-delegate-construction">Per-call delegate construction</h2>
+<p>Every production-shaped method constructs a fresh <code>Firestore</code> delegate per call. This is intentional. See <a href="../pyric-admin-firestore-explanation-per-call-delegate/">Per-call delegate construction</a>. The cost is one class instance per operation, which is dominated by the cost of the operation itself.</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="#production-shaped-methods">Production-shaped methods</a> </li><li data-depth="3"> <a href="#collectionpath-string-collectionreference">collection(path: string): CollectionReference</a> </li><li data-depth="3"> <a href="#docpath-string-documentreference">doc(path: string): DocumentReference</a> </li><li data-depth="3"> <a href="#collectiongroupcollectionid-string-query">collectionGroup(collectionId: string): Query</a> </li><li data-depth="3"> <a href="#batch-writebatch">batch(): WriteBatch</a> </li><li data-depth="3"> <a href="#runtransactionrfn-opts-promiser">runTransaction&lt;R&gt;(fn, opts?): Promise&lt;R&gt;</a> </li><li data-depth="2"> <a href="#sandbox-only-methods">Sandbox-only methods</a> </li><li data-depth="3"> <a href="#setrulesrules-string-lintresult">setRules(rules: string): LintResult</a> </li><li data-depth="3"> <a href="#seedoptions-lintresult">seed(options?): LintResult</a> </li><li data-depth="3"> <a href="#snapshot-recordstring-documentdata">snapshot(): Record&lt;string, DocumentData&gt;</a> </li><li data-depth="2"> <a href="#what-this-handle-ignores">What this handle ignores</a> </li><li data-depth="2"> <a href="#per-call-delegate-construction">Per-call delegate construction</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-admin-firestore-reference-sandbox-firestore.md ADDED Viewed

@@ -0,0 +1,77 @@
+# `SandboxFirestore` surface
+The handle returned from `getFirestore(ctx)`. Extends `Firestore` from `firebase-admin/firestore` (via the simulator's compat impl) and adds three sandbox-only methods.
+## Production-shaped methods
+These mirror `firebase-admin/firestore` exactly. The production docs and types apply.
+### `collection(path: string): CollectionReference`
+Get a `CollectionReference` for the given path. Chain `.doc`, `.where`, `.orderBy`, `.limit`, `.get`, `.add`, etc.
+### `doc(path: string): DocumentReference`
+Get a `DocumentReference` for the given path. Chain `.get`, `.set`, `.update`, `.delete`, `.collection` (subcollection).
+### `collectionGroup(collectionId: string): Query`
+Build a collection-group query: matches every collection named `collectionId` anywhere in the database.
+### `batch(): WriteBatch`
+Construct a write batch. Chain `.set`, `.update`, `.delete`, `.commit`.
+### `runTransaction<R>(fn, opts?): Promise<R>`
+Run a transaction. The callback receives a `Transaction` object with `.get` (ref or query), `.set`, `.update`, `.delete`. Reads inside the callback are tracked for read-after-write detection.
+`opts` is accepted for shape parity with `firebase-admin/firestore`'s `OperationOptions`. The sandbox ignores per-op options that don't apply.
+## Sandbox-only methods
+These have no production analog and use sandbox-specific verbs so they can't be confused with deployment operations.
+### `setRules(rules: string): LintResult`
+Replace the active ruleset. Returns the lint result from `pyric/rules`: surface the warnings if any. If the source has parse-level errors, the rules are not swapped (consistent with `LocalEnvironment.deployRules`).
+After a successful `setRules`, every active snapshot listener is re-evaluated under the new rules. See [Listener re-evaluation on `deployRules`](../pyric-sandbox-explanation-listener-re-evaluation/) in `pyric/sandbox`.
+### `seed(options?): LintResult`
+Replace stored documents with a new seed map. Active rules are preserved.
+```ts
+db.seed({
+  documents: {
+    'notes/n1': { ownerId: 'alice', title: 'first' },
+    'notes/n2': { ownerId: 'bob',   title: 'second' },
+  },
+});
+```
+Pass an empty `documents` map (or omit it) to clear data without touching rules.
+Returns the lint of the preserved ruleset for consistency with `setRules`: the same `LintResult` shape across both methods means the caller can check warnings the same way after either call.
+### `snapshot(): Record<string, DocumentData>`
+Capture every stored document as a `{ [path]: data }` map. Reads from the live state and is independent of rules (same idea as `sandbox.admin.getDocument(...)` but for the whole database in one call).
+```ts
+const state = db.snapshot();
+console.log(state['notes/n1']);  // { ownerId: 'alice', title: 'first' }
+```
+The returned object is a structural clone. Mutating it does not affect the sandbox.
+## What this handle ignores
+The handle accepts but does not act on the production `OperationOptions.auth` field. Auth is captured at handle construction from `ctx.auth`: it cannot be overridden per call. To act as a different user, derive a new context via `sandbox.withAuth(...)` and call `getFirestore` again.
+This is per the [identity-is-a-context](../pyric-sandbox-explanation-identity-is-a-context/) design: identity lives on the context, not on individual operations.
+## Per-call delegate construction
+Every production-shaped method constructs a fresh `Firestore` delegate per call. This is intentional. See [Per-call delegate construction](../pyric-admin-firestore-explanation-per-call-delegate/). The cost is one class instance per operation, which is dominated by the cost of the operation itself.

package/dist/serve/docs-ui/docs/pyric-admin-firestore-tutorials-01-first-admin-session/index.html ADDED Viewed

@@ -0,0 +1,118 @@
+<!DOCTYPE html><html lang="en"> <head><meta charset="UTF-8"><meta name="viewport" content="width=device-width, initial-scale=1.0"><title>Your first admin-shaped Firestore session · 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/"> 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/" aria-current="true"> 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/"> 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/" aria-current="true"> 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-admin-firestore/">pyric-admin / 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">First admin session</span> </li> </ol> </nav>  <article class="prose">  <h1 id="your-first-admin-shaped-firestore-session">Your first admin-shaped Firestore session</h1>
+<p>In this tutorial you will use <code>pyric-admin</code> to write, read, batch, transact, and watch documents in a sandbox. By the end you will have seen every piece of the surface in action.</p>
+<h2 id="before-you-start">Before you start</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"> admin-tutorial</span><span style="color:#ABB2BF"> &#x26;&#x26; </span><span style="color:#56B6C2">cd</span><span style="color:#98C379"> admin-tutorial</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/sandbox</span><span style="color:#98C379"> pyric-admin</span></span></code></pre>
+<h2 id="step-1-boot-the-sandbox-and-deploy-rules">Step 1: Boot the sandbox and deploy rules</h2>
+<p>Create <code>session.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 style="color:#E06C75">getFirestore</span><span style="color:#ABB2BF">, </span><span style="color:#E06C75">FieldValue</span><span style="color:#ABB2BF">, </span><span style="color:#E06C75">onSnapshot</span><span style="color:#ABB2BF"> } </span><span style="color:#C678DD">from</span><span style="color:#98C379"> 'pyric-admin'</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>
+<span class="line"><span style="color:#C678DD">const</span><span style="color:#E5C07B"> adminCtx</span><span style="color:#56B6C2"> =</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">'admin'</span><span style="color:#ABB2BF">, </span><span style="color:#E06C75">token</span><span style="color:#ABB2BF">: { </span><span style="color:#E06C75">admin</span><span style="color:#ABB2BF">: </span><span style="color:#D19A66">true</span><span style="color:#ABB2BF"> } });</span></span>
+<span class="line"><span style="color:#C678DD">const</span><span style="color:#E5C07B"> adminDb</span><span style="color:#56B6C2"> =</span><span style="color:#61AFEF"> getFirestore</span><span style="color:#ABB2BF">(</span><span style="color:#E06C75">adminCtx</span><span style="color:#ABB2BF">);</span></span>
+<span class="line"></span>
+<span class="line"><span style="color:#C678DD">const</span><span style="color:#E5C07B"> lint</span><span style="color:#56B6C2"> =</span><span style="color:#E5C07B"> adminDb</span><span style="color:#ABB2BF">.</span><span style="color:#61AFEF">setRules</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 create: if request.auth.uid == request.resource.data.ownerId;</span></span>
+<span class="line"><span style="color:#98C379">      allow update, delete:</span></span>
+<span class="line"><span style="color:#98C379">        if request.auth.uid == resource.data.ownerId;</span></span>
+<span class="line"><span style="color:#98C379">    }</span></span>
+<span class="line"><span style="color:#98C379">    match /counters/{id} {</span></span>
+<span class="line"><span style="color:#98C379">      allow read, write: if request.auth.token.admin == true;</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>Run with <code>bun run session.ts</code>. You should see <code>Rules deployed.</code> and no warnings.</p>
+<h2 id="step-2-write-as-one-user">Step 2: Write as one user</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"> aliceCtx</span><span style="color:#56B6C2"> =</span><span style="color:#E5C07B"> sandbox</span><span style="color:#ABB2BF">.</span><span style="color:#61AFEF">withAuth</span><span style="color:#ABB2BF">({ </span><span style="color:#E06C75">uid</span><span style="color:#ABB2BF">: </span><span style="color:#98C379">'alice'</span><span style="color:#ABB2BF"> });</span></span>
+<span class="line"><span style="color:#C678DD">const</span><span style="color:#E5C07B"> aliceDb</span><span style="color:#56B6C2"> =</span><span style="color:#61AFEF"> getFirestore</span><span style="color:#ABB2BF">(</span><span style="color:#E06C75">aliceCtx</span><span style="color:#ABB2BF">);</span></span>
+<span class="line"></span>
+<span class="line"><span style="color:#C678DD">await</span><span style="color:#E5C07B"> aliceDb</span><span style="color:#ABB2BF">.</span><span style="color:#61AFEF">collection</span><span style="color:#ABB2BF">(</span><span style="color:#98C379">'notes'</span><span style="color:#ABB2BF">).</span><span style="color:#61AFEF">doc</span><span style="color:#ABB2BF">(</span><span style="color:#98C379">'n1'</span><span style="color:#ABB2BF">).</span><span style="color:#61AFEF">set</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:#E5C07B"> aliceDb</span><span style="color:#ABB2BF">.</span><span style="color:#61AFEF">collection</span><span style="color:#ABB2BF">(</span><span style="color:#98C379">'notes'</span><span style="color:#ABB2BF">).</span><span style="color:#61AFEF">doc</span><span style="color:#ABB2BF">(</span><span style="color:#98C379">'n1'</span><span style="color:#ABB2BF">).</span><span style="color:#61AFEF">get</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">'Alice reads 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:</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>Alice reads back: { ownerId: "alice", title: "My first note" }</span></span></code></pre>
+<h2 id="step-3-try-a-denied-write">Step 3: 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"> bobDb</span><span style="color:#56B6C2"> =</span><span style="color:#61AFEF"> getFirestore</span><span style="color:#ABB2BF">(</span><span style="color:#E5C07B">sandbox</span><span style="color:#ABB2BF">.</span><span style="color:#61AFEF">withAuth</span><span style="color:#ABB2BF">({ </span><span style="color:#E06C75">uid</span><span style="color:#ABB2BF">: </span><span style="color:#98C379">'bob'</span><span style="color:#ABB2BF"> }));</span></span>
+<span class="line"></span>
+<span class="line"><span style="color:#C678DD">try</span><span style="color:#ABB2BF"> {</span></span>
+<span class="line"><span style="color:#C678DD">  await</span><span style="color:#E5C07B"> bobDb</span><span style="color:#ABB2BF">.</span><span style="color:#61AFEF">collection</span><span style="color:#ABB2BF">(</span><span style="color:#98C379">'notes'</span><span style="color:#ABB2BF">).</span><span style="color:#61AFEF">doc</span><span style="color:#ABB2BF">(</span><span style="color:#98C379">'n1'</span><span style="color:#ABB2BF">).</span><span style="color:#61AFEF">update</span><span style="color:#ABB2BF">({ </span><span style="color:#E06C75">title</span><span style="color:#ABB2BF">: </span><span style="color:#98C379">'Bob hijacks'</span><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 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>Bob is not Alice; the update rule requires <code>request.auth.uid == resource.data.ownerId</code>. The denial fires with full context.</p>
+<h2 id="step-4-run-a-transaction">Step 4: Run a transaction</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"> result</span><span style="color:#56B6C2"> =</span><span style="color:#C678DD"> await</span><span style="color:#E5C07B"> adminDb</span><span style="color:#ABB2BF">.</span><span style="color:#61AFEF">runTransaction</span><span style="color:#ABB2BF">(</span><span style="color:#C678DD">async</span><span style="color:#ABB2BF"> (</span><span style="color:#E06C75;font-style:italic">tx</span><span style="color:#ABB2BF">) </span><span style="color:#C678DD">=></span><span style="color:#ABB2BF"> {</span></span>
+<span class="line"><span style="color:#C678DD">  const</span><span style="color:#E5C07B"> counterRef</span><span style="color:#56B6C2"> =</span><span style="color:#E5C07B"> adminDb</span><span style="color:#ABB2BF">.</span><span style="color:#61AFEF">doc</span><span style="color:#ABB2BF">(</span><span style="color:#98C379">'counters/main'</span><span style="color:#ABB2BF">);</span></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:#E5C07B"> tx</span><span style="color:#ABB2BF">.</span><span style="color:#61AFEF">get</span><span style="color:#ABB2BF">(</span><span style="color:#E06C75">counterRef</span><span style="color:#ABB2BF">);</span></span>
+<span class="line"><span style="color:#C678DD">  const</span><span style="color:#E5C07B"> current</span><span style="color:#56B6C2"> =</span><span style="color:#E5C07B"> snap</span><span style="color:#ABB2BF">.</span><span style="color:#E06C75">exists</span><span style="color:#C678DD"> ?</span><span style="color:#E5C07B"> snap</span><span style="color:#ABB2BF">.</span><span style="color:#61AFEF">data</span><span style="color:#ABB2BF">().</span><span style="color:#E06C75">count</span><span style="color:#C678DD"> :</span><span style="color:#D19A66"> 0</span><span style="color:#ABB2BF">;</span></span>
+<span class="line"><span style="color:#E5C07B">  tx</span><span style="color:#ABB2BF">.</span><span style="color:#61AFEF">set</span><span style="color:#ABB2BF">(</span><span style="color:#E06C75">counterRef</span><span style="color:#ABB2BF">, { </span><span style="color:#E06C75">count</span><span style="color:#ABB2BF">: </span><span style="color:#E06C75">current</span><span style="color:#56B6C2"> +</span><span style="color:#D19A66"> 1</span><span style="color:#ABB2BF"> });</span></span>
+<span class="line"><span style="color:#C678DD">  return</span><span style="color:#E06C75"> current</span><span style="color:#56B6C2"> +</span><span style="color:#D19A66"> 1</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:#E5C07B">console</span><span style="color:#ABB2BF">.</span><span style="color:#61AFEF">log</span><span style="color:#ABB2BF">(</span><span style="color:#98C379">'Counter is now:'</span><span style="color:#ABB2BF">, </span><span style="color:#E06C75">result</span><span style="color:#ABB2BF">);</span></span></code></pre>
+<p>Output: <code>Counter is now: 1</code>. Run the file again and it becomes 2 (the sandbox isn’t reset between runs of the script).</p>
+<h2 id="step-5-write-a-batch">Step 5: Write a batch</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"> batch</span><span style="color:#56B6C2"> =</span><span style="color:#E5C07B"> adminDb</span><span style="color:#ABB2BF">.</span><span style="color:#61AFEF">batch</span><span style="color:#ABB2BF">();</span></span>
+<span class="line"><span style="color:#E5C07B">batch</span><span style="color:#ABB2BF">.</span><span style="color:#61AFEF">set</span><span style="color:#ABB2BF">(</span><span style="color:#E5C07B">adminDb</span><span style="color:#ABB2BF">.</span><span style="color:#61AFEF">doc</span><span style="color:#ABB2BF">(</span><span style="color:#98C379">'notes/n2'</span><span style="color:#ABB2BF">), { </span><span style="color:#E06C75">ownerId</span><span style="color:#ABB2BF">: </span><span style="color:#98C379">'alice'</span><span style="color:#ABB2BF">, </span><span style="color:#E06C75">title</span><span style="color:#ABB2BF">: </span><span style="color:#98C379">'batched A'</span><span style="color:#ABB2BF"> });</span></span>
+<span class="line"><span style="color:#E5C07B">batch</span><span style="color:#ABB2BF">.</span><span style="color:#61AFEF">set</span><span style="color:#ABB2BF">(</span><span style="color:#E5C07B">adminDb</span><span style="color:#ABB2BF">.</span><span style="color:#61AFEF">doc</span><span style="color:#ABB2BF">(</span><span style="color:#98C379">'notes/n3'</span><span style="color:#ABB2BF">), { </span><span style="color:#E06C75">ownerId</span><span style="color:#ABB2BF">: </span><span style="color:#98C379">'alice'</span><span style="color:#ABB2BF">, </span><span style="color:#E06C75">title</span><span style="color:#ABB2BF">: </span><span style="color:#98C379">'batched B'</span><span style="color:#ABB2BF"> });</span></span>
+<span class="line"><span style="color:#E5C07B">batch</span><span style="color:#ABB2BF">.</span><span style="color:#61AFEF">update</span><span style="color:#ABB2BF">(</span><span style="color:#E5C07B">adminDb</span><span style="color:#ABB2BF">.</span><span style="color:#61AFEF">doc</span><span style="color:#ABB2BF">(</span><span style="color:#98C379">'counters/main'</span><span style="color:#ABB2BF">), { </span><span style="color:#E06C75">count</span><span style="color:#ABB2BF">: </span><span style="color:#E5C07B">FieldValue</span><span style="color:#ABB2BF">.</span><span style="color:#61AFEF">increment</span><span style="color:#ABB2BF">(</span><span style="color:#D19A66">2</span><span style="color:#ABB2BF">) });</span></span>
+<span class="line"><span style="color:#C678DD">await</span><span style="color:#E5C07B"> batch</span><span style="color:#ABB2BF">.</span><span style="color:#61AFEF">commit</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">'After batch:'</span><span style="color:#ABB2BF">, </span><span style="color:#E5C07B">adminDb</span><span style="color:#ABB2BF">.</span><span style="color:#61AFEF">snapshot</span><span style="color:#ABB2BF">());</span></span></code></pre>
+<p>The three operations either all succeed or all fail. <code>FieldValue.increment(2)</code> resolves against the pre-batch state.</p>
+<h2 id="step-6-watch-with-onsnapshot">Step 6: 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">any</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 style="color:#E5C07B">aliceDb</span><span style="color:#ABB2BF">.</span><span style="color:#61AFEF">collection</span><span style="color:#ABB2BF">(</span><span style="color:#98C379">'notes'</span><span style="color:#ABB2BF">), (</span><span style="color:#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>
+<span class="line"><span style="color:#C678DD">await</span><span style="color:#E5C07B"> aliceDb</span><span style="color:#ABB2BF">.</span><span style="color:#61AFEF">collection</span><span style="color:#ABB2BF">(</span><span style="color:#98C379">'notes'</span><span style="color:#ABB2BF">).</span><span style="color:#61AFEF">doc</span><span style="color:#ABB2BF">(</span><span style="color:#98C379">'n4'</span><span style="color:#ABB2BF">).</span><span style="color:#61AFEF">set</span><span style="color:#ABB2BF">({ </span><span style="color:#E06C75">ownerId</span><span style="color:#ABB2BF">: </span><span style="color:#98C379">'alice'</span><span style="color:#ABB2BF">, </span><span style="color:#E06C75">title</span><span style="color:#ABB2BF">: </span><span style="color:#98C379">'live'</span><span style="color:#ABB2BF"> });</span></span>
+<span class="line"><span style="color:#C678DD">await</span><span style="color:#E5C07B"> aliceDb</span><span style="color:#ABB2BF">.</span><span style="color:#61AFEF">collection</span><span style="color:#ABB2BF">(</span><span style="color:#98C379">'notes'</span><span style="color:#ABB2BF">).</span><span style="color:#61AFEF">doc</span><span style="color:#ABB2BF">(</span><span style="color:#98C379">'n1'</span><span style="color:#ABB2BF">).</span><span style="color:#61AFEF">update</span><span style="color:#ABB2BF">({ </span><span style="color:#E06C75">title</span><span style="color:#ABB2BF">: </span><span style="color:#98C379">'updated'</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">'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:</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>  'modified n1',                        // update</span></span>
+<span class="line"><span>]</span></span></code></pre>
+<p>The listener fires once for the initial state, then again per write. Don’t forget to <code>unsubscribe</code>: without it, a script holding the listener forever keeps the sandbox alive in memory.</p>
+<h2 id="step-7-snapshot-the-world">Step 7: Snapshot the world</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">'Full state:'</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:#E5C07B">adminDb</span><span style="color:#ABB2BF">.</span><span style="color:#61AFEF">snapshot</span><span style="color:#ABB2BF">());</span></span></code></pre>
+<p>Every document, every path. Use this for forensic dumps when a test fails.</p>
+<h2 id="what-you-have-learned">What you have learned</h2>
+<ul>
+<li><code>getFirestore(ctx)</code> is the entry point. Every operation runs under <code>ctx.auth</code>.</li>
+<li><code>setRules</code>, <code>seed</code>, <code>snapshot</code> are the sandbox-only methods on the handle.</li>
+<li>The chainable production-shaped surface (<code>collection</code>, <code>doc</code>, <code>batch</code>, <code>runTransaction</code>) works as in <code>firebase-admin/firestore</code>.</li>
+<li><code>onSnapshot</code> mirrors the Web SDK’s function form (preferred over <code>ref.onSnapshot(...)</code> for portability across <code>pyric-admin</code> and <code>pyric/firestore</code>).</li>
+<li><code>SandboxError</code> carries <code>denialContext</code> for <code>permission-denied</code>.</li>
+</ul>
+<h2 id="what-to-do-next">What to do next</h2>
+<ul>
+<li>Pick between this package and <code>pyric/firestore</code>: see <a href="../pyric-sandbox-how-to-pick-an-adapter/">Pick between <code>pyric-admin</code> and <code>pyric/firestore</code></a>.</li>
+<li>Wire denials into a UI: see <a href="../pyric-admin-firestore-how-to-translate-denials/">Translate denials with <code>denialContext</code></a>.</li>
+<li>Use the sandbox in a real test suite: see Use the sandbox in a test harness.</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="#before-you-start">Before you start</a> </li><li data-depth="2"> <a href="#step-1-boot-the-sandbox-and-deploy-rules">Step 1: Boot the sandbox and deploy rules</a> </li><li data-depth="2"> <a href="#step-2-write-as-one-user">Step 2: Write as one user</a> </li><li data-depth="2"> <a href="#step-3-try-a-denied-write">Step 3: Try a denied write</a> </li><li data-depth="2"> <a href="#step-4-run-a-transaction">Step 4: Run a transaction</a> </li><li data-depth="2"> <a href="#step-5-write-a-batch">Step 5: Write a batch</a> </li><li data-depth="2"> <a href="#step-6-watch-with-onsnapshot">Step 6: Watch with onSnapshot</a> </li><li data-depth="2"> <a href="#step-7-snapshot-the-world">Step 7: Snapshot the world</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>