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-how-to-list-and-delete.md ADDED Viewed

@@ -0,0 +1,86 @@
+# How to list and delete objects
+This guide shows you how to enumerate objects under a prefix and remove them.
+## List a prefix
+```ts
+import { ref, listAll } from 'pyric/storage';
+const result = await listAll(ref(storage, 'sessions'));
+console.log('Items:', result.items.map((r) => r.name));
+console.log('Prefixes:', result.prefixes.map((r) => r.name));
+```
+`items` is direct children; `prefixes` is sub-folders (deduplicated). For `listAll(ref(storage))` (no path), the operation scans the whole bucket.
+## Iterate recursively
+`listAll` returns only direct children. To walk the full tree, recurse:
+```ts
+async function walk(folderRef: StorageReference, out: string[] = []): Promise<string[]> {
+  const result = await listAll(folderRef);
+  for (const item of result.items) out.push(item.fullPath);
+  for (const sub of result.prefixes) await walk(sub, out);
+  return out;
+}
+const all = await walk(ref(storage));
+```
+`fullPath` carries the absolute path (including the bucket prefix). Use `.name` for the leaf name only.
+## Delete a single object
+```ts
+import { deleteObject } from 'pyric/storage';
+await deleteObject(ref(storage, 'sessions/n1'));
+```
+Atomically removes both the blob data and the metadata. No-op on missing paths.
+## Bulk delete
+The package doesn't ship a bulk-delete helper, so compose one:
+```ts
+async function deleteFolder(folderRef: StorageReference): Promise<void> {
+  const result = await listAll(folderRef);
+  for (const item of result.items) await deleteObject(item);
+  for (const sub of result.prefixes) await deleteFolder(sub);
+}
+await deleteFolder(ref(storage, 'sessions'));
+```
+On sandbox this is fast (sub-millisecond per delete). On prod it makes one HTTPS call per object, costly for large folders.
+## Pagination is deferred
+`list(ref, { maxResults, pageToken })` is part of the production `firebase/storage` API but not implemented in the v1 scope. The driving use case (session archives) doesn't need pagination: every list fits in one call. The `nextPageToken: undefined` field in `ListResult` is reserved for future compatibility.
+If you have a use case that needs pagination, file an issue.
+## Gating list with rules
+`listAll` enforces the rules engine. Firebase's `read` permission governs both download and list, evaluated against the *prefix path*, so `listAll` requires `read` on the folder you're listing. A denied prefix throws `storage/unauthorized`.
+A `read` rule scoped to an item (`match /sessions/{id} { allow read }`) does NOT grant list on the parent `/sessions`; give the folder its own rule:
+```rules
+match /sessions {
+  allow read: if request.auth != null; // covers listAll of /sessions
+}
+match /sessions/{sessionId} {
+  allow read: if request.auth != null; // covers downloads of items
+}
+```
+This mirrors production Firebase. With no rules configured, `listAll` is open-by-default like every other operation. (A distinct `allow list:` verb is deferred: the v1 scope's two-verb model folds get+list into `read`.)
+## Where to look next
+- For the reference shape and overloads, see [`StorageReference`](https://pyric.dev/docs/pyric-storage-reference-api/#storagereference) and [`ref`](https://pyric.dev/docs/pyric-storage-reference-api/#ref-1).
+- For the listing result, see [`ListResult`](https://pyric.dev/docs/pyric-storage-reference-api/#listresult).

package/dist/serve/docs-ui/docs/pyric-storage-how-to-switch-backends/index.html ADDED Viewed

@@ -0,0 +1,43 @@
+<!DOCTYPE html><html lang="en"> <head><meta charset="UTF-8"><meta name="viewport" content="width=device-width, initial-scale=1.0"><title>Select the Storage runtime · 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>How-to</span> </li><li> <span class="docs-breadcrumbs-sep" aria-hidden="true">/</span> <span aria-current="page">Switch backends</span> </li> </ol> </nav>  <article class="prose">  <h1 id="select-the-storage-runtime">Select the Storage runtime</h1>
+<p>Keep application imports canonical:</p>
+<pre class="astro-code one-dark-pro" style="background-color:#282c34;color:#abb2bf; overflow-x: auto;" tabindex="0" data-language="ts"><code><span class="line"><span style="color:#C678DD">import</span><span style="color:#ABB2BF"> { </span><span style="color:#E06C75">initializeApp</span><span style="color:#ABB2BF"> } </span><span style="color:#C678DD">from</span><span style="color:#98C379"> 'firebase/app'</span><span style="color:#ABB2BF">;</span></span>
+<span class="line"><span style="color:#C678DD">import</span><span style="color:#ABB2BF"> { </span><span style="color:#E06C75">getStorage</span><span style="color:#ABB2BF">, </span><span style="color:#E06C75">ref</span><span style="color:#ABB2BF">, </span><span style="color:#E06C75">uploadBytes</span><span style="color:#ABB2BF"> } </span><span style="color:#C678DD">from</span><span style="color:#98C379"> 'firebase/storage'</span><span style="color:#ABB2BF">;</span></span>
+<span class="line"></span>
+<span class="line"><span style="color:#C678DD">const</span><span style="color:#E5C07B"> app</span><span style="color:#56B6C2"> =</span><span style="color:#61AFEF"> initializeApp</span><span style="color:#ABB2BF">(</span><span style="color:#E06C75">firebaseConfig</span><span style="color:#ABB2BF">);</span></span>
+<span class="line"><span style="color:#C678DD">const</span><span style="color:#E5C07B"> storage</span><span style="color:#56B6C2"> =</span><span style="color:#61AFEF"> getStorage</span><span style="color:#ABB2BF">(</span><span style="color:#E06C75">app</span><span style="color:#ABB2BF">);</span></span>
+<span class="line"><span style="color:#C678DD">await</span><span style="color:#61AFEF"> uploadBytes</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 style="color:#E06C75">bytes</span><span style="color:#ABB2BF">);</span></span></code></pre>
+<p>The package resolver chooses the implementation before this code runs.</p>
+<h2 id="development-uses-the-sandbox-mirror">Development uses the sandbox mirror</h2>
+<p>With <code>pyricSandbox()</code> or <code>pyric dev</code>, <code>firebase/storage</code> resolves to the Pyric
+served entry. The Firebase config and optional bucket argument are accepted,
+but the single-bucket sandbox stores bytes in IndexedDB and enforces the rules
+loaded by the development runtime.</p>
+<p><code>getDownloadURL</code> returns a page-local <code>blob:</code> snapshot. Revoke it when done:</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">'avatars/ada.png'</span><span style="color:#ABB2BF">));</span></span>
+<span class="line"><span style="color:#E5C07B">image</span><span style="color:#ABB2BF">.</span><span style="color:#E06C75">src</span><span style="color:#56B6C2"> =</span><span style="color:#E06C75"> url</span><span style="color:#ABB2BF">;</span></span>
+<span class="line"><span style="color:#E5C07B">image</span><span style="color:#ABB2BF">.</span><span style="color:#61AFEF">addEventListener</span><span style="color:#ABB2BF">(</span><span style="color:#98C379">'load'</span><span style="color:#ABB2BF">, () </span><span style="color:#C678DD">=></span><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:#E06C75">once</span><span style="color:#ABB2BF">: </span><span style="color:#D19A66">true</span><span style="color:#ABB2BF"> });</span></span></code></pre>
+<h2 id="production-uses-firebase-directly">Production uses Firebase directly</h2>
+<p>A normal production build does not activate the Pyric swap. The same
+<code>firebase/storage</code> import resolves to Firebase, so <code>getStorage(app)</code> reaches the
+configured bucket and <code>getDownloadURL</code> returns Firebase’s token-signed HTTPS
+URL. <code>pyric/storage</code> is not loaded and does not delegate the call.</p>
+<pre class="astro-code one-dark-pro" style="background-color:#282c34;color:#abb2bf; overflow-x: auto;" tabindex="0" data-language="text"><code><span class="line"><span>firebase/storage import</span></span>
+<span class="line"><span>├── Vite dev / pyric dev ──> Pyric sandbox mirror</span></span>
+<span class="line"><span>└── production build ──────> Firebase Storage</span></span></code></pre>
+<h2 id="direct-pyric-imports-are-sandbox-only">Direct Pyric imports are sandbox-only</h2>
+<p>Use <code>getStorageSandbox(target, options?)</code> when a test or tool explicitly owns a
+<code>Sandbox</code> or <code>SandboxContext</code>:</p>
+<pre class="astro-code one-dark-pro" style="background-color:#282c34;color:#abb2bf; overflow-x: auto;" tabindex="0" data-language="ts"><code><span class="line"><span style="color:#C678DD">import</span><span style="color:#ABB2BF"> { </span><span style="color:#E06C75">initializeSandbox</span><span style="color:#ABB2BF"> } </span><span style="color:#C678DD">from</span><span style="color:#98C379"> 'pyric/sandbox'</span><span style="color:#ABB2BF">;</span></span>
+<span class="line"><span style="color:#C678DD">import</span><span style="color:#ABB2BF"> { </span><span style="color:#E06C75">getStorageSandbox</span><span style="color:#ABB2BF">, </span><span style="color:#E06C75">ref</span><span style="color:#ABB2BF">, </span><span style="color:#E06C75">uploadBytes</span><span style="color:#ABB2BF"> } </span><span style="color:#C678DD">from</span><span style="color:#98C379"> 'pyric/storage'</span><span style="color:#ABB2BF">;</span></span>
+<span class="line"></span>
+<span class="line"><span style="color:#C678DD">const</span><span style="color:#E5C07B"> sandbox</span><span style="color:#56B6C2"> =</span><span style="color:#61AFEF"> initializeSandbox</span><span style="color:#ABB2BF">();</span></span>
+<span class="line"><span style="color:#C678DD">const</span><span style="color:#E5C07B"> storage</span><span style="color:#56B6C2"> =</span><span style="color:#61AFEF"> getStorageSandbox</span><span style="color:#ABB2BF">(</span><span style="color:#E5C07B">sandbox</span><span style="color:#ABB2BF">.</span><span style="color:#61AFEF">withAuth</span><span style="color:#ABB2BF">({ </span><span style="color:#E06C75">uid</span><span style="color:#ABB2BF">: </span><span style="color:#98C379">'alice'</span><span style="color:#ABB2BF"> }));</span></span>
+<span class="line"><span style="color:#C678DD">await</span><span style="color:#61AFEF"> uploadBytes</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 style="color:#E06C75">bytes</span><span style="color:#ABB2BF">);</span></span></code></pre>
+<p>There is no Pyric production factory. Import <code>firebase/storage</code> for production.</p>
+<h2 id="where-to-look-next">Where to look next</h2>
+<ul>
+<li>Use the Vite plugin</li>
+<li><a href="../pyric-storage-how-to-enforce-rules/">Enforce Storage rules</a></li>
+<li><a href="../pyric-storage-reference-storage-options/"><code>StorageOptions</code></a></li>
+<li><a href="../pyric-storage-explanation-implementation-scope/">Implementation scope</a></li>
+</ul>  </article> </main> <aside class="doc-toc" aria-label="On this page"> <h2 class="doc-toc-heading">On this page</h2> <ul> <li data-depth="2"> <a href="#development-uses-the-sandbox-mirror">Development uses the sandbox mirror</a> </li><li data-depth="2"> <a href="#production-uses-firebase-directly">Production uses Firebase directly</a> </li><li data-depth="2"> <a href="#direct-pyric-imports-are-sandbox-only">Direct Pyric imports are sandbox-only</a> </li><li data-depth="2"> <a href="#where-to-look-next">Where to look next</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-how-to-switch-backends.md ADDED Viewed

@@ -0,0 +1,65 @@
+# Select the Storage runtime
+Keep application imports canonical:
+```ts
+import { initializeApp } from 'firebase/app';
+import { getStorage, ref, uploadBytes } from 'firebase/storage';
+const app = initializeApp(firebaseConfig);
+const storage = getStorage(app);
+await uploadBytes(ref(storage, 'sessions/n1'), bytes);
+```
+The package resolver chooses the implementation before this code runs.
+## Development uses the sandbox mirror
+With `pyricSandbox()` or `pyric dev`, `firebase/storage` resolves to the Pyric
+served entry. The Firebase config and optional bucket argument are accepted,
+but the single-bucket sandbox stores bytes in IndexedDB and enforces the rules
+loaded by the development runtime.
+`getDownloadURL` returns a page-local `blob:` snapshot. Revoke it when done:
+```ts
+const url = await getDownloadURL(ref(storage, 'avatars/ada.png'));
+image.src = url;
+image.addEventListener('load', () => URL.revokeObjectURL(url), { once: true });
+```
+## Production uses Firebase directly
+A normal production build does not activate the Pyric swap. The same
+`firebase/storage` import resolves to Firebase, so `getStorage(app)` reaches the
+configured bucket and `getDownloadURL` returns Firebase's token-signed HTTPS
+URL. `pyric/storage` is not loaded and does not delegate the call.
+```text
+firebase/storage import
+├── Vite dev / pyric dev ──> Pyric sandbox mirror
+└── production build ──────> Firebase Storage
+```
+## Direct Pyric imports are sandbox-only
+Use `getStorageSandbox(target, options?)` when a test or tool explicitly owns a
+`Sandbox` or `SandboxContext`:
+```ts
+import { initializeSandbox } from 'pyric/sandbox';
+import { getStorageSandbox, ref, uploadBytes } from 'pyric/storage';
+const sandbox = initializeSandbox();
+const storage = getStorageSandbox(sandbox.withAuth({ uid: 'alice' }));
+await uploadBytes(ref(storage, 'sessions/n1'), bytes);
+```
+There is no Pyric production factory. Import `firebase/storage` for production.
+## Where to look next
+- Use the Vite plugin
+- [Enforce Storage rules](../pyric-storage-how-to-enforce-rules/)
+- [`StorageOptions`](../pyric-storage-reference-storage-options/)
+- [Implementation scope](../pyric-storage-explanation-implementation-scope/)

package/dist/serve/docs-ui/docs/pyric-storage-how-to-test-rule-expressions/index.html ADDED Viewed

@@ -0,0 +1,70 @@
+<!DOCTYPE html><html lang="en"> <head><meta charset="UTF-8"><meta name="viewport" content="width=device-width, initial-scale=1.0"><title>How to test rule expressions independently · 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>How-to</span> </li><li> <span class="docs-breadcrumbs-sep" aria-hidden="true">/</span> <span aria-current="page">Test rule expressions</span> </li> </ol> </nav>  <article class="prose">  <h1 id="how-to-test-rule-expressions-independently">How to test rule expressions independently</h1>
+<p>This guide shows you how to verify a Storage rule expression without uploading anything. Useful when iterating on a complex rule or building a rules-test harness.</p>
+<h2 id="the-two-functions">The two functions</h2>
+<pre class="astro-code one-dark-pro" style="background-color:#282c34;color:#abb2bf; overflow-x: auto;" tabindex="0" data-language="ts"><code><span class="line"><span style="color:#C678DD">import</span><span style="color:#ABB2BF"> { </span><span style="color:#E06C75">parseStorageRules</span><span style="color:#ABB2BF">, </span><span style="color:#E06C75">evaluateStorageRules</span><span style="color:#ABB2BF"> } </span><span style="color:#C678DD">from</span><span style="color:#98C379"> 'pyric/storage'</span><span style="color:#ABB2BF">;</span></span></code></pre>
+<ul>
+<li><strong><code>parseStorageRules(source)</code></strong> returns a <code>ParsedRules</code> object. Throws a <code>SyntaxError</code> with line/column info if the source is malformed.</li>
+<li><strong><code>evaluateStorageRules(rules, input)</code></strong> takes parsed rules plus a synthetic request shape and returns <code>{ allowed: true } | { allowed: false; reason }</code>.</li>
+</ul>
+<h2 id="a-complete-test">A complete test</h2>
+<pre class="astro-code one-dark-pro" style="background-color:#282c34;color:#abb2bf; overflow-x: auto;" tabindex="0" data-language="ts"><code><span class="line"><span style="color:#C678DD">const</span><span style="color:#E5C07B"> source</span><span style="color:#56B6C2"> =</span><span style="color:#98C379"> `service firebase.storage {</span></span>
+<span class="line"><span style="color:#98C379">  match /b/{bucket}/o {</span></span>
+<span class="line"><span style="color:#98C379">    match /sessions/{id} {</span></span>
+<span class="line"><span style="color:#98C379">      allow write: if request.auth != null</span></span>
+<span class="line"><span style="color:#98C379">                   &#x26;&#x26; request.resource.size &#x3C; 10 * 1024 * 1024</span></span>
+<span class="line"><span style="color:#98C379">                   &#x26;&#x26; request.resource.contentType == 'application/json';</span></span>
+<span class="line"><span style="color:#98C379">      allow read: if request.auth != null;</span></span>
+<span class="line"><span style="color:#98C379">    }</span></span>
+<span class="line"><span style="color:#98C379">  }</span></span>
+<span class="line"><span style="color:#98C379">}`</span><span style="color:#ABB2BF">;</span></span>
+<span class="line"></span>
+<span class="line"><span style="color:#C678DD">const</span><span style="color:#E5C07B"> rules</span><span style="color:#56B6C2"> =</span><span style="color:#61AFEF"> parseStorageRules</span><span style="color:#ABB2BF">(</span><span style="color:#E06C75">source</span><span style="color:#ABB2BF">);</span></span>
+<span class="line"></span>
+<span class="line"><span style="color:#7F848E;font-style:italic">// Authenticated, valid upload.</span></span>
+<span class="line"><span style="color:#C678DD">const</span><span style="color:#E5C07B"> okay</span><span style="color:#56B6C2"> =</span><span style="color:#61AFEF"> evaluateStorageRules</span><span style="color:#ABB2BF">(</span><span style="color:#E06C75">rules</span><span style="color:#ABB2BF">, {</span></span>
+<span class="line"><span style="color:#E06C75">  path</span><span style="color:#ABB2BF">: </span><span style="color:#98C379">'b/pyric-default/o/sessions/n1'</span><span style="color:#ABB2BF">,</span></span>
+<span class="line"><span style="color:#E06C75">  method</span><span style="color:#ABB2BF">: </span><span style="color:#98C379">'create'</span><span style="color:#ABB2BF">,</span></span>
+<span class="line"><span style="color:#E06C75">  auth</span><span style="color:#ABB2BF">: { </span><span style="color:#E06C75">uid</span><span style="color:#ABB2BF">: </span><span style="color:#98C379">'alice'</span><span style="color:#ABB2BF">, </span><span style="color:#E06C75">token</span><span style="color:#ABB2BF">: {} },</span></span>
+<span class="line"><span style="color:#E06C75">  resource</span><span style="color:#ABB2BF">: { </span><span style="color:#E06C75">size</span><span style="color:#ABB2BF">: </span><span style="color:#D19A66">1024</span><span style="color:#ABB2BF">, </span><span style="color:#E06C75">contentType</span><span style="color:#ABB2BF">: </span><span style="color:#98C379">'application/json'</span><span style="color:#ABB2BF"> },</span></span>
+<span class="line"><span style="color:#ABB2BF">});</span></span>
+<span class="line"><span style="color:#E5C07B">console</span><span style="color:#ABB2BF">.</span><span style="color:#61AFEF">log</span><span style="color:#ABB2BF">(</span><span style="color:#E06C75">okay</span><span style="color:#ABB2BF">);  </span><span style="color:#7F848E;font-style:italic">// { allowed: true }</span></span>
+<span class="line"></span>
+<span class="line"><span style="color:#7F848E;font-style:italic">// Anonymous upload denies.</span></span>
+<span class="line"><span style="color:#C678DD">const</span><span style="color:#E5C07B"> denied</span><span style="color:#56B6C2"> =</span><span style="color:#61AFEF"> evaluateStorageRules</span><span style="color:#ABB2BF">(</span><span style="color:#E06C75">rules</span><span style="color:#ABB2BF">, {</span></span>
+<span class="line"><span style="color:#E06C75">  path</span><span style="color:#ABB2BF">: </span><span style="color:#98C379">'b/pyric-default/o/sessions/n1'</span><span style="color:#ABB2BF">,</span></span>
+<span class="line"><span style="color:#E06C75">  method</span><span style="color:#ABB2BF">: </span><span style="color:#98C379">'create'</span><span style="color:#ABB2BF">,</span></span>
+<span class="line"><span style="color:#E06C75">  auth</span><span style="color:#ABB2BF">: </span><span style="color:#D19A66">null</span><span style="color:#ABB2BF">,</span></span>
+<span class="line"><span style="color:#E06C75">  resource</span><span style="color:#ABB2BF">: { </span><span style="color:#E06C75">size</span><span style="color:#ABB2BF">: </span><span style="color:#D19A66">1024</span><span style="color:#ABB2BF">, </span><span style="color:#E06C75">contentType</span><span style="color:#ABB2BF">: </span><span style="color:#98C379">'application/json'</span><span style="color:#ABB2BF"> },</span></span>
+<span class="line"><span style="color:#ABB2BF">});</span></span>
+<span class="line"><span style="color:#E5C07B">console</span><span style="color:#ABB2BF">.</span><span style="color:#61AFEF">log</span><span style="color:#ABB2BF">(</span><span style="color:#E06C75">denied</span><span style="color:#ABB2BF">);</span></span>
+<span class="line"><span style="color:#7F848E;font-style:italic">// { allowed: false, reason: 'request.auth != null failed' }</span></span></code></pre>
+<p>The synthetic input mirrors what the actual handler builds when an operation runs against a sandbox-backed handle.</p>
+<h2 id="the-input-shape">The input shape</h2>
+<pre class="astro-code one-dark-pro" style="background-color:#282c34;color:#abb2bf; overflow-x: auto;" tabindex="0" data-language="ts"><code><span class="line"><span style="color:#ABB2BF">{</span></span>
+<span class="line"><span style="color:#E06C75">  path</span><span style="color:#ABB2BF">: </span><span style="color:#E06C75">string</span><span style="color:#ABB2BF">;                          </span><span style="color:#7F848E;font-style:italic">// full path, including bucket prefix</span></span>
+<span class="line"><span style="color:#E06C75">  method</span><span style="color:#ABB2BF">: </span><span style="color:#98C379">'get'</span><span style="color:#56B6C2"> |</span><span style="color:#98C379"> 'create'</span><span style="color:#56B6C2"> |</span><span style="color:#98C379"> 'update'</span><span style="color:#56B6C2"> |</span><span style="color:#98C379"> 'delete'</span><span style="color:#ABB2BF">;</span></span>
+<span class="line"><span style="color:#E06C75">  auth</span><span style="color:#ABB2BF">: { </span><span style="color:#E06C75">uid</span><span style="color:#ABB2BF">: </span><span style="color:#E06C75">string</span><span style="color:#ABB2BF">; </span><span style="color:#E06C75">token</span><span style="color:#ABB2BF">: </span><span style="color:#E06C75">object</span><span style="color:#ABB2BF"> } </span><span style="color:#56B6C2">|</span><span style="color:#D19A66"> null</span><span style="color:#ABB2BF">;</span></span>
+<span class="line"><span style="color:#E06C75">  resource</span><span style="color:#C678DD">?:</span><span style="color:#ABB2BF"> { </span><span style="color:#E06C75">size</span><span style="color:#ABB2BF">: </span><span style="color:#E06C75">number</span><span style="color:#ABB2BF">; </span><span style="color:#E06C75">contentType</span><span style="color:#ABB2BF">: </span><span style="color:#E06C75">string</span><span style="color:#ABB2BF"> };  </span><span style="color:#7F848E;font-style:italic">// for writes</span></span>
+<span class="line"><span style="color:#E06C75">  existing</span><span style="color:#C678DD">?:</span><span style="color:#ABB2BF"> { </span><span style="color:#E06C75">size</span><span style="color:#ABB2BF">: </span><span style="color:#E06C75">number</span><span style="color:#ABB2BF">; </span><span style="color:#E06C75">contentType</span><span style="color:#ABB2BF">: </span><span style="color:#E06C75">string</span><span style="color:#ABB2BF">; </span><span style="color:#E06C75">metadata</span><span style="color:#C678DD">?:</span><span style="color:#E06C75"> Record</span><span style="color:#56B6C2">&#x3C;</span><span style="color:#E06C75">string</span><span style="color:#ABB2BF">, string> };  </span><span style="color:#7F848E;font-style:italic">// for read/update/delete</span></span>
+<span class="line"><span style="color:#ABB2BF">}</span></span></code></pre>
+<p><code>resource</code> represents <code>request.resource</code> (what’s being uploaded). <code>existing</code> represents <code>resource</code> (what’s already stored). Set whichever the rule references.</p>
+<h2 id="why-not-go-through-the-handler">Why not go through the handler</h2>
+<p>Using <code>evaluateStorageRules</code> directly:</p>
+<ul>
+<li>Doesn’t require constructing a sandbox.</li>
+<li>Doesn’t require uploading any data.</li>
+<li>Is fast (microseconds, it only walks the AST).</li>
+</ul>
+<p>For iterating on rule logic or building a parametric rules-test harness, this is the right surface. For end-to-end verification (does the actual handler enforce the rule correctly?) use <code>getStorageSandbox(target, { rules: source })</code> and exercise it through normal operations.</p>
+<h2 id="what-you-cant-test-this-way">What you can’t test this way</h2>
+<p>The synthetic input is what <em>you</em> fabricate. The real handler builds its input from the operation arguments, so if your handler-side wiring has a bug (passing wrong content-type, wrong size), <code>evaluateStorageRules</code> won’t catch it. The two surfaces verify different layers:</p>
+<ul>
+<li><code>evaluateStorageRules</code> verifies the rule’s <em>logic</em>.</li>
+<li><code>getStorageSandbox</code> with the rule deployed verifies the <em>integration</em>.</li>
+</ul>
+<p>For a full test, run both. Most tests need only one or the other.</p>
+<h2 id="where-to-look-next">Where to look next</h2>
+<ul>
+<li>For the input and result shapes, see <a href="https://pyric.dev/docs/pyric-storage-reference-api/#evaluatestoragerules" target="_blank" rel="noopener noreferrer" class="external-link"><code>evaluateStorageRules</code></a>.</li>
+<li>For the grammar these functions parse, see <a href="../pyric-storage-reference-rules-subset/">Storage rules subset</a>.</li>
+</ul>  </article> </main> <aside class="doc-toc" aria-label="On this page"> <h2 class="doc-toc-heading">On this page</h2> <ul> <li data-depth="2"> <a href="#the-two-functions">The two functions</a> </li><li data-depth="2"> <a href="#a-complete-test">A complete test</a> </li><li data-depth="2"> <a href="#the-input-shape">The input shape</a> </li><li data-depth="2"> <a href="#why-not-go-through-the-handler">Why not go through the handler</a> </li><li data-depth="2"> <a href="#what-you-cant-test-this-way">What you can’t test this way</a> </li><li data-depth="2"> <a href="#where-to-look-next">Where to look next</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-how-to-test-rule-expressions.md ADDED Viewed

@@ -0,0 +1,88 @@
+# How to test rule expressions independently
+This guide shows you how to verify a Storage rule expression without uploading anything. Useful when iterating on a complex rule or building a rules-test harness.
+## The two functions
+```ts
+import { parseStorageRules, evaluateStorageRules } from 'pyric/storage';
+```
+- **`parseStorageRules(source)`** returns a `ParsedRules` object. Throws a `SyntaxError` with line/column info if the source is malformed.
+- **`evaluateStorageRules(rules, input)`** takes parsed rules plus a synthetic request shape and returns `{ allowed: true } | { allowed: false; reason }`.
+## A complete test
+```ts
+const source = `service firebase.storage {
+  match /b/{bucket}/o {
+    match /sessions/{id} {
+      allow write: if request.auth != null
+                   && request.resource.size < 10 * 1024 * 1024
+                   && request.resource.contentType == 'application/json';
+      allow read: if request.auth != null;
+    }
+  }
+}`;
+const rules = parseStorageRules(source);
+// Authenticated, valid upload.
+const okay = evaluateStorageRules(rules, {
+  path: 'b/pyric-default/o/sessions/n1',
+  method: 'create',
+  auth: { uid: 'alice', token: {} },
+  resource: { size: 1024, contentType: 'application/json' },
+});
+console.log(okay);  // { allowed: true }
+// Anonymous upload denies.
+const denied = evaluateStorageRules(rules, {
+  path: 'b/pyric-default/o/sessions/n1',
+  method: 'create',
+  auth: null,
+  resource: { size: 1024, contentType: 'application/json' },
+});
+console.log(denied);
+// { allowed: false, reason: 'request.auth != null failed' }
+```
+The synthetic input mirrors what the actual handler builds when an operation runs against a sandbox-backed handle.
+## The input shape
+```ts
+{
+  path: string;                          // full path, including bucket prefix
+  method: 'get' | 'create' | 'update' | 'delete';
+  auth: { uid: string; token: object } | null;
+  resource?: { size: number; contentType: string };  // for writes
+  existing?: { size: number; contentType: string; metadata?: Record<string, string> };  // for read/update/delete
+}
+```
+`resource` represents `request.resource` (what's being uploaded). `existing` represents `resource` (what's already stored). Set whichever the rule references.
+## Why not go through the handler
+Using `evaluateStorageRules` directly:
+- Doesn't require constructing a sandbox.
+- Doesn't require uploading any data.
+- Is fast (microseconds, it only walks the AST).
+For iterating on rule logic or building a parametric rules-test harness, this is the right surface. For end-to-end verification (does the actual handler enforce the rule correctly?) use `getStorageSandbox(target, { rules: source })` and exercise it through normal operations.
+## What you can't test this way
+The synthetic input is what *you* fabricate. The real handler builds its input from the operation arguments, so if your handler-side wiring has a bug (passing wrong content-type, wrong size), `evaluateStorageRules` won't catch it. The two surfaces verify different layers:
+- `evaluateStorageRules` verifies the rule's *logic*.
+- `getStorageSandbox` with the rule deployed verifies the *integration*.
+For a full test, run both. Most tests need only one or the other.
+## Where to look next
+- For the input and result shapes, see [`evaluateStorageRules`](https://pyric.dev/docs/pyric-storage-reference-api/#evaluatestoragerules).
+- For the grammar these functions parse, see [Storage rules subset](../pyric-storage-reference-rules-subset/).