@pyric/cli 0.1.0-alpha.9

package/dist/serve/docs-ui/docs/pyric-admin-firestore-explanation-per-call-delegate.md

@@ -0,0 +1,94 @@
+# Per-call delegate construction
+
+Every production-shaped method on `SandboxFirestore` constructs a fresh
+`Firestore` delegate from `pyric/sandbox/admin-firestore` per call. This page
+explains why and what it costs.
+
+## The pattern
+
+```ts
+function buildFirestoreHandle(ctx: SandboxContext): SandboxFirestore {
+  const delegate = (): Firestore =>
+    createCompatFirestore(getInternalEnv(ctx.sandbox), { auth: ctx.auth });
+
+  return {
+    collection(path) { return delegate().collection(path); },
+    doc(path)        { return delegate().doc(path); },
+    batch()          { return delegate().batch(); },
+    runTransaction(fn, _opts) { return delegate().runTransaction(fn); },
+    // ...
+  };
+}
+```
+
+Each method calls `delegate()` to get a fresh `Firestore` instance, then invokes the production-shaped method on it. The instance is constructed per call.
+
+## Why not cache one delegate
+
+The obvious alternative caches the delegate at handle-construction time:
+
+```ts
+// Naive version — broken.
+function buildFirestoreHandle(ctx: SandboxContext): SandboxFirestore {
+  const delegate = createCompatFirestore(getInternalEnv(ctx.sandbox), { auth: ctx.auth });
+  return {
+    collection(path) { return delegate.collection(path); },
+    // ...
+  };
+}
+```
+
+This is faster (one allocation instead of many) and broken in one specific case: `sandbox.reset()`.
+
+`Sandbox.reset()` swaps the underlying `LocalEnvironment` for a fresh one. Existing `SandboxContext`s continue to work. Their next operation resolves through `getEnv()` and finds the new environment. But a cached delegate would still be bound to the *old* environment. Operations through the cached delegate would land in a discarded environment that nobody else can see.
+
+Per-call construction reads `getInternalEnv(ctx.sandbox)` on every operation, so it always sees the current environment. `reset()` propagates for free.
+
+## What the cost is
+
+`createCompatFirestore` is essentially a constructor: it allocates a class instance, captures a reference to the env, captures the auth. No I/O, no network, no expensive computation. The cost is one allocation per operation.
+
+For comparison, a single Firestore `set` involves: serialising the payload, evaluating rules, walking the local state, appending to the event log, firing snapshot listeners. The delegate construction is a rounding error against any of these.
+
+We measured. It's not worth optimising.
+
+## What this means for refs
+
+`DocumentReference`, `CollectionReference`, `Query`, `WriteBatch`, `Transaction` objects returned from a delegate are bound to the *delegate*, which is bound to the env that was live when the delegate was constructed.
+
+In practice this means:
+
+- A `DocumentReference` obtained from `db.doc('notes/n1')` keeps working across normal operations.
+- A `DocumentReference` obtained before `sandbox.reset()` will, after the reset, operate against a discarded environment.
+
+The latter is a real edge case. Test code that holds refs across resets is unusual but happens. The fix is to re-acquire refs after reset:
+
+```ts
+beforeEach(() => {
+  sandbox.reset();
+  adminDb.setRules(RULES);
+  notesRef = adminDb.collection('notes');  // refresh
+});
+```
+
+The README and the `getFirestore` JSDoc both call this out: refs are bound to whichever environment was live when they were obtained.
+
+## Why this isn't a leak
+
+A naive reader might worry: "If every method constructs a delegate, are old delegates leaking?" No. Delegates are throwaway: they're constructed, used once, and become eligible for garbage collection. No long-lived references, no module-level state.
+
+The only thing that lives across operations is the `SandboxFirestore` handle itself, which is cached per-context in a `WeakMap`. When the context is garbage-collected, the handle goes with it.
+
+## The idempotency cache
+
+```ts
+const handleCache = new WeakMap<SandboxContext, SandboxFirestore>();
+```
+
+This is at the handle level, not the delegate level. The handle is cheap to keep (it's a small object with method references), and idempotency means `getFirestore(ctx)` returns the same object every time. Cached results from the first call (like the error-translation wrapping) don't get re-applied.
+
+The cache is a `WeakMap`, so a context that goes out of scope drops its handle automatically. No manual cleanup needed.
+
+## Where this leaves us
+
+The per-call delegate is the price we pay for `reset()` working transparently. It's a small price (one allocation per operation, no network), and the alternative (cached delegate, broken `reset`) creates a class of test bugs that are hard to diagnose. The trade is clearly worth it; this page exists so future maintainers don't try to "optimise" it.

package/dist/serve/docs-ui/docs/pyric-admin-firestore-explanation-why-mirror-admin-shape/index.html

@@ -0,0 +1,59 @@
+<!DOCTYPE html><html lang="en"> <head><meta charset="UTF-8"><meta name="viewport" content="width=device-width, initial-scale=1.0"><title>Why mirror the admin SDK shape · 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/"> 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/" aria-current="true"> 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/"> 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/" aria-current="true"> 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-admin-firestore/">pyric-admin / firestore</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 mirror the admin SDK</span> </li> </ol> </nav>  <article class="prose">  <h1 id="why-mirror-the-admin-sdk-shape">Why mirror the admin SDK shape</h1>
+<p><code>pyric-admin</code> re-implements the <code>firebase-admin/firestore</code> API. Same chainable style, same method names, same arguments, same return types. The behaviour is sandbox-aware (it talks to <code>pyric/sandbox</code> instead of Google’s servers), but the surface is faithful.</p>
+<p>This page explains why we mirrored an existing API instead of designing a new one.</p>
+<h2 id="the-principle">The principle</h2>
+<p>Test code should look like production code. Anything else is friction.</p>
+<p>A team writes a Cloud Function in <code>firebase-admin/firestore</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">async</span><span style="color:#C678DD"> function</span><span style="color:#61AFEF"> archiveOld</span><span style="color:#ABB2BF">(): </span><span style="color:#E5C07B">Promise</span><span style="color:#ABB2BF">&#x3C;</span><span style="color:#E5C07B">void</span><span style="color:#ABB2BF">> {</span></span>
+<span class="line"><span style="color:#C678DD">  const</span><span style="color:#E5C07B"> snapshot</span><span style="color:#56B6C2"> =</span><span style="color:#C678DD"> await</span><span style="color:#E06C75"> db</span></span>
+<span class="line"><span style="color:#ABB2BF">    .</span><span style="color:#61AFEF">collection</span><span style="color:#ABB2BF">(</span><span style="color:#98C379">'notes'</span><span style="color:#ABB2BF">)</span></span>
+<span class="line"><span style="color:#ABB2BF">    .</span><span style="color:#61AFEF">where</span><span style="color:#ABB2BF">(</span><span style="color:#98C379">'archived'</span><span style="color:#ABB2BF">, </span><span style="color:#98C379">'=='</span><span style="color:#ABB2BF">, </span><span style="color:#D19A66">false</span><span style="color:#ABB2BF">)</span></span>
+<span class="line"><span style="color:#ABB2BF">    .</span><span style="color:#61AFEF">where</span><span style="color:#ABB2BF">(</span><span style="color:#98C379">'lastSeen'</span><span style="color:#ABB2BF">, </span><span style="color:#98C379">'&#x3C;'</span><span style="color:#ABB2BF">, </span><span style="color:#E06C75">cutoff</span><span style="color:#ABB2BF">)</span></span>
+<span class="line"><span style="color:#ABB2BF">    .</span><span style="color:#61AFEF">get</span><span style="color:#ABB2BF">();</span></span>
+<span class="line"><span style="color:#C678DD">  const</span><span style="color:#E5C07B"> batch</span><span style="color:#56B6C2"> =</span><span style="color:#E5C07B"> db</span><span style="color:#ABB2BF">.</span><span style="color:#61AFEF">batch</span><span style="color:#ABB2BF">();</span></span>
+<span class="line"><span style="color:#E5C07B">  snapshot</span><span style="color:#ABB2BF">.</span><span style="color:#E5C07B">docs</span><span style="color:#ABB2BF">.</span><span style="color:#61AFEF">forEach</span><span style="color:#ABB2BF">((</span><span style="color:#E06C75;font-style:italic">doc</span><span style="color:#ABB2BF">) </span><span style="color:#C678DD">=></span><span style="color:#E5C07B"> batch</span><span style="color:#ABB2BF">.</span><span style="color:#61AFEF">update</span><span style="color:#ABB2BF">(</span><span style="color:#E5C07B">doc</span><span style="color:#ABB2BF">.</span><span style="color:#E06C75">ref</span><span style="color:#ABB2BF">, { </span><span style="color:#E06C75">archived</span><span style="color:#ABB2BF">: </span><span style="color:#D19A66">true</span><span style="color:#ABB2BF"> }));</span></span>
+<span class="line"><span style="color:#C678DD">  await</span><span style="color:#E5C07B"> batch</span><span style="color:#ABB2BF">.</span><span style="color:#61AFEF">commit</span><span style="color:#ABB2BF">();</span></span>
+<span class="line"><span style="color:#ABB2BF">}</span></span></code></pre>
+<p>The test for that function should look identical except for how <code>db</code> is obtained:</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:#7F848E;font-style:italic">// Production</span></span>
+<span class="line"><span style="color:#C678DD">const</span><span style="color:#E5C07B"> db</span><span style="color:#56B6C2"> =</span><span style="color:#61AFEF"> getFirestoreAdmin</span><span style="color:#ABB2BF">();</span></span>
+<span class="line"></span>
+<span class="line"><span style="color:#7F848E;font-style:italic">// Test</span></span>
+<span class="line"><span style="color:#C678DD">const</span><span style="color:#E5C07B"> db</span><span style="color:#56B6C2"> =</span><span style="color:#61AFEF"> getFirestore</span><span style="color:#ABB2BF">(</span><span style="color:#E5C07B">sandbox</span><span style="color:#ABB2BF">.</span><span style="color:#61AFEF">withAuth</span><span style="color:#ABB2BF">({ </span><span style="color:#E06C75">uid</span><span style="color:#ABB2BF">: </span><span style="color:#98C379">'admin'</span><span style="color:#ABB2BF">, </span><span style="color:#E06C75">token</span><span style="color:#ABB2BF">: { </span><span style="color:#E06C75">admin</span><span style="color:#ABB2BF">: </span><span style="color:#D19A66">true</span><span style="color:#ABB2BF"> } }));</span></span></code></pre>
+<p>That’s the shape we picked. Anything beyond the <code>db =</code> line is the same code in both contexts. Test code that imports from <code>pyric-admin</code> works against the sandbox today and against <code>firebase-admin/firestore</code> tomorrow if you swap the import.</p>
+<h2 id="what-we-considered">What we considered</h2>
+<h3 id="a-simpler-api-for-tests-only">A simpler API for tests only</h3>
+<p>We could have designed a small, opinionated test-only API:</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:#7F848E;font-style:italic">// Hypothetical, not the actual API.</span></span>
+<span class="line"><span style="color:#C678DD">await</span><span style="color:#E5C07B"> sandbox</span><span style="color:#ABB2BF">.</span><span style="color:#61AFEF">write</span><span style="color:#ABB2BF">(</span><span style="color:#98C379">'notes/n1'</span><span style="color:#ABB2BF">, { </span><span style="color:#E06C75">ownerId</span><span style="color:#ABB2BF">: </span><span style="color:#98C379">'alice'</span><span style="color:#ABB2BF"> });</span></span>
+<span class="line"><span style="color:#C678DD">const</span><span style="color:#E5C07B"> data</span><span style="color:#56B6C2"> =</span><span style="color:#C678DD"> await</span><span style="color:#E5C07B"> sandbox</span><span style="color:#ABB2BF">.</span><span style="color:#61AFEF">read</span><span style="color:#ABB2BF">(</span><span style="color:#98C379">'notes/n1'</span><span style="color:#ABB2BF">, { </span><span style="color:#E06C75">as</span><span style="color:#ABB2BF">: </span><span style="color:#98C379">'alice'</span><span style="color:#ABB2BF"> });</span></span></code></pre>
+<p>Shorter. Easier to learn. Fundamentally different from production code.</p>
+<p>The problem is that “test the shape of your production code” has a different goal from “express a test scenario concisely”. Production code has methods (<code>add</code>, <code>update</code>, <code>set</code>, <code>delete</code>), arguments (<code>where</code>, <code>orderBy</code>, <code>limit</code>), return types (<code>QuerySnapshot.docChanges()</code>). The test API that elides those forces test authors to mentally translate. The translation is where bugs hide.</p>
+<h3 id="a-type-only-wrapper-over-the-simulator">A type-only wrapper over the simulator</h3>
+<p>Another option: ship raw types and let consumers wire up a translation layer themselves. We rejected it because every consumer would do the same translation, with subtle differences. Bugs would compound.</p>
+<h3 id="a-firebase-admin-peer-dependency">A <code>firebase-admin</code> peer dependency</h3>
+<p>We could have made <code>firebase-admin/firestore</code> a peer dep and provided a connector. We didn’t because:</p>
+<ul>
+<li><code>firebase-admin</code> is a Node-only package, which would forbid browser use.</li>
+<li>The dep graph is heavy. Pulling in 50+ MB of <code>firebase-admin</code> for a test runner is unwelcome.</li>
+<li>The compat impl in <code>pyric/sandbox/admin-firestore</code> is browser-safe. Reusing
+it gives us the same surface without pulling <code>firebase-admin</code> into sandbox
+test runners.</li>
+</ul>
+<h2 id="what-we-add-on-top">What we add on top</h2>
+<p>Three sandbox-only methods on the handle:</p>
+<ul>
+<li><code>setRules(rules)</code>: replace the active ruleset.</li>
+<li><code>seed({ documents })</code>: replace stored documents.</li>
+<li><code>snapshot()</code>: read all stored documents.</li>
+</ul>
+<p>These have no production analog. We picked sandbox-flavoured verbs (<code>setRules</code>, <code>seed</code>, <code>snapshot</code>) so a reader can’t confuse them with deployment operations. <code>db.deploy(...)</code> would have been the most natural-feeling name for <code>setRules</code>, but it would also have invited “did this hit production?” panic.</p>
+<h2 id="what-we-dont-add">What we don’t add</h2>
+<ul>
+<li>No per-call <code>auth</code> override. Identity is per-context; the handle is bound at construction. See <a href="../pyric-sandbox-explanation-identity-is-a-context/">Identity is a context, not a sandbox</a>.</li>
+<li>No alternative APIs that change semantics. The shape exists to mirror production; second-guessing it would defeat the point.</li>
+<li>No “test helpers” embedded in the handle. The <code>WriteBatch</code> is a <code>WriteBatch</code>, not a <code>WriteBatch &#x26; TestUtilities</code>. If you need test affordances, build them as a wrapper around the handle.</li>
+</ul>
+<h2 id="where-this-leaves-us">Where this leaves us</h2>
+<p>A test file that imports <code>pyric-admin</code> reads like a Cloud Function. Production code that someday becomes a test fixture works without changes. The transition between writing production code and writing tests for it is invisible at the API level.</p>
+<p>That’s worth more than any minor convenience a custom API would have offered.</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-principle">The principle</a> </li><li data-depth="2"> <a href="#what-we-considered">What we considered</a> </li><li data-depth="3"> <a href="#a-simpler-api-for-tests-only">A simpler API for tests only</a> </li><li data-depth="3"> <a href="#a-type-only-wrapper-over-the-simulator">A type-only wrapper over the simulator</a> </li><li data-depth="3"> <a href="#a-firebase-admin-peer-dependency">A firebase-admin peer dependency</a> </li><li data-depth="2"> <a href="#what-we-add-on-top">What we add on top</a> </li><li data-depth="2"> <a href="#what-we-dont-add">What we don’t add</a> </li><li data-depth="2"> <a href="#where-this-leaves-us">Where this leaves us</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-admin-firestore-explanation-why-mirror-admin-shape.md

@@ -0,0 +1,88 @@
+# Why mirror the admin SDK shape
+
+`pyric-admin` re-implements the `firebase-admin/firestore` API. Same chainable style, same method names, same arguments, same return types. The behaviour is sandbox-aware (it talks to `pyric/sandbox` instead of Google's servers), but the surface is faithful.
+
+This page explains why we mirrored an existing API instead of designing a new one.
+
+## The principle
+
+Test code should look like production code. Anything else is friction.
+
+A team writes a Cloud Function in `firebase-admin/firestore`:
+
+```ts
+async function archiveOld(): Promise<void> {
+  const snapshot = await db
+    .collection('notes')
+    .where('archived', '==', false)
+    .where('lastSeen', '<', cutoff)
+    .get();
+  const batch = db.batch();
+  snapshot.docs.forEach((doc) => batch.update(doc.ref, { archived: true }));
+  await batch.commit();
+}
+```
+
+The test for that function should look identical except for how `db` is obtained:
+
+```ts
+// Production
+const db = getFirestoreAdmin();
+
+// Test
+const db = getFirestore(sandbox.withAuth({ uid: 'admin', token: { admin: true } }));
+```
+
+That's the shape we picked. Anything beyond the `db =` line is the same code in both contexts. Test code that imports from `pyric-admin` works against the sandbox today and against `firebase-admin/firestore` tomorrow if you swap the import.
+
+## What we considered
+
+### A simpler API for tests only
+
+We could have designed a small, opinionated test-only API:
+
+```ts
+// Hypothetical, not the actual API.
+await sandbox.write('notes/n1', { ownerId: 'alice' });
+const data = await sandbox.read('notes/n1', { as: 'alice' });
+```
+
+Shorter. Easier to learn. Fundamentally different from production code.
+
+The problem is that "test the shape of your production code" has a different goal from "express a test scenario concisely". Production code has methods (`add`, `update`, `set`, `delete`), arguments (`where`, `orderBy`, `limit`), return types (`QuerySnapshot.docChanges()`). The test API that elides those forces test authors to mentally translate. The translation is where bugs hide.
+
+### A type-only wrapper over the simulator
+
+Another option: ship raw types and let consumers wire up a translation layer themselves. We rejected it because every consumer would do the same translation, with subtle differences. Bugs would compound.
+
+### A `firebase-admin` peer dependency
+
+We could have made `firebase-admin/firestore` a peer dep and provided a connector. We didn't because:
+
+- `firebase-admin` is a Node-only package, which would forbid browser use.
+- The dep graph is heavy. Pulling in 50+ MB of `firebase-admin` for a test runner is unwelcome.
+- The compat impl in `pyric/sandbox/admin-firestore` is browser-safe. Reusing
+  it gives us the same surface without pulling `firebase-admin` into sandbox
+  test runners.
+
+## What we add on top
+
+Three sandbox-only methods on the handle:
+
+- `setRules(rules)`: replace the active ruleset.
+- `seed({ documents })`: replace stored documents.
+- `snapshot()`: read all stored documents.
+
+These have no production analog. We picked sandbox-flavoured verbs (`setRules`, `seed`, `snapshot`) so a reader can't confuse them with deployment operations. `db.deploy(...)` would have been the most natural-feeling name for `setRules`, but it would also have invited "did this hit production?" panic.
+
+## What we don't add
+
+- No per-call `auth` override. Identity is per-context; the handle is bound at construction. See [Identity is a context, not a sandbox](../pyric-sandbox-explanation-identity-is-a-context/).
+- No alternative APIs that change semantics. The shape exists to mirror production; second-guessing it would defeat the point.
+- No "test helpers" embedded in the handle. The `WriteBatch` is a `WriteBatch`, not a `WriteBatch & TestUtilities`. If you need test affordances, build them as a wrapper around the handle.
+
+## Where this leaves us
+
+A test file that imports `pyric-admin` reads like a Cloud Function. Production code that someday becomes a test fixture works without changes. The transition between writing production code and writing tests for it is invisible at the API level.
+
+That's worth more than any minor convenience a custom API would have offered.

package/dist/serve/docs-ui/docs/pyric-admin-firestore-how-to-run-a-transaction/index.html

@@ -0,0 +1,53 @@
+<!DOCTYPE html><html lang="en"> <head><meta charset="UTF-8"><meta name="viewport" content="width=device-width, initial-scale=1.0"><title>How to run a transaction · 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/"> 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/" aria-current="true"> 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/"> 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/" aria-current="true"> 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-admin-firestore/">pyric-admin / firestore</a> </li><li> <span class="docs-breadcrumbs-sep" aria-hidden="true">/</span> <span>How-to</span> </li><li> <span class="docs-breadcrumbs-sep" aria-hidden="true">/</span> <span aria-current="page">Run a transaction</span> </li> </ol> </nav>  <article class="prose">  <h1 id="how-to-run-a-transaction">How to run a transaction</h1>
+<p>This guide shows you how to use <code>runTransaction</code> on a sandbox Firestore handle.</p>
+<h2 id="the-shape">The shape</h2>
+<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">getFirestore</span><span style="color:#ABB2BF"> } </span><span style="color:#C678DD">from</span><span style="color:#98C379"> 'pyric-admin'</span><span style="color:#ABB2BF">;</span></span>
+<span class="line"></span>
+<span class="line"><span style="color:#C678DD">const</span><span style="color:#E5C07B"> db</span><span style="color:#56B6C2"> =</span><span style="color:#61AFEF"> getFirestore</span><span style="color:#ABB2BF">(</span><span style="color:#E5C07B">sandbox</span><span style="color:#ABB2BF">.</span><span style="color:#61AFEF">withAuth</span><span style="color:#ABB2BF">({ </span><span style="color:#E06C75">uid</span><span style="color:#ABB2BF">: </span><span style="color:#98C379">'alice'</span><span style="color:#ABB2BF"> }));</span></span>
+<span class="line"></span>
+<span class="line"><span style="color:#C678DD">const</span><span style="color:#E5C07B"> result</span><span style="color:#56B6C2"> =</span><span style="color:#C678DD"> await</span><span style="color:#E5C07B"> db</span><span style="color:#ABB2BF">.</span><span style="color:#61AFEF">runTransaction</span><span style="color:#ABB2BF">(</span><span style="color:#C678DD">async</span><span style="color:#ABB2BF"> (</span><span style="color:#E06C75;font-style:italic">tx</span><span style="color:#ABB2BF">) </span><span style="color:#C678DD">=></span><span style="color:#ABB2BF"> {</span></span>
+<span class="line"><span style="color:#C678DD">  const</span><span style="color:#E5C07B"> snap</span><span style="color:#56B6C2"> =</span><span style="color:#C678DD"> await</span><span style="color:#E5C07B"> tx</span><span style="color:#ABB2BF">.</span><span style="color:#61AFEF">get</span><span style="color:#ABB2BF">(</span><span style="color:#E5C07B">db</span><span style="color:#ABB2BF">.</span><span style="color:#61AFEF">doc</span><span style="color:#ABB2BF">(</span><span style="color:#98C379">'counters/main'</span><span style="color:#ABB2BF">));</span></span>
+<span class="line"><span style="color:#C678DD">  const</span><span style="color:#E5C07B"> current</span><span style="color:#56B6C2"> =</span><span style="color:#E5C07B"> snap</span><span style="color:#ABB2BF">.</span><span style="color:#E06C75">exists</span><span style="color:#C678DD"> ?</span><span style="color:#E5C07B"> snap</span><span style="color:#ABB2BF">.</span><span style="color:#61AFEF">data</span><span style="color:#ABB2BF">().</span><span style="color:#E06C75">count</span><span style="color:#C678DD"> :</span><span style="color:#D19A66"> 0</span><span style="color:#ABB2BF">;</span></span>
+<span class="line"><span style="color:#E5C07B">  tx</span><span style="color:#ABB2BF">.</span><span style="color:#61AFEF">set</span><span style="color:#ABB2BF">(</span><span style="color:#E5C07B">db</span><span style="color:#ABB2BF">.</span><span style="color:#61AFEF">doc</span><span style="color:#ABB2BF">(</span><span style="color:#98C379">'counters/main'</span><span style="color:#ABB2BF">), { </span><span style="color:#E06C75">count</span><span style="color:#ABB2BF">: </span><span style="color:#E06C75">current</span><span style="color:#56B6C2"> +</span><span style="color:#D19A66"> 1</span><span style="color:#ABB2BF"> });</span></span>
+<span class="line"><span style="color:#C678DD">  return</span><span style="color:#E06C75"> current</span><span style="color:#56B6C2"> +</span><span style="color:#D19A66"> 1</span><span style="color:#ABB2BF">;</span></span>
+<span class="line"><span style="color:#ABB2BF">});</span></span></code></pre>
+<p>The callback receives a <code>Transaction</code> object with <code>.get</code>, <code>.getAll</code>, <code>.set</code>, <code>.update</code>, <code>.delete</code>, <code>.create</code>. All reads must happen before any writes: read-after-write inside a tx throws <code>'failed-precondition'</code>.</p>
+<h2 id="read-tracking">Read tracking</h2>
+<p>The sandbox tracks every doc the callback reads. On commit:</p>
+<ul>
+<li>If any read doc was written by anyone else between the read and the commit, the transaction would (in production) retry. The sandbox is synchronous, so this can’t actually happen, but reads are still recorded for diagnostic value.</li>
+<li>If the callback itself reads a doc after writing to it, the second read throws <code>'failed-precondition'</code>. This matches production’s read-after-write rule.</li>
+<li>If the callback writes to a doc and then deletes the same doc within the same tx, the simulator handles the ordering correctly.</li>
+</ul>
+<p>The recorded reads are available on the event log via <code>getInternalEnv(sandbox).getEventLog().getEvents()</code>: each transaction event carries a <code>reads</code> array.</p>
+<h2 id="aborted-transactions">Aborted transactions</h2>
+<p>If the callback throws, the transaction is aborted: no writes are applied, the event log records the abort with the thrown error, and the original error re-throws to the caller:</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">try</span><span style="color:#ABB2BF"> {</span></span>
+<span class="line"><span style="color:#C678DD">  await</span><span style="color:#E5C07B"> db</span><span style="color:#ABB2BF">.</span><span style="color:#61AFEF">runTransaction</span><span style="color:#ABB2BF">(</span><span style="color:#C678DD">async</span><span style="color:#ABB2BF"> (</span><span style="color:#E06C75;font-style:italic">tx</span><span style="color:#ABB2BF">) </span><span style="color:#C678DD">=></span><span style="color:#ABB2BF"> {</span></span>
+<span class="line"><span style="color:#C678DD">    const</span><span style="color:#E5C07B"> snap</span><span style="color:#56B6C2"> =</span><span style="color:#C678DD"> await</span><span style="color:#E5C07B"> tx</span><span style="color:#ABB2BF">.</span><span style="color:#61AFEF">get</span><span style="color:#ABB2BF">(</span><span style="color:#E5C07B">db</span><span style="color:#ABB2BF">.</span><span style="color:#61AFEF">doc</span><span style="color:#ABB2BF">(</span><span style="color:#98C379">'counters/main'</span><span style="color:#ABB2BF">));</span></span>
+<span class="line"><span style="color:#C678DD">    if</span><span style="color:#ABB2BF"> (</span><span style="color:#56B6C2">!</span><span style="color:#E5C07B">snap</span><span style="color:#ABB2BF">.</span><span style="color:#E06C75">exists</span><span style="color:#ABB2BF">) </span><span style="color:#C678DD">throw</span><span style="color:#C678DD"> new</span><span style="color:#61AFEF"> Error</span><span style="color:#ABB2BF">(</span><span style="color:#98C379">'counter missing'</span><span style="color:#ABB2BF">);</span></span>
+<span class="line"><span style="color:#E5C07B">    tx</span><span style="color:#ABB2BF">.</span><span style="color:#61AFEF">set</span><span style="color:#ABB2BF">(</span><span style="color:#E5C07B">db</span><span style="color:#ABB2BF">.</span><span style="color:#61AFEF">doc</span><span style="color:#ABB2BF">(</span><span style="color:#98C379">'counters/main'</span><span style="color:#ABB2BF">), { </span><span style="color:#E06C75">count</span><span style="color:#ABB2BF">: </span><span style="color:#E5C07B">snap</span><span style="color:#ABB2BF">.</span><span style="color:#61AFEF">data</span><span style="color:#ABB2BF">().</span><span style="color:#E06C75">count</span><span style="color:#56B6C2"> +</span><span style="color:#D19A66"> 1</span><span style="color:#ABB2BF"> });</span></span>
+<span class="line"><span style="color:#ABB2BF">  });</span></span>
+<span class="line"><span style="color:#ABB2BF">} </span><span style="color:#C678DD">catch</span><span style="color:#ABB2BF"> (</span><span style="color:#E06C75">e</span><span style="color:#ABB2BF">) {</span></span>
+<span class="line"><span style="color:#E5C07B">  console</span><span style="color:#ABB2BF">.</span><span style="color:#61AFEF">error</span><span style="color:#ABB2BF">(</span><span style="color:#98C379">'Transaction aborted:'</span><span style="color:#ABB2BF">, </span><span style="color:#E5C07B">e</span><span style="color:#ABB2BF">.</span><span style="color:#E06C75">message</span><span style="color:#ABB2BF">);</span></span>
+<span class="line"><span style="color:#ABB2BF">}</span></span></code></pre>
+<p>Aborted transactions are <strong>not undoable</strong>. Popping one as an undo step would skip a real prior write, so the sandbox refuses to treat them as undoable events.</p>
+<h2 id="denied-operations-inside-a-transaction">Denied operations inside a transaction</h2>
+<p>If a <code>tx.set</code> would deny under the current rules, the transaction aborts with <code>SandboxError('permission-denied')</code>. The <code>denialContext</code> is populated with the request/resource shapes for the denied operation, matching how a single-operation denial looks.</p>
+<h2 id="cross-context-transactions-are-not-allowed">Cross-context transactions are not allowed</h2>
+<p>A transaction’s auth is the registering context’s auth, captured at <code>runTransaction</code> call time. You cannot pass per-call auth or switch identity mid-transaction. To act as a different user, derive a different context:</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"> adminDb</span><span style="color:#56B6C2"> =</span><span style="color:#61AFEF"> getFirestore</span><span style="color:#ABB2BF">(</span><span style="color:#E5C07B">sandbox</span><span style="color:#ABB2BF">.</span><span style="color:#61AFEF">withAuth</span><span style="color:#ABB2BF">({ </span><span style="color:#E06C75">uid</span><span style="color:#ABB2BF">: </span><span style="color:#98C379">'admin'</span><span style="color:#ABB2BF">, </span><span style="color:#E06C75">token</span><span style="color:#ABB2BF">: { </span><span style="color:#E06C75">admin</span><span style="color:#ABB2BF">: </span><span style="color:#D19A66">true</span><span style="color:#ABB2BF"> } }));</span></span>
+<span class="line"><span style="color:#C678DD">await</span><span style="color:#E5C07B"> adminDb</span><span style="color:#ABB2BF">.</span><span style="color:#61AFEF">runTransaction</span><span style="color:#ABB2BF">(</span><span style="color:#C678DD">async</span><span style="color:#ABB2BF"> (</span><span style="color:#E06C75;font-style:italic">tx</span><span style="color:#ABB2BF">) </span><span style="color:#C678DD">=></span><span style="color:#ABB2BF"> { </span><span style="color:#7F848E;font-style:italic">/* runs as admin */</span><span style="color:#ABB2BF"> });</span></span></code></pre>
+<h2 id="when-runtransaction-is-overkill">When <code>runTransaction</code> is overkill</h2>
+<p>For single-doc operations with no read dependency, plain <code>set</code> / <code>update</code> / <code>delete</code> is fine. Reach for <code>runTransaction</code> when:</p>
+<ul>
+<li>You need to read-then-write on the same document atomically.</li>
+<li>You need to write across multiple documents that depend on each other’s values.</li>
+<li>You want production-shaped read tracking in your event log.</li>
+</ul>
+<p>For multi-doc writes that don’t need read-then-write semantics, use a <code>WriteBatch</code> instead. See <a href="../pyric-admin-firestore-how-to-write-a-batch/">Write a batch</a>.</p>
+<h2 id="where-to-look-next">Where to look next</h2>
+<ul>
+<li>For the production-shaped <code>Transaction</code> API, see the <a href="https://firebase.google.com/docs/reference/admin/node/firebase-admin.firestore.transaction" target="_blank" rel="noopener noreferrer" class="external-link">Firebase admin SDK docs</a>.</li>
+<li>For the substrate’s read-tracking behaviour, see <a href="../pyric-sandbox-reference-internal-protocol/"><code>pyric/sandbox</code>’s internal protocol</a>.</li>
+</ul>  </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-shape">The shape</a> </li><li data-depth="2"> <a href="#read-tracking">Read tracking</a> </li><li data-depth="2"> <a href="#aborted-transactions">Aborted transactions</a> </li><li data-depth="2"> <a href="#denied-operations-inside-a-transaction">Denied operations inside a transaction</a> </li><li data-depth="2"> <a href="#cross-context-transactions-are-not-allowed">Cross-context transactions are not allowed</a> </li><li data-depth="2"> <a href="#when-runtransaction-is-overkill">When runTransaction is overkill</a> </li><li data-depth="2"> <a href="#where-to-look-next">Where to look 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/pyric-admin-firestore-how-to-run-a-transaction.md

@@ -0,0 +1,76 @@
+# How to run a transaction
+
+This guide shows you how to use `runTransaction` on a sandbox Firestore handle.
+
+## The shape
+
+```ts
+import { getFirestore } from 'pyric-admin';
+
+const db = getFirestore(sandbox.withAuth({ uid: 'alice' }));
+
+const result = await db.runTransaction(async (tx) => {
+  const snap = await tx.get(db.doc('counters/main'));
+  const current = snap.exists ? snap.data().count : 0;
+  tx.set(db.doc('counters/main'), { count: current + 1 });
+  return current + 1;
+});
+```
+
+The callback receives a `Transaction` object with `.get`, `.getAll`, `.set`, `.update`, `.delete`, `.create`. All reads must happen before any writes: read-after-write inside a tx throws `'failed-precondition'`.
+
+## Read tracking
+
+The sandbox tracks every doc the callback reads. On commit:
+
+- If any read doc was written by anyone else between the read and the commit, the transaction would (in production) retry. The sandbox is synchronous, so this can't actually happen, but reads are still recorded for diagnostic value.
+- If the callback itself reads a doc after writing to it, the second read throws `'failed-precondition'`. This matches production's read-after-write rule.
+- If the callback writes to a doc and then deletes the same doc within the same tx, the simulator handles the ordering correctly.
+
+The recorded reads are available on the event log via `getInternalEnv(sandbox).getEventLog().getEvents()`: each transaction event carries a `reads` array.
+
+## Aborted transactions
+
+If the callback throws, the transaction is aborted: no writes are applied, the event log records the abort with the thrown error, and the original error re-throws to the caller:
+
+```ts
+try {
+  await db.runTransaction(async (tx) => {
+    const snap = await tx.get(db.doc('counters/main'));
+    if (!snap.exists) throw new Error('counter missing');
+    tx.set(db.doc('counters/main'), { count: snap.data().count + 1 });
+  });
+} catch (e) {
+  console.error('Transaction aborted:', e.message);
+}
+```
+
+Aborted transactions are **not undoable**. Popping one as an undo step would skip a real prior write, so the sandbox refuses to treat them as undoable events.
+
+## Denied operations inside a transaction
+
+If a `tx.set` would deny under the current rules, the transaction aborts with `SandboxError('permission-denied')`. The `denialContext` is populated with the request/resource shapes for the denied operation, matching how a single-operation denial looks.
+
+## Cross-context transactions are not allowed
+
+A transaction's auth is the registering context's auth, captured at `runTransaction` call time. You cannot pass per-call auth or switch identity mid-transaction. To act as a different user, derive a different context:
+
+```ts
+const adminDb = getFirestore(sandbox.withAuth({ uid: 'admin', token: { admin: true } }));
+await adminDb.runTransaction(async (tx) => { /* runs as admin */ });
+```
+
+## When `runTransaction` is overkill
+
+For single-doc operations with no read dependency, plain `set` / `update` / `delete` is fine. Reach for `runTransaction` when:
+
+- You need to read-then-write on the same document atomically.
+- You need to write across multiple documents that depend on each other's values.
+- You want production-shaped read tracking in your event log.
+
+For multi-doc writes that don't need read-then-write semantics, use a `WriteBatch` instead. See [Write a batch](../pyric-admin-firestore-how-to-write-a-batch/).
+
+## Where to look next
+
+- For the production-shaped `Transaction` API, see the [Firebase admin SDK docs](https://firebase.google.com/docs/reference/admin/node/firebase-admin.firestore.transaction).
+- For the substrate's read-tracking behaviour, see [`pyric/sandbox`'s internal protocol](../pyric-sandbox-reference-internal-protocol/).