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

package/dist/sandbox/branches/store.js

@@ -0,0 +1,264 @@
+/**
+ * Persisted branches: the on-disk form of the in-memory branch primitive.
+ *
+ * THE FORMAT, stated once because the CLI and Studio both read it.
+ *
+ *   <project>/.pyric/state/branches/<name>/
+ *     manifest.json          { format, created, base, eventCount }
+ *     events.json            the applied event log, a JSON array of SandboxEvent
+ *     candidate-rules.json   the rule sources the fork installed in place of
+ *                            the base's, absent when the fork installed none
+ *     base/firestore.json    the forked base state, one file per service:
+ *     base/database.json       documents, the Realtime Database envelope,
+ *     base/storage.json        objects with base64 bytes and metadata,
+ *     base/auth.json           accounts and provider config, and the three
+ *     base/rules.json          rule sources
+ *     state/<service>.json   what the branch holds now, the same five files
+ *
+ * One file per service rather than one bundle, so a reader opening the
+ * directory sees which services a branch carries without decoding anything,
+ * and two changes to different services never rewrite the same file. The
+ * directory name is the branch name and is the join key, so the manifest does
+ * not repeat it: the directory is the index, exactly as the authored record
+ * convention states. `base` is `live` or the name of the checkpoint the fork
+ * was taken from.
+ *
+ * Why the branch carries two states rather than a base and a replayable log.
+ * The event log records Firestore writes, which is one of the five services a
+ * branch holds. A branch that had uploaded a Storage object or created an
+ * account could not be rebuilt from its base and its log, so the log is what
+ * was applied and `state/` is what the branch holds. `base/` stays because a
+ * promotion is a delta against it: state on the target the branch never
+ * touched has to survive landing, and only the base says which state that is.
+ *
+ * This module reads and writes files, so it is Node only and is published at
+ * the `pyric/sandbox/branches/store` subpath rather than from the browser
+ * barrel `pyric/sandbox`.
+ */
+import { existsSync, mkdirSync, readFileSync, readdirSync, rmSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { DOC_VALUE_ENCODING } from '../../firestore/internal/value-codec.js';
+import { SANDBOX_SERVICES, captureFullState, } from '../full-state.js';
+import { wallClockState } from '../clock.js';
+import { fork } from './engine.js';
+/** The tag every branch manifest carries, so an unrelated directory is not read as one. */
+export const BRANCH_FORMAT = 'pyric-branch-v2';
+/** Where branches live, relative to the project directory. */
+export const BRANCH_STORE_RELATIVE = join('.pyric', 'state', 'branches');
+const MANIFEST_FILE = 'manifest.json';
+const EVENTS_FILE = 'events.json';
+const CANDIDATE_RULES_FILE = 'candidate-rules.json';
+const CLOCK_FILE = 'clock.json';
+const FIRESTORE_ENCODING_FILE = 'firestore-encoding.json';
+const BASE_DIRECTORY = 'base';
+const STATE_DIRECTORY = 'state';
+/** The names a branch may take: one path segment, so a name can never escape the store. */
+export const BRANCH_NAME_PATTERN = /^[a-z0-9][a-z0-9._-]{0,63}$/;
+/** A branch name the store refuses. Thrown rather than returned: it is a caller mistake. */
+export class BranchNameError extends Error {
+    constructor(name) {
+        super(`'${name}' is not a branch name. A branch name is 1 to 64 characters of lowercase letters, digits, dot, dash, or underscore, starting with a letter or digit.`);
+        this.name = 'BranchNameError';
+    }
+}
+/** Reject a name that is not one path segment of the branch store. */
+function assertBranchName(name) {
+    if (!BRANCH_NAME_PATTERN.test(name))
+        throw new BranchNameError(name);
+}
+/** The directory one branch occupies. */
+export function branchDirectory(projectDir, name) {
+    assertBranchName(name);
+    return join(projectDir, BRANCH_STORE_RELATIVE, name);
+}
+/** The file one service's slice of a stored state occupies. */
+function stateServicePath(dir, stateDir, service) {
+    return join(dir, stateDir, `${service}.json`);
+}
+/** Write one full state as one file per service. */
+function writeState(dir, stateDir, state) {
+    mkdirSync(join(dir, stateDir), { recursive: true });
+    for (const service of SANDBOX_SERVICES) {
+        writeFileSync(stateServicePath(dir, stateDir, service), `${JSON.stringify(state[service])}\n`, 'utf8');
+    }
+    // The clock is not a service, so it gets its own file beside them rather than
+    // a place in the service list the diff walks. A branch reloaded from disk
+    // reaches the same `request.time` verdict the branch reached in memory.
+    writeFileSync(join(dir, stateDir, CLOCK_FILE), `${JSON.stringify(state.clock ?? wallClockState())}\n`, 'utf8');
+    writeFileSync(join(dir, stateDir, FIRESTORE_ENCODING_FILE), `${JSON.stringify(state.firestoreEncoding ?? null)}\n`, 'utf8');
+}
+/** Older branch directories contain unencoded maps and have no encoding file. */
+function readFirestoreEncoding(dir, stateDir) {
+    const path = join(dir, stateDir, FIRESTORE_ENCODING_FILE);
+    const hasNoEncoding = !existsSync(path);
+    if (hasNoEncoding)
+        return undefined;
+    const encoding = JSON.parse(readFileSync(path, 'utf8'));
+    const isLegacyState = encoding === null;
+    if (isLegacyState)
+        return undefined;
+    const isSupported = encoding === DOC_VALUE_ENCODING;
+    if (isSupported)
+        return encoding;
+    throw new Error('Unsupported Firestore value encoding in branch state.');
+}
+/** Read one service's slice back, or null when the branch directory has no such file. */
+function readSandboxService(dir, stateDir, service) {
+    const path = stateServicePath(dir, stateDir, service);
+    if (!existsSync(path))
+        return null;
+    return JSON.parse(readFileSync(path, 'utf8'));
+}
+/** The clock one state directory carries, or the wall clock when it has none. */
+function readClock(dir, stateDir) {
+    const path = join(dir, stateDir, CLOCK_FILE);
+    if (!existsSync(path))
+        return wallClockState();
+    return JSON.parse(readFileSync(path, 'utf8'));
+}
+/** One full state a branch directory carries, under `base/` or under `state/`. */
+function readState(dir, stateDir) {
+    return {
+        clock: readClock(dir, stateDir),
+        firestoreEncoding: readFirestoreEncoding(dir, stateDir),
+        firestore: (readSandboxService(dir, stateDir, 'firestore') ?? {}),
+        database: readSandboxService(dir, stateDir, 'database'),
+        storage: (readSandboxService(dir, stateDir, 'storage') ?? []),
+        auth: (readSandboxService(dir, stateDir, 'auth') ?? {
+            users: [],
+            providers: {},
+        }),
+        rules: (readSandboxService(dir, stateDir, 'rules') ?? {
+            firestore: '',
+            database: null,
+            storage: null,
+        }),
+    };
+}
+/**
+ * Write one branch to its own directory, replacing whatever was there. The
+ * base, the current state, and the event log are all written from the branch
+ * itself, so a save after an `apply` or after a write on any service records
+ * exactly what the engine holds.
+ */
+export async function saveBranch(projectDir, name, branch, options) {
+    const dir = branchDirectory(projectDir, name);
+    const manifest = {
+        format: BRANCH_FORMAT,
+        created: options.created ?? new Date().toISOString(),
+        base: options.base,
+        eventCount: branch.events.length,
+    };
+    const current = await captureFullState(branch.sandbox);
+    mkdirSync(dir, { recursive: true });
+    writeState(dir, BASE_DIRECTORY, branch.base);
+    writeState(dir, STATE_DIRECTORY, current);
+    writeFileSync(join(dir, EVENTS_FILE), `${JSON.stringify(branch.events)}\n`, 'utf8');
+    const candidateRulesPath = join(dir, CANDIDATE_RULES_FILE);
+    const hasCandidateRules = Object.keys(branch.candidateRules).length > 0;
+    if (hasCandidateRules) {
+        writeFileSync(candidateRulesPath, `${JSON.stringify(branch.candidateRules)}\n`, 'utf8');
+    }
+    else {
+        rmSync(candidateRulesPath, { force: true });
+    }
+    writeFileSync(join(dir, MANIFEST_FILE), `${JSON.stringify(manifest, null, 2)}\n`, 'utf8');
+    return manifest;
+}
+/** The manifest one directory holds, or null when it holds none this store wrote. */
+function readManifest(dir) {
+    const path = join(dir, MANIFEST_FILE);
+    if (!existsSync(path))
+        return null;
+    let parsed;
+    try {
+        parsed = JSON.parse(readFileSync(path, 'utf8'));
+    }
+    catch {
+        return null;
+    }
+    if (parsed.format !== BRANCH_FORMAT)
+        return null;
+    if (typeof parsed.created !== 'string')
+        return null;
+    if (typeof parsed.base !== 'string')
+        return null;
+    if (typeof parsed.eventCount !== 'number')
+        return null;
+    return {
+        format: BRANCH_FORMAT,
+        created: parsed.created,
+        base: parsed.base,
+        eventCount: parsed.eventCount,
+    };
+}
+/** The candidate rules one branch directory carries, empty when it carries none. */
+function readCandidateRules(dir) {
+    const path = join(dir, CANDIDATE_RULES_FILE);
+    if (!existsSync(path))
+        return {};
+    return JSON.parse(readFileSync(path, 'utf8'));
+}
+/** The event log one branch directory carries. */
+function readEvents(dir) {
+    const path = join(dir, EVENTS_FILE);
+    if (!existsSync(path))
+        return [];
+    const parsed = JSON.parse(readFileSync(path, 'utf8'));
+    if (!Array.isArray(parsed))
+        return [];
+    return parsed;
+}
+/**
+ * Rebuild one branch from its directory, or null when the project has no
+ * branch by that name. The branch's sandbox is forked onto the stored current
+ * state, and the stored base and event log are restored beside it, so a loaded
+ * branch and a branch that never left memory are the same value in every
+ * service rather than only in the one the event log records.
+ */
+export async function loadBranch(projectDir, name) {
+    const dir = branchDirectory(projectDir, name);
+    const manifest = readManifest(dir);
+    if (manifest === null)
+        return null;
+    const forked = await fork(readState(dir, STATE_DIRECTORY), readCandidateRules(dir));
+    const branch = {
+        sandbox: forked.sandbox,
+        candidateRules: forked.candidateRules,
+        base: readState(dir, BASE_DIRECTORY),
+        events: readEvents(dir),
+        discarded: false,
+    };
+    return { name, branch, manifest };
+}
+/**
+ * Every branch the project holds, ordered by name. A directory that carries no
+ * manifest this store wrote is skipped rather than failing the listing, so an
+ * unrelated file under the branch directory does not take the listing down.
+ */
+export function listBranches(projectDir) {
+    const root = join(projectDir, BRANCH_STORE_RELATIVE);
+    if (!existsSync(root))
+        return [];
+    const listed = [];
+    for (const entry of readdirSync(root, { withFileTypes: true })) {
+        if (!entry.isDirectory())
+            continue;
+        if (!BRANCH_NAME_PATTERN.test(entry.name))
+            continue;
+        const manifest = readManifest(join(root, entry.name));
+        if (manifest === null)
+            continue;
+        listed.push({ name: entry.name, ...manifest });
+    }
+    return listed.sort((a, b) => a.name.localeCompare(b.name));
+}
+/** Remove one branch directory. Returns whether there was one to remove. */
+export function removeBranch(projectDir, name) {
+    const dir = branchDirectory(projectDir, name);
+    if (!existsSync(dir))
+        return false;
+    rmSync(dir, { recursive: true, force: true });
+    return true;
+}
+//# sourceMappingURL=store.js.map

package/dist/sandbox/branches/store.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"store.js","sourceRoot":"","sources":["../../../src/sandbox/branches/store.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AACH,OAAO,EAAE,UAAU,EAAE,SAAS,EAAE,YAAY,EAAE,WAAW,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AAClG,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AACjC,OAAO,EAAE,kBAAkB,EAAE,MAAM,yCAAyC,CAAC;AAE7E,OAAO,EACL,gBAAgB,EAChB,gBAAgB,GAGjB,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EAAE,cAAc,EAA0B,MAAM,aAAa,CAAC;AAErE,OAAO,EAAE,IAAI,EAA0C,MAAM,aAAa,CAAC;AAE3E,2FAA2F;AAC3F,MAAM,CAAC,MAAM,aAAa,GAAG,iBAAiB,CAAC;AAE/C,8DAA8D;AAC9D,MAAM,CAAC,MAAM,qBAAqB,GAAG,IAAI,CAAC,QAAQ,EAAE,OAAO,EAAE,UAAU,CAAC,CAAC;AAEzE,MAAM,aAAa,GAAG,eAAe,CAAC;AACtC,MAAM,WAAW,GAAG,aAAa,CAAC;AAClC,MAAM,oBAAoB,GAAG,sBAAsB,CAAC;AACpD,MAAM,UAAU,GAAG,YAAY,CAAC;AAChC,MAAM,uBAAuB,GAAG,yBAAyB,CAAC;AAC1D,MAAM,cAAc,GAAG,MAAM,CAAC;AAC9B,MAAM,eAAe,GAAG,OAAO,CAAC;AAEhC,2FAA2F;AAC3F,MAAM,CAAC,MAAM,mBAAmB,GAAG,6BAA6B,CAAC;AAEjE,4FAA4F;AAC5F,MAAM,OAAO,eAAgB,SAAQ,KAAK;IACxC,YAAY,IAAY;QACtB,KAAK,CACH,IAAI,IAAI,sJAAsJ,CAC/J,CAAC;QACF,IAAI,CAAC,IAAI,GAAG,iBAAiB,CAAC;IAChC,CAAC;CACF;AAiCD,sEAAsE;AACtE,SAAS,gBAAgB,CAAC,IAAY;IACpC,IAAI,CAAC,mBAAmB,CAAC,IAAI,CAAC,IAAI,CAAC;QAAE,MAAM,IAAI,eAAe,CAAC,IAAI,CAAC,CAAC;AACvE,CAAC;AAED,yCAAyC;AACzC,MAAM,UAAU,eAAe,CAAC,UAAkB,EAAE,IAAY;IAC9D,gBAAgB,CAAC,IAAI,CAAC,CAAC;IACvB,OAAO,IAAI,CAAC,UAAU,EAAE,qBAAqB,EAAE,IAAI,CAAC,CAAC;AACvD,CAAC;AAED,+DAA+D;AAC/D,SAAS,gBAAgB,CAAC,GAAW,EAAE,QAAgB,EAAE,OAAuB;IAC9E,OAAO,IAAI,CAAC,GAAG,EAAE,QAAQ,EAAE,GAAG,OAAO,OAAO,CAAC,CAAC;AAChD,CAAC;AAED,oDAAoD;AACpD,SAAS,UAAU,CAAC,GAAW,EAAE,QAAgB,EAAE,KAAuB;IACxE,SAAS,CAAC,IAAI,CAAC,GAAG,EAAE,QAAQ,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IACpD,KAAK,MAAM,OAAO,IAAI,gBAAgB,EAAE,CAAC;QACvC,aAAa,CACX,gBAAgB,CAAC,GAAG,EAAE,QAAQ,EAAE,OAAO,CAAC,EACxC,GAAG,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,IAAI,EACrC,MAAM,CACP,CAAC;IACJ,CAAC;IACD,8EAA8E;IAC9E,0EAA0E;IAC1E,wEAAwE;IACxE,aAAa,CACX,IAAI,CAAC,GAAG,EAAE,QAAQ,EAAE,UAAU,CAAC,EAC/B,GAAG,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,KAAK,IAAI,cAAc,EAAE,CAAC,IAAI,EACtD,MAAM,CACP,CAAC;IACF,aAAa,CAAC,IAAI,CAAC,GAAG,EAAE,QAAQ,EAAE,uBAAuB,CAAC,EAAE,GAAG,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,iBAAiB,IAAI,IAAI,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;AAC9H,CAAC;AAED,iFAAiF;AACjF,SAAS,qBAAqB,CAAC,GAAW,EAAE,QAAgB;IAC1D,MAAM,IAAI,GAAG,IAAI,CAAC,GAAG,EAAE,QAAQ,EAAE,uBAAuB,CAAC,CAAC;IAC1D,MAAM,aAAa,GAAG,CAAC,UAAU,CAAC,IAAI,CAAC,CAAC;IACxC,IAAI,aAAa;QAAE,OAAO,SAAS,CAAC;IACpC,MAAM,QAAQ,GAAY,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC,CAAC;IACjE,MAAM,aAAa,GAAG,QAAQ,KAAK,IAAI,CAAC;IACxC,IAAI,aAAa;QAAE,OAAO,SAAS,CAAC;IACpC,MAAM,WAAW,GAAG,QAAQ,KAAK,kBAAkB,CAAC;IACpD,IAAI,WAAW;QAAE,OAAO,QAAQ,CAAC;IACjC,MAAM,IAAI,KAAK,CAAC,uDAAuD,CAAC,CAAC;AAC3E,CAAC;AAED,yFAAyF;AACzF,SAAS,kBAAkB,CAAC,GAAW,EAAE,QAAgB,EAAE,OAAuB;IAChF,MAAM,IAAI,GAAG,gBAAgB,CAAC,GAAG,EAAE,QAAQ,EAAE,OAAO,CAAC,CAAC;IACtD,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC;QAAE,OAAO,IAAI,CAAC;IACnC,OAAO,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC,CAAC;AAChD,CAAC;AAED,iFAAiF;AACjF,SAAS,SAAS,CAAC,GAAW,EAAE,QAAgB;IAC9C,MAAM,IAAI,GAAG,IAAI,CAAC,GAAG,EAAE,QAAQ,EAAE,UAAU,CAAC,CAAC;IAC7C,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC;QAAE,OAAO,cAAc,EAAE,CAAC;IAC/C,OAAO,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,IAAI,EAAE,MAAM,CAAC,CAAsB,CAAC;AACrE,CAAC;AAED,kFAAkF;AAClF,SAAS,SAAS,CAAC,GAAW,EAAE,QAAgB;IAC9C,OAAO;QACL,KAAK,EAAE,SAAS,CAAC,GAAG,EAAE,QAAQ,CAAC;QAC/B,iBAAiB,EAAE,qBAAqB,CAAC,GAAG,EAAE,QAAQ,CAAC;QACvD,SAAS,EAAE,CAAC,kBAAkB,CAAC,GAAG,EAAE,QAAQ,EAAE,WAAW,CAAC,IAAI,EAAE,CAAkC;QAClG,QAAQ,EAAE,kBAAkB,CAAC,GAAG,EAAE,QAAQ,EAAE,UAAU,CAAiC;QACvF,OAAO,EAAE,CAAC,kBAAkB,CAAC,GAAG,EAAE,QAAQ,EAAE,SAAS,CAAC,IAAI,EAAE,CAAgC;QAC5F,IAAI,EAAE,CAAC,kBAAkB,CAAC,GAAG,EAAE,QAAQ,EAAE,MAAM,CAAC,IAAI;YAClD,KAAK,EAAE,EAAE;YACT,SAAS,EAAE,EAAE;SACd,CAA6B;QAC9B,KAAK,EAAE,CAAC,kBAAkB,CAAC,GAAG,EAAE,QAAQ,EAAE,OAAO,CAAC,IAAI;YACpD,SAAS,EAAE,EAAE;YACb,QAAQ,EAAE,IAAI;YACd,OAAO,EAAE,IAAI;SACd,CAA8B;KAChC,CAAC;AACJ,CAAC;AAED;;;;;GAKG;AACH,MAAM,CAAC,KAAK,UAAU,UAAU,CAC9B,UAAkB,EAClB,IAAY,EACZ,MAAc,EACd,OAA0B;IAE1B,MAAM,GAAG,GAAG,eAAe,CAAC,UAAU,EAAE,IAAI,CAAC,CAAC;IAC9C,MAAM,QAAQ,GAAmB;QAC/B,MAAM,EAAE,aAAa;QACrB,OAAO,EAAE,OAAO,CAAC,OAAO,IAAI,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;QACpD,IAAI,EAAE,OAAO,CAAC,IAAI;QAClB,UAAU,EAAE,MAAM,CAAC,MAAM,CAAC,MAAM;KACjC,CAAC;IACF,MAAM,OAAO,GAAG,MAAM,gBAAgB,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;IACvD,SAAS,CAAC,GAAG,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IACpC,UAAU,CAAC,GAAG,EAAE,cAAc,EAAE,MAAM,CAAC,IAAI,CAAC,CAAC;IAC7C,UAAU,CAAC,GAAG,EAAE,eAAe,EAAE,OAAO,CAAC,CAAC;IAC1C,aAAa,CAAC,IAAI,CAAC,GAAG,EAAE,WAAW,CAAC,EAAE,GAAG,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,MAAM,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;IACpF,MAAM,kBAAkB,GAAG,IAAI,CAAC,GAAG,EAAE,oBAAoB,CAAC,CAAC;IAC3D,MAAM,iBAAiB,GAAG,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,cAAc,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC;IACxE,IAAI,iBAAiB,EAAE,CAAC;QACtB,aAAa,CAAC,kBAAkB,EAAE,GAAG,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,cAAc,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;IAC1F,CAAC;SAAM,CAAC;QACN,MAAM,CAAC,kBAAkB,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC;IAC9C,CAAC;IACD,aAAa,CAAC,IAAI,CAAC,GAAG,EAAE,aAAa,CAAC,EAAE,GAAG,IAAI,CAAC,SAAS,CAAC,QAAQ,EAAE,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;IAC1F,OAAO,QAAQ,CAAC;AAClB,CAAC;AAED,qFAAqF;AACrF,SAAS,YAAY,CAAC,GAAW;IAC/B,MAAM,IAAI,GAAG,IAAI,CAAC,GAAG,EAAE,aAAa,CAAC,CAAC;IACtC,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC;QAAE,OAAO,IAAI,CAAC;IACnC,IAAI,MAA+B,CAAC;IACpC,IAAI,CAAC;QACH,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,IAAI,EAAE,MAAM,CAAC,CAA4B,CAAC;IAC7E,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC;IACd,CAAC;IACD,IAAI,MAAM,CAAC,MAAM,KAAK,aAAa;QAAE,OAAO,IAAI,CAAC;IACjD,IAAI,OAAO,MAAM,CAAC,OAAO,KAAK,QAAQ;QAAE,OAAO,IAAI,CAAC;IACpD,IAAI,OAAO,MAAM,CAAC,IAAI,KAAK,QAAQ;QAAE,OAAO,IAAI,CAAC;IACjD,IAAI,OAAO,MAAM,CAAC,UAAU,KAAK,QAAQ;QAAE,OAAO,IAAI,CAAC;IACvD,OAAO;QACL,MAAM,EAAE,aAAa;QACrB,OAAO,EAAE,MAAM,CAAC,OAAO;QACvB,IAAI,EAAE,MAAM,CAAC,IAAI;QACjB,UAAU,EAAE,MAAM,CAAC,UAAU;KAC9B,CAAC;AACJ,CAAC;AAED,oFAAoF;AACpF,SAAS,kBAAkB,CAAC,GAAW;IACrC,MAAM,IAAI,GAAG,IAAI,CAAC,GAAG,EAAE,oBAAoB,CAAC,CAAC;IAC7C,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC;QAAE,OAAO,EAAE,CAAC;IACjC,OAAO,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,IAAI,EAAE,MAAM,CAAC,CAAyB,CAAC;AACxE,CAAC;AAED,kDAAkD;AAClD,SAAS,UAAU,CAAC,GAAW;IAC7B,MAAM,IAAI,GAAG,IAAI,CAAC,GAAG,EAAE,WAAW,CAAC,CAAC;IACpC,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC;QAAE,OAAO,EAAE,CAAC;IACjC,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,IAAI,EAAE,MAAM,CAAC,CAAY,CAAC;IACjE,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC;QAAE,OAAO,EAAE,CAAC;IACtC,OAAO,MAAwB,CAAC;AAClC,CAAC;AAED;;;;;;GAMG;AACH,MAAM,CAAC,KAAK,UAAU,UAAU,CAC9B,UAAkB,EAClB,IAAY;IAEZ,MAAM,GAAG,GAAG,eAAe,CAAC,UAAU,EAAE,IAAI,CAAC,CAAC;IAC9C,MAAM,QAAQ,GAAG,YAAY,CAAC,GAAG,CAAC,CAAC;IACnC,IAAI,QAAQ,KAAK,IAAI;QAAE,OAAO,IAAI,CAAC;IACnC,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,SAAS,CAAC,GAAG,EAAE,eAAe,CAAC,EAAE,kBAAkB,CAAC,GAAG,CAAC,CAAC,CAAC;IACpF,MAAM,MAAM,GAAW;QACrB,OAAO,EAAE,MAAM,CAAC,OAAO;QACvB,cAAc,EAAE,MAAM,CAAC,cAAc;QACrC,IAAI,EAAE,SAAS,CAAC,GAAG,EAAE,cAAc,CAAC;QACpC,MAAM,EAAE,UAAU,CAAC,GAAG,CAAC;QACvB,SAAS,EAAE,KAAK;KACjB,CAAC;IACF,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,CAAC;AACpC,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,YAAY,CAAC,UAAkB;IAC7C,MAAM,IAAI,GAAG,IAAI,CAAC,UAAU,EAAE,qBAAqB,CAAC,CAAC;IACrD,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC;QAAE,OAAO,EAAE,CAAC;IACjC,MAAM,MAAM,GAAoB,EAAE,CAAC;IACnC,KAAK,MAAM,KAAK,IAAI,WAAW,CAAC,IAAI,EAAE,EAAE,aAAa,EAAE,IAAI,EAAE,CAAC,EAAE,CAAC;QAC/D,IAAI,CAAC,KAAK,CAAC,WAAW,EAAE;YAAE,SAAS;QACnC,IAAI,CAAC,mBAAmB,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC;YAAE,SAAS;QACpD,MAAM,QAAQ,GAAG,YAAY,CAAC,IAAI,CAAC,IAAI,EAAE,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC;QACtD,IAAI,QAAQ,KAAK,IAAI;YAAE,SAAS;QAChC,MAAM,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,KAAK,CAAC,IAAI,EAAE,GAAG,QAAQ,EAAE,CAAC,CAAC;IACjD,CAAC;IACD,OAAO,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,aAAa,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC;AAC7D,CAAC;AAED,4EAA4E;AAC5E,MAAM,UAAU,YAAY,CAAC,UAAkB,EAAE,IAAY;IAC3D,MAAM,GAAG,GAAG,eAAe,CAAC,UAAU,EAAE,IAAI,CAAC,CAAC;IAC9C,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC;QAAE,OAAO,KAAK,CAAC;IACnC,MAAM,CAAC,GAAG,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC;IAC9C,OAAO,IAAI,CAAC;AACd,CAAC"}

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

@@ -0,0 +1,39 @@
+/**
+ * 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 { type FullSandboxState, type FullStateCaptureOptions } from '../full-state.js';
+import type { LocalSandbox } from '../types/service.js';
+import { type Checkpoint, type CheckpointCounts } from './types.js';
+/** How much each service holds in one state. */
+export declare function countsOf(state: FullSandboxState): CheckpointCounts;
+/**
+ * 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 declare function captureCheckpoint(sandbox: LocalSandbox, options?: FullStateCaptureOptions): Promise<Checkpoint>;
+/**
+ * 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 declare function restoreCheckpoint(sandbox: LocalSandbox, checkpoint: Checkpoint): Promise<void>;
+//# sourceMappingURL=capture.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"capture.d.ts","sourceRoot":"","sources":["../../../src/sandbox/checkpoints/capture.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,EAAoC,KAAK,gBAAgB,EAAE,KAAK,uBAAuB,EAAE,MAAM,kBAAkB,CAAC;AACzH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AAExD,OAAO,EAAqB,KAAK,UAAU,EAAE,KAAK,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAmBvF,gDAAgD;AAChD,wBAAgB,QAAQ,CAAC,KAAK,EAAE,gBAAgB,GAAG,gBAAgB,CAOlE;AAED;;;;;GAKG;AACH,wBAAsB,iBAAiB,CAAC,OAAO,EAAE,YAAY,EAAE,OAAO,GAAE,uBAA4B,GAAG,OAAO,CAAC,UAAU,CAAC,CAGzH;AAED;;;;;;;;;;;;GAYG;AACH,wBAAsB,iBAAiB,CACrC,OAAO,EAAE,YAAY,EACrB,UAAU,EAAE,UAAU,GACrB,OAAO,CAAC,IAAI,CAAC,CAIf"}

package/dist/sandbox/checkpoints/capture.js

@@ -0,0 +1,69 @@
+/**
+ * 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 } from '../full-state.js';
+import { getClock } from '../clock.js';
+import { CHECKPOINT_FORMAT } from './types.js';
+import { assertCheckpointState } from './validation.js';
+/** True when a JSON value is a plain object with keys to count. */
+function isCountableTree(value) {
+    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) {
+    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) {
+    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, options = {}) {
+    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, checkpoint) {
+    assertCheckpointState(checkpoint.state);
+    sandbox.reset();
+    await applyFullState(sandbox, checkpoint.state);
+}
+//# sourceMappingURL=capture.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"capture.js","sourceRoot":"","sources":["../../../src/sandbox/checkpoints/capture.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,EAAE,cAAc,EAAE,gBAAgB,EAAuD,MAAM,kBAAkB,CAAC;AAEzH,OAAO,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AACvC,OAAO,EAAE,iBAAiB,EAA0C,MAAM,YAAY,CAAC;AACvF,OAAO,EAAE,qBAAqB,EAAE,MAAM,iBAAiB,CAAC;AAExD,mEAAmE;AACnE,SAAS,eAAe,CAAC,KAAc;IACrC,OAAO,KAAK,KAAK,IAAI,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;AAC9E,CAAC;AAED;;;;GAIG;AACH,SAAS,kBAAkB,CAAC,QAAsC;IAChE,IAAI,CAAC,eAAe,CAAC,QAAQ,CAAC;QAAE,OAAO,CAAC,CAAC;IACzC,MAAM,IAAI,GAAG,eAAe,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,QAAQ,CAAC;IACvE,OAAO,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,MAAM,CAAC;AAClC,CAAC;AAED,gDAAgD;AAChD,MAAM,UAAU,QAAQ,CAAC,KAAuB;IAC9C,OAAO;QACL,SAAS,EAAE,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,SAAS,CAAC,CAAC,MAAM;QAC9C,QAAQ,EAAE,kBAAkB,CAAC,KAAK,CAAC,QAAQ,CAAC;QAC5C,OAAO,EAAE,KAAK,CAAC,OAAO,CAAC,MAAM;QAC7B,IAAI,EAAE,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,MAAM;KAC9B,CAAC;AACJ,CAAC;AAED;;;;;GAKG;AACH,MAAM,CAAC,KAAK,UAAU,iBAAiB,CAAC,OAAqB,EAAE,UAAmC,EAAE;IAClG,MAAM,KAAK,GAAG,MAAM,gBAAgB,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;IACvD,OAAO,EAAE,MAAM,EAAE,iBAAiB,EAAE,EAAE,EAAE,QAAQ,CAAC,OAAO,CAAC,CAAC,GAAG,EAAE,EAAE,MAAM,EAAE,QAAQ,CAAC,KAAK,CAAC,EAAE,KAAK,EAAE,CAAC;AACpG,CAAC;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,CAAC,KAAK,UAAU,iBAAiB,CACrC,OAAqB,EACrB,UAAsB;IAEtB,qBAAqB,CAAC,UAAU,CAAC,KAAK,CAAC,CAAC;IACxC,OAAO,CAAC,KAAK,EAAE,CAAC;IAChB,MAAM,cAAc,CAAC,OAAO,EAAE,UAAU,CAAC,KAAK,CAAC,CAAC;AAClD,CAAC"}

package/dist/sandbox/checkpoints/directory-backend.d.ts

@@ -0,0 +1,30 @@
+/**
+ * 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 { type CheckpointBackend } from './types.js';
+/** Where checkpoints live, relative to the project directory. */
+export declare const CHECKPOINT_STORE_RELATIVE: string;
+/**
+ * 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 declare function directoryCheckpointBackend(projectDir: string): CheckpointBackend;
+//# sourceMappingURL=directory-backend.d.ts.map

package/dist/sandbox/checkpoints/directory-backend.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"directory-backend.d.ts","sourceRoot":"","sources":["../../../src/sandbox/checkpoints/directory-backend.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAKH,OAAO,EAKL,KAAK,iBAAiB,EAEvB,MAAM,YAAY,CAAC;AAEpB,iEAAiE;AACjE,eAAO,MAAM,yBAAyB,QAAyC,CAAC;AAuChF;;;;;GAKG;AACH,wBAAgB,0BAA0B,CAAC,UAAU,EAAE,MAAM,GAAG,iBAAiB,CA+BhF"}

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

@@ -0,0 +1,98 @@
+/**
+ * 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, } 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) {
+    return join(projectDir, CHECKPOINT_STORE_RELATIVE);
+}
+/** The file one checkpoint occupies. */
+function checkpointPath(projectDir, name) {
+    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) {
+    if (!existsSync(path))
+        return null;
+    let parsed;
+    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) {
+    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) {
+    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 = [];
+            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;
+        },
+    };
+}
+//# sourceMappingURL=directory-backend.js.map

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

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

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

@@ -0,0 +1,15 @@
+/**
+ * `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';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/sandbox/checkpoints/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,OAAO,EAAE,iBAAiB,EAAE,QAAQ,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAC;AAC9E,OAAO,EAAE,uBAAuB,EAAE,MAAM,qBAAqB,CAAC;AAC9D,OAAO,EACL,eAAe,EACf,eAAe,EACf,cAAc,EACd,gBAAgB,EAChB,sBAAsB,EACtB,cAAc,GACf,MAAM,mBAAmB,CAAC;AAC3B,YAAY,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AACzD,OAAO,EACL,iBAAiB,EACjB,uBAAuB,EACvB,mBAAmB,EACnB,oBAAoB,EACpB,oBAAoB,GACrB,MAAM,YAAY,CAAC;AACpB,YAAY,EACV,UAAU,EACV,iBAAiB,EACjB,gBAAgB,EAChB,iBAAiB,GAClB,MAAM,YAAY,CAAC"}

package/dist/sandbox/checkpoints/index.js

@@ -0,0 +1,13 @@
+/**
+ * `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 { CHECKPOINT_FORMAT, CHECKPOINT_NAME_PATTERN, CheckpointNameError, assertCheckpointName, isCheckpointEnvelope, } from './types.js';
+//# sourceMappingURL=index.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/sandbox/checkpoints/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,OAAO,EAAE,iBAAiB,EAAE,QAAQ,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAC;AAC9E,OAAO,EAAE,uBAAuB,EAAE,MAAM,qBAAqB,CAAC;AAC9D,OAAO,EACL,eAAe,EACf,eAAe,EACf,cAAc,EACd,gBAAgB,EAChB,sBAAsB,EACtB,cAAc,GACf,MAAM,mBAAmB,CAAC;AAE3B,OAAO,EACL,iBAAiB,EACjB,uBAAuB,EACvB,mBAAmB,EACnB,oBAAoB,EACpB,oBAAoB,GACrB,MAAM,YAAY,CAAC"}

package/dist/sandbox/checkpoints/record-backend.d.ts

@@ -0,0 +1,25 @@
+/**
+ * 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 { type CheckpointBackend } from './types.js';
+/**
+ * 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 declare function recordCheckpointBackend(store: PersistenceBackend): CheckpointBackend;
+//# sourceMappingURL=record-backend.d.ts.map

package/dist/sandbox/checkpoints/record-backend.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"record-backend.d.ts","sourceRoot":"","sources":["../../../src/sandbox/checkpoints/record-backend.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,yBAAyB,CAAC;AAClE,OAAO,EAIL,KAAK,iBAAiB,EAEvB,MAAM,YAAY,CAAC;AAyCpB;;;;;GAKG;AACH,wBAAgB,uBAAuB,CAAC,KAAK,EAAE,kBAAkB,GAAG,iBAAiB,CAsCpF"}