@pyric/cli 0.1.0-alpha.25 → 0.1.0-alpha.26

package/dist/serve/site-ui/docs/pyric-rules-reference-api.md

@@ -2,6 +2,51 @@
 
 ## Classes
 
+<a id="rtdbexpressionsyntaxerror"></a>
+
+### RtdbExpressionSyntaxError
+
+Why [canonicalRtdbExpression](#canonicalrtdbexpression) could not read its input.
+
+#### Extends
+
+- `Error`
+
+#### Constructors
+
+<a id="constructor"></a>
+
+##### Constructor
+
+```ts
+new RtdbExpressionSyntaxError(raw: string, message: string): RtdbExpressionSyntaxError;
+```
+
+###### Parameters
+
+| Parameter | Type |
+| :------ | :------ |
+| `raw` | `string` |
+| `message` | `string` |
+
+###### Returns
+
+[`RtdbExpressionSyntaxError`](#rtdbexpressionsyntaxerror)
+
+###### Overrides
+
+```ts
+Error.constructor
+```
+
+#### Properties
+
+| Property | Modifier | Type |
+| :------ | :------ | :------ |
+| <a id="raw"></a> `raw` | `readonly` | `string` |
+
+***
+
 <a id="rulesassertionerror"></a>
 
 ### RulesAssertionError
@@ -17,7 +62,7 @@ without extra wiring.
 
 #### Constructors
 
-<a id="constructor"></a>
+<a id="constructor-1"></a>
 
 ##### Constructor
 
@@ -57,7 +102,7 @@ caller can surface them without re-parsing.
 
 #### Constructors
 
-<a id="constructor-1"></a>
+<a id="constructor-2"></a>
 
 ##### Constructor
 
@@ -106,7 +151,7 @@ fail on a known simulator gap.
 
 #### Constructors
 
-<a id="constructor-2"></a>
+<a id="constructor-3"></a>
 
 ##### Constructor
 
@@ -158,6 +203,18 @@ The outcome of running one Firestore case through `simulate`. Never a
 
 ***
 
+<a id="diffrtdbrulesoptions"></a>
+
+### DiffRtdbRulesOptions
+
+#### Properties
+
+| Property | Type | Description |
+| :------ | :------ | :------ |
+| <a id="ignoreequivalent"></a> `ignoreEquivalent?` | `boolean` | Treat two `.read`, `.write` or `.validate` expressions as the same rule when their [canonicalRtdbExpression](#canonicalrtdbexpression) texts are equal: spellings that cannot change any decision, such as `===` for `==` or `child('a/' + $id)` for `child('a').child($id)`. A changed entry still reports both expressions as written. An expression that does not parse is compared as written. Default `false`: expressions compare as text. |
+
+***
+
 <a id="evaluatedruleinfo"></a>
 
 ### EvaluatedRuleInfo
@@ -664,6 +721,26 @@ a file system.
 
 ***
 
+<a id="rtdbrulechange"></a>
+
+### RtdbRuleChange
+
+One rule expression that differs. `deployed` is absent for `added` and
+`local` is absent for `removed`: the change is what deploying the local
+ruleset would do to the deployed one.
+
+#### Properties
+
+| Property | Type |
+| :------ | :------ |
+| <a id="change"></a> `change` | `"added"` \| `"removed"` \| `"changed"` |
+| <a id="deployed"></a> `deployed?` | `string` |
+| <a id="kind-3"></a> `kind` | [`RtdbRuleKind`](#rtdbrulekind) |
+| <a id="local"></a> `local?` | `string` |
+| <a id="path-2"></a> `path` | `string` |
+
+***
+
 <a id="rtdbrulecoverage"></a>
 
 ### RtdbRuleCoverage
@@ -678,9 +755,9 @@ a file system.
 | <a id="evaluated"></a> `evaluated` | `number` | Evaluations that produced a verdict: `allow + deny + error`. |
 | <a id="expression-1"></a> `expression` | `string` | The rule expression, or the declared index list for `indexOn`. |
 | <a id="file-3"></a> `file?` | `string` | The rules file holding the node, when the summary covers several files. |
-| <a id="kind-3"></a> `kind` | [`RtdbCoverageKind`](#rtdbcoveragekind) | - |
+| <a id="kind-4"></a> `kind` | [`RtdbCoverageKind`](#rtdbcoveragekind) | - |
 | <a id="line-2"></a> `line?` | `number` | 1-indexed line in the rules file, when a line lookup was supplied. |
-| <a id="path-2"></a> `path` | `string` | The rule node's path, such as `/rooms/$roomId`. |
+| <a id="path-3"></a> `path` | `string` | The rule node's path, such as `/rooms/$roomId`. |
 | <a id="status"></a> `status` | [`RtdbCoverageStatus`](#rtdbcoveragestatus) | - |
 | <a id="unsupported-5"></a> `unsupported` | `number` | - |
 
@@ -926,7 +1003,7 @@ throws when `firebase.json` deploys none to the default instance.
 | :------ | :------ |
 | <a id="code"></a> `code` | `string` |
 | <a id="message"></a> `message` | `string` |
-| <a id="path-3"></a> `path` | `string` |
+| <a id="path-4"></a> `path` | `string` |
 | <a id="rule-2"></a> `rule` | [`RtdbRulesFindingRule`](#rtdbrulesfindingrule-1) |
 
 ***
@@ -993,7 +1070,7 @@ returns an empty `trace` and surfaces the wire text on `TestResult.notes`.
 | <a id="line-4"></a> `line?` | `number` | 1-indexed source line, when known. |
 | <a id="message-2"></a> `message` | `string` | Human-readable description. |
 | <a id="origin"></a> `origin` | [`RuleIssueOrigin`](#ruleissueorigin-1) | - |
-| <a id="path-4"></a> `path?` | `string` | Rules path the issue applies to, when known (e.g. `'/users/{uid}'`). |
+| <a id="path-5"></a> `path?` | `string` | Rules path the issue applies to, when known (e.g. `'/users/{uid}'`). |
 | <a id="rule-3"></a> `rule?` | `".read"` \| `".write"` \| `".validate"` | The Realtime Database rule at `path` the issue applies to. Absent for Firestore issues and for an RTDB issue about the whole ruleset. |
 | <a id="severity"></a> `severity` | [`RuleIssueSeverity`](#ruleissueseverity-1) | - |
 
@@ -1009,7 +1086,7 @@ Context passed to the callback overload of ruleset().
 
 | Property | Type |
 | :------ | :------ |
-| <a id="path-5"></a> `path` | (`path`: `string`, `def`: [`PathDef`](#pathdef)) => `void` |
+| <a id="path-6"></a> `path` | (`path`: `string`, `def`: [`PathDef`](#pathdef)) => `void` |
 
 ***
 
@@ -1035,7 +1112,7 @@ expression the request was evaluating when the budget ran out.
 | Property | Type |
 | :------ | :------ |
 | <a id="column-2"></a> `column?` | `number` |
-| <a id="kind-4"></a> `kind` | `"expressions"` \| `"document-lookups"` |
+| <a id="kind-5"></a> `kind` | `"expressions"` \| `"document-lookups"` |
 | <a id="limit"></a> `limit` | `number` |
 | <a id="line-5"></a> `line?` | `number` |
 | <a id="message-3"></a> `message` | `string` |
@@ -1208,6 +1285,16 @@ type RtdbRuleEvaluation = z.infer<typeof RtdbRuleEvaluationSchema>;
 
 ***
 
+<a id="rtdbrulekind"></a>
+
+### RtdbRuleKind
+
+```ts
+type RtdbRuleKind = ".read" | ".write" | ".validate" | ".indexOn";
+```
+
+***
+
 <a id="rtdbrulesfindingrule-1"></a>
 
 ### RtdbRulesFindingRule
@@ -2363,6 +2450,31 @@ A `bytes` value.
 
 ***
 
+<a id="canonicalrtdbexpression"></a>
+
+### canonicalRtdbExpression()
+
+```ts
+function canonicalRtdbExpression(raw: string): string;
+```
+
+Canonical text of an RTDB rule expression: two expressions with equal
+canonical texts evaluate identically for every request. Deterministic and
+idempotent. Throws [RtdbExpressionSyntaxError](#rtdbexpressionsyntaxerror) for text that is not a
+rule expression.
+
+#### Parameters
+
+| Parameter | Type |
+| :------ | :------ |
+| `raw` | `string` |
+
+#### Returns
+
+`string`
+
+***
+
 <a id="definertdbrules"></a>
 
 ### defineRtdbRules()
@@ -2383,6 +2495,33 @@ function defineRtdbRules(definition: RtdbRulesDefinition): RtdbRulesDocument;
 
 ***
 
+<a id="diffrtdbrules"></a>
+
+### diffRtdbRules()
+
+```ts
+function diffRtdbRules(
+   deployed: Record<string, unknown>,
+   local: Record<string, unknown>,
+   options?: DiffRtdbRulesOptions): RtdbRuleChange[];
+```
+
+Node-level diff of two `rules` trees, ordered by path then rule kind.
+
+#### Parameters
+
+| Parameter | Type |
+| :------ | :------ |
+| `deployed` | `Record`\<`string`, `unknown`\> |
+| `local` | `Record`\<`string`, `unknown`\> |
+| `options?` | [`DiffRtdbRulesOptions`](#diffrtdbrulesoptions) |
+
+#### Returns
+
+[`RtdbRuleChange`](#rtdbrulechange)[]
+
+***
+
 <a id="duration"></a>
 
 ### duration()

package/dist/serve/site-ui/docs/secure/rtdb-rules-in-typescript/index.html

@@ -68,6 +68,61 @@ html{scrollbar-gutter:stable}
 <li><code>pyric database rules validate database.rules.json</code> prints the error findings only. It exits <code>2</code> when there is one or when the file is not rules JSON, <code>1</code> when the file can’t be read, and <code>0</code> otherwise.</li>
 <li><code>pyric rules simulate --service database --rules-file database.rules.json --operation read --path /notes/n1</code> evaluates one request against the file.</li>
 </ul>
+<h2 id="compare-compiled-rules-with-the-rules-you-wrote-by-hand">Compare compiled rules with the rules you wrote by hand</h2>
+<p>When you move hand-written rules to TypeScript, the compiled JSON spells the same rules differently: <code>auth != null</code> where you wrote <code>auth.uid !== null</code>, <code>child('a').child($id)</code> where you wrote <code>child('a/' + $id)</code>. <code>diffRtdbRules</code> with <code>ignoreEquivalent</code> reports only the rules that can decide differently:</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">readFileSync</span><span style="color:#ABB2BF"> } </span><span style="color:#C678DD">from</span><span style="color:#98C379"> 'node:fs'</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">diffRtdbRules</span><span style="color:#ABB2BF">, </span><span style="color:#E06C75">canonicalRtdbExpression</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"> handWritten</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:#61AFEF">readFileSync</span><span style="color:#ABB2BF">(</span><span style="color:#98C379">'legacy/database.rules.json'</span><span style="color:#ABB2BF">, </span><span style="color:#98C379">'utf8'</span><span style="color:#ABB2BF">)).</span><span style="color:#E06C75">rules</span><span style="color:#ABB2BF">;</span></span>
+<span class="line"><span style="color:#C678DD">const</span><span style="color:#E5C07B"> compiled</span><span style="color:#56B6C2"> =</span><span style="color:#E5C07B"> rules</span><span style="color:#ABB2BF">.</span><span style="color:#61AFEF">toJSON</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:#61AFEF">diffRtdbRules</span><span style="color:#ABB2BF">(</span><span style="color:#E06C75">handWritten</span><span style="color:#ABB2BF">, </span><span style="color:#E06C75">compiled</span><span style="color:#ABB2BF">);                             </span><span style="color:#7F848E;font-style:italic">// every rule whose text differs</span></span>
+<span class="line"><span style="color:#61AFEF">diffRtdbRules</span><span style="color:#ABB2BF">(</span><span style="color:#E06C75">handWritten</span><span style="color:#ABB2BF">, </span><span style="color:#E06C75">compiled</span><span style="color:#ABB2BF">, { </span><span style="color:#E06C75">ignoreEquivalent</span><span style="color:#ABB2BF">: </span><span style="color:#D19A66">true</span><span style="color:#ABB2BF"> }); </span><span style="color:#7F848E;font-style:italic">// only rules that can decide differently</span></span>
+<span class="line"><span style="color:#7F848E;font-style:italic">// → [{ path, kind: '.read' | '.write' | '.validate' | '.indexOn', change: 'added' | 'removed' | 'changed', deployed?, local? }]</span></span>
+<span class="line"></span>
+<span class="line"><span style="color:#61AFEF">canonicalRtdbExpression</span><span style="color:#ABB2BF">(</span><span style="color:#98C379">"$uid === auth.uid"</span><span style="color:#ABB2BF">);  </span><span style="color:#7F848E;font-style:italic">// "$uid == auth.uid"</span></span>
+<span class="line"><span style="color:#61AFEF">canonicalRtdbExpression</span><span style="color:#ABB2BF">(</span><span style="color:#98C379">"auth.uid !== null"</span><span style="color:#ABB2BF">);  </span><span style="color:#7F848E;font-style:italic">// "!(auth == null)"</span></span></code></pre>
+<p>A changed entry keeps both expressions exactly as written. Without the option the diff compares text.</p>
+<p>Two expressions are equivalent when their canonical texts are equal. The canonical form applies only rewrites that cannot change a decision, errors included (a rule that errors fails, and <code>||</code> or <code>!</code> does not rescue it):</p>
+<div class="table-scroll">
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+<table><thead><tr><th>Treated as the same</th><th>Why</th></tr></thead><tbody><tr><td>whitespace, grouping parentheses, <code>a &#x26;&#x26; (b &#x26;&#x26; c)</code> and <code>a &#x26;&#x26; b &#x26;&#x26; c</code></td><td>parentheses only shape the tree; <code>&#x26;&#x26;</code> and <code>||</code> evaluate left to right either way</td></tr><tr><td><code>"a"</code> and <code>'a'</code>, for a string literal written without a backslash</td><td>the same string; a literal with any escape (<code>'\d'</code>, <code>'\u0041'</code>) keeps its spelling, since production’s reading of most escapes has not been observed</td></tr><tr><td><code>===</code> and <code>==</code>, <code>!==</code> and <code>!=</code></td><td>RTDB compares without type conversion in both</td></tr><tr><td><code>auth.uid == null</code> and <code>auth == null</code></td><td><code>auth</code> is null exactly when signed out, and a signed-in <code>auth</code> always has a uid</td></tr><tr><td><code>child('a/b/' + $id + '/c')</code> and <code>child('a').child('b').child($id).child('c')</code></td><td>a <code>$</code> variable is exactly one key, and <code>child()</code> reads <code>/</code> as a separator</td></tr><tr><td><code>a != b</code> and <code>!(a == b)</code></td><td>both fail on the same inputs; otherwise <code>==</code> gives a boolean</td></tr><tr><td><code>a == b</code> and <code>b == a</code></td><td>equality is symmetric; operands that could fail other than with a rule error, or that index into an array, keep their order</td></tr></tbody></table></div>
+<p>Deliberately not treated as the same: a concatenated part that is not a string literal or a <code>$</code> variable, <code>auth.uid</code> included (<code>child('m/' + auth.uid)</code> is not <code>child('m').child(auth.uid)</code>, because production has not been observed reading a uid such as <code>/x</code> or <code>a//b</code> with empty segments the same way in both forms); a literal glued to a variable (<code>'user_' + $id</code>) or written with an escape; empty segments and key-invalid characters in a path; the order of <code>&#x26;&#x26;</code> and <code>||</code> operands; <code>>=</code> and <code>></code>; double negation; and arithmetic or constant folding. A rule that falls in one of those is reported as changed, so read those entries yourself.</p>
 <h2 id="turn-enforcement-from-a-deployed-game">Turn enforcement, from a deployed game</h2>
 <p>This turn-enforcement example is built from the same parts:</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>
@@ -93,4 +148,4 @@ html{scrollbar-gutter:stable}
 <h2 id="and-from-an-agent">And from an agent</h2>
 <p>An agent authors and checks the same way you do: lint and simulate locally (<code>pyric rules lint --service database</code>, <code>pyric rules simulate --service database</code>, or <code>rtdb_simulate_access</code> against the connected sandbox), generate JSON with <code>pyric database rules generate</code>, then ship with <code>firebase-tools</code>. See the RTDB task in <a href="../../agent/work-with-an-agent/">Work with an agent</a>.</p>
 <h2 id="where-to-go-next">Where to go next</h2>
-<p>The full builder catalog, with the exact expression each one produces, is in the <a href="../../pyric-database-reference-api/">constraints reference</a>. For matches, turns, results, counters, presence, rate limits and validated shapes, compose the <a href="../rtdb-rules-standard-library/">RTDB rules standard library</a> instead of writing the expressions yourself. For the data side of RTDB, see <a href="../../build/realtime-database/">Sync realtime data</a>.</p> </article> </main> <aside class="doc-toc" aria-label="On this page" data-astro-cid-mw7aashj> <h2 class="doc-toc-heading" data-astro-cid-mw7aashj>On this page</h2> <ul data-astro-cid-mw7aashj> <li data-depth="2" data-astro-cid-mw7aashj> <a href="#define-the-rules-in-code" data-astro-cid-mw7aashj>Define the rules in code</a> </li><li data-depth="2" data-astro-cid-mw7aashj> <a href="#check-it-before-anything-runs" data-astro-cid-mw7aashj>Check it before anything runs</a> </li><li data-depth="2" data-astro-cid-mw7aashj> <a href="#simulate-a-request" data-astro-cid-mw7aashj>Simulate a request</a> </li><li data-depth="2" data-astro-cid-mw7aashj> <a href="#ship-the-json" data-astro-cid-mw7aashj>Ship the JSON</a> </li><li data-depth="2" data-astro-cid-mw7aashj> <a href="#turn-enforcement-from-a-deployed-game" data-astro-cid-mw7aashj>Turn enforcement, from a deployed game</a> </li><li data-depth="2" data-astro-cid-mw7aashj> <a href="#and-from-an-agent" data-astro-cid-mw7aashj>And from an agent</a> </li><li data-depth="2" data-astro-cid-mw7aashj> <a href="#where-to-go-next" data-astro-cid-mw7aashj>Where to go 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> 
+<p>The full builder catalog, with the exact expression each one produces, is in the <a href="../../pyric-database-reference-api/">constraints reference</a>. For matches, turns, results, counters, presence, rate limits and validated shapes, compose the <a href="../rtdb-rules-standard-library/">RTDB rules standard library</a> instead of writing the expressions yourself. For the data side of RTDB, see <a href="../../build/realtime-database/">Sync realtime data</a>.</p> </article> </main> <aside class="doc-toc" aria-label="On this page" data-astro-cid-mw7aashj> <h2 class="doc-toc-heading" data-astro-cid-mw7aashj>On this page</h2> <ul data-astro-cid-mw7aashj> <li data-depth="2" data-astro-cid-mw7aashj> <a href="#define-the-rules-in-code" data-astro-cid-mw7aashj>Define the rules in code</a> </li><li data-depth="2" data-astro-cid-mw7aashj> <a href="#check-it-before-anything-runs" data-astro-cid-mw7aashj>Check it before anything runs</a> </li><li data-depth="2" data-astro-cid-mw7aashj> <a href="#simulate-a-request" data-astro-cid-mw7aashj>Simulate a request</a> </li><li data-depth="2" data-astro-cid-mw7aashj> <a href="#ship-the-json" data-astro-cid-mw7aashj>Ship the JSON</a> </li><li data-depth="2" data-astro-cid-mw7aashj> <a href="#compare-compiled-rules-with-the-rules-you-wrote-by-hand" data-astro-cid-mw7aashj>Compare compiled rules with the rules you wrote by hand</a> </li><li data-depth="2" data-astro-cid-mw7aashj> <a href="#turn-enforcement-from-a-deployed-game" data-astro-cid-mw7aashj>Turn enforcement, from a deployed game</a> </li><li data-depth="2" data-astro-cid-mw7aashj> <a href="#and-from-an-agent" data-astro-cid-mw7aashj>And from an agent</a> </li><li data-depth="2" data-astro-cid-mw7aashj> <a href="#where-to-go-next" data-astro-cid-mw7aashj>Where to go 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/site-ui/docs/secure/rtdb-rules-in-typescript.md

@@ -82,6 +82,39 @@ The CLI checks the JSON file itself, so CI can gate on it without TypeScript in
 - `pyric database rules validate database.rules.json` prints the error findings only. It exits `2` when there is one or when the file is not rules JSON, `1` when the file can't be read, and `0` otherwise.
 - `pyric rules simulate --service database --rules-file database.rules.json --operation read --path /notes/n1` evaluates one request against the file.
 
+## Compare compiled rules with the rules you wrote by hand
+
+When you move hand-written rules to TypeScript, the compiled JSON spells the same rules differently: `auth != null` where you wrote `auth.uid !== null`, `child('a').child($id)` where you wrote `child('a/' + $id)`. `diffRtdbRules` with `ignoreEquivalent` reports only the rules that can decide differently:
+```ts
+import { readFileSync } from 'node:fs';
+import { diffRtdbRules, canonicalRtdbExpression } from 'pyric/rules';
+
+const handWritten = JSON.parse(readFileSync('legacy/database.rules.json', 'utf8')).rules;
+const compiled = rules.toJSON().rules;
+
+diffRtdbRules(handWritten, compiled);                             // every rule whose text differs
+diffRtdbRules(handWritten, compiled, { ignoreEquivalent: true }); // only rules that can decide differently
+// → [{ path, kind: '.read' | '.write' | '.validate' | '.indexOn', change: 'added' | 'removed' | 'changed', deployed?, local? }]
+
+canonicalRtdbExpression("$uid === auth.uid");  // "$uid == auth.uid"
+canonicalRtdbExpression("auth.uid !== null");  // "!(auth == null)"
+```
+A changed entry keeps both expressions exactly as written. Without the option the diff compares text.
+
+Two expressions are equivalent when their canonical texts are equal. The canonical form applies only rewrites that cannot change a decision, errors included (a rule that errors fails, and `||` or `!` does not rescue it):
+
+| Treated as the same | Why |
+| --- | --- |
+| whitespace, grouping parentheses, `a && (b && c)` and `a && b && c` | parentheses only shape the tree; `&&` and `\|\|` evaluate left to right either way |
+| `"a"` and `'a'`, for a string literal written without a backslash | the same string; a literal with any escape (`'\d'`, `'\u0041'`) keeps its spelling, since production's reading of most escapes has not been observed |
+| `===` and `==`, `!==` and `!=` | RTDB compares without type conversion in both |
+| `auth.uid == null` and `auth == null` | `auth` is null exactly when signed out, and a signed-in `auth` always has a uid |
+| `child('a/b/' + $id + '/c')` and `child('a').child('b').child($id).child('c')` | a `$` variable is exactly one key, and `child()` reads `/` as a separator |
+| `a != b` and `!(a == b)` | both fail on the same inputs; otherwise `==` gives a boolean |
+| `a == b` and `b == a` | equality is symmetric; operands that could fail other than with a rule error, or that index into an array, keep their order |
+
+Deliberately not treated as the same: a concatenated part that is not a string literal or a `$` variable, `auth.uid` included (`child('m/' + auth.uid)` is not `child('m').child(auth.uid)`, because production has not been observed reading a uid such as `/x` or `a//b` with empty segments the same way in both forms); a literal glued to a variable (`'user_' + $id`) or written with an escape; empty segments and key-invalid characters in a path; the order of `&&` and `||` operands; `>=` and `>`; double negation; and arithmetic or constant folding. A rule that falls in one of those is reported as changed, so read those entries yourself.
+
 ## Turn enforcement, from a deployed game
 
 This turn-enforcement example is built from the same parts:

package/dist/serve/site-ui/examples/chess/index.html

@@ -1,4 +1,4 @@
 <!DOCTYPE html><html lang="en"> <head><meta charset="UTF-8"><meta name="viewport" content="width=device-width, initial-scale=1.0, viewport-fit=cover"><title>Play chess against Security Rules</title><link rel="icon" type="image/svg+xml" href="/__pyric/ui/pyric-logo.svg"><link rel="preconnect" href="https://use.typekit.net" crossorigin><link rel="stylesheet" href="https://use.typekit.net/jwb3ycu.css"><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"><style>html{scrollbar-gutter:stable}
 </style>
 <link rel="stylesheet" href="/__pyric/ui/_astro/_example_.B9DG9HLJ.css">
-<link rel="stylesheet" href="/__pyric/ui/_astro/app.8TtSeQQX.css"></head> <body>  <style>astro-island,astro-slot,astro-static-slot{display:contents}</style><script>(()=>{var e=async t=>{await(await t())()};(self.Astro||(self.Astro={})).only=e;window.dispatchEvent(new Event("astro:only"));})();</script><script>(()=>{var A=Object.defineProperty;var g=(i,o,a)=>o in i?A(i,o,{enumerable:!0,configurable:!0,writable:!0,value:a}):i[o]=a;var d=(i,o,a)=>g(i,typeof o!="symbol"?o+"":o,a);{let i={0:t=>m(t),1:t=>a(t),2:t=>new RegExp(t),3:t=>new Date(t),4:t=>new Map(a(t)),5:t=>new Set(a(t)),6:t=>BigInt(t),7:t=>new URL(t),8:t=>new Uint8Array(t),9:t=>new Uint16Array(t),10:t=>new Uint32Array(t),11:t=>1/0*t},o=t=>{let[l,e]=t;return l in i?i[l](e):void 0},a=t=>t.map(o),m=t=>typeof t!="object"||t===null?t:Object.fromEntries(Object.entries(t).map(([l,e])=>[l,o(e)]));class y extends HTMLElement{constructor(){super(...arguments);d(this,"Component");d(this,"hydrator");d(this,"hydrate",async()=>{var b;if(!this.hydrator||!this.isConnected)return;let e=(b=this.parentElement)==null?void 0:b.closest("astro-island[ssr]");if(e){e.addEventListener("astro:hydrate",this.hydrate,{once:!0});return}let c=this.querySelectorAll("astro-slot"),n={},h=this.querySelectorAll("template[data-astro-template]");for(let r of h){let s=r.closest(this.tagName);s!=null&&s.isSameNode(this)&&(n[r.getAttribute("data-astro-template")||"default"]=r.innerHTML,r.remove())}for(let r of c){let s=r.closest(this.tagName);s!=null&&s.isSameNode(this)&&(n[r.getAttribute("name")||"default"]=r.innerHTML)}let p;try{p=this.hasAttribute("props")?m(JSON.parse(this.getAttribute("props"))):{}}catch(r){let s=this.getAttribute("component-url")||"<unknown>",v=this.getAttribute("component-export");throw v&&(s+=` (export ${v})`),console.error(`[hydrate] Error parsing props for component ${s}`,this.getAttribute("props"),r),r}let u;await this.hydrator(this)(this.Component,p,n,{client:this.getAttribute("client")}),this.removeAttribute("ssr"),this.dispatchEvent(new CustomEvent("astro:hydrate"))});d(this,"unmount",()=>{this.isConnected||this.dispatchEvent(new CustomEvent("astro:unmount"))})}disconnectedCallback(){document.removeEventListener("astro:after-swap",this.unmount),document.addEventListener("astro:after-swap",this.unmount,{once:!0})}connectedCallback(){if(!this.hasAttribute("await-children")||document.readyState==="interactive"||document.readyState==="complete")this.childrenConnectedCallback();else{let e=()=>{document.removeEventListener("DOMContentLoaded",e),c.disconnect(),this.childrenConnectedCallback()},c=new MutationObserver(()=>{var n;((n=this.lastChild)==null?void 0:n.nodeType)===Node.COMMENT_NODE&&this.lastChild.nodeValue==="astro:end"&&(this.lastChild.remove(),e())});c.observe(this,{childList:!0}),document.addEventListener("DOMContentLoaded",e)}}async childrenConnectedCallback(){let e=this.getAttribute("before-hydration-url");e&&await import(e),this.start()}async start(){let e=JSON.parse(this.getAttribute("opts")),c=this.getAttribute("client");if(Astro[c]===void 0){window.addEventListener(`astro:${c}`,()=>this.start(),{once:!0});return}try{await Astro[c](async()=>{let n=this.getAttribute("renderer-url"),[h,{default:p}]=await Promise.all([import(this.getAttribute("component-url")),n?import(n):()=>()=>{}]),u=this.getAttribute("component-export")||"default";if(!u.includes("."))this.Component=h[u];else{this.Component=h;for(let f of u.split("."))this.Component=this.Component[f]}return this.hydrator=p,this.hydrate},e,this)}catch(n){console.error(`[astro-island] Error hydrating ${this.getAttribute("component-url")}`,n)}}attributeChangedCallback(){this.hydrate()}}d(y,"observedAttributes",["props"]),customElements.get("astro-island")||customElements.define("astro-island",y)}})();</script><astro-island uid="ZN6Jl9" component-url="/__pyric/ui/_astro/chess-showcase.CZe_3fJZ.js" component-export="ChessShowcase" renderer-url="/__pyric/ui/_astro/client.D2ORs4B-.js" props="{}" ssr client="only" opts="{&quot;name&quot;:&quot;ChessShowcase&quot;,&quot;value&quot;:&quot;react&quot;}"></astro-island>  </body></html> 
+<link rel="stylesheet" href="/__pyric/ui/_astro/app.8TtSeQQX.css"></head> <body>  <style>astro-island,astro-slot,astro-static-slot{display:contents}</style><script>(()=>{var e=async t=>{await(await t())()};(self.Astro||(self.Astro={})).only=e;window.dispatchEvent(new Event("astro:only"));})();</script><script>(()=>{var A=Object.defineProperty;var g=(i,o,a)=>o in i?A(i,o,{enumerable:!0,configurable:!0,writable:!0,value:a}):i[o]=a;var d=(i,o,a)=>g(i,typeof o!="symbol"?o+"":o,a);{let i={0:t=>m(t),1:t=>a(t),2:t=>new RegExp(t),3:t=>new Date(t),4:t=>new Map(a(t)),5:t=>new Set(a(t)),6:t=>BigInt(t),7:t=>new URL(t),8:t=>new Uint8Array(t),9:t=>new Uint16Array(t),10:t=>new Uint32Array(t),11:t=>1/0*t},o=t=>{let[l,e]=t;return l in i?i[l](e):void 0},a=t=>t.map(o),m=t=>typeof t!="object"||t===null?t:Object.fromEntries(Object.entries(t).map(([l,e])=>[l,o(e)]));class y extends HTMLElement{constructor(){super(...arguments);d(this,"Component");d(this,"hydrator");d(this,"hydrate",async()=>{var b;if(!this.hydrator||!this.isConnected)return;let e=(b=this.parentElement)==null?void 0:b.closest("astro-island[ssr]");if(e){e.addEventListener("astro:hydrate",this.hydrate,{once:!0});return}let c=this.querySelectorAll("astro-slot"),n={},h=this.querySelectorAll("template[data-astro-template]");for(let r of h){let s=r.closest(this.tagName);s!=null&&s.isSameNode(this)&&(n[r.getAttribute("data-astro-template")||"default"]=r.innerHTML,r.remove())}for(let r of c){let s=r.closest(this.tagName);s!=null&&s.isSameNode(this)&&(n[r.getAttribute("name")||"default"]=r.innerHTML)}let p;try{p=this.hasAttribute("props")?m(JSON.parse(this.getAttribute("props"))):{}}catch(r){let s=this.getAttribute("component-url")||"<unknown>",v=this.getAttribute("component-export");throw v&&(s+=` (export ${v})`),console.error(`[hydrate] Error parsing props for component ${s}`,this.getAttribute("props"),r),r}let u;await this.hydrator(this)(this.Component,p,n,{client:this.getAttribute("client")}),this.removeAttribute("ssr"),this.dispatchEvent(new CustomEvent("astro:hydrate"))});d(this,"unmount",()=>{this.isConnected||this.dispatchEvent(new CustomEvent("astro:unmount"))})}disconnectedCallback(){document.removeEventListener("astro:after-swap",this.unmount),document.addEventListener("astro:after-swap",this.unmount,{once:!0})}connectedCallback(){if(!this.hasAttribute("await-children")||document.readyState==="interactive"||document.readyState==="complete")this.childrenConnectedCallback();else{let e=()=>{document.removeEventListener("DOMContentLoaded",e),c.disconnect(),this.childrenConnectedCallback()},c=new MutationObserver(()=>{var n;((n=this.lastChild)==null?void 0:n.nodeType)===Node.COMMENT_NODE&&this.lastChild.nodeValue==="astro:end"&&(this.lastChild.remove(),e())});c.observe(this,{childList:!0}),document.addEventListener("DOMContentLoaded",e)}}async childrenConnectedCallback(){let e=this.getAttribute("before-hydration-url");e&&await import(e),this.start()}async start(){let e=JSON.parse(this.getAttribute("opts")),c=this.getAttribute("client");if(Astro[c]===void 0){window.addEventListener(`astro:${c}`,()=>this.start(),{once:!0});return}try{await Astro[c](async()=>{let n=this.getAttribute("renderer-url"),[h,{default:p}]=await Promise.all([import(this.getAttribute("component-url")),n?import(n):()=>()=>{}]),u=this.getAttribute("component-export")||"default";if(!u.includes("."))this.Component=h[u];else{this.Component=h;for(let f of u.split("."))this.Component=this.Component[f]}return this.hydrator=p,this.hydrate},e,this)}catch(n){console.error(`[astro-island] Error hydrating ${this.getAttribute("component-url")}`,n)}}attributeChangedCallback(){this.hydrate()}}d(y,"observedAttributes",["props"]),customElements.get("astro-island")||customElements.define("astro-island",y)}})();</script><astro-island uid="sFXys" component-url="/__pyric/ui/_astro/chess-showcase.CZe_3fJZ.js" component-export="ChessShowcase" renderer-url="/__pyric/ui/_astro/client.D2ORs4B-.js" props="{}" ssr client="only" opts="{&quot;name&quot;:&quot;ChessShowcase&quot;,&quot;value&quot;:&quot;react&quot;}"></astro-island>  </body></html> 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pyric/cli",
-  "version": "0.1.0-alpha.25",
+  "version": "0.1.0-alpha.26",
   "license": "Apache-2.0",
   "homepage": "https://pyric.dev",
   "repository": {
@@ -245,12 +245,12 @@
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.0.0",
-    "create-pyric": "^0.1.0-alpha.25",
+    "create-pyric": "^0.1.0-alpha.26",
     "esbuild": "^0.28.0",
     "fake-indexeddb": "^6.0.0",
     "jsonc-parser": "^3.3.1",
-    "pyric": "^0.1.0-alpha.25",
-    "pyric-admin": "^0.1.0-alpha.25",
+    "pyric": "^0.1.0-alpha.26",
+    "pyric-admin": "^0.1.0-alpha.26",
     "ws": "^8.18.0",
     "zod": "^3.23.0"
   },

package/src/rtdb/inspect-deployed-rules.ts

@@ -9,25 +9,14 @@
  * URL, and it is not returned in any result or message.
  */
 import type { ToolHandler } from 'pyric/sandbox/internal';
+import { diffRtdbRules, type RtdbRuleChange } from 'pyric/rules/internal/rtdb';
 import { parseRtdbRulesText } from './rules-json.js';
 import { HOSTED_CREDENTIAL_SOURCES } from '../credentials/node/scope.js';
 
-/** The rule kinds the diff compares. */
-export const DIFFED_RULE_KINDS = ['.indexOn', '.read', '.validate', '.write'] as const;
-export type RtdbRuleKind = (typeof DIFFED_RULE_KINDS)[number];
-
-/**
- * One rule expression that differs. `deployed` is absent for `added` and
- * `local` is absent for `removed`: the change is what deploying the local
- * ruleset would do to the deployed one.
- */
-export interface RtdbRuleChange {
-  path: string;
-  kind: RtdbRuleKind;
-  change: 'added' | 'removed' | 'changed';
-  deployed?: string;
-  local?: string;
-}
+// The diff itself is pure and lives in `pyric` (public from `pyric/rules`);
+// it is re-exported here so this module's exports stay as they were.
+export { DIFFED_RULE_KINDS, diffRtdbRules } from 'pyric/rules/internal/rtdb';
+export type { DiffRtdbRulesOptions, RtdbRuleChange, RtdbRuleKind } from 'pyric/rules/internal/rtdb';
 
 export interface InspectDeployedRtdbRulesOptions {
   scope: { resolveToken(): Promise<string> };
@@ -96,67 +85,6 @@ export async function inspectDeployedRtdbRules(
   return { ok: true, deployed, diff: diffRtdbRules(deployed.rules, local.rules) };
 }
 
-/** Node-level diff of two `rules` trees, ordered by path then rule kind. */
-export function diffRtdbRules(
-  deployed: Record<string, unknown>,
-  local: Record<string, unknown>,
-): RtdbRuleChange[] {
-  const deployedRules = collectRules(deployed);
-  const localRules = collectRules(local);
-  const changes: RtdbRuleChange[] = [];
-  for (const key of new Set([...deployedRules.keys(), ...localRules.keys()])) {
-    const d = deployedRules.get(key);
-    const l = localRules.get(key);
-    if (d?.value === l?.value) continue;
-    const node = (d ?? l)!;
-    const change: RtdbRuleChange = {
-      path: node.path,
-      kind: node.kind,
-      change: d === undefined ? 'added' : l === undefined ? 'removed' : 'changed',
-    };
-    if (d !== undefined) change.deployed = d.value;
-    if (l !== undefined) change.local = l.value;
-    changes.push(change);
-  }
-  return changes.sort((a, b) => compare(a.path, b.path) || compare(a.kind, b.kind));
-}
-
-const compare = (a: string, b: string): number => (a < b ? -1 : a > b ? 1 : 0);
-
-interface CollectedRule {
-  path: string;
-  kind: RtdbRuleKind;
-  value: string;
-}
-
-function formatRuleValue(kind: RtdbRuleKind, value: unknown): string {
-  if (kind === '.indexOn') {
-    const normalized = typeof value === 'string' ? [value] : value;
-    return JSON.stringify(normalized);
-  }
-  // A boolean and its string form are one expression: `true` and "true".
-  return typeof value === 'string' ? value : JSON.stringify(value);
-}
-
-function collectRules(root: Record<string, unknown>): Map<string, CollectedRule> {
-  const out = new Map<string, CollectedRule>();
-  const walk = (node: Record<string, unknown>, path: string): void => {
-    for (const [key, child] of Object.entries(node)) {
-      if (key.startsWith('.')) {
-        if ((DIFFED_RULE_KINDS as readonly string[]).includes(key)) {
-          const kind = key as RtdbRuleKind;
-          const value = formatRuleValue(kind, child);
-          out.set(`${path}\u0000${kind}`, { path, kind, value });
-        }
-      } else if (typeof child === 'object' && child !== null && !Array.isArray(child)) {
-        walk(child as Record<string, unknown>, `${path === '/' ? '' : path}/${key}`);
-      }
-    }
-  };
-  walk(root, '/');
-  return out;
-}
-
 export interface RtdbInspectRulesToolDeps {
   scope: { resolveToken(): Promise<string> };
   databaseURL: string;