@pyric/cli 0.1.0-alpha.9

package/dist/serve/docs-ui/docs/pyric-sandbox-explanation-listener-re-evaluation.md

@@ -0,0 +1,82 @@
+# Listener re-evaluation on `deployRules`
+
+A snapshot listener attached before a `deployRules` call gets re-evaluated under the new rules. This is a deliberate departure from production Firestore behaviour. The reasoning matters; this page lays it out.
+
+## What production does
+
+In production, a `cloud.firestore` ruleset change does **not** affect listeners that are already attached. The listener keeps using whatever rules were in force when it was created. Subsequent `deployRules` calls roll out for new listeners and new operations, but live streams continue with their original gating until the consumer detaches and re-attaches.
+
+This matches how production thinks about rules deployment: deploys are eventually-consistent, propagation takes seconds to minutes, and a listener's evaluation context is captured at attach time.
+
+## What the sandbox does
+
+`pyric/sandbox` re-evaluates every active listener immediately after `deployRules` succeeds. Three cases:
+
+- **Allowed → denied**: the listener is marked errored. Its `onError` callback fires (if provided); `onSnapshot` does not fire again. Once-per-stream error semantics.
+- **Errored → allowed**: the `errored` flag clears and the listener fires as an initial snapshot. The consumer sees a fresh baseline.
+- **Allowed → allowed**: behaves like a write-driven re-evaluation. Diff against the listener's last delivered snapshot; suppress if unchanged; fire if it changed.
+
+For query listeners, the same logic applies per-doc: added / removed change entries surface as the readable doc set flips.
+
+## Why diverge
+
+The playground is the driving consumer. A user editing rules in the playground UI wants to see their UI react. If a listener doesn't re-evaluate when rules change:
+
+- An over-permissive rule that the user is trying to tighten will still allow reads that should now deny.
+- An over-restrictive rule that the user is loosening will still deny reads that should now allow.
+
+Either way the UI shows stale state until the user manually refreshes. That breaks the "edit rules, see the effect" feedback loop the playground exists for.
+
+For a unit-test consumer, the divergence rarely matters. Tests typically don't reconfigure rules mid-listener. But when they do, the sandbox's behaviour is what tests usually want. "Test that this rule blocks a read that was previously allowed" works without detach-reattach gymnastics.
+
+## When this hurts
+
+Two situations where production parity would be nicer:
+
+- **Reproducing a production bug** where the symptom is "a listener kept its old gating". The sandbox can't reproduce this, because every rule change re-gates everything. You'd need the emulator or live Firestore.
+- **Verifying eventual consistency**. The sandbox is synchronous; rules apply immediately. Production isn't; rules take propagation time. Tests that depend on the propagation window need a different tool.
+
+Both are edge cases. Document them, route them to the right tool, leave the default behaviour where it serves the common case.
+
+## What dispose does differently
+
+`dispose` (called by `reset`) doesn't re-evaluate. It drops every listener registry. Subscribers that were live against the outgoing environment are gone; the new environment starts with no listeners. This is correct because `reset` is "wipe everything". Partial state would be confusing.
+
+The distinction:
+
+- **`deployRules`**: rules change, data stays, listeners stay (and re-evaluate).
+- **`reset`**: data, rules, listeners, subscribers, all wiped. Fresh environment.
+- **`dispose`**: keep data and rules, drop listeners and subscribers. Used when you're about to discard the sandbox.
+
+## Implementation: iterate over a copy
+
+The re-evaluation loop walks every active listener. A callback may add or remove listeners during the loop (React StrictMode does this routinely; HMR likewise). Iterating the map directly while it mutates is a bug.
+
+The loop snapshots the listener IDs first, then checks `snapshotListeners.has(id)` per iteration:
+
+```ts
+const records = Array.from(this.snapshotListeners.values());
+for (const record of records) {
+  if (!this.snapshotListeners.has(record.id)) continue;  // unsubscribed mid-loop
+  // ... re-evaluate
+}
+```
+
+The same pattern appears in write-driven listener notification. The mutating-during-iteration risk is the same in both cases; the fix is the same.
+
+## The "once-per-stream" error contract
+
+Production: a snapshot listener that errors delivers the error exactly once, then receives no further snapshots. The listener stays subscribed from the consumer's view; the stream is dead.
+
+The sandbox honours this. A listener that flips allowed → denied fires its `onError` once (if registered) and is marked `errored`. Subsequent re-evaluations under further rule changes that keep it denied don't re-fire the error. Re-allowed listeners clear the flag and fire a fresh initial snapshot.
+
+This matters for UI code that displays "this listener failed". Without the once-per-stream rule, the same error would re-fire on every subsequent rule change, spamming the consumer.
+
+## Stream errors vs. one-shot denials
+
+Both surface through `sandbox.onEvent`, on different `kind` discriminators. The targets differ, which is why the event shapes differ:
+
+- `kind: 'request' && result: 'deny'` is "an operation the consumer issued was denied." The consumer knows which operation; the event names `method`, `path`, `auth`, `reasons`.
+- `kind: 'listener_errored'` is "a listener died without anyone calling it." The consumer might not know which listener, so the event carries a `listenerId` and a `target` discriminator (`doc` path or query collection) on top of the error payload.
+
+A host UI that wants to surface every kind of denial subscribes once to `onEvent` and dispatches on `event.kind`.

package/dist/serve/docs-ui/docs/pyric-sandbox-explanation-local-backend-vs-firestore-offline/index.html

@@ -0,0 +1,64 @@
+<!DOCTYPE html><html lang="en"> <head><meta charset="UTF-8"><meta name="viewport" content="width=device-width, initial-scale=1.0"><title>A local backend, not Firestore offline persistence · 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/"> pyric / rules </a> </li><li> <a href="/__pyric/ui/docs/pyric-sandbox/" aria-current="true"> 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/"> pyric / rules </a> </li><li> <a href="/__pyric/ui/docs/pyric-sandbox/" aria-current="true"> 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-sandbox/">pyric / sandbox</a> </li><li> <span class="docs-breadcrumbs-sep" aria-hidden="true">/</span> <span>Explanation</span> </li><li> <span class="docs-breadcrumbs-sep" aria-hidden="true">/</span> <span aria-current="page">Local backend vs. offline</span> </li> </ol> </nav>  <article class="prose">  <h1 id="a-local-backend-not-firestore-offline-persistence">A local backend, not Firestore offline persistence</h1>
+<p>A natural worry when you see <code>pyric dev</code> keep data across refreshes and sync across tabs is: <em>“are you reimplementing Firestore’s offline + multi-tab persistence?”</em> That feature is one of the largest parts of the Firestore SDK, and reimplementing it would be a massive undertaking.</p>
+<p>The answer is <strong>no, by construction.</strong> pyric’s sandbox is a <strong>single local backend</strong>, not a cache in front of a remote server. That one structural difference removes essentially all of the complexity that makes offline synchronization a hard problem. This page explains why, so the distinction is clear before anyone reaches for the wrong mental model.</p>
+<h2 id="what-firestores-offline--multi-tab-actually-is">What Firestore’s offline + multi-tab actually is</h2>
+<p>Firestore’s offline persistence is a <strong>cache-and-sync layer in front of an authoritative remote server</strong>:</p>
+<ul>
+<li><strong>Offline writes</strong> are applied <em>optimistically</em> to a local IndexedDB cache and added to a <strong>mutation queue</strong>. They are sent to the server later; if the server <strong>rejects</strong> them (security rules, a conflict), they must be <strong>rolled back</strong> and every affected listener re-notified.</li>
+<li><strong>Reading offline</strong> serves results from the cache. When the client reconnects, the server’s watch stream must be <strong>reconciled</strong> with the still-pending local mutations (<code>local view = remote document cache + pending mutations</code>).</li>
+<li><strong>Queries offline</strong> require tracking target state, resume tokens, existence/bloom filters, and <strong>limbo resolution</strong>: “this document matches the query locally, but I can’t currently confirm it still exists on the server.”</li>
+<li><strong>Multi-tab</strong> is solved with a <strong>shared IndexedDB cache plus leader election</strong>: every tab runs the full client, but one is elected <strong>primary</strong> and owns the network stream; the others share the cache and coordinate via IndexedDB and Web Locks, with the primary handing off when its tab closes.</li>
+</ul>
+<p>Every one of those mechanisms exists to solve the same underlying problem: <strong>keeping a local cache and a remote authoritative server convergent, across multiple clients.</strong> That is a distributed-systems problem, and it is why the feature is large.</p>
+<h2 id="why-pyric-does-not-have-that-problem">Why pyric does not have that problem</h2>
+<p>In pyric there is <strong>no remote server</strong>, and there is <strong>exactly one authoritative instance</strong>: the sandbox. (The multi-tab realization is one sandbox hosted in a SharedWorker in the browser, or, for an agent, in the dev-server process; tabs and agents are thin clients. Conceptually it is a single backend, and <em>where</em> that backend runs, browser or Node, does not change the argument below. “Local” means “no remote to reconcile with,” not “in the browser.”) Because of that:</p>
+<div class="table-scroll">
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+<table><thead><tr><th>Firestore offline must do…</th><th>pyric (single local backend)</th></tr></thead><tbody><tr><td>mutation queue + optimistic apply + <strong>rollback</strong></td><td><strong>nothing</strong>: a write hits the one backend; rules evaluate immediately; it succeeds or fails <em>now</em>, never “accepted then rejected later”</td></tr><tr><td><strong>reconcile</strong> local cache ↔ remote server</td><td><strong>nothing</strong>: there is only one state</td></tr><tr><td>query coherence, <strong>limbo</strong> resolution, resume tokens, watch stream</td><td><strong>nothing</strong>: queries run directly against the one in-memory state</td></tr><tr><td><strong>leader election</strong> / primary handoff</td><td><strong>nothing</strong>: one instance; no “who owns the network,” because there is no network</td></tr><tr><td>concurrent-client <strong>conflict resolution</strong></td><td><strong>nothing</strong>: all tabs send operations to one backend, whose single event loop <strong>serializes</strong> them</td></tr></tbody></table></div>
+<p>The complexity in Firestore is the <strong>price of distribution</strong>. pyric is not distributed: it is one in-process object that several thin clients talk to. That is a <em>centralized</em> problem, which is categorically simpler. pyric’s “offline” is trivial because the sandbox is <strong>always local</strong>. There is no online↔offline transition to reconcile in the first place.</p>
+<h2 id="what-pyric-does-take-on-instead-and-why-it-is-small">What pyric does take on instead (and why it is small)</h2>
+<p>The single-backend model is not free, but its costs are mechanical, not distributed-systems-shaped:</p>
+<ul>
+<li>A <strong>transport layer</strong>: marshalling operations and streaming snapshot updates between a tab and the backend.</li>
+<li><strong>Serialization</strong> of values across that boundary (reusing the persistence serializer) and faithful propagation of typed errors (<code>permission-denied</code>, <code>auth/…</code>).</li>
+<li><strong>Lifecycle</strong>: the in-browser backend restores its state from IndexedDB when it starts.</li>
+<li>A small <strong>durability window</strong>: a write in the brief interval before the next debounced persist flush can be lost if the process dies right then, the same trade-off any debounced save makes.</li>
+</ul>
+<p>None of these are Firestore’s offline engine. There is no queue, no rollback, no reconciliation, no leader election, no limbo.</p>
+<h2 id="the-one-line-that-would-change-the-answer">The one line that would change the answer</h2>
+<p>There is exactly one way pyric would inherit Firestore’s full offline complexity: if it became a <strong>local-first layer that runs your app against the local backend and syncs to real Firestore in the background.</strong> That reintroduces <strong>two sources of truth that must converge</strong>, and with them the mutation queue, rollback, conflict resolution, and the rest.</p>
+<p>pyric deliberately does <strong>not</strong> do this. Its model is <strong>build against the local backend, then swap to real Firestore at deploy time</strong>. The import map flips <code>firebase/*</code> from the sandbox to the real SDK, and from then on the real backend is authoritative. There is never a moment where a local store and a remote store both hold writes that must be merged. That swap-at-deploy boundary is the guardrail that keeps the sandbox simple.</p>
+<p>There is a second, subtler way to inherit the same complexity: give a thin client its own <strong>offline-writing cache</strong>. A cache that accepts writes while disconnected is <em>also</em> a second source of truth, and it drags in the same queue / rollback / reconcile machinery. So pyric’s clients are always <strong>pure-thin</strong>. They hold no authoritative state. A client that loses its connection (a co-resident tab can’t lose it; a dev-server socket can) cannot operate until it reconnects, and it reconnects with <strong>nothing to reconcile</strong>. A trivial reconnect, not a distributed problem. That keeps the single-backend guarantee intact whether the one backend runs in a SharedWorker or a dev-server process.</p>
+<h2 id="the-takeaway">The takeaway</h2>
+<ul>
+<li>Firestore offline = a <strong>cache synchronizing with a remote server</strong>, continuously. Hard, because it is distributed.</li>
+<li>pyric = a <strong>single local backend</strong>, accessed by thin clients, swapped for real Firestore at deploy. Simple, because it is centralized.</li>
+</ul>
+<p>Multi-tab consistency and refresh-persistence in pyric are the centralized versions of those features (one backend, one cache, one writer), not the Firestore offline engine wearing a different coat. If you ever want the local-first-syncs-to-prod product, that is a separate, deliberate decision with its own cost. It is not something the sandbox drifts into.</p>  </article> </main> <aside class="doc-toc" aria-label="On this page"> <h2 class="doc-toc-heading">On this page</h2> <ul> <li data-depth="2"> <a href="#what-firestores-offline--multi-tab-actually-is">What Firestore’s offline + multi-tab actually is</a> </li><li data-depth="2"> <a href="#why-pyric-does-not-have-that-problem">Why pyric does not have that problem</a> </li><li data-depth="2"> <a href="#what-pyric-does-take-on-instead-and-why-it-is-small">What pyric does take on instead (and why it is small)</a> </li><li data-depth="2"> <a href="#the-one-line-that-would-change-the-answer">The one line that would change the answer</a> </li><li data-depth="2"> <a href="#the-takeaway">The takeaway</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-sandbox-explanation-local-backend-vs-firestore-offline.md

@@ -0,0 +1,56 @@
+# A local backend, not Firestore offline persistence
+
+A natural worry when you see `pyric dev` keep data across refreshes and sync across tabs is: *"are you reimplementing Firestore's offline + multi-tab persistence?"* That feature is one of the largest parts of the Firestore SDK, and reimplementing it would be a massive undertaking.
+
+The answer is **no, by construction.** pyric's sandbox is a **single local backend**, not a cache in front of a remote server. That one structural difference removes essentially all of the complexity that makes offline synchronization a hard problem. This page explains why, so the distinction is clear before anyone reaches for the wrong mental model.
+
+## What Firestore's offline + multi-tab actually is
+
+Firestore's offline persistence is a **cache-and-sync layer in front of an authoritative remote server**:
+
+- **Offline writes** are applied *optimistically* to a local IndexedDB cache and added to a **mutation queue**. They are sent to the server later; if the server **rejects** them (security rules, a conflict), they must be **rolled back** and every affected listener re-notified.
+- **Reading offline** serves results from the cache. When the client reconnects, the server's watch stream must be **reconciled** with the still-pending local mutations (`local view = remote document cache + pending mutations`).
+- **Queries offline** require tracking target state, resume tokens, existence/bloom filters, and **limbo resolution**: "this document matches the query locally, but I can't currently confirm it still exists on the server."
+- **Multi-tab** is solved with a **shared IndexedDB cache plus leader election**: every tab runs the full client, but one is elected **primary** and owns the network stream; the others share the cache and coordinate via IndexedDB and Web Locks, with the primary handing off when its tab closes.
+
+Every one of those mechanisms exists to solve the same underlying problem: **keeping a local cache and a remote authoritative server convergent, across multiple clients.** That is a distributed-systems problem, and it is why the feature is large.
+
+## Why pyric does not have that problem
+
+In pyric there is **no remote server**, and there is **exactly one authoritative instance**: the sandbox. (The multi-tab realization is one sandbox hosted in a SharedWorker in the browser, or, for an agent, in the dev-server process; tabs and agents are thin clients. Conceptually it is a single backend, and *where* that backend runs, browser or Node, does not change the argument below. "Local" means "no remote to reconcile with," not "in the browser.") Because of that:
+
+| Firestore offline must do… | pyric (single local backend) |
+|---|---|
+| mutation queue + optimistic apply + **rollback** | **nothing**: a write hits the one backend; rules evaluate immediately; it succeeds or fails *now*, never "accepted then rejected later" |
+| **reconcile** local cache ↔ remote server | **nothing**: there is only one state |
+| query coherence, **limbo** resolution, resume tokens, watch stream | **nothing**: queries run directly against the one in-memory state |
+| **leader election** / primary handoff | **nothing**: one instance; no "who owns the network," because there is no network |
+| concurrent-client **conflict resolution** | **nothing**: all tabs send operations to one backend, whose single event loop **serializes** them |
+
+The complexity in Firestore is the **price of distribution**. pyric is not distributed: it is one in-process object that several thin clients talk to. That is a *centralized* problem, which is categorically simpler. pyric's "offline" is trivial because the sandbox is **always local**. There is no online↔offline transition to reconcile in the first place.
+
+## What pyric does take on instead (and why it is small)
+
+The single-backend model is not free, but its costs are mechanical, not distributed-systems-shaped:
+
+- A **transport layer**: marshalling operations and streaming snapshot updates between a tab and the backend.
+- **Serialization** of values across that boundary (reusing the persistence serializer) and faithful propagation of typed errors (`permission-denied`, `auth/…`).
+- **Lifecycle**: the in-browser backend restores its state from IndexedDB when it starts.
+- A small **durability window**: a write in the brief interval before the next debounced persist flush can be lost if the process dies right then, the same trade-off any debounced save makes.
+
+None of these are Firestore's offline engine. There is no queue, no rollback, no reconciliation, no leader election, no limbo.
+
+## The one line that would change the answer
+
+There is exactly one way pyric would inherit Firestore's full offline complexity: if it became a **local-first layer that runs your app against the local backend and syncs to real Firestore in the background.** That reintroduces **two sources of truth that must converge**, and with them the mutation queue, rollback, conflict resolution, and the rest.
+
+pyric deliberately does **not** do this. Its model is **build against the local backend, then swap to real Firestore at deploy time**. The import map flips `firebase/*` from the sandbox to the real SDK, and from then on the real backend is authoritative. There is never a moment where a local store and a remote store both hold writes that must be merged. That swap-at-deploy boundary is the guardrail that keeps the sandbox simple.
+
+There is a second, subtler way to inherit the same complexity: give a thin client its own **offline-writing cache**. A cache that accepts writes while disconnected is *also* a second source of truth, and it drags in the same queue / rollback / reconcile machinery. So pyric's clients are always **pure-thin**. They hold no authoritative state. A client that loses its connection (a co-resident tab can't lose it; a dev-server socket can) cannot operate until it reconnects, and it reconnects with **nothing to reconcile**. A trivial reconnect, not a distributed problem. That keeps the single-backend guarantee intact whether the one backend runs in a SharedWorker or a dev-server process.
+
+## The takeaway
+
+- Firestore offline = a **cache synchronizing with a remote server**, continuously. Hard, because it is distributed.
+- pyric = a **single local backend**, accessed by thin clients, swapped for real Firestore at deploy. Simple, because it is centralized.
+
+Multi-tab consistency and refresh-persistence in pyric are the centralized versions of those features (one backend, one cache, one writer), not the Firestore offline engine wearing a different coat. If you ever want the local-first-syncs-to-prod product, that is a separate, deliberate decision with its own cost. It is not something the sandbox drifts into.

package/dist/serve/docs-ui/docs/pyric-sandbox-explanation-why-adapters-are-siblings/index.html

@@ -0,0 +1,92 @@
+<!DOCTYPE html><html lang="en"> <head><meta charset="UTF-8"><meta name="viewport" content="width=device-width, initial-scale=1.0"><title>Why service adapters live in sibling packages · 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/"> pyric / rules </a> </li><li> <a href="/__pyric/ui/docs/pyric-sandbox/" aria-current="true"> 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/"> pyric / rules </a> </li><li> <a href="/__pyric/ui/docs/pyric-sandbox/" aria-current="true"> 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-sandbox/">pyric / sandbox</a> </li><li> <span class="docs-breadcrumbs-sep" aria-hidden="true">/</span> <span>Explanation</span> </li><li> <span class="docs-breadcrumbs-sep" aria-hidden="true">/</span> <span aria-current="page">Why adapters are siblings</span> </li> </ol> </nav>  <article class="prose">  <h1 id="why-service-adapters-live-in-sibling-packages">Why service adapters live in sibling packages</h1>
+<p><code>pyric/sandbox</code> doesn’t ship the data-plane API. The functions you actually call (<code>getDoc</code>, <code>setDoc</code>, <code>collection</code>, <code>onSnapshot</code>, <code>runTransaction</code>) live in <code>pyric-admin</code> (Admin-SDK-shaped) and <code>pyric/firestore</code> (modular Web-SDK-shaped). This page explains why.</p>
+<h2 id="two-production-shapes-one-substrate">Two production shapes, one substrate</h2>
+<p>Firebase ships two Firestore SDKs that look quite different up close. Server / Admin / Cloud Functions code uses <code>firebase-admin/firestore</code>: chainable methods, class-shaped query builders, instance-bound operations. Browser / mobile / React Native code uses <code>firebase/firestore</code>: modular functions, function-bound queries, tree-shakable imports.</p>
+<p>Both are good APIs. Neither is a superset of the other. A package targeting both audiences has two reasonable choices:</p>
+<ol>
+<li>Pick one shape, force the other audience to translate.</li>
+<li>Ship both shapes over a shared substrate.</li>
+</ol>
+<p>We picked (2). The shared substrate is <code>pyric/sandbox</code>; the two shapes are <code>pyric-admin</code> and <code>pyric/firestore</code>.</p>
+<h2 id="why-not-bundle-everything">Why not bundle everything</h2>
+<p>A monorepo with one big <code>pyric/sandbox</code> that includes both APIs would work, mechanically. The reason not to is bundle cost and conceptual clutter.</p>
+<h3 id="bundle-cost">Bundle cost</h3>
+<p>A browser app that uses the modular Web SDK does not want the Admin-SDK shape in its bundle. These are more than different APIs. They have different opinions about what <code>Query</code> is, what a transaction’s read/write API looks like, what reference identity means. If both surfaces live in one package, tree-shaking has to be perfect to avoid pulling in the unused shape. Tree-shaking in practice is “almost perfect”, and “almost” hurts.</p>
+<p>Splitting into separate packages means the bundler doesn’t have to be clever. The browser app imports <code>pyric/firestore</code>, and that’s all the bundler sees.</p>
+<h3 id="conceptual-clutter">Conceptual clutter</h3>
+<p>The substrate’s API surface (<code>Sandbox</code>, <code>SandboxContext</code>, listeners, lifecycle, error family) is small and stable. The data-plane API surfaces are large and follow upstream SDKs. Mixing them in one package would either bury the substrate in a sea of <code>getDoc</code>/<code>setDoc</code> exports or split into namespaces inside one package, which is sibling packages with extra steps.</p>
+<p>Keeping the split visible at the package level makes the dependency direction obvious: the data planes depend on the substrate, never the other way around.</p>
+<h2 id="what-the-adapters-do">What the adapters do</h2>
+<p>Both adapters are thin. The pattern, abstracted:</p>
+<pre class="astro-code one-dark-pro" style="background-color:#282c34;color:#abb2bf; overflow-x: auto;" tabindex="0" data-language="plaintext"><code><span class="line"><span>User call (getDoc, db.collection.get, etc.)</span></span>
+<span class="line"><span>  ↓</span></span>
+<span class="line"><span>Adapter translates to a generic Operation { method, path, auth, data? }</span></span>
+<span class="line"><span>  ↓</span></span>
+<span class="line"><span>LocalEnvironment.execute(operation)</span></span>
+<span class="line"><span>  ↓</span></span>
+<span class="line"><span>Simulator + LocalState + EventLog</span></span>
+<span class="line"><span>  ↓</span></span>
+<span class="line"><span>OperationResult { allowed, data?, debugMessages, event }</span></span>
+<span class="line"><span>  ↓</span></span>
+<span class="line"><span>Adapter translates back to user-facing types (QuerySnapshot, DocumentSnapshot, etc.)</span></span></code></pre>
+<p>The adapter is mostly translation. Each one does a few extra things to match its upstream SDK’s idiosyncrasies (<code>pyric-admin</code> constructs a per-call compatibility implementation to keep reference semantics right; <code>pyric/firestore</code> adapts the modular Web SDK shape), but the core flow is the same.</p>
+<p>This is what makes “the substrate is shared” workable. Both adapters bottom out at the same <code>LocalEnvironment</code> methods. Two contexts derived from one sandbox, one through <code>pyric-admin</code> and one through <code>pyric/firestore</code>, see the same data.</p>
+<h2 id="what-lives-where">What lives where</h2>
+<div class="table-scroll">
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+<table><thead><tr><th>Symbol / behaviour</th><th>Package</th></tr></thead><tbody><tr><td><code>Sandbox</code>, <code>SandboxContext</code>, <code>withAuth</code></td><td><code>pyric/sandbox</code></td></tr><tr><td><code>SandboxError</code>, denial channels</td><td><code>pyric/sandbox</code></td></tr><tr><td><code>LocalEnvironment</code> (raw substrate)</td><td><code>pyric/sandbox/internal</code></td></tr><tr><td>Admin-SDK-shaped Firestore API</td><td><code>pyric-admin</code></td></tr><tr><td>Modular Web SDK-shaped Firestore API</td><td><code>pyric/firestore</code></td></tr><tr><td>Rules parser, linter, simulator</td><td><code>pyric/rules/internal</code></td></tr><tr><td>Credentials for Rules Test API / verify</td><td><code>@pyric/cli/credentials/node</code></td></tr><tr><td>Production shipping (rules, indexes, hosting, functions)</td><td><code>firebase-tools</code> / Console</td></tr></tbody></table></div>
+<p>The rule of thumb: anything <em>shape-agnostic</em> (the data, the rules, the lifecycle) lives in the substrate; anything <em>shape-specific</em> lives in an adapter.</p>
+<h2 id="the-runtime-cycle">The runtime cycle</h2>
+<p><code>pyric/sandbox</code> imports the rules simulator from <code>pyric/rules/internal</code>. <code>pyric/rules</code> imports <code>LocalEnvironment</code> (type-only) from <code>pyric/sandbox/internal</code>. This is a module cycle inside the package graph.</p>
+<p>The cycle is benign: the import from <code>pyric/rules/internal</code> into <code>pyric/sandbox</code> is value (the <code>SimulateFirestoreRulesHandler</code> class and a handful of wrappers); the import from <code>pyric/sandbox</code> back into <code>pyric/rules</code> is type-only (the <code>LocalEnvironment</code> interface for the internal <code>createFirestoreSimulatorTools</code>’s <code>resolveSandbox</code> dep). Neither side is in the other’s runtime call graph beyond what’s documented.</p>
+<p>We accepted the cycle because the alternative, duplicating wrapper classes in both packages, would make <code>instanceof Timestamp</code> start lying depending on which copy was imported. The substrate consuming the simulator’s wrapper types is the canonical path.</p>
+<h2 id="future-adapters">Future adapters</h2>
+<p>The same pattern extends to other services. Hypothetical <code>pyric/auth</code> would:</p>
+<ul>
+<li>Depend on <code>pyric/sandbox</code>.</li>
+<li>Add an <code>Auth</code> service handle.</li>
+<li>Track auth state inside a future multi-service <code>LocalEnvironment</code>.</li>
+<li>Surface user-management APIs (<code>createUser</code>, <code>updateUser</code>) in the shape of <code>firebase-admin/auth</code> or <code>firebase/auth</code>.</li>
+</ul>
+<p>The substrate would need a multi-service split inside <code>LocalEnvironment</code> (currently Firestore-only) and the adapter would slot in.</p>
+<p>Same for <code>pyric/database</code> (Realtime Database) and <code>pyric/storage</code> (Cloud Storage). <code>pyric/storage</code> already exists for the storage data plane; its admin surface (<code>provisionStorage</code>, CORS helpers) lives on <code>pyric/storage</code>. Production Storage setup for real projects prefers <code>firebase-tools</code> / Console.</p>
+<p>The point of the sibling-package shape is that each new adapter is a contained addition. Nobody who already uses <code>pyric-admin</code> cares when <code>pyric/database</code> lands; the substrate gets a new service slot but the existing adapter surface doesn’t move.</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="#two-production-shapes-one-substrate">Two production shapes, one substrate</a> </li><li data-depth="2"> <a href="#why-not-bundle-everything">Why not bundle everything</a> </li><li data-depth="3"> <a href="#bundle-cost">Bundle cost</a> </li><li data-depth="3"> <a href="#conceptual-clutter">Conceptual clutter</a> </li><li data-depth="2"> <a href="#what-the-adapters-do">What the adapters do</a> </li><li data-depth="2"> <a href="#what-lives-where">What lives where</a> </li><li data-depth="2"> <a href="#the-runtime-cycle">The runtime cycle</a> </li><li data-depth="2"> <a href="#future-adapters">Future adapters</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-sandbox-explanation-why-adapters-are-siblings.md

@@ -0,0 +1,90 @@
+# Why service adapters live in sibling packages
+
+`pyric/sandbox` doesn't ship the data-plane API. The functions you actually call (`getDoc`, `setDoc`, `collection`, `onSnapshot`, `runTransaction`) live in `pyric-admin` (Admin-SDK-shaped) and `pyric/firestore` (modular Web-SDK-shaped). This page explains why.
+
+## Two production shapes, one substrate
+
+Firebase ships two Firestore SDKs that look quite different up close. Server / Admin / Cloud Functions code uses `firebase-admin/firestore`: chainable methods, class-shaped query builders, instance-bound operations. Browser / mobile / React Native code uses `firebase/firestore`: modular functions, function-bound queries, tree-shakable imports.
+
+Both are good APIs. Neither is a superset of the other. A package targeting both audiences has two reasonable choices:
+
+1. Pick one shape, force the other audience to translate.
+2. Ship both shapes over a shared substrate.
+
+We picked (2). The shared substrate is `pyric/sandbox`; the two shapes are `pyric-admin` and `pyric/firestore`.
+
+## Why not bundle everything
+
+A monorepo with one big `pyric/sandbox` that includes both APIs would work, mechanically. The reason not to is bundle cost and conceptual clutter.
+
+### Bundle cost
+
+A browser app that uses the modular Web SDK does not want the Admin-SDK shape in its bundle. These are more than different APIs. They have different opinions about what `Query` is, what a transaction's read/write API looks like, what reference identity means. If both surfaces live in one package, tree-shaking has to be perfect to avoid pulling in the unused shape. Tree-shaking in practice is "almost perfect", and "almost" hurts.
+
+Splitting into separate packages means the bundler doesn't have to be clever. The browser app imports `pyric/firestore`, and that's all the bundler sees.
+
+### Conceptual clutter
+
+The substrate's API surface (`Sandbox`, `SandboxContext`, listeners, lifecycle, error family) is small and stable. The data-plane API surfaces are large and follow upstream SDKs. Mixing them in one package would either bury the substrate in a sea of `getDoc`/`setDoc` exports or split into namespaces inside one package, which is sibling packages with extra steps.
+
+Keeping the split visible at the package level makes the dependency direction obvious: the data planes depend on the substrate, never the other way around.
+
+## What the adapters do
+
+Both adapters are thin. The pattern, abstracted:
+
+```
+User call (getDoc, db.collection.get, etc.)
+  ↓
+Adapter translates to a generic Operation { method, path, auth, data? }
+  ↓
+LocalEnvironment.execute(operation)
+  ↓
+Simulator + LocalState + EventLog
+  ↓
+OperationResult { allowed, data?, debugMessages, event }
+  ↓
+Adapter translates back to user-facing types (QuerySnapshot, DocumentSnapshot, etc.)
+```
+
+The adapter is mostly translation. Each one does a few extra things to match its upstream SDK's idiosyncrasies (`pyric-admin` constructs a per-call compatibility implementation to keep reference semantics right; `pyric/firestore` adapts the modular Web SDK shape), but the core flow is the same.
+
+This is what makes "the substrate is shared" workable. Both adapters bottom out at the same `LocalEnvironment` methods. Two contexts derived from one sandbox, one through `pyric-admin` and one through `pyric/firestore`, see the same data.
+
+## What lives where
+
+| Symbol / behaviour | Package |
+|---|---|
+| `Sandbox`, `SandboxContext`, `withAuth` | `pyric/sandbox` |
+| `SandboxError`, denial channels | `pyric/sandbox` |
+| `LocalEnvironment` (raw substrate) | `pyric/sandbox/internal` |
+| Admin-SDK-shaped Firestore API | `pyric-admin` |
+| Modular Web SDK-shaped Firestore API | `pyric/firestore` |
+| Rules parser, linter, simulator | `pyric/rules/internal` |
+| Credentials for Rules Test API / verify | `@pyric/cli/credentials/node` |
+| Production shipping (rules, indexes, hosting, functions) | `firebase-tools` / Console |
+
+The rule of thumb: anything *shape-agnostic* (the data, the rules, the lifecycle) lives in the substrate; anything *shape-specific* lives in an adapter.
+
+## The runtime cycle
+
+`pyric/sandbox` imports the rules simulator from `pyric/rules/internal`. `pyric/rules` imports `LocalEnvironment` (type-only) from `pyric/sandbox/internal`. This is a module cycle inside the package graph.
+
+The cycle is benign: the import from `pyric/rules/internal` into `pyric/sandbox` is value (the `SimulateFirestoreRulesHandler` class and a handful of wrappers); the import from `pyric/sandbox` back into `pyric/rules` is type-only (the `LocalEnvironment` interface for the internal `createFirestoreSimulatorTools`'s `resolveSandbox` dep). Neither side is in the other's runtime call graph beyond what's documented.
+
+We accepted the cycle because the alternative, duplicating wrapper classes in both packages, would make `instanceof Timestamp` start lying depending on which copy was imported. The substrate consuming the simulator's wrapper types is the canonical path.
+
+## Future adapters
+
+The same pattern extends to other services. Hypothetical `pyric/auth` would:
+
+- Depend on `pyric/sandbox`.
+- Add an `Auth` service handle.
+- Track auth state inside a future multi-service `LocalEnvironment`.
+- Surface user-management APIs (`createUser`, `updateUser`) in the shape of `firebase-admin/auth` or `firebase/auth`.
+
+The substrate would need a multi-service split inside `LocalEnvironment` (currently Firestore-only) and the adapter would slot in.
+
+Same for `pyric/database` (Realtime Database) and `pyric/storage` (Cloud Storage). `pyric/storage` already exists for the storage data plane; its admin surface (`provisionStorage`, CORS helpers) lives on `pyric/storage`. Production Storage setup for real projects prefers `firebase-tools` / Console.
+
+The point of the sibling-package shape is that each new adapter is a contained addition. Nobody who already uses `pyric-admin` cares when `pyric/database` lands; the substrate gets a new service slot but the existing adapter surface doesn't move.