npm - @pyric/cli - Versions diffs - 0.1.0-alpha.9 - Mend

@pyric/cli 0.1.0-alpha.9

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (1169) hide show

package/dist/serve/docs-ui/docs/pyric-rules-reference-value-wrappers/index.html ADDED Viewed

@@ -0,0 +1,102 @@
+<!DOCTYPE html><html lang="en"> <head><meta charset="UTF-8"><meta name="viewport" content="width=device-width, initial-scale=1.0"><title>Value wrappers · Pyric Studio</title><link rel="preconnect" href="https://fonts.googleapis.com"><link rel="preconnect" href="https://fonts.gstatic.com" crossorigin><link href="https://fonts.googleapis.com/css2?family=Inter:wght@300;400;500;600;700&family=JetBrains+Mono:wght@400;500;700&display=swap" rel="stylesheet"><link rel="stylesheet" href="/__pyric/ui/_astro/_slug_.CQYSemvw.css"></head> <body>  <header class="studio__bar"> <div class="studio__bar-inner"> <a class="studio__brand" href="/__pyric/ui/" aria-label="Pyric Studio">Pyric</a> <nav class="studio__nav" aria-label="Studio tabs"> <a class="studio__nav-tab" href="/__pyric/ui/"> Home </a><a class="studio__nav-tab" href="/__pyric/ui/firestore"> Firestore </a><a class="studio__nav-tab" href="/__pyric/ui/auth"> Auth </a><a class="studio__nav-tab" href="/__pyric/ui/rtdb"> RTDB </a><a class="studio__nav-tab" href="/__pyric/ui/storage"> Storage </a><a class="studio__nav-tab" href="/__pyric/ui/traffic"> Traffic </a><a class="studio__nav-tab" href="/__pyric/ui/settings"> Settings </a><a class="studio__nav-tab" href="/__pyric/ui/docs" aria-current="page"> Docs </a> </nav> </div> </header> <div class="docs-shell">  <details class="docs-nav-drawer"> <summary>Navigate</summary> <nav class="docs-nav" aria-label="Documentation"> <div class="docs-search" data-index-url="/__pyric/ui/docs/index.json"> <div class="docs-search-field"> <svg class="docs-search-icon" viewBox="0 0 16 16" width="14" height="14" aria-hidden="true"> <path d="M11.5 11.5 15 15M13 7A6 6 0 1 1 1 7a6 6 0 0 1 12 0Z" fill="none" stroke="currentColor" stroke-width="1.4" stroke-linecap="round"></path> </svg> <input type="text" class="docs-search-input" placeholder="Search docs" aria-label="Search docs" autocomplete="off" spellcheck="false"> <kbd class="docs-search-kbd">⌘K</kbd> </div> <ul class="docs-search-results" hidden></ul> </div> <script type="module">let i=null;function d(t){return i||(i=fetch(t).then(e=>e.json())),i}function l(t,e){return t.title.toLowerCase().includes(e)||t.excerpt.toLowerCase().includes(e)?!0:t.headings.some(r=>r.text.toLowerCase().includes(e))}function u(t,e,r){if(e.innerHTML="",t.length===0){e.hidden=!1;{const n=document.createElement("li");n.className="docs-search-empty",n.textContent="No matches",e.appendChild(n)}return}e.hidden=!1;for(const n of t.slice(0,8)){const s=document.createElement("li"),c=document.createElement("a");c.href=n.path;const o=document.createElement("span");o.className="docs-search-result-title",o.textContent=n.title;const a=document.createElement("span");a.className="docs-search-result-meta",a.textContent=[n.group,n.section].filter(Boolean).join(" / "),c.append(o,a),s.appendChild(c),e.appendChild(s)}}document.querySelectorAll(".docs-search").forEach(t=>{const e=t.dataset.indexUrl,r=t.querySelector(".docs-search-input"),n=t.querySelector(".docs-search-results");r.addEventListener("input",async()=>{const s=r.value.trim().toLowerCase();if(!s){n.hidden=!0,n.innerHTML="";return}const{pages:c}=await d(e);r.value.trim().toLowerCase()===s&&u(c.filter(o=>l(o,s)),n)}),r.addEventListener("focus",()=>{d(e),n.childElementCount>0&&(n.hidden=!1)}),r.addEventListener("keydown",s=>{s.key==="Escape"&&(r.value="",n.hidden=!0,n.innerHTML="",r.blur())}),r.addEventListener("blur",()=>{window.setTimeout(()=>{n.hidden=!0},150)})});document.addEventListener("keydown",t=>{if(!(t.metaKey||t.ctrlKey)||t.key.toLowerCase()!=="k")return;const e=[...document.querySelectorAll(".docs-search-input")].find(r=>r.offsetParent!==null);e&&(t.preventDefault(),e.focus(),e.select())});</script> <a class="docs-nav-toplink" href="/__pyric/ui/docs/overview/"> Overview </a><details class="docs-nav-group"> <summary>Run locally</summary> <div class="docs-nav-group-body"> <div class="docs-nav-section">  <ul> <li> <a href="/__pyric/ui/docs/start-building/"> Quickstart </a> </li><li> <a href="/__pyric/ui/docs/how-the-swap-works/"> How the swap works </a> </li><li> <a href="/__pyric/ui/docs/set-up-your-agent/"> Connect an agent </a> </li><li> <a href="/__pyric/ui/docs/test-in-node/"> Test in Node </a> </li> </ul> </div> </div> </details><details class="docs-nav-group"> <summary>Develop with Firebase APIs</summary> <div class="docs-nav-group-body"> <div class="docs-nav-section">  <ul> <li> <a href="/__pyric/ui/docs/sign-in-and-manage-users/"> Sign in and manage users </a> </li><li> <a href="/__pyric/ui/docs/store-and-query-data/"> Store and query data </a> </li><li> <a href="/__pyric/ui/docs/sync-realtime-data/"> Sync realtime data </a> </li><li> <a href="/__pyric/ui/docs/store-files/"> Store files </a> </li><li> <a href="/__pyric/ui/docs/receive-messages/"> Receive messages </a> </li><li> <a href="/__pyric/ui/docs/run-ai-logic-locally/"> Run AI Logic locally </a> </li><li> <a href="/__pyric/ui/docs/pyric-cli-how-to-run-rtdb-onvaluecreated/"> Run an RTDB function locally </a> </li><li> <a href="/__pyric/ui/docs/which-data-service/"> Which data service? </a> </li> </ul> </div> </div> </details><details class="docs-nav-group"> <summary>Inspect and correct</summary> <div class="docs-nav-group-body"> <div class="docs-nav-section"> <h2 class="docs-nav-heading"> Inspect the sandbox </h2> <ul> <li> <a href="/__pyric/ui/docs/see-whats-happening/"> Traffic &amp; rule verdicts </a> </li><li> <a href="/__pyric/ui/docs/read-a-denial/"> Read a denial and understand it </a> </li><li> <a href="/__pyric/ui/docs/shape-your-data/"> Seed, snapshot, replay </a> </li><li> <a href="/__pyric/ui/docs/watch-and-review/"> Review agent activity </a> </li> </ul> </div><div class="docs-nav-section"> <h2 class="docs-nav-heading"> Correct Security Rules </h2> <ul> <li> <a href="/__pyric/ui/docs/secure-it-with-rules/"> Security Rules </a> </li><li> <a href="/__pyric/ui/docs/simulate-and-lint/"> Simulate and lint before you deploy </a> </li><li> <a href="/__pyric/ui/docs/rules-patterns/"> Rules patterns </a> </li><li> <a href="/__pyric/ui/docs/rules-standard-library/"> The rules standard library </a> </li><li> <a href="/__pyric/ui/docs/rtdb-rules-in-typescript/"> RTDB rules in TypeScript </a> </li><li> <a href="/__pyric/ui/docs/firestore-rules-limits/"> Rules limits </a> </li><li> <a href="/__pyric/ui/docs/whats-possible/"> Case studies </a> </li> </ul> </div><div class="docs-nav-section"> <h2 class="docs-nav-heading"> Work with an agent </h2> <ul> <li> <a href="/__pyric/ui/docs/what-your-agent-can-do/"> Work through an agent </a> </li><li> <a href="/__pyric/ui/docs/skills/"> Agent skills </a> </li> </ul> </div> </div> </details><details class="docs-nav-group"> <summary>Verify the boundary</summary> <div class="docs-nav-group-body"> <div class="docs-nav-section">  <ul> <li> <a href="/__pyric/ui/docs/pyric-cli-how-to-verify-against-a-captured-session/"> Verify a captured session </a> </li><li> <a href="/__pyric/ui/docs/write-a-rules-test-suite/"> Write a rules test suite </a> </li><li> <a href="/__pyric/ui/docs/audit-your-rules/"> Audit rules and data </a> </li> </ul> </div> </div> </details><details class="docs-nav-group"> <summary>Ship unchanged</summary> <div class="docs-nav-group-body"> <div class="docs-nav-section">  <ul> <li> <a href="/__pyric/ui/docs/ship-to-production/"> Ship to production </a> </li><li> <a href="/__pyric/ui/docs/set-up-the-project/"> Set up the Firebase project </a> </li> </ul> </div> </div> </details><details class="docs-nav-group"> <summary>Conformance</summary> <div class="docs-nav-group-body"> <div class="docs-nav-section">  <ul> <li> <a href="/__pyric/ui/docs/how-we-know-it-matches-firebase/"> Conformance </a> </li><li> <a href="/__pyric/ui/docs/whats-experimental/"> What&#39;s experimental </a> </li><li> <a href="/__pyric/ui/docs/pyric-conformance-scores/"> Conformance scores </a> </li><li> <a href="/__pyric/ui/docs/pyric-app-compat/"> App </a> </li><li> <a href="/__pyric/ui/docs/pyric-firestore-compat/"> Firestore </a> </li><li> <a href="/__pyric/ui/docs/pyric-auth-compat/"> Auth </a> </li><li> <a href="/__pyric/ui/docs/pyric-database-compat/"> Realtime Database </a> </li><li> <a href="/__pyric/ui/docs/pyric-storage-compat/"> Storage </a> </li><li> <a href="/__pyric/ui/docs/pyric-rules-compat/"> Rules </a> </li><li> <a href="/__pyric/ui/docs/pyric-messaging-compat/"> Messaging </a> </li><li> <a href="/__pyric/ui/docs/pyric-ai-compat/"> AI Logic </a> </li><li> <a href="/__pyric/ui/docs/pyric-cli-functions-rtdb-compat/"> Functions · RTDB </a> </li> </ul> </div> </div> </details> <details class="docs-nav-group" open> <summary>Reference</summary> <div class="docs-nav-group-body"> <div class="docs-nav-section"> <ul> <li> <a href="/__pyric/ui/docs/pyric-cli/"> @pyric/cli </a> </li><li> <a href="/__pyric/ui/docs/pyric-explanation-versioning-and-compatibility/"> pyric </a> </li><li> <a href="/__pyric/ui/docs/pyric-firestore/"> pyric / firestore </a> </li><li> <a href="/__pyric/ui/docs/pyric-rules/" aria-current="true"> pyric / rules </a> </li><li> <a href="/__pyric/ui/docs/pyric-sandbox/"> pyric / sandbox </a> </li><li> <a href="/__pyric/ui/docs/pyric-storage/"> pyric / storage </a> </li><li> <a href="/__pyric/ui/docs/pyric-auth/"> pyric / auth </a> </li><li> <a href="/__pyric/ui/docs/pyric-database/"> pyric / database </a> </li><li> <a href="/__pyric/ui/docs/pyric-admin-app/"> pyric-admin / app </a> </li><li> <a href="/__pyric/ui/docs/pyric-admin-firestore/"> pyric-admin / firestore </a> </li><li> <a href="/__pyric/ui/docs/pyric-admin-auth/"> pyric-admin / auth </a> </li><li> <a href="/__pyric/ui/docs/pyric-admin-database/"> pyric-admin / database </a> </li><li> <a href="/__pyric/ui/docs/pyric-admin-storage/"> pyric-admin / storage </a> </li><li> <a href="/__pyric/ui/docs/ui/"> @pyric/ui </a> </li><li> <a href="/__pyric/ui/docs/api-reference/"> API reference </a> </li> </ul> </div> </div> </details> </nav> </details> <nav class="docs-nav" aria-label="Documentation"> <div class="docs-search" data-index-url="/__pyric/ui/docs/index.json"> <div class="docs-search-field"> <svg class="docs-search-icon" viewBox="0 0 16 16" width="14" height="14" aria-hidden="true"> <path d="M11.5 11.5 15 15M13 7A6 6 0 1 1 1 7a6 6 0 0 1 12 0Z" fill="none" stroke="currentColor" stroke-width="1.4" stroke-linecap="round"></path> </svg> <input type="text" class="docs-search-input" placeholder="Search docs" aria-label="Search docs" autocomplete="off" spellcheck="false"> <kbd class="docs-search-kbd">⌘K</kbd> </div> <ul class="docs-search-results" hidden></ul> </div>  <a class="docs-nav-toplink" href="/__pyric/ui/docs/overview/" id="nav-group-overview"> Overview </a><details class="docs-nav-group" id="nav-group-run-locally"> <summary>Run locally</summary> <div class="docs-nav-group-body"> <div class="docs-nav-section">  <ul> <li> <a href="/__pyric/ui/docs/start-building/"> Quickstart </a> </li><li> <a href="/__pyric/ui/docs/how-the-swap-works/"> How the swap works </a> </li><li> <a href="/__pyric/ui/docs/set-up-your-agent/"> Connect an agent </a> </li><li> <a href="/__pyric/ui/docs/test-in-node/"> Test in Node </a> </li> </ul> </div> </div> </details><details class="docs-nav-group" id="nav-group-develop-with-firebase-apis"> <summary>Develop with Firebase APIs</summary> <div class="docs-nav-group-body"> <div class="docs-nav-section">  <ul> <li> <a href="/__pyric/ui/docs/sign-in-and-manage-users/"> Sign in and manage users </a> </li><li> <a href="/__pyric/ui/docs/store-and-query-data/"> Store and query data </a> </li><li> <a href="/__pyric/ui/docs/sync-realtime-data/"> Sync realtime data </a> </li><li> <a href="/__pyric/ui/docs/store-files/"> Store files </a> </li><li> <a href="/__pyric/ui/docs/receive-messages/"> Receive messages </a> </li><li> <a href="/__pyric/ui/docs/run-ai-logic-locally/"> Run AI Logic locally </a> </li><li> <a href="/__pyric/ui/docs/pyric-cli-how-to-run-rtdb-onvaluecreated/"> Run an RTDB function locally </a> </li><li> <a href="/__pyric/ui/docs/which-data-service/"> Which data service? </a> </li> </ul> </div> </div> </details><details class="docs-nav-group" id="nav-group-inspect-and-correct"> <summary>Inspect and correct</summary> <div class="docs-nav-group-body"> <div class="docs-nav-section"> <h2 class="docs-nav-heading" id="nav-section-inspect-and-correct-inspect-the-sandbox"> Inspect the sandbox </h2> <ul> <li> <a href="/__pyric/ui/docs/see-whats-happening/"> Traffic &amp; rule verdicts </a> </li><li> <a href="/__pyric/ui/docs/read-a-denial/"> Read a denial and understand it </a> </li><li> <a href="/__pyric/ui/docs/shape-your-data/"> Seed, snapshot, replay </a> </li><li> <a href="/__pyric/ui/docs/watch-and-review/"> Review agent activity </a> </li> </ul> </div><div class="docs-nav-section"> <h2 class="docs-nav-heading" id="nav-section-inspect-and-correct-correct-security-rules"> Correct Security Rules </h2> <ul> <li> <a href="/__pyric/ui/docs/secure-it-with-rules/"> Security Rules </a> </li><li> <a href="/__pyric/ui/docs/simulate-and-lint/"> Simulate and lint before you deploy </a> </li><li> <a href="/__pyric/ui/docs/rules-patterns/"> Rules patterns </a> </li><li> <a href="/__pyric/ui/docs/rules-standard-library/"> The rules standard library </a> </li><li> <a href="/__pyric/ui/docs/rtdb-rules-in-typescript/"> RTDB rules in TypeScript </a> </li><li> <a href="/__pyric/ui/docs/firestore-rules-limits/"> Rules limits </a> </li><li> <a href="/__pyric/ui/docs/whats-possible/"> Case studies </a> </li> </ul> </div><div class="docs-nav-section"> <h2 class="docs-nav-heading" id="nav-section-inspect-and-correct-work-with-an-agent"> Work with an agent </h2> <ul> <li> <a href="/__pyric/ui/docs/what-your-agent-can-do/"> Work through an agent </a> </li><li> <a href="/__pyric/ui/docs/skills/"> Agent skills </a> </li> </ul> </div> </div> </details><details class="docs-nav-group" id="nav-group-verify-the-boundary"> <summary>Verify the boundary</summary> <div class="docs-nav-group-body"> <div class="docs-nav-section">  <ul> <li> <a href="/__pyric/ui/docs/pyric-cli-how-to-verify-against-a-captured-session/"> Verify a captured session </a> </li><li> <a href="/__pyric/ui/docs/write-a-rules-test-suite/"> Write a rules test suite </a> </li><li> <a href="/__pyric/ui/docs/audit-your-rules/"> Audit rules and data </a> </li> </ul> </div> </div> </details><details class="docs-nav-group" id="nav-group-ship-unchanged"> <summary>Ship unchanged</summary> <div class="docs-nav-group-body"> <div class="docs-nav-section">  <ul> <li> <a href="/__pyric/ui/docs/ship-to-production/"> Ship to production </a> </li><li> <a href="/__pyric/ui/docs/set-up-the-project/"> Set up the Firebase project </a> </li> </ul> </div> </div> </details><details class="docs-nav-group" id="nav-group-conformance"> <summary>Conformance</summary> <div class="docs-nav-group-body"> <div class="docs-nav-section">  <ul> <li> <a href="/__pyric/ui/docs/how-we-know-it-matches-firebase/"> Conformance </a> </li><li> <a href="/__pyric/ui/docs/whats-experimental/"> What&#39;s experimental </a> </li><li> <a href="/__pyric/ui/docs/pyric-conformance-scores/"> Conformance scores </a> </li><li> <a href="/__pyric/ui/docs/pyric-app-compat/"> App </a> </li><li> <a href="/__pyric/ui/docs/pyric-firestore-compat/"> Firestore </a> </li><li> <a href="/__pyric/ui/docs/pyric-auth-compat/"> Auth </a> </li><li> <a href="/__pyric/ui/docs/pyric-database-compat/"> Realtime Database </a> </li><li> <a href="/__pyric/ui/docs/pyric-storage-compat/"> Storage </a> </li><li> <a href="/__pyric/ui/docs/pyric-rules-compat/"> Rules </a> </li><li> <a href="/__pyric/ui/docs/pyric-messaging-compat/"> Messaging </a> </li><li> <a href="/__pyric/ui/docs/pyric-ai-compat/"> AI Logic </a> </li><li> <a href="/__pyric/ui/docs/pyric-cli-functions-rtdb-compat/"> Functions · RTDB </a> </li> </ul> </div> </div> </details> <details class="docs-nav-group" id="nav-group-reference" open> <summary>Reference</summary> <div class="docs-nav-group-body"> <div class="docs-nav-section"> <ul> <li> <a href="/__pyric/ui/docs/pyric-cli/"> @pyric/cli </a> </li><li> <a href="/__pyric/ui/docs/pyric-explanation-versioning-and-compatibility/"> pyric </a> </li><li> <a href="/__pyric/ui/docs/pyric-firestore/"> pyric / firestore </a> </li><li> <a href="/__pyric/ui/docs/pyric-rules/" aria-current="true"> pyric / rules </a> </li><li> <a href="/__pyric/ui/docs/pyric-sandbox/"> pyric / sandbox </a> </li><li> <a href="/__pyric/ui/docs/pyric-storage/"> pyric / storage </a> </li><li> <a href="/__pyric/ui/docs/pyric-auth/"> pyric / auth </a> </li><li> <a href="/__pyric/ui/docs/pyric-database/"> pyric / database </a> </li><li> <a href="/__pyric/ui/docs/pyric-admin-app/"> pyric-admin / app </a> </li><li> <a href="/__pyric/ui/docs/pyric-admin-firestore/"> pyric-admin / firestore </a> </li><li> <a href="/__pyric/ui/docs/pyric-admin-auth/"> pyric-admin / auth </a> </li><li> <a href="/__pyric/ui/docs/pyric-admin-database/"> pyric-admin / database </a> </li><li> <a href="/__pyric/ui/docs/pyric-admin-storage/"> pyric-admin / storage </a> </li><li> <a href="/__pyric/ui/docs/ui/"> @pyric/ui </a> </li><li> <a href="/__pyric/ui/docs/api-reference/"> API reference </a> </li> </ul> </div> </div> </details> </nav> <main class="doc-main"> <nav class="docs-breadcrumbs" aria-label="Breadcrumb"> <ol> <li>  <a href="/__pyric/ui/docs/pyric-rules/">pyric / rules</a> </li><li> <span class="docs-breadcrumbs-sep" aria-hidden="true">/</span> <span>Reference</span> </li><li> <span class="docs-breadcrumbs-sep" aria-hidden="true">/</span> <span aria-current="page">Value wrappers</span> </li> </ol> </nav>  <article class="prose">  <h1 id="value-wrappers">Value wrappers</h1>
+<p>The simulator and the sentinel expression engine model Firestore’s runtime types as TypeScript classes. Every wrapper extends <code>RulesValue</code>, exposes <code>equals</code>, <code>toJSON</code>, and <code>toString</code>, and dispatches method calls via <code>callMethod</code>. These classes are engine-internal, importable from <code>pyric/rules/internal</code>.</p>
+<p>Most callers don’t need the classes directly: <code>pyric/rules</code>’s public value helpers (<code>serverTimestamp()</code>, <code>timestamp()</code>, <code>bytes()</code>, <code>latlng()</code>, <code>duration()</code>, <code>reference()</code>, <code>vector()</code>) construct the right wrapper instance for a <code>FirestoreCase</code>’s <code>data</code> / <code>resource</code> field. See <a href="../pyric-rules-reference-api/">Public API</a>.</p>
+<p>You reach for the classes on <code>pyric/rules/internal</code> directly when:</p>
+<ul>
+<li>Building a <code>SimulationContext</code> by hand (custom evaluator).</li>
+<li>Walking results from <code>evaluate()</code> and deciding what to do with them.</li>
+<li>Writing your own wrapper for a type the built-ins don’t model.</li>
+</ul>
+<h2 id="rulesvalue-base-class"><code>RulesValue</code> (base class)</h2>
+<pre class="astro-code one-dark-pro" style="background-color:#282c34;color:#abb2bf; overflow-x: auto;" tabindex="0" data-language="ts"><code><span class="line"><span style="color:#C678DD">abstract</span><span style="color:#C678DD"> class</span><span style="color:#E5C07B"> RulesValue</span><span style="color:#ABB2BF"> {</span></span>
+<span class="line"><span style="color:#C678DD">  readonly</span><span style="color:#E06C75"> typeName</span><span style="color:#ABB2BF">: </span><span style="color:#E5C07B">string</span><span style="color:#ABB2BF">;</span></span>
+<span class="line"><span style="color:#61AFEF">  callMethod</span><span style="color:#ABB2BF">(</span><span style="color:#E06C75;font-style:italic">method</span><span style="color:#ABB2BF">: </span><span style="color:#E5C07B">string</span><span style="color:#ABB2BF">, </span><span style="color:#E06C75;font-style:italic">args</span><span style="color:#ABB2BF">: </span><span style="color:#E5C07B">unknown</span><span style="color:#ABB2BF">[]): </span><span style="color:#E5C07B">unknown</span><span style="color:#ABB2BF"> | </span><span style="color:#E5C07B">NoOp</span><span style="color:#ABB2BF">;</span></span>
+<span class="line"><span style="color:#61AFEF">  binaryOp</span><span style="color:#C678DD">?</span><span style="color:#ABB2BF">(</span><span style="color:#E06C75;font-style:italic">op</span><span style="color:#ABB2BF">: </span><span style="color:#E5C07B">string</span><span style="color:#ABB2BF">, </span><span style="color:#E06C75;font-style:italic">other</span><span style="color:#ABB2BF">: </span><span style="color:#E5C07B">unknown</span><span style="color:#ABB2BF">): </span><span style="color:#E5C07B">unknown</span><span style="color:#ABB2BF"> | </span><span style="color:#E5C07B">NoOp</span><span style="color:#ABB2BF">;</span></span>
+<span class="line"><span style="color:#61AFEF">  equals</span><span style="color:#ABB2BF">(</span><span style="color:#E06C75;font-style:italic">other</span><span style="color:#ABB2BF">: </span><span style="color:#E5C07B">unknown</span><span style="color:#ABB2BF">): </span><span style="color:#E5C07B">boolean</span><span style="color:#ABB2BF">;</span></span>
+<span class="line"><span style="color:#61AFEF">  toJSON</span><span style="color:#ABB2BF">(): </span><span style="color:#E5C07B">unknown</span><span style="color:#ABB2BF">;</span></span>
+<span class="line"><span style="color:#61AFEF">  toString</span><span style="color:#ABB2BF">(): </span><span style="color:#E5C07B">string</span><span style="color:#ABB2BF">;</span></span>
+<span class="line"><span style="color:#ABB2BF">}</span></span></code></pre>
+<p><code>NO_OP</code> is the sentinel returned from <code>callMethod</code> and <code>binaryOp</code> when a wrapper doesn’t implement a method or operation. The evaluator translates <code>NO_OP</code> into an <code>UnsupportedError</code>, which the handler maps to <code>state: 'UNSUPPORTED'</code>.</p>
+<h2 id="timestamp"><code>Timestamp</code></h2>
+<p>Wraps <code>request.time</code>, <code>getAfter()</code> timestamps, and any field value that was <code>FieldValue.serverTimestamp()</code> in the request payload.</p>
+<pre class="astro-code one-dark-pro" style="background-color:#282c34;color:#abb2bf; overflow-x: auto;" tabindex="0" data-language="ts"><code><span class="line"><span style="color:#C678DD">class</span><span style="color:#E5C07B"> Timestamp</span><span style="color:#C678DD"> extends</span><span style="color:#E5C07B"> RulesValue</span><span style="color:#ABB2BF"> {</span></span>
+<span class="line"><span style="color:#C678DD">  readonly</span><span style="color:#E06C75"> seconds</span><span style="color:#ABB2BF">: </span><span style="color:#E5C07B">number</span><span style="color:#ABB2BF">;</span></span>
+<span class="line"><span style="color:#C678DD">  readonly</span><span style="color:#E06C75"> nanos</span><span style="color:#ABB2BF">: </span><span style="color:#E5C07B">number</span><span style="color:#ABB2BF">;</span></span>
+<span class="line"></span>
+<span class="line"><span style="color:#C678DD">  static</span><span style="color:#61AFEF"> fromMillis</span><span style="color:#ABB2BF">(</span><span style="color:#E06C75;font-style:italic">ms</span><span style="color:#ABB2BF">: </span><span style="color:#E5C07B">number</span><span style="color:#ABB2BF">): </span><span style="color:#E5C07B">Timestamp</span><span style="color:#ABB2BF">;</span></span>
+<span class="line"><span style="color:#C678DD">  static</span><span style="color:#61AFEF"> fromYMD</span><span style="color:#ABB2BF">(</span><span style="color:#E06C75;font-style:italic">year</span><span style="color:#ABB2BF">: </span><span style="color:#E5C07B">number</span><span style="color:#ABB2BF">, </span><span style="color:#E06C75;font-style:italic">month</span><span style="color:#ABB2BF">: </span><span style="color:#E5C07B">number</span><span style="color:#ABB2BF">, </span><span style="color:#E06C75;font-style:italic">day</span><span style="color:#ABB2BF">: </span><span style="color:#E5C07B">number</span><span style="color:#ABB2BF">): </span><span style="color:#E5C07B">Timestamp</span><span style="color:#ABB2BF">;  </span><span style="color:#7F848E;font-style:italic">// timestamp.date(y, m, d) — 1-based month</span></span>
+<span class="line"><span style="color:#C678DD">  static</span><span style="color:#61AFEF"> fromIsoString</span><span style="color:#ABB2BF">(</span><span style="color:#E06C75;font-style:italic">iso</span><span style="color:#ABB2BF">: </span><span style="color:#E5C07B">string</span><span style="color:#ABB2BF">): </span><span style="color:#E5C07B">Timestamp</span><span style="color:#ABB2BF">;</span></span>
+<span class="line"></span>
+<span class="line"><span style="color:#61AFEF">  toMillis</span><span style="color:#ABB2BF">(): </span><span style="color:#E5C07B">number</span><span style="color:#ABB2BF">;</span></span>
+<span class="line"><span style="color:#ABB2BF">}</span></span></code></pre>
+<p>Methods exposed to rules (via <code>callMethod</code>): <code>date</code>, <code>day</code>, <code>dayOfWeek</code>, <code>dayOfYear</code>, <code>hours</code>, <code>minutes</code>, <code>month</code>, <code>nanos</code>, <code>seconds</code>, <code>time</code>, <code>toMillis</code>, <code>year</code>.</p>
+<p>Binary ops: <code>==</code>, <code>!=</code>, <code>&#x3C;</code>, <code>&#x3C;=</code>, <code>></code>, <code>>=</code> against another <code>Timestamp</code>; <code>+</code>/<code>-</code> against a <code>Duration</code> returning a new <code>Timestamp</code>; <code>-</code> against another <code>Timestamp</code> returning a <code>Duration</code>.</p>
+<p>Internal storage uses signed <code>seconds</code> and non-negative <code>nanos</code> (protobuf convention). <code>equals</code> is a field-compare: two timestamps with the same epoch but different sub-second precision are equal only if both <code>seconds</code> and <code>nanos</code> match.</p>
+<h2 id="path"><code>Path</code></h2>
+<p>Wraps <code>request.path</code>, <code>__name__</code>, and path literals constructed from <code>path(...)</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">class</span><span style="color:#E5C07B"> Path</span><span style="color:#C678DD"> extends</span><span style="color:#E5C07B"> RulesValue</span><span style="color:#ABB2BF"> {</span></span>
+<span class="line"><span style="color:#C678DD">  readonly</span><span style="color:#E06C75"> segments</span><span style="color:#ABB2BF">: </span><span style="color:#C678DD">readonly</span><span style="color:#E5C07B"> string</span><span style="color:#ABB2BF">[];</span></span>
+<span class="line"><span style="color:#C678DD">  readonly</span><span style="color:#E06C75"> bindings</span><span style="color:#ABB2BF">: </span><span style="color:#E5C07B">Readonly</span><span style="color:#ABB2BF">&#x3C;</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">string</span><span style="color:#ABB2BF">>>;</span></span>
+<span class="line"></span>
+<span class="line"><span style="color:#C678DD">  static</span><span style="color:#61AFEF"> fromString</span><span style="color:#ABB2BF">(</span><span style="color:#E06C75;font-style:italic">s</span><span style="color:#ABB2BF">: </span><span style="color:#E5C07B">string</span><span style="color:#ABB2BF">): </span><span style="color:#E5C07B">Path</span><span style="color:#ABB2BF">;</span></span>
+<span class="line"></span>
+<span class="line"><span style="color:#61AFEF">  bind</span><span style="color:#ABB2BF">(</span><span style="color:#E06C75;font-style:italic">bindings</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">Path</span><span style="color:#ABB2BF">;</span></span>
+<span class="line"><span style="color:#61AFEF">  field</span><span style="color:#ABB2BF">(</span><span style="color:#E06C75;font-style:italic">name</span><span style="color:#ABB2BF">: </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:#7F848E;font-style:italic">// named-binding access</span></span>
+<span class="line"><span style="color:#ABB2BF">}</span></span></code></pre>
+<p>Methods: standard accessors. <code>bindings</code> is the wildcard map from the matched path pattern. <code>request.path.&#x3C;name></code> returns <code>bindings[name]</code> for <code>&#x3C;name></code> that was a wildcard in the match path. Without bindings, named-field access returns <code>null</code>.</p>
+<h2 id="reference"><code>Reference</code></h2>
+<p>Wraps DocumentReference values inside test data.</p>
+<pre class="astro-code one-dark-pro" style="background-color:#282c34;color:#abb2bf; overflow-x: auto;" tabindex="0" data-language="ts"><code><span class="line"><span style="color:#C678DD">class</span><span style="color:#E5C07B"> Reference</span><span style="color:#C678DD"> extends</span><span style="color:#E5C07B"> RulesValue</span><span style="color:#ABB2BF"> {</span></span>
+<span class="line"><span style="color:#C678DD">  readonly</span><span style="color:#E06C75"> path</span><span style="color:#ABB2BF">: </span><span style="color:#E5C07B">Path</span><span style="color:#ABB2BF">;</span></span>
+<span class="line"><span style="color:#ABB2BF">}</span></span>
+<span class="line"></span>
+<span class="line"><span style="color:#C678DD">function</span><span style="color:#61AFEF"> referenceToResourceName</span><span style="color:#ABB2BF">(</span><span style="color:#E06C75;font-style:italic">ref</span><span style="color:#ABB2BF">: </span><span style="color:#E5C07B">Reference</span><span style="color:#ABB2BF">): </span><span style="color:#E5C07B">string</span><span style="color:#ABB2BF">;</span></span></code></pre>
+<p>Use <code>referenceToResourceName</code> to get the full <code>/databases/.../documents/...</code> form when calling the Rules Test API.</p>
+<h2 id="duration"><code>Duration</code></h2>
+<p>Wraps <code>request.time - resource.data.&#x3C;ts></code> results and <code>duration.value(n, 'h')</code> constructions.</p>
+<pre class="astro-code one-dark-pro" style="background-color:#282c34;color:#abb2bf; overflow-x: auto;" tabindex="0" data-language="ts"><code><span class="line"><span style="color:#C678DD">class</span><span style="color:#E5C07B"> Duration</span><span style="color:#C678DD"> extends</span><span style="color:#E5C07B"> RulesValue</span><span style="color:#ABB2BF"> {</span></span>
+<span class="line"><span style="color:#C678DD">  readonly</span><span style="color:#E06C75"> seconds</span><span style="color:#ABB2BF">: </span><span style="color:#E5C07B">number</span><span style="color:#ABB2BF">;</span></span>
+<span class="line"><span style="color:#C678DD">  readonly</span><span style="color:#E06C75"> nanos</span><span style="color:#ABB2BF">: </span><span style="color:#E5C07B">number</span><span style="color:#ABB2BF">;</span></span>
+<span class="line"></span>
+<span class="line"><span style="color:#C678DD">  static</span><span style="color:#61AFEF"> fromValue</span><span style="color:#ABB2BF">(</span><span style="color:#E06C75;font-style:italic">magnitude</span><span style="color:#ABB2BF">: </span><span style="color:#E5C07B">number</span><span style="color:#ABB2BF">, </span><span style="color:#E06C75;font-style:italic">unit</span><span style="color:#ABB2BF">: </span><span style="color:#E5C07B">string</span><span style="color:#ABB2BF">): </span><span style="color:#E5C07B">Duration</span><span style="color:#ABB2BF">;   </span><span style="color:#7F848E;font-style:italic">// duration.value(n, 'd'|'h'|'m'|'s'|'ms')</span></span>
+<span class="line"><span style="color:#C678DD">  static</span><span style="color:#61AFEF"> fromTime</span><span style="color:#ABB2BF">(</span><span style="color:#E06C75;font-style:italic">h</span><span style="color:#ABB2BF">: </span><span style="color:#E5C07B">number</span><span style="color:#ABB2BF">, </span><span style="color:#E06C75;font-style:italic">m</span><span style="color:#ABB2BF">: </span><span style="color:#E5C07B">number</span><span style="color:#ABB2BF">, </span><span style="color:#E06C75;font-style:italic">s</span><span style="color:#ABB2BF">: </span><span style="color:#E5C07B">number</span><span style="color:#ABB2BF">, </span><span style="color:#E06C75;font-style:italic">ns</span><span style="color:#ABB2BF">: </span><span style="color:#E5C07B">number</span><span style="color:#ABB2BF">): </span><span style="color:#E5C07B">Duration</span><span style="color:#ABB2BF">;</span></span>
+<span class="line"><span style="color:#C678DD">  static</span><span style="color:#61AFEF"> abs</span><span style="color:#ABB2BF">(</span><span style="color:#E06C75;font-style:italic">d</span><span style="color:#ABB2BF">: </span><span style="color:#E5C07B">Duration</span><span style="color:#ABB2BF">): </span><span style="color:#E5C07B">Duration</span><span style="color:#ABB2BF">;</span></span>
+<span class="line"><span style="color:#ABB2BF">}</span></span></code></pre>
+<p>Unit codes for <code>fromValue</code>: <code>'w'</code>, <code>'d'</code>, <code>'h'</code>, <code>'m'</code>, <code>'s'</code>, <code>'ms'</code>. Binary ops mirror <code>Timestamp</code>’s.</p>
+<h2 id="bytes"><code>Bytes</code></h2>
+<p>Wraps <code>bytes</code> values.</p>
+<pre class="astro-code one-dark-pro" style="background-color:#282c34;color:#abb2bf; overflow-x: auto;" tabindex="0" data-language="ts"><code><span class="line"><span style="color:#C678DD">class</span><span style="color:#E5C07B"> Bytes</span><span style="color:#C678DD"> extends</span><span style="color:#E5C07B"> RulesValue</span><span style="color:#ABB2BF"> {</span></span>
+<span class="line"><span style="color:#C678DD">  readonly</span><span style="color:#E06C75"> data</span><span style="color:#ABB2BF">: </span><span style="color:#E5C07B">Uint8Array</span><span style="color:#ABB2BF">;</span></span>
+<span class="line"></span>
+<span class="line"><span style="color:#C678DD">  static</span><span style="color:#61AFEF"> fromUtf8</span><span style="color:#ABB2BF">(</span><span style="color:#E06C75;font-style:italic">s</span><span style="color:#ABB2BF">: </span><span style="color:#E5C07B">string</span><span style="color:#ABB2BF">): </span><span style="color:#E5C07B">Bytes</span><span style="color:#ABB2BF">;</span></span>
+<span class="line"><span style="color:#C678DD">  static</span><span style="color:#61AFEF"> fromHex</span><span style="color:#ABB2BF">(</span><span style="color:#E06C75;font-style:italic">hex</span><span style="color:#ABB2BF">: </span><span style="color:#E5C07B">string</span><span style="color:#ABB2BF">): </span><span style="color:#E5C07B">Bytes</span><span style="color:#ABB2BF">;</span></span>
+<span class="line"></span>
+<span class="line"><span style="color:#61AFEF">  size</span><span style="color:#ABB2BF">(): </span><span style="color:#E5C07B">number</span><span style="color:#ABB2BF">;</span></span>
+<span class="line"><span style="color:#61AFEF">  toBase64</span><span style="color:#ABB2BF">(): </span><span style="color:#E5C07B">string</span><span style="color:#ABB2BF">;      </span><span style="color:#7F848E;font-style:italic">// URL-safe, no padding</span></span>
+<span class="line"><span style="color:#61AFEF">  toHexString</span><span style="color:#ABB2BF">(): </span><span style="color:#E5C07B">string</span><span style="color:#ABB2BF">;</span></span>
+<span class="line"><span style="color:#ABB2BF">}</span></span></code></pre>
+<p>Slice access (<code>bytes[start:end]</code>) is supported via <code>sliceAccess</code> expressions and produces a new <code>Bytes</code>.</p>
+<h2 id="latlng"><code>LatLng</code></h2>
+<p>Wraps geo-point values.</p>
+<pre class="astro-code one-dark-pro" style="background-color:#282c34;color:#abb2bf; overflow-x: auto;" tabindex="0" data-language="ts"><code><span class="line"><span style="color:#C678DD">class</span><span style="color:#E5C07B"> LatLng</span><span style="color:#C678DD"> extends</span><span style="color:#E5C07B"> RulesValue</span><span style="color:#ABB2BF"> {</span></span>
+<span class="line"><span style="color:#C678DD">  readonly</span><span style="color:#E06C75"> lat</span><span style="color:#ABB2BF">: </span><span style="color:#E5C07B">number</span><span style="color:#ABB2BF">;</span></span>
+<span class="line"><span style="color:#C678DD">  readonly</span><span style="color:#E06C75"> lng</span><span style="color:#ABB2BF">: </span><span style="color:#E5C07B">number</span><span style="color:#ABB2BF">;</span></span>
+<span class="line"></span>
+<span class="line"><span style="color:#C678DD">  constructor</span><span style="color:#ABB2BF">(</span><span style="color:#E06C75;font-style:italic">lat</span><span style="color:#ABB2BF">: </span><span style="color:#E5C07B">number</span><span style="color:#ABB2BF">, </span><span style="color:#E06C75;font-style:italic">lng</span><span style="color:#ABB2BF">: </span><span style="color:#E5C07B">number</span><span style="color:#ABB2BF">);</span></span>
+<span class="line"></span>
+<span class="line"><span style="color:#7F848E;font-style:italic">  // distance(other) returns metres via the haversine formula.</span></span>
+<span class="line"><span style="color:#ABB2BF">}</span></span></code></pre>
+<h2 id="vector"><code>Vector</code></h2>
+<p>Wraps embedding vectors.</p>
+<pre class="astro-code one-dark-pro" style="background-color:#282c34;color:#abb2bf; overflow-x: auto;" tabindex="0" data-language="ts"><code><span class="line"><span style="color:#C678DD">class</span><span style="color:#E5C07B"> Vector</span><span style="color:#C678DD"> extends</span><span style="color:#E5C07B"> RulesValue</span><span style="color:#ABB2BF"> {</span></span>
+<span class="line"><span style="color:#C678DD">  readonly</span><span style="color:#E06C75"> values</span><span style="color:#ABB2BF">: </span><span style="color:#C678DD">readonly</span><span style="color:#E5C07B"> number</span><span style="color:#ABB2BF">[];</span></span>
+<span class="line"><span style="color:#ABB2BF">}</span></span></code></pre>
+<h2 id="rulesvalue-and-no_op"><code>RulesValue</code> and <code>NO_OP</code></h2>
+<p>Exported for callers writing custom wrappers. To add support for a new type:</p>
+<ol>
+<li>Extend <code>RulesValue</code>.</li>
+<li>Set <code>typeName</code> to the lowercase namespace identifier (<code>'reference'</code>, <code>'timestamp'</code>, …).</li>
+<li>Implement <code>callMethod</code> returning <code>NO_OP</code> for unsupported methods.</li>
+<li>Implement <code>binaryOp</code> if your type participates in arithmetic or comparison.</li>
+<li>Implement <code>equals</code> for cross-type equality (default is reference equality).</li>
+</ol>  </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="#rulesvalue-base-class">RulesValue (base class)</a> </li><li data-depth="2"> <a href="#timestamp">Timestamp</a> </li><li data-depth="2"> <a href="#path">Path</a> </li><li data-depth="2"> <a href="#reference">Reference</a> </li><li data-depth="2"> <a href="#duration">Duration</a> </li><li data-depth="2"> <a href="#bytes">Bytes</a> </li><li data-depth="2"> <a href="#latlng">LatLng</a> </li><li data-depth="2"> <a href="#vector">Vector</a> </li><li data-depth="2"> <a href="#rulesvalue-and-no_op">RulesValue and NO_OP</a> </li> </ul> </aside> </div> <script type="module">const a=document.querySelector("[data-api-symbol-filter]"),d=[...document.querySelectorAll("[data-api-symbol-group]")],n=document.querySelector("[data-api-symbol-empty]");a?.addEventListener("input",()=>{const t=a.value.trim().toLowerCase();let o=0;for(const i of d){let e=0;i.querySelectorAll("[data-api-symbol]").forEach(l=>{const r=!t||(l.dataset.apiSymbol??"").includes(t);l.hidden=!r,r&&e++}),i.hidden=e===0,o+=e}n&&(n.hidden=o>0)});</script> <script type="module">const s=new Map;document.querySelectorAll('.doc-toc a[href^="#"]').forEach(t=>s.set(decodeURIComponent(t.hash.slice(1)),t));if(s.size>0){const t=new Set,n=()=>{let o=null;for(const e of s.keys())if(t.has(e)){o=e;break}s.forEach((e,c)=>e.classList.toggle("active",c===o))},r=new IntersectionObserver(o=>{for(const e of o)e.isIntersecting?t.add(e.target.id):t.delete(e.target.id);n()},{rootMargin:"-72px 0px -60% 0px"});s.forEach((o,e)=>{const c=document.getElementById(e);c&&r.observe(c)})}</script> <script type="module">document.querySelector('.studio__nav [aria-current="page"]')?.scrollIntoView({block:"nearest",inline:"center"});</script> </body> </html>

package/dist/serve/docs-ui/docs/pyric-rules-reference-value-wrappers.md ADDED Viewed

@@ -0,0 +1,152 @@
+# Value wrappers
+The simulator and the sentinel expression engine model Firestore's runtime types as TypeScript classes. Every wrapper extends `RulesValue`, exposes `equals`, `toJSON`, and `toString`, and dispatches method calls via `callMethod`. These classes are engine-internal, importable from `pyric/rules/internal`.
+Most callers don't need the classes directly: `pyric/rules`'s public value helpers (`serverTimestamp()`, `timestamp()`, `bytes()`, `latlng()`, `duration()`, `reference()`, `vector()`) construct the right wrapper instance for a `FirestoreCase`'s `data` / `resource` field. See [Public API](../pyric-rules-reference-api/).
+You reach for the classes on `pyric/rules/internal` directly when:
+- Building a `SimulationContext` by hand (custom evaluator).
+- Walking results from `evaluate()` and deciding what to do with them.
+- Writing your own wrapper for a type the built-ins don't model.
+## `RulesValue` (base class)
+```ts
+abstract class RulesValue {
+  readonly typeName: string;
+  callMethod(method: string, args: unknown[]): unknown | NoOp;
+  binaryOp?(op: string, other: unknown): unknown | NoOp;
+  equals(other: unknown): boolean;
+  toJSON(): unknown;
+  toString(): string;
+}
+```
+`NO_OP` is the sentinel returned from `callMethod` and `binaryOp` when a wrapper doesn't implement a method or operation. The evaluator translates `NO_OP` into an `UnsupportedError`, which the handler maps to `state: 'UNSUPPORTED'`.
+## `Timestamp`
+Wraps `request.time`, `getAfter()` timestamps, and any field value that was `FieldValue.serverTimestamp()` in the request payload.
+```ts
+class Timestamp extends RulesValue {
+  readonly seconds: number;
+  readonly nanos: number;
+  static fromMillis(ms: number): Timestamp;
+  static fromYMD(year: number, month: number, day: number): Timestamp;  // timestamp.date(y, m, d) — 1-based month
+  static fromIsoString(iso: string): Timestamp;
+  toMillis(): number;
+}
+```
+Methods exposed to rules (via `callMethod`): `date`, `day`, `dayOfWeek`, `dayOfYear`, `hours`, `minutes`, `month`, `nanos`, `seconds`, `time`, `toMillis`, `year`.
+Binary ops: `==`, `!=`, `<`, `<=`, `>`, `>=` against another `Timestamp`; `+`/`-` against a `Duration` returning a new `Timestamp`; `-` against another `Timestamp` returning a `Duration`.
+Internal storage uses signed `seconds` and non-negative `nanos` (protobuf convention). `equals` is a field-compare: two timestamps with the same epoch but different sub-second precision are equal only if both `seconds` and `nanos` match.
+## `Path`
+Wraps `request.path`, `__name__`, and path literals constructed from `path(...)`.
+```ts
+class Path extends RulesValue {
+  readonly segments: readonly string[];
+  readonly bindings: Readonly<Record<string, string>>;
+  static fromString(s: string): Path;
+  bind(bindings: Record<string, unknown>): Path;
+  field(name: string): unknown;                 // named-binding access
+}
+```
+Methods: standard accessors. `bindings` is the wildcard map from the matched path pattern. `request.path.<name>` returns `bindings[name]` for `<name>` that was a wildcard in the match path. Without bindings, named-field access returns `null`.
+## `Reference`
+Wraps DocumentReference values inside test data.
+```ts
+class Reference extends RulesValue {
+  readonly path: Path;
+}
+function referenceToResourceName(ref: Reference): string;
+```
+Use `referenceToResourceName` to get the full `/databases/.../documents/...` form when calling the Rules Test API.
+## `Duration`
+Wraps `request.time - resource.data.<ts>` results and `duration.value(n, 'h')` constructions.
+```ts
+class Duration extends RulesValue {
+  readonly seconds: number;
+  readonly nanos: number;
+  static fromValue(magnitude: number, unit: string): Duration;   // duration.value(n, 'd'|'h'|'m'|'s'|'ms')
+  static fromTime(h: number, m: number, s: number, ns: number): Duration;
+  static abs(d: Duration): Duration;
+}
+```
+Unit codes for `fromValue`: `'w'`, `'d'`, `'h'`, `'m'`, `'s'`, `'ms'`. Binary ops mirror `Timestamp`'s.
+## `Bytes`
+Wraps `bytes` values.
+```ts
+class Bytes extends RulesValue {
+  readonly data: Uint8Array;
+  static fromUtf8(s: string): Bytes;
+  static fromHex(hex: string): Bytes;
+  size(): number;
+  toBase64(): string;      // URL-safe, no padding
+  toHexString(): string;
+}
+```
+Slice access (`bytes[start:end]`) is supported via `sliceAccess` expressions and produces a new `Bytes`.
+## `LatLng`
+Wraps geo-point values.
+```ts
+class LatLng extends RulesValue {
+  readonly lat: number;
+  readonly lng: number;
+  constructor(lat: number, lng: number);
+  // distance(other) returns metres via the haversine formula.
+}
+```
+## `Vector`
+Wraps embedding vectors.
+```ts
+class Vector extends RulesValue {
+  readonly values: readonly number[];
+}
+```
+## `RulesValue` and `NO_OP`
+Exported for callers writing custom wrappers. To add support for a new type:
+1. Extend `RulesValue`.
+2. Set `typeName` to the lowercase namespace identifier (`'reference'`, `'timestamp'`, …).
+3. Implement `callMethod` returning `NO_OP` for unsupported methods.
+4. Implement `binaryOp` if your type participates in arithmetic or comparison.
+5. Implement `equals` for cross-type equality (default is reference equality).

package/dist/serve/docs-ui/docs/pyric-rules.md ADDED Viewed

@@ -0,0 +1,93 @@
+# `pyric/rules`
+Pyric-native Firestore Security Rules tooling. A browser-safe parser, linter, modules resolver, in-process simulator, and Rules Test API client, packaged so the data-plane swap-in (`pyric/firestore`) stays minimal.
+The surface is grouped around the things you can do with a rules source:
+- **Parse** it into a typed AST you can walk.
+- **Lint** it for compilation limits, runtime-budget risks, and known agent failure modes.
+- **Validate** it for security and quality findings (`SEC-1` … `STR-3`).
+- **Resolve** `2+modules` imports against a stdlib of reusable functions.
+- **Simulate** it locally against test cases. No network, no propagation wait.
+- **Test** it against the live Firebase Rules Test API.
+- **Wrap** it in agent-tool factories for `@inbrowser/agent` registries.
+Parse, Lint, Validate, Simulate, and Test all sit behind the public front door: `firestoreRules`, `rtdbRules`, `lint`, `assertCase`, and `explainCase`. The parser, linter, validator, simulator, modules resolver, and agent-tool factories are internal engine seams, exposed only under `pyric/rules/internal*` for callers that need them directly. They may change without notice.
+## Install
+```bash
+bun add pyric
+# or
+npm install pyric
+```
+## A 30-second example
+```ts
+import { firestoreRules } from 'pyric/rules';
+const source = `rules_version = '2';
+service cloud.firestore {
+  match /databases/{db}/documents {
+    match /notes/{id} {
+      allow read: if request.auth != null;
+      allow write: if request.auth.uid == resource.data.ownerId;
+    }
+  }
+}`;
+const ruleset = firestoreRules(source);
+console.log(ruleset.lint()); // []
+const { passed, failed } = ruleset.simulate([
+  {
+    description: 'authed read is allowed',
+    expectation: 'ALLOW',
+    method: 'get',
+    path: 'notes/n1',
+    auth: { uid: 'alice' },
+  },
+]);
+console.log(passed, failed); // 1 0
+```
+`firestoreRules(source)` throws `RulesCompileError` if the source doesn't parse. `simulate` never throws on rule outcomes; failures and unsupported cases come back in the result, not as exceptions.
+The RTDB constraints DSL (`defineRtdbRules`, `ruleset`, `schemaRules`, and the combinators) is public and lives on the same root entry:
+```ts
+import { rtdbRules, defineRtdbRules, ruleset, allow } from 'pyric/rules';
+```
+The parser, validator, simulator internals, modules resolver, and agent-tool factories live on `pyric/rules/internal` and `pyric/rules/internal/node`. They're not part of the public contract:
+```ts
+import { resolveModules, createFirestoreRulesTools } from 'pyric/rules/internal/node';
+```
+## Where to go next
+Documentation is organised under [`docs/`](../pyric-rules/) following the [Diataxis](https://diataxis.fr/) framework:
+| If you want to | Read |
+|---|---|
+| Learn the package by following a complete lesson | Tutorials |
+| Accomplish a specific task | How-to guides |
+| Look up an exact symbol, lint rule, or schema | Reference |
+| Understand why the package is shaped this way | Explanation |
+### Starting points by role
+- **First time here?** Work through [Lint your first rules file](../simulate-and-lint/), then [Write a test suite for your rules](../write-a-rules-test-suite/).
+- **Building an agent or CLI?** See [Register rules tools with an agent](../pyric-rules-how-to-register-tools-with-an-agent/) and the [`pyric/rules` API reference](https://pyric.dev/docs/pyric-rules-reference-api/).
+- **Triaging a lint warning?** Jump to [Lint rules reference](../pyric-rules-reference-lint-rules/).
+- **Debugging an `UNSUPPORTED` test result?** Read [Simulator vs Rules Test API](../pyric-rules-explanation-simulator-vs-rules-test-api/).
+## Position in the Pyric stack
+`pyric/rules` is the **rules-tooling** sibling of `pyric/firestore` (the modular Web-SDK swap-in). The split is deliberate: the data-plane swap-in must mirror the production Firestore surface and nothing more. Anything that is *about* rules (parsing them, linting them, simulating them) lives here. See [Why this package exists](../pyric-rules-explanation-why-this-package-exists/) for the longer story.
+## Licence
+Same as the parent workspace.