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

package/dist/sandbox/checkpoints/record-backend.js

@@ -0,0 +1,81 @@
+/**
+ * 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 { assertCheckpointName, isCheckpointEnvelope, } 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) {
+    const record = (await store.getRecord(CHECKPOINT_REGISTRY_KEY, RECORD_ID));
+    if (!Array.isArray(record?.value))
+        return [];
+    return record.value.filter((name) => typeof name === 'string');
+}
+/** Replace the registry with `names`, sorted, so every listing reads one order. */
+async function writeRegistry(store, names) {
+    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, name) {
+    const record = (await store.getRecord(CHECKPOINT_PREFIX + name, RECORD_ID));
+    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) {
+    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 = [];
+            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;
+        },
+    };
+}
+//# sourceMappingURL=record-backend.js.map

package/dist/sandbox/checkpoints/record-backend.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"record-backend.js","sourceRoot":"","sources":["../../../src/sandbox/checkpoints/record-backend.ts"],"names":[],"mappings":"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"}

package/dist/sandbox/checkpoints/saved-states.d.ts

@@ -0,0 +1,35 @@
+/**
+ * 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 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 declare function saveCheckpoint(backend: CheckpointBackend, name: string, sandbox: LocalSandbox): Promise<SavedCheckpoint>;
+/** The checkpoint kept under `name`, or null when the backend holds none. */
+export declare function readCheckpoint(backend: CheckpointBackend, name: string): Promise<Checkpoint | null>;
+/** Every checkpoint the backend holds, ordered by name. */
+export declare function listCheckpoints(backend: CheckpointBackend): Promise<CheckpointListing[]>;
+/** The names the backend holds, ordered, for a refusal that has to name them. */
+export declare function checkpointNames(backend: CheckpointBackend): Promise<string[]>;
+/**
+ * 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 declare function restoreNamedCheckpoint(backend: CheckpointBackend, name: string, sandbox: LocalSandbox): Promise<Checkpoint | null>;
+/** Remove one checkpoint. Reports whether there was one to remove. */
+export declare function removeCheckpoint(backend: CheckpointBackend, name: string): Promise<boolean>;
+//# sourceMappingURL=saved-states.d.ts.map

package/dist/sandbox/checkpoints/saved-states.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"saved-states.d.ts","sourceRoot":"","sources":["../../../src/sandbox/checkpoints/saved-states.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AAExD,OAAO,KAAK,EAAE,UAAU,EAAE,iBAAiB,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAEnF,gFAAgF;AAChF,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,OAAO,CAAC;IACnB,UAAU,EAAE,UAAU,CAAC;CACxB;AAED,uFAAuF;AACvF,wBAAsB,cAAc,CAClC,OAAO,EAAE,iBAAiB,EAC1B,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,YAAY,GACpB,OAAO,CAAC,eAAe,CAAC,CAK1B;AAED,6EAA6E;AAC7E,wBAAgB,cAAc,CAC5B,OAAO,EAAE,iBAAiB,EAC1B,IAAI,EAAE,MAAM,GACX,OAAO,CAAC,UAAU,GAAG,IAAI,CAAC,CAE5B;AAED,2DAA2D;AAC3D,wBAAgB,eAAe,CAAC,OAAO,EAAE,iBAAiB,GAAG,OAAO,CAAC,iBAAiB,EAAE,CAAC,CAExF;AAED,iFAAiF;AACjF,wBAAsB,eAAe,CAAC,OAAO,EAAE,iBAAiB,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAEnF;AAED;;;;GAIG;AACH,wBAAsB,sBAAsB,CAC1C,OAAO,EAAE,iBAAiB,EAC1B,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,YAAY,GACpB,OAAO,CAAC,UAAU,GAAG,IAAI,CAAC,CAK5B;AAED,sEAAsE;AACtE,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,iBAAiB,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAE3F"}

package/dist/sandbox/checkpoints/saved-states.js

@@ -0,0 +1,47 @@
+/**
+ * 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 { captureCheckpoint, restoreCheckpoint } from './capture.js';
+/** Capture the sandbox and keep it under `name`, replacing whatever that name held. */
+export async function saveCheckpoint(backend, name, sandbox) {
+    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, name) {
+    return backend.read(name);
+}
+/** Every checkpoint the backend holds, ordered by name. */
+export function listCheckpoints(backend) {
+    return backend.list();
+}
+/** The names the backend holds, ordered, for a refusal that has to name them. */
+export async function checkpointNames(backend) {
+    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, name, sandbox) {
+    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, name) {
+    return backend.remove(name);
+}
+//# sourceMappingURL=saved-states.js.map

package/dist/sandbox/checkpoints/saved-states.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"saved-states.js","sourceRoot":"","sources":["../../../src/sandbox/checkpoints/saved-states.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAGH,OAAO,EAAE,iBAAiB,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAC;AAUpE,uFAAuF;AACvF,MAAM,CAAC,KAAK,UAAU,cAAc,CAClC,OAA0B,EAC1B,IAAY,EACZ,OAAqB;IAErB,MAAM,SAAS,GAAG,CAAC,MAAM,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,KAAK,IAAI,CAAC;IACtD,MAAM,UAAU,GAAG,MAAM,iBAAiB,CAAC,OAAO,EAAE,EAAE,OAAO,EAAE,OAAO,CAAC,OAAO,IAAI,QAAQ,EAAE,CAAC,CAAC;IAC9F,MAAM,OAAO,CAAC,KAAK,CAAC,IAAI,EAAE,UAAU,CAAC,CAAC;IACtC,OAAO,EAAE,IAAI,EAAE,SAAS,EAAE,UAAU,EAAE,CAAC;AACzC,CAAC;AAED,6EAA6E;AAC7E,MAAM,UAAU,cAAc,CAC5B,OAA0B,EAC1B,IAAY;IAEZ,OAAO,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AAC5B,CAAC;AAED,2DAA2D;AAC3D,MAAM,UAAU,eAAe,CAAC,OAA0B;IACxD,OAAO,OAAO,CAAC,IAAI,EAAE,CAAC;AACxB,CAAC;AAED,iFAAiF;AACjF,MAAM,CAAC,KAAK,UAAU,eAAe,CAAC,OAA0B;IAC9D,OAAO,CAAC,MAAM,OAAO,CAAC,IAAI,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;AAC3D,CAAC;AAED;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,sBAAsB,CAC1C,OAA0B,EAC1B,IAAY,EACZ,OAAqB;IAErB,MAAM,UAAU,GAAG,MAAM,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAC5C,IAAI,UAAU,KAAK,IAAI;QAAE,OAAO,IAAI,CAAC;IACrC,MAAM,iBAAiB,CAAC,OAAO,EAAE,UAAU,CAAC,CAAC;IAC7C,OAAO,UAAU,CAAC;AACpB,CAAC;AAED,sEAAsE;AACtE,MAAM,UAAU,gBAAgB,CAAC,OAA0B,EAAE,IAAY;IACvE,OAAO,OAAO,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;AAC9B,CAAC"}

package/dist/sandbox/checkpoints/types.d.ts

@@ -0,0 +1,84 @@
+/**
+ * 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';
+/** The tag every checkpoint carries, so an unrelated record is not read as one. */
+export declare 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 declare const CHECKPOINT_NAME_PATTERN: RegExp;
+/** A checkpoint name a backend refuses. Thrown rather than returned: it is a caller mistake. */
+export declare class CheckpointNameError extends Error {
+    constructor(name: string);
+}
+/** 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>;
+}
+/** Recognize the envelope; restore validates each service before resetting state. */
+export declare function isCheckpointEnvelope(value: unknown): value is Checkpoint;
+/** Reject a name that is not one segment of a backend's keyspace. */
+export declare function assertCheckpointName(name: string): void;
+//# sourceMappingURL=types.d.ts.map

package/dist/sandbox/checkpoints/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/sandbox/checkpoints/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AAGzD,mFAAmF;AACnF,eAAO,MAAM,iBAAiB,wBAAwB,CAAC;AAEvD;;;GAGG;AACH,eAAO,MAAM,uBAAuB,QAA0B,CAAC;AAE/D,gGAAgG;AAChG,qBAAa,mBAAoB,SAAQ,KAAK;gBAChC,IAAI,EAAE,MAAM;CAMzB;AAED,gEAAgE;AAChE,MAAM,WAAW,gBAAgB;IAC/B,2BAA2B;IAC3B,SAAS,EAAE,MAAM,CAAC;IAClB,oDAAoD;IACpD,QAAQ,EAAE,MAAM,CAAC;IACjB,uBAAuB;IACvB,OAAO,EAAE,MAAM,CAAC;IAChB,qBAAqB;IACrB,IAAI,EAAE,MAAM,CAAC;CACd;AAED,gFAAgF;AAChF,MAAM,WAAW,UAAU;IACzB,MAAM,EAAE,OAAO,iBAAiB,CAAC;IACjC,sEAAsE;IACtE,EAAE,EAAE,MAAM,CAAC;IACX,0EAA0E;IAC1E,MAAM,EAAE,gBAAgB,CAAC;IACzB,kDAAkD;IAClD,KAAK,EAAE,gBAAgB,CAAC;CACzB;AAED,kGAAkG;AAClG,MAAM,WAAW,iBAAiB;IAChC,IAAI,EAAE,MAAM,CAAC;IACb,EAAE,EAAE,MAAM,CAAC;IACX,MAAM,EAAE,gBAAgB,CAAC;CAC1B;AAED;;;;;;;;GAQG;AACH,MAAM,WAAW,iBAAiB;IAChC;;;;OAIG;IACH,QAAQ,CAAC,OAAO,CAAC,EAAE,QAAQ,GAAG,WAAW,CAAC;IAC1C,4EAA4E;IAC5E,KAAK,CAAC,IAAI,EAAE,MAAM,EAAE,UAAU,EAAE,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC3D,+EAA+E;IAC/E,IAAI,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,GAAG,IAAI,CAAC,CAAC;IAC/C,2DAA2D;IAC3D,IAAI,IAAI,OAAO,CAAC,iBAAiB,EAAE,CAAC,CAAC;IACrC,sEAAsE;IACtE,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;CACxC;AAcD,qFAAqF;AACrF,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,UAAU,CAExE;AAED,qEAAqE;AACrE,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAEvD"}

package/dist/sandbox/checkpoints/types.js

@@ -0,0 +1,51 @@
+/**
+ * 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 { 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) {
+        super(`'${name}' is not a checkpoint name. A checkpoint name is 1 to 64 characters of letters, digits, dash, or underscore.`);
+        this.name = 'CheckpointNameError';
+    }
+}
+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) {
+    return checkpointEnvelopeSchema.safeParse(value).success;
+}
+/** Reject a name that is not one segment of a backend's keyspace. */
+export function assertCheckpointName(name) {
+    if (!CHECKPOINT_NAME_PATTERN.test(name))
+        throw new CheckpointNameError(name);
+}
+//# sourceMappingURL=types.js.map

package/dist/sandbox/checkpoints/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/sandbox/checkpoints/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAGH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,mFAAmF;AACnF,MAAM,CAAC,MAAM,iBAAiB,GAAG,qBAAqB,CAAC;AAEvD;;;GAGG;AACH,MAAM,CAAC,MAAM,uBAAuB,GAAG,uBAAuB,CAAC;AAE/D,gGAAgG;AAChG,MAAM,OAAO,mBAAoB,SAAQ,KAAK;IAC5C,YAAY,IAAY;QACtB,KAAK,CACH,IAAI,IAAI,8GAA8G,CACvH,CAAC;QACF,IAAI,CAAC,IAAI,GAAG,qBAAqB,CAAC;IACpC,CAAC;CACF;AA0DD,MAAM,wBAAwB,GAAG,CAAC,CAAC,MAAM,CAAC;IACxC,MAAM,EAAE,CAAC,CAAC,OAAO,CAAC,iBAAiB,CAAC;IACpC,EAAE,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,MAAM,EAAE;IACvB,MAAM,EAAE,CAAC,CAAC,MAAM,CAAC;QACf,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,WAAW,EAAE;QACzC,QAAQ,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,WAAW,EAAE;QACxC,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,WAAW,EAAE;QACvC,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,WAAW,EAAE;KACrC,CAAC;IACF,KAAK,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE,CAAC,KAAK,KAAK,SAAS,EAAE,UAAU,CAAC;CACpE,CAAC,CAAC;AAEH,qFAAqF;AACrF,MAAM,UAAU,oBAAoB,CAAC,KAAc;IACjD,OAAO,wBAAwB,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC,OAAO,CAAC;AAC3D,CAAC;AAED,qEAAqE;AACrE,MAAM,UAAU,oBAAoB,CAAC,IAAY;IAC/C,IAAI,CAAC,uBAAuB,CAAC,IAAI,CAAC,IAAI,CAAC;QAAE,MAAM,IAAI,mBAAmB,CAAC,IAAI,CAAC,CAAC;AAC/E,CAAC"}

package/dist/sandbox/checkpoints/validation.d.ts

@@ -0,0 +1,3 @@
+/** Validate serialized state and fallible service inputs before resetting healthy state. */
+export declare function assertCheckpointState(state: unknown): void;
+//# sourceMappingURL=validation.d.ts.map

package/dist/sandbox/checkpoints/validation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validation.d.ts","sourceRoot":"","sources":["../../../src/sandbox/checkpoints/validation.ts"],"names":[],"mappings":"AAmEA,4FAA4F;AAC5F,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,OAAO,GAAG,IAAI,CAiC1D"}

package/dist/sandbox/checkpoints/validation.js

@@ -0,0 +1,99 @@
+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 { 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(),
+};
+/** 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) {
+    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(),
+};
+const checkpointStateSchema = z.object(stateFields);
+/** Validate serialized state and fallible service inputs before resetting healthy state. */
+export function assertCheckpointState(state) {
+    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)}`);
+        }
+    }
+}
+//# sourceMappingURL=validation.js.map

package/dist/sandbox/checkpoints/validation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"validation.js","sourceRoot":"","sources":["../../../src/sandbox/checkpoints/validation.ts"],"names":[],"mappings":"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"}

package/dist/sandbox/clock.d.ts

@@ -0,0 +1,121 @@
+/**
+ * The sandbox's one source of time.
+ *
+ * Every value the sandbox stamps that claims to be "when this happened" reads
+ * this clock: Firestore `serverTimestamp()` and `request.time`, Realtime
+ * Database `ServerValue.TIMESTAMP` and rules `now`, Storage `timeCreated` /
+ * `updated` and its `request.time`, auth token `iat` / `exp` / `auth_time` and
+ * account metadata, listener dispatch stamps, and the event, checkpoint, and
+ * persistence stamps that record when a sandbox operation happened. Moving the
+ * clock therefore moves every one of those together, which is the whole point:
+ * a rule that reads `request.time` and a document that carries a
+ * `serverTimestamp()` written in the same operation agree about what time it
+ * is.
+ *
+ * ## The model
+ *
+ * Three modes, one number each.
+ *
+ * - `wall` (the default): `now()` is `Date.now()`. Nothing about the sandbox's
+ *   behaviour differs from a build with no clock at all.
+ * - `fixed`: {@link SandboxClock.set} names an instant and **freezes** the
+ *   clock there. `now()` returns that instant until the clock is moved again.
+ *   Naming an exact instant is a request for determinism, so time stops.
+ * - `offset`: {@link SandboxClock.advance} from `wall` shifts the clock by a
+ *   delta and lets it **keep flowing**. Jumping forward a day is a request to
+ *   be a day later, not a request to stop, and monotonic progress is what push
+ *   ids, listener ordering, and elapsed-time bookkeeping rely on.
+ *
+ * `advance` is consistent with whichever mode it finds. From `wall` it opens an
+ * offset; from `offset` it grows that offset; from `fixed` it moves the frozen
+ * instant and stays frozen. {@link SandboxClock.reset} returns to `wall`.
+ *
+ * The clock is deliberately not monotonic across a `set`: a caller who pins an
+ * instant in the past gets an instant in the past, and the sandbox will stamp
+ * it. That is the caller's decision to make.
+ *
+ * Node-safe and browser-safe: it reads `Date.now()` and nothing else.
+ */
+import type { Sandbox } from './types/service.js';
+/**
+ * The key a sandbox carries its clock under. Registered globally
+ * (`Symbol.for`) rather than minted per module, because a workspace can load
+ * this module twice (a package specifier resolving to the built output, a
+ * relative path resolving to the source) and a per-module symbol would make
+ * {@link getClock} fail to recognize a sandbox built by the other copy.
+ */
+export declare const SANDBOX_CLOCK: unique symbol;
+/**
+ * Resolve one sandbox's clock. The clock is the sandbox's whole notion of
+ * time: every `serverTimestamp()`, `request.time`, token `iat`, and event stamp
+ * on that sandbox reads it, so moving it here moves all of them.
+ *
+ * The clock survives `sandbox.reset()`, which swaps the Firestore environment
+ * but not the sandbox: a pinned instant is a property of the session, not of
+ * the data in it.
+ *
+ * Throws if `sandbox` was not produced by `initializeSandbox()`, the same guard
+ * `getInternalEnv` applies.
+ */
+export declare function getClock(sandbox: Sandbox): SandboxClock;
+/**
+ * How the clock is currently deriving `now()`. See the module header for what
+ * each mode promises.
+ */
+export type SandboxClockMode = 'wall' | 'fixed' | 'offset';
+/**
+ * A clock's whole state as one plain value. Captured into a checkpoint or a
+ * branch's full state so a restore or a fork carries the virtual time it was
+ * taken under, and safe to serialize as JSON.
+ */
+export interface SandboxClockState {
+    mode: SandboxClockMode;
+    /** The frozen instant, in epoch milliseconds. Only meaningful when `mode` is `fixed`. */
+    fixedAt: number;
+    /** Milliseconds added to the wall clock. Only meaningful when `mode` is `offset`. */
+    offsetMs: number;
+}
+/** The state a clock that has never been moved reports. */
+export declare function wallClockState(): SandboxClockState;
+/**
+ * One sandbox's clock. Owned by the sandbox and shared by every service on it,
+ * so `set` / `advance` / `reset` move all of them at once.
+ */
+export declare class SandboxClock {
+    private currentMode;
+    private fixedAt;
+    private offsetMs;
+    private readonly listeners;
+    /**
+     * Watch for a move. A sandbox hosted behind a transport (the SharedWorker
+     * host, say) has readers in another realm that cannot call `now()`
+     * synchronously, so they mirror this state instead and need to be told when
+     * it changes. Returns the function that stops watching.
+     */
+    onChange(listener: (state: SandboxClockState) => void): () => void;
+    private announce;
+    /** Which of the three modes the clock is in. */
+    get mode(): SandboxClockMode;
+    /** The sandbox's current time, in epoch milliseconds. */
+    now(): number;
+    /** The sandbox's current time as a `Date`. */
+    date(): Date;
+    /**
+     * Pin the clock to `epochMs` and freeze it there. Every subsequent `now()`
+     * returns exactly `epochMs` until the clock is advanced, set again, or reset.
+     */
+    set(epochMs: number): void;
+    /**
+     * Move the clock forward (or, with a negative delta, back) by `ms`. A frozen
+     * clock stays frozen at the new instant; a wall or offset clock keeps
+     * flowing, shifted.
+     */
+    advance(ms: number): void;
+    /** Return to the wall clock, discarding any pin or offset. */
+    reset(): void;
+    /** This clock's whole state, as a value a checkpoint or branch can hold. */
+    capture(): SandboxClockState;
+    /** Adopt a captured state wholesale. */
+    restore(state: SandboxClockState): void;
+}
+//# sourceMappingURL=clock.d.ts.map

package/dist/sandbox/clock.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"clock.d.ts","sourceRoot":"","sources":["../../src/sandbox/clock.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AAGH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,oBAAoB,CAAC;AAElD;;;;;;GAMG;AACH,eAAO,MAAM,aAAa,eAAoC,CAAC;AAE/D;;;;;;;;;;;GAWG;AACH,wBAAgB,QAAQ,CAAC,OAAO,EAAE,OAAO,GAAG,YAAY,CASvD;AAED;;;GAGG;AACH,MAAM,MAAM,gBAAgB,GAAG,MAAM,GAAG,OAAO,GAAG,QAAQ,CAAC;AAE3D;;;;GAIG;AACH,MAAM,WAAW,iBAAiB;IAChC,IAAI,EAAE,gBAAgB,CAAC;IACvB,yFAAyF;IACzF,OAAO,EAAE,MAAM,CAAC;IAChB,qFAAqF;IACrF,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,2DAA2D;AAC3D,wBAAgB,cAAc,IAAI,iBAAiB,CAElD;AAQD;;;GAGG;AACH,qBAAa,YAAY;IACvB,OAAO,CAAC,WAAW,CAA4B;IAC/C,OAAO,CAAC,OAAO,CAAK;IACpB,OAAO,CAAC,QAAQ,CAAK;IACrB,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAiD;IAE3E;;;;;OAKG;IACH,QAAQ,CAAC,QAAQ,EAAE,CAAC,KAAK,EAAE,iBAAiB,KAAK,IAAI,GAAG,MAAM,IAAI;IAOlE,OAAO,CAAC,QAAQ;IAOhB,gDAAgD;IAChD,IAAI,IAAI,IAAI,gBAAgB,CAE3B;IAED,yDAAyD;IACzD,GAAG,IAAI,MAAM;IAUb,8CAA8C;IAC9C,IAAI,IAAI,IAAI;IAIZ;;;OAGG;IACH,GAAG,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI;IAQ1B;;;;OAIG;IACH,OAAO,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI;IAYzB,8DAA8D;IAC9D,KAAK,IAAI,IAAI;IAOb,4EAA4E;IAC5E,OAAO,IAAI,iBAAiB;IAI5B,wCAAwC;IACxC,OAAO,CAAC,KAAK,EAAE,iBAAiB,GAAG,IAAI;CAMxC"}