@pyric/cli 0.1.0-alpha.9

package/dist/serve/docs-ui/docs/pyric-cli-how-to-use-the-vite-plugin.md

@@ -0,0 +1,309 @@
+# Use the Vite plugin (`@pyric/cli/vite`)
+
+The `pyricSandbox()` Vite plugin gives a **source-driven** app the same
+`firebase/*` → pyric-sandbox swap that `pyric dev` gives a **static** app,
+without leaving your normal `vite dev` loop (HMR, source maps, your own
+router/UI stack). Your app's `firebase/*` imports stay exactly as written; the
+plugin swaps them at Vite's module-resolution layer. A plain `vite build` keeps
+the real firebase package; only `vite dev` and an explicit sandbox build
+(`vite build --mode development`) run the swap. See
+[Two build flavors](#two-build-flavors-production-vs-sandbox).
+
+## Plugin or `pyric dev`? (they're complementary)
+
+Both do the identical thing: run your unmodified `firebase/*` against an
+in-browser pyric sandbox with your `firestore.rules` enforced, but at different
+points in your toolchain. Pick by how your app is built:
+
+| | `pyricSandbox()` Vite plugin | `pyric dev` |
+|---|---|---|
+| **Use it for** | source-driven apps you run with `vite dev` | static / pre-built / retrofit apps (`dist/`, `public/`, any folder with `firebase.json`) |
+| **Where the swap happens** | at module resolution, before bundling | at load time, via a runtime import map over already-built files |
+| **Dev loop** | your existing `vite dev` (HMR, source maps) | `pyric dev` owns the dev server |
+
+They are **not** competing. If you already build with Vite, the plugin keeps you
+in one toolchain (`vite dev` for the sandbox, `vite build` for prod). If you have
+a pre-built or no-build app, reach for [`pyric dev`](../pyric-cli-how-to-serve-persistence-and-multi-tab/).
+
+> **What the plugin covers.** It swaps `firebase/*`, deploys/hot-reloads your
+> rules, runs the sandbox in a **SharedWorker** (one backend shared across tabs,
+> durable in IndexedDB), supports opt-in on-disk **persistence**, **seeding**, and
+> session **capture**, and can mount the **MCP bridge** (`bridge: true`) so an
+> external agent drives the same sandbox, the same surface `pyric dev` gives a
+> static app, in one Vite plugin.
+
+## Prerequisites
+
+- A Vite app (Vite 5, 6, or 7) whose data layer uses canonical `firebase/*`
+  imports (`firebase/app`, `firebase/auth`, `firebase/firestore`).
+- A `firestore.rules` file (and optionally a `firebase.json`) in your project.
+
+## Install
+
+Add `@pyric/cli` as a development dependency:
+
+```bash
+npm install --save-dev @pyric/cli
+```
+
+(`vite` is a peer dependency you already have.)
+
+## Add it to `vite.config.ts`
+
+Import `pyricSandbox` from `@pyric/cli/vite` and add it to your `plugins`:
+
+```ts
+// vite.config.ts
+import { defineConfig } from 'vite';
+import { pyricSandbox } from '@pyric/cli/vite';
+
+export default defineConfig({
+  plugins: [pyricSandbox()],
+});
+```
+
+With no options, the plugin discovers your rules from `firebase.json`'s
+`firestore.rules`, falling back to `firestore.rules` in your project root.
+
+### Options
+
+`pyricSandbox(options?)`: all optional.
+
+| Option | Type | Default | What it does |
+|---|---|---|---|
+| `rules` | `string` | `firebase.json`'s `firestore.rules`, else `firestore.rules` in the project root | Path to your Firestore rules file, **relative to `root`**. Overrides whatever `firebase.json` declares. |
+| `root` | `string` | Vite's own `root` | Project directory used to discover `firebase.json` and resolve `rules`. |
+| `persist` | `boolean` | `false` | Persist sandbox data + test users to `.pyric/state/state.json` so they survive reloads and restarts. Off = ephemeral. |
+| `fresh` | `boolean` | `false` | With `persist`: discard the existing state file and re-seed from scratch. |
+| `seed` | `string` | none | Path to a seed file: a `"collection/doc" → fields` JSON map, **or** a `pyric snapshot` state-file. Applied at page init; lived state wins once it exists. |
+| `capture` | `boolean` | `true` | Write the live session to `.pyric/last-session.json` for `pyric verify`. Pass `false` to suppress. |
+| `bridge` | `boolean \| { project?, disableAuditLog? }` | `false` | Mount the **MCP bridge** so an external agent can drive the sandbox. `true` ⇒ defaults; the object form sets the audit project / disables the audit log. The agent shares the **same SharedWorker sandbox** as your app (and Studio). See [Drive the sandbox from an agent](#drive-the-sandbox-from-an-agent-bridge). |
+| `swapInBuild` | `boolean` | mode-based | Force whether `vite build` runs the swap, overriding the mode default. Unset: swap for any non-`production` mode. `true` = always a sandbox build; `false` = always real firebase in builds. `vite dev` is unaffected. See [Two build flavors](#two-build-flavors-production-vs-sandbox). |
+
+```ts
+// Point at a non-default rules file, and persist + seed the sandbox
+pyricSandbox({
+  rules: 'config/firestore.rules',
+  persist: true,
+  seed: 'seed.json',
+});
+```
+
+## Run your app on the sandbox
+
+Start your normal dev server:
+
+```bash
+npm run dev   # i.e. vite dev
+```
+
+Now `vite dev` serves your app against the in-process pyric sandbox:
+
+- Your app's `firebase/*` imports are **unchanged**: the plugin swaps
+  `firebase/app`, `firebase/auth`, and `firebase/firestore` to pyric's adapters
+  at resolution time. You never import anything from pyric in app code.
+- Your `firestore.rules` are **deployed at page load**: the plugin injects a
+  small init module into the served HTML, and that module deploys your rules
+  before your app code runs.
+- The Firebase config you pass to `initializeApp(config)` is
+  **accepted but ignored** in dev. No project, no credentials, no network:
+  the sandbox stands in for the real backend. (That same config flows through
+  untouched to your production build; see [Two build flavors](#two-build-flavors-production-vs-sandbox).)
+
+### Rules hot-reload on save
+
+Edit your `firestore.rules` and save. The plugin watches the file (through
+Vite's own watcher, no second file watcher) and **re-deploys the rules in
+place**, with no page reload. You'll see a line like:
+
+```
+  ↻ [pyric] rules reloaded (a1b2c3d4e5f6)
+```
+
+If a save leaves the rules un-parseable, the plugin keeps the **last good**
+ruleset live and warns instead of breaking your session:
+
+```
+  ⚠ [pyric] rules NOT reloaded (last-good stays live): <reason>
+```
+
+Fix the file and save again to deploy the corrected rules.
+
+### Multi-tab sync and persistence
+
+By default the sandbox runs in a **SharedWorker**: every tab of your dev origin
+talks to **one** backend, so a write in one tab shows up live in another, and the
+data is held in IndexedDB (it survives a refresh). If the browser lacks
+`SharedWorker`, the plugin falls back to a per-tab in-page sandbox automatically.
+
+That IndexedDB data is still **browser-local**: it doesn't land in your repo. To
+make data + test users durable across restarts (and committable), turn on
+`persist`:
+
+```ts
+pyricSandbox({ persist: true });          // writes .pyric/state/state.json
+pyricSandbox({ persist: true, fresh: true }); // wipe + re-seed this run
+```
+
+To preload data, point `seed` at a `"collection/doc" → fields` map or a file from
+`pyric snapshot`. With `persist`, the seed applies only on the first run. After
+that, **lived state wins**:
+
+```ts
+pyricSandbox({ seed: 'seed.json' });
+```
+
+The persistence model (the `.pyric/state` file, `persist` vs `fresh`, and how
+seed precedence works) is identical to `pyric dev` and documented in depth in
+[Persistence and multi-tab](../pyric-cli-how-to-serve-persistence-and-multi-tab/).
+
+## Drive the sandbox from an agent (`bridge`)
+
+Turn on `bridge` and the plugin mounts the **MCP bridge** on Vite's own dev
+origin, so an external agent (Claude Code, Cursor, any MCP client) can read and
+write the *same* sandbox your app is using, live, while you keep `vite dev`:
+
+```ts
+pyricSandbox({ bridge: true });
+// or tune the audit log:
+pyricSandbox({ bridge: { project: 'my-app', disableAuditLog: false } });
+```
+
+This adds three routes on your dev server's port (no sidecar process):
+
+| Route | What it is |
+|---|---|
+| `POST /__pyric/mcp` | MCP over streamable HTTP, point your agent here |
+| `GET /__pyric/health` | bridge health JSON |
+| `WS /__pyric/sandbox` | the page's bridge peer, routing to the SharedWorker (wired automatically) |
+
+Connect from Claude Code with the **pyric Claude Code plugin**: it runs a bundled
+stdio proxy that auto-discovers the running bridge from `.pyric/serve.json` (no
+fixed port, no `claude mcp add`). The [Wire Claude Code](../pyric-cli-tutorials-wire-claude-code/)
+tutorial walks the agent-side setup end to end.
+
+Open your app in a browser tab; the page connects to the bridge automatically (the
+plugin injects the bridge URL into the served init payload), and your agent can
+then seed, query, undo/redo, and audit the sandbox the page is running on.
+
+> **One shared sandbox.** The bridge routes the agent's tool-calls *through* the
+> **SharedWorker**: the same backend your app and (if enabled) Pyric Studio use.
+> Agent writes show up live in your open tab and in Studio, and vice versa; there
+> is no separate agent sandbox. The agent still reaches the worker through an open
+> page, so keep a tab open while it works.
+
+The bridge is the same machinery as [`pyric dev --bridge`](../pyric-cli-how-to-serve-persistence-and-multi-tab/);
+the [Wire Claude Code](../pyric-cli-tutorials-wire-claude-code/) tutorial walks the
+agent-side setup end to end.
+
+## Two build flavors: production vs. sandbox
+
+Under `vite dev` the swap is always on. For `vite build`, the plugin decides by
+the build **mode**:
+
+| Command | Mode | Output |
+|---|---|---|
+| `vite build` | `production` (default) | ships the **real `firebase` package**, your production artifact |
+| `vite build --mode development` | any non-`production` mode | a **sandbox build** that bundles pyric's in-page adapters instead of the SDK |
+
+A plain `vite build` means there is **no separate "graduation" step**. The
+Firebase config you passed to `initializeApp` (ignored by the sandbox in dev)
+is the *same* config your built app uses to talk to real Firebase in production.
+Dev and prod are one toolchain: `vite dev` and the sandbox build run on the
+sandbox, `vite build` runs on Firebase, and your source never changes between
+them.
+
+### The sandbox build (`vite build --mode development`)
+
+`vite build --mode development` produces a **self-contained bundle** whose
+`firebase/*` imports are already swapped to pyric's in-page adapters, plus a
+sandbox init chunk (the runtime bootstrap and the sign-in helper) that shares
+one runtime with your app, nothing to intercept or inject at load time, so you
+can preview a bundled build under `pyric dev` (which sees the marker and skips
+its own runtime injection for these pages):
+
+```bash
+vite build --mode development   # or the scaffolded `build:sandbox` script
+pyric dev                       # serves dist/ against the sandbox
+```
+
+The output carries a **sandbox-build marker** in `index.html`
+(`<meta name="pyric-sandbox-build">`). The marker makes the flavor unmistakable:
+
+- `pyric dev` **trusts** a marked dist and serves it (it skips the inlined-SDK
+  scan; a swapped bundle has no real SDK to find).
+- Production hosting deploys should use an **unmarked** production build
+  (`vite build` / production mode) and `firebase-tools` — a sandbox-marked dist
+  must never reach production.
+
+To force the build behavior regardless of mode, pass `swapInBuild` to the
+plugin: `pyricSandbox({ swapInBuild: true })` always produces a sandbox build,
+`{ swapInBuild: false }` never swaps in a build (real firebase in every mode).
+
+### Why `pyric dev` refuses a plain `vite build`
+
+`pyric dev`'s import map can only remap **bare** `firebase/*` specifiers. A plain
+`vite build` inlines the real SDK into the app chunk, leaving nothing to
+intercept: the page would reach live Google endpoints with the sandbox's fake
+credentials. Rather than serve that silently, `pyric dev` **hard-refuses** a dist
+that bundles the real SDK and points you at the two ways forward: run plain
+`pyric dev` (the child dev-server flow, plugin active), or rebuild with
+`vite build --mode development` and serve that.
+
+## Library imports are swapped too (transitive deps)
+
+The swap happens at resolution time, *before* bundling, so it also catches
+libraries that import `firebase/*` on your behalf: `react-firebase-hooks`,
+`reactfire`, and similar. When such a library does
+`import { getFirestore } from 'firebase/firestore'`, that import resolves to the
+sandbox adapter exactly as your own code does. The library transparently runs on
+the sandbox with no changes.
+
+This works because the plugin also tames Vite's **dependency optimizer**. Vite
+pre-bundles `node_modules` with esbuild; left alone, the optimizer would pre-bake
+a library's `firebase/*` import to the *real* firebase before the plugin's
+resolver ever runs. The plugin mirrors its swap into the optimizer's esbuild pass
+(and excludes the served `firebase/*` modules from pre-bundling) so the optimizer
+and the dev resolver agree. You don't need to configure any of this: adding the
+plugin is enough. But it's why the swap reaches dependencies, not just your own code.
+
+## Limitations
+
+What the plugin does and doesn't cover:
+
+- **Libraries that reach into Firebase internals throw at import.** The swap
+  mirrors Firebase's **public modular surface**: what your app and most
+  data-layer libraries use. A library that reaches into Firebase *internals*
+  (`@firebase/component`, `_getProvider`, app component registration, e.g.
+  `firebaseui`, parts of `@angular/fire`) falls outside that surface and
+  **throws at import**. This is inherent to mirroring the public API; `pyric
+  serve` has the same ceiling.
+
+- **Only `firebase/app`, `firebase/auth`, and `firebase/firestore` are swapped.**
+  Other subpaths (`firebase/storage`, `firebase/database`) resolve to the real
+  package: the same surface `pyric dev` covers today.
+
+- **The agent reaches the sandbox through an open page.** `pyricSandbox({ bridge: true })`
+  routes the agent's tool-calls through the SharedWorker (the same backend your
+  app and Studio use), but the worker lives in the browser, so a tab must stay
+  open for the agent to act. (`pyric dev --bridge` has the same shape.)
+
+## Troubleshooting
+
+**`@pyric/cli/vite: pyric is not built …`** The plugin needs pyric's compiled
+output to read Firebase's public surface. In a monorepo checkout, build pyric
+first (e.g. `bun run build`). An installed `@pyric/cli` from npm ships built, so
+you'll only hit this developing against a source checkout.
+
+**A `firebase/*` import you expected to swap didn't.** Only `firebase/app`,
+`firebase/auth`, and `firebase/firestore` are swapped. Other `firebase/*`
+subpaths (e.g. `firebase/storage`, `firebase/database`) resolve to the real
+package in this release.
+
+## See also
+
+- [Persistence and multi-tab with `pyric dev`](../pyric-cli-how-to-serve-persistence-and-multi-tab/):
+  the static-app analog; the worker/persist/seed model is identical to the plugin's.
+- [Getting started](../start-building/): the end-to-end scaffold →
+  serve → agent loop.
+- [Why an in-browser backend is *not* Firestore offline persistence](../pyric-sandbox-explanation-local-backend-vs-firestore-offline/).

package/dist/serve/docs-ui/docs/pyric-cli-how-to-verify-against-a-captured-session/index.html

@@ -0,0 +1,128 @@
+<!DOCTYPE html><html lang="en"> <head><meta charset="UTF-8"><meta name="viewport" content="width=device-width, initial-scale=1.0"><title>How to verify your rules against a captured session · 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" open> <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/" aria-current="page"> Verify a captured session </a> </li><li> <a href="/__pyric/ui/docs/write-a-rules-test-suite/"> Write a rules test suite </a> </li><li> <a href="/__pyric/ui/docs/audit-your-rules/"> Audit rules and data </a> </li> </ul> </div> </div> </details><details class="docs-nav-group"> <summary>Ship unchanged</summary> <div class="docs-nav-group-body"> <div class="docs-nav-section">  <ul> <li> <a href="/__pyric/ui/docs/ship-to-production/"> Ship to production </a> </li><li> <a href="/__pyric/ui/docs/set-up-the-project/"> Set up the Firebase project </a> </li> </ul> </div> </div> </details><details class="docs-nav-group"> <summary>Conformance</summary> <div class="docs-nav-group-body"> <div class="docs-nav-section">  <ul> <li> <a href="/__pyric/ui/docs/how-we-know-it-matches-firebase/"> Conformance </a> </li><li> <a href="/__pyric/ui/docs/whats-experimental/"> What&#39;s experimental </a> </li><li> <a href="/__pyric/ui/docs/pyric-conformance-scores/"> Conformance scores </a> </li><li> <a href="/__pyric/ui/docs/pyric-app-compat/"> App </a> </li><li> <a href="/__pyric/ui/docs/pyric-firestore-compat/"> Firestore </a> </li><li> <a href="/__pyric/ui/docs/pyric-auth-compat/"> Auth </a> </li><li> <a href="/__pyric/ui/docs/pyric-database-compat/"> Realtime Database </a> </li><li> <a href="/__pyric/ui/docs/pyric-storage-compat/"> Storage </a> </li><li> <a href="/__pyric/ui/docs/pyric-rules-compat/"> Rules </a> </li><li> <a href="/__pyric/ui/docs/pyric-messaging-compat/"> Messaging </a> </li><li> <a href="/__pyric/ui/docs/pyric-ai-compat/"> AI Logic </a> </li><li> <a href="/__pyric/ui/docs/pyric-cli-functions-rtdb-compat/"> Functions · RTDB </a> </li> </ul> </div> </div> </details> <details class="docs-nav-group"> <summary>Reference</summary> <div class="docs-nav-group-body"> <div class="docs-nav-section"> <ul> <li> <a href="/__pyric/ui/docs/pyric-cli/"> @pyric/cli </a> </li><li> <a href="/__pyric/ui/docs/pyric-explanation-versioning-and-compatibility/"> pyric </a> </li><li> <a href="/__pyric/ui/docs/pyric-firestore/"> pyric / firestore </a> </li><li> <a href="/__pyric/ui/docs/pyric-rules/"> pyric / rules </a> </li><li> <a href="/__pyric/ui/docs/pyric-sandbox/"> pyric / sandbox </a> </li><li> <a href="/__pyric/ui/docs/pyric-storage/"> pyric / storage </a> </li><li> <a href="/__pyric/ui/docs/pyric-auth/"> pyric / auth </a> </li><li> <a href="/__pyric/ui/docs/pyric-database/"> pyric / database </a> </li><li> <a href="/__pyric/ui/docs/pyric-admin-app/"> pyric-admin / app </a> </li><li> <a href="/__pyric/ui/docs/pyric-admin-firestore/"> pyric-admin / firestore </a> </li><li> <a href="/__pyric/ui/docs/pyric-admin-auth/"> pyric-admin / auth </a> </li><li> <a href="/__pyric/ui/docs/pyric-admin-database/"> pyric-admin / database </a> </li><li> <a href="/__pyric/ui/docs/pyric-admin-storage/"> pyric-admin / storage </a> </li><li> <a href="/__pyric/ui/docs/ui/"> @pyric/ui </a> </li><li> <a href="/__pyric/ui/docs/api-reference/"> API reference </a> </li> </ul> </div> </div> </details> </nav> </details> <nav class="docs-nav" aria-label="Documentation"> <div class="docs-search" data-index-url="/__pyric/ui/docs/index.json"> <div class="docs-search-field"> <svg class="docs-search-icon" viewBox="0 0 16 16" width="14" height="14" aria-hidden="true"> <path d="M11.5 11.5 15 15M13 7A6 6 0 1 1 1 7a6 6 0 0 1 12 0Z" fill="none" stroke="currentColor" stroke-width="1.4" stroke-linecap="round"></path> </svg> <input type="text" class="docs-search-input" placeholder="Search docs" aria-label="Search docs" autocomplete="off" spellcheck="false"> <kbd class="docs-search-kbd">⌘K</kbd> </div> <ul class="docs-search-results" hidden></ul> </div>  <a class="docs-nav-toplink" href="/__pyric/ui/docs/overview/" id="nav-group-overview"> Overview </a><details class="docs-nav-group" id="nav-group-run-locally"> <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" open> <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/" aria-current="page"> Verify a captured session </a> </li><li> <a href="/__pyric/ui/docs/write-a-rules-test-suite/"> Write a rules test suite </a> </li><li> <a href="/__pyric/ui/docs/audit-your-rules/"> Audit rules and data </a> </li> </ul> </div> </div> </details><details class="docs-nav-group" id="nav-group-ship-unchanged"> <summary>Ship unchanged</summary> <div class="docs-nav-group-body"> <div class="docs-nav-section">  <ul> <li> <a href="/__pyric/ui/docs/ship-to-production/"> Ship to production </a> </li><li> <a href="/__pyric/ui/docs/set-up-the-project/"> Set up the Firebase project </a> </li> </ul> </div> </div> </details><details class="docs-nav-group" id="nav-group-conformance"> <summary>Conformance</summary> <div class="docs-nav-group-body"> <div class="docs-nav-section">  <ul> <li> <a href="/__pyric/ui/docs/how-we-know-it-matches-firebase/"> Conformance </a> </li><li> <a href="/__pyric/ui/docs/whats-experimental/"> What&#39;s experimental </a> </li><li> <a href="/__pyric/ui/docs/pyric-conformance-scores/"> Conformance scores </a> </li><li> <a href="/__pyric/ui/docs/pyric-app-compat/"> App </a> </li><li> <a href="/__pyric/ui/docs/pyric-firestore-compat/"> Firestore </a> </li><li> <a href="/__pyric/ui/docs/pyric-auth-compat/"> Auth </a> </li><li> <a href="/__pyric/ui/docs/pyric-database-compat/"> Realtime Database </a> </li><li> <a href="/__pyric/ui/docs/pyric-storage-compat/"> Storage </a> </li><li> <a href="/__pyric/ui/docs/pyric-rules-compat/"> Rules </a> </li><li> <a href="/__pyric/ui/docs/pyric-messaging-compat/"> Messaging </a> </li><li> <a href="/__pyric/ui/docs/pyric-ai-compat/"> AI Logic </a> </li><li> <a href="/__pyric/ui/docs/pyric-cli-functions-rtdb-compat/"> Functions · RTDB </a> </li> </ul> </div> </div> </details> <details class="docs-nav-group" id="nav-group-reference"> <summary>Reference</summary> <div class="docs-nav-group-body"> <div class="docs-nav-section"> <ul> <li> <a href="/__pyric/ui/docs/pyric-cli/"> @pyric/cli </a> </li><li> <a href="/__pyric/ui/docs/pyric-explanation-versioning-and-compatibility/"> pyric </a> </li><li> <a href="/__pyric/ui/docs/pyric-firestore/"> pyric / firestore </a> </li><li> <a href="/__pyric/ui/docs/pyric-rules/"> pyric / rules </a> </li><li> <a href="/__pyric/ui/docs/pyric-sandbox/"> pyric / sandbox </a> </li><li> <a href="/__pyric/ui/docs/pyric-storage/"> pyric / storage </a> </li><li> <a href="/__pyric/ui/docs/pyric-auth/"> pyric / auth </a> </li><li> <a href="/__pyric/ui/docs/pyric-database/"> pyric / database </a> </li><li> <a href="/__pyric/ui/docs/pyric-admin-app/"> pyric-admin / app </a> </li><li> <a href="/__pyric/ui/docs/pyric-admin-firestore/"> pyric-admin / firestore </a> </li><li> <a href="/__pyric/ui/docs/pyric-admin-auth/"> pyric-admin / auth </a> </li><li> <a href="/__pyric/ui/docs/pyric-admin-database/"> pyric-admin / database </a> </li><li> <a href="/__pyric/ui/docs/pyric-admin-storage/"> pyric-admin / storage </a> </li><li> <a href="/__pyric/ui/docs/ui/"> @pyric/ui </a> </li><li> <a href="/__pyric/ui/docs/api-reference/"> API reference </a> </li> </ul> </div> </div> </details> </nav> <main class="doc-main"> <nav class="docs-breadcrumbs" aria-label="Breadcrumb"> <ol> <li>  <a href="/__pyric/ui/docs/pyric-cli-how-to-verify-against-a-captured-session/">Verify the boundary</a> </li><li> <span class="docs-breadcrumbs-sep" aria-hidden="true">/</span> <span aria-current="page">Verify a captured session</span> </li> </ol> </nav>  <article class="prose">  <h1 id="how-to-verify-your-rules-against-a-captured-session">How to verify your rules against a captured session</h1>
+<p><code>pyric verify</code> replays a captured sandbox session against candidate rules and
+reports service-labelled divergences. It works for Firestore and Realtime
+Database captures. It answers the question that makes “build in the sandbox,
+swap to prod” safe: <em>will the rules I’m about to ship break what I built?</em></p>
+<h2 id="capture-a-session-then-verify">Capture a session, then verify</h2>
+<p>Capture is on by default in <code>pyric dev</code>, so the loop has three steps.</p>
+<ol>
+<li>
+<p>Start the sandbox. The session is written to <code>.pyric/last-session.json</code> as
+you go:</p>
+<pre class="astro-code one-dark-pro" style="background-color:#282c34;color:#abb2bf; overflow-x: auto;" tabindex="0" data-language="sh"><code><span class="line"><span style="color:#61AFEF">pyric</span><span style="color:#98C379"> dev</span></span></code></pre>
+<p>(Pass <code>--no-capture</code> to disable the recording.)</p>
+</li>
+<li>
+<p>Exercise your app against the running sandbox: sign in, create documents,
+run the journeys you care about. Every write is recorded.</p>
+</li>
+<li>
+<p>Replay the latest capture against the rules you intend to deploy:</p>
+<pre class="astro-code one-dark-pro" style="background-color:#282c34;color:#abb2bf; overflow-x: auto;" tabindex="0" data-language="sh"><code><span class="line"><span style="color:#61AFEF">pyric</span><span style="color:#98C379"> verify</span></span></code></pre>
+<p>With no positional argument, <code>verify</code> reads <code>.pyric/last-session.json</code>.
+It verifies the Firestore and RTDB services present in that capture.
+Candidate rules are resolved from <code>firebase.json</code>:</p>
+<pre class="astro-code one-dark-pro" style="background-color:#282c34;color:#abb2bf; overflow-x: auto;" tabindex="0" data-language="json"><code><span class="line"><span style="color:#ABB2BF">{</span></span>
+<span class="line"><span style="color:#E06C75">  "firestore"</span><span style="color:#ABB2BF">: { </span><span style="color:#E06C75">"rules"</span><span style="color:#ABB2BF">: </span><span style="color:#98C379">"firestore.rules"</span><span style="color:#ABB2BF"> },</span></span>
+<span class="line"><span style="color:#E06C75">  "database"</span><span style="color:#ABB2BF">: { </span><span style="color:#E06C75">"rules"</span><span style="color:#ABB2BF">: </span><span style="color:#98C379">"database.rules.json"</span><span style="color:#ABB2BF"> }</span></span>
+<span class="line"><span style="color:#ABB2BF">}</span></span></code></pre>
+</li>
+</ol>
+<h2 id="verify-against-edited-rules">Verify against edited rules</h2>
+<p>If you’ve tightened or rewritten your rules and want to check them before
+deploying, pass service-qualified rules overrides:</p>
+<pre class="astro-code one-dark-pro" style="background-color:#282c34;color:#abb2bf; overflow-x: auto;" tabindex="0" data-language="sh"><code><span class="line"><span style="color:#61AFEF">pyric</span><span style="color:#98C379"> verify</span><span style="color:#D19A66"> --rules</span><span style="color:#98C379"> firestore=path/to/firestore.rules</span></span>
+<span class="line"><span style="color:#61AFEF">pyric</span><span style="color:#98C379"> verify</span><span style="color:#D19A66"> --rules</span><span style="color:#98C379"> rtdb=path/to/database.rules.json</span></span></code></pre>
+<p>The capture stays fixed; only the ruleset changes. The diff between what the
+sandbox allowed and what these rules allow is exactly what surfaces.</p>
+<p>For a mixed capture, repeat <code>--rules</code>:</p>
+<pre class="astro-code one-dark-pro" style="background-color:#282c34;color:#abb2bf; overflow-x: auto;" tabindex="0" data-language="sh"><code><span class="line"><span style="color:#61AFEF">pyric</span><span style="color:#98C379"> verify</span><span style="color:#56B6C2"> \</span></span>
+<span class="line"><span style="color:#D19A66">  --rules</span><span style="color:#98C379"> firestore=firestore.rules</span><span style="color:#56B6C2"> \</span></span>
+<span class="line"><span style="color:#D19A66">  --rules</span><span style="color:#98C379"> rtdb=database.rules.json</span></span></code></pre>
+<p>To check only one service in a mixed capture, use <code>--service</code>:</p>
+<pre class="astro-code one-dark-pro" style="background-color:#282c34;color:#abb2bf; overflow-x: auto;" tabindex="0" data-language="sh"><code><span class="line"><span style="color:#61AFEF">pyric</span><span style="color:#98C379"> verify</span><span style="color:#D19A66"> --service</span><span style="color:#98C379"> rtdb</span><span style="color:#D19A66"> --rules</span><span style="color:#98C379"> rtdb=database.rules.json</span></span></code></pre>
+<h2 id="choose-a-verification-engine">Choose a verification engine</h2>
+<p>The default engine is <code>sandbox</code>: Firestore uses local replay and RTDB uses the
+local RTDB replay primitive. This is the fast loop for development and CI:</p>
+<pre class="astro-code one-dark-pro" style="background-color:#282c34;color:#abb2bf; overflow-x: auto;" tabindex="0" data-language="sh"><code><span class="line"><span style="color:#61AFEF">pyric</span><span style="color:#98C379"> verify</span><span style="color:#98C379"> journeys/checkout.json</span><span style="color:#D19A66"> --engine</span><span style="color:#98C379"> sandbox</span></span></code></pre>
+<p>For Firestore, you can also derive Rules Test API cases from the same fixture
+and send them to Firebase’s hosted Rules Test API:</p>
+<pre class="astro-code one-dark-pro" style="background-color:#282c34;color:#abb2bf; overflow-x: auto;" tabindex="0" data-language="sh"><code><span class="line"><span style="color:#61AFEF">pyric</span><span style="color:#98C379"> verify</span><span style="color:#98C379"> journeys/checkout.json</span><span style="color:#56B6C2"> \</span></span>
+<span class="line"><span style="color:#D19A66">  --service</span><span style="color:#98C379"> firestore</span><span style="color:#56B6C2"> \</span></span>
+<span class="line"><span style="color:#D19A66">  --engine</span><span style="color:#98C379"> rules-test-api</span><span style="color:#56B6C2"> \</span></span>
+<span class="line"><span style="color:#D19A66">  --project</span><span style="color:#98C379"> demo-app</span><span style="color:#56B6C2"> \</span></span>
+<span class="line"><span style="color:#D19A66">  --rules</span><span style="color:#98C379"> firestore=firestore.rules</span></span></code></pre>
+<p>Use <code>both</code> when you want the local sandbox replay and hosted Firestore result in
+one run:</p>
+<pre class="astro-code one-dark-pro" style="background-color:#282c34;color:#abb2bf; overflow-x: auto;" tabindex="0" data-language="sh"><code><span class="line"><span style="color:#61AFEF">pyric</span><span style="color:#98C379"> verify</span><span style="color:#98C379"> journeys/checkout.json</span><span style="color:#56B6C2"> \</span></span>
+<span class="line"><span style="color:#D19A66">  --service</span><span style="color:#98C379"> firestore</span><span style="color:#56B6C2"> \</span></span>
+<span class="line"><span style="color:#D19A66">  --engine</span><span style="color:#98C379"> both</span><span style="color:#56B6C2"> \</span></span>
+<span class="line"><span style="color:#D19A66">  --project</span><span style="color:#98C379"> demo-app</span><span style="color:#56B6C2"> \</span></span>
+<span class="line"><span style="color:#D19A66">  --rules</span><span style="color:#98C379"> firestore=firestore.rules</span></span></code></pre>
+<p>RTDB verification is sandbox-only. RTDB constraints still feed verification as
+RTDB rules JSON or an in-process <code>RtdbRulesDocument</code>; they are not a separate
+verification service.</p>
+<h2 id="inspect-derived-firestore-cases">Inspect derived Firestore cases</h2>
+<p>When you want to see exactly what will be sent to the Rules Test API, derive the
+cases without running verification:</p>
+<pre class="astro-code one-dark-pro" style="background-color:#282c34;color:#abb2bf; overflow-x: auto;" tabindex="0" data-language="sh"><code><span class="line"><span style="color:#61AFEF">pyric</span><span style="color:#98C379"> verify</span><span style="color:#98C379"> cases</span><span style="color:#98C379"> journeys/checkout.json</span><span style="color:#56B6C2"> \</span></span>
+<span class="line"><span style="color:#D19A66">  --service</span><span style="color:#98C379"> firestore</span><span style="color:#56B6C2"> \</span></span>
+<span class="line"><span style="color:#D19A66">  --out</span><span style="color:#98C379"> journeys/checkout.cases.json</span></span></code></pre>
+<p>The output contains <code>testCases</code>, warnings, and unsupported events. Admin/setup
+traffic and listener re-evaluations are excluded so the cases describe user
+behavior protected by rules.</p>
+<h2 id="verify-a-specific-fixture">Verify a specific fixture</h2>
+<p>To replay a saved fixture instead of the latest capture, pass its path:</p>
+<pre class="astro-code one-dark-pro" style="background-color:#282c34;color:#abb2bf; overflow-x: auto;" tabindex="0" data-language="sh"><code><span class="line"><span style="color:#61AFEF">pyric</span><span style="color:#98C379"> verify</span><span style="color:#98C379"> journeys/checkout.json</span></span></code></pre>
+<h2 id="interpreting-the-result">Interpreting the result</h2>
+<p>A session <strong>fails</strong> (exit code <code>1</code>) when replay finds a failing divergence:
+a write that succeeded in the sandbox would now be denied, an operation is not
+replayable, or the replayed state differs from the captured state. Each failure
+is labelled by service:</p>
+<pre class="astro-code one-dark-pro" style="background-color:#282c34;color:#abb2bf; overflow-x: auto;" tabindex="0" data-language="plaintext"><code><span class="line"><span>✗ chat - rtdb: 1 failure(s)</span></span>
+<span class="line"><span>    [rtdb] now-denied: set /rooms/r1/messages/m1 (PERMISSION_DENIED)</span></span></code></pre>
+<p>Firestore auto-id aliases, time drift, and sentinel drift are informational.
+They are expected artefacts of replaying generated values, so they do not fail
+the run. A clean run exits <code>0</code>:</p>
+<pre class="astro-code one-dark-pro" style="background-color:#282c34;color:#abb2bf; overflow-x: auto;" tabindex="0" data-language="plaintext"><code><span class="line"><span>✓ chat - firestore: ok (0 informational), rtdb: ok (0 informational)</span></span>
+<span class="line"><span></span></span>
+<span class="line"><span>✓ all selected services replay cleanly.</span></span></code></pre>
+<h2 id="run-a-suite-in-ci">Run a suite in CI</h2>
+<p>To verify many captured journeys at once, point <code>verify</code> at a directory. Every
+<code>*.json</code> fixture in it is replayed and the command exits non-zero if any one
+diverges:</p>
+<pre class="astro-code one-dark-pro" style="background-color:#282c34;color:#abb2bf; overflow-x: auto;" tabindex="0" data-language="sh"><code><span class="line"><span style="color:#61AFEF">pyric</span><span style="color:#98C379"> verify</span><span style="color:#98C379"> journeys/</span><span style="color:#D19A66"> --rules</span><span style="color:#98C379"> firestore=firestore.rules</span></span></code></pre>
+<p>Add <code>--json</code> for machine-readable output to feed into a dashboard or gate.</p>
+<p>A minimal CI step: fail the build if any captured journey would break under
+the rules being shipped:</p>
+<pre class="astro-code one-dark-pro" style="background-color:#282c34;color:#abb2bf; overflow-x: auto;" tabindex="0" data-language="yaml"><code><span class="line"><span style="color:#ABB2BF">- </span><span style="color:#E06C75">name</span><span style="color:#ABB2BF">: </span><span style="color:#98C379">Verify rules against captured journeys</span></span>
+<span class="line"><span style="color:#E06C75">  run</span><span style="color:#ABB2BF">: </span><span style="color:#98C379">pyric verify journeys/ --rules firestore=firestore.rules</span></span></code></pre>
+<p>The non-zero exit on a real divergence is what blocks the merge.</p>
+<h2 id="verify-from-code">Verify from code</h2>
+<p>Use <code>@pyric/cli/verify</code> when your RTDB rules are authored in memory:</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">verifyFixture</span><span style="color:#ABB2BF"> } </span><span style="color:#C678DD">from</span><span style="color:#98C379"> '@pyric/cli/verify'</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">rules</span><span style="color:#ABB2BF"> } </span><span style="color:#C678DD">from</span><span style="color:#98C379"> './database.rules.js'</span><span style="color:#ABB2BF">;</span></span>
+<span class="line"></span>
+<span class="line"><span style="color:#C678DD">const</span><span style="color:#E5C07B"> fixture</span><span style="color:#56B6C2"> =</span><span style="color:#E5C07B"> JSON</span><span style="color:#ABB2BF">.</span><span style="color:#61AFEF">parse</span><span style="color:#ABB2BF">(</span><span style="color:#C678DD">await</span><span style="color:#E5C07B"> Bun</span><span style="color:#ABB2BF">.</span><span style="color:#61AFEF">file</span><span style="color:#ABB2BF">(</span><span style="color:#98C379">'.pyric/last-session.json'</span><span style="color:#ABB2BF">).</span><span style="color:#61AFEF">text</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:#61AFEF"> verifyFixture</span><span style="color:#ABB2BF">(</span><span style="color:#E06C75">fixture</span><span style="color:#ABB2BF">, {</span></span>
+<span class="line"><span style="color:#E06C75">  engines</span><span style="color:#ABB2BF">: [</span><span style="color:#98C379">'sandbox'</span><span style="color:#ABB2BF">],</span></span>
+<span class="line"><span style="color:#E06C75">  rules</span><span style="color:#ABB2BF">: { </span><span style="color:#E06C75">rtdb</span><span style="color:#ABB2BF">: </span><span style="color:#E06C75">rules</span><span style="color:#ABB2BF"> },</span></span>
+<span class="line"><span style="color:#ABB2BF">});</span></span>
+<span class="line"></span>
+<span class="line"><span style="color:#C678DD">if</span><span style="color:#ABB2BF"> (</span><span style="color:#56B6C2">!</span><span style="color:#E5C07B">result</span><span style="color:#ABB2BF">.</span><span style="color:#E06C75">ok</span><span style="color:#ABB2BF">) </span><span style="color:#E5C07B">process</span><span style="color:#ABB2BF">.</span><span style="color:#61AFEF">exit</span><span style="color:#ABB2BF">(</span><span style="color:#D19A66">1</span><span style="color:#ABB2BF">);</span></span></code></pre>
+<p><code>rules</code> can be an RTDB rules JSON object or an <code>RtdbRulesDocument</code> from
+<code>defineRtdbRules()</code>.</p>
+<p>Firestore can use the hosted engine from 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">import</span><span style="color:#ABB2BF"> { </span><span style="color:#E06C75">verifyFixture</span><span style="color:#ABB2BF"> } </span><span style="color:#C678DD">from</span><span style="color:#98C379"> '@pyric/cli/verify'</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:#61AFEF"> verifyFixture</span><span style="color:#ABB2BF">(</span><span style="color:#E06C75">fixture</span><span style="color:#ABB2BF">, {</span></span>
+<span class="line"><span style="color:#E06C75">  engines</span><span style="color:#ABB2BF">: [</span><span style="color:#98C379">'rulesTestApi'</span><span style="color:#ABB2BF">],</span></span>
+<span class="line"><span style="color:#E06C75">  services</span><span style="color:#ABB2BF">: [</span><span style="color:#98C379">'firestore'</span><span style="color:#ABB2BF">],</span></span>
+<span class="line"><span style="color:#E06C75">  rules</span><span style="color:#ABB2BF">: { </span><span style="color:#E06C75">firestore</span><span style="color:#ABB2BF">: </span><span style="color:#E06C75">firestoreRulesSource</span><span style="color:#ABB2BF"> },</span></span>
+<span class="line"><span style="color:#E06C75">  rulesTestApi</span><span style="color:#ABB2BF">: {</span></span>
+<span class="line"><span style="color:#E06C75">    scope</span><span style="color:#ABB2BF">,</span></span>
+<span class="line"><span style="color:#E06C75">    expressionReportLevel</span><span style="color:#ABB2BF">: </span><span style="color:#98C379">'VISITED'</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></code></pre>
+<p>For the full flag list, see the <a href="../pyric-cli-reference-cli/#pyric-verify"><code>pyric verify</code> reference</a>.</p>  </article> </main> <aside class="doc-toc" aria-label="On this page"> <h2 class="doc-toc-heading">On this page</h2> <ul> <li data-depth="2"> <a href="#capture-a-session-then-verify">Capture a session, then verify</a> </li><li data-depth="2"> <a href="#verify-against-edited-rules">Verify against edited rules</a> </li><li data-depth="2"> <a href="#choose-a-verification-engine">Choose a verification engine</a> </li><li data-depth="2"> <a href="#inspect-derived-firestore-cases">Inspect derived Firestore cases</a> </li><li data-depth="2"> <a href="#verify-a-specific-fixture">Verify a specific fixture</a> </li><li data-depth="2"> <a href="#interpreting-the-result">Interpreting the result</a> </li><li data-depth="2"> <a href="#run-a-suite-in-ci">Run a suite in CI</a> </li><li data-depth="2"> <a href="#verify-from-code">Verify from code</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>