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-reference-test-case-schema/index.html ADDED Viewed

@@ -0,0 +1,94 @@
+<!DOCTYPE html><html lang="en"> <head><meta charset="UTF-8"><meta name="viewport" content="width=device-width, initial-scale=1.0"><title>FirestoreCase schema · 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>Reference</span> </li><li> <span class="docs-breadcrumbs-sep" aria-hidden="true">/</span> <span aria-current="page">FirestoreCase schema</span> </li> </ol> </nav>  <article class="prose">  <h1 id="firestorecase-schema"><code>FirestoreCase</code> schema</h1>
+<p><code>FirestoreCase</code> is the unit of work for <code>firestoreRules(source).simulate(cases)</code> and <code>firestoreRules(source).explain(oneCase)</code>, both from <code>pyric/rules</code>. It’s structurally identical to the engine-internal <code>TestCase</code> type (<code>pyric/rules/internal</code>), re-exported under the public name so callers never need to reach into the engine seam. A Zod schema for the same shape, <code>TestCaseSchema</code>, is available on <code>pyric/rules/internal</code> for callers that want runtime validation; it is not part of the public contract.</p>
+<h2 id="required-fields">Required fields</h2>
+<h3 id="description-string"><code>description: string</code></h3>
+<p>Human-readable label. Echoed back in each <code>TestResult.description</code> so failures point at a specific case.</p>
+<h3 id="expectation-allow--deny"><code>expectation: 'ALLOW' | 'DENY'</code></h3>
+<p>What the rule should decide for this request. On the resulting <code>CaseResult</code>, <code>passed</code> is <code>true</code> when the simulator’s <code>decision</code> matches; <code>false</code> when it differs; <code>unsupported</code> is <code>true</code> when the simulator abstained.</p>
+<h3 id="method-get--list--create--update--delete"><code>method: 'get' | 'list' | 'create' | 'update' | 'delete'</code></h3>
+<p>The Firestore method under test. Note that the rules engine also recognises the coarser <code>read</code> (= <code>get</code> ∪ <code>list</code>) and <code>write</code> (= <code>create</code> ∪ <code>update</code> ∪ <code>delete</code>) groupings in <code>allow</code> statements. Those resolve automatically.</p>
+<h3 id="path-string"><code>path: string</code></h3>
+<p>Document path relative to the database, e.g. <code>'users/alice'</code> or <code>'admin/config/secrets/api-keys'</code>. Leading slashes are tolerated.</p>
+<p>For <code>method: 'list'</code> the path may also be a COLLECTION path (e.g. <code>'menuItems'</code>): the simulator evaluates the document-level match block with the document wildcard hypothetical and <code>resource</code> undefined, matching the emulator’s query semantics. A note on the result records when this widening applied. Doc-style list paths keep working unchanged.</p>
+<h2 id="optional-fields">Optional fields</h2>
+<h3 id="auth--uid-string-token-recordstring-unknown---null"><code>auth: { uid: string; token?: Record&#x3C;string, unknown> } | null</code></h3>
+<p>Auth context. Omit (or set <code>null</code>) for an unauthenticated request, and <code>request.auth</code> will be <code>null</code>. <code>token</code> populates <code>request.auth.token</code>, which is where custom claims land.</p>
+<h3 id="data-recordstring-unknown"><code>data: Record&#x3C;string, unknown></code></h3>
+<p>The proposed write payload. Becomes <code>request.resource.data</code> on write operations. Ignored on <code>get</code> and <code>list</code> (read requests have no proposed write).</p>
+<h3 id="resource-recordstring-unknown"><code>resource: Record&#x3C;string, unknown></code></h3>
+<p>The existing document, if any. Becomes <code>resource.data</code> for the rule evaluation. Omit for <code>create</code> cases against an empty path, set for <code>update</code>/<code>delete</code> cases against an existing document, and set for <code>get</code> to model the document being read.</p>
+<h3 id="functionmocks-functionmock"><code>functionMocks: FunctionMock[]</code></h3>
+<p>Mock results for <code>get()</code> and <code>exists()</code> calls the rule makes:</p>
+<pre class="astro-code one-dark-pro" style="background-color:#282c34;color:#abb2bf; overflow-x: auto;" tabindex="0" data-language="ts"><code><span class="line"><span style="color:#C678DD">interface</span><span style="color:#E5C07B"> FunctionMock</span><span style="color:#ABB2BF"> {</span></span>
+<span class="line"><span style="color:#E06C75">  function</span><span style="color:#ABB2BF">: </span><span style="color:#98C379">'get'</span><span style="color:#ABB2BF"> | </span><span style="color:#98C379">'exists'</span><span style="color:#ABB2BF">;</span></span>
+<span class="line"><span style="color:#E06C75">  path</span><span style="color:#ABB2BF">: </span><span style="color:#E5C07B">string</span><span style="color:#ABB2BF">;                                       </span><span style="color:#7F848E;font-style:italic">// relative to db</span></span>
+<span class="line"><span style="color:#E06C75">  result</span><span style="color:#ABB2BF">: </span><span style="color:#E5C07B">Record</span><span style="color:#ABB2BF">&#x3C;</span><span style="color:#E5C07B">string</span><span style="color:#ABB2BF">, </span><span style="color:#E5C07B">unknown</span><span style="color:#ABB2BF">> | </span><span style="color:#E5C07B">boolean</span><span style="color:#ABB2BF">;          </span><span style="color:#7F848E;font-style:italic">// doc data for get; boolean for exists</span></span>
+<span class="line"><span style="color:#ABB2BF">}</span></span></code></pre>
+<p>For <code>get</code>, supply the document data. For <code>exists</code>, supply <code>true</code> (the mock will produce a document) or <code>false</code> (no result, the rule will see absence). Paths are relative. The simulator handles the <code>/databases/(default)/documents/</code> prefix.</p>
+<h3 id="query-listquery"><code>query: ListQuery</code></h3>
+<p>Only honoured for <code>method: 'list'</code>. Populates <code>request.query</code>:</p>
+<pre class="astro-code one-dark-pro" style="background-color:#282c34;color:#abb2bf; overflow-x: auto;" tabindex="0" data-language="ts"><code><span class="line"><span style="color:#C678DD">interface</span><span style="color:#E5C07B"> ListQuery</span><span style="color:#ABB2BF"> {</span></span>
+<span class="line"><span style="color:#E06C75">  limit</span><span style="color:#C678DD">?</span><span style="color:#ABB2BF">: </span><span style="color:#E5C07B">number</span><span style="color:#ABB2BF">;</span></span>
+<span class="line"><span style="color:#E06C75">  offset</span><span style="color:#C678DD">?</span><span style="color:#ABB2BF">: </span><span style="color:#E5C07B">number</span><span style="color:#ABB2BF">;</span></span>
+<span class="line"><span style="color:#E06C75">  orderBy</span><span style="color:#C678DD">?</span><span style="color:#ABB2BF">: </span><span style="color:#E5C07B">string</span><span style="color:#ABB2BF">;</span></span>
+<span class="line"><span style="color:#ABB2BF">}</span></span></code></pre>
+<p>Unset fields read as <code>null</code> from rules. If your rule reads <code>request.query.limit</code>, set it. Otherwise <code>null &#x3C; 100</code> evaluates to <code>false</code> and the rule silently denies.</p>
+<h3 id="requesttime-string"><code>requestTime: string</code></h3>
+<p>ISO-8601 timestamp used as <code>request.time</code>. Defaults to the wallclock at simulation time. Pin this whenever your rule reads <code>request.time</code> to keep tests deterministic. The lint rule <code>REQUEST_TIME_NOT_PINNED</code> surfaces unpinned cases, but only through the engine-internal <code>lintFirestoreRules(source, { testCases })</code> on <code>pyric/rules/internal</code>; the public <code>lint(source)</code> and <code>firestoreRules(source).lint()</code> don’t take a <code>testCases</code> option. See <a href="../pyric-rules-how-to-pin-request-time/">Pin <code>request.time</code> for deterministic tests</a>.</p>
+<h3 id="writemode"><code>writeMode</code></h3>
+<p>Explicit write-mode discriminator. When set, the simulator runs <code>projectAfterState(writeMode, resource, data)</code> to derive both <code>request.resource.data</code> and the value <code>getAfter(path)</code> returns. When unset, the simulator falls back to “<code>tc.data</code> IS the after-state”, which is correct for shallow <code>create</code> but wrong for nested-map updates.</p>
+<pre class="astro-code one-dark-pro" style="background-color:#282c34;color:#abb2bf; overflow-x: auto;" tabindex="0" data-language="ts"><code><span class="line"><span style="color:#C678DD">type</span><span style="color:#E5C07B"> WriteMode</span><span style="color:#56B6C2"> =</span></span>
+<span class="line"><span style="color:#ABB2BF">  | { </span><span style="color:#E06C75">kind</span><span style="color:#ABB2BF">: </span><span style="color:#98C379">'create'</span><span style="color:#ABB2BF"> }</span></span>
+<span class="line"><span style="color:#ABB2BF">  | { </span><span style="color:#E06C75">kind</span><span style="color:#ABB2BF">: </span><span style="color:#98C379">'set'</span><span style="color:#ABB2BF">; </span><span style="color:#E06C75">merge</span><span style="color:#ABB2BF">: </span><span style="color:#E5C07B">boolean</span><span style="color:#ABB2BF"> }</span></span>
+<span class="line"><span style="color:#ABB2BF">  | { </span><span style="color:#E06C75">kind</span><span style="color:#ABB2BF">: </span><span style="color:#98C379">'update'</span><span style="color:#ABB2BF"> }</span></span>
+<span class="line"><span style="color:#ABB2BF">  | { </span><span style="color:#E06C75">kind</span><span style="color:#ABB2BF">: </span><span style="color:#98C379">'delete'</span><span style="color:#ABB2BF"> };</span></span></code></pre>
+<div class="table-scroll">
+<table><thead><tr><th>Mode</th><th>After-state</th></tr></thead><tbody><tr><td><code>{ kind: 'create' }</code></td><td><code>data</code> (asserts the doc did not exist)</td></tr><tr><td><code>{ kind: 'set', merge: false }</code></td><td><code>data</code> (full replace)</td></tr><tr><td><code>{ kind: 'set', merge: true }</code></td><td>recursive merge of <code>resource</code> and <code>data</code></td></tr><tr><td><code>{ kind: 'update' }</code></td><td>top-level keys in <code>data</code> replace those in <code>resource</code>; dot-paths patch nested maps</td></tr><tr><td><code>{ kind: 'delete' }</code></td><td><code>null</code></td></tr></tbody></table></div>
+<h2 id="server-timestamp-sentinels-in-data">Server-timestamp sentinels in <code>data</code></h2>
+<p>When your write payload contains a server-timestamp sentinel (exactly <code>{ __type: 'serverTimestamp' }</code>), the simulator resolves every occurrence to the same <code>Timestamp</code> instance (matching <code>request.time</code>). Use the <code>serverTimestamp()</code> value helper for clarity:</p>
+<pre class="astro-code one-dark-pro" style="background-color:#282c34;color:#abb2bf; overflow-x: auto;" tabindex="0" data-language="ts"><code><span class="line"><span style="color:#C678DD">import</span><span style="color:#ABB2BF"> { </span><span style="color:#E06C75">serverTimestamp</span><span style="color:#ABB2BF">, </span><span style="color:#C678DD">type</span><span style="color:#E06C75"> FirestoreCase</span><span style="color:#ABB2BF"> } </span><span style="color:#C678DD">from</span><span style="color:#98C379"> 'pyric/rules'</span><span style="color:#ABB2BF">;</span></span>
+<span class="line"></span>
+<span class="line"><span style="color:#C678DD">const</span><span style="color:#E5C07B"> tc</span><span style="color:#ABB2BF">: </span><span style="color:#E5C07B">FirestoreCase</span><span style="color:#56B6C2"> =</span><span style="color:#ABB2BF"> {</span></span>
+<span class="line"><span style="color:#E06C75">  description</span><span style="color:#ABB2BF">: </span><span style="color:#98C379">'create stamps createdAt = request.time'</span><span style="color:#ABB2BF">,</span></span>
+<span class="line"><span style="color:#E06C75">  expectation</span><span style="color:#ABB2BF">: </span><span style="color:#98C379">'ALLOW'</span><span style="color:#ABB2BF">,</span></span>
+<span class="line"><span style="color:#E06C75">  method</span><span style="color:#ABB2BF">: </span><span style="color:#98C379">'create'</span><span style="color:#ABB2BF">,</span></span>
+<span class="line"><span style="color:#E06C75">  path</span><span style="color:#ABB2BF">: </span><span style="color:#98C379">'notes/n1'</span><span style="color:#ABB2BF">,</span></span>
+<span class="line"><span style="color:#E06C75">  auth</span><span style="color:#ABB2BF">: { </span><span style="color:#E06C75">uid</span><span style="color:#ABB2BF">: </span><span style="color:#98C379">'alice'</span><span style="color:#ABB2BF"> },</span></span>
+<span class="line"><span style="color:#E06C75">  data</span><span style="color:#ABB2BF">: { </span><span style="color:#E06C75">ownerId</span><span style="color:#ABB2BF">: </span><span style="color:#98C379">'alice'</span><span style="color:#ABB2BF">, </span><span style="color:#E06C75">createdAt</span><span style="color:#ABB2BF">: </span><span style="color:#61AFEF">serverTimestamp</span><span style="color:#ABB2BF">() },</span></span>
+<span class="line"><span style="color:#E06C75">  requestTime</span><span style="color:#ABB2BF">: </span><span style="color:#98C379">'2026-04-15T12:00:00Z'</span><span style="color:#ABB2BF">,</span></span>
+<span class="line"><span style="color:#ABB2BF">};</span></span></code></pre>
+<p>The single-instance invariant matters because <code>data.createdAt == request.time</code> succeeds via field-compare on the <code>Timestamp</code> wrapper.</p>
+<h2 id="validation">Validation</h2>
+<p><code>TestCaseSchema</code>, the Zod schema behind <code>FirestoreCase</code>, lives on <code>pyric/rules/internal</code> (an internal, unstable surface):</p>
+<pre class="astro-code one-dark-pro" style="background-color:#282c34;color:#abb2bf; overflow-x: auto;" tabindex="0" data-language="ts"><code><span class="line"><span style="color:#C678DD">import</span><span style="color:#ABB2BF"> { </span><span style="color:#E06C75">TestCaseSchema</span><span style="color:#ABB2BF"> } </span><span style="color:#C678DD">from</span><span style="color:#98C379"> 'pyric/rules/internal'</span><span style="color:#ABB2BF">;</span></span>
+<span class="line"></span>
+<span class="line"><span style="color:#C678DD">const</span><span style="color:#E5C07B"> parsed</span><span style="color:#56B6C2"> =</span><span style="color:#E5C07B"> TestCaseSchema</span><span style="color:#ABB2BF">.</span><span style="color:#61AFEF">parse</span><span style="color:#ABB2BF">(</span><span style="color:#E06C75">input</span><span style="color:#ABB2BF">);  </span><span style="color:#7F848E;font-style:italic">// throws on schema mismatch</span></span></code></pre>
+<p><code>TestCaseSchema</code> is a Zod schema, so you can also <code>safeParse</code> it or compose it into your own validators.</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="#required-fields">Required fields</a> </li><li data-depth="3"> <a href="#description-string">description: string</a> </li><li data-depth="3"> <a href="#expectation-allow--deny">expectation: &#39;ALLOW&#39; | &#39;DENY&#39;</a> </li><li data-depth="3"> <a href="#method-get--list--create--update--delete">method: &#39;get&#39; | &#39;list&#39; | &#39;create&#39; | &#39;update&#39; | &#39;delete&#39;</a> </li><li data-depth="3"> <a href="#path-string">path: string</a> </li><li data-depth="2"> <a href="#optional-fields">Optional fields</a> </li><li data-depth="3"> <a href="#auth--uid-string-token-recordstring-unknown---null">auth: { uid: string; token?: Record&lt;string, unknown&gt; } | null</a> </li><li data-depth="3"> <a href="#data-recordstring-unknown">data: Record&lt;string, unknown&gt;</a> </li><li data-depth="3"> <a href="#resource-recordstring-unknown">resource: Record&lt;string, unknown&gt;</a> </li><li data-depth="3"> <a href="#functionmocks-functionmock">functionMocks: FunctionMock[]</a> </li><li data-depth="3"> <a href="#query-listquery">query: ListQuery</a> </li><li data-depth="3"> <a href="#requesttime-string">requestTime: string</a> </li><li data-depth="3"> <a href="#writemode">writeMode</a> </li><li data-depth="2"> <a href="#server-timestamp-sentinels-in-data">Server-timestamp sentinels in data</a> </li><li data-depth="2"> <a href="#validation">Validation</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-reference-test-case-schema.md ADDED Viewed

@@ -0,0 +1,121 @@
+# `FirestoreCase` schema
+`FirestoreCase` is the unit of work for `firestoreRules(source).simulate(cases)` and `firestoreRules(source).explain(oneCase)`, both from `pyric/rules`. It's structurally identical to the engine-internal `TestCase` type (`pyric/rules/internal`), re-exported under the public name so callers never need to reach into the engine seam. A Zod schema for the same shape, `TestCaseSchema`, is available on `pyric/rules/internal` for callers that want runtime validation; it is not part of the public contract.
+## Required fields
+### `description: string`
+Human-readable label. Echoed back in each `TestResult.description` so failures point at a specific case.
+### `expectation: 'ALLOW' | 'DENY'`
+What the rule should decide for this request. On the resulting `CaseResult`, `passed` is `true` when the simulator's `decision` matches; `false` when it differs; `unsupported` is `true` when the simulator abstained.
+### `method: 'get' | 'list' | 'create' | 'update' | 'delete'`
+The Firestore method under test. Note that the rules engine also recognises the coarser `read` (= `get` ∪ `list`) and `write` (= `create` ∪ `update` ∪ `delete`) groupings in `allow` statements. Those resolve automatically.
+### `path: string`
+Document path relative to the database, e.g. `'users/alice'` or `'admin/config/secrets/api-keys'`. Leading slashes are tolerated.
+For `method: 'list'` the path may also be a COLLECTION path (e.g. `'menuItems'`): the simulator evaluates the document-level match block with the document wildcard hypothetical and `resource` undefined, matching the emulator's query semantics. A note on the result records when this widening applied. Doc-style list paths keep working unchanged.
+## Optional fields
+### `auth: { uid: string; token?: Record<string, unknown> } | null`
+Auth context. Omit (or set `null`) for an unauthenticated request, and `request.auth` will be `null`. `token` populates `request.auth.token`, which is where custom claims land.
+### `data: Record<string, unknown>`
+The proposed write payload. Becomes `request.resource.data` on write operations. Ignored on `get` and `list` (read requests have no proposed write).
+### `resource: Record<string, unknown>`
+The existing document, if any. Becomes `resource.data` for the rule evaluation. Omit for `create` cases against an empty path, set for `update`/`delete` cases against an existing document, and set for `get` to model the document being read.
+### `functionMocks: FunctionMock[]`
+Mock results for `get()` and `exists()` calls the rule makes:
+```ts
+interface FunctionMock {
+  function: 'get' | 'exists';
+  path: string;                                       // relative to db
+  result: Record<string, unknown> | boolean;          // doc data for get; boolean for exists
+}
+```
+For `get`, supply the document data. For `exists`, supply `true` (the mock will produce a document) or `false` (no result, the rule will see absence). Paths are relative. The simulator handles the `/databases/(default)/documents/` prefix.
+### `query: ListQuery`
+Only honoured for `method: 'list'`. Populates `request.query`:
+```ts
+interface ListQuery {
+  limit?: number;
+  offset?: number;
+  orderBy?: string;
+}
+```
+Unset fields read as `null` from rules. If your rule reads `request.query.limit`, set it. Otherwise `null < 100` evaluates to `false` and the rule silently denies.
+### `requestTime: string`
+ISO-8601 timestamp used as `request.time`. Defaults to the wallclock at simulation time. Pin this whenever your rule reads `request.time` to keep tests deterministic. The lint rule `REQUEST_TIME_NOT_PINNED` surfaces unpinned cases, but only through the engine-internal `lintFirestoreRules(source, { testCases })` on `pyric/rules/internal`; the public `lint(source)` and `firestoreRules(source).lint()` don't take a `testCases` option. See [Pin `request.time` for deterministic tests](../pyric-rules-how-to-pin-request-time/).
+### `writeMode`
+Explicit write-mode discriminator. When set, the simulator runs `projectAfterState(writeMode, resource, data)` to derive both `request.resource.data` and the value `getAfter(path)` returns. When unset, the simulator falls back to "`tc.data` IS the after-state", which is correct for shallow `create` but wrong for nested-map updates.
+```ts
+type WriteMode =
+  | { kind: 'create' }
+  | { kind: 'set'; merge: boolean }
+  | { kind: 'update' }
+  | { kind: 'delete' };
+```
+| Mode | After-state |
+|---|---|
+| `{ kind: 'create' }` | `data` (asserts the doc did not exist) |
+| `{ kind: 'set', merge: false }` | `data` (full replace) |
+| `{ kind: 'set', merge: true }` | recursive merge of `resource` and `data` |
+| `{ kind: 'update' }` | top-level keys in `data` replace those in `resource`; dot-paths patch nested maps |
+| `{ kind: 'delete' }` | `null` |
+## Server-timestamp sentinels in `data`
+When your write payload contains a server-timestamp sentinel (exactly `{ __type: 'serverTimestamp' }`), the simulator resolves every occurrence to the same `Timestamp` instance (matching `request.time`). Use the `serverTimestamp()` value helper for clarity:
+```ts
+import { serverTimestamp, type FirestoreCase } from 'pyric/rules';
+const tc: FirestoreCase = {
+  description: 'create stamps createdAt = request.time',
+  expectation: 'ALLOW',
+  method: 'create',
+  path: 'notes/n1',
+  auth: { uid: 'alice' },
+  data: { ownerId: 'alice', createdAt: serverTimestamp() },
+  requestTime: '2026-04-15T12:00:00Z',
+};
+```
+The single-instance invariant matters because `data.createdAt == request.time` succeeds via field-compare on the `Timestamp` wrapper.
+## Validation
+`TestCaseSchema`, the Zod schema behind `FirestoreCase`, lives on `pyric/rules/internal` (an internal, unstable surface):
+```ts
+import { TestCaseSchema } from 'pyric/rules/internal';
+const parsed = TestCaseSchema.parse(input);  // throws on schema mismatch
+```
+`TestCaseSchema` is a Zod schema, so you can also `safeParse` it or compose it into your own validators.

package/dist/serve/docs-ui/docs/pyric-rules-reference-validator-findings/index.html ADDED Viewed

@@ -0,0 +1,87 @@
+<!DOCTYPE html><html lang="en"> <head><meta charset="UTF-8"><meta name="viewport" content="width=device-width, initial-scale=1.0"><title>Validator findings · 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>Reference</span> </li><li> <span class="docs-breadcrumbs-sep" aria-hidden="true">/</span> <span aria-current="page">Validator findings</span> </li> </ol> </nav>  <article class="prose">  <h1 id="validator-findings">Validator findings</h1>
+<p>The validator runs as part of <code>lint(source)</code> and <code>firestoreRules(source).lint()</code>, both from <code>pyric/rules</code>. Each finding surfaces as a <code>RuleIssue</code> with <code>origin: 'validate'</code>. The validator’s own internal shape, <code>ValidationFinding</code>, still exists on <code>pyric/rules/internal</code> (via <code>validateFirestoreRules(ast)</code>) for callers that need the raw four-level severity scale:</p>
+<pre class="astro-code one-dark-pro" style="background-color:#282c34;color:#abb2bf; overflow-x: auto;" tabindex="0" data-language="ts"><code><span class="line"><span style="color:#C678DD">interface</span><span style="color:#E5C07B"> ValidationFinding</span><span style="color:#ABB2BF"> {</span></span>
+<span class="line"><span style="color:#E06C75">  code</span><span style="color:#ABB2BF">: </span><span style="color:#E5C07B">string</span><span style="color:#ABB2BF">;</span></span>
+<span class="line"><span style="color:#E06C75">  severity</span><span style="color:#ABB2BF">: </span><span style="color:#98C379">'critical'</span><span style="color:#ABB2BF"> | </span><span style="color:#98C379">'high'</span><span style="color:#ABB2BF"> | </span><span style="color:#98C379">'medium'</span><span style="color:#ABB2BF"> | </span><span style="color:#98C379">'low'</span><span style="color:#ABB2BF">;</span></span>
+<span class="line"><span style="color:#E06C75">  path</span><span style="color:#ABB2BF">: </span><span style="color:#E5C07B">string</span><span style="color:#ABB2BF">;          </span><span style="color:#7F848E;font-style:italic">// match path, or '/' for whole-file findings</span></span>
+<span class="line"><span style="color:#E06C75">  operation</span><span style="color:#C678DD">?</span><span style="color:#ABB2BF">: </span><span style="color:#E5C07B">string</span><span style="color:#ABB2BF">;    </span><span style="color:#7F848E;font-style:italic">// 'read', 'write', 'create, update', etc.</span></span>
+<span class="line"><span style="color:#E06C75">  message</span><span style="color:#ABB2BF">: </span><span style="color:#E5C07B">string</span><span style="color:#ABB2BF">;</span></span>
+<span class="line"><span style="color:#ABB2BF">}</span></span></code></pre>
+<p>On the public <code>RuleIssue</code>, <code>critical</code> and <code>high</code> fold to <code>'error'</code>, <code>medium</code> folds to <code>'warning'</code>, and <code>low</code> folds to <code>'info'</code>.</p>
+<p>Findings are grouped by code family:</p>
+<ul>
+<li><code>SEC-*</code>: security</li>
+<li><code>SEM-*</code>: semantics (rules that compile but evaluate incorrectly)</li>
+<li><code>QUA-*</code>: quality</li>
+<li><code>STR-*</code>: structure</li>
+</ul>
+<p>The validator is distinct from the linter: it reports issues a human reviewer would flag, regardless of compilation or runtime budget. Run both for full coverage.</p>
+<h2 id="security-sec">Security (<code>SEC</code>)</h2>
+<h3 id="sec-1-public-write-critical"><code>SEC-1</code>: Public write (<code>critical</code>)</h3>
+<p>A write rule (<code>write</code>, <code>create</code>, <code>update</code>, or <code>delete</code>) with <code>if true</code>. Anyone can write without authentication.</p>
+<h3 id="sec-2-public-read-at-recursive-wildcard-critical"><code>SEC-2</code>: Public read at recursive wildcard (<code>critical</code>)</h3>
+<p>A read rule with <code>if true</code> whose match path uses <code>{document=**}</code>. Every document under the prefix is readable by anyone.</p>
+<h3 id="sec-3-write-without-auth-check-high"><code>SEC-3</code>: Write without auth check (<code>high</code>)</h3>
+<p>A write rule whose condition does not reference <code>request.auth</code> (directly or through any called function). Catches rules that gate on data shape only.</p>
+<h3 id="sec-4-no-default-deny-medium"><code>SEC-4</code>: No default deny (<code>medium</code>)</h3>
+<p>The ruleset lacks a default-deny block (<code>match /{document=**} { allow read, write: if false; }</code>). Without it, unmatched paths fall through to Firestore’s defaults, which can surprise.</p>
+<h3 id="sec-5-recursive-wildcard-with-non-deny-rule-high"><code>SEC-5</code>: Recursive wildcard with non-deny rule (<code>high</code>)</h3>
+<p>A <code>{document=**}</code> match block has an allow rule that isn’t trivially <code>if false</code>. Because recursive matches override specific matches, the rule effectively governs every document under the prefix.</p>
+<h3 id="sec-6-write-without-data-validation-high"><code>SEC-6</code>: Write without data validation (<code>high</code>)</h3>
+<p>A <code>create</code> or <code>update</code> rule that does not reference <code>request.resource.data</code> (directly or transitively). Any payload shape is accepted.</p>
+<h2 id="semantics-sem">Semantics (<code>SEM</code>)</h2>
+<h3 id="sem-1-requestresourcedata-on-a-read-rule-high"><code>SEM-1</code>: <code>request.resource.data</code> on a read rule (<code>high</code>)</h3>
+<p>Read rules don’t carry a <code>request.resource</code>. The field is unset, so the predicate silently denies.</p>
+<h3 id="sem-2-resourcedata-on-a-create-rule-high"><code>SEM-2</code>: <code>resource.data</code> on a create rule (<code>high</code>)</h3>
+<p>The document doesn’t exist yet on <code>create</code>, so <code>resource.data</code> is null. Use <code>request.resource.data</code> instead.</p>
+<h3 id="sem-3-more-than-10-document-reads-high"><code>SEM-3</code>: More than 10 document reads (<code>high</code>)</h3>
+<p><code>get()</code> / <code>exists()</code> count exceeds the documented Firestore limit of 10 per rule. Same threshold as the linter’s <code>GET_COUNT</code> error band.</p>
+<h3 id="sem-4-call-to-undefined-function-high"><code>SEM-4</code>: Call to undefined function (<code>high</code>)</h3>
+<p>A function call references a name that isn’t defined in the current scope or any parent scope.</p>
+<h2 id="quality-qua">Quality (<code>QUA</code>)</h2>
+<h3 id="qua-1-hardcoded-true-medium-for-writes-low-for-reads"><code>QUA-1</code>: Hardcoded <code>true</code> (<code>medium</code> for writes, <code>low</code> for reads)</h3>
+<p>Same shape as the linter’s <code>PERMISSIVE_RULE</code>. Reported here at lower severity than the linter blocks the deploy at, because the validator is advisory.</p>
+<h3 id="qua-2-empty-match-block-low"><code>QUA-2</code>: Empty match block (<code>low</code>)</h3>
+<p>A match block with no allow rules, no children, and no functions. Dead code.</p>
+<h3 id="qua-3-duplicate-function-names-medium"><code>QUA-3</code>: Duplicate function names (<code>medium</code>)</h3>
+<p>Two functions share a name within the same scope. Behaviour depends on declaration order, confusing at best.</p>
+<h3 id="qua-4-unused-function-low"><code>QUA-4</code>: Unused function (<code>low</code>)</h3>
+<p>A function is defined but never called.</p>
+<h3 id="qua-5-deep-condition-low"><code>QUA-5</code>: Deep condition (<code>low</code>)</h3>
+<p>A single rule’s predicate exceeds an internal depth threshold. Consider extracting helpers.</p>
+<h2 id="structure-str">Structure (<code>STR</code>)</h2>
+<h3 id="str-1-match-with-no-wildcard-low"><code>STR-1</code>: Match with no wildcard (<code>low</code>)</h3>
+<p>A match path with no <code>{wildcard}</code> segment matches exactly one document. Usually a sign of a typo or a missing wildcard segment.</p>
+<h3 id="str-2-nested-match-without-allows-medium"><code>STR-2</code>: Nested match without allows (<code>medium</code>)</h3>
+<p>A parent block with no allow rules but with nested matches. Often a sign that the parent intended to lock the collection but ended up doing nothing.</p>
+<h3 id="str-3-overlapping-sibling-paths-low"><code>STR-3</code>: Overlapping sibling paths (<code>low</code>)</h3>
+<p>Two sibling match blocks whose paths could match the same document. The more permissive rule wins, which may not be intended.</p>
+<h2 id="severity-model">Severity model</h2>
+<p>The validator’s <code>severity</code> scale (<code>critical</code>, <code>high</code>, <code>medium</code>, <code>low</code>) is more granular than the linter’s (<code>error</code>, <code>warning</code>). The values map as follows for tooling that treats them as block / advisory:</p>
+<div class="table-scroll">
+<table><thead><tr><th>Severity</th><th>Recommended action</th></tr></thead><tbody><tr><td><code>critical</code></td><td>Block deploy.</td></tr><tr><td><code>high</code></td><td>Block by default; allow override with explicit human ack.</td></tr><tr><td><code>medium</code></td><td>Surface in review; do not block.</td></tr><tr><td><code>low</code></td><td>Surface in review; do not block.</td></tr></tbody></table></div>
+<p>The mapping is a convention, not enforced. Callers compose their own gates.</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="#security-sec">Security (SEC)</a> </li><li data-depth="3"> <a href="#sec-1-public-write-critical">SEC-1: Public write (critical)</a> </li><li data-depth="3"> <a href="#sec-2-public-read-at-recursive-wildcard-critical">SEC-2: Public read at recursive wildcard (critical)</a> </li><li data-depth="3"> <a href="#sec-3-write-without-auth-check-high">SEC-3: Write without auth check (high)</a> </li><li data-depth="3"> <a href="#sec-4-no-default-deny-medium">SEC-4: No default deny (medium)</a> </li><li data-depth="3"> <a href="#sec-5-recursive-wildcard-with-non-deny-rule-high">SEC-5: Recursive wildcard with non-deny rule (high)</a> </li><li data-depth="3"> <a href="#sec-6-write-without-data-validation-high">SEC-6: Write without data validation (high)</a> </li><li data-depth="2"> <a href="#semantics-sem">Semantics (SEM)</a> </li><li data-depth="3"> <a href="#sem-1-requestresourcedata-on-a-read-rule-high">SEM-1: request.resource.data on a read rule (high)</a> </li><li data-depth="3"> <a href="#sem-2-resourcedata-on-a-create-rule-high">SEM-2: resource.data on a create rule (high)</a> </li><li data-depth="3"> <a href="#sem-3-more-than-10-document-reads-high">SEM-3: More than 10 document reads (high)</a> </li><li data-depth="3"> <a href="#sem-4-call-to-undefined-function-high">SEM-4: Call to undefined function (high)</a> </li><li data-depth="2"> <a href="#quality-qua">Quality (QUA)</a> </li><li data-depth="3"> <a href="#qua-1-hardcoded-true-medium-for-writes-low-for-reads">QUA-1: Hardcoded true (medium for writes, low for reads)</a> </li><li data-depth="3"> <a href="#qua-2-empty-match-block-low">QUA-2: Empty match block (low)</a> </li><li data-depth="3"> <a href="#qua-3-duplicate-function-names-medium">QUA-3: Duplicate function names (medium)</a> </li><li data-depth="3"> <a href="#qua-4-unused-function-low">QUA-4: Unused function (low)</a> </li><li data-depth="3"> <a href="#qua-5-deep-condition-low">QUA-5: Deep condition (low)</a> </li><li data-depth="2"> <a href="#structure-str">Structure (STR)</a> </li><li data-depth="3"> <a href="#str-1-match-with-no-wildcard-low">STR-1: Match with no wildcard (low)</a> </li><li data-depth="3"> <a href="#str-2-nested-match-without-allows-medium">STR-2: Nested match without allows (medium)</a> </li><li data-depth="3"> <a href="#str-3-overlapping-sibling-paths-low">STR-3: Overlapping sibling paths (low)</a> </li><li data-depth="2"> <a href="#severity-model">Severity model</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-reference-validator-findings.md ADDED Viewed

@@ -0,0 +1,117 @@
+# Validator findings
+The validator runs as part of `lint(source)` and `firestoreRules(source).lint()`, both from `pyric/rules`. Each finding surfaces as a `RuleIssue` with `origin: 'validate'`. The validator's own internal shape, `ValidationFinding`, still exists on `pyric/rules/internal` (via `validateFirestoreRules(ast)`) for callers that need the raw four-level severity scale:
+```ts
+interface ValidationFinding {
+  code: string;
+  severity: 'critical' | 'high' | 'medium' | 'low';
+  path: string;          // match path, or '/' for whole-file findings
+  operation?: string;    // 'read', 'write', 'create, update', etc.
+  message: string;
+}
+```
+On the public `RuleIssue`, `critical` and `high` fold to `'error'`, `medium` folds to `'warning'`, and `low` folds to `'info'`.
+Findings are grouped by code family:
+- `SEC-*`: security
+- `SEM-*`: semantics (rules that compile but evaluate incorrectly)
+- `QUA-*`: quality
+- `STR-*`: structure
+The validator is distinct from the linter: it reports issues a human reviewer would flag, regardless of compilation or runtime budget. Run both for full coverage.
+## Security (`SEC`)
+### `SEC-1`: Public write (`critical`)
+A write rule (`write`, `create`, `update`, or `delete`) with `if true`. Anyone can write without authentication.
+### `SEC-2`: Public read at recursive wildcard (`critical`)
+A read rule with `if true` whose match path uses `{document=**}`. Every document under the prefix is readable by anyone.
+### `SEC-3`: Write without auth check (`high`)
+A write rule whose condition does not reference `request.auth` (directly or through any called function). Catches rules that gate on data shape only.
+### `SEC-4`: No default deny (`medium`)
+The ruleset lacks a default-deny block (`match /{document=**} { allow read, write: if false; }`). Without it, unmatched paths fall through to Firestore's defaults, which can surprise.
+### `SEC-5`: Recursive wildcard with non-deny rule (`high`)
+A `{document=**}` match block has an allow rule that isn't trivially `if false`. Because recursive matches override specific matches, the rule effectively governs every document under the prefix.
+### `SEC-6`: Write without data validation (`high`)
+A `create` or `update` rule that does not reference `request.resource.data` (directly or transitively). Any payload shape is accepted.
+## Semantics (`SEM`)
+### `SEM-1`: `request.resource.data` on a read rule (`high`)
+Read rules don't carry a `request.resource`. The field is unset, so the predicate silently denies.
+### `SEM-2`: `resource.data` on a create rule (`high`)
+The document doesn't exist yet on `create`, so `resource.data` is null. Use `request.resource.data` instead.
+### `SEM-3`: More than 10 document reads (`high`)
+`get()` / `exists()` count exceeds the documented Firestore limit of 10 per rule. Same threshold as the linter's `GET_COUNT` error band.
+### `SEM-4`: Call to undefined function (`high`)
+A function call references a name that isn't defined in the current scope or any parent scope.
+## Quality (`QUA`)
+### `QUA-1`: Hardcoded `true` (`medium` for writes, `low` for reads)
+Same shape as the linter's `PERMISSIVE_RULE`. Reported here at lower severity than the linter blocks the deploy at, because the validator is advisory.
+### `QUA-2`: Empty match block (`low`)
+A match block with no allow rules, no children, and no functions. Dead code.
+### `QUA-3`: Duplicate function names (`medium`)
+Two functions share a name within the same scope. Behaviour depends on declaration order, confusing at best.
+### `QUA-4`: Unused function (`low`)
+A function is defined but never called.
+### `QUA-5`: Deep condition (`low`)
+A single rule's predicate exceeds an internal depth threshold. Consider extracting helpers.
+## Structure (`STR`)
+### `STR-1`: Match with no wildcard (`low`)
+A match path with no `{wildcard}` segment matches exactly one document. Usually a sign of a typo or a missing wildcard segment.
+### `STR-2`: Nested match without allows (`medium`)
+A parent block with no allow rules but with nested matches. Often a sign that the parent intended to lock the collection but ended up doing nothing.
+### `STR-3`: Overlapping sibling paths (`low`)
+Two sibling match blocks whose paths could match the same document. The more permissive rule wins, which may not be intended.
+## Severity model
+The validator's `severity` scale (`critical`, `high`, `medium`, `low`) is more granular than the linter's (`error`, `warning`). The values map as follows for tooling that treats them as block / advisory:
+| Severity | Recommended action |
+|---|---|
+| `critical` | Block deploy. |
+| `high` | Block by default; allow override with explicit human ack. |
+| `medium` | Surface in review; do not block. |
+| `low` | Surface in review; do not block. |
+The mapping is a convention, not enforced. Callers compose their own gates.