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-explanation-internal-adapter-protocol/index.html ADDED Viewed

@@ -0,0 +1,71 @@
+<!DOCTYPE html><html lang="en"> <head><meta charset="UTF-8"><meta name="viewport" content="width=device-width, initial-scale=1.0"><title>The /internal adapter protocol · 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/"> 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/" aria-current="page"> 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/"> 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/" aria-current="page"> 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-explanation">Explanation</a> </li><li> <span class="docs-breadcrumbs-sep" aria-hidden="true">/</span> <span aria-current="page">The /internal protocol</span> </li> </ol> </nav> <article class="prose">  <h1 id="the-internal-adapter-protocol">The <code>/internal</code> adapter protocol</h1>
+<p><code>pyric/sandbox</code> ships a second sub-path: <code>pyric/sandbox/internal</code>. The public entry stays narrow — <code>Sandbox</code>, <code>SandboxContext</code>, <code>SandboxError</code>, listener channels, lifecycle. Anything an adapter needs but a consumer shouldn’t reach for lives behind the <code>/internal</code> gate.</p>
+<p>This page explains the gate and what it implies for adapter authors.</p>
+<h2 id="whats-behind-the-gate">What’s behind the gate</h2>
+<p>The substrate’s runtime types: <code>LocalEnvironment</code>, <code>EventLog</code>, transaction primitives, sentinel converters, error translation helpers. Adapter packages (<code>pyric-admin</code>, <code>pyric/firestore</code>) consume these to translate user-facing SDK calls into substrate operations.</p>
+<p>The full list is documented in <a href="../pyric-sandbox-reference-internal-protocol/">The <code>/internal</code> adapter protocol</a>.</p>
+<h2 id="why-a-gate-at-all">Why a gate at all</h2>
+<p>Three reasons to hide a surface behind a sub-path:</p>
+<ol>
+<li><strong>Discourage application use.</strong> App code that imports from <code>/internal</code> is reaching past the public API. The path name is the warning.</li>
+<li><strong>Permit breakage between minor versions.</strong> The public API is semver-stable. <code>/internal</code> is not — its shape evolves with the substrate’s needs.</li>
+<li><strong>Document the dependency direction.</strong> Adapters depend on <code>/internal</code>; the substrate doesn’t depend on adapters. The gate makes the direction visible.</li>
+</ol>
+<p>The gate is by convention, not enforcement. <code>pyric/sandbox/internal</code> is a regular subpath export. TypeScript will happily resolve it from application code. The conventional discouragement is the point — the type name, the path name, the documentation all say “this is for adapter authors”. Authors who reach past it accept the breakage risk.</p>
+<h2 id="how-adapters-use-it">How adapters use it</h2>
+<p>A typical adapter does three things with <code>/internal</code>:</p>
+<h3 id="1-resolve-the-runtime-substrate">1. Resolve the runtime substrate</h3>
+<pre class="astro-code one-dark-pro" style="background-color:#282c34;color:#abb2bf; overflow-x: auto;" tabindex="0" data-language="ts"><code><span class="line"><span style="color:#C678DD">import</span><span style="color:#ABB2BF"> { </span><span style="color:#E06C75">getInternalEnv</span><span style="color:#ABB2BF"> } </span><span style="color:#C678DD">from</span><span style="color:#98C379"> 'pyric/sandbox/internal'</span><span style="color:#ABB2BF">;</span></span>
+<span class="line"><span style="color:#C678DD">import</span><span style="color:#C678DD"> type</span><span style="color:#ABB2BF"> { </span><span style="color:#E06C75">SandboxContext</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">function</span><span style="color:#61AFEF"> getFirestore</span><span style="color:#ABB2BF">(</span><span style="color:#E06C75;font-style:italic">ctx</span><span style="color:#ABB2BF">: </span><span style="color:#E5C07B">SandboxContext</span><span style="color:#ABB2BF">): </span><span style="color:#E5C07B">FirestoreHandle</span><span style="color:#ABB2BF"> {</span></span>
+<span class="line"><span style="color:#C678DD">  const</span><span style="color:#E5C07B"> env</span><span style="color:#56B6C2"> =</span><span style="color:#61AFEF"> getInternalEnv</span><span style="color:#ABB2BF">(</span><span style="color:#E5C07B">ctx</span><span style="color:#ABB2BF">.</span><span style="color:#E06C75">sandbox</span><span style="color:#ABB2BF">);</span></span>
+<span class="line"><span style="color:#C678DD">  return</span><span style="color:#61AFEF"> buildHandleAroundEnv</span><span style="color:#ABB2BF">(</span><span style="color:#E06C75">env</span><span style="color:#ABB2BF">, </span><span style="color:#E5C07B">ctx</span><span style="color:#ABB2BF">.</span><span style="color:#E06C75">auth</span><span style="color:#ABB2BF">);</span></span>
+<span class="line"><span style="color:#ABB2BF">}</span></span></code></pre>
+<p><code>getInternalEnv</code> throws if the <code>Sandbox</code> wasn’t produced by <code>initializeSandbox</code> — adapters can rely on this to reject malformed input early.</p>
+<h3 id="2-translate-user-calls-to-substrate-operations">2. Translate user calls to substrate operations</h3>
+<pre class="astro-code one-dark-pro" style="background-color:#282c34;color:#abb2bf; overflow-x: auto;" tabindex="0" data-language="ts"><code><span class="line"><span style="color:#C678DD">import</span><span style="color:#C678DD"> type</span><span style="color:#ABB2BF"> { </span><span style="color:#E06C75">Operation</span><span style="color:#ABB2BF">, </span><span style="color:#E06C75">OperationResult</span><span style="color:#ABB2BF"> } </span><span style="color:#C678DD">from</span><span style="color:#98C379"> 'pyric/sandbox/internal'</span><span style="color:#ABB2BF">;</span></span>
+<span class="line"></span>
+<span class="line"><span style="color:#C678DD">async</span><span style="color:#C678DD"> function</span><span style="color:#61AFEF"> set</span><span style="color:#ABB2BF">(</span><span style="color:#E06C75;font-style:italic">handle</span><span style="color:#ABB2BF">, </span><span style="color:#E06C75;font-style:italic">path</span><span style="color:#ABB2BF">, </span><span style="color:#E06C75;font-style:italic">data</span><span style="color:#ABB2BF">) {</span></span>
+<span class="line"><span style="color:#C678DD">  const</span><span style="color:#E5C07B"> operation</span><span style="color:#ABB2BF">: </span><span style="color:#E5C07B">Operation</span><span style="color:#56B6C2"> =</span><span style="color:#ABB2BF"> {</span></span>
+<span class="line"><span style="color:#E06C75">    method</span><span style="color:#ABB2BF">: </span><span style="color:#E06C75">data</span><span style="color:#C678DD"> ?</span><span style="color:#98C379"> 'set'</span><span style="color:#C678DD"> :</span><span style="color:#98C379"> 'delete'</span><span style="color:#ABB2BF">,</span></span>
+<span class="line"><span style="color:#E06C75">    path</span><span style="color:#ABB2BF">,</span></span>
+<span class="line"><span style="color:#E06C75">    auth</span><span style="color:#ABB2BF">: </span><span style="color:#E5C07B">handle</span><span style="color:#ABB2BF">.</span><span style="color:#E06C75">auth</span><span style="color:#ABB2BF">,</span></span>
+<span class="line"><span style="color:#E06C75">    data</span><span style="color:#ABB2BF">,</span></span>
+<span class="line"><span style="color:#ABB2BF">  };</span></span>
+<span class="line"><span style="color:#C678DD">  const</span><span style="color:#E5C07B"> result</span><span style="color:#ABB2BF">: </span><span style="color:#E5C07B">OperationResult</span><span style="color:#56B6C2"> =</span><span style="color:#E5C07B"> handle</span><span style="color:#ABB2BF">.</span><span style="color:#E5C07B">env</span><span style="color:#ABB2BF">.</span><span style="color:#61AFEF">execute</span><span style="color:#ABB2BF">(</span><span style="color:#E06C75">operation</span><span style="color:#ABB2BF">);</span></span>
+<span class="line"><span style="color:#C678DD">  if</span><span style="color:#ABB2BF"> (</span><span style="color:#56B6C2">!</span><span style="color:#E5C07B">result</span><span style="color:#ABB2BF">.</span><span style="color:#E06C75">allowed</span><span style="color:#ABB2BF">) </span><span style="color:#C678DD">throw</span><span style="color:#61AFEF"> translateError</span><span style="color:#ABB2BF">(</span><span style="color:#E5C07B">result</span><span style="color:#ABB2BF">.</span><span style="color:#E06C75">error</span><span style="color:#ABB2BF">);</span></span>
+<span class="line"><span style="color:#C678DD">  return</span><span style="color:#E06C75"> result</span><span style="color:#ABB2BF">;</span></span>
+<span class="line"><span style="color:#ABB2BF">}</span></span></code></pre>
+<p>Operations are plain shapes. Each adapter writes its own translation logic — <code>pyric-admin</code> translates chainable calls, <code>pyric/firestore</code> translates modular function calls. Both produce <code>Operation</code> and consume <code>OperationResult</code>.</p>
+<h3 id="3-resolve-sentinels">3. Resolve sentinels</h3>
+<pre class="astro-code one-dark-pro" style="background-color:#282c34;color:#abb2bf; overflow-x: auto;" tabindex="0" data-language="ts"><code><span class="line"><span style="color:#C678DD">import</span><span style="color:#ABB2BF"> { </span><span style="color:#E06C75">resolveValueTree</span><span style="color:#ABB2BF">, </span><span style="color:#E06C75">registerDefaultConverters</span><span style="color:#ABB2BF"> } </span><span style="color:#C678DD">from</span><span style="color:#98C379"> 'pyric/sandbox/internal'</span><span style="color:#ABB2BF">;</span></span></code></pre>
+<p>Sentinels (<code>FieldValue.increment</code>, <code>serverTimestamp</code>, <code>arrayUnion</code>) are values the substrate doesn’t store directly — they describe an operation on the current document. The adapter resolves them via <code>resolveValueTree(payload, env, method)</code> before handing the payload to <code>LocalEnvironment.execute</code>.</p>
+<h2 id="what-adapters-shouldnt-do">What adapters shouldn’t do</h2>
+<h3 id="treat-internal-as-a-stable-api-surface">Treat <code>/internal</code> as a stable API surface</h3>
+<p>The shape changes when the substrate’s needs change. Methods get renamed. Types get widened. New parameters appear. The package’s semver does not protect <code>/internal</code>.</p>
+<p>In practice, the surface has been stable for months at a time — the substrate isn’t churning. But “stable in practice” is not “stable by contract”. Adapter authors should pin to specific versions of <code>pyric/sandbox</code> and update deliberately.</p>
+<h3 id="add-business-logic-to-the-substrate">Add business logic to the substrate</h3>
+<p>If a piece of behaviour translates user intent (“interpret this dot-path update as a nested-map patch”, “merge this batch’s writes by collection”, “schedule this snapshot listener fire after the current micro-task”), it belongs in the adapter, not in <code>/internal</code>. The substrate stores documents and runs rules. Anything beyond that is adapter responsibility.</p>
+<p>This rule keeps the substrate small. Adapters can differ in their merge semantics, their fire timing, their reference identity model — all live in the adapter, the substrate doesn’t care.</p>
+<h3 id="import-from-internal-in-application-code">Import from <code>/internal</code> in application code</h3>
+<p>Application code uses <code>pyric-admin</code> or <code>pyric/firestore</code>. The reason is forward-compatibility: if a future minor release changes a <code>/internal</code> type, the adapter absorbs the change and the application doesn’t notice. Application code that imports from <code>/internal</code> becomes a breakage liability the next time the substrate evolves.</p>
+<p>If an application needs something an adapter doesn’t expose, the right move is to file a request on the adapter — not to reach into <code>/internal</code> and add the wrapping itself.</p>
+<h2 id="the-star-export-decision">The star-export decision</h2>
+<p>The <code>/internal</code> index uses <code>export * from '../firestore/local-environment.js'</code> and similar wildcards. The alternative is a hand-maintained named-export list.</p>
+<p>We picked stars because:</p>
+<ul>
+<li><code>pyric-admin</code> reaches in for a long tail of helper symbols (<code>DELETE_MARKER</code>, <code>KEEP</code>, <code>FIRESTORE_ERROR_CODES</code>, etc.). The list is dozens of entries.</li>
+<li>Keeping the named-export list in sync with the moved files’ actual exports creates maintenance churn — every new export needs two changes.</li>
+<li>Star exports propagate automatically. Add a new export to a moved file, it appears at <code>pyric/sandbox/internal</code>.</li>
+</ul>
+<p>The downside is that adding a new public export in a moved file silently appears on <code>/internal</code> without an explicit decision. We accept that: anything in those files is intended to be reachable by adapters; the gate isn’t there to filter, it’s there to label the surface.</p>
+<h2 id="will-internal-ever-be-promoted">Will <code>/internal</code> ever be promoted?</h2>
+<p>When the multi-service architecture lands (Auth, RTDB, Storage all sharing one <code>LocalEnvironment</code>) the substrate’s surface will need to stabilise. At that point parts of <code>/internal</code> will likely be promoted to the public API — probably the parts adapters need most (<code>Operation</code>, <code>OperationResult</code>, sentinel conversion).</p>
+<p>Promotion will be deliberate. Each symbol that moves to the public API gets:</p>
+<ul>
+<li>A documented contract on the public reference page.</li>
+<li>Semver protection going forward.</li>
+<li>A removal from <code>/internal</code> (or kept as a re-export for adapter compatibility).</li>
+</ul>
+<p>Until then, <code>/internal</code> is the place where the protocol evolves.</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="#whats-behind-the-gate">What’s behind the gate</a> </li><li data-depth="2"> <a href="#why-a-gate-at-all">Why a gate at all</a> </li><li data-depth="2"> <a href="#how-adapters-use-it">How adapters use it</a> </li><li data-depth="3"> <a href="#1-resolve-the-runtime-substrate">1. Resolve the runtime substrate</a> </li><li data-depth="3"> <a href="#2-translate-user-calls-to-substrate-operations">2. Translate user calls to substrate operations</a> </li><li data-depth="3"> <a href="#3-resolve-sentinels">3. Resolve sentinels</a> </li><li data-depth="2"> <a href="#what-adapters-shouldnt-do">What adapters shouldn’t do</a> </li><li data-depth="3"> <a href="#treat-internal-as-a-stable-api-surface">Treat /internal as a stable API surface</a> </li><li data-depth="3"> <a href="#add-business-logic-to-the-substrate">Add business logic to the substrate</a> </li><li data-depth="3"> <a href="#import-from-internal-in-application-code">Import from /internal in application code</a> </li><li data-depth="2"> <a href="#the-star-export-decision">The star-export decision</a> </li><li data-depth="2"> <a href="#will-internal-ever-be-promoted">Will /internal ever be promoted?</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-explanation-internal-adapter-protocol.md ADDED Viewed

@@ -0,0 +1,105 @@
+# The `/internal` adapter protocol
+`pyric/sandbox` ships a second sub-path: `pyric/sandbox/internal`. The public entry stays narrow — `Sandbox`, `SandboxContext`, `SandboxError`, listener channels, lifecycle. Anything an adapter needs but a consumer shouldn't reach for lives behind the `/internal` gate.
+This page explains the gate and what it implies for adapter authors.
+## What's behind the gate
+The substrate's runtime types: `LocalEnvironment`, `EventLog`, transaction primitives, sentinel converters, error translation helpers. Adapter packages (`pyric-admin`, `pyric/firestore`) consume these to translate user-facing SDK calls into substrate operations.
+The full list is documented in [The `/internal` adapter protocol](../pyric-sandbox-reference-internal-protocol/).
+## Why a gate at all
+Three reasons to hide a surface behind a sub-path:
+1. **Discourage application use.** App code that imports from `/internal` is reaching past the public API. The path name is the warning.
+2. **Permit breakage between minor versions.** The public API is semver-stable. `/internal` is not — its shape evolves with the substrate's needs.
+3. **Document the dependency direction.** Adapters depend on `/internal`; the substrate doesn't depend on adapters. The gate makes the direction visible.
+The gate is by convention, not enforcement. `pyric/sandbox/internal` is a regular subpath export. TypeScript will happily resolve it from application code. The conventional discouragement is the point — the type name, the path name, the documentation all say "this is for adapter authors". Authors who reach past it accept the breakage risk.
+## How adapters use it
+A typical adapter does three things with `/internal`:
+### 1. Resolve the runtime substrate
+```ts
+import { getInternalEnv } from 'pyric/sandbox/internal';
+import type { SandboxContext } from 'pyric/sandbox';
+function getFirestore(ctx: SandboxContext): FirestoreHandle {
+  const env = getInternalEnv(ctx.sandbox);
+  return buildHandleAroundEnv(env, ctx.auth);
+}
+```
+`getInternalEnv` throws if the `Sandbox` wasn't produced by `initializeSandbox` — adapters can rely on this to reject malformed input early.
+### 2. Translate user calls to substrate operations
+```ts
+import type { Operation, OperationResult } from 'pyric/sandbox/internal';
+async function set(handle, path, data) {
+  const operation: Operation = {
+    method: data ? 'set' : 'delete',
+    path,
+    auth: handle.auth,
+    data,
+  };
+  const result: OperationResult = handle.env.execute(operation);
+  if (!result.allowed) throw translateError(result.error);
+  return result;
+}
+```
+Operations are plain shapes. Each adapter writes its own translation logic — `pyric-admin` translates chainable calls, `pyric/firestore` translates modular function calls. Both produce `Operation` and consume `OperationResult`.
+### 3. Resolve sentinels
+```ts
+import { resolveValueTree, registerDefaultConverters } from 'pyric/sandbox/internal';
+```
+Sentinels (`FieldValue.increment`, `serverTimestamp`, `arrayUnion`) are values the substrate doesn't store directly — they describe an operation on the current document. The adapter resolves them via `resolveValueTree(payload, env, method)` before handing the payload to `LocalEnvironment.execute`.
+## What adapters shouldn't do
+### Treat `/internal` as a stable API surface
+The shape changes when the substrate's needs change. Methods get renamed. Types get widened. New parameters appear. The package's semver does not protect `/internal`.
+In practice, the surface has been stable for months at a time — the substrate isn't churning. But "stable in practice" is not "stable by contract". Adapter authors should pin to specific versions of `pyric/sandbox` and update deliberately.
+### Add business logic to the substrate
+If a piece of behaviour translates user intent ("interpret this dot-path update as a nested-map patch", "merge this batch's writes by collection", "schedule this snapshot listener fire after the current micro-task"), it belongs in the adapter, not in `/internal`. The substrate stores documents and runs rules. Anything beyond that is adapter responsibility.
+This rule keeps the substrate small. Adapters can differ in their merge semantics, their fire timing, their reference identity model — all live in the adapter, the substrate doesn't care.
+### Import from `/internal` in application code
+Application code uses `pyric-admin` or `pyric/firestore`. The reason is forward-compatibility: if a future minor release changes a `/internal` type, the adapter absorbs the change and the application doesn't notice. Application code that imports from `/internal` becomes a breakage liability the next time the substrate evolves.
+If an application needs something an adapter doesn't expose, the right move is to file a request on the adapter — not to reach into `/internal` and add the wrapping itself.
+## The star-export decision
+The `/internal` index uses `export * from '../firestore/local-environment.js'` and similar wildcards. The alternative is a hand-maintained named-export list.
+We picked stars because:
+- `pyric-admin` reaches in for a long tail of helper symbols (`DELETE_MARKER`, `KEEP`, `FIRESTORE_ERROR_CODES`, etc.). The list is dozens of entries.
+- Keeping the named-export list in sync with the moved files' actual exports creates maintenance churn — every new export needs two changes.
+- Star exports propagate automatically. Add a new export to a moved file, it appears at `pyric/sandbox/internal`.
+The downside is that adding a new public export in a moved file silently appears on `/internal` without an explicit decision. We accept that: anything in those files is intended to be reachable by adapters; the gate isn't there to filter, it's there to label the surface.
+## Will `/internal` ever be promoted?
+When the multi-service architecture lands (Auth, RTDB, Storage all sharing one `LocalEnvironment`) the substrate's surface will need to stabilise. At that point parts of `/internal` will likely be promoted to the public API — probably the parts adapters need most (`Operation`, `OperationResult`, sentinel conversion).
+Promotion will be deliberate. Each symbol that moves to the public API gets:
+- A documented contract on the public reference page.
+- Semver protection going forward.
+- A removal from `/internal` (or kept as a re-export for adapter compatibility).
+Until then, `/internal` is the place where the protocol evolves.