@pyric/cli 0.1.0-alpha.9

package/dist/serve/docs-ui/docs/pyric-database-reference-constraints.md

@@ -0,0 +1,168 @@
+# API reference: RTDB rules constraints
+
+Typed builders that produce Realtime Database security-rule expressions, plus the assembly layer that places them in a path tree and compiles the tree to Firebase rules JSON. Everything on this page is importable directly from `pyric/rules`, the public front door. The dedicated constraints-only subpaths that used to exist (`pyric/rules/rtdb/constraints`, `pyric/rules/rtdb-constraints`) no longer do; there is one place to import the DSL from now. The engine that compiles and simulates against it (the parser, linter, simulator, and tool factories) lives on the internal `pyric/rules/internal/rtdb` subpath instead.
+
+Every builder returns an `Expr`, which is a plain string of RTDB rules language. The produced expressions below are pinned by spec tests, so they are safe to rely on byte for byte.
+
+Realtime Database support is experimental. The behaviors here are verified in-process; see the [compatibility matrix](../pyric-database-compat/) for what is pinned against production.
+
+## Combinators
+
+| Export | Signature | Produces |
+|---|---|---|
+| `expr(raw)` | `(raw: string) => Expr` | the raw string, unchanged |
+| `all(...exprs)` | `(...exprs: Expr[]) => Expr` | `(a) && (b) && ...` (each operand parenthesized) |
+| `any(...exprs)` | `(...exprs: Expr[]) => Expr` | `(a) \|\| (b) \|\| ...` |
+| `not(e)` | `(e: Expr) => Expr` | `!(e)` |
+| `deny()` | `() => Expr` | `false` |
+| `always()` | `() => Expr` | `true` |
+| `allow()` | alias of `always` | `true` |
+
+## Atoms
+
+| Export | Signature | Produces |
+|---|---|---|
+| `authenticated()` | `() => Expr` | `auth !== null` |
+| `ownPath(pathVar)` | `(pathVar: string) => Expr` | `auth.uid === $pathVar` |
+| `ownField(field)` | `(field: string) => Expr` | `auth.uid === data.child("field").val()` |
+| `isNew()` | `() => Expr` | `!data.exists()` |
+| `hasChildren()` | `() => Expr` | `newData.hasChildren()` |
+| `hasChild(field)` | `(field: string) => Expr` | `newData.hasChild("field")` |
+| `fieldIsString(field)` | `(field: string) => Expr` | `newData.child("field").isString()` |
+| `fieldIsNumber(field)` | `(field: string) => Expr` | `newData.child("field").isNumber()` |
+| `fieldIsBoolean(field)` | `(field: string) => Expr` | `newData.child("field").isBoolean()` |
+| `fieldEnum(field, values)` | `(field: string, values: string[]) => Expr` | `newData.child("f").val() === "a" \|\| ... === "b"` |
+| `immutable(field)` | `(field: string) => Expr` | `!data.exists() \|\| newData.child("f").val() === data.child("f").val()` |
+| `immutableSelf()` | `() => Expr` | `!data.exists() \|\| newData.val() === data.val()` |
+| `rootExists(segments)` | `(segments: Segment[]) => Expr` | `root.child("a").child($var).exists()` |
+| `rootEquals(segments, value)` | `(segments: Segment[], value: string) => Expr` | `root.child(...).val() === "value"` |
+
+`Segment = string | { $: string }`. A string segment is quoted (`child("members")`); a `{ $: name }` segment is inserted unquoted, which is how path variables (`{ $: '$roomId' }`) and runtime references (`{ $: 'auth.uid' }`) enter a path chain. `fieldEnum`'s branches are not individually parenthesized; compose it through `all()`/`any()`, which wrap it.
+
+## Policies (composed atoms)
+
+| Export | Signature | Produces |
+|---|---|---|
+| `pathOwnerOnly(pathVar)` | `(pathVar: string) => Expr` | `(auth !== null) && (auth.uid === $var)` |
+| `fieldOwnerOnly(field)` | `(field: string) => Expr` | `(auth !== null) && (auth.uid === data.child("f").val())` |
+| `ownerOrNew(field)` | `(field: string) => Expr` | signed in, and the record is new or owned by the caller |
+| `hasRole(segments, role)` | `(segments: Segment[], role: string) => Expr` | `rootEquals(segments, role)` |
+| `isMember(listName, pathVarName)` | `(listName: string, pathVarName: string) => Expr` | `root.child("list").child($var).child(auth.uid).exists()` (prepends `$` to `pathVarName` itself) |
+| `required(...fields)` | `(...fields: string[]) => Expr` | AND of `newData.hasChild(...)` per field |
+| `transition(field, allowed)` | `(field: string, allowed: Array<[from, to]>) => Expr` | OR of `(data.child("f").val() === "from") && (newData.child("f").val() === "to")` pairs |
+
+## Data helpers
+
+| Export | Signature | Produces |
+|---|---|---|
+| `dataVal(path?)` | `(path?: string) => Expr` | `data.val()` or `data.child("p").val()` |
+| `newDataVal(path?)` | `(path?: string) => Expr` | same on `newData` |
+| `dataExists(path?)` / `newDataExists(path?)` | `(path?: string) => Expr` | `.exists()` variants |
+| `newDataIs(type)` | `('String' \| 'Number' \| 'Boolean') => Expr` | `newData.isString()` and friends |
+| `dataParentVal(depth, field)` | `(depth: number, field: string) => Expr` | `data.parent()...child("f").val()`, `depth` parent hops |
+| `newDataParentVal(depth, field)` | `(depth: number, field: string) => Expr` | same on `newData` |
+| `newDataParentExists(depth, field)` | `(depth: number, field: string) => Expr` | `newData.parent()...child("f").exists()` |
+| `eq(left, right)` | `(left: Expr, right: CompareValue) => Expr` | `left === right` |
+| `neq(left, right)` | `(left: Expr, right: CompareValue) => Expr` | `left !== right` |
+| `gt(left, n)` | `(left: Expr, n: number) => Expr` | `left > n` |
+| `lte(left, n)` | `(left: Expr, n: number) => Expr` | `left <= n` |
+| `AUTH_UID` | `Segment` constant `{ $: 'auth.uid' }` | an unquoted comparison value or path segment |
+
+`eq`/`neq` format the right side by type: strings are quoted, numbers and booleans are literal, `null` is `null`, and a `{ $: ... }` segment is inserted unquoted (so `eq(newDataVal('host'), AUTH_UID)` produces `newData.child("host").val() === auth.uid`).
+
+## Game primitives
+
+These are first-class exports, pinned by spec tests, and the deployed tic-tac-toe ruleset is built on them.
+
+| Export | Signature | Semantics |
+|---|---|---|
+| `turnGuard(turnField, players, statusField?, playingValue?)` | `(turnField: string, players: Record<string, string>, statusField?: string, playingValue?: string) => Expr` | write guard: for each mark, the stored turn equals the mark AND the stored player field equals `auth.uid`; optionally AND-ed with a status check. Reads `data` (pre-write state) throughout, never `newData`, so a writer cannot hand themselves the turn |
+| `flip(marks)` | `(marks: string[]) => Expr` | validate for the turn field: creation sets the first mark, then circular rotation (X to O to X; supports 2 or more marks) |
+| `winCheckHelper(mark, lines, boardPath?)` | `(mark: string, lines: number[][], boardPath = 'board') => Expr` | validate for a boolean claim field: `true` requires some line of board cells to all equal the mark, `false` requires no such line. The client claims, the rules verify |
+
+## Schema
+
+| Export | Signature | Semantics |
+|---|---|---|
+| `schemaRules(schema, fieldConstraints?)` | `(schema: z.ZodObject, fieldConstraints?: Record<string, Expr[]>) => SchemaRulesResult` | parent `.validate` requires children plus every non-optional key; each field gets a child `.validate` from its Zod type; `fieldConstraints[key]` is AND-merged with the type check |
+
+Supported Zod types: `string`, `number`, `boolean`, `enum`, `literal` (string, number, boolean), unions of supported types, nested objects (recursive), and `.optional()` (unwrapped, excluded from required). Anything else (arrays, dates, records) throws `Unsupported Zod type`, which `check()` surfaces as a `COMPILE_ERROR` finding.
+
+## Assembly
+
+### `defineRtdbRules(definition)`
+
+```ts
+function defineRtdbRules(definition: {
+  paths: Record<string, PathDef> | ((ctx: RulesetContext) => void);
+}): RtdbRulesDocument;
+```
+
+The authoring entry, and the one to reach for first. The returned
+`RtdbRulesDocument` is an inert authored artifact: on the public surface it
+exposes no methods. Pass it to `rtdbRules()` for everything analytical:
+
+| Call | Returns | Notes |
+|---|---|---|
+| `rtdbRules(doc).lint()` | `RuleIssue[]` | parser errors and lint warnings (for example `LOOSE_EQUALITY` for `==`), per node and rule; a compile throw surfaces as one `COMPILE_ERROR` issue |
+| `rtdbRules(doc).simulate(cases)` | `{ passed, failed, unsupported, cases }` | in-process verdicts for a list of `RtdbCase`s |
+| `rtdbRules(doc).explain(oneCase)` | `RtdbExplanation` | the structured account of one case |
+| `rtdbRules(doc).toJSON()` | `{ rules: {...} }` | Firebase rules JSON; raw `'true'`/`'false'` become JSON booleans |
+
+Case conveniences: `auth: 'alice'` normalizes to `{ uid: 'alice', token: {} }`.
+
+There is no `databaseUrl` on the definition — compilation is
+environment-independent. The method-bearing document interface (with
+`compile`/`check`/`simulate` on the document itself) is internal, on
+`pyric/rules/internal/rtdb`.
+
+### `ruleset(input)`
+
+```ts
+function ruleset(
+  input: Record<string, PathDef> | ((ctx: RulesetContext) => void),
+): CompiledRtdbRules;
+```
+
+The raw compiled-tree builder underneath `defineRtdbRules`. Same path inputs,
+no document wrapper. Returns `CompiledRtdbRules` (the `RtdbNode` root), not a
+project-scoped IR.
+
+### `PathDef`
+
+```ts
+interface PathDef {
+  read?: Expr;
+  write?: Expr;
+  validate?: Expr;
+  schema?: z.ZodObject<z.ZodRawShape>;
+  fieldConstraints?: Record<string, Expr[]>;
+  indexOn?: string[];
+  children?: Record<string, PathDef>;
+}
+```
+
+Placement semantics worth knowing:
+
+- Path keys are literal strings with `$wildcards` as segments (`'/games/$gameId'`); every `$segment` becomes a path variable in scope for expression validation.
+- `children` keys are path suffixes (`'/comments/$commentId'`) concatenated onto the parent path.
+- An explicit `validate` wins over the schema-derived parent validate; the schema's per-field validates still apply.
+- `indexOn` on a path that ends in a `$wildcard` is hoisted to the parent container node (`'/posts/$postId'` places `.indexOn` on `posts`). On a non-wildcard path it is silently dropped, so put it on the wildcard path.
+- Every expression is parsed, validated, and linted at build time; findings attach to the compiled tree and surface through `rtdbRules(doc).lint()`.
+
+## Deployment boundary
+
+Constraint helpers compile locally and never contact production. Ship the
+result with `firebase-tools` / Console (`firebase deploy --only database`).
+
+## Exported types
+
+`Expr`, `Segment`, `PathDef`, `RulesetContext`, `SchemaRulesResult`, `RtdbRulesDocument`, `RtdbRulesDefinition`, `RtdbRulesCheckResult`, `RtdbRulesFinding`, `RtdbRulesFindingRule` (`'.read' | '.write' | '.validate' | 'ruleset'`), `RtdbRulesJson`, `RtdbRulesSimulationAuth`, `RtdbRulesSimulationInput`, `CompiledRtdbRules`.
+
+## Boundaries
+
+- `winCheckHelper`'s full expression is verified by parse and substring checks rather than a byte-level snapshot.
+- A `PathDef` whose node cannot be found during assembly is skipped without error.
+- `schemaRules` with nested optional objects is untested territory.
+
+See [rules-tooling.md](../pyric-database-reference-rules-tooling/) for the parser, linter, simulator internals, and tool factories, and the [authoring tutorial](../pyric-database-tutorials-01-author-rtdb-rules-with-constraints/) for the guided path.

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

@@ -0,0 +1,218 @@
+<!DOCTYPE html><html lang="en"> <head><meta charset="UTF-8"><meta name="viewport" content="width=device-width, initial-scale=1.0"><title>RTDB rules tooling · 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/"> 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/" aria-current="true"> 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/"> 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/" aria-current="true"> 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-database/">pyric / database</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">RTDB rules tooling</span> </li> </ol> </nav>  <article class="prose">  <h1 id="rtdb-rules-tooling">RTDB rules tooling</h1>
+<p>The RTDB constraints DSL (<code>defineRtdbRules</code> and the combinators) is public,
+re-exported directly from <code>pyric/rules</code>. The engine underneath it (expression
+parser, validator, linter, compile/simulate/serialize, and replay) is
+engine-internal, on the <code>pyric/rules/internal/rtdb</code> subpath. That subpath isn’t
+covered by the public <code>pyric/rules</code> contract and may change without notice.</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">defineRtdbRules</span><span style="color:#ABB2BF">, </span><span style="color:#E06C75">rtdbRules</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 style="color:#C678DD">import</span><span style="color:#ABB2BF"> {</span></span>
+<span class="line"><span style="color:#E06C75">  compileRtdbRules</span><span style="color:#ABB2BF">,</span></span>
+<span class="line"><span style="color:#E06C75">  simulateRtdbRules</span><span style="color:#ABB2BF">,</span></span>
+<span class="line"><span style="color:#E06C75">  serializeRtdbRules</span><span style="color:#ABB2BF">,</span></span>
+<span class="line"><span style="color:#E06C75">  replay</span><span style="color:#ABB2BF">,</span></span>
+<span class="line"><span style="color:#E06C75">  parseExpression</span><span style="color:#ABB2BF">,</span></span>
+<span class="line"><span style="color:#ABB2BF">} </span><span style="color:#C678DD">from</span><span style="color:#98C379"> 'pyric/rules/internal/rtdb'</span><span style="color:#ABB2BF">;</span></span></code></pre>
+<h2 id="constraints-authoring">Constraints authoring</h2>
+<h3 id="definertdbrulesdefinition-rtdbrulesdocument"><code>defineRtdbRules(definition): RtdbRulesDocument</code></h3>
+<p>Create an in-memory RTDB rules document from path constraints.</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">defineRtdbRules</span><span style="color:#ABB2BF">, </span><span style="color:#E06C75">deny</span><span style="color:#ABB2BF">, </span><span style="color:#E06C75">pathOwnerOnly</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"> rules</span><span style="color:#56B6C2"> =</span><span style="color:#61AFEF"> defineRtdbRules</span><span style="color:#ABB2BF">({</span></span>
+<span class="line"><span style="color:#E06C75">  paths</span><span style="color:#ABB2BF">: {</span></span>
+<span class="line"><span style="color:#98C379">    '/'</span><span style="color:#ABB2BF">: { </span><span style="color:#E06C75">read</span><span style="color:#ABB2BF">: </span><span style="color:#61AFEF">deny</span><span style="color:#ABB2BF">(), </span><span style="color:#E06C75">write</span><span style="color:#ABB2BF">: </span><span style="color:#61AFEF">deny</span><span style="color:#ABB2BF">() },</span></span>
+<span class="line"><span style="color:#98C379">    '/profiles/$uid'</span><span style="color:#ABB2BF">: {</span></span>
+<span class="line"><span style="color:#E06C75">      read</span><span style="color:#ABB2BF">: </span><span style="color:#61AFEF">pathOwnerOnly</span><span style="color:#ABB2BF">(</span><span style="color:#98C379">'$uid'</span><span style="color:#ABB2BF">),</span></span>
+<span class="line"><span style="color:#E06C75">      write</span><span style="color:#ABB2BF">: </span><span style="color:#61AFEF">pathOwnerOnly</span><span style="color:#ABB2BF">(</span><span style="color:#98C379">'$uid'</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:#ABB2BF">});</span></span></code></pre>
+<p><code>definition</code>:</p>
+<pre class="astro-code one-dark-pro" style="background-color:#282c34;color:#abb2bf; overflow-x: auto;" tabindex="0" data-language="ts"><code><span class="line"><span style="color:#C678DD">type</span><span style="color:#E5C07B"> RtdbRulesDefinition</span><span style="color:#56B6C2"> =</span><span style="color:#ABB2BF"> {</span></span>
+<span class="line"><span style="color:#E06C75">  paths</span><span style="color:#ABB2BF">: </span><span style="color:#E5C07B">Record</span><span style="color:#ABB2BF">&#x3C;</span><span style="color:#E5C07B">string</span><span style="color:#ABB2BF">, </span><span style="color:#E5C07B">PathDef</span><span style="color:#ABB2BF">> | ((</span><span style="color:#E06C75;font-style:italic">ctx</span><span style="color:#ABB2BF">: </span><span style="color:#E5C07B">RulesetContext</span><span style="color:#ABB2BF">) </span><span style="color:#C678DD">=></span><span style="color:#E5C07B"> void</span><span style="color:#ABB2BF">);</span></span>
+<span class="line"><span style="color:#ABB2BF">};</span></span></code></pre>
+<p>There is no <code>databaseUrl</code> on the definition. Compilation is
+environment-independent; the database URL is a Firebase project concern when
+you ship with <code>firebase-tools</code>, not part of the authored artifact.</p>
+<h3 id="rtdbrulesdocument"><code>RtdbRulesDocument</code></h3>
+<p>The value <code>defineRtdbRules</code> returns. On the public surface it is an inert
+authored artifact: the type exposes no methods. You hand it to <code>rtdbRules()</code>,
+which is the one analysis 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">rtdbRules</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"> ruleset</span><span style="color:#56B6C2"> =</span><span style="color:#61AFEF"> rtdbRules</span><span style="color:#ABB2BF">(</span><span style="color:#E06C75">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:#E5C07B"> ruleset</span><span style="color:#ABB2BF">.</span><span style="color:#61AFEF">lint</span><span style="color:#ABB2BF">();   </span><span style="color:#7F848E;font-style:italic">// RuleIssue[]</span></span>
+<span class="line"><span style="color:#C678DD">const</span><span style="color:#E5C07B"> summary</span><span style="color:#56B6C2"> =</span><span style="color:#E5C07B"> ruleset</span><span style="color:#ABB2BF">.</span><span style="color:#61AFEF">simulate</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">'owner reads their profile'</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">    operation</span><span style="color:#ABB2BF">: </span><span style="color:#98C379">'read'</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">'/profiles/alice'</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">'alice'</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:#C678DD">const</span><span style="color:#E5C07B"> json</span><span style="color:#56B6C2"> =</span><span style="color:#E5C07B"> ruleset</span><span style="color:#ABB2BF">.</span><span style="color:#61AFEF">toJSON</span><span style="color:#ABB2BF">();   </span><span style="color:#7F848E;font-style:italic">// { rules: {...} }</span></span></code></pre>
+<p><code>lint()</code> folds the document’s parser and linter findings into one
+<code>RuleIssue[]</code> list; a compile failure arrives as a <code>COMPILE_ERROR</code> issue
+rather than a throw. <code>simulate(cases)</code> takes <code>RtdbCase[]</code> and returns
+<code>{ passed, failed, unsupported, cases }</code>. <code>toJSON()</code> compiles to Firebase
+RTDB rules JSON.</p>
+<p>The method-bearing document interface (<code>toJSON</code> / <code>compile</code> / <code>check</code> /
+<code>simulate</code> on the document itself) is internal. Engine consumers reach it via
+<code>pyric/rules/internal/rtdb</code>, which exports it under the same
+<code>RtdbRulesDocument</code> name; it is not covered by the public contract.</p>
+<p><code>RtdbRulesSimulationInput</code> is the input shape of the internal document
+<code>simulate</code> method (the public <code>rtdbRules().simulate</code> takes <code>RtdbCase[]</code>
+instead). It accepts the existing simulation fields plus these authoring
+conveniences:</p>
+<pre class="astro-code one-dark-pro" style="background-color:#282c34;color:#abb2bf; overflow-x: auto;" tabindex="0" data-language="ts"><code><span class="line"><span style="color:#C678DD">type</span><span style="color:#E5C07B"> RtdbRulesSimulationInput</span><span style="color:#56B6C2"> =</span><span style="color:#ABB2BF"> {</span></span>
+<span class="line"><span style="color:#E06C75">  operation</span><span style="color:#ABB2BF">: </span><span style="color:#98C379">'read'</span><span style="color:#ABB2BF"> | </span><span style="color:#98C379">'write'</span><span style="color:#ABB2BF"> | </span><span style="color:#98C379">'validate'</span><span style="color:#ABB2BF">;</span></span>
+<span class="line"><span style="color:#E06C75">  path</span><span style="color:#ABB2BF">: </span><span style="color:#E5C07B">string</span><span style="color:#ABB2BF">;</span></span>
+<span class="line"><span style="color:#E06C75">  auth</span><span style="color:#C678DD">?</span><span style="color:#ABB2BF">: </span><span style="color:#E5C07B">string</span><span style="color:#ABB2BF"> | { </span><span style="color:#E06C75">uid</span><span style="color:#ABB2BF">: </span><span style="color:#E5C07B">string</span><span style="color:#ABB2BF">; </span><span style="color:#E06C75">token</span><span style="color:#C678DD">?</span><span style="color:#ABB2BF">: </span><span style="color:#E5C07B">Record</span><span style="color:#ABB2BF">&#x3C;</span><span style="color:#E5C07B">string</span><span style="color:#ABB2BF">, </span><span style="color:#E5C07B">unknown</span><span style="color:#ABB2BF">> } | </span><span style="color:#E5C07B">null</span><span style="color:#ABB2BF">;</span></span>
+<span class="line"><span style="color:#E06C75">  data</span><span style="color:#C678DD">?</span><span style="color:#ABB2BF">: </span><span style="color:#E5C07B">Record</span><span style="color:#ABB2BF">&#x3C;</span><span style="color:#E5C07B">string</span><span style="color:#ABB2BF">, </span><span style="color:#E5C07B">unknown</span><span style="color:#ABB2BF">>;</span></span>
+<span class="line"><span style="color:#E06C75">  mockData</span><span style="color:#C678DD">?</span><span style="color:#ABB2BF">: </span><span style="color:#E5C07B">Record</span><span style="color:#ABB2BF">&#x3C;</span><span style="color:#E5C07B">string</span><span style="color:#ABB2BF">, </span><span style="color:#E5C07B">unknown</span><span style="color:#ABB2BF">>;</span></span>
+<span class="line"><span style="color:#E06C75">  newData</span><span style="color:#C678DD">?</span><span style="color:#ABB2BF">: </span><span style="color:#E5C07B">unknown</span><span style="color:#ABB2BF">;</span></span>
+<span class="line"><span style="color:#ABB2BF">};</span></span></code></pre>
+<p><code>auth: 'alice'</code> becomes <code>{ uid: 'alice', token: {} }</code>. <code>data</code> is an alias for
+<code>mockData</code>; if both are supplied, <code>mockData</code> is used.</p>
+<p><code>RtdbRulesCheckResult</code>:</p>
+<pre class="astro-code one-dark-pro" style="background-color:#282c34;color:#abb2bf; overflow-x: auto;" tabindex="0" data-language="ts"><code><span class="line"><span style="color:#C678DD">type</span><span style="color:#E5C07B"> RtdbRulesCheckResult</span><span style="color:#56B6C2"> =</span><span style="color:#ABB2BF"> {</span></span>
+<span class="line"><span style="color:#E06C75">  ok</span><span style="color:#ABB2BF">: </span><span style="color:#E5C07B">boolean</span><span style="color:#ABB2BF">;</span></span>
+<span class="line"><span style="color:#E06C75">  errors</span><span style="color:#ABB2BF">: </span><span style="color:#E5C07B">RtdbRulesFinding</span><span style="color:#ABB2BF">[];</span></span>
+<span class="line"><span style="color:#E06C75">  warnings</span><span style="color:#ABB2BF">: </span><span style="color:#E5C07B">RtdbRulesFinding</span><span style="color:#ABB2BF">[];</span></span>
+<span class="line"><span style="color:#ABB2BF">};</span></span></code></pre>
+<p>Compile failures return an error finding with code <code>COMPILE_ERROR</code>.</p>
+<h3 id="generating-databaserulesjson">Generating <code>database.rules.json</code></h3>
+<p><code>rtdbRules(rules).toJSON()</code> compiles a constraints document to the exact
+<code>{ rules: {...} }</code> shape Firebase expects in <code>database.rules.json</code>. Everything
+that writes the file — the CLI, the MCP library tool, and this helper — runs
+the same compilation and never recompiles the rules a second time.</p>
+<p>For scripts running in Node, <code>pyric/rules/internal/node</code> exports a helper that
+writes the file directly:</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">writeRtdbRulesFile</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 style="color:#C678DD">import</span><span style="color:#ABB2BF"> { </span><span style="color:#E06C75">rules</span><span style="color:#ABB2BF"> } </span><span style="color:#C678DD">from</span><span style="color:#98C379"> './database.rules.js'</span><span style="color:#ABB2BF">;</span></span>
+<span class="line"></span>
+<span class="line"><span style="color:#C678DD">const</span><span style="color:#E5C07B"> path</span><span style="color:#56B6C2"> =</span><span style="color:#C678DD"> await</span><span style="color:#61AFEF"> writeRtdbRulesFile</span><span style="color:#ABB2BF">(</span><span style="color:#E06C75">rules</span><span style="color:#ABB2BF">, </span><span style="color:#98C379">'database.rules.json'</span><span style="color:#ABB2BF">);</span></span></code></pre>
+<h4 id="writertdbrulesfiledoc-path-promisestring"><code>writeRtdbRulesFile(doc, path): Promise&#x3C;string></code></h4>
+<p>Compiles <code>doc</code> and writes the rules JSON as pretty-printed output to <code>path</code>,
+creating parent directories as needed, and returns the resolved absolute path
+written. It is Node-only (imports <code>node:fs</code>), so it lives on the internal
+<code>pyric/rules/internal/node</code> entry rather than alongside the compilation
+itself: <code>rtdbRules(rules).toJSON()</code>, from the public <code>pyric/rules</code>, never
+pulls in Node builtins.</p>
+<h4 id="cli">CLI</h4>
+<pre class="astro-code one-dark-pro" style="background-color:#282c34;color:#abb2bf; overflow-x: auto;" tabindex="0" data-language="sh"><code><span class="line"><span style="color:#61AFEF">pyric</span><span style="color:#98C379"> database</span><span style="color:#98C379"> rules</span><span style="color:#98C379"> generate</span><span style="color:#ABB2BF"> [--config &#x3C;</span><span style="color:#98C379">pat</span><span style="color:#ABB2BF">h></span><span style="color:#98C379">]</span><span style="color:#ABB2BF"> [--out &#x3C;</span><span style="color:#98C379">pat</span><span style="color:#ABB2BF">h></span><span style="color:#98C379">]</span></span></code></pre>
+<p>Loads a constraints module (default <code>database.rules.ts</code>, or the <code>--config</code>
+path), looks for a named <code>rules</code> export or a default export produced by
+<code>defineRtdbRules(...)</code>, compiles it to rules JSON, and writes it to <code>--out</code>
+(default: the <code>database.rules</code> path from <code>firebase.json</code>, or
+<code>database.rules.json</code>). This is a local artifact step only — inspect, diff,
+and commit the file, then ship with <code>firebase-tools</code> / Console.</p>
+<h4 id="mcp--library">MCP / library</h4>
+<p>The <code>rtdb_generate_rules</code> tool (library; not on the default bridge) takes the
+same <code>configPath</code> (and an optional <code>cwd</code>), loads the module the same way, and
+returns the compiled <code>{ rulesJson }</code> without contacting a Firebase project.</p>
+<h3 id="verifying-captured-sessions">Verifying captured sessions</h3>
+<p>Constraints documents can be passed directly to <code>@pyric/cli/verify</code> as
+candidate RTDB rules:</p>
+<pre class="astro-code one-dark-pro" style="background-color:#282c34;color:#abb2bf; overflow-x: auto;" tabindex="0" data-language="ts"><code><span class="line"><span style="color:#C678DD">import</span><span style="color:#ABB2BF"> { </span><span style="color:#E06C75">verifyFixture</span><span style="color:#ABB2BF"> } </span><span style="color:#C678DD">from</span><span style="color:#98C379"> '@pyric/cli/verify'</span><span style="color:#ABB2BF">;</span></span>
+<span class="line"><span style="color:#C678DD">import</span><span style="color:#ABB2BF"> { </span><span style="color:#E06C75">rules</span><span style="color:#ABB2BF"> } </span><span style="color:#C678DD">from</span><span style="color:#98C379"> './database.rules.js'</span><span style="color:#ABB2BF">;</span></span>
+<span class="line"></span>
+<span class="line"><span style="color:#C678DD">const</span><span style="color:#E5C07B"> fixture</span><span style="color:#56B6C2"> =</span><span style="color:#E5C07B"> JSON</span><span style="color:#ABB2BF">.</span><span style="color:#61AFEF">parse</span><span style="color:#ABB2BF">(</span><span style="color:#C678DD">await</span><span style="color:#E5C07B"> Bun</span><span style="color:#ABB2BF">.</span><span style="color:#61AFEF">file</span><span style="color:#ABB2BF">(</span><span style="color:#98C379">'.pyric/last-session.json'</span><span style="color:#ABB2BF">).</span><span style="color:#61AFEF">text</span><span style="color:#ABB2BF">());</span></span>
+<span class="line"></span>
+<span class="line"><span style="color:#C678DD">const</span><span style="color:#E5C07B"> result</span><span style="color:#56B6C2"> =</span><span style="color:#C678DD"> await</span><span style="color:#61AFEF"> verifyFixture</span><span style="color:#ABB2BF">(</span><span style="color:#E06C75">fixture</span><span style="color:#ABB2BF">, {</span></span>
+<span class="line"><span style="color:#E06C75">  engines</span><span style="color:#ABB2BF">: [</span><span style="color:#98C379">'sandbox'</span><span style="color:#ABB2BF">],</span></span>
+<span class="line"><span style="color:#E06C75">  rules</span><span style="color:#ABB2BF">: { </span><span style="color:#E06C75">rtdb</span><span style="color:#ABB2BF">: </span><span style="color:#E06C75">rules</span><span style="color:#ABB2BF"> },</span></span>
+<span class="line"><span style="color:#ABB2BF">});</span></span></code></pre>
+<p>For CLI verification, generate JSON first and pass it as the RTDB rules file:</p>
+<pre class="astro-code one-dark-pro" style="background-color:#282c34;color:#abb2bf; overflow-x: auto;" tabindex="0" data-language="ts"><code><span class="line"><span style="color:#C678DD">await</span><span style="color:#E5C07B"> Bun</span><span style="color:#ABB2BF">.</span><span style="color:#61AFEF">write</span><span style="color:#ABB2BF">(</span><span style="color:#98C379">'database.rules.json'</span><span style="color:#ABB2BF">, </span><span style="color:#E5C07B">JSON</span><span style="color:#ABB2BF">.</span><span style="color:#61AFEF">stringify</span><span style="color:#ABB2BF">(</span><span style="color:#61AFEF">rtdbRules</span><span style="color:#ABB2BF">(</span><span style="color:#E06C75">rules</span><span style="color:#ABB2BF">).</span><span style="color:#61AFEF">toJSON</span><span style="color:#ABB2BF">(), </span><span style="color:#D19A66">null</span><span style="color:#ABB2BF">, </span><span style="color:#D19A66">2</span><span style="color:#ABB2BF">));</span></span></code></pre>
+<pre class="astro-code one-dark-pro" style="background-color:#282c34;color:#abb2bf; overflow-x: auto;" tabindex="0" data-language="sh"><code><span class="line"><span style="color:#61AFEF">pyric</span><span style="color:#98C379"> verify</span><span style="color:#D19A66"> --service</span><span style="color:#98C379"> rtdb</span><span style="color:#D19A66"> --rules</span><span style="color:#98C379"> rtdb=database.rules.json</span></span></code></pre>
+<p>Verification lives in <code>@pyric/cli/verify</code> because constraints are an authoring
+surface and captured-session replay is local tooling around an app session.
+The Firebase Rules Test API engine is Firestore-only; RTDB constraints verify by
+compiling to RTDB rules JSON and replaying captured RTDB commits locally.</p>
+<h2 id="compiled-rules-internal">Compiled rules (internal)</h2>
+<h3 id="compilertdbrulesrulesjson-compiledrtdbrules"><code>compileRtdbRules(rulesJson): CompiledRtdbRules</code></h3>
+<p>Convert Firebase RTDB rules JSON into the compiled tree the simulator uses
+(<code>CompiledRtdbRules</code> is the <code>RtdbNode</code> root).</p>
+<h3 id="serializertdbrulescompiled--rules-recordstring-unknown"><code>serializeRtdbRules(compiled): { rules: Record&#x3C;string, unknown> }</code></h3>
+<p>Convert a compiled tree back to Firebase RTDB rules JSON.</p>
+<h3 id="simulatertdbrulescompiled-input-simulateresult"><code>simulateRtdbRules(compiled, input): SimulateResult</code></h3>
+<p>Evaluate one operation against a compiled rules tree.</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"> compiled</span><span style="color:#56B6C2"> =</span><span style="color:#61AFEF"> compileRtdbRules</span><span style="color:#ABB2BF">({</span></span>
+<span class="line"><span style="color:#E06C75">  rules</span><span style="color:#ABB2BF">: {</span></span>
+<span class="line"><span style="color:#E06C75">    profiles</span><span style="color:#ABB2BF">: {</span></span>
+<span class="line"><span style="color:#E06C75">      $uid</span><span style="color:#ABB2BF">: {</span></span>
+<span class="line"><span style="color:#98C379">        '.read'</span><span style="color:#ABB2BF">: </span><span style="color:#98C379">'auth.uid === $uid'</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:#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"> result</span><span style="color:#56B6C2"> =</span><span style="color:#61AFEF"> simulateRtdbRules</span><span style="color:#ABB2BF">(</span><span style="color:#E06C75">compiled</span><span style="color:#ABB2BF">, {</span></span>
+<span class="line"><span style="color:#E06C75">  operation</span><span style="color:#ABB2BF">: </span><span style="color:#98C379">'read'</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">'/profiles/alice'</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 style="color:#E06C75">token</span><span style="color:#ABB2BF">: {} },</span></span>
+<span class="line"><span style="color:#E06C75">  mockData</span><span style="color:#ABB2BF">: {},</span></span>
+<span class="line"><span style="color:#ABB2BF">});</span></span></code></pre>
+<p><code>SimulationInput</code>:</p>
+<pre class="astro-code one-dark-pro" style="background-color:#282c34;color:#abb2bf; overflow-x: auto;" tabindex="0" data-language="ts"><code><span class="line"><span style="color:#C678DD">type</span><span style="color:#E5C07B"> SimulationInput</span><span style="color:#56B6C2"> =</span><span style="color:#ABB2BF"> {</span></span>
+<span class="line"><span style="color:#E06C75">  operation</span><span style="color:#ABB2BF">: </span><span style="color:#98C379">'read'</span><span style="color:#ABB2BF"> | </span><span style="color:#98C379">'write'</span><span style="color:#ABB2BF"> | </span><span style="color:#98C379">'validate'</span><span style="color:#ABB2BF">;</span></span>
+<span class="line"><span style="color:#E06C75">  path</span><span style="color:#ABB2BF">: </span><span style="color:#E5C07B">string</span><span style="color:#ABB2BF">;</span></span>
+<span class="line"><span style="color:#E06C75">  auth</span><span style="color:#ABB2BF">: { </span><span style="color:#E06C75">uid</span><span style="color:#ABB2BF">: </span><span style="color:#E5C07B">string</span><span style="color:#ABB2BF">; </span><span style="color:#E06C75">token</span><span style="color:#ABB2BF">: </span><span style="color:#E5C07B">Record</span><span style="color:#ABB2BF">&#x3C;</span><span style="color:#E5C07B">string</span><span style="color:#ABB2BF">, </span><span style="color:#E5C07B">unknown</span><span style="color:#ABB2BF">> } | </span><span style="color:#E5C07B">null</span><span style="color:#ABB2BF">;</span></span>
+<span class="line"><span style="color:#E06C75">  mockData</span><span style="color:#ABB2BF">: </span><span style="color:#E5C07B">Record</span><span style="color:#ABB2BF">&#x3C;</span><span style="color:#E5C07B">string</span><span style="color:#ABB2BF">, </span><span style="color:#E5C07B">unknown</span><span style="color:#ABB2BF">>;</span></span>
+<span class="line"><span style="color:#E06C75">  newData</span><span style="color:#C678DD">?</span><span style="color:#ABB2BF">: </span><span style="color:#E5C07B">unknown</span><span style="color:#ABB2BF">;</span></span>
+<span class="line"><span style="color:#ABB2BF">};</span></span></code></pre>
+<h3 id="replay--expression-helpers"><code>replay</code> / expression helpers</h3>
+<p>Also on <code>pyric/rules/internal/rtdb</code>:</p>
+<ul>
+<li><code>replay</code> — replay captured RTDB commits against candidate rules</li>
+<li><code>parseExpression</code> / <code>validateExpression</code> / <code>lintExpression</code> /
+<code>buildRuleExpression</code> — expression-level parse, validate, and lint</li>
+</ul>
+<h2 id="production-deployment">Production deployment</h2>
+<p>The rules engine performs no production reads or writes. Generate and inspect
+rules locally (<code>pyric database rules generate</code>, <code>rtdbRules(doc).toJSON()</code>), then
+ship with <code>firebase-tools</code> / Console (<code>firebase deploy --only database</code>).
+Production operations never live on the Firebase-shaped <code>pyric/database</code> mirror
+or this internal engine seam.</p>
+<h2 id="constraint-helpers">Constraint helpers</h2>
+<p>The RTDB rule constraint helpers are re-exported directly from <code>pyric/rules</code>,
+the public front door. The previous dedicated subpaths (<code>pyric/rules/rtdb</code>,
+<code>pyric/rules/rtdb/constraints</code>, <code>pyric/rules/rtdb-constraints</code>) no longer
+exist; there is one place to import the DSL from now.</p>
+<p>The complete builder catalog, with the exact expression each helper
+produces, lives in <a href="../pyric-database-reference-constraints/">constraints.md</a>. At a glance the
+groups are:</p>
+<ul>
+<li>boolean composition: <code>expr</code>, <code>all</code>, <code>any</code>, <code>not</code>, <code>deny</code>, <code>always</code>, <code>allow</code></li>
+<li>auth, ownership, and state atoms: <code>authenticated</code>, <code>ownPath</code>, <code>ownField</code>,
+<code>isNew</code>, <code>immutable</code>, <code>immutableSelf</code>, <code>rootExists</code>, <code>rootEquals</code></li>
+<li>schema predicates: <code>hasChildren</code>, <code>hasChild</code>, <code>fieldIsString</code>,
+<code>fieldIsNumber</code>, <code>fieldIsBoolean</code>, <code>fieldEnum</code></li>
+<li>data navigation and comparison: <code>dataVal</code>, <code>newDataVal</code>, <code>dataExists</code>,
+<code>newDataExists</code>, <code>newDataIs</code>, <code>dataParentVal</code>, <code>newDataParentVal</code>,
+<code>newDataParentExists</code>, <code>eq</code>, <code>neq</code>, <code>gt</code>, <code>lte</code>, and the <code>AUTH_UID</code>
+segment constant</li>
+<li>policy helpers: <code>pathOwnerOnly</code>, <code>fieldOwnerOnly</code>, <code>ownerOrNew</code>,
+<code>hasRole</code>, <code>isMember</code>, <code>required</code>, <code>transition</code></li>
+<li>game primitives: <code>turnGuard</code>, <code>flip</code>, <code>winCheckHelper</code></li>
+<li>assembly: <code>defineRtdbRules</code>, <code>ruleset</code>, <code>schemaRules</code></li>
+</ul>
+<h3 id="pathdef"><code>PathDef</code></h3>
+<pre class="astro-code one-dark-pro" style="background-color:#282c34;color:#abb2bf; overflow-x: auto;" tabindex="0" data-language="ts"><code><span class="line"><span style="color:#C678DD">interface</span><span style="color:#E5C07B"> PathDef</span><span style="color:#ABB2BF"> {</span></span>
+<span class="line"><span style="color:#E06C75">  read</span><span style="color:#C678DD">?</span><span style="color:#ABB2BF">: </span><span style="color:#E5C07B">Expr</span><span style="color:#ABB2BF">;</span></span>
+<span class="line"><span style="color:#E06C75">  write</span><span style="color:#C678DD">?</span><span style="color:#ABB2BF">: </span><span style="color:#E5C07B">Expr</span><span style="color:#ABB2BF">;</span></span>
+<span class="line"><span style="color:#E06C75">  validate</span><span style="color:#C678DD">?</span><span style="color:#ABB2BF">: </span><span style="color:#E5C07B">Expr</span><span style="color:#ABB2BF">;</span></span>
+<span class="line"><span style="color:#E06C75">  schema</span><span style="color:#C678DD">?</span><span style="color:#ABB2BF">: </span><span style="color:#E5C07B">z</span><span style="color:#ABB2BF">.</span><span style="color:#E5C07B">ZodObject</span><span style="color:#ABB2BF">&#x3C;</span><span style="color:#E5C07B">any</span><span style="color:#ABB2BF">>;</span></span>
+<span class="line"><span style="color:#E06C75">  fieldConstraints</span><span style="color:#C678DD">?</span><span style="color:#ABB2BF">: </span><span style="color:#E5C07B">Record</span><span style="color:#ABB2BF">&#x3C;</span><span style="color:#E5C07B">string</span><span style="color:#ABB2BF">, </span><span style="color:#E5C07B">Expr</span><span style="color:#ABB2BF">[]>;</span></span>
+<span class="line"><span style="color:#E06C75">  indexOn</span><span style="color:#C678DD">?</span><span style="color:#ABB2BF">: </span><span style="color:#E5C07B">string</span><span style="color:#ABB2BF">[];</span></span>
+<span class="line"><span style="color:#E06C75">  children</span><span style="color:#C678DD">?</span><span style="color:#ABB2BF">: </span><span style="color:#E5C07B">Record</span><span style="color:#ABB2BF">&#x3C;</span><span style="color:#E5C07B">string</span><span style="color:#ABB2BF">, </span><span style="color:#E5C07B">PathDef</span><span style="color:#ABB2BF">>;</span></span>
+<span class="line"><span style="color:#ABB2BF">}</span></span></code></pre>
+<p><code>schema</code> supports Zod object fields composed from strings, numbers, booleans,
+enums, literals, unions of supported types, nested objects, and optional fields.
+Unsupported Zod types throw during compilation.</p>
+<p>The game primitives (<code>turnGuard</code>, <code>flip</code>, <code>winCheckHelper</code>) are
+first-class exports with spec-pinned output; the deployed tic-tac-toe
+ruleset is built on them. Their semantics are in
+<a href="../pyric-database-reference-constraints/">constraints.md</a>.</p>  </article> </main> <aside class="doc-toc" aria-label="On this page"> <h2 class="doc-toc-heading">On this page</h2> <ul> <li data-depth="2"> <a href="#constraints-authoring">Constraints authoring</a> </li><li data-depth="3"> <a href="#definertdbrulesdefinition-rtdbrulesdocument">defineRtdbRules(definition): RtdbRulesDocument</a> </li><li data-depth="3"> <a href="#rtdbrulesdocument">RtdbRulesDocument</a> </li><li data-depth="3"> <a href="#generating-databaserulesjson">Generating database.rules.json</a> </li><li data-depth="3"> <a href="#verifying-captured-sessions">Verifying captured sessions</a> </li><li data-depth="2"> <a href="#compiled-rules-internal">Compiled rules (internal)</a> </li><li data-depth="3"> <a href="#compilertdbrulesrulesjson-compiledrtdbrules">compileRtdbRules(rulesJson): CompiledRtdbRules</a> </li><li data-depth="3"> <a href="#serializertdbrulescompiled--rules-recordstring-unknown">serializeRtdbRules(compiled): { rules: Record&lt;string, unknown&gt; }</a> </li><li data-depth="3"> <a href="#simulatertdbrulescompiled-input-simulateresult">simulateRtdbRules(compiled, input): SimulateResult</a> </li><li data-depth="3"> <a href="#replay--expression-helpers">replay / expression helpers</a> </li><li data-depth="2"> <a href="#production-deployment">Production deployment</a> </li><li data-depth="2"> <a href="#constraint-helpers">Constraint helpers</a> </li><li data-depth="3"> <a href="#pathdef">PathDef</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>