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

package/src/storage/reference.ts

@@ -18,6 +18,7 @@
  * collapsed. Empty path is legal — it's the root reference.
  */
 import { TARGET_SYMBOL, targetOf, type FirebaseStorage } from './service.js';
+import { refPathOf } from './url.js';
 
 /**
  * Public reference shape. Methods are inherited from the impl
@@ -37,7 +38,9 @@ export interface StorageReference {
 /**
  * Construct a reference. Two overloads matching Firebase:
  *
- *   `ref(storage, path?)`   — `path` is bucket-rooted. Omit for root.
+ *   `ref(storage, path?)`   — `path` is bucket-rooted. Omit for root. A
+ *                             `gs://` or download URL names its object, as
+ *                             `./url.ts` describes.
  *   `ref(parent, path)`     — `path` is relative to `parent.fullPath`.
  */
 export function ref(storage: FirebaseStorage, path?: string): StorageReference;
@@ -49,11 +52,11 @@ export function ref(
   if (isStorageReference(target)) {
     // Relative-to-parent overload.
     targetOf(target.storage);
-    return new SandboxStorageReference(target.storage, joinPaths(target.fullPath, path ?? ''));
+    return new SandboxStorageReference(target.storage, joinPaths(target.fullPath, refPathOf(path, false)));
   }
   // Storage-rooted overload.
   targetOf(target);
-  return new SandboxStorageReference(target, normalizePath(path ?? ''));
+  return new SandboxStorageReference(target, normalizePath(refPathOf(path, true)));
 }
 
 // ─── Sandbox impl ──────────────────────────────────────────────────

package/src/storage/remote-bytes.ts

@@ -0,0 +1,122 @@
+/**
+ * Storage bytes between a Node process and a hosted sandbox's HTTP byte route.
+ *
+ * Rules and the commit stay on the relay channel's RPC; the bytes move over
+ * HTTP. Uploads begin over the RPC, which returns the upload's own URL, send
+ * the object in slices with `Content-Range`, and finish over the RPC. Reads
+ * are a `GET` with the session token, optionally for a byte range.
+ */
+
+/** How a remote client reaches its host's byte route. */
+export interface RemoteByteRoute {
+  /** The host's HTTP origin. */
+  baseUrl: string;
+  /** The host's session token, which authorizes this process's reads. */
+  sessionToken(): Promise<string | null>;
+}
+
+/** The channel operations an upload needs. */
+interface OperationChannel {
+  op(op: { method: string } & Record<string, unknown>): Promise<unknown>;
+}
+
+const SLICE_BYTES = 4 * 1024 * 1024;
+const ROUTE_PREFIX = '/__pyric/storage/v0/b/';
+
+function failure(code: string, message: string): Error & { code: string } {
+  return Object.assign(new Error(`${code}: ${message}`), { code });
+}
+
+function routeFailure(status: number, path: string): Error & { code: string } {
+  const refused = status === 401 || status === 403;
+  if (refused) return failure('storage/unauthorized', `The host refused bytes for '${path}' (HTTP ${status}).`);
+  const missing = status === 404;
+  if (missing) return failure('storage/object-not-found', `Object '${path}' does not exist.`);
+  return failure('storage/unknown', `The host's byte route answered HTTP ${status} for '${path}'.`);
+}
+
+/** How many bytes a byte route answer says the host holds. */
+function receivedFrom(response: Response, size: number): number {
+  const complete = response.status === 200;
+  if (complete) return size;
+  const held = /^bytes=0-(\d+)$/.exec(response.headers.get('range') ?? '');
+  return held === null ? 0 : Number(held[1]) + 1;
+}
+
+export interface RemoteUploadRequest {
+  path: string;
+  data: Blob;
+  contentType?: string;
+  metadata?: Record<string, unknown>;
+  actAs?: unknown;
+}
+
+/** Upload over the byte route; resolves with the object's metadata from `finishUpload`. */
+export async function uploadOverByteRoute(channel: OperationChannel, route: RemoteByteRoute, request: RemoteUploadRequest): Promise<unknown> {
+  const { path, data, contentType, metadata, actAs } = request;
+  const begun = (await channel.op({
+    method: 'storage.beginUpload',
+    path,
+    size: data.size,
+    ...(contentType !== undefined ? { contentType } : {}),
+    ...(metadata !== undefined ? { metadata } : {}),
+    ...(actAs !== undefined ? { actAs } : {}),
+  })) as { uploadId: string; uploadUrl?: string };
+  const uploadUrl = begun.uploadUrl;
+  const unrouted = uploadUrl === undefined;
+  if (unrouted) throw failure('storage/unknown', 'The host began the upload without a byte route URL.');
+  const url = new URL(uploadUrl, route.baseUrl).href;
+  const finish = { method: 'storage.finishUpload', uploadId: begun.uploadId, ...(actAs !== undefined ? { actAs } : {}) };
+  try {
+    let offset = 0;
+    while (offset < data.size) {
+      const end = Math.min(offset + SLICE_BYTES, data.size);
+      const response = await fetch(url, {
+        method: 'PUT',
+        headers: { 'content-range': `bytes ${offset}-${end - 1}/${data.size}` },
+        body: data.slice(offset, end),
+      });
+      const accepted = response.status === 200 || response.status === 308 || response.status === 409;
+      if (!accepted) throw routeFailure(response.status, path);
+      offset = receivedFrom(response, data.size);
+    }
+    return await channel.op(finish);
+  } catch (error) {
+    try {
+      await channel.op({ method: 'storage.abortUpload', uploadId: begun.uploadId, ...(actAs !== undefined ? { actAs } : {}) });
+    } catch {
+      // The host discards staging a stopped host left, too.
+    }
+    throw error;
+  }
+}
+
+export interface RemoteReadRequest {
+  bucket: string;
+  path: string;
+  /** First byte, inclusive. */
+  start?: number;
+  /** Last byte, inclusive. */
+  end?: number;
+  /** Refuse bytes of any other generation. */
+  generation?: string;
+}
+
+/** A `GET` of an object, or a range of it, over the byte route. Throws unless the response carries bytes. */
+export async function fetchFromByteRoute(route: RemoteByteRoute, request: RemoteReadRequest): Promise<Response> {
+  const token = await route.sessionToken();
+  const missingToken = token === null || token === '';
+  if (missingToken) throw failure('unavailable', 'The host gave no session token for its byte route.');
+  const url = new URL(`${ROUTE_PREFIX}${encodeURIComponent(request.bucket)}/o/${encodeURIComponent(request.path)}`, route.baseUrl);
+  url.searchParams.set('alt', 'media');
+  const generation = request.generation;
+  if (generation !== undefined) url.searchParams.set('generation', generation);
+  const headers: Record<string, string> = { 'x-pyric-session-token': token };
+  const ranged = request.start !== undefined || request.end !== undefined;
+  if (ranged) headers.range = `bytes=${request.start ?? 0}-${request.end ?? ''}`;
+  const response = await fetch(url, { headers });
+  const pastEnd = response.status === 416;
+  if (pastEnd) return new Response(new Uint8Array(0), { status: 206 });
+  if (!response.ok) throw routeFailure(response.status, request.path);
+  return response;
+}

package/src/storage/resumable.ts

@@ -1,3 +1,4 @@
+import { storageTaskProgress, storageTaskResult } from '../sandbox/internal/storage-activity.js';
 /**
  * Resumable upload operations: `uploadBytesResumable` and related task observers.
  *
@@ -85,6 +86,7 @@ class UploadTaskImpl implements UploadTask {
   private _reject!: (error: Error | StorageError) => void;
   private _observers: TaskObserver[] = [];
   private _didIntermediateProgress = false;
+  private _committing = false;
   private _error: Error | StorageError | undefined;
   private readonly _ref: StorageReference;
   private readonly _blob: Blob;
@@ -267,7 +269,8 @@ class UploadTaskImpl implements UploadTask {
       if (hasNextCb) {
         const fn = nextCb as (snapshot: UploadTaskSnapshot) => unknown;
         try {
-          fn(this._snapshot);
+          storageTaskProgress(this);
+            fn(this._snapshot);
         } catch {
           // Observational
         }
@@ -279,6 +282,7 @@ class UploadTaskImpl implements UploadTask {
         if (hasNextCb) {
           const fn = nextCb as (snapshot: UploadTaskSnapshot) => unknown;
           try {
+            storageTaskProgress(this);
             fn(this._snapshot);
           } catch {
             // Observational
@@ -291,7 +295,8 @@ class UploadTaskImpl implements UploadTask {
           if (hasNextCb) {
             const fn = nextCb as (snapshot: UploadTaskSnapshot) => unknown;
             try {
-              fn(this._snapshot);
+              storageTaskProgress(this);
+            fn(this._snapshot);
             } catch {
               // Observational
             }
@@ -300,7 +305,8 @@ class UploadTaskImpl implements UploadTask {
           if (hasCompleteCb) {
             const fn = compCb as () => unknown;
             try {
-              fn();
+              storageTaskResult(this);
+            fn();
             } catch {
               // Observational
             }
@@ -376,6 +382,7 @@ class UploadTaskImpl implements UploadTask {
         if (hasNext) {
           const fn = obs.next as (snapshot: UploadTaskSnapshot) => unknown;
           try {
+            storageTaskProgress(this);
             fn(this._snapshot);
           } catch {
             // Ignore observer exceptions
@@ -410,6 +417,7 @@ class UploadTaskImpl implements UploadTask {
         if (hasComplete) {
           const fn = obs.complete as () => unknown;
           try {
+            storageTaskResult(this);
             fn();
           } catch {
             // Ignore observer exceptions
@@ -445,11 +453,13 @@ class UploadTaskImpl implements UploadTask {
   }
 
   private async _commitUpload(): Promise<void> {
+    if (this._committing) return;
     const isNotRunning = this._snapshot.state !== 'running';
     if (isNotRunning) {
       return;
     }
 
+    this._committing = true;
     try {
       const result = await uploadBytes(this._ref, this._blob, this._metadata, this._provenance);
       const isStillRunning = this._snapshot.state === 'running';
@@ -480,6 +490,9 @@ class UploadTaskImpl implements UploadTask {
         this._notifyObservers('error');
         this._reject(this._error);
       }
+    } finally {
+      this._committing = false;
+      if (this._snapshot.state === 'running') queueMicrotask(() => this._runStep());
     }
   }
 }

package/src/storage/rules-resolution.ts

@@ -1,4 +1,5 @@
-import type { Expr, MatchBlock, StorageRules } from './sandbox/rules.js';
+import { parseStorageRules, type Expr, type MatchBlock, type StorageRules } from './sandbox/rules.js';
+import { resolveModulesBrowser } from '../rules/modules/resolver-browser.js';
 
 export interface StorageRulesResolution {
   readonly targetService: 'firebase.storage';
@@ -75,6 +76,47 @@ function matchUsesFirestoreLookup(
   return match.children.some((child) => matchUsesFirestoreLookup(child, matchScope));
 }
 
+/** A storage rules source, lowered and parsed, with the record hosts read back. */
+export interface CompiledStorageRules {
+  readonly rules: StorageRules;
+  readonly resolution: StorageRulesResolution;
+}
+
+/**
+ * Compile a storage rules source into the ruleset the evaluator runs and the
+ * resolution record hosts read back, lowering `2+modules` source first.
+ * Throws on a source that does not parse or whose imports do not resolve, so
+ * a caller never installs a ruleset it could not compile.
+ */
+export function compileStorageRules(declared: string): CompiledStorageRules {
+  let source = declared;
+  let modules: readonly string[] = [];
+  let bundledModules: readonly string[] = [];
+  let moduleEvidenceIds: readonly string[] = [];
+  let rules = parseStorageRules(source);
+  if (rules._version === '2+modules') {
+    const resolved = resolveModulesBrowser(source);
+    if (!resolved.success) {
+      throw new SyntaxError(
+        `Storage rules module resolution failed (${resolved.error.code}): ${resolved.error.message}`,
+      );
+    }
+    source = resolved.data.resolved;
+    modules = resolved.data.modules;
+    bundledModules = resolved.data.bundledModules;
+    moduleEvidenceIds = resolved.data.evidenceIds;
+    rules = parseStorageRules(source);
+  }
+  const resolution = createStorageRulesResolution(
+    source,
+    modules,
+    bundledModules,
+    moduleEvidenceIds,
+    rules,
+  );
+  return { rules, resolution };
+}
+
 export function createStorageRulesResolution(
   source: string,
   modules: readonly string[],

package/src/storage/sandbox/persistence-state.ts

@@ -0,0 +1,71 @@
+import type { FirebaseStorage } from '../service.js';
+import { getStorageService } from '../service.js';
+import type { StoredMetadata } from '../persistence.js';
+import { arrayBufferToBase64, base64ToBytes } from '../base64.js';
+
+/** Lossless object records for a host persisting the handle's bucket. */
+export interface StorageStateRecord {
+  dataBase64: string;
+  blobType: string;
+  metadata: StoredMetadata;
+}
+
+export async function snapshotStorageState(storage: FirebaseStorage): Promise<StorageStateRecord[]> {
+  const service = await getStorageService(storage);
+  const records: StorageStateRecord[] = [];
+  for (const metadata of await service.backend.listByPrefix('')) {
+    const blob = await service.backend.getBlob(metadata.fullPath, metadata.bucket);
+    const isMissingBlob = blob === undefined;
+    if (isMissingBlob) throw new Error(`Storage object '${metadata.fullPath}' has metadata without bytes.`);
+    records.push({
+      dataBase64: arrayBufferToBase64(await blob.arrayBuffer()),
+      blobType: blob.type,
+      metadata: structuredClone(metadata),
+    });
+  }
+  return records;
+}
+
+/** An object whose bytes its backend holds in a file named by their SHA-256. */
+export interface StorageReferenceRecord {
+  sha256: string;
+  size: number;
+  blobType: string;
+  metadata: StoredMetadata;
+}
+
+/** Every object in the handle's bucket as a reference; reads no object bytes. */
+export async function referenceStorageState(storage: FirebaseStorage): Promise<StorageReferenceRecord[]> {
+  const service = await getStorageService(storage);
+  const references = service.backend.references;
+  const unsupported = references === undefined;
+  if (unsupported) throw new Error('This Storage backend keeps no object files to refer to.');
+  return references.call(service.backend);
+}
+
+/** Restore objects whose bytes the backend already holds, writing only their metadata. */
+export async function restoreStorageReferences(storage: FirebaseStorage, records: readonly StorageReferenceRecord[]): Promise<void> {
+  const service = await getStorageService(storage);
+  const putReference = service.backend.putReference;
+  const unsupported = putReference === undefined;
+  if (unsupported) throw new Error('This Storage backend keeps no object files to refer to.');
+  for (const record of records) {
+    await putReference.call(service.backend, record.metadata.fullPath, { sha256: record.sha256, size: record.size }, record.blobType, structuredClone(record.metadata));
+  }
+}
+
+/** Restore stored metadata directly, retaining generations and timestamps. */
+export async function restoreStorageState(storage: FirebaseStorage, records: readonly StorageStateRecord[]): Promise<void> {
+  const service = await getStorageService(storage);
+  for (const record of records) {
+    const bytes = Uint8Array.from(base64ToBytes(record.dataBase64));
+    const blob = new Blob([bytes], { type: record.blobType });
+    await service.backend.put(record.metadata.fullPath, blob, structuredClone(record.metadata));
+  }
+}
+
+/** Clear the bucket, including writes already queued but not yet visible to listings. */
+export async function resetStorageState(storage: FirebaseStorage): Promise<void> {
+  const service = await getStorageService(storage);
+  await service.backend.reset();
+}

package/src/storage/sandbox/rules-bindings.ts

@@ -0,0 +1,69 @@
+import { Timestamp } from '../../rules/simulator/wrappers/timestamp.js';
+import type { EvaluationInput, StorageResource } from './rules.js';
+import { RuleError } from './rules-values.js';
+import { normalizeAuthState } from '../../sandbox/sandbox-context.js';
+
+/**
+ * Build the `resource.*` binding from the existing-object record, converting
+ * the ISO-8601 time fields to timestamps so they compare against
+ * `request.time` (which {@link buildRequestObject} models the same way),
+ * against each other (`resource.timeCreated == resource.updated`), and take
+ * durations (`resource.timeCreated + duration.value(1, 'h')`).
+ *
+ * A field the record does not carry is left `undefined`, which the
+ * evaluator's property read reports as production's absent-property ERROR.
+ */
+export function buildResourceObject(resource: StorageResource): Record<string, unknown> {
+  return {
+    size: resource.size,
+    contentType: resource.contentType,
+    metadata: resource.metadata,
+    name: resource.name,
+    bucket: resource.bucket,
+    generation: resource.generation,
+    metageneration: resource.metageneration,
+    timeCreated: isoToTimestamp(resource.timeCreated),
+    updated: isoToTimestamp(resource.updated),
+  };
+}
+
+/** ISO-8601 → timestamp. An unparseable or absent value stays `undefined`
+ *  (→ absent-property error → deny) rather than becoming a NaN timestamp. */
+function isoToTimestamp(iso: string | undefined): Timestamp | undefined {
+  if (iso === undefined) return undefined;
+  const ms = Date.parse(iso);
+  if (Number.isNaN(ms)) return undefined;
+  return Timestamp.fromMillis(ms);
+}
+
+/** Build the `request.*` binding; `now` is the evaluation instant in epoch millis. */
+export function buildRequestObject(input: EvaluationInput, now: number): Record<string, unknown> {
+  const auth = input.request.auth;
+  let requestAuth: unknown;
+  if (auth === null || auth === undefined) {
+    // The production Storage engine represents anonymous auth as an absent
+    // property, not a usable null value. Ordinary `request.auth != null`
+    // gates still deny, while conditionals cannot incorrectly select a
+    // fallback branch from the synthetic null.
+    requestAuth = new RuleError('Property auth is undefined on object.');
+  } else {
+    // Projecting a top-level `tenant` into `token.firebase.tenant` is one
+    // cross-surface rule about an identity, not a Storage rules concern, so
+    // the sandbox context owns it and every surface reads the same shape.
+    requestAuth = normalizeAuthState(auth);
+  }
+  const request: Record<string, unknown> = {
+    auth: requestAuth,
+    // Production treats an operation without an incoming object (notably
+    // delete/read) as an absent binding. A direct null comparison errors just
+    // like a property read; neither may turn the missing value into an allow.
+    resource: input.request.resource ?? new RuleError('Property resource is undefined on object.'),
+    method: input.request.method,
+    path: input.request.path,
+    // The same Timestamp value `timestamp.date(...)` and `timestamp.value(...)`
+    // build, so `request.time < timestamp.date(2030, 1, 1)` compares
+    // timestamps and `request.time.year()` reads a component.
+    time: Timestamp.fromMillis(now),
+  };
+  return request;
+}

package/src/storage/sandbox/rules-collection-methods.ts

@@ -0,0 +1,161 @@
+import { FirestoreSet } from '../../rules/simulator/firestore-set.js';
+import { MapDiff } from '../../rules/simulator/mapdiff.js';
+import type { EvalCtx } from './rules-evaluator.js';
+import { RuleEvalError } from './rules-evaluation-error.js';
+import {
+  evalArguments,
+  evalValueMethod,
+  expectNoArguments,
+  functionNotFound,
+  type MethodCall,
+  type ReceiverMethod,
+  type ReceiverMethods,
+} from './rules-method-calls.js';
+import {
+  describeRulesType as describeType,
+  isRuleError as isErr,
+  isRulesMap,
+  rulesEquals,
+} from './rules-values.js';
+
+const SET_ALGEBRA = ['difference', 'intersection', 'union'] as const;
+type SetAlgebraMethod = (typeof SET_ALGEBRA)[number];
+
+const MAP_DIFF_KEY_SETS = ['addedKeys', 'affectedKeys', 'changedKeys', 'removedKeys', 'unchangedKeys'] as const;
+type MapDiffKeySet = (typeof MAP_DIFF_KEY_SETS)[number];
+
+/**
+ * `.size()` on the sized types: string length, list element count, map
+ * own-key count, Set member count, and the Bytes count the Bytes value
+ * answers for itself.
+ */
+function evalSize(receiver: unknown, expr: MethodCall): unknown {
+  expectNoArguments(expr);
+  if (typeof receiver === 'string' || Array.isArray(receiver)) return receiver.length;
+  if (isRulesMap(receiver)) return Object.keys(receiver).length;
+  if (receiver instanceof FirestoreSet) return receiver.size();
+  return evalValueMethod(receiver, expr);
+}
+
+/** `Map.keys()` returns the map's own keys and never exposes JS prototypes. */
+function evalMapKeys(receiver: unknown, expr: MethodCall): unknown {
+  expectNoArguments(expr);
+  if (!isRulesMap(receiver)) throw functionNotFound(expr.method);
+  return Object.keys(receiver);
+}
+
+/** `Map.get(key, default)` for the production-probed string-key form. */
+function evalMapGet(receiver: unknown, expr: MethodCall, ctx: EvalCtx): unknown {
+  if (!isRulesMap(receiver)) throw functionNotFound(expr.method);
+  if (expr.args.length !== 2) {
+    throw new RuleEvalError(`get() expects a key and default value`);
+  }
+  const args = evalArguments(expr, ctx);
+  if (isErr(args)) return args;
+  const [key, fallback] = args;
+  if (typeof key !== 'string') {
+    throw new RuleEvalError(`get() key must be a string`);
+  }
+  return Object.prototype.hasOwnProperty.call(receiver, key) ? receiver[key] : fallback;
+}
+
+/**
+ * `hasAll`, `hasAny`, and `hasOnly` on a List or Set receiver, with a List
+ * or Set argument, under Rules value equality.
+ */
+function evalMembership(receiver: unknown, expr: MethodCall, ctx: EvalCtx): unknown {
+  const members = membersOf(receiver);
+  if (members === undefined) throw functionNotFound(expr.method);
+  if (expr.args.length !== 1) {
+    throw new RuleEvalError(`${expr.method}() expects one list or set argument`);
+  }
+  const args = evalArguments(expr, ctx);
+  if (isErr(args)) return args;
+  const candidates = membersOf(args[0]);
+  if (candidates === undefined) {
+    throw new RuleEvalError(`${expr.method}() argument must be a list or set`);
+  }
+  const contains = (values: unknown[], value: unknown) => values.some((item) => rulesEquals(item, value));
+  if (expr.method === 'hasAll') return candidates.every((candidate) => contains(members, candidate));
+  if (expr.method === 'hasAny') return candidates.some((candidate) => contains(members, candidate));
+  return members.every((member) => contains(candidates, member));
+}
+
+/** The members of a List or Set, or undefined for any other value. */
+function membersOf(value: unknown): unknown[] | undefined {
+  if (Array.isArray(value)) return value;
+  if (value instanceof FirestoreSet) return value.toArray();
+  return undefined;
+}
+
+/** `List.toSet()`: the list's distinct members as a Set. */
+function evalToSet(receiver: unknown, expr: MethodCall): unknown {
+  expectNoArguments(expr);
+  if (!Array.isArray(receiver)) throw functionNotFound(expr.method);
+  return new FirestoreSet(receiver);
+}
+
+/**
+ * `Set.difference`, `Set.union`, and `Set.intersection`. They take a Set
+ * argument; production rejects a List argument with "Unsupported operation
+ * error" and a List receiver with "Function not found error", both captured
+ * by rules-storage-stdlib-sets-and-mapdiff.
+ */
+function evalSetAlgebra(receiver: unknown, expr: MethodCall, ctx: EvalCtx): unknown {
+  if (!(receiver instanceof FirestoreSet)) throw functionNotFound(expr.method);
+  if (expr.args.length !== 1) {
+    throw new RuleEvalError(`${expr.method}() expects one set argument`);
+  }
+  const args = evalArguments(expr, ctx);
+  if (isErr(args)) return args;
+  const [other] = args;
+  if (!(other instanceof FirestoreSet)) {
+    throw new RuleEvalError(
+      `Unsupported operation error. Received: set.${expr.method}(${describeType(other)}). Expected: set.${expr.method}(set).`,
+    );
+  }
+  return receiver[expr.method as SetAlgebraMethod](other);
+}
+
+/**
+ * `Map.diff(other)`: a MapDiff from `other` (the before state) to the
+ * receiver (the after state), as in
+ * `request.resource.metadata.diff(resource.metadata)`.
+ */
+function evalMapDiff(receiver: unknown, expr: MethodCall, ctx: EvalCtx): unknown {
+  if (!isRulesMap(receiver)) throw functionNotFound(expr.method);
+  if (expr.args.length !== 1) {
+    throw new RuleEvalError(`diff() expects one map argument`);
+  }
+  const args = evalArguments(expr, ctx);
+  if (isErr(args)) return args;
+  const [before] = args;
+  if (!isRulesMap(before)) {
+    throw new RuleEvalError(`diff() argument must be a map, got ${describeType(before)}`);
+  }
+  return new MapDiff(before, receiver);
+}
+
+/** The MapDiff key sets `addedKeys()` through `unchangedKeys()`, each a Set. */
+function evalMapDiffKeySet(receiver: unknown, expr: MethodCall): unknown {
+  expectNoArguments(expr);
+  if (!(receiver instanceof MapDiff)) throw functionNotFound(expr.method);
+  return receiver[expr.method as MapDiffKeySet]();
+}
+
+function methodsNamed(names: readonly string[], method: ReceiverMethod): ReceiverMethods {
+  return Object.fromEntries(names.map((name) => [name, method]));
+}
+
+export const collectionMethods: ReceiverMethods = {
+  diff: evalMapDiff,
+  get: evalMapGet,
+  hasAll: evalMembership,
+  hasAny: evalMembership,
+  hasOnly: evalMembership,
+  keys: evalMapKeys,
+  size: evalSize,
+  toSet: evalToSet,
+  ...methodsNamed(SET_ALGEBRA, evalSetAlgebra),
+  ...methodsNamed(MAP_DIFF_KEY_SETS, evalMapDiffKeySet),
+};