rightsize 0.3.0 → 0.4.0

package/dist/backend-msb/commands.d.ts

@@ -14,6 +14,12 @@ export declare const MsbCommands: {
     snapshotRemove(name: string): string[];
     /** `msb snapshot inspect <name>` — exit 0 means the snapshot exists, non-zero means it doesn't; `hasCheckpoint`'s backend call. */
     snapshotInspect(name: string): string[];
+    /** `msb snapshot export <ref> <dest>` — writes a `.tar.zst` artifact archive; deliberately never `--with-image` (its import fails an integrity check in 0.6.6, see the checkpoints guide). `exportCheckpoint`'s backend call. */
+    snapshotExport(ref: string, dest: string): string[];
+    /** `msb snapshot import <archive>` — unpacks into a digest-derived directory under `~/.microsandbox/snapshots/`, never the original name; `importCheckpoint`'s backend call. */
+    snapshotImport(archive: string): string[];
+    /** `msb snapshot list --format json` — full `digest`/`name`/`artifact_path`/`image_ref` entries, used to CONFIRM an imported snapshot's digest-dir basename is present (the basename itself, not the `digest` field, is the effective ref — the full digest does not resolve as a snapshot ref). */
+    snapshotList(): string[];
     /** `msb copy -q <hostPath> <name>:<containerPath>` — host-to-guest transfer, `cp -r`-style destination naming for a directory source. */
     copyIn(hostPath: string, name: string, containerPath: string): string[];
     /** `msb copy -q <name>:<containerPath> <hostPath>` — the reverse direction of `copyIn`. */

package/dist/backend-msb/commands.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"commands.d.ts","sourceRoot":"","sources":["../../src/backend-msb/commands.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AAEtD;;;;;;GAMG;AACH,eAAO,MAAM,WAAW;cACZ,aAAa,GAAG,MAAM,EAAE;IAgClC,0JAA0J;4BAClI,MAAM,QAAQ,MAAM,GAAG,MAAM,EAAE;IAIvD,yGAAyG;yBACpF,MAAM,GAAG,MAAM,EAAE;IAItC,mIAAmI;0BAC7G,MAAM,GAAG,MAAM,EAAE;IAIvC,yIAAyI;qBACxH,MAAM,QAAQ,MAAM,iBAAiB,MAAM,GAAG,MAAM,EAAE;IAIvE,2FAA2F;kBAC7E,MAAM,iBAAiB,MAAM,YAAY,MAAM,GAAG,MAAM,EAAE;eAI7D,MAAM,OAAO,SAAS,MAAM,EAAE,GAAG,MAAM,EAAE;qBAInC,MAAM,OAAO,SAAS,MAAM,EAAE,GAAG,MAAM,EAAE;eAI/C,MAAM,GAAG,MAAM,EAAE;qBAIX,MAAM,GAAG,MAAM,EAAE;eAIvB,MAAM,GAAG,MAAM,EAAE;aAInB,MAAM,GAAG,MAAM,EAAE;UAIpB,MAAM,EAAE;IAKd;;;;;;;OAOG;2BACoB,MAAM,GAAG,MAAM,EAAE;CAGzC,CAAC"}
+{"version":3,"file":"commands.d.ts","sourceRoot":"","sources":["../../src/backend-msb/commands.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AAEtD;;;;;;GAMG;AACH,eAAO,MAAM,WAAW;cACZ,aAAa,GAAG,MAAM,EAAE;IAgClC,0JAA0J;4BAClI,MAAM,QAAQ,MAAM,GAAG,MAAM,EAAE;IAIvD,yGAAyG;yBACpF,MAAM,GAAG,MAAM,EAAE;IAItC,mIAAmI;0BAC7G,MAAM,GAAG,MAAM,EAAE;IAIvC,iOAAiO;wBAC7M,MAAM,QAAQ,MAAM,GAAG,MAAM,EAAE;IAInD,gLAAgL;4BACxJ,MAAM,GAAG,MAAM,EAAE;IAIzC,oSAAoS;oBACpR,MAAM,EAAE;IAIxB,yIAAyI;qBACxH,MAAM,QAAQ,MAAM,iBAAiB,MAAM,GAAG,MAAM,EAAE;IAIvE,2FAA2F;kBAC7E,MAAM,iBAAiB,MAAM,YAAY,MAAM,GAAG,MAAM,EAAE;eAI7D,MAAM,OAAO,SAAS,MAAM,EAAE,GAAG,MAAM,EAAE;qBAInC,MAAM,OAAO,SAAS,MAAM,EAAE,GAAG,MAAM,EAAE;eAI/C,MAAM,GAAG,MAAM,EAAE;qBAIX,MAAM,GAAG,MAAM,EAAE;eAIvB,MAAM,GAAG,MAAM,EAAE;aAInB,MAAM,GAAG,MAAM,EAAE;UAIpB,MAAM,EAAE;IAKd;;;;;;;OAOG;2BACoB,MAAM,GAAG,MAAM,EAAE;CAGzC,CAAC"}

package/dist/backend-msb/commands.js

@@ -50,6 +50,18 @@ export const MsbCommands = {
     snapshotInspect(name) {
         return ["snapshot", "inspect", name];
     },
+    /** `msb snapshot export <ref> <dest>` — writes a `.tar.zst` artifact archive; deliberately never `--with-image` (its import fails an integrity check in 0.6.6, see the checkpoints guide). `exportCheckpoint`'s backend call. */
+    snapshotExport(ref, dest) {
+        return ["snapshot", "export", ref, dest];
+    },
+    /** `msb snapshot import <archive>` — unpacks into a digest-derived directory under `~/.microsandbox/snapshots/`, never the original name; `importCheckpoint`'s backend call. */
+    snapshotImport(archive) {
+        return ["snapshot", "import", archive];
+    },
+    /** `msb snapshot list --format json` — full `digest`/`name`/`artifact_path`/`image_ref` entries, used to CONFIRM an imported snapshot's digest-dir basename is present (the basename itself, not the `digest` field, is the effective ref — the full digest does not resolve as a snapshot ref). */
+    snapshotList() {
+        return ["snapshot", "list", "--format", "json"];
+    },
     /** `msb copy -q <hostPath> <name>:<containerPath>` — host-to-guest transfer, `cp -r`-style destination naming for a directory source. */
     copyIn(hostPath, name, containerPath) {
         return ["copy", "-q", hostPath, `${name}:${containerPath}`];

package/dist/backend-msb/commands.js.map

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

package/dist/backend-msb/snapshot-import.d.ts

@@ -0,0 +1,33 @@
+/**
+ * True if `stderr` (an `msb snapshot import` non-zero exit) names msb's own
+ * "this digest is already imported" signal, as opposed to some other import
+ * failure. Observed verbatim against the real msb 0.6.6 binary:
+ *
+ * ```
+ * error: snapshot already exists: <path>
+ * ```
+ *
+ * For a content-addressed archive this IS success — the artifact is already
+ * present under that digest either way — so `importCheckpoint` treats it as
+ * one rather than surfacing it. Deliberately a substring match on the stable
+ * prefix, the same reasoning `isSnapshotNotFoundError` applies to its own
+ * wording: the trailing path varies per host and msb has no structured/typed
+ * error for this.
+ */
+export declare function isSnapshotAlreadyExistsError(stderr: string): boolean;
+/**
+ * Extracts the digest-dir basename from one `msb snapshot import`
+ * invocation's output. Verified against the real msb 0.6.6 binary: on both a
+ * success (the printed stdout line) and an already-exists failure (the
+ * `error: snapshot already exists: <path>` stderr line), the relevant line
+ * ENDS with the artifact path under `~/.microsandbox/snapshots/`, whose
+ * basename is the digest-derived directory name (e.g.
+ * `sha256-b9c0448ee9d54e33`) — never the original archive's own recorded
+ * ref. Callers pass whichever stream actually carries the signal (stdout on
+ * success, stderr on an already-exists failure). `undefined` means the
+ * output carried no recognizable trailing path — a shape this backend
+ * doesn't understand, which the caller turns into its own actionable error
+ * rather than guessing.
+ */
+export declare function parseImportedDigestDirName(output: string): string | undefined;
+//# sourceMappingURL=snapshot-import.d.ts.map

package/dist/backend-msb/snapshot-import.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"snapshot-import.d.ts","sourceRoot":"","sources":["../../src/backend-msb/snapshot-import.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,4BAA4B,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAEpE;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,0BAA0B,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAY7E"}

package/dist/backend-msb/snapshot-import.js

@@ -0,0 +1,48 @@
+import * as path from "node:path";
+/**
+ * True if `stderr` (an `msb snapshot import` non-zero exit) names msb's own
+ * "this digest is already imported" signal, as opposed to some other import
+ * failure. Observed verbatim against the real msb 0.6.6 binary:
+ *
+ * ```
+ * error: snapshot already exists: <path>
+ * ```
+ *
+ * For a content-addressed archive this IS success — the artifact is already
+ * present under that digest either way — so `importCheckpoint` treats it as
+ * one rather than surfacing it. Deliberately a substring match on the stable
+ * prefix, the same reasoning `isSnapshotNotFoundError` applies to its own
+ * wording: the trailing path varies per host and msb has no structured/typed
+ * error for this.
+ */
+export function isSnapshotAlreadyExistsError(stderr) {
+    return stderr.includes("snapshot already exists");
+}
+/**
+ * Extracts the digest-dir basename from one `msb snapshot import`
+ * invocation's output. Verified against the real msb 0.6.6 binary: on both a
+ * success (the printed stdout line) and an already-exists failure (the
+ * `error: snapshot already exists: <path>` stderr line), the relevant line
+ * ENDS with the artifact path under `~/.microsandbox/snapshots/`, whose
+ * basename is the digest-derived directory name (e.g.
+ * `sha256-b9c0448ee9d54e33`) — never the original archive's own recorded
+ * ref. Callers pass whichever stream actually carries the signal (stdout on
+ * success, stderr on an already-exists failure). `undefined` means the
+ * output carried no recognizable trailing path — a shape this backend
+ * doesn't understand, which the caller turns into its own actionable error
+ * rather than guessing.
+ */
+export function parseImportedDigestDirName(output) {
+    const lines = output
+        .split("\n")
+        .map((line) => line.trim())
+        .filter((line) => line.length > 0);
+    const lastLine = lines.at(-1);
+    if (lastLine === undefined) {
+        return undefined;
+    }
+    const match = /(\S+)\s*$/.exec(lastLine);
+    const artifactPath = match?.[1];
+    return artifactPath === undefined ? undefined : path.basename(artifactPath);
+}
+//# sourceMappingURL=snapshot-import.js.map

package/dist/backend-msb/snapshot-import.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"snapshot-import.js","sourceRoot":"","sources":["../../src/backend-msb/snapshot-import.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,IAAI,MAAM,WAAW,CAAC;AAElC;;;;;;;;;;;;;;;GAeG;AACH,MAAM,UAAU,4BAA4B,CAAC,MAAc;IACzD,OAAO,MAAM,CAAC,QAAQ,CAAC,yBAAyB,CAAC,CAAC;AACpD,CAAC;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,0BAA0B,CAAC,MAAc;IACvD,MAAM,KAAK,GAAG,MAAM;SACjB,KAAK,CAAC,IAAI,CAAC;SACX,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC;SAC1B,MAAM,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;IACrC,MAAM,QAAQ,GAAG,KAAK,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC;IAC9B,IAAI,QAAQ,KAAK,SAAS,EAAE,CAAC;QAC3B,OAAO,SAAS,CAAC;IACnB,CAAC;IACD,MAAM,KAAK,GAAG,WAAW,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;IACzC,MAAM,YAAY,GAAG,KAAK,EAAE,CAAC,CAAC,CAAC,CAAC;IAChC,OAAO,YAAY,KAAK,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC,QAAQ,CAAC,YAAY,CAAC,CAAC;AAC9E,CAAC"}

package/dist/backend-msb/snapshot-list.d.ts

@@ -0,0 +1,43 @@
+/**
+ * One `msb snapshot list --format json` entry, the fields
+ * `importCheckpoint`'s presence check actually reads. The current msb
+ * release's shape carries more fields than this (created/size/...); only
+ * `digest`, `name`, and `artifact_path` (snake_case on the wire) matter
+ * here, so everything else is ignored rather than modeled. `digest` itself
+ * is never returned as an effective ref (see `confirmDigestDirNamePresent`)
+ * — it is read only to skip a malformed/empty entry.
+ */
+export interface SnapshotListEntry {
+    readonly digest: string | undefined;
+    readonly name: string | undefined;
+    readonly artifactPath: string | undefined;
+}
+/**
+ * Parses `msb snapshot list --format json`'s array-of-objects output.
+ * Malformed/non-array JSON resolves to an empty list rather than throwing —
+ * the caller (`importCheckpoint`) already turns "digest not found" into its
+ * own actionable `BackendError`, so a parse failure here degrading to "found
+ * nothing" produces the same class of error rather than a confusing crash
+ * one level removed from the actual msb output.
+ */
+export declare function parseSnapshotList(json: string): SnapshotListEntry[];
+/**
+ * Confirms an imported snapshot's digest-dir basename (e.g.
+ * `sha256-b9c0448ee9d54e33`, parsed from `msb snapshot import`'s own
+ * output — see `snapshot-import.ts`) actually appears in `msb snapshot
+ * list`: an entry whose `name` equals `digestDirName` outright, or whose
+ * `artifact_path`'s basename does (`msb snapshot list` was verified to
+ * report both shapes depending on how the snapshot was created).
+ *
+ * Returns `digestDirName` itself once confirmed present — NOT the entry's
+ * `digest` field. Live-verified against msb 0.6.6: the full
+ * `sha256:<64hex>` digest does not resolve as a snapshot ref at all (`msb
+ * snapshot inspect sha256:<full>` fails "snapshot not found" — msb treats
+ * it as a literal path). Only the digest-dir name resolves for
+ * `inspect`/`rm`/`run --snapshot`, so it — not the `digest` field — is the
+ * effective ref `importCheckpoint` must hand back. `undefined` means no
+ * entry matched — the caller throws rather than returning an unconfirmed
+ * ref.
+ */
+export declare function confirmDigestDirNamePresent(entries: readonly SnapshotListEntry[], digestDirName: string): string | undefined;
+//# sourceMappingURL=snapshot-list.d.ts.map

package/dist/backend-msb/snapshot-list.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"snapshot-list.d.ts","sourceRoot":"","sources":["../../src/backend-msb/snapshot-list.ts"],"names":[],"mappings":"AAEA;;;;;;;;GAQG;AACH,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC;IACpC,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,CAAC;IAClC,QAAQ,CAAC,YAAY,EAAE,MAAM,GAAG,SAAS,CAAC;CAC3C;AAED;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG,iBAAiB,EAAE,CAkBnE;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,2BAA2B,CAAC,OAAO,EAAE,SAAS,iBAAiB,EAAE,EAAE,aAAa,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAO5H"}

package/dist/backend-msb/snapshot-list.js

@@ -0,0 +1,53 @@
+import * as path from "node:path";
+/**
+ * Parses `msb snapshot list --format json`'s array-of-objects output.
+ * Malformed/non-array JSON resolves to an empty list rather than throwing —
+ * the caller (`importCheckpoint`) already turns "digest not found" into its
+ * own actionable `BackendError`, so a parse failure here degrading to "found
+ * nothing" produces the same class of error rather than a confusing crash
+ * one level removed from the actual msb output.
+ */
+export function parseSnapshotList(json) {
+    let parsed;
+    try {
+        parsed = JSON.parse(json);
+    }
+    catch {
+        return [];
+    }
+    if (!Array.isArray(parsed)) {
+        return [];
+    }
+    return parsed.map((raw) => {
+        const rec = (typeof raw === "object" && raw !== null ? raw : {});
+        return {
+            digest: typeof rec["digest"] === "string" ? rec["digest"] : undefined,
+            name: typeof rec["name"] === "string" ? rec["name"] : undefined,
+            artifactPath: typeof rec["artifact_path"] === "string" ? rec["artifact_path"] : undefined,
+        };
+    });
+}
+/**
+ * Confirms an imported snapshot's digest-dir basename (e.g.
+ * `sha256-b9c0448ee9d54e33`, parsed from `msb snapshot import`'s own
+ * output — see `snapshot-import.ts`) actually appears in `msb snapshot
+ * list`: an entry whose `name` equals `digestDirName` outright, or whose
+ * `artifact_path`'s basename does (`msb snapshot list` was verified to
+ * report both shapes depending on how the snapshot was created).
+ *
+ * Returns `digestDirName` itself once confirmed present — NOT the entry's
+ * `digest` field. Live-verified against msb 0.6.6: the full
+ * `sha256:<64hex>` digest does not resolve as a snapshot ref at all (`msb
+ * snapshot inspect sha256:<full>` fails "snapshot not found" — msb treats
+ * it as a literal path). Only the digest-dir name resolves for
+ * `inspect`/`rm`/`run --snapshot`, so it — not the `digest` field — is the
+ * effective ref `importCheckpoint` must hand back. `undefined` means no
+ * entry matched — the caller throws rather than returning an unconfirmed
+ * ref.
+ */
+export function confirmDigestDirNamePresent(entries, digestDirName) {
+    const present = entries.some((entry) => entry.digest !== undefined &&
+        (entry.name === digestDirName || (entry.artifactPath !== undefined && path.basename(entry.artifactPath) === digestDirName)));
+    return present ? digestDirName : undefined;
+}
+//# sourceMappingURL=snapshot-list.js.map

package/dist/backend-msb/snapshot-list.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"snapshot-list.js","sourceRoot":"","sources":["../../src/backend-msb/snapshot-list.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,IAAI,MAAM,WAAW,CAAC;AAiBlC;;;;;;;GAOG;AACH,MAAM,UAAU,iBAAiB,CAAC,IAAY;IAC5C,IAAI,MAAe,CAAC;IACpB,IAAI,CAAC;QACH,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;IAC5B,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,EAAE,CAAC;IACZ,CAAC;IACD,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC;QAC3B,OAAO,EAAE,CAAC;IACZ,CAAC;IACD,OAAO,MAAM,CAAC,GAAG,CAAC,CAAC,GAAG,EAAqB,EAAE;QAC3C,MAAM,GAAG,GAAG,CAAC,OAAO,GAAG,KAAK,QAAQ,IAAI,GAAG,KAAK,IAAI,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAA4B,CAAC;QAC5F,OAAO;YACL,MAAM,EAAE,OAAO,GAAG,CAAC,QAAQ,CAAC,KAAK,QAAQ,CAAC,CAAC,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,SAAS;YACrE,IAAI,EAAE,OAAO,GAAG,CAAC,MAAM,CAAC,KAAK,QAAQ,CAAC,CAAC,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,SAAS;YAC/D,YAAY,EAAE,OAAO,GAAG,CAAC,eAAe,CAAC,KAAK,QAAQ,CAAC,CAAC,CAAC,GAAG,CAAC,eAAe,CAAC,CAAC,CAAC,CAAC,SAAS;SAC1F,CAAC;IACJ,CAAC,CAAC,CAAC;AACL,CAAC;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,UAAU,2BAA2B,CAAC,OAAqC,EAAE,aAAqB;IACtG,MAAM,OAAO,GAAG,OAAO,CAAC,IAAI,CAC1B,CAAC,KAAK,EAAE,EAAE,CACR,KAAK,CAAC,MAAM,KAAK,SAAS;QAC1B,CAAC,KAAK,CAAC,IAAI,KAAK,aAAa,IAAI,CAAC,KAAK,CAAC,YAAY,KAAK,SAAS,IAAI,IAAI,CAAC,QAAQ,CAAC,KAAK,CAAC,YAAY,CAAC,KAAK,aAAa,CAAC,CAAC,CAC9H,CAAC;IACF,OAAO,OAAO,CAAC,CAAC,CAAC,aAAa,CAAC,CAAC,CAAC,SAAS,CAAC;AAC7C,CAAC"}

package/dist/core/backend.d.ts

@@ -135,6 +135,35 @@ export interface SandboxBackend {
      * not allowed.
      */
     hasCheckpoint(ref: string): Promise<boolean>;
+    /**
+     * Writes this checkpoint's backend payload to `destFile` — the artifact
+     * step of `Checkpoints.exportTo`, byte-for-byte what the backend's own CLI
+     * produces (docker: `docker save -o <destFile> <ref>`; microsandbox:
+     * `msb snapshot export <ref> <destFile>`, never `--with-image` — see the
+     * checkpoints guide for why). Only ever called once the generic layer has
+     * already confirmed `ref` belongs to the ACTIVE backend and probed it
+     * exists via `hasCheckpoint`; a failure surfaces the underlying tool's
+     * stderr in a `BackendError`, the same convention `copyToContainer` uses.
+     */
+    exportCheckpoint(ref: string, destFile: string): Promise<void>;
+    /**
+     * Materializes an exported archive's backend payload from `srcFile` and
+     * returns the EFFECTIVE ref to use from here on — not necessarily `ref`
+     * itself. docker preserves the original tag on `docker load`, so its
+     * effective ref IS `ref`; microsandbox's `snapshot import` writes under a
+     * digest-derived DIRECTORY NAME (e.g. `sha256-b9c0448ee9d54e33`) it never
+     * lets the caller choose, so its effective ref is that directory name,
+     * confirmed present via `snapshot list --format json` — never the full
+     * `sha256:<64hex>` digest, which does not resolve as a snapshot ref at
+     * all. An already-exists failure for a content-addressed archive is
+     * treated as success. `ref` is the archive's own recorded ref (from
+     * `checkpoint.json`), passed through for backends (docker) that have no
+     * new ref to derive. Only ever called once the generic layer has already
+     * validated the archive's `checkpoint.json` (version, name, backend)
+     * against the active backend; any failure other than "already imported"
+     * surfaces the underlying tool's stderr in a `BackendError`.
+     */
+    importCheckpoint(srcFile: string, ref: string): Promise<string>;
     /**
      * Best-effort stop+remove of a sandbox identified by NAME rather than a
      * `SandboxHandle` — the reaping ledger only ever stores names (it must be

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

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

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

@@ -62,6 +62,51 @@ export declare function list(): Promise<Checkpoint[]>;
  * throws `InvalidCheckpointNameError` and touches no file.
  */
 export declare function remove(name: string): Promise<boolean>;
+/**
+ * Bundles `cp` into a self-describing archive at `destPath`: `checkpoint.json`
+ * (the pinned metadata — format version, this checkpoint's name if it was
+ * ever registered under one, ref, backend, creation time, and spec) plus an
+ * `artifact` member holding the backend's own payload, byte-for-byte what
+ * `SandboxBackend.exportCheckpoint` produces. See the
+ * [checkpoints guide](/guide/checkpoints#moving-checkpoints-between-machines)
+ * for the full CI-cache pattern this exists for.
+ *
+ * Requires the ACTIVE backend to equal `cp.backend` — the same
+ * `CheckpointBackendMismatchError` `fromCheckpoint(cp).start()` throws —
+ * before any backend or filesystem work. Then probes the artifact still
+ * exists via `hasCheckpoint`: exporting a stale checkpoint throws
+ * `CheckpointArtifactMissingError` rather than producing a broken archive.
+ * Only once both checks pass does this stage the export in a fresh unique
+ * temp directory (removed in a `finally` regardless of outcome) and tar it
+ * into `destPath` (parent directories created; a pre-existing file there is
+ * overwritten). Works on an ephemeral (unnamed) checkpoint too — the
+ * resulting archive just carries `name: null`.
+ */
+export declare function exportTo(cp: Checkpoint, destPath: string): Promise<void>;
+/**
+ * The inverse of `exportTo`: extracts `srcPath`, validates its
+ * `checkpoint.json` (format version, `name` against
+ * `CHECKPOINT_NAME_PATTERN` when non-null, backend against the ACTIVE
+ * backend — a `MalformedCheckpointArchiveError` or `CheckpointBackendMismatchError`
+ * either way, before any backend call or registry write), then hands the
+ * extracted `artifact` to `SandboxBackend.importCheckpoint`, which
+ * materializes it and returns the EFFECTIVE ref (docker: the same `ref` the
+ * archive recorded; microsandbox: the digest `snapshot import` actually
+ * assigned it — never necessarily the archive's own `ref`).
+ *
+ * A NAMED archive (`name` non-null) gets replace semantics matching
+ * `checkpoint(name)`: if a registry entry already exists for that name under
+ * a DIFFERENT ref and its recorded backend matches the active one, its old
+ * artifact is best-effort removed first (never a foreign-backend
+ * `removeCheckpoint` call — the same gate `remove()` applies); the registry
+ * entry is then written (or overwritten) with the effective ref. A NAMELESS
+ * archive writes no registry entry at all — the returned `Checkpoint` is
+ * purely ephemeral, the same as an unnamed `checkpoint()` call's result.
+ * Either way, the returned `Checkpoint` restores via the existing
+ * `fromCheckpoint()` path with zero changes — refs are opaque throughout
+ * this library.
+ */
+export declare function importFrom(srcPath: string): Promise<Checkpoint>;
 /**
  * The library's entry point for rediscovering NAMED checkpoints across
  * processes — see the [checkpoints guide](/guide/checkpoints#reusing-checkpoints-across-runs)
@@ -76,5 +121,9 @@ export declare const Checkpoints: {
     list: typeof list;
     /** Deletes a named checkpoint — see `remove` above. */
     remove: typeof remove;
+    /** Bundles a checkpoint into a portable archive — see `exportTo` above. */
+    exportTo: typeof exportTo;
+    /** Materializes a portable archive on this machine — see `importFrom` above. */
+    importFrom: typeof importFrom;
 };
 //# sourceMappingURL=api.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"api.d.ts","sourceRoot":"","sources":["../../../src/core/checkpoint/api.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAe9C;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,wBAAsB,IAAI,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,GAAG,SAAS,CAAC,CAwBxE;AAED;;;;;;;GAOG;AACH,wBAAsB,IAAI,IAAI,OAAO,CAAC,UAAU,EAAE,CAAC,CAWlD;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAsB,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAmB3D;AAED;;;;;;GAMG;AACH,eAAO,MAAM,WAAW;IACtB,yDAAyD;;IAEzD,2EAA2E;;IAE3E,uDAAuD;;CAExD,CAAC"}
+{"version":3,"file":"api.d.ts","sourceRoot":"","sources":["../../../src/core/checkpoint/api.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAoB9C;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,wBAAsB,IAAI,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,GAAG,SAAS,CAAC,CAwBxE;AAED;;;;;;;GAOG;AACH,wBAAsB,IAAI,IAAI,OAAO,CAAC,UAAU,EAAE,CAAC,CAWlD;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAsB,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAmB3D;AAqBD;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAsB,QAAQ,CAAC,EAAE,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAsB9E;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAsB,UAAU,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC,CAqCrE;AAED;;;;;;GAMG;AACH,eAAO,MAAM,WAAW;IACtB,yDAAyD;;IAEzD,2EAA2E;;IAE3E,uDAAuD;;IAEvD,2EAA2E;;IAE3E,gFAAgF;;CAEjF,CAAC"}

package/dist/core/checkpoint/api.js

@@ -1,7 +1,9 @@
 import { cacheDir } from "../cache-dir.js";
 import { Backends } from "../backends.js";
+import { CheckpointArtifactMissingError, CheckpointBackendMismatchError } from "../errors.js";
 import { requireValidCheckpointName } from "./name.js";
-import { readCheckpointRegistry, removeCheckpointRegistryFile, listCheckpointNames, fromCheckpointRegistryEntry, } from "./registry.js";
+import { readCheckpointRegistry, removeCheckpointRegistryFile, writeCheckpointRegistryAtomic, listCheckpointNames, fromCheckpointRegistryEntry, toCheckpointRegistrySpec, } from "./registry.js";
+import { writeCheckpointArchive, readCheckpointArchive, CHECKPOINT_ARCHIVE_VERSION } from "./archive.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) };
@@ -120,6 +122,123 @@ export async function remove(name) {
     await removeCheckpointRegistryFile(dir, name);
     return true;
 }
+/**
+ * Reverse lookup: the registry entry (if any) whose `ref`/`backend` match a
+ * `Checkpoint`'s own — `exportTo`'s only way to learn whether the checkpoint
+ * it's given was ever named, and under what name, since a `Checkpoint`
+ * object itself never carries one (see `toCheckpoint` above). Scans every
+ * registered name the same way `list()` does; a corrupt entry is silently
+ * skipped, matching `list()`'s own tolerance.
+ */
+async function findRegistryEntryByRef(dir, ref, backend) {
+    const names = await listCheckpointNames(dir);
+    for (const name of names) {
+        const read = await readCheckpointRegistry(dir, name);
+        if (read.kind === "found" && read.entry.ref === ref && read.entry.backend === backend) {
+            return read.entry;
+        }
+    }
+    return undefined;
+}
+/**
+ * Bundles `cp` into a self-describing archive at `destPath`: `checkpoint.json`
+ * (the pinned metadata — format version, this checkpoint's name if it was
+ * ever registered under one, ref, backend, creation time, and spec) plus an
+ * `artifact` member holding the backend's own payload, byte-for-byte what
+ * `SandboxBackend.exportCheckpoint` produces. See the
+ * [checkpoints guide](/guide/checkpoints#moving-checkpoints-between-machines)
+ * for the full CI-cache pattern this exists for.
+ *
+ * Requires the ACTIVE backend to equal `cp.backend` — the same
+ * `CheckpointBackendMismatchError` `fromCheckpoint(cp).start()` throws —
+ * before any backend or filesystem work. Then probes the artifact still
+ * exists via `hasCheckpoint`: exporting a stale checkpoint throws
+ * `CheckpointArtifactMissingError` rather than producing a broken archive.
+ * Only once both checks pass does this stage the export in a fresh unique
+ * temp directory (removed in a `finally` regardless of outcome) and tar it
+ * into `destPath` (parent directories created; a pre-existing file there is
+ * overwritten). Works on an ephemeral (unnamed) checkpoint too — the
+ * resulting archive just carries `name: null`.
+ */
+export async function exportTo(cp, destPath) {
+    const active = Backends.active();
+    if (cp.backend !== active.name) {
+        throw new CheckpointBackendMismatchError(cp.backend, active.name);
+    }
+    const exists = await active.hasCheckpoint(cp.ref);
+    if (!exists) {
+        throw new CheckpointArtifactMissingError(cp.ref, cp.backend);
+    }
+    const dir = cacheDir();
+    const registryEntry = await findRegistryEntryByRef(dir, cp.ref, cp.backend);
+    const metadata = {
+        rightsizeArchive: CHECKPOINT_ARCHIVE_VERSION,
+        name: registryEntry?.name ?? null,
+        ref: cp.ref,
+        backend: cp.backend,
+        createdIso: registryEntry?.createdIso ?? new Date().toISOString(),
+        spec: toCheckpointRegistrySpec(cp.spec),
+    };
+    await writeCheckpointArchive(destPath, metadata, (artifactPath) => active.exportCheckpoint(cp.ref, artifactPath));
+}
+/**
+ * The inverse of `exportTo`: extracts `srcPath`, validates its
+ * `checkpoint.json` (format version, `name` against
+ * `CHECKPOINT_NAME_PATTERN` when non-null, backend against the ACTIVE
+ * backend — a `MalformedCheckpointArchiveError` or `CheckpointBackendMismatchError`
+ * either way, before any backend call or registry write), then hands the
+ * extracted `artifact` to `SandboxBackend.importCheckpoint`, which
+ * materializes it and returns the EFFECTIVE ref (docker: the same `ref` the
+ * archive recorded; microsandbox: the digest `snapshot import` actually
+ * assigned it — never necessarily the archive's own `ref`).
+ *
+ * A NAMED archive (`name` non-null) gets replace semantics matching
+ * `checkpoint(name)`: if a registry entry already exists for that name under
+ * a DIFFERENT ref and its recorded backend matches the active one, its old
+ * artifact is best-effort removed first (never a foreign-backend
+ * `removeCheckpoint` call — the same gate `remove()` applies); the registry
+ * entry is then written (or overwritten) with the effective ref. A NAMELESS
+ * archive writes no registry entry at all — the returned `Checkpoint` is
+ * purely ephemeral, the same as an unnamed `checkpoint()` call's result.
+ * Either way, the returned `Checkpoint` restores via the existing
+ * `fromCheckpoint()` path with zero changes — refs are opaque throughout
+ * this library.
+ */
+export async function importFrom(srcPath) {
+    const active = Backends.active();
+    return readCheckpointArchive(srcPath, async (metadata, artifactPath) => {
+        if (metadata.name !== null) {
+            requireValidCheckpointName(metadata.name);
+        }
+        if (metadata.backend !== active.name) {
+            throw new CheckpointBackendMismatchError(metadata.backend, active.name);
+        }
+        const effectiveRef = await active.importCheckpoint(artifactPath, metadata.ref);
+        const spec = fromCheckpointRegistryEntry({
+            name: metadata.name ?? "",
+            ref: effectiveRef,
+            backend: active.name,
+            createdIso: metadata.createdIso,
+            spec: metadata.spec,
+        });
+        if (metadata.name !== null) {
+            const dir = cacheDir();
+            const existing = await readCheckpointRegistry(dir, metadata.name);
+            if (existing.kind === "found" && existing.entry.ref !== effectiveRef && existing.entry.backend === active.name) {
+                await active.removeCheckpoint(existing.entry.ref).catch(() => { });
+            }
+            const entry = {
+                name: metadata.name,
+                ref: effectiveRef,
+                backend: active.name,
+                createdIso: metadata.createdIso,
+                spec: metadata.spec,
+            };
+            await writeCheckpointRegistryAtomic(dir, metadata.name, entry);
+        }
+        return { ref: effectiveRef, backend: active.name, spec };
+    });
+}
 /**
  * The library's entry point for rediscovering NAMED checkpoints across
  * processes — see the [checkpoints guide](/guide/checkpoints#reusing-checkpoints-across-runs)
@@ -134,5 +253,9 @@ export const Checkpoints = {
     list,
     /** Deletes a named checkpoint — see `remove` above. */
     remove,
+    /** Bundles a checkpoint into a portable archive — see `exportTo` above. */
+    exportTo,
+    /** Materializes a portable archive on this machine — see `importFrom` above. */
+    importFrom,
 };
 //# sourceMappingURL=api.js.map

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

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

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

@@ -0,0 +1,52 @@
+import type { CheckpointRegistrySpec } from "./registry.js";
+/** The one archive format version this library understands — pinned identically across every rightsize language implementation. */
+export declare const CHECKPOINT_ARCHIVE_VERSION = 1;
+/**
+ * `checkpoint.json`'s exact shape — pinned identically in every rightsize
+ * language implementation. `name` is `null` for an archive built from an
+ * unnamed (ephemeral) checkpoint; every other field mirrors
+ * `CheckpointRegistryEntry` plus the format version.
+ */
+export interface CheckpointArchiveMetadata {
+    readonly rightsizeArchive: 1;
+    readonly name: string | null;
+    readonly ref: string;
+    readonly backend: string;
+    readonly createdIso: string;
+    readonly spec: CheckpointRegistrySpec;
+}
+/**
+ * Parses and validates `text` (the extracted archive's `checkpoint.json`
+ * content) into a `CheckpointArchiveMetadata`. Every failure — invalid JSON,
+ * a `rightsizeArchive` value other than `CHECKPOINT_ARCHIVE_VERSION` (named
+ * in the thrown error, per the pinned format's own contract), a malformed
+ * `name`/`ref`/`backend`/`createdIso`/`spec` — throws
+ * `MalformedCheckpointArchiveError` naming `archivePath` (the ORIGINAL
+ * archive the caller passed to `importFrom`, not the temp-extracted json
+ * path, so the error is actionable). Never touches a backend or the
+ * registry — pure parsing.
+ */
+export declare function parseCheckpointArchiveMetadata(text: string, archivePath: string): CheckpointArchiveMetadata;
+/**
+ * Builds a checkpoint archive at `destPath`: stages `checkpoint.json` and an
+ * `artifact` file (written by `exportArtifact`, the backend's own
+ * `exportCheckpoint` call) in a fresh temp directory, then tars exactly
+ * those two members at the archive's root — never nested under the temp
+ * dir's own path. `destPath`'s parent directories are created first; a
+ * pre-existing file at `destPath` is overwritten (tar's own default
+ * behavior). The temp directory is removed in a `finally`, on success and on
+ * failure alike.
+ */
+export declare function writeCheckpointArchive(destPath: string, metadata: CheckpointArchiveMetadata, exportArtifact: (artifactPath: string) => Promise<void>): Promise<void>;
+/**
+ * Extracts `srcPath` into a fresh temp directory, parses and validates
+ * `checkpoint.json` (see `parseCheckpointArchiveMetadata`), confirms the
+ * `artifact` member is present, then hands both to `importArtifact` — the
+ * caller's own backend/registry validation and `importCheckpoint` call —
+ * before the temp directory is removed in a `finally`. `srcPath` not
+ * existing, or not being a valid tar, or missing its `checkpoint.json`
+ * member each throw `MalformedCheckpointArchiveError` naming `srcPath`
+ * itself, before any backend call.
+ */
+export declare function readCheckpointArchive<T>(srcPath: string, importArtifact: (metadata: CheckpointArchiveMetadata, artifactPath: string) => Promise<T>): Promise<T>;
+//# sourceMappingURL=archive.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"archive.d.ts","sourceRoot":"","sources":["../../../src/core/checkpoint/archive.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,eAAe,CAAC;AAG5D,mIAAmI;AACnI,eAAO,MAAM,0BAA0B,IAAI,CAAC;AAU5C;;;;;GAKG;AACH,MAAM,WAAW,yBAAyB;IACxC,QAAQ,CAAC,gBAAgB,EAAE,CAAC,CAAC;IAC7B,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,IAAI,EAAE,sBAAsB,CAAC;CACvC;AAWD;;;;;;;;;;GAUG;AACH,wBAAgB,8BAA8B,CAAC,IAAI,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,yBAAyB,CAwC3G;AAED;;;;;;;;;GASG;AACH,wBAAsB,sBAAsB,CAC1C,QAAQ,EAAE,MAAM,EAChB,QAAQ,EAAE,yBAAyB,EACnC,cAAc,EAAE,CAAC,YAAY,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,GACtD,OAAO,CAAC,IAAI,CAAC,CAkBf;AAED;;;;;;;;;GASG;AACH,wBAAsB,qBAAqB,CAAC,CAAC,EAC3C,OAAO,EAAE,MAAM,EACf,cAAc,EAAE,CAAC,QAAQ,EAAE,yBAAyB,EAAE,YAAY,EAAE,MAAM,KAAK,OAAO,CAAC,CAAC,CAAC,GACxF,OAAO,CAAC,CAAC,CAAC,CAsCZ"}