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-sandbox-reference-divergences/index.html ADDED Viewed

@@ -0,0 +1,125 @@
+<!DOCTYPE html><html lang="en"> <head><meta charset="UTF-8"><meta name="viewport" content="width=device-width, initial-scale=1.0"><title>Divergence · 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/" aria-current="true"> 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/"> pyric / rules </a> </li><li> <a href="/__pyric/ui/docs/pyric-sandbox/" aria-current="true"> 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-sandbox/">pyric / sandbox</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">Divergence</span> </li> </ol> </nav>  <article class="prose">  <h1 id="divergence"><code>Divergence</code></h1>
+<p>What <code>replay(events, rules, opts, originalState)</code> returns when the replayed state doesn’t perfectly match the captured state. A discriminated union; filter on <code>kind</code> to handle each case.</p>
+<h2 id="what-is-a-divergence">What is a divergence?</h2>
+<p>A divergence is a single classified difference between what the original sandbox stored and what the replayed sandbox produced after re-issuing every captured write.</p>
+<p>When the engine sees a difference, it tries to <em>explain</em> it from captured metadata (which fields had <code>FieldValue.*</code> sentinels, which paths came from auto-id minting, which <code>request.time</code> the rule engine evaluated against). Each explanation maps to a <code>kind</code>. If no explanation fits, the kind is <code>real-divergence</code>, the only kind that signals an actual bug. The other three are intentional by-design differences.</p>
+<p>Two design rules govern the classifier:</p>
+<ol>
+<li><strong>No shape inference.</strong> The engine never guesses based on what a value <em>looks</em> like. A timestamp-shaped object isn’t classified as <code>time-drift</code> unless the captured <code>sentinels[]</code> says it came from <code>serverTimestamp()</code>. Anything not licensed by captured metadata is <code>real-divergence</code>.</li>
+<li><strong>Leaf-precise.</strong> The engine walks both documents recursively and reports field paths at the leaf (<code>profile.lastSeen</code>, <code>tags[0]</code>, <code>arr[2].nested</code>). A sentinel-bearing parent doesn’t mask sibling changes.</li>
+</ol>
+<h2 id="the-union">The union</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">type</span><span style="color:#E5C07B"> Divergence</span><span style="color:#56B6C2"> =</span></span>
+<span class="line"><span style="color:#ABB2BF">  | {</span></span>
+<span class="line"><span style="color:#E06C75">      kind</span><span style="color:#ABB2BF">: </span><span style="color:#98C379">'sentinel-drift'</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">      field</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">      sentinelKind</span><span style="color:#ABB2BF">: </span><span style="color:#98C379">'serverTimestamp'</span><span style="color:#ABB2BF"> | </span><span style="color:#98C379">'increment'</span><span style="color:#ABB2BF"> | </span><span style="color:#98C379">'arrayUnion'</span><span style="color:#ABB2BF"> | </span><span style="color:#98C379">'arrayRemove'</span><span style="color:#ABB2BF"> | </span><span style="color:#98C379">'delete'</span><span style="color:#ABB2BF">;</span></span>
+<span class="line"><span style="color:#E06C75">      before</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">      after</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>
+<span class="line"><span style="color:#ABB2BF">  | { </span><span style="color:#E06C75">kind</span><span style="color:#ABB2BF">: </span><span style="color:#98C379">'autoid-alias'</span><span style="color:#ABB2BF">; </span><span style="color:#E06C75">originalPath</span><span style="color:#ABB2BF">: </span><span style="color:#E5C07B">string</span><span style="color:#ABB2BF">; </span><span style="color:#E06C75">replayedPath</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 style="color:#E06C75">kind</span><span style="color:#ABB2BF">: </span><span style="color:#98C379">'time-drift'</span><span style="color:#ABB2BF">;     </span><span style="color:#E06C75">path</span><span style="color:#ABB2BF">: </span><span style="color:#E5C07B">string</span><span style="color:#ABB2BF">; </span><span style="color:#E06C75">field</span><span style="color:#ABB2BF">: </span><span style="color:#E5C07B">string</span><span style="color:#ABB2BF">;  </span><span style="color:#E06C75">before</span><span style="color:#ABB2BF">: </span><span style="color:#E5C07B">unknown</span><span style="color:#ABB2BF">; </span><span style="color:#E06C75">after</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 style="color:#E06C75">kind</span><span style="color:#ABB2BF">: </span><span style="color:#98C379">'real-divergence'</span><span style="color:#ABB2BF">;</span><span style="color:#E06C75">path</span><span style="color:#ABB2BF">: </span><span style="color:#E5C07B">string</span><span style="color:#ABB2BF">; </span><span style="color:#E06C75">field</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">before</span><span style="color:#ABB2BF">: </span><span style="color:#E5C07B">unknown</span><span style="color:#ABB2BF">; </span><span style="color:#E06C75">after</span><span style="color:#ABB2BF">: </span><span style="color:#E5C07B">unknown</span><span style="color:#ABB2BF"> };</span></span></code></pre>
+<h2 id="kind-autoid-alias"><code>kind: 'autoid-alias'</code></h2>
+<p>A write that originated from <code>LocalEnvironment.createWithAutoId</code> minted a fresh document ID on replay: same content, different path.</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:#ABB2BF">{ </span><span style="color:#E06C75">kind</span><span style="color:#ABB2BF">: </span><span style="color:#98C379">'autoid-alias'</span><span style="color:#ABB2BF">, </span><span style="color:#E06C75">originalPath</span><span style="color:#ABB2BF">: </span><span style="color:#98C379">'notes/Iy5CGRl0HlP1XZo4GGiI'</span><span style="color:#ABB2BF">, </span><span style="color:#E06C75">replayedPath</span><span style="color:#ABB2BF">: </span><span style="color:#98C379">'notes/5MM3PdzWUQvqRCi3wthO'</span><span style="color:#ABB2BF"> }</span></span></code></pre>
+<p>Re-using the original ID would be incorrect: auto-id semantics include “the id is unique.” Two replays of the same log on different sandboxes legitimately mint different ids. The engine emits one alias entry per such write and exposes the full mapping on <code>ReplayResult.pathAliases</code> so consumers that index by path can map original → replayed.</p>
+<p>Not a bug. Consumers comparing document presence should consult <code>pathAliases</code> before flagging “missing doc.”</p>
+<h2 id="kind-sentinel-drift"><code>kind: 'sentinel-drift'</code></h2>
+<p>A captured <code>FieldValue.*</code> sentinel (other than <code>serverTimestamp</code>, which has its own kind) sits at this exact field path, and the subtree differs between original and replayed state.</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:#ABB2BF">{</span></span>
+<span class="line"><span style="color:#E06C75">  kind</span><span style="color:#ABB2BF">: </span><span style="color:#98C379">'sentinel-drift'</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">'counters/x'</span><span style="color:#ABB2BF">,</span></span>
+<span class="line"><span style="color:#E06C75">  field</span><span style="color:#ABB2BF">: </span><span style="color:#98C379">'count'</span><span style="color:#ABB2BF">,</span></span>
+<span class="line"><span style="color:#E06C75">  sentinelKind</span><span style="color:#ABB2BF">: </span><span style="color:#98C379">'increment'</span><span style="color:#ABB2BF">,</span></span>
+<span class="line"><span style="color:#E06C75">  before</span><span style="color:#ABB2BF">: </span><span style="color:#D19A66">5</span><span style="color:#ABB2BF">,</span></span>
+<span class="line"><span style="color:#E06C75">  after</span><span style="color:#ABB2BF">: </span><span style="color:#D19A66">7</span><span style="color:#ABB2BF">,</span></span>
+<span class="line"><span style="color:#ABB2BF">}</span></span></code></pre>
+<p>Usually means <strong>the prior state differed</strong>, not that the sentinel itself misbehaved. <code>increment</code>, <code>arrayUnion</code>, <code>arrayRemove</code>, and <code>deleteField</code> are deterministic given the same prior. If their result differs, the prior was different. Look for an upstream <code>real-divergence</code> that explains why.</p>
+<p>In practice, with the same captured stream replayed onto a fresh sandbox, sentinel-drift is rare. It surfaces most often when you replay onto state that <em>isn’t</em> the captured starting point (e.g., partial replays, splicing two logs).</p>
+<h2 id="kind-time-drift"><code>kind: 'time-drift'</code></h2>
+<p>A captured <code>serverTimestamp()</code> sentinel at this exact field path resolved to a different <code>Timestamp</code> on replay.</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:#ABB2BF">{</span></span>
+<span class="line"><span style="color:#E06C75">  kind</span><span style="color:#ABB2BF">: </span><span style="color:#98C379">'time-drift'</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">'notes/stamped'</span><span style="color:#ABB2BF">,</span></span>
+<span class="line"><span style="color:#E06C75">  field</span><span style="color:#ABB2BF">: </span><span style="color:#98C379">'ts'</span><span style="color:#ABB2BF">,</span></span>
+<span class="line"><span style="color:#E06C75">  before</span><span style="color:#ABB2BF">: { </span><span style="color:#E06C75">__type</span><span style="color:#ABB2BF">: </span><span style="color:#98C379">'timestamp'</span><span style="color:#ABB2BF">, </span><span style="color:#E06C75">seconds</span><span style="color:#ABB2BF">: </span><span style="color:#D19A66">1778955966</span><span style="color:#ABB2BF">, </span><span style="color:#E06C75">nanos</span><span style="color:#ABB2BF">: </span><span style="color:#D19A66">624000000</span><span style="color:#ABB2BF"> },</span></span>
+<span class="line"><span style="color:#E06C75">  after</span><span style="color:#ABB2BF">:  { </span><span style="color:#E06C75">__type</span><span style="color:#ABB2BF">: </span><span style="color:#98C379">'timestamp'</span><span style="color:#ABB2BF">, </span><span style="color:#E06C75">seconds</span><span style="color:#ABB2BF">: </span><span style="color:#D19A66">1778955966</span><span style="color:#ABB2BF">, </span><span style="color:#E06C75">nanos</span><span style="color:#ABB2BF">: </span><span style="color:#D19A66">657000000</span><span style="color:#ABB2BF"> },</span></span>
+<span class="line"><span style="color:#ABB2BF">}</span></span></code></pre>
+<p>Only fires when <code>pinRequestTime: false</code>. With the default <code>pinRequestTime: true</code>, the engine re-issues the captured <code>request.time</code> to the fresh sandbox so the sentinel resolves to the same value: zero <code>time-drift</code>.</p>
+<p>Not a bug. Useful for two scenarios:</p>
+<ul>
+<li><strong>Rules that branch on <code>request.time</code></strong>. Turn pinning off and see whether a captured stream that passed yesterday still passes today. If a rule like <code>allow write: if request.time >= timestamp.date(2024, 1, 1)</code> started failing, you’d see denied writes surface as <code>real-divergence</code> rather than <code>time-drift</code> (the time-drift signals “yes, time moved” without it being a bug).</li>
+<li><strong>Debugging “why is my serverTimestamp different”</strong>. The <code>before</code> / <code>after</code> values show exactly how far the clock drifted.</li>
+</ul>
+<h2 id="kind-real-divergence"><code>kind: 'real-divergence'</code></h2>
+<p>Anything else. Captured metadata doesn’t license this difference, so the engine flags it.</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:#ABB2BF">{</span></span>
+<span class="line"><span style="color:#E06C75">  kind</span><span style="color:#ABB2BF">: </span><span style="color:#98C379">'real-divergence'</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">'notes/x'</span><span style="color:#ABB2BF">,</span></span>
+<span class="line"><span style="color:#E06C75">  field</span><span style="color:#ABB2BF">: </span><span style="color:#98C379">'profile.name'</span><span style="color:#ABB2BF">,</span></span>
+<span class="line"><span style="color:#E06C75">  before</span><span style="color:#ABB2BF">: </span><span style="color:#98C379">'alice'</span><span style="color:#ABB2BF">,</span></span>
+<span class="line"><span style="color:#E06C75">  after</span><span style="color:#ABB2BF">: </span><span style="color:#98C379">'NOT-alice'</span><span style="color:#ABB2BF">,</span></span>
+<span class="line"><span style="color:#ABB2BF">}</span></span></code></pre>
+<p>The <code>field</code> may be absent. For example, when an entire document is present on one side and missing on the other, the path alone identifies the divergence:</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:#ABB2BF">{ </span><span style="color:#E06C75">kind</span><span style="color:#ABB2BF">: </span><span style="color:#98C379">'real-divergence'</span><span style="color:#ABB2BF">, </span><span style="color:#E06C75">path</span><span style="color:#ABB2BF">: </span><span style="color:#98C379">'notes/x'</span><span style="color:#ABB2BF">, </span><span style="color:#E06C75">before</span><span style="color:#ABB2BF">: { </span><span style="color:#7F848E;font-style:italic">/* doc */</span><span style="color:#ABB2BF"> }, </span><span style="color:#E06C75">after</span><span style="color:#ABB2BF">: </span><span style="color:#D19A66">undefined</span><span style="color:#ABB2BF"> }</span></span></code></pre>
+<p>This is the only kind that signals an actual bug. Common causes:</p>
+<ul>
+<li><strong>Rules changed between capture and replay</strong>: a write that succeeded originally gets denied; the doc is missing in replayed state.</li>
+<li><strong>A captured write hit a sandbox feature that isn’t deterministic</strong>: the engine’s contract says writes are deterministic given the same prior + rules + clock; if you see real-divergence on a clean replay, something is non-deterministic in the path you’re testing.</li>
+<li><strong>Replay state seeded incorrectly</strong>: if you persisted state separately from events and they drift apart, fields can disagree.</li>
+</ul>
+<h2 id="classifying-in-code">Classifying in code</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">for</span><span style="color:#ABB2BF"> (</span><span style="color:#C678DD">const</span><span style="color:#E5C07B"> d</span><span style="color:#C678DD"> of</span><span style="color:#E06C75"> divergences</span><span style="color:#ABB2BF">) {</span></span>
+<span class="line"><span style="color:#C678DD">  switch</span><span style="color:#ABB2BF"> (</span><span style="color:#E5C07B">d</span><span style="color:#ABB2BF">.</span><span style="color:#E06C75">kind</span><span style="color:#ABB2BF">) {</span></span>
+<span class="line"><span style="color:#C678DD">    case</span><span style="color:#98C379"> 'autoid-alias'</span><span style="color:#ABB2BF">:</span></span>
+<span class="line"><span style="color:#7F848E;font-style:italic">      // Intentional: map d.originalPath → d.replayedPath in your index.</span></span>
+<span class="line"><span style="color:#C678DD">      break</span><span style="color:#ABB2BF">;</span></span>
+<span class="line"><span style="color:#C678DD">    case</span><span style="color:#98C379"> 'sentinel-drift'</span><span style="color:#ABB2BF">:</span></span>
+<span class="line"><span style="color:#E5C07B">      console</span><span style="color:#ABB2BF">.</span><span style="color:#61AFEF">warn</span><span style="color:#ABB2BF">(</span><span style="color:#98C379">`</span><span style="color:#C678DD">${</span><span style="color:#E5C07B">d</span><span style="color:#ABB2BF">.</span><span style="color:#E06C75">path</span><span style="color:#C678DD">}</span><span style="color:#98C379">.</span><span style="color:#C678DD">${</span><span style="color:#E5C07B">d</span><span style="color:#ABB2BF">.</span><span style="color:#E06C75">field</span><span style="color:#C678DD">}</span><span style="color:#98C379"> drifted (</span><span style="color:#C678DD">${</span><span style="color:#E5C07B">d</span><span style="color:#ABB2BF">.</span><span style="color:#E06C75">sentinelKind</span><span style="color:#C678DD">}</span><span style="color:#98C379">): </span><span style="color:#C678DD">${</span><span style="color:#E5C07B">d</span><span style="color:#ABB2BF">.</span><span style="color:#E06C75">before</span><span style="color:#C678DD">}</span><span style="color:#98C379"> → </span><span style="color:#C678DD">${</span><span style="color:#E5C07B">d</span><span style="color:#ABB2BF">.</span><span style="color:#E06C75">after</span><span style="color:#C678DD">}</span><span style="color:#98C379">`</span><span style="color:#ABB2BF">);</span></span>
+<span class="line"><span style="color:#C678DD">      break</span><span style="color:#ABB2BF">;</span></span>
+<span class="line"><span style="color:#C678DD">    case</span><span style="color:#98C379"> 'time-drift'</span><span style="color:#ABB2BF">:</span></span>
+<span class="line"><span style="color:#E5C07B">      console</span><span style="color:#ABB2BF">.</span><span style="color:#61AFEF">warn</span><span style="color:#ABB2BF">(</span><span style="color:#98C379">`</span><span style="color:#C678DD">${</span><span style="color:#E5C07B">d</span><span style="color:#ABB2BF">.</span><span style="color:#E06C75">path</span><span style="color:#C678DD">}</span><span style="color:#98C379">.</span><span style="color:#C678DD">${</span><span style="color:#E5C07B">d</span><span style="color:#ABB2BF">.</span><span style="color:#E06C75">field</span><span style="color:#C678DD">}</span><span style="color:#98C379"> drifted via serverTimestamp`</span><span style="color:#ABB2BF">);</span></span>
+<span class="line"><span style="color:#C678DD">      break</span><span style="color:#ABB2BF">;</span></span>
+<span class="line"><span style="color:#C678DD">    case</span><span style="color:#98C379"> 'real-divergence'</span><span style="color:#ABB2BF">:</span></span>
+<span class="line"><span style="color:#E5C07B">      console</span><span style="color:#ABB2BF">.</span><span style="color:#61AFEF">error</span><span style="color:#ABB2BF">(</span><span style="color:#98C379">`real divergence at </span><span style="color:#C678DD">${</span><span style="color:#E5C07B">d</span><span style="color:#ABB2BF">.</span><span style="color:#E06C75">path</span><span style="color:#C678DD">}${</span><span style="color:#E5C07B">d</span><span style="color:#ABB2BF">.</span><span style="color:#E06C75">field</span><span style="color:#C678DD"> ?</span><span style="color:#98C379"> '.'</span><span style="color:#56B6C2"> +</span><span style="color:#E5C07B"> d</span><span style="color:#ABB2BF">.</span><span style="color:#E06C75">field</span><span style="color:#C678DD"> :</span><span style="color:#98C379"> ''</span><span style="color:#C678DD">}</span><span style="color:#98C379">: </span><span style="color:#C678DD">${</span><span style="color:#E5C07B">d</span><span style="color:#ABB2BF">.</span><span style="color:#E06C75">before</span><span style="color:#C678DD">}</span><span style="color:#98C379"> → </span><span style="color:#C678DD">${</span><span style="color:#E5C07B">d</span><span style="color:#ABB2BF">.</span><span style="color:#E06C75">after</span><span style="color:#C678DD">}</span><span style="color:#98C379">`</span><span style="color:#ABB2BF">);</span></span>
+<span class="line"><span style="color:#C678DD">      break</span><span style="color:#ABB2BF">;</span></span>
+<span class="line"><span style="color:#ABB2BF">  }</span></span>
+<span class="line"><span style="color:#ABB2BF">}</span></span></code></pre>
+<p>A typical CI assertion: <code>expect(divergences.filter(d => d.kind === 'real-divergence')).toHaveLength(0)</code>.</p>
+<h2 id="field-path-syntax">Field-path syntax</h2>
+<p><code>path</code> is the document path (<code>notes/x</code>). <code>field</code> is a dotted/bracket-indexed leaf path within the document:</p>
+<div class="table-scroll">
+<table><thead><tr><th>field</th><th>meaning</th></tr></thead><tbody><tr><td><code>name</code></td><td>top-level key</td></tr><tr><td><code>profile.lastSeen</code></td><td>nested object key</td></tr><tr><td><code>tags[0]</code></td><td>array element</td></tr><tr><td><code>history[2].at</code></td><td>nested key inside an array element</td></tr></tbody></table></div>
+<p>This matches the <code>field</code> shape on captured <code>WriteSandboxEvent.sentinels[]</code>, so sentinel-vs-divergence comparisons are exact-string matches without any path normalization.</p>
+<h2 id="see-also">See also</h2>
+<ul>
+<li><a href="../pyric-sandbox-how-to-replay-events/">How-to: Replay a captured event stream</a>: capture / replay / classify workflow.</li>
+<li><a href="../pyric-sandbox-reference-sandbox-event/"><code>SandboxEvent</code> reference</a>: the events <code>sandbox.history()</code> returns, including <code>WriteSandboxEvent.sentinels</code>.</li>
+<li><code>packages/pyric/src/sandbox/replay/index.ts</code>: the classifier source; file header documents the contract.</li>
+</ul>  </article> </main> <aside class="doc-toc" aria-label="On this page"> <h2 class="doc-toc-heading">On this page</h2> <ul> <li data-depth="2"> <a href="#what-is-a-divergence">What is a divergence?</a> </li><li data-depth="2"> <a href="#the-union">The union</a> </li><li data-depth="2"> <a href="#kind-autoid-alias">kind: &#39;autoid-alias&#39;</a> </li><li data-depth="2"> <a href="#kind-sentinel-drift">kind: &#39;sentinel-drift&#39;</a> </li><li data-depth="2"> <a href="#kind-time-drift">kind: &#39;time-drift&#39;</a> </li><li data-depth="2"> <a href="#kind-real-divergence">kind: &#39;real-divergence&#39;</a> </li><li data-depth="2"> <a href="#classifying-in-code">Classifying in code</a> </li><li data-depth="2"> <a href="#field-path-syntax">Field-path syntax</a> </li><li data-depth="2"> <a href="#see-also">See also</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-sandbox-reference-divergences.md ADDED Viewed

@@ -0,0 +1,151 @@
+# `Divergence`
+What `replay(events, rules, opts, originalState)` returns when the replayed state doesn't perfectly match the captured state. A discriminated union; filter on `kind` to handle each case.
+## What is a divergence?
+A divergence is a single classified difference between what the original sandbox stored and what the replayed sandbox produced after re-issuing every captured write.
+When the engine sees a difference, it tries to *explain* it from captured metadata (which fields had `FieldValue.*` sentinels, which paths came from auto-id minting, which `request.time` the rule engine evaluated against). Each explanation maps to a `kind`. If no explanation fits, the kind is `real-divergence`, the only kind that signals an actual bug. The other three are intentional by-design differences.
+Two design rules govern the classifier:
+1. **No shape inference.** The engine never guesses based on what a value *looks* like. A timestamp-shaped object isn't classified as `time-drift` unless the captured `sentinels[]` says it came from `serverTimestamp()`. Anything not licensed by captured metadata is `real-divergence`.
+2. **Leaf-precise.** The engine walks both documents recursively and reports field paths at the leaf (`profile.lastSeen`, `tags[0]`, `arr[2].nested`). A sentinel-bearing parent doesn't mask sibling changes.
+## The union
+```ts
+type Divergence =
+  | {
+      kind: 'sentinel-drift';
+      path: string;
+      field: string;
+      sentinelKind: 'serverTimestamp' | 'increment' | 'arrayUnion' | 'arrayRemove' | 'delete';
+      before: unknown;
+      after: unknown;
+    }
+  | { kind: 'autoid-alias'; originalPath: string; replayedPath: string }
+  | { kind: 'time-drift';     path: string; field: string;  before: unknown; after: unknown }
+  | { kind: 'real-divergence';path: string; field?: string; before: unknown; after: unknown };
+```
+## `kind: 'autoid-alias'`
+A write that originated from `LocalEnvironment.createWithAutoId` minted a fresh document ID on replay: same content, different path.
+```ts
+{ kind: 'autoid-alias', originalPath: 'notes/Iy5CGRl0HlP1XZo4GGiI', replayedPath: 'notes/5MM3PdzWUQvqRCi3wthO' }
+```
+Re-using the original ID would be incorrect: auto-id semantics include "the id is unique." Two replays of the same log on different sandboxes legitimately mint different ids. The engine emits one alias entry per such write and exposes the full mapping on `ReplayResult.pathAliases` so consumers that index by path can map original → replayed.
+Not a bug. Consumers comparing document presence should consult `pathAliases` before flagging "missing doc."
+## `kind: 'sentinel-drift'`
+A captured `FieldValue.*` sentinel (other than `serverTimestamp`, which has its own kind) sits at this exact field path, and the subtree differs between original and replayed state.
+```ts
+{
+  kind: 'sentinel-drift',
+  path: 'counters/x',
+  field: 'count',
+  sentinelKind: 'increment',
+  before: 5,
+  after: 7,
+}
+```
+Usually means **the prior state differed**, not that the sentinel itself misbehaved. `increment`, `arrayUnion`, `arrayRemove`, and `deleteField` are deterministic given the same prior. If their result differs, the prior was different. Look for an upstream `real-divergence` that explains why.
+In practice, with the same captured stream replayed onto a fresh sandbox, sentinel-drift is rare. It surfaces most often when you replay onto state that *isn't* the captured starting point (e.g., partial replays, splicing two logs).
+## `kind: 'time-drift'`
+A captured `serverTimestamp()` sentinel at this exact field path resolved to a different `Timestamp` on replay.
+```ts
+{
+  kind: 'time-drift',
+  path: 'notes/stamped',
+  field: 'ts',
+  before: { __type: 'timestamp', seconds: 1778955966, nanos: 624000000 },
+  after:  { __type: 'timestamp', seconds: 1778955966, nanos: 657000000 },
+}
+```
+Only fires when `pinRequestTime: false`. With the default `pinRequestTime: true`, the engine re-issues the captured `request.time` to the fresh sandbox so the sentinel resolves to the same value: zero `time-drift`.
+Not a bug. Useful for two scenarios:
+- **Rules that branch on `request.time`**. Turn pinning off and see whether a captured stream that passed yesterday still passes today. If a rule like `allow write: if request.time >= timestamp.date(2024, 1, 1)` started failing, you'd see denied writes surface as `real-divergence` rather than `time-drift` (the time-drift signals "yes, time moved" without it being a bug).
+- **Debugging "why is my serverTimestamp different"**. The `before` / `after` values show exactly how far the clock drifted.
+## `kind: 'real-divergence'`
+Anything else. Captured metadata doesn't license this difference, so the engine flags it.
+```ts
+{
+  kind: 'real-divergence',
+  path: 'notes/x',
+  field: 'profile.name',
+  before: 'alice',
+  after: 'NOT-alice',
+}
+```
+The `field` may be absent. For example, when an entire document is present on one side and missing on the other, the path alone identifies the divergence:
+```ts
+{ kind: 'real-divergence', path: 'notes/x', before: { /* doc */ }, after: undefined }
+```
+This is the only kind that signals an actual bug. Common causes:
+- **Rules changed between capture and replay**: a write that succeeded originally gets denied; the doc is missing in replayed state.
+- **A captured write hit a sandbox feature that isn't deterministic**: the engine's contract says writes are deterministic given the same prior + rules + clock; if you see real-divergence on a clean replay, something is non-deterministic in the path you're testing.
+- **Replay state seeded incorrectly**: if you persisted state separately from events and they drift apart, fields can disagree.
+## Classifying in code
+```ts
+for (const d of divergences) {
+  switch (d.kind) {
+    case 'autoid-alias':
+      // Intentional: map d.originalPath → d.replayedPath in your index.
+      break;
+    case 'sentinel-drift':
+      console.warn(`${d.path}.${d.field} drifted (${d.sentinelKind}): ${d.before} → ${d.after}`);
+      break;
+    case 'time-drift':
+      console.warn(`${d.path}.${d.field} drifted via serverTimestamp`);
+      break;
+    case 'real-divergence':
+      console.error(`real divergence at ${d.path}${d.field ? '.' + d.field : ''}: ${d.before} → ${d.after}`);
+      break;
+  }
+}
+```
+A typical CI assertion: `expect(divergences.filter(d => d.kind === 'real-divergence')).toHaveLength(0)`.
+## Field-path syntax
+`path` is the document path (`notes/x`). `field` is a dotted/bracket-indexed leaf path within the document:
+| field | meaning |
+|---|---|
+| `name` | top-level key |
+| `profile.lastSeen` | nested object key |
+| `tags[0]` | array element |
+| `history[2].at` | nested key inside an array element |
+This matches the `field` shape on captured `WriteSandboxEvent.sentinels[]`, so sentinel-vs-divergence comparisons are exact-string matches without any path normalization.
+## See also
+- [How-to: Replay a captured event stream](../pyric-sandbox-how-to-replay-events/): capture / replay / classify workflow.
+- [`SandboxEvent` reference](../pyric-sandbox-reference-sandbox-event/): the events `sandbox.history()` returns, including `WriteSandboxEvent.sentinels`.
+- `packages/pyric/src/sandbox/replay/index.ts`: the classifier source; file header documents the contract.

package/dist/serve/docs-ui/docs/pyric-sandbox-reference-error-codes/index.html ADDED Viewed

@@ -0,0 +1,110 @@
+<!DOCTYPE html><html lang="en"> <head><meta charset="UTF-8"><meta name="viewport" content="width=device-width, initial-scale=1.0"><title>SandboxError codes · 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/" aria-current="true"> 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/"> pyric / rules </a> </li><li> <a href="/__pyric/ui/docs/pyric-sandbox/" aria-current="true"> 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-sandbox/">pyric / sandbox</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">SandboxError codes</span> </li> </ol> </nav>  <article class="prose">  <h1 id="sandboxerror-codes"><code>SandboxError</code> codes</h1>
+<p>Every error the sandbox raises is a <code>SandboxError</code> carrying a <code>code</code>. Catch with <code>instanceof SandboxError</code>, switch on <code>code</code>.</p>
+<pre class="astro-code one-dark-pro" style="background-color:#282c34;color:#abb2bf; overflow-x: auto;" tabindex="0" data-language="ts"><code><span class="line"><span style="color:#C678DD">import</span><span style="color:#ABB2BF"> { </span><span style="color:#E06C75">SandboxError</span><span style="color:#ABB2BF"> } </span><span style="color:#C678DD">from</span><span style="color:#98C379"> 'pyric/sandbox'</span><span style="color:#ABB2BF">;</span></span>
+<span class="line"></span>
+<span class="line"><span style="color:#C678DD">try</span><span style="color:#ABB2BF"> {</span></span>
+<span class="line"><span style="color:#C678DD">  await</span><span style="color:#E5C07B"> aliceDb</span><span style="color:#ABB2BF">.</span><span style="color:#61AFEF">collection</span><span style="color:#ABB2BF">(</span><span style="color:#98C379">'admin'</span><span style="color:#ABB2BF">).</span><span style="color:#61AFEF">doc</span><span style="color:#ABB2BF">(</span><span style="color:#98C379">'x'</span><span style="color:#ABB2BF">).</span><span style="color:#61AFEF">set</span><span style="color:#ABB2BF">({ </span><span style="color:#E06C75">value</span><span style="color:#ABB2BF">: </span><span style="color:#D19A66">1</span><span style="color:#ABB2BF"> });</span></span>
+<span class="line"><span style="color:#ABB2BF">} </span><span style="color:#C678DD">catch</span><span style="color:#ABB2BF"> (</span><span style="color:#E06C75">e</span><span style="color:#ABB2BF">) {</span></span>
+<span class="line"><span style="color:#C678DD">  if</span><span style="color:#ABB2BF"> (</span><span style="color:#E06C75">e</span><span style="color:#C678DD"> instanceof</span><span style="color:#E5C07B"> SandboxError</span><span style="color:#56B6C2"> &#x26;&#x26;</span><span style="color:#E5C07B"> e</span><span style="color:#ABB2BF">.</span><span style="color:#E06C75">code</span><span style="color:#56B6C2"> ===</span><span style="color:#98C379"> 'permission-denied'</span><span style="color:#ABB2BF">) {</span></span>
+<span class="line"><span style="color:#E5C07B">    console</span><span style="color:#ABB2BF">.</span><span style="color:#61AFEF">log</span><span style="color:#ABB2BF">(</span><span style="color:#98C379">'Rules said no:'</span><span style="color:#ABB2BF">, </span><span style="color:#E5C07B">e</span><span style="color:#ABB2BF">.</span><span style="color:#E06C75">denialContext</span><span style="color:#ABB2BF">);</span></span>
+<span class="line"><span style="color:#ABB2BF">  }</span></span>
+<span class="line"><span style="color:#ABB2BF">}</span></span></code></pre>
+<h2 id="firebase-aligned-codes">Firebase-aligned codes</h2>
+<p>These match Firebase / gRPC conventions so production-shaped <code>catch (e) { if (e.code === 'permission-denied') }</code> code keeps working.</p>
+<h3 id="invalid-argument"><code>'invalid-argument'</code></h3>
+<p>Caller passed something the API does not accept. Common cases:</p>
+<ul>
+<li><code>sandbox.withAuth(undefined)</code>: say <code>withAuth(null)</code> explicitly.</li>
+<li><code>sandbox.withAuth({ uid: '' })</code>: UID must be non-empty.</li>
+<li><code>sandbox.withAuth({ uid: 'x', token: 'oops' })</code>: <code>token</code> must be an object.</li>
+<li>Hand-rolled <code>Sandbox</code> handle passed to a service factory (via <code>getInternalEnv</code> from <code>/internal</code>).</li>
+</ul>
+<p>Errors of this kind carry <code>remediation</code> text explaining the fix.</p>
+<h3 id="permission-denied"><code>'permission-denied'</code></h3>
+<p>Rules denied the operation. The <code>denialContext</code> field is populated with:</p>
+<ul>
+<li><code>auth</code>: the identity that was active.</li>
+<li><code>reasons</code>: the simulator’s debug messages (one per evaluated rule).</li>
+<li><code>request</code>: the eval-time <code>request.*</code> shape (method, path, resource data).</li>
+<li><code>resource</code>: the eval-time <code>resource.*</code> (existing doc, exists flag).</li>
+<li><code>rule</code> (best-effort): line and expression source.</li>
+</ul>
+<p>See the <a href="../pyric-sandbox-reference-sandbox-event/"><code>SandboxEvent</code> reference</a>. <code>DenialContext</code> mirrors the <code>kind: 'request' &#x26;&#x26; result: 'deny'</code> event shape.</p>
+<h3 id="not-found"><code>'not-found'</code></h3>
+<p>Operation referenced a document that does not exist:</p>
+<ul>
+<li><code>update</code> against a non-existent document.</li>
+<li><code>transaction</code> reading a path that’s gone.</li>
+</ul>
+<h3 id="already-exists"><code>'already-exists'</code></h3>
+<p><code>create</code> against a path that already has a document. (Plain <code>set</code> overwrites; <code>create</code> insists on absence.)</p>
+<h3 id="failed-precondition"><code>'failed-precondition'</code></h3>
+<p>The operation could not run in the current state, for reasons other than missing/extra docs:</p>
+<ul>
+<li>Read-after-write violation inside a transaction.</li>
+<li>Ambiguous post-delete reference.</li>
+</ul>
+<h3 id="aborted"><code>'aborted'</code></h3>
+<p>A transaction was aborted, typically because its callback threw. The thrown error propagates synchronously; the event log marks the transaction as aborted and excludes it from undo.</p>
+<h3 id="unavailable"><code>'unavailable'</code></h3>
+<p>Reserved. Not currently emitted; there is no network stream to drop. May appear if a future service has a transport.</p>
+<h2 id="sandbox-specific-codes">Sandbox-specific codes</h2>
+<p>These don’t have a production analog. They exist so callers can distinguish “the sandbox doesn’t model this” from “your rule is wrong” without parsing messages.</p>
+<h3 id="unimplemented"><code>'unimplemented'</code></h3>
+<p>The sandbox doesn’t yet model a feature your rule uses. Returned from the simulator’s <code>UnsupportedError</code> channel surfaced through this code. For most agent workflows the right response is to route the offending case to the live Firebase Rules Test API; see <a href="../pyric-rules-explanation-simulator-vs-rules-test-api/"><code>pyric/rules</code></a>.</p>
+<h3 id="not-seeded"><code>'not-seeded'</code></h3>
+<p>An operation was issued before <code>LocalEnvironment.seed</code> provided rules. The default state is empty, with no rules. Most operations will deny under default-deny semantics, but some surfaces (admin reads, listing operations) raise this code instead so it’s obvious the sandbox hasn’t been initialised.</p>
+<h3 id="rules-not-loaded"><code>'rules-not-loaded'</code></h3>
+<p>Similar to <code>'not-seeded'</code>, but specifically signals that rules haven’t been deployed yet. Use <code>LocalEnvironment.deployRules(source)</code> or seed with <code>rules</code> before issuing operations that need to evaluate.</p>
+<h2 id="constructing-errors-yourself">Constructing errors yourself</h2>
+<p>Two forms:</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:#7F848E;font-style:italic">// Positional — backwards-compatible.</span></span>
+<span class="line"><span style="color:#C678DD">throw</span><span style="color:#C678DD"> new</span><span style="color:#61AFEF"> SandboxError</span><span style="color:#ABB2BF">(</span><span style="color:#98C379">'permission-denied'</span><span style="color:#ABB2BF">, </span><span style="color:#98C379">'Denied: …'</span><span style="color:#ABB2BF">, </span><span style="color:#E06C75">denialContext</span><span style="color:#ABB2BF">);</span></span>
+<span class="line"></span>
+<span class="line"><span style="color:#7F848E;font-style:italic">// Options bag — use when attaching remediation.</span></span>
+<span class="line"><span style="color:#C678DD">throw</span><span style="color:#C678DD"> new</span><span style="color:#61AFEF"> SandboxError</span><span style="color:#ABB2BF">({</span></span>
+<span class="line"><span style="color:#E06C75">  code</span><span style="color:#ABB2BF">: </span><span style="color:#98C379">'invalid-argument'</span><span style="color:#ABB2BF">,</span></span>
+<span class="line"><span style="color:#E06C75">  message</span><span style="color:#ABB2BF">: </span><span style="color:#98C379">'withAuth() needs an explicit AuthState.'</span><span style="color:#ABB2BF">,</span></span>
+<span class="line"><span style="color:#E06C75">  remediation</span><span style="color:#ABB2BF">: </span><span style="color:#98C379">'For anonymous: withAuth(null). For users: withAuth({ uid: "…" }).'</span><span style="color:#ABB2BF">,</span></span>
+<span class="line"><span style="color:#ABB2BF">});</span></span></code></pre>
+<p>When <code>remediation</code> is set, it is appended to the error’s <code>.message</code> with a blank-line separator so consumers that surface <code>.message</code> (logs, UIs) see the guidance without an API change. The structured form is also available on the instance as <code>error.remediation</code>.</p>
+<h2 id="what-carries-denialcontext">What carries <code>denialContext</code></h2>
+<p>Only <code>'permission-denied'</code> errors. Every other code has <code>denialContext: undefined</code>. Consumers branching on <code>denialContext</code> should check the code first.</p>
+<p>The exact field set depends on the operation:</p>
+<div class="table-scroll">
+<table><thead><tr><th>Operation</th><th><code>request</code></th><th><code>resource</code></th></tr></thead><tbody><tr><td><code>get</code></td><td>method=<code>'get'</code>, path</td><td>data + exists for the existing doc</td></tr><tr><td><code>list</code></td><td>method=<code>'list'</code>, path</td><td>none (collection ops; resource not modelled per-doc)</td></tr><tr><td><code>create</code></td><td>method=<code>'create'</code>, path, resourceData</td><td>data=<code>null</code>, exists=<code>false</code></td></tr><tr><td><code>update</code></td><td>method=<code>'update'</code>, path, resourceData</td><td>data + exists for the existing doc</td></tr><tr><td><code>delete</code></td><td>method=<code>'delete'</code>, path</td><td>data + exists for the existing doc</td></tr></tbody></table></div>
+<p><code>resourceData</code> reflects the post-sentinel-resolution payload: what the rule actually saw on <code>request.resource.data</code>.</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="#firebase-aligned-codes">Firebase-aligned codes</a> </li><li data-depth="3"> <a href="#invalid-argument">&#39;invalid-argument&#39;</a> </li><li data-depth="3"> <a href="#permission-denied">&#39;permission-denied&#39;</a> </li><li data-depth="3"> <a href="#not-found">&#39;not-found&#39;</a> </li><li data-depth="3"> <a href="#already-exists">&#39;already-exists&#39;</a> </li><li data-depth="3"> <a href="#failed-precondition">&#39;failed-precondition&#39;</a> </li><li data-depth="3"> <a href="#aborted">&#39;aborted&#39;</a> </li><li data-depth="3"> <a href="#unavailable">&#39;unavailable&#39;</a> </li><li data-depth="2"> <a href="#sandbox-specific-codes">Sandbox-specific codes</a> </li><li data-depth="3"> <a href="#unimplemented">&#39;unimplemented&#39;</a> </li><li data-depth="3"> <a href="#not-seeded">&#39;not-seeded&#39;</a> </li><li data-depth="3"> <a href="#rules-not-loaded">&#39;rules-not-loaded&#39;</a> </li><li data-depth="2"> <a href="#constructing-errors-yourself">Constructing errors yourself</a> </li><li data-depth="2"> <a href="#what-carries-denialcontext">What carries denialContext</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>