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

package/src/sandbox/checkpoints/capture.ts

@@ -0,0 +1,77 @@
+/**
+ * Taking a checkpoint and putting one back.
+ *
+ * Both are one call onto the full-state seam, so a checkpoint holds exactly
+ * what {@link captureFullState} reads and restoring one leaves the sandbox
+ * exactly where {@link applyFullState} puts it. There is no second definition
+ * of what "the whole sandbox" means, which is what keeps a checkpoint from
+ * quietly dropping a service the sandbox grew.
+ *
+ * The counts are derived from the state rather than read from the services a
+ * second time, so a listing can never disagree with the state beside it.
+ */
+
+import { applyFullState, captureFullState, type FullSandboxState, type FullStateCaptureOptions } from '../full-state.js';
+import type { LocalSandbox } from '../types/service.js';
+import { getClock } from '../clock.js';
+import { CHECKPOINT_FORMAT, type Checkpoint, type CheckpointCounts } from './types.js';
+import { assertCheckpointState } from './validation.js';
+
+/** True when a JSON value is a plain object with keys to count. */
+function isCountableTree(value: unknown): value is Record<string, unknown> {
+  return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+
+/**
+ * How many top-level keys the Realtime Database tree holds. The state carries
+ * the backend's persistence envelope, whose `data` key is the tree itself, so
+ * the count is taken there rather than over the envelope's own keys.
+ */
+function databaseEntryCount(database: FullSandboxState['database']): number {
+  if (!isCountableTree(database)) return 0;
+  const tree = isCountableTree(database.data) ? database.data : database;
+  return Object.keys(tree).length;
+}
+
+/** How much each service holds in one state. */
+export function countsOf(state: FullSandboxState): CheckpointCounts {
+  return {
+    firestore: Object.keys(state.firestore).length,
+    database: databaseEntryCount(state.database),
+    storage: state.storage.length,
+    auth: state.auth.users.length,
+  };
+}
+
+/**
+ * Read the whole sandbox into a checkpoint.
+ *
+ * A pure read: nothing in the sandbox changes, and two captures with no
+ * intervening write are the same value apart from `at`.
+ */
+export async function captureCheckpoint(sandbox: LocalSandbox, options: FullStateCaptureOptions = {}): Promise<Checkpoint> {
+  const state = await captureFullState(sandbox, options);
+  return { format: CHECKPOINT_FORMAT, at: getClock(sandbox).now(), counts: countsOf(state), state };
+}
+
+/**
+ * Replace the whole sandbox with what a checkpoint holds.
+ *
+ * A total replace, not a merge: state the sandbox holds that the checkpoint
+ * does not is gone when this returns.
+ *
+ * The operation log is reset first, and this is the difference between
+ * restoring a checkpoint and promoting a branch. Both write a full state, but
+ * a promotion continues the sandbox's history and a restore declares that the
+ * history since the checkpoint did not happen. A cursor a reader holds from
+ * before the restore names an event in a log that is gone, and the reset is
+ * what lets the log say so rather than reading like a continuation.
+ */
+export async function restoreCheckpoint(
+  sandbox: LocalSandbox,
+  checkpoint: Checkpoint,
+): Promise<void> {
+  assertCheckpointState(checkpoint.state);
+  sandbox.reset();
+  await applyFullState(sandbox, checkpoint.state);
+}

package/src/sandbox/checkpoints/directory-backend.ts

@@ -0,0 +1,110 @@
+/**
+ * Checkpoints kept as files under a project directory.
+ *
+ * One file per checkpoint, `<project>/.pyric/state/checkpoints/<name>.json`,
+ * named by the checkpoint. The directory is the index: the listing reads it
+ * rather than a manifest, so a checkpoint copied into the directory by hand is
+ * one the listing finds and a checkpoint deleted from it is one the listing
+ * does not.
+ *
+ * Each write lands through a temporary file and a rename, so a process that
+ * dies mid-write leaves the previous checkpoint intact rather than a truncated
+ * one. A file that does not parse, or that carries no format tag this module
+ * wrote, is skipped by the listing rather than failing it, so one unrelated
+ * JSON file in the directory does not take the whole listing down.
+ *
+ * This module reads and writes files, so it is Node only and is published at
+ * the `pyric/sandbox/checkpoints/directory` subpath rather than from the
+ * browser barrel `pyric/sandbox`.
+ */
+
+import { existsSync, mkdirSync, readFileSync, readdirSync, renameSync, rmSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+import {
+  CHECKPOINT_NAME_PATTERN,
+  assertCheckpointName,
+  isCheckpointEnvelope,
+  type Checkpoint,
+  type CheckpointBackend,
+  type CheckpointListing,
+} from './types.js';
+
+/** Where checkpoints live, relative to the project directory. */
+export const CHECKPOINT_STORE_RELATIVE = join('.pyric', 'state', 'checkpoints');
+
+const FILE_SUFFIX = '.json';
+
+/** The directory one project's checkpoints occupy. */
+function checkpointsDirectory(projectDir: string): string {
+  return join(projectDir, CHECKPOINT_STORE_RELATIVE);
+}
+
+/** The file one checkpoint occupies. */
+function checkpointPath(projectDir: string, name: string): string {
+  assertCheckpointName(name);
+  return join(checkpointsDirectory(projectDir), `${name}${FILE_SUFFIX}`);
+}
+
+/** One checkpoint read off disk, or null when the file is absent or not one. */
+function readCheckpointFile(path: string): Checkpoint | null {
+  if (!existsSync(path)) return null;
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(readFileSync(path, 'utf8'));
+  } catch {
+    return null;
+  }
+  if (!isCheckpointEnvelope(parsed)) return null;
+  return parsed;
+}
+
+/** Every name the directory holds that could be a checkpoint, ordered. */
+function storedNames(projectDir: string): string[] {
+  const dir = checkpointsDirectory(projectDir);
+  if (!existsSync(dir)) return [];
+  return readdirSync(dir)
+    .filter((file) => file.endsWith(FILE_SUFFIX))
+    .map((file) => file.slice(0, -FILE_SUFFIX.length))
+    .filter((name) => CHECKPOINT_NAME_PATTERN.test(name))
+    .sort((a, b) => a.localeCompare(b));
+}
+
+/**
+ * Keep checkpoints as files under `projectDir`.
+ *
+ * @param projectDir The project the checkpoints belong to. The directory is
+ *                   created on the first write and is not required to exist.
+ */
+export function directoryCheckpointBackend(projectDir: string): CheckpointBackend {
+  return {
+    async write(name, checkpoint) {
+      const path = checkpointPath(projectDir, name);
+      mkdirSync(checkpointsDirectory(projectDir), { recursive: true });
+      const pending = `${path}.pending-${process.pid}`;
+      writeFileSync(pending, `${JSON.stringify(checkpoint)}\n`, 'utf8');
+      renameSync(pending, path);
+    },
+
+    async read(name) {
+      return readCheckpointFile(checkpointPath(projectDir, name));
+    },
+
+    async list() {
+      const listed: CheckpointListing[] = [];
+      for (const name of storedNames(projectDir)) {
+        const checkpoint = readCheckpointFile(checkpointPath(projectDir, name));
+        if (checkpoint === null) continue;
+        listed.push({ name, at: checkpoint.at, counts: checkpoint.counts });
+      }
+      return listed;
+    },
+
+    async remove(name) {
+      const path = checkpointPath(projectDir, name);
+      if (!existsSync(path)) return false;
+      rmSync(path, { force: true });
+      return true;
+    },
+  };
+}

package/src/sandbox/checkpoints/index.ts

@@ -0,0 +1,32 @@
+/**
+ * `pyric/sandbox/checkpoints` is the saved-state primitive's public surface.
+ *
+ * Re-exports only. The capture and restore live in `capture.ts`, the four
+ * host-facing operations in `saved-states.ts`, the shapes and the backend seam
+ * in `types.ts`, and the record-store backend in `record-backend.ts`. The
+ * directory backend is published from its own subpath because it reads files.
+ */
+export { captureCheckpoint, countsOf, restoreCheckpoint } from './capture.js';
+export { recordCheckpointBackend } from './record-backend.js';
+export {
+  checkpointNames,
+  listCheckpoints,
+  readCheckpoint,
+  removeCheckpoint,
+  restoreNamedCheckpoint,
+  saveCheckpoint,
+} from './saved-states.js';
+export type { SavedCheckpoint } from './saved-states.js';
+export {
+  CHECKPOINT_FORMAT,
+  CHECKPOINT_NAME_PATTERN,
+  CheckpointNameError,
+  assertCheckpointName,
+  isCheckpointEnvelope,
+} from './types.js';
+export type {
+  Checkpoint,
+  CheckpointBackend,
+  CheckpointCounts,
+  CheckpointListing,
+} from './types.js';

package/src/sandbox/checkpoints/record-backend.ts

@@ -0,0 +1,109 @@
+/**
+ * Checkpoints kept in a page's own record store, which in a browser is
+ * IndexedDB.
+ *
+ * One record per checkpoint under its own key, plus a registry record holding
+ * the ordered names. The registry exists because a
+ * {@link PersistenceBackend} lists the records within a key rather than the
+ * keys themselves, so without it there would be no way to answer "what
+ * checkpoints are there" at all.
+ *
+ * The keyspace is prefixed, so a checkpoint never collides with the instance
+ * id, the session record, or a service's own persisted state in the same
+ * store. Nothing here touches the filesystem, so this backend is the one a
+ * worker or a page uses.
+ */
+
+import type { PersistenceBackend } from '../persistence/types.js';
+import {
+  assertCheckpointName,
+  isCheckpointEnvelope,
+  type Checkpoint,
+  type CheckpointBackend,
+  type CheckpointListing,
+} from './types.js';
+
+/** The key one checkpoint's record occupies, keyed by its name. */
+const CHECKPOINT_PREFIX = 'pyric:checkpoint:';
+
+/** The key holding the ordered checkpoint names, since a store lists records, not keys. */
+const CHECKPOINT_REGISTRY_KEY = 'pyric:checkpoints';
+
+/** The one record id under each key, so a key holds exactly one value. */
+const RECORD_ID = 'value';
+
+/** The names the registry record holds, empty when it holds none. */
+async function registeredNames(store: PersistenceBackend): Promise<string[]> {
+  const record = (await store.getRecord(CHECKPOINT_REGISTRY_KEY, RECORD_ID)) as
+    | { value?: unknown }
+    | null
+    | undefined;
+  if (!Array.isArray(record?.value)) return [];
+  return (record.value as unknown[]).filter((name): name is string => typeof name === 'string');
+}
+
+/** Replace the registry with `names`, sorted, so every listing reads one order. */
+async function writeRegistry(store: PersistenceBackend, names: string[]): Promise<void> {
+  const sorted = [...new Set(names)].sort((a, b) => a.localeCompare(b));
+  await store.putRecords(CHECKPOINT_REGISTRY_KEY, new Map([[RECORD_ID, { value: sorted }]]));
+}
+
+/** One checkpoint read back, or null when the key holds nothing this backend wrote. */
+async function readCheckpointRecord(
+  store: PersistenceBackend,
+  name: string,
+): Promise<Checkpoint | null> {
+  const record = (await store.getRecord(CHECKPOINT_PREFIX + name, RECORD_ID)) as
+    | { value?: unknown }
+    | null
+    | undefined;
+  const held = record?.value;
+  if (!isCheckpointEnvelope(held)) return null;
+  return held;
+}
+
+/**
+ * Keep checkpoints as records in `store`.
+ *
+ * @param store The record store the host already persists into, which in the
+ *              served worker is the page's own IndexedDB.
+ */
+export function recordCheckpointBackend(store: PersistenceBackend): CheckpointBackend {
+  return {
+    async write(name, checkpoint) {
+      assertCheckpointName(name);
+      await store.putRecords(
+        CHECKPOINT_PREFIX + name,
+        new Map([[RECORD_ID, { value: checkpoint }]]),
+      );
+      await writeRegistry(store, [...(await registeredNames(store)), name]);
+    },
+
+    async read(name) {
+      assertCheckpointName(name);
+      return readCheckpointRecord(store, name);
+    },
+
+    async list() {
+      const listed: CheckpointListing[] = [];
+      for (const name of await registeredNames(store)) {
+        const checkpoint = await readCheckpointRecord(store, name);
+        if (checkpoint === null) continue;
+        listed.push({ name, at: checkpoint.at, counts: checkpoint.counts });
+      }
+      return listed;
+    },
+
+    async remove(name) {
+      assertCheckpointName(name);
+      const names = await registeredNames(store);
+      if (!names.includes(name)) return false;
+      await store.clear(CHECKPOINT_PREFIX + name);
+      await writeRegistry(
+        store,
+        names.filter((held) => held !== name),
+      );
+      return true;
+    },
+  };
+}

package/src/sandbox/checkpoints/saved-states.ts

@@ -0,0 +1,72 @@
+/**
+ * The four operations a host offers over checkpoints, written once.
+ *
+ * Save, restore, list, delete. Each takes the backend that says where the
+ * checkpoints are kept, so the Node process and the page run the same code
+ * over a directory of files and over a record store respectively. The
+ * host-visible refusals live here too: restoring a name nothing answers to
+ * names the ones that do, because a caller who mistyped a checkpoint wants the
+ * list rather than an empty sandbox.
+ */
+
+import type { LocalSandbox } from '../types/service.js';
+import { captureCheckpoint, restoreCheckpoint } from './capture.js';
+import type { Checkpoint, CheckpointBackend, CheckpointListing } from './types.js';
+
+/** What a save reports: the checkpoint written, and whether it replaced one. */
+export interface SavedCheckpoint {
+  name: string;
+  overwrote: boolean;
+  checkpoint: Checkpoint;
+}
+
+/** Capture the sandbox and keep it under `name`, replacing whatever that name held. */
+export async function saveCheckpoint(
+  backend: CheckpointBackend,
+  name: string,
+  sandbox: LocalSandbox,
+): Promise<SavedCheckpoint> {
+  const overwrote = (await backend.read(name)) !== null;
+  const checkpoint = await captureCheckpoint(sandbox, { storage: backend.storage ?? 'inline' });
+  await backend.write(name, checkpoint);
+  return { name, overwrote, checkpoint };
+}
+
+/** The checkpoint kept under `name`, or null when the backend holds none. */
+export function readCheckpoint(
+  backend: CheckpointBackend,
+  name: string,
+): Promise<Checkpoint | null> {
+  return backend.read(name);
+}
+
+/** Every checkpoint the backend holds, ordered by name. */
+export function listCheckpoints(backend: CheckpointBackend): Promise<CheckpointListing[]> {
+  return backend.list();
+}
+
+/** The names the backend holds, ordered, for a refusal that has to name them. */
+export async function checkpointNames(backend: CheckpointBackend): Promise<string[]> {
+  return (await backend.list()).map((entry) => entry.name);
+}
+
+/**
+ * Put the sandbox back to the checkpoint kept under `name`, and report which
+ * one was restored. Resolves null when the backend holds no such checkpoint,
+ * and the sandbox is left exactly as it was.
+ */
+export async function restoreNamedCheckpoint(
+  backend: CheckpointBackend,
+  name: string,
+  sandbox: LocalSandbox,
+): Promise<Checkpoint | null> {
+  const checkpoint = await backend.read(name);
+  if (checkpoint === null) return null;
+  await restoreCheckpoint(sandbox, checkpoint);
+  return checkpoint;
+}
+
+/** Remove one checkpoint. Reports whether there was one to remove. */
+export function removeCheckpoint(backend: CheckpointBackend, name: string): Promise<boolean> {
+  return backend.remove(name);
+}

package/src/sandbox/checkpoints/types.ts

@@ -0,0 +1,115 @@
+/**
+ * What a checkpoint is, and what a place to keep one has to do.
+ *
+ * A checkpoint is a named {@link FullSandboxState} with the counts a listing
+ * reports beside it. The state is the whole sandbox, so restoring a checkpoint
+ * puts every service back to the instant it was taken: Firestore documents,
+ * the Realtime Database tree, Storage objects with their bytes and metadata,
+ * auth accounts, and the three rule sources.
+ *
+ * {@link CheckpointBackend} is the seam between the checkpoint and where it is
+ * kept. The Node process keeps checkpoints as files under the project
+ * directory; a page keeps them as records in its own IndexedDB. Both answer
+ * the same four questions, so the capture, restore, listing, and naming rules
+ * are written once and neither host reimplements them.
+ */
+
+import type { FullSandboxState } from '../full-state.js';
+import { z } from 'zod';
+
+/** The tag every checkpoint carries, so an unrelated record is not read as one. */
+export const CHECKPOINT_FORMAT = 'pyric-checkpoint-v1';
+
+/**
+ * The names a checkpoint may take. One filename segment and one record id, so
+ * a name can never reach outside the place its backend keeps checkpoints.
+ */
+export const CHECKPOINT_NAME_PATTERN = /^[A-Za-z0-9_-]{1,64}$/;
+
+/** A checkpoint name a backend refuses. Thrown rather than returned: it is a caller mistake. */
+export class CheckpointNameError extends Error {
+  constructor(name: string) {
+    super(
+      `'${name}' is not a checkpoint name. A checkpoint name is 1 to 64 characters of letters, digits, dash, or underscore.`,
+    );
+    this.name = 'CheckpointNameError';
+  }
+}
+
+/** How much each service held when the checkpoint was taken. */
+export interface CheckpointCounts {
+  /** Firestore documents. */
+  firestore: number;
+  /** Top-level keys of the Realtime Database tree. */
+  database: number;
+  /** Storage objects. */
+  storage: number;
+  /** Auth accounts. */
+  auth: number;
+}
+
+/** One checkpoint: the whole sandbox at an instant, with the counts over it. */
+export interface Checkpoint {
+  format: typeof CHECKPOINT_FORMAT;
+  /** When the checkpoint was taken, in milliseconds since the epoch. */
+  at: number;
+  /** How much each service held. Read by a listing so it needs no state. */
+  counts: CheckpointCounts;
+  /** The whole sandbox, as one plain JSON value. */
+  state: FullSandboxState;
+}
+
+/** One entry of a checkpoint listing: the name plus what a caller reads without loading state. */
+export interface CheckpointListing {
+  name: string;
+  at: number;
+  counts: CheckpointCounts;
+}
+
+/**
+ * Where checkpoints are kept.
+ *
+ * A backend stores and returns whole {@link Checkpoint} values and decides
+ * nothing about them. It rejects a name that does not match
+ * {@link CHECKPOINT_NAME_PATTERN} by throwing {@link CheckpointNameError},
+ * because a name that could reach outside its keeping place is a caller
+ * mistake rather than a missing checkpoint.
+ */
+export interface CheckpointBackend {
+  /**
+   * How checkpoints kept here record Storage bytes. `reference` names each
+   * object by hash and suits a backend that keeps those bytes itself, so a
+   * checkpoint copies none of them. Absent means inline.
+   */
+  readonly storage?: 'inline' | 'reference';
+  /** Write one checkpoint under `name`, replacing whatever that name held. */
+  write(name: string, checkpoint: Checkpoint): Promise<void>;
+  /** The checkpoint stored under `name`, or null when the backend holds none. */
+  read(name: string): Promise<Checkpoint | null>;
+  /** Every checkpoint the backend holds, ordered by name. */
+  list(): Promise<CheckpointListing[]>;
+  /** Remove one checkpoint. Reports whether there was one to remove. */
+  remove(name: string): Promise<boolean>;
+}
+
+const checkpointEnvelopeSchema = z.object({
+  format: z.literal(CHECKPOINT_FORMAT),
+  at: z.number().finite(),
+  counts: z.object({
+    firestore: z.number().int().nonnegative(),
+    database: z.number().int().nonnegative(),
+    storage: z.number().int().nonnegative(),
+    auth: z.number().int().nonnegative(),
+  }),
+  state: z.unknown().refine(value => value !== undefined, 'Required'),
+});
+
+/** Recognize the envelope; restore validates each service before resetting state. */
+export function isCheckpointEnvelope(value: unknown): value is Checkpoint {
+  return checkpointEnvelopeSchema.safeParse(value).success;
+}
+
+/** Reject a name that is not one segment of a backend's keyspace. */
+export function assertCheckpointName(name: string): void {
+  if (!CHECKPOINT_NAME_PATTERN.test(name)) throw new CheckpointNameError(name);
+}

package/src/sandbox/checkpoints/validation.ts

@@ -0,0 +1,102 @@
+import { z } from 'zod';
+import { DOC_VALUE_ENCODING } from '../../firestore/internal/value-codec.js';
+import { base64ToBytes } from '../../storage/base64.js';
+import { normalizePath } from '../../storage/reference.js';
+import { compileStorageRules } from '../../storage/rules-resolution.js';
+import type { FullSandboxState, StorageObjectState } from '../full-state.js';
+import { seedUserSchema, storedMetadataSchema } from '../internal/state-schemas.js';
+import { decodeStateDocument } from '../internal/state-values.js';
+import { SandboxError } from '../types/errors.js';
+
+const storageFields = {
+  path: z.string().min(1).refine(path => normalizePath(path) === path, 'Expected a canonical object path'),
+  contentType: z.string().optional(),
+  customMetadata: z.record(z.string()),
+  metadata: storedMetadataSchema.omit({ fullPath: true, contentType: true, customMetadata: true }).optional(),
+  blobType: z.string().optional(),
+} satisfies Record<keyof StorageObjectState, z.ZodType<unknown>>;
+
+/** A Storage entry carries its bytes inline, or names them by SHA-256 with its metadata. */
+const storageObjectSchema = z.union([
+  z.object({
+    ...storageFields,
+    contentBase64: z.string().regex(/^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$/,
+      'Expected standard padded base64'),
+  }),
+  z.object({
+    ...storageFields,
+    sha256: z.string().regex(/^[0-9a-f]{64}$/, 'Expected a SHA-256 hex digest'),
+    size: z.number().int().nonnegative(),
+    metadata: storageFields.metadata.unwrap(),
+  }),
+]);
+
+const databaseEnvelopeSchema = z.object({
+  '.pyricRtdbPersistence': z.literal(1),
+  data: z.unknown().refine(value => value !== undefined, 'Required'),
+  priorities: z.record(z.union([z.string(), z.number().finite()])),
+});
+
+/** Legacy trees have no marker; a marked record must use the supported envelope. */
+function hasSupportedDatabaseEnvelope(value: unknown): boolean {
+  const isObject = value !== null && typeof value === 'object' && !Array.isArray(value);
+  const isTreeValue = !isObject;
+  if (isTreeValue) return value !== undefined;
+  const hasMarker = '.pyricRtdbPersistence' in value;
+  const isLegacyTree = !hasMarker;
+  if (isLegacyTree) return true;
+  return databaseEnvelopeSchema.safeParse(value).success;
+}
+
+const stateFields = {
+  firestore: z.record(z.record(z.unknown())),
+  firestoreEncoding: z.literal(DOC_VALUE_ENCODING).optional(),
+  database: z.unknown().refine(hasSupportedDatabaseEnvelope, 'Invalid RTDB persistence envelope'),
+  storage: z.array(storageObjectSchema),
+  auth: z.object({ users: z.array(seedUserSchema), providers: z.record(z.boolean()) }),
+  rules: z.object({
+    firestore: z.string(),
+    database: z.object({ rules: z.record(z.unknown()) }).nullable(),
+    storage: z.string().nullable(),
+  }),
+  clock: z.object({ mode: z.enum(['wall', 'fixed', 'offset']),
+    fixedAt: z.number().finite(), offsetMs: z.number().finite() }).optional(),
+} satisfies Record<keyof FullSandboxState, z.ZodType<unknown>>;
+
+const checkpointStateSchema = z.object(stateFields);
+
+/** Validate serialized state and fallible service inputs before resetting healthy state. */
+export function assertCheckpointState(state: unknown): void {
+  const result = checkpointStateSchema.safeParse(state);
+  const isInvalidState = !result.success;
+  if (isInvalidState) {
+    const details = result.error.issues.map(issue => `${issue.path.join('.')}: ${issue.message}`).join('; ');
+    throw new SandboxError('invalid-argument', `Invalid checkpoint state (${details}).`);
+  }
+  try {
+    for (const document of Object.values(result.data.firestore)) {
+      decodeStateDocument(document, result.data.firestoreEncoding);
+    }
+  } catch (error) {
+    throw new SandboxError('invalid-argument', `Invalid checkpoint Firestore values: ${String(error)}`);
+  }
+  for (const object of result.data.storage) {
+    const declaredSize = object.metadata?.size;
+    const isLegacyObject = declaredSize === undefined;
+    if (isLegacyObject) continue;
+    const actualSize = 'contentBase64' in object ? base64ToBytes(object.contentBase64).byteLength : object.size;
+    const hasWrongSize = actualSize !== declaredSize;
+    if (hasWrongSize) {
+      throw new SandboxError('invalid-argument', `Invalid checkpoint Storage size for '${object.path}'.`);
+    }
+  }
+  const storageRules = result.data.rules.storage;
+  const hasStorageRules = storageRules !== null;
+  if (hasStorageRules) {
+    try {
+      compileStorageRules(storageRules);
+    } catch (error) {
+      throw new SandboxError('invalid-argument', `Invalid checkpoint Storage rules: ${String(error)}`);
+    }
+  }
+}