@pyric/cli 0.1.0-alpha.9

package/dist/serve/docs-ui/docs/pyric-rules-reference-conformance-gaps.md

@@ -0,0 +1,360 @@
+# Firestore rules gaps: where pyric and Firebase disagree
+
+A gap is a rule that gets one answer from pyric and a different answer from
+Firebase. You write the rule once. pyric allows the request and Firebase
+denies it, or the other way round. The rule you tested is not the rule you
+shipped.
+
+Every gap on this page was captured from the production Rules Test API, not
+inferred. There are seven. Skim the headings. If none of them names something
+your rules use, none of them affects you.
+
+Tracked in [#135](https://github.com/davideast/pyric/issues/135).
+
+## How to read severity
+
+Every gap has two facts. A single label hides one of them, so this page
+reports both.
+
+**Fidelity** is the direction of the disagreement. Either pyric allows where
+Firebase denies, or pyric denies where Firebase allows. Either way the verdict
+you get locally is not the verdict you get in production, and the whole point
+of a local mirror is that the two match.
+
+**Production impact** is whether the gap lets a request through in production
+that should not get through. It follows from the direction.
+
+- **pyric allows, Firebase denies.** Production is stricter than pyric. Nothing
+  pyric wrongly allowed reaches production, so there is no production hole. The
+  cost is trust: a local ALLOW you relied on is wrong, and a legitimate
+  operation you validated locally can be refused in production.
+- **pyric denies, Firebase allows.** Production is more permissive than pyric.
+  A request your local mirror refused can succeed in production. This is the
+  direction that ships a hole: a rule you tested as blocking may not block.
+
+Read both. A broken verdict with no production hole is still a broken verdict,
+and a narrow trigger in the permissive direction is still the direction that
+leaks. Six of the seven gaps below are pyric-allows-Firebase-denies; the
+seventh runs the other way, and it is the one to watch.
+
+## Hashing built-ins allow in pyric and deny in Firebase
+
+**Fidelity:** pyric allows, Firebase denies.
+**Production impact:** no production hole, because Firebase denies here too. The
+cost is trust: a legitimate write you validated locally is refused in the cloud.
+
+### What you would write
+
+A rule that gates on a digest. An upload token, a content checksum, a
+signature check:
+
+```
+match /docs/{id} {
+  allow create: if request.auth != null
+    && hashing.sha256(request.resource.data.body).toHexString()
+       == request.resource.data.checksum;
+}
+```
+
+Or any use of `hashing.md5()`, `hashing.crc32()`, `hashing.crc32c()`, or
+`Bytes.toBase64()`.
+
+### What happens
+
+In pyric the digest comes out equal to the reference value and the write is
+ALLOWED. In Firebase the same comparison is DENIED.
+
+pyric's byte encoding and hash output do not agree with production's. That is
+a verdict-level fact, not a theory about which byte differs. On all five
+captured cases, including the textbook md5 of the empty string and the NIST
+sha256 of `abc`, pyric says allow and production says deny.
+
+Any rule whose decision depends on a hash value or a base64 encoding passes
+locally and fails in the cloud.
+
+### What you should do
+
+Do not gate access on a hash comparison. Compute the digest in your
+application, store it as a field, and let the rule compare fields. That runs
+identically in both engines.
+
+`toHexString()` and `toUtf8().size()` agree with production. The digest
+functions and `toBase64()` do not.
+
+## `getAfter()` and `existsAfter()` allow in pyric and deny in Firebase
+
+**Fidelity:** pyric allows, Firebase denies.
+**Production impact:** no production hole, because Firebase denies here too. The
+cost is trust: a legitimate write you validated locally is refused in the cloud.
+
+### What you would write
+
+A post-write check, usually to keep two documents consistent:
+
+```
+match /orders/{id} {
+  allow create: if request.auth != null
+    && existsAfter(request.path) == true
+    && getAfter(request.path).data.total == request.resource.data.total;
+}
+```
+
+### What happens
+
+In pyric the write is ALLOWED. pyric models the post-write state and hands
+back the document you are about to write.
+
+In Firebase the write is DENIED. A `getAfter()` result carries no document
+identity in the response, so a comparison against it errors, and an errored
+expression denies. `existsAfter()` diverges the same way on a create, on a
+delete, and over an unrelated path. All four captured cases: pyric allow,
+production deny.
+
+The production verdict here comes from a mocked post-write lookup in the Rules
+Test API. That API is the only oracle there is for a rule that reads state the
+request has not committed yet, and it denies where pyric allows.
+
+### What you should do
+
+Do not write rules that depend on `getAfter()` or `existsAfter()`. You cannot
+test them here and get an answer that means anything. Where the rule is really
+about the write in front of you, use `request.resource.data`, which agrees on
+both sides.
+
+## `.id` and `__name__` on a `get()` result allow in pyric and deny in Firebase
+
+**Fidelity:** pyric allows, Firebase denies.
+**Production impact:** no production hole, because Firebase denies here too. The
+cost is trust: a legitimate write you validated locally is refused in the cloud.
+
+### What you would write
+
+A rule that reads the identity of a document it looked up:
+
+```
+match /pages/{id} {
+  allow create: if get(/databases/$(database)/documents/cfg/site).id == 'site';
+}
+```
+
+### What happens
+
+In pyric the write is ALLOWED. pyric attaches a document identity to the
+`get()` result, so `.id` and `__name__` read back the path you asked for.
+
+In Firebase the write is DENIED. The looked-up document carries no identity in
+the response, so `.id` errors with "Property id is undefined on object" and
+the rule denies. `__name__` behaves the same. The production verdict comes
+from a mocked lookup in the Rules Test API, which is the oracle for every
+cross-document read in these captures.
+
+### What you should do
+
+Read data off a `get()`, not identity. `get(...).data.<field>` matches
+production exactly, and so does `exists(...)`.
+
+```
+allow create: if get(/databases/$(database)/documents/cfg/site).data.open == true;
+```
+
+If you need the identity, you already have it. It is the path you passed to
+`get()`.
+
+## `request.query` allows in pyric and denies in Firebase
+
+**Fidelity:** pyric allows, Firebase denies.
+**Production impact:** no production hole, because Firebase denies here too. The
+cost is trust: a legitimate write you validated locally is refused in the cloud.
+
+### What you would write
+
+A rule that inspects the query on a request that is not a list:
+
+```
+match /notes/{id} {
+  allow create: if request.auth != null
+    && request.query is map
+    && request.query.size() == 0;
+}
+```
+
+### What happens
+
+In pyric the write is ALLOWED. pyric models `request.query` as an empty map on
+a `get`, `create`, `update`, or `delete`. In Firebase the same comparison is
+DENIED.
+
+### What you should do
+
+Only touch `request.query` inside a `list` rule, which is the only request
+that has one. On a document request, drop the check.
+
+## Out-of-range slices allow in pyric and deny in Firebase
+
+**Fidelity:** pyric allows, Firebase denies.
+**Production impact:** no production hole, because Firebase denies here too. The
+cost is trust: a legitimate write you validated locally is refused in the cloud.
+
+### What you would write
+
+A slice whose end index runs past the end of the value:
+
+```
+match /notes/{id} {
+  allow create: if request.resource.data.tags[1:99].size() == 3
+    && request.resource.data.title[6:99] == 'world';
+}
+```
+
+### What happens
+
+In pyric both slices clamp to the length of the list or the string, the
+comparison succeeds, and the write is ALLOWED. In Firebase an out-of-range
+slice end is DENIED, on lists and on strings alike.
+
+### What you should do
+
+Never slice past the end. Check the size first, or slice with an index you
+know is in range:
+
+```
+allow create: if request.resource.data.tags.size() >= 4
+  && request.resource.data.tags[1:4].size() == 3;
+```
+
+In-range slices, empty slices (`[i:i]`), and full-length slices all agree with
+production.
+
+## `path()` on a value that is already a path allows in pyric and denies in Firebase
+
+**Fidelity:** pyric allows, Firebase denies.
+**Production impact:** no production hole, because Firebase denies here too. The
+cost is trust: a legitimate write you validated locally is refused in the cloud.
+
+### What you would write
+
+A `path()` call wrapped around something that is already a `Path`, usually
+because it came out of a helper:
+
+```
+function asPath(p) {
+  return path(p);
+}
+match /users/{uid} {
+  allow read: if asPath(path('users/alice')) == path('users/alice');
+}
+```
+
+### What happens
+
+In pyric `path()` is idempotent. Passing it a `Path` gives the same `Path`
+back and the read is ALLOWED. In Firebase the same expression is DENIED.
+
+### What you should do
+
+Call `path()` exactly once, on a string. Everything else about paths matches
+production: `path()` on a string literal, equality and inequality, `bind()`,
+numeric indexing, and type checks.
+
+## A float in your test data reads as an int in pyric
+
+**Fidelity:** pyric denies, Firebase allows.
+**Production impact:** the leaking direction. A request your local mirror
+refused is allowed in production, so a rule you tested as blocking may not
+block. The trigger is narrow: it fires only where a rule tells integral-valued
+floats apart from ints with `is float` / `is int`. But this is the one gap on
+the page where production is the more permissive side, so it is the one to
+watch.
+
+### What you would write
+
+A type check on a number in the payload:
+
+```
+match /readings/{id} {
+  allow create: if request.resource.data.x is float
+    && !(request.resource.data.x is int);
+}
+```
+
+### What happens
+
+In pyric the write is DENIED. In Firebase it is ALLOWED.
+
+Firestore stores a type tag next to the number, so a value written as a float
+stays a float. pyric reads test data from JSON, where `2.0` and `2` are the
+same number, and narrows it toward int.
+
+This is the leaking direction. pyric refuses a write production accepts, so a
+rule that leans on `is float` to keep something out reads as a denial on your
+machine and lets it through in the cloud. You often catch it anyway, because a
+legitimate write fails locally and you go looking. The danger is the case you do
+not run locally: a rule you trusted to block, tested once, and shipped.
+
+### What you should do
+
+Do not use `is float` or `is int` to tell payload numbers apart while testing
+locally. Test the property you actually care about, which is usually a range:
+
+```
+allow create: if request.resource.data.x is number
+  && request.resource.data.x >= 0
+  && request.resource.data.x <= 100;
+```
+
+Integer division, truncation, modulo, division by zero, and `is int` on a
+genuinely integral value all match production.
+
+## Everything else in the simulator matches Firebase
+
+Sixteen of the twenty-three captured observations replay clean, case for case:
+time and math built-ins, durations and geopoints, cross-type operator
+overloads, error absorption in `&&` and `||`, user-defined functions and
+recursive rules, list and string methods, `List.concat()` / `removeAll()` /
+`toSet()`, `Map.get()` with defaults and nested paths, `matches()` as an
+anchored full-string regex, own-keys-only map membership with no prototype
+leakage, required-field checks and `mapDiff`, set algebra, string literals and
+regexes, timestamp math and casts, undefined-field access, and the
+unsupported-feature witness.
+
+## How this is checked, and how to check it yourself
+
+Each gap above is replayed on every test run. The suite loads each captured
+production observation, runs the same ruleset and the same request through the
+local simulator, and compares verdicts case for case.
+
+- Suite: `packages/pyric/test/rules/oracle-conformance.test.ts`. Run it with
+  `bun test packages/pyric/test/rules/oracle-conformance.test.ts`.
+- Captures: `packages/conformance/observations/firestore-rules/*.json`,
+  twenty-three of them.
+- Rulesets and cases: `packages/conformance/rules-corpus/firestore/`.
+
+The observation and case keys behind each section above:
+
+| Gap | Observation :: cases |
+|---|---|
+| Hashing built-ins | `rules-firestore-bytes-toutf8-and-hashing` :: `toBase64 round-trip`, `md5 empty string`, `sha256 abc`, `crc32 IEEE 802.3 ref`, `crc32c Castagnoli ref` |
+| `getAfter()` / `existsAfter()` | `rules-firestore-get-after-and-exists-after` :: `getAfter target == request.resource.data`, `existsAfter create true`, `existsAfter delete false`, `existsAfter unrelated mocked path` |
+| `get()` result identity | `rules-firestore-get-missing-doc` :: `get(mocked).id == 'site'`, `get(mocked).__name__ == path literal` |
+| `request.query` | `rules-firestore-globals-request-path-and-resource-id` :: `request.query empty map` |
+| Out-of-range slices | `rules-firestore-range-slice-list-and-string` :: `list slice end OOB clamps to length`, `string slice end OOB clamps to length` |
+| `path()` idempotence | `rules-firestore-path-constructor-and-bind` :: `path() idempotent on Path arg` |
+| Float payload reads as int | `rules-firestore-int-float-and-division` :: `float payload is float / not int` |
+
+Every gap is pinned in the suite's `KNOWN_DIVERGENCES` table, which asserts
+both sides: production's captured verdict and the simulator's live verdict.
+The suite is green while a gap is exactly as described. It fails the moment
+either side moves, including when someone fixes the simulator, which forces
+the fix to delete the pin instead of landing silently beside a stale one. No
+divergent case is skipped.
+
+A third outcome is not a gap. The simulator can answer UNSUPPORTED, an
+explicit refusal to evaluate a construct it does not model. A refusal is loud
+and you cannot mistake it for a verdict, so those cases are recorded and not
+asserted against production.
+
+## Where to look next
+
+- [Storage rules gaps](../pyric-storage-reference-conformance-gaps/) for the
+  same page on the storage side.
+- [Compatibility matrix](../pyric-rules-compat/) for the row-by-row registry.

package/dist/serve/docs-ui/docs/pyric-rules-reference-errors/index.html

@@ -0,0 +1,76 @@
+<!DOCTYPE html><html lang="en"> <head><meta charset="UTF-8"><meta name="viewport" content="width=device-width, initial-scale=1.0"><title>Errors · 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>Reference</span> </li><li> <span class="docs-breadcrumbs-sep" aria-hidden="true">/</span> <span aria-current="page">Errors</span> </li> </ol> </nav>  <article class="prose">  <h1 id="errors">Errors</h1>
+<p><code>pyric/rules</code> throws exactly three error classes on its public surface. Everything below the public surface (the parser, evaluator, and handlers on <code>pyric/rules/internal</code>) has its own error vocabulary; those types still apply, but only to the internal engine now.</p>
+<h2 id="public-errors">Public errors</h2>
+<h3 id="rulescompileerror"><code>RulesCompileError</code></h3>
+<p>Thrown by <code>firestoreRules(source)</code> / <code>rtdbRules(...)</code> when the source doesn’t compile.</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">class</span><span style="color:#E5C07B"> RulesCompileError</span><span style="color:#C678DD"> extends</span><span style="color:#E5C07B"> Error</span><span style="color:#ABB2BF"> {</span></span>
+<span class="line"><span style="color:#C678DD">  readonly</span><span style="color:#E06C75"> issues</span><span style="color:#ABB2BF">: </span><span style="color:#E5C07B">RuleIssue</span><span style="color:#ABB2BF">[];</span></span>
+<span class="line"><span style="color:#ABB2BF">}</span></span></code></pre>
+<p>Carries the compile-blocking issues on <code>.issues</code> so a caller can surface them without re-parsing.</p>
+<h3 id="rulesassertionerror"><code>RulesAssertionError</code></h3>
+<p>Thrown by <code>assertCase</code> when the simulated decision did not match the case’s expectation. The message is the rendered <code>explainCase</code> trace, so a test runner surfaces the “why” without extra wiring.</p>
+<h3 id="rulesunsupportederror"><code>RulesUnsupportedError</code></h3>
+<p>Thrown by <code>assertCase</code> when the simulator abstained: it hit a feature it doesn’t implement, so neither a pass nor a genuine failure can be asserted. Distinct from <code>RulesAssertionError</code> so a runner can choose to skip rather than fail on a known simulator gap.</p>
+<h2 id="internal-engine-errors-pyricrulesinternal">Internal engine errors (<code>pyric/rules/internal</code>)</h2>
+<p>These are not part of the public contract. They belong to the parser, evaluator, and handlers exposed on <code>pyric/rules/internal</code> and may change without notice. <code>firestoreRules</code>, <code>lint</code>, and the assertion adapters absorb all of them internally and never let them escape as-is; the sections above are what a public-surface caller actually sees.</p>
+<h3 id="parse-failures">Parse failures</h3>
+<h4 id="parseerror"><code>ParseError</code></h4>
+<p>Returned internally by <code>parseToASTOrError</code> and embedded in the internal <code>LintResult.parseError</code>. Not thrown. On the public surface this shows up as a <code>RuleIssue</code> with <code>origin: 'parse'</code> (from <code>lint()</code>) or inside <code>RulesCompileError.issues</code> (from <code>firestoreRules()</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">interface</span><span style="color:#E5C07B"> ParseError</span><span style="color:#ABB2BF"> {</span></span>
+<span class="line"><span style="color:#E06C75">  line</span><span style="color:#ABB2BF">: </span><span style="color:#E5C07B">number</span><span style="color:#ABB2BF">;        </span><span style="color:#7F848E;font-style:italic">// 1-based</span></span>
+<span class="line"><span style="color:#E06C75">  column</span><span style="color:#ABB2BF">: </span><span style="color:#E5C07B">number</span><span style="color:#ABB2BF">;      </span><span style="color:#7F848E;font-style:italic">// 1-based</span></span>
+<span class="line"><span style="color:#E06C75">  offset</span><span style="color:#ABB2BF">: </span><span style="color:#E5C07B">number</span><span style="color:#ABB2BF">;      </span><span style="color:#7F848E;font-style:italic">// byte offset into the trimmed source</span></span>
+<span class="line"><span style="color:#E06C75">  expected</span><span style="color:#ABB2BF">: </span><span style="color:#E5C07B">string</span><span style="color:#ABB2BF">;    </span><span style="color:#7F848E;font-style:italic">// what the grammar wanted next</span></span>
+<span class="line"><span style="color:#E06C75">  actual</span><span style="color:#ABB2BF">: </span><span style="color:#E5C07B">string</span><span style="color:#ABB2BF">;      </span><span style="color:#7F848E;font-style:italic">// up to 40 chars at the failure point</span></span>
+<span class="line"><span style="color:#E06C75">  message</span><span style="color:#ABB2BF">: </span><span style="color:#E5C07B">string</span><span style="color:#ABB2BF">;     </span><span style="color:#7F848E;font-style:italic">// ohm's human-readable message with a caret</span></span>
+<span class="line"><span style="color:#ABB2BF">}</span></span></code></pre>
+<p>Use <code>line</code> / <code>column</code> for editor diagnostics, <code>message</code> for terminal output, <code>expected</code> / <code>actual</code> for custom UIs.</p>
+<h4 id="parseresult"><code>ParseResult</code></h4>
+<p>Returned by <code>parseExpression</code> and <code>parseRulesFile</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">interface</span><span style="color:#E5C07B"> ParseResult</span><span style="color:#ABB2BF"> {</span></span>
+<span class="line"><span style="color:#E06C75">  valid</span><span style="color:#ABB2BF">: </span><span style="color:#E5C07B">boolean</span><span style="color:#ABB2BF">;</span></span>
+<span class="line"><span style="color:#E06C75">  errors</span><span style="color:#ABB2BF">: </span><span style="color:#E5C07B">Array</span><span style="color:#ABB2BF">&#x3C;{ </span><span style="color:#E06C75">message</span><span style="color:#ABB2BF">: </span><span style="color:#E5C07B">string</span><span style="color:#ABB2BF"> }>;</span></span>
+<span class="line"><span style="color:#E06C75">  parseError</span><span style="color:#C678DD">?</span><span style="color:#ABB2BF">: </span><span style="color:#E5C07B">ParseError</span><span style="color:#ABB2BF">;</span></span>
+<span class="line"><span style="color:#ABB2BF">}</span></span></code></pre>
+<p><code>errors</code> is the legacy surface; <code>parseError</code> is the structured form.</p>
+<h3 id="evaluator-errors">Evaluator errors</h3>
+<p>These extend <code>Error</code> and are thrown synchronously during expression evaluation. <code>SimulateFirestoreRulesHandler.simulate</code> catches them and converts them into result states; callers using <code>evaluate</code> directly need to handle them. None of this escapes to the public surface: <code>firestoreRules(source).simulate(cases)</code> never throws on a rule outcome.</p>
+<h4 id="evalerror"><code>EvalError</code></h4>
+<p>Real evaluation failure: type mismatch, missing field, division by zero. Carries an optional <code>expr: Expression</code> for the failing AST node.</p>
+<p>The handler catches <code>EvalError</code> and treats it as that rule denying, matching production’s “runtime errors deny” behaviour. A test case where every rule denied via <code>EvalError</code> lands in <code>DENY</code> (not <code>UNSUPPORTED</code>).</p>
+<h4 id="unsupportederror-extends-evalerror"><code>UnsupportedError</code> extends <code>EvalError</code></h4>
+<p>The simulator hit a feature it does not yet implement: an unknown built-in function, a namespace method missing from a wrapper, a type it doesn’t model. Caught by the handler and surfaced as <code>unsupported: true</code> on the public <code>CaseResult</code> / <code>RtdbCaseResult</code>.</p>
+<p><code>UnsupportedError</code> is the only path to an unsupported result. If every rule in a match block threw <code>EvalError</code> instead, the case decides <code>DENY</code>.</p>
+<h4 id="expressionwalkerror"><code>ExpressionWalkError</code></h4>
+<p>Thrown by <code>resolveExpressionsInData</code> when an <code>$expr</code> wrapper has the wrong shape (extra keys, non-string value, etc.). Carries <code>code: 'invalid-argument'</code> and a dotted <code>path</code> to the offending leaf.</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">class</span><span style="color:#E5C07B"> ExpressionWalkError</span><span style="color:#C678DD"> extends</span><span style="color:#E5C07B"> Error</span><span style="color:#ABB2BF"> {</span></span>
+<span class="line"><span style="color:#C678DD">  readonly</span><span style="color:#E06C75"> code</span><span style="color:#ABB2BF">: </span><span style="color:#98C379">'invalid-argument'</span><span style="color:#ABB2BF">;</span></span>
+<span class="line"><span style="color:#C678DD">  readonly</span><span style="color:#E06C75"> path</span><span style="color:#ABB2BF">: </span><span style="color:#E5C07B">string</span><span style="color:#ABB2BF">;   </span><span style="color:#7F848E;font-style:italic">// e.g. 'users.0.balance'</span></span>
+<span class="line"><span style="color:#ABB2BF">}</span></span></code></pre>
+<h4 id="expressionlexerror-and-expressionparseerror"><code>ExpressionLexError</code> and <code>ExpressionParseError</code></h4>
+<p>Thrown by <code>tokenize</code> / <code>parse</code> in the sentinel expression DSL. Carry a <code>Position</code> so the caller can report <code>line:column</code> against the original <code>$expr</code> source.</p>
+<h3 id="handler-results">Handler results</h3>
+<p>The handlers (<code>SimulateFirestoreRulesHandler</code>, <code>TestFirestoreRulesHandler</code>, the modules resolver) never throw for expected failure modes. They return <code>Outcome</code>-shaped objects:</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"> Result</span><span style="color:#ABB2BF">&#x3C;</span><span style="color:#E5C07B">T</span><span style="color:#ABB2BF">> </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:#E5C07B">T</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:#E5C07B">string</span><span style="color:#ABB2BF">; </span><span style="color:#E06C75">message</span><span style="color:#ABB2BF">: </span><span style="color:#E5C07B">string</span><span style="color:#ABB2BF">; </span><span style="color:#E06C75">recoverable</span><span style="color:#C678DD">?</span><span style="color:#ABB2BF">: </span><span style="color:#E5C07B">boolean</span><span style="color:#ABB2BF"> } };</span></span></code></pre>
+<h4 id="simulator-errorcode-values">Simulator <code>error.code</code> values</h4>
+<ul>
+<li><code>PARSE_FAILED</code>: the source did not parse.</li>
+</ul>
+<h4 id="rules-test-api-client-errorcode-values">Rules Test API client <code>error.code</code> values</h4>
+<ul>
+<li><code>PARSE_FAILED</code>: the source did not parse (the API surfaced issues instead of running tests).</li>
+<li><code>PERMISSION_DENIED</code>: service account lacks <code>firebaserules.releases.test</code>. <code>recoverable: false</code>.</li>
+<li><code>INVALID_REQUEST</code>: 400 from the API. <code>recoverable: true</code>.</li>
+<li><code>RULES_ERROR</code>: the API returned source-level issues. <code>recoverable: true</code>.</li>
+<li><code>FETCH_FAILED</code>: network or unexpected non-2xx. <code>recoverable</code> depends on the underlying cause.</li>
+</ul>
+<h4 id="modules-resolver-errorcode-values">Modules resolver <code>error.code</code> values</h4>
+<ul>
+<li><code>PARSE_FAILED</code>: source did not parse.</li>
+<li><code>NOT_MODULE_SOURCE</code>: version is not <code>'2+modules'</code>.</li>
+<li><code>UNKNOWN_MODULE</code>: module name not found in stdlib, <code>modules</code> map, or <code>basePath</code>.</li>
+<li><code>UNKNOWN_FUNCTION</code>: module exists but the imported function is not exported (or doesn’t exist at all; the message disambiguates).</li>
+<li><code>DUPLICATE_FUNCTION</code>: same function exported by two modules, or collision with a source-defined function.</li>
+</ul>  </article> </main> <aside class="doc-toc" aria-label="On this page"> <h2 class="doc-toc-heading">On this page</h2> <ul> <li data-depth="2"> <a href="#public-errors">Public errors</a> </li><li data-depth="3"> <a href="#rulescompileerror">RulesCompileError</a> </li><li data-depth="3"> <a href="#rulesassertionerror">RulesAssertionError</a> </li><li data-depth="3"> <a href="#rulesunsupportederror">RulesUnsupportedError</a> </li><li data-depth="2"> <a href="#internal-engine-errors-pyricrulesinternal">Internal engine errors (pyric/rules/internal)</a> </li><li data-depth="3"> <a href="#parse-failures">Parse failures</a> </li><li data-depth="3"> <a href="#evaluator-errors">Evaluator errors</a> </li><li data-depth="3"> <a href="#handler-results">Handler results</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-reference-errors.md

@@ -0,0 +1,123 @@
+# Errors
+
+`pyric/rules` throws exactly three error classes on its public surface. Everything below the public surface (the parser, evaluator, and handlers on `pyric/rules/internal`) has its own error vocabulary; those types still apply, but only to the internal engine now.
+
+## Public errors
+
+### `RulesCompileError`
+
+Thrown by `firestoreRules(source)` / `rtdbRules(...)` when the source doesn't compile.
+
+```ts
+class RulesCompileError extends Error {
+  readonly issues: RuleIssue[];
+}
+```
+
+Carries the compile-blocking issues on `.issues` so a caller can surface them without re-parsing.
+
+### `RulesAssertionError`
+
+Thrown by `assertCase` when the simulated decision did not match the case's expectation. The message is the rendered `explainCase` trace, so a test runner surfaces the "why" without extra wiring.
+
+### `RulesUnsupportedError`
+
+Thrown by `assertCase` when the simulator abstained: it hit a feature it doesn't implement, so neither a pass nor a genuine failure can be asserted. Distinct from `RulesAssertionError` so a runner can choose to skip rather than fail on a known simulator gap.
+
+## Internal engine errors (`pyric/rules/internal`)
+
+These are not part of the public contract. They belong to the parser, evaluator, and handlers exposed on `pyric/rules/internal` and may change without notice. `firestoreRules`, `lint`, and the assertion adapters absorb all of them internally and never let them escape as-is; the sections above are what a public-surface caller actually sees.
+
+### Parse failures
+
+#### `ParseError`
+
+Returned internally by `parseToASTOrError` and embedded in the internal `LintResult.parseError`. Not thrown. On the public surface this shows up as a `RuleIssue` with `origin: 'parse'` (from `lint()`) or inside `RulesCompileError.issues` (from `firestoreRules()`).
+
+```ts
+interface ParseError {
+  line: number;        // 1-based
+  column: number;      // 1-based
+  offset: number;      // byte offset into the trimmed source
+  expected: string;    // what the grammar wanted next
+  actual: string;      // up to 40 chars at the failure point
+  message: string;     // ohm's human-readable message with a caret
+}
+```
+
+Use `line` / `column` for editor diagnostics, `message` for terminal output, `expected` / `actual` for custom UIs.
+
+#### `ParseResult`
+
+Returned by `parseExpression` and `parseRulesFile`:
+
+```ts
+interface ParseResult {
+  valid: boolean;
+  errors: Array<{ message: string }>;
+  parseError?: ParseError;
+}
+```
+
+`errors` is the legacy surface; `parseError` is the structured form.
+
+### Evaluator errors
+
+These extend `Error` and are thrown synchronously during expression evaluation. `SimulateFirestoreRulesHandler.simulate` catches them and converts them into result states; callers using `evaluate` directly need to handle them. None of this escapes to the public surface: `firestoreRules(source).simulate(cases)` never throws on a rule outcome.
+
+#### `EvalError`
+
+Real evaluation failure: type mismatch, missing field, division by zero. Carries an optional `expr: Expression` for the failing AST node.
+
+The handler catches `EvalError` and treats it as that rule denying, matching production's "runtime errors deny" behaviour. A test case where every rule denied via `EvalError` lands in `DENY` (not `UNSUPPORTED`).
+
+#### `UnsupportedError` extends `EvalError`
+
+The simulator hit a feature it does not yet implement: an unknown built-in function, a namespace method missing from a wrapper, a type it doesn't model. Caught by the handler and surfaced as `unsupported: true` on the public `CaseResult` / `RtdbCaseResult`.
+
+`UnsupportedError` is the only path to an unsupported result. If every rule in a match block threw `EvalError` instead, the case decides `DENY`.
+
+#### `ExpressionWalkError`
+
+Thrown by `resolveExpressionsInData` when an `$expr` wrapper has the wrong shape (extra keys, non-string value, etc.). Carries `code: 'invalid-argument'` and a dotted `path` to the offending leaf.
+
+```ts
+class ExpressionWalkError extends Error {
+  readonly code: 'invalid-argument';
+  readonly path: string;   // e.g. 'users.0.balance'
+}
+```
+
+#### `ExpressionLexError` and `ExpressionParseError`
+
+Thrown by `tokenize` / `parse` in the sentinel expression DSL. Carry a `Position` so the caller can report `line:column` against the original `$expr` source.
+
+### Handler results
+
+The handlers (`SimulateFirestoreRulesHandler`, `TestFirestoreRulesHandler`, the modules resolver) never throw for expected failure modes. They return `Outcome`-shaped objects:
+
+```ts
+type Result<T> =
+  | { success: true; data: T }
+  | { success: false; error: { code: string; message: string; recoverable?: boolean } };
+```
+
+#### Simulator `error.code` values
+
+- `PARSE_FAILED`: the source did not parse.
+
+#### Rules Test API client `error.code` values
+
+- `PARSE_FAILED`: the source did not parse (the API surfaced issues instead of running tests).
+- `PERMISSION_DENIED`: service account lacks `firebaserules.releases.test`. `recoverable: false`.
+- `INVALID_REQUEST`: 400 from the API. `recoverable: true`.
+- `RULES_ERROR`: the API returned source-level issues. `recoverable: true`.
+- `FETCH_FAILED`: network or unexpected non-2xx. `recoverable` depends on the underlying cause.
+
+#### Modules resolver `error.code` values
+
+- `PARSE_FAILED`: source did not parse.
+- `NOT_MODULE_SOURCE`: version is not `'2+modules'`.
+- `UNKNOWN_MODULE`: module name not found in stdlib, `modules` map, or `basePath`.
+- `UNKNOWN_FUNCTION`: module exists but the imported function is not exported (or doesn't exist at all; the message disambiguates).
+- `DUPLICATE_FUNCTION`: same function exported by two modules, or collision with a source-defined function.