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-rules-explanation-the-2-plus-modules-extension/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>The 2+modules extension · 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/" aria-current="true"> 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/"> pyric / firestore </a> </li><li> <a href="/__pyric/ui/docs/pyric-rules/" aria-current="true"> 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-rules/">pyric / rules</a> </li><li> <span class="docs-breadcrumbs-sep" aria-hidden="true">/</span> <span>Explanation</span> </li><li> <span class="docs-breadcrumbs-sep" aria-hidden="true">/</span> <span aria-current="page">The 2+modules extension</span> </li> </ol> </nav>  <article class="prose">  <h1 id="the-2modules-extension">The <code>2+modules</code> extension</h1>
+<p>Firestore rules don’t have imports. The DSL has functions, but every function has to be defined in the same file as the match block that calls it. This means real-world rules either repeat the same helper code across files (and drift) or live in one giant file (and become unreadable).</p>
+<p><code>2+modules</code> is a Pyric extension that adds imports to the rules language, on the way <em>into</em> the Firebase deploy. The production rules engine never sees <code>2+modules</code>. It only sees standard <code>'2'</code> rules. The resolver does the rewrite.</p>
+<h2 id="what-it-adds">What it adds</h2>
+<p>A new version string and an <code>import</code> statement:</p>
+<pre class="astro-code one-dark-pro" style="background-color:#282c34;color:#abb2bf; overflow-x: auto;" tabindex="0" data-language="rules"><code><span class="line"><span style="color:#C678DD">import</span><span style="color:#ABB2BF"> { isAuthenticated, isOwner } </span><span style="color:#C678DD">from</span><span style="color:#98C379"> 'auth'</span><span style="color:#ABB2BF">;</span></span>
+<span class="line"><span style="color:#C678DD">import</span><span style="color:#ABB2BF"> { hasOnly } </span><span style="color:#C678DD">from</span><span style="color:#98C379"> 'validation'</span><span style="color:#ABB2BF">;</span></span>
+<span class="line"></span>
+<span class="line"><span style="color:#C678DD">rules_version</span><span style="color:#ABB2BF"> = </span><span style="color:#98C379">'2+modules'</span><span style="color:#ABB2BF">;</span></span>
+<span class="line"><span style="color:#C678DD">service</span><span style="color:#ABB2BF"> cloud.firestore { … }</span></span></code></pre>
+<p>Module names are either:</p>
+<ul>
+<li><strong>Stdlib</strong> names like <code>auth</code>, <code>validation</code>, <code>lobby</code>: built-in modules bundled with the package.</li>
+<li><strong>Relative paths</strong> like <code>./moderation</code>: resolved against a <code>basePath</code> you supply.</li>
+<li><strong>In-memory entries</strong>: passed via <code>options.modules</code> as a <code>Record&#x3C;name, source></code>.</li>
+</ul>
+<p>Functions inside a module file declare visibility with <code>export</code>:</p>
+<pre class="astro-code one-dark-pro" style="background-color:#282c34;color:#abb2bf; overflow-x: auto;" tabindex="0" data-language="rules"><code><span class="line"><span style="color:#7F848E;font-style:italic">// auth.rules</span></span>
+<span class="line"><span style="color:#ABB2BF">export </span><span style="color:#C678DD">function</span><span style="color:#ABB2BF"> isAuthenticated() { </span><span style="color:#C678DD">return</span><span style="color:#E5C07B"> request</span><span style="color:#ABB2BF">.auth != </span><span style="color:#D19A66">null</span><span style="color:#ABB2BF">; }</span></span>
+<span class="line"><span style="color:#ABB2BF">export </span><span style="color:#C678DD">function</span><span style="color:#ABB2BF"> isOwner(userId) { </span><span style="color:#C678DD">return</span><span style="color:#ABB2BF"> isAuthenticated() &#x26;&#x26; </span><span style="color:#E5C07B">request</span><span style="color:#ABB2BF">.auth.uid == userId; }</span></span>
+<span class="line"></span>
+<span class="line"><span style="color:#C678DD">function</span><span style="color:#ABB2BF"> _private() { </span><span style="color:#C678DD">return</span><span style="color:#E5C07B"> request</span><span style="color:#ABB2BF">.time != </span><span style="color:#D19A66">null</span><span style="color:#ABB2BF">; }</span></span></code></pre>
+<p><code>isAuthenticated</code> and <code>isOwner</code> are importable. <code>_private</code> is not. It’s an internal helper.</p>
+<h2 id="what-it-doesnt-add">What it doesn’t add</h2>
+<p>Crucially: no new runtime behaviour. Every <code>2+modules</code> source is equivalent to a <code>'2'</code> source with all imported functions inlined and the version rewritten. The resolver does the work; the Firebase engine sees standard rules. There is no module system at runtime, no lazy loading, no separate compilation.</p>
+<p>This is deliberate. We did not want to extend the rules language in any way that production wouldn’t understand. The constraint is: anything you write in <code>2+modules</code> must reduce to something Firebase will accept after <code>resolveModules</code> runs. No new operators, no new types, no behaviour that doesn’t exist in the underlying DSL.</p>
+<h2 id="how-resolution-works">How resolution works</h2>
+<ol>
+<li><strong>Parse</strong> the source. If <code>version !== '2+modules'</code>, return <code>NOT_MODULE_SOURCE</code>.</li>
+<li><strong>Load</strong> every imported module. Stdlib names resolve from a bundled assets directory; relative paths read from <code>basePath</code>; entries in <code>options.modules</code> win first.</li>
+<li><strong>Prefix private functions</strong> with the sanitised module name (<code>auth__isAuthenticated</code>) so they don’t collide. Exported functions keep their original name.</li>
+<li><strong>Collect</strong> every requested function plus its transitive dependencies. A function <code>isOwner</code> that calls <code>isAuthenticated</code> brings the latter along automatically.</li>
+<li><strong>Inject</strong> the resulting function list at root scope inside the match block.</li>
+<li><strong>Rewrite</strong> the version to <code>'2'</code> and clear the import list.</li>
+<li><strong>Assemble</strong> the AST back to a rules source string.</li>
+</ol>
+<p>The output is a standard <code>'2'</code> rules source with the imports gone and the relevant helpers inlined. You feed that to <code>firebase deploy</code> and it deploys like any hand-written ruleset.</p>
+<h2 id="why-prefix-only-private-functions">Why prefix only private functions</h2>
+<p>Two reasons:</p>
+<ul>
+<li><strong>Collision safety</strong>: a private helper named <code>cfg</code> in <code>geometry.rules</code> should not collide with a function named <code>cfg</code> defined in the user’s own rules. Prefixing it to <code>geometry__cfg</code> keeps the user-defined name available.</li>
+<li><strong>Stable export API</strong>: exported functions are the module’s public surface. Prefixing them would force every caller to use the prefixed name (<code>auth__isAuthenticated()</code>), which defeats the point of imports.</li>
+</ul>
+<h2 id="why-no-syntax-level-module-boundaries">Why no syntax-level module boundaries</h2>
+<p>The resolver flattens everything into a single function namespace. This means an exported function from <code>auth</code> and an exported function from <code>validation</code> cannot share a name. If they do, the resolver returns <code>DUPLICATE_FUNCTION</code> and refuses to assemble.</p>
+<p>We considered keeping the prefix on exported functions and rewriting the call sites in the user’s source. We rejected it because:</p>
+<ul>
+<li>The result is opaque (<code>auth__isOwner(...)</code>); the import was supposed to make it readable.</li>
+<li>Conflicts between exported names are rare in practice. The stdlib is small and curated, and project-local modules tend to be domain-specific.</li>
+<li>The diagnostic is clear: <code>DUPLICATE_FUNCTION</code> tells you exactly which modules collide.</li>
+</ul>
+<h2 id="why-a-custom-version-string">Why a custom version string</h2>
+<p>We needed a marker that distinguishes “this source needs resolution before deploy” from “this source is ready to deploy”. The two choices were:</p>
+<ol>
+<li><strong>A new version string</strong> (<code>'2+modules'</code>): unambiguous, single-source-of-truth, fails fast on accidental deploy.</li>
+<li><strong>A comment or directive</strong> (<code>// @pyric:modules</code>): unobtrusive, but nothing fails when it’s ignored.</li>
+</ol>
+<p>We chose (1) because Firebase’s deploy path validates the version string before parsing anything else. If a <code>2+modules</code> source leaks into a real deploy by accident, Firebase rejects it with a clear error (“unknown rules version”) instead of attempting to parse the imports as rules.</p>  </article> </main> <aside class="doc-toc" aria-label="On this page"> <h2 class="doc-toc-heading">On this page</h2> <ul> <li data-depth="2"> <a href="#what-it-adds">What it adds</a> </li><li data-depth="2"> <a href="#what-it-doesnt-add">What it doesn’t add</a> </li><li data-depth="2"> <a href="#how-resolution-works">How resolution works</a> </li><li data-depth="2"> <a href="#why-prefix-only-private-functions">Why prefix only private functions</a> </li><li data-depth="2"> <a href="#why-no-syntax-level-module-boundaries">Why no syntax-level module boundaries</a> </li><li data-depth="2"> <a href="#why-a-custom-version-string">Why a custom version string</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-rules-explanation-the-2-plus-modules-extension.md ADDED Viewed

@@ -0,0 +1,79 @@
+# The `2+modules` extension
+Firestore rules don't have imports. The DSL has functions, but every function has to be defined in the same file as the match block that calls it. This means real-world rules either repeat the same helper code across files (and drift) or live in one giant file (and become unreadable).
+`2+modules` is a Pyric extension that adds imports to the rules language, on the way *into* the Firebase deploy. The production rules engine never sees `2+modules`. It only sees standard `'2'` rules. The resolver does the rewrite.
+## What it adds
+A new version string and an `import` statement:
+```rules
+import { isAuthenticated, isOwner } from 'auth';
+import { hasOnly } from 'validation';
+rules_version = '2+modules';
+service cloud.firestore { … }
+```
+Module names are either:
+- **Stdlib** names like `auth`, `validation`, `lobby`: built-in modules bundled with the package.
+- **Relative paths** like `./moderation`: resolved against a `basePath` you supply.
+- **In-memory entries**: passed via `options.modules` as a `Record<name, source>`.
+Functions inside a module file declare visibility with `export`:
+```rules
+// auth.rules
+export function isAuthenticated() { return request.auth != null; }
+export function isOwner(userId) { return isAuthenticated() && request.auth.uid == userId; }
+function _private() { return request.time != null; }
+```
+`isAuthenticated` and `isOwner` are importable. `_private` is not. It's an internal helper.
+## What it doesn't add
+Crucially: no new runtime behaviour. Every `2+modules` source is equivalent to a `'2'` source with all imported functions inlined and the version rewritten. The resolver does the work; the Firebase engine sees standard rules. There is no module system at runtime, no lazy loading, no separate compilation.
+This is deliberate. We did not want to extend the rules language in any way that production wouldn't understand. The constraint is: anything you write in `2+modules` must reduce to something Firebase will accept after `resolveModules` runs. No new operators, no new types, no behaviour that doesn't exist in the underlying DSL.
+## How resolution works
+1. **Parse** the source. If `version !== '2+modules'`, return `NOT_MODULE_SOURCE`.
+2. **Load** every imported module. Stdlib names resolve from a bundled assets directory; relative paths read from `basePath`; entries in `options.modules` win first.
+3. **Prefix private functions** with the sanitised module name (`auth__isAuthenticated`) so they don't collide. Exported functions keep their original name.
+4. **Collect** every requested function plus its transitive dependencies. A function `isOwner` that calls `isAuthenticated` brings the latter along automatically.
+5. **Inject** the resulting function list at root scope inside the match block.
+6. **Rewrite** the version to `'2'` and clear the import list.
+7. **Assemble** the AST back to a rules source string.
+The output is a standard `'2'` rules source with the imports gone and the relevant helpers inlined. You feed that to `firebase deploy` and it deploys like any hand-written ruleset.
+## Why prefix only private functions
+Two reasons:
+- **Collision safety**: a private helper named `cfg` in `geometry.rules` should not collide with a function named `cfg` defined in the user's own rules. Prefixing it to `geometry__cfg` keeps the user-defined name available.
+- **Stable export API**: exported functions are the module's public surface. Prefixing them would force every caller to use the prefixed name (`auth__isAuthenticated()`), which defeats the point of imports.
+## Why no syntax-level module boundaries
+The resolver flattens everything into a single function namespace. This means an exported function from `auth` and an exported function from `validation` cannot share a name. If they do, the resolver returns `DUPLICATE_FUNCTION` and refuses to assemble.
+We considered keeping the prefix on exported functions and rewriting the call sites in the user's source. We rejected it because:
+- The result is opaque (`auth__isOwner(...)`); the import was supposed to make it readable.
+- Conflicts between exported names are rare in practice. The stdlib is small and curated, and project-local modules tend to be domain-specific.
+- The diagnostic is clear: `DUPLICATE_FUNCTION` tells you exactly which modules collide.
+## Why a custom version string
+We needed a marker that distinguishes "this source needs resolution before deploy" from "this source is ready to deploy". The two choices were:
+1. **A new version string** (`'2+modules'`): unambiguous, single-source-of-truth, fails fast on accidental deploy.
+2. **A comment or directive** (`// @pyric:modules`): unobtrusive, but nothing fails when it's ignored.
+We chose (1) because Firebase's deploy path validates the version string before parsing anything else. If a `2+modules` source leaks into a real deploy by accident, Firebase rejects it with a clear error ("unknown rules version") instead of attempting to parse the imports as rules.

package/dist/serve/docs-ui/docs/pyric-rules-explanation-value-wrappers-design/index.html ADDED Viewed

@@ -0,0 +1,63 @@
+<!DOCTYPE html><html lang="en"> <head><meta charset="UTF-8"><meta name="viewport" content="width=device-width, initial-scale=1.0"><title>Value wrapper design · 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/" aria-current="true"> 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/"> pyric / firestore </a> </li><li> <a href="/__pyric/ui/docs/pyric-rules/" aria-current="true"> 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-rules/">pyric / rules</a> </li><li> <span class="docs-breadcrumbs-sep" aria-hidden="true">/</span> <span>Explanation</span> </li><li> <span class="docs-breadcrumbs-sep" aria-hidden="true">/</span> <span aria-current="page">Value wrapper design</span> </li> </ol> </nav>  <article class="prose">  <h1 id="value-wrapper-design">Value wrapper design</h1>
+<p>Firestore rules have a small but real type system. <code>request.time</code> is a <code>timestamp</code>. <code>request.path</code> is a <code>path</code>. <code>bytes[0:10]</code> is a <code>bytes</code> value. <code>is duration</code>, <code>is timestamp</code>, <code>is reference</code> are type tests. None of these have first-class JavaScript representations (<code>Timestamp</code> is not a primitive, <code>Path</code> is not a primitive), so the simulator has to model them somehow.</p>
+<p>We model them as classes. Each Firestore rules type is a TypeScript class extending <code>RulesValue</code>. This page explains why, and what falls out.</p>
+<h2 id="what-the-rules-engine-sees">What the rules engine sees</h2>
+<p>When a rule says <code>request.time.toMillis() > 1700000000000</code>, the production engine evaluates:</p>
+<ol>
+<li><code>request.time</code>: a value of type <code>timestamp</code>.</li>
+<li><code>.toMillis()</code>: a method dispatch on <code>timestamp</code>, returning <code>int</code>.</li>
+<li><code>> 1700000000000</code>: a binary comparison on <code>int</code>.</li>
+</ol>
+<p>For step 2 to work, the simulator’s representation of <code>request.time</code> has to remember that it’s a <code>timestamp</code> (not a bare number, not a generic object) and dispatch <code>toMillis</code> accordingly.</p>
+<p>Three options were on the table:</p>
+<ul>
+<li><strong>Plain objects with a discriminator field</strong> (<code>{ __type: 'timestamp', seconds, nanos }</code>). Lightweight and JSON-serialisable, but every method call goes through a switch and <code>instanceof</code> doesn’t work.</li>
+<li><strong>Tagged union with a service registry</strong> (<code>evaluator.dispatch('timestamp', 'toMillis', value, args)</code>). Decouples values from behaviour. Hard to extend without touching central code.</li>
+<li><strong>Class instances</strong> (<code>class Timestamp { toMillis() {...} }</code>). Methods live with their data, <code>instanceof</code> works, but classes have to be imported by every package that touches them.</li>
+</ul>
+<p>We chose classes. The class-instances approach pulled together best in practice:</p>
+<ul>
+<li>Methods are co-located with the data they operate on, so adding a new method to <code>Timestamp</code> is a one-file change.</li>
+<li><code>instanceof Timestamp</code> works, so the evaluator can branch on type at runtime without a registry.</li>
+<li><code>equals()</code> is a method that knows how to compare two instances, so deep-equality of test data and rule results is straightforward.</li>
+<li><code>toJSON()</code> is built into the protocol: the wrappers serialise to plain objects when crossing the wire to the Rules Test API.</li>
+</ul>
+<h2 id="the-rulesvalue-base-class">The <code>RulesValue</code> base class</h2>
+<p>All wrappers extend <code>RulesValue</code>. The base class is intentionally thin:</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">abstract</span><span style="color:#C678DD"> class</span><span style="color:#E5C07B"> RulesValue</span><span style="color:#ABB2BF"> {</span></span>
+<span class="line"><span style="color:#C678DD">  readonly</span><span style="color:#E06C75"> typeName</span><span style="color:#ABB2BF">: </span><span style="color:#E5C07B">string</span><span style="color:#ABB2BF">;            </span><span style="color:#7F848E;font-style:italic">// 'timestamp', 'path', 'bytes', ...</span></span>
+<span class="line"><span style="color:#61AFEF">  callMethod</span><span style="color:#ABB2BF">(</span><span style="color:#E06C75;font-style:italic">method</span><span style="color:#ABB2BF">, </span><span style="color:#E06C75;font-style:italic">args</span><span style="color:#ABB2BF">): </span><span style="color:#E5C07B">unknown</span><span style="color:#ABB2BF"> | </span><span style="color:#E5C07B">NoOp</span><span style="color:#ABB2BF">;</span></span>
+<span class="line"><span style="color:#61AFEF">  binaryOp</span><span style="color:#C678DD">?</span><span style="color:#ABB2BF">(</span><span style="color:#E06C75;font-style:italic">op</span><span style="color:#ABB2BF">, </span><span style="color:#E06C75;font-style:italic">other</span><span style="color:#ABB2BF">): </span><span style="color:#E5C07B">unknown</span><span style="color:#ABB2BF"> | </span><span style="color:#E5C07B">NoOp</span><span style="color:#ABB2BF">;</span></span>
+<span class="line"><span style="color:#61AFEF">  equals</span><span style="color:#ABB2BF">(</span><span style="color:#E06C75;font-style:italic">other</span><span style="color:#ABB2BF">): </span><span style="color:#E5C07B">boolean</span><span style="color:#ABB2BF">;</span></span>
+<span class="line"><span style="color:#61AFEF">  toJSON</span><span style="color:#ABB2BF">(): </span><span style="color:#E5C07B">unknown</span><span style="color:#ABB2BF">;</span></span>
+<span class="line"><span style="color:#61AFEF">  toString</span><span style="color:#ABB2BF">(): </span><span style="color:#E5C07B">string</span><span style="color:#ABB2BF">;</span></span>
+<span class="line"><span style="color:#ABB2BF">}</span></span></code></pre>
+<p><code>callMethod</code> and <code>binaryOp</code> exist so the evaluator can dispatch generically: <code>if (lhs instanceof RulesValue) return lhs.callMethod(method, args)</code>. The handler doesn’t need a per-type switch; the polymorphism does the work.</p>
+<p><code>typeName</code> is the lowercase identifier the rules engine uses for the <code>is</code> operator. <code>request.time is timestamp</code> works because <code>Timestamp.typeName === 'timestamp'</code>.</p>
+<h2 id="the-no_op-sentinel">The <code>NO_OP</code> sentinel</h2>
+<p>When a wrapper is asked to dispatch a method or operation it doesn’t implement, it returns <code>NO_OP</code> rather than throwing or returning <code>undefined</code>. The evaluator catches <code>NO_OP</code> and throws <code>UnsupportedError</code>, which the handler maps to <code>state: 'UNSUPPORTED'</code>.</p>
+<p>The sentinel exists so that:</p>
+<ul>
+<li>The wrapper can decline cleanly without knowing why the caller is dispatching.</li>
+<li>The evaluator can distinguish “method returned <code>undefined</code>” (a legitimate result) from “method does not exist” (an <code>UnsupportedError</code>).</li>
+<li>Adding a new method to a wrapper does not require updating the evaluator: add the case to <code>callMethod</code> and start returning a real value instead of <code>NO_OP</code>.</li>
+</ul>
+<h2 id="equality-semantics">Equality semantics</h2>
+<p><code>equals()</code> is what makes test data comparable. Two <code>Timestamp</code> instances with the same <code>seconds</code> and <code>nanos</code> are equal. Two <code>Path</code> instances with the same segments are equal. Without this, every rule that compares two timestamps would have to compare by reference, and test data, which constructs fresh wrappers every time, would never compare equal to the engine’s wrappers.</p>
+<p>Equality is a field-compare, not a reference compare. This is the same model production uses. It does mean care is needed when constructing test data: a <code>Timestamp</code> built from a different <code>seconds</code>/<code>nanos</code> split (say <code>seconds: 100, nanos: 0</code> vs <code>seconds: 99, nanos: 1_000_000_000</code>) is <strong>not</strong> equal under field-compare, even though both represent the same instant. The <code>Timestamp</code> constructor normalises through <code>seconds + Math.floor(nanos / 1e9)</code>, so canonical forms always compare correctly.</p>
+<h2 id="the-single-instance-invariant-for-server_timestamp">The single-instance invariant for <code>SERVER_TIMESTAMP</code></h2>
+<p>The handler resolves every <code>{ __type: 'serverTimestamp' }</code> sentinel in your test data to the <strong>same</strong> <code>Timestamp</code> instance, not a fresh one per occurrence. This matters because:</p>
+<ul>
+<li><code>data.createdAt == request.time</code> succeeds via <code>equals</code> (field-compare), which would work either way.</li>
+<li>But the <em>single-instance</em> property documents the intent: the request’s notion of “now” is one value, not many. If you ever refactor the resolver to construct per-call, deepEquals comparisons inside the engine will still pass, but the conceptual model breaks. The single-instance invariant exists to prevent that drift.</li>
+</ul>
+<h2 id="why-the-wrappers-live-here-not-in-pyricsandbox">Why the wrappers live here, not in <code>pyric/sandbox</code></h2>
+<p>The sandbox in <code>pyric/sandbox</code> also needs <code>Timestamp</code>, <code>Vector</code>, <code>Reference</code>. When it reads a document containing a timestamp field, it needs to return a <code>Timestamp</code> instance that <code>instanceof Timestamp</code> is true for. If the wrapper classes lived in the sandbox, the rules simulator couldn’t use them without depending on the sandbox; if they lived in both packages, <code>instanceof Timestamp</code> would lie depending on which copy was imported.</p>
+<p>The classes themselves are engine-internal, importable from <code>pyric/rules/internal</code> for callers that need <code>instanceof</code> checks or custom evaluation. Most callers never import them directly: the public <code>pyric/rules</code> value helpers (<code>serverTimestamp()</code>, <code>timestamp()</code>, <code>bytes()</code>, <code>latlng()</code>, <code>duration()</code>, <code>reference()</code>, <code>vector()</code>) construct the right instance without exposing the class.</p>
+<p>The wrappers live in <code>pyric/rules</code> (internally) because:</p>
+<ul>
+<li>This is the package that defines what <code>is timestamp</code> means.</li>
+<li>This is the package that evaluates expressions, which is where most wrapper code is exercised.</li>
+<li>One canonical class per type, so <code>instanceof</code> always works.</li>
+</ul>
+<p>The cost is a small runtime cycle: <code>pyric/sandbox</code> imports the wrappers from this package, and this package imports the <code>LocalEnvironment</code> type from <code>pyric/sandbox/internal</code>. The cycle is type-only on the rules-tooling side and value-import on the sandbox side, which is benign at build time and runtime. We accepted the cycle over duplicating the wrappers.</p>  </article> </main> <aside class="doc-toc" aria-label="On this page"> <h2 class="doc-toc-heading">On this page</h2> <ul> <li data-depth="2"> <a href="#what-the-rules-engine-sees">What the rules engine sees</a> </li><li data-depth="2"> <a href="#the-rulesvalue-base-class">The RulesValue base class</a> </li><li data-depth="2"> <a href="#the-no_op-sentinel">The NO_OP sentinel</a> </li><li data-depth="2"> <a href="#equality-semantics">Equality semantics</a> </li><li data-depth="2"> <a href="#the-single-instance-invariant-for-server_timestamp">The single-instance invariant for SERVER_TIMESTAMP</a> </li><li data-depth="2"> <a href="#why-the-wrappers-live-here-not-in-pyricsandbox">Why the wrappers live here, not in pyric/sandbox</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-rules-explanation-value-wrappers-design.md ADDED Viewed

@@ -0,0 +1,84 @@
+# Value wrapper design
+Firestore rules have a small but real type system. `request.time` is a `timestamp`. `request.path` is a `path`. `bytes[0:10]` is a `bytes` value. `is duration`, `is timestamp`, `is reference` are type tests. None of these have first-class JavaScript representations (`Timestamp` is not a primitive, `Path` is not a primitive), so the simulator has to model them somehow.
+We model them as classes. Each Firestore rules type is a TypeScript class extending `RulesValue`. This page explains why, and what falls out.
+## What the rules engine sees
+When a rule says `request.time.toMillis() > 1700000000000`, the production engine evaluates:
+1. `request.time`: a value of type `timestamp`.
+2. `.toMillis()`: a method dispatch on `timestamp`, returning `int`.
+3. `> 1700000000000`: a binary comparison on `int`.
+For step 2 to work, the simulator's representation of `request.time` has to remember that it's a `timestamp` (not a bare number, not a generic object) and dispatch `toMillis` accordingly.
+Three options were on the table:
+- **Plain objects with a discriminator field** (`{ __type: 'timestamp', seconds, nanos }`). Lightweight and JSON-serialisable, but every method call goes through a switch and `instanceof` doesn't work.
+- **Tagged union with a service registry** (`evaluator.dispatch('timestamp', 'toMillis', value, args)`). Decouples values from behaviour. Hard to extend without touching central code.
+- **Class instances** (`class Timestamp { toMillis() {...} }`). Methods live with their data, `instanceof` works, but classes have to be imported by every package that touches them.
+We chose classes. The class-instances approach pulled together best in practice:
+- Methods are co-located with the data they operate on, so adding a new method to `Timestamp` is a one-file change.
+- `instanceof Timestamp` works, so the evaluator can branch on type at runtime without a registry.
+- `equals()` is a method that knows how to compare two instances, so deep-equality of test data and rule results is straightforward.
+- `toJSON()` is built into the protocol: the wrappers serialise to plain objects when crossing the wire to the Rules Test API.
+## The `RulesValue` base class
+All wrappers extend `RulesValue`. The base class is intentionally thin:
+```ts
+abstract class RulesValue {
+  readonly typeName: string;            // 'timestamp', 'path', 'bytes', ...
+  callMethod(method, args): unknown | NoOp;
+  binaryOp?(op, other): unknown | NoOp;
+  equals(other): boolean;
+  toJSON(): unknown;
+  toString(): string;
+}
+```
+`callMethod` and `binaryOp` exist so the evaluator can dispatch generically: `if (lhs instanceof RulesValue) return lhs.callMethod(method, args)`. The handler doesn't need a per-type switch; the polymorphism does the work.
+`typeName` is the lowercase identifier the rules engine uses for the `is` operator. `request.time is timestamp` works because `Timestamp.typeName === 'timestamp'`.
+## The `NO_OP` sentinel
+When a wrapper is asked to dispatch a method or operation it doesn't implement, it returns `NO_OP` rather than throwing or returning `undefined`. The evaluator catches `NO_OP` and throws `UnsupportedError`, which the handler maps to `state: 'UNSUPPORTED'`.
+The sentinel exists so that:
+- The wrapper can decline cleanly without knowing why the caller is dispatching.
+- The evaluator can distinguish "method returned `undefined`" (a legitimate result) from "method does not exist" (an `UnsupportedError`).
+- Adding a new method to a wrapper does not require updating the evaluator: add the case to `callMethod` and start returning a real value instead of `NO_OP`.
+## Equality semantics
+`equals()` is what makes test data comparable. Two `Timestamp` instances with the same `seconds` and `nanos` are equal. Two `Path` instances with the same segments are equal. Without this, every rule that compares two timestamps would have to compare by reference, and test data, which constructs fresh wrappers every time, would never compare equal to the engine's wrappers.
+Equality is a field-compare, not a reference compare. This is the same model production uses. It does mean care is needed when constructing test data: a `Timestamp` built from a different `seconds`/`nanos` split (say `seconds: 100, nanos: 0` vs `seconds: 99, nanos: 1_000_000_000`) is **not** equal under field-compare, even though both represent the same instant. The `Timestamp` constructor normalises through `seconds + Math.floor(nanos / 1e9)`, so canonical forms always compare correctly.
+## The single-instance invariant for `SERVER_TIMESTAMP`
+The handler resolves every `{ __type: 'serverTimestamp' }` sentinel in your test data to the **same** `Timestamp` instance, not a fresh one per occurrence. This matters because:
+- `data.createdAt == request.time` succeeds via `equals` (field-compare), which would work either way.
+- But the *single-instance* property documents the intent: the request's notion of "now" is one value, not many. If you ever refactor the resolver to construct per-call, deepEquals comparisons inside the engine will still pass, but the conceptual model breaks. The single-instance invariant exists to prevent that drift.
+## Why the wrappers live here, not in `pyric/sandbox`
+The sandbox in `pyric/sandbox` also needs `Timestamp`, `Vector`, `Reference`. When it reads a document containing a timestamp field, it needs to return a `Timestamp` instance that `instanceof Timestamp` is true for. If the wrapper classes lived in the sandbox, the rules simulator couldn't use them without depending on the sandbox; if they lived in both packages, `instanceof Timestamp` would lie depending on which copy was imported.
+The classes themselves are engine-internal, importable from `pyric/rules/internal` for callers that need `instanceof` checks or custom evaluation. Most callers never import them directly: the public `pyric/rules` value helpers (`serverTimestamp()`, `timestamp()`, `bytes()`, `latlng()`, `duration()`, `reference()`, `vector()`) construct the right instance without exposing the class.
+The wrappers live in `pyric/rules` (internally) because:
+- This is the package that defines what `is timestamp` means.
+- This is the package that evaluates expressions, which is where most wrapper code is exercised.
+- One canonical class per type, so `instanceof` always works.
+The cost is a small runtime cycle: `pyric/sandbox` imports the wrappers from this package, and this package imports the `LocalEnvironment` type from `pyric/sandbox/internal`. The cycle is type-only on the rules-tooling side and value-import on the sandbox side, which is benign at build time and runtime. We accepted the cycle over duplicating the wrappers.

package/dist/serve/docs-ui/docs/pyric-rules-explanation-why-this-package-exists/index.html ADDED Viewed

@@ -0,0 +1,34 @@
+<!DOCTYPE html><html lang="en"> <head><meta charset="UTF-8"><meta name="viewport" content="width=device-width, initial-scale=1.0"><title>Why this package exists · Pyric Studio</title><link rel="preconnect" href="https://fonts.googleapis.com"><link rel="preconnect" href="https://fonts.gstatic.com" crossorigin><link href="https://fonts.googleapis.com/css2?family=Inter:wght@300;400;500;600;700&family=JetBrains+Mono:wght@400;500;700&display=swap" rel="stylesheet"><link rel="stylesheet" href="/__pyric/ui/_astro/_slug_.CQYSemvw.css"></head> <body>  <header class="studio__bar"> <div class="studio__bar-inner"> <a class="studio__brand" href="/__pyric/ui/" aria-label="Pyric Studio">Pyric</a> <nav class="studio__nav" aria-label="Studio tabs"> <a class="studio__nav-tab" href="/__pyric/ui/"> Home </a><a class="studio__nav-tab" href="/__pyric/ui/firestore"> Firestore </a><a class="studio__nav-tab" href="/__pyric/ui/auth"> Auth </a><a class="studio__nav-tab" href="/__pyric/ui/rtdb"> RTDB </a><a class="studio__nav-tab" href="/__pyric/ui/storage"> Storage </a><a class="studio__nav-tab" href="/__pyric/ui/traffic"> Traffic </a><a class="studio__nav-tab" href="/__pyric/ui/settings"> Settings </a><a class="studio__nav-tab" href="/__pyric/ui/docs" aria-current="page"> Docs </a> </nav> </div> </header> <div class="docs-shell">  <details class="docs-nav-drawer"> <summary>Navigate</summary> <nav class="docs-nav" aria-label="Documentation"> <div class="docs-search" data-index-url="/__pyric/ui/docs/index.json"> <div class="docs-search-field"> <svg class="docs-search-icon" viewBox="0 0 16 16" width="14" height="14" aria-hidden="true"> <path d="M11.5 11.5 15 15M13 7A6 6 0 1 1 1 7a6 6 0 0 1 12 0Z" fill="none" stroke="currentColor" stroke-width="1.4" stroke-linecap="round"></path> </svg> <input type="text" class="docs-search-input" placeholder="Search docs" aria-label="Search docs" autocomplete="off" spellcheck="false"> <kbd class="docs-search-kbd">⌘K</kbd> </div> <ul class="docs-search-results" hidden></ul> </div> <script type="module">let i=null;function d(t){return i||(i=fetch(t).then(e=>e.json())),i}function l(t,e){return t.title.toLowerCase().includes(e)||t.excerpt.toLowerCase().includes(e)?!0:t.headings.some(r=>r.text.toLowerCase().includes(e))}function u(t,e,r){if(e.innerHTML="",t.length===0){e.hidden=!1;{const n=document.createElement("li");n.className="docs-search-empty",n.textContent="No matches",e.appendChild(n)}return}e.hidden=!1;for(const n of t.slice(0,8)){const s=document.createElement("li"),c=document.createElement("a");c.href=n.path;const o=document.createElement("span");o.className="docs-search-result-title",o.textContent=n.title;const a=document.createElement("span");a.className="docs-search-result-meta",a.textContent=[n.group,n.section].filter(Boolean).join(" / "),c.append(o,a),s.appendChild(c),e.appendChild(s)}}document.querySelectorAll(".docs-search").forEach(t=>{const e=t.dataset.indexUrl,r=t.querySelector(".docs-search-input"),n=t.querySelector(".docs-search-results");r.addEventListener("input",async()=>{const s=r.value.trim().toLowerCase();if(!s){n.hidden=!0,n.innerHTML="";return}const{pages:c}=await d(e);r.value.trim().toLowerCase()===s&&u(c.filter(o=>l(o,s)),n)}),r.addEventListener("focus",()=>{d(e),n.childElementCount>0&&(n.hidden=!1)}),r.addEventListener("keydown",s=>{s.key==="Escape"&&(r.value="",n.hidden=!0,n.innerHTML="",r.blur())}),r.addEventListener("blur",()=>{window.setTimeout(()=>{n.hidden=!0},150)})});document.addEventListener("keydown",t=>{if(!(t.metaKey||t.ctrlKey)||t.key.toLowerCase()!=="k")return;const e=[...document.querySelectorAll(".docs-search-input")].find(r=>r.offsetParent!==null);e&&(t.preventDefault(),e.focus(),e.select())});</script> <a class="docs-nav-toplink" href="/__pyric/ui/docs/overview/"> Overview </a><details class="docs-nav-group"> <summary>Run locally</summary> <div class="docs-nav-group-body"> <div class="docs-nav-section">  <ul> <li> <a href="/__pyric/ui/docs/start-building/"> Quickstart </a> </li><li> <a href="/__pyric/ui/docs/how-the-swap-works/"> How the swap works </a> </li><li> <a href="/__pyric/ui/docs/set-up-your-agent/"> Connect an agent </a> </li><li> <a href="/__pyric/ui/docs/test-in-node/"> Test in Node </a> </li> </ul> </div> </div> </details><details class="docs-nav-group"> <summary>Develop with Firebase APIs</summary> <div class="docs-nav-group-body"> <div class="docs-nav-section">  <ul> <li> <a href="/__pyric/ui/docs/sign-in-and-manage-users/"> Sign in and manage users </a> </li><li> <a href="/__pyric/ui/docs/store-and-query-data/"> Store and query data </a> </li><li> <a href="/__pyric/ui/docs/sync-realtime-data/"> Sync realtime data </a> </li><li> <a href="/__pyric/ui/docs/store-files/"> Store files </a> </li><li> <a href="/__pyric/ui/docs/receive-messages/"> Receive messages </a> </li><li> <a href="/__pyric/ui/docs/run-ai-logic-locally/"> Run AI Logic locally </a> </li><li> <a href="/__pyric/ui/docs/pyric-cli-how-to-run-rtdb-onvaluecreated/"> Run an RTDB function locally </a> </li><li> <a href="/__pyric/ui/docs/which-data-service/"> Which data service? </a> </li> </ul> </div> </div> </details><details class="docs-nav-group"> <summary>Inspect and correct</summary> <div class="docs-nav-group-body"> <div class="docs-nav-section"> <h2 class="docs-nav-heading"> Inspect the sandbox </h2> <ul> <li> <a href="/__pyric/ui/docs/see-whats-happening/"> Traffic &amp; rule verdicts </a> </li><li> <a href="/__pyric/ui/docs/read-a-denial/"> Read a denial and understand it </a> </li><li> <a href="/__pyric/ui/docs/shape-your-data/"> Seed, snapshot, replay </a> </li><li> <a href="/__pyric/ui/docs/watch-and-review/"> Review agent activity </a> </li> </ul> </div><div class="docs-nav-section"> <h2 class="docs-nav-heading"> Correct Security Rules </h2> <ul> <li> <a href="/__pyric/ui/docs/secure-it-with-rules/"> Security Rules </a> </li><li> <a href="/__pyric/ui/docs/simulate-and-lint/"> Simulate and lint before you deploy </a> </li><li> <a href="/__pyric/ui/docs/rules-patterns/"> Rules patterns </a> </li><li> <a href="/__pyric/ui/docs/rules-standard-library/"> The rules standard library </a> </li><li> <a href="/__pyric/ui/docs/rtdb-rules-in-typescript/"> RTDB rules in TypeScript </a> </li><li> <a href="/__pyric/ui/docs/firestore-rules-limits/"> Rules limits </a> </li><li> <a href="/__pyric/ui/docs/whats-possible/"> Case studies </a> </li> </ul> </div><div class="docs-nav-section"> <h2 class="docs-nav-heading"> Work with an agent </h2> <ul> <li> <a href="/__pyric/ui/docs/what-your-agent-can-do/"> Work through an agent </a> </li><li> <a href="/__pyric/ui/docs/skills/"> Agent skills </a> </li> </ul> </div> </div> </details><details class="docs-nav-group"> <summary>Verify the boundary</summary> <div class="docs-nav-group-body"> <div class="docs-nav-section">  <ul> <li> <a href="/__pyric/ui/docs/pyric-cli-how-to-verify-against-a-captured-session/"> Verify a captured session </a> </li><li> <a href="/__pyric/ui/docs/write-a-rules-test-suite/"> Write a rules test suite </a> </li><li> <a href="/__pyric/ui/docs/audit-your-rules/"> Audit rules and data </a> </li> </ul> </div> </div> </details><details class="docs-nav-group"> <summary>Ship unchanged</summary> <div class="docs-nav-group-body"> <div class="docs-nav-section">  <ul> <li> <a href="/__pyric/ui/docs/ship-to-production/"> Ship to production </a> </li><li> <a href="/__pyric/ui/docs/set-up-the-project/"> Set up the Firebase project </a> </li> </ul> </div> </div> </details><details class="docs-nav-group"> <summary>Conformance</summary> <div class="docs-nav-group-body"> <div class="docs-nav-section">  <ul> <li> <a href="/__pyric/ui/docs/how-we-know-it-matches-firebase/"> Conformance </a> </li><li> <a href="/__pyric/ui/docs/whats-experimental/"> What&#39;s experimental </a> </li><li> <a href="/__pyric/ui/docs/pyric-conformance-scores/"> Conformance scores </a> </li><li> <a href="/__pyric/ui/docs/pyric-app-compat/"> App </a> </li><li> <a href="/__pyric/ui/docs/pyric-firestore-compat/"> Firestore </a> </li><li> <a href="/__pyric/ui/docs/pyric-auth-compat/"> Auth </a> </li><li> <a href="/__pyric/ui/docs/pyric-database-compat/"> Realtime Database </a> </li><li> <a href="/__pyric/ui/docs/pyric-storage-compat/"> Storage </a> </li><li> <a href="/__pyric/ui/docs/pyric-rules-compat/"> Rules </a> </li><li> <a href="/__pyric/ui/docs/pyric-messaging-compat/"> Messaging </a> </li><li> <a href="/__pyric/ui/docs/pyric-ai-compat/"> AI Logic </a> </li><li> <a href="/__pyric/ui/docs/pyric-cli-functions-rtdb-compat/"> Functions · RTDB </a> </li> </ul> </div> </div> </details> <details class="docs-nav-group" open> <summary>Reference</summary> <div class="docs-nav-group-body"> <div class="docs-nav-section"> <ul> <li> <a href="/__pyric/ui/docs/pyric-cli/"> @pyric/cli </a> </li><li> <a href="/__pyric/ui/docs/pyric-explanation-versioning-and-compatibility/"> pyric </a> </li><li> <a href="/__pyric/ui/docs/pyric-firestore/"> pyric / firestore </a> </li><li> <a href="/__pyric/ui/docs/pyric-rules/" aria-current="true"> 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/"> pyric / firestore </a> </li><li> <a href="/__pyric/ui/docs/pyric-rules/" aria-current="true"> 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-rules/">pyric / rules</a> </li><li> <span class="docs-breadcrumbs-sep" aria-hidden="true">/</span> <span>Explanation</span> </li><li> <span class="docs-breadcrumbs-sep" aria-hidden="true">/</span> <span aria-current="page">Why this package exists</span> </li> </ol> </nav>  <article class="prose">  <h1 id="why-this-package-exists">Why this package exists</h1>
+<p>Firestore Security Rules is a small DSL that sits between every read and write your app makes. In Pyric we have two distinct needs around that DSL:</p>
+<ol>
+<li>
+<p>A <strong>data-plane</strong> for the app code (<code>getDoc</code>, <code>setDoc</code>, <code>onSnapshot</code>, the modular Web SDK shape) that can be swapped between production Firestore and an in-process sandbox. This lives in <code>pyric/firestore</code>.</p>
+</li>
+<li>
+<p><strong>Tooling around the rules themselves</strong>: parsing them, linting them, simulating them, testing them. This is <code>pyric/rules</code>.</p>
+</li>
+</ol>
+<p>The split looks bureaucratic at first. Why not put both in one package? Two reasons:</p>
+<h2 id="the-swap-in-surface-must-stay-minimal">The swap-in surface must stay minimal</h2>
+<p><code>pyric/firestore</code> is meant to be a drop-in replacement for <code>firebase/firestore</code>. Any host that imports it should see exactly the surface area that the upstream modular Web SDK exposes. No more, no less. Adding rules tooling to that import path would either pollute the swap-in surface (making the package look bigger than the production package it mirrors) or force consumers to import from non-standard sub-paths (which break tree-shaking and make TypeScript editor completion noisier than it needs to be).</p>
+<p>The same reasoning shapes <code>pyric/rules</code> internally: the public front door (<code>firestoreRules</code>, <code>rtdbRules</code>, <code>lint</code>, the assertion adapters) is small on purpose, but the engine underneath it (the parser, <code>parseToAST</code>; the linter, <code>lintFirestoreRules</code>; the validator, <code>validateFirestoreRules</code>; the simulator, <code>SimulateFirestoreRulesHandler</code>; seven value wrappers; and a sentinel expression engine) is bigger than the production data-plane surface. Bundling all of that onto <code>pyric/firestore</code>’s root would dominate the swap-in package, which is why it stays behind <code>pyric/rules/internal</code> instead.</p>
+<h2 id="the-audiences-are-different">The audiences are different</h2>
+<p>Most apps using <code>pyric/firestore</code> will never call any function in <code>pyric/rules</code>. The data-plane is consumed by feature code: components, hooks, server actions. The rules tooling is consumed by tooling code: CI scripts, lint hooks, deploy pipelines, agent runtimes. These audiences have different bundle-size sensitivities (a feature-code package has to pay for every dependency in every consumer’s bundle; a tooling package only loads in CI) and different release cadences (the data plane changes when the Firestore Web SDK does; the rules tooling changes when we discover a new agent failure mode).</p>
+<p>A clean split lets each side evolve at its own speed without burdening the other.</p>
+<h2 id="what-ends-up-here">What ends up here</h2>
+<p>Anything <em>about</em> rules:</p>
+<ul>
+<li>The parser that turns rules text into an AST.</li>
+<li>The linter that catches compilation limits, runtime-budget risks, and security anti-patterns.</li>
+<li>The validator that emits the <code>SEC</code> / <code>SEM</code> / <code>QUA</code> / <code>STR</code> finding codes.</li>
+<li>The modules resolver and stdlib.</li>
+<li>The local simulator (used by the sandbox and by agents).</li>
+<li>The Rules Test API client (used by CI and by agents).</li>
+<li>The value wrappers that model <code>Timestamp</code>, <code>Path</code>, <code>Bytes</code>, etc.</li>
+<li>The sentinel expression engine used by <code>pyric/sandbox</code> for declarative writes.</li>
+<li>The tool factories that wrap all of the above as <code>@inbrowser/agent</code> tool handlers.</li>
+</ul>
+<h2 id="what-stays-out">What stays out</h2>
+<p>The Firestore Web SDK surface stays in <code>pyric/firestore</code>. Production shipping stays with <code>firebase-tools</code> / Console. Credentials for the Rules Test API live in <code>@pyric/cli/credentials/node</code>. The sandbox itself (the <code>LocalEnvironment</code> that holds documents and listeners) stays in <code>pyric/sandbox</code>. These packages form a loose hexagon: data plane, rules tooling, sandbox, and local CLI verify — none depends on a kitchen-sink control-plane package.</p>
+<h2 id="tradeoffs">Tradeoffs</h2>
+<p>The cost of the split is duplication risk: a value wrapper used by both the sandbox (for type coercion at read-time) and the rules simulator (for expression evaluation) has to live in exactly one of the two packages, and the other has to import it. We chose to put the wrappers here because the rules simulator is the source of truth for “what does Firestore think this value is”. The sandbox imports <code>Timestamp</code>, <code>Vector</code>, <code>Reference</code> from <code>pyric/rules/internal</code> as a result, which creates a runtime cycle in workspace terms. The cycle is benign at build time (the two packages export non-overlapping symbols and TypeScript handles the resolution), but it does mean both have to be built in a specific order. We accepted that complexity over the alternatives: duplicating the wrapper classes, which would make <code>instanceof Timestamp</code> start lying, or shipping a third <code>pyric/firestore-values</code> package, which would split the wrappers from their evaluator and make the evaluation logic harder to reason about.</p>  </article> </main> <aside class="doc-toc" aria-label="On this page"> <h2 class="doc-toc-heading">On this page</h2> <ul> <li data-depth="2"> <a href="#the-swap-in-surface-must-stay-minimal">The swap-in surface must stay minimal</a> </li><li data-depth="2"> <a href="#the-audiences-are-different">The audiences are different</a> </li><li data-depth="2"> <a href="#what-ends-up-here">What ends up here</a> </li><li data-depth="2"> <a href="#what-stays-out">What stays out</a> </li><li data-depth="2"> <a href="#tradeoffs">Tradeoffs</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>