@pyric/cli 0.1.0-alpha.9

package/dist/serve/docs-ui/docs/pyric-sandbox-reference-sandbox-event.md

@@ -0,0 +1,204 @@
+# `SandboxEvent`
+
+The discriminated union `sandbox.onEvent(cb)` delivers. Filter on `kind` to
+recover any individual event family. The unified channel replaces the prior
+`onRequest` / `onDenial` / `onSnapshotError` triplet.
+
+## The union
+
+```ts
+type SandboxEvent =
+  | RequestEvent              // kind: 'request'
+  | WriteSandboxEvent         // kind: 'write'
+  | SnapshotDeliveryEvent     // kind: 'snapshot_delivery'
+  | SnapshotSuppressedEvent   // kind: 'snapshot_suppressed'
+  | ListenerLifecycleEvent    // kind: 'listener_attach' | 'listener_detach' | 'listener_errored'
+  | SessionBoundaryEvent;     // kind: 'session_boundary'
+```
+
+Every event carries `kind: <discriminator>`, `id: string` (unique within the sandbox process; React-list-key safe), and `at: number` (`Date.now()` at emission).
+
+## `kind: 'request'`: every evaluated op
+
+```ts
+interface RequestEvent {
+  kind: 'request';
+  id: string;
+  at: number;
+  evalMs: number;
+  method: 'get' | 'list' | 'create' | 'update' | 'set' | 'delete';
+  path: string;
+  auth: AuthState;
+  result: 'allow' | 'deny' | 'unsupported';
+  reasons: string[];
+  request?: { resourceData?: Record<string, unknown> };
+  resourceBefore?: { data: Record<string, unknown> | null; exists: boolean };
+  resourceAfter?: { data: Record<string, unknown> | null; exists: boolean };
+  matchedRule?: { ruleIndex: number; operations: string[] };
+  origin: 'user' | 'listener' | 'transaction' | 'batch';
+  groupId?: string;
+  groupKind?: 'batch' | 'transaction';
+  triggeredBy?: { method: string; path: string };
+}
+```
+
+Fires once per simulator-evaluated op. Denials surface here with `result: 'deny'`; the previous `DenialEvent` shape lives on as a derived field-projection. Filter `kind === 'request' && result === 'deny'` to recover it.
+
+**`method`** preserves the caller's verb. `set` stays `'set'` (the rule engine maps it internally to `'create'` or `'update'` based on whether the doc exists; that mapping appears on `matchedRule.operations`).
+
+**`origin`** disambiguates user-driven single ops from batch / transaction sub-ops and from listener re-evals. `groupId` is shared across the sub-ops of a single batch or transaction; `groupKind` tells you which.
+
+**`triggeredBy`** populates on `origin: 'listener'` events when the listener re-eval was caused by a user op (write, batch, or transaction). Initial-fire events and `deployRules`-driven re-evals carry no `triggeredBy`.
+
+**`evalMs`** is the wall-clock duration of `simulator.simulate(...)`. Sub-millisecond for trivial rules; a traffic-monitor validation probe measured ~95ms p99 on connect-four's deep boolean chains.
+
+## `kind: 'write'`: committed writes only
+
+```ts
+interface WriteSandboxEvent {
+  kind: 'write';
+  id: string;
+  at: number;
+  method: 'create' | 'update' | 'set' | 'delete';
+  path: string;
+  auth: AuthState;
+  data?: Record<string, unknown>;
+  priorState: Record<string, unknown> | null;
+  nextState: Record<string, unknown> | null;
+  groupId?: string;
+  groupKind?: 'batch' | 'transaction';
+  sentinels?: Array<{ field: string; kind: 'serverTimestamp' | 'increment' | 'arrayUnion' | 'arrayRemove' | 'delete' }>;
+  autoId?: string;
+  requestTime: { seconds: number; nanoseconds: number };
+}
+```
+
+Fires AFTER the corresponding `kind: 'request'` event for the same op, and ONLY for writes that the rule engine allowed AND the keyspace successfully applied. Denied or rolled-back writes don't emit a write event. They surface as `kind: 'request' && result: 'deny'` only.
+
+**`data`** is the **pre-resolution** payload: the user's intent. `FieldValue.*` sentinels are preserved as their marker shapes (`{ __type: 'serverTimestamp' }`, etc.); plain values pass through unchanged. The replay engine re-resolves the markers against a fresh sandbox so `pinRequestTime: false` actually drifts and `pinRequestTime: true` matches capture. Absent on `delete`. The materialized values the keyspace applied live on `nextState`.
+
+**`priorState`** / **`nextState`** are full **post-resolution** doc snapshots, actual stored state. `null` when the doc is absent. Use these for diff rendering, undo, or forensic logging.
+
+**`sentinels`** is a flat index of the markers in `data`, keyed by field path (dotted with bracket-indices, `a.b[0].c`). Redundant with `data` (you could walk it yourself), but cheap to consume and emitted unconditionally when sentinels are present. Absent when the write had none.
+
+**`autoId`** is the minted document ID (the path's last segment) when the write came from `collection.add()` / `LocalEnvironment.createWithAutoId`. The replay engine aliases this path to a fresh mint rather than reusing the original ID. Absent on explicit-ID writes.
+
+**`requestTime`** pins the `request.time` the rule engine evaluated against. The shape mirrors the Firestore Web SDK Timestamp (`{ seconds, nanoseconds }`). Required. The replay engine re-issues this exact value when re-resolving `serverTimestamp()` sentinels so resolved fields are bit-identical on replay; rules that branch on `request.time` evaluate identically. Within a batch or transaction, all sub-ops share the same `requestTime`.
+
+## `kind: 'snapshot_delivery'`: listener callback fired
+
+```ts
+interface SnapshotDeliveryEvent {
+  kind: 'snapshot_delivery';
+  id: string;
+  at: number;
+  listenerId: string;
+  target: { kind: 'doc'; path: string } | { kind: 'query'; collection: string };
+  auth: AuthState;
+  addedCount: number;
+  modifiedCount: number;
+  removedCount: number;
+  size: number;
+  sample?: {
+    docs: Array<{ path: string; data: Record<string, unknown> | null }>;
+  };
+  triggeredBy?: { method: string; path: string };
+}
+```
+
+Fires AFTER the user callback runs, corresponding 1:1 with actual snapshot deliveries.
+
+**`addedCount` + `modifiedCount` + `removedCount`** match `QuerySnapshot.docChanges()`. Doc-target listeners report exactly one of (added=1, removed=1, modified=1) per fire. Query-target listeners can report any combination; the initial fire surfaces every doc as `added`.
+
+**`size`** is the doc count surfaced to the listener: `1` (exists) / `0` (deleted) for doc-target, `n` for query-target.
+
+**`sample.docs`** carries the docs as the user callback received them, serialization-ready. Consumers truncate before persisting if scenarios produce large snapshots; the sandbox doesn't truncate itself.
+
+**`triggeredBy`** absent on initial fire (no user op caused it) and on `deployRules`-driven re-evals.
+
+## `kind: 'snapshot_suppressed'`: re-eval ran but didn't deliver
+
+```ts
+interface SnapshotSuppressedEvent {
+  kind: 'snapshot_suppressed';
+  id: string;
+  at: number;
+  listenerId: string;
+  target: { kind: 'doc'; path: string } | { kind: 'query'; collection: string };
+  auth: AuthState;
+  reason: 'no-op';
+  triggeredBy?: { method: string; path: string };
+}
+```
+
+Fires when a listener wakes up on a write but the diff against the prior snapshot finds nothing observable changed (the no-op suppression). Useful for "why didn't my listener fire" debugging.
+
+**`reason`** is `'no-op'` in v1. The discriminator exists so future suppression sources (auth changes, rules changes mid-listen) can land without reshape.
+
+## `kind: 'listener_attach' | 'listener_detach' | 'listener_errored'`
+
+```ts
+interface ListenerLifecycleEvent {
+  kind: 'listener_attach' | 'listener_detach' | 'listener_errored';
+  id: string;
+  at: number;
+  listenerId: string;
+  target: { kind: 'doc'; path: string } | { kind: 'query'; collection: string };
+  auth: AuthState;
+  error?: {
+    code: 'permission-denied';
+    message: string;
+    reasons?: string[];
+  };
+}
+```
+
+**`listener_attach`** fires once when `onSnapshot` registers a record, BEFORE the initial-snapshot delivery.
+
+**`listener_detach`** fires once when the returned unsubscribe is called against a still-registered listener. Idempotent unsubscribes don't double-emit. Listeners dropped by `sandbox.reset()` don't emit detach; the `session_boundary` event covers the rollover.
+
+**`listener_errored`** fires when a stream-level rule denial silently terminates the listener (initial-read denial, change-driven re-read denial, or `deployRules` flipping a listener allowed → denied). The listener stops delivering snapshots after this event and the user's `errorCallback` fires once with the same error.
+
+**`error`** is populated on `listener_errored` only. The shape mirrors what the previous `SnapshotErrorEvent` carried.
+
+## `kind: 'session_boundary'`: reset / dispose
+
+```ts
+interface SessionBoundaryEvent {
+  kind: 'session_boundary';
+  id: string;
+  at: number;
+  phase: 'reset' | 'dispose';
+  priorOpCount: number;
+}
+```
+
+Fires BEFORE the env swap on `sandbox.reset()` and BEFORE registry teardown on `sandbox.dispose()`. The subscription itself survives `reset()`; only `dispose()` clears it.
+
+**`priorOpCount`** is the cumulative count of events emitted from this sandbox prior to the boundary. Useful for verifying a persisted stream's segmentation against the sandbox's own bookkeeping.
+
+## Filter cookbook
+
+```ts
+// All denials (replaces the old onDenial channel).
+const isDenial = (e: SandboxEvent): e is RequestEvent =>
+  e.kind === 'request' && e.result === 'deny';
+
+// Snapshot stream errors (replaces the old onSnapshotError channel).
+const isStreamError = (e: SandboxEvent): e is ListenerLifecycleEvent =>
+  e.kind === 'listener_errored';
+
+// Every committed write (replaces tapping the internal EventLog).
+const isCommittedWrite = (e: SandboxEvent): e is WriteSandboxEvent =>
+  e.kind === 'write';
+
+// Anything a listener delivered to user code.
+const isLiveDelivery = (e: SandboxEvent): e is SnapshotDeliveryEvent =>
+  e.kind === 'snapshot_delivery';
+```
+
+## See also
+
+- [Observe sandbox events](../pyric-sandbox-how-to-observe-events/): usage patterns + subscriber contract.
+- [`Sandbox.onEvent`](../pyric-sandbox-reference-sandbox-and-context/): the method docs.
+- Design rationale: the reasoning for replacing the three-channel surface with one.

package/dist/serve/docs-ui/docs/pyric-sandbox-reference-snapshot-and-admin/index.html

@@ -0,0 +1,53 @@
+<!DOCTYPE html><html lang="en"> <head><meta charset="UTF-8"><meta name="viewport" content="width=device-width, initial-scale=1.0"><title>SandboxSnapshot and admin reads · Pyric Studio</title><link rel="preconnect" href="https://fonts.googleapis.com"><link rel="preconnect" href="https://fonts.gstatic.com" crossorigin><link href="https://fonts.googleapis.com/css2?family=Inter:wght@300;400;500;600;700&family=JetBrains+Mono:wght@400;500;700&display=swap" rel="stylesheet"><link rel="stylesheet" href="/__pyric/ui/_astro/_slug_.CQYSemvw.css"></head> <body>  <header class="studio__bar"> <div class="studio__bar-inner"> <a class="studio__brand" href="/__pyric/ui/" aria-label="Pyric Studio">Pyric</a> <nav class="studio__nav" aria-label="Studio tabs"> <a class="studio__nav-tab" href="/__pyric/ui/"> Home </a><a class="studio__nav-tab" href="/__pyric/ui/firestore"> Firestore </a><a class="studio__nav-tab" href="/__pyric/ui/auth"> Auth </a><a class="studio__nav-tab" href="/__pyric/ui/rtdb"> RTDB </a><a class="studio__nav-tab" href="/__pyric/ui/storage"> Storage </a><a class="studio__nav-tab" href="/__pyric/ui/traffic"> Traffic </a><a class="studio__nav-tab" href="/__pyric/ui/settings"> Settings </a><a class="studio__nav-tab" href="/__pyric/ui/docs" aria-current="page"> Docs </a> </nav> </div> </header> <div class="docs-shell">  <details class="docs-nav-drawer"> <summary>Navigate</summary> <nav class="docs-nav" aria-label="Documentation"> <div class="docs-search" data-index-url="/__pyric/ui/docs/index.json"> <div class="docs-search-field"> <svg class="docs-search-icon" viewBox="0 0 16 16" width="14" height="14" aria-hidden="true"> <path d="M11.5 11.5 15 15M13 7A6 6 0 1 1 1 7a6 6 0 0 1 12 0Z" fill="none" stroke="currentColor" stroke-width="1.4" stroke-linecap="round"></path> </svg> <input type="text" class="docs-search-input" placeholder="Search docs" aria-label="Search docs" autocomplete="off" spellcheck="false"> <kbd class="docs-search-kbd">⌘K</kbd> </div> <ul class="docs-search-results" hidden></ul> </div> <script type="module">let i=null;function d(t){return i||(i=fetch(t).then(e=>e.json())),i}function l(t,e){return t.title.toLowerCase().includes(e)||t.excerpt.toLowerCase().includes(e)?!0:t.headings.some(r=>r.text.toLowerCase().includes(e))}function u(t,e,r){if(e.innerHTML="",t.length===0){e.hidden=!1;{const n=document.createElement("li");n.className="docs-search-empty",n.textContent="No matches",e.appendChild(n)}return}e.hidden=!1;for(const n of t.slice(0,8)){const s=document.createElement("li"),c=document.createElement("a");c.href=n.path;const o=document.createElement("span");o.className="docs-search-result-title",o.textContent=n.title;const a=document.createElement("span");a.className="docs-search-result-meta",a.textContent=[n.group,n.section].filter(Boolean).join(" / "),c.append(o,a),s.appendChild(c),e.appendChild(s)}}document.querySelectorAll(".docs-search").forEach(t=>{const e=t.dataset.indexUrl,r=t.querySelector(".docs-search-input"),n=t.querySelector(".docs-search-results");r.addEventListener("input",async()=>{const s=r.value.trim().toLowerCase();if(!s){n.hidden=!0,n.innerHTML="";return}const{pages:c}=await d(e);r.value.trim().toLowerCase()===s&&u(c.filter(o=>l(o,s)),n)}),r.addEventListener("focus",()=>{d(e),n.childElementCount>0&&(n.hidden=!1)}),r.addEventListener("keydown",s=>{s.key==="Escape"&&(r.value="",n.hidden=!0,n.innerHTML="",r.blur())}),r.addEventListener("blur",()=>{window.setTimeout(()=>{n.hidden=!0},150)})});document.addEventListener("keydown",t=>{if(!(t.metaKey||t.ctrlKey)||t.key.toLowerCase()!=="k")return;const e=[...document.querySelectorAll(".docs-search-input")].find(r=>r.offsetParent!==null);e&&(t.preventDefault(),e.focus(),e.select())});</script> <a class="docs-nav-toplink" href="/__pyric/ui/docs/overview/"> Overview </a><details class="docs-nav-group"> <summary>Run locally</summary> <div class="docs-nav-group-body"> <div class="docs-nav-section">  <ul> <li> <a href="/__pyric/ui/docs/start-building/"> Quickstart </a> </li><li> <a href="/__pyric/ui/docs/how-the-swap-works/"> How the swap works </a> </li><li> <a href="/__pyric/ui/docs/set-up-your-agent/"> Connect an agent </a> </li><li> <a href="/__pyric/ui/docs/test-in-node/"> Test in Node </a> </li> </ul> </div> </div> </details><details class="docs-nav-group"> <summary>Develop with Firebase APIs</summary> <div class="docs-nav-group-body"> <div class="docs-nav-section">  <ul> <li> <a href="/__pyric/ui/docs/sign-in-and-manage-users/"> Sign in and manage users </a> </li><li> <a href="/__pyric/ui/docs/store-and-query-data/"> Store and query data </a> </li><li> <a href="/__pyric/ui/docs/sync-realtime-data/"> Sync realtime data </a> </li><li> <a href="/__pyric/ui/docs/store-files/"> Store files </a> </li><li> <a href="/__pyric/ui/docs/receive-messages/"> Receive messages </a> </li><li> <a href="/__pyric/ui/docs/run-ai-logic-locally/"> Run AI Logic locally </a> </li><li> <a href="/__pyric/ui/docs/pyric-cli-how-to-run-rtdb-onvaluecreated/"> Run an RTDB function locally </a> </li><li> <a href="/__pyric/ui/docs/which-data-service/"> Which data service? </a> </li> </ul> </div> </div> </details><details class="docs-nav-group"> <summary>Inspect and correct</summary> <div class="docs-nav-group-body"> <div class="docs-nav-section"> <h2 class="docs-nav-heading"> Inspect the sandbox </h2> <ul> <li> <a href="/__pyric/ui/docs/see-whats-happening/"> Traffic &amp; rule verdicts </a> </li><li> <a href="/__pyric/ui/docs/read-a-denial/"> Read a denial and understand it </a> </li><li> <a href="/__pyric/ui/docs/shape-your-data/"> Seed, snapshot, replay </a> </li><li> <a href="/__pyric/ui/docs/watch-and-review/"> Review agent activity </a> </li> </ul> </div><div class="docs-nav-section"> <h2 class="docs-nav-heading"> Correct Security Rules </h2> <ul> <li> <a href="/__pyric/ui/docs/secure-it-with-rules/"> Security Rules </a> </li><li> <a href="/__pyric/ui/docs/simulate-and-lint/"> Simulate and lint before you deploy </a> </li><li> <a href="/__pyric/ui/docs/rules-patterns/"> Rules patterns </a> </li><li> <a href="/__pyric/ui/docs/rules-standard-library/"> The rules standard library </a> </li><li> <a href="/__pyric/ui/docs/rtdb-rules-in-typescript/"> RTDB rules in TypeScript </a> </li><li> <a href="/__pyric/ui/docs/firestore-rules-limits/"> Rules limits </a> </li><li> <a href="/__pyric/ui/docs/whats-possible/"> Case studies </a> </li> </ul> </div><div class="docs-nav-section"> <h2 class="docs-nav-heading"> Work with an agent </h2> <ul> <li> <a href="/__pyric/ui/docs/what-your-agent-can-do/"> Work through an agent </a> </li><li> <a href="/__pyric/ui/docs/skills/"> Agent skills </a> </li> </ul> </div> </div> </details><details class="docs-nav-group"> <summary>Verify the boundary</summary> <div class="docs-nav-group-body"> <div class="docs-nav-section">  <ul> <li> <a href="/__pyric/ui/docs/pyric-cli-how-to-verify-against-a-captured-session/"> Verify a captured session </a> </li><li> <a href="/__pyric/ui/docs/write-a-rules-test-suite/"> Write a rules test suite </a> </li><li> <a href="/__pyric/ui/docs/audit-your-rules/"> Audit rules and data </a> </li> </ul> </div> </div> </details><details class="docs-nav-group"> <summary>Ship unchanged</summary> <div class="docs-nav-group-body"> <div class="docs-nav-section">  <ul> <li> <a href="/__pyric/ui/docs/ship-to-production/"> Ship to production </a> </li><li> <a href="/__pyric/ui/docs/set-up-the-project/"> Set up the Firebase project </a> </li> </ul> </div> </div> </details><details class="docs-nav-group"> <summary>Conformance</summary> <div class="docs-nav-group-body"> <div class="docs-nav-section">  <ul> <li> <a href="/__pyric/ui/docs/how-we-know-it-matches-firebase/"> Conformance </a> </li><li> <a href="/__pyric/ui/docs/whats-experimental/"> What&#39;s experimental </a> </li><li> <a href="/__pyric/ui/docs/pyric-conformance-scores/"> Conformance scores </a> </li><li> <a href="/__pyric/ui/docs/pyric-app-compat/"> App </a> </li><li> <a href="/__pyric/ui/docs/pyric-firestore-compat/"> Firestore </a> </li><li> <a href="/__pyric/ui/docs/pyric-auth-compat/"> Auth </a> </li><li> <a href="/__pyric/ui/docs/pyric-database-compat/"> Realtime Database </a> </li><li> <a href="/__pyric/ui/docs/pyric-storage-compat/"> Storage </a> </li><li> <a href="/__pyric/ui/docs/pyric-rules-compat/"> Rules </a> </li><li> <a href="/__pyric/ui/docs/pyric-messaging-compat/"> Messaging </a> </li><li> <a href="/__pyric/ui/docs/pyric-ai-compat/"> AI Logic </a> </li><li> <a href="/__pyric/ui/docs/pyric-cli-functions-rtdb-compat/"> Functions · RTDB </a> </li> </ul> </div> </div> </details> <details class="docs-nav-group" open> <summary>Reference</summary> <div class="docs-nav-group-body"> <div class="docs-nav-section"> <ul> <li> <a href="/__pyric/ui/docs/pyric-cli/"> @pyric/cli </a> </li><li> <a href="/__pyric/ui/docs/pyric-explanation-versioning-and-compatibility/"> pyric </a> </li><li> <a href="/__pyric/ui/docs/pyric-firestore/"> pyric / firestore </a> </li><li> <a href="/__pyric/ui/docs/pyric-rules/"> pyric / rules </a> </li><li> <a href="/__pyric/ui/docs/pyric-sandbox/" aria-current="true"> pyric / sandbox </a> </li><li> <a href="/__pyric/ui/docs/pyric-storage/"> pyric / storage </a> </li><li> <a href="/__pyric/ui/docs/pyric-auth/"> pyric / auth </a> </li><li> <a href="/__pyric/ui/docs/pyric-database/"> pyric / database </a> </li><li> <a href="/__pyric/ui/docs/pyric-admin-app/"> pyric-admin / app </a> </li><li> <a href="/__pyric/ui/docs/pyric-admin-firestore/"> pyric-admin / firestore </a> </li><li> <a href="/__pyric/ui/docs/pyric-admin-auth/"> pyric-admin / auth </a> </li><li> <a href="/__pyric/ui/docs/pyric-admin-database/"> pyric-admin / database </a> </li><li> <a href="/__pyric/ui/docs/pyric-admin-storage/"> pyric-admin / storage </a> </li><li> <a href="/__pyric/ui/docs/ui/"> @pyric/ui </a> </li><li> <a href="/__pyric/ui/docs/api-reference/"> API reference </a> </li> </ul> </div> </div> </details> </nav> </details> <nav class="docs-nav" aria-label="Documentation"> <div class="docs-search" data-index-url="/__pyric/ui/docs/index.json"> <div class="docs-search-field"> <svg class="docs-search-icon" viewBox="0 0 16 16" width="14" height="14" aria-hidden="true"> <path d="M11.5 11.5 15 15M13 7A6 6 0 1 1 1 7a6 6 0 0 1 12 0Z" fill="none" stroke="currentColor" stroke-width="1.4" stroke-linecap="round"></path> </svg> <input type="text" class="docs-search-input" placeholder="Search docs" aria-label="Search docs" autocomplete="off" spellcheck="false"> <kbd class="docs-search-kbd">⌘K</kbd> </div> <ul class="docs-search-results" hidden></ul> </div>  <a class="docs-nav-toplink" href="/__pyric/ui/docs/overview/" id="nav-group-overview"> Overview </a><details class="docs-nav-group" id="nav-group-run-locally"> <summary>Run locally</summary> <div class="docs-nav-group-body"> <div class="docs-nav-section">  <ul> <li> <a href="/__pyric/ui/docs/start-building/"> Quickstart </a> </li><li> <a href="/__pyric/ui/docs/how-the-swap-works/"> How the swap works </a> </li><li> <a href="/__pyric/ui/docs/set-up-your-agent/"> Connect an agent </a> </li><li> <a href="/__pyric/ui/docs/test-in-node/"> Test in Node </a> </li> </ul> </div> </div> </details><details class="docs-nav-group" id="nav-group-develop-with-firebase-apis"> <summary>Develop with Firebase APIs</summary> <div class="docs-nav-group-body"> <div class="docs-nav-section">  <ul> <li> <a href="/__pyric/ui/docs/sign-in-and-manage-users/"> Sign in and manage users </a> </li><li> <a href="/__pyric/ui/docs/store-and-query-data/"> Store and query data </a> </li><li> <a href="/__pyric/ui/docs/sync-realtime-data/"> Sync realtime data </a> </li><li> <a href="/__pyric/ui/docs/store-files/"> Store files </a> </li><li> <a href="/__pyric/ui/docs/receive-messages/"> Receive messages </a> </li><li> <a href="/__pyric/ui/docs/run-ai-logic-locally/"> Run AI Logic locally </a> </li><li> <a href="/__pyric/ui/docs/pyric-cli-how-to-run-rtdb-onvaluecreated/"> Run an RTDB function locally </a> </li><li> <a href="/__pyric/ui/docs/which-data-service/"> Which data service? </a> </li> </ul> </div> </div> </details><details class="docs-nav-group" id="nav-group-inspect-and-correct"> <summary>Inspect and correct</summary> <div class="docs-nav-group-body"> <div class="docs-nav-section"> <h2 class="docs-nav-heading" id="nav-section-inspect-and-correct-inspect-the-sandbox"> Inspect the sandbox </h2> <ul> <li> <a href="/__pyric/ui/docs/see-whats-happening/"> Traffic &amp; rule verdicts </a> </li><li> <a href="/__pyric/ui/docs/read-a-denial/"> Read a denial and understand it </a> </li><li> <a href="/__pyric/ui/docs/shape-your-data/"> Seed, snapshot, replay </a> </li><li> <a href="/__pyric/ui/docs/watch-and-review/"> Review agent activity </a> </li> </ul> </div><div class="docs-nav-section"> <h2 class="docs-nav-heading" id="nav-section-inspect-and-correct-correct-security-rules"> Correct Security Rules </h2> <ul> <li> <a href="/__pyric/ui/docs/secure-it-with-rules/"> Security Rules </a> </li><li> <a href="/__pyric/ui/docs/simulate-and-lint/"> Simulate and lint before you deploy </a> </li><li> <a href="/__pyric/ui/docs/rules-patterns/"> Rules patterns </a> </li><li> <a href="/__pyric/ui/docs/rules-standard-library/"> The rules standard library </a> </li><li> <a href="/__pyric/ui/docs/rtdb-rules-in-typescript/"> RTDB rules in TypeScript </a> </li><li> <a href="/__pyric/ui/docs/firestore-rules-limits/"> Rules limits </a> </li><li> <a href="/__pyric/ui/docs/whats-possible/"> Case studies </a> </li> </ul> </div><div class="docs-nav-section"> <h2 class="docs-nav-heading" id="nav-section-inspect-and-correct-work-with-an-agent"> Work with an agent </h2> <ul> <li> <a href="/__pyric/ui/docs/what-your-agent-can-do/"> Work through an agent </a> </li><li> <a href="/__pyric/ui/docs/skills/"> Agent skills </a> </li> </ul> </div> </div> </details><details class="docs-nav-group" id="nav-group-verify-the-boundary"> <summary>Verify the boundary</summary> <div class="docs-nav-group-body"> <div class="docs-nav-section">  <ul> <li> <a href="/__pyric/ui/docs/pyric-cli-how-to-verify-against-a-captured-session/"> Verify a captured session </a> </li><li> <a href="/__pyric/ui/docs/write-a-rules-test-suite/"> Write a rules test suite </a> </li><li> <a href="/__pyric/ui/docs/audit-your-rules/"> Audit rules and data </a> </li> </ul> </div> </div> </details><details class="docs-nav-group" id="nav-group-ship-unchanged"> <summary>Ship unchanged</summary> <div class="docs-nav-group-body"> <div class="docs-nav-section">  <ul> <li> <a href="/__pyric/ui/docs/ship-to-production/"> Ship to production </a> </li><li> <a href="/__pyric/ui/docs/set-up-the-project/"> Set up the Firebase project </a> </li> </ul> </div> </div> </details><details class="docs-nav-group" id="nav-group-conformance"> <summary>Conformance</summary> <div class="docs-nav-group-body"> <div class="docs-nav-section">  <ul> <li> <a href="/__pyric/ui/docs/how-we-know-it-matches-firebase/"> Conformance </a> </li><li> <a href="/__pyric/ui/docs/whats-experimental/"> What&#39;s experimental </a> </li><li> <a href="/__pyric/ui/docs/pyric-conformance-scores/"> Conformance scores </a> </li><li> <a href="/__pyric/ui/docs/pyric-app-compat/"> App </a> </li><li> <a href="/__pyric/ui/docs/pyric-firestore-compat/"> Firestore </a> </li><li> <a href="/__pyric/ui/docs/pyric-auth-compat/"> Auth </a> </li><li> <a href="/__pyric/ui/docs/pyric-database-compat/"> Realtime Database </a> </li><li> <a href="/__pyric/ui/docs/pyric-storage-compat/"> Storage </a> </li><li> <a href="/__pyric/ui/docs/pyric-rules-compat/"> Rules </a> </li><li> <a href="/__pyric/ui/docs/pyric-messaging-compat/"> Messaging </a> </li><li> <a href="/__pyric/ui/docs/pyric-ai-compat/"> AI Logic </a> </li><li> <a href="/__pyric/ui/docs/pyric-cli-functions-rtdb-compat/"> Functions · RTDB </a> </li> </ul> </div> </div> </details> <details class="docs-nav-group" id="nav-group-reference" open> <summary>Reference</summary> <div class="docs-nav-group-body"> <div class="docs-nav-section"> <ul> <li> <a href="/__pyric/ui/docs/pyric-cli/"> @pyric/cli </a> </li><li> <a href="/__pyric/ui/docs/pyric-explanation-versioning-and-compatibility/"> pyric </a> </li><li> <a href="/__pyric/ui/docs/pyric-firestore/"> pyric / firestore </a> </li><li> <a href="/__pyric/ui/docs/pyric-rules/"> pyric / rules </a> </li><li> <a href="/__pyric/ui/docs/pyric-sandbox/" aria-current="true"> pyric / sandbox </a> </li><li> <a href="/__pyric/ui/docs/pyric-storage/"> pyric / storage </a> </li><li> <a href="/__pyric/ui/docs/pyric-auth/"> pyric / auth </a> </li><li> <a href="/__pyric/ui/docs/pyric-database/"> pyric / database </a> </li><li> <a href="/__pyric/ui/docs/pyric-admin-app/"> pyric-admin / app </a> </li><li> <a href="/__pyric/ui/docs/pyric-admin-firestore/"> pyric-admin / firestore </a> </li><li> <a href="/__pyric/ui/docs/pyric-admin-auth/"> pyric-admin / auth </a> </li><li> <a href="/__pyric/ui/docs/pyric-admin-database/"> pyric-admin / database </a> </li><li> <a href="/__pyric/ui/docs/pyric-admin-storage/"> pyric-admin / storage </a> </li><li> <a href="/__pyric/ui/docs/ui/"> @pyric/ui </a> </li><li> <a href="/__pyric/ui/docs/api-reference/"> API reference </a> </li> </ul> </div> </div> </details> </nav> <main class="doc-main"> <nav class="docs-breadcrumbs" aria-label="Breadcrumb"> <ol> <li>  <a href="/__pyric/ui/docs/pyric-sandbox/">pyric / sandbox</a> </li><li> <span class="docs-breadcrumbs-sep" aria-hidden="true">/</span> <span>Reference</span> </li><li> <span class="docs-breadcrumbs-sep" aria-hidden="true">/</span> <span aria-current="page">Snapshot and admin reads</span> </li> </ol> </nav>  <article class="prose">  <h1 id="sandboxsnapshot-and-admin-reads"><code>SandboxSnapshot</code> and admin reads</h1>
+<p>Two related surfaces. <code>SandboxSnapshot</code> is the shape returned by <code>Sandbox.snapshot()</code>. <code>SandboxAdmin</code> is the rule-bypass read surface exposed on <code>Sandbox.admin</code>.</p>
+<h2 id="sandboxsnapshot"><code>SandboxSnapshot</code></h2>
+<pre class="astro-code one-dark-pro" style="background-color:#282c34;color:#abb2bf; overflow-x: auto;" tabindex="0" data-language="ts"><code><span class="line"><span style="color:#C678DD">interface</span><span style="color:#E5C07B"> SandboxSnapshot</span><span style="color:#ABB2BF"> {</span></span>
+<span class="line"><span style="color:#E06C75">  firestore</span><span style="color:#C678DD">?</span><span style="color:#ABB2BF">: </span><span style="color:#E5C07B">Record</span><span style="color:#ABB2BF">&#x3C;</span><span style="color:#E5C07B">string</span><span style="color:#ABB2BF">, </span><span style="color:#E5C07B">unknown</span><span style="color:#ABB2BF">>;</span></span>
+<span class="line"><span style="color:#ABB2BF">  [</span><span style="color:#E06C75;font-style:italic">service</span><span style="color:#ABB2BF">: </span><span style="color:#E5C07B">string</span><span style="color:#ABB2BF">]: </span><span style="color:#E5C07B">unknown</span><span style="color:#ABB2BF">;</span></span>
+<span class="line"><span style="color:#ABB2BF">}</span></span></code></pre>
+<p>Coarse capture of every service’s state, keyed by service name. In v1 only <code>firestore</code> is populated; future services (<code>auth</code>, <code>database</code>, <code>storage</code>) will add their own keys.</p>
+<p>The <code>firestore</code> value is a flat map of document path → document data:</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"> snap</span><span style="color:#56B6C2"> =</span><span style="color:#E5C07B"> sandbox</span><span style="color:#ABB2BF">.</span><span style="color:#61AFEF">snapshot</span><span style="color:#ABB2BF">();</span></span>
+<span class="line"><span style="color:#E5C07B">console</span><span style="color:#ABB2BF">.</span><span style="color:#61AFEF">log</span><span style="color:#ABB2BF">(</span><span style="color:#E5C07B">snap</span><span style="color:#ABB2BF">.</span><span style="color:#E06C75">firestore</span><span style="color:#ABB2BF">);</span></span>
+<span class="line"><span style="color:#7F848E;font-style:italic">// {</span></span>
+<span class="line"><span style="color:#7F848E;font-style:italic">//   'users/alice': { name: 'Alice' },</span></span>
+<span class="line"><span style="color:#7F848E;font-style:italic">//   'users/bob':   { name: 'Bob' },</span></span>
+<span class="line"><span style="color:#7F848E;font-style:italic">//   'notes/n1':    { owner: 'alice', title: 'hello' },</span></span>
+<span class="line"><span style="color:#7F848E;font-style:italic">// }</span></span></code></pre>
+<p>Use this for:</p>
+<ul>
+<li><strong>Round-tripping</strong>: capture snapshot before a destructive test, restore after.</li>
+<li><strong>Diagnostic dumps</strong>: log the full state when a test fails.</li>
+<li><strong>Cross-checks</strong>: assert against the whole state, not individual docs.</li>
+</ul>
+<p>The snapshot is a structural clone of the state at call time. Mutating the returned object does not affect the sandbox.</p>
+<h2 id="sandboxadmin"><code>SandboxAdmin</code></h2>
+<pre class="astro-code one-dark-pro" style="background-color:#282c34;color:#abb2bf; overflow-x: auto;" tabindex="0" data-language="ts"><code><span class="line"><span style="color:#C678DD">interface</span><span style="color:#E5C07B"> SandboxAdmin</span><span style="color:#ABB2BF"> {</span></span>
+<span class="line"><span style="color:#61AFEF">  getDocument</span><span style="color:#ABB2BF">(</span><span style="color:#E06C75;font-style:italic">path</span><span style="color:#ABB2BF">: </span><span style="color:#E5C07B">string</span><span style="color:#ABB2BF">): </span><span style="color:#E5C07B">unknown</span><span style="color:#ABB2BF"> | </span><span style="color:#E5C07B">null</span><span style="color:#ABB2BF">;</span></span>
+<span class="line"><span style="color:#61AFEF">  listDocuments</span><span style="color:#ABB2BF">(</span><span style="color:#E06C75;font-style:italic">prefix</span><span style="color:#ABB2BF">: </span><span style="color:#E5C07B">string</span><span style="color:#ABB2BF">):</span></span>
+<span class="line"><span style="color:#ABB2BF">    { </span><span style="color:#E06C75">path</span><span style="color:#ABB2BF">: </span><span style="color:#E06C75">string</span><span style="color:#ABB2BF">; </span><span style="color:#E06C75">data</span><span style="color:#ABB2BF">: </span><span style="color:#E06C75">unknown</span><span style="color:#ABB2BF">; </span><span style="color:#E06C75">phantom</span><span style="color:#C678DD">?:</span><span style="color:#D19A66"> true</span><span style="color:#ABB2BF"> }[];</span></span>
+<span class="line"><span style="color:#ABB2BF">}</span></span></code></pre>
+<p>Available on <code>sandbox.admin</code>. Identity-agnostic: admin reads aren’t gated on auth, so they live on the sandbox (not on a context).</p>
+<h3 id="getdocumentpath"><code>getDocument(path)</code></h3>
+<p>Read a single Firestore document by full path, ignoring rules. Returns <code>null</code> if the document doesn’t exist.</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"> doc</span><span style="color:#56B6C2"> =</span><span style="color:#E5C07B"> sandbox</span><span style="color:#ABB2BF">.</span><span style="color:#E5C07B">admin</span><span style="color:#ABB2BF">.</span><span style="color:#61AFEF">getDocument</span><span style="color:#ABB2BF">(</span><span style="color:#98C379">'users/alice'</span><span style="color:#ABB2BF">);</span></span>
+<span class="line"><span style="color:#7F848E;font-style:italic">// doc is { name: 'Alice', ... } or null</span></span></code></pre>
+<p>Use this in tests to assert “did the write actually land?” without needing a separate admin context.</p>
+<h3 id="listdocumentsprefix"><code>listDocuments(prefix)</code></h3>
+<p>List Firestore documents under a collection path, ignoring rules.</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"> docs</span><span style="color:#56B6C2"> =</span><span style="color:#E5C07B"> sandbox</span><span style="color:#ABB2BF">.</span><span style="color:#E5C07B">admin</span><span style="color:#ABB2BF">.</span><span style="color:#61AFEF">listDocuments</span><span style="color:#ABB2BF">(</span><span style="color:#98C379">'users'</span><span style="color:#ABB2BF">);</span></span>
+<span class="line"><span style="color:#7F848E;font-style:italic">// [</span></span>
+<span class="line"><span style="color:#7F848E;font-style:italic">//   { path: 'users/alice', data: { name: 'Alice' } },</span></span>
+<span class="line"><span style="color:#7F848E;font-style:italic">//   { path: 'users/bob',   data: { name: 'Bob' } },</span></span>
+<span class="line"><span style="color:#7F848E;font-style:italic">// ]</span></span></code></pre>
+<h3 id="phantom-documents">Phantom documents</h3>
+<p><code>listDocuments</code> includes <strong>phantom</strong> records: synthesised parent docs that have descendants but no stored data of their own. These match what a live Firestore listing would expose for nested collections:</p>
+<pre class="astro-code one-dark-pro" style="background-color:#282c34;color:#abb2bf; overflow-x: auto;" tabindex="0" data-language="ts"><code><span class="line"><span style="color:#7F848E;font-style:italic">// Wrote 'rooms/alpha/messages/m1' directly. Now list rooms:</span></span>
+<span class="line"><span style="color:#C678DD">const</span><span style="color:#E5C07B"> rooms</span><span style="color:#56B6C2"> =</span><span style="color:#E5C07B"> sandbox</span><span style="color:#ABB2BF">.</span><span style="color:#E5C07B">admin</span><span style="color:#ABB2BF">.</span><span style="color:#61AFEF">listDocuments</span><span style="color:#ABB2BF">(</span><span style="color:#98C379">'rooms'</span><span style="color:#ABB2BF">);</span></span>
+<span class="line"><span style="color:#7F848E;font-style:italic">// [</span></span>
+<span class="line"><span style="color:#7F848E;font-style:italic">//   { path: 'rooms/alpha', data: {}, phantom: true },</span></span>
+<span class="line"><span style="color:#7F848E;font-style:italic">// ]</span></span></code></pre>
+<p>The <code>phantom: true</code> flag lets test code distinguish “this doc was explicitly written and is empty” from “this doc exists only because something underneath it was written”. The discover crawler in <code>pyric/rules</code> uses this signal to walk structure without confusing the two cases.</p>
+<h2 id="why-this-surface-is-on-the-root-sandbox">Why this surface is on the root sandbox</h2>
+<p>Both <code>snapshot()</code> and <code>admin</code> are presented on <code>Sandbox</code>, not <code>SandboxContext</code>. The reason is conceptual rather than mechanical: a context exists to carry identity, and admin reads are explicitly identity-agnostic. Putting them on contexts would invite confused calls like <code>aliceCtx.admin.getDocument(...)</code> which read like “alice’s admin view”. Admin reads are not anyone’s view. They’re a backdoor for tests.</p>
+<p>When other services land (Auth, Storage, Realtime Database), the admin surface namespaces by service: <code>admin.firestore.getDocument</code>, <code>admin.storage.getObject</code>. The flat shape in v1 is preserved during that transition so existing call sites don’t break.</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="#sandboxsnapshot">SandboxSnapshot</a> </li><li data-depth="2"> <a href="#sandboxadmin">SandboxAdmin</a> </li><li data-depth="3"> <a href="#getdocumentpath">getDocument(path)</a> </li><li data-depth="3"> <a href="#listdocumentsprefix">listDocuments(prefix)</a> </li><li data-depth="3"> <a href="#phantom-documents">Phantom documents</a> </li><li data-depth="2"> <a href="#why-this-surface-is-on-the-root-sandbox">Why this surface is on the root sandbox</a> </li> </ul> </aside> </div> <script type="module">const a=document.querySelector("[data-api-symbol-filter]"),d=[...document.querySelectorAll("[data-api-symbol-group]")],n=document.querySelector("[data-api-symbol-empty]");a?.addEventListener("input",()=>{const t=a.value.trim().toLowerCase();let o=0;for(const i of d){let e=0;i.querySelectorAll("[data-api-symbol]").forEach(l=>{const r=!t||(l.dataset.apiSymbol??"").includes(t);l.hidden=!r,r&&e++}),i.hidden=e===0,o+=e}n&&(n.hidden=o>0)});</script> <script type="module">const s=new Map;document.querySelectorAll('.doc-toc a[href^="#"]').forEach(t=>s.set(decodeURIComponent(t.hash.slice(1)),t));if(s.size>0){const t=new Set,n=()=>{let o=null;for(const e of s.keys())if(t.has(e)){o=e;break}s.forEach((e,c)=>e.classList.toggle("active",c===o))},r=new IntersectionObserver(o=>{for(const e of o)e.isIntersecting?t.add(e.target.id):t.delete(e.target.id);n()},{rootMargin:"-72px 0px -60% 0px"});s.forEach((o,e)=>{const c=document.getElementById(e);c&&r.observe(c)})}</script> <script type="module">document.querySelector('.studio__nav [aria-current="page"]')?.scrollIntoView({block:"nearest",inline:"center"});</script> </body> </html>

package/dist/serve/docs-ui/docs/pyric-sandbox-reference-snapshot-and-admin.md

@@ -0,0 +1,89 @@
+# `SandboxSnapshot` and admin reads
+
+Two related surfaces. `SandboxSnapshot` is the shape returned by `Sandbox.snapshot()`. `SandboxAdmin` is the rule-bypass read surface exposed on `Sandbox.admin`.
+
+## `SandboxSnapshot`
+
+```ts
+interface SandboxSnapshot {
+  firestore?: Record<string, unknown>;
+  [service: string]: unknown;
+}
+```
+
+Coarse capture of every service's state, keyed by service name. In v1 only `firestore` is populated; future services (`auth`, `database`, `storage`) will add their own keys.
+
+The `firestore` value is a flat map of document path → document data:
+
+```ts
+const snap = sandbox.snapshot();
+console.log(snap.firestore);
+// {
+//   'users/alice': { name: 'Alice' },
+//   'users/bob':   { name: 'Bob' },
+//   'notes/n1':    { owner: 'alice', title: 'hello' },
+// }
+```
+
+Use this for:
+
+- **Round-tripping**: capture snapshot before a destructive test, restore after.
+- **Diagnostic dumps**: log the full state when a test fails.
+- **Cross-checks**: assert against the whole state, not individual docs.
+
+The snapshot is a structural clone of the state at call time. Mutating the returned object does not affect the sandbox.
+
+## `SandboxAdmin`
+
+```ts
+interface SandboxAdmin {
+  getDocument(path: string): unknown | null;
+  listDocuments(prefix: string):
+    { path: string; data: unknown; phantom?: true }[];
+}
+```
+
+Available on `sandbox.admin`. Identity-agnostic: admin reads aren't gated on auth, so they live on the sandbox (not on a context).
+
+### `getDocument(path)`
+
+Read a single Firestore document by full path, ignoring rules. Returns `null` if the document doesn't exist.
+
+```ts
+const doc = sandbox.admin.getDocument('users/alice');
+// doc is { name: 'Alice', ... } or null
+```
+
+Use this in tests to assert "did the write actually land?" without needing a separate admin context.
+
+### `listDocuments(prefix)`
+
+List Firestore documents under a collection path, ignoring rules.
+
+```ts
+const docs = sandbox.admin.listDocuments('users');
+// [
+//   { path: 'users/alice', data: { name: 'Alice' } },
+//   { path: 'users/bob',   data: { name: 'Bob' } },
+// ]
+```
+
+### Phantom documents
+
+`listDocuments` includes **phantom** records: synthesised parent docs that have descendants but no stored data of their own. These match what a live Firestore listing would expose for nested collections:
+
+```ts
+// Wrote 'rooms/alpha/messages/m1' directly. Now list rooms:
+const rooms = sandbox.admin.listDocuments('rooms');
+// [
+//   { path: 'rooms/alpha', data: {}, phantom: true },
+// ]
+```
+
+The `phantom: true` flag lets test code distinguish "this doc was explicitly written and is empty" from "this doc exists only because something underneath it was written". The discover crawler in `pyric/rules` uses this signal to walk structure without confusing the two cases.
+
+## Why this surface is on the root sandbox
+
+Both `snapshot()` and `admin` are presented on `Sandbox`, not `SandboxContext`. The reason is conceptual rather than mechanical: a context exists to carry identity, and admin reads are explicitly identity-agnostic. Putting them on contexts would invite confused calls like `aliceCtx.admin.getDocument(...)` which read like "alice's admin view". Admin reads are not anyone's view. They're a backdoor for tests.
+
+When other services land (Auth, Storage, Realtime Database), the admin surface namespaces by service: `admin.firestore.getDocument`, `admin.storage.getObject`. The flat shape in v1 is preserved during that transition so existing call sites don't break.