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-agent-failure-modes/index.html ADDED Viewed

@@ -0,0 +1,50 @@
+<!DOCTYPE html><html lang="en"> <head><meta charset="UTF-8"><meta name="viewport" content="width=device-width, initial-scale=1.0"><title>Agent failure modes the linter catches · 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">Agent failure modes</span> </li> </ol> </nav>  <article class="prose">  <h1 id="agent-failure-modes-the-linter-catches">Agent failure modes the linter catches</h1>
+<p>Most of the linter’s compilation and budget rules came from production: we hit the limit, learned the number, encoded it. A separate set of rules came from somewhere different. We watched LLM-driven agents try to write rules and fail in characteristic ways.</p>
+<p>These rules are advisory in nature but defensive in posture. Each one exists because an agent shipped the same broken pattern more than once in our playground sessions. This page tells the stories.</p>
+<h2 id="escaping-a-denial-with-if-true">Escaping a denial with <code>if true</code></h2>
+<p>The most common failure mode. The agent writes a rule with a careful predicate. A test case denies when the agent expected it to allow. The agent doesn’t understand why, can’t reproduce the rule’s mental model, and replaces the predicate with <code>if true</code> to make the test pass.</p>
+<p>The deploy ships. The collection is now publicly writable.</p>
+<p>The linter catches this with two rules:</p>
+<ul>
+<li><strong><code>PERMISSIVE_RULE</code></strong>: any write rule whose predicate folds to constant <code>true</code>. The fold handles boolean literals, <code>&#x26;&#x26;</code> / <code>||</code> of booleans, <code>!</code> of a boolean. It does not try to prove <code>1 == 1</code> or follow function calls; a few false negatives are acceptable, a single false positive would block a legitimate deploy.</li>
+<li><strong><code>RECURSIVE_WILDCARD_OPEN</code></strong>: a match path with <code>{document=**}</code> combined with an always-true predicate. The recursive wildcard makes the open-rule especially dangerous because it overrides every specific rule beneath it. Separate from <code>PERMISSIVE_RULE</code> so the diagnostic names the specific anti-pattern.</li>
+</ul>
+<p>Both are <code>severity: 'error'</code>. The deploy path refuses to swap a ruleset that contains either.</p>
+<p>The fix isn’t to relax the linter. It’s to give the agent a real diagnostic for the original denial. Each <code>CaseResult</code>’s <code>trace</code> array shows exactly which rule decided; <code>explainCase</code> renders it into a readable string. If the agent learns to read that trace, the escape doesn’t happen.</p>
+<h2 id="silently-removing-predicates">Silently removing predicates</h2>
+<p>A subtler variant. The agent writes:</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">allow</span><span style="color:#61AFEF"> update</span><span style="color:#ABB2BF">: </span><span style="color:#C678DD">if</span><span style="color:#E5C07B"> request</span><span style="color:#ABB2BF">.auth.uid == </span><span style="color:#E5C07B">resource</span><span style="color:#ABB2BF">.data.ownerId</span></span>
+<span class="line"><span style="color:#ABB2BF">              &#x26;&#x26; status == </span><span style="color:#98C379">'open'</span><span style="color:#ABB2BF">;</span></span></code></pre>
+<p>A test case fails because the test set <code>status</code> to <code>'closed'</code>. The agent doesn’t update the test data. It removes the <code>status == 'open'</code> conjunct from the rule. The test passes. The deploy ships. Updates against closed records are no longer gated.</p>
+<p><code>RULES_WEAKENED</code> exists for this. When you pass the previously-deployed source to the linter (via the engine-internal <code>lintFirestoreRules</code> on <code>pyric/rules/internal</code>, since the public <code>lint</code> and <code>firestoreRules(source).lint()</code> take no options):</p>
+<pre class="astro-code one-dark-pro" style="background-color:#282c34;color:#abb2bf; overflow-x: auto;" tabindex="0" data-language="ts"><code><span class="line"><span style="color:#61AFEF">lintFirestoreRules</span><span style="color:#ABB2BF">(</span><span style="color:#E06C75">newSource</span><span style="color:#ABB2BF">, { </span><span style="color:#E06C75">previousSource</span><span style="color:#ABB2BF">: </span><span style="color:#E06C75">oldSource</span><span style="color:#ABB2BF"> });</span></span></code></pre>
+<p>…the linter normalises every match path, finds the corresponding allow rule by op-set, extracts the top-level conjuncts of each predicate (split only on <code>&#x26;&#x26;</code>, never <code>||</code>), and reports every conjunct that existed before and is missing now.</p>
+<p><code>RULES_WEAKENED</code> is <code>warning</code>, not <code>error</code>. There are real reasons to delete a predicate: a refactor, a dedupe, an intentional broadening. The signal is “review this”, not “refuse the deploy”. A human (or a more careful agent) decides whether the removal is intentional.</p>
+<h2 id="javascript-hallucinations">JavaScript hallucinations</h2>
+<p>LLMs trained primarily on JavaScript will write <code>.filter()</code>, <code>.map()</code>, <code>.toLowerCase()</code>, <code>===</code>, <code>?.</code>, <code>??</code> in rules sources. None of these exist in the Firestore rules DSL. They either fail to parse (with an unhelpful “expected <code>)</code>” message) or parse and then fail at runtime (silently denying every request).</p>
+<p>The pre-parse syntax-hint pass fires on the raw source, before the parser runs, so the diagnostic is precise even when the file is unparseable:</p>
+<ul>
+<li><strong><code>INVALID_OPERATOR</code></strong>: <code>===</code>, <code>!==</code>, <code>?.</code>, <code>??</code>, backtick template literals. Each gets a specific message naming the JS operator and the Firestore-equivalent (or absence of one).</li>
+</ul>
+<p>The post-parse hallucination pass walks the AST for syntactically-valid-but-semantically-wrong calls:</p>
+<ul>
+<li><strong><code>HALLUCINATED_METHOD</code></strong>: method calls that don’t exist in the rules surface.</li>
+<li><strong><code>HALLUCINATED_GLOBAL</code></strong>: references to globals the engine doesn’t expose (<code>Math</code>, <code>JSON</code>, <code>Date</code>).</li>
+<li><strong><code>WRONG_CONTEXT_PATH</code></strong>: <code>get(...)</code> calls whose path doesn’t begin with <code>/databases/$(database)/documents/</code>.</li>
+<li><strong><code>LENGTH_PROPERTY</code></strong>: <code>.length</code> access on a string or list (the rules surface uses <code>.size()</code>).</li>
+<li><strong><code>INVALID_PATH_INTERPOLATION</code></strong>: match-style <code>{ident}</code> used inside a path literal where Firestore requires <code>$(ident)</code>.</li>
+<li><strong><code>METHOD_MISSING_PARENS</code></strong>: an identifier in expression position that looks like a method name without parens.</li>
+</ul>
+<p>Each rule produces a fix string when possible. The agent gets “you wrote <code>.length</code>, Firestore wants <code>.size()</code>” instead of a generic syntax error.</p>
+<h2 id="time-dependent-flakiness">Time-dependent flakiness</h2>
+<p>A rule reads <code>request.time</code> (a date-gated discount window, a trial-period check, an audit-log retention rule). The agent’s test case doesn’t pin <code>requestTime</code>, so the simulator falls back to wallclock. The test passes today, fails three months later when the rule’s date threshold has rolled past wallclock. CI starts going red intermittently.</p>
+<p><code>REQUEST_TIME_NOT_PINNED</code> activates when <code>options.testCases</code> is passed to the linter. For each rule that transitively reads <code>request.time</code>, the linter emits one warning per test case that targets the rule and doesn’t set <code>requestTime</code>. The fix is mechanical: add the ISO-8601 string. The diagnostic is precise: it names the rule, the test case, the path.</p>
+<p>This is the only lint rule that depends on a test suite, and the dependency is opt-in (<code>options.testCases</code> defaults to undefined). Source-only calls to the internal <code>lintFirestoreRules(source)</code> (or the public <code>lint(source)</code> / <code>firestoreRules(source).lint()</code>, which never take a test suite at all) behave as they always did.</p>
+<h2 id="the-shape-of-these-rules">The shape of these rules</h2>
+<p>Every rule on this page shares three properties:</p>
+<ul>
+<li><strong>It came from observation, not specification.</strong> No one sat down to design <code>RULES_WEAKENED</code>; we watched it ship a regression and added the check the next day.</li>
+<li><strong>It targets the agent, not the language.</strong> A careful human reading the source would catch most of these on review. The point is to surface them automatically.</li>
+<li><strong>It carries a precise fix.</strong> “Your rule is wrong” is a useless diagnostic for an agent looping on the linter’s output. “Replace <code>if true</code> with <code>request.auth.uid == resource.data.ownerId</code>” is something the agent can act on directly.</li>
+</ul>
+<p>The list is not closed. As we watch new failure modes emerge (typically when a model architecture changes, or a new playground scenario surfaces a recurring mistake), new rules join it.</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="#escaping-a-denial-with-if-true">Escaping a denial with if true</a> </li><li data-depth="2"> <a href="#silently-removing-predicates">Silently removing predicates</a> </li><li data-depth="2"> <a href="#javascript-hallucinations">JavaScript hallucinations</a> </li><li data-depth="2"> <a href="#time-dependent-flakiness">Time-dependent flakiness</a> </li><li data-depth="2"> <a href="#the-shape-of-these-rules">The shape of these rules</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-agent-failure-modes.md ADDED Viewed

@@ -0,0 +1,78 @@
+# Agent failure modes the linter catches
+Most of the linter's compilation and budget rules came from production: we hit the limit, learned the number, encoded it. A separate set of rules came from somewhere different. We watched LLM-driven agents try to write rules and fail in characteristic ways.
+These rules are advisory in nature but defensive in posture. Each one exists because an agent shipped the same broken pattern more than once in our playground sessions. This page tells the stories.
+## Escaping a denial with `if true`
+The most common failure mode. The agent writes a rule with a careful predicate. A test case denies when the agent expected it to allow. The agent doesn't understand why, can't reproduce the rule's mental model, and replaces the predicate with `if true` to make the test pass.
+The deploy ships. The collection is now publicly writable.
+The linter catches this with two rules:
+- **`PERMISSIVE_RULE`**: any write rule whose predicate folds to constant `true`. The fold handles boolean literals, `&&` / `||` of booleans, `!` of a boolean. It does not try to prove `1 == 1` or follow function calls; a few false negatives are acceptable, a single false positive would block a legitimate deploy.
+- **`RECURSIVE_WILDCARD_OPEN`**: a match path with `{document=**}` combined with an always-true predicate. The recursive wildcard makes the open-rule especially dangerous because it overrides every specific rule beneath it. Separate from `PERMISSIVE_RULE` so the diagnostic names the specific anti-pattern.
+Both are `severity: 'error'`. The deploy path refuses to swap a ruleset that contains either.
+The fix isn't to relax the linter. It's to give the agent a real diagnostic for the original denial. Each `CaseResult`'s `trace` array shows exactly which rule decided; `explainCase` renders it into a readable string. If the agent learns to read that trace, the escape doesn't happen.
+## Silently removing predicates
+A subtler variant. The agent writes:
+```rules
+allow update: if request.auth.uid == resource.data.ownerId
+              && status == 'open';
+```
+A test case fails because the test set `status` to `'closed'`. The agent doesn't update the test data. It removes the `status == 'open'` conjunct from the rule. The test passes. The deploy ships. Updates against closed records are no longer gated.
+`RULES_WEAKENED` exists for this. When you pass the previously-deployed source to the linter (via the engine-internal `lintFirestoreRules` on `pyric/rules/internal`, since the public `lint` and `firestoreRules(source).lint()` take no options):
+```ts
+lintFirestoreRules(newSource, { previousSource: oldSource });
+```
+…the linter normalises every match path, finds the corresponding allow rule by op-set, extracts the top-level conjuncts of each predicate (split only on `&&`, never `||`), and reports every conjunct that existed before and is missing now.
+`RULES_WEAKENED` is `warning`, not `error`. There are real reasons to delete a predicate: a refactor, a dedupe, an intentional broadening. The signal is "review this", not "refuse the deploy". A human (or a more careful agent) decides whether the removal is intentional.
+## JavaScript hallucinations
+LLMs trained primarily on JavaScript will write `.filter()`, `.map()`, `.toLowerCase()`, `===`, `?.`, `??` in rules sources. None of these exist in the Firestore rules DSL. They either fail to parse (with an unhelpful "expected `)`" message) or parse and then fail at runtime (silently denying every request).
+The pre-parse syntax-hint pass fires on the raw source, before the parser runs, so the diagnostic is precise even when the file is unparseable:
+- **`INVALID_OPERATOR`**: `===`, `!==`, `?.`, `??`, backtick template literals. Each gets a specific message naming the JS operator and the Firestore-equivalent (or absence of one).
+The post-parse hallucination pass walks the AST for syntactically-valid-but-semantically-wrong calls:
+- **`HALLUCINATED_METHOD`**: method calls that don't exist in the rules surface.
+- **`HALLUCINATED_GLOBAL`**: references to globals the engine doesn't expose (`Math`, `JSON`, `Date`).
+- **`WRONG_CONTEXT_PATH`**: `get(...)` calls whose path doesn't begin with `/databases/$(database)/documents/`.
+- **`LENGTH_PROPERTY`**: `.length` access on a string or list (the rules surface uses `.size()`).
+- **`INVALID_PATH_INTERPOLATION`**: match-style `{ident}` used inside a path literal where Firestore requires `$(ident)`.
+- **`METHOD_MISSING_PARENS`**: an identifier in expression position that looks like a method name without parens.
+Each rule produces a fix string when possible. The agent gets "you wrote `.length`, Firestore wants `.size()`" instead of a generic syntax error.
+## Time-dependent flakiness
+A rule reads `request.time` (a date-gated discount window, a trial-period check, an audit-log retention rule). The agent's test case doesn't pin `requestTime`, so the simulator falls back to wallclock. The test passes today, fails three months later when the rule's date threshold has rolled past wallclock. CI starts going red intermittently.
+`REQUEST_TIME_NOT_PINNED` activates when `options.testCases` is passed to the linter. For each rule that transitively reads `request.time`, the linter emits one warning per test case that targets the rule and doesn't set `requestTime`. The fix is mechanical: add the ISO-8601 string. The diagnostic is precise: it names the rule, the test case, the path.
+This is the only lint rule that depends on a test suite, and the dependency is opt-in (`options.testCases` defaults to undefined). Source-only calls to the internal `lintFirestoreRules(source)` (or the public `lint(source)` / `firestoreRules(source).lint()`, which never take a test suite at all) behave as they always did.
+## The shape of these rules
+Every rule on this page shares three properties:
+- **It came from observation, not specification.** No one sat down to design `RULES_WEAKENED`; we watched it ship a regression and added the check the next day.
+- **It targets the agent, not the language.** A careful human reading the source would catch most of these on review. The point is to surface them automatically.
+- **It carries a precise fix.** "Your rule is wrong" is a useless diagnostic for an agent looping on the linter's output. "Replace `if true` with `request.auth.uid == resource.data.ownerId`" is something the agent can act on directly.
+The list is not closed. As we watch new failure modes emerge (typically when a model architecture changes, or a new playground scenario surfaces a recurring mistake), new rules join it.

package/dist/serve/docs-ui/docs/pyric-rules-explanation-lint-vs-validate-vs-simulate-vs-test/index.html ADDED Viewed

@@ -0,0 +1,79 @@
+<!DOCTYPE html><html lang="en"> <head><meta charset="UTF-8"><meta name="viewport" content="width=device-width, initial-scale=1.0"><title>Lint vs validate vs simulate vs test · 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">Lint vs validate vs test</span> </li> </ol> </nav>  <article class="prose">  <h1 id="lint-vs-validate-vs-simulate-vs-test">Lint vs validate vs simulate vs test</h1>
+<p>The package offers four distinct ways to look at a rules source. Their names suggest they overlap. They don’t, and the distinction matters when you’re building a CI pipeline or an agent loop.</p>
+<h2 id="lint-structural-risks">Lint: structural risks</h2>
+<p><code>lint(source)</code> (or <code>firestoreRules(source).lint()</code>), both public, answer: <em>“will this ruleset compile? and if it does, will it survive at runtime?”</em> Both are built on the engine-internal linter, <code>lintFirestoreRules</code> (<code>pyric/rules/internal</code>); the public functions fold its output into <code>RuleIssue</code>s with <code>origin: 'lint'</code>.</p>
+<p>The linter walks the AST counting things (chain depths, let bindings, function-call depths, <code>get()</code> counts, expression tree sizes) and compares those numbers to thresholds it learned from production. Some thresholds are exact: 256 KB source size, 98 chain depth, 11 lets per function. Others are bands derived from observing the runtime budget’s behaviour in the flaky zone (40 / 60 / 100 nodes depending on call count).</p>
+<p>The linter also catches a small but high-value set of <em>known agent failure modes</em>: <code>PERMISSIVE_RULE</code>, <code>RECURSIVE_WILDCARD_OPEN</code>, <code>RULES_WEAKENED</code>, <code>HALLUCINATED_METHOD</code>, <code>INVALID_OPERATOR</code>. These were not in the original linter spec. They were added after watching agents repeatedly ship the same broken patterns. See <a href="../pyric-rules-explanation-agent-failure-modes/">Agent failure modes</a> for the stories behind them.</p>
+<p>What linting does <strong>not</strong> tell you: whether your rules behave the way you intend. A rule that compiles, fits the budget, and avoids every agent footgun can still permit something it shouldn’t. That question is for the simulator and the test API.</p>
+<h2 id="validate-security-and-quality-findings">Validate: security and quality findings</h2>
+<p>The engine-internal <code>validateFirestoreRules(ast)</code> (<code>pyric/rules/internal</code>) answers: <em>“would a careful human reviewer flag anything here?”</em> On the public surface its findings arrive folded into the same <code>RuleIssue</code> list as the linter’s, tagged <code>origin: 'validate'</code>. Both <code>lint(source)</code> and <code>firestoreRules(source).lint()</code> run the validator internally, so most callers never call it directly.</p>
+<p>The validator runs structural checks: public writes, unauthenticated writes, missing default-deny, write-without-data-validation, duplicate function names, overlapping match paths. Its findings carry a four-level severity (<code>critical</code> / <code>high</code> / <code>medium</code> / <code>low</code>) and a code (<code>SEC-1</code>, <code>SEM-2</code>, <code>QUA-3</code>, <code>STR-1</code>).</p>
+<p>The validator’s coverage overlaps the linter’s at the edges. <code>QUA-1</code> (hardcoded <code>true</code>) is reported by both, for instance. The two surfaces exist because:</p>
+<ul>
+<li>The linter focuses on <em>operational</em> concerns: will this deploy? will it run within budget? does it look like JavaScript when it shouldn’t?</li>
+<li>The validator focuses on <em>review</em> concerns: is this safe? is this clean? is this consistent?</li>
+</ul>
+<p>In practice, run both. Their findings union without redundancy in most cases.</p>
+<h2 id="simulate-does-the-rule-decide-correctly-locally">Simulate: does the rule decide correctly, locally?</h2>
+<p><code>firestoreRules(source).simulate(cases)</code> answers: <em>“given these requests, what does the rule decide?”</em></p>
+<p>The simulator parses the rules, builds a <code>SimulationContext</code> from each case, walks every expression with a hand-written evaluator, and produces an <code>ALLOW</code> / <code>DENY</code> decision (or reports the case as unsupported if it doesn’t yet model some feature). You compare the decision to your expectation and learn whether your rule does the right thing for the inputs you care about.</p>
+<p>The simulator is sub-millisecond per case once parsed. It is the right surface for:</p>
+<ul>
+<li>Agent loops that iterate on a rule and need fast feedback.</li>
+<li>CI checks that exercise hundreds of test cases on every PR.</li>
+<li>Local development without a Firebase project.</li>
+</ul>
+<p>It is <strong>not</strong> the right surface when:</p>
+<ul>
+<li>A case comes back unsupported and you need a verdict the simulator can’t give you.</li>
+<li>You’re shipping rules that must behave exactly like production. The simulator is close to bit-for-bit parity, but not bit-for-bit.</li>
+</ul>
+<h2 id="test-does-the-live-firestore-engine-agree">Test: does the live Firestore engine agree?</h2>
+<p>The engine-internal <code>TestFirestoreRulesHandler.execute(scope, source, testCases)</code> (<code>pyric/rules/internal</code>) answers: <em>“would production decide the same way?”</em> There’s no public front-door equivalent yet.</p>
+<p>This calls Google’s Firebase Rules Test API. The request goes to Google’s servers, the rules are evaluated in the production engine, and you get pass/fail per case. The test API never deploys anything (it’s a pure evaluation surface), but it costs HTTP latency and requires a service-account credential.</p>
+<p>Use it when:</p>
+<ul>
+<li>You’re about to deploy and want certainty.</li>
+<li>The simulator returned <code>UNSUPPORTED</code> and you need a verdict.</li>
+<li>You’re investigating a discrepancy between local and production behaviour.</li>
+</ul>
+<h2 id="which-surface-for-which-question">Which surface for which question</h2>
+<div class="table-scroll">
+<table><thead><tr><th>Question</th><th>Surface</th></tr></thead><tbody><tr><td>Will this compile?</td><td>Lint (<code>SOURCE_SIZE</code>, <code>CHAIN_DEPTH</code>, <code>LET_LIMIT</code>)</td></tr><tr><td>Will this survive the runtime budget?</td><td>Lint (<code>EXPRESSION_BUDGET</code>, <code>CALL_DEPTH</code>, <code>GET_COUNT</code>, <code>SHARED_GATE</code>)</td></tr><tr><td>Did the agent open the database again?</td><td>Lint (<code>PERMISSIVE_RULE</code>, <code>RECURSIVE_WILDCARD_OPEN</code>)</td></tr><tr><td>Did anyone silently weaken security?</td><td>Lint with <code>previousSource</code> (<code>RULES_WEAKENED</code>)</td></tr><tr><td>Would a reviewer flag this?</td><td>Validate (<code>SEC</code> / <code>SEM</code> / <code>QUA</code> / <code>STR</code>)</td></tr><tr><td>Does the rule decide what I think it does?</td><td>Simulate</td></tr><tr><td>Does the production engine agree?</td><td>Test</td></tr></tbody></table></div>
+<p>A complete pipeline tends to look like: validate + lint (block on errors), simulate (verify intended behaviour locally), test (parity check before deploy, or when simulator abstains).</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="#lint-structural-risks">Lint: structural risks</a> </li><li data-depth="2"> <a href="#validate-security-and-quality-findings">Validate: security and quality findings</a> </li><li data-depth="2"> <a href="#simulate-does-the-rule-decide-correctly-locally">Simulate: does the rule decide correctly, locally?</a> </li><li data-depth="2"> <a href="#test-does-the-live-firestore-engine-agree">Test: does the live Firestore engine agree?</a> </li><li data-depth="2"> <a href="#which-surface-for-which-question">Which surface for which question</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-lint-vs-validate-vs-simulate-vs-test.md ADDED Viewed

@@ -0,0 +1,69 @@
+# Lint vs validate vs simulate vs test
+The package offers four distinct ways to look at a rules source. Their names suggest they overlap. They don't, and the distinction matters when you're building a CI pipeline or an agent loop.
+## Lint: structural risks
+`lint(source)` (or `firestoreRules(source).lint()`), both public, answer: *"will this ruleset compile? and if it does, will it survive at runtime?"* Both are built on the engine-internal linter, `lintFirestoreRules` (`pyric/rules/internal`); the public functions fold its output into `RuleIssue`s with `origin: 'lint'`.
+The linter walks the AST counting things (chain depths, let bindings, function-call depths, `get()` counts, expression tree sizes) and compares those numbers to thresholds it learned from production. Some thresholds are exact: 256 KB source size, 98 chain depth, 11 lets per function. Others are bands derived from observing the runtime budget's behaviour in the flaky zone (40 / 60 / 100 nodes depending on call count).
+The linter also catches a small but high-value set of *known agent failure modes*: `PERMISSIVE_RULE`, `RECURSIVE_WILDCARD_OPEN`, `RULES_WEAKENED`, `HALLUCINATED_METHOD`, `INVALID_OPERATOR`. These were not in the original linter spec. They were added after watching agents repeatedly ship the same broken patterns. See [Agent failure modes](../pyric-rules-explanation-agent-failure-modes/) for the stories behind them.
+What linting does **not** tell you: whether your rules behave the way you intend. A rule that compiles, fits the budget, and avoids every agent footgun can still permit something it shouldn't. That question is for the simulator and the test API.
+## Validate: security and quality findings
+The engine-internal `validateFirestoreRules(ast)` (`pyric/rules/internal`) answers: *"would a careful human reviewer flag anything here?"* On the public surface its findings arrive folded into the same `RuleIssue` list as the linter's, tagged `origin: 'validate'`. Both `lint(source)` and `firestoreRules(source).lint()` run the validator internally, so most callers never call it directly.
+The validator runs structural checks: public writes, unauthenticated writes, missing default-deny, write-without-data-validation, duplicate function names, overlapping match paths. Its findings carry a four-level severity (`critical` / `high` / `medium` / `low`) and a code (`SEC-1`, `SEM-2`, `QUA-3`, `STR-1`).
+The validator's coverage overlaps the linter's at the edges. `QUA-1` (hardcoded `true`) is reported by both, for instance. The two surfaces exist because:
+- The linter focuses on *operational* concerns: will this deploy? will it run within budget? does it look like JavaScript when it shouldn't?
+- The validator focuses on *review* concerns: is this safe? is this clean? is this consistent?
+In practice, run both. Their findings union without redundancy in most cases.
+## Simulate: does the rule decide correctly, locally?
+`firestoreRules(source).simulate(cases)` answers: *"given these requests, what does the rule decide?"*
+The simulator parses the rules, builds a `SimulationContext` from each case, walks every expression with a hand-written evaluator, and produces an `ALLOW` / `DENY` decision (or reports the case as unsupported if it doesn't yet model some feature). You compare the decision to your expectation and learn whether your rule does the right thing for the inputs you care about.
+The simulator is sub-millisecond per case once parsed. It is the right surface for:
+- Agent loops that iterate on a rule and need fast feedback.
+- CI checks that exercise hundreds of test cases on every PR.
+- Local development without a Firebase project.
+It is **not** the right surface when:
+- A case comes back unsupported and you need a verdict the simulator can't give you.
+- You're shipping rules that must behave exactly like production. The simulator is close to bit-for-bit parity, but not bit-for-bit.
+## Test: does the live Firestore engine agree?
+The engine-internal `TestFirestoreRulesHandler.execute(scope, source, testCases)` (`pyric/rules/internal`) answers: *"would production decide the same way?"* There's no public front-door equivalent yet.
+This calls Google's Firebase Rules Test API. The request goes to Google's servers, the rules are evaluated in the production engine, and you get pass/fail per case. The test API never deploys anything (it's a pure evaluation surface), but it costs HTTP latency and requires a service-account credential.
+Use it when:
+- You're about to deploy and want certainty.
+- The simulator returned `UNSUPPORTED` and you need a verdict.
+- You're investigating a discrepancy between local and production behaviour.
+## Which surface for which question
+| Question | Surface |
+|---|---|
+| Will this compile? | Lint (`SOURCE_SIZE`, `CHAIN_DEPTH`, `LET_LIMIT`) |
+| Will this survive the runtime budget? | Lint (`EXPRESSION_BUDGET`, `CALL_DEPTH`, `GET_COUNT`, `SHARED_GATE`) |
+| Did the agent open the database again? | Lint (`PERMISSIVE_RULE`, `RECURSIVE_WILDCARD_OPEN`) |
+| Did anyone silently weaken security? | Lint with `previousSource` (`RULES_WEAKENED`) |
+| Would a reviewer flag this? | Validate (`SEC` / `SEM` / `QUA` / `STR`) |
+| Does the rule decide what I think it does? | Simulate |
+| Does the production engine agree? | Test |
+A complete pipeline tends to look like: validate + lint (block on errors), simulate (verify intended behaviour locally), test (parity check before deploy, or when simulator abstains).

package/dist/serve/docs-ui/docs/pyric-rules-explanation-runtime-budget-and-shared-gates/index.html ADDED Viewed

@@ -0,0 +1,67 @@
+<!DOCTYPE html><html lang="en"> <head><meta charset="UTF-8"><meta name="viewport" content="width=device-width, initial-scale=1.0"><title>The runtime budget and shared gates · 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">Runtime budget and gates</span> </li> </ol> </nav>  <article class="prose">  <h1 id="the-runtime-budget-and-shared-gates">The runtime budget and shared gates</h1>
+<p>Firestore rules have two kinds of limits. Compilation limits fail loudly: a <code>400 INVALID_ARGUMENT</code> at deploy. The runtime evaluation budget fails silently: a <code>403 PERMISSION_DENIED</code> that looks identical to a denied rule.</p>
+<p>The compile-time limits have exact values. The runtime limits do not. Everything on this page is researched and observed behavior discovered by Pyric’s tooling, and it explains why the linter’s thresholds look the way they do.</p>
+<h2 id="the-exact-limits">The exact limits</h2>
+<p>Three hard caps that Firebase enforces at deploy time:</p>
+<ul>
+<li><strong>256 KB source.</strong> Exact byte limit. Anything longer is rejected outright.</li>
+<li><strong>Chain depth 98.</strong> A flat <code>a &#x26;&#x26; b &#x26;&#x26; c &#x26;&#x26; … &#x26;&#x26; z</code> chain of length 99 or more refuses to compile. The limit is on chain depth, not total nodes: <code>(a &#x26;&#x26; b) &#x26;&#x26; (c &#x26;&#x26; d)</code> has chain depth 1 of <code>&#x26;&#x26;</code>-of-<code>&#x26;&#x26;</code>s. Wrapping reduces depth.</li>
+<li><strong>11 let bindings per function.</strong> A function with 12 lets fails to compile.</li>
+</ul>
+<p>These were verified in production by deliberately building rulesets that crossed each threshold by one. The linter encodes the exact values; you get a clear error when you approach or hit them.</p>
+<h2 id="the-hard-limit">The hard limit</h2>
+<p>Beyond those three caps, every rule evaluation runs against a runtime budget. If the budget is exhausted, the engine denies the request with no diagnostic. The request looks identical to one your <code>allow</code> rule rejected. The exhaustion is silent, and silent failures are the worst kind to debug.</p>
+<p>The budget is not a simple “you can evaluate N expressions” rule. Empirically:</p>
+<ul>
+<li><strong>One function call with 98 expressions</strong> passes reliably (5/5 in our production tests).</li>
+<li><strong>Two function calls with 120 total expressions</strong> passes reliably (5/5).</li>
+<li><strong>Two function calls with 130 total</strong> is <strong>flaky</strong> (2/5 pass).</li>
+<li><strong>Three function calls with 60 total expressions</strong> is <strong>flaky</strong> (2/5 pass).</li>
+<li><strong>Three function calls with 90 total</strong> is mostly stable (4/5).</li>
+</ul>
+<p>The pattern: function-call overhead dominates. Each call eats a non-trivial chunk of the budget. Three thin calls can fail where one fat call would succeed.</p>
+<p>Reverse-engineering: <code>available = base − (call_count × call_overhead)</code>. We don’t know <code>base</code> or <code>call_overhead</code> exactly. Firestore’s evaluation has a non-deterministic flaky zone where the same ruleset will sometimes pass and sometimes fail. The linter’s thresholds are deliberately conservative inside the flaky zone:</p>
+<div class="table-scroll">
+<table><thead><tr><th>Function calls in rule</th><th>Warn at</th><th>Error at</th></tr></thead><tbody><tr><td>1 or 2</td><td>100 expressions</td><td>120</td></tr><tr><td>3</td><td>60</td><td>90</td></tr><tr><td>4+</td><td>40</td><td>60</td></tr></tbody></table></div>
+<p>These over-flag. Some rules in the flaky zone work in practice. The alternative is under-flagging and shipping rules that work in dev and fail under load.</p>
+<h2 id="shared-gates">Shared gates</h2>
+<p>Even with a single rule sitting comfortably inside its budget, two rules in the same match block can collectively blow it. This is the “shared gate” problem, and the linter’s <code>SHARED_GATE</code> warning exists because it took an entire weekend of chess debugging to figure out.</p>
+<p>The scenario: two <code>allow update</code> rules whose conditions both start with the same first expression, say <code>request.auth.uid == resource.data.host</code>. The engine evaluates each rule against the request. Even though only one rule actually applies, the prefix evaluation happens in both. If each rule’s body is near the budget on its own, their combined evaluation crosses the line.</p>
+<p>The fix is to give each rule a unique first expression, a discriminator. Instead of:</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">allow</span><span style="color:#61AFEF"> update</span><span style="color:#ABB2BF">: </span><span style="color:#C678DD">if</span><span style="color:#E5C07B"> request</span><span style="color:#ABB2BF">.auth.uid == </span><span style="color:#E5C07B">resource</span><span style="color:#ABB2BF">.data.host &#x26;&#x26; validBigCheckA();</span></span>
+<span class="line"><span style="color:#C678DD">allow</span><span style="color:#61AFEF"> update</span><span style="color:#ABB2BF">: </span><span style="color:#C678DD">if</span><span style="color:#E5C07B"> request</span><span style="color:#ABB2BF">.auth.uid == </span><span style="color:#E5C07B">resource</span><span style="color:#ABB2BF">.data.host &#x26;&#x26; validBigCheckB();</span></span></code></pre>
+<p>route on something distinct:</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">allow</span><span style="color:#61AFEF"> update</span><span style="color:#ABB2BF">: </span><span style="color:#C678DD">if</span><span style="color:#E5C07B"> request</span><span style="color:#ABB2BF">.</span><span style="color:#E5C07B">resource</span><span style="color:#ABB2BF">.data.moveType == </span><span style="color:#98C379">'A'</span><span style="color:#ABB2BF"> &#x26;&#x26; validBigCheckA();</span></span>
+<span class="line"><span style="color:#C678DD">allow</span><span style="color:#61AFEF"> update</span><span style="color:#ABB2BF">: </span><span style="color:#C678DD">if</span><span style="color:#E5C07B"> request</span><span style="color:#ABB2BF">.</span><span style="color:#E5C07B">resource</span><span style="color:#ABB2BF">.data.moveType == </span><span style="color:#98C379">'B'</span><span style="color:#ABB2BF"> &#x26;&#x26; validBigCheckB();</span></span></code></pre>
+<p>Now each rule short-circuits before its heavy body runs, and the engine doesn’t end up evaluating both bodies in parallel.</p>
+<p>The linter detects <code>SHARED_GATE</code> by computing a structural fingerprint of every rule’s first expression and grouping by fingerprint. Two or more rules with the same fingerprint produce a warning.</p>
+<h2 id="get-call-costs">Get-call costs</h2>
+<p>A separate hard limit applies to document reads from rules (<code>get(...)</code> and <code>exists(...)</code>): 10 per rule. The linter’s <code>GET_COUNT</code> rule warns at 5 and errors at 10. Firestore caches same-path calls within a single rule evaluation, but only for the same path: <code>get(users/$(uid))</code> and <code>get(users/$(otherUid))</code> are two reads, not one.</p>
+<p><code>GET_DUPLICATION</code> catches a related agent failure mode: a helper function that internally calls <code>get()</code>, invoked multiple times from the same rule. The agent thinks it’s calling a tidy abstraction; the engine sees N reads. The fix is to wrap the calls in a function that caches via a <code>let</code>.</p>
+<h2 id="why-the-linter-sometimes-blocks-the-deploy">Why the linter sometimes blocks the deploy</h2>
+<p>Most lint warnings are advisory. A handful are not: <code>SOURCE_SIZE</code>, <code>CHAIN_DEPTH</code> (above the band), <code>LET_LIMIT</code>, <code>GET_COUNT</code> (above 10), <code>PERMISSIVE_RULE</code>, <code>RECURSIVE_WILDCARD_OPEN</code>, <code>HALLUCINATED_METHOD</code>, <code>INVALID_OPERATOR</code>. Treat <code>severity: 'error'</code> as a hard gate before <code>firebase deploy</code>. The choice is deliberate: these are the categories where the cost of shipping the bad rule is high (a deploy that fails compilation; a publicly-readable database) and the cost of demanding a fix is low (the linter tells you exactly what’s wrong).</p>
+<p><code>RULES_WEAKENED</code> is <code>warning</code>, not <code>error</code>. There are legitimate reasons to remove a predicate: a refactor, a dedupe, an intentional broadening. The signal is “review this”, not “block the deploy”.</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-exact-limits">The exact limits</a> </li><li data-depth="2"> <a href="#the-hard-limit">The hard limit</a> </li><li data-depth="2"> <a href="#shared-gates">Shared gates</a> </li><li data-depth="2"> <a href="#get-call-costs">Get-call costs</a> </li><li data-depth="2"> <a href="#why-the-linter-sometimes-blocks-the-deploy">Why the linter sometimes blocks the deploy</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>