@pyric/cli 0.1.0-alpha.9

package/dist/serve/docs-ui/docs/pyric-sandbox-how-to-observe-events.md

@@ -0,0 +1,168 @@
+# How to observe sandbox events
+
+One subscription covers everything observable. `sandbox.onEvent(cb)` fires a [`SandboxEvent`](../pyric-sandbox-reference-sandbox-event/) for every rule evaluation, every committed write, every snapshot delivered to a listener callback, every suppressed re-eval, every listener attach / detach / errored, and every reset / dispose boundary. Filter on `event.kind` to recover whichever slice your code cares about.
+
+## When to use which kind
+
+| You want to | Filter for |
+|---|---|
+| Surface denials in a banner / toast | `kind === 'request' && result === 'deny'` |
+| Render a "Network panel"-style traffic monitor | `kind === 'request'` |
+| Log every committed write for forensic replay | `kind === 'write'` |
+| Render a snapshot listener's deliveries | `kind === 'snapshot_delivery'` |
+| Investigate "why didn't my listener fire" | `kind === 'snapshot_suppressed'` |
+| Track listener lifecycle (attach / detach / errored) | `kind` starts with `'listener_'` |
+| Segment a persisted stream around `reset()` / `dispose()` | `kind === 'session_boundary'` |
+| Measure rule-engine eval cost | `kind === 'request'`, read `evalMs` |
+| Attribute a listener re-eval to the originating write | `kind === 'snapshot_delivery'`, read `triggeredBy` |
+
+## Subscribe
+
+```ts
+import { initializeSandbox, type SandboxEvent } from 'pyric/sandbox';
+
+const sandbox = initializeSandbox();
+const events: SandboxEvent[] = [];
+
+const unsubscribe = sandbox.onEvent((event) => events.push(event));
+
+// ... later:
+unsubscribe();
+```
+
+The subscription **survives `sandbox.reset()`**. The underlying environment swaps but the user callback stays in the sandbox-level registry. A `session_boundary` event with `phase: 'reset'` fires immediately before the swap so consumers can segment their stream. On `sandbox.dispose()` the boundary fires once with `phase: 'dispose'` and the registry clears.
+
+## Render a traffic panel
+
+```tsx
+function TrafficPanel() {
+  const [events, setEvents] = useState<SandboxEvent[]>([]);
+  useEffect(() => {
+    return sandbox.onEvent((ev) => {
+      setEvents((prev) => {
+        // Cap the in-memory buffer — see "Volume" below.
+        const next = prev.length >= 5000 ? prev.slice(-4999) : prev.slice();
+        next.push(ev);
+        return next;
+      });
+    });
+  }, []);
+
+  return (
+    <ul>
+      {events.filter((e) => e.kind === 'request').map((r) => (
+        <li key={r.id}>
+          <Badge tone={r.result === 'allow' ? 'green' : 'red'}>{r.result}</Badge>
+          <code>{r.method} {r.path}</code>
+          <span>{r.auth?.uid ?? 'null'}</span>
+          <span>{r.evalMs.toFixed(1)}ms</span>
+        </li>
+      ))}
+    </ul>
+  );
+}
+```
+
+## Derive denials as a filter
+
+The previous `onDenial` channel is gone. Denials are a one-line filter:
+
+```ts
+const unsubscribe = sandbox.onEvent((event) => {
+  if (event.kind !== 'request' || event.result !== 'deny') return;
+  showBanner(`${event.method} ${event.path} denied`);
+});
+```
+
+The same `request` event carries `auth`, `reasons`, `request.resourceData`, and `resourceBefore`: every field the old `DenialEvent` carried, plus the per-eval `evalMs` the request channel always had.
+
+## Capture snapshot deliveries
+
+`onRequest` used to fire one listener-origin event per write that touched a watched path, even when the listener's diff-check determined the result was identical to the prior snapshot. That over-counted: consumers saw "the listener was woken up", not "the listener delivered to user code". The new `snapshot_delivery` and `snapshot_suppressed` events disambiguate.
+
+```ts
+sandbox.onEvent((event) => {
+  if (event.kind === 'snapshot_delivery') {
+    console.log(
+      `listener ${event.listenerId} delivered: ` +
+      `+${event.addedCount} ~${event.modifiedCount} -${event.removedCount} ` +
+      `(size=${event.size})`,
+    );
+  } else if (event.kind === 'snapshot_suppressed') {
+    console.log(`listener ${event.listenerId} woke up but had nothing to deliver`);
+  }
+});
+```
+
+The initial-fire event (when a listener attaches) emits `snapshot_delivery` with every existing doc as `added` and no `triggeredBy`. Write-driven re-evals carry `triggeredBy: { method, path }`.
+
+## Track listener lifecycle
+
+```ts
+sandbox.onEvent((event) => {
+  if (event.kind === 'listener_attach') console.log(`+ ${event.target.kind}: ${describe(event.target)}`);
+  else if (event.kind === 'listener_detach') console.log(`- ${event.listenerId}`);
+  else if (event.kind === 'listener_errored') console.log(`! ${event.listenerId}: ${event.error?.message}`);
+});
+```
+
+Attach fires once before the initial-snapshot delivery. Detach fires when the returned unsubscribe is called against a still-registered listener (idempotent calls don't double-emit; listeners dropped by `reset()` don't emit detach, the `session_boundary` event covers the rollover). Errored fires when a stream-level rule denial silently terminates the listener.
+
+## Volume: default-hide listener re-evals
+
+Per the issue #307 probe data: a query listener can re-evaluate on every write to its collection. With N existing docs and N writes, the upper bound is O(N²) re-evals. The `snapshot_delivery` count tracks actual user-callback invocations, much smaller than the raw re-eval count. Use `kind: 'snapshot_delivery'` events (rather than `kind: 'request' && origin: 'listener'`) when "how many times did the listener fire" is the question.
+
+The decision-doc recommendation: in a UI panel, default-hide `kind: 'request' && origin: 'listener'` events behind a toggle. Default-show: user-origin requests + snapshot deliveries + listener lifecycle + denials. `snapshot_suppressed` is opt-in (inspector mode).
+
+## Capture committed writes for replay
+
+```ts
+sandbox.onEvent((event) => {
+  if (event.kind !== 'write') return;
+  // priorState and nextState are full doc snapshots — null when absent.
+  // groupKind disambiguates batch / transaction sub-ops sharing a groupId.
+  archive.append({
+    at: event.at,
+    op: `${event.method} ${event.path}`,
+    auth: event.auth?.uid ?? null,
+    prior: event.priorState,
+    next: event.nextState,
+    group: event.groupKind,
+    groupId: event.groupId,
+  });
+});
+```
+
+`write` events fire only for writes that the rule engine allowed AND the keyspace successfully applied. Denied or rolled-back writes surface as `kind: 'request' && result: 'deny'` with no companion `write` event.
+
+The `sentinels`, `autoId`, and `requestTime` fields on `WriteSandboxEvent` are populated so a captured stream can be replayed. See [Replay a captured event stream](../pyric-sandbox-how-to-replay-events/). For live observation you can ignore them.
+
+## Segment around reset()
+
+```ts
+let session = 1;
+sandbox.onEvent((event) => {
+  if (event.kind === 'session_boundary') {
+    console.log(`--- session ${session} closed (${event.priorOpCount} events) ---`);
+    if (event.phase === 'reset') session++;
+  }
+});
+```
+
+`session_boundary` fires BEFORE the env swap on `reset()` and BEFORE teardown on `dispose()`. The subscription survives reset; only dispose clears it.
+
+## Subscriber contract
+
+The sandbox calls your callback **synchronously**, inline with the op that produced the event. A few consequences worth understanding:
+
+- **Heavy synchronous work inflates the next op's `evalMs`.** The event you receive carries timing for the rules evaluation that finished, but the *next* op is sitting on the same event loop. If your subscriber sorts a 10k-element array on every event, the user-visible op latency includes that work. Push expensive processing into a `queueMicrotask` / `setTimeout(..., 0)` or onto a worker.
+- **The sandbox does not await async subscribers.** If you write `sandbox.onEvent(async (ev) => { await fetch(...) })`, the sandbox returns from emit before your `await` resolves. Subscribers are **observational**: the sandbox doesn't propagate their errors and won't pause ops on them. Do your own error handling inside the handler.
+- **Async rejections are swallowed.** A rejected Promise from an async subscriber is silently caught. It will not become an `unhandledRejection`, but it will also not surface anywhere. Wrap in `try/catch` yourself if you need to know your subscriber crashed.
+- **Large `resourceData` / `sample.docs` balloons the in-memory buffer.** A 1 MB write becomes ~1 MB per event in your ring buffer. Multiply by 5000-event default cap = 5 GB worst case. Strip or truncate before retaining events long-term.
+- **No back-pressure.** There is no per-subscriber queue. If a subscriber is slow synchronously, the sandbox blocks; if it's slow asynchronously, the sandbox doesn't wait but events accumulate in *your* downstream pipeline. Size your consumer's buffer.
+
+## See also
+
+- [`SandboxEvent` reference](../pyric-sandbox-reference-sandbox-event/): field-by-field for every kind.
+- [Listener re-evaluation on `deployRules`](../pyric-sandbox-explanation-listener-re-evaluation/): why deploy-rules-driven re-evals carry no `triggeredBy`.
+- Design rationale: the reasoning for replacing the three-channel surface with one.

package/dist/serve/docs-ui/docs/pyric-sandbox-how-to-pick-an-adapter/index.html

@@ -0,0 +1,79 @@
+<!DOCTYPE html><html lang="en"> <head><meta charset="UTF-8"><meta name="viewport" content="width=device-width, initial-scale=1.0"><title>How to pick between pyric-admin and pyric/firestore · 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>How-to</span> </li><li> <span class="docs-breadcrumbs-sep" aria-hidden="true">/</span> <span aria-current="page">Pick an adapter</span> </li> </ol> </nav>  <article class="prose">  <h1 id="how-to-pick-between-pyric-admin-and-pyricfirestore">How to pick between <code>pyric-admin</code> and <code>pyric/firestore</code></h1>
+<p>Two adapter packages sit on top of <code>pyric/sandbox</code>. Both expose Firestore. They look the same from a distance and shape differently up close. This guide helps you pick.</p>
+<h2 id="the-two-surfaces">The two surfaces</h2>
+<p><strong><code>pyric-admin</code></strong> mirrors <code>firebase-admin/firestore</code>: chainable, class-shaped.</p>
+<pre class="astro-code one-dark-pro" style="background-color:#282c34;color:#abb2bf; overflow-x: auto;" tabindex="0" data-language="ts"><code><span class="line"><span style="color:#C678DD">import</span><span style="color:#ABB2BF"> { </span><span style="color:#E06C75">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">await</span><span style="color:#E5C07B"> db</span><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 style="color:#61AFEF">doc</span><span style="color:#ABB2BF">(</span><span style="color:#98C379">'n1'</span><span style="color:#ABB2BF">).</span><span style="color:#61AFEF">set</span><span style="color:#ABB2BF">({ </span><span style="color:#E06C75">title</span><span style="color:#ABB2BF">: </span><span style="color:#98C379">'hello'</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"> db</span><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 style="color:#61AFEF">where</span><span style="color:#ABB2BF">(</span><span style="color:#98C379">'owner'</span><span style="color:#ABB2BF">, </span><span style="color:#98C379">'=='</span><span style="color:#ABB2BF">, </span><span style="color:#98C379">'alice'</span><span style="color:#ABB2BF">).</span><span style="color:#61AFEF">get</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 style="color:#7F848E;font-style:italic">/* ... */</span><span style="color:#ABB2BF"> });</span></span></code></pre>
+<p><strong><code>pyric/firestore</code></strong> mirrors <code>firebase/firestore</code> (the modular Web SDK): function-shaped, tree-shakable.</p>
+<pre class="astro-code one-dark-pro" style="background-color:#282c34;color:#abb2bf; overflow-x: auto;" tabindex="0" data-language="ts"><code><span class="line"><span style="color:#C678DD">import</span><span style="color:#ABB2BF"> { </span><span style="color:#E06C75">initializeFirestore</span><span style="color:#ABB2BF">, </span><span style="color:#E06C75">getDoc</span><span style="color:#ABB2BF">, </span><span style="color:#E06C75">setDoc</span><span style="color:#ABB2BF">, </span><span style="color:#E06C75">doc</span><span style="color:#ABB2BF">, </span><span style="color:#E06C75">query</span><span style="color:#ABB2BF">, </span><span style="color:#E06C75">where</span><span style="color:#ABB2BF">, </span><span style="color:#E06C75">getDocs</span><span style="color:#ABB2BF"> } </span><span style="color:#C678DD">from</span><span style="color:#98C379"> 'pyric/firestore'</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"> initializeFirestore</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">await</span><span style="color:#61AFEF"> setDoc</span><span style="color:#ABB2BF">(</span><span style="color:#61AFEF">doc</span><span style="color:#ABB2BF">(</span><span style="color:#E06C75">db</span><span style="color:#ABB2BF">, </span><span style="color:#98C379">'notes'</span><span style="color:#ABB2BF">, </span><span style="color:#98C379">'n1'</span><span style="color:#ABB2BF">), { </span><span style="color:#E06C75">title</span><span style="color:#ABB2BF">: </span><span style="color:#98C379">'hello'</span><span style="color:#ABB2BF"> });</span></span>
+<span class="line"><span style="color:#C678DD">const</span><span style="color:#E5C07B"> q</span><span style="color:#56B6C2"> =</span><span style="color:#61AFEF"> query</span><span style="color:#ABB2BF">(</span><span style="color:#E5C07B">db</span><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 style="color:#61AFEF">where</span><span style="color:#ABB2BF">(</span><span style="color:#98C379">'owner'</span><span style="color:#ABB2BF">, </span><span style="color:#98C379">'=='</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"> snap</span><span style="color:#56B6C2"> =</span><span style="color:#C678DD"> await</span><span style="color:#61AFEF"> getDocs</span><span style="color:#ABB2BF">(</span><span style="color:#E06C75">q</span><span style="color:#ABB2BF">);</span></span></code></pre>
+<p>Both back onto the same <code>LocalEnvironment</code> under the hood. The runtime behaviour is identical; only the API shape differs.</p>
+<h2 id="decision-matrix">Decision matrix</h2>
+<div class="table-scroll">
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+<table><thead><tr><th>Pick</th><th>When</th></tr></thead><tbody><tr><td><code>pyric-admin</code></td><td>Your production code uses <code>firebase-admin/firestore</code> (Node services, Cloud Functions).</td></tr><tr><td><code>pyric-admin</code></td><td>You prefer chainable / OO-style APIs.</td></tr><tr><td><code>pyric-admin</code></td><td>You’re writing tests that need to mirror admin SDK semantics.</td></tr><tr><td><code>pyric/firestore</code></td><td>Your production code uses <code>firebase/firestore</code> (web app, React Native).</td></tr><tr><td><code>pyric/firestore</code></td><td>You want tree-shaking; the modular SDK is designed for it.</td></tr><tr><td><code>pyric/firestore</code></td><td>You’re sharing test code with browser-side components that import <code>firebase/firestore</code>.</td></tr></tbody></table></div>
+<h2 id="rule-of-thumb">Rule of thumb</h2>
+<p>The right choice is whatever shape your <em>production</em> code already uses. The sandbox is a development tool, and keeping the test code’s surface identical to production avoids translation bugs.</p>
+<p>If you’re working in both environments (a hybrid app, a Cloud Functions backend with a web frontend), use both. They share the same sandbox cleanly:</p>
+<pre class="astro-code one-dark-pro" style="background-color:#282c34;color:#abb2bf; overflow-x: auto;" tabindex="0" data-language="ts"><code><span class="line"><span style="color:#C678DD">import</span><span style="color:#ABB2BF"> { </span><span style="color:#E06C75">initializeSandbox</span><span style="color:#ABB2BF"> } </span><span style="color:#C678DD">from</span><span style="color:#98C379"> 'pyric/sandbox'</span><span style="color:#ABB2BF">;</span></span>
+<span class="line"><span style="color:#C678DD">import</span><span style="color:#ABB2BF"> { </span><span style="color:#E06C75">getFirestore</span><span style="color:#C678DD"> as</span><span style="color:#E06C75"> getAdmin</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 style="color:#C678DD">import</span><span style="color:#ABB2BF"> { </span><span style="color:#E06C75">initializeFirestore</span><span style="color:#ABB2BF"> } </span><span style="color:#C678DD">from</span><span style="color:#98C379"> 'pyric/firestore'</span><span style="color:#ABB2BF">;</span></span>
+<span class="line"></span>
+<span class="line"><span style="color:#C678DD">const</span><span style="color:#E5C07B"> sandbox</span><span style="color:#56B6C2"> =</span><span style="color:#61AFEF"> initializeSandbox</span><span style="color:#ABB2BF">();</span></span>
+<span class="line"></span>
+<span class="line"><span style="color:#C678DD">const</span><span style="color:#E5C07B"> adminDb</span><span style="color:#56B6C2"> =</span><span style="color:#61AFEF"> getAdmin</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">'backend'</span><span style="color:#ABB2BF"> }));</span></span>
+<span class="line"><span style="color:#C678DD">const</span><span style="color:#E5C07B"> webDb</span><span style="color:#56B6C2"> =</span><span style="color:#61AFEF"> initializeFirestore</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:#7F848E;font-style:italic">// Both see the same data.</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">collection</span><span style="color:#ABB2BF">(</span><span style="color:#98C379">'notes'</span><span style="color:#ABB2BF">).</span><span style="color:#61AFEF">doc</span><span style="color:#ABB2BF">(</span><span style="color:#98C379">'n1'</span><span style="color:#ABB2BF">).</span><span style="color:#61AFEF">set</span><span style="color:#ABB2BF">({ </span><span style="color:#E06C75">title</span><span style="color:#ABB2BF">: </span><span style="color:#98C379">'from backend'</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:#61AFEF"> getDoc</span><span style="color:#ABB2BF">(</span><span style="color:#61AFEF">doc</span><span style="color:#ABB2BF">(</span><span style="color:#E06C75">webDb</span><span style="color:#ABB2BF">, </span><span style="color:#98C379">'notes'</span><span style="color:#ABB2BF">, </span><span style="color:#98C379">'n1'</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">log</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:#7F848E;font-style:italic">// { title: 'from backend' }</span></span></code></pre>
+<h2 id="can-i-use-both-inside-one-test">Can I use both inside one test?</h2>
+<p>Yes. Each adapter is a thin wrapper over <code>SandboxContext</code> and <code>LocalEnvironment</code>. The two adapters don’t conflict, and their objects don’t interfere with each other.</p>
+<p>The only thing to remember: <code>setRules</code> exists only on <code>pyric-admin</code>’s handle (it’s an admin-shaped operation). Use the admin handle to deploy rules, then both handles see them.</p>
+<h2 id="where-to-look-next">Where to look next</h2>
+<ul>
+<li>For a hands-on intro that uses <code>pyric-admin</code>, see <a href="../pyric-sandbox-tutorials-01-your-first-sandbox-session/">Your first sandbox session</a>.</li>
+<li>For the rationale behind the two-adapter design, see <a href="../pyric-sandbox-explanation-why-adapters-are-siblings/">Why service adapters live in sibling packages</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-two-surfaces">The two surfaces</a> </li><li data-depth="2"> <a href="#decision-matrix">Decision matrix</a> </li><li data-depth="2"> <a href="#rule-of-thumb">Rule of thumb</a> </li><li data-depth="2"> <a href="#can-i-use-both-inside-one-test">Can I use both inside one test?</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-sandbox-how-to-pick-an-adapter.md

@@ -0,0 +1,75 @@
+# How to pick between `pyric-admin` and `pyric/firestore`
+
+Two adapter packages sit on top of `pyric/sandbox`. Both expose Firestore. They look the same from a distance and shape differently up close. This guide helps you pick.
+
+## The two surfaces
+
+**`pyric-admin`** mirrors `firebase-admin/firestore`: chainable, class-shaped.
+
+```ts
+import { getFirestore } from 'pyric-admin';
+
+const db = getFirestore(sandbox.withAuth({ uid: 'alice' }));
+
+await db.collection('notes').doc('n1').set({ title: 'hello' });
+const snap = await db.collection('notes').where('owner', '==', 'alice').get();
+await db.runTransaction(async (tx) => { /* ... */ });
+```
+
+**`pyric/firestore`** mirrors `firebase/firestore` (the modular Web SDK): function-shaped, tree-shakable.
+
+```ts
+import { initializeFirestore, getDoc, setDoc, doc, query, where, getDocs } from 'pyric/firestore';
+
+const db = initializeFirestore(sandbox.withAuth({ uid: 'alice' }));
+
+await setDoc(doc(db, 'notes', 'n1'), { title: 'hello' });
+const q = query(db.collection('notes'), where('owner', '==', 'alice'));
+const snap = await getDocs(q);
+```
+
+Both back onto the same `LocalEnvironment` under the hood. The runtime behaviour is identical; only the API shape differs.
+
+## Decision matrix
+
+| Pick | When |
+|---|---|
+| `pyric-admin` | Your production code uses `firebase-admin/firestore` (Node services, Cloud Functions). |
+| `pyric-admin` | You prefer chainable / OO-style APIs. |
+| `pyric-admin` | You're writing tests that need to mirror admin SDK semantics. |
+| `pyric/firestore` | Your production code uses `firebase/firestore` (web app, React Native). |
+| `pyric/firestore` | You want tree-shaking; the modular SDK is designed for it. |
+| `pyric/firestore` | You're sharing test code with browser-side components that import `firebase/firestore`. |
+
+## Rule of thumb
+
+The right choice is whatever shape your *production* code already uses. The sandbox is a development tool, and keeping the test code's surface identical to production avoids translation bugs.
+
+If you're working in both environments (a hybrid app, a Cloud Functions backend with a web frontend), use both. They share the same sandbox cleanly:
+
+```ts
+import { initializeSandbox } from 'pyric/sandbox';
+import { getFirestore as getAdmin } from 'pyric-admin';
+import { initializeFirestore } from 'pyric/firestore';
+
+const sandbox = initializeSandbox();
+
+const adminDb = getAdmin(sandbox.withAuth({ uid: 'backend' }));
+const webDb = initializeFirestore(sandbox.withAuth({ uid: 'alice' }));
+
+// Both see the same data.
+await adminDb.collection('notes').doc('n1').set({ title: 'from backend' });
+const snap = await getDoc(doc(webDb, 'notes', 'n1'));
+console.log(snap.data());  // { title: 'from backend' }
+```
+
+## Can I use both inside one test?
+
+Yes. Each adapter is a thin wrapper over `SandboxContext` and `LocalEnvironment`. The two adapters don't conflict, and their objects don't interfere with each other.
+
+The only thing to remember: `setRules` exists only on `pyric-admin`'s handle (it's an admin-shaped operation). Use the admin handle to deploy rules, then both handles see them.
+
+## Where to look next
+
+- For a hands-on intro that uses `pyric-admin`, see [Your first sandbox session](../pyric-sandbox-tutorials-01-your-first-sandbox-session/).
+- For the rationale behind the two-adapter design, see [Why service adapters live in sibling packages](../pyric-sandbox-explanation-why-adapters-are-siblings/).

package/dist/serve/docs-ui/docs/pyric-sandbox-how-to-replay-events/index.html

@@ -0,0 +1,88 @@
+<!DOCTYPE html><html lang="en"> <head><meta charset="UTF-8"><meta name="viewport" content="width=device-width, initial-scale=1.0"><title>How to replay a captured event stream · 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>How-to</span> </li><li> <span class="docs-breadcrumbs-sep" aria-hidden="true">/</span> <span aria-current="page">Replay events</span> </li> </ol> </nav>  <article class="prose">  <h1 id="how-to-replay-a-captured-event-stream">How to replay a captured event stream</h1>
+<p>The sandbox captures every <code>SandboxEvent</code> it emits. Hand the captured stream to <code>replay(events, rules)</code> from <code>pyric/sandbox</code> and the engine re-issues every write against a fresh sandbox, classifying the differences against an optional snapshot of the original state.</p>
+<h2 id="when-to-use-this">When to use this</h2>
+<div class="table-scroll">
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+<table><thead><tr><th>You want to</th><th>Reach for</th></tr></thead><tbody><tr><td>Verify the same writes produce the same state on a new project</td><td><code>replay(events, rules, opts, originalState)</code></td></tr><tr><td>Reconstruct a sandbox at a point-in-time from a persisted log</td><td><code>replay(events, rules)</code>; ignore divergences, use the returned sandbox</td></tr><tr><td>Find when a rule change broke a captured session</td><td>replay against the new rules; look for <code>real-divergence</code></td></tr><tr><td>Debug “why did <code>serverTimestamp()</code> resolve differently”</td><td>check <code>time-drift</code> divergences (turn off <code>pinRequestTime</code> if you want to see the drift)</td></tr></tbody></table></div>
+<h2 id="capture">Capture</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">initializeSandbox</span><span style="color:#ABB2BF"> } </span><span style="color:#C678DD">from</span><span style="color:#98C379"> 'pyric/sandbox'</span><span style="color:#ABB2BF">;</span></span>
+<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"> sandbox</span><span style="color:#56B6C2"> =</span><span style="color:#61AFEF"> initializeSandbox</span><span style="color:#ABB2BF">();</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">'alice'</span><span style="color:#ABB2BF"> }));</span></span>
+<span class="line"><span style="color:#E5C07B">db</span><span style="color:#ABB2BF">.</span><span style="color:#61AFEF">setRules</span><span style="color:#ABB2BF">(</span><span style="color:#E5C07B">RULES</span><span style="color:#ABB2BF">);</span></span>
+<span class="line"></span>
+<span class="line"><span style="color:#7F848E;font-style:italic">// ... do work ...</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">collection</span><span style="color:#ABB2BF">(</span><span style="color:#98C379">'notes'</span><span style="color:#ABB2BF">).</span><span style="color:#61AFEF">doc</span><span style="color:#ABB2BF">(</span><span style="color:#98C379">'a'</span><span style="color:#ABB2BF">).</span><span style="color:#61AFEF">set</span><span style="color:#ABB2BF">({ </span><span style="color:#E06C75">ts</span><span style="color:#ABB2BF">: </span><span style="color:#E5C07B">FieldValue</span><span style="color:#ABB2BF">.</span><span style="color:#61AFEF">serverTimestamp</span><span style="color:#ABB2BF">() });</span></span>
+<span class="line"></span>
+<span class="line"><span style="color:#7F848E;font-style:italic">// Snapshot the event stream + the resulting state.</span></span>
+<span class="line"><span style="color:#C678DD">const</span><span style="color:#E5C07B"> events</span><span style="color:#56B6C2"> =</span><span style="color:#E5C07B"> sandbox</span><span style="color:#ABB2BF">.</span><span style="color:#61AFEF">history</span><span style="color:#ABB2BF">();</span></span>
+<span class="line"><span style="color:#C678DD">const</span><span style="color:#E5C07B"> state</span><span style="color:#56B6C2"> =</span><span style="color:#E5C07B"> sandbox</span><span style="color:#ABB2BF">.</span><span style="color:#61AFEF">snapshot</span><span style="color:#ABB2BF">().</span><span style="color:#E06C75">firestore</span><span style="color:#56B6C2"> ??</span><span style="color:#ABB2BF"> {};</span></span>
+<span class="line"></span>
+<span class="line"><span style="color:#7F848E;font-style:italic">// Persist `events` and `state` wherever you want (file, Firebase Storage, etc).</span></span></code></pre>
+<p><code>sandbox.history()</code> returns a defensive copy of every <code>SandboxEvent</code> the sandbox has emitted: request, write, snapshot delivery, listener lifecycle, session_boundary. The replay engine only consumes <code>kind: 'write'</code> events; the rest pass through untouched (useful if you persist the full log for diagnostic purposes).</p>
+<p>The captured <code>request.resourceData</code> and <code>write.data</code> ship <strong>pre-resolution</strong>. <code>FieldValue.serverTimestamp()</code> arrives as <code>{ __type: 'serverTimestamp' }</code>, not a materialized Timestamp; <code>FieldValue.increment(1)</code> arrives as <code>{ __type: 'increment', value: 1 }</code>, etc. This is what lets the replay engine re-resolve them against a fresh sandbox (and lets <code>pinRequestTime</code> actually do something). <code>write.priorState</code> / <code>write.nextState</code> carry the <strong>post-resolution</strong> values, the actual stored state at that moment.</p>
+<h2 id="replay">Replay</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">replay</span><span style="color:#ABB2BF"> } </span><span style="color:#C678DD">from</span><span style="color:#98C379"> 'pyric/sandbox'</span><span style="color:#ABB2BF">;</span></span>
+<span class="line"></span>
+<span class="line"><span style="color:#C678DD">const</span><span style="color:#ABB2BF"> { </span><span style="color:#E06C75">sandbox</span><span style="color:#ABB2BF">: </span><span style="color:#E5C07B">replayed</span><span style="color:#ABB2BF">, </span><span style="color:#E5C07B">divergences</span><span style="color:#ABB2BF">, </span><span style="color:#E5C07B">pathAliases</span><span style="color:#ABB2BF"> } </span><span style="color:#56B6C2">=</span><span style="color:#61AFEF"> replay</span><span style="color:#ABB2BF">(</span></span>
+<span class="line"><span style="color:#E06C75">  events</span><span style="color:#ABB2BF">,</span></span>
+<span class="line"><span style="color:#E5C07B">  RULES</span><span style="color:#ABB2BF">,</span></span>
+<span class="line"><span style="color:#ABB2BF">  { </span><span style="color:#E06C75">pinRequestTime</span><span style="color:#ABB2BF">: </span><span style="color:#D19A66">true</span><span style="color:#ABB2BF"> },   </span><span style="color:#7F848E;font-style:italic">// default — matches captured serverTimestamp() values</span></span>
+<span class="line"><span style="color:#E06C75">  state</span><span style="color:#ABB2BF">,                      </span><span style="color:#7F848E;font-style:italic">// optional — enables divergence classification</span></span>
+<span class="line"><span style="color:#ABB2BF">);</span></span></code></pre>
+<p>The function builds a fresh sandbox with the same rules, walks every captured write, re-issues it (with sentinels intact), and, if you passed <code>state</code>, diffs the replayed final state against it.</p>
+<h2 id="classify-divergences">Classify divergences</h2>
+<p>The <code>divergences</code> array is a discriminated union. Filter on <code>kind</code> and handle each case. <code>real-divergence</code> is the only kind that signals an actual bug; the others are intentional by-design differences (auto-id minting, clock drift on unpinned replay, sentinel resolution against a different prior).</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"> real</span><span style="color:#56B6C2"> =</span><span style="color:#E5C07B"> divergences</span><span style="color:#ABB2BF">.</span><span style="color:#61AFEF">filter</span><span style="color:#ABB2BF">((</span><span style="color:#E06C75;font-style:italic">d</span><span style="color:#ABB2BF">) </span><span style="color:#C678DD">=></span><span style="color:#E5C07B"> d</span><span style="color:#ABB2BF">.</span><span style="color:#E06C75">kind</span><span style="color:#56B6C2"> ===</span><span style="color:#98C379"> 'real-divergence'</span><span style="color:#ABB2BF">);</span></span>
+<span class="line"><span style="color:#61AFEF">expect</span><span style="color:#ABB2BF">(</span><span style="color:#E06C75">real</span><span style="color:#ABB2BF">).</span><span style="color:#61AFEF">toHaveLength</span><span style="color:#ABB2BF">(</span><span style="color:#D19A66">0</span><span style="color:#ABB2BF">);    </span><span style="color:#7F848E;font-style:italic">// typical CI assertion</span></span></code></pre>
+<p>See the <a href="../pyric-sandbox-reference-divergences/"><code>Divergence</code> reference</a> for the full union shape, per-kind semantics, and field-path syntax.</p>
+<h2 id="pinrequesttime-the-default-that-prevents-flake"><code>pinRequestTime</code>: the default that prevents flake</h2>
+<p>Every <code>WriteSandboxEvent</code> carries the exact <code>request.time</code> the rule engine evaluated against. With <code>pinRequestTime: true</code> (default), the engine re-issues that <code>Timestamp</code> to the fresh sandbox so:</p>
+<ul>
+<li><code>serverTimestamp()</code> sentinels resolve to the same value as capture (no <code>time-drift</code>).</li>
+<li>Rules that branch on <code>request.time</code> (e.g., <code>allow write: if request.time >= timestamp.date(2024, 1, 1);</code>) evaluate identically.</li>
+</ul>
+<p>Turn it off when you <em>want</em> to test “does the captured stream still pass under today’s clock?” That catches rules that depend on a time that’s now in the past.</p>
+<h2 id="auto-ids-alias-to-fresh-mints">Auto-IDs alias to fresh mints</h2>
+<p>Writes that originated from <code>collection.add()</code> / <code>LocalEnvironment.createWithAutoId</code> carry <code>autoId: '&#x3C;mintedSegment>'</code> on the event. On replay the engine calls <code>createWithAutoId</code> again, mints a fresh ID, and records the alias in <code>pathAliases</code>. Two consequences:</p>
+<ul>
+<li>The replayed sandbox holds the doc at a <em>different</em> path than the original.</li>
+<li>The diff classifier treats those paths as <code>autoid-alias</code>, not <code>real-divergence</code>.</li>
+</ul>
+<p>Consumers that index by path (a UI showing “doc X exists”) should consult <code>pathAliases</code> to map original → replayed.</p>
+<h2 id="limitations-v1">Limitations (v1)</h2>
+<ul>
+<li>Pinned <code>requestTime</code> works for <code>execute</code> only. Replaying writes that were originally part of a batch or transaction currently re-creates a fresh <code>serverTime</code> for those op-groups. If your captured stream is heavy on batch/tx writes that touch <code>serverTimestamp()</code>, expect small <code>time-drift</code> entries, usually harmless because they share a single time within the group.</li>
+<li><code>sandbox.history()</code> has no cap in v1. Long-running sandboxes accumulate. If memory becomes an issue, snapshot + <code>reset()</code> to roll over (the closing <code>session_boundary</code> event marks the boundary cleanly).</li>
+<li>The replay engine doesn’t currently replay <code>request</code> events with denials, only the writes. Consumers that want to surface “this captured op was denied on replay” can correlate <code>events.filter(e => e.kind === 'request' &#x26;&#x26; e.result === 'deny')</code> against the replay’s <code>divergences</code> list.</li>
+</ul>
+<h2 id="see-also">See also</h2>
+<ul>
+<li><a href="../pyric-sandbox-reference-divergences/"><code>Divergence</code> reference</a>: the union shape and per-kind semantics.</li>
+<li><a href="../pyric-sandbox-reference-sandbox-event/"><code>SandboxEvent</code> reference</a>: field-by-field for each event kind.</li>
+<li><a href="../pyric-sandbox-how-to-observe-events/">Observe sandbox events</a>: the live channel (<code>onEvent</code>) that feeds into <code>history()</code>.</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="#when-to-use-this">When to use this</a> </li><li data-depth="2"> <a href="#capture">Capture</a> </li><li data-depth="2"> <a href="#replay">Replay</a> </li><li data-depth="2"> <a href="#classify-divergences">Classify divergences</a> </li><li data-depth="2"> <a href="#pinrequesttime-the-default-that-prevents-flake">pinRequestTime: the default that prevents flake</a> </li><li data-depth="2"> <a href="#auto-ids-alias-to-fresh-mints">Auto-IDs alias to fresh mints</a> </li><li data-depth="2"> <a href="#limitations-v1">Limitations (v1)</a> </li><li data-depth="2"> <a href="#see-also">See also</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>