@pyric/cli 0.1.0-alpha.9

package/dist/serve/docs-ui/docs/pyric-rules-how-to-inspect-rules-via-the-ast.md

@@ -0,0 +1,129 @@
+# How to inspect rules through the AST
+
+Parse rules into a typed AST and walk the tree for custom analysis: bespoke lint rules, generated documentation, or structural facts the built-in linter doesn't surface.
+
+The parser (`parseToAST`, `parseToASTOrError`, `parseFunctions`), the AST types, and `validateFirestoreRules` are engine-internal, imported from `pyric/rules/internal`. That surface isn't covered by the public `pyric/rules` contract and may change without notice. For the AST alone, `firestoreRules(source).toJSON()` on the public front door returns the same tree without touching the parser directly; reach for the internal imports below when you need to parse arbitrary fragments or run the validator standalone.
+
+## Parse to AST
+
+`parseToASTOrError` returns either the AST or a structured failure. Use it when you want a diagnostic on parse failure:
+
+```ts
+import { parseToASTOrError } from 'pyric/rules/internal';
+
+const result = parseToASTOrError(source);
+if (!result.ok) {
+  console.error(`Line ${result.error.line}, col ${result.error.column}: ${result.error.message}`);
+  process.exit(1);
+}
+const ast = result.ast;
+```
+
+When `null` is sufficient signal:
+
+```ts
+import { parseToAST } from 'pyric/rules/internal';
+
+const ast = parseToAST(source);
+if (!ast) throw new Error('parse failed');
+```
+
+## Walk match blocks
+
+`FirestoreRules.service.match` is the root match (always `/databases/{db}/documents`). Walk its `children` recursively to enumerate every nested match block:
+
+```ts
+import type { MatchBlock } from 'pyric/rules/internal';
+
+function walk(block: MatchBlock, parentPath = ''): void {
+  const path = parentPath + block.path.raw;
+  for (const allow of block.allows) {
+    console.log(`${path}  allow ${allow.operations.join(',')}`);
+  }
+  for (const child of block.children) walk(child, path);
+}
+
+walk(ast.service.match);
+```
+
+## Inspect path patterns
+
+A `PathPattern` is `{ raw: string, segments: PathSegment[] }`. Each segment is one of three shapes:
+
+- `{ type: 'literal', value: 'users' }`
+- `{ type: 'wildcard', name: 'uid' }`: for `{uid}`
+- `{ type: 'recursive', name: 'document' }`: for `{document=**}`
+
+Branch on `seg.type` rather than parsing `raw`:
+
+```ts
+for (const seg of block.path.segments) {
+  if (seg.type === 'literal') console.log('static:', seg.value);
+  else if (seg.type === 'wildcard') console.log('wildcard:', seg.name);
+  else console.log('recursive:', seg.name);
+}
+```
+
+## Walk expressions
+
+`Expression` is a discriminated union. The discriminator is `type`:
+
+```ts
+import type { Expression } from 'pyric/rules/internal';
+
+function walkExpr(expr: Expression, visit: (e: Expression) => void): void {
+  visit(expr);
+  switch (expr.type) {
+    case 'binaryOp':       walkExpr(expr.left, visit); walkExpr(expr.right, visit); break;
+    case 'unaryOp':        walkExpr(expr.operand, visit); break;
+    case 'methodCall':     walkExpr(expr.object, visit); expr.args.forEach((a) => walkExpr(a, visit)); break;
+    case 'memberAccess':   walkExpr(expr.object, visit); break;
+    case 'bracketAccess':  walkExpr(expr.object, visit); walkExpr(expr.index, visit); break;
+    case 'ternary':        walkExpr(expr.condition, visit); walkExpr(expr.consequent, visit); walkExpr(expr.alternate, visit); break;
+    case 'inExpr':         walkExpr(expr.element, visit); walkExpr(expr.collection, visit); break;
+    case 'isExpr':         walkExpr(expr.value, visit); break;
+    case 'listLiteral':    expr.elements.forEach((e) => walkExpr(e, visit)); break;
+    case 'mapLiteral':     expr.entries.forEach((en) => { walkExpr(en.key, visit); walkExpr(en.value, visit); }); break;
+    case 'functionCall':   expr.args.forEach((a) => walkExpr(a, visit)); break;
+    // 'literal', 'identifier', 'pathLiteral' — leaf nodes
+  }
+}
+```
+
+See [AST reference](../pyric-rules-reference-ast/) for every node shape.
+
+## Run the validator
+
+If your custom checks overlap with security or quality concerns, run the bundled validator and union the findings into your output:
+
+```ts
+import { validateFirestoreRules } from 'pyric/rules/internal';
+
+const findings = validateFirestoreRules(ast);
+for (const f of findings) {
+  console.log(`[${f.severity}] ${f.code} at ${f.path}: ${f.message}`);
+}
+```
+
+The validator covers public-write detection, default-deny audit, duplicate function names, overlapping paths, and other structural issues. See [Validator findings reference](../pyric-rules-reference-validator-findings/) for the full code list.
+
+## Parse just a function body
+
+Useful for editor pop-ups or function-level lint hooks:
+
+```ts
+import { parseFunctions } from 'pyric/rules/internal';
+
+const fns = parseFunctions(`
+  function isAdmin() { return request.auth.token.role == 'admin'; }
+`);
+if (fns) console.log(fns[0].name); // 'isAdmin'
+```
+
+`parseFunctions` wraps the input in a minimal `rules_version='2'` shell and returns only the parsed `FunctionDef[]`, or `null` if parsing failed.
+
+## Where to look next
+
+- For every AST node shape, see [AST reference](../pyric-rules-reference-ast/).
+- For the validator codes, see [Validator findings reference](../pyric-rules-reference-validator-findings/).
+- For `parseToASTOrError`'s `ParseError` shape, see [Errors reference](../pyric-rules-reference-errors/#parseerror).

package/dist/serve/docs-ui/docs/pyric-rules-how-to-lint-rules-source/index.html

@@ -0,0 +1,55 @@
+<!DOCTYPE html><html lang="en"> <head><meta charset="UTF-8"><meta name="viewport" content="width=device-width, initial-scale=1.0"><title>How to lint a rules source · 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>How-to</span> </li><li> <span class="docs-breadcrumbs-sep" aria-hidden="true">/</span> <span aria-current="page">Lint a rules source</span> </li> </ol> </nav>  <article class="prose">  <h1 id="how-to-lint-a-rules-source">How to lint a rules source</h1>
+<p>Lint a Firestore rules source, read the result, and gate a deploy on it. Everything here runs in-process.</p>
+<h2 id="lint-a-string">Lint a string</h2>
+<pre class="astro-code one-dark-pro" style="background-color:#282c34;color:#abb2bf; overflow-x: auto;" tabindex="0" data-language="ts"><code><span class="line"><span style="color:#C678DD">import</span><span style="color:#ABB2BF"> { </span><span style="color:#E06C75">lint</span><span style="color:#ABB2BF"> } </span><span style="color:#C678DD">from</span><span style="color:#98C379"> 'pyric/rules'</span><span style="color:#ABB2BF">;</span></span>
+<span class="line"></span>
+<span class="line"><span style="color:#C678DD">const</span><span style="color:#E5C07B"> issues</span><span style="color:#56B6C2"> =</span><span style="color:#61AFEF"> lint</span><span style="color:#ABB2BF">(</span><span style="color:#E06C75">source</span><span style="color:#ABB2BF">);</span></span></code></pre>
+<p><code>issues</code> is a <code>RuleIssue[]</code>. Each issue carries <code>origin</code>: <code>'parse'</code> for a compile blocker, <code>'validate'</code> for a structural/security finding, <code>'lint'</code> for a budget/quality/hallucination warning. <code>lint</code> never throws, even on empty or unparseable source.</p>
+<h2 id="branch-on-parse-errors-first">Branch on parse errors first</h2>
+<p>A parse error means “this isn’t a ruleset yet”, a different category from any lint or validation finding. Filter on <code>origin === 'parse'</code> before acting on the rest:</p>
+<pre class="astro-code one-dark-pro" style="background-color:#282c34;color:#abb2bf; overflow-x: auto;" tabindex="0" data-language="ts"><code><span class="line"><span style="color:#C678DD">const</span><span style="color:#E5C07B"> issues</span><span style="color:#56B6C2"> =</span><span style="color:#61AFEF"> lint</span><span style="color:#ABB2BF">(</span><span style="color:#E06C75">source</span><span style="color:#ABB2BF">);</span></span>
+<span class="line"><span style="color:#C678DD">const</span><span style="color:#E5C07B"> parseErrors</span><span style="color:#56B6C2"> =</span><span style="color:#E5C07B"> issues</span><span style="color:#ABB2BF">.</span><span style="color:#61AFEF">filter</span><span style="color:#ABB2BF">((</span><span style="color:#E06C75;font-style:italic">i</span><span style="color:#ABB2BF">) </span><span style="color:#C678DD">=></span><span style="color:#E5C07B"> i</span><span style="color:#ABB2BF">.</span><span style="color:#E06C75">origin</span><span style="color:#56B6C2"> ===</span><span style="color:#98C379"> 'parse'</span><span style="color:#ABB2BF">);</span></span>
+<span class="line"><span style="color:#C678DD">if</span><span style="color:#ABB2BF"> (</span><span style="color:#E5C07B">parseErrors</span><span style="color:#ABB2BF">.</span><span style="color:#E06C75">length</span><span style="color:#56B6C2"> ></span><span style="color:#D19A66"> 0</span><span style="color:#ABB2BF">) {</span></span>
+<span class="line"><span style="color:#C678DD">  for</span><span style="color:#ABB2BF"> (</span><span style="color:#C678DD">const</span><span style="color:#E5C07B"> e</span><span style="color:#C678DD"> of</span><span style="color:#E06C75"> parseErrors</span><span style="color:#ABB2BF">) {</span></span>
+<span class="line"><span style="color:#E5C07B">    console</span><span style="color:#ABB2BF">.</span><span style="color:#61AFEF">error</span><span style="color:#ABB2BF">(</span><span style="color:#98C379">`Line </span><span style="color:#C678DD">${</span><span style="color:#E5C07B">e</span><span style="color:#ABB2BF">.</span><span style="color:#E06C75">line</span><span style="color:#56B6C2"> ??</span><span style="color:#98C379"> '?'</span><span style="color:#C678DD">}</span><span style="color:#98C379">: </span><span style="color:#C678DD">${</span><span style="color:#E5C07B">e</span><span style="color:#ABB2BF">.</span><span style="color:#E06C75">message</span><span style="color:#C678DD">}</span><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:#E5C07B">  process</span><span style="color:#ABB2BF">.</span><span style="color:#61AFEF">exit</span><span style="color:#ABB2BF">(</span><span style="color:#D19A66">1</span><span style="color:#ABB2BF">);</span></span>
+<span class="line"><span style="color:#ABB2BF">}</span></span>
+<span class="line"><span style="color:#7F848E;font-style:italic">// Safe to treat the rest of `issues` as validate/lint findings.</span></span></code></pre>
+<p>Pre-parse syntax hints (JS-isms like <code>===</code>, <code>?.</code>, <code>??</code>, backtick strings) fire even when the file doesn’t parse, so <code>issues</code> may already contain useful entries before the parse-error check.</p>
+<h2 id="block-deploys-on-errors-only">Block deploys on errors only</h2>
+<p><code>issues</code> mixes severities. Gate CI (and refuse to <code>firebase deploy</code>) when any issue has <code>severity: 'error'</code>. Mirror that behaviour:</p>
+<pre class="astro-code one-dark-pro" style="background-color:#282c34;color:#abb2bf; overflow-x: auto;" tabindex="0" data-language="ts"><code><span class="line"><span style="color:#C678DD">const</span><span style="color:#E5C07B"> errors</span><span style="color:#56B6C2"> =</span><span style="color:#E5C07B"> issues</span><span style="color:#ABB2BF">.</span><span style="color:#61AFEF">filter</span><span style="color:#ABB2BF">((</span><span style="color:#E06C75;font-style:italic">i</span><span style="color:#ABB2BF">) </span><span style="color:#C678DD">=></span><span style="color:#E5C07B"> i</span><span style="color:#ABB2BF">.</span><span style="color:#E06C75">severity</span><span style="color:#56B6C2"> ===</span><span style="color:#98C379"> 'error'</span><span style="color:#ABB2BF">);</span></span>
+<span class="line"><span style="color:#C678DD">if</span><span style="color:#ABB2BF"> (</span><span style="color:#E5C07B">errors</span><span style="color:#ABB2BF">.</span><span style="color:#E06C75">length</span><span style="color:#56B6C2"> ></span><span style="color:#D19A66"> 0</span><span style="color:#ABB2BF">) {</span></span>
+<span class="line"><span style="color:#C678DD">  for</span><span style="color:#ABB2BF"> (</span><span style="color:#C678DD">const</span><span style="color:#E5C07B"> e</span><span style="color:#C678DD"> of</span><span style="color:#E06C75"> errors</span><span style="color:#ABB2BF">) </span><span style="color:#E5C07B">console</span><span style="color:#ABB2BF">.</span><span style="color:#61AFEF">error</span><span style="color:#ABB2BF">(</span><span style="color:#98C379">`[</span><span style="color:#C678DD">${</span><span style="color:#E5C07B">e</span><span style="color:#ABB2BF">.</span><span style="color:#E06C75">code</span><span style="color:#C678DD">}</span><span style="color:#98C379">] </span><span style="color:#C678DD">${</span><span style="color:#E5C07B">e</span><span style="color:#ABB2BF">.</span><span style="color:#E06C75">message</span><span style="color:#C678DD">}</span><span style="color:#98C379">`</span><span style="color:#ABB2BF">);</span></span>
+<span class="line"><span style="color:#E5C07B">  process</span><span style="color:#ABB2BF">.</span><span style="color:#61AFEF">exit</span><span style="color:#ABB2BF">(</span><span style="color:#D19A66">1</span><span style="color:#ABB2BF">);</span></span>
+<span class="line"><span style="color:#ABB2BF">}</span></span></code></pre>
+<h2 id="catch-silent-rule-weakening-on-update-and-pin-requesttime">Catch silent rule weakening on update, and pin <code>request.time</code></h2>
+<p>Two lint rules, <code>RULES_WEAKENED</code> and <code>REQUEST_TIME_NOT_PINNED</code>, need extra input beyond a bare source string: the previously-deployed source, and your test suite, respectively. Neither <code>lint(source)</code> nor <code>firestoreRules(source).lint()</code> takes options, so both checks are reached through the engine-internal <code>lintFirestoreRules(source, options)</code>, imported from <code>pyric/rules/internal</code>:</p>
+<pre class="astro-code one-dark-pro" style="background-color:#282c34;color:#abb2bf; overflow-x: auto;" tabindex="0" data-language="ts"><code><span class="line"><span style="color:#C678DD">import</span><span style="color:#ABB2BF"> { </span><span style="color:#E06C75">lintFirestoreRules</span><span style="color:#ABB2BF"> } </span><span style="color:#C678DD">from</span><span style="color:#98C379"> 'pyric/rules/internal'</span><span style="color:#ABB2BF">;</span></span>
+<span class="line"></span>
+<span class="line"><span style="color:#C678DD">const</span><span style="color:#E5C07B"> result</span><span style="color:#56B6C2"> =</span><span style="color:#61AFEF"> lintFirestoreRules</span><span style="color:#ABB2BF">(</span><span style="color:#E06C75">newSource</span><span style="color:#ABB2BF">, {</span></span>
+<span class="line"><span style="color:#E06C75">  previousSource</span><span style="color:#ABB2BF">: </span><span style="color:#E06C75">oldSource</span><span style="color:#ABB2BF">,</span></span>
+<span class="line"><span style="color:#E06C75">  testCases</span><span style="color:#ABB2BF">,</span></span>
+<span class="line"><span style="color:#ABB2BF">});</span></span>
+<span class="line"></span>
+<span class="line"><span style="color:#C678DD">const</span><span style="color:#E5C07B"> weakened</span><span style="color:#56B6C2"> =</span><span style="color:#E5C07B"> result</span><span style="color:#ABB2BF">.</span><span style="color:#E5C07B">warnings</span><span style="color:#ABB2BF">.</span><span style="color:#61AFEF">filter</span><span style="color:#ABB2BF">((</span><span style="color:#E06C75;font-style:italic">w</span><span style="color:#ABB2BF">) </span><span style="color:#C678DD">=></span><span style="color:#E5C07B"> w</span><span style="color:#ABB2BF">.</span><span style="color:#E06C75">rule</span><span style="color:#56B6C2"> ===</span><span style="color:#98C379"> 'RULES_WEAKENED'</span><span style="color:#ABB2BF">);</span></span>
+<span class="line"><span style="color:#C678DD">const</span><span style="color:#E5C07B"> unpinned</span><span style="color:#56B6C2"> =</span><span style="color:#E5C07B"> result</span><span style="color:#ABB2BF">.</span><span style="color:#E5C07B">warnings</span><span style="color:#ABB2BF">.</span><span style="color:#61AFEF">filter</span><span style="color:#ABB2BF">((</span><span style="color:#E06C75;font-style:italic">w</span><span style="color:#ABB2BF">) </span><span style="color:#C678DD">=></span><span style="color:#E5C07B"> w</span><span style="color:#ABB2BF">.</span><span style="color:#E06C75">rule</span><span style="color:#56B6C2"> ===</span><span style="color:#98C379"> 'REQUEST_TIME_NOT_PINNED'</span><span style="color:#ABB2BF">);</span></span></code></pre>
+<p><code>RULES_WEAKENED</code> is a <code>warning</code>, not an <code>error</code>. There are legitimate reasons to delete a predicate (refactor, dedupe). The signal is “review this”, not “block the deploy”. See <a href="../pyric-rules-how-to-compare-rulesets-for-weakening/">How to compare two rulesets for weakening</a> and <a href="../pyric-rules-how-to-pin-request-time/">Pin <code>request.time</code> for deterministic tests</a>.</p>
+<h2 id="inspect-structural-metrics">Inspect structural metrics</h2>
+<p>The internal <code>lintFirestoreRules</code> result also carries <code>metrics</code>, the structural summary. <code>lint(source)</code> has no equivalent on the public surface:</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">lintFirestoreRules</span><span style="color:#ABB2BF"> } </span><span style="color:#C678DD">from</span><span style="color:#98C379"> 'pyric/rules/internal'</span><span style="color:#ABB2BF">;</span></span>
+<span class="line"></span>
+<span class="line"><span style="color:#C678DD">const</span><span style="color:#E5C07B"> result</span><span style="color:#56B6C2"> =</span><span style="color:#61AFEF"> lintFirestoreRules</span><span style="color:#ABB2BF">(</span><span style="color:#E06C75">source</span><span style="color:#ABB2BF">);</span></span>
+<span class="line"><span style="color:#C678DD">const</span><span style="color:#E5C07B"> m</span><span style="color:#56B6C2"> =</span><span style="color:#E5C07B"> result</span><span style="color:#ABB2BF">.</span><span style="color:#E06C75">metrics</span><span style="color:#ABB2BF">;</span></span>
+<span class="line"><span style="color:#E5C07B">console</span><span style="color:#ABB2BF">.</span><span style="color:#61AFEF">log</span><span style="color:#ABB2BF">(</span></span>
+<span class="line"><span style="color:#98C379">  `</span><span style="color:#C678DD">${</span><span style="color:#E5C07B">m</span><span style="color:#ABB2BF">.</span><span style="color:#E06C75">allowRuleCount</span><span style="color:#C678DD">}</span><span style="color:#98C379"> rules, </span><span style="color:#C678DD">${</span><span style="color:#E5C07B">m</span><span style="color:#ABB2BF">.</span><span style="color:#E06C75">functionCount</span><span style="color:#C678DD">}</span><span style="color:#98C379"> functions, `</span></span>
+<span class="line"><span style="color:#56B6C2">  +</span><span style="color:#98C379"> `max chain depth </span><span style="color:#C678DD">${</span><span style="color:#E5C07B">m</span><span style="color:#ABB2BF">.</span><span style="color:#E06C75">maxChainDepth</span><span style="color:#C678DD">}</span><span style="color:#98C379"> (</span><span style="color:#C678DD">${</span><span style="color:#E5C07B">m</span><span style="color:#ABB2BF">.</span><span style="color:#E06C75">maxChainOp</span><span style="color:#C678DD">}</span><span style="color:#98C379">), `</span></span>
+<span class="line"><span style="color:#56B6C2">  +</span><span style="color:#98C379"> `max let bindings </span><span style="color:#C678DD">${</span><span style="color:#E5C07B">m</span><span style="color:#ABB2BF">.</span><span style="color:#E06C75">maxLetBindings</span><span style="color:#C678DD">}</span><span style="color:#98C379"> in </span><span style="color:#C678DD">${</span><span style="color:#E5C07B">m</span><span style="color:#ABB2BF">.</span><span style="color:#E06C75">maxLetBindingsFunction</span><span style="color:#56B6C2"> ||</span><span style="color:#98C379"> 'n/a'</span><span style="color:#C678DD">}</span><span style="color:#98C379">`</span><span style="color:#ABB2BF">,</span></span>
+<span class="line"><span style="color:#ABB2BF">);</span></span></code></pre>
+<p>Use these to plot trends across PRs or to assert on growth in CI.</p>
+<h2 id="where-to-look-next">Where to look next</h2>
+<ul>
+<li>Want the exact thresholds and detection algorithms? See <a href="../pyric-rules-reference-lint-rules/">Lint rules reference</a>.</li>
+<li>Want to know <em>why</em> these particular rules exist? See <a href="../pyric-rules-explanation-runtime-budget-and-shared-gates/">Runtime budget and shared gates</a> and <a href="../pyric-rules-explanation-agent-failure-modes/">Agent failure modes</a>.</li>
+</ul>  </article> </main> <aside class="doc-toc" aria-label="On this page"> <h2 class="doc-toc-heading">On this page</h2> <ul> <li data-depth="2"> <a href="#lint-a-string">Lint a string</a> </li><li data-depth="2"> <a href="#branch-on-parse-errors-first">Branch on parse errors first</a> </li><li data-depth="2"> <a href="#block-deploys-on-errors-only">Block deploys on errors only</a> </li><li data-depth="2"> <a href="#catch-silent-rule-weakening-on-update-and-pin-requesttime">Catch silent rule weakening on update, and pin request.time</a> </li><li data-depth="2"> <a href="#inspect-structural-metrics">Inspect structural metrics</a> </li><li data-depth="2"> <a href="#where-to-look-next">Where to look next</a> </li> </ul> </aside> </div> <script type="module">const a=document.querySelector("[data-api-symbol-filter]"),d=[...document.querySelectorAll("[data-api-symbol-group]")],n=document.querySelector("[data-api-symbol-empty]");a?.addEventListener("input",()=>{const t=a.value.trim().toLowerCase();let o=0;for(const i of d){let e=0;i.querySelectorAll("[data-api-symbol]").forEach(l=>{const r=!t||(l.dataset.apiSymbol??"").includes(t);l.hidden=!r,r&&e++}),i.hidden=e===0,o+=e}n&&(n.hidden=o>0)});</script> <script type="module">const s=new Map;document.querySelectorAll('.doc-toc a[href^="#"]').forEach(t=>s.set(decodeURIComponent(t.hash.slice(1)),t));if(s.size>0){const t=new Set,n=()=>{let o=null;for(const e of s.keys())if(t.has(e)){o=e;break}s.forEach((e,c)=>e.classList.toggle("active",c===o))},r=new IntersectionObserver(o=>{for(const e of o)e.isIntersecting?t.add(e.target.id):t.delete(e.target.id);n()},{rootMargin:"-72px 0px -60% 0px"});s.forEach((o,e)=>{const c=document.getElementById(e);c&&r.observe(c)})}</script> <script type="module">document.querySelector('.studio__nav [aria-current="page"]')?.scrollIntoView({block:"nearest",inline:"center"});</script> </body> </html>

package/dist/serve/docs-ui/docs/pyric-rules-how-to-lint-rules-source.md

@@ -0,0 +1,84 @@
+# How to lint a rules source
+
+Lint a Firestore rules source, read the result, and gate a deploy on it. Everything here runs in-process.
+
+## Lint a string
+
+```ts
+import { lint } from 'pyric/rules';
+
+const issues = lint(source);
+```
+
+`issues` is a `RuleIssue[]`. Each issue carries `origin`: `'parse'` for a compile blocker, `'validate'` for a structural/security finding, `'lint'` for a budget/quality/hallucination warning. `lint` never throws, even on empty or unparseable source.
+
+## Branch on parse errors first
+
+A parse error means "this isn't a ruleset yet", a different category from any lint or validation finding. Filter on `origin === 'parse'` before acting on the rest:
+
+```ts
+const issues = lint(source);
+const parseErrors = issues.filter((i) => i.origin === 'parse');
+if (parseErrors.length > 0) {
+  for (const e of parseErrors) {
+    console.error(`Line ${e.line ?? '?'}: ${e.message}`);
+  }
+  process.exit(1);
+}
+// Safe to treat the rest of `issues` as validate/lint findings.
+```
+
+Pre-parse syntax hints (JS-isms like `===`, `?.`, `??`, backtick strings) fire even when the file doesn't parse, so `issues` may already contain useful entries before the parse-error check.
+
+## Block deploys on errors only
+
+`issues` mixes severities. Gate CI (and refuse to `firebase deploy`) when any issue has `severity: 'error'`. Mirror that behaviour:
+
+```ts
+const errors = issues.filter((i) => i.severity === 'error');
+if (errors.length > 0) {
+  for (const e of errors) console.error(`[${e.code}] ${e.message}`);
+  process.exit(1);
+}
+```
+
+## Catch silent rule weakening on update, and pin `request.time`
+
+Two lint rules, `RULES_WEAKENED` and `REQUEST_TIME_NOT_PINNED`, need extra input beyond a bare source string: the previously-deployed source, and your test suite, respectively. Neither `lint(source)` nor `firestoreRules(source).lint()` takes options, so both checks are reached through the engine-internal `lintFirestoreRules(source, options)`, imported from `pyric/rules/internal`:
+
+```ts
+import { lintFirestoreRules } from 'pyric/rules/internal';
+
+const result = lintFirestoreRules(newSource, {
+  previousSource: oldSource,
+  testCases,
+});
+
+const weakened = result.warnings.filter((w) => w.rule === 'RULES_WEAKENED');
+const unpinned = result.warnings.filter((w) => w.rule === 'REQUEST_TIME_NOT_PINNED');
+```
+
+`RULES_WEAKENED` is a `warning`, not an `error`. There are legitimate reasons to delete a predicate (refactor, dedupe). The signal is "review this", not "block the deploy". See [How to compare two rulesets for weakening](../pyric-rules-how-to-compare-rulesets-for-weakening/) and [Pin `request.time` for deterministic tests](../pyric-rules-how-to-pin-request-time/).
+
+## Inspect structural metrics
+
+The internal `lintFirestoreRules` result also carries `metrics`, the structural summary. `lint(source)` has no equivalent on the public surface:
+
+```ts
+import { lintFirestoreRules } from 'pyric/rules/internal';
+
+const result = lintFirestoreRules(source);
+const m = result.metrics;
+console.log(
+  `${m.allowRuleCount} rules, ${m.functionCount} functions, `
+  + `max chain depth ${m.maxChainDepth} (${m.maxChainOp}), `
+  + `max let bindings ${m.maxLetBindings} in ${m.maxLetBindingsFunction || 'n/a'}`,
+);
+```
+
+Use these to plot trends across PRs or to assert on growth in CI.
+
+## Where to look next
+
+- Want the exact thresholds and detection algorithms? See [Lint rules reference](../pyric-rules-reference-lint-rules/).
+- Want to know *why* these particular rules exist? See [Runtime budget and shared gates](../pyric-rules-explanation-runtime-budget-and-shared-gates/) and [Agent failure modes](../pyric-rules-explanation-agent-failure-modes/).

package/dist/serve/docs-ui/docs/pyric-rules-how-to-pin-request-time/index.html

@@ -0,0 +1,49 @@
+<!DOCTYPE html><html lang="en"> <head><meta charset="UTF-8"><meta name="viewport" content="width=device-width, initial-scale=1.0"><title>How to pin request.time for deterministic tests · 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>How-to</span> </li><li> <span class="docs-breadcrumbs-sep" aria-hidden="true">/</span> <span aria-current="page">Pin request.time</span> </li> </ol> </nav>  <article class="prose">  <h1 id="how-to-pin-requesttime-for-deterministic-tests">How to pin <code>request.time</code> for deterministic tests</h1>
+<p>A rule that reads <code>request.time</code> evaluates against wallclock by default. That makes any date-gated test flaky: the same <code>FirestoreCase</code> run twice can decide <code>ALLOW</code> once and <code>DENY</code> the next. Pin time and the verdict is reproducible.</p>
+<h2 id="set-requesttime-on-every-affected-firestorecase">Set <code>requestTime</code> on every affected <code>FirestoreCase</code></h2>
+<p><code>requestTime</code> accepts an ISO-8601 string. The simulator parses it into a <code>Timestamp</code> and uses it for <code>request.time</code>:</p>
+<pre class="astro-code one-dark-pro" style="background-color:#282c34;color:#abb2bf; overflow-x: auto;" tabindex="0" data-language="ts"><code><span class="line"><span style="color:#C678DD">import</span><span style="color:#C678DD"> type</span><span style="color:#ABB2BF"> { </span><span style="color:#E06C75">FirestoreCase</span><span style="color:#ABB2BF"> } </span><span style="color:#C678DD">from</span><span style="color:#98C379"> 'pyric/rules'</span><span style="color:#ABB2BF">;</span></span>
+<span class="line"></span>
+<span class="line"><span style="color:#C678DD">const</span><span style="color:#E5C07B"> testCases</span><span style="color:#ABB2BF">: </span><span style="color:#E5C07B">FirestoreCase</span><span style="color:#ABB2BF">[] </span><span style="color:#56B6C2">=</span><span style="color:#ABB2BF"> [</span></span>
+<span class="line"><span style="color:#ABB2BF">  {</span></span>
+<span class="line"><span style="color:#E06C75">    description</span><span style="color:#ABB2BF">: </span><span style="color:#98C379">'inside the trial window'</span><span style="color:#ABB2BF">,</span></span>
+<span class="line"><span style="color:#E06C75">    expectation</span><span style="color:#ABB2BF">: </span><span style="color:#98C379">'ALLOW'</span><span style="color:#ABB2BF">,</span></span>
+<span class="line"><span style="color:#E06C75">    method</span><span style="color:#ABB2BF">: </span><span style="color:#98C379">'create'</span><span style="color:#ABB2BF">,</span></span>
+<span class="line"><span style="color:#E06C75">    path</span><span style="color:#ABB2BF">: </span><span style="color:#98C379">'orders/o1'</span><span style="color:#ABB2BF">,</span></span>
+<span class="line"><span style="color:#E06C75">    auth</span><span style="color:#ABB2BF">: { </span><span style="color:#E06C75">uid</span><span style="color:#ABB2BF">: </span><span style="color:#98C379">'alice'</span><span style="color:#ABB2BF"> },</span></span>
+<span class="line"><span style="color:#E06C75">    data</span><span style="color:#ABB2BF">: { </span><span style="color:#E06C75">amount</span><span style="color:#ABB2BF">: </span><span style="color:#D19A66">100</span><span style="color:#ABB2BF"> },</span></span>
+<span class="line"><span style="color:#E06C75">    requestTime</span><span style="color:#ABB2BF">: </span><span style="color:#98C379">'2026-04-15T12:00:00Z'</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>
+<span class="line"><span style="color:#E06C75">    description</span><span style="color:#ABB2BF">: </span><span style="color:#98C379">'after the trial window'</span><span style="color:#ABB2BF">,</span></span>
+<span class="line"><span style="color:#E06C75">    expectation</span><span style="color:#ABB2BF">: </span><span style="color:#98C379">'DENY'</span><span style="color:#ABB2BF">,</span></span>
+<span class="line"><span style="color:#E06C75">    method</span><span style="color:#ABB2BF">: </span><span style="color:#98C379">'create'</span><span style="color:#ABB2BF">,</span></span>
+<span class="line"><span style="color:#E06C75">    path</span><span style="color:#ABB2BF">: </span><span style="color:#98C379">'orders/o1'</span><span style="color:#ABB2BF">,</span></span>
+<span class="line"><span style="color:#E06C75">    auth</span><span style="color:#ABB2BF">: { </span><span style="color:#E06C75">uid</span><span style="color:#ABB2BF">: </span><span style="color:#98C379">'alice'</span><span style="color:#ABB2BF"> },</span></span>
+<span class="line"><span style="color:#E06C75">    data</span><span style="color:#ABB2BF">: { </span><span style="color:#E06C75">amount</span><span style="color:#ABB2BF">: </span><span style="color:#D19A66">100</span><span style="color:#ABB2BF"> },</span></span>
+<span class="line"><span style="color:#E06C75">    requestTime</span><span style="color:#ABB2BF">: </span><span style="color:#98C379">'2026-05-15T12:00:00Z'</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 same ISO string is forwarded to the Firebase Rules Test API when you run via the internal <code>TestFirestoreRulesHandler</code> (<code>pyric/rules/internal</code>), so the two evaluation paths stay in agreement.</p>
+<h2 id="find-unpinned-cases-automatically">Find unpinned cases automatically</h2>
+<p>Pass the test suite to the linter and look for <code>REQUEST_TIME_NOT_PINNED</code>. The public <code>lint(source)</code> and <code>firestoreRules(source).lint()</code> don’t take a <code>testCases</code> option, so this check runs through the engine-internal <code>lintFirestoreRules</code>:</p>
+<pre class="astro-code one-dark-pro" style="background-color:#282c34;color:#abb2bf; overflow-x: auto;" tabindex="0" data-language="ts"><code><span class="line"><span style="color:#C678DD">import</span><span style="color:#ABB2BF"> { </span><span style="color:#E06C75">lintFirestoreRules</span><span style="color:#ABB2BF"> } </span><span style="color:#C678DD">from</span><span style="color:#98C379"> 'pyric/rules/internal'</span><span style="color:#ABB2BF">;</span></span>
+<span class="line"></span>
+<span class="line"><span style="color:#C678DD">const</span><span style="color:#E5C07B"> result</span><span style="color:#56B6C2"> =</span><span style="color:#61AFEF"> lintFirestoreRules</span><span style="color:#ABB2BF">(</span><span style="color:#E06C75">source</span><span style="color:#ABB2BF">, { </span><span style="color:#E06C75">testCases</span><span style="color:#ABB2BF"> });</span></span>
+<span class="line"><span style="color:#C678DD">const</span><span style="color:#E5C07B"> unpinned</span><span style="color:#56B6C2"> =</span><span style="color:#E5C07B"> result</span><span style="color:#ABB2BF">.</span><span style="color:#E5C07B">warnings</span><span style="color:#ABB2BF">.</span><span style="color:#61AFEF">filter</span><span style="color:#ABB2BF">((</span><span style="color:#E06C75;font-style:italic">w</span><span style="color:#ABB2BF">) </span><span style="color:#C678DD">=></span><span style="color:#E5C07B"> w</span><span style="color:#ABB2BF">.</span><span style="color:#E06C75">rule</span><span style="color:#56B6C2"> ===</span><span style="color:#98C379"> 'REQUEST_TIME_NOT_PINNED'</span><span style="color:#ABB2BF">);</span></span>
+<span class="line"></span>
+<span class="line"><span style="color:#C678DD">for</span><span style="color:#ABB2BF"> (</span><span style="color:#C678DD">const</span><span style="color:#E5C07B"> w</span><span style="color:#C678DD"> of</span><span style="color:#E06C75"> unpinned</span><span style="color:#ABB2BF">) {</span></span>
+<span class="line"><span style="color:#E5C07B">  console</span><span style="color:#ABB2BF">.</span><span style="color:#61AFEF">warn</span><span style="color:#ABB2BF">(</span><span style="color:#E5C07B">w</span><span style="color:#ABB2BF">.</span><span style="color:#E06C75">message</span><span style="color:#ABB2BF">);</span></span>
+<span class="line"><span style="color:#7F848E;font-style:italic">  // Output:</span></span>
+<span class="line"><span style="color:#7F848E;font-style:italic">  // Test case "&#x3C;description>" targets rule #&#x3C;n> (path '&#x3C;p>') which reads</span></span>
+<span class="line"><span style="color:#7F848E;font-style:italic">  // request.time, but does not set requestTime. Result is non-deterministic</span></span>
+<span class="line"><span style="color:#7F848E;font-style:italic">  // across runs.</span></span>
+<span class="line"><span style="color:#ABB2BF">}</span></span></code></pre>
+<p>The linter only flags a case if its <code>path</code> actually matches a rule that reads <code>request.time</code>. Cases that target unrelated paths aren’t reported.</p>
+<h2 id="when-requesttime-doesnt-help">When <code>requestTime</code> doesn’t help</h2>
+<p><code>requestTime</code> only fixes <code>request.time</code>. If your rule reads <code>resource.data.createdAt</code> and that field was populated by <code>FieldValue.serverTimestamp()</code>, the simulator resolves the sentinel using the same pinned time. But if your test data hardcodes a different timestamp, the comparison uses that. Make the resource value match what the rule expects to see.</p>
+<h2 id="where-to-look-next">Where to look next</h2>
+<ul>
+<li>For the timestamp value model, see <a href="../pyric-rules-reference-value-wrappers/#timestamp"><code>Timestamp</code> in the value wrappers reference</a>.</li>
+<li>For the <code>TestCase</code> schema field, see <a href="../pyric-rules-reference-test-case-schema/"><code>requestTime</code> in the <code>TestCase</code> schema</a>.</li>
+</ul>  </article> </main> <aside class="doc-toc" aria-label="On this page"> <h2 class="doc-toc-heading">On this page</h2> <ul> <li data-depth="2"> <a href="#set-requesttime-on-every-affected-firestorecase">Set requestTime on every affected FirestoreCase</a> </li><li data-depth="2"> <a href="#find-unpinned-cases-automatically">Find unpinned cases automatically</a> </li><li data-depth="2"> <a href="#when-requesttime-doesnt-help">When requestTime doesn’t help</a> </li><li data-depth="2"> <a href="#where-to-look-next">Where to look next</a> </li> </ul> </aside> </div> <script type="module">const a=document.querySelector("[data-api-symbol-filter]"),d=[...document.querySelectorAll("[data-api-symbol-group]")],n=document.querySelector("[data-api-symbol-empty]");a?.addEventListener("input",()=>{const t=a.value.trim().toLowerCase();let o=0;for(const i of d){let e=0;i.querySelectorAll("[data-api-symbol]").forEach(l=>{const r=!t||(l.dataset.apiSymbol??"").includes(t);l.hidden=!r,r&&e++}),i.hidden=e===0,o+=e}n&&(n.hidden=o>0)});</script> <script type="module">const s=new Map;document.querySelectorAll('.doc-toc a[href^="#"]').forEach(t=>s.set(decodeURIComponent(t.hash.slice(1)),t));if(s.size>0){const t=new Set,n=()=>{let o=null;for(const e of s.keys())if(t.has(e)){o=e;break}s.forEach((e,c)=>e.classList.toggle("active",c===o))},r=new IntersectionObserver(o=>{for(const e of o)e.isIntersecting?t.add(e.target.id):t.delete(e.target.id);n()},{rootMargin:"-72px 0px -60% 0px"});s.forEach((o,e)=>{const c=document.getElementById(e);c&&r.observe(c)})}</script> <script type="module">document.querySelector('.studio__nav [aria-current="page"]')?.scrollIntoView({block:"nearest",inline:"center"});</script> </body> </html>

package/dist/serve/docs-ui/docs/pyric-rules-how-to-pin-request-time.md

@@ -0,0 +1,64 @@
+# How to pin `request.time` for deterministic tests
+
+A rule that reads `request.time` evaluates against wallclock by default. That makes any date-gated test flaky: the same `FirestoreCase` run twice can decide `ALLOW` once and `DENY` the next. Pin time and the verdict is reproducible.
+
+## Set `requestTime` on every affected `FirestoreCase`
+
+`requestTime` accepts an ISO-8601 string. The simulator parses it into a `Timestamp` and uses it for `request.time`:
+
+```ts
+import type { FirestoreCase } from 'pyric/rules';
+
+const testCases: FirestoreCase[] = [
+  {
+    description: 'inside the trial window',
+    expectation: 'ALLOW',
+    method: 'create',
+    path: 'orders/o1',
+    auth: { uid: 'alice' },
+    data: { amount: 100 },
+    requestTime: '2026-04-15T12:00:00Z',
+  },
+  {
+    description: 'after the trial window',
+    expectation: 'DENY',
+    method: 'create',
+    path: 'orders/o1',
+    auth: { uid: 'alice' },
+    data: { amount: 100 },
+    requestTime: '2026-05-15T12:00:00Z',
+  },
+];
+```
+
+The same ISO string is forwarded to the Firebase Rules Test API when you run via the internal `TestFirestoreRulesHandler` (`pyric/rules/internal`), so the two evaluation paths stay in agreement.
+
+## Find unpinned cases automatically
+
+Pass the test suite to the linter and look for `REQUEST_TIME_NOT_PINNED`. The public `lint(source)` and `firestoreRules(source).lint()` don't take a `testCases` option, so this check runs through the engine-internal `lintFirestoreRules`:
+
+```ts
+import { lintFirestoreRules } from 'pyric/rules/internal';
+
+const result = lintFirestoreRules(source, { testCases });
+const unpinned = result.warnings.filter((w) => w.rule === 'REQUEST_TIME_NOT_PINNED');
+
+for (const w of unpinned) {
+  console.warn(w.message);
+  // Output:
+  // Test case "<description>" targets rule #<n> (path '<p>') which reads
+  // request.time, but does not set requestTime. Result is non-deterministic
+  // across runs.
+}
+```
+
+The linter only flags a case if its `path` actually matches a rule that reads `request.time`. Cases that target unrelated paths aren't reported.
+
+## When `requestTime` doesn't help
+
+`requestTime` only fixes `request.time`. If your rule reads `resource.data.createdAt` and that field was populated by `FieldValue.serverTimestamp()`, the simulator resolves the sentinel using the same pinned time. But if your test data hardcodes a different timestamp, the comparison uses that. Make the resource value match what the rule expects to see.
+
+## Where to look next
+
+- For the timestamp value model, see [`Timestamp` in the value wrappers reference](../pyric-rules-reference-value-wrappers/#timestamp).
+- For the `TestCase` schema field, see [`requestTime` in the `TestCase` schema](../pyric-rules-reference-test-case-schema/).