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

@pyric/cli 0.1.0-alpha.9

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

Files changed (1169) hide show

package/dist/serve/docs-ui/docs/pyric-storage-explanation-implementation-scope/index.html ADDED Viewed

@@ -0,0 +1,52 @@
+<!DOCTYPE html><html lang="en"> <head><meta charset="UTF-8"><meta name="viewport" content="width=device-width, initial-scale=1.0"><title>Implementation scope and deferred features · Pyric Studio</title><link rel="preconnect" href="https://fonts.googleapis.com"><link rel="preconnect" href="https://fonts.gstatic.com" crossorigin><link href="https://fonts.googleapis.com/css2?family=Inter:wght@300;400;500;600;700&family=JetBrains+Mono:wght@400;500;700&display=swap" rel="stylesheet"><link rel="stylesheet" href="/__pyric/ui/_astro/_slug_.CQYSemvw.css"></head> <body>  <header class="studio__bar"> <div class="studio__bar-inner"> <a class="studio__brand" href="/__pyric/ui/" aria-label="Pyric Studio">Pyric</a> <nav class="studio__nav" aria-label="Studio tabs"> <a class="studio__nav-tab" href="/__pyric/ui/"> Home </a><a class="studio__nav-tab" href="/__pyric/ui/firestore"> Firestore </a><a class="studio__nav-tab" href="/__pyric/ui/auth"> Auth </a><a class="studio__nav-tab" href="/__pyric/ui/rtdb"> RTDB </a><a class="studio__nav-tab" href="/__pyric/ui/storage"> Storage </a><a class="studio__nav-tab" href="/__pyric/ui/traffic"> Traffic </a><a class="studio__nav-tab" href="/__pyric/ui/settings"> Settings </a><a class="studio__nav-tab" href="/__pyric/ui/docs" aria-current="page"> Docs </a> </nav> </div> </header> <div class="docs-shell">  <details class="docs-nav-drawer"> <summary>Navigate</summary> <nav class="docs-nav" aria-label="Documentation"> <div class="docs-search" data-index-url="/__pyric/ui/docs/index.json"> <div class="docs-search-field"> <svg class="docs-search-icon" viewBox="0 0 16 16" width="14" height="14" aria-hidden="true"> <path d="M11.5 11.5 15 15M13 7A6 6 0 1 1 1 7a6 6 0 0 1 12 0Z" fill="none" stroke="currentColor" stroke-width="1.4" stroke-linecap="round"></path> </svg> <input type="text" class="docs-search-input" placeholder="Search docs" aria-label="Search docs" autocomplete="off" spellcheck="false"> <kbd class="docs-search-kbd">⌘K</kbd> </div> <ul class="docs-search-results" hidden></ul> </div> <script type="module">let i=null;function d(t){return i||(i=fetch(t).then(e=>e.json())),i}function l(t,e){return t.title.toLowerCase().includes(e)||t.excerpt.toLowerCase().includes(e)?!0:t.headings.some(r=>r.text.toLowerCase().includes(e))}function u(t,e,r){if(e.innerHTML="",t.length===0){e.hidden=!1;{const n=document.createElement("li");n.className="docs-search-empty",n.textContent="No matches",e.appendChild(n)}return}e.hidden=!1;for(const n of t.slice(0,8)){const s=document.createElement("li"),c=document.createElement("a");c.href=n.path;const o=document.createElement("span");o.className="docs-search-result-title",o.textContent=n.title;const a=document.createElement("span");a.className="docs-search-result-meta",a.textContent=[n.group,n.section].filter(Boolean).join(" / "),c.append(o,a),s.appendChild(c),e.appendChild(s)}}document.querySelectorAll(".docs-search").forEach(t=>{const e=t.dataset.indexUrl,r=t.querySelector(".docs-search-input"),n=t.querySelector(".docs-search-results");r.addEventListener("input",async()=>{const s=r.value.trim().toLowerCase();if(!s){n.hidden=!0,n.innerHTML="";return}const{pages:c}=await d(e);r.value.trim().toLowerCase()===s&&u(c.filter(o=>l(o,s)),n)}),r.addEventListener("focus",()=>{d(e),n.childElementCount>0&&(n.hidden=!1)}),r.addEventListener("keydown",s=>{s.key==="Escape"&&(r.value="",n.hidden=!0,n.innerHTML="",r.blur())}),r.addEventListener("blur",()=>{window.setTimeout(()=>{n.hidden=!0},150)})});document.addEventListener("keydown",t=>{if(!(t.metaKey||t.ctrlKey)||t.key.toLowerCase()!=="k")return;const e=[...document.querySelectorAll(".docs-search-input")].find(r=>r.offsetParent!==null);e&&(t.preventDefault(),e.focus(),e.select())});</script> <a class="docs-nav-toplink" href="/__pyric/ui/docs/overview/"> Overview </a><details class="docs-nav-group"> <summary>Run locally</summary> <div class="docs-nav-group-body"> <div class="docs-nav-section">  <ul> <li> <a href="/__pyric/ui/docs/start-building/"> Quickstart </a> </li><li> <a href="/__pyric/ui/docs/how-the-swap-works/"> How the swap works </a> </li><li> <a href="/__pyric/ui/docs/set-up-your-agent/"> Connect an agent </a> </li><li> <a href="/__pyric/ui/docs/test-in-node/"> Test in Node </a> </li> </ul> </div> </div> </details><details class="docs-nav-group"> <summary>Develop with Firebase APIs</summary> <div class="docs-nav-group-body"> <div class="docs-nav-section">  <ul> <li> <a href="/__pyric/ui/docs/sign-in-and-manage-users/"> Sign in and manage users </a> </li><li> <a href="/__pyric/ui/docs/store-and-query-data/"> Store and query data </a> </li><li> <a href="/__pyric/ui/docs/sync-realtime-data/"> Sync realtime data </a> </li><li> <a href="/__pyric/ui/docs/store-files/"> Store files </a> </li><li> <a href="/__pyric/ui/docs/receive-messages/"> Receive messages </a> </li><li> <a href="/__pyric/ui/docs/run-ai-logic-locally/"> Run AI Logic locally </a> </li><li> <a href="/__pyric/ui/docs/pyric-cli-how-to-run-rtdb-onvaluecreated/"> Run an RTDB function locally </a> </li><li> <a href="/__pyric/ui/docs/which-data-service/"> Which data service? </a> </li> </ul> </div> </div> </details><details class="docs-nav-group"> <summary>Inspect and correct</summary> <div class="docs-nav-group-body"> <div class="docs-nav-section"> <h2 class="docs-nav-heading"> Inspect the sandbox </h2> <ul> <li> <a href="/__pyric/ui/docs/see-whats-happening/"> Traffic &amp; rule verdicts </a> </li><li> <a href="/__pyric/ui/docs/read-a-denial/"> Read a denial and understand it </a> </li><li> <a href="/__pyric/ui/docs/shape-your-data/"> Seed, snapshot, replay </a> </li><li> <a href="/__pyric/ui/docs/watch-and-review/"> Review agent activity </a> </li> </ul> </div><div class="docs-nav-section"> <h2 class="docs-nav-heading"> Correct Security Rules </h2> <ul> <li> <a href="/__pyric/ui/docs/secure-it-with-rules/"> Security Rules </a> </li><li> <a href="/__pyric/ui/docs/simulate-and-lint/"> Simulate and lint before you deploy </a> </li><li> <a href="/__pyric/ui/docs/rules-patterns/"> Rules patterns </a> </li><li> <a href="/__pyric/ui/docs/rules-standard-library/"> The rules standard library </a> </li><li> <a href="/__pyric/ui/docs/rtdb-rules-in-typescript/"> RTDB rules in TypeScript </a> </li><li> <a href="/__pyric/ui/docs/firestore-rules-limits/"> Rules limits </a> </li><li> <a href="/__pyric/ui/docs/whats-possible/"> Case studies </a> </li> </ul> </div><div class="docs-nav-section"> <h2 class="docs-nav-heading"> Work with an agent </h2> <ul> <li> <a href="/__pyric/ui/docs/what-your-agent-can-do/"> Work through an agent </a> </li><li> <a href="/__pyric/ui/docs/skills/"> Agent skills </a> </li> </ul> </div> </div> </details><details class="docs-nav-group"> <summary>Verify the boundary</summary> <div class="docs-nav-group-body"> <div class="docs-nav-section">  <ul> <li> <a href="/__pyric/ui/docs/pyric-cli-how-to-verify-against-a-captured-session/"> Verify a captured session </a> </li><li> <a href="/__pyric/ui/docs/write-a-rules-test-suite/"> Write a rules test suite </a> </li><li> <a href="/__pyric/ui/docs/audit-your-rules/"> Audit rules and data </a> </li> </ul> </div> </div> </details><details class="docs-nav-group"> <summary>Ship unchanged</summary> <div class="docs-nav-group-body"> <div class="docs-nav-section">  <ul> <li> <a href="/__pyric/ui/docs/ship-to-production/"> Ship to production </a> </li><li> <a href="/__pyric/ui/docs/set-up-the-project/"> Set up the Firebase project </a> </li> </ul> </div> </div> </details><details class="docs-nav-group"> <summary>Conformance</summary> <div class="docs-nav-group-body"> <div class="docs-nav-section">  <ul> <li> <a href="/__pyric/ui/docs/how-we-know-it-matches-firebase/"> Conformance </a> </li><li> <a href="/__pyric/ui/docs/whats-experimental/"> What&#39;s experimental </a> </li><li> <a href="/__pyric/ui/docs/pyric-conformance-scores/"> Conformance scores </a> </li><li> <a href="/__pyric/ui/docs/pyric-app-compat/"> App </a> </li><li> <a href="/__pyric/ui/docs/pyric-firestore-compat/"> Firestore </a> </li><li> <a href="/__pyric/ui/docs/pyric-auth-compat/"> Auth </a> </li><li> <a href="/__pyric/ui/docs/pyric-database-compat/"> Realtime Database </a> </li><li> <a href="/__pyric/ui/docs/pyric-storage-compat/"> Storage </a> </li><li> <a href="/__pyric/ui/docs/pyric-rules-compat/"> Rules </a> </li><li> <a href="/__pyric/ui/docs/pyric-messaging-compat/"> Messaging </a> </li><li> <a href="/__pyric/ui/docs/pyric-ai-compat/"> AI Logic </a> </li><li> <a href="/__pyric/ui/docs/pyric-cli-functions-rtdb-compat/"> Functions · RTDB </a> </li> </ul> </div> </div> </details> <details class="docs-nav-group" open> <summary>Reference</summary> <div class="docs-nav-group-body"> <div class="docs-nav-section"> <ul> <li> <a href="/__pyric/ui/docs/pyric-cli/"> @pyric/cli </a> </li><li> <a href="/__pyric/ui/docs/pyric-explanation-versioning-and-compatibility/"> pyric </a> </li><li> <a href="/__pyric/ui/docs/pyric-firestore/"> pyric / firestore </a> </li><li> <a href="/__pyric/ui/docs/pyric-rules/"> pyric / rules </a> </li><li> <a href="/__pyric/ui/docs/pyric-sandbox/"> pyric / sandbox </a> </li><li> <a href="/__pyric/ui/docs/pyric-storage/" aria-current="true"> pyric / storage </a> </li><li> <a href="/__pyric/ui/docs/pyric-auth/"> pyric / auth </a> </li><li> <a href="/__pyric/ui/docs/pyric-database/"> pyric / database </a> </li><li> <a href="/__pyric/ui/docs/pyric-admin-app/"> pyric-admin / app </a> </li><li> <a href="/__pyric/ui/docs/pyric-admin-firestore/"> pyric-admin / firestore </a> </li><li> <a href="/__pyric/ui/docs/pyric-admin-auth/"> pyric-admin / auth </a> </li><li> <a href="/__pyric/ui/docs/pyric-admin-database/"> pyric-admin / database </a> </li><li> <a href="/__pyric/ui/docs/pyric-admin-storage/"> pyric-admin / storage </a> </li><li> <a href="/__pyric/ui/docs/ui/"> @pyric/ui </a> </li><li> <a href="/__pyric/ui/docs/api-reference/"> API reference </a> </li> </ul> </div> </div> </details> </nav> </details> <nav class="docs-nav" aria-label="Documentation"> <div class="docs-search" data-index-url="/__pyric/ui/docs/index.json"> <div class="docs-search-field"> <svg class="docs-search-icon" viewBox="0 0 16 16" width="14" height="14" aria-hidden="true"> <path d="M11.5 11.5 15 15M13 7A6 6 0 1 1 1 7a6 6 0 0 1 12 0Z" fill="none" stroke="currentColor" stroke-width="1.4" stroke-linecap="round"></path> </svg> <input type="text" class="docs-search-input" placeholder="Search docs" aria-label="Search docs" autocomplete="off" spellcheck="false"> <kbd class="docs-search-kbd">⌘K</kbd> </div> <ul class="docs-search-results" hidden></ul> </div>  <a class="docs-nav-toplink" href="/__pyric/ui/docs/overview/" id="nav-group-overview"> Overview </a><details class="docs-nav-group" id="nav-group-run-locally"> <summary>Run locally</summary> <div class="docs-nav-group-body"> <div class="docs-nav-section">  <ul> <li> <a href="/__pyric/ui/docs/start-building/"> Quickstart </a> </li><li> <a href="/__pyric/ui/docs/how-the-swap-works/"> How the swap works </a> </li><li> <a href="/__pyric/ui/docs/set-up-your-agent/"> Connect an agent </a> </li><li> <a href="/__pyric/ui/docs/test-in-node/"> Test in Node </a> </li> </ul> </div> </div> </details><details class="docs-nav-group" id="nav-group-develop-with-firebase-apis"> <summary>Develop with Firebase APIs</summary> <div class="docs-nav-group-body"> <div class="docs-nav-section">  <ul> <li> <a href="/__pyric/ui/docs/sign-in-and-manage-users/"> Sign in and manage users </a> </li><li> <a href="/__pyric/ui/docs/store-and-query-data/"> Store and query data </a> </li><li> <a href="/__pyric/ui/docs/sync-realtime-data/"> Sync realtime data </a> </li><li> <a href="/__pyric/ui/docs/store-files/"> Store files </a> </li><li> <a href="/__pyric/ui/docs/receive-messages/"> Receive messages </a> </li><li> <a href="/__pyric/ui/docs/run-ai-logic-locally/"> Run AI Logic locally </a> </li><li> <a href="/__pyric/ui/docs/pyric-cli-how-to-run-rtdb-onvaluecreated/"> Run an RTDB function locally </a> </li><li> <a href="/__pyric/ui/docs/which-data-service/"> Which data service? </a> </li> </ul> </div> </div> </details><details class="docs-nav-group" id="nav-group-inspect-and-correct"> <summary>Inspect and correct</summary> <div class="docs-nav-group-body"> <div class="docs-nav-section"> <h2 class="docs-nav-heading" id="nav-section-inspect-and-correct-inspect-the-sandbox"> Inspect the sandbox </h2> <ul> <li> <a href="/__pyric/ui/docs/see-whats-happening/"> Traffic &amp; rule verdicts </a> </li><li> <a href="/__pyric/ui/docs/read-a-denial/"> Read a denial and understand it </a> </li><li> <a href="/__pyric/ui/docs/shape-your-data/"> Seed, snapshot, replay </a> </li><li> <a href="/__pyric/ui/docs/watch-and-review/"> Review agent activity </a> </li> </ul> </div><div class="docs-nav-section"> <h2 class="docs-nav-heading" id="nav-section-inspect-and-correct-correct-security-rules"> Correct Security Rules </h2> <ul> <li> <a href="/__pyric/ui/docs/secure-it-with-rules/"> Security Rules </a> </li><li> <a href="/__pyric/ui/docs/simulate-and-lint/"> Simulate and lint before you deploy </a> </li><li> <a href="/__pyric/ui/docs/rules-patterns/"> Rules patterns </a> </li><li> <a href="/__pyric/ui/docs/rules-standard-library/"> The rules standard library </a> </li><li> <a href="/__pyric/ui/docs/rtdb-rules-in-typescript/"> RTDB rules in TypeScript </a> </li><li> <a href="/__pyric/ui/docs/firestore-rules-limits/"> Rules limits </a> </li><li> <a href="/__pyric/ui/docs/whats-possible/"> Case studies </a> </li> </ul> </div><div class="docs-nav-section"> <h2 class="docs-nav-heading" id="nav-section-inspect-and-correct-work-with-an-agent"> Work with an agent </h2> <ul> <li> <a href="/__pyric/ui/docs/what-your-agent-can-do/"> Work through an agent </a> </li><li> <a href="/__pyric/ui/docs/skills/"> Agent skills </a> </li> </ul> </div> </div> </details><details class="docs-nav-group" id="nav-group-verify-the-boundary"> <summary>Verify the boundary</summary> <div class="docs-nav-group-body"> <div class="docs-nav-section">  <ul> <li> <a href="/__pyric/ui/docs/pyric-cli-how-to-verify-against-a-captured-session/"> Verify a captured session </a> </li><li> <a href="/__pyric/ui/docs/write-a-rules-test-suite/"> Write a rules test suite </a> </li><li> <a href="/__pyric/ui/docs/audit-your-rules/"> Audit rules and data </a> </li> </ul> </div> </div> </details><details class="docs-nav-group" id="nav-group-ship-unchanged"> <summary>Ship unchanged</summary> <div class="docs-nav-group-body"> <div class="docs-nav-section">  <ul> <li> <a href="/__pyric/ui/docs/ship-to-production/"> Ship to production </a> </li><li> <a href="/__pyric/ui/docs/set-up-the-project/"> Set up the Firebase project </a> </li> </ul> </div> </div> </details><details class="docs-nav-group" id="nav-group-conformance"> <summary>Conformance</summary> <div class="docs-nav-group-body"> <div class="docs-nav-section">  <ul> <li> <a href="/__pyric/ui/docs/how-we-know-it-matches-firebase/"> Conformance </a> </li><li> <a href="/__pyric/ui/docs/whats-experimental/"> What&#39;s experimental </a> </li><li> <a href="/__pyric/ui/docs/pyric-conformance-scores/"> Conformance scores </a> </li><li> <a href="/__pyric/ui/docs/pyric-app-compat/"> App </a> </li><li> <a href="/__pyric/ui/docs/pyric-firestore-compat/"> Firestore </a> </li><li> <a href="/__pyric/ui/docs/pyric-auth-compat/"> Auth </a> </li><li> <a href="/__pyric/ui/docs/pyric-database-compat/"> Realtime Database </a> </li><li> <a href="/__pyric/ui/docs/pyric-storage-compat/"> Storage </a> </li><li> <a href="/__pyric/ui/docs/pyric-rules-compat/"> Rules </a> </li><li> <a href="/__pyric/ui/docs/pyric-messaging-compat/"> Messaging </a> </li><li> <a href="/__pyric/ui/docs/pyric-ai-compat/"> AI Logic </a> </li><li> <a href="/__pyric/ui/docs/pyric-cli-functions-rtdb-compat/"> Functions · RTDB </a> </li> </ul> </div> </div> </details> <details class="docs-nav-group" id="nav-group-reference" open> <summary>Reference</summary> <div class="docs-nav-group-body"> <div class="docs-nav-section"> <ul> <li> <a href="/__pyric/ui/docs/pyric-cli/"> @pyric/cli </a> </li><li> <a href="/__pyric/ui/docs/pyric-explanation-versioning-and-compatibility/"> pyric </a> </li><li> <a href="/__pyric/ui/docs/pyric-firestore/"> pyric / firestore </a> </li><li> <a href="/__pyric/ui/docs/pyric-rules/"> pyric / rules </a> </li><li> <a href="/__pyric/ui/docs/pyric-sandbox/"> pyric / sandbox </a> </li><li> <a href="/__pyric/ui/docs/pyric-storage/" aria-current="true"> pyric / storage </a> </li><li> <a href="/__pyric/ui/docs/pyric-auth/"> pyric / auth </a> </li><li> <a href="/__pyric/ui/docs/pyric-database/"> pyric / database </a> </li><li> <a href="/__pyric/ui/docs/pyric-admin-app/"> pyric-admin / app </a> </li><li> <a href="/__pyric/ui/docs/pyric-admin-firestore/"> pyric-admin / firestore </a> </li><li> <a href="/__pyric/ui/docs/pyric-admin-auth/"> pyric-admin / auth </a> </li><li> <a href="/__pyric/ui/docs/pyric-admin-database/"> pyric-admin / database </a> </li><li> <a href="/__pyric/ui/docs/pyric-admin-storage/"> pyric-admin / storage </a> </li><li> <a href="/__pyric/ui/docs/ui/"> @pyric/ui </a> </li><li> <a href="/__pyric/ui/docs/api-reference/"> API reference </a> </li> </ul> </div> </div> </details> </nav> <main class="doc-main"> <nav class="docs-breadcrumbs" aria-label="Breadcrumb"> <ol> <li>  <a href="/__pyric/ui/docs/pyric-storage/">pyric / storage</a> </li><li> <span class="docs-breadcrumbs-sep" aria-hidden="true">/</span> <span>Explanation</span> </li><li> <span class="docs-breadcrumbs-sep" aria-hidden="true">/</span> <span aria-current="page">Implementation scope</span> </li> </ol> </nav>  <article class="prose">  <h1 id="implementation-scope-and-deferred-features">Implementation scope and deferred features</h1>
+<p><code>pyric/storage</code> is a deliberate v1 scope. The scope is what the session-archive use case needed; anything beyond that is deferred. This page is the canonical list of what’s not in the package and why.</p>
+<h2 id="whats-in-scope">What’s in scope</h2>
+<p>The bounded subset:</p>
+<ul>
+<li><code>getStorage</code>, <code>getStorageSandbox</code>.</li>
+<li><code>ref</code> with both overloads.</li>
+<li><code>uploadBytes</code>, <code>uploadString</code>.</li>
+<li><code>getBytes</code>, <code>getBlob</code>, <code>getDownloadURL</code>.</li>
+<li><code>getMetadata</code>, <code>updateMetadata</code>.</li>
+<li><code>listAll</code>.</li>
+<li><code>deleteObject</code>.</li>
+<li><code>parseStorageRules</code>, <code>evaluateStorageRules</code>.</li>
+<li>A Storage rules subset: service header, path matching, umbrella and granular allow verbs (<code>read</code>/<code>write</code>, <code>get</code>/<code>list</code>/<code>create</code>/<code>update</code>/<code>delete</code>), user-defined functions with <code>let</code>, <code>request.time</code> and <code>timestamp.date()</code>, <code>matches()</code>, dotted and bracket <code>customMetadata</code> access, <code>firestore.get()</code>/<code>firestore.exists()</code> cross-service lookups, and standard operators.</li>
+</ul>
+<p>End-to-end coverage: see <code>packages/pyric/test/storage/session-archive.test.ts</code>.</p>
+<h3 id="the-sandbox-getdownloadurl-boundary">The sandbox <code>getDownloadURL</code> boundary</h3>
+<p>The sandbox mirror returns a page-local <code>blob:</code> URL over the rules-checked bytes. Production builds resolve <code>firebase/storage</code> directly and therefore receive Firebase’s token-signed HTTPS URL:</p>
+<pre class="astro-code one-dark-pro" style="background-color:#282c34;color:#abb2bf; overflow-x: auto;" tabindex="0" data-language="ts"><code><span class="line"><span style="color:#C678DD">const</span><span style="color:#E5C07B"> url</span><span style="color:#56B6C2"> =</span><span style="color:#C678DD"> await</span><span style="color:#61AFEF"> getDownloadURL</span><span style="color:#ABB2BF">(</span><span style="color:#61AFEF">ref</span><span style="color:#ABB2BF">(</span><span style="color:#E06C75">storage</span><span style="color:#ABB2BF">, </span><span style="color:#98C379">'sessions/n1'</span><span style="color:#ABB2BF">));</span></span>
+<span class="line"><span style="color:#7F848E;font-style:italic">// ... use url ...</span></span>
+<span class="line"><span style="color:#E5C07B">URL</span><span style="color:#ABB2BF">.</span><span style="color:#61AFEF">revokeObjectURL</span><span style="color:#ABB2BF">(</span><span style="color:#E06C75">url</span><span style="color:#ABB2BF">);  </span><span style="color:#7F848E;font-style:italic">// free the memory when done</span></span></code></pre>
+<p>The sandbox URL is a snapshot, not a Firebase download token. It cannot be shared outside the page and expires when revoked or when the page unloads.</p>
+<h2 id="whats-deferred">What’s deferred</h2>
+<h3 id="paginated-list">Paginated <code>list</code></h3>
+<p><code>list(ref, { maxResults, pageToken })</code> from the upstream API isn’t implemented. <code>listAll</code> covers every v1 scope scenario; pagination is reserved for future compatibility (the <code>nextPageToken: undefined</code> field in <code>ListResult</code> is there for that day).</p>
+<h3 id="uploadbytesresumable"><code>uploadBytesResumable</code></h3>
+<p>Resumable uploads with pause/resume/progress are a substantial piece of code that didn’t serve the use case. Synchronous <code>uploadBytes</code> is what the package ships.</p>
+<h3 id="admin-sdk-shape">Admin SDK shape</h3>
+<p>A sibling <code>pyric/storage-admin</code> package could mirror <code>firebase-admin/storage</code> the way <code>pyric-admin</code> mirrors <code>firebase-admin/firestore</code>. Not built yet; not blocking the v1 scope.</p>
+<h3 id="recorded-production-parity-testing">Recorded production parity testing</h3>
+<p>Storage’s behavior is not yet pinned to recorded production observations the way Auth and Firestore are. The rules engine is verified against the engine spec; the data plane is verified against the documented API. Pinning Storage to recorded production behavior is future work.</p>
+<h3 id="resource-content-hash-fields"><code>resource</code> content-hash fields</h3>
+<p>The engine doesn’t yet expose <code>md5Hash</code>, <code>crc32c</code>, or <code>etag</code> on <code>resource</code>. The object-identity and time fields (<code>name</code>, <code>bucket</code>, <code>timeCreated</code>, <code>updated</code>, <code>generation</code>, <code>metageneration</code>) and the content fields (<code>size</code>, <code>contentType</code>, <code>metadata</code>) all work, sourced from the persisted object record.</p>
+<h3 id="gated-listall">Gated <code>listAll</code></h3>
+<p><code>listAll</code> enforces the rules engine (ST-B2). Firebase’s <code>read</code> (or granular <code>list</code>) permission governs list, and list is evaluated against the scanned prefix path, so <code>listAll</code> requires <code>read</code>/<code>list</code> on the listed folder. A <code>read</code> rule scoped to <code>match /sessions/{id}</code> does NOT grant list on <code>/sessions</code>; the folder needs its own read rule (the session-archive ruleset adds <code>match /sessions { allow read: if request.auth != null; }</code>). This matches prod: in real Firebase you’d hit the same requirement. With no rules configured, <code>listAll</code> is open-by-default like every other operation.</p>
+<h3 id="cross-bucket-isolation">Cross-bucket isolation</h3>
+<p>The <code>bucket</code> option round-trips through metadata but doesn’t actually partition data. v1 has a single implicit bucket. Real multi-bucket support is reserved for when a consumer needs it.</p>
+<h3 id="cloud-functions-storage-triggers">Cloud Functions Storage triggers</h3>
+<p>Triggers on upload / delete are out of scope. They’re not data-plane concerns. The closest analog would be a sandbox-side event channel; not built.</p>
+<h3 id="image-transformations--firebase-extensions">Image transformations / Firebase Extensions</h3>
+<p>Not modelled. Production-only.</p>
+<h2 id="how-to-know-if-your-use-case-is-in-scope">How to know if your use case is in scope</h2>
+<p>Three questions:</p>
+<ol>
+<li><strong>Is your operation in the in-scope list above?</strong> If yes, it works.</li>
+<li><strong>Does your rule use only the subset in <a href="../pyric-storage-reference-rules-subset/"><code>Storage rules subset</code></a>?</strong> If yes, it’ll parse and enforce correctly.</li>
+<li><strong>Are you running with the Pyric package swap active?</strong> If yes, Storage is the IndexedDB-backed sandbox; a normal production build resolves Firebase directly.</li>
+</ol>
+<p>If your answer to any is “no”, check the deferred list. Production-only features remain available by running the normal build against Firebase.</p>
+<h2 id="when-to-upgrade-the-v1-scope">When to upgrade the v1 scope</h2>
+<p>The package will graduate from v1 scope to stable when consumers ask for the deferred features in concrete use cases. Until then, the scope reflects what was needed; expanding it speculatively would add surface that nobody runs through tests.</p>
+<p>If you have a use case the v1 scope doesn’t cover, file an issue with the operation, the rule, and the expected behaviour. That’s the input that drives v1 scope graduation.</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-in-scope">What’s in scope</a> </li><li data-depth="3"> <a href="#the-sandbox-getdownloadurl-boundary">The sandbox getDownloadURL boundary</a> </li><li data-depth="2"> <a href="#whats-deferred">What’s deferred</a> </li><li data-depth="3"> <a href="#paginated-list">Paginated list</a> </li><li data-depth="3"> <a href="#uploadbytesresumable">uploadBytesResumable</a> </li><li data-depth="3"> <a href="#admin-sdk-shape">Admin SDK shape</a> </li><li data-depth="3"> <a href="#recorded-production-parity-testing">Recorded production parity testing</a> </li><li data-depth="3"> <a href="#resource-content-hash-fields">resource content-hash fields</a> </li><li data-depth="3"> <a href="#gated-listall">Gated listAll</a> </li><li data-depth="3"> <a href="#cross-bucket-isolation">Cross-bucket isolation</a> </li><li data-depth="3"> <a href="#cloud-functions-storage-triggers">Cloud Functions Storage triggers</a> </li><li data-depth="3"> <a href="#image-transformations--firebase-extensions">Image transformations / Firebase Extensions</a> </li><li data-depth="2"> <a href="#how-to-know-if-your-use-case-is-in-scope">How to know if your use case is in scope</a> </li><li data-depth="2"> <a href="#when-to-upgrade-the-v1-scope">When to upgrade the v1 scope</a> </li> </ul> </aside> </div> <script type="module">const a=document.querySelector("[data-api-symbol-filter]"),d=[...document.querySelectorAll("[data-api-symbol-group]")],n=document.querySelector("[data-api-symbol-empty]");a?.addEventListener("input",()=>{const t=a.value.trim().toLowerCase();let o=0;for(const i of d){let e=0;i.querySelectorAll("[data-api-symbol]").forEach(l=>{const r=!t||(l.dataset.apiSymbol??"").includes(t);l.hidden=!r,r&&e++}),i.hidden=e===0,o+=e}n&&(n.hidden=o>0)});</script> <script type="module">const s=new Map;document.querySelectorAll('.doc-toc a[href^="#"]').forEach(t=>s.set(decodeURIComponent(t.hash.slice(1)),t));if(s.size>0){const t=new Set,n=()=>{let o=null;for(const e of s.keys())if(t.has(e)){o=e;break}s.forEach((e,c)=>e.classList.toggle("active",c===o))},r=new IntersectionObserver(o=>{for(const e of o)e.isIntersecting?t.add(e.target.id):t.delete(e.target.id);n()},{rootMargin:"-72px 0px -60% 0px"});s.forEach((o,e)=>{const c=document.getElementById(e);c&&r.observe(c)})}</script> <script type="module">document.querySelector('.studio__nav [aria-current="page"]')?.scrollIntoView({block:"nearest",inline:"center"});</script> </body> </html>

package/dist/serve/docs-ui/docs/pyric-storage-explanation-implementation-scope.md ADDED Viewed

@@ -0,0 +1,85 @@
+# Implementation scope and deferred features
+`pyric/storage` is a deliberate v1 scope. The scope is what the session-archive use case needed; anything beyond that is deferred. This page is the canonical list of what's not in the package and why.
+## What's in scope
+The bounded subset:
+- `getStorage`, `getStorageSandbox`.
+- `ref` with both overloads.
+- `uploadBytes`, `uploadString`.
+- `getBytes`, `getBlob`, `getDownloadURL`.
+- `getMetadata`, `updateMetadata`.
+- `listAll`.
+- `deleteObject`.
+- `parseStorageRules`, `evaluateStorageRules`.
+- A Storage rules subset: service header, path matching, umbrella and granular allow verbs (`read`/`write`, `get`/`list`/`create`/`update`/`delete`), user-defined functions with `let`, `request.time` and `timestamp.date()`, `matches()`, dotted and bracket `customMetadata` access, `firestore.get()`/`firestore.exists()` cross-service lookups, and standard operators.
+End-to-end coverage: see `packages/pyric/test/storage/session-archive.test.ts`.
+### The sandbox `getDownloadURL` boundary
+The sandbox mirror returns a page-local `blob:` URL over the rules-checked bytes. Production builds resolve `firebase/storage` directly and therefore receive Firebase's token-signed HTTPS URL:
+```ts
+const url = await getDownloadURL(ref(storage, 'sessions/n1'));
+// ... use url ...
+URL.revokeObjectURL(url);  // free the memory when done
+```
+The sandbox URL is a snapshot, not a Firebase download token. It cannot be shared outside the page and expires when revoked or when the page unloads.
+## What's deferred
+### Paginated `list`
+`list(ref, { maxResults, pageToken })` from the upstream API isn't implemented. `listAll` covers every v1 scope scenario; pagination is reserved for future compatibility (the `nextPageToken: undefined` field in `ListResult` is there for that day).
+### `uploadBytesResumable`
+Resumable uploads with pause/resume/progress are a substantial piece of code that didn't serve the use case. Synchronous `uploadBytes` is what the package ships.
+### Admin SDK shape
+A sibling `pyric/storage-admin` package could mirror `firebase-admin/storage` the way `pyric-admin` mirrors `firebase-admin/firestore`. Not built yet; not blocking the v1 scope.
+### Recorded production parity testing
+Storage's behavior is not yet pinned to recorded production observations the way Auth and Firestore are. The rules engine is verified against the engine spec; the data plane is verified against the documented API. Pinning Storage to recorded production behavior is future work.
+### `resource` content-hash fields
+The engine doesn't yet expose `md5Hash`, `crc32c`, or `etag` on `resource`. The object-identity and time fields (`name`, `bucket`, `timeCreated`, `updated`, `generation`, `metageneration`) and the content fields (`size`, `contentType`, `metadata`) all work, sourced from the persisted object record.
+### Gated `listAll`
+`listAll` enforces the rules engine (ST-B2). Firebase's `read` (or granular `list`) permission governs list, and list is evaluated against the scanned prefix path, so `listAll` requires `read`/`list` on the listed folder. A `read` rule scoped to `match /sessions/{id}` does NOT grant list on `/sessions`; the folder needs its own read rule (the session-archive ruleset adds `match /sessions { allow read: if request.auth != null; }`). This matches prod: in real Firebase you'd hit the same requirement. With no rules configured, `listAll` is open-by-default like every other operation.
+### Cross-bucket isolation
+The `bucket` option round-trips through metadata but doesn't actually partition data. v1 has a single implicit bucket. Real multi-bucket support is reserved for when a consumer needs it.
+### Cloud Functions Storage triggers
+Triggers on upload / delete are out of scope. They're not data-plane concerns. The closest analog would be a sandbox-side event channel; not built.
+### Image transformations / Firebase Extensions
+Not modelled. Production-only.
+## How to know if your use case is in scope
+Three questions:
+1. **Is your operation in the in-scope list above?** If yes, it works.
+2. **Does your rule use only the subset in [`Storage rules subset`](../pyric-storage-reference-rules-subset/)?** If yes, it'll parse and enforce correctly.
+3. **Are you running with the Pyric package swap active?** If yes, Storage is the IndexedDB-backed sandbox; a normal production build resolves Firebase directly.
+If your answer to any is "no", check the deferred list. Production-only features remain available by running the normal build against Firebase.
+## When to upgrade the v1 scope
+The package will graduate from v1 scope to stable when consumers ask for the deferred features in concrete use cases. Until then, the scope reflects what was needed; expanding it speculatively would add surface that nobody runs through tests.
+If you have a use case the v1 scope doesn't cover, file an issue with the operation, the rule, and the expected behaviour. That's the input that drives v1 scope graduation.

package/dist/serve/docs-ui/docs/pyric-storage-explanation-session-archive-use-case/index.html ADDED Viewed

@@ -0,0 +1,58 @@
+<!DOCTYPE html><html lang="en"> <head><meta charset="UTF-8"><meta name="viewport" content="width=device-width, initial-scale=1.0"><title>The session-archive driver · Pyric Studio</title><link rel="preconnect" href="https://fonts.googleapis.com"><link rel="preconnect" href="https://fonts.gstatic.com" crossorigin><link href="https://fonts.googleapis.com/css2?family=Inter:wght@300;400;500;600;700&family=JetBrains+Mono:wght@400;500;700&display=swap" rel="stylesheet"><link rel="stylesheet" href="/__pyric/ui/_astro/_slug_.CQYSemvw.css"></head> <body>  <header class="studio__bar"> <div class="studio__bar-inner"> <a class="studio__brand" href="/__pyric/ui/" aria-label="Pyric Studio">Pyric</a> <nav class="studio__nav" aria-label="Studio tabs"> <a class="studio__nav-tab" href="/__pyric/ui/"> Home </a><a class="studio__nav-tab" href="/__pyric/ui/firestore"> Firestore </a><a class="studio__nav-tab" href="/__pyric/ui/auth"> Auth </a><a class="studio__nav-tab" href="/__pyric/ui/rtdb"> RTDB </a><a class="studio__nav-tab" href="/__pyric/ui/storage"> Storage </a><a class="studio__nav-tab" href="/__pyric/ui/traffic"> Traffic </a><a class="studio__nav-tab" href="/__pyric/ui/settings"> Settings </a><a class="studio__nav-tab" href="/__pyric/ui/docs" aria-current="page"> Docs </a> </nav> </div> </header> <div class="docs-shell">  <details class="docs-nav-drawer"> <summary>Navigate</summary> <nav class="docs-nav" aria-label="Documentation"> <div class="docs-search" data-index-url="/__pyric/ui/docs/index.json"> <div class="docs-search-field"> <svg class="docs-search-icon" viewBox="0 0 16 16" width="14" height="14" aria-hidden="true"> <path d="M11.5 11.5 15 15M13 7A6 6 0 1 1 1 7a6 6 0 0 1 12 0Z" fill="none" stroke="currentColor" stroke-width="1.4" stroke-linecap="round"></path> </svg> <input type="text" class="docs-search-input" placeholder="Search docs" aria-label="Search docs" autocomplete="off" spellcheck="false"> <kbd class="docs-search-kbd">⌘K</kbd> </div> <ul class="docs-search-results" hidden></ul> </div> <script type="module">let i=null;function d(t){return i||(i=fetch(t).then(e=>e.json())),i}function l(t,e){return t.title.toLowerCase().includes(e)||t.excerpt.toLowerCase().includes(e)?!0:t.headings.some(r=>r.text.toLowerCase().includes(e))}function u(t,e,r){if(e.innerHTML="",t.length===0){e.hidden=!1;{const n=document.createElement("li");n.className="docs-search-empty",n.textContent="No matches",e.appendChild(n)}return}e.hidden=!1;for(const n of t.slice(0,8)){const s=document.createElement("li"),c=document.createElement("a");c.href=n.path;const o=document.createElement("span");o.className="docs-search-result-title",o.textContent=n.title;const a=document.createElement("span");a.className="docs-search-result-meta",a.textContent=[n.group,n.section].filter(Boolean).join(" / "),c.append(o,a),s.appendChild(c),e.appendChild(s)}}document.querySelectorAll(".docs-search").forEach(t=>{const e=t.dataset.indexUrl,r=t.querySelector(".docs-search-input"),n=t.querySelector(".docs-search-results");r.addEventListener("input",async()=>{const s=r.value.trim().toLowerCase();if(!s){n.hidden=!0,n.innerHTML="";return}const{pages:c}=await d(e);r.value.trim().toLowerCase()===s&&u(c.filter(o=>l(o,s)),n)}),r.addEventListener("focus",()=>{d(e),n.childElementCount>0&&(n.hidden=!1)}),r.addEventListener("keydown",s=>{s.key==="Escape"&&(r.value="",n.hidden=!0,n.innerHTML="",r.blur())}),r.addEventListener("blur",()=>{window.setTimeout(()=>{n.hidden=!0},150)})});document.addEventListener("keydown",t=>{if(!(t.metaKey||t.ctrlKey)||t.key.toLowerCase()!=="k")return;const e=[...document.querySelectorAll(".docs-search-input")].find(r=>r.offsetParent!==null);e&&(t.preventDefault(),e.focus(),e.select())});</script> <a class="docs-nav-toplink" href="/__pyric/ui/docs/overview/"> Overview </a><details class="docs-nav-group"> <summary>Run locally</summary> <div class="docs-nav-group-body"> <div class="docs-nav-section">  <ul> <li> <a href="/__pyric/ui/docs/start-building/"> Quickstart </a> </li><li> <a href="/__pyric/ui/docs/how-the-swap-works/"> How the swap works </a> </li><li> <a href="/__pyric/ui/docs/set-up-your-agent/"> Connect an agent </a> </li><li> <a href="/__pyric/ui/docs/test-in-node/"> Test in Node </a> </li> </ul> </div> </div> </details><details class="docs-nav-group"> <summary>Develop with Firebase APIs</summary> <div class="docs-nav-group-body"> <div class="docs-nav-section">  <ul> <li> <a href="/__pyric/ui/docs/sign-in-and-manage-users/"> Sign in and manage users </a> </li><li> <a href="/__pyric/ui/docs/store-and-query-data/"> Store and query data </a> </li><li> <a href="/__pyric/ui/docs/sync-realtime-data/"> Sync realtime data </a> </li><li> <a href="/__pyric/ui/docs/store-files/"> Store files </a> </li><li> <a href="/__pyric/ui/docs/receive-messages/"> Receive messages </a> </li><li> <a href="/__pyric/ui/docs/run-ai-logic-locally/"> Run AI Logic locally </a> </li><li> <a href="/__pyric/ui/docs/pyric-cli-how-to-run-rtdb-onvaluecreated/"> Run an RTDB function locally </a> </li><li> <a href="/__pyric/ui/docs/which-data-service/"> Which data service? </a> </li> </ul> </div> </div> </details><details class="docs-nav-group"> <summary>Inspect and correct</summary> <div class="docs-nav-group-body"> <div class="docs-nav-section"> <h2 class="docs-nav-heading"> Inspect the sandbox </h2> <ul> <li> <a href="/__pyric/ui/docs/see-whats-happening/"> Traffic &amp; rule verdicts </a> </li><li> <a href="/__pyric/ui/docs/read-a-denial/"> Read a denial and understand it </a> </li><li> <a href="/__pyric/ui/docs/shape-your-data/"> Seed, snapshot, replay </a> </li><li> <a href="/__pyric/ui/docs/watch-and-review/"> Review agent activity </a> </li> </ul> </div><div class="docs-nav-section"> <h2 class="docs-nav-heading"> Correct Security Rules </h2> <ul> <li> <a href="/__pyric/ui/docs/secure-it-with-rules/"> Security Rules </a> </li><li> <a href="/__pyric/ui/docs/simulate-and-lint/"> Simulate and lint before you deploy </a> </li><li> <a href="/__pyric/ui/docs/rules-patterns/"> Rules patterns </a> </li><li> <a href="/__pyric/ui/docs/rules-standard-library/"> The rules standard library </a> </li><li> <a href="/__pyric/ui/docs/rtdb-rules-in-typescript/"> RTDB rules in TypeScript </a> </li><li> <a href="/__pyric/ui/docs/firestore-rules-limits/"> Rules limits </a> </li><li> <a href="/__pyric/ui/docs/whats-possible/"> Case studies </a> </li> </ul> </div><div class="docs-nav-section"> <h2 class="docs-nav-heading"> Work with an agent </h2> <ul> <li> <a href="/__pyric/ui/docs/what-your-agent-can-do/"> Work through an agent </a> </li><li> <a href="/__pyric/ui/docs/skills/"> Agent skills </a> </li> </ul> </div> </div> </details><details class="docs-nav-group"> <summary>Verify the boundary</summary> <div class="docs-nav-group-body"> <div class="docs-nav-section">  <ul> <li> <a href="/__pyric/ui/docs/pyric-cli-how-to-verify-against-a-captured-session/"> Verify a captured session </a> </li><li> <a href="/__pyric/ui/docs/write-a-rules-test-suite/"> Write a rules test suite </a> </li><li> <a href="/__pyric/ui/docs/audit-your-rules/"> Audit rules and data </a> </li> </ul> </div> </div> </details><details class="docs-nav-group"> <summary>Ship unchanged</summary> <div class="docs-nav-group-body"> <div class="docs-nav-section">  <ul> <li> <a href="/__pyric/ui/docs/ship-to-production/"> Ship to production </a> </li><li> <a href="/__pyric/ui/docs/set-up-the-project/"> Set up the Firebase project </a> </li> </ul> </div> </div> </details><details class="docs-nav-group"> <summary>Conformance</summary> <div class="docs-nav-group-body"> <div class="docs-nav-section">  <ul> <li> <a href="/__pyric/ui/docs/how-we-know-it-matches-firebase/"> Conformance </a> </li><li> <a href="/__pyric/ui/docs/whats-experimental/"> What&#39;s experimental </a> </li><li> <a href="/__pyric/ui/docs/pyric-conformance-scores/"> Conformance scores </a> </li><li> <a href="/__pyric/ui/docs/pyric-app-compat/"> App </a> </li><li> <a href="/__pyric/ui/docs/pyric-firestore-compat/"> Firestore </a> </li><li> <a href="/__pyric/ui/docs/pyric-auth-compat/"> Auth </a> </li><li> <a href="/__pyric/ui/docs/pyric-database-compat/"> Realtime Database </a> </li><li> <a href="/__pyric/ui/docs/pyric-storage-compat/"> Storage </a> </li><li> <a href="/__pyric/ui/docs/pyric-rules-compat/"> Rules </a> </li><li> <a href="/__pyric/ui/docs/pyric-messaging-compat/"> Messaging </a> </li><li> <a href="/__pyric/ui/docs/pyric-ai-compat/"> AI Logic </a> </li><li> <a href="/__pyric/ui/docs/pyric-cli-functions-rtdb-compat/"> Functions · RTDB </a> </li> </ul> </div> </div> </details> <details class="docs-nav-group" open> <summary>Reference</summary> <div class="docs-nav-group-body"> <div class="docs-nav-section"> <ul> <li> <a href="/__pyric/ui/docs/pyric-cli/"> @pyric/cli </a> </li><li> <a href="/__pyric/ui/docs/pyric-explanation-versioning-and-compatibility/"> pyric </a> </li><li> <a href="/__pyric/ui/docs/pyric-firestore/"> pyric / firestore </a> </li><li> <a href="/__pyric/ui/docs/pyric-rules/"> pyric / rules </a> </li><li> <a href="/__pyric/ui/docs/pyric-sandbox/"> pyric / sandbox </a> </li><li> <a href="/__pyric/ui/docs/pyric-storage/" aria-current="true"> pyric / storage </a> </li><li> <a href="/__pyric/ui/docs/pyric-auth/"> pyric / auth </a> </li><li> <a href="/__pyric/ui/docs/pyric-database/"> pyric / database </a> </li><li> <a href="/__pyric/ui/docs/pyric-admin-app/"> pyric-admin / app </a> </li><li> <a href="/__pyric/ui/docs/pyric-admin-firestore/"> pyric-admin / firestore </a> </li><li> <a href="/__pyric/ui/docs/pyric-admin-auth/"> pyric-admin / auth </a> </li><li> <a href="/__pyric/ui/docs/pyric-admin-database/"> pyric-admin / database </a> </li><li> <a href="/__pyric/ui/docs/pyric-admin-storage/"> pyric-admin / storage </a> </li><li> <a href="/__pyric/ui/docs/ui/"> @pyric/ui </a> </li><li> <a href="/__pyric/ui/docs/api-reference/"> API reference </a> </li> </ul> </div> </div> </details> </nav> </details> <nav class="docs-nav" aria-label="Documentation"> <div class="docs-search" data-index-url="/__pyric/ui/docs/index.json"> <div class="docs-search-field"> <svg class="docs-search-icon" viewBox="0 0 16 16" width="14" height="14" aria-hidden="true"> <path d="M11.5 11.5 15 15M13 7A6 6 0 1 1 1 7a6 6 0 0 1 12 0Z" fill="none" stroke="currentColor" stroke-width="1.4" stroke-linecap="round"></path> </svg> <input type="text" class="docs-search-input" placeholder="Search docs" aria-label="Search docs" autocomplete="off" spellcheck="false"> <kbd class="docs-search-kbd">⌘K</kbd> </div> <ul class="docs-search-results" hidden></ul> </div>  <a class="docs-nav-toplink" href="/__pyric/ui/docs/overview/" id="nav-group-overview"> Overview </a><details class="docs-nav-group" id="nav-group-run-locally"> <summary>Run locally</summary> <div class="docs-nav-group-body"> <div class="docs-nav-section">  <ul> <li> <a href="/__pyric/ui/docs/start-building/"> Quickstart </a> </li><li> <a href="/__pyric/ui/docs/how-the-swap-works/"> How the swap works </a> </li><li> <a href="/__pyric/ui/docs/set-up-your-agent/"> Connect an agent </a> </li><li> <a href="/__pyric/ui/docs/test-in-node/"> Test in Node </a> </li> </ul> </div> </div> </details><details class="docs-nav-group" id="nav-group-develop-with-firebase-apis"> <summary>Develop with Firebase APIs</summary> <div class="docs-nav-group-body"> <div class="docs-nav-section">  <ul> <li> <a href="/__pyric/ui/docs/sign-in-and-manage-users/"> Sign in and manage users </a> </li><li> <a href="/__pyric/ui/docs/store-and-query-data/"> Store and query data </a> </li><li> <a href="/__pyric/ui/docs/sync-realtime-data/"> Sync realtime data </a> </li><li> <a href="/__pyric/ui/docs/store-files/"> Store files </a> </li><li> <a href="/__pyric/ui/docs/receive-messages/"> Receive messages </a> </li><li> <a href="/__pyric/ui/docs/run-ai-logic-locally/"> Run AI Logic locally </a> </li><li> <a href="/__pyric/ui/docs/pyric-cli-how-to-run-rtdb-onvaluecreated/"> Run an RTDB function locally </a> </li><li> <a href="/__pyric/ui/docs/which-data-service/"> Which data service? </a> </li> </ul> </div> </div> </details><details class="docs-nav-group" id="nav-group-inspect-and-correct"> <summary>Inspect and correct</summary> <div class="docs-nav-group-body"> <div class="docs-nav-section"> <h2 class="docs-nav-heading" id="nav-section-inspect-and-correct-inspect-the-sandbox"> Inspect the sandbox </h2> <ul> <li> <a href="/__pyric/ui/docs/see-whats-happening/"> Traffic &amp; rule verdicts </a> </li><li> <a href="/__pyric/ui/docs/read-a-denial/"> Read a denial and understand it </a> </li><li> <a href="/__pyric/ui/docs/shape-your-data/"> Seed, snapshot, replay </a> </li><li> <a href="/__pyric/ui/docs/watch-and-review/"> Review agent activity </a> </li> </ul> </div><div class="docs-nav-section"> <h2 class="docs-nav-heading" id="nav-section-inspect-and-correct-correct-security-rules"> Correct Security Rules </h2> <ul> <li> <a href="/__pyric/ui/docs/secure-it-with-rules/"> Security Rules </a> </li><li> <a href="/__pyric/ui/docs/simulate-and-lint/"> Simulate and lint before you deploy </a> </li><li> <a href="/__pyric/ui/docs/rules-patterns/"> Rules patterns </a> </li><li> <a href="/__pyric/ui/docs/rules-standard-library/"> The rules standard library </a> </li><li> <a href="/__pyric/ui/docs/rtdb-rules-in-typescript/"> RTDB rules in TypeScript </a> </li><li> <a href="/__pyric/ui/docs/firestore-rules-limits/"> Rules limits </a> </li><li> <a href="/__pyric/ui/docs/whats-possible/"> Case studies </a> </li> </ul> </div><div class="docs-nav-section"> <h2 class="docs-nav-heading" id="nav-section-inspect-and-correct-work-with-an-agent"> Work with an agent </h2> <ul> <li> <a href="/__pyric/ui/docs/what-your-agent-can-do/"> Work through an agent </a> </li><li> <a href="/__pyric/ui/docs/skills/"> Agent skills </a> </li> </ul> </div> </div> </details><details class="docs-nav-group" id="nav-group-verify-the-boundary"> <summary>Verify the boundary</summary> <div class="docs-nav-group-body"> <div class="docs-nav-section">  <ul> <li> <a href="/__pyric/ui/docs/pyric-cli-how-to-verify-against-a-captured-session/"> Verify a captured session </a> </li><li> <a href="/__pyric/ui/docs/write-a-rules-test-suite/"> Write a rules test suite </a> </li><li> <a href="/__pyric/ui/docs/audit-your-rules/"> Audit rules and data </a> </li> </ul> </div> </div> </details><details class="docs-nav-group" id="nav-group-ship-unchanged"> <summary>Ship unchanged</summary> <div class="docs-nav-group-body"> <div class="docs-nav-section">  <ul> <li> <a href="/__pyric/ui/docs/ship-to-production/"> Ship to production </a> </li><li> <a href="/__pyric/ui/docs/set-up-the-project/"> Set up the Firebase project </a> </li> </ul> </div> </div> </details><details class="docs-nav-group" id="nav-group-conformance"> <summary>Conformance</summary> <div class="docs-nav-group-body"> <div class="docs-nav-section">  <ul> <li> <a href="/__pyric/ui/docs/how-we-know-it-matches-firebase/"> Conformance </a> </li><li> <a href="/__pyric/ui/docs/whats-experimental/"> What&#39;s experimental </a> </li><li> <a href="/__pyric/ui/docs/pyric-conformance-scores/"> Conformance scores </a> </li><li> <a href="/__pyric/ui/docs/pyric-app-compat/"> App </a> </li><li> <a href="/__pyric/ui/docs/pyric-firestore-compat/"> Firestore </a> </li><li> <a href="/__pyric/ui/docs/pyric-auth-compat/"> Auth </a> </li><li> <a href="/__pyric/ui/docs/pyric-database-compat/"> Realtime Database </a> </li><li> <a href="/__pyric/ui/docs/pyric-storage-compat/"> Storage </a> </li><li> <a href="/__pyric/ui/docs/pyric-rules-compat/"> Rules </a> </li><li> <a href="/__pyric/ui/docs/pyric-messaging-compat/"> Messaging </a> </li><li> <a href="/__pyric/ui/docs/pyric-ai-compat/"> AI Logic </a> </li><li> <a href="/__pyric/ui/docs/pyric-cli-functions-rtdb-compat/"> Functions · RTDB </a> </li> </ul> </div> </div> </details> <details class="docs-nav-group" id="nav-group-reference" open> <summary>Reference</summary> <div class="docs-nav-group-body"> <div class="docs-nav-section"> <ul> <li> <a href="/__pyric/ui/docs/pyric-cli/"> @pyric/cli </a> </li><li> <a href="/__pyric/ui/docs/pyric-explanation-versioning-and-compatibility/"> pyric </a> </li><li> <a href="/__pyric/ui/docs/pyric-firestore/"> pyric / firestore </a> </li><li> <a href="/__pyric/ui/docs/pyric-rules/"> pyric / rules </a> </li><li> <a href="/__pyric/ui/docs/pyric-sandbox/"> pyric / sandbox </a> </li><li> <a href="/__pyric/ui/docs/pyric-storage/" aria-current="true"> pyric / storage </a> </li><li> <a href="/__pyric/ui/docs/pyric-auth/"> pyric / auth </a> </li><li> <a href="/__pyric/ui/docs/pyric-database/"> pyric / database </a> </li><li> <a href="/__pyric/ui/docs/pyric-admin-app/"> pyric-admin / app </a> </li><li> <a href="/__pyric/ui/docs/pyric-admin-firestore/"> pyric-admin / firestore </a> </li><li> <a href="/__pyric/ui/docs/pyric-admin-auth/"> pyric-admin / auth </a> </li><li> <a href="/__pyric/ui/docs/pyric-admin-database/"> pyric-admin / database </a> </li><li> <a href="/__pyric/ui/docs/pyric-admin-storage/"> pyric-admin / storage </a> </li><li> <a href="/__pyric/ui/docs/ui/"> @pyric/ui </a> </li><li> <a href="/__pyric/ui/docs/api-reference/"> API reference </a> </li> </ul> </div> </div> </details> </nav> <main class="doc-main"> <nav class="docs-breadcrumbs" aria-label="Breadcrumb"> <ol> <li>  <a href="/__pyric/ui/docs/pyric-storage/">pyric / storage</a> </li><li> <span class="docs-breadcrumbs-sep" aria-hidden="true">/</span> <span>Explanation</span> </li><li> <span class="docs-breadcrumbs-sep" aria-hidden="true">/</span> <span aria-current="page">The session-archive driver</span> </li> </ol> </nav>  <article class="prose">  <h1 id="the-session-archive-driver">The session-archive driver</h1>
+<p><code>pyric/storage</code> was scoped around one use case: storing completed agent sessions so a user can come back to them later. This page explains the use case and how it shaped the package.</p>
+<h2 id="what-an-agent-session-is">What an agent session is</h2>
+<p>Pyric’s agent runtime produces sessions, each a record of one task. The session captures the prompt, the tool calls, the LLM responses, the events streamed to the UI, the final outcome. A session is small (kilobytes, occasionally a megabyte) but unbounded: there can be thousands of them over time.</p>
+<p>A user finishing a session typically wants two things:</p>
+<ul>
+<li><strong>Persistence</strong>: come back later, see the session as it was.</li>
+<li><strong>Sharing</strong>: send a session to a colleague or attach it to a bug report.</li>
+</ul>
+<p>The sharing requirement implies a real bucket, <code>pyric_sessions/&#x3C;userId>/&#x3C;sessionId>.json</code> on production Firebase Storage, with appropriate access rules. The persistence requirement implies the same flow needs to work locally first.</p>
+<h2 id="why-an-in-process-backend-mattered">Why an in-process backend mattered</h2>
+<p>The playground is a browser app. It mutates documents and rules in-place; sessions naturally land there before any explicit upload. Two implications:</p>
+<ul>
+<li><strong>Latency.</strong> A user shouldn’t wait on a network round-trip for “save my session”. Sub-millisecond reads and writes matter.</li>
+<li><strong>Offline.</strong> A user on a flaky connection still wants their sessions to be there.</li>
+</ul>
+<p>A real Cloud Storage round-trip per session save is the wrong shape. So is “save everything in <code>localStorage</code>” (wrong quota, wrong API). IndexedDB lands in the middle: local, persistent, asynchronous.</p>
+<h2 id="why-rules-mattered">Why rules mattered</h2>
+<p>The eventual upload to production is gated by rules. We wanted those rules visible at session-save time so the user sees “this would be rejected” before they hit upload. The rule shape:</p>
+<pre class="astro-code one-dark-pro" style="background-color:#282c34;color:#abb2bf; overflow-x: auto;" tabindex="0" data-language="rules"><code><span class="line"><span style="color:#C678DD">service</span><span style="color:#ABB2BF"> firebase.storage {</span></span>
+<span class="line"><span style="color:#C678DD">  match</span><span style="color:#ABB2BF"> /b/</span><span style="color:#E06C75;font-style:italic">{bucket}</span><span style="color:#ABB2BF">/o {</span></span>
+<span class="line"><span style="color:#C678DD">    match</span><span style="color:#ABB2BF"> /sessions/</span><span style="color:#E06C75;font-style:italic">{sessionId}</span><span style="color:#ABB2BF"> {</span></span>
+<span class="line"><span style="color:#C678DD">      allow</span><span style="color:#61AFEF"> write</span><span style="color:#ABB2BF">: </span><span style="color:#C678DD">if</span><span style="color:#E5C07B"> request</span><span style="color:#ABB2BF">.auth != </span><span style="color:#D19A66">null</span></span>
+<span class="line"><span style="color:#ABB2BF">                   &#x26;&#x26; (</span><span style="color:#E5C07B">request</span><span style="color:#ABB2BF">.</span><span style="color:#E5C07B">resource</span><span style="color:#ABB2BF"> == </span><span style="color:#D19A66">null</span></span>
+<span class="line"><span style="color:#ABB2BF">                       || (</span><span style="color:#E5C07B">request</span><span style="color:#ABB2BF">.</span><span style="color:#E5C07B">resource</span><span style="color:#ABB2BF">.size &#x3C; </span><span style="color:#D19A66">10</span><span style="color:#ABB2BF"> * </span><span style="color:#D19A66">1024</span><span style="color:#ABB2BF"> * </span><span style="color:#D19A66">1024</span></span>
+<span class="line"><span style="color:#ABB2BF">                           &#x26;&#x26; </span><span style="color:#E5C07B">request</span><span style="color:#ABB2BF">.</span><span style="color:#E5C07B">resource</span><span style="color:#ABB2BF">.contentType == </span><span style="color:#98C379">'application/json'</span><span style="color:#ABB2BF">));</span></span>
+<span class="line"><span style="color:#C678DD">      allow</span><span style="color:#61AFEF"> read</span><span style="color:#ABB2BF">: </span><span style="color:#C678DD">if</span><span style="color:#E5C07B"> request</span><span style="color:#ABB2BF">.auth != </span><span style="color:#D19A66">null</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>
+<span class="line"><span style="color:#ABB2BF">}</span></span></code></pre>
+<p>Four real-world bits embedded:</p>
+<ul>
+<li><strong>Anonymous denials.</strong> Anyone hitting “save” while not signed in gets blocked.</li>
+<li><strong>Size limits.</strong> A 50 MB session is almost certainly a bug; reject early.</li>
+<li><strong>Content-type pinning.</strong> JSON only, so a non-JSON upload doesn’t masquerade.</li>
+<li><strong>Delete carve-out.</strong> <code>request.resource == null</code> lets deletes through (they don’t carry a payload).</li>
+</ul>
+<p>These were the <em>real</em> rules used in production. Tested locally first means the engineer iterating on them sees denials in their playground tab, not in their analytics dashboard the next day.</p>
+<h2 id="why-the-rule-engine-is-local-to-this-package">Why the rule engine is local to this package</h2>
+<p><code>pyric/rules</code> is a sibling-package answer to the same problem for Firestore: parse, lint, simulate. We didn’t reuse it because the Storage rules grammar is different from the Firestore rules grammar. Different identifiers (<code>request.resource.contentType</code> doesn’t exist in Firestore), different verbs (<code>read</code> / <code>write</code> vs <code>read</code> / <code>write</code> / <code>get</code> / <code>list</code> / <code>create</code> / <code>update</code> / <code>delete</code>), different evaluation contexts.</p>
+<p>A separate parser + evaluator for Storage rules avoided the headache of multiplexing two grammars in one package. It also kept the rule subset small: the Storage rules v1 scope covers what session archives needed, nothing more.</p>
+<p>When more Storage features land (custom verbs, time gating, regex), the same package can grow to absorb them. When a <code>pyric/storage-admin</code> sibling lands, the parser stays here and the admin shape pulls it in.</p>
+<h2 id="why-bucket-is-a-label-not-a-partition">Why <code>bucket</code> is a label, not a partition</h2>
+<p>Production Storage has real multi-bucket isolation. We didn’t reproduce that because the session archive uses one bucket per project, and multi-bucket is a feature most consumers don’t reach. The <code>bucket</code> option round-trips through metadata so generated metadata matches production shape; the actual data is one IndexedDB partition.</p>
+<p>When a multi-bucket scenario actually matters to a consumer, the partition can light up. Until then, treating it as a label kept the implementation small.</p>
+<h2 id="what-the-use-case-did-not-need">What the use case did not need</h2>
+<p>A few things we explicitly didn’t build because the session archive doesn’t need them:</p>
+<ul>
+<li><strong>Resumable uploads.</strong> Sessions are small; one-shot uploads are fine.</li>
+<li><strong>Progress events.</strong> A 100 ms upload doesn’t need a progress bar.</li>
+<li><strong>Server-side transformations.</strong> Sessions are JSON; we don’t generate thumbnails.</li>
+<li><strong>Cloud Functions triggers on upload.</strong> No server-side logic to invoke.</li>
+<li><strong>Granular allow verbs.</strong> Read vs write is the only distinction sessions need.</li>
+</ul>
+<p>Each is a real Storage feature; each is deferred. The deferral list lives in <a href="../pyric-storage-explanation-implementation-scope/">Implementation scope and deferred features</a>.</p>
+<h2 id="why-this-matters">Why this matters</h2>
+<p>The v1 scope wasn’t picked from a feature wishlist. It was driven by one concrete consumer. Every line in this package serves the session-archive flow. When a future consumer comes along with a different use case (large files, server-side triggers, real multi-bucket), the package will grow to absorb their needs <em>because</em> they’re real, not speculative.</p>
+<p>This is the pattern: build what’s needed, document what’s deferred, expand on demand.</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="#what-an-agent-session-is">What an agent session is</a> </li><li data-depth="2"> <a href="#why-an-in-process-backend-mattered">Why an in-process backend mattered</a> </li><li data-depth="2"> <a href="#why-rules-mattered">Why rules mattered</a> </li><li data-depth="2"> <a href="#why-the-rule-engine-is-local-to-this-package">Why the rule engine is local to this package</a> </li><li data-depth="2"> <a href="#why-bucket-is-a-label-not-a-partition">Why bucket is a label, not a partition</a> </li><li data-depth="2"> <a href="#what-the-use-case-did-not-need">What the use case did not need</a> </li><li data-depth="2"> <a href="#why-this-matters">Why this matters</a> </li> </ul> </aside> </div> <script type="module">const a=document.querySelector("[data-api-symbol-filter]"),d=[...document.querySelectorAll("[data-api-symbol-group]")],n=document.querySelector("[data-api-symbol-empty]");a?.addEventListener("input",()=>{const t=a.value.trim().toLowerCase();let o=0;for(const i of d){let e=0;i.querySelectorAll("[data-api-symbol]").forEach(l=>{const r=!t||(l.dataset.apiSymbol??"").includes(t);l.hidden=!r,r&&e++}),i.hidden=e===0,o+=e}n&&(n.hidden=o>0)});</script> <script type="module">const s=new Map;document.querySelectorAll('.doc-toc a[href^="#"]').forEach(t=>s.set(decodeURIComponent(t.hash.slice(1)),t));if(s.size>0){const t=new Set,n=()=>{let o=null;for(const e of s.keys())if(t.has(e)){o=e;break}s.forEach((e,c)=>e.classList.toggle("active",c===o))},r=new IntersectionObserver(o=>{for(const e of o)e.isIntersecting?t.add(e.target.id):t.delete(e.target.id);n()},{rootMargin:"-72px 0px -60% 0px"});s.forEach((o,e)=>{const c=document.getElementById(e);c&&r.observe(c)})}</script> <script type="module">document.querySelector('.studio__nav [aria-current="page"]')?.scrollIntoView({block:"nearest",inline:"center"});</script> </body> </html>

package/dist/serve/docs-ui/docs/pyric-storage-explanation-session-archive-use-case.md ADDED Viewed

@@ -0,0 +1,82 @@
+# The session-archive driver
+`pyric/storage` was scoped around one use case: storing completed agent sessions so a user can come back to them later. This page explains the use case and how it shaped the package.
+## What an agent session is
+Pyric's agent runtime produces sessions, each a record of one task. The session captures the prompt, the tool calls, the LLM responses, the events streamed to the UI, the final outcome. A session is small (kilobytes, occasionally a megabyte) but unbounded: there can be thousands of them over time.
+A user finishing a session typically wants two things:
+- **Persistence**: come back later, see the session as it was.
+- **Sharing**: send a session to a colleague or attach it to a bug report.
+The sharing requirement implies a real bucket, `pyric_sessions/<userId>/<sessionId>.json` on production Firebase Storage, with appropriate access rules. The persistence requirement implies the same flow needs to work locally first.
+## Why an in-process backend mattered
+The playground is a browser app. It mutates documents and rules in-place; sessions naturally land there before any explicit upload. Two implications:
+- **Latency.** A user shouldn't wait on a network round-trip for "save my session". Sub-millisecond reads and writes matter.
+- **Offline.** A user on a flaky connection still wants their sessions to be there.
+A real Cloud Storage round-trip per session save is the wrong shape. So is "save everything in `localStorage`" (wrong quota, wrong API). IndexedDB lands in the middle: local, persistent, asynchronous.
+## Why rules mattered
+The eventual upload to production is gated by rules. We wanted those rules visible at session-save time so the user sees "this would be rejected" before they hit upload. The rule shape:
+```rules
+service firebase.storage {
+  match /b/{bucket}/o {
+    match /sessions/{sessionId} {
+      allow write: if request.auth != null
+                   && (request.resource == null
+                       || (request.resource.size < 10 * 1024 * 1024
+                           && request.resource.contentType == 'application/json'));
+      allow read: if request.auth != null;
+    }
+  }
+}
+```
+Four real-world bits embedded:
+- **Anonymous denials.** Anyone hitting "save" while not signed in gets blocked.
+- **Size limits.** A 50 MB session is almost certainly a bug; reject early.
+- **Content-type pinning.** JSON only, so a non-JSON upload doesn't masquerade.
+- **Delete carve-out.** `request.resource == null` lets deletes through (they don't carry a payload).
+These were the *real* rules used in production. Tested locally first means the engineer iterating on them sees denials in their playground tab, not in their analytics dashboard the next day.
+## Why the rule engine is local to this package
+`pyric/rules` is a sibling-package answer to the same problem for Firestore: parse, lint, simulate. We didn't reuse it because the Storage rules grammar is different from the Firestore rules grammar. Different identifiers (`request.resource.contentType` doesn't exist in Firestore), different verbs (`read` / `write` vs `read` / `write` / `get` / `list` / `create` / `update` / `delete`), different evaluation contexts.
+A separate parser + evaluator for Storage rules avoided the headache of multiplexing two grammars in one package. It also kept the rule subset small: the Storage rules v1 scope covers what session archives needed, nothing more.
+When more Storage features land (custom verbs, time gating, regex), the same package can grow to absorb them. When a `pyric/storage-admin` sibling lands, the parser stays here and the admin shape pulls it in.
+## Why `bucket` is a label, not a partition
+Production Storage has real multi-bucket isolation. We didn't reproduce that because the session archive uses one bucket per project, and multi-bucket is a feature most consumers don't reach. The `bucket` option round-trips through metadata so generated metadata matches production shape; the actual data is one IndexedDB partition.
+When a multi-bucket scenario actually matters to a consumer, the partition can light up. Until then, treating it as a label kept the implementation small.
+## What the use case did not need
+A few things we explicitly didn't build because the session archive doesn't need them:
+- **Resumable uploads.** Sessions are small; one-shot uploads are fine.
+- **Progress events.** A 100 ms upload doesn't need a progress bar.
+- **Server-side transformations.** Sessions are JSON; we don't generate thumbnails.
+- **Cloud Functions triggers on upload.** No server-side logic to invoke.
+- **Granular allow verbs.** Read vs write is the only distinction sessions need.
+Each is a real Storage feature; each is deferred. The deferral list lives in [Implementation scope and deferred features](../pyric-storage-explanation-implementation-scope/).
+## Why this matters
+The v1 scope wasn't picked from a feature wishlist. It was driven by one concrete consumer. Every line in this package serves the session-archive flow. When a future consumer comes along with a different use case (large files, server-side triggers, real multi-bucket), the package will grow to absorb their needs *because* they're real, not speculative.
+This is the pattern: build what's needed, document what's deferred, expand on demand.

package/dist/serve/docs-ui/docs/pyric-storage-explanation-why-indexeddb/index.html ADDED Viewed

@@ -0,0 +1,50 @@
+<!DOCTYPE html><html lang="en"> <head><meta charset="UTF-8"><meta name="viewport" content="width=device-width, initial-scale=1.0"><title>Why IndexedDB · Pyric Studio</title><link rel="preconnect" href="https://fonts.googleapis.com"><link rel="preconnect" href="https://fonts.gstatic.com" crossorigin><link href="https://fonts.googleapis.com/css2?family=Inter:wght@300;400;500;600;700&family=JetBrains+Mono:wght@400;500;700&display=swap" rel="stylesheet"><link rel="stylesheet" href="/__pyric/ui/_astro/_slug_.CQYSemvw.css"></head> <body>  <header class="studio__bar"> <div class="studio__bar-inner"> <a class="studio__brand" href="/__pyric/ui/" aria-label="Pyric Studio">Pyric</a> <nav class="studio__nav" aria-label="Studio tabs"> <a class="studio__nav-tab" href="/__pyric/ui/"> Home </a><a class="studio__nav-tab" href="/__pyric/ui/firestore"> Firestore </a><a class="studio__nav-tab" href="/__pyric/ui/auth"> Auth </a><a class="studio__nav-tab" href="/__pyric/ui/rtdb"> RTDB </a><a class="studio__nav-tab" href="/__pyric/ui/storage"> Storage </a><a class="studio__nav-tab" href="/__pyric/ui/traffic"> Traffic </a><a class="studio__nav-tab" href="/__pyric/ui/settings"> Settings </a><a class="studio__nav-tab" href="/__pyric/ui/docs" aria-current="page"> Docs </a> </nav> </div> </header> <div class="docs-shell">  <details class="docs-nav-drawer"> <summary>Navigate</summary> <nav class="docs-nav" aria-label="Documentation"> <div class="docs-search" data-index-url="/__pyric/ui/docs/index.json"> <div class="docs-search-field"> <svg class="docs-search-icon" viewBox="0 0 16 16" width="14" height="14" aria-hidden="true"> <path d="M11.5 11.5 15 15M13 7A6 6 0 1 1 1 7a6 6 0 0 1 12 0Z" fill="none" stroke="currentColor" stroke-width="1.4" stroke-linecap="round"></path> </svg> <input type="text" class="docs-search-input" placeholder="Search docs" aria-label="Search docs" autocomplete="off" spellcheck="false"> <kbd class="docs-search-kbd">⌘K</kbd> </div> <ul class="docs-search-results" hidden></ul> </div> <script type="module">let i=null;function d(t){return i||(i=fetch(t).then(e=>e.json())),i}function l(t,e){return t.title.toLowerCase().includes(e)||t.excerpt.toLowerCase().includes(e)?!0:t.headings.some(r=>r.text.toLowerCase().includes(e))}function u(t,e,r){if(e.innerHTML="",t.length===0){e.hidden=!1;{const n=document.createElement("li");n.className="docs-search-empty",n.textContent="No matches",e.appendChild(n)}return}e.hidden=!1;for(const n of t.slice(0,8)){const s=document.createElement("li"),c=document.createElement("a");c.href=n.path;const o=document.createElement("span");o.className="docs-search-result-title",o.textContent=n.title;const a=document.createElement("span");a.className="docs-search-result-meta",a.textContent=[n.group,n.section].filter(Boolean).join(" / "),c.append(o,a),s.appendChild(c),e.appendChild(s)}}document.querySelectorAll(".docs-search").forEach(t=>{const e=t.dataset.indexUrl,r=t.querySelector(".docs-search-input"),n=t.querySelector(".docs-search-results");r.addEventListener("input",async()=>{const s=r.value.trim().toLowerCase();if(!s){n.hidden=!0,n.innerHTML="";return}const{pages:c}=await d(e);r.value.trim().toLowerCase()===s&&u(c.filter(o=>l(o,s)),n)}),r.addEventListener("focus",()=>{d(e),n.childElementCount>0&&(n.hidden=!1)}),r.addEventListener("keydown",s=>{s.key==="Escape"&&(r.value="",n.hidden=!0,n.innerHTML="",r.blur())}),r.addEventListener("blur",()=>{window.setTimeout(()=>{n.hidden=!0},150)})});document.addEventListener("keydown",t=>{if(!(t.metaKey||t.ctrlKey)||t.key.toLowerCase()!=="k")return;const e=[...document.querySelectorAll(".docs-search-input")].find(r=>r.offsetParent!==null);e&&(t.preventDefault(),e.focus(),e.select())});</script> <a class="docs-nav-toplink" href="/__pyric/ui/docs/overview/"> Overview </a><details class="docs-nav-group"> <summary>Run locally</summary> <div class="docs-nav-group-body"> <div class="docs-nav-section">  <ul> <li> <a href="/__pyric/ui/docs/start-building/"> Quickstart </a> </li><li> <a href="/__pyric/ui/docs/how-the-swap-works/"> How the swap works </a> </li><li> <a href="/__pyric/ui/docs/set-up-your-agent/"> Connect an agent </a> </li><li> <a href="/__pyric/ui/docs/test-in-node/"> Test in Node </a> </li> </ul> </div> </div> </details><details class="docs-nav-group"> <summary>Develop with Firebase APIs</summary> <div class="docs-nav-group-body"> <div class="docs-nav-section">  <ul> <li> <a href="/__pyric/ui/docs/sign-in-and-manage-users/"> Sign in and manage users </a> </li><li> <a href="/__pyric/ui/docs/store-and-query-data/"> Store and query data </a> </li><li> <a href="/__pyric/ui/docs/sync-realtime-data/"> Sync realtime data </a> </li><li> <a href="/__pyric/ui/docs/store-files/"> Store files </a> </li><li> <a href="/__pyric/ui/docs/receive-messages/"> Receive messages </a> </li><li> <a href="/__pyric/ui/docs/run-ai-logic-locally/"> Run AI Logic locally </a> </li><li> <a href="/__pyric/ui/docs/pyric-cli-how-to-run-rtdb-onvaluecreated/"> Run an RTDB function locally </a> </li><li> <a href="/__pyric/ui/docs/which-data-service/"> Which data service? </a> </li> </ul> </div> </div> </details><details class="docs-nav-group"> <summary>Inspect and correct</summary> <div class="docs-nav-group-body"> <div class="docs-nav-section"> <h2 class="docs-nav-heading"> Inspect the sandbox </h2> <ul> <li> <a href="/__pyric/ui/docs/see-whats-happening/"> Traffic &amp; rule verdicts </a> </li><li> <a href="/__pyric/ui/docs/read-a-denial/"> Read a denial and understand it </a> </li><li> <a href="/__pyric/ui/docs/shape-your-data/"> Seed, snapshot, replay </a> </li><li> <a href="/__pyric/ui/docs/watch-and-review/"> Review agent activity </a> </li> </ul> </div><div class="docs-nav-section"> <h2 class="docs-nav-heading"> Correct Security Rules </h2> <ul> <li> <a href="/__pyric/ui/docs/secure-it-with-rules/"> Security Rules </a> </li><li> <a href="/__pyric/ui/docs/simulate-and-lint/"> Simulate and lint before you deploy </a> </li><li> <a href="/__pyric/ui/docs/rules-patterns/"> Rules patterns </a> </li><li> <a href="/__pyric/ui/docs/rules-standard-library/"> The rules standard library </a> </li><li> <a href="/__pyric/ui/docs/rtdb-rules-in-typescript/"> RTDB rules in TypeScript </a> </li><li> <a href="/__pyric/ui/docs/firestore-rules-limits/"> Rules limits </a> </li><li> <a href="/__pyric/ui/docs/whats-possible/"> Case studies </a> </li> </ul> </div><div class="docs-nav-section"> <h2 class="docs-nav-heading"> Work with an agent </h2> <ul> <li> <a href="/__pyric/ui/docs/what-your-agent-can-do/"> Work through an agent </a> </li><li> <a href="/__pyric/ui/docs/skills/"> Agent skills </a> </li> </ul> </div> </div> </details><details class="docs-nav-group"> <summary>Verify the boundary</summary> <div class="docs-nav-group-body"> <div class="docs-nav-section">  <ul> <li> <a href="/__pyric/ui/docs/pyric-cli-how-to-verify-against-a-captured-session/"> Verify a captured session </a> </li><li> <a href="/__pyric/ui/docs/write-a-rules-test-suite/"> Write a rules test suite </a> </li><li> <a href="/__pyric/ui/docs/audit-your-rules/"> Audit rules and data </a> </li> </ul> </div> </div> </details><details class="docs-nav-group"> <summary>Ship unchanged</summary> <div class="docs-nav-group-body"> <div class="docs-nav-section">  <ul> <li> <a href="/__pyric/ui/docs/ship-to-production/"> Ship to production </a> </li><li> <a href="/__pyric/ui/docs/set-up-the-project/"> Set up the Firebase project </a> </li> </ul> </div> </div> </details><details class="docs-nav-group"> <summary>Conformance</summary> <div class="docs-nav-group-body"> <div class="docs-nav-section">  <ul> <li> <a href="/__pyric/ui/docs/how-we-know-it-matches-firebase/"> Conformance </a> </li><li> <a href="/__pyric/ui/docs/whats-experimental/"> What&#39;s experimental </a> </li><li> <a href="/__pyric/ui/docs/pyric-conformance-scores/"> Conformance scores </a> </li><li> <a href="/__pyric/ui/docs/pyric-app-compat/"> App </a> </li><li> <a href="/__pyric/ui/docs/pyric-firestore-compat/"> Firestore </a> </li><li> <a href="/__pyric/ui/docs/pyric-auth-compat/"> Auth </a> </li><li> <a href="/__pyric/ui/docs/pyric-database-compat/"> Realtime Database </a> </li><li> <a href="/__pyric/ui/docs/pyric-storage-compat/"> Storage </a> </li><li> <a href="/__pyric/ui/docs/pyric-rules-compat/"> Rules </a> </li><li> <a href="/__pyric/ui/docs/pyric-messaging-compat/"> Messaging </a> </li><li> <a href="/__pyric/ui/docs/pyric-ai-compat/"> AI Logic </a> </li><li> <a href="/__pyric/ui/docs/pyric-cli-functions-rtdb-compat/"> Functions · RTDB </a> </li> </ul> </div> </div> </details> <details class="docs-nav-group" open> <summary>Reference</summary> <div class="docs-nav-group-body"> <div class="docs-nav-section"> <ul> <li> <a href="/__pyric/ui/docs/pyric-cli/"> @pyric/cli </a> </li><li> <a href="/__pyric/ui/docs/pyric-explanation-versioning-and-compatibility/"> pyric </a> </li><li> <a href="/__pyric/ui/docs/pyric-firestore/"> pyric / firestore </a> </li><li> <a href="/__pyric/ui/docs/pyric-rules/"> pyric / rules </a> </li><li> <a href="/__pyric/ui/docs/pyric-sandbox/"> pyric / sandbox </a> </li><li> <a href="/__pyric/ui/docs/pyric-storage/" aria-current="true"> pyric / storage </a> </li><li> <a href="/__pyric/ui/docs/pyric-auth/"> pyric / auth </a> </li><li> <a href="/__pyric/ui/docs/pyric-database/"> pyric / database </a> </li><li> <a href="/__pyric/ui/docs/pyric-admin-app/"> pyric-admin / app </a> </li><li> <a href="/__pyric/ui/docs/pyric-admin-firestore/"> pyric-admin / firestore </a> </li><li> <a href="/__pyric/ui/docs/pyric-admin-auth/"> pyric-admin / auth </a> </li><li> <a href="/__pyric/ui/docs/pyric-admin-database/"> pyric-admin / database </a> </li><li> <a href="/__pyric/ui/docs/pyric-admin-storage/"> pyric-admin / storage </a> </li><li> <a href="/__pyric/ui/docs/ui/"> @pyric/ui </a> </li><li> <a href="/__pyric/ui/docs/api-reference/"> API reference </a> </li> </ul> </div> </div> </details> </nav> </details> <nav class="docs-nav" aria-label="Documentation"> <div class="docs-search" data-index-url="/__pyric/ui/docs/index.json"> <div class="docs-search-field"> <svg class="docs-search-icon" viewBox="0 0 16 16" width="14" height="14" aria-hidden="true"> <path d="M11.5 11.5 15 15M13 7A6 6 0 1 1 1 7a6 6 0 0 1 12 0Z" fill="none" stroke="currentColor" stroke-width="1.4" stroke-linecap="round"></path> </svg> <input type="text" class="docs-search-input" placeholder="Search docs" aria-label="Search docs" autocomplete="off" spellcheck="false"> <kbd class="docs-search-kbd">⌘K</kbd> </div> <ul class="docs-search-results" hidden></ul> </div>  <a class="docs-nav-toplink" href="/__pyric/ui/docs/overview/" id="nav-group-overview"> Overview </a><details class="docs-nav-group" id="nav-group-run-locally"> <summary>Run locally</summary> <div class="docs-nav-group-body"> <div class="docs-nav-section">  <ul> <li> <a href="/__pyric/ui/docs/start-building/"> Quickstart </a> </li><li> <a href="/__pyric/ui/docs/how-the-swap-works/"> How the swap works </a> </li><li> <a href="/__pyric/ui/docs/set-up-your-agent/"> Connect an agent </a> </li><li> <a href="/__pyric/ui/docs/test-in-node/"> Test in Node </a> </li> </ul> </div> </div> </details><details class="docs-nav-group" id="nav-group-develop-with-firebase-apis"> <summary>Develop with Firebase APIs</summary> <div class="docs-nav-group-body"> <div class="docs-nav-section">  <ul> <li> <a href="/__pyric/ui/docs/sign-in-and-manage-users/"> Sign in and manage users </a> </li><li> <a href="/__pyric/ui/docs/store-and-query-data/"> Store and query data </a> </li><li> <a href="/__pyric/ui/docs/sync-realtime-data/"> Sync realtime data </a> </li><li> <a href="/__pyric/ui/docs/store-files/"> Store files </a> </li><li> <a href="/__pyric/ui/docs/receive-messages/"> Receive messages </a> </li><li> <a href="/__pyric/ui/docs/run-ai-logic-locally/"> Run AI Logic locally </a> </li><li> <a href="/__pyric/ui/docs/pyric-cli-how-to-run-rtdb-onvaluecreated/"> Run an RTDB function locally </a> </li><li> <a href="/__pyric/ui/docs/which-data-service/"> Which data service? </a> </li> </ul> </div> </div> </details><details class="docs-nav-group" id="nav-group-inspect-and-correct"> <summary>Inspect and correct</summary> <div class="docs-nav-group-body"> <div class="docs-nav-section"> <h2 class="docs-nav-heading" id="nav-section-inspect-and-correct-inspect-the-sandbox"> Inspect the sandbox </h2> <ul> <li> <a href="/__pyric/ui/docs/see-whats-happening/"> Traffic &amp; rule verdicts </a> </li><li> <a href="/__pyric/ui/docs/read-a-denial/"> Read a denial and understand it </a> </li><li> <a href="/__pyric/ui/docs/shape-your-data/"> Seed, snapshot, replay </a> </li><li> <a href="/__pyric/ui/docs/watch-and-review/"> Review agent activity </a> </li> </ul> </div><div class="docs-nav-section"> <h2 class="docs-nav-heading" id="nav-section-inspect-and-correct-correct-security-rules"> Correct Security Rules </h2> <ul> <li> <a href="/__pyric/ui/docs/secure-it-with-rules/"> Security Rules </a> </li><li> <a href="/__pyric/ui/docs/simulate-and-lint/"> Simulate and lint before you deploy </a> </li><li> <a href="/__pyric/ui/docs/rules-patterns/"> Rules patterns </a> </li><li> <a href="/__pyric/ui/docs/rules-standard-library/"> The rules standard library </a> </li><li> <a href="/__pyric/ui/docs/rtdb-rules-in-typescript/"> RTDB rules in TypeScript </a> </li><li> <a href="/__pyric/ui/docs/firestore-rules-limits/"> Rules limits </a> </li><li> <a href="/__pyric/ui/docs/whats-possible/"> Case studies </a> </li> </ul> </div><div class="docs-nav-section"> <h2 class="docs-nav-heading" id="nav-section-inspect-and-correct-work-with-an-agent"> Work with an agent </h2> <ul> <li> <a href="/__pyric/ui/docs/what-your-agent-can-do/"> Work through an agent </a> </li><li> <a href="/__pyric/ui/docs/skills/"> Agent skills </a> </li> </ul> </div> </div> </details><details class="docs-nav-group" id="nav-group-verify-the-boundary"> <summary>Verify the boundary</summary> <div class="docs-nav-group-body"> <div class="docs-nav-section">  <ul> <li> <a href="/__pyric/ui/docs/pyric-cli-how-to-verify-against-a-captured-session/"> Verify a captured session </a> </li><li> <a href="/__pyric/ui/docs/write-a-rules-test-suite/"> Write a rules test suite </a> </li><li> <a href="/__pyric/ui/docs/audit-your-rules/"> Audit rules and data </a> </li> </ul> </div> </div> </details><details class="docs-nav-group" id="nav-group-ship-unchanged"> <summary>Ship unchanged</summary> <div class="docs-nav-group-body"> <div class="docs-nav-section">  <ul> <li> <a href="/__pyric/ui/docs/ship-to-production/"> Ship to production </a> </li><li> <a href="/__pyric/ui/docs/set-up-the-project/"> Set up the Firebase project </a> </li> </ul> </div> </div> </details><details class="docs-nav-group" id="nav-group-conformance"> <summary>Conformance</summary> <div class="docs-nav-group-body"> <div class="docs-nav-section">  <ul> <li> <a href="/__pyric/ui/docs/how-we-know-it-matches-firebase/"> Conformance </a> </li><li> <a href="/__pyric/ui/docs/whats-experimental/"> What&#39;s experimental </a> </li><li> <a href="/__pyric/ui/docs/pyric-conformance-scores/"> Conformance scores </a> </li><li> <a href="/__pyric/ui/docs/pyric-app-compat/"> App </a> </li><li> <a href="/__pyric/ui/docs/pyric-firestore-compat/"> Firestore </a> </li><li> <a href="/__pyric/ui/docs/pyric-auth-compat/"> Auth </a> </li><li> <a href="/__pyric/ui/docs/pyric-database-compat/"> Realtime Database </a> </li><li> <a href="/__pyric/ui/docs/pyric-storage-compat/"> Storage </a> </li><li> <a href="/__pyric/ui/docs/pyric-rules-compat/"> Rules </a> </li><li> <a href="/__pyric/ui/docs/pyric-messaging-compat/"> Messaging </a> </li><li> <a href="/__pyric/ui/docs/pyric-ai-compat/"> AI Logic </a> </li><li> <a href="/__pyric/ui/docs/pyric-cli-functions-rtdb-compat/"> Functions · RTDB </a> </li> </ul> </div> </div> </details> <details class="docs-nav-group" id="nav-group-reference" open> <summary>Reference</summary> <div class="docs-nav-group-body"> <div class="docs-nav-section"> <ul> <li> <a href="/__pyric/ui/docs/pyric-cli/"> @pyric/cli </a> </li><li> <a href="/__pyric/ui/docs/pyric-explanation-versioning-and-compatibility/"> pyric </a> </li><li> <a href="/__pyric/ui/docs/pyric-firestore/"> pyric / firestore </a> </li><li> <a href="/__pyric/ui/docs/pyric-rules/"> pyric / rules </a> </li><li> <a href="/__pyric/ui/docs/pyric-sandbox/"> pyric / sandbox </a> </li><li> <a href="/__pyric/ui/docs/pyric-storage/" aria-current="true"> pyric / storage </a> </li><li> <a href="/__pyric/ui/docs/pyric-auth/"> pyric / auth </a> </li><li> <a href="/__pyric/ui/docs/pyric-database/"> pyric / database </a> </li><li> <a href="/__pyric/ui/docs/pyric-admin-app/"> pyric-admin / app </a> </li><li> <a href="/__pyric/ui/docs/pyric-admin-firestore/"> pyric-admin / firestore </a> </li><li> <a href="/__pyric/ui/docs/pyric-admin-auth/"> pyric-admin / auth </a> </li><li> <a href="/__pyric/ui/docs/pyric-admin-database/"> pyric-admin / database </a> </li><li> <a href="/__pyric/ui/docs/pyric-admin-storage/"> pyric-admin / storage </a> </li><li> <a href="/__pyric/ui/docs/ui/"> @pyric/ui </a> </li><li> <a href="/__pyric/ui/docs/api-reference/"> API reference </a> </li> </ul> </div> </div> </details> </nav> <main class="doc-main"> <nav class="docs-breadcrumbs" aria-label="Breadcrumb"> <ol> <li>  <a href="/__pyric/ui/docs/pyric-storage/">pyric / storage</a> </li><li> <span class="docs-breadcrumbs-sep" aria-hidden="true">/</span> <span>Explanation</span> </li><li> <span class="docs-breadcrumbs-sep" aria-hidden="true">/</span> <span aria-current="page">Why IndexedDB</span> </li> </ol> </nav>  <article class="prose">  <h1 id="why-indexeddb">Why IndexedDB</h1>
+<p><code>pyric/storage</code>’s sandbox backend persists blobs and metadata in IndexedDB. This page explains why, and what the choice implies.</p>
+<h2 id="what-we-needed">What we needed</h2>
+<p>The driving consumer is the playground: a browser app that lets users iterate on Firebase data + rules in-page. The session archive lives in the browser too, completed sessions stored locally and optionally uploaded to production later.</p>
+<p>That meant three constraints:</p>
+<ul>
+<li><strong>Browser-native.</strong> No Node <code>fs</code>, no native binaries, no Java emulator.</li>
+<li><strong>Persistent across reloads.</strong> A user who tweaks rules, uploads a few sessions, and refreshes the page should find them still there.</li>
+<li><strong>Asynchronous.</strong> The browser’s main thread can’t block on disk I/O.</li>
+</ul>
+<p>IndexedDB ticks all three. It’s the only browser API that’s both standardised and persistent for arbitrary blobs.</p>
+<h2 id="the-alternatives-we-considered">The alternatives we considered</h2>
+<h3 id="localstorage"><code>localStorage</code></h3>
+<p>Synchronous, capped at roughly 5 to 10 MB, strings only. A 1 MB JSON session would dominate the quota immediately. Ruled out.</p>
+<h3 id="the-cache-api">The Cache API</h3>
+<p>Better quota, persistent, async, but designed for HTTP request/response pairs. Storing arbitrary objects via it requires shoehorning a <code>Request</code> and <code>Response</code> around every blob. The fit is wrong.</p>
+<h3 id="in-memory-only">In-memory only</h3>
+<p>Simplest. Fast. Lost on every reload. The playground UX depended on persistence; an in-memory-only backend would have been hostile to iteration.</p>
+<h3 id="origin-private-file-system-opfs">Origin Private File System (OPFS)</h3>
+<p>Newer, more file-system-shaped, persistent. We didn’t pick it because:</p>
+<ul>
+<li>Browser support is recent. IndexedDB is universal.</li>
+<li>The API is less ergonomic for “store a blob with metadata keyed by path”. OPFS wants directories, sync access handles, more ceremony.</li>
+<li>IndexedDB’s transaction model maps cleanly to Storage operations (each upload is one tx, each download is one tx).</li>
+</ul>
+<p>OPFS is a future option if IndexedDB hits limits. For now, IndexedDB is doing the job.</p>
+<h2 id="how-the-data-is-laid-out">How the data is laid out</h2>
+<p>Two object stores:</p>
+<ul>
+<li><strong><code>blobs</code></strong>: keyed by <code>fullPath</code>, value is the binary payload (<code>ArrayBuffer</code>).</li>
+<li><strong><code>metadata</code></strong>: keyed by <code>fullPath</code>, value is the <code>FullMetadata</code> record.</li>
+</ul>
+<p>An upload is one transaction that writes to both stores. A delete is one transaction that removes from both. Listing reads from the metadata store and walks its key range.</p>
+<p>The two-store split is deliberate. Metadata is small and frequently read (every list, every <code>getMetadata</code>); blobs are large and read only on explicit download. Splitting them lets the browser cache metadata aggressively without paging blobs through the same heap.</p>
+<h2 id="what-this-implies">What this implies</h2>
+<h3 id="quota">Quota</h3>
+<p>IndexedDB’s quota is browser-dependent. Chrome / Edge / Firefox allow a percentage of free disk (single-digit GB on most machines). Safari is more conservative. Users hitting the quota get a <code>QuotaExceededError</code>.</p>
+<p>The v1 scope doesn’t surface a quota-checked API. Consumers worried about quota should <code>try/catch</code> and surface the error to the user.</p>
+<h3 id="concurrency">Concurrency</h3>
+<p>IndexedDB’s transaction model is single-writer-per-store. Two simultaneous <code>uploadBytes</code> calls serialise behind the scenes. For the sandbox use case (one user, one tab) this is fine. For a hypothetical multi-tab scenario, the second tab’s writes would wait briefly.</p>
+<h3 id="lifetime">Lifetime</h3>
+<p>IndexedDB persists until the user clears site data. Sandbox <code>reset()</code> does <em>not</em> clear it: <code>reset()</code> is about the sandbox’s in-memory state, not the storage backend. To wipe a storage handle’s data, build a new sandbox with a different <code>dbName</code>, or call <code>deleteObject</code> per item.</p>
+<p>This separation is deliberate but occasionally surprising. The README and the <a href="../pyric-storage-reference-storage-options/"><code>StorageOptions</code></a> page call out the <code>dbName</code> idiom for test isolation.</p>
+<h3 id="browser-only">Browser-only</h3>
+<p>The IndexedDB path runs in browsers and in test runners that emulate IndexedDB (Bun has reasonable polyfills; Vitest with <code>happy-dom</code> or <code>jsdom</code> works). It does not run in plain Node.</p>
+<p>The IndexedDB sandbox does not run in plain Node. Production Node code imports Firebase directly; that is not a sandbox substitute. A pure-Node Storage sandbox backend is not in scope today.</p>
+<h2 id="where-this-leaves-us">Where this leaves us</h2>
+<p>IndexedDB hits the constraints, the data layout is simple, the API maps naturally to Storage operations. The few rough edges (quota errors, browser-only) are bounded and documented.</p>
+<p>If the package grows beyond the session-archive use case (into large-file workflows, multi-GB sets, server-side stores) the backend choice will probably split. The sandbox handle would gain an in-memory option for tests; a hypothetical filesystem option for Node-side use. The API shape stays the same.</p>
+<p>For now, IndexedDB is what the v1 scope needs.</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="#what-we-needed">What we needed</a> </li><li data-depth="2"> <a href="#the-alternatives-we-considered">The alternatives we considered</a> </li><li data-depth="3"> <a href="#localstorage">localStorage</a> </li><li data-depth="3"> <a href="#the-cache-api">The Cache API</a> </li><li data-depth="3"> <a href="#in-memory-only">In-memory only</a> </li><li data-depth="3"> <a href="#origin-private-file-system-opfs">Origin Private File System (OPFS)</a> </li><li data-depth="2"> <a href="#how-the-data-is-laid-out">How the data is laid out</a> </li><li data-depth="2"> <a href="#what-this-implies">What this implies</a> </li><li data-depth="3"> <a href="#quota">Quota</a> </li><li data-depth="3"> <a href="#concurrency">Concurrency</a> </li><li data-depth="3"> <a href="#lifetime">Lifetime</a> </li><li data-depth="3"> <a href="#browser-only">Browser-only</a> </li><li data-depth="2"> <a href="#where-this-leaves-us">Where this leaves us</a> </li> </ul> </aside> </div> <script type="module">const a=document.querySelector("[data-api-symbol-filter]"),d=[...document.querySelectorAll("[data-api-symbol-group]")],n=document.querySelector("[data-api-symbol-empty]");a?.addEventListener("input",()=>{const t=a.value.trim().toLowerCase();let o=0;for(const i of d){let e=0;i.querySelectorAll("[data-api-symbol]").forEach(l=>{const r=!t||(l.dataset.apiSymbol??"").includes(t);l.hidden=!r,r&&e++}),i.hidden=e===0,o+=e}n&&(n.hidden=o>0)});</script> <script type="module">const s=new Map;document.querySelectorAll('.doc-toc a[href^="#"]').forEach(t=>s.set(decodeURIComponent(t.hash.slice(1)),t));if(s.size>0){const t=new Set,n=()=>{let o=null;for(const e of s.keys())if(t.has(e)){o=e;break}s.forEach((e,c)=>e.classList.toggle("active",c===o))},r=new IntersectionObserver(o=>{for(const e of o)e.isIntersecting?t.add(e.target.id):t.delete(e.target.id);n()},{rootMargin:"-72px 0px -60% 0px"});s.forEach((o,e)=>{const c=document.getElementById(e);c&&r.observe(c)})}</script> <script type="module">document.querySelector('.studio__nav [aria-current="page"]')?.scrollIntoView({block:"nearest",inline:"center"});</script> </body> </html>