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-query-constraints/index.html ADDED Viewed

@@ -0,0 +1,80 @@
+<!DOCTYPE html><html lang="en"> <head><meta charset="UTF-8"><meta name="viewport" content="width=device-width, initial-scale=1.0"><title>Query constraints · 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">Query constraints</span> </li> </ol> </nav>  <article class="prose">  <h1 id="query-constraints">Query constraints</h1>
+<p><code>pyric/firestore</code> mirrors <code>firebase/firestore</code>’s constraint factories. Compose them via <code>query(...)</code>.</p>
+<h2 id="filters">Filters</h2>
+<h3 id="wherefield-op-value"><code>where(field, op, value)</code></h3>
+<pre class="astro-code one-dark-pro" style="background-color:#282c34;color:#abb2bf; overflow-x: auto;" tabindex="0" data-language="ts"><code><span class="line"><span style="color:#61AFEF">where</span><span style="color:#ABB2BF">(</span><span style="color:#98C379">'ownerId'</span><span style="color:#ABB2BF">, </span><span style="color:#98C379">'=='</span><span style="color:#ABB2BF">, </span><span style="color:#98C379">'alice'</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">'priority'</span><span style="color:#ABB2BF">, </span><span style="color:#98C379">'>='</span><span style="color:#ABB2BF">, </span><span style="color:#D19A66">5</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">'tags'</span><span style="color:#ABB2BF">, </span><span style="color:#98C379">'array-contains'</span><span style="color:#ABB2BF">, </span><span style="color:#98C379">'urgent'</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">'status'</span><span style="color:#ABB2BF">, </span><span style="color:#98C379">'in'</span><span style="color:#ABB2BF">, [</span><span style="color:#98C379">'open'</span><span style="color:#ABB2BF">, </span><span style="color:#98C379">'pending'</span><span style="color:#ABB2BF">])</span></span></code></pre>
+<p><code>op</code> is one of <code>==</code>, <code>!=</code>, <code>&#x3C;</code>, <code>&#x3C;=</code>, <code>></code>, <code>>=</code>, <code>array-contains</code>, <code>array-contains-any</code>, <code>in</code>, <code>not-in</code>.</p>
+<h3 id="orfilters"><code>or(...filters)</code></h3>
+<p>Compose multiple filters with OR semantics. The combined constraint matches a doc when any inner filter matches.</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:#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">  or</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">'priority'</span><span style="color:#ABB2BF">, </span><span style="color:#98C379">'>='</span><span style="color:#ABB2BF">, </span><span style="color:#D19A66">5</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">'flagged'</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>
+<span class="line"><span style="color:#ABB2BF">  ),</span></span>
+<span class="line"><span style="color:#ABB2BF">);</span></span></code></pre>
+<h3 id="andfilters"><code>and(...filters)</code></h3>
+<p>Compose multiple filters with AND semantics. Top-level constraints already AND together, so <code>and</code> is only needed inside an <code>or</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:#61AFEF">or</span><span style="color:#ABB2BF">(</span></span>
+<span class="line"><span style="color:#61AFEF">  and</span><span style="color:#ABB2BF">(</span><span style="color:#61AFEF">where</span><span style="color:#ABB2BF">(</span><span style="color:#98C379">'priority'</span><span style="color:#ABB2BF">, </span><span style="color:#98C379">'>='</span><span style="color:#ABB2BF">, </span><span style="color:#D19A66">5</span><span style="color:#ABB2BF">), </span><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">false</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">'flagged'</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>
+<span class="line"><span style="color:#ABB2BF">)</span></span></code></pre>
+<h2 id="ordering">Ordering</h2>
+<h3 id="orderbyfield-direction"><code>orderBy(field, direction?)</code></h3>
+<pre class="astro-code one-dark-pro" style="background-color:#282c34;color:#abb2bf; overflow-x: auto;" tabindex="0" data-language="ts"><code><span class="line"><span style="color:#61AFEF">orderBy</span><span style="color:#ABB2BF">(</span><span style="color:#98C379">'createdAt'</span><span style="color:#ABB2BF">)              </span><span style="color:#7F848E;font-style:italic">// default 'asc'</span></span>
+<span class="line"><span style="color:#61AFEF">orderBy</span><span style="color:#ABB2BF">(</span><span style="color:#98C379">'createdAt'</span><span style="color:#ABB2BF">, </span><span style="color:#98C379">'desc'</span><span style="color:#ABB2BF">)</span></span>
+<span class="line"><span style="color:#61AFEF">orderBy</span><span style="color:#ABB2BF">(</span><span style="color:#98C379">'priority'</span><span style="color:#ABB2BF">, </span><span style="color:#98C379">'desc'</span><span style="color:#ABB2BF">)</span></span></code></pre>
+<p><code>direction</code> is <code>'asc'</code> or <code>'desc'</code>. Multiple <code>orderBy</code> calls in one query stack; later constraints are tiebreakers.</p>
+<h2 id="limits">Limits</h2>
+<h3 id="limitn"><code>limit(n)</code></h3>
+<p>Cap the result set to <code>n</code> documents.</p>
+<h3 id="limittolastn"><code>limitToLast(n)</code></h3>
+<p>Cap to the last <code>n</code> documents in the query’s ordering. Requires at least one <code>orderBy</code>. Reverses internally to fetch the tail.</p>
+<h2 id="cursors">Cursors</h2>
+<p>Four constraints for pagination. Each accepts either a <code>DocumentSnapshot</code> (start at / after this doc) or positional field values matching the <code>orderBy</code> constraints.</p>
+<h3 id="startatsnapshot--startatvalues"><code>startAt(snapshot)</code> / <code>startAt(...values)</code></h3>
+<p>Include the matching doc and everything after.</p>
+<h3 id="startaftersnapshot--startaftervalues"><code>startAfter(snapshot)</code> / <code>startAfter(...values)</code></h3>
+<p>Exclude the matching doc; start at the next one.</p>
+<h3 id="endatsnapshot--endatvalues"><code>endAt(snapshot)</code> / <code>endAt(...values)</code></h3>
+<p>Include everything up to and including the matching doc.</p>
+<h3 id="endbeforesnapshot--endbeforevalues"><code>endBefore(snapshot)</code> / <code>endBefore(...values)</code></h3>
+<p>Exclude the matching doc; end just before it.</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"> firstPage</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:#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">  orderBy</span><span style="color:#ABB2BF">(</span><span style="color:#98C379">'createdAt'</span><span style="color:#ABB2BF">),</span></span>
+<span class="line"><span style="color:#61AFEF">  limit</span><span style="color:#ABB2BF">(</span><span style="color:#D19A66">20</span><span style="color:#ABB2BF">),</span></span>
+<span class="line"><span style="color:#ABB2BF">));</span></span>
+<span class="line"><span style="color:#C678DD">const</span><span style="color:#E5C07B"> lastDoc</span><span style="color:#56B6C2"> =</span><span style="color:#E5C07B"> firstPage</span><span style="color:#ABB2BF">.</span><span style="color:#E06C75">docs</span><span style="color:#ABB2BF">[</span><span style="color:#E5C07B">firstPage</span><span style="color:#ABB2BF">.</span><span style="color:#E5C07B">docs</span><span style="color:#ABB2BF">.</span><span style="color:#E06C75">length</span><span style="color:#56B6C2"> -</span><span style="color:#D19A66"> 1</span><span style="color:#ABB2BF">];</span></span>
+<span class="line"></span>
+<span class="line"><span style="color:#C678DD">const</span><span style="color:#E5C07B"> secondPage</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:#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">  orderBy</span><span style="color:#ABB2BF">(</span><span style="color:#98C379">'createdAt'</span><span style="color:#ABB2BF">),</span></span>
+<span class="line"><span style="color:#61AFEF">  startAfter</span><span style="color:#ABB2BF">(</span><span style="color:#E06C75">lastDoc</span><span style="color:#ABB2BF">),</span></span>
+<span class="line"><span style="color:#61AFEF">  limit</span><span style="color:#ABB2BF">(</span><span style="color:#D19A66">20</span><span style="color:#ABB2BF">),</span></span>
+<span class="line"><span style="color:#ABB2BF">));</span></span></code></pre>
+<h2 id="sandbox-backend-caveat">Sandbox-backend caveat</h2>
+<p>Chained queries (<code>.where</code>, <code>.orderBy</code>, <code>.limit</code>) currently route to the underlying <code>LocalEnvironment</code> as whole-collection listeners when used with <code>onSnapshot</code>. The simulator fires for any change in the collection and the callback receives every document. Filter / order honouring at the listener layer is in a later slice. For <code>getDocs</code> calls, the constraints apply normally.</p>
+<p>This matters only for the sandbox mirror’s <code>onSnapshot</code>. One-shot <code>getDocs</code>
+evaluates the filters correctly. In an inactive production run, the canonical
+import remains Firebase and uses Firebase’s listener behaviour.</p>
+<h2 id="combining-everything">Combining everything</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"> 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">  or</span><span style="color:#ABB2BF">(</span></span>
+<span class="line"><span style="color:#61AFEF">    and</span><span style="color:#ABB2BF">(</span><span style="color:#61AFEF">where</span><span style="color:#ABB2BF">(</span><span style="color:#98C379">'priority'</span><span style="color:#ABB2BF">, </span><span style="color:#98C379">'>='</span><span style="color:#ABB2BF">, </span><span style="color:#D19A66">5</span><span style="color:#ABB2BF">), </span><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">false</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">'flagged'</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>
+<span class="line"><span style="color:#ABB2BF">  ),</span></span>
+<span class="line"><span style="color:#61AFEF">  orderBy</span><span style="color:#ABB2BF">(</span><span style="color:#98C379">'createdAt'</span><span style="color:#ABB2BF">, </span><span style="color:#98C379">'desc'</span><span style="color:#ABB2BF">),</span></span>
+<span class="line"><span style="color:#61AFEF">  orderBy</span><span style="color:#ABB2BF">(</span><span style="color:#98C379">'priority'</span><span style="color:#ABB2BF">, </span><span style="color:#98C379">'desc'</span><span style="color:#ABB2BF">),</span></span>
+<span class="line"><span style="color:#61AFEF">  limit</span><span style="color:#ABB2BF">(</span><span style="color:#D19A66">20</span><span style="color:#ABB2BF">),</span></span>
+<span class="line"><span style="color:#ABB2BF">);</span></span></code></pre>
+<p>The order of constraints in the argument list doesn’t change semantics. The engine sorts them into the right execution order, so keep them in a readable order for humans.</p>
+<h2 id="where-to-look-next">Where to look next</h2>
+<ul>
+<li>For the upstream-SDK reference on query semantics (composite indexes, query restrictions), see the <a href="https://firebase.google.com/docs/reference/js/firestore_" target="_blank" rel="noopener noreferrer" class="external-link">Firebase Web SDK docs</a>.</li>
+<li>For listener routing on chained queries in the sandbox, see <a href="../pyric-firestore-explanation-target-symbol-opacity/">The <code>TARGET_SYMBOL</code> opacity contract</a>.</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="#filters">Filters</a> </li><li data-depth="3"> <a href="#wherefield-op-value">where(field, op, value)</a> </li><li data-depth="3"> <a href="#orfilters">or(...filters)</a> </li><li data-depth="3"> <a href="#andfilters">and(...filters)</a> </li><li data-depth="2"> <a href="#ordering">Ordering</a> </li><li data-depth="3"> <a href="#orderbyfield-direction">orderBy(field, direction?)</a> </li><li data-depth="2"> <a href="#limits">Limits</a> </li><li data-depth="3"> <a href="#limitn">limit(n)</a> </li><li data-depth="3"> <a href="#limittolastn">limitToLast(n)</a> </li><li data-depth="2"> <a href="#cursors">Cursors</a> </li><li data-depth="3"> <a href="#startatsnapshot--startatvalues">startAt(snapshot) / startAt(...values)</a> </li><li data-depth="3"> <a href="#startaftersnapshot--startaftervalues">startAfter(snapshot) / startAfter(...values)</a> </li><li data-depth="3"> <a href="#endatsnapshot--endatvalues">endAt(snapshot) / endAt(...values)</a> </li><li data-depth="3"> <a href="#endbeforesnapshot--endbeforevalues">endBefore(snapshot) / endBefore(...values)</a> </li><li data-depth="2"> <a href="#sandbox-backend-caveat">Sandbox-backend caveat</a> </li><li data-depth="2"> <a href="#combining-everything">Combining everything</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-query-constraints.md ADDED Viewed

@@ -0,0 +1,129 @@
+# Query constraints
+`pyric/firestore` mirrors `firebase/firestore`'s constraint factories. Compose them via `query(...)`.
+## Filters
+### `where(field, op, value)`
+```ts
+where('ownerId', '==', 'alice')
+where('priority', '>=', 5)
+where('tags', 'array-contains', 'urgent')
+where('status', 'in', ['open', 'pending'])
+```
+`op` is one of `==`, `!=`, `<`, `<=`, `>`, `>=`, `array-contains`, `array-contains-any`, `in`, `not-in`.
+### `or(...filters)`
+Compose multiple filters with OR semantics. The combined constraint matches a doc when any inner filter matches.
+```ts
+query(
+  collection(db, 'notes'),
+  or(
+    where('priority', '>=', 5),
+    where('flagged', '==', true),
+  ),
+);
+```
+### `and(...filters)`
+Compose multiple filters with AND semantics. Top-level constraints already AND together, so `and` is only needed inside an `or`.
+```ts
+or(
+  and(where('priority', '>=', 5), where('archived', '==', false)),
+  where('flagged', '==', true),
+)
+```
+## Ordering
+### `orderBy(field, direction?)`
+```ts
+orderBy('createdAt')              // default 'asc'
+orderBy('createdAt', 'desc')
+orderBy('priority', 'desc')
+```
+`direction` is `'asc'` or `'desc'`. Multiple `orderBy` calls in one query stack; later constraints are tiebreakers.
+## Limits
+### `limit(n)`
+Cap the result set to `n` documents.
+### `limitToLast(n)`
+Cap to the last `n` documents in the query's ordering. Requires at least one `orderBy`. Reverses internally to fetch the tail.
+## Cursors
+Four constraints for pagination. Each accepts either a `DocumentSnapshot` (start at / after this doc) or positional field values matching the `orderBy` constraints.
+### `startAt(snapshot)` / `startAt(...values)`
+Include the matching doc and everything after.
+### `startAfter(snapshot)` / `startAfter(...values)`
+Exclude the matching doc; start at the next one.
+### `endAt(snapshot)` / `endAt(...values)`
+Include everything up to and including the matching doc.
+### `endBefore(snapshot)` / `endBefore(...values)`
+Exclude the matching doc; end just before it.
+```ts
+const firstPage = await getDocs(query(
+  collection(db, 'notes'),
+  orderBy('createdAt'),
+  limit(20),
+));
+const lastDoc = firstPage.docs[firstPage.docs.length - 1];
+const secondPage = await getDocs(query(
+  collection(db, 'notes'),
+  orderBy('createdAt'),
+  startAfter(lastDoc),
+  limit(20),
+));
+```
+## Sandbox-backend caveat
+Chained queries (`.where`, `.orderBy`, `.limit`) currently route to the underlying `LocalEnvironment` as whole-collection listeners when used with `onSnapshot`. The simulator fires for any change in the collection and the callback receives every document. Filter / order honouring at the listener layer is in a later slice. For `getDocs` calls, the constraints apply normally.
+This matters only for the sandbox mirror's `onSnapshot`. One-shot `getDocs`
+evaluates the filters correctly. In an inactive production run, the canonical
+import remains Firebase and uses Firebase's listener behaviour.
+## Combining everything
+```ts
+const q = query(
+  collection(db, 'notes'),
+  or(
+    and(where('priority', '>=', 5), where('archived', '==', false)),
+    where('flagged', '==', true),
+  ),
+  orderBy('createdAt', 'desc'),
+  orderBy('priority', 'desc'),
+  limit(20),
+);
+```
+The order of constraints in the argument list doesn't change semantics. The engine sorts them into the right execution order, so keep them in a readable order for humans.
+## Where to look next
+- For the upstream-SDK reference on query semantics (composite indexes, query restrictions), see the [Firebase Web SDK docs](https://firebase.google.com/docs/reference/js/firestore_).
+- For listener routing on chained queries in the sandbox, see [The `TARGET_SYMBOL` opacity contract](../pyric-firestore-explanation-target-symbol-opacity/).

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

@@ -0,0 +1,58 @@
+<!DOCTYPE html><html lang="en"> <head><meta charset="UTF-8"><meta name="viewport" content="width=device-width, initial-scale=1.0"><title>Sandbox-only operations · 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">Sandbox-only operations</span> </li> </ol> </nav>  <article class="prose">  <h1 id="sandbox-only-operations">Sandbox-only operations</h1>
+<p>Firestore-specific controls are top-level exports from
+<code>pyric/sandbox/firestore</code>. They operate on the owning local <code>Sandbox</code>, not on a
+Firestore data-plane handle.</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>
+<span class="line"><span style="color:#E06C75">  inspect</span><span style="color:#ABB2BF">,</span></span>
+<span class="line"><span style="color:#E06C75">  seedDocuments</span><span style="color:#ABB2BF">,</span></span>
+<span class="line"><span style="color:#E06C75">  setRules</span><span style="color:#ABB2BF">,</span></span>
+<span class="line"><span style="color:#E06C75">  snapshotDocuments</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/sandbox/firestore'</span><span style="color:#ABB2BF">;</span></span></code></pre>
+<h2 id="setrulessandbox-source-lintresult"><code>setRules(sandbox, source): LintResult</code></h2>
+<p>Replace the sandbox’s active Firestore ruleset.</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"> 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, write: if request.auth != null;</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></code></pre>
+<p>The result contains the rules linter’s findings. Source with parse-level errors
+is not installed. After a successful change, active snapshot listeners
+re-evaluate under the new rules.</p>
+<h2 id="seeddocumentssandbox-documents-lintresult"><code>seedDocuments(sandbox, documents): LintResult</code></h2>
+<p>Replace the sandbox’s Firestore documents in bulk while preserving the current
+rules. Seeding bypasses rules evaluation and does not synthesise request events
+or listener callbacks.</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:#61AFEF">seedDocuments</span><span style="color:#ABB2BF">(</span><span style="color:#E06C75">sandbox</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></code></pre>
+<h2 id="snapshotdocumentssandbox-recordstring-documentdata"><code>snapshotDocuments(sandbox): Record&#x3C;string, DocumentData></code></h2>
+<p>Return a structural clone of every Firestore document without snapshotting any
+other sandbox service.</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"> documents</span><span style="color:#56B6C2"> =</span><span style="color:#61AFEF"> snapshotDocuments</span><span style="color:#ABB2BF">(</span><span style="color:#E06C75">sandbox</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">documents</span><span style="color:#ABB2BF">[</span><span style="color:#98C379">'notes/n1'</span><span style="color:#ABB2BF">]);</span></span></code></pre>
+<p>Mutating the result does not affect the sandbox.</p>
+<h2 id="inspectsandbox-options-firestoreinspectreport"><code>inspect(sandbox, options?): FirestoreInspectReport</code></h2>
+<p>Return a JSON-serialisable report containing the current rules and lint
+findings, document counts, and recent Firestore requests and denials.</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"> report</span><span style="color:#56B6C2"> =</span><span style="color:#61AFEF"> inspect</span><span style="color:#ABB2BF">(</span><span style="color:#E06C75">sandbox</span><span style="color:#ABB2BF">, { </span><span style="color:#E06C75">recentEventLimit</span><span style="color:#ABB2BF">: </span><span style="color:#D19A66">5</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">report</span><span style="color:#ABB2BF">.</span><span style="color:#E5C07B">documents</span><span style="color:#ABB2BF">.</span><span style="color:#E06C75">totalCount</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">report</span><span style="color:#ABB2BF">.</span><span style="color:#E5C07B">events</span><span style="color:#ABB2BF">.</span><span style="color:#E06C75">recentDenials</span><span style="color:#ABB2BF">);</span></span></code></pre>
+<p><code>recentEventLimit</code> defaults to <code>10</code>.</p>
+<h2 id="ownership-contract">Ownership contract</h2>
+<p>All four functions accept a local <code>Sandbox</code>. A Firestore handle and a
+<code>RemoteSandbox</code> are rejected by the type contract. The control subpath therefore
+makes ownership explicit and keeps sandbox lifecycle operations off the
+<code>firebase/firestore</code>-compatible data-plane surface.</p>
+<p>For production rules deployment, use the deployment API rather than this
+sandbox subpath. Production data remains the responsibility of the unchanged
+Firebase SDK and Firebase services.</p>
+<h2 id="where-to-look-next">Where to look next</h2>
+<ul>
+<li>For a task-oriented example, see <a href="../pyric-firestore-how-to-use-sandbox-ops/">How to use sandbox-only operations</a>.</li>
+<li>For the lint result shape, see <a href="../pyric-rules-reference-lint-rules/"><code>pyric/rules</code> lint rules reference</a>.</li>
+<li>For production rule deployments, see the Firebase CLI docs (<code>firebase deploy --only firestore:rules</code>).</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="#setrulessandbox-source-lintresult">setRules(sandbox, source): LintResult</a> </li><li data-depth="2"> <a href="#seeddocumentssandbox-documents-lintresult">seedDocuments(sandbox, documents): LintResult</a> </li><li data-depth="2"> <a href="#snapshotdocumentssandbox-recordstring-documentdata">snapshotDocuments(sandbox): Record&lt;string, DocumentData&gt;</a> </li><li data-depth="2"> <a href="#inspectsandbox-options-firestoreinspectreport">inspect(sandbox, options?): FirestoreInspectReport</a> </li><li data-depth="2"> <a href="#ownership-contract">Ownership contract</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-sandbox-ops.md ADDED Viewed

@@ -0,0 +1,88 @@
+# Sandbox-only operations
+Firestore-specific controls are top-level exports from
+`pyric/sandbox/firestore`. They operate on the owning local `Sandbox`, not on a
+Firestore data-plane handle.
+```ts
+import {
+  inspect,
+  seedDocuments,
+  setRules,
+  snapshotDocuments,
+} from 'pyric/sandbox/firestore';
+```
+## `setRules(sandbox, source): LintResult`
+Replace the sandbox's active Firestore ruleset.
+```ts
+const lint = setRules(sandbox, `rules_version = '2';
+service cloud.firestore {
+  match /databases/{db}/documents {
+    match /notes/{id} {
+      allow read, write: if request.auth != null;
+    }
+  }
+}`);
+```
+The result contains the rules linter's findings. Source with parse-level errors
+is not installed. After a successful change, active snapshot listeners
+re-evaluate under the new rules.
+## `seedDocuments(sandbox, documents): LintResult`
+Replace the sandbox's Firestore documents in bulk while preserving the current
+rules. Seeding bypasses rules evaluation and does not synthesise request events
+or listener callbacks.
+```ts
+seedDocuments(sandbox, {
+  'notes/n1': { ownerId: 'alice', title: 'first' },
+  'notes/n2': { ownerId: 'bob', title: 'second' },
+});
+```
+## `snapshotDocuments(sandbox): Record<string, DocumentData>`
+Return a structural clone of every Firestore document without snapshotting any
+other sandbox service.
+```ts
+const documents = snapshotDocuments(sandbox);
+console.log(documents['notes/n1']);
+```
+Mutating the result does not affect the sandbox.
+## `inspect(sandbox, options?): FirestoreInspectReport`
+Return a JSON-serialisable report containing the current rules and lint
+findings, document counts, and recent Firestore requests and denials.
+```ts
+const report = inspect(sandbox, { recentEventLimit: 5 });
+console.log(report.documents.totalCount);
+console.log(report.events.recentDenials);
+```
+`recentEventLimit` defaults to `10`.
+## Ownership contract
+All four functions accept a local `Sandbox`. A Firestore handle and a
+`RemoteSandbox` are rejected by the type contract. The control subpath therefore
+makes ownership explicit and keeps sandbox lifecycle operations off the
+`firebase/firestore`-compatible data-plane surface.
+For production rules deployment, use the deployment API rather than this
+sandbox subpath. Production data remains the responsibility of the unchanged
+Firebase SDK and Firebase services.
+## Where to look next
+- For a task-oriented example, see [How to use sandbox-only operations](../pyric-firestore-how-to-use-sandbox-ops/).
+- For the lint result shape, see [`pyric/rules` lint rules reference](../pyric-rules-reference-lint-rules/).
+- For production rule deployments, see the Firebase CLI docs (`firebase deploy --only firestore:rules`).