@pyric/cli 0.1.0-alpha.9

package/dist/serve/docs-ui/docs/pyric-rules-explanation-runtime-budget-and-shared-gates.md

@@ -0,0 +1,75 @@
+# The runtime budget and shared gates
+
+Firestore rules have two kinds of limits. Compilation limits fail loudly: a `400 INVALID_ARGUMENT` at deploy. The runtime evaluation budget fails silently: a `403 PERMISSION_DENIED` that looks identical to a denied rule.
+
+The compile-time limits have exact values. The runtime limits do not. Everything on this page is researched and observed behavior discovered by Pyric's tooling, and it explains why the linter's thresholds look the way they do.
+
+## The exact limits
+
+Three hard caps that Firebase enforces at deploy time:
+
+- **256 KB source.** Exact byte limit. Anything longer is rejected outright.
+- **Chain depth 98.** A flat `a && b && c && … && z` chain of length 99 or more refuses to compile. The limit is on chain depth, not total nodes: `(a && b) && (c && d)` has chain depth 1 of `&&`-of-`&&`s. Wrapping reduces depth.
+- **11 let bindings per function.** A function with 12 lets fails to compile.
+
+These were verified in production by deliberately building rulesets that crossed each threshold by one. The linter encodes the exact values; you get a clear error when you approach or hit them.
+
+## The hard limit
+
+Beyond those three caps, every rule evaluation runs against a runtime budget. If the budget is exhausted, the engine denies the request with no diagnostic. The request looks identical to one your `allow` rule rejected. The exhaustion is silent, and silent failures are the worst kind to debug.
+
+The budget is not a simple "you can evaluate N expressions" rule. Empirically:
+
+- **One function call with 98 expressions** passes reliably (5/5 in our production tests).
+- **Two function calls with 120 total expressions** passes reliably (5/5).
+- **Two function calls with 130 total** is **flaky** (2/5 pass).
+- **Three function calls with 60 total expressions** is **flaky** (2/5 pass).
+- **Three function calls with 90 total** is mostly stable (4/5).
+
+The pattern: function-call overhead dominates. Each call eats a non-trivial chunk of the budget. Three thin calls can fail where one fat call would succeed.
+
+Reverse-engineering: `available = base − (call_count × call_overhead)`. We don't know `base` or `call_overhead` exactly. Firestore's evaluation has a non-deterministic flaky zone where the same ruleset will sometimes pass and sometimes fail. The linter's thresholds are deliberately conservative inside the flaky zone:
+
+| Function calls in rule | Warn at | Error at |
+|---|---|---|
+| 1 or 2 | 100 expressions | 120 |
+| 3 | 60 | 90 |
+| 4+ | 40 | 60 |
+
+These over-flag. Some rules in the flaky zone work in practice. The alternative is under-flagging and shipping rules that work in dev and fail under load.
+
+## Shared gates
+
+Even with a single rule sitting comfortably inside its budget, two rules in the same match block can collectively blow it. This is the "shared gate" problem, and the linter's `SHARED_GATE` warning exists because it took an entire weekend of chess debugging to figure out.
+
+The scenario: two `allow update` rules whose conditions both start with the same first expression, say `request.auth.uid == resource.data.host`. The engine evaluates each rule against the request. Even though only one rule actually applies, the prefix evaluation happens in both. If each rule's body is near the budget on its own, their combined evaluation crosses the line.
+
+The fix is to give each rule a unique first expression, a discriminator. Instead of:
+
+```rules
+allow update: if request.auth.uid == resource.data.host && validBigCheckA();
+allow update: if request.auth.uid == resource.data.host && validBigCheckB();
+```
+
+route on something distinct:
+
+```rules
+allow update: if request.resource.data.moveType == 'A' && validBigCheckA();
+allow update: if request.resource.data.moveType == 'B' && validBigCheckB();
+```
+
+Now each rule short-circuits before its heavy body runs, and the engine doesn't end up evaluating both bodies in parallel.
+
+The linter detects `SHARED_GATE` by computing a structural fingerprint of every rule's first expression and grouping by fingerprint. Two or more rules with the same fingerprint produce a warning.
+
+## Get-call costs
+
+A separate hard limit applies to document reads from rules (`get(...)` and `exists(...)`): 10 per rule. The linter's `GET_COUNT` rule warns at 5 and errors at 10. Firestore caches same-path calls within a single rule evaluation, but only for the same path: `get(users/$(uid))` and `get(users/$(otherUid))` are two reads, not one.
+
+`GET_DUPLICATION` catches a related agent failure mode: a helper function that internally calls `get()`, invoked multiple times from the same rule. The agent thinks it's calling a tidy abstraction; the engine sees N reads. The fix is to wrap the calls in a function that caches via a `let`.
+
+## Why the linter sometimes blocks the deploy
+
+Most lint warnings are advisory. A handful are not: `SOURCE_SIZE`, `CHAIN_DEPTH` (above the band), `LET_LIMIT`, `GET_COUNT` (above 10), `PERMISSIVE_RULE`, `RECURSIVE_WILDCARD_OPEN`, `HALLUCINATED_METHOD`, `INVALID_OPERATOR`. Treat `severity: 'error'` as a hard gate before `firebase deploy`. The choice is deliberate: these are the categories where the cost of shipping the bad rule is high (a deploy that fails compilation; a publicly-readable database) and the cost of demanding a fix is low (the linter tells you exactly what's wrong).
+
+`RULES_WEAKENED` is `warning`, not `error`. There are legitimate reasons to remove a predicate: a refactor, a dedupe, an intentional broadening. The signal is "review this", not "block the deploy".

package/dist/serve/docs-ui/docs/pyric-rules-explanation-sentinel-expression-engine/index.html

@@ -0,0 +1,49 @@
+<!DOCTYPE html><html lang="en"> <head><meta charset="UTF-8"><meta name="viewport" content="width=device-width, initial-scale=1.0"><title>The sentinel expression engine ($expr) · 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/" aria-current="true"> pyric / rules </a> </li><li> <a href="/__pyric/ui/docs/pyric-sandbox/"> pyric / sandbox </a> </li><li> <a href="/__pyric/ui/docs/pyric-storage/"> pyric / storage </a> </li><li> <a href="/__pyric/ui/docs/pyric-auth/"> pyric / auth </a> </li><li> <a href="/__pyric/ui/docs/pyric-database/"> pyric / database </a> </li><li> <a href="/__pyric/ui/docs/pyric-admin-app/"> pyric-admin / app </a> </li><li> <a href="/__pyric/ui/docs/pyric-admin-firestore/"> pyric-admin / firestore </a> </li><li> <a href="/__pyric/ui/docs/pyric-admin-auth/"> pyric-admin / auth </a> </li><li> <a href="/__pyric/ui/docs/pyric-admin-database/"> pyric-admin / database </a> </li><li> <a href="/__pyric/ui/docs/pyric-admin-storage/"> pyric-admin / storage </a> </li><li> <a href="/__pyric/ui/docs/ui/"> @pyric/ui </a> </li><li> <a href="/__pyric/ui/docs/api-reference/"> API reference </a> </li> </ul> </div> </div> </details> </nav> </details> <nav class="docs-nav" aria-label="Documentation"> <div class="docs-search" data-index-url="/__pyric/ui/docs/index.json"> <div class="docs-search-field"> <svg class="docs-search-icon" viewBox="0 0 16 16" width="14" height="14" aria-hidden="true"> <path d="M11.5 11.5 15 15M13 7A6 6 0 1 1 1 7a6 6 0 0 1 12 0Z" fill="none" stroke="currentColor" stroke-width="1.4" stroke-linecap="round"></path> </svg> <input type="text" class="docs-search-input" placeholder="Search docs" aria-label="Search docs" autocomplete="off" spellcheck="false"> <kbd class="docs-search-kbd">⌘K</kbd> </div> <ul class="docs-search-results" hidden></ul> </div>  <a class="docs-nav-toplink" href="/__pyric/ui/docs/overview/" id="nav-group-overview"> Overview </a><details class="docs-nav-group" id="nav-group-run-locally"> <summary>Run locally</summary> <div class="docs-nav-group-body"> <div class="docs-nav-section">  <ul> <li> <a href="/__pyric/ui/docs/start-building/"> Quickstart </a> </li><li> <a href="/__pyric/ui/docs/how-the-swap-works/"> How the swap works </a> </li><li> <a href="/__pyric/ui/docs/set-up-your-agent/"> Connect an agent </a> </li><li> <a href="/__pyric/ui/docs/test-in-node/"> Test in Node </a> </li> </ul> </div> </div> </details><details class="docs-nav-group" id="nav-group-develop-with-firebase-apis"> <summary>Develop with Firebase APIs</summary> <div class="docs-nav-group-body"> <div class="docs-nav-section">  <ul> <li> <a href="/__pyric/ui/docs/sign-in-and-manage-users/"> Sign in and manage users </a> </li><li> <a href="/__pyric/ui/docs/store-and-query-data/"> Store and query data </a> </li><li> <a href="/__pyric/ui/docs/sync-realtime-data/"> Sync realtime data </a> </li><li> <a href="/__pyric/ui/docs/store-files/"> Store files </a> </li><li> <a href="/__pyric/ui/docs/receive-messages/"> Receive messages </a> </li><li> <a href="/__pyric/ui/docs/run-ai-logic-locally/"> Run AI Logic locally </a> </li><li> <a href="/__pyric/ui/docs/pyric-cli-how-to-run-rtdb-onvaluecreated/"> Run an RTDB function locally </a> </li><li> <a href="/__pyric/ui/docs/which-data-service/"> Which data service? </a> </li> </ul> </div> </div> </details><details class="docs-nav-group" id="nav-group-inspect-and-correct"> <summary>Inspect and correct</summary> <div class="docs-nav-group-body"> <div class="docs-nav-section"> <h2 class="docs-nav-heading" id="nav-section-inspect-and-correct-inspect-the-sandbox"> Inspect the sandbox </h2> <ul> <li> <a href="/__pyric/ui/docs/see-whats-happening/"> Traffic &amp; rule verdicts </a> </li><li> <a href="/__pyric/ui/docs/read-a-denial/"> Read a denial and understand it </a> </li><li> <a href="/__pyric/ui/docs/shape-your-data/"> Seed, snapshot, replay </a> </li><li> <a href="/__pyric/ui/docs/watch-and-review/"> Review agent activity </a> </li> </ul> </div><div class="docs-nav-section"> <h2 class="docs-nav-heading" id="nav-section-inspect-and-correct-correct-security-rules"> Correct Security Rules </h2> <ul> <li> <a href="/__pyric/ui/docs/secure-it-with-rules/"> Security Rules </a> </li><li> <a href="/__pyric/ui/docs/simulate-and-lint/"> Simulate and lint before you deploy </a> </li><li> <a href="/__pyric/ui/docs/rules-patterns/"> Rules patterns </a> </li><li> <a href="/__pyric/ui/docs/rules-standard-library/"> The rules standard library </a> </li><li> <a href="/__pyric/ui/docs/rtdb-rules-in-typescript/"> RTDB rules in TypeScript </a> </li><li> <a href="/__pyric/ui/docs/firestore-rules-limits/"> Rules limits </a> </li><li> <a href="/__pyric/ui/docs/whats-possible/"> Case studies </a> </li> </ul> </div><div class="docs-nav-section"> <h2 class="docs-nav-heading" id="nav-section-inspect-and-correct-work-with-an-agent"> Work with an agent </h2> <ul> <li> <a href="/__pyric/ui/docs/what-your-agent-can-do/"> Work through an agent </a> </li><li> <a href="/__pyric/ui/docs/skills/"> Agent skills </a> </li> </ul> </div> </div> </details><details class="docs-nav-group" id="nav-group-verify-the-boundary"> <summary>Verify the boundary</summary> <div class="docs-nav-group-body"> <div class="docs-nav-section">  <ul> <li> <a href="/__pyric/ui/docs/pyric-cli-how-to-verify-against-a-captured-session/"> Verify a captured session </a> </li><li> <a href="/__pyric/ui/docs/write-a-rules-test-suite/"> Write a rules test suite </a> </li><li> <a href="/__pyric/ui/docs/audit-your-rules/"> Audit rules and data </a> </li> </ul> </div> </div> </details><details class="docs-nav-group" id="nav-group-ship-unchanged"> <summary>Ship unchanged</summary> <div class="docs-nav-group-body"> <div class="docs-nav-section">  <ul> <li> <a href="/__pyric/ui/docs/ship-to-production/"> Ship to production </a> </li><li> <a href="/__pyric/ui/docs/set-up-the-project/"> Set up the Firebase project </a> </li> </ul> </div> </div> </details><details class="docs-nav-group" id="nav-group-conformance"> <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/" aria-current="true"> 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-rules/">pyric / rules</a> </li><li> <span class="docs-breadcrumbs-sep" aria-hidden="true">/</span> <span>Explanation</span> </li><li> <span class="docs-breadcrumbs-sep" aria-hidden="true">/</span> <span aria-current="page">Sentinel expression engine</span> </li> </ol> </nav>  <article class="prose">  <h1 id="the-sentinel-expression-engine-expr">The sentinel expression engine (<code>$expr</code>)</h1>
+<p>Firestore writes are usually concrete: <code>{ count: 5, owner: 'alice' }</code>. But sometimes you want a write whose value depends on the document at write time: “increment <code>count</code> by one if it’s less than 100”, “set <code>lastSeen</code> to the current request time”, “merge this list with the existing one and dedupe”. The Firestore SDK offers a handful of <code>FieldValue</code> sentinels for the most common cases (<code>increment</code>, <code>arrayUnion</code>, <code>serverTimestamp</code>), but anything outside that small set requires a transaction.</p>
+<p>The sentinel expression engine extends that surface. It defines a tiny expression DSL that can appear anywhere in a write payload, wrapped as <code>{ $expr: '...' }</code>. At commit time, every wrapper is resolved against the current document, <em>before</em> the write hits the data plane. The result is a fully-concrete payload that Firestore stores normally.</p>
+<p>The engine is small (a hand-written lexer, parser, evaluator) and intentionally separate from the Firestore rules grammar. It powers <code>pyric/sandbox</code>’s declarative transactions. This page explains the model.</p>
+<h2 id="the-shape">The shape</h2>
+<p>A wrapper is an object whose <em>only</em> key is <code>$expr</code> and whose value is a string:</p>
+<pre class="astro-code one-dark-pro" style="background-color:#282c34;color:#abb2bf; overflow-x: auto;" tabindex="0" data-language="ts"><code><span class="line"><span style="color:#ABB2BF">{ </span><span style="color:#E06C75">count</span><span style="color:#ABB2BF">: { </span><span style="color:#E06C75">$expr</span><span style="color:#ABB2BF">: </span><span style="color:#98C379">'doc.count + 1'</span><span style="color:#ABB2BF"> } }</span></span></code></pre>
+<p>Anything else (extra keys alongside <code>$expr</code>, non-string <code>$expr</code> values, nested wrappers without proper shape) is rejected with <code>ExpressionWalkError</code>. The strict shape is deliberate: it makes the wrapper instantly recognisable when scanning a payload, and it prevents accidental collisions with field names.</p>
+<h2 id="the-walker">The walker</h2>
+<p><code>resolveExpressionsInData(data, env)</code> walks the payload tree once:</p>
+<ul>
+<li>For each plain object, it checks “is this a wrapper?”. If yes, evaluate the expression against <code>env</code> and use the result as the value.</li>
+<li>For each non-wrapper object, recurse into its values.</li>
+<li>For each array, preserve length and order; recurse into each element.</li>
+<li>Leaves (primitives, <code>null</code>, sentinel passthroughs) are unchanged.</li>
+</ul>
+<p>The walker doesn’t recurse into eval results. If a <code>$expr</code> resolves to an object that itself contains a <code>$expr</code> key, that nested key is treated as data, not another wrapper. Without this rule, you’d have wrappers chained through document reads in non-obvious ways.</p>
+<h2 id="the-dsl">The DSL</h2>
+<p>The expression language has just enough surface to be useful and small enough to be safe:</p>
+<ul>
+<li><strong>Identifiers</strong> read from <code>env</code>: <code>doc</code>, <code>now</code>, <code>auth</code>. The environment is supplied by the caller; sandbox transactions populate it with the document under the write, the server time, and the auth context.</li>
+<li><strong>Member access</strong>: <code>doc.count</code>, <code>auth.uid</code>.</li>
+<li><strong>Numeric arithmetic</strong>: <code>+</code>, <code>-</code>, <code>*</code>, <code>/</code>, <code>%</code>.</li>
+<li><strong>Comparison</strong>: <code>==</code>, <code>!=</code>, <code>&#x3C;</code>, <code>&#x3C;=</code>, <code>></code>, <code>>=</code>.</li>
+<li><strong>Logical</strong>: <code>&#x26;&#x26;</code>, <code>||</code>, <code>!</code>.</li>
+<li><strong>Ternary</strong>: <code>cond ? then : else</code>.</li>
+<li><strong>Built-ins</strong>: a curated set. <code>min</code>, <code>max</code>, <code>concat</code>, <code>length</code>, plus deliberate omissions like <code>eval</code> and <code>fetch</code>.</li>
+</ul>
+<p>No I/O. No loops. No assignment. No function definitions. The DSL is intentionally not Turing-complete; the expression has to terminate in bounded time.</p>
+<h2 id="why-a-separate-parser">Why a separate parser</h2>
+<p>The rules grammar (the one in <code>FirestoreRules.ohm</code>) is much larger: imports, services, match blocks, allow statements, <code>is</code> expressions, path literals. Reusing it for <code>$expr</code> would buy nothing (rules-grammar features like <code>match</code> and <code>allow</code> are meaningless inside a payload) and would carry every rules-grammar quirk into the DSL. Worst case, a typo in <code>$expr</code> would produce an opaque parser error that mentioned <code>allow read: if</code>.</p>
+<p>A hand-written lexer and parser stay small (a few hundred lines), produce focused error messages with <code>line:column</code> positions, and let us evolve the DSL without disturbing the rules language.</p>
+<h2 id="error-model">Error model</h2>
+<p>Three classes of failure, each with a distinct error type:</p>
+<ul>
+<li><strong><code>ExpressionWalkError</code></strong>: wrong wrapper shape. The walker found <code>$expr</code> alongside other keys, or with a non-string value. Carries a dotted <code>path</code> to the offending leaf.</li>
+<li><strong><code>ExpressionLexError</code></strong>: the expression string contained characters the lexer doesn’t recognise. Carries a position.</li>
+<li><strong><code>ExpressionParseError</code></strong>: the token stream didn’t form a valid expression. Carries a position.</li>
+<li><strong><code>EvalError</code></strong>: the expression parsed but failed at runtime (missing identifier, type mismatch).</li>
+</ul>
+<p>The four types let tool authors translate each failure into a precise diagnostic: shape errors point at the payload, lex/parse errors point at the expression string, eval errors point at the runtime context.</p>
+<h2 id="when-to-reach-for-expr">When to reach for <code>$expr</code></h2>
+<p>The sandbox layer uses <code>$expr</code> in its declarative transaction API:</p>
+<pre class="astro-code one-dark-pro" style="background-color:#282c34;color:#abb2bf; overflow-x: auto;" tabindex="0" data-language="ts"><code><span class="line"><span style="color:#C678DD">await</span><span style="color:#E5C07B"> sandbox</span><span style="color:#ABB2BF">.</span><span style="color:#61AFEF">firestore</span><span style="color:#ABB2BF">(</span><span style="color:#98C379">'/notes/n1'</span><span style="color:#ABB2BF">).</span><span style="color:#61AFEF">set</span><span style="color:#ABB2BF">({</span></span>
+<span class="line"><span style="color:#E06C75">  count</span><span style="color:#ABB2BF">: { </span><span style="color:#E06C75">$expr</span><span style="color:#ABB2BF">: </span><span style="color:#98C379">'doc.count + 1'</span><span style="color:#ABB2BF"> },</span></span>
+<span class="line"><span style="color:#E06C75">  lastSeen</span><span style="color:#ABB2BF">: { </span><span style="color:#E06C75">$expr</span><span style="color:#ABB2BF">: </span><span style="color:#98C379">'now'</span><span style="color:#ABB2BF"> },</span></span>
+<span class="line"><span style="color:#ABB2BF">}, { </span><span style="color:#E06C75">merge</span><span style="color:#ABB2BF">: </span><span style="color:#D19A66">true</span><span style="color:#ABB2BF"> });</span></span></code></pre>
+<p>Outside the sandbox, you generally don’t need it. The production Firestore data plane has <code>FieldValue.increment</code> and <code>FieldValue.serverTimestamp</code> for the common cases. The engine exists because the sandbox needs a way to express <em>any</em> depends-on-current-state write without each write becoming a four-step transaction.</p>
+<p>If you’re building tooling that operates on <code>$expr</code>-bearing payloads (for example, a UI that displays pending writes), you’ll want <code>resolveExpressionsInData</code> and <code>tokenize</code> / <code>parse</code> to inspect the expressions before they resolve. Both are exported for that reason.</p>  </article> </main> <aside class="doc-toc" aria-label="On this page"> <h2 class="doc-toc-heading">On this page</h2> <ul> <li data-depth="2"> <a href="#the-shape">The shape</a> </li><li data-depth="2"> <a href="#the-walker">The walker</a> </li><li data-depth="2"> <a href="#the-dsl">The DSL</a> </li><li data-depth="2"> <a href="#why-a-separate-parser">Why a separate parser</a> </li><li data-depth="2"> <a href="#error-model">Error model</a> </li><li data-depth="2"> <a href="#when-to-reach-for-expr">When to reach for $expr</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-rules-explanation-sentinel-expression-engine.md

@@ -0,0 +1,74 @@
+# The sentinel expression engine (`$expr`)
+
+Firestore writes are usually concrete: `{ count: 5, owner: 'alice' }`. But sometimes you want a write whose value depends on the document at write time: "increment `count` by one if it's less than 100", "set `lastSeen` to the current request time", "merge this list with the existing one and dedupe". The Firestore SDK offers a handful of `FieldValue` sentinels for the most common cases (`increment`, `arrayUnion`, `serverTimestamp`), but anything outside that small set requires a transaction.
+
+The sentinel expression engine extends that surface. It defines a tiny expression DSL that can appear anywhere in a write payload, wrapped as `{ $expr: '...' }`. At commit time, every wrapper is resolved against the current document, *before* the write hits the data plane. The result is a fully-concrete payload that Firestore stores normally.
+
+The engine is small (a hand-written lexer, parser, evaluator) and intentionally separate from the Firestore rules grammar. It powers `pyric/sandbox`'s declarative transactions. This page explains the model.
+
+## The shape
+
+A wrapper is an object whose *only* key is `$expr` and whose value is a string:
+
+```ts
+{ count: { $expr: 'doc.count + 1' } }
+```
+
+Anything else (extra keys alongside `$expr`, non-string `$expr` values, nested wrappers without proper shape) is rejected with `ExpressionWalkError`. The strict shape is deliberate: it makes the wrapper instantly recognisable when scanning a payload, and it prevents accidental collisions with field names.
+
+## The walker
+
+`resolveExpressionsInData(data, env)` walks the payload tree once:
+
+- For each plain object, it checks "is this a wrapper?". If yes, evaluate the expression against `env` and use the result as the value.
+- For each non-wrapper object, recurse into its values.
+- For each array, preserve length and order; recurse into each element.
+- Leaves (primitives, `null`, sentinel passthroughs) are unchanged.
+
+The walker doesn't recurse into eval results. If a `$expr` resolves to an object that itself contains a `$expr` key, that nested key is treated as data, not another wrapper. Without this rule, you'd have wrappers chained through document reads in non-obvious ways.
+
+## The DSL
+
+The expression language has just enough surface to be useful and small enough to be safe:
+
+- **Identifiers** read from `env`: `doc`, `now`, `auth`. The environment is supplied by the caller; sandbox transactions populate it with the document under the write, the server time, and the auth context.
+- **Member access**: `doc.count`, `auth.uid`.
+- **Numeric arithmetic**: `+`, `-`, `*`, `/`, `%`.
+- **Comparison**: `==`, `!=`, `<`, `<=`, `>`, `>=`.
+- **Logical**: `&&`, `||`, `!`.
+- **Ternary**: `cond ? then : else`.
+- **Built-ins**: a curated set. `min`, `max`, `concat`, `length`, plus deliberate omissions like `eval` and `fetch`.
+
+No I/O. No loops. No assignment. No function definitions. The DSL is intentionally not Turing-complete; the expression has to terminate in bounded time.
+
+## Why a separate parser
+
+The rules grammar (the one in `FirestoreRules.ohm`) is much larger: imports, services, match blocks, allow statements, `is` expressions, path literals. Reusing it for `$expr` would buy nothing (rules-grammar features like `match` and `allow` are meaningless inside a payload) and would carry every rules-grammar quirk into the DSL. Worst case, a typo in `$expr` would produce an opaque parser error that mentioned `allow read: if`.
+
+A hand-written lexer and parser stay small (a few hundred lines), produce focused error messages with `line:column` positions, and let us evolve the DSL without disturbing the rules language.
+
+## Error model
+
+Three classes of failure, each with a distinct error type:
+
+- **`ExpressionWalkError`**: wrong wrapper shape. The walker found `$expr` alongside other keys, or with a non-string value. Carries a dotted `path` to the offending leaf.
+- **`ExpressionLexError`**: the expression string contained characters the lexer doesn't recognise. Carries a position.
+- **`ExpressionParseError`**: the token stream didn't form a valid expression. Carries a position.
+- **`EvalError`**: the expression parsed but failed at runtime (missing identifier, type mismatch).
+
+The four types let tool authors translate each failure into a precise diagnostic: shape errors point at the payload, lex/parse errors point at the expression string, eval errors point at the runtime context.
+
+## When to reach for `$expr`
+
+The sandbox layer uses `$expr` in its declarative transaction API:
+
+```ts
+await sandbox.firestore('/notes/n1').set({
+  count: { $expr: 'doc.count + 1' },
+  lastSeen: { $expr: 'now' },
+}, { merge: true });
+```
+
+Outside the sandbox, you generally don't need it. The production Firestore data plane has `FieldValue.increment` and `FieldValue.serverTimestamp` for the common cases. The engine exists because the sandbox needs a way to express *any* depends-on-current-state write without each write becoming a four-step transaction.
+
+If you're building tooling that operates on `$expr`-bearing payloads (for example, a UI that displays pending writes), you'll want `resolveExpressionsInData` and `tokenize` / `parse` to inspect the expressions before they resolve. Both are exported for that reason.

package/dist/serve/docs-ui/docs/pyric-rules-explanation-simulator-vs-rules-test-api/index.html

@@ -0,0 +1,95 @@
+<!DOCTYPE html><html lang="en"> <head><meta charset="UTF-8"><meta name="viewport" content="width=device-width, initial-scale=1.0"><title>Simulator vs Rules Test API · 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/" aria-current="true"> pyric / rules </a> </li><li> <a href="/__pyric/ui/docs/pyric-sandbox/"> pyric / sandbox </a> </li><li> <a href="/__pyric/ui/docs/pyric-storage/"> pyric / storage </a> </li><li> <a href="/__pyric/ui/docs/pyric-auth/"> pyric / auth </a> </li><li> <a href="/__pyric/ui/docs/pyric-database/"> pyric / database </a> </li><li> <a href="/__pyric/ui/docs/pyric-admin-app/"> pyric-admin / app </a> </li><li> <a href="/__pyric/ui/docs/pyric-admin-firestore/"> pyric-admin / firestore </a> </li><li> <a href="/__pyric/ui/docs/pyric-admin-auth/"> pyric-admin / auth </a> </li><li> <a href="/__pyric/ui/docs/pyric-admin-database/"> pyric-admin / database </a> </li><li> <a href="/__pyric/ui/docs/pyric-admin-storage/"> pyric-admin / storage </a> </li><li> <a href="/__pyric/ui/docs/ui/"> @pyric/ui </a> </li><li> <a href="/__pyric/ui/docs/api-reference/"> API reference </a> </li> </ul> </div> </div> </details> </nav> </details> <nav class="docs-nav" aria-label="Documentation"> <div class="docs-search" data-index-url="/__pyric/ui/docs/index.json"> <div class="docs-search-field"> <svg class="docs-search-icon" viewBox="0 0 16 16" width="14" height="14" aria-hidden="true"> <path d="M11.5 11.5 15 15M13 7A6 6 0 1 1 1 7a6 6 0 0 1 12 0Z" fill="none" stroke="currentColor" stroke-width="1.4" stroke-linecap="round"></path> </svg> <input type="text" class="docs-search-input" placeholder="Search docs" aria-label="Search docs" autocomplete="off" spellcheck="false"> <kbd class="docs-search-kbd">⌘K</kbd> </div> <ul class="docs-search-results" hidden></ul> </div>  <a class="docs-nav-toplink" href="/__pyric/ui/docs/overview/" id="nav-group-overview"> Overview </a><details class="docs-nav-group" id="nav-group-run-locally"> <summary>Run locally</summary> <div class="docs-nav-group-body"> <div class="docs-nav-section">  <ul> <li> <a href="/__pyric/ui/docs/start-building/"> Quickstart </a> </li><li> <a href="/__pyric/ui/docs/how-the-swap-works/"> How the swap works </a> </li><li> <a href="/__pyric/ui/docs/set-up-your-agent/"> Connect an agent </a> </li><li> <a href="/__pyric/ui/docs/test-in-node/"> Test in Node </a> </li> </ul> </div> </div> </details><details class="docs-nav-group" id="nav-group-develop-with-firebase-apis"> <summary>Develop with Firebase APIs</summary> <div class="docs-nav-group-body"> <div class="docs-nav-section">  <ul> <li> <a href="/__pyric/ui/docs/sign-in-and-manage-users/"> Sign in and manage users </a> </li><li> <a href="/__pyric/ui/docs/store-and-query-data/"> Store and query data </a> </li><li> <a href="/__pyric/ui/docs/sync-realtime-data/"> Sync realtime data </a> </li><li> <a href="/__pyric/ui/docs/store-files/"> Store files </a> </li><li> <a href="/__pyric/ui/docs/receive-messages/"> Receive messages </a> </li><li> <a href="/__pyric/ui/docs/run-ai-logic-locally/"> Run AI Logic locally </a> </li><li> <a href="/__pyric/ui/docs/pyric-cli-how-to-run-rtdb-onvaluecreated/"> Run an RTDB function locally </a> </li><li> <a href="/__pyric/ui/docs/which-data-service/"> Which data service? </a> </li> </ul> </div> </div> </details><details class="docs-nav-group" id="nav-group-inspect-and-correct"> <summary>Inspect and correct</summary> <div class="docs-nav-group-body"> <div class="docs-nav-section"> <h2 class="docs-nav-heading" id="nav-section-inspect-and-correct-inspect-the-sandbox"> Inspect the sandbox </h2> <ul> <li> <a href="/__pyric/ui/docs/see-whats-happening/"> Traffic &amp; rule verdicts </a> </li><li> <a href="/__pyric/ui/docs/read-a-denial/"> Read a denial and understand it </a> </li><li> <a href="/__pyric/ui/docs/shape-your-data/"> Seed, snapshot, replay </a> </li><li> <a href="/__pyric/ui/docs/watch-and-review/"> Review agent activity </a> </li> </ul> </div><div class="docs-nav-section"> <h2 class="docs-nav-heading" id="nav-section-inspect-and-correct-correct-security-rules"> Correct Security Rules </h2> <ul> <li> <a href="/__pyric/ui/docs/secure-it-with-rules/"> Security Rules </a> </li><li> <a href="/__pyric/ui/docs/simulate-and-lint/"> Simulate and lint before you deploy </a> </li><li> <a href="/__pyric/ui/docs/rules-patterns/"> Rules patterns </a> </li><li> <a href="/__pyric/ui/docs/rules-standard-library/"> The rules standard library </a> </li><li> <a href="/__pyric/ui/docs/rtdb-rules-in-typescript/"> RTDB rules in TypeScript </a> </li><li> <a href="/__pyric/ui/docs/firestore-rules-limits/"> Rules limits </a> </li><li> <a href="/__pyric/ui/docs/whats-possible/"> Case studies </a> </li> </ul> </div><div class="docs-nav-section"> <h2 class="docs-nav-heading" id="nav-section-inspect-and-correct-work-with-an-agent"> Work with an agent </h2> <ul> <li> <a href="/__pyric/ui/docs/what-your-agent-can-do/"> Work through an agent </a> </li><li> <a href="/__pyric/ui/docs/skills/"> Agent skills </a> </li> </ul> </div> </div> </details><details class="docs-nav-group" id="nav-group-verify-the-boundary"> <summary>Verify the boundary</summary> <div class="docs-nav-group-body"> <div class="docs-nav-section">  <ul> <li> <a href="/__pyric/ui/docs/pyric-cli-how-to-verify-against-a-captured-session/"> Verify a captured session </a> </li><li> <a href="/__pyric/ui/docs/write-a-rules-test-suite/"> Write a rules test suite </a> </li><li> <a href="/__pyric/ui/docs/audit-your-rules/"> Audit rules and data </a> </li> </ul> </div> </div> </details><details class="docs-nav-group" id="nav-group-ship-unchanged"> <summary>Ship unchanged</summary> <div class="docs-nav-group-body"> <div class="docs-nav-section">  <ul> <li> <a href="/__pyric/ui/docs/ship-to-production/"> Ship to production </a> </li><li> <a href="/__pyric/ui/docs/set-up-the-project/"> Set up the Firebase project </a> </li> </ul> </div> </div> </details><details class="docs-nav-group" id="nav-group-conformance"> <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/" aria-current="true"> 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-rules/">pyric / rules</a> </li><li> <span class="docs-breadcrumbs-sep" aria-hidden="true">/</span> <span>Explanation</span> </li><li> <span class="docs-breadcrumbs-sep" aria-hidden="true">/</span> <span aria-current="page">Simulator vs Rules Test API</span> </li> </ol> </nav>  <article class="prose">  <h1 id="simulator-vs-rules-test-api">Simulator vs Rules Test API</h1>
+<p>Two surfaces evaluate rules against test cases. Underneath, they share a case shape and a result vocabulary; they disagree on tradeoffs. Choosing between them is a deliberate decision, not an implementation detail.</p>
+<h2 id="the-shared-surface">The shared surface</h2>
+<p>The public front door only fronts one of the two: <code>firestoreRules(source).simulate(cases)</code> runs the local simulator, takes <code>FirestoreCase[]</code>, and returns a <code>SimulationSummary</code> (<code>{ passed, failed, unsupported, cases: CaseResult[] }</code>) that never carries a thrown-error branch, since a parse failure already threw <code>RulesCompileError</code> at construction.</p>
+<p>The Rules Test API has no public front door yet. Both engines still share their case and result vocabulary one level down, on <code>pyric/rules/internal</code>: <code>TestFirestoreRulesHandler.execute</code> (the Rules Test API client) and the internal <code>SimulateFirestoreRulesHandler.simulate</code> both take a rules source and a list of <code>TestCase</code> objects (the same shape as the public <code>FirestoreCase</code>), and both return a <code>TestFirestoreRulesResult</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">type</span><span style="color:#E5C07B"> TestFirestoreRulesResult</span><span style="color:#56B6C2"> =</span></span>
+<span class="line"><span style="color:#ABB2BF">  | { </span><span style="color:#E06C75">success</span><span style="color:#ABB2BF">: </span><span style="color:#E5C07B">true</span><span style="color:#ABB2BF">; </span><span style="color:#E06C75">data</span><span style="color:#ABB2BF">: { </span><span style="color:#E06C75">passed</span><span style="color:#ABB2BF">; </span><span style="color:#E06C75">failed</span><span style="color:#ABB2BF">; </span><span style="color:#E06C75">unsupported</span><span style="color:#ABB2BF">; </span><span style="color:#E06C75">results</span><span style="color:#ABB2BF"> } }</span></span>
+<span class="line"><span style="color:#ABB2BF">  | { </span><span style="color:#E06C75">success</span><span style="color:#ABB2BF">: </span><span style="color:#E5C07B">false</span><span style="color:#ABB2BF">; </span><span style="color:#E06C75">error</span><span style="color:#ABB2BF">: { </span><span style="color:#E06C75">code</span><span style="color:#ABB2BF">; </span><span style="color:#E06C75">message</span><span style="color:#ABB2BF">; </span><span style="color:#E06C75">recoverable</span><span style="color:#ABB2BF"> } };</span></span></code></pre>
+<p>Each <code>TestResult</code> in <code>results</code> carries <code>description</code>, <code>expectation</code>, <code>state</code>, and <code>debugMessages</code>. The <code>state</code> is <code>'PASSED' | 'FAILED' | 'UNSUPPORTED'</code>.</p>
+<p>The shared internal shape is a feature. You can swap one internal handler for the other, or route the same test suite to both, without rewriting any test-case code. See <a href="../pyric-rules-how-to-test-rules-against-firebase/">How to test rules against the Firebase Rules Test API</a> for the escalation pattern built on the public <code>simulate</code> plus the internal test-API client.</p>
+<h2 id="what-they-disagree-on">What they disagree on</h2>
+<div class="table-scroll">
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+<table><thead><tr><th>Axis</th><th>Local simulator</th><th>Rules Test API</th></tr></thead><tbody><tr><td>Where it runs</td><td>In-process</td><td>Google’s servers</td></tr><tr><td>Latency per call</td><td>Sub-millisecond</td><td>Tens to hundreds of milliseconds</td></tr><tr><td>Credentials required</td><td>None</td><td><code>ProjectScope</code> with <code>firebaserules.releases.test</code></td></tr><tr><td>Parity with production</td><td>Close, not bit-for-bit</td><td>Bit-for-bit</td></tr><tr><td>Returns <code>UNSUPPORTED</code>?</td><td>Yes, when it hits an unimplemented feature</td><td>Never</td></tr><tr><td>Side effects</td><td>None</td><td>None (the API evaluates, it doesn’t deploy)</td></tr><tr><td>Cost</td><td>Free</td><td>Costs of the Cloud API call</td></tr></tbody></table></div>
+<h2 id="when-the-simulator-returns-unsupported">When the simulator returns <code>UNSUPPORTED</code></h2>
+<p>The local simulator implements most of the rules language: literals, identifiers, member access, method calls, all the binary and unary operators, function definitions with let bindings, all the standard built-ins (<code>get</code>, <code>exists</code>, <code>getAfter</code>, <code>existsAfter</code>, <code>debug</code>, <code>request.auth</code>, <code>request.resource</code>, <code>resource</code>, path literals, the type-test <code>is</code> operator). It does <strong>not</strong> implement every namespace method on every wrapper type. <code>duration.value(...).abs()</code> works, some less-common <code>bytes</code> arithmetic does not.</p>
+<p>When the evaluator hits a method or operation it doesn’t model, it throws <code>UnsupportedError</code> rather than guessing. The handler catches that and surfaces it as an abstention: <code>state: 'UNSUPPORTED'</code> internally, <code>unsupported: true</code> on the public <code>CaseResult</code>. The semantics is “the gap is on my side, not yours”. An unsupported case is <strong>not</strong> counted as a failure: <code>failed</code> and <code>unsupported</code> are separate counters on both the internal result and the public <code>SimulationSummary</code>.</p>
+<p>The right response to <code>UNSUPPORTED</code> depends on context:</p>
+<ul>
+<li><strong>Agent loops</strong> can treat <code>UNSUPPORTED</code> as “don’t know, ask the API”. A common pattern is to run locally first, then escalate only the unsupported subset to the live API.</li>
+<li><strong>CI</strong> can treat <code>UNSUPPORTED</code> as a build-time signal: “this rule uses a feature the simulator doesn’t model, so switch this case to the live API or restructure the rule”.</li>
+<li><strong>Local development</strong> can ignore <code>UNSUPPORTED</code> until the rule is otherwise correct, then verify against the API once.</li>
+</ul>
+<h2 id="when-the-simulator-is-wrong">When the simulator is wrong</h2>
+<p>It does happen. The simulator is a re-implementation of the rules engine, not a transcription. Areas where production has surprised us:</p>
+<ul>
+<li><strong>Timestamp precision</strong>: <code>request.time</code> in production has nanosecond precision; our <code>Timestamp</code> wrapper carries it, but agents that round to milliseconds in their test data can produce <code>request.time != data.createdAt</code> when production would say they’re equal.</li>
+<li><strong>Map field access on absent keys</strong>: production’s behaviour on <code>request.resource.data.maybeAbsent.subfield</code> has edge cases around the absent-vs-null distinction that we approximate. Tests that depend on this should run against the live API.</li>
+<li><strong><code>getAfter()</code> projection corners</strong>: we project the post-write document using <code>projectAfterState</code>, which mirrors the admin SDK’s merge semantics. Production’s projection is implementation-defined.</li>
+</ul>
+<p>When the simulator and the API disagree, we treat the API as authoritative and fix the simulator. The integration test suite (<code>parity-stress-integration.test.ts</code>) deliberately runs both against the same cases to catch drift.</p>
+<h2 id="when-to-prefer-each">When to prefer each</h2>
+<p><strong>Reach for the simulator first</strong> when:</p>
+<ul>
+<li>You’re iterating on a rule and want fast feedback.</li>
+<li>You don’t have credentials (browser sandbox, local dev, untrusted CI).</li>
+<li>You’re testing hundreds of cases and the API would be cost-prohibitive.</li>
+</ul>
+<p><strong>Reach for the test API</strong> when:</p>
+<ul>
+<li>The simulator returned <code>UNSUPPORTED</code> for cases you need verdicts on.</li>
+<li>You’re at the end of a deploy pipeline and want absolute parity.</li>
+<li>You’re investigating a production discrepancy.</li>
+</ul>
+<p>The fastest agent loops use simulator-first with <code>UNSUPPORTED</code> escalation:</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"> local</span><span style="color:#56B6C2"> =</span><span style="color:#61AFEF"> firestoreRules</span><span style="color:#ABB2BF">(</span><span style="color:#E06C75">source</span><span style="color:#ABB2BF">).</span><span style="color:#61AFEF">simulate</span><span style="color:#ABB2BF">(</span><span style="color:#E06C75">testCases</span><span style="color:#ABB2BF">);</span></span>
+<span class="line"><span style="color:#C678DD">const</span><span style="color:#E5C07B"> escalate</span><span style="color:#56B6C2"> =</span><span style="color:#E5C07B"> local</span><span style="color:#ABB2BF">.</span><span style="color:#E5C07B">cases</span><span style="color:#ABB2BF">.</span><span style="color:#61AFEF">filter</span><span style="color:#ABB2BF">((</span><span style="color:#E06C75;font-style:italic">c</span><span style="color:#ABB2BF">) </span><span style="color:#C678DD">=></span><span style="color:#E5C07B"> c</span><span style="color:#ABB2BF">.</span><span style="color:#E06C75">unsupported</span><span style="color:#ABB2BF">).</span><span style="color:#61AFEF">map</span><span style="color:#ABB2BF">((</span><span style="color:#E06C75;font-style:italic">c</span><span style="color:#ABB2BF">) </span><span style="color:#C678DD">=></span><span style="color:#E5C07B"> c</span><span style="color:#ABB2BF">.</span><span style="color:#E06C75">case</span><span style="color:#ABB2BF">);</span></span>
+<span class="line"><span style="color:#C678DD">if</span><span style="color:#ABB2BF"> (</span><span style="color:#E5C07B">escalate</span><span style="color:#ABB2BF">.</span><span style="color:#E06C75">length</span><span style="color:#56B6C2"> ></span><span style="color:#D19A66"> 0</span><span style="color:#ABB2BF">) {</span></span>
+<span class="line"><span style="color:#C678DD">  const</span><span style="color:#E5C07B"> remote</span><span style="color:#56B6C2"> =</span><span style="color:#C678DD"> await</span><span style="color:#E5C07B"> api</span><span style="color:#ABB2BF">.</span><span style="color:#61AFEF">execute</span><span style="color:#ABB2BF">(</span><span style="color:#E06C75">scope</span><span style="color:#ABB2BF">, </span><span style="color:#E06C75">source</span><span style="color:#ABB2BF">, </span><span style="color:#E06C75">escalate</span><span style="color:#ABB2BF">);</span></span>
+<span class="line"><span style="color:#7F848E;font-style:italic">  // merge remote.data.results back into local.cases by matching case</span></span>
+<span class="line"><span style="color:#ABB2BF">}</span></span></code></pre>
+<p>Local-first keeps the inner loop in sub-millisecond territory; the API is only paid when the simulator genuinely can’t decide.</p>  </article> </main> <aside class="doc-toc" aria-label="On this page"> <h2 class="doc-toc-heading">On this page</h2> <ul> <li data-depth="2"> <a href="#the-shared-surface">The shared surface</a> </li><li data-depth="2"> <a href="#what-they-disagree-on">What they disagree on</a> </li><li data-depth="2"> <a href="#when-the-simulator-returns-unsupported">When the simulator returns UNSUPPORTED</a> </li><li data-depth="2"> <a href="#when-the-simulator-is-wrong">When the simulator is wrong</a> </li><li data-depth="2"> <a href="#when-to-prefer-each">When to prefer each</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-rules-explanation-simulator-vs-rules-test-api.md

@@ -0,0 +1,80 @@
+# Simulator vs Rules Test API
+
+Two surfaces evaluate rules against test cases. Underneath, they share a case shape and a result vocabulary; they disagree on tradeoffs. Choosing between them is a deliberate decision, not an implementation detail.
+
+## The shared surface
+
+The public front door only fronts one of the two: `firestoreRules(source).simulate(cases)` runs the local simulator, takes `FirestoreCase[]`, and returns a `SimulationSummary` (`{ passed, failed, unsupported, cases: CaseResult[] }`) that never carries a thrown-error branch, since a parse failure already threw `RulesCompileError` at construction.
+
+The Rules Test API has no public front door yet. Both engines still share their case and result vocabulary one level down, on `pyric/rules/internal`: `TestFirestoreRulesHandler.execute` (the Rules Test API client) and the internal `SimulateFirestoreRulesHandler.simulate` both take a rules source and a list of `TestCase` objects (the same shape as the public `FirestoreCase`), and both return a `TestFirestoreRulesResult`:
+
+```ts
+type TestFirestoreRulesResult =
+  | { success: true; data: { passed; failed; unsupported; results } }
+  | { success: false; error: { code; message; recoverable } };
+```
+
+Each `TestResult` in `results` carries `description`, `expectation`, `state`, and `debugMessages`. The `state` is `'PASSED' | 'FAILED' | 'UNSUPPORTED'`.
+
+The shared internal shape is a feature. You can swap one internal handler for the other, or route the same test suite to both, without rewriting any test-case code. See [How to test rules against the Firebase Rules Test API](../pyric-rules-how-to-test-rules-against-firebase/) for the escalation pattern built on the public `simulate` plus the internal test-API client.
+
+## What they disagree on
+
+| Axis | Local simulator | Rules Test API |
+|---|---|---|
+| Where it runs | In-process | Google's servers |
+| Latency per call | Sub-millisecond | Tens to hundreds of milliseconds |
+| Credentials required | None | `ProjectScope` with `firebaserules.releases.test` |
+| Parity with production | Close, not bit-for-bit | Bit-for-bit |
+| Returns `UNSUPPORTED`? | Yes, when it hits an unimplemented feature | Never |
+| Side effects | None | None (the API evaluates, it doesn't deploy) |
+| Cost | Free | Costs of the Cloud API call |
+
+## When the simulator returns `UNSUPPORTED`
+
+The local simulator implements most of the rules language: literals, identifiers, member access, method calls, all the binary and unary operators, function definitions with let bindings, all the standard built-ins (`get`, `exists`, `getAfter`, `existsAfter`, `debug`, `request.auth`, `request.resource`, `resource`, path literals, the type-test `is` operator). It does **not** implement every namespace method on every wrapper type. `duration.value(...).abs()` works, some less-common `bytes` arithmetic does not.
+
+When the evaluator hits a method or operation it doesn't model, it throws `UnsupportedError` rather than guessing. The handler catches that and surfaces it as an abstention: `state: 'UNSUPPORTED'` internally, `unsupported: true` on the public `CaseResult`. The semantics is "the gap is on my side, not yours". An unsupported case is **not** counted as a failure: `failed` and `unsupported` are separate counters on both the internal result and the public `SimulationSummary`.
+
+The right response to `UNSUPPORTED` depends on context:
+
+- **Agent loops** can treat `UNSUPPORTED` as "don't know, ask the API". A common pattern is to run locally first, then escalate only the unsupported subset to the live API.
+- **CI** can treat `UNSUPPORTED` as a build-time signal: "this rule uses a feature the simulator doesn't model, so switch this case to the live API or restructure the rule".
+- **Local development** can ignore `UNSUPPORTED` until the rule is otherwise correct, then verify against the API once.
+
+## When the simulator is wrong
+
+It does happen. The simulator is a re-implementation of the rules engine, not a transcription. Areas where production has surprised us:
+
+- **Timestamp precision**: `request.time` in production has nanosecond precision; our `Timestamp` wrapper carries it, but agents that round to milliseconds in their test data can produce `request.time != data.createdAt` when production would say they're equal.
+- **Map field access on absent keys**: production's behaviour on `request.resource.data.maybeAbsent.subfield` has edge cases around the absent-vs-null distinction that we approximate. Tests that depend on this should run against the live API.
+- **`getAfter()` projection corners**: we project the post-write document using `projectAfterState`, which mirrors the admin SDK's merge semantics. Production's projection is implementation-defined.
+
+When the simulator and the API disagree, we treat the API as authoritative and fix the simulator. The integration test suite (`parity-stress-integration.test.ts`) deliberately runs both against the same cases to catch drift.
+
+## When to prefer each
+
+**Reach for the simulator first** when:
+
+- You're iterating on a rule and want fast feedback.
+- You don't have credentials (browser sandbox, local dev, untrusted CI).
+- You're testing hundreds of cases and the API would be cost-prohibitive.
+
+**Reach for the test API** when:
+
+- The simulator returned `UNSUPPORTED` for cases you need verdicts on.
+- You're at the end of a deploy pipeline and want absolute parity.
+- You're investigating a production discrepancy.
+
+The fastest agent loops use simulator-first with `UNSUPPORTED` escalation:
+
+```ts
+const local = firestoreRules(source).simulate(testCases);
+const escalate = local.cases.filter((c) => c.unsupported).map((c) => c.case);
+if (escalate.length > 0) {
+  const remote = await api.execute(scope, source, escalate);
+  // merge remote.data.results back into local.cases by matching case
+}
+```
+
+Local-first keeps the inner loop in sub-millisecond territory; the API is only paid when the simulator genuinely can't decide.