rightsize 0.2.0 → 0.3.0

package/dist/core/checkpoint/api.js

@@ -0,0 +1,138 @@
+import { cacheDir } from "../cache-dir.js";
+import { Backends } from "../backends.js";
+import { requireValidCheckpointName } from "./name.js";
+import { readCheckpointRegistry, removeCheckpointRegistryFile, listCheckpointNames, fromCheckpointRegistryEntry, } from "./registry.js";
+/** Every field of a `Checkpoint` comes straight from the registry entry except `spec`, which is reconstructed via `fromCheckpointRegistryEntry` — see that function's own doc for what is and isn't meaningful in the result. */
+function toCheckpoint(entry) {
+    return { ref: entry.ref, backend: entry.backend, spec: fromCheckpointRegistryEntry(entry) };
+}
+/**
+ * Rediscovers a named checkpoint written by an earlier `checkpoint(name)`
+ * call — in this process or an entirely different one, since the registry
+ * lives on disk under the shared rightsize cache directory. No entry for
+ * `name` resolves to `undefined`. A corrupt entry is treated the same as
+ * absent, with a best-effort delete of the bad file.
+ *
+ * When the entry's own recorded backend matches the CURRENTLY active
+ * backend, the underlying artifact is probed via the backend's
+ * `hasCheckpoint` SPI before this resolves — an artifact that's gone (removed
+ * by hand, or by something outside this library) makes the entry stale: it's
+ * best-effort deleted and this resolves to `undefined`, the same as if it
+ * had never existed. A probe FAILURE (the backend call itself throws) is
+ * never swallowed into a `false` — only a confirmed "does not exist"
+ * resolves that way, so a probe failure propagates out of this call.
+ *
+ * When the entry's recorded backend DIFFERS from the active one, this
+ * returns the entry unprobed — an msb ref means nothing to a docker probe
+ * and vice versa. `GenericContainer.fromCheckpoint(cp).start()`'s own
+ * `CheckpointBackendMismatchError` gate stays the sole authority for that
+ * mismatch; this function must not force-resolve a backend the host may not
+ * even have.
+ *
+ * `name` is validated against `CHECKPOINT_NAME_PATTERN` before anything else
+ * — including before the registry file is even looked up — so a `name`
+ * carrying `../` segments can never reach path construction; an invalid name
+ * throws `InvalidCheckpointNameError` and touches no file.
+ */
+export async function find(name) {
+    requireValidCheckpointName(name);
+    const dir = cacheDir();
+    const read = await readCheckpointRegistry(dir, name);
+    if (read.kind === "missing") {
+        return undefined;
+    }
+    if (read.kind === "corrupt") {
+        await removeCheckpointRegistryFile(dir, name);
+        return undefined;
+    }
+    const entry = read.entry;
+    const active = Backends.active();
+    if (entry.backend !== active.name) {
+        return toCheckpoint(entry);
+    }
+    const exists = await active.hasCheckpoint(entry.ref);
+    if (!exists) {
+        await removeCheckpointRegistryFile(dir, name);
+        return undefined;
+    }
+    return toCheckpoint(entry);
+}
+/**
+ * Every named checkpoint currently in the registry — registry contents
+ * only, never probed against a backend (unlike `find`), so a stale entry
+ * whose artifact is gone still appears here until something calls `find` or
+ * `remove` on it. A corrupt entry is silently skipped, never removed (only
+ * `find`/`remove` clean those up, since `list` never resolves a single name
+ * the caller could target for a retry).
+ */
+export async function list() {
+    const dir = cacheDir();
+    const names = await listCheckpointNames(dir);
+    const checkpoints = [];
+    for (const name of names) {
+        const read = await readCheckpointRegistry(dir, name);
+        if (read.kind === "found") {
+            checkpoints.push(toCheckpoint(read.entry));
+        }
+    }
+    return checkpoints;
+}
+/**
+ * Deletes a named checkpoint: best-effort removal of the backend artifact
+ * (only when the entry's recorded backend matches the currently active
+ * one — this call never touches a backend that isn't active) plus the
+ * registry file, regardless of order of failure in either. Idempotent and
+ * always best-effort: "not found" anywhere (no registry entry at all) is
+ * success, reported as `false`; an existing entry — valid or corrupt —
+ * reports `true` once its registry file is gone.
+ *
+ * When the entry's recorded backend DIFFERS from the currently active one,
+ * only the registry record is deleted — the underlying artifact (the docker
+ * image, or the microsandbox snapshot) is left on disk PERMANENTLY, since
+ * this call never touches a backend that isn't active. Nothing in this
+ * library reclaims it automatically — and once the record is gone, a later
+ * `remove(name)` finds nothing to act on. Remove a checkpoint under its
+ * creating backend in the first place, or clean the leftover artifact
+ * directly with that backend's own CLI one-liner (see the
+ * [checkpoints guide](/guide/checkpoints#cleanup-checkpoints-are-not-auto-reaped)).
+ *
+ * `name` is validated against `CHECKPOINT_NAME_PATTERN` before anything else
+ * — including before the registry file is even looked up — so a `name`
+ * carrying `../` segments can never reach path construction; an invalid name
+ * throws `InvalidCheckpointNameError` and touches no file.
+ */
+export async function remove(name) {
+    requireValidCheckpointName(name);
+    const dir = cacheDir();
+    const read = await readCheckpointRegistry(dir, name);
+    if (read.kind === "missing") {
+        return false;
+    }
+    if (read.kind === "corrupt") {
+        await removeCheckpointRegistryFile(dir, name);
+        return true;
+    }
+    const entry = read.entry;
+    const active = Backends.active();
+    if (entry.backend === active.name) {
+        await active.removeCheckpoint(entry.ref).catch(() => { });
+    }
+    await removeCheckpointRegistryFile(dir, name);
+    return true;
+}
+/**
+ * The library's entry point for rediscovering NAMED checkpoints across
+ * processes — see the [checkpoints guide](/guide/checkpoints#reusing-checkpoints-across-runs)
+ * for the `find(...) ?? seed()` first-run/later-run pattern this exists to
+ * support. Unnamed `checkpoint()` calls never appear here; only a
+ * `checkpoint(name)` call writes a registry entry these functions can find.
+ */
+export const Checkpoints = {
+    /** Rediscovers a named checkpoint — see `find` above. */
+    find,
+    /** Every named checkpoint currently in the registry — see `list` above. */
+    list,
+    /** Deletes a named checkpoint — see `remove` above. */
+    remove,
+};
+//# sourceMappingURL=api.js.map

package/dist/core/checkpoint/api.js.map

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

package/dist/core/checkpoint/name.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Pinned identically across every rightsize language implementation (see the
+ * named-checkpoints spec's own "Names and refs" section): lowercase letters,
+ * digits, and hyphens only, starting with a letter or digit, at most 41
+ * characters. This is also exactly the alphabet both backends' ref formats
+ * embed verbatim (`rz-ckpt-<name>`, `rightsize/checkpoint:<name>`), so a
+ * valid name is guaranteed to produce a valid ref on either backend.
+ */
+export declare const CHECKPOINT_NAME_PATTERN: RegExp;
+/** Fails fast — before any backend or filesystem call — on a `name` that doesn't match `CHECKPOINT_NAME_PATTERN`. */
+export declare function requireValidCheckpointName(name: string): void;
+//# sourceMappingURL=name.d.ts.map

package/dist/core/checkpoint/name.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"name.d.ts","sourceRoot":"","sources":["../../../src/core/checkpoint/name.ts"],"names":[],"mappings":"AAEA;;;;;;;GAOG;AACH,eAAO,MAAM,uBAAuB,QAA8B,CAAC;AAEnE,qHAAqH;AACrH,wBAAgB,0BAA0B,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAI7D"}

package/dist/core/checkpoint/name.js

@@ -0,0 +1,17 @@
+import { InvalidCheckpointNameError } from "../errors.js";
+/**
+ * Pinned identically across every rightsize language implementation (see the
+ * named-checkpoints spec's own "Names and refs" section): lowercase letters,
+ * digits, and hyphens only, starting with a letter or digit, at most 41
+ * characters. This is also exactly the alphabet both backends' ref formats
+ * embed verbatim (`rz-ckpt-<name>`, `rightsize/checkpoint:<name>`), so a
+ * valid name is guaranteed to produce a valid ref on either backend.
+ */
+export const CHECKPOINT_NAME_PATTERN = /^[a-z0-9][a-z0-9-]{0,40}$/;
+/** Fails fast — before any backend or filesystem call — on a `name` that doesn't match `CHECKPOINT_NAME_PATTERN`. */
+export function requireValidCheckpointName(name) {
+    if (!CHECKPOINT_NAME_PATTERN.test(name)) {
+        throw new InvalidCheckpointNameError(name);
+    }
+}
+//# sourceMappingURL=name.js.map

package/dist/core/checkpoint/name.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"name.js","sourceRoot":"","sources":["../../../src/core/checkpoint/name.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,0BAA0B,EAAE,MAAM,cAAc,CAAC;AAE1D;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,uBAAuB,GAAG,2BAA2B,CAAC;AAEnE,qHAAqH;AACrH,MAAM,UAAU,0BAA0B,CAAC,IAAY;IACrD,IAAI,CAAC,uBAAuB,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC;QACxC,MAAM,IAAI,0BAA0B,CAAC,IAAI,CAAC,CAAC;IAC7C,CAAC;AACH,CAAC"}

package/dist/core/checkpoint/ref.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Mints the backend-specific checkpoint ref: `rz-ckpt-<suffix>` on
+ * microsandbox, `rightsize/checkpoint:<suffix>` elsewhere. `name` present
+ * (a NAMED checkpoint) makes the suffix — and therefore the whole ref —
+ * deterministic: re-checkpointing the same name reproduces the exact same
+ * ref, which is what makes the registry's replace semantics (remove the old
+ * artifact under this ref, then create the new one) correct. `name`
+ * `undefined` mints a fresh random 12-hex suffix instead, byte-for-byte the
+ * pre-named-checkpoints behavior.
+ */
+export declare function checkpointRef(backendName: string, name: string | undefined): string;
+//# sourceMappingURL=ref.d.ts.map

package/dist/core/checkpoint/ref.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ref.d.ts","sourceRoot":"","sources":["../../../src/core/checkpoint/ref.ts"],"names":[],"mappings":"AAEA;;;;;;;;;GASG;AACH,wBAAgB,aAAa,CAAC,WAAW,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,CAGnF"}

package/dist/core/checkpoint/ref.js

@@ -0,0 +1,16 @@
+import { randomBytes } from "node:crypto";
+/**
+ * Mints the backend-specific checkpoint ref: `rz-ckpt-<suffix>` on
+ * microsandbox, `rightsize/checkpoint:<suffix>` elsewhere. `name` present
+ * (a NAMED checkpoint) makes the suffix — and therefore the whole ref —
+ * deterministic: re-checkpointing the same name reproduces the exact same
+ * ref, which is what makes the registry's replace semantics (remove the old
+ * artifact under this ref, then create the new one) correct. `name`
+ * `undefined` mints a fresh random 12-hex suffix instead, byte-for-byte the
+ * pre-named-checkpoints behavior.
+ */
+export function checkpointRef(backendName, name) {
+    const suffix = name ?? randomBytes(6).toString("hex");
+    return backendName === "microsandbox" ? `rz-ckpt-${suffix}` : `rightsize/checkpoint:${suffix}`;
+}
+//# sourceMappingURL=ref.js.map

package/dist/core/checkpoint/ref.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ref.js","sourceRoot":"","sources":["../../../src/core/checkpoint/ref.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAE1C;;;;;;;;;GASG;AACH,MAAM,UAAU,aAAa,CAAC,WAAmB,EAAE,IAAwB;IACzE,MAAM,MAAM,GAAG,IAAI,IAAI,WAAW,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC;IACtD,OAAO,WAAW,KAAK,cAAc,CAAC,CAAC,CAAC,WAAW,MAAM,EAAE,CAAC,CAAC,CAAC,wBAAwB,MAAM,EAAE,CAAC;AACjG,CAAC"}

package/dist/core/checkpoint/registry.d.ts

@@ -0,0 +1,107 @@
+import type { ContainerSpec } from "../model.js";
+/**
+ * The reduced, cross-language-pinned subset of `ContainerSpec` a named
+ * checkpoint's registry entry carries — exactly the fields
+ * `GenericContainer.fromCheckpoint()` actually reads (env, command, exposed
+ * ports, memory limit), never the rest (name, image, host ports, mounts,
+ * network topology, `runId`, `keepAlive`). Field names and shapes are part
+ * of the wire format: `env` as a plain object (not an array of pairs, unlike
+ * `ContainerSpec.env`), `command` as an array or `null` (never `undefined` —
+ * JSON has no `undefined`), `exposedPorts` as guest ports only.
+ */
+export interface CheckpointRegistrySpec {
+    readonly env: Record<string, string>;
+    readonly command: ReadonlyArray<string> | null;
+    readonly exposedPorts: ReadonlyArray<number>;
+    readonly memoryLimitMb: number | null;
+}
+/**
+ * One `checkpoints/<name>.json` record: written atomically only after the
+ * backend checkpoint it describes has actually succeeded, and read by
+ * `Checkpoints.find`/`list`/`remove` in this process or a later one. Every
+ * field here is part of the cross-language contract pinned by the
+ * named-checkpoints spec — a Kotlin or Rust process must be able to parse
+ * exactly this shape.
+ */
+export interface CheckpointRegistryEntry {
+    readonly name: string;
+    readonly ref: string;
+    /** The backend that created this checkpoint (e.g. `"microsandbox"`, `"docker"`) — `find`/`remove` only probe/touch the artifact when this matches the CURRENTLY active backend. */
+    readonly backend: string;
+    readonly createdIso: string;
+    readonly spec: CheckpointRegistrySpec;
+}
+/** `<cacheDir>/checkpoints` — the directory every named checkpoint's registry file lives under. */
+export declare function checkpointsDir(cacheDir: string): string;
+/**
+ * `checkpoints/<name>.json`. Validates `name` against
+ * `CHECKPOINT_NAME_PATTERN` itself (throwing `InvalidCheckpointNameError` on
+ * a miss) rather than trusting every caller to have done so already — this
+ * is the one function every registry read/write ultimately funnels through
+ * to build a path, so a defensive check here is what stands between a `../`
+ * name and a path that escapes `checkpoints/` even if some future caller
+ * forgets `requireValidCheckpointName` at its own boundary.
+ */
+export declare function checkpointRegistryPath(cacheDir: string, name: string): string;
+/** The three outcomes reading a registry file can settle to — corrupt is deliberately distinct from missing, since `find`/`remove` react differently to each (see their own docs). */
+export type CheckpointRegistryReadResult = {
+    readonly kind: "missing";
+} | {
+    readonly kind: "corrupt";
+} | {
+    readonly kind: "found";
+    readonly entry: CheckpointRegistryEntry;
+};
+/**
+ * Reads and parses `checkpoints/<name>.json`. `"missing"` means the file
+ * does not exist at all; `"corrupt"` means it exists but isn't a well-shaped
+ * `CheckpointRegistryEntry` — malformed JSON or a missing/mistyped required
+ * field. An invalid `name` (see `checkpointRegistryPath`) throws
+ * `InvalidCheckpointNameError` rather than resolving `"missing"` — the path
+ * is resolved BEFORE the file-read `try`, so that throw is never mistaken
+ * for an ordinary "no file here" miss.
+ */
+export declare function readCheckpointRegistry(cacheDir: string, name: string): Promise<CheckpointRegistryReadResult>;
+/**
+ * Atomically writes `checkpoints/<name>.json` (tmp file + rename, the same
+ * protocol as the reuse registry's `writeRegistryAtomic` and the reaping
+ * ledger's `writeRunRecord`) — called once, only after the backend
+ * checkpoint this entry describes has already succeeded. A concurrent reader
+ * only ever observes either the previous complete file (if this is a
+ * replace) or this one, never a partial write.
+ */
+export declare function writeCheckpointRegistryAtomic(cacheDir: string, name: string, entry: CheckpointRegistryEntry): Promise<void>;
+/** Best-effort delete of `checkpoints/<name>.json`. A file already gone is not an error. */
+export declare function removeCheckpointRegistryFile(cacheDir: string, name: string): Promise<void>;
+/**
+ * Every checkpoint name with a registry file on disk, derived from the
+ * directory listing itself (not from parsing) — includes names whose file
+ * turns out to be corrupt; `Checkpoints.list()` filters those out itself
+ * after reading each one. Excludes the atomic-write tmp files (`.<name>.json.tmp-...`),
+ * which sort before their target thanks to the leading dot but are never a
+ * real entry. `checkpoints/` not existing yet (nothing ever checkpointed
+ * with a name) is not an error — resolves to an empty list.
+ */
+export declare function listCheckpointNames(cacheDir: string): Promise<string[]>;
+/**
+ * The write-side projection: `handle.spec` (a full `ContainerSpec`) down to
+ * the reduced, pinned shape the registry persists. `undefined` fields
+ * normalize to `null` (JSON has no `undefined`); `ports` keeps only the
+ * guest side (the source container's own host ports are never meaningful to
+ * a later restore, which allocates fresh ones).
+ */
+export declare function toCheckpointRegistrySpec(spec: ContainerSpec): CheckpointRegistrySpec;
+/**
+ * The read-side counterpart: reconstructs a `ContainerSpec`-shaped object
+ * from a persisted `CheckpointRegistryEntry`, for handing back as a
+ * `Checkpoint`'s `spec` from `Checkpoints.find`/`list` (which never held the
+ * source container's actual `ContainerSpec`, only what the registry
+ * persisted). Only the four fields `GenericContainer.fromCheckpoint()`
+ * itself reads — `env`, `command`, `ports` (guest side only), and
+ * `memoryLimitMb` — carry real information; every other field is a stable
+ * placeholder, since the registry never persists it. `checkpointRef` mirrors
+ * what a live backend hands back after its own reboot-from-snapshot cycle:
+ * pointing at itself.
+ */
+export declare function fromCheckpointRegistryEntry(entry: CheckpointRegistryEntry): ContainerSpec;
+//# sourceMappingURL=registry.d.ts.map

package/dist/core/checkpoint/registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.d.ts","sourceRoot":"","sources":["../../../src/core/checkpoint/registry.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAGjD;;;;;;;;;GASG;AACH,MAAM,WAAW,sBAAsB;IACrC,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACrC,QAAQ,CAAC,OAAO,EAAE,aAAa,CAAC,MAAM,CAAC,GAAG,IAAI,CAAC;IAC/C,QAAQ,CAAC,YAAY,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC;IAC7C,QAAQ,CAAC,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;CACvC;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,uBAAuB;IACtC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,mLAAmL;IACnL,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,IAAI,EAAE,sBAAsB,CAAC;CACvC;AAED,mGAAmG;AACnG,wBAAgB,cAAc,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAEvD;AAED;;;;;;;;GAQG;AACH,wBAAgB,sBAAsB,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAG7E;AAkDD,sLAAsL;AACtL,MAAM,MAAM,4BAA4B,GACpC;IAAE,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAA;CAAE,GAC5B;IAAE,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAA;CAAE,GAC5B;IAAE,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,uBAAuB,CAAA;CAAE,CAAC;AAExE;;;;;;;;GAQG;AACH,wBAAsB,sBAAsB,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,4BAA4B,CAAC,CAkBlH;AAED;;;;;;;GAOG;AACH,wBAAsB,6BAA6B,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,uBAAuB,GAAG,OAAO,CAAC,IAAI,CAAC,CAOjI;AAED,4FAA4F;AAC5F,wBAAsB,4BAA4B,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAEhG;AAED;;;;;;;;GAQG;AACH,wBAAsB,mBAAmB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAQ7E;AAOD;;;;;;GAMG;AACH,wBAAgB,wBAAwB,CAAC,IAAI,EAAE,aAAa,GAAG,sBAAsB,CAWpF;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,2BAA2B,CAAC,KAAK,EAAE,uBAAuB,GAAG,aAAa,CAezF"}

package/dist/core/checkpoint/registry.js

@@ -0,0 +1,180 @@
+import * as fsp from "node:fs/promises";
+import * as path from "node:path";
+import { requireValidCheckpointName } from "./name.js";
+/** `<cacheDir>/checkpoints` — the directory every named checkpoint's registry file lives under. */
+export function checkpointsDir(cacheDir) {
+    return path.join(cacheDir, "checkpoints");
+}
+/**
+ * `checkpoints/<name>.json`. Validates `name` against
+ * `CHECKPOINT_NAME_PATTERN` itself (throwing `InvalidCheckpointNameError` on
+ * a miss) rather than trusting every caller to have done so already — this
+ * is the one function every registry read/write ultimately funnels through
+ * to build a path, so a defensive check here is what stands between a `../`
+ * name and a path that escapes `checkpoints/` even if some future caller
+ * forgets `requireValidCheckpointName` at its own boundary.
+ */
+export function checkpointRegistryPath(cacheDir, name) {
+    requireValidCheckpointName(name);
+    return path.join(checkpointsDir(cacheDir), `${name}.json`);
+}
+function isCheckpointRegistrySpec(value) {
+    if (typeof value !== "object" || value === null) {
+        return false;
+    }
+    const rec = value;
+    const env = rec["env"];
+    if (typeof env !== "object" || env === null || Array.isArray(env)) {
+        return false;
+    }
+    if (!Object.values(env).every((v) => typeof v === "string")) {
+        return false;
+    }
+    const command = rec["command"];
+    if (command !== null && !(Array.isArray(command) && command.every((c) => typeof c === "string"))) {
+        return false;
+    }
+    const exposedPorts = rec["exposedPorts"];
+    if (!Array.isArray(exposedPorts) || !exposedPorts.every((p) => typeof p === "number")) {
+        return false;
+    }
+    const memoryLimitMb = rec["memoryLimitMb"];
+    if (memoryLimitMb !== null && typeof memoryLimitMb !== "number") {
+        return false;
+    }
+    return true;
+}
+function isCheckpointRegistryEntry(value) {
+    if (typeof value !== "object" || value === null) {
+        return false;
+    }
+    const rec = value;
+    if (typeof rec["name"] !== "string" ||
+        typeof rec["ref"] !== "string" ||
+        typeof rec["backend"] !== "string" ||
+        typeof rec["createdIso"] !== "string") {
+        return false;
+    }
+    return isCheckpointRegistrySpec(rec["spec"]);
+}
+/**
+ * Reads and parses `checkpoints/<name>.json`. `"missing"` means the file
+ * does not exist at all; `"corrupt"` means it exists but isn't a well-shaped
+ * `CheckpointRegistryEntry` — malformed JSON or a missing/mistyped required
+ * field. An invalid `name` (see `checkpointRegistryPath`) throws
+ * `InvalidCheckpointNameError` rather than resolving `"missing"` — the path
+ * is resolved BEFORE the file-read `try`, so that throw is never mistaken
+ * for an ordinary "no file here" miss.
+ */
+export async function readCheckpointRegistry(cacheDir, name) {
+    const registryPath = checkpointRegistryPath(cacheDir, name);
+    let text;
+    try {
+        text = await fsp.readFile(registryPath, "utf8");
+    }
+    catch {
+        return { kind: "missing" };
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(text);
+    }
+    catch {
+        return { kind: "corrupt" };
+    }
+    if (!isCheckpointRegistryEntry(parsed)) {
+        return { kind: "corrupt" };
+    }
+    return { kind: "found", entry: parsed };
+}
+/**
+ * Atomically writes `checkpoints/<name>.json` (tmp file + rename, the same
+ * protocol as the reuse registry's `writeRegistryAtomic` and the reaping
+ * ledger's `writeRunRecord`) — called once, only after the backend
+ * checkpoint this entry describes has already succeeded. A concurrent reader
+ * only ever observes either the previous complete file (if this is a
+ * replace) or this one, never a partial write.
+ */
+export async function writeCheckpointRegistryAtomic(cacheDir, name, entry) {
+    const dir = checkpointsDir(cacheDir);
+    await fsp.mkdir(dir, { recursive: true });
+    const target = checkpointRegistryPath(cacheDir, name);
+    const tmp = path.join(dir, `.${name}.json.tmp-${process.pid}-${Date.now()}`);
+    await fsp.writeFile(tmp, JSON.stringify(entry));
+    await fsp.rename(tmp, target);
+}
+/** Best-effort delete of `checkpoints/<name>.json`. A file already gone is not an error. */
+export async function removeCheckpointRegistryFile(cacheDir, name) {
+    await fsp.unlink(checkpointRegistryPath(cacheDir, name)).catch(() => { });
+}
+/**
+ * Every checkpoint name with a registry file on disk, derived from the
+ * directory listing itself (not from parsing) — includes names whose file
+ * turns out to be corrupt; `Checkpoints.list()` filters those out itself
+ * after reading each one. Excludes the atomic-write tmp files (`.<name>.json.tmp-...`),
+ * which sort before their target thanks to the leading dot but are never a
+ * real entry. `checkpoints/` not existing yet (nothing ever checkpointed
+ * with a name) is not an error — resolves to an empty list.
+ */
+export async function listCheckpointNames(cacheDir) {
+    let entries;
+    try {
+        entries = await fsp.readdir(checkpointsDir(cacheDir));
+    }
+    catch {
+        return [];
+    }
+    return entries.filter((f) => f.endsWith(".json") && !f.startsWith(".")).map((f) => f.slice(0, -".json".length));
+}
+/** The inverse of the env part of `toCheckpointRegistrySpec`: `Record<string,string>` back to the array-of-pairs shape `ContainerSpec.env` uses. */
+function envRecordToPairs(env) {
+    return Object.entries(env);
+}
+/**
+ * The write-side projection: `handle.spec` (a full `ContainerSpec`) down to
+ * the reduced, pinned shape the registry persists. `undefined` fields
+ * normalize to `null` (JSON has no `undefined`); `ports` keeps only the
+ * guest side (the source container's own host ports are never meaningful to
+ * a later restore, which allocates fresh ones).
+ */
+export function toCheckpointRegistrySpec(spec) {
+    const env = {};
+    for (const [key, value] of spec.env) {
+        env[key] = value;
+    }
+    return {
+        env,
+        command: spec.command ?? null,
+        exposedPorts: spec.ports.map((p) => p.guestPort),
+        memoryLimitMb: spec.memoryLimitMb ?? null,
+    };
+}
+/**
+ * The read-side counterpart: reconstructs a `ContainerSpec`-shaped object
+ * from a persisted `CheckpointRegistryEntry`, for handing back as a
+ * `Checkpoint`'s `spec` from `Checkpoints.find`/`list` (which never held the
+ * source container's actual `ContainerSpec`, only what the registry
+ * persisted). Only the four fields `GenericContainer.fromCheckpoint()`
+ * itself reads — `env`, `command`, `ports` (guest side only), and
+ * `memoryLimitMb` — carry real information; every other field is a stable
+ * placeholder, since the registry never persists it. `checkpointRef` mirrors
+ * what a live backend hands back after its own reboot-from-snapshot cycle:
+ * pointing at itself.
+ */
+export function fromCheckpointRegistryEntry(entry) {
+    return {
+        name: entry.name,
+        image: entry.ref,
+        env: envRecordToPairs(entry.spec.env),
+        command: entry.spec.command ?? undefined,
+        ports: entry.spec.exposedPorts.map((guestPort) => ({ hostPort: 0, guestPort })),
+        mounts: [],
+        networkId: undefined,
+        aliases: [],
+        runId: "",
+        memoryLimitMb: entry.spec.memoryLimitMb ?? undefined,
+        keepAlive: false,
+        checkpointRef: entry.ref,
+    };
+}
+//# sourceMappingURL=registry.js.map

package/dist/core/checkpoint/registry.js.map

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

package/dist/core/errors.d.ts

@@ -77,10 +77,11 @@ export declare class IsolationRequiredError extends Error {
 }
 /**
  * Thrown by `checkpoint()` when the active backend's
- * `capabilities.checkpoint` is `false` — microsandbox has no upstream
- * microVM snapshot support today. Thrown before any backend call: the
- * generic layer gates on the capability itself rather than letting the
- * backend's own `commitToImage` reject.
+ * `capabilities.checkpoint` is `false` — both real backends (docker, image
+ * commit; microsandbox, disk snapshot) support it today, so this only fires
+ * against a backend that genuinely lacks the capability (a test double).
+ * Thrown before any backend call: the generic layer gates on the capability
+ * itself rather than letting the backend's own `createCheckpoint` reject.
  */
 export declare class CheckpointUnsupportedError extends Error {
     /** The active backend's name (e.g. `"microsandbox"`). */
@@ -89,4 +90,59 @@ export declare class CheckpointUnsupportedError extends Error {
     /** The active backend's name (e.g. `"microsandbox"`). */
     backend: string);
 }
+/**
+ * Thrown by `GenericContainer.fromCheckpoint(cp).start()` when the active
+ * backend's name doesn't match the backend that created `cp` — a checkpoint
+ * ref is only meaningful to the backend that minted it (a docker image tag
+ * means nothing to `msb`, and a msb snapshot name means nothing to docker).
+ * Thrown before any backend call.
+ */
+export declare class CheckpointBackendMismatchError extends Error {
+    /** The backend that created the checkpoint. */
+    readonly createdOnBackend: string;
+    /** The backend `start()` actually resolved. */
+    readonly activeBackend: string;
+    constructor(
+    /** The backend that created the checkpoint. */
+    createdOnBackend: string, 
+    /** The backend `start()` actually resolved. */
+    activeBackend: string);
+}
+/**
+ * Thrown at `start()` when a container built via `GenericContainer.fromCheckpoint()`
+ * is also marked `withReuse()` — reuse's identity hash never covers
+ * `checkpointRef`, so an adopted sandbox from an earlier process could never
+ * be verified against the checkpoint this container was meant to restore.
+ * Thrown only once reuse is actually double opt-in active, the same
+ * placement as `ReuseWithNetworkError`.
+ */
+export declare class ReuseFromCheckpointError extends Error {
+    constructor();
+}
+/**
+ * Thrown by `copyFileToContainer`/`copyContentToContainer`/
+ * `copyFileFromContainer` when `containerPath` is not absolute — both
+ * backends require an absolute `NAME:/path` shape, so a relative path can
+ * never reach either CLI. Thrown before any backend call.
+ */
+export declare class RelativeContainerPathError extends Error {
+    /** The rejected path, exactly as passed in. */
+    readonly containerPath: string;
+    constructor(
+    /** The rejected path, exactly as passed in. */
+    containerPath: string);
+}
+/**
+ * Thrown by `checkpoint(name)` when `name` doesn't match
+ * `^[a-z0-9][a-z0-9-]{0,40}$` — the same pattern pinned across every
+ * rightsize language implementation. Thrown before any backend or
+ * filesystem call, so a bad name never mints a ref or touches the registry.
+ */
+export declare class InvalidCheckpointNameError extends Error {
+    /** The rejected name, exactly as passed in. */
+    readonly checkpointName: string;
+    constructor(
+    /** The rejected name, exactly as passed in. */
+    checkpointName: string);
+}
 //# sourceMappingURL=errors.d.ts.map

package/dist/core/errors.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../src/core/errors.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,qBAAa,yBAA0B,SAAQ,KAAK;IAEhD,uDAAuD;IACvD,QAAQ,CAAC,OAAO,EAAE,MAAM;IACxB,yDAAyD;IACzD,QAAQ,CAAC,OAAO,EAAE,MAAM;IACxB,qFAAqF;IACrF,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM;;IALxB,uDAAuD;IAC9C,OAAO,EAAE,MAAM;IACxB,yDAAyD;IAChD,OAAO,EAAE,MAAM;IACxB,qFAAqF;IAC5E,MAAM,CAAC,EAAE,MAAM,YAAA;CAK3B;AAED;;;;;;GAMG;AACH,qBAAa,qBAAsB,SAAQ,KAAK;IAG5C,4FAA4F;IAC5F,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO;gBAFxB,OAAO,EAAE,MAAM;IACf,4FAA4F;IACnF,KAAK,CAAC,EAAE,OAAO,YAAA;CAK3B;AAED,gFAAgF;AAChF,qBAAa,oBAAqB,SAAQ,KAAK;gBACjC,OAAO,EAAE,MAAM;CAI5B;AAED,8EAA8E;AAC9E,qBAAa,YAAa,SAAQ,KAAK;gBACzB,OAAO,EAAE,MAAM;CAI5B;AAED,kIAAkI;AAClI,qBAAa,cAAe,SAAQ,KAAK;gBAC3B,OAAO,EAAE,MAAM;CAI5B;AAED;;;;;;;;;GASG;AACH,qBAAa,qBAAsB,SAAQ,KAAK;;CAS/C;AAED;;;;;;GAMG;AACH,qBAAa,sBAAuB,SAAQ,KAAK;IAE7C,mDAAmD;IACnD,QAAQ,CAAC,OAAO,EAAE,MAAM;;IADxB,mDAAmD;IAC1C,OAAO,EAAE,MAAM;CAS3B;AAED;;;;;;GAMG;AACH,qBAAa,0BAA2B,SAAQ,KAAK;IAEjD,yDAAyD;IACzD,QAAQ,CAAC,OAAO,EAAE,MAAM;;IADxB,yDAAyD;IAChD,OAAO,EAAE,MAAM;CAS3B"}
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../src/core/errors.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,qBAAa,yBAA0B,SAAQ,KAAK;IAEhD,uDAAuD;IACvD,QAAQ,CAAC,OAAO,EAAE,MAAM;IACxB,yDAAyD;IACzD,QAAQ,CAAC,OAAO,EAAE,MAAM;IACxB,qFAAqF;IACrF,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM;;IALxB,uDAAuD;IAC9C,OAAO,EAAE,MAAM;IACxB,yDAAyD;IAChD,OAAO,EAAE,MAAM;IACxB,qFAAqF;IAC5E,MAAM,CAAC,EAAE,MAAM,YAAA;CAK3B;AAED;;;;;;GAMG;AACH,qBAAa,qBAAsB,SAAQ,KAAK;IAG5C,4FAA4F;IAC5F,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO;gBAFxB,OAAO,EAAE,MAAM;IACf,4FAA4F;IACnF,KAAK,CAAC,EAAE,OAAO,YAAA;CAK3B;AAED,gFAAgF;AAChF,qBAAa,oBAAqB,SAAQ,KAAK;gBACjC,OAAO,EAAE,MAAM;CAI5B;AAED,8EAA8E;AAC9E,qBAAa,YAAa,SAAQ,KAAK;gBACzB,OAAO,EAAE,MAAM;CAI5B;AAED,kIAAkI;AAClI,qBAAa,cAAe,SAAQ,KAAK;gBAC3B,OAAO,EAAE,MAAM;CAI5B;AAED;;;;;;;;;GASG;AACH,qBAAa,qBAAsB,SAAQ,KAAK;;CAS/C;AAED;;;;;;GAMG;AACH,qBAAa,sBAAuB,SAAQ,KAAK;IAE7C,mDAAmD;IACnD,QAAQ,CAAC,OAAO,EAAE,MAAM;;IADxB,mDAAmD;IAC1C,OAAO,EAAE,MAAM;CAS3B;AAED;;;;;;;GAOG;AACH,qBAAa,0BAA2B,SAAQ,KAAK;IAEjD,yDAAyD;IACzD,QAAQ,CAAC,OAAO,EAAE,MAAM;;IADxB,yDAAyD;IAChD,OAAO,EAAE,MAAM;CAQ3B;AAED;;;;;;GAMG;AACH,qBAAa,8BAA+B,SAAQ,KAAK;IAErD,+CAA+C;IAC/C,QAAQ,CAAC,gBAAgB,EAAE,MAAM;IACjC,+CAA+C;IAC/C,QAAQ,CAAC,aAAa,EAAE,MAAM;;IAH9B,+CAA+C;IACtC,gBAAgB,EAAE,MAAM;IACjC,+CAA+C;IACtC,aAAa,EAAE,MAAM;CASjC;AAED;;;;;;;GAOG;AACH,qBAAa,wBAAyB,SAAQ,KAAK;;CASlD;AAED;;;;;GAKG;AACH,qBAAa,0BAA2B,SAAQ,KAAK;IAEjD,+CAA+C;IAC/C,QAAQ,CAAC,aAAa,EAAE,MAAM;;IAD9B,+CAA+C;IACtC,aAAa,EAAE,MAAM;CAKjC;AAED;;;;;GAKG;AACH,qBAAa,0BAA2B,SAAQ,KAAK;IAEjD,+CAA+C;IAC/C,QAAQ,CAAC,cAAc,EAAE,MAAM;;IAD/B,+CAA+C;IACtC,cAAc,EAAE,MAAM;CASlC"}