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/how-the-swap-works/index.html ADDED Viewed

@@ -0,0 +1,47 @@
+<!DOCTYPE html><html lang="en"> <head><meta charset="UTF-8"><meta name="viewport" content="width=device-width, initial-scale=1.0"><title>How firebase/* imports resolve locally and in production · Pyric Studio</title><meta name="description" content="Understand how your firebase imports reached a local backend, and why production is untouched."><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" open> <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/" aria-current="page"> 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"> <summary>Reference</summary> <div class="docs-nav-group-body"> <div class="docs-nav-section"> <ul> <li> <a href="/__pyric/ui/docs/pyric-cli/"> @pyric/cli </a> </li><li> <a href="/__pyric/ui/docs/pyric-explanation-versioning-and-compatibility/"> pyric </a> </li><li> <a href="/__pyric/ui/docs/pyric-firestore/"> pyric / firestore </a> </li><li> <a href="/__pyric/ui/docs/pyric-rules/"> pyric / rules </a> </li><li> <a href="/__pyric/ui/docs/pyric-sandbox/"> pyric / sandbox </a> </li><li> <a href="/__pyric/ui/docs/pyric-storage/"> pyric / storage </a> </li><li> <a href="/__pyric/ui/docs/pyric-auth/"> pyric / auth </a> </li><li> <a href="/__pyric/ui/docs/pyric-database/"> pyric / database </a> </li><li> <a href="/__pyric/ui/docs/pyric-admin-app/"> pyric-admin / app </a> </li><li> <a href="/__pyric/ui/docs/pyric-admin-firestore/"> 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" open> <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/" aria-current="page"> 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"> <summary>Reference</summary> <div class="docs-nav-group-body"> <div class="docs-nav-section"> <ul> <li> <a href="/__pyric/ui/docs/pyric-cli/"> @pyric/cli </a> </li><li> <a href="/__pyric/ui/docs/pyric-explanation-versioning-and-compatibility/"> pyric </a> </li><li> <a href="/__pyric/ui/docs/pyric-firestore/"> pyric / firestore </a> </li><li> <a href="/__pyric/ui/docs/pyric-rules/"> pyric / rules </a> </li><li> <a href="/__pyric/ui/docs/pyric-sandbox/"> pyric / sandbox </a> </li><li> <a href="/__pyric/ui/docs/pyric-storage/"> pyric / storage </a> </li><li> <a href="/__pyric/ui/docs/pyric-auth/"> pyric / auth </a> </li><li> <a href="/__pyric/ui/docs/pyric-database/"> pyric / database </a> </li><li> <a href="/__pyric/ui/docs/pyric-admin-app/"> pyric-admin / app </a> </li><li> <a href="/__pyric/ui/docs/pyric-admin-firestore/"> 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/start-building/">Run locally</a> </li><li> <span class="docs-breadcrumbs-sep" aria-hidden="true">/</span> <span aria-current="page">How the swap works</span> </li> </ol> </nav>  <article class="prose">  <h1 id="how-firebase-imports-resolve-locally-and-in-production">How firebase/* imports resolve locally and in production</h1>
+<p>In activated development, your app’s <code>firebase/*</code> imports resolve to a local backend with rules enforced, and no request leaves your machine. With that activation absent in production, the runtime resolves those imports to Firebase directly. Here is the whole mechanism, in three parts.</p>
+<h2 id="resolve-imports-to-pyric-during-development">Resolve imports to Pyric during development</h2>
+<p>Your source says <code>import { getFirestore } from 'firebase/firestore'</code>. In development, that specifier resolves to Pyric instead of the Firebase SDK. The swap happens in one of two layers:</p>
+<div class="table-scroll">
+<table><thead><tr><th>You run</th><th>Where the swap happens</th><th>Over what</th></tr></thead><tbody><tr><td><code>pyric dev</code></td><td>at load time, through an import map on the served page</td><td>files that are already built</td></tr><tr><td>the Vite plugin</td><td>at module resolution, before bundling, inside your normal <code>vite dev</code> loop</td><td>your source and its transitive dependencies</td></tr></tbody></table></div>
+<p>The Vite path reaches libraries too. A dependency that imports <code>firebase/firestore</code> on your behalf lands on the sandbox the same way your own code does.</p>
+<p>Either way, the call sites are identical to production code. The Firebase config you pass to <code>initializeApp</code> is accepted and ignored in development, because there is no project to talk to.</p>
+<p>For a Node child process, <code>pyric dev</code> sets <code>PYRIC_SANDBOX</code> and preloads
+<code>@pyric/cli/register</code>. While activated, that resolver maps <code>firebase/*</code> to
+<code>pyric/*</code> and <code>firebase-admin/*</code> to <code>pyric-admin/*</code>.</p>
+<h2 id="one-backend-shared-across-tabs">One backend, shared across tabs</h2>
+<p>The sandbox runs in a SharedWorker, and three things follow:</p>
+<ul>
+<li>Every tab of your dev origin talks to the same backend, so a write in one tab shows up live in another.</li>
+<li>The data is held in IndexedDB and survives a refresh.</li>
+<li>If the browser has no SharedWorker, Pyric falls back to a per-tab sandbox automatically.</li>
+</ul>
+<p>This is also why an agent and Studio see what you see. The MCP bridge and the Studio UI route into the same worker. One backend, and everything looks at it.</p>
+<h2 id="production-keeps-real-firebase">Production keeps real Firebase</h2>
+<p>A plain <code>vite build</code> leaves the development swap inactive and ships the real <code>firebase</code> package, using the same config you passed to <code>initializeApp</code> all along. A Node production process does not set <code>PYRIC_SANDBOX</code>, so <code>@pyric/cli/register</code> is inert and normal resolution loads Firebase directly. Nothing in your app source changes.</p>
+<ul>
+<li>There is no graduation step and no environment flag in your source.</li>
+<li>A sandbox-flavored build carries a marker in <code>index.html</code>; production hosting deploys should use an unmarked production build so a sandbox-wired dist never reaches production by accident.</li>
+<li>The swap lives in the toolchain on purpose. Remove Pyric from the project and you have a stock Firebase app again.</li>
+</ul>
+<h2 id="where-to-go-next">Where to go next</h2>
+<p>Watch the backend work, every read, write, and verdict, in <a href="../see-whats-happening/">see what’s happening</a>. Or start building: <a href="../sign-in-and-manage-users/">sign users in</a>.</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="#resolve-imports-to-pyric-during-development">Resolve imports to Pyric during development</a> </li><li data-depth="2"> <a href="#one-backend-shared-across-tabs">One backend, shared across tabs</a> </li><li data-depth="2"> <a href="#production-keeps-real-firebase">Production keeps real Firebase</a> </li><li data-depth="2"> <a href="#where-to-go-next">Where to go next</a> </li> </ul> </aside> </div> <script type="module">const a=document.querySelector("[data-api-symbol-filter]"),d=[...document.querySelectorAll("[data-api-symbol-group]")],n=document.querySelector("[data-api-symbol-empty]");a?.addEventListener("input",()=>{const t=a.value.trim().toLowerCase();let o=0;for(const i of d){let e=0;i.querySelectorAll("[data-api-symbol]").forEach(l=>{const r=!t||(l.dataset.apiSymbol??"").includes(t);l.hidden=!r,r&&e++}),i.hidden=e===0,o+=e}n&&(n.hidden=o>0)});</script> <script type="module">const s=new Map;document.querySelectorAll('.doc-toc a[href^="#"]').forEach(t=>s.set(decodeURIComponent(t.hash.slice(1)),t));if(s.size>0){const t=new Set,n=()=>{let o=null;for(const e of s.keys())if(t.has(e)){o=e;break}s.forEach((e,c)=>e.classList.toggle("active",c===o))},r=new IntersectionObserver(o=>{for(const e of o)e.isIntersecting?t.add(e.target.id):t.delete(e.target.id);n()},{rootMargin:"-72px 0px -60% 0px"});s.forEach((o,e)=>{const c=document.getElementById(e);c&&r.observe(c)})}</script> <script type="module">document.querySelector('.studio__nav [aria-current="page"]')?.scrollIntoView({block:"nearest",inline:"center"});</script> </body> </html>

package/dist/serve/docs-ui/docs/how-the-swap-works.md ADDED Viewed

@@ -0,0 +1,43 @@
+# How firebase/* imports resolve locally and in production
+In activated development, your app's `firebase/*` imports resolve to a local backend with rules enforced, and no request leaves your machine. With that activation absent in production, the runtime resolves those imports to Firebase directly. Here is the whole mechanism, in three parts.
+## Resolve imports to Pyric during development
+Your source says `import { getFirestore } from 'firebase/firestore'`. In development, that specifier resolves to Pyric instead of the Firebase SDK. The swap happens in one of two layers:
+| You run | Where the swap happens | Over what |
+|---|---|---|
+| `pyric dev` | at load time, through an import map on the served page | files that are already built |
+| the Vite plugin | at module resolution, before bundling, inside your normal `vite dev` loop | your source and its transitive dependencies |
+The Vite path reaches libraries too. A dependency that imports `firebase/firestore` on your behalf lands on the sandbox the same way your own code does.
+Either way, the call sites are identical to production code. The Firebase config you pass to `initializeApp` is accepted and ignored in development, because there is no project to talk to.
+For a Node child process, `pyric dev` sets `PYRIC_SANDBOX` and preloads
+`@pyric/cli/register`. While activated, that resolver maps `firebase/*` to
+`pyric/*` and `firebase-admin/*` to `pyric-admin/*`.
+## One backend, shared across tabs
+The sandbox runs in a SharedWorker, and three things follow:
+- Every tab of your dev origin talks to the same backend, so a write in one tab shows up live in another.
+- The data is held in IndexedDB and survives a refresh.
+- If the browser has no SharedWorker, Pyric falls back to a per-tab sandbox automatically.
+This is also why an agent and Studio see what you see. The MCP bridge and the Studio UI route into the same worker. One backend, and everything looks at it.
+## Production keeps real Firebase
+A plain `vite build` leaves the development swap inactive and ships the real `firebase` package, using the same config you passed to `initializeApp` all along. A Node production process does not set `PYRIC_SANDBOX`, so `@pyric/cli/register` is inert and normal resolution loads Firebase directly. Nothing in your app source changes.
+- There is no graduation step and no environment flag in your source.
+- A sandbox-flavored build carries a marker in `index.html`; production hosting deploys should use an unmarked production build so a sandbox-wired dist never reaches production by accident.
+- The swap lives in the toolchain on purpose. Remove Pyric from the project and you have a stock Firebase app again.
+## Where to go next
+Watch the backend work, every read, write, and verdict, in [see what's happening](../see-whats-happening/). Or start building: [sign users in](../sign-in-and-manage-users/).

package/dist/serve/docs-ui/docs/how-we-know-it-matches-firebase/index.html ADDED Viewed

@@ -0,0 +1,131 @@
+<!DOCTYPE html><html lang="en"> <head><meta charset="UTF-8"><meta name="viewport" content="width=device-width, initial-scale=1.0"><title>How does Pyric know it works like Firebase? · Pyric Studio</title><meta name="description" content="See the production evidence behind Pyric's conformance claims, the gaps those claims leave open, and the checks to make before shipping."><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" open> <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/" aria-current="page"> 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"> <summary>Reference</summary> <div class="docs-nav-group-body"> <div class="docs-nav-section"> <ul> <li> <a href="/__pyric/ui/docs/pyric-cli/"> @pyric/cli </a> </li><li> <a href="/__pyric/ui/docs/pyric-explanation-versioning-and-compatibility/"> pyric </a> </li><li> <a href="/__pyric/ui/docs/pyric-firestore/"> pyric / firestore </a> </li><li> <a href="/__pyric/ui/docs/pyric-rules/"> pyric / rules </a> </li><li> <a href="/__pyric/ui/docs/pyric-sandbox/"> pyric / sandbox </a> </li><li> <a href="/__pyric/ui/docs/pyric-storage/"> pyric / storage </a> </li><li> <a href="/__pyric/ui/docs/pyric-auth/"> pyric / auth </a> </li><li> <a href="/__pyric/ui/docs/pyric-database/"> pyric / database </a> </li><li> <a href="/__pyric/ui/docs/pyric-admin-app/"> pyric-admin / app </a> </li><li> <a href="/__pyric/ui/docs/pyric-admin-firestore/"> 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" open> <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/" aria-current="page"> 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"> <summary>Reference</summary> <div class="docs-nav-group-body"> <div class="docs-nav-section"> <ul> <li> <a href="/__pyric/ui/docs/pyric-cli/"> @pyric/cli </a> </li><li> <a href="/__pyric/ui/docs/pyric-explanation-versioning-and-compatibility/"> pyric </a> </li><li> <a href="/__pyric/ui/docs/pyric-firestore/"> pyric / firestore </a> </li><li> <a href="/__pyric/ui/docs/pyric-rules/"> pyric / rules </a> </li><li> <a href="/__pyric/ui/docs/pyric-sandbox/"> pyric / sandbox </a> </li><li> <a href="/__pyric/ui/docs/pyric-storage/"> pyric / storage </a> </li><li> <a href="/__pyric/ui/docs/pyric-auth/"> pyric / auth </a> </li><li> <a href="/__pyric/ui/docs/pyric-database/"> pyric / database </a> </li><li> <a href="/__pyric/ui/docs/pyric-admin-app/"> pyric-admin / app </a> </li><li> <a href="/__pyric/ui/docs/pyric-admin-firestore/"> 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/how-we-know-it-matches-firebase/">Conformance</a> </li><li> <span class="docs-breadcrumbs-sep" aria-hidden="true">/</span> <span aria-current="page">Conformance</span> </li> </ol> </nav>  <article class="prose">  <h1 id="how-does-pyric-know-it-works-like-firebase">How does Pyric know it works like Firebase?</h1>
+<p>If Pyric is a mirror of Firebase, how does it know it actually behaves like Firebase?</p>
+<p>Documentation describes intent. TypeScript declarations describe shape. Neither records what a deployed Firebase project actually did. The strongest available evidence is Firebase itself, so Pyric captures production behavior, compares the local result, and publishes where the two agree and where they do not. That is what it means to conform.</p>
+<p>The application call stays the same:</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">signInWithEmailAndPassword</span><span style="color:#ABB2BF"> } </span><span style="color:#C678DD">from</span><span style="color:#98C379"> 'firebase/auth'</span><span style="color:#ABB2BF">;</span></span></code></pre>
+<p>During Vite development, supported <code>firebase/*</code> imports resolve to Pyric. A production build resolves them to Firebase. Conformance asks whether the two implementations return the same value, error, state transition, or Rules verdict for a defined behavior.</p>
+<h2 id="the-conformance-system">The conformance system</h2>
+<p>One behavior moves through five connected steps:</p>
+<div class="conformance-flow">
+<div class="flow-step">Production Firebase</div>
+<div class="flow-arrow" aria-hidden="true">→</div>
+<div class="flow-step">Capture evidence<span class="flow-sub">observation or Rules corpus</span></div>
+<div class="flow-arrow" aria-hidden="true">→</div>
+<div class="flow-step">Register the claim<span class="flow-sub">status and evidence</span></div>
+<div class="flow-arrow" aria-hidden="true">→</div>
+<div class="flow-step">Check Pyric<span class="flow-sub">tests and conformance gates</span></div>
+<div class="flow-arrow" aria-hidden="true">→</div>
+<div class="flow-step">Publish the result<span class="flow-sub">generated matrices</span></div>
+</div>
+<p>The observation records what Firebase did. The registry states the claim Pyric makes about that behavior. A local check determines whether Pyric matches the recorded result. Generated matrices expose the status and its evidence without letting the published result drift away from the source.</p>
+<h2 id="follow-one-behavior-from-firebase-to-the-matrix">Follow one behavior from Firebase to the matrix</h2>
+<p>Consider a failed password sign-in. A probe signs into a real Firebase project with the wrong password and records the result, including the Firebase SDK version and project used for the capture:</p>
+<pre class="astro-code one-dark-pro" style="background-color:#282c34;color:#abb2bf; overflow-x: auto;" tabindex="0" data-language="json"><code><span class="line"><span style="color:#ABB2BF">{</span></span>
+<span class="line"><span style="color:#E06C75">  "name"</span><span style="color:#ABB2BF">: </span><span style="color:#98C379">"auth-wrong-password-error-code"</span><span style="color:#ABB2BF">,</span></span>
+<span class="line"><span style="color:#E06C75">  "rowIds"</span><span style="color:#ABB2BF">: [</span><span style="color:#98C379">"auth#15"</span><span style="color:#ABB2BF">],</span></span>
+<span class="line"><span style="color:#E06C75">  "fbSdkVersion"</span><span style="color:#ABB2BF">: </span><span style="color:#98C379">"12.13.0"</span><span style="color:#ABB2BF">,</span></span>
+<span class="line"><span style="color:#E06C75">  "projectId"</span><span style="color:#ABB2BF">: </span><span style="color:#98C379">"blockingfun"</span><span style="color:#ABB2BF">,</span></span>
+<span class="line"><span style="color:#E06C75">  "behavior"</span><span style="color:#ABB2BF">: {</span></span>
+<span class="line"><span style="color:#E06C75">    "code"</span><span style="color:#ABB2BF">: </span><span style="color:#98C379">"auth/wrong-password"</span><span style="color:#ABB2BF">,</span></span>
+<span class="line"><span style="color:#E06C75">    "messageContains"</span><span style="color:#ABB2BF">: {</span></span>
+<span class="line"><span style="color:#E06C75">      "wrongPassword"</span><span style="color:#ABB2BF">: </span><span style="color:#D19A66">true</span><span style="color:#ABB2BF">,</span></span>
+<span class="line"><span style="color:#E06C75">      "invalidCredential"</span><span style="color:#ABB2BF">: </span><span style="color:#D19A66">false</span></span>
+<span class="line"><span style="color:#ABB2BF">    }</span></span>
+<span class="line"><span style="color:#ABB2BF">  }</span></span>
+<span class="line"><span style="color:#ABB2BF">}</span></span></code></pre>
+<p>That committed <a href="https://github.com/davideast/pyric/blob/main/packages/conformance/observations/auth/auth-wrong-password-error-code.json" target="_blank" rel="noopener noreferrer" class="external-link">observation</a> is a captured fact, not a summary of Firebase documentation. It is then attached to a specific registry row:</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:#ABB2BF">{</span></span>
+<span class="line"><span style="color:#E06C75">  id</span><span style="color:#ABB2BF">: </span><span style="color:#98C379">'auth#15'</span><span style="color:#ABB2BF">,</span></span>
+<span class="line"><span style="color:#E06C75">  api</span><span style="color:#ABB2BF">: </span><span style="color:#98C379">'signInWithEmailAndPassword(auth, email, password)'</span><span style="color:#ABB2BF">,</span></span>
+<span class="line"><span style="color:#E06C75">  behavior</span><span style="color:#ABB2BF">: </span><span style="color:#98C379">'Throws auth/wrong-password when the password does not match'</span><span style="color:#ABB2BF">,</span></span>
+<span class="line"><span style="color:#E06C75">  status</span><span style="color:#ABB2BF">: </span><span style="color:#98C379">'conforms'</span><span style="color:#ABB2BF">,</span></span>
+<span class="line"><span style="color:#E06C75">  oracleObservations</span><span style="color:#ABB2BF">: [</span><span style="color:#98C379">'auth-wrong-password-error-code'</span><span style="color:#ABB2BF">],</span></span>
+<span class="line"><span style="color:#E06C75">  conformanceTests</span><span style="color:#ABB2BF">: [</span><span style="color:#98C379">'packages/pyric/test/auth/sandbox-email-password.test.ts'</span><span style="color:#ABB2BF">],</span></span>
+<span class="line"><span style="color:#E06C75">  automation</span><span style="color:#ABB2BF">: </span><span style="color:#98C379">'oracle-backed'</span><span style="color:#ABB2BF">,</span></span>
+<span class="line"><span style="color:#ABB2BF">}</span></span></code></pre>
+<p>The <a href="https://github.com/davideast/pyric/blob/main/packages/conformance/registry/auth.ts" target="_blank" rel="noopener noreferrer" class="external-link">registry row</a> is the published claim. It names the production evidence, the broader local behavior test, the current status, and the strength of the automation behind it.</p>
+<p>Separately, an <a href="https://github.com/davideast/pyric/blob/main/packages/pyric/test/auth/oracle-conformance.test.ts" target="_blank" rel="noopener noreferrer" class="external-link">oracle conformance test</a> reads the observation and requires Pyric to return the recorded error 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">const</span><span style="color:#E5C07B"> observation</span><span style="color:#56B6C2"> =</span><span style="color:#61AFEF"> load</span><span style="color:#ABB2BF">(</span><span style="color:#98C379">'auth-wrong-password-error-code.json'</span><span style="color:#ABB2BF">);</span></span>
+<span class="line"></span>
+<span class="line"><span style="color:#C678DD">await</span><span style="color:#61AFEF"> expectCode</span><span style="color:#ABB2BF">(</span></span>
+<span class="line"><span style="color:#61AFEF">  signInWithEmailAndPassword</span><span style="color:#ABB2BF">(</span><span style="color:#E06C75">auth</span><span style="color:#ABB2BF">, </span><span style="color:#98C379">'wp@example.com'</span><span style="color:#ABB2BF">, </span><span style="color:#98C379">'wrong9999'</span><span style="color:#ABB2BF">),</span></span>
+<span class="line"><span style="color:#E5C07B">  observation</span><span style="color:#ABB2BF">.</span><span style="color:#E06C75">code</span><span style="color:#ABB2BF">,</span></span>
+<span class="line"><span style="color:#ABB2BF">);</span></span></code></pre>
+<p>CI checks this chain in layers. Registry validation rejects missing or inconsistent evidence references. The library tests exercise local behavior, including observation-backed comparisons like this one. Selected production observations also have dedicated replay checks. The generated matrices are rebuilt from the registry and current public-surface census, then checked for drift.</p>
+<p>This distinction matters. <code>compat:check</code> validates the conformance model and generated results, but it does not replay every production observation by itself. The full CI suite combines those gates with the tests that exercise Pyric.</p>
+<h2 id="security-rules-require-a-corpus">Security Rules require a corpus</h2>
+<p>A single API result can be captured as one observation. Security Rules need a broader method because a ruleset is a program. The relevant question is whether Firebase allows or denies a request under a particular ruleset, data state, identity, and operation.</p>
+<p>The <a href="https://github.com/davideast/pyric/tree/main/packages/conformance/rules-corpus" target="_blank" rel="noopener noreferrer" class="external-link">Rules corpus</a> stores those inputs as scenarios. For example, Firestore treats direct access to a missing map field as a runtime error. Comparing that field with <code>null</code> denies the request, while the <code>in</code> operator performs an actual absence check:</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">rules_version</span><span style="color:#ABB2BF"> = </span><span style="color:#98C379">'2'</span><span style="color:#ABB2BF">;</span></span>
+<span class="line"><span style="color:#C678DD">service</span><span style="color:#ABB2BF"> cloud.firestore {</span></span>
+<span class="line"><span style="color:#C678DD">  match</span><span style="color:#ABB2BF"> /databases/</span><span style="color:#E06C75;font-style:italic">{database}</span><span style="color:#ABB2BF">/documents {</span></span>
+<span class="line"><span style="color:#C678DD">    match</span><span style="color:#ABB2BF"> /typoEqNullDeny/</span><span style="color:#E06C75;font-style:italic">{id}</span><span style="color:#ABB2BF"> {</span></span>
+<span class="line"><span style="color:#C678DD">      allow</span><span style="color:#61AFEF"> create</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.typo == </span><span style="color:#D19A66">null</span><span style="color:#ABB2BF">;</span></span>
+<span class="line"><span style="color:#ABB2BF">    }</span></span>
+<span class="line"></span>
+<span class="line"><span style="color:#C678DD">    match</span><span style="color:#ABB2BF"> /notInAllow/</span><span style="color:#E06C75;font-style:italic">{id}</span><span style="color:#ABB2BF"> {</span></span>
+<span class="line"><span style="color:#C678DD">      allow</span><span style="color:#61AFEF"> create</span><span style="color:#ABB2BF">: </span><span style="color:#C678DD">if</span><span style="color:#ABB2BF"> !(</span><span style="color:#98C379">'typo'</span><span style="color:#C678DD"> in</span><span style="color:#E5C07B"> request</span><span style="color:#ABB2BF">.</span><span style="color:#E5C07B">resource</span><span style="color:#ABB2BF">.data);</span></span>
+<span class="line"><span style="color:#ABB2BF">    }</span></span>
+<span class="line"><span style="color:#ABB2BF">  }</span></span>
+<span class="line"><span style="color:#ABB2BF">}</span></span></code></pre>
+<p>The corpus expects the first request to be denied and the second to be allowed. Firebase supplies the authoritative verdict. Pyric’s simulator must reach the same result.</p>
+<p>Firestore and Storage expose hosted Rules Test APIs, so their capture runners can ask Firebase for each verdict directly. Realtime Database has no equivalent API. Its runner deploys each scenario’s rules to a dedicated oracle database, executes the live operations in an isolated namespace, records the results, restores the previous rules, and verifies cleanup. The acquisition paths differ, but the contract is the same: production decides the expected verdict.</p>
+<p>Committed Rules observations are replayed locally against the matching corpus scenarios. A mismatch remains visible as a documented divergence or bug until the simulator agrees.</p>
+<h2 id="public-surface-and-behavior-answer-different-questions">Public surface and behavior answer different questions</h2>
+<p>Behavior evidence cannot show whether an API is missing. A perfect match on a small set of calls would still leave a poor mirror if Firebase exposed much more.</p>
+<p>The public-surface census therefore reads Firebase’s public exports and compares them with Pyric. Runtime values and exported type names are measured separately. Names beginning with <code>_</code> remain available as a raw diagnostic but do not count as public Firebase surface. Unsupported or deprecated public APIs stay in the denominator, and Pyric-only helpers receive no credit.</p>
+<p>The census proves name presence, not signature equivalence or runtime behavior. Those questions belong to types, tests, and registry evidence. Keeping the axes separate prevents a strong result on one axis from hiding a weak result on another.</p>
+<p>The current <a href="../pyric-conformance-scores/">conformance scoreboard</a> publishes public runtime surface, public type surface, and behavior fidelity separately.</p>
+<h2 id="five-states-keep-the-gaps-visible">Five states keep the gaps visible</h2>
+<p>Every tracked behavior has one of five states:</p>
+<div class="table-scroll">
+<table><thead><tr><th>State</th><th>Meaning</th></tr></thead><tbody><tr><td><strong>Conforms</strong></td><td>The tracked behavior matches Firebase at the stated level of evidence.</td></tr><tr><td><strong>Documented divergence</strong></td><td>Firebase and Pyric intentionally differ, with both behaviors and the reason recorded.</td></tr><tr><td><strong>Bug</strong></td><td>Pyric should match Firebase but currently does not.</td></tr><tr><td><strong>Unsupported</strong></td><td>The behavior is outside the current implementation.</td></tr><tr><td><strong>Unverified</strong></td><td>The behavior is tracked, but the available evidence does not yet establish the result.</td></tr></tbody></table></div>
+<p>Status and evidence strength are separate. A conforming row may be backed by a production observation, a shape capture, a local test, or a narrower source of evidence. The matrix shows that distinction rather than treating every green row as equally proven.</p>
+<p>The registry is also a tracked behavior set, not an inventory of every behavior Firebase could exhibit. Missing from the registry does not mean passed. It means no claim is being published for that behavior yet.</p>
+<h2 id="what-this-proves-and-what-it-does-not">What this proves, and what it does not</h2>
+<p>Conformance is a floor, not a guarantee of total equivalence.</p>
+<ul>
+<li><strong>Evidence covers defined claims.</strong> A production observation supports the rows connected to it. It does not generalize to adjacent behavior that was never captured.</li>
+<li><strong>Observations are snapshots.</strong> Each records an SDK version and project configuration. Configuration-dependent behavior can remain unknown until the right project and probe exercise it.</li>
+<li><strong>The behavior registry is incomplete by design.</strong> It contains the claims currently tracked. Firebase behavior outside that set is not silently counted as conforming.</li>
+<li><strong>Evidence is uneven.</strong> Some rows are pinned directly to production. Others have local, type-level, or sandbox-only evidence. The matrices expose that strength row by row.</li>
+<li><strong>Surface evidence is name-level.</strong> The census can establish that a public runtime or type name exists. It does not prove the full signature, semantics, or interaction with other APIs.</li>
+<li><strong>A local mirror cannot remove the production boundary.</strong> Project configuration, deployed Rules, credentials, service state, and Firebase changes still require controlled verification before release.</li>
+</ul>
+<p>No published result is typed into this page. Registry state and the live public-surface census generate the matrices and scoreboard. A generated page that drifts from those sources fails its check.</p>
+<h2 id="verify-the-boundary-before-shipping">Verify the boundary before shipping</h2>
+<p>Pyric is designed for local development, where operations have no production consequences. Before deployment, replay the captured development session against the candidate Rules:</p>
+<pre class="astro-code one-dark-pro" style="background-color:#282c34;color:#abb2bf; overflow-x: auto;" tabindex="0" data-language="bash"><code><span class="line"><span style="color:#61AFEF">npx</span><span style="color:#98C379"> pyric</span><span style="color:#98C379"> verify</span></span></code></pre>
+<p>The default engine runs locally and requires no cloud credentials. For Firestore, the hosted Rules Test API can provide a second verdict from Google in a controlled project:</p>
+<pre class="astro-code one-dark-pro" style="background-color:#282c34;color:#abb2bf; overflow-x: auto;" tabindex="0" data-language="bash"><code><span class="line"><span style="color:#61AFEF">npx</span><span style="color:#98C379"> pyric</span><span style="color:#98C379"> verify</span><span style="color:#D19A66"> --engine</span><span style="color:#98C379"> both</span><span style="color:#D19A66"> --project</span><span style="color:#98C379"> staging-project</span></span></code></pre>
+<p>Hosted verification evaluates derived cases. It does not deploy Rules or modify production data. It does require Firebase credentials and a project configured for that check.</p>
+<p>This is the final boundary of the conformance claim. Pyric supplies evidence that local behavior matches the cases it tracks. A staging or hosted verification step checks the application-specific configuration that a general conformance suite cannot know. Then the same <code>firebase/*</code> application code can proceed through the normal Firebase deployment path described in <a href="../ship-to-production/">Ship to production</a>.</p>
+<p>The generated matrices contain the current evidence for <a href="../pyric-app-compat/">App</a>, <a href="../pyric-auth-compat/">Auth</a>, <a href="../pyric-firestore-compat/">Firestore</a>, <a href="../pyric-database-compat/">Realtime Database</a>, <a href="../pyric-storage-compat/">Storage</a>, <a href="../pyric-messaging-compat/">Messaging</a>, <a href="../pyric-ai-compat/">AI Logic</a>, <a href="../pyric-rules-compat/">Security Rules</a>, and <a href="../pyric-cli-functions-rtdb-compat/">Functions with Realtime Database</a>.</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-conformance-system">The conformance system</a> </li><li data-depth="2"> <a href="#follow-one-behavior-from-firebase-to-the-matrix">Follow one behavior from Firebase to the matrix</a> </li><li data-depth="2"> <a href="#security-rules-require-a-corpus">Security Rules require a corpus</a> </li><li data-depth="2"> <a href="#public-surface-and-behavior-answer-different-questions">Public surface and behavior answer different questions</a> </li><li data-depth="2"> <a href="#five-states-keep-the-gaps-visible">Five states keep the gaps visible</a> </li><li data-depth="2"> <a href="#what-this-proves-and-what-it-does-not">What this proves, and what it does not</a> </li><li data-depth="2"> <a href="#verify-the-boundary-before-shipping">Verify the boundary before shipping</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/how-we-know-it-matches-firebase.md ADDED Viewed

@@ -0,0 +1,169 @@
+# How does Pyric know it works like Firebase?
+If Pyric is a mirror of Firebase, how does it know it actually behaves like Firebase?
+Documentation describes intent. TypeScript declarations describe shape. Neither records what a deployed Firebase project actually did. The strongest available evidence is Firebase itself, so Pyric captures production behavior, compares the local result, and publishes where the two agree and where they do not. That is what it means to conform.
+The application call stays the same:
+```ts
+import { signInWithEmailAndPassword } from 'firebase/auth';
+```
+During Vite development, supported `firebase/*` imports resolve to Pyric. A production build resolves them to Firebase. Conformance asks whether the two implementations return the same value, error, state transition, or Rules verdict for a defined behavior.
+## The conformance system
+One behavior moves through five connected steps:
+<div class="conformance-flow">
+<div class="flow-step">Production Firebase</div>
+<div class="flow-arrow" aria-hidden="true">→</div>
+<div class="flow-step">Capture evidence<span class="flow-sub">observation or Rules corpus</span></div>
+<div class="flow-arrow" aria-hidden="true">→</div>
+<div class="flow-step">Register the claim<span class="flow-sub">status and evidence</span></div>
+<div class="flow-arrow" aria-hidden="true">→</div>
+<div class="flow-step">Check Pyric<span class="flow-sub">tests and conformance gates</span></div>
+<div class="flow-arrow" aria-hidden="true">→</div>
+<div class="flow-step">Publish the result<span class="flow-sub">generated matrices</span></div>
+</div>
+The observation records what Firebase did. The registry states the claim Pyric makes about that behavior. A local check determines whether Pyric matches the recorded result. Generated matrices expose the status and its evidence without letting the published result drift away from the source.
+## Follow one behavior from Firebase to the matrix
+Consider a failed password sign-in. A probe signs into a real Firebase project with the wrong password and records the result, including the Firebase SDK version and project used for the capture:
+```json
+{
+  "name": "auth-wrong-password-error-code",
+  "rowIds": ["auth#15"],
+  "fbSdkVersion": "12.13.0",
+  "projectId": "blockingfun",
+  "behavior": {
+    "code": "auth/wrong-password",
+    "messageContains": {
+      "wrongPassword": true,
+      "invalidCredential": false
+    }
+  }
+}
+```
+That committed [observation](https://github.com/davideast/pyric/blob/main/packages/conformance/observations/auth/auth-wrong-password-error-code.json) is a captured fact, not a summary of Firebase documentation. It is then attached to a specific registry row:
+```ts
+{
+  id: 'auth#15',
+  api: 'signInWithEmailAndPassword(auth, email, password)',
+  behavior: 'Throws auth/wrong-password when the password does not match',
+  status: 'conforms',
+  oracleObservations: ['auth-wrong-password-error-code'],
+  conformanceTests: ['packages/pyric/test/auth/sandbox-email-password.test.ts'],
+  automation: 'oracle-backed',
+}
+```
+The [registry row](https://github.com/davideast/pyric/blob/main/packages/conformance/registry/auth.ts) is the published claim. It names the production evidence, the broader local behavior test, the current status, and the strength of the automation behind it.
+Separately, an [oracle conformance test](https://github.com/davideast/pyric/blob/main/packages/pyric/test/auth/oracle-conformance.test.ts) reads the observation and requires Pyric to return the recorded error code:
+```ts
+const observation = load('auth-wrong-password-error-code.json');
+await expectCode(
+  signInWithEmailAndPassword(auth, 'wp@example.com', 'wrong9999'),
+  observation.code,
+);
+```
+CI checks this chain in layers. Registry validation rejects missing or inconsistent evidence references. The library tests exercise local behavior, including observation-backed comparisons like this one. Selected production observations also have dedicated replay checks. The generated matrices are rebuilt from the registry and current public-surface census, then checked for drift.
+This distinction matters. `compat:check` validates the conformance model and generated results, but it does not replay every production observation by itself. The full CI suite combines those gates with the tests that exercise Pyric.
+## Security Rules require a corpus
+A single API result can be captured as one observation. Security Rules need a broader method because a ruleset is a program. The relevant question is whether Firebase allows or denies a request under a particular ruleset, data state, identity, and operation.
+The [Rules corpus](https://github.com/davideast/pyric/tree/main/packages/conformance/rules-corpus) stores those inputs as scenarios. For example, Firestore treats direct access to a missing map field as a runtime error. Comparing that field with `null` denies the request, while the `in` operator performs an actual absence check:
+```rules
+rules_version = '2';
+service cloud.firestore {
+  match /databases/{database}/documents {
+    match /typoEqNullDeny/{id} {
+      allow create: if request.resource.data.typo == null;
+    }
+    match /notInAllow/{id} {
+      allow create: if !('typo' in request.resource.data);
+    }
+  }
+}
+```
+The corpus expects the first request to be denied and the second to be allowed. Firebase supplies the authoritative verdict. Pyric's simulator must reach the same result.
+Firestore and Storage expose hosted Rules Test APIs, so their capture runners can ask Firebase for each verdict directly. Realtime Database has no equivalent API. Its runner deploys each scenario's rules to a dedicated oracle database, executes the live operations in an isolated namespace, records the results, restores the previous rules, and verifies cleanup. The acquisition paths differ, but the contract is the same: production decides the expected verdict.
+Committed Rules observations are replayed locally against the matching corpus scenarios. A mismatch remains visible as a documented divergence or bug until the simulator agrees.
+## Public surface and behavior answer different questions
+Behavior evidence cannot show whether an API is missing. A perfect match on a small set of calls would still leave a poor mirror if Firebase exposed much more.
+The public-surface census therefore reads Firebase's public exports and compares them with Pyric. Runtime values and exported type names are measured separately. Names beginning with `_` remain available as a raw diagnostic but do not count as public Firebase surface. Unsupported or deprecated public APIs stay in the denominator, and Pyric-only helpers receive no credit.
+The census proves name presence, not signature equivalence or runtime behavior. Those questions belong to types, tests, and registry evidence. Keeping the axes separate prevents a strong result on one axis from hiding a weak result on another.
+The current [conformance scoreboard](../pyric-conformance-scores/) publishes public runtime surface, public type surface, and behavior fidelity separately.
+## Five states keep the gaps visible
+Every tracked behavior has one of five states:
+| State | Meaning |
+|---|---|
+| **Conforms** | The tracked behavior matches Firebase at the stated level of evidence. |
+| **Documented divergence** | Firebase and Pyric intentionally differ, with both behaviors and the reason recorded. |
+| **Bug** | Pyric should match Firebase but currently does not. |
+| **Unsupported** | The behavior is outside the current implementation. |
+| **Unverified** | The behavior is tracked, but the available evidence does not yet establish the result. |
+Status and evidence strength are separate. A conforming row may be backed by a production observation, a shape capture, a local test, or a narrower source of evidence. The matrix shows that distinction rather than treating every green row as equally proven.
+The registry is also a tracked behavior set, not an inventory of every behavior Firebase could exhibit. Missing from the registry does not mean passed. It means no claim is being published for that behavior yet.
+## What this proves, and what it does not
+Conformance is a floor, not a guarantee of total equivalence.
+- **Evidence covers defined claims.** A production observation supports the rows connected to it. It does not generalize to adjacent behavior that was never captured.
+- **Observations are snapshots.** Each records an SDK version and project configuration. Configuration-dependent behavior can remain unknown until the right project and probe exercise it.
+- **The behavior registry is incomplete by design.** It contains the claims currently tracked. Firebase behavior outside that set is not silently counted as conforming.
+- **Evidence is uneven.** Some rows are pinned directly to production. Others have local, type-level, or sandbox-only evidence. The matrices expose that strength row by row.
+- **Surface evidence is name-level.** The census can establish that a public runtime or type name exists. It does not prove the full signature, semantics, or interaction with other APIs.
+- **A local mirror cannot remove the production boundary.** Project configuration, deployed Rules, credentials, service state, and Firebase changes still require controlled verification before release.
+No published result is typed into this page. Registry state and the live public-surface census generate the matrices and scoreboard. A generated page that drifts from those sources fails its check.
+## Verify the boundary before shipping
+Pyric is designed for local development, where operations have no production consequences. Before deployment, replay the captured development session against the candidate Rules:
+```bash
+npx pyric verify
+```
+The default engine runs locally and requires no cloud credentials. For Firestore, the hosted Rules Test API can provide a second verdict from Google in a controlled project:
+```bash
+npx pyric verify --engine both --project staging-project
+```
+Hosted verification evaluates derived cases. It does not deploy Rules or modify production data. It does require Firebase credentials and a project configured for that check.
+This is the final boundary of the conformance claim. Pyric supplies evidence that local behavior matches the cases it tracks. A staging or hosted verification step checks the application-specific configuration that a general conformance suite cannot know. Then the same `firebase/*` application code can proceed through the normal Firebase deployment path described in [Ship to production](../ship-to-production/).
+The generated matrices contain the current evidence for [App](../pyric-app-compat/), [Auth](../pyric-auth-compat/), [Firestore](../pyric-firestore-compat/), [Realtime Database](../pyric-database-compat/), [Storage](../pyric-storage-compat/), [Messaging](../pyric-messaging-compat/), [AI Logic](../pyric-ai-compat/), [Security Rules](../pyric-rules-compat/), and [Functions with Realtime Database](../pyric-cli-functions-rtdb-compat/).

package/dist/serve/docs-ui/docs/index.html ADDED Viewed

	@@ -0,0 +1,2 @@
1	+ <!DOCTYPE html><html lang="en" data-astro-cid-zsukdfzm> <head><meta charset="UTF-8"><meta http-equiv="refresh" content="0; url=/__pyric/ui/docs/overview/"><link rel="canonical" href="/__pyric/ui/docs/overview/"><title>Pyric docs</title><style>html{background:#16161a;color:#72728a;font:14px -apple-system,BlinkMacSystemFont,Segoe UI,sans-serif}body{margin:0;min-height:100vh;display:grid;place-items:center}a[data-astro-cid-zsukdfzm]{color:inherit;opacity:0;animation:reveal 0s 1.5s forwards}@keyframes reveal{to{opacity:1}}
2	+ </style></head> <body data-astro-cid-zsukdfzm> <p data-astro-cid-zsukdfzm><a href="/__pyric/ui/docs/overview/" data-astro-cid-zsukdfzm>Open the Pyric docs</a></p> </body></html>