rightsize 0.2.0 → 0.3.0

package/dist/core/errors.js

@@ -102,21 +102,94 @@ export 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 class CheckpointUnsupportedError extends Error {
     backend;
     constructor(
     /** The active backend's name (e.g. `"microsandbox"`). */
     backend) {
-        super(`checkpoint() is not supported by the '${backend}' backend — checkpoint/restore is implemented via image ` +
-            "commit on the docker backend today; native microVM memory snapshots for microsandbox are on the " +
-            "roadmap. Set RIGHTSIZE_BACKEND=docker to use checkpoint/restore.");
+        super(`checkpoint() is not supported by the '${backend}' backend — checkpointing needs a backend whose ` +
+            "capabilities.checkpoint is true.");
         this.backend = backend;
         this.name = "CheckpointUnsupportedError";
     }
 }
+/**
+ * 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 class CheckpointBackendMismatchError extends Error {
+    createdOnBackend;
+    activeBackend;
+    constructor(
+    /** The backend that created the checkpoint. */
+    createdOnBackend, 
+    /** The backend `start()` actually resolved. */
+    activeBackend) {
+        super(`this checkpoint was created on the '${createdOnBackend}' backend but the active backend is ` +
+            `'${activeBackend}' — set RIGHTSIZE_BACKEND=${createdOnBackend} to restore it there, or create a fresh ` +
+            `checkpoint under the '${activeBackend}' backend instead.`);
+        this.createdOnBackend = createdOnBackend;
+        this.activeBackend = activeBackend;
+        this.name = "CheckpointBackendMismatchError";
+    }
+}
+/**
+ * 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 class ReuseFromCheckpointError extends Error {
+    constructor() {
+        super("withReuse() cannot be combined with fromCheckpoint() — reuse's identity hash does not cover " +
+            "checkpointRef, so an adopted sandbox could never be verified against the checkpoint it was meant to " +
+            "restore. Drop either withReuse() or fromCheckpoint().");
+        this.name = "ReuseFromCheckpointError";
+    }
+}
+/**
+ * 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 class RelativeContainerPathError extends Error {
+    containerPath;
+    constructor(
+    /** The rejected path, exactly as passed in. */
+    containerPath) {
+        super(`containerPath must be an absolute path (got '${containerPath}') — both backends require an absolute guest path.`);
+        this.containerPath = containerPath;
+        this.name = "RelativeContainerPathError";
+    }
+}
+/**
+ * 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 class InvalidCheckpointNameError extends Error {
+    checkpointName;
+    constructor(
+    /** The rejected name, exactly as passed in. */
+    checkpointName) {
+        super(`checkpoint name '${checkpointName}' is invalid — a checkpoint name must match ^[a-z0-9][a-z0-9-]{0,40}$ ` +
+            "(start with a lowercase letter or digit, contain only lowercase letters, digits, and hyphens after " +
+            "that, and be at most 41 characters long).");
+        this.checkpointName = checkpointName;
+        this.name = "InvalidCheckpointNameError";
+    }
+}
 //# sourceMappingURL=errors.js.map

package/dist/core/errors.js.map

@@ -1 +1 @@
-{"version":3,"file":"errors.js","sourceRoot":"","sources":["../../src/core/errors.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,MAAM,OAAO,yBAA0B,SAAQ,KAAK;IAGvC;IAEA;IAEA;IANX;IACE,uDAAuD;IAC9C,OAAe;IACxB,yDAAyD;IAChD,OAAe;IACxB,qFAAqF;IAC5E,MAAe;QAExB,KAAK,CAAC,YAAY,OAAO,8BAA8B,OAAO,YAAY,MAAM,CAAC,CAAC,CAAC,MAAM,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;QANjG,YAAO,GAAP,OAAO,CAAQ;QAEf,YAAO,GAAP,OAAO,CAAQ;QAEf,WAAM,GAAN,MAAM,CAAS;QAGxB,IAAI,CAAC,IAAI,GAAG,2BAA2B,CAAC;IAC1C,CAAC;CACF;AAED;;;;;;GAMG;AACH,MAAM,OAAO,qBAAsB,SAAQ,KAAK;IAInC;IAHX,YACE,OAAe;IACf,4FAA4F;IACnF,KAAe;QAExB,KAAK,CAAC,OAAO,EAAE,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC;QAFnD,UAAK,GAAL,KAAK,CAAU;QAGxB,IAAI,CAAC,IAAI,GAAG,uBAAuB,CAAC;IACtC,CAAC;CACF;AAED,gFAAgF;AAChF,MAAM,OAAO,oBAAqB,SAAQ,KAAK;IAC7C,YAAY,OAAe;QACzB,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,sBAAsB,CAAC;IACrC,CAAC;CACF;AAED,8EAA8E;AAC9E,MAAM,OAAO,YAAa,SAAQ,KAAK;IACrC,YAAY,OAAe;QACzB,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,cAAc,CAAC;IAC7B,CAAC;CACF;AAED,kIAAkI;AAClI,MAAM,OAAO,cAAe,SAAQ,KAAK;IACvC,YAAY,OAAe;QACzB,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,gBAAgB,CAAC;IAC/B,CAAC;CACF;AAED;;;;;;;;;GASG;AACH,MAAM,OAAO,qBAAsB,SAAQ,KAAK;IAC9C;QACE,KAAK,CACH,mGAAmG;YACjG,oGAAoG;YACpG,iDAAiD,CACpD,CAAC;QACF,IAAI,CAAC,IAAI,GAAG,uBAAuB,CAAC;IACtC,CAAC;CACF;AAED;;;;;;GAMG;AACH,MAAM,OAAO,sBAAuB,SAAQ,KAAK;IAGpC;IAFX;IACE,mDAAmD;IAC1C,OAAe;QAExB,KAAK,CACH,2FAA2F,OAAO,KAAK;YACrG,oGAAoG;YACpG,iFAAiF,CACpF,CAAC;QANO,YAAO,GAAP,OAAO,CAAQ;QAOxB,IAAI,CAAC,IAAI,GAAG,wBAAwB,CAAC;IACvC,CAAC;CACF;AAED;;;;;;GAMG;AACH,MAAM,OAAO,0BAA2B,SAAQ,KAAK;IAGxC;IAFX;IACE,yDAAyD;IAChD,OAAe;QAExB,KAAK,CACH,yCAAyC,OAAO,0DAA0D;YACxG,kGAAkG;YAClG,kEAAkE,CACrE,CAAC;QANO,YAAO,GAAP,OAAO,CAAQ;QAOxB,IAAI,CAAC,IAAI,GAAG,4BAA4B,CAAC;IAC3C,CAAC;CACF"}
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../../src/core/errors.ts"],"names":[],"mappings":"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"}

package/dist/core/generic-container.d.ts

@@ -35,25 +35,32 @@ export declare class GenericContainer implements AsyncDisposable, NetworkMember
     private backendOverride;
     private reuseRequested;
     private requireIsolationRequested;
+    private checkpointRef;
+    private checkpointSourceBackend;
     private handle;
     private backend;
     private mappedPorts;
     private running;
+    private installedNetworkLinks;
     /** Builds against `image` (e.g. `"redis:8.6-alpine"`); no I/O happens until `start()`. */
     constructor(image: string);
     /** Convenience: `new GenericContainer(image).start()`. */
     static start(image: string): Promise<GenericContainer>;
     /**
      * Builds a normal, ephemeral `GenericContainer` from a `Checkpoint`
-     * (`checkpoint()`'s return value): image is `cp.imageRef`, and
+     * (`checkpoint()`'s return value): image is `cp.ref`, and
      * env/command/exposed ports/memory limit default to `cp.spec` — chain
      * further builder calls (a different `waitingFor`, `withBackend`, …)
      * before `start()`, the same as any other container. Never carries over
-     * `cp.spec`'s network/aliases/mounts — the committed image already has
-     * the filesystem baked in, and (as with `withReuse()`'s own network
+     * `cp.spec`'s network/aliases/mounts — the captured state already has the
+     * filesystem baked in, and (as with `withReuse()`'s own network
      * restriction) network topology is never part of what a checkpoint
-     * captures. Once started, a restored container is ordinary in every
-     * respect: fresh host ports, normal reaping-ledger tracking, normal stop.
+     * captures. `start()` throws `CheckpointBackendMismatchError` before any
+     * backend call if the active backend isn't the one that created `cp`, and
+     * `ReuseFromCheckpointError` if this container is also marked
+     * `withReuse()` — reuse's identity hash never covers a checkpoint ref.
+     * Once started, a restored container is ordinary in every other respect:
+     * fresh host ports, normal reaping-ledger tracking, normal stop.
      */
     static fromCheckpoint(cp: Checkpoint): GenericContainer;
     /** Sets an environment variable visible to the workload. Last-write-wins if called again with the same key; insertion order is otherwise preserved. */
@@ -222,19 +229,81 @@ export declare class GenericContainer implements AsyncDisposable, NetworkMember
     mappedPort(guestPort: number): number;
     private requireHandle;
     /**
-     * Commits this running container's filesystem to a new image and returns
-     * a `Checkpoint` — a FILESYSTEM capture, not a memory snapshot:
-     * `fromCheckpoint()` boots a fresh container from the committed image
-     * with processes restarting from scratch, not resuming. Requires the
-     * active backend's `capabilities.checkpoint` (docker: `true`, via image
-     * commit; microsandbox: `false`, no upstream microVM snapshot support
-     * yet) — checked BEFORE any backend call, so an unsupported backend never
-     * attempts one. Throws a state error (same shape as `exec`/`logs`) if
-     * this container isn't currently running. Checkpoint images are never
-     * auto-reaped (they're images, not containers) — see the checkpoints
-     * guide for the manual cleanup one-liner.
-     */
-    checkpoint(): Promise<Checkpoint>;
+     * Captures this running container's state and returns a `Checkpoint` — a
+     * FILESYSTEM capture, not a memory snapshot: `fromCheckpoint()` boots a
+     * container from the captured state with processes restarting from
+     * scratch, not resuming. Requires the active backend's
+     * `capabilities.checkpoint` (`true` on both real backends today: docker
+     * via image commit, microsandbox via disk snapshot) — checked BEFORE any
+     * backend call, so an unsupported backend never attempts one. Throws a
+     * state error (same shape as `exec`/`logs`) if this container isn't
+     * currently running.
+     *
+     * Passing `name` makes this checkpoint NAMED and durable: the ref becomes
+     * deterministic (`rz-ckpt-<name>` / `rightsize/checkpoint:<name>` instead
+     * of a random 12-hex suffix), and — only once the backend call below has
+     * actually succeeded — a registry entry is written under
+     * `<cacheDir>/checkpoints/<name>.json` that `Checkpoints.find`/`list`/
+     * `remove` can rediscover later, in this process or a different one. `name`
+     * must match `^[a-z0-9][a-z0-9-]{0,40}$`; an invalid name throws
+     * `InvalidCheckpointNameError` before any backend call. Checkpointing under
+     * a name that already has a registry entry REPLACES it: the ref is the
+     * same deterministic value either way, so this best-effort clears the old
+     * artifact under that ref before creating the new one, then overwrites the
+     * registry entry — the latest checkpoint under a name always wins.
+     * Omitting `name` keeps the original behavior byte-for-byte: a random ref,
+     * no registry entry, ephemeral.
+     *
+     * On a backend whose `capabilities.checkpointRestartsWorkload` is `true`
+     * (microsandbox: the stop/snapshot/reboot cycle boots a fresh microVM),
+     * this re-runs the container's own wait strategy before returning — a bare
+     * return right after the backend call would hand back a false-ready
+     * container. docker's commit-to-image never disturbs the running
+     * container, so no re-wait happens there.
+     *
+     * That same reboot also kills any network links this container had
+     * installed toward already-running siblings (msb emulates them with
+     * exec-tunnels, which the workload restart tears down along with
+     * everything else on the sandbox), so when links were installed in the
+     * first place, this re-runs `installNetworkLinks` with those same links
+     * BEFORE the wait-strategy re-run — the wait must gate a container that is
+     * fully re-linked, not just booted.
+     *
+     * Checkpoints are never auto-reaped (a committed image or a disk snapshot
+     * is not a container) — see the checkpoints guide for the manual cleanup
+     * one-liners and the `Checkpoints.remove` cleanup affordance.
+     */
+    checkpoint(name?: string): Promise<Checkpoint>;
+    /**
+     * Copies a host file or directory into this running container at
+     * `containerPath`, creating the destination's parent directory first
+     * (`exec: mkdir -p <parent>`) — callers never pre-create directories on
+     * either side. `containerPath` must be absolute (both backends' own copy
+     * tools require `NAME:/abs/path`); `hostPath` may be a file or a
+     * directory, `cp -r`-style: copying a directory to an absent destination
+     * produces that destination as a copy of the source's CONTENTS, not the
+     * source nested one level down. Requires a running container — throws the
+     * same state error `exec()`/`logs()` do, before any backend call. Works on
+     * a reuse container too, but the copy mutates shared state that is NOT
+     * part of the reuse identity hash — see the reuse guide's caveat.
+     */
+    copyFileToContainer(hostPath: string, containerPath: string): Promise<void>;
+    /**
+     * Convenience over `copyFileToContainer()`: writes `content` to a private
+     * (mode `0600`) temp file and copies THAT file in, removing the temp file
+     * afterward regardless of outcome. No streaming protocol — content is
+     * always fully materialized on host disk before the copy.
+     */
+    copyContentToContainer(content: string | Uint8Array, containerPath: string): Promise<void>;
+    /**
+     * Copies a file or directory OUT of this running container at
+     * `containerPath` to `hostPath`, creating the destination's host parent
+     * directory first via the standard library — the mirror image of
+     * `copyFileToContainer`'s guest-side `mkdir -p`. `containerPath` must be
+     * absolute; `cp -r`-style destination naming applies here too. Requires a
+     * running container, like `copyFileToContainer`.
+     */
+    copyFileFromContainer(containerPath: string, hostPath: string): Promise<void>;
     /** Runs a one-shot command inside the running container and waits for it to exit. Throws if the container is not running. */
     exec(...cmd: string[]): Promise<ExecResult>;
     /** Fetches the workload's logs so far (a bounded tail), as a single string. Throws if the container is not running. */

package/dist/core/generic-container.d.ts.map

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

package/dist/core/generic-container.js

@@ -1,8 +1,14 @@
 import { randomBytes } from "node:crypto";
+import * as fs from "node:fs/promises";
+import * as os from "node:os";
+import * as path from "node:path";
 import { FreePorts } from "./free-ports.js";
 import { RunId } from "./run-id.js";
 import { Network } from "./network.js";
-import { PortBindConflictError, IsolationRequiredError, CheckpointUnsupportedError } from "./errors.js";
+import { PortBindConflictError, IsolationRequiredError, CheckpointUnsupportedError, CheckpointBackendMismatchError, ReuseFromCheckpointError, RelativeContainerPathError, BackendError, } from "./errors.js";
+import { requireValidCheckpointName } from "./checkpoint/name.js";
+import { checkpointRef } from "./checkpoint/ref.js";
+import { toCheckpointRegistrySpec, writeCheckpointRegistryAtomic } from "./checkpoint/registry.js";
 import { Wait } from "./wait.js";
 import { registerSyncCleanup, unregisterSyncCleanup } from "./cleanup.js";
 import { Backends } from "./backends.js";
@@ -12,6 +18,12 @@ import { ReuseWithNetworkError } from "./errors.js";
 import { reuseEnabled } from "./reuse/env.js";
 import { reuseHash, reuseName } from "./reuse/hash.js";
 import { readRegistry, writeRegistryAtomic, removeRegistry } from "./reuse/registry.js";
+/** Fails fast — before any backend call — on a relative `containerPath`: both backends require an absolute `NAME:/path` shape. */
+function requireAbsoluteContainerPath(containerPath) {
+    if (!path.posix.isAbsolute(containerPath)) {
+        throw new RelativeContainerPathError(containerPath);
+    }
+}
 const MAX_START_ATTEMPTS = 5;
 let sequence = 0;
 function nextSequence() {
@@ -94,10 +106,13 @@ export class GenericContainer {
     backendOverride;
     reuseRequested = false;
     requireIsolationRequested = false;
+    checkpointRef;
+    checkpointSourceBackend;
     handle;
     backend;
     mappedPorts = new Map();
     running = false;
+    installedNetworkLinks = [];
     /** Builds against `image` (e.g. `"redis:8.6-alpine"`); no I/O happens until `start()`. */
     constructor(image) {
         this.image = image;
@@ -108,18 +123,24 @@ export class GenericContainer {
     }
     /**
      * Builds a normal, ephemeral `GenericContainer` from a `Checkpoint`
-     * (`checkpoint()`'s return value): image is `cp.imageRef`, and
+     * (`checkpoint()`'s return value): image is `cp.ref`, and
      * env/command/exposed ports/memory limit default to `cp.spec` — chain
      * further builder calls (a different `waitingFor`, `withBackend`, …)
      * before `start()`, the same as any other container. Never carries over
-     * `cp.spec`'s network/aliases/mounts — the committed image already has
-     * the filesystem baked in, and (as with `withReuse()`'s own network
+     * `cp.spec`'s network/aliases/mounts — the captured state already has the
+     * filesystem baked in, and (as with `withReuse()`'s own network
      * restriction) network topology is never part of what a checkpoint
-     * captures. Once started, a restored container is ordinary in every
-     * respect: fresh host ports, normal reaping-ledger tracking, normal stop.
+     * captures. `start()` throws `CheckpointBackendMismatchError` before any
+     * backend call if the active backend isn't the one that created `cp`, and
+     * `ReuseFromCheckpointError` if this container is also marked
+     * `withReuse()` — reuse's identity hash never covers a checkpoint ref.
+     * Once started, a restored container is ordinary in every other respect:
+     * fresh host ports, normal reaping-ledger tracking, normal stop.
      */
     static fromCheckpoint(cp) {
-        const container = new GenericContainer(cp.imageRef);
+        const container = new GenericContainer(cp.ref);
+        container.checkpointRef = cp.ref;
+        container.checkpointSourceBackend = cp.backend;
         for (const [key, value] of cp.spec.env) {
             container.withEnv(key, value);
         }
@@ -265,6 +286,7 @@ export class GenericContainer {
             // requested-but-env-disabled reuse container falls through to here
             // deliberately (Testcontainers semantics), so it must stay false.
             keepAlive: false,
+            checkpointRef: this.checkpointRef,
         };
         return this.customizeSpec(spec, (guest) => {
             const p = ports.get(guest);
@@ -293,6 +315,10 @@ export class GenericContainer {
             runId: RunId.value,
             memoryLimitMb: this.memoryLimitMb,
             keepAlive: true,
+            // Reuse + fromCheckpoint is rejected in start() before this is ever
+            // built (see ReuseFromCheckpointError) — always undefined in
+            // practice, present only to satisfy ContainerSpec's shape.
+            checkpointRef: this.checkpointRef,
         };
         return this.customizeSpec(spec, (guest) => {
             const p = ports.get(guest);
@@ -341,6 +367,12 @@ export class GenericContainer {
      */
     async start() {
         const backend = this.resolveBackend();
+        // Before any backend work at all: a checkpoint ref is only meaningful
+        // to the backend that minted it (a docker image tag means nothing to
+        // msb, a msb snapshot name means nothing to docker).
+        if (this.checkpointSourceBackend !== undefined && this.checkpointSourceBackend !== backend.name) {
+            throw new CheckpointBackendMismatchError(this.checkpointSourceBackend, backend.name);
+        }
         // Only the env-resolved path (never an explicit withBackend() override)
         // drives the reaper: writes this process's run record, sweeps dead runs
         // on first use, and spawns the watchdog. Skipping it for overrides is
@@ -367,6 +399,9 @@ export class GenericContainer {
                 if (this.network !== undefined) {
                     throw new ReuseWithNetworkError();
                 }
+                if (this.checkpointRef !== undefined) {
+                    throw new ReuseFromCheckpointError();
+                }
                 return this.startReuse(backend);
             }
             process.stderr.write(`[rightsize] reuse was requested via withReuse() for '${this.image}' but RIGHTSIZE_REUSE is not ` +
@@ -441,6 +476,7 @@ export class GenericContainer {
         try {
             const links = this.network?.linksForNewMember() ?? [];
             await backend.installNetworkLinks(handle, links);
+            this.installedNetworkLinks = links;
             // Register AFTER links are computed/installed — a container must
             // never see itself in its own linksForNewMember() call.
             if (this.network !== undefined) {
@@ -745,26 +781,139 @@ export class GenericContainer {
         return { handle: this.handle, backend: this.backend };
     }
     /**
-     * Commits this running container's filesystem to a new image and returns
-     * a `Checkpoint` — a FILESYSTEM capture, not a memory snapshot:
-     * `fromCheckpoint()` boots a fresh container from the committed image
-     * with processes restarting from scratch, not resuming. Requires the
-     * active backend's `capabilities.checkpoint` (docker: `true`, via image
-     * commit; microsandbox: `false`, no upstream microVM snapshot support
-     * yet) — checked BEFORE any backend call, so an unsupported backend never
-     * attempts one. Throws a state error (same shape as `exec`/`logs`) if
-     * this container isn't currently running. Checkpoint images are never
-     * auto-reaped (they're images, not containers) — see the checkpoints
-     * guide for the manual cleanup one-liner.
+     * Captures this running container's state and returns a `Checkpoint` — a
+     * FILESYSTEM capture, not a memory snapshot: `fromCheckpoint()` boots a
+     * container from the captured state with processes restarting from
+     * scratch, not resuming. Requires the active backend's
+     * `capabilities.checkpoint` (`true` on both real backends today: docker
+     * via image commit, microsandbox via disk snapshot) — checked BEFORE any
+     * backend call, so an unsupported backend never attempts one. Throws a
+     * state error (same shape as `exec`/`logs`) if this container isn't
+     * currently running.
+     *
+     * Passing `name` makes this checkpoint NAMED and durable: the ref becomes
+     * deterministic (`rz-ckpt-<name>` / `rightsize/checkpoint:<name>` instead
+     * of a random 12-hex suffix), and — only once the backend call below has
+     * actually succeeded — a registry entry is written under
+     * `<cacheDir>/checkpoints/<name>.json` that `Checkpoints.find`/`list`/
+     * `remove` can rediscover later, in this process or a different one. `name`
+     * must match `^[a-z0-9][a-z0-9-]{0,40}$`; an invalid name throws
+     * `InvalidCheckpointNameError` before any backend call. Checkpointing under
+     * a name that already has a registry entry REPLACES it: the ref is the
+     * same deterministic value either way, so this best-effort clears the old
+     * artifact under that ref before creating the new one, then overwrites the
+     * registry entry — the latest checkpoint under a name always wins.
+     * Omitting `name` keeps the original behavior byte-for-byte: a random ref,
+     * no registry entry, ephemeral.
+     *
+     * On a backend whose `capabilities.checkpointRestartsWorkload` is `true`
+     * (microsandbox: the stop/snapshot/reboot cycle boots a fresh microVM),
+     * this re-runs the container's own wait strategy before returning — a bare
+     * return right after the backend call would hand back a false-ready
+     * container. docker's commit-to-image never disturbs the running
+     * container, so no re-wait happens there.
+     *
+     * That same reboot also kills any network links this container had
+     * installed toward already-running siblings (msb emulates them with
+     * exec-tunnels, which the workload restart tears down along with
+     * everything else on the sandbox), so when links were installed in the
+     * first place, this re-runs `installNetworkLinks` with those same links
+     * BEFORE the wait-strategy re-run — the wait must gate a container that is
+     * fully re-linked, not just booted.
+     *
+     * Checkpoints are never auto-reaped (a committed image or a disk snapshot
+     * is not a container) — see the checkpoints guide for the manual cleanup
+     * one-liners and the `Checkpoints.remove` cleanup affordance.
      */
-    async checkpoint() {
+    async checkpoint(name) {
+        if (name !== undefined) {
+            requireValidCheckpointName(name);
+        }
         const { handle, backend } = this.requireHandle();
         if (!backend.capabilities.checkpoint) {
             throw new CheckpointUnsupportedError(backend.name);
         }
-        const imageRef = `rightsize/checkpoint:${randomBytes(6).toString("hex")}`;
-        await backend.commitToImage(handle, imageRef);
-        return { imageRef, spec: handle.spec };
+        const ref = checkpointRef(backend.name, name);
+        if (name !== undefined) {
+            // Replace semantics: the ref is deterministic from `name`, so a prior
+            // checkpoint under this same name — if any — sits under this exact
+            // ref. Best-effort clear it before creating the new one.
+            await swallow(() => backend.removeCheckpoint(ref));
+        }
+        await backend.createCheckpoint(handle, ref);
+        if (backend.capabilities.checkpointRestartsWorkload) {
+            if (this.installedNetworkLinks.length > 0) {
+                await backend.installNetworkLinks(handle, this.installedNetworkLinks);
+            }
+            await this.waitStrategy.waitUntilReady(this.asWaitTarget());
+        }
+        if (name !== undefined) {
+            // Only after the backend checkpoint above has actually succeeded — a
+            // failed createCheckpoint() already threw, so a registry entry is
+            // never written for a checkpoint that doesn't exist.
+            const entry = {
+                name,
+                ref,
+                backend: backend.name,
+                createdIso: new Date().toISOString(),
+                spec: toCheckpointRegistrySpec(handle.spec),
+            };
+            await writeCheckpointRegistryAtomic(cacheDir(), name, entry);
+        }
+        return { ref, backend: backend.name, spec: handle.spec };
+    }
+    /**
+     * Copies a host file or directory into this running container at
+     * `containerPath`, creating the destination's parent directory first
+     * (`exec: mkdir -p <parent>`) — callers never pre-create directories on
+     * either side. `containerPath` must be absolute (both backends' own copy
+     * tools require `NAME:/abs/path`); `hostPath` may be a file or a
+     * directory, `cp -r`-style: copying a directory to an absent destination
+     * produces that destination as a copy of the source's CONTENTS, not the
+     * source nested one level down. Requires a running container — throws the
+     * same state error `exec()`/`logs()` do, before any backend call. Works on
+     * a reuse container too, but the copy mutates shared state that is NOT
+     * part of the reuse identity hash — see the reuse guide's caveat.
+     */
+    async copyFileToContainer(hostPath, containerPath) {
+        const { handle, backend } = this.requireHandle();
+        requireAbsoluteContainerPath(containerPath);
+        const parent = path.posix.dirname(containerPath);
+        const mkdir = await backend.exec(handle, ["mkdir", "-p", parent]);
+        if (mkdir.exitCode !== 0) {
+            throw new BackendError(`could not create parent directory '${parent}' in '${handle.spec.name}' before copying in: ${mkdir.stderr.trim()}`);
+        }
+        await backend.copyToContainer(handle, hostPath, containerPath);
+    }
+    /**
+     * Convenience over `copyFileToContainer()`: writes `content` to a private
+     * (mode `0600`) temp file and copies THAT file in, removing the temp file
+     * afterward regardless of outcome. No streaming protocol — content is
+     * always fully materialized on host disk before the copy.
+     */
+    async copyContentToContainer(content, containerPath) {
+        const tempPath = path.join(os.tmpdir(), `rightsize-copy-content-${randomBytes(6).toString("hex")}`);
+        await fs.writeFile(tempPath, content, { mode: 0o600 });
+        try {
+            await this.copyFileToContainer(tempPath, containerPath);
+        }
+        finally {
+            await fs.rm(tempPath, { force: true });
+        }
+    }
+    /**
+     * Copies a file or directory OUT of this running container at
+     * `containerPath` to `hostPath`, creating the destination's host parent
+     * directory first via the standard library — the mirror image of
+     * `copyFileToContainer`'s guest-side `mkdir -p`. `containerPath` must be
+     * absolute; `cp -r`-style destination naming applies here too. Requires a
+     * running container, like `copyFileToContainer`.
+     */
+    async copyFileFromContainer(containerPath, hostPath) {
+        const { handle, backend } = this.requireHandle();
+        requireAbsoluteContainerPath(containerPath);
+        await fs.mkdir(path.dirname(hostPath), { recursive: true });
+        await backend.copyFromContainer(handle, containerPath, hostPath);
     }
     /** Runs a one-shot command inside the running container and waits for it to exit. Throws if the container is not running. */
     async exec(...cmd) {