@pyric/cli 0.1.0-alpha.9

package/dist/serve/docs-ui/docs/pyric-rules-reference-simulator-context.md

@@ -0,0 +1,104 @@
+# Simulator context and result states
+
+The simulator evaluates expressions against a `SimulationContext`. This page describes its shape and the three result states a test case can land in. `SimulationContext` and `evaluate` are engine-internal, reached through `pyric/rules/internal`; the public front door is `firestoreRules(source).simulate(cases)` / `.explain(oneCase)`, which builds and consumes this context internally and returns a `CaseResult` / `Explanation` instead. This page documents the internals for callers who need them directly, and to explain what the public result fields mean underneath.
+
+## `SimulationContext`
+
+```ts
+interface SimulationContext {
+  request: SimRequest;
+  resource: SimResource;
+  mockDocuments: Map<string, Record<string, unknown>>;
+  pathVariables: Record<string, string>;
+  functions: Map<string, FunctionDef>;
+  database: string;
+  afterStatePath: Path;
+  afterState: Record<string, unknown> | null;
+  existsAfter: boolean;
+}
+```
+
+You don't construct this directly. `SimulateFirestoreRulesHandler.simulate` builds it from each case. The shape is documented because `evaluate(expression, ctx)` is exported from `pyric/rules/internal`, so callers writing custom evaluators do need to build it.
+
+### `request: SimRequest`
+
+```ts
+interface SimRequest {
+  auth: { uid: string; token: Record<string, unknown> } | null;
+  resource: { data: Record<string, unknown> };   // proposed write payload
+  method: string;
+  path: Path;          // full Path including /databases/(default)/documents
+  query: Record<string, unknown>;
+  time: Timestamp;
+}
+```
+
+The rule sees this as `request`. `request.auth` is `null` for unauthenticated cases.
+
+### `resource: SimResource`
+
+```ts
+interface SimResource {
+  data: Record<string, unknown>;   // existing document data
+  id: string;                      // last segment of the path
+  __name__: Path;                  // full Path
+}
+```
+
+The rule sees this as `resource`. On `create`, `resource.data` is `{}` and `existsAfter` is `true` for the post-write doc.
+
+### `mockDocuments`
+
+Keyed by the *full* document path (including the database prefix). `get()` and `exists()` look here first. Built from `TestCase.functionMocks`.
+
+### `pathVariables`
+
+The match-block wildcard bindings (e.g. `{ uid: 'alice' }` when matching `/users/{uid}` against `/users/alice`). Plus an injected `database: '(default)'`.
+
+### `functions`
+
+Function definitions visible at the matched scope: parent-match functions, this-match functions, and any inlined modules.
+
+### `afterStatePath`, `afterState`, `existsAfter`
+
+The projected post-write document for `getAfter()` / `existsAfter()`. When the rule calls those built-ins with `request.path`, they return `afterState` / `existsAfter`. With any other path they fall through to `get()` / `exists()` against the same data. Unrelated docs aren't mutated by the write under evaluation.
+
+## Result states
+
+Every case lands in one of three states. Internally these are the engine's `PASSED` / `FAILED` / `UNSUPPORTED` `TestResult.state` values; on the public `CaseResult` (from `firestoreRules(source).simulate(cases)`) they show up as the `passed` and `unsupported` booleans plus a `decision: 'ALLOW' | 'DENY' | 'UNSUPPORTED'` field, and `SimulationSummary` tallies them into `passed` / `failed` / `unsupported` counts.
+
+### `PASSED`
+
+The simulator's decision matched the case's `expectation`. The expected outcome was reached. On the public result: `passed: true`.
+
+### `FAILED`
+
+The simulator's decision was the opposite of `expectation`. The rule allowed when you expected deny, or denied when you expected allow. The `trace` field on the public `CaseResult` carries the rule-by-rule account of which rule decided.
+
+### `UNSUPPORTED`
+
+The simulator encountered a feature it does not yet implement and chose to abstain rather than guess. **`UNSUPPORTED` is not `FAILED`**. The simulator is saying "the gap is on my side". On the public result: `unsupported: true`, `passed: false`, tallied separately from `failed` in `SimulationSummary`.
+
+When you see `UNSUPPORTED`, you have three options:
+
+1. Trust the rule and skip the case in local CI.
+2. Reformulate the rule to avoid the unsupported feature.
+3. Route only the unsupported cases to the Firebase Rules Test API. See [How to test rules against the Firebase Rules Test API](../pyric-rules-how-to-test-rules-against-firebase/).
+
+The live Rules Test API never returns `UNSUPPORTED`. It uses the production engine and decides every case.
+
+## Decision precedence within a match block
+
+Multiple `allow` rules in the same match block use **OR semantics**:
+
+- Any rule decides `ALLOW` → final decision is `ALLOW` (evaluation short-circuits).
+- Otherwise, if any rule threw `UnsupportedError` → final decision is `UNSUPPORTED`.
+- Otherwise → `DENY`.
+
+Real evaluation errors (`EvalError`, type mismatches) are caught and treated as that rule denying, matching production's behaviour where runtime errors deny the request.
+
+## Path resolution
+
+The simulator walks the AST from the root match (`/databases/{database}/documents`), trying each child's path pattern against the test case's path segments. The first child that consumes all segments wins. Recursive wildcards (`{x=**}`) consume every remaining segment in one bite.
+
+When no match block accepts the path, the case is treated as a deny (`PASSED` if `expectation === 'DENY'`, otherwise `FAILED`). The debug messages note `No match block found`.

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

@@ -0,0 +1,241 @@
+<!DOCTYPE html><html lang="en"> <head><meta charset="UTF-8"><meta name="viewport" content="width=device-width, initial-scale=1.0"><title>Standard library modules · 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">Standard library modules</span> </li> </ol> </nav>  <article class="prose">  <h1 id="standard-library-modules">Standard library modules</h1>
+<p>Fifteen modules ship with <code>pyric/rules</code>. Each module is a <code>.rules</code> file living under <code>src/rules/modules/stdlib/</code>; imports resolve automatically without any configuration.</p>
+<p>Use them by setting <code>rules_version = '2+modules'</code> and adding import statements:</p>
+<pre class="astro-code one-dark-pro" style="background-color:#282c34;color:#abb2bf; overflow-x: auto;" tabindex="0" data-language="rules"><code><span class="line"><span style="color:#C678DD">import</span><span style="color:#ABB2BF"> { isAuthenticated, isOwner } </span><span style="color:#C678DD">from</span><span style="color:#98C379"> 'auth'</span><span style="color:#ABB2BF">;</span></span>
+<span class="line"><span style="color:#C678DD">import</span><span style="color:#ABB2BF"> { hasOnly } </span><span style="color:#C678DD">from</span><span style="color:#98C379"> 'validation'</span><span style="color:#ABB2BF">;</span></span></code></pre>
+<p>Then run <code>resolveModules(source)</code> to inline the exports into a standard <code>'2'</code> source. <code>resolveModules</code> is an internal engine seam, imported from <code>pyric/rules/internal/node</code>, not the public <code>pyric/rules</code> front door. See <a href="../pyric-rules-how-to-resolve-module-imports/">How to resolve <code>2+modules</code> imports</a>.</p>
+<p>Convention: modules either operate against <code>request</code> / <code>resource</code> / <code>request.auth</code> only (self-contained) or take explicit parameters (no implicit lookups).</p>
+<h2 id="auth"><code>auth</code></h2>
+<p>Access-control primitives.</p>
+<div class="table-scroll">
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+<table><thead><tr><th>Function</th><th>Returns</th></tr></thead><tbody><tr><td><code>isAuthenticated()</code></td><td><code>request.auth != null</code></td></tr><tr><td><code>isOwner(userId)</code></td><td><code>isAuthenticated() &#x26;&#x26; request.auth.uid == userId</code></td></tr></tbody></table></div>
+<h2 id="validation"><code>validation</code></h2>
+<p>Document field validation.</p>
+<div class="table-scroll">
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+<table><thead><tr><th>Function</th><th>Returns</th></tr></thead><tbody><tr><td><code>hasRequired(fields)</code></td><td><code>request.resource.data.keys().hasAll(fields)</code></td></tr><tr><td><code>hasOnly(fields)</code></td><td><code>request.resource.data.keys().hasOnly(fields)</code></td></tr></tbody></table></div>
+<h2 id="lobby"><code>lobby</code></h2>
+<p>Game-session lifecycle. Convention: documents have <code>host</code>, <code>guest</code>, and <code>status</code> fields.</p>
+<div class="table-scroll">
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+<table><thead><tr><th>Function</th><th>Returns</th></tr></thead><tbody><tr><td><code>validCreate()</code></td><td>Host is the auth user, guest empty, status is <code>waiting</code></td></tr><tr><td><code>validJoin()</code></td><td>Guest slot empty, joiner is not host, status flips to <code>playing</code></td></tr><tr><td><code>canCancel()</code></td><td>Status is <code>waiting</code>, requester is host</td></tr></tbody></table></div>
+<h2 id="turns"><code>turns</code></h2>
+<p>Turn enforcement for two-player games. Convention: documents have <code>host</code>, <code>guest</code>, and <code>currentTurn</code> fields.</p>
+<div class="table-scroll">
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+<table><thead><tr><th>Function</th><th>Returns</th></tr></thead><tbody><tr><td><code>isMyTurn()</code></td><td><code>currentTurn</code> matches auth uid (host or guest)</td></tr><tr><td><code>turnFlipped()</code></td><td><code>currentTurn</code> alternates between host and guest</td></tr></tbody></table></div>
+<h2 id="state"><code>state</code></h2>
+<p>Game-state tracking.</p>
+<div class="table-scroll">
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+<table><thead><tr><th>Function</th><th>Returns</th></tr></thead><tbody><tr><td><code>isPlaying()</code></td><td><code>resource.data.status == 'playing'</code></td></tr><tr><td><code>moveIncremented()</code></td><td><code>moveCount</code> increased by exactly 1</td></tr><tr><td><code>participantsUnchanged()</code></td><td><code>host</code> and <code>guest</code> fields unchanged</td></tr></tbody></table></div>
+<h2 id="membership"><code>membership</code></h2>
+<p>Role- and claims-based access control.</p>
+<div class="table-scroll">
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+<table><thead><tr><th>Function</th><th>Returns</th></tr></thead><tbody><tr><td><code>hasClaim(claim)</code></td><td>Auth token has non-null value at <code>claim</code></td></tr><tr><td><code>hasClaimRole(claim, role)</code></td><td>Auth token claim matches the role value</td></tr><tr><td><code>isMemberOf(membersMap)</code></td><td>Auth uid is a key in the members map</td></tr><tr><td><code>hasRole(membersMap, role)</code></td><td>Auth uid has the given role in the members map</td></tr></tbody></table></div>
+<h2 id="lifecycle"><code>lifecycle</code></h2>
+<p>Field immutability and timestamp enforcement.</p>
+<div class="table-scroll">
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+<table><thead><tr><th>Function</th><th>Returns</th></tr></thead><tbody><tr><td><code>fieldUnchanged(field)</code></td><td>Field value identical before and after the write</td></tr><tr><td><code>immutableFields(fields)</code></td><td>Every listed field is unchanged (uses MapDiff)</td></tr><tr><td><code>isServerTimestamp(field)</code></td><td>Field value equals <code>request.time</code></td></tr></tbody></table></div>
+<h2 id="transitions"><code>transitions</code></h2>
+<p>State-machine enforcement.</p>
+<div class="table-scroll">
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+<table><thead><tr><th>Function</th><th>Returns</th></tr></thead><tbody><tr><td><code>validTransition(field, from, to)</code></td><td>Field transitions from <code>from</code> to <code>to</code></td></tr><tr><td><code>statusIs(field, value)</code></td><td>Pre-write <code>field</code> equals <code>value</code></td></tr><tr><td><code>newStatusIs(field, value)</code></td><td>Post-write <code>field</code> equals <code>value</code></td></tr></tbody></table></div>
+<h2 id="geometry"><code>geometry</code></h2>
+<p>Movement-game validation via a config-document lookup. The caller must pass the config data (from a <code>get()</code> call) as the parameter. No implicit dependencies.</p>
+<div class="table-scroll">
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+<table><thead><tr><th>Function</th><th>Returns</th></tr></thead><tbody><tr><td><code>validSimpleMove(cfg)</code></td><td><code>cfg.moves[piece][from][to] == true</code></td></tr><tr><td><code>validJumpMove(cfg)</code></td><td><code>cfg.jumps[piece][from][to] == captured</code></td></tr></tbody></table></div>
+<p>Usage:</p>
+<pre class="astro-code one-dark-pro" style="background-color:#282c34;color:#abb2bf; overflow-x: auto;" tabindex="0" data-language="rules"><code><span class="line"><span style="color:#C678DD">import</span><span style="color:#ABB2BF"> { validSimpleMove, validJumpMove } </span><span style="color:#C678DD">from</span><span style="color:#98C379"> 'geometry'</span><span style="color:#ABB2BF">;</span></span>
+<span class="line"></span>
+<span class="line"><span style="color:#C678DD">function</span><span style="color:#ABB2BF"> config() {</span></span>
+<span class="line"><span style="color:#C678DD">  return</span><span style="color:#56B6C2"> get</span><span style="color:#ABB2BF">(/databases/$(database)/documents/gameConfig/checkers).data;</span></span>
+<span class="line"><span style="color:#ABB2BF">}</span></span>
+<span class="line"></span>
+<span class="line"><span style="color:#C678DD">match</span><span style="color:#ABB2BF"> /games/</span><span style="color:#E06C75;font-style:italic">{gameId}</span><span style="color:#ABB2BF"> {</span></span>
+<span class="line"><span style="color:#C678DD">  allow</span><span style="color:#61AFEF"> update</span><span style="color:#ABB2BF">: </span><span style="color:#C678DD">if</span><span style="color:#ABB2BF"> validSimpleMove(config()) &#x26;&#x26; piecePlaced();</span></span>
+<span class="line"><span style="color:#C678DD">  allow</span><span style="color:#61AFEF"> update</span><span style="color:#ABB2BF">: </span><span style="color:#C678DD">if</span><span style="color:#ABB2BF"> validJumpMove(config()) &#x26;&#x26; captureValid();</span></span>
+<span class="line"><span style="color:#ABB2BF">}</span></span></code></pre>
+<h2 id="importing-private-functions">Importing private functions</h2>
+<p>Functions in a module that aren’t marked <code>export</code> are still inlined by the resolver, but renamed with a module prefix (<code>{module}__{name}</code>) so they don’t collide with source-defined functions or with private helpers in other modules. You can’t import a private function by name; doing so produces <code>UNKNOWN_FUNCTION</code> with a message that explains the function exists but isn’t exported.</p>
+<h2 id="overriding-a-stdlib-module">Overriding a stdlib module</h2>
+<p>Pass a <code>modules</code> map to <code>resolveModules</code> to shadow a stdlib name:</p>
+<pre class="astro-code one-dark-pro" style="background-color:#282c34;color:#abb2bf; overflow-x: auto;" tabindex="0" data-language="ts"><code><span class="line"><span style="color:#C678DD">import</span><span style="color:#ABB2BF"> { </span><span style="color:#E06C75">resolveModules</span><span style="color:#ABB2BF"> } </span><span style="color:#C678DD">from</span><span style="color:#98C379"> 'pyric/rules/internal/node'</span><span style="color:#ABB2BF">;</span></span>
+<span class="line"></span>
+<span class="line"><span style="color:#61AFEF">resolveModules</span><span style="color:#ABB2BF">(</span><span style="color:#E06C75">source</span><span style="color:#ABB2BF">, {</span></span>
+<span class="line"><span style="color:#E06C75">  modules</span><span style="color:#ABB2BF">: {</span></span>
+<span class="line"><span style="color:#E06C75">    auth</span><span style="color:#ABB2BF">: </span><span style="color:#98C379">`</span></span>
+<span class="line"><span style="color:#98C379">      export function isAuthenticated() {</span></span>
+<span class="line"><span style="color:#98C379">        return request.auth != null &#x26;&#x26; request.auth.token.email_verified;</span></span>
+<span class="line"><span style="color:#98C379">      }</span></span>
+<span class="line"><span style="color:#98C379">      export function isOwner(userId) {</span></span>
+<span class="line"><span style="color:#98C379">        return isAuthenticated() &#x26;&#x26; request.auth.uid == userId;</span></span>
+<span class="line"><span style="color:#98C379">      }</span></span>
+<span class="line"><span style="color:#98C379">    `</span><span style="color:#ABB2BF">,</span></span>
+<span class="line"><span style="color:#ABB2BF">  },</span></span>
+<span class="line"><span style="color:#ABB2BF">});</span></span></code></pre>
+<p>The <code>modules</code> map takes priority over both stdlib and <code>basePath</code> resolution.</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="#auth">auth</a> </li><li data-depth="2"> <a href="#validation">validation</a> </li><li data-depth="2"> <a href="#lobby">lobby</a> </li><li data-depth="2"> <a href="#turns">turns</a> </li><li data-depth="2"> <a href="#state">state</a> </li><li data-depth="2"> <a href="#membership">membership</a> </li><li data-depth="2"> <a href="#lifecycle">lifecycle</a> </li><li data-depth="2"> <a href="#transitions">transitions</a> </li><li data-depth="2"> <a href="#geometry">geometry</a> </li><li data-depth="2"> <a href="#importing-private-functions">Importing private functions</a> </li><li data-depth="2"> <a href="#overriding-a-stdlib-module">Overriding a stdlib module</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-stdlib-modules.md

@@ -0,0 +1,143 @@
+# Standard library modules
+
+Fifteen modules ship with `pyric/rules`. Each module is a `.rules` file living under `src/rules/modules/stdlib/`; imports resolve automatically without any configuration.
+
+Use them by setting `rules_version = '2+modules'` and adding import statements:
+
+```rules
+import { isAuthenticated, isOwner } from 'auth';
+import { hasOnly } from 'validation';
+```
+
+Then run `resolveModules(source)` to inline the exports into a standard `'2'` source. `resolveModules` is an internal engine seam, imported from `pyric/rules/internal/node`, not the public `pyric/rules` front door. See [How to resolve `2+modules` imports](../pyric-rules-how-to-resolve-module-imports/).
+
+Convention: modules either operate against `request` / `resource` / `request.auth` only (self-contained) or take explicit parameters (no implicit lookups).
+
+## `auth`
+
+Access-control primitives.
+
+| Function | Returns |
+|---|---|
+| `isAuthenticated()` | `request.auth != null` |
+| `isOwner(userId)` | `isAuthenticated() && request.auth.uid == userId` |
+
+## `validation`
+
+Document field validation.
+
+| Function | Returns |
+|---|---|
+| `hasRequired(fields)` | `request.resource.data.keys().hasAll(fields)` |
+| `hasOnly(fields)` | `request.resource.data.keys().hasOnly(fields)` |
+
+## `lobby`
+
+Game-session lifecycle. Convention: documents have `host`, `guest`, and `status` fields.
+
+| Function | Returns |
+|---|---|
+| `validCreate()` | Host is the auth user, guest empty, status is `waiting` |
+| `validJoin()` | Guest slot empty, joiner is not host, status flips to `playing` |
+| `canCancel()` | Status is `waiting`, requester is host |
+
+## `turns`
+
+Turn enforcement for two-player games. Convention: documents have `host`, `guest`, and `currentTurn` fields.
+
+| Function | Returns |
+|---|---|
+| `isMyTurn()` | `currentTurn` matches auth uid (host or guest) |
+| `turnFlipped()` | `currentTurn` alternates between host and guest |
+
+## `state`
+
+Game-state tracking.
+
+| Function | Returns |
+|---|---|
+| `isPlaying()` | `resource.data.status == 'playing'` |
+| `moveIncremented()` | `moveCount` increased by exactly 1 |
+| `participantsUnchanged()` | `host` and `guest` fields unchanged |
+
+## `membership`
+
+Role- and claims-based access control.
+
+| Function | Returns |
+|---|---|
+| `hasClaim(claim)` | Auth token has non-null value at `claim` |
+| `hasClaimRole(claim, role)` | Auth token claim matches the role value |
+| `isMemberOf(membersMap)` | Auth uid is a key in the members map |
+| `hasRole(membersMap, role)` | Auth uid has the given role in the members map |
+
+## `lifecycle`
+
+Field immutability and timestamp enforcement.
+
+| Function | Returns |
+|---|---|
+| `fieldUnchanged(field)` | Field value identical before and after the write |
+| `immutableFields(fields)` | Every listed field is unchanged (uses MapDiff) |
+| `isServerTimestamp(field)` | Field value equals `request.time` |
+
+## `transitions`
+
+State-machine enforcement.
+
+| Function | Returns |
+|---|---|
+| `validTransition(field, from, to)` | Field transitions from `from` to `to` |
+| `statusIs(field, value)` | Pre-write `field` equals `value` |
+| `newStatusIs(field, value)` | Post-write `field` equals `value` |
+
+## `geometry`
+
+Movement-game validation via a config-document lookup. The caller must pass the config data (from a `get()` call) as the parameter. No implicit dependencies.
+
+| Function | Returns |
+|---|---|
+| `validSimpleMove(cfg)` | `cfg.moves[piece][from][to] == true` |
+| `validJumpMove(cfg)` | `cfg.jumps[piece][from][to] == captured` |
+
+Usage:
+
+```rules
+import { validSimpleMove, validJumpMove } from 'geometry';
+
+function config() {
+  return get(/databases/$(database)/documents/gameConfig/checkers).data;
+}
+
+match /games/{gameId} {
+  allow update: if validSimpleMove(config()) && piecePlaced();
+  allow update: if validJumpMove(config()) && captureValid();
+}
+```
+
+## Importing private functions
+
+Functions in a module that aren't marked `export` are still inlined by the resolver, but renamed with a module prefix (`{module}__{name}`) so they don't collide with source-defined functions or with private helpers in other modules. You can't import a private function by name; doing so produces `UNKNOWN_FUNCTION` with a message that explains the function exists but isn't exported.
+
+## Overriding a stdlib module
+
+Pass a `modules` map to `resolveModules` to shadow a stdlib name:
+
+```ts
+import { resolveModules } from 'pyric/rules/internal/node';
+
+resolveModules(source, {
+  modules: {
+    auth: `
+      export function isAuthenticated() {
+        return request.auth != null && request.auth.token.email_verified;
+      }
+      export function isOwner(userId) {
+        return isAuthenticated() && request.auth.uid == userId;
+      }
+    `,
+  },
+});
+```
+
+The `modules` map takes priority over both stdlib and `basePath` resolution.