npm - pyric-tools - Versions diffs - 0.1.0-alpha.7 - Mend

pyric-tools 0.1.0-alpha.7

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 (1052) 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_.BsN3bPok.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/prototype"> Prototype </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> <details class="docs-nav-group"> <summary>pyric-tools</summary> <div class="docs-nav-group-body"> <div class="docs-nav-section">  <ul> <li> <a href="/__pyric/ui/docs/pyric-tools/"> Overview </a> </li> </ul> </div><div class="docs-nav-section"> <h2 class="docs-nav-heading"> Tutorials </h2> <ul> <li> <a href="/__pyric/ui/docs/pyric-tools-tutorials-getting-started/"> Getting started </a> </li><li> <a href="/__pyric/ui/docs/pyric-tools-tutorials-server-adoption/"> Server adoption </a> </li><li> <a href="/__pyric/ui/docs/pyric-tools-tutorials-wire-claude-code/"> Wire Claude Code </a> </li> </ul> </div><div class="docs-nav-section"> <h2 class="docs-nav-heading"> How-to </h2> <ul> <li> <a href="/__pyric/ui/docs/pyric-tools-how-to-build-a-standalone-binary/"> Build a standalone binary </a> </li><li> <a href="/__pyric/ui/docs/pyric-tools-how-to-configure-auth-providers-and-domains/"> Configure auth providers </a> </li><li> <a href="/__pyric/ui/docs/pyric-tools-how-to-discover-a-schema-from-firestore/"> Infer a schema </a> </li><li> <a href="/__pyric/ui/docs/pyric-tools-how-to-promote-sandbox-state-to-a-fixture/"> Promote sandbox state </a> </li><li> <a href="/__pyric/ui/docs/pyric-tools-how-to-serve-persistence-and-multi-tab/"> Persistence &amp; multi-tab </a> </li><li> <a href="/__pyric/ui/docs/pyric-tools-how-to-use-the-vite-plugin/"> Use the Vite plugin </a> </li><li> <a href="/__pyric/ui/docs/pyric-tools-how-to-verify-against-a-captured-session/"> Verify rules against prod </a> </li> </ul> </div><div class="docs-nav-section"> <h2 class="docs-nav-heading"> Reference </h2> <ul> <li> <a href="/__pyric/ui/docs/pyric-tools-reference-cli/"> pyric CLI reference </a> </li><li> <a href="/__pyric/ui/docs/pyric-tools-reference-verify/"> Verify API </a> </li> </ul> </div><div class="docs-nav-section"> <h2 class="docs-nav-heading"> Bridge </h2> <ul> <li> <a href="/__pyric/ui/docs/pyric-tools-bridge/"> pyric-tools/bridge </a> </li> </ul> </div> </div> </details><details class="docs-nav-group"> <summary>pyric-tools / deploy</summary> <div class="docs-nav-group-body"> <div class="docs-nav-section">  <ul> <li> <a href="/__pyric/ui/docs/pyric-tools-deploy/"> Overview </a> </li> </ul> </div><div class="docs-nav-section"> <h2 class="docs-nav-heading"> Tutorials </h2> <ul> <li> <a href="/__pyric/ui/docs/pyric-tools-deploy-tutorials-01-deploy-a-cloud-function/"> Deploy a Cloud Function </a> </li> </ul> </div><div class="docs-nav-section"> <h2 class="docs-nav-heading"> How-to </h2> <ul> <li> <a href="/__pyric/ui/docs/pyric-tools-deploy-how-to-build-projectscope-from-firebase-auth/"> Scope from Firebase Auth </a> </li><li> <a href="/__pyric/ui/docs/pyric-tools-deploy-how-to-build-projectscope-from-service-account/"> Scope from service account </a> </li><li> <a href="/__pyric/ui/docs/pyric-tools-deploy-how-to-bundle-and-deploy-a-function/"> Bundle &amp; deploy a function </a> </li><li> <a href="/__pyric/ui/docs/pyric-tools-deploy-how-to-deploy-firestore-indexes/"> Deploy Firestore indexes </a> </li><li> <a href="/__pyric/ui/docs/pyric-tools-deploy-how-to-deploy-firestore-rules/"> Deploy Firestore rules </a> </li><li> <a href="/__pyric/ui/docs/pyric-tools-deploy-how-to-deploy-hosting-rewrites/"> Deploy Hosting rewrites </a> </li><li> <a href="/__pyric/ui/docs/pyric-tools-deploy-how-to-deploy-realtime-database-rules/"> Deploy RTDB rules </a> </li><li> <a href="/__pyric/ui/docs/pyric-tools-deploy-how-to-deploy-to-a-preview-channel/"> Deploy to a preview channel </a> </li><li> <a href="/__pyric/ui/docs/pyric-tools-deploy-how-to-handle-errors-and-outcomes/"> Handle errors and outcomes </a> </li><li> <a href="/__pyric/ui/docs/pyric-tools-deploy-how-to-provision-a-firestore-database/"> Provision a database </a> </li><li> <a href="/__pyric/ui/docs/pyric-tools-deploy-how-to-register-tools-with-an-agent/"> Register deploy tools </a> </li> </ul> </div><div class="docs-nav-section"> <h2 class="docs-nav-heading"> Reference </h2> <ul> <li> <a href="/__pyric/ui/docs/pyric-tools-deploy-reference-api/"> Public API </a> </li><li> <a href="/__pyric/ui/docs/pyric-tools-deploy-reference-cli-agent-io/"> pyric deploy agent I/O </a> </li><li> <a href="/__pyric/ui/docs/pyric-tools-deploy-reference-error-codes/"> Error codes by operation </a> </li><li> <a href="/__pyric/ui/docs/pyric-tools-deploy-reference-firestore-namespace/"> firestore namespace </a> </li><li> <a href="/__pyric/ui/docs/pyric-tools-deploy-reference-functions-namespace/"> functions namespace </a> </li><li> <a href="/__pyric/ui/docs/pyric-tools-deploy-reference-hosting-config/"> firebase.json hosting config </a> </li><li> <a href="/__pyric/ui/docs/pyric-tools-deploy-reference-hosting-namespace/"> hosting namespace </a> </li><li> <a href="/__pyric/ui/docs/pyric-tools-deploy-reference-rtdb-namespace/"> rtdb namespace </a> </li><li> <a href="/__pyric/ui/docs/pyric-tools-deploy-reference-scope-and-outcome/"> Scope and Outcome </a> </li><li> <a href="/__pyric/ui/docs/pyric-tools-deploy-reference-tool-factories/"> Tool factories </a> </li> </ul> </div><div class="docs-nav-section"> <h2 class="docs-nav-heading"> Explanation </h2> <ul> <li> <a href="/__pyric/ui/docs/pyric-tools-deploy-explanation-primitives-vs-orchestrators/"> Primitives vs. orchestrators </a> </li><li> <a href="/__pyric/ui/docs/pyric-tools-deploy-explanation-token-caching/"> Token caching and memoizeTtl </a> </li><li> <a href="/__pyric/ui/docs/pyric-tools-deploy-explanation-why-no-firebase-cli/"> Why no Firebase CLI </a> </li><li> <a href="/__pyric/ui/docs/pyric-tools-deploy-explanation-why-this-package-exists/"> Why this package exists </a> </li> </ul> </div> </div> </details><details class="docs-nav-group"> <summary>pyric / firestore</summary> <div class="docs-nav-group-body"> <div class="docs-nav-section">  <ul> <li> <a href="/__pyric/ui/docs/pyric-firestore/"> Overview </a> </li> </ul> </div><div class="docs-nav-section"> <h2 class="docs-nav-heading"> Tutorials </h2> <ul> <li> <a href="/__pyric/ui/docs/pyric-firestore-tutorials-01-write-a-sandbox-demo/"> Sandbox-backed demo </a> </li><li> <a href="/__pyric/ui/docs/pyric-firestore-tutorials-02-swap-to-prod-backend/"> Swap to prod backend </a> </li> </ul> </div><div class="docs-nav-section"> <h2 class="docs-nav-heading"> How-to </h2> <ul> <li> <a href="/__pyric/ui/docs/pyric-firestore-how-to-build-queries/"> Build queries </a> </li><li> <a href="/__pyric/ui/docs/pyric-firestore-how-to-migrate-from-firebase-firestore/"> Migrate from Firestore </a> </li><li> <a href="/__pyric/ui/docs/pyric-firestore-how-to-pick-a-backend/"> Pick a backend </a> </li><li> <a href="/__pyric/ui/docs/pyric-firestore-how-to-run-a-transaction/"> Run a transaction </a> </li><li> <a href="/__pyric/ui/docs/pyric-firestore-how-to-use-onsnapshot/"> Use onSnapshot </a> </li><li> <a href="/__pyric/ui/docs/pyric-firestore-how-to-use-sandbox-ops/"> Use sandbox-only ops </a> </li> </ul> </div><div class="docs-nav-section"> <h2 class="docs-nav-heading"> Reference </h2> <ul> <li> <a href="/__pyric/ui/docs/pyric-firestore-reference-api/"> Public API </a> </li><li> <a href="/__pyric/ui/docs/pyric-firestore-reference-feature-matrix/"> Feature matrix </a> </li><li> <a href="/__pyric/ui/docs/pyric-firestore-reference-getfirestore/"> getFirestore overloads </a> </li><li> <a href="/__pyric/ui/docs/pyric-firestore-reference-query-constraints/"> Query constraints </a> </li><li> <a href="/__pyric/ui/docs/pyric-firestore-reference-sandbox-ops/"> Sandbox-only operations </a> </li><li> <a href="/__pyric/ui/docs/pyric-firestore-reference-tool-factories/"> Tool factories </a> </li> </ul> </div><div class="docs-nav-section"> <h2 class="docs-nav-heading"> Explanation </h2> <ul> <li> <a href="/__pyric/ui/docs/pyric-firestore-explanation-rules-tooling-is-separate/"> Rules tooling is separate </a> </li><li> <a href="/__pyric/ui/docs/pyric-firestore-explanation-target-symbol-opacity/"> TARGET_SYMBOL opacity </a> </li><li> <a href="/__pyric/ui/docs/pyric-firestore-explanation-two-backends-one-surface/"> Two backends, one surface </a> </li> </ul> </div><div class="docs-nav-section"> <h2 class="docs-nav-heading"> Compat </h2> <ul> <li> <a href="/__pyric/ui/docs/pyric-firestore-compat/"> Compatibility matrix </a> </li> </ul> </div> </div> </details><details class="docs-nav-group"> <summary>pyric / rules</summary> <div class="docs-nav-group-body"> <div class="docs-nav-section">  <ul> <li> <a href="/__pyric/ui/docs/pyric-rules/"> Overview </a> </li> </ul> </div><div class="docs-nav-section"> <h2 class="docs-nav-heading"> Tutorials </h2> <ul> <li> <a href="/__pyric/ui/docs/pyric-rules-tutorials-01-lint-your-first-rules-file/"> Lint your first rules file </a> </li><li> <a href="/__pyric/ui/docs/pyric-rules-tutorials-02-write-a-test-suite-for-your-rules/"> Write a rules test suite </a> </li> </ul> </div><div class="docs-nav-section"> <h2 class="docs-nav-heading"> How-to </h2> <ul> <li> <a href="/__pyric/ui/docs/pyric-rules-how-to-compare-rulesets-for-weakening/"> Compare rulesets </a> </li><li> <a href="/__pyric/ui/docs/pyric-rules-how-to-inspect-rules-via-the-ast/"> Inspect rules via the AST </a> </li><li> <a href="/__pyric/ui/docs/pyric-rules-how-to-lint-rules-source/"> Lint a rules source </a> </li><li> <a href="/__pyric/ui/docs/pyric-rules-how-to-pin-request-time/"> Pin request.time </a> </li><li> <a href="/__pyric/ui/docs/pyric-rules-how-to-register-tools-with-an-agent/"> Register rules tools </a> </li><li> <a href="/__pyric/ui/docs/pyric-rules-how-to-resolve-module-imports/"> Resolve 2+modules imports </a> </li><li> <a href="/__pyric/ui/docs/pyric-rules-how-to-simulate-rules-locally/"> Simulate rules locally </a> </li><li> <a href="/__pyric/ui/docs/pyric-rules-how-to-test-rules-against-firebase/"> Test rules against Firebase </a> </li> </ul> </div><div class="docs-nav-section"> <h2 class="docs-nav-heading"> Reference </h2> <ul> <li> <a href="/__pyric/ui/docs/pyric-rules-reference-api/"> Public API </a> </li><li> <a href="/__pyric/ui/docs/pyric-rules-reference-ast/"> AST </a> </li><li> <a href="/__pyric/ui/docs/pyric-rules-reference-errors/"> Errors </a> </li><li> <a href="/__pyric/ui/docs/pyric-rules-reference-lint-rules/"> Lint rules </a> </li><li> <a href="/__pyric/ui/docs/pyric-rules-reference-simulator-context/"> Simulator context </a> </li><li> <a href="/__pyric/ui/docs/pyric-rules-reference-stdlib-modules/"> Standard library modules </a> </li><li> <a href="/__pyric/ui/docs/pyric-rules-reference-test-case-schema/"> TestCase schema </a> </li><li> <a href="/__pyric/ui/docs/pyric-rules-reference-validator-findings/"> Validator findings </a> </li><li> <a href="/__pyric/ui/docs/pyric-rules-reference-value-wrappers/"> Value wrappers </a> </li> </ul> </div><div class="docs-nav-section"> <h2 class="docs-nav-heading"> Explanation </h2> <ul> <li> <a href="/__pyric/ui/docs/pyric-rules-explanation-agent-failure-modes/"> Agent failure modes </a> </li><li> <a href="/__pyric/ui/docs/pyric-rules-explanation-lint-vs-validate-vs-simulate-vs-test/"> Lint vs validate vs test </a> </li><li> <a href="/__pyric/ui/docs/pyric-rules-explanation-runtime-budget-and-shared-gates/"> Runtime budget and gates </a> </li><li> <a href="/__pyric/ui/docs/pyric-rules-explanation-sentinel-expression-engine/"> Sentinel expression engine </a> </li><li> <a href="/__pyric/ui/docs/pyric-rules-explanation-simulator-vs-rules-test-api/"> Simulator vs Rules Test API </a> </li><li> <a href="/__pyric/ui/docs/pyric-rules-explanation-the-2-plus-modules-extension/"> The 2+modules extension </a> </li><li> <a href="/__pyric/ui/docs/pyric-rules-explanation-value-wrappers-design/"> Value wrapper design </a> </li><li> <a href="/__pyric/ui/docs/pyric-rules-explanation-why-this-package-exists/"> Why this package exists </a> </li> </ul> </div> </div> </details><details class="docs-nav-group" open> <summary>pyric / sandbox</summary> <div class="docs-nav-group-body"> <div class="docs-nav-section">  <ul> <li> <a href="/__pyric/ui/docs/pyric-sandbox/"> Overview </a> </li> </ul> </div><div class="docs-nav-section"> <h2 class="docs-nav-heading"> Tutorials </h2> <ul> <li> <a href="/__pyric/ui/docs/pyric-sandbox-tutorials-01-your-first-sandbox-session/"> Your first sandbox session </a> </li><li> <a href="/__pyric/ui/docs/pyric-sandbox-tutorials-02-use-the-sandbox-in-a-test-harness/"> Sandbox in a test harness </a> </li><li> <a href="/__pyric/ui/docs/pyric-sandbox-tutorials-03-build-a-traffic-monitor/"> Traffic monitor </a> </li> </ul> </div><div class="docs-nav-section"> <h2 class="docs-nav-heading"> How-to </h2> <ul> <li> <a href="/__pyric/ui/docs/pyric-sandbox-how-to-multiple-isolated-sandboxes/"> Run isolated sandboxes </a> </li><li> <a href="/__pyric/ui/docs/pyric-sandbox-how-to-observe-events/"> Observe sandbox events </a> </li><li> <a href="/__pyric/ui/docs/pyric-sandbox-how-to-pick-an-adapter/"> Pick an adapter </a> </li><li> <a href="/__pyric/ui/docs/pyric-sandbox-how-to-replay-events/"> Replay events </a> </li><li> <a href="/__pyric/ui/docs/pyric-sandbox-how-to-reset-between-tests/"> Reset between tests </a> </li><li> <a href="/__pyric/ui/docs/pyric-sandbox-how-to-seed-data-and-rules/"> Seed data and rules </a> </li><li> <a href="/__pyric/ui/docs/pyric-sandbox-how-to-switch-users/"> Switch users </a> </li><li> <a href="/__pyric/ui/docs/pyric-sandbox-how-to-use-admin-reads/"> Use admin reads </a> </li> </ul> </div><div class="docs-nav-section"> <h2 class="docs-nav-heading"> Reference </h2> <ul> <li> <a href="/__pyric/ui/docs/pyric-sandbox-reference-api/"> Public API </a> </li><li> <a href="/__pyric/ui/docs/pyric-sandbox-reference-divergences/" aria-current="page"> Divergence </a> </li><li> <a href="/__pyric/ui/docs/pyric-sandbox-reference-error-codes/"> SandboxError codes </a> </li><li> <a href="/__pyric/ui/docs/pyric-sandbox-reference-internal-protocol/"> The /internal protocol </a> </li><li> <a href="/__pyric/ui/docs/pyric-sandbox-reference-sandbox-and-context/"> Sandbox and context </a> </li><li> <a href="/__pyric/ui/docs/pyric-sandbox-reference-sandbox-event/"> SandboxEvent </a> </li><li> <a href="/__pyric/ui/docs/pyric-sandbox-reference-snapshot-and-admin/"> Snapshot and admin reads </a> </li> </ul> </div><div class="docs-nav-section"> <h2 class="docs-nav-heading"> Explanation </h2> <ul> <li> <a href="/__pyric/ui/docs/pyric-sandbox-explanation-every-op-is-a-request/"> Every operation is a request </a> </li><li> <a href="/__pyric/ui/docs/pyric-sandbox-explanation-identity-is-a-context/"> Identity is a context </a> </li><li> <a href="/__pyric/ui/docs/pyric-sandbox-explanation-internal-adapter-protocol/"> The /internal protocol </a> </li><li> <a href="/__pyric/ui/docs/pyric-sandbox-explanation-listener-re-evaluation/"> Listener re-evaluation </a> </li><li> <a href="/__pyric/ui/docs/pyric-sandbox-explanation-local-backend-vs-firestore-offline/"> Local backend vs. offline </a> </li><li> <a href="/__pyric/ui/docs/pyric-sandbox-explanation-why-adapters-are-siblings/"> Why adapters are siblings </a> </li><li> <a href="/__pyric/ui/docs/pyric-sandbox-explanation-why-this-package-exists/"> Why this package exists </a> </li> </ul> </div> </div> </details><details class="docs-nav-group"> <summary>pyric / storage</summary> <div class="docs-nav-group-body"> <div class="docs-nav-section">  <ul> <li> <a href="/__pyric/ui/docs/pyric-storage/"> Overview </a> </li> </ul> </div><div class="docs-nav-section"> <h2 class="docs-nav-heading"> Tutorials </h2> <ul> <li> <a href="/__pyric/ui/docs/pyric-storage-tutorials-01-upload-and-download/"> Upload and download </a> </li> </ul> </div><div class="docs-nav-section"> <h2 class="docs-nav-heading"> How-to </h2> <ul> <li> <a href="/__pyric/ui/docs/pyric-storage-how-to-enforce-rules/"> Enforce Storage rules </a> </li><li> <a href="/__pyric/ui/docs/pyric-storage-how-to-list-and-delete/"> List and delete objects </a> </li><li> <a href="/__pyric/ui/docs/pyric-storage-how-to-round-trip-metadata/"> Round-trip metadata </a> </li><li> <a href="/__pyric/ui/docs/pyric-storage-how-to-switch-backends/"> Switch backends </a> </li><li> <a href="/__pyric/ui/docs/pyric-storage-how-to-test-rule-expressions/"> Test rule expressions </a> </li> </ul> </div><div class="docs-nav-section"> <h2 class="docs-nav-heading"> Reference </h2> <ul> <li> <a href="/__pyric/ui/docs/pyric-storage-reference-api/"> Public API </a> </li><li> <a href="/__pyric/ui/docs/pyric-storage-reference-error-codes/"> Error codes </a> </li><li> <a href="/__pyric/ui/docs/pyric-storage-reference-rules-subset/"> Storage rules subset </a> </li><li> <a href="/__pyric/ui/docs/pyric-storage-reference-storage-options/"> StorageOptions </a> </li> </ul> </div><div class="docs-nav-section"> <h2 class="docs-nav-heading"> Explanation </h2> <ul> <li> <a href="/__pyric/ui/docs/pyric-storage-explanation-implementation-scope/"> Implementation scope </a> </li><li> <a href="/__pyric/ui/docs/pyric-storage-explanation-session-archive-use-case/"> The session-archive driver </a> </li><li> <a href="/__pyric/ui/docs/pyric-storage-explanation-why-indexeddb/"> Why IndexedDB </a> </li> </ul> </div><div class="docs-nav-section"> <h2 class="docs-nav-heading"> Compat </h2> <ul> <li> <a href="/__pyric/ui/docs/pyric-storage-compat/"> Compatibility matrix </a> </li> </ul> </div> </div> </details><details class="docs-nav-group"> <summary>pyric / auth</summary> <div class="docs-nav-group-body"> <div class="docs-nav-section">  <ul> <li> <a href="/__pyric/ui/docs/pyric-auth/"> Overview </a> </li> </ul> </div><div class="docs-nav-section"> <h2 class="docs-nav-heading"> Reference </h2> <ul> <li> <a href="/__pyric/ui/docs/pyric-auth-reference-api/"> API reference </a> </li><li> <a href="/__pyric/ui/docs/pyric-auth-reference-feature-matrix/"> Feature matrix </a> </li><li> <a href="/__pyric/ui/docs/pyric-auth-reference-sandbox-test-driver/"> Sandbox test driver </a> </li> </ul> </div><div class="docs-nav-section"> <h2 class="docs-nav-heading"> Compat </h2> <ul> <li> <a href="/__pyric/ui/docs/pyric-auth-compat/"> Compatibility matrix </a> </li> </ul> </div> </div> </details><details class="docs-nav-group"> <summary>pyric / database</summary> <div class="docs-nav-group-body"> <div class="docs-nav-section">  <ul> <li> <a href="/__pyric/ui/docs/pyric-database/"> Overview </a> </li> </ul> </div><div class="docs-nav-section"> <h2 class="docs-nav-heading"> Tutorials </h2> <ul> <li> <a href="/__pyric/ui/docs/pyric-database-tutorials-01-author-rtdb-rules-with-constraints/"> Author RTDB rules </a> </li> </ul> </div><div class="docs-nav-section"> <h2 class="docs-nav-heading"> Reference </h2> <ul> <li> <a href="/__pyric/ui/docs/pyric-database-reference-rules-tooling/"> RTDB rules tooling </a> </li> </ul> </div><div class="docs-nav-section"> <h2 class="docs-nav-heading"> Explanation </h2> <ul> <li> <a href="/__pyric/ui/docs/pyric-database-explanation-rules-authoring-and-deploy-are-separate/"> Authoring vs. deploy </a> </li> </ul> </div><div class="docs-nav-section"> <h2 class="docs-nav-heading"> Compat </h2> <ul> <li> <a href="/__pyric/ui/docs/pyric-database-compat/"> Compatibility matrix </a> </li> </ul> </div> </div> </details><details class="docs-nav-group"> <summary>pyric-admin / firestore</summary> <div class="docs-nav-group-body"> <div class="docs-nav-section">  <ul> <li> <a href="/__pyric/ui/docs/pyric-admin-firestore/"> Overview </a> </li> </ul> </div><div class="docs-nav-section"> <h2 class="docs-nav-heading"> Tutorials </h2> <ul> <li> <a href="/__pyric/ui/docs/pyric-admin-firestore-tutorials-01-first-admin-session/"> First admin session </a> </li> </ul> </div><div class="docs-nav-section"> <h2 class="docs-nav-heading"> How-to </h2> <ul> <li> <a href="/__pyric/ui/docs/pyric-admin-firestore-how-to-run-a-transaction/"> Run a transaction </a> </li><li> <a href="/__pyric/ui/docs/pyric-admin-firestore-how-to-seed-and-set-rules/"> Seed and set rules </a> </li><li> <a href="/__pyric/ui/docs/pyric-admin-firestore-how-to-translate-denials/"> Translate denials </a> </li><li> <a href="/__pyric/ui/docs/pyric-admin-firestore-how-to-use-onsnapshot/"> Use onSnapshot </a> </li><li> <a href="/__pyric/ui/docs/pyric-admin-firestore-how-to-write-a-batch/"> Write a batch </a> </li> </ul> </div><div class="docs-nav-section"> <h2 class="docs-nav-heading"> Reference </h2> <ul> <li> <a href="/__pyric/ui/docs/pyric-admin-firestore-reference-api/"> Public API </a> </li><li> <a href="/__pyric/ui/docs/pyric-admin-firestore-reference-onsnapshot/"> onSnapshot overloads </a> </li><li> <a href="/__pyric/ui/docs/pyric-admin-firestore-reference-re-exported-types/"> Re-exported types </a> </li><li> <a href="/__pyric/ui/docs/pyric-admin-firestore-reference-sandbox-firestore/"> SandboxFirestore surface </a> </li> </ul> </div><div class="docs-nav-section"> <h2 class="docs-nav-heading"> Explanation </h2> <ul> <li> <a href="/__pyric/ui/docs/pyric-admin-firestore-explanation-error-translation/"> Error translation </a> </li><li> <a href="/__pyric/ui/docs/pyric-admin-firestore-explanation-per-call-delegate/"> Per-call delegate </a> </li><li> <a href="/__pyric/ui/docs/pyric-admin-firestore-explanation-why-mirror-admin-shape/"> Why mirror the admin SDK </a> </li> </ul> </div> </div> </details><details class="docs-nav-group"> <summary>@pyric/ui</summary> <div class="docs-nav-group-body"> <div class="docs-nav-section">  <ul> <li> <a href="/__pyric/ui/docs/ui/"> Overview </a> </li> </ul> </div><div class="docs-nav-section"> <h2 class="docs-nav-heading"> Primitives </h2> <ul> <li> <a href="/__pyric/ui/docs/ui-primitives-badge/"> &lt;Badge&gt; </a> </li><li> <a href="/__pyric/ui/docs/ui-primitives-confirmdialog/"> &lt;ConfirmDialog&gt; + useConfirm </a> </li><li> <a href="/__pyric/ui/docs/ui-primitives-copybutton/"> &lt;CopyButton&gt; </a> </li><li> <a href="/__pyric/ui/docs/ui-primitives-jsonview/"> &lt;JsonView&gt; </a> </li><li> <a href="/__pyric/ui/docs/ui-primitives-segmentedcontrol/"> &lt;SegmentedControl&gt; </a> </li><li> <a href="/__pyric/ui/docs/ui-primitives-toast/"> &lt;ToastProvider&gt; + useToast </a> </li><li> <a href="/__pyric/ui/docs/ui-primitives-virtuallist/"> &lt;VirtualList&gt; </a> </li> </ul> </div><div class="docs-nav-section"> <h2 class="docs-nav-heading"> Firestore </h2> <ul> <li> <a href="/__pyric/ui/docs/ui-firestore-collectionlist/"> &lt;CollectionList&gt; </a> </li><li> <a href="/__pyric/ui/docs/ui-firestore-deletewithconfirm/"> &lt;DeleteWithConfirm&gt; </a> </li><li> <a href="/__pyric/ui/docs/ui-firestore-documenteditor/"> &lt;DocumentEditor&gt; </a> </li><li> <a href="/__pyric/ui/docs/ui-firestore-documentlist/"> &lt;DocumentList&gt; </a> </li><li> <a href="/__pyric/ui/docs/ui-firestore-documentpreview/"> &lt;DocumentPreview&gt; </a> </li><li> <a href="/__pyric/ui/docs/ui-firestore-querybuilder/"> &lt;QueryBuilder&gt; </a> </li><li> <a href="/__pyric/ui/docs/ui-firestore-referencepicker/"> &lt;ReferencePicker&gt; </a> </li> </ul> </div><div class="docs-nav-section"> <h2 class="docs-nav-heading"> Storage </h2> <ul> <li> <a href="/__pyric/ui/docs/ui-storage-deleteselectionwithconfirm/"> &lt;DeleteSelectionWithConfirm&gt; </a> </li><li> <a href="/__pyric/ui/docs/ui-storage-objectbrowser/"> &lt;ObjectBrowser&gt; </a> </li><li> <a href="/__pyric/ui/docs/ui-storage-objectinspector/"> &lt;ObjectInspector&gt; </a> </li><li> <a href="/__pyric/ui/docs/ui-storage-pathbreadcrumb/"> &lt;PathBreadcrumb&gt; </a> </li><li> <a href="/__pyric/ui/docs/ui-storage/"> @pyric/ui/storage </a> </li><li> <a href="/__pyric/ui/docs/ui-storage-uploaddropzone/"> &lt;UploadDropzone&gt; </a> </li><li> <a href="/__pyric/ui/docs/ui-storage-rules-aware-affordances/"> Rules-aware affordances </a> </li><li> <a href="/__pyric/ui/docs/ui-storage-usestoragerulesgate/"> useStorageRulesGate </a> </li> </ul> </div><div class="docs-nav-section"> <h2 class="docs-nav-heading"> Traffic </h2> <ul> <li> <a href="/__pyric/ui/docs/ui-traffic/"> @pyric/ui/traffic </a> </li><li> <a href="/__pyric/ui/docs/ui-traffic-ruleheatmap/"> &lt;RuleHeatmap&gt; </a> </li><li> <a href="/__pyric/ui/docs/ui-traffic-trafficdetail/"> &lt;TrafficDetail&gt; </a> </li><li> <a href="/__pyric/ui/docs/ui-traffic-trafficlog/"> TrafficLog components </a> </li><li> <a href="/__pyric/ui/docs/ui-traffic-trafficstats/"> &lt;TrafficStats&gt; </a> </li> </ul> </div><div class="docs-nav-section"> <h2 class="docs-nav-heading"> Auth </h2> <ul> <li> <a href="/__pyric/ui/docs/ui-auth-authsigninhelper/"> AuthSignInHelper </a> </li><li> <a href="/__pyric/ui/docs/ui-auth-authusers/"> Auth users admin </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>  <details class="docs-nav-group" id="nav-group-pyric-tools"> <summary>pyric-tools</summary> <div class="docs-nav-group-body"> <div class="docs-nav-section">  <ul> <li> <a href="/__pyric/ui/docs/pyric-tools/"> Overview </a> </li> </ul> </div><div class="docs-nav-section"> <h2 class="docs-nav-heading" id="nav-section-pyric-tools-tutorials"> Tutorials </h2> <ul> <li> <a href="/__pyric/ui/docs/pyric-tools-tutorials-getting-started/"> Getting started </a> </li><li> <a href="/__pyric/ui/docs/pyric-tools-tutorials-server-adoption/"> Server adoption </a> </li><li> <a href="/__pyric/ui/docs/pyric-tools-tutorials-wire-claude-code/"> Wire Claude Code </a> </li> </ul> </div><div class="docs-nav-section"> <h2 class="docs-nav-heading" id="nav-section-pyric-tools-how-to"> How-to </h2> <ul> <li> <a href="/__pyric/ui/docs/pyric-tools-how-to-build-a-standalone-binary/"> Build a standalone binary </a> </li><li> <a href="/__pyric/ui/docs/pyric-tools-how-to-configure-auth-providers-and-domains/"> Configure auth providers </a> </li><li> <a href="/__pyric/ui/docs/pyric-tools-how-to-discover-a-schema-from-firestore/"> Infer a schema </a> </li><li> <a href="/__pyric/ui/docs/pyric-tools-how-to-promote-sandbox-state-to-a-fixture/"> Promote sandbox state </a> </li><li> <a href="/__pyric/ui/docs/pyric-tools-how-to-serve-persistence-and-multi-tab/"> Persistence &amp; multi-tab </a> </li><li> <a href="/__pyric/ui/docs/pyric-tools-how-to-use-the-vite-plugin/"> Use the Vite plugin </a> </li><li> <a href="/__pyric/ui/docs/pyric-tools-how-to-verify-against-a-captured-session/"> Verify rules against prod </a> </li> </ul> </div><div class="docs-nav-section"> <h2 class="docs-nav-heading" id="nav-section-pyric-tools-reference"> Reference </h2> <ul> <li> <a href="/__pyric/ui/docs/pyric-tools-reference-cli/"> pyric CLI reference </a> </li><li> <a href="/__pyric/ui/docs/pyric-tools-reference-verify/"> Verify API </a> </li> </ul> </div><div class="docs-nav-section"> <h2 class="docs-nav-heading" id="nav-section-pyric-tools-bridge"> Bridge </h2> <ul> <li> <a href="/__pyric/ui/docs/pyric-tools-bridge/"> pyric-tools/bridge </a> </li> </ul> </div> </div> </details><details class="docs-nav-group" id="nav-group-pyric-tools-deploy"> <summary>pyric-tools / deploy</summary> <div class="docs-nav-group-body"> <div class="docs-nav-section">  <ul> <li> <a href="/__pyric/ui/docs/pyric-tools-deploy/"> Overview </a> </li> </ul> </div><div class="docs-nav-section"> <h2 class="docs-nav-heading" id="nav-section-pyric-tools-deploy-tutorials"> Tutorials </h2> <ul> <li> <a href="/__pyric/ui/docs/pyric-tools-deploy-tutorials-01-deploy-a-cloud-function/"> Deploy a Cloud Function </a> </li> </ul> </div><div class="docs-nav-section"> <h2 class="docs-nav-heading" id="nav-section-pyric-tools-deploy-how-to"> How-to </h2> <ul> <li> <a href="/__pyric/ui/docs/pyric-tools-deploy-how-to-build-projectscope-from-firebase-auth/"> Scope from Firebase Auth </a> </li><li> <a href="/__pyric/ui/docs/pyric-tools-deploy-how-to-build-projectscope-from-service-account/"> Scope from service account </a> </li><li> <a href="/__pyric/ui/docs/pyric-tools-deploy-how-to-bundle-and-deploy-a-function/"> Bundle &amp; deploy a function </a> </li><li> <a href="/__pyric/ui/docs/pyric-tools-deploy-how-to-deploy-firestore-indexes/"> Deploy Firestore indexes </a> </li><li> <a href="/__pyric/ui/docs/pyric-tools-deploy-how-to-deploy-firestore-rules/"> Deploy Firestore rules </a> </li><li> <a href="/__pyric/ui/docs/pyric-tools-deploy-how-to-deploy-hosting-rewrites/"> Deploy Hosting rewrites </a> </li><li> <a href="/__pyric/ui/docs/pyric-tools-deploy-how-to-deploy-realtime-database-rules/"> Deploy RTDB rules </a> </li><li> <a href="/__pyric/ui/docs/pyric-tools-deploy-how-to-deploy-to-a-preview-channel/"> Deploy to a preview channel </a> </li><li> <a href="/__pyric/ui/docs/pyric-tools-deploy-how-to-handle-errors-and-outcomes/"> Handle errors and outcomes </a> </li><li> <a href="/__pyric/ui/docs/pyric-tools-deploy-how-to-provision-a-firestore-database/"> Provision a database </a> </li><li> <a href="/__pyric/ui/docs/pyric-tools-deploy-how-to-register-tools-with-an-agent/"> Register deploy tools </a> </li> </ul> </div><div class="docs-nav-section"> <h2 class="docs-nav-heading" id="nav-section-pyric-tools-deploy-reference"> Reference </h2> <ul> <li> <a href="/__pyric/ui/docs/pyric-tools-deploy-reference-api/"> Public API </a> </li><li> <a href="/__pyric/ui/docs/pyric-tools-deploy-reference-cli-agent-io/"> pyric deploy agent I/O </a> </li><li> <a href="/__pyric/ui/docs/pyric-tools-deploy-reference-error-codes/"> Error codes by operation </a> </li><li> <a href="/__pyric/ui/docs/pyric-tools-deploy-reference-firestore-namespace/"> firestore namespace </a> </li><li> <a href="/__pyric/ui/docs/pyric-tools-deploy-reference-functions-namespace/"> functions namespace </a> </li><li> <a href="/__pyric/ui/docs/pyric-tools-deploy-reference-hosting-config/"> firebase.json hosting config </a> </li><li> <a href="/__pyric/ui/docs/pyric-tools-deploy-reference-hosting-namespace/"> hosting namespace </a> </li><li> <a href="/__pyric/ui/docs/pyric-tools-deploy-reference-rtdb-namespace/"> rtdb namespace </a> </li><li> <a href="/__pyric/ui/docs/pyric-tools-deploy-reference-scope-and-outcome/"> Scope and Outcome </a> </li><li> <a href="/__pyric/ui/docs/pyric-tools-deploy-reference-tool-factories/"> Tool factories </a> </li> </ul> </div><div class="docs-nav-section"> <h2 class="docs-nav-heading" id="nav-section-pyric-tools-deploy-explanation"> Explanation </h2> <ul> <li> <a href="/__pyric/ui/docs/pyric-tools-deploy-explanation-primitives-vs-orchestrators/"> Primitives vs. orchestrators </a> </li><li> <a href="/__pyric/ui/docs/pyric-tools-deploy-explanation-token-caching/"> Token caching and memoizeTtl </a> </li><li> <a href="/__pyric/ui/docs/pyric-tools-deploy-explanation-why-no-firebase-cli/"> Why no Firebase CLI </a> </li><li> <a href="/__pyric/ui/docs/pyric-tools-deploy-explanation-why-this-package-exists/"> Why this package exists </a> </li> </ul> </div> </div> </details><details class="docs-nav-group" id="nav-group-pyric-firestore"> <summary>pyric / firestore</summary> <div class="docs-nav-group-body"> <div class="docs-nav-section">  <ul> <li> <a href="/__pyric/ui/docs/pyric-firestore/"> Overview </a> </li> </ul> </div><div class="docs-nav-section"> <h2 class="docs-nav-heading" id="nav-section-pyric-firestore-tutorials"> Tutorials </h2> <ul> <li> <a href="/__pyric/ui/docs/pyric-firestore-tutorials-01-write-a-sandbox-demo/"> Sandbox-backed demo </a> </li><li> <a href="/__pyric/ui/docs/pyric-firestore-tutorials-02-swap-to-prod-backend/"> Swap to prod backend </a> </li> </ul> </div><div class="docs-nav-section"> <h2 class="docs-nav-heading" id="nav-section-pyric-firestore-how-to"> How-to </h2> <ul> <li> <a href="/__pyric/ui/docs/pyric-firestore-how-to-build-queries/"> Build queries </a> </li><li> <a href="/__pyric/ui/docs/pyric-firestore-how-to-migrate-from-firebase-firestore/"> Migrate from Firestore </a> </li><li> <a href="/__pyric/ui/docs/pyric-firestore-how-to-pick-a-backend/"> Pick a backend </a> </li><li> <a href="/__pyric/ui/docs/pyric-firestore-how-to-run-a-transaction/"> Run a transaction </a> </li><li> <a href="/__pyric/ui/docs/pyric-firestore-how-to-use-onsnapshot/"> Use onSnapshot </a> </li><li> <a href="/__pyric/ui/docs/pyric-firestore-how-to-use-sandbox-ops/"> Use sandbox-only ops </a> </li> </ul> </div><div class="docs-nav-section"> <h2 class="docs-nav-heading" id="nav-section-pyric-firestore-reference"> Reference </h2> <ul> <li> <a href="/__pyric/ui/docs/pyric-firestore-reference-api/"> Public API </a> </li><li> <a href="/__pyric/ui/docs/pyric-firestore-reference-feature-matrix/"> Feature matrix </a> </li><li> <a href="/__pyric/ui/docs/pyric-firestore-reference-getfirestore/"> getFirestore overloads </a> </li><li> <a href="/__pyric/ui/docs/pyric-firestore-reference-query-constraints/"> Query constraints </a> </li><li> <a href="/__pyric/ui/docs/pyric-firestore-reference-sandbox-ops/"> Sandbox-only operations </a> </li><li> <a href="/__pyric/ui/docs/pyric-firestore-reference-tool-factories/"> Tool factories </a> </li> </ul> </div><div class="docs-nav-section"> <h2 class="docs-nav-heading" id="nav-section-pyric-firestore-explanation"> Explanation </h2> <ul> <li> <a href="/__pyric/ui/docs/pyric-firestore-explanation-rules-tooling-is-separate/"> Rules tooling is separate </a> </li><li> <a href="/__pyric/ui/docs/pyric-firestore-explanation-target-symbol-opacity/"> TARGET_SYMBOL opacity </a> </li><li> <a href="/__pyric/ui/docs/pyric-firestore-explanation-two-backends-one-surface/"> Two backends, one surface </a> </li> </ul> </div><div class="docs-nav-section"> <h2 class="docs-nav-heading" id="nav-section-pyric-firestore-compat"> Compat </h2> <ul> <li> <a href="/__pyric/ui/docs/pyric-firestore-compat/"> Compatibility matrix </a> </li> </ul> </div> </div> </details><details class="docs-nav-group" id="nav-group-pyric-rules"> <summary>pyric / rules</summary> <div class="docs-nav-group-body"> <div class="docs-nav-section">  <ul> <li> <a href="/__pyric/ui/docs/pyric-rules/"> Overview </a> </li> </ul> </div><div class="docs-nav-section"> <h2 class="docs-nav-heading" id="nav-section-pyric-rules-tutorials"> Tutorials </h2> <ul> <li> <a href="/__pyric/ui/docs/pyric-rules-tutorials-01-lint-your-first-rules-file/"> Lint your first rules file </a> </li><li> <a href="/__pyric/ui/docs/pyric-rules-tutorials-02-write-a-test-suite-for-your-rules/"> Write a rules test suite </a> </li> </ul> </div><div class="docs-nav-section"> <h2 class="docs-nav-heading" id="nav-section-pyric-rules-how-to"> How-to </h2> <ul> <li> <a href="/__pyric/ui/docs/pyric-rules-how-to-compare-rulesets-for-weakening/"> Compare rulesets </a> </li><li> <a href="/__pyric/ui/docs/pyric-rules-how-to-inspect-rules-via-the-ast/"> Inspect rules via the AST </a> </li><li> <a href="/__pyric/ui/docs/pyric-rules-how-to-lint-rules-source/"> Lint a rules source </a> </li><li> <a href="/__pyric/ui/docs/pyric-rules-how-to-pin-request-time/"> Pin request.time </a> </li><li> <a href="/__pyric/ui/docs/pyric-rules-how-to-register-tools-with-an-agent/"> Register rules tools </a> </li><li> <a href="/__pyric/ui/docs/pyric-rules-how-to-resolve-module-imports/"> Resolve 2+modules imports </a> </li><li> <a href="/__pyric/ui/docs/pyric-rules-how-to-simulate-rules-locally/"> Simulate rules locally </a> </li><li> <a href="/__pyric/ui/docs/pyric-rules-how-to-test-rules-against-firebase/"> Test rules against Firebase </a> </li> </ul> </div><div class="docs-nav-section"> <h2 class="docs-nav-heading" id="nav-section-pyric-rules-reference"> Reference </h2> <ul> <li> <a href="/__pyric/ui/docs/pyric-rules-reference-api/"> Public API </a> </li><li> <a href="/__pyric/ui/docs/pyric-rules-reference-ast/"> AST </a> </li><li> <a href="/__pyric/ui/docs/pyric-rules-reference-errors/"> Errors </a> </li><li> <a href="/__pyric/ui/docs/pyric-rules-reference-lint-rules/"> Lint rules </a> </li><li> <a href="/__pyric/ui/docs/pyric-rules-reference-simulator-context/"> Simulator context </a> </li><li> <a href="/__pyric/ui/docs/pyric-rules-reference-stdlib-modules/"> Standard library modules </a> </li><li> <a href="/__pyric/ui/docs/pyric-rules-reference-test-case-schema/"> TestCase schema </a> </li><li> <a href="/__pyric/ui/docs/pyric-rules-reference-validator-findings/"> Validator findings </a> </li><li> <a href="/__pyric/ui/docs/pyric-rules-reference-value-wrappers/"> Value wrappers </a> </li> </ul> </div><div class="docs-nav-section"> <h2 class="docs-nav-heading" id="nav-section-pyric-rules-explanation"> Explanation </h2> <ul> <li> <a href="/__pyric/ui/docs/pyric-rules-explanation-agent-failure-modes/"> Agent failure modes </a> </li><li> <a href="/__pyric/ui/docs/pyric-rules-explanation-lint-vs-validate-vs-simulate-vs-test/"> Lint vs validate vs test </a> </li><li> <a href="/__pyric/ui/docs/pyric-rules-explanation-runtime-budget-and-shared-gates/"> Runtime budget and gates </a> </li><li> <a href="/__pyric/ui/docs/pyric-rules-explanation-sentinel-expression-engine/"> Sentinel expression engine </a> </li><li> <a href="/__pyric/ui/docs/pyric-rules-explanation-simulator-vs-rules-test-api/"> Simulator vs Rules Test API </a> </li><li> <a href="/__pyric/ui/docs/pyric-rules-explanation-the-2-plus-modules-extension/"> The 2+modules extension </a> </li><li> <a href="/__pyric/ui/docs/pyric-rules-explanation-value-wrappers-design/"> Value wrapper design </a> </li><li> <a href="/__pyric/ui/docs/pyric-rules-explanation-why-this-package-exists/"> Why this package exists </a> </li> </ul> </div> </div> </details><details class="docs-nav-group" id="nav-group-pyric-sandbox" open> <summary>pyric / sandbox</summary> <div class="docs-nav-group-body"> <div class="docs-nav-section">  <ul> <li> <a href="/__pyric/ui/docs/pyric-sandbox/"> Overview </a> </li> </ul> </div><div class="docs-nav-section"> <h2 class="docs-nav-heading" id="nav-section-pyric-sandbox-tutorials"> Tutorials </h2> <ul> <li> <a href="/__pyric/ui/docs/pyric-sandbox-tutorials-01-your-first-sandbox-session/"> Your first sandbox session </a> </li><li> <a href="/__pyric/ui/docs/pyric-sandbox-tutorials-02-use-the-sandbox-in-a-test-harness/"> Sandbox in a test harness </a> </li><li> <a href="/__pyric/ui/docs/pyric-sandbox-tutorials-03-build-a-traffic-monitor/"> Traffic monitor </a> </li> </ul> </div><div class="docs-nav-section"> <h2 class="docs-nav-heading" id="nav-section-pyric-sandbox-how-to"> How-to </h2> <ul> <li> <a href="/__pyric/ui/docs/pyric-sandbox-how-to-multiple-isolated-sandboxes/"> Run isolated sandboxes </a> </li><li> <a href="/__pyric/ui/docs/pyric-sandbox-how-to-observe-events/"> Observe sandbox events </a> </li><li> <a href="/__pyric/ui/docs/pyric-sandbox-how-to-pick-an-adapter/"> Pick an adapter </a> </li><li> <a href="/__pyric/ui/docs/pyric-sandbox-how-to-replay-events/"> Replay events </a> </li><li> <a href="/__pyric/ui/docs/pyric-sandbox-how-to-reset-between-tests/"> Reset between tests </a> </li><li> <a href="/__pyric/ui/docs/pyric-sandbox-how-to-seed-data-and-rules/"> Seed data and rules </a> </li><li> <a href="/__pyric/ui/docs/pyric-sandbox-how-to-switch-users/"> Switch users </a> </li><li> <a href="/__pyric/ui/docs/pyric-sandbox-how-to-use-admin-reads/"> Use admin reads </a> </li> </ul> </div><div class="docs-nav-section"> <h2 class="docs-nav-heading" id="nav-section-pyric-sandbox-reference"> Reference </h2> <ul> <li> <a href="/__pyric/ui/docs/pyric-sandbox-reference-api/"> Public API </a> </li><li> <a href="/__pyric/ui/docs/pyric-sandbox-reference-divergences/" aria-current="page"> Divergence </a> </li><li> <a href="/__pyric/ui/docs/pyric-sandbox-reference-error-codes/"> SandboxError codes </a> </li><li> <a href="/__pyric/ui/docs/pyric-sandbox-reference-internal-protocol/"> The /internal protocol </a> </li><li> <a href="/__pyric/ui/docs/pyric-sandbox-reference-sandbox-and-context/"> Sandbox and context </a> </li><li> <a href="/__pyric/ui/docs/pyric-sandbox-reference-sandbox-event/"> SandboxEvent </a> </li><li> <a href="/__pyric/ui/docs/pyric-sandbox-reference-snapshot-and-admin/"> Snapshot and admin reads </a> </li> </ul> </div><div class="docs-nav-section"> <h2 class="docs-nav-heading" id="nav-section-pyric-sandbox-explanation"> Explanation </h2> <ul> <li> <a href="/__pyric/ui/docs/pyric-sandbox-explanation-every-op-is-a-request/"> Every operation is a request </a> </li><li> <a href="/__pyric/ui/docs/pyric-sandbox-explanation-identity-is-a-context/"> Identity is a context </a> </li><li> <a href="/__pyric/ui/docs/pyric-sandbox-explanation-internal-adapter-protocol/"> The /internal protocol </a> </li><li> <a href="/__pyric/ui/docs/pyric-sandbox-explanation-listener-re-evaluation/"> Listener re-evaluation </a> </li><li> <a href="/__pyric/ui/docs/pyric-sandbox-explanation-local-backend-vs-firestore-offline/"> Local backend vs. offline </a> </li><li> <a href="/__pyric/ui/docs/pyric-sandbox-explanation-why-adapters-are-siblings/"> Why adapters are siblings </a> </li><li> <a href="/__pyric/ui/docs/pyric-sandbox-explanation-why-this-package-exists/"> Why this package exists </a> </li> </ul> </div> </div> </details><details class="docs-nav-group" id="nav-group-pyric-storage"> <summary>pyric / storage</summary> <div class="docs-nav-group-body"> <div class="docs-nav-section">  <ul> <li> <a href="/__pyric/ui/docs/pyric-storage/"> Overview </a> </li> </ul> </div><div class="docs-nav-section"> <h2 class="docs-nav-heading" id="nav-section-pyric-storage-tutorials"> Tutorials </h2> <ul> <li> <a href="/__pyric/ui/docs/pyric-storage-tutorials-01-upload-and-download/"> Upload and download </a> </li> </ul> </div><div class="docs-nav-section"> <h2 class="docs-nav-heading" id="nav-section-pyric-storage-how-to"> How-to </h2> <ul> <li> <a href="/__pyric/ui/docs/pyric-storage-how-to-enforce-rules/"> Enforce Storage rules </a> </li><li> <a href="/__pyric/ui/docs/pyric-storage-how-to-list-and-delete/"> List and delete objects </a> </li><li> <a href="/__pyric/ui/docs/pyric-storage-how-to-round-trip-metadata/"> Round-trip metadata </a> </li><li> <a href="/__pyric/ui/docs/pyric-storage-how-to-switch-backends/"> Switch backends </a> </li><li> <a href="/__pyric/ui/docs/pyric-storage-how-to-test-rule-expressions/"> Test rule expressions </a> </li> </ul> </div><div class="docs-nav-section"> <h2 class="docs-nav-heading" id="nav-section-pyric-storage-reference"> Reference </h2> <ul> <li> <a href="/__pyric/ui/docs/pyric-storage-reference-api/"> Public API </a> </li><li> <a href="/__pyric/ui/docs/pyric-storage-reference-error-codes/"> Error codes </a> </li><li> <a href="/__pyric/ui/docs/pyric-storage-reference-rules-subset/"> Storage rules subset </a> </li><li> <a href="/__pyric/ui/docs/pyric-storage-reference-storage-options/"> StorageOptions </a> </li> </ul> </div><div class="docs-nav-section"> <h2 class="docs-nav-heading" id="nav-section-pyric-storage-explanation"> Explanation </h2> <ul> <li> <a href="/__pyric/ui/docs/pyric-storage-explanation-implementation-scope/"> Implementation scope </a> </li><li> <a href="/__pyric/ui/docs/pyric-storage-explanation-session-archive-use-case/"> The session-archive driver </a> </li><li> <a href="/__pyric/ui/docs/pyric-storage-explanation-why-indexeddb/"> Why IndexedDB </a> </li> </ul> </div><div class="docs-nav-section"> <h2 class="docs-nav-heading" id="nav-section-pyric-storage-compat"> Compat </h2> <ul> <li> <a href="/__pyric/ui/docs/pyric-storage-compat/"> Compatibility matrix </a> </li> </ul> </div> </div> </details><details class="docs-nav-group" id="nav-group-pyric-auth"> <summary>pyric / auth</summary> <div class="docs-nav-group-body"> <div class="docs-nav-section">  <ul> <li> <a href="/__pyric/ui/docs/pyric-auth/"> Overview </a> </li> </ul> </div><div class="docs-nav-section"> <h2 class="docs-nav-heading" id="nav-section-pyric-auth-reference"> Reference </h2> <ul> <li> <a href="/__pyric/ui/docs/pyric-auth-reference-api/"> API reference </a> </li><li> <a href="/__pyric/ui/docs/pyric-auth-reference-feature-matrix/"> Feature matrix </a> </li><li> <a href="/__pyric/ui/docs/pyric-auth-reference-sandbox-test-driver/"> Sandbox test driver </a> </li> </ul> </div><div class="docs-nav-section"> <h2 class="docs-nav-heading" id="nav-section-pyric-auth-compat"> Compat </h2> <ul> <li> <a href="/__pyric/ui/docs/pyric-auth-compat/"> Compatibility matrix </a> </li> </ul> </div> </div> </details><details class="docs-nav-group" id="nav-group-pyric-database"> <summary>pyric / database</summary> <div class="docs-nav-group-body"> <div class="docs-nav-section">  <ul> <li> <a href="/__pyric/ui/docs/pyric-database/"> Overview </a> </li> </ul> </div><div class="docs-nav-section"> <h2 class="docs-nav-heading" id="nav-section-pyric-database-tutorials"> Tutorials </h2> <ul> <li> <a href="/__pyric/ui/docs/pyric-database-tutorials-01-author-rtdb-rules-with-constraints/"> Author RTDB rules </a> </li> </ul> </div><div class="docs-nav-section"> <h2 class="docs-nav-heading" id="nav-section-pyric-database-reference"> Reference </h2> <ul> <li> <a href="/__pyric/ui/docs/pyric-database-reference-rules-tooling/"> RTDB rules tooling </a> </li> </ul> </div><div class="docs-nav-section"> <h2 class="docs-nav-heading" id="nav-section-pyric-database-explanation"> Explanation </h2> <ul> <li> <a href="/__pyric/ui/docs/pyric-database-explanation-rules-authoring-and-deploy-are-separate/"> Authoring vs. deploy </a> </li> </ul> </div><div class="docs-nav-section"> <h2 class="docs-nav-heading" id="nav-section-pyric-database-compat"> Compat </h2> <ul> <li> <a href="/__pyric/ui/docs/pyric-database-compat/"> Compatibility matrix </a> </li> </ul> </div> </div> </details><details class="docs-nav-group" id="nav-group-pyric-admin-firestore"> <summary>pyric-admin / firestore</summary> <div class="docs-nav-group-body"> <div class="docs-nav-section">  <ul> <li> <a href="/__pyric/ui/docs/pyric-admin-firestore/"> Overview </a> </li> </ul> </div><div class="docs-nav-section"> <h2 class="docs-nav-heading" id="nav-section-pyric-admin-firestore-tutorials"> Tutorials </h2> <ul> <li> <a href="/__pyric/ui/docs/pyric-admin-firestore-tutorials-01-first-admin-session/"> First admin session </a> </li> </ul> </div><div class="docs-nav-section"> <h2 class="docs-nav-heading" id="nav-section-pyric-admin-firestore-how-to"> How-to </h2> <ul> <li> <a href="/__pyric/ui/docs/pyric-admin-firestore-how-to-run-a-transaction/"> Run a transaction </a> </li><li> <a href="/__pyric/ui/docs/pyric-admin-firestore-how-to-seed-and-set-rules/"> Seed and set rules </a> </li><li> <a href="/__pyric/ui/docs/pyric-admin-firestore-how-to-translate-denials/"> Translate denials </a> </li><li> <a href="/__pyric/ui/docs/pyric-admin-firestore-how-to-use-onsnapshot/"> Use onSnapshot </a> </li><li> <a href="/__pyric/ui/docs/pyric-admin-firestore-how-to-write-a-batch/"> Write a batch </a> </li> </ul> </div><div class="docs-nav-section"> <h2 class="docs-nav-heading" id="nav-section-pyric-admin-firestore-reference"> Reference </h2> <ul> <li> <a href="/__pyric/ui/docs/pyric-admin-firestore-reference-api/"> Public API </a> </li><li> <a href="/__pyric/ui/docs/pyric-admin-firestore-reference-onsnapshot/"> onSnapshot overloads </a> </li><li> <a href="/__pyric/ui/docs/pyric-admin-firestore-reference-re-exported-types/"> Re-exported types </a> </li><li> <a href="/__pyric/ui/docs/pyric-admin-firestore-reference-sandbox-firestore/"> SandboxFirestore surface </a> </li> </ul> </div><div class="docs-nav-section"> <h2 class="docs-nav-heading" id="nav-section-pyric-admin-firestore-explanation"> Explanation </h2> <ul> <li> <a href="/__pyric/ui/docs/pyric-admin-firestore-explanation-error-translation/"> Error translation </a> </li><li> <a href="/__pyric/ui/docs/pyric-admin-firestore-explanation-per-call-delegate/"> Per-call delegate </a> </li><li> <a href="/__pyric/ui/docs/pyric-admin-firestore-explanation-why-mirror-admin-shape/"> Why mirror the admin SDK </a> </li> </ul> </div> </div> </details><details class="docs-nav-group" id="nav-group-pyric-ui"> <summary>@pyric/ui</summary> <div class="docs-nav-group-body"> <div class="docs-nav-section">  <ul> <li> <a href="/__pyric/ui/docs/ui/"> Overview </a> </li> </ul> </div><div class="docs-nav-section"> <h2 class="docs-nav-heading" id="nav-section-pyric-ui-primitives"> Primitives </h2> <ul> <li> <a href="/__pyric/ui/docs/ui-primitives-badge/"> &lt;Badge&gt; </a> </li><li> <a href="/__pyric/ui/docs/ui-primitives-confirmdialog/"> &lt;ConfirmDialog&gt; + useConfirm </a> </li><li> <a href="/__pyric/ui/docs/ui-primitives-copybutton/"> &lt;CopyButton&gt; </a> </li><li> <a href="/__pyric/ui/docs/ui-primitives-jsonview/"> &lt;JsonView&gt; </a> </li><li> <a href="/__pyric/ui/docs/ui-primitives-segmentedcontrol/"> &lt;SegmentedControl&gt; </a> </li><li> <a href="/__pyric/ui/docs/ui-primitives-toast/"> &lt;ToastProvider&gt; + useToast </a> </li><li> <a href="/__pyric/ui/docs/ui-primitives-virtuallist/"> &lt;VirtualList&gt; </a> </li> </ul> </div><div class="docs-nav-section"> <h2 class="docs-nav-heading" id="nav-section-pyric-ui-firestore"> Firestore </h2> <ul> <li> <a href="/__pyric/ui/docs/ui-firestore-collectionlist/"> &lt;CollectionList&gt; </a> </li><li> <a href="/__pyric/ui/docs/ui-firestore-deletewithconfirm/"> &lt;DeleteWithConfirm&gt; </a> </li><li> <a href="/__pyric/ui/docs/ui-firestore-documenteditor/"> &lt;DocumentEditor&gt; </a> </li><li> <a href="/__pyric/ui/docs/ui-firestore-documentlist/"> &lt;DocumentList&gt; </a> </li><li> <a href="/__pyric/ui/docs/ui-firestore-documentpreview/"> &lt;DocumentPreview&gt; </a> </li><li> <a href="/__pyric/ui/docs/ui-firestore-querybuilder/"> &lt;QueryBuilder&gt; </a> </li><li> <a href="/__pyric/ui/docs/ui-firestore-referencepicker/"> &lt;ReferencePicker&gt; </a> </li> </ul> </div><div class="docs-nav-section"> <h2 class="docs-nav-heading" id="nav-section-pyric-ui-storage"> Storage </h2> <ul> <li> <a href="/__pyric/ui/docs/ui-storage-deleteselectionwithconfirm/"> &lt;DeleteSelectionWithConfirm&gt; </a> </li><li> <a href="/__pyric/ui/docs/ui-storage-objectbrowser/"> &lt;ObjectBrowser&gt; </a> </li><li> <a href="/__pyric/ui/docs/ui-storage-objectinspector/"> &lt;ObjectInspector&gt; </a> </li><li> <a href="/__pyric/ui/docs/ui-storage-pathbreadcrumb/"> &lt;PathBreadcrumb&gt; </a> </li><li> <a href="/__pyric/ui/docs/ui-storage/"> @pyric/ui/storage </a> </li><li> <a href="/__pyric/ui/docs/ui-storage-uploaddropzone/"> &lt;UploadDropzone&gt; </a> </li><li> <a href="/__pyric/ui/docs/ui-storage-rules-aware-affordances/"> Rules-aware affordances </a> </li><li> <a href="/__pyric/ui/docs/ui-storage-usestoragerulesgate/"> useStorageRulesGate </a> </li> </ul> </div><div class="docs-nav-section"> <h2 class="docs-nav-heading" id="nav-section-pyric-ui-traffic"> Traffic </h2> <ul> <li> <a href="/__pyric/ui/docs/ui-traffic/"> @pyric/ui/traffic </a> </li><li> <a href="/__pyric/ui/docs/ui-traffic-ruleheatmap/"> &lt;RuleHeatmap&gt; </a> </li><li> <a href="/__pyric/ui/docs/ui-traffic-trafficdetail/"> &lt;TrafficDetail&gt; </a> </li><li> <a href="/__pyric/ui/docs/ui-traffic-trafficlog/"> TrafficLog components </a> </li><li> <a href="/__pyric/ui/docs/ui-traffic-trafficstats/"> &lt;TrafficStats&gt; </a> </li> </ul> </div><div class="docs-nav-section"> <h2 class="docs-nav-heading" id="nav-section-pyric-ui-auth"> Auth </h2> <ul> <li> <a href="/__pyric/ui/docs/ui-auth-authsigninhelper/"> AuthSignInHelper </a> </li><li> <a href="/__pyric/ui/docs/ui-auth-authusers/"> Auth users admin </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> <a href="#nav-section-pyric-sandbox-reference">Reference</a> </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 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> </body> </html>

package/dist/serve/docs-ui/docs/pyric-sandbox-reference-divergences.md ADDED Viewed

@@ -0,0 +1,137 @@
+# `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.