pyric 0.1.0-alpha.21 → 0.1.0-alpha.24

package/src/firestore/sandbox/admin-compat/query.ts

@@ -1,3 +1,4 @@
+import { captureIndexQuery } from '../../../rules/indexes/query-analysis.js';
 /** Admin-compatible query builders and snapshot shaping.
  * Candidate gathering, rule enforcement, and execution live behind
  * `LocalEnvironment.runQuery`; this adapter only builds immutable plan
@@ -7,6 +8,9 @@ import type { LocalEnvironment } from 'pyric/sandbox/internal';
 import { translateReadData } from './snapshots.js';
 import { getSnapshotField } from './field-path.js';
 import { activityValue } from '../../../firestore/sandbox/activity-query-value.js';
+import { activityDisplayValue } from '../../../firestore/sandbox/activity-query-display.js';
+import { activityStructuralIdentity } from '../activity-structural-identity.js';
+import type { SdkActivitySource } from '../../../sandbox/internal/sdk-activity.js';
 import {
   executionCursor,
   executionFilter,
@@ -25,8 +29,6 @@ import {
 import type { QueryConstraintPlan } from '../snapshot-listeners.js';
 import {
   normalizedQueryOrders,
-  type QueryFilter,
-  type QueryCursor,
   type QueryExecutionSpec,
   type QueryOrderClause,
   type QueryScope,
@@ -127,13 +129,6 @@ function cursorValuesFromSnapshot(
 // Public surface — QueryImpl.
 // ─────────────────────────────────────────────────────────────────────────
 
-/**
- * Cursor position along the orderBy fields. `values` is positional —
- * `values[i]` compares against `orders[i].field`. `inclusive`
- * distinguishes startAt/endAt (true) from startAfter/endBefore (false).
- */
-type Cursor = QueryCursor;
-
 export class QueryImpl implements Query {
   protected readonly env: LocalEnvironment;
   protected readonly auth: AuthContext;
@@ -186,14 +181,22 @@ export class QueryImpl implements Query {
   }
 
   orderBy(field: string, direction: OrderDirection = 'asc'): Query {
+    const hasInvalidDirection = direction !== 'asc' && direction !== 'desc';
+    if (hasInvalidDirection) {
+      throw new FirestoreCompatError({
+        code: 'invalid-argument', message: "orderBy() direction must be 'asc' or 'desc'.",
+      });
+    }
     return this.clone({ orders: [...this.orders, { field, direction }] });
   }
 
   limit(n: number): Query {
+    assertFiniteLimit(n);
     return this.clone({ limitCount: n, limitFromEnd: false });
   }
 
   limitToLast(n: number): Query {
+    assertFiniteLimit(n);
     return this.clone({ limitCount: n, limitFromEnd: true });
   }
 
@@ -271,6 +274,18 @@ export class QueryImpl implements Query {
     return { kind: 'collection', path: this.collectionPath };
   }
 
+  /** SDK diagnostics reuse the engine's captured query identity without reading operands again. */
+  sdkActivitySource(): SdkActivitySource {
+    const scope = this.queryScope();
+    return {
+      service: 'firestore',
+      target: scope.kind === 'collection' ? scope.path : scope.collectionId,
+      key: activityStructuralIdentity({ scope, query: this.activityQuery() }),
+      isQuery: true,
+      indexQuery: captureIndexQuery(scope.kind === 'collection' ? scope.path : scope.collectionId, scope.kind === 'collection-group', this.clauses, this.orders),
+    };
+  }
+
   /**
    * Submit the plan and return the engine's fully executed rows. `get()` and
    * `aggregate()` both run through this rule-enforced path (FS-B1 / RULES-B1), so query
@@ -305,13 +320,25 @@ export class QueryImpl implements Query {
    * Full executable identity for activity monitoring. The rules-proof
    * projection intentionally drops OR branches, rich operands, cursor
    * detail, and most ordering, so it cannot safely identify repeated reads.
+   *
+   * `value` is the digest identity that comparison uses; `display` is the
+   * bounded projection of the same operand's construction-time snapshot, for
+   * a surface that prints the query back to the developer. Both derive from
+   * one captured operand, so equal queries still produce equal identities.
    */
   protected activityQuery(): unknown {
-    const filter = (value: QueryFilter): unknown => value.kind === 'where'
-      ? { kind: 'where', field: value.field, op: value.op, value: activityValue(value.value) }
+    const filter = (value: ComparableQueryFilter): unknown => value.kind === 'where'
+      ? {
+        kind: 'where',
+        field: value.field,
+        op: value.op,
+        value: activityValue(value.value),
+        display: activityDisplayValue(value.comparisonValue.value),
+      }
       : { kind: value.kind, filters: value.filters.map(filter) };
-    const cursor = (value: Cursor | undefined): unknown => value === undefined ? null : {
+    const cursor = (value: ComparableCursor | undefined): unknown => value === undefined ? null : {
       values: value.values.map((item) => activityValue(item)),
+      display: value.comparisonValues.map((item) => activityDisplayValue(item.value)),
       inclusive: value.inclusive,
       fromSnapshot: value.fromSnapshot,
     };
@@ -496,3 +523,10 @@ function computeAggregate(
   // average — undefined for empty/all-non-numeric sets
   return n === 0 ? null : sum / n;
 }
+
+function assertFiniteLimit(n: number): void {
+  const hasInvalidLimit = !Number.isFinite(n);
+  if (hasInvalidLimit) {
+    throw new FirestoreCompatError({ code: 'invalid-argument', message: 'Query limit must be a finite number.' });
+  }
+}

package/src/firestore/sandbox/admin-compat/read-translation.ts

@@ -20,13 +20,22 @@ import {
   Bytes as InternalBytes,
   LatLng as InternalLatLng,
   Vector as InternalVector,
+  Reference as InternalReference,
 } from 'pyric/rules/internal';
 import { Timestamp as CompatTimestamp, type DocumentData } from './types.js';
+import { registerReferenceQueryValue } from '../query-value-registry.js';
 
 function translateValue(value: unknown): unknown {
-  if (value instanceof InternalTimestamp) {
+  const isTimestamp = value instanceof InternalTimestamp;
+  if (isTimestamp) {
     return new CompatTimestamp(value.seconds, value.nanos);
   }
+  const isReference = value instanceof InternalReference;
+  if (isReference) {
+    // Stored values have reference identity but no client connection owner.
+    registerReferenceQueryValue(value, value.path);
+    return value;
+  }
   // Bytes + LatLng wrappers (rules-internal) ride through the read path
   // as their instance form. The `pyric/firestore` modular layer does
   // the final conversion to `firebase/firestore`'s `Bytes` / `GeoPoint`
@@ -35,13 +44,16 @@ function translateValue(value: unknown): unknown {
   // `instanceof` against `pyric/rules`. Without these
   // short-circuits, the generic object walk below would destructure the
   // class instance into a plain `{...}` and erase the type.
-  if (value instanceof InternalBytes) return value;
-  if (value instanceof InternalLatLng) return value;
-  if (value instanceof InternalVector) return value;
-  if (Array.isArray(value)) {
+  const isPreservedScalar = value instanceof InternalBytes
+    || value instanceof InternalLatLng
+    || value instanceof InternalVector;
+  if (isPreservedScalar) return value;
+  const isArray = Array.isArray(value);
+  if (isArray) {
     return value.map(translateValue);
   }
-  if (value && typeof value === 'object') {
+  const isMap = value !== null && typeof value === 'object';
+  if (isMap) {
     // Rebuild via `Object.fromEntries` (CreateDataProperty semantics) rather
     // than `out[k] = …`: a stored field literally named `__proto__` would,
     // through bare bracket assignment, invoke the prototype accessor and

package/src/firestore/sandbox/admin-compat/transaction.ts

@@ -30,6 +30,7 @@ import {
   type DocumentSnapshot,
   type Query,
   type QuerySnapshot,
+  type SetOptions,
   type Transaction,
 } from './types.js';
 
@@ -50,13 +51,15 @@ export class TransactionImpl implements Transaction {
   get(ref: DocumentReference): Promise<DocumentSnapshot>;
   get(query: Query): Promise<QuerySnapshot>;
   async get(refOrQuery: DocumentReference | Query): Promise<DocumentSnapshot | QuerySnapshot> {
-    if (isQuery(refOrQuery)) {
+    const readsQuery = isQuery(refOrQuery);
+    if (readsQuery) {
       // Run the query through the wrapper's normal path. In the
       // single-threaded simulator, env.listDocuments and simTx.get see
       // the same state snapshot, so registering reads after-the-fact
       // is consistent.
       const snap = await refOrQuery.get();
-      if (snap.size > 0) {
+      const hasDocuments = snap.size > 0;
+      if (hasDocuments) {
         // Registers the touched paths in the tx's read set so the
         // simulator's commit-time read-after-write check sees them.
         // Throws ReadAfterWriteError if any tx.set/update/delete
@@ -71,8 +74,15 @@ export class TransactionImpl implements Transaction {
     return makeDocSnapshot(refOrQuery, data);
   }
 
-  set(ref: DocumentReference, data: DocumentData): Transaction {
-    this.simTx.set(ref.path, data);
+  set(ref: DocumentReference, data: DocumentData, options?: SetOptions): Transaction {
+    const mergeFields = options?.mergeFields;
+    const hasFieldMask = mergeFields !== undefined;
+    if (hasFieldMask) {
+      this.simTx.set(ref.path, data, { mergeFields });
+      return this;
+    }
+    const mergesAllFields = options?.merge === true;
+    this.simTx.set(ref.path, data, mergesAllFields ? true : undefined);
     return this;
   }
 

package/src/firestore/sandbox/admin-compat/types.ts

@@ -16,11 +16,7 @@
  */
 
 export { FirestoreCompatError } from '../firestore-compat-error.js';
-import {
-  boundedActivityIdentity,
-  registerActivityValue,
-} from '../../../firestore/sandbox/activity-value-registry.js';
-import { registerQueryValue } from '../../../firestore/sandbox/query-value-registry.js';
+export { Timestamp } from '../../timestamp.js';
 import type {
   QueryOrderDirection,
   QueryWhereFilterOp,
@@ -59,18 +55,17 @@ export interface OperationOptions {
  *
  *   - default (neither flag set) → REPLACE the existing document
  *     entirely. Firestore default for `set()`.
- *   - `{ merge: true }` → shallow-merge every top-level field in
+ *   - `{ merge: true }` → merge the nested leaf fields in
  *     `data` into the existing document. Fields not in `data` are
  *     preserved. Rule eval still runs the `update` clause when the
  *     doc exists.
  *   - `{ mergeFields: [...] }` → project `data` down to just the
- *     listed top-level fields, then merge. Other fields in `data` are
+ *     listed field paths, then merge. Other fields in `data` are
  *     ignored; other fields in the existing doc are preserved.
  *
  * `merge` and `mergeFields` are mutually exclusive at the JS-SDK
  * level. We don't currently enforce the constraint — if both are
- * provided, `mergeFields` wins (matches the JS SDK's effective
- * behavior).
+ * provided, `mergeFields` wins. This is a known validation gap.
  */
 export interface SetOptions extends OperationOptions {
   merge?: boolean;
@@ -222,7 +217,7 @@ export interface CollectionReference extends Query {
 }
 
 export interface WriteBatch {
-  set(ref: DocumentReference, data: DocumentData): WriteBatch;
+  set(ref: DocumentReference, data: DocumentData, options?: SetOptions): WriteBatch;
   update(ref: DocumentReference, data: DocumentData): WriteBatch;
   delete(ref: DocumentReference): WriteBatch;
   commit(opts?: OperationOptions): Promise<void>;
@@ -236,7 +231,7 @@ export interface Transaction {
   // lands.
   get(ref: DocumentReference): Promise<DocumentSnapshot>;
   get(query: Query): Promise<QuerySnapshot>;
-  set(ref: DocumentReference, data: DocumentData): Transaction;
+  set(ref: DocumentReference, data: DocumentData, options?: SetOptions): Transaction;
   update(ref: DocumentReference, data: DocumentData): Transaction;
   delete(ref: DocumentReference): Transaction;
 }
@@ -299,83 +294,6 @@ export class FieldValue {
   }
 }
 
-// ─────────────────────────────────────────────────────────────────────────
-// Timestamp — Admin SDK shape (`seconds` + `nanoseconds`). Distinct from
-// the rules-internal Timestamp at `simulator/wrappers/timestamp.ts` which
-// uses `nanos` and carries evaluator hooks (binaryOp/callMethod). Both
-// round-trip through the same `__type:'timestamp'` discriminator on the
-// wire; the compat class is the user-facing surface.
-// ─────────────────────────────────────────────────────────────────────────
-
-export class Timestamp {
-  constructor(
-    public readonly seconds: number,
-    public readonly nanoseconds: number,
-  ) {
-    registerActivityValue(
-      this,
-      boundedActivityIdentity('timestamp', String(seconds), '\0', String(nanoseconds)),
-    );
-    registerQueryValue(this, Object.freeze({
-      type: 'timestamp',
-      seconds,
-      nanoseconds,
-    }), () => new Timestamp(seconds, nanoseconds));
-  }
-  static now(): Timestamp {
-    return Timestamp.fromMillis(Date.now());
-  }
-  static fromDate(d: Date): Timestamp {
-    return Timestamp.fromMillis(d.getTime());
-  }
-  static fromMillis(ms: number): Timestamp {
-    // FS-B12 — derive nanoseconds as `floor((ms - seconds*1000) * 1e6)` so
-    // the value is ALWAYS non-negative (matching `fb.Timestamp.fromMillis`).
-    // The old `(ms % 1000) * 1e6` produced negative nanos for negative
-    // millis, so `fromMillis(-500)` round-tripped to -1500 via toMillis().
-    const seconds = Math.floor(ms / 1000);
-    const nanoseconds = Math.floor((ms - seconds * 1000) * 1_000_000);
-    return new Timestamp(seconds, nanoseconds);
-  }
-  toDate(): Date {
-    return new Date(this.toMillis());
-  }
-  toMillis(): number {
-    // FS-B12 — `nanoseconds / 1e6` (matching `fb.Timestamp.toMillis`), not
-    // `floor(nanoseconds / 1e6)`; the floor dropped sub-millisecond nanos
-    // and broke the negative-millis round-trip.
-    return this.seconds * 1000 + this.nanoseconds / 1_000_000;
-  }
-  /** FS-B12 — value equality, mirroring `fb.Timestamp.isEqual`. */
-  isEqual(other: Timestamp): boolean {
-    return other.seconds === this.seconds && other.nanoseconds === this.nanoseconds;
-  }
-  /** FS-B12 — textual form, mirroring `fb.Timestamp.toString`. */
-  toString(): string {
-    return `Timestamp(seconds=${this.seconds}, nanoseconds=${this.nanoseconds})`;
-  }
-  /** FS-B12 — JSON form, mirroring `fb.Timestamp.toJSON`. */
-  toJSON(): { type: string; seconds: number; nanoseconds: number } {
-    return {
-      type: 'firestore/timestamp/1.0',
-      seconds: this.seconds,
-      nanoseconds: this.nanoseconds,
-    };
-  }
-  /**
-   * FS-B12 — primitive coercion for `<`/`<=`/`>=`/`>` comparisons, mirroring
-   * `fb.Timestamp.valueOf`: a zero-padded `<seconds>.<nanoseconds>` string
-   * (seconds offset by MIN_SECONDS so it stays non-negative and lexically
-   * ordered).
-   */
-  valueOf(): string {
-    const MIN_SECONDS = -62_135_596_800;
-    const adjustedSeconds = this.seconds - MIN_SECONDS;
-    const formattedSeconds = String(adjustedSeconds).padStart(12, '0');
-    const formattedNanoseconds = String(this.nanoseconds).padStart(9, '0');
-    return `${formattedSeconds}.${formattedNanoseconds}`;
-  }
-}
 
 // ─────────────────────────────────────────────────────────────────────────
 // Simulator error types re-exported for the admin-compatible surface.

package/src/firestore/sandbox/atomic-state.ts

@@ -0,0 +1,112 @@
+import type { BatchOperation, BatchResult, DocBacking, DocumentData } from './document-store.js';
+import { resolveValueTree, partitionDeletes } from './value-resolver.js';
+import { applyUpdate } from './field-merge.js';
+
+/** Validate the ordered writes, apply them, and report each committed version change. */
+export function applyAtomicBatch(
+  documents: DocBacking,
+  operations: BatchOperation[],
+  onWrite: (path: string) => void,
+): BatchResult {
+  // Later operations see earlier creates/deletes without mutating storage.
+  const errors: { index: number; error: string }[] = [];
+  const projectedExistence = new Map<string, boolean>();
+  for (const [index, op] of operations.entries()) {
+    const documentExists = projectedExistence.get(op.path) ?? documents.has(op.path);
+    switch (op.method) {
+      case 'create':
+        if (documentExists) {
+          errors.push({ index, error: `Document '${op.path}' already exists` });
+        }
+        projectedExistence.set(op.path, true);
+        break;
+      case 'update': {
+        const documentMissing = !documentExists;
+        if (documentMissing) {
+          errors.push({ index, error: `Document '${op.path}' does not exist` });
+        }
+        break;
+      }
+      case 'delete':
+        // Delete-missing is a no-op in production: `WriteBatch.delete`
+        // and `Transaction.delete` on an absent doc resolve cleanly,
+        // matching the single-op `deleteDoc` contract (matrix row
+        // Firestore #39, oracle:
+        // packages/conformance/observations/firestore/firestore-deletedoc-missing.json).
+        // Apply phase below tolerates the absence via `documents.delete`,
+        // which is itself a no-op on a missing key.
+        projectedExistence.set(op.path, false);
+        break;
+      case 'set':
+        projectedExistence.set(op.path, true);
+        break;
+    }
+  }
+
+  const hasInvalidOperations = errors.length > 0;
+  if (hasInvalidOperations) {
+    return { success: false, errors };
+  }
+
+  // Capture prior state for all affected documents (for undo)
+  const priorStates = new Map<string, DocumentData | null>();
+  for (const op of operations) {
+    const isFirstWrite = !priorStates.has(op.path);
+    if (isFirstWrite) {
+      const documentExists = documents.has(op.path);
+      let priorData: DocumentData | null = null;
+      if (documentExists) priorData = { ...documents.get(op.path) };
+      priorStates.set(op.path, priorData);
+    }
+  }
+
+  // Apply all operations. Each non-delete write routes through the
+  // resolver with the correct prior — captured above, so resolution
+  // order within the batch sees the same prior the rules saw. Item 2:
+  // every non-delete branch partitions DELETE_FIELD markers out via
+  // partitionDeletes so they don't leak into storage.
+  for (const op of operations) {
+    switch (op.method) {
+      case 'create': {
+        const resolved = resolveValueTree({ ...op.data }, {
+          path: op.path,
+          method: 'create',
+          prior: null,
+        });
+        const { writes } = partitionDeletes(resolved);
+        documents.set(op.path, writes);
+        break;
+      }
+      case 'update': {
+        const existing = documents.get(op.path);
+        const documentMissing = existing === undefined;
+        if (documentMissing) throw new Error(`Validated document '${op.path}' disappeared during atomic application`);
+        const resolved = resolveValueTree({ ...op.data }, {
+          path: op.path,
+          method: 'update',
+          prior: existing,
+        });
+        // FS-B5: dot-path FieldPath expansion + sibling-preserving merge.
+        documents.set(op.path, applyUpdate(existing, resolved));
+        break;
+      }
+      case 'set': {
+        const priorForSet = priorStates.get(op.path) ?? null;
+        const resolved = resolveValueTree({ ...op.data }, {
+          path: op.path,
+          method: 'set',
+          prior: priorForSet,
+        });
+        const { writes } = partitionDeletes(resolved);
+        documents.set(op.path, writes);
+        break;
+      }
+      case 'delete':
+        documents.delete(op.path);
+        break;
+    }
+    onWrite(op.path);
+  }
+
+  return { success: true, priorStates };
+}