@pyric/cli 0.1.0-alpha.20 → 0.1.0-alpha.22

package/dist/serve/site-ui/_astro/writes.BsPBG3dp.js

@@ -0,0 +1,653 @@
+import{P as st,c as it,Q as oe,U as J,V as at,W as T,X as ot,Y as f,_ as ut,$ as ct,a0 as dt,a1 as H,a2 as S,a3 as lt,a4 as ht,v as ue,a5 as q,a6 as Fe,a7 as ft,a8 as mt,B as Ae,M as p,K as O,T as ye,y as pt,a9 as yt,aa as gt,ab as bt,C as ce,ac as wt,ad as vt,ae as xt,af as St,ag as Ct,S as kt,ah as qt}from"./sandbox-controls.rOuZTOUG.js";const Et={atomic:`// @pyric-services cloud.firestore
+// Atomic module — cross-document integrity for BATCH writes, via the
+// get()/getAfter() pair. Firestore evaluates every write in a batch
+// against rules, and getAfter() returns another document's POST-BATCH
+// state — so a rule can require "this write is only valid if a
+// companion write happened in the same atomic batch".
+//
+// All semantics live-verified against a production database: companion
+// visibility, solo-write denial, wrong-delta denial, single-use consumption
+// incl. replay denial, and out-of-batch getAfter() falling back to current
+// state.
+//
+// Explicit-param design: pass BOTH states of the companion doc —
+// \`get(path).data\` (pre-batch) and \`getAfter(path).data\` (post-batch).
+//
+//   import { companionChangedBy, consumedFlag } from 'atomic';
+//
+//   // Denormalized counter: creating a task REQUIRES the team's
+//   // taskCount to have been incremented in the same batch:
+//   match /teams/{teamId}/tasks/{taskId} {
+//     function teamBefore() {
+//       return get(/databases/$(database)/documents/teams/$(teamId)).data;
+//     }
+//     function teamAfter() {
+//       return getAfter(/databases/$(database)/documents/teams/$(teamId)).data;
+//     }
+//     allow create: if companionChangedBy(teamBefore(), teamAfter(), 'taskCount', 1);
+//   }
+//
+//   // Single-use invite: the join is valid only when the invite was
+//   // consumed (false -> true) IN THIS BATCH — replays deny because
+//   // the pre-batch state is already true:
+//   allow update: if consumedFlag(inviteBefore(), inviteAfter(), 'used');
+//
+// NOTE (simulator): in-batch companion semantics cannot be expressed
+// in the simulator or the Rules Test API mock surface — the simulator
+// treats cross-doc getAfter() as get(). These function BODIES are
+// simulator-tested with explicit values; the getAfter() WIRING is the
+// live v1 scope's job. Companion writes need their own allow rules too —
+// every write in a batch is evaluated.
+
+// The companion doc's field changed by EXACTLY n in this batch.
+// before/after are the SAME doc's get()/getAfter() data.
+export function companionChangedBy(before, after, field, n) {
+  return after[field] == before[field] + n;
+}
+
+// A single-use flag was consumed IN THIS BATCH: pre-batch false,
+// post-batch true. Replays deny (pre-batch is already true), and a
+// solo write denies (getAfter == get, so false != true).
+export function consumedFlag(before, after, flagField) {
+  return before[flagField] == false && after[flagField] == true;
+}
+`,auth:`// @pyric-services cloud.firestore,firebase.storage
+// @pyric-evidence storage-rules#125,firestore-rules#189
+export function isAuthenticated() {
+  return request.auth != null;
+}
+
+export function isOwner(userId) {
+  return isAuthenticated() && request.auth.uid == userId;
+}
+`,content:`// @pyric-services cloud.firestore
+// Content module for author-owned documents — the most common
+// Firebase app shape (posts, notes, docs, comments, tasks).
+//
+// Convention: documents carry an author field (a UID string) and
+// usually a status field ('draft' | 'published' | ...). Field names
+// are parameters, not conventions — pass yours.
+//
+// Usage:
+//   import { validAuthorCreate, isAuthor, canReadContent, notDeleted } from 'content';
+//   import { onlyFieldsChanged } from 'lifecycle';
+//
+//   match /posts/{postId} {
+//     // Create: author is the signed-in user.
+//     allow create: if validAuthorCreate('author');
+//     // Read: published to everyone, drafts to the author only.
+//     allow read: if canReadContent('status', 'author') && notDeleted();
+//     // Update: author edits content fields; authorship immutable.
+//     allow update: if isAuthor('author') && onlyFieldsChanged(['title', 'body', 'status']);
+//     allow delete: if isAuthor('author');
+//   }
+
+// Create guard: signed in, and the incoming doc's author field is the
+// caller. Use on \`create\` (reads request.resource).
+export function validAuthorCreate(authorField) {
+  return request.auth != null
+    && request.resource.data[authorField] == request.auth.uid;
+}
+
+// The caller is the EXISTING document's author. Use on update/delete
+// (reads resource).
+export function isAuthor(authorField) {
+  return request.auth != null
+    && resource.data[authorField] == request.auth.uid;
+}
+
+// Read visibility: published content is public; anything else is
+// visible to its author only. Works for get; for list queries the
+// client must filter (rules are not filters — a bare collection query
+// will be denied unless it proves status == 'published').
+export function canReadContent(statusField, authorField) {
+  return resource.data[statusField] == 'published'
+    || (request.auth != null && resource.data[authorField] == request.auth.uid);
+}
+
+// Soft-delete guard: the document is not marked deleted. Reads the
+// EXISTING doc; a doc without the field passes — bracket access is
+// the null-on-miss idiom (dotted access of a missing key ERRORS).
+export function notDeleted() {
+  return resource.data['deleted'] != true;
+}
+`,counters:`// @pyric-services cloud.firestore
+// Counters module for denormalized numeric integrity.
+//
+// The recurring shape: a client-maintained count (likes, votes, moves,
+// quantities) that rules must keep honest — it may only change by a
+// known step, or stay within known bounds. Generalizes the
+// state-module's moveIncremented() (hardcoded to moveCount) to any
+// field.
+//
+// Usage:
+//   import { incrementedBy, changedBy, boundedNumber } from 'counters';
+//
+//   // A like toggle: likeCount moves by exactly ±1:
+//   allow update: if changedBy('likeCount', -1, 1);
+//
+//   // A move counter: strictly +1 per move:
+//   allow update: if incrementedBy('moveCount', 1);
+//
+//   // A rating: any write keeps it in [1, 5]:
+//   allow write: if boundedNumber('rating', 1, 5);
+
+// The field changed by EXACTLY n relative to the existing document.
+// n may be negative (decrement). Update rules only (needs resource).
+export function incrementedBy(field, n) {
+  return request.resource.data[field] == resource.data[field] + n;
+}
+
+// The field's delta is within [min, max] (inclusive) — and it is NOT
+// required to change (delta 0 passes when min <= 0 <= max).
+export function changedBy(field, min, max) {
+  return request.resource.data[field] - resource.data[field] >= min
+    && request.resource.data[field] - resource.data[field] <= max;
+}
+
+// The incoming value is a number within [min, max] (inclusive).
+// Works on create and update. Missing field reads null (dynamic
+// access) and fails the type check rather than erroring.
+export function boundedNumber(field, min, max) {
+  return (request.resource.data[field] is int || request.resource.data[field] is float)
+    && request.resource.data[field] >= min
+    && request.resource.data[field] <= max;
+}
+`,geometry:`// @pyric-services cloud.firestore
+// Geometry module for movement game validation via config document lookup.
+//
+// Caller must pass the config document data as an explicit parameter.
+// The config doc is read via get() and cached per request — define a
+// config() function in your rules and pass its result to these functions.
+//
+// Config doc schema:
+//   moves[pieceType][fromCell][toCell] = true
+//   jumps[pieceType][fromCell][toCell] = capturedCellName
+//
+// Usage:
+//   import { validSimpleMove, validJumpMove } from 'geometry';
+//
+//   function config() {
+//     return get(/databases/$(database)/documents/gameConfig/checkers).data;
+//   }
+//
+//   allow update: if validSimpleMove(config())
+//     && piecePlaced() && moveIntegrity();
+//
+//   allow update: if validJumpMove(config())
+//     && captureValid() && captureDecrement() && moveIntegrity();
+
+// Validate a simple (non-capture) move via config document lookup.
+// Uses 3-level dynamic nesting: cfg.moves[piece][from][to].
+// piece comes from resource.data (pre-write board) so client can't fake it.
+export function validSimpleMove(cfg) {
+  let mf = request.resource.data.moveFrom;
+  let mt = request.resource.data.moveTo;
+  let piece = resource.data[mf];
+  return cfg.moves[piece][mf][mt] == true;
+}
+
+// Validate a jump (capture) move via config document lookup.
+// cfg.jumps[piece][from][to] returns the expected captured cell name.
+// Caller must separately verify the captured piece is an opponent piece.
+export function validJumpMove(cfg) {
+  let mf = request.resource.data.moveFrom;
+  let mt = request.resource.data.moveTo;
+  let cap = request.resource.data.captured;
+  let piece = resource.data[mf];
+  return cfg.jumps[piece][mf][mt] == cap;
+}
+`,joining:`// @pyric-services cloud.firestore
+// Joining module — how membership CHANGES, safely. The connective
+// tissue between content/spaces: spaces gates children behind a
+// members field; joining lets users enter and leave that field
+// WITHOUT an admin backend, with no privilege escalation.
+//
+// Convention: a MAP-shaped members field (uid -> role) on the parent
+// doc. Compose with lifecycle's onlyFieldsChanged so a join/leave
+// write can't touch anything else:
+//
+//   import { onlyAddedSelf, onlyRemovedSelf } from 'joining';
+//   import { onlyFieldsChanged } from 'lifecycle';
+//   import { isSpaceMember, hasSpaceRole } from 'spaces';
+//
+//   match /teams/{teamId} {
+//     allow read: if isSpaceMember(resource.data);
+//
+//     // Open self-service join (public team) at a fixed role, and
+//     // self-service leave — nothing else about the doc may change:
+//     allow update: if onlyFieldsChanged(['members'])
+//       && (onlyAddedSelf('members', 'editor') || onlyRemovedSelf('members'));
+//     // Admins manage the doc freely:
+//     allow update: if hasSpaceRole(resource.data, 'admin');
+//   }
+//
+// Every guarantee here is production-verified against the live Rules Test API:
+// the field-level map diff is reliable; the empty no-op diff DENIES (set
+// equality, not hasOnly — hasOnly on an empty set passes); role escalation via
+// CHANGING an existing entry denies; adding or removing anyone else denies.
+
+// The write adds EXACTLY the caller to the members map, at EXACTLY
+// \`role\`, changing and removing nobody. Update rules only.
+export function onlyAddedSelf(membersField, role) {
+  let diff = request.resource.data[membersField].diff(resource.data[membersField]);
+  return request.auth != null
+    && diff.addedKeys() == [request.auth.uid].toSet()
+    && diff.changedKeys().size() == 0
+    && diff.removedKeys().size() == 0
+    && request.resource.data[membersField][request.auth.uid] == role;
+}
+
+// The write removes EXACTLY the caller from the members map, adding
+// and changing nobody. Self-service leave. Update rules only.
+export function onlyRemovedSelf(membersField) {
+  let diff = request.resource.data[membersField].diff(resource.data[membersField]);
+  return request.auth != null
+    && diff.removedKeys() == [request.auth.uid].toSet()
+    && diff.addedKeys().size() == 0
+    && diff.changedKeys().size() == 0;
+}
+`,lifecycle:`// @pyric-services cloud.firestore
+// Lifecycle module for field immutability and timestamp enforcement.
+//
+// Common pattern: certain fields must never change after document creation
+// (createdBy, createdAt, authorId).
+//
+// Usage:
+//   import { fieldUnchanged, immutableFields, isServerTimestamp } from 'lifecycle';
+//
+//   // Single field:
+//   allow update: if fieldUnchanged('createdBy');
+//
+//   // Multiple fields (replaces chained fieldUnchanged calls):
+//   allow update: if immutableFields(['createdBy', 'createdAt', 'authorId']);
+//
+//   // The dual: users may edit title/body but NOTHING else:
+//   allow update: if onlyFieldsChanged(['title', 'body']);
+//
+//   allow create: if isServerTimestamp('createdAt');
+
+// Ensure a field's value is identical between existing and incoming document.
+// Use on update rules to enforce immutability.
+export function fieldUnchanged(field) {
+  return resource.data[field] == request.resource.data[field];
+}
+
+// Ensure multiple fields are unchanged between existing and incoming document.
+// Uses MapDiff — one expression instead of N chained fieldUnchanged() calls.
+export function immutableFields(fields) {
+  return request.resource.data.diff(resource.data).unchangedKeys().hasAll(fields);
+}
+
+// Ensure a field is set to the server timestamp.
+// Use on create or update rules to enforce server-side time.
+export function isServerTimestamp(field) {
+  return request.resource.data[field] == request.time;
+}
+
+// The dual of immutableFields: every changed field is in the allowed
+// list (fields NOT listed are implicitly immutable). Top-level keys
+// only — nested-map diffs are unreliable in production; flatten the
+// schema instead of reaching for a nested diff.
+export function onlyFieldsChanged(fields) {
+  return request.resource.data.diff(resource.data).affectedKeys().hasOnly(fields);
+}
+
+// Exactly n top-level fields changed in this write. n == 1 is the
+// board-integrity / edit-one-field-per-write guard (Pattern 5,
+// generalized beyond games).
+export function nFieldsChanged(n) {
+  return request.resource.data.diff(resource.data).affectedKeys().size() == n;
+}
+`,lobby:`// @pyric-services cloud.firestore
+// Lobby module for 2-participant coordination.
+//
+// Convention: documents must have these fields:
+//   host: string (creator's UID)
+//   guest: string ('' when waiting, joiner's UID when joined)
+//   status: 'waiting' | 'playing' | 'ready' (or any active state)
+//
+// Usage:
+//   import { validCreate, validJoin, canCancel } from 'lobby';
+//
+//   allow create: if validCreate();
+//   allow update: if validJoin();
+//   allow delete: if canCancel();
+
+// Is this a waiting lobby with an open seat?
+function isWaiting() {
+  return resource.data.status == 'waiting'
+    && resource.data.guest == '';
+}
+
+// Create: caller is host, seat empty, status waiting
+export function validCreate() {
+  return request.auth != null
+    && request.resource.data.host == request.auth.uid
+    && request.resource.data.guest == ''
+    && request.resource.data.status == 'waiting';
+}
+
+// Join: fill empty seat, transition to next status, no self-join
+export function validJoin() {
+  return request.auth != null
+    && isWaiting()
+    && request.resource.data.guest == request.auth.uid
+    && request.auth.uid != resource.data.host
+    && request.resource.data.status == 'playing'
+    && request.resource.data.host == resource.data.host;
+}
+
+// Cancel: only host, only while waiting
+export function canCancel() {
+  return request.auth != null
+    && resource.data.status == 'waiting'
+    && request.auth.uid == resource.data.host;
+}
+`,membership:`// @pyric-services cloud.firestore,firebase.storage
+// @pyric-evidence storage-rules#125,firestore-rules#189
+// Membership module for role-based and claims-based access control.
+//
+// Two access patterns:
+//   1. Custom claims on auth token (0 get() calls, set server-side)
+//   2. Member maps on documents (0 get() calls on the doc itself)
+//
+// Usage:
+//   import { hasClaim, hasClaimRole, isMemberOf, hasRole } from 'membership';
+//
+//   // Workspace access via custom claims
+//   allow read: if hasClaim('workspace_id');
+//   allow write: if hasClaimRole('workspace_role', 'admin');
+//
+//   // Project access via member map on document
+//   allow read: if isMemberOf(resource.data.members);
+//   allow update: if hasRole(resource.data.members, 'admin');
+
+// Check if the auth token has a non-null value for a claim key.
+export function hasClaim(claim) {
+  return request.auth != null
+    && request.auth.token[claim] != null;
+}
+
+// Check if the auth token has a specific value for a claim key.
+export function hasClaimRole(claim, role) {
+  return request.auth != null
+    && request.auth.token[claim] == role;
+}
+
+// Check if the caller's UID exists as a key in a members map.
+export function isMemberOf(membersMap) {
+  return request.auth != null
+    && request.auth.uid in membersMap;
+}
+
+// Check if the caller has a specific role in a members map.
+export function hasRole(membersMap, role) {
+  return request.auth != null
+    && membersMap[request.auth.uid] == role;
+}
+`,spaces:`// @pyric-services cloud.firestore
+// Spaces module — cross-document membership gating for shared spaces
+// (teams, rooms, groups, projects, parties). The second-most-common
+// app shape after author-owned content: a PARENT document defines who
+// may touch its children.
+//
+// Explicit-param design (like geometry): the caller reads the parent
+// doc ONCE via a helper and passes its data in. Define the helper in
+// your rules — get() is cached per request, so every function below
+// can share one read (of the 10-get budget):
+//
+//   import { isSpaceMember, hasSpaceRole, validMemberCreate } from 'spaces';
+//
+//   match /spaces/{spaceId}/tasks/{taskId} {
+//     function space() {
+//       return get(/databases/$(database)/documents/spaces/$(spaceId)).data;
+//     }
+//     allow read: if isSpaceMember(space());
+//     allow create: if validMemberCreate(space(), 'author');
+//     allow delete: if hasSpaceRole(space(), 'admin');
+//   }
+//
+// Members field shapes verified against the production engine:
+//   list: members: ['uidA', 'uidB']            → isSpaceMember only
+//   map:  members: { uidA: 'admin', ... }      → isSpaceMember + hasSpaceRole
+// A missing members field, a non-member uid, or a missing parent doc
+// (get() of a missing doc errors) all fail CLOSED.
+
+// The caller is in the space's members field. \`in\` covers both
+// shapes: list membership and map keys.
+export function isSpaceMember(spaceData) {
+  return request.auth != null && request.auth.uid in spaceData.members;
+}
+
+// The caller's role in a MAP-shaped members field equals \`role\`.
+// List-shaped members carry no roles — this denies on them.
+export function hasSpaceRole(spaceData, role) {
+  return request.auth != null && spaceData.members[request.auth.uid] == role;
+}
+
+// Member-gated authored create: the caller is a member AND the
+// incoming child doc's author field is the caller. The "post a
+// message / add a task" guard.
+export function validMemberCreate(spaceData, authorField) {
+  return isSpaceMember(spaceData)
+    && request.resource.data[authorField] == request.auth.uid;
+}
+`,state:`// @pyric-services cloud.firestore
+// Game state machine helpers.
+//
+// Convention: documents must have these fields:
+//   status: 'waiting' | 'playing' | 'won' | 'draw'
+//   moveCount: number
+//   host: string (UID)
+//   guest: string (UID)
+//
+// Usage:
+//   import { isPlaying, moveIncremented, participantsUnchanged } from 'state';
+//
+//   allow update: if isPlaying() && moveIncremented() && participantsUnchanged();
+
+// Is the game actively in play?
+export function isPlaying() {
+  return resource.data.status == 'playing';
+}
+
+// Did moveCount increment by exactly 1?
+export function moveIncremented() {
+  return request.resource.data.moveCount == resource.data.moveCount + 1;
+}
+
+// Are host and guest unchanged? (prevents mid-game identity swap)
+export function participantsUnchanged() {
+  return request.resource.data.host == resource.data.host
+      && request.resource.data.guest == resource.data.guest;
+}
+`,"storage/metadata":`// @pyric-services firebase.storage
+// @pyric-evidence storage-rules#132
+// Storage custom-metadata policies. Custom metadata is a flat string map.
+
+export function hasRequiredMetadata(keys) {
+  return request.resource.metadata.keys().hasAll(keys);
+}
+
+export function metadataString(key, min, max) {
+  return request.resource.metadata[key] is string
+    && request.resource.metadata[key].size() >= min
+    && request.resource.metadata[key].size() <= max;
+}
+
+export function incomingMetadataOwner(key) {
+  return request.auth != null
+    && request.resource.metadata[key] == request.auth.uid;
+}
+
+export function existingMetadataOwner(key) {
+  return request.auth != null
+    && resource.metadata[key] == request.auth.uid;
+}
+`,"storage/objects":`// @pyric-services firebase.storage
+// @pyric-evidence storage-rules#132
+// Storage operation identity. Use request.method rather than null checks:
+// production treats missing resource/request.resource bindings as errors.
+
+export function isCreate() {
+  return request.method == 'create';
+}
+
+export function isUpdate() {
+  return request.method == 'update';
+}
+
+export function isDelete() {
+  return request.method == 'delete';
+}
+`,"storage/time":`// @pyric-services firebase.storage
+// @pyric-evidence storage-rules#132
+// Freshness checks over server-owned Storage object timestamps. Boundaries are
+// strict: equality with the deadline is not "within" the window.
+
+export function createdWithin(seconds) {
+  return request.time < resource.timeCreated + duration.value(seconds, 's');
+}
+
+export function updatedWithin(seconds) {
+  return request.time < resource.updated + duration.value(seconds, 's');
+}
+`,"storage/uploads":`// @pyric-services firebase.storage
+// @pyric-evidence storage-rules#132
+// Storage upload request primitives. These inspect declared object metadata;
+// MIME helpers do not inspect or authenticate the uploaded bytes.
+
+export function sizeAtMost(maxBytes) {
+  return request.resource.size <= maxBytes;
+}
+
+export function sizeBetween(minBytes, maxBytes) {
+  return request.resource.size >= minBytes
+    && request.resource.size <= maxBytes;
+}
+
+export function contentTypeMatches(pattern) {
+  return request.resource.contentType.matches(pattern);
+}
+
+export function contentTypeIsOneOf(types) {
+  return request.resource.contentType in types;
+}
+`,timing:`// @pyric-services cloud.firestore
+// Timing module for cooldown / rate-limit enforcement.
+//
+// Rules CAN rate-limit (contrary to a common assumption — jrpg
+// FINDINGS F-004): compare request.time against a stored server
+// timestamp. Pair with lifecycle's isServerTimestamp on the SAME
+// write so the stored timestamp cannot be forged by the client:
+//
+//   import { cooldownElapsed } from 'timing';
+//   import { isServerTimestamp } from 'lifecycle';
+//
+//   // At most one move every 2 seconds:
+//   allow update: if cooldownElapsed('lastMoveAt', 2)
+//     && isServerTimestamp('lastMoveAt');
+
+// The stored timestamp is more than \`seconds\` old (strict). Update
+// rules only — needs \`resource\`. The field must be a Timestamp; a
+// missing field errors, which denies (fail-closed).
+export function cooldownElapsed(field, seconds) {
+  return request.time > resource.data[field] + duration.value(seconds, 's');
+}
+`,transitions:`// @pyric-services cloud.firestore
+// Transitions module for state machine enforcement.
+//
+// Validates that a field transitions from one known value to another.
+// Use to enforce valid status flows (e.g., open -> in_progress -> completed).
+//
+// Usage:
+//   import { validTransition, statusIs, newStatusIs } from 'transitions';
+//
+//   // Only allow open -> in_progress
+//   allow update: if validTransition('status', 'open', 'in_progress');
+//
+//   // Allow update only when currently active
+//   allow update: if statusIs('status', 'active');
+//
+//   // Compound: multiple valid transitions via OR
+//   allow update: if validTransition('status', 'open', 'in_progress')
+//     || validTransition('status', 'in_progress', 'completed')
+//     || validTransition('status', 'completed', 'archived');
+
+// Check that a field transitions from one value to another.
+export function validTransition(field, from, to) {
+  return resource.data[field] == from
+    && request.resource.data[field] == to;
+}
+
+// Check the current (existing) value of a field.
+export function statusIs(field, value) {
+  return resource.data[field] == value;
+}
+
+// Check the incoming (new) value of a field.
+export function newStatusIs(field, value) {
+  return request.resource.data[field] == value;
+}
+`,turns:`// @pyric-services cloud.firestore
+// Turn enforcement for 2-participant games/sessions.
+//
+// Convention: documents must have these fields:
+//   host: string (UID)
+//   guest: string (UID)
+//   currentTurn: 'host' | 'guest'
+//
+// Usage:
+//   import { isMyTurn, turnFlipped } from 'turns';
+//
+//   allow update: if isMyTurn() && turnFlipped();
+
+// Is the caller the participant whose turn it is?
+export function isMyTurn() {
+  return (resource.data.currentTurn == 'host'
+            && request.auth.uid == resource.data.host)
+      || (resource.data.currentTurn == 'guest'
+            && request.auth.uid == resource.data.guest);
+}
+
+// Did the turn alternate?
+export function turnFlipped() {
+  return (resource.data.currentTurn == 'host'
+            && request.resource.data.currentTurn == 'guest')
+      || (resource.data.currentTurn == 'guest'
+            && request.resource.data.currentTurn == 'host');
+}
+`,validation:`// @pyric-services cloud.firestore
+// Validation module for document field shape and value checks.
+//
+// Usage:
+//   import { hasRequired, hasOnly, validString, isOneOf } from 'validation';
+//
+//   allow create: if hasRequired(['title', 'status'])
+//     && validString('title', 1, 100)
+//     && isOneOf('status', ['draft', 'published']);
+
+export function hasRequired(fields) {
+  return request.resource.data.keys().hasAll(fields);
+}
+
+export function hasOnly(fields) {
+  return request.resource.data.keys().hasOnly(fields);
+}
+
+// Incoming field is a string with size in [min, max] (inclusive).
+// Uses dynamic access, so a MISSING field reads as null (not an
+// error) and fails the \`is string\` check — safe on optional fields.
+export function validString(field, min, max) {
+  return request.resource.data[field] is string
+    && request.resource.data[field].size() >= min
+    && request.resource.data[field].size() <= max;
+}
+
+// Enum check: the incoming field value is one of the allowed values.
+// (\`in\` on a list — NOT \`.includes()\`, which does not exist in rules.)
+export function isOneOf(field, values) {
+  return request.resource.data[field] in values;
+}
+`};function Tt(){const t={};for(const[e,n]of Object.entries(Et))t[e]=n,t[`./stdlib/${e}.rules`]=n;return t}const Oe=Tt(),Rt=new Set(Object.keys(Oe));function gn(t,e){const n=Object.entries(e?.modules??{}),r=Object.fromEntries(n),s=new Set(n.map(([a])=>a)),i=new Set([...Rt].filter(a=>!s.has(a)));return st(null,t,{...e,modules:{...Oe,...r}},i)}const Ft=Symbol.for("pyric.remote.sandbox");function de(t){return t!=null&&t[Ft]===!0}function bn(t={}){return it()}function D(t){return t.replace(/^\/+|\/+$/g,"").split("/")}function Ie(t){return D(t).length%2===0&&D(t).length>0}function le(t){return D(t).length%2===1}function Y(t){const e=D(t);return e[e.length-1]??""}function De(t){return D(t).slice(0,-1).join("/")}function je(t,e){const n=e!==void 0,r=n?oe(e):void 0;return{id:t.id,ref:t,exists:n,data:()=>n?r:void 0,get:s=>J(r,s)}}const ge=new WeakMap;let At=1;function be(t){let e=ge.get(t);return e===void 0&&(e=At++,ge.set(t,e)),e}function $(t){if(t===null||typeof t=="boolean")return t;if(typeof t=="string")return at(t);if(typeof t>"u")return{type:"undefined"};if(typeof t=="bigint")return T("bigint",t.toString());if(typeof t=="number"){const n=Number.isNaN(t)?"NaN":t===1/0?"Infinity":t===-1/0?"-Infinity":Object.is(t,-0)?"-0":String(t);return T("number",n)}if(typeof t!="object"&&typeof t!="function")return{type:typeof t,value:String(t)};const e=ot(t);if(e!==void 0)return e;try{if(Array.isArray(t))return{type:"array",id:be(t)}}catch{}return{type:"opaque-object",id:be(t)}}function w(t){return new f({code:"invalid-argument",message:t})}function ne(t,e,n,r=!1,s=!1){if(t===null||typeof t=="string"||typeof t=="boolean")return{comparison:t,execution:t};if(typeof t=="number")return{comparison:t,execution:t};if(typeof t>"u"||typeof t=="bigint"||typeof t=="function"||typeof t=="symbol")throw w(`Unsupported Firestore query value: ${typeof t}.`);if(typeof t!="object")throw w("Unsupported Firestore query value.");const i=ut(t);if(i!==void 0){const o=ct(t);if(o!==void 0&&n!==void 0&&o!==n)throw w("Document reference belongs to a different Firestore database.");return{comparison:{type:"registered-firestore-value",value:i},execution:dt(t)}}if(t instanceof Date){const o=t.getTime();if(!Number.isFinite(o))throw w("Invalid Date query value.");const c=Math.floor(o/1e3),u=Object.freeze({seconds:c,nanoseconds:Math.floor((o-c*1e3)*1e6)}),l={type:"timestamp",...u};return H(u,l,()=>Object.freeze({...u})),{comparison:{type:"registered-firestore-value",value:l},execution:u}}if(t instanceof Uint8Array){const o=t.slice();return{comparison:{type:"bytes",values:Array.from(o)},execution:o}}if(e.has(t))throw w("Cyclic query operands are not Firestore values.");const a=Object.getPrototypeOf(t);if(a!==Object.prototype&&a!==null&&!Array.isArray(t))throw w("Firestore query maps must be plain objects.");e.add(t);try{if(Array.isArray(t)){if(s&&!r)throw w("Nested arrays are not supported.");const u=t.map(d=>ne(d,e,n,r,!0)),l=u.map(d=>d.execution);return S(l,$(t)),{comparison:{type:"array",values:u.map(d=>d.comparison)},execution:l}}const o=Object.keys(t).sort().map(u=>({key:u,captured:ne(t[u],e,n,r,!1)})),c=Object.fromEntries(o.map(({key:u,captured:l})=>[u,l.execution]));return S(c,$(t)),{comparison:{type:"map",entries:o.map(({key:u,captured:l})=>[u,l.comparison])},execution:c}}finally{e.delete(t)}}function Me(t,e,n=!1){try{const r=ne(t,new Set,e,n);return Object.freeze({kind:"canonical",value:r.comparison,executionValue:r.execution})}catch(r){if(r instanceof f)throw r;const s=r instanceof Error?r.message:String(r);throw w(`Invalid Firestore query value: ${s}`)}}function _e(t,e){return lt(t.value,e.value)}function N(t,e){if(t.kind==="where"){const n="comparisonValue"in t?t.comparisonValue:Me(t.value,e,t.op==="in"||t.op==="not-in");return Object.freeze({kind:"where",field:t.field,op:t.op,value:n.executionValue,comparisonValue:n})}return Object.freeze({kind:t.kind,filters:Object.freeze(t.filters.map(n=>N(n,e)))})}function U(t,e,n,r){const s=t.map(i=>Me(i,r));return Object.freeze({values:Object.freeze(s.map(i=>i.executionValue)),comparisonValues:Object.freeze(s),inclusive:e,fromSnapshot:n})}function ze(t,e){return t.length!==e.length?!1:t.every((n,r)=>{const s=e[r];return n.kind!==s.kind?!1:n.kind==="where"&&s.kind==="where"?n.field===s.field&&n.op===s.op&&_e(n.comparisonValue,s.comparisonValue):n.kind!=="where"&&s.kind!=="where"&&ze(n.filters,s.filters)})}function we(t,e){return t===void 0||e===void 0?t===e:t.inclusive===e.inclusive&&t.comparisonValues.length===e.comparisonValues.length&&t.comparisonValues.every((n,r)=>_e(n,e.comparisonValues[r]))}function Ot(t,e){return t.kind!==e.kind?!1:t.kind==="collection"&&e.kind==="collection"?t.path===e.path:t.kind==="collection-group"&&e.kind==="collection-group"&&t.collectionId===e.collectionId}function Pe(t){return t.kind==="where"?Object.freeze({kind:t.kind,field:t.field,op:t.op,value:t.value}):Object.freeze({kind:t.kind,filters:Object.freeze(t.filters.map(Pe))})}function ve(t){if(t!==void 0)return Object.freeze({values:t.values,inclusive:t.inclusive,fromSnapshot:t.fromSnapshot})}function It(t,e){return ze(t.filters,e.filters)&&t.orders.length===e.orders.length&&t.orders.every((n,r)=>{const s=e.orders[r];return n.field===s.field&&n.direction===s.direction})&&t.limitCount===e.limitCount&&t.limitFromEnd===e.limitFromEnd&&we(t.start,e.start)&&we(t.end,e.end)}const Ue="__name__";function xe(t,e){const n=t.data();if(n===void 0)throw new f({code:"not-found",message:`Snapshot-based cursors require an existing document — got an empty snapshot for ${t.id??"<unknown>"}.`});return e.map(r=>r.field===Ue?t.ref:n[r.field])}class j{env;auth;collectionPath;clauses;orders;limitCount;limitFromEnd;start;end;bypassRules;documentRef;constructor(e){this.env=e.env,this.auth=e.auth,this.collectionPath=e.collectionPath,this.documentRef=e.documentRef,this.clauses=Object.freeze((e.clauses??[]).map(n=>N(n))),this.orders=Object.freeze((e.orders??[]).map(n=>Object.freeze({...n}))),this.limitCount=e.limitCount,this.limitFromEnd=e.limitFromEnd??!1,this.start=e.start===void 0?void 0:Object.freeze({...e.start,values:Object.freeze(e.start.comparisonValues.map(n=>n.executionValue)),comparisonValues:e.start.comparisonValues}),this.end=e.end===void 0?void 0:Object.freeze({...e.end,values:Object.freeze(e.end.comparisonValues.map(n=>n.executionValue)),comparisonValues:e.end.comparisonValues}),this.bypassRules=e.bypassRules??!1}where(e,n,r){return this.clone({clauses:[...this.clauses,N({kind:"where",field:e,op:n,value:r})]})}applyFilter(e){return this.clone({clauses:[...this.clauses,N(e)]})}orderBy(e,n="asc"){return this.clone({orders:[...this.orders,{field:e,direction:n}]})}limit(e){return this.clone({limitCount:e,limitFromEnd:!1})}limitToLast(e){return this.clone({limitCount:e,limitFromEnd:!0})}startCursor(e,n){return this.clone({start:U(this.normalizeExplicitCursorValues(e),n,!1)})}endCursor(e,n){return this.clone({end:U(this.normalizeExplicitCursorValues(e),n,!1)})}startCursorFromSnapshot(e,n){return this.clone({start:U(xe(e,this.normalizedOrders()),n,!0)})}endCursorFromSnapshot(e,n){return this.clone({end:U(xe(e,this.normalizedOrders()),n,!0)})}isStructurallyEqual(e){return e instanceof j?this.env===e.env&&this.bypassRules===e.bypassRules&&Ot(this.queryScope(),e.queryScope())&&It(this.comparableExecutionSpec(),e.comparableExecutionSpec()):!1}clone(e){return new j({env:this.env,auth:this.auth,collectionPath:this.collectionPath,documentRef:this.documentRef,clauses:e.clauses??this.clauses,orders:e.orders??this.orders,limitCount:"limitCount"in e?e.limitCount:this.limitCount,limitFromEnd:e.limitFromEnd??this.limitFromEnd,start:"start"in e?e.start:this.start,end:"end"in e?e.end:this.end,bypassRules:this.bypassRules})}queryScope(){return{kind:"collection",path:this.collectionPath}}readQueryRows(e){const n=e?.auth!==void 0?e.auth:this.auth;let r;try{r=this.env.runQuery({scope:this.queryScope(),auth:n,execution:this.executionSpec(),bypassRules:this.bypassRules,activityQuery:this.activityQuery()})}catch(s){const i=s?.simError;throw i?new f(i):s}if(!r.allowed)throw new f(r.error);return r.docs}activityQuery(){const e=r=>r.kind==="where"?{kind:"where",field:r.field,op:r.op,value:$(r.value)}:{kind:r.kind,filters:r.filters.map(e)},n=r=>r===void 0?null:{values:r.values.map(s=>$(s)),inclusive:r.inclusive,fromSnapshot:r.fromSnapshot};return{scope:this.activityScope(),filters:this.clauses.map(e),orderBy:this.orders.map(r=>({...r})),limit:this.limitCount??null,limitFromEnd:this.limitFromEnd,start:n(this.start),end:n(this.end)}}activityScope(){return{kind:"collection"}}normalizedOrders(){return ht(this.executionSpec())}normalizeExplicitCursorValues(e){const n=this.orders;return e.map((r,s)=>{if(n[s]?.field!==Ue)return r;if(typeof r!="string")throw new f({code:"invalid-argument",message:"Expected a string for a document ID cursor value."});const i=r.includes("/")?r:`${this.collectionPath}/${r}`;return this.documentRef(i)})}executionSpec(){const e={filters:Object.freeze(this.clauses.map(Pe)),orders:this.orders,limitCount:this.limitCount,limitFromEnd:this.limitFromEnd,start:ve(this.start),end:ve(this.end)};return Object.freeze(e)}comparableExecutionSpec(){return{filters:this.clauses,orders:this.orders,limitCount:this.limitCount,limitFromEnd:this.limitFromEnd,start:this.start,end:this.end}}snapshotConstraints(){return Object.freeze({execution:this.executionSpec(),activityQuery:this.activityQuery()})}async get(e){const r=this.readQueryRows(e).map(s=>{const i=this.documentRef(s.path),a=oe(s.data);return{id:i.id,ref:i,exists:!0,data:()=>a,get:o=>J(a,o)}});return{size:r.length,empty:r.length===0,docs:r,forEach(s){r.forEach(s)}}}async aggregate(e,n){const r=this.readQueryRows(n),s={};for(const i of Object.keys(e))s[i]=jt(e[i],r);return{data:()=>s}}}function Dt(t,e){if(!e.includes("."))return t[e];let n=t;for(const r of e.split(".")){if(typeof n!="object"||n===null||Array.isArray(n))return;n=n[r]}return n}function jt(t,e){if(t.kind==="count")return e.length;let n=0,r=0;for(const s of e){const i=Dt(s.data,t.field);typeof i=="number"&&Number.isFinite(i)&&(n+=i,r++)}return t.kind==="sum"?n:r===0?null:n/r}function k(t,e){if(t.error)throw new f(t.error);const n=t.debugMessages.length>0?t.debugMessages.join("; "):"(no debug message)";throw new f(q("permission-denied",`${e}: ${n}`))}class Mt{env;auth;bypassRules;collectionRef;id;path;constructor(e,n,r,s=!1,i){this.env=e,this.auth=n,this.bypassRules=s,this.collectionRef=i,this.path=r,this.id=Y(r),S(this,T("reference",r)),ue(this,r,e)}get parent(){return this.collectionRef(De(this.path))}collection(e){return this.collectionRef(`${this.path}/${e}`)}async get(e){const n=this.env.execute({method:"get",path:this.path,auth:e?.auth!==void 0?e.auth:this.auth,bypassRules:this.bypassRules});n.allowed||k(n,"get denied");const r=n.data===void 0||n.data===null?void 0:n.data;return je(this,r)}async set(e,n){const r=n?.auth!==void 0?n.auth:this.auth;if(n?.mergeFields!==void 0){const i=n.mergeFields.map(u=>String(u)),o=this.env.getDocument(this.path)===null?"create":"update",c=this.env.execute({method:o,path:this.path,data:e,auth:r,merge:{mergeFields:i},bypassRules:this.bypassRules});c.allowed||k(c,`set denied (as ${o})`);return}if(n?.merge===!0){const a=this.env.getDocument(this.path)===null?"create":"update",o=this.env.execute({method:a,path:this.path,data:e,auth:r,merge:!0,bypassRules:this.bypassRules});o.allowed||k(o,`set denied (as ${a})`);return}const s=this.env.execute({method:"set",path:this.path,data:e,auth:r,bypassRules:this.bypassRules});s.allowed||k(s,"set denied")}async update(e,n){const r=this.env.execute({method:"update",path:this.path,data:e,auth:n?.auth!==void 0?n.auth:this.auth,bypassRules:this.bypassRules});r.allowed||k(r,"update denied")}async delete(e){const n=this.env.execute({method:"delete",path:this.path,auth:e?.auth!==void 0?e.auth:this.auth,bypassRules:this.bypassRules});n.allowed||k(n,"delete denied")}}function L(t,e,n,r){return new Mt(t,e,n,r,s=>new Ne(t,e,s,r))}class Ne extends j{id;path;constructor(e,n,r,s=!1){super({env:e,auth:n,collectionPath:r,bypassRules:s,documentRef:i=>L(e,n,i,s)}),this.path=r,this.id=Y(r)}doc(e){const n=e??Fe();return L(this.env,this.auth,`${this.path}/${n}`,this.bypassRules)}async add(e,n){const r=this.doc();return await r.set(e,n),r}}class he extends j{collectionId;constructor(e){super({...e,collectionPath:"",documentRef:n=>L(e.env,e.auth,n,e.bypassRules??!1)}),this.collectionId=e.collectionId}clone(e){return new he({env:this.env,auth:this.auth,collectionId:this.collectionId,clauses:e.clauses??this.clauses,orders:e.orders??this.orders,limitCount:"limitCount"in e?e.limitCount:this.limitCount,limitFromEnd:e.limitFromEnd??this.limitFromEnd,start:"start"in e?e.start:this.start,end:"end"in e?e.end:this.end,bypassRules:this.bypassRules})}queryScope(){return{kind:"collection-group",collectionId:this.collectionId}}activityScope(){return{kind:"collection-group"}}}class _t{env;auth;bypassRules;ops=[];constructor(e,n,r=!1){this.env=e,this.auth=n,this.bypassRules=r}set(e,n){const s=this.env.getDocument(e.path)===null?"create":"update";return this.ops.push({method:s,path:e.path,data:n}),this}update(e,n){return this.ops.push({method:"update",path:e.path,data:n}),this}delete(e){return this.ops.push({method:"delete",path:e.path}),this}async commit(e){if(this.ops.length===0)return;const n=this.env.batch(this.ops,e?.auth!==void 0?e.auth:this.auth,this.bypassRules);if(n.allowed)return;if(n.error)throw new f(n.error);const s=n.results.find(i=>!i.allowed)?.debugMessages.join("; ")??"batch denied";throw new f(q("permission-denied",`batch failed: ${s}`))}}function zt(t){return typeof t.where=="function"}class Pt{simTx;constructor(e){this.simTx=e}async get(e){if(zt(e)){const s=await e.get();return s.size>0&&this.simTx.getAll(...s.docs.map(i=>i.ref.path)),s}const r=this.simTx.get(e.path).data();return je(e,r)}set(e,n){return this.simTx.set(e.path,n),this}update(e,n){return this.simTx.update(e.path,n),this}delete(e){return this.simTx.delete(e.path),this}}class Ut{env;auth;bypassRules;provenance;constructor(e,n,r=!1,s){this.env=e,this.auth=n,this.bypassRules=r,this.provenance=s}collection(e){if(!le(e))throw new f(q("invalid-argument",`collection path must have an odd number of segments: ${e}`));return new Ne(this.env,this.auth,e,this.bypassRules)}doc(e){if(!Ie(e))throw new f(q("invalid-argument",`document path must have an even number of segments: ${e}`));return L(this.env,this.auth,e,this.bypassRules)}collectionGroup(e){if(e.length===0||e.includes("/"))throw new f(q("invalid-argument",`collection group id must be a single non-empty segment with no '/': ${e}`));return new he({env:this.env,auth:this.auth,collectionId:e,bypassRules:this.bypassRules})}batch(){return new _t(this.env,this.auth,this.bypassRules)}async runTransaction(e,n){let r;try{r=await this.env.transaction(s=>{const i=new Pt(s);return e(i)},{auth:n?.auth!==void 0?n.auth:this.auth,bypassRules:this.bypassRules,provenance:this.provenance,maxAttempts:n?.maxAttempts})}catch(s){throw s instanceof ft?new f(s.simError):s instanceof mt?new f(s.simError):s}if(!r.allowed){if(r.error)throw new f(r.error);const i=r.writes.find(a=>!a.allowed)?.debugMessages.join("; ")??"transaction denied at commit";throw new f(q("permission-denied",`transaction failed: ${i}`))}return r.returnValue}}function Nt(t,e){return new Ut(t,e?.auth??null,e?.bypassRules??!1,e?.provenance)}const Bt=Symbol("pyric/sandbox/context"),Vt=Symbol("pyric/sandbox/bypassRules");function $t(t){const e=t.trim();if(!e)return[];const n=e.indexOf(": ");if(n!==-1){const s=e.slice(n+2).trim().split("; ").map(i=>i.trim()).filter(i=>i.length>0);if(s.length>0)return s}return[e]}function Se(t,e){if(t instanceof f===!1)return t;const r=t.code;if(r==="permission-denied"===!1)return new p(r,t.message);const i={auth:e.auth,reasons:$t(t.message)},a=t.simError;if(a!==void 0){if(a.request!==void 0){const m=a.request;i.request={method:m.method,path:m.path},m.resourceData!==void 0&&(i.request.resourceData=m.resourceData)}if(a.resource!==void 0&&(i.resource={data:a.resource.data,exists:a.resource.exists}),a.query!==void 0&&(i.query=a.query),a.rule!==void 0&&(i.rule=a.rule),a.remediation!==void 0)return new p({code:r,message:t.message,denialContext:i,remediation:a.remediation})}return new p(r,t.message,i)}function W(t,e,n=!1){return new Proxy(t,{get(r,s,i){if(s===Bt)return e;if(s===Vt)return n;const a=Reflect.get(r,s,i);return typeof a!="function"?a:function(...o){let c;try{const u=()=>a.apply(r,o);c=e.sandbox.runWithProvenance?.(Ae(e.operationContext),u)??u()}catch(u){throw Se(u,e)}return c instanceof Promise?c.then(u=>u&&typeof u=="object"?W(u,e,n):u).catch(u=>{throw Se(u,e)}):c&&typeof c=="object"?W(c,e,n):c}}})}function Be(t,e=!1){if(de(t.sandbox))throw new Error("pyric/sandbox/admin-firestore: internal — a remote sandbox context reached the local engine builder; remote dispatch should have handled it. Please report this.");const n=()=>Nt(O(t.sandbox),{auth:t.auth,bypassRules:e,provenance:Ae(t.operationContext)});return{collection(r){return n().collection(r)},doc(r){return n().doc(r)},collectionGroup(r){return n().collectionGroup(r)},batch(){return n().batch()},runTransaction(r,s){return n().runTransaction(r,s)},setRules(r){return O(t.sandbox).deployRules(r)},seed(r){const s=O(t.sandbox);return s.seed({rules:s.getRules(),documents:r?.documents??{}})},snapshot(){return O(t.sandbox).snapshot()}}}function re(t){if(t instanceof p)return t;if(t!==null&&typeof t=="object"){const e=t;if(typeof e.code=="string"&&typeof e.message=="string"){const n=e.denialContext!==null&&typeof e.denialContext=="object"?e.denialContext:void 0;return new p(e.code,e.message,n)}}return t}function g(t){return new p("invalid-argument",t)}async function y(t,e){try{return await t.sandbox.channel.op({...e,actAs:t.lens})}catch(n){throw re(n)}}const Lt=new Set(["serverTimestamp","increment","arrayUnion","arrayRemove","deleteField"]);function Wt(t){return t!==null&&typeof t=="object"&&typeof t.__type=="string"&&Lt.has(t.__type)}function Qt(t){switch(t.__type){case"serverTimestamp":return{__sentinel:"serverTimestamp"};case"increment":return{__sentinel:"increment",n:t.value};case"arrayUnion":return{__sentinel:"arrayUnion",values:t.values.map(b)};case"arrayRemove":return{__sentinel:"arrayRemove",values:t.values.map(b)};case"deleteField":return{__sentinel:"deleteField"}}}function b(t){if(t===null||typeof t!="object")return t;if(Wt(t))return Qt(t);if(t instanceof ye)return t.toJSON();if(t instanceof Date)return ye.fromDate(t).toJSON();if(Array.isArray(t))return t.map(b);const e=Object.getPrototypeOf(t);if(e!==Object.prototype&&e!==null){const r=t.toJSON;if(typeof r=="function")return r.call(t);throw g(`remote Firestore: cannot serialize a ${e.constructor?.name??"class"} instance for the wire — use plain data, Timestamp, Date, or FieldValue sentinels.`)}const n={};for(const[r,s]of Object.entries(t))n[r]=b(s);return n}function C(t){return b(t)}function se(t){return pt(JSON.parse(t.json))}function Ve(t){return oe(se(t))}function $e(t,e){const n=e.exists&&e.data?Ve(e.data):void 0;return{id:t.id,ref:t,exists:e.exists,data:()=>n,get:r=>J(n,r)}}function Le(t,e){const n=e.docs.map(r=>{const s=r.path??r.id,i=Q(t,s),a=r.data?Ve(r.data):{};return{id:i.id,ref:i,exists:!0,data:()=>a,get:o=>J(a,o)}});return{size:n.length,empty:n.length===0,docs:n,forEach(r){n.forEach(s=>r(s))}}}const We=Symbol("pyric/sandbox/admin-firestore/remoteSnapshotRegistrar");function Qe(...t){throw new p("failed-precondition","remote Firestore: onSnapshot is not wired yet — import pyric-admin/firestore (or pyric/sandbox/admin-firestore) before subscribing.")}function Ge(t,e,n,r,s){const i=n.includeMetadataChanges!==!0;let a,o;try{o=t.sandbox.channel.subscribe({target:e,actAs:t.lens},c=>{if(!r)return;const u=c;if(Array.isArray(u.docs)){const l=u.docs.map(m=>({path:m.path??m.id,data:m.data?se(m.data):{}})),d=e.__ref==="query"?e.source.__ref==="group"?e.source.collectionId:e.source.path:e.__ref==="group"?e.collectionId:e.path,h=yt({path:d},l,{excludesMetadataChanges:i},a);a=l,r(h)}else if(typeof u.id=="string"){const l=u.path??u.id,d=u.exists&&u.data?se(u.data):null;r(gt(l,d))}},c=>{const u=re(c);s?s(u):console.error("pyric remote Firestore: uncaught onSnapshot error:",u)})}catch(c){throw re(c)}return o}const Je=Symbol("pyric/sandbox/admin-firestore/remoteQueryState");function Gt(t){if(!(t===null||typeof t!="object"))return t[Je]}function He(t){return t.kind==="where"?(Ye(t.op),{kind:"where",field:t.field,op:t.op,value:b(t.value)}):{kind:t.kind,filters:t.filters.map(He)}}const Jt=new Set(["<","<=","==","!=",">=",">","in","not-in","array-contains","array-contains-any"]);function Ye(t){if(!Jt.has(t))throw g(`invalid where operator: ${String(t)}`)}function B(t){const e=[...t.filters];for(const n of t.orders)e.push({kind:"orderBy",field:n.field,direction:n.direction});return t.start&&e.push({kind:t.start.inclusive?"startAt":"startAfter",values:t.start.values.map(b)}),t.end&&e.push({kind:t.end.inclusive?"endAt":"endBefore",values:t.end.values.map(b)}),t.limitCount!==void 0&&e.push(t.limitFromEnd?{kind:"limitToLast",n:t.limitCount}:{kind:"limit",n:t.limitCount}),e.length===0?t.source:{__ref:"query",source:t.source,constraints:e}}function Ce(t,e,n){if(e.length===0)throw g(`${n}(snapshot) on a remote sandbox requires at least one explicit orderBy() clause — the relay protocol has no document-key cursor.`);if(e.some(s=>s.field==="__name__"))throw g(`${n}(snapshot) on a remote sandbox does not support orderBy('__name__') — the relay protocol has no document-key cursor, and __name__ is not a data field a value cursor can carry. Order by a real document field instead.`);const r=t.data();if(r===void 0)throw new p("not-found",`Snapshot-based cursors require an existing document — got an empty snapshot for ${t.id??"<unknown>"}.`);return e.map(s=>r[s.field])}function fe(t,e){const n=s=>fe(t,{...e,...s});return{[Je]:e,where(s,i,a){return Ye(i),n({filters:[...e.filters,{kind:"where",field:s,op:i,value:b(a)}]})},applyFilter(s){return n({filters:[...e.filters,He(s)]})},orderBy(s,i="asc"){return n({orders:[...e.orders,{field:s,direction:i}]})},limit(s){return n({limitCount:s,limitFromEnd:!1})},limitToLast(s){return n({limitCount:s,limitFromEnd:!0})},startCursor(s,i){return n({start:{values:[...s],inclusive:i}})},endCursor(s,i){return n({end:{values:[...s],inclusive:i}})},startCursorFromSnapshot(s,i){return n({start:{values:Ce(s,e.orders,i?"startAt":"startAfter"),inclusive:i}})},endCursorFromSnapshot(s,i){return n({end:{values:Ce(s,e.orders,i?"endAt":"endBefore"),inclusive:i}})},async get(s){V(e);const i=await y(t,{method:"getDocs",source:B(e)});return Le(t,i)},async aggregate(s){V(e);const i=await y(t,{method:"aggregate",source:B(e),spec:s});return{data:()=>i.data}},[We]:(s,i,a)=>(V(e),Ge(t,B(e),s,i,a)),onSnapshot:Qe}}function V(t){if(t.limitFromEnd&&t.orders.length===0)throw g("limitToLast() queries require at least one orderBy clause.")}function ie(t,e){const n=fe(t,{source:{__ref:"collection",path:e},filters:[],orders:[],limitFromEnd:!1});return Object.assign(Object.create(Object.getPrototypeOf(n)),n,{id:Y(e),path:e,doc(s){const i=s??Fe();return Q(t,`${e}/${i}`)},async add(s,i){const a=await y(t,{method:"addDoc",collectionPath:e,data:C(s)});return Q(t,a.path)}})}function Q(t,e){const n={id:Y(e),path:e,get parent(){return ie(t,De(e))},collection(r){const s=`${e}/${r}`;if(!le(s))throw g(`collection path must have an odd number of segments: ${s}`);return ie(t,s)},async get(r){const s=await y(t,{method:"getDoc",path:e});return $e(n,s)},async set(r,s){await y(t,{method:"setDoc",path:e,data:C(r),...ke(s)?{options:ke(s)}:{}})},async update(r,s){await y(t,{method:"updateDoc",path:e,data:C(r)})},async delete(r){await y(t,{method:"deleteDoc",path:e})},[We]:(r,s,i)=>Ge(t,{__ref:"doc",path:e},r,s,i),onSnapshot:Qe};return n}function ke(t){if(!t)return;const e={};return t.merge!==void 0&&(e.merge=t.merge),t.mergeFields!==void 0&&(e.mergeFields=[...t.mergeFields]),e.merge!==void 0||e.mergeFields!==void 0?e:void 0}function Ht(t){const e=[];let n=!1;const r={set(i,a){return s(),e.push({method:"set",path:i.path,data:C(a)}),r},update(i,a){return s(),e.push({method:"update",path:i.path,data:C(a)}),r},delete(i){return s(),e.push({method:"delete",path:i.path}),r},async commit(i){s(),n=!0,await y(t,{method:"batchCommit",writes:e})}};function s(){if(n)throw new p("failed-precondition","WriteBatch has already been committed.")}return r}const Yt=5;async function Xt(t,e,n=Yt){for(let r=0;r<n;r++){const s=[],i=[],a=()=>{if(i.length>0)throw new p("failed-precondition",bt)},o={get(d){a();const h=Gt(d);return h!==void 0?u(h):c(d)},set(d,h){return i.push({method:"set",path:d.path,data:C(h)}),o},update(d,h){return i.push({method:"update",path:d.path,data:C(h)}),o},delete(d){return i.push({method:"delete",path:d.path}),o}};async function c(d){const h=await y(t,{method:"getDoc",path:d.path});return s.push({path:h.path??d.path,data:h.exists&&h.data?h.data:null}),$e(d,h)}async function u(d){V(d);const h=await y(t,{method:"getDocs",source:B(d)});for(const m of h.docs)s.push({path:m.path??m.id,data:m.data??null});return Le(t,h)}const l=await e(o);try{return await y(t,{method:"txnCommit",reads:s,writes:i}),l}catch(d){if(d instanceof p&&d.code==="aborted")continue;throw d}}throw new p("aborted",`Transaction failed after ${n} attempts due to repeated conflicts. Another writer is concurrently updating the same documents.`)}function Z(t,e){return new p("unimplemented",`SandboxFirestore.${t} is not available on a remote sandbox — its return value is synchronous and the data lives in the browser worker. ${e}`)}function Xe(t,e){const n={sandbox:t,lens:e};return{collection(r){if(!le(r))throw g(`collection path must have an odd number of segments: ${r}`);return ie(n,r)},doc(r){if(!Ie(r))throw g(`document path must have an even number of segments: ${r}`);return Q(n,r)},collectionGroup(r){if(r.length===0||r.includes("/"))throw g(`collection group id must be a single non-empty segment with no '/': ${r}`);return fe(n,{source:{__ref:"group",collectionId:r},filters:[],orders:[],limitFromEnd:!1})},batch(){return Ht(n)},runTransaction(r,s){return Xt(n,r,s?.maxAttempts)},setRules(){throw Z("setRules","Deploy rules asynchronously through the relay instead: `await sandbox.channel.op({ method: 'setFirestoreRules', source })`.")},seed(){throw Z("seed","The relay has no atomic seed op; write seed docs through this handle (`db.doc(path).set(data)` / `db.batch()`), or drive `sandbox.channel.op({ method: 'admin.setDocument', path, data })` per document.")},snapshot(){throw Z("snapshot","Read the worker state asynchronously instead: `await sandbox.channel.op({ method: 'admin.readState' })`.")}}}const qe=new WeakMap;function Ke(t){const e=qe.get(t);if(e)return e;const n=de(t.sandbox)?Xe(t.sandbox,Kt(t.auth)):W(Be(t),t);return qe.set(t,n),n}function Kt(t){if(t==null)return{mode:"anon"};const e={mode:"as",uid:t.uid};return t.token!==void 0&&(e.token=t.token),t.tenant!==void 0&&(e.tenant=t.tenant),e}const Ee=new WeakMap;function Zt(t){const e=en(t)?t:t.withAuth(null),n=Ee.get(e);if(n)return n;const r=e.operationContext.authLens.mode==="admin"?e:ce(e,{source:e.operationContext.source,authLens:{mode:"admin"},...e.operationContext.planId===void 0?{}:{planId:e.operationContext.planId}}),s=de(r.sandbox)?Xe(r.sandbox,{mode:"admin"}):W(Be(r,!0),r,!0);return Ee.set(e,s),s}function en(t){return t!==null&&typeof t=="object"&&"sandbox"in t&&typeof t.withAuth=="function"}class x{bytes;constructor(e){this.bytes=e,S(this,wt(e)),H(this,Object.freeze({type:"bytes",values:Object.freeze(Array.from(e))}),()=>new x(e.slice()))}static fromBase64String(e){const n=atob(e),r=new Uint8Array(n.length);for(let s=0;s<n.length;s+=1)r[s]=n.charCodeAt(s);return new x(r)}static fromUint8Array(e){return new x(e.slice())}toBase64(){let e="";for(const n of this.bytes)e+=String.fromCharCode(n);return btoa(e)}toUint8Array(){return this.bytes.slice()}toString(){return`Bytes(base64: ${this.toBase64()})`}isEqual(e){return e instanceof x&&this.bytes.length===e.bytes.length&&this.bytes.every((n,r)=>n===e.bytes[r])}toJSON(){return{type:"firestore/bytes/1.0",bytes:this.toBase64()}}static fromJSON(e){const n=e;if(n.type!=="firestore/bytes/1.0"||typeof n.bytes!="string")throw new TypeError("Invalid Bytes JSON value.");return x.fromBase64String(n.bytes)}}class I{lat;lng;constructor(e,n){if(this.lat=e,this.lng=n,!Number.isFinite(e)||e<-90||e>90)throw new TypeError("Latitude must be a number between -90 and 90.");if(!Number.isFinite(n)||n<-180||n>180)throw new TypeError("Longitude must be a number between -180 and 180.");S(this,T("geo-point",String(e),"\0",String(n))),H(this,Object.freeze({type:"geo-point",latitude:e,longitude:n}),()=>new I(e,n))}get latitude(){return this.lat}get longitude(){return this.lng}isEqual(e){return e instanceof I&&this.lat===e.lat&&this.lng===e.lng}toJSON(){return{latitude:this.lat,longitude:this.lng,type:"firestore/geoPoint/1.0"}}static fromJSON(e){const n=e;if(n.type!=="firestore/geoPoint/1.0"||typeof n.latitude!="number"||typeof n.longitude!="number")throw new TypeError("Invalid GeoPoint JSON value.");return new I(n.latitude,n.longitude)}}class E{_values;constructor(e){this._values=e,H(this,Object.freeze({type:"vector",values:Object.freeze(e.slice())}),()=>new E(e.slice()))}static create(e){if(!e.every(n=>typeof n=="number"))throw new TypeError("Vector values must be numbers.");return new E(e.slice())}toArray(){return this._values.slice()}isEqual(e){const n=e instanceof E?e._values:void 0;return n!==void 0&&this._values.length===n.length&&this._values.every((r,s)=>r===n[s])}toJSON(){return{type:"firestore/vectorValue/1.0",vectorValues:this.toArray()}}static fromJSON(e){const n=e;if(n.type!=="firestore/vectorValue/1.0"||!Array.isArray(n.vectorValues)||!n.vectorValues.every(r=>typeof r=="number"))throw new TypeError("Invalid VectorValue JSON value.");return E.create(n.vectorValues)}}function tn(t=[]){return E.create(t)}function wn(){return vt.serverTimestamp()}const v=Symbol("pyric/firestore/target");function z(t){return t.kind==="sandbox"?t.db:t.getDb()}const X=new WeakMap;function nn(t,e){return X.set(t,e),t}const P=new WeakMap;function rn(t,e,n){return X.set(t,e),P.set(t,n),t}function me(t,e){const n=A(e);if(t.kind==="sandbox")return n;const r=P.get(n);if(!r)throw new TypeError("pyric/firestore: live ref missing rebuild closure — was it produced by a factory in this package?");return r(z(t))}function sn(t,e){const n=A(e);if(t.kind==="sandbox")return n;const r=P.get(n);if(!r)throw new TypeError("pyric/firestore: live collection ref missing rebuild closure.");return r(z(t))}function vn(t,e){const n=A(e);if(t.kind==="sandbox")return n;const r=P.get(n);if(!r)throw new TypeError("pyric/firestore: live query missing rebuild closure.");return r(z(t))}function M(t,e,n){return e.kind==="sandbox-live"?rn(t,e,n):nn(t,e)}function xn(t){const e=A(t),n=P.get(e);return n||(()=>e)}function F(t){const e=an(t);return e.assertUsable?.(),e}function an(t){let e;if(v in t?e=t[v]:e=X.get(t),!e)throw new TypeError("pyric/firestore: unrecognized reference — was it produced by a factory in this package?");return e}const Ze=new WeakMap,et=new WeakMap;function pe(t){return Ze.get(t)}function A(t){return et.get(t)??t}function tt(t,e,n){const r={id:t.id??"",path:t.path??""};return Ze.set(r,n),et.set(r,t),X.set(r,e),r}function on(t){return t instanceof Ct?Array.from(t.value):null}function ae(t){if(t instanceof xt)return x.fromUint8Array(t.data);if(t instanceof St)return new I(t.lat,t.lng);const e=on(t);if(e)return tn(e);if(Array.isArray(t))return t.map(ae);if(t!==null&&typeof t=="object"){const n=Object.getPrototypeOf(t);if(n===Object.prototype||n===null){const r={};for(const[s,i]of Object.entries(t))r[s]=ae(i);return r}}return t}function Sn(t){if(t!==void 0)return ae(t)}class R extends Error{code;customData;name="FirebaseError";constructor(e,n,r){super(n),this.code=e,this.customData=r,Object.setPrototypeOf(this,new.target.prototype)}}Object.defineProperty(R,"name",{value:"FirebaseError"});let G;function Cn(t){G=t}function nt(t){return G?.resolve(t,!1)}function un(){if(!G)throw new TypeError("No default sandbox app registry is installed - import and initialize pyric/app before calling a service factory without an app.");return G.defaultApp()}function cn(t){if(t===void 0)return cn(un());const e=nt(t);if(e)return e.service("firestore/default",()=>{const{sandbox:n,session:r}=e,s=ee();e.onDelete(s.terminate);const i=e.authScope;i&&s.own(r.onCurrentUserChanged(o=>{O(n).reevaluateLiveListeners(o,i)}));const a={kind:"sandbox-live",sandbox:n,getDb:Te(n,()=>r.currentUser),authScope:i,...s};return{[v]:a,app:t}});if(rt(t)){const r={kind:"sandbox",db:Ke(t),sandbox:t.sandbox,...ee()};return{[v]:r}}if(ln(t)){const n={kind:"sandbox-live",sandbox:t,getDb:Te(t),...ee()};return{[v]:n}}throw new TypeError("pyric/firestore is a sandbox-only mirror. Package resolution must leave firebase/firestore unchanged for production; activate pyric sandbox or @pyric/cli/register before importing to select the sandbox.")}function ee(){let t=!1;const e=new Set;return{own(n){return t?(n(),()=>{}):(e.add(n),()=>e.delete(n))},assertUsable(){if(t)throw new R("failed-precondition","The client has already been terminated.")},terminate(){if(!t){t=!0;for(const n of e)n();e.clear()}}}}function dn(t){const e=nt(t);if(e){e.assertAlive();const a=e.sandbox;return dn(ce(a.withAuth(null),{source:{kind:"app"},authLens:{mode:"admin"}}))}const n=rt(t)?t:t.withAuth(null),r=n.sandbox,i={kind:"sandbox",db:Zt(n),sandbox:r};return{[v]:i}}function rt(t){return t instanceof kt}function ln(t){if(t===null||typeof t!="object")return!1;const e=t;return typeof e.withAuth=="function"&&typeof e.onCurrentUserChanged=="function"&&"currentUser"in e&&"admin"in e}function Te(t,e=()=>t.currentUser){return()=>{const n=ce(t.withAuth(e()),{source:{kind:"app"},authLens:{mode:"app-session"}});return Ke(n)}}class hn{started=!1;networkEnabled=!0;persistenceMode;pending=new Set;cachedPaths=new Set;cachedQueries=new WeakSet;syncObservers=new Set;syncScheduled=!1;markStarted(){this.started=!0}enablePersistence(e){if(this.started||this.persistenceMode!==void 0)throw new R("failed-precondition","Firestore has already been started and persistence can no longer be enabled.");this.persistenceMode=e,this.started=!0}disableNetwork(){this.started=!0,this.networkEnabled=!1}async enableNetwork(){this.started=!0,this.networkEnabled=!0;for(const e of this.pending)e.localDone&&e.resolve(e.value);await Promise.all([...this.pending].map(e=>e.promise))}runWrite(e,n){if(this.started=!0,n&&this.cachedPaths.add(n),this.networkEnabled)return e();let r,s;const i=new Promise((o,c)=>{r=o,s=c}),a={path:n,promise:i,localDone:!1,resolve:r,reject:s};return this.pending.add(a),e().then(o=>{a.localDone=!0,a.value=o,this.networkEnabled&&a.resolve(o)},o=>a.reject(o)),i.then(()=>this.pending.delete(a),()=>this.pending.delete(a)),i}waitForPendingWrites(){this.started=!0;const e=[...this.pending].map(n=>n.promise);return Promise.all(e).then(()=>{})}cachePath(e){this.started=!0,this.cachedPaths.add(e)}assertPathCached(e){if(this.started=!0,!this.cachedPaths.has(e))throw new R("unavailable","Failed to get document from cache. (However, this document may exist on the server.)")}cacheQuery(e){this.started=!0,this.cachedQueries.add(e)}hasCachedQuery(e){return this.started=!0,this.cachedQueries.has(e)||this.cachedPaths.size>0}snapshotMetadata(e){return Object.freeze({fromCache:!this.networkEnabled,hasPendingWrites:[...this.pending].some(n=>n.path===e)})}querySnapshotMetadata(){return Object.freeze({fromCache:!this.networkEnabled,hasPendingWrites:this.pending.size>0})}addSnapshotsInSyncObserver(e){return this.syncObservers.add(e),e(),()=>this.syncObservers.delete(e)}notifySnapshotDelivered(){this.syncScheduled||this.syncObservers.size===0||(this.syncScheduled=!0,queueMicrotask(()=>{this.syncScheduled=!1;for(const e of[...this.syncObservers])e()}))}}const Re=new WeakMap;function _(t){let e=Re.get(t);return e||(e=new hn,Re.set(t,e)),e}function te(t,e,n){return S(t,T("reference",e)),ue(t,e,n),t}function kn(t,...e){const n=F(t),r=v in t,s=r?void 0:pe(t),i=z(n);if(r){if(e.length===0)throw new TypeError("doc(db, path) requires at least one path segment.");const l=e.join("/"),d=i.doc(l),h=M(d,n,m=>m.doc(l));return te(h,l,n)}const a=A(t),o=e.length===0?a.doc():a.doc(e.join("/")),c=o.path,u=M(o,n,l=>l.doc(c));if(s){const l=tt(u,n,s);return te(l,c,n)}return te(u,c,n)}function qn(t,...e){const n=F(t),r=v in t;if(e.length===0)throw new TypeError("collection() requires at least one path segment.");if(r){const c=e.join("/"),u=z(n).collection(c);return M(u,n,l=>l.collection(c))}const s=A(t),i=e.join("/"),a=s.collection(i),o=a.path;return M(a,n,c=>c.collection(o))}function fn(t){return t instanceof Error&&"code"in t&&typeof t.code=="string"}function mn(t){if(t instanceof R||!fn(t))return t;const e={};t.denialContext!==void 0&&(e.denialContext=t.denialContext),t.remediation!==void 0&&(e.remediation=t.remediation);const n=new R(t.code,t.message,Object.keys(e).length===0?void 0:e);return t.denialContext!==void 0&&Object.assign(n,{denialContext:t.denialContext}),t.remediation!==void 0&&Object.assign(n,{remediation:t.remediation}),n}async function K(t){try{return await t()}catch(e){throw mn(e)}}async function En(t,e,n){const r=F(t),s=pe(t),i=s?s.toFirestore(e):e;return _(r).runWrite(()=>K(()=>me(r,t).set(i,n)),t.path)}async function Tn(t,e){const n=F(t);return _(n).runWrite(()=>K(()=>me(n,t).update(e)),t.path)}async function Rn(t){const e=F(t);return _(e).runWrite(()=>K(()=>me(e,t).delete()),t.path)}async function Fn(t,e){const n=F(t),r=pe(t),s=r?r.toFirestore(e):e,i=await _(n).runWrite(async()=>{const c=await K(()=>sn(n,t).add(s));return _(n).cachePath(c.path),c}),a=i.path,o=M(i,n,c=>c.doc(a));if(S(o,T("reference",a)),ue(o,a,n,o),r){const c=tt(o,n,r);return qt(o,c),c}return o}export{Cn as A,dn as B,un as C,nt as D,x as E,R as F,I as G,wn as H,pe as a,et as b,_ as c,kn as d,z as e,Sn as f,cn as g,P as h,bn as i,Me as j,_e as k,F as l,vn as m,me as n,mn as o,xn as p,M as q,gn as r,En as s,nn as t,A as u,tt as v,qn as w,Fn as x,Tn as y,Rn as z};