rightsize 0.7.9 → 0.7.12

package/dist/core/generic-container.js

@@ -4,11 +4,12 @@ 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 { nextSandboxName } from "./sandbox-name.js";
 import { Network } from "./network.js";
-import { PortBindConflictError, IsolationRequiredError, CheckpointUnsupportedError, CheckpointBackendMismatchError, ReuseFromCheckpointError, RelativeContainerPathError, BackendError, RootDiskConflictError, TmpfsRootExceedsMemoryError, NetworkDisabledConflictError, TmpfsRootCheckpointError, } from "./errors.js";
+import { PortBindConflictError, IsolationRequiredError, CheckpointUnsupportedError, CheckpointBackendMismatchError, ReuseFromCheckpointError, CheckpointRestoreEnvOverrideError, RelativeContainerPathError, BackendError, RootDiskConflictError, TmpfsRootExceedsMemoryError, NetworkDisabledConflictError, TmpfsRootCheckpointError, } from "./errors.js";
 import { requireValidCheckpointName } from "./checkpoint/name.js";
 import { checkpointRef } from "./checkpoint/ref.js";
-import { toCheckpointRegistrySpec, writeCheckpointRegistryAtomic } from "./checkpoint/registry.js";
+import { toCheckpointRegistrySpec, writeCheckpointRegistryAtomic, readCheckpointRegistry } from "./checkpoint/registry.js";
 import { Wait } from "./wait.js";
 import { registerSyncCleanup, unregisterSyncCleanup } from "./cleanup.js";
 import { Backends } from "./backends.js";
@@ -24,12 +25,29 @@ function requireAbsoluteContainerPath(containerPath) {
         throw new RelativeContainerPathError(containerPath);
     }
 }
-const MAX_START_ATTEMPTS = 5;
-let sequence = 0;
-function nextSequence() {
-    sequence += 1;
-    return sequence;
+/**
+ * Order-insensitive equality for env pairs — `start()`'s only use is telling
+ * "the checkpoint's own captured env, re-applied unchanged" from "the caller
+ * actually changed it" (see `CheckpointRestoreEnvOverrideError`). Compared as
+ * key/value sets rather than positionally: `withEnv()` re-setting an
+ * existing key moves it to the end of `envPairs` (last-write-wins,
+ * insertion-ordered — see `withEnv()`'s own doc), which must not by itself
+ * read as a change.
+ */
+function envPairsEqual(a, b) {
+    const aMap = new Map(a);
+    const bMap = new Map(b);
+    if (aMap.size !== bMap.size) {
+        return false;
+    }
+    for (const [key, value] of aMap) {
+        if (bMap.get(key) !== value) {
+            return false;
+        }
+    }
+    return true;
 }
+const MAX_START_ATTEMPTS = 5;
 /** Typed-first, string-fallback classification: walk the cause chain for a typed conflict, else match the daemon's own wording. */
 function isPortBindConflict(err) {
     let current = err;
@@ -75,6 +93,10 @@ function registryRecordToPorts(record) {
     }
     return ports;
 }
+/** `ContainerSpec.hostUdpEgressPorts`'s own computation: the distinct, ascending-sorted target host ports of `links`' UDP-protocol entries — shared by every spec-construction site a networked boot can reach. */
+function hostUdpEgressPortsFor(links) {
+    return [...new Set(links.filter((link) => link.protocol === "udp").map((link) => link.targetHostPort))].sort((a, b) => a - b);
+}
 /**
  * The builder, launcher, and lifecycle guard for a single container — the
  * one class every module (`RedisContainer`, `PostgresContainer`, …)
@@ -97,6 +119,8 @@ export class GenericContainer {
     image;
     envPairs = [];
     exposedPorts = [];
+    /** UDP counterpart of `exposedPorts` (`withExposedUdpPorts`) — a separate field, never merged with the TCP list; see `PortBinding`'s own doc on why the same guest port can appear in both. */
+    exposedUdpPorts = [];
     command;
     network;
     aliasNames = [];
@@ -111,9 +135,20 @@ export class GenericContainer {
     requireIsolationRequested = false;
     checkpointRef;
     checkpointSourceBackend;
+    /**
+     * `cp.spec.env` exactly as captured, set once by `fromCheckpoint()` and
+     * never touched again — kept separate from the mutable `envPairs` so
+     * `start()` can tell "the caller re-applied the checkpoint's own env
+     * unchanged" from "the caller actually overrode or extended it" (see
+     * `CheckpointRestoreEnvOverrideError`). `undefined` for every container
+     * not built via `fromCheckpoint()`.
+     */
+    checkpointCapturedEnv;
     handle;
     backend;
     mappedPorts = new Map();
+    /** UDP counterpart of `mappedPorts` — a SEPARATE per-protocol store, never a shared bare-int-keyed map (see `getMappedUdpPort`). */
+    mappedUdpPorts = new Map();
     running = false;
     installedNetworkLinks = [];
     /** Builds against `image` (e.g. `"redis:8.6-alpine"`); no I/O happens until `start()`. */
@@ -136,7 +171,14 @@ export class GenericContainer {
      * 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.
+     * `withReuse()` — reuse's identity hash never covers a checkpoint ref. On
+     * msb specifically, `start()` also throws `CheckpointRestoreEnvOverrideError`
+     * before any backend call if a further `withEnv()` call actually changes
+     * the env beyond what `cp.spec.env` captured — msb's restore command has
+     * no way to inject env at boot time (see that error's own doc); re-calling
+     * `withEnv()` with the checkpoint's own captured values, unchanged, never
+     * throws. docker is unaffected — an overridden/extended env reaches a
+     * docker restore normally.
      * Once started, a restored container is ordinary in every other respect:
      * fresh host ports, normal reaping-ledger tracking, normal stop.
      */
@@ -144,14 +186,26 @@ export class GenericContainer {
         const container = new GenericContainer(cp.ref);
         container.checkpointRef = cp.ref;
         container.checkpointSourceBackend = cp.backend;
+        container.checkpointCapturedEnv = cp.spec.env;
         for (const [key, value] of cp.spec.env) {
             container.withEnv(key, value);
         }
         if (cp.spec.command !== undefined) {
             container.withCommand(...cp.spec.command);
         }
-        if (cp.spec.ports.length > 0) {
-            container.withExposedPorts(...cp.spec.ports.map((p) => p.guestPort));
+        // Split by protocol into the right builder field — cp.spec.ports mixes
+        // both transports (see PortBinding's own doc on why they're tagged
+        // rather than kept in separate lists at the ContainerSpec level), but
+        // the builder itself keeps two independent fields, exactly the way a
+        // fresh (non-restored) container's own withExposedPorts()/
+        // withExposedUdpPorts() calls would populate them.
+        const tcpGuestPorts = cp.spec.ports.filter((p) => p.protocol === "tcp").map((p) => p.guestPort);
+        const udpGuestPorts = cp.spec.ports.filter((p) => p.protocol === "udp").map((p) => p.guestPort);
+        if (tcpGuestPorts.length > 0) {
+            container.withExposedPorts(...tcpGuestPorts);
+        }
+        if (udpGuestPorts.length > 0) {
+            container.withExposedUdpPorts(...udpGuestPorts);
         }
         if (cp.spec.memoryLimitMb !== undefined) {
             container.withMemoryLimit(cp.spec.memoryLimitMb);
@@ -167,11 +221,34 @@ export class GenericContainer {
         this.envPairs.push([key, value]);
         return this;
     }
-    /** Publishes these guest ports to pre-allocated host ports (see `FreePorts`); read back with `getMappedPort`. */
+    /** Publishes these guest ports to pre-allocated host ports (see `FreePorts`); read back with `getMappedPort`. TCP only — see `withExposedUdpPorts` for UDP. */
     withExposedPorts(...ports) {
         this.exposedPorts.push(...ports);
         return this;
     }
+    /**
+     * Publishes these guest ports over UDP to pre-allocated host ports (see
+     * `FreePorts.allocateUdp`); read back with `getMappedUdpPort`. A separate
+     * list from `withExposedPorts` — the same numeric guest port may be
+     * exposed on both protocols (DNS's 53, say), and each gets its own
+     * independent host-port mapping.
+     *
+     * UDP exposure is deliberately invisible to the default wait strategies:
+     * `Wait.forListeningPort()`/`Wait.forHttp()` only ever probe
+     * `withExposedPorts`' TCP guest ports, so a container exposing ONLY UDP
+     * ports is vacuously ready under the default wait — prefer
+     * `Wait.forLogMessage(...)` for a UDP-only service.
+     *
+     * A UDP-exposed container can be a link target on a `Network` on both
+     * backends. On microsandbox the consumer gets an in-guest forwarder per UDP
+     * link, which needs a busybox-style `nc` (with `-u`/`-e`) and `timeout` in
+     * the consumer image; a datagram over 1472 bytes of payload breaks the
+     * receiving sandbox's inbound networking there (see the networking guide).
+     */
+    withExposedUdpPorts(...ports) {
+        this.exposedUdpPorts.push(...ports);
+        return this;
+    }
     /** Overrides the image's default ENTRYPOINT/CMD. Omit this call entirely to run the image unmodified. */
     withCommand(...cmd) {
         this.command = cmd;
@@ -310,18 +387,14 @@ export class GenericContainer {
     resolveBackend() {
         return this.backendOverride ?? Backends.active();
     }
-    buildSpec(name, ports) {
+    /** `hostUdpEgressPorts` is precomputed by `start()` from the SAME `linksForNewMember()` call `installNetworkLinks` is later given — never recomputed here, so the argv a networked boot builds from and the links actually installed after it always agree. */
+    buildSpec(name, ports, hostUdpEgressPorts) {
         const spec = {
             name,
             image: this.image,
             env: this.envPairs.map(([k, v]) => [k, v]),
             command: this.command,
-            ports: this.exposedPorts.map((guestPort) => ({
-                hostPort: ports.get(guestPort) ?? (() => {
-                    throw new Error(`no allocated host port for guest port ${guestPort}`);
-                })(),
-                guestPort,
-            })),
+            ports: this.buildPortBindings(ports),
             mounts: this.mounts,
             networkId: this.network?.id,
             aliases: this.aliasNames,
@@ -336,9 +409,10 @@ export class GenericContainer {
             diskLimitMb: this.diskLimitMb,
             tmpfsRootMb: this.tmpfsRootMb,
             networkDisabled: this.networkDisabled,
+            hostUdpEgressPorts,
         };
         return GenericContainer.validateSpecConflicts(this.customizeSpec(spec, (guest) => {
-            const p = ports.get(guest);
+            const p = ports.tcp.get(guest);
             if (p === undefined) {
                 throw new Error(`no allocated host port for guest port ${guest}`);
             }
@@ -352,12 +426,7 @@ export class GenericContainer {
             image: this.image,
             env: this.envPairs.map(([k, v]) => [k, v]),
             command: this.command,
-            ports: this.exposedPorts.map((guestPort) => ({
-                hostPort: ports.get(guestPort) ?? (() => {
-                    throw new Error(`no allocated host port for guest port ${guestPort}`);
-                })(),
-                guestPort,
-            })),
+            ports: this.buildPortBindings(ports),
             mounts: this.mounts,
             networkId: undefined,
             aliases: this.aliasNames,
@@ -371,9 +440,13 @@ export class GenericContainer {
             diskLimitMb: this.diskLimitMb,
             tmpfsRootMb: this.tmpfsRootMb,
             networkDisabled: this.networkDisabled,
+            // A reuse container never joins a Network (ReuseWithNetworkError,
+            // checked before this is ever reached) — no links, ever, to derive a
+            // host-UDP-egress list from.
+            hostUdpEgressPorts: [],
         };
         return GenericContainer.validateSpecConflicts(this.customizeSpec(spec, (guest) => {
-            const p = ports.get(guest);
+            const p = ports.tcp.get(guest);
             if (p === undefined) {
                 throw new Error(`no allocated host port for guest port ${guest}`);
             }
@@ -406,6 +479,7 @@ export class GenericContainer {
             env: this.envPairs.map(([k, v]) => [k, v]),
             command: this.command,
             exposedPorts: this.exposedPorts,
+            exposedUdpPorts: this.exposedUdpPorts,
             memoryLimitMb: this.memoryLimitMb,
             copies: this.mounts.map((m) => ({ guestPath: m.guestPath, hostPath: m.hostPath })),
             diskLimitMb: this.diskLimitMb,
@@ -414,16 +488,44 @@ export class GenericContainer {
         });
     }
     async allocatePorts() {
-        const ports = new Map();
+        const tcp = new Map();
         for (const guestPort of this.exposedPorts) {
-            ports.set(guestPort, await FreePorts.allocate());
+            tcp.set(guestPort, await FreePorts.allocate());
         }
-        return ports;
+        const udp = new Map();
+        for (const guestPort of this.exposedUdpPorts) {
+            udp.set(guestPort, await FreePorts.allocateUdp());
+        }
+        return { tcp, udp };
     }
     releasePorts(ports) {
-        for (const hostPort of ports.values()) {
+        for (const hostPort of ports.tcp.values()) {
             FreePorts.release(hostPort);
         }
+        for (const hostPort of ports.udp.values()) {
+            FreePorts.releaseUdp(hostPort);
+        }
+    }
+    /** Builds the `ContainerSpec.ports` array from this builder's TCP and UDP exposed-port lists plus their allocated host ports — shared by `buildSpec` and `buildReuseSpec`. */
+    buildPortBindings(ports) {
+        return [
+            ...this.exposedPorts.map((guestPort) => ({
+                hostPort: ports.tcp.get(guestPort) ??
+                    (() => {
+                        throw new Error(`no allocated host port for guest port ${guestPort}`);
+                    })(),
+                guestPort,
+                protocol: "tcp",
+            })),
+            ...this.exposedUdpPorts.map((guestPort) => ({
+                hostPort: ports.udp.get(guestPort) ??
+                    (() => {
+                        throw new Error(`no allocated host port for guest port ${guestPort}/udp`);
+                    })(),
+                guestPort,
+                protocol: "udp",
+            })),
+        ];
     }
     /**
      * Fails fast — before any backend call — on the combinations
@@ -466,6 +568,20 @@ export class GenericContainer {
         if (this.checkpointSourceBackend !== undefined && this.checkpointSourceBackend !== backend.name) {
             throw new CheckpointBackendMismatchError(this.checkpointSourceBackend, backend.name);
         }
+        // Also before any backend work: msb's restore command has no -e/--env
+        // flag at all (see CheckpointRestoreEnvOverrideError's own doc) — an env
+        // the caller has genuinely changed beyond the checkpoint's own captured
+        // values can never reach a restored msb sandbox, so this refuses rather
+        // than silently booting it without the env the caller asked for. Only
+        // msb is checked: docker's restore is an ordinary create/run against the
+        // committed image, so an overridden env reaches it normally. Re-applying
+        // the checkpoint's own captured env unchanged never throws — only a call
+        // that actually changes what would be sent does.
+        if (this.checkpointRef !== undefined &&
+            backend.name === "microsandbox" &&
+            !envPairsEqual(this.checkpointCapturedEnv ?? [], this.envPairs)) {
+            throw new CheckpointRestoreEnvOverrideError(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
@@ -504,6 +620,15 @@ export class GenericContainer {
             await backend.ensureNetwork(this.network.id);
             await trackNetwork(this.network.id);
         }
+        // Computed once, before create() — never recomputed inside the retry
+        // loop below or ahead of the installNetworkLinks call after it: a
+        // backend that routes links through the host (msb) needs this
+        // container's own UDP-egress policy baked into the SAME argv that boots
+        // it, and the links actually installed once it's up must be the exact
+        // list that policy was built from, not a freshly recomputed one that
+        // could in principle disagree with it.
+        const links = this.network?.linksForNewMember() ?? [];
+        const hostUdpEgressPorts = hostUdpEgressPortsFor(links);
         let handle;
         let allocatedPorts;
         let lastConflict;
@@ -511,13 +636,16 @@ export class GenericContainer {
         // set) until the retry loop exits: releasing them immediately would let the
         // next attempt legally re-pick the very port that just conflicted — the OS
         // frequently reissues a just-freed ephemeral port — wasting an attempt on a
-        // proven-contended port.
-        const conflictedPorts = [];
+        // proven-contended port. Tracked per protocol so the finally block below
+        // releases each back into the RIGHT pool (TCP vs UDP have independent OS
+        // port tables — see FreePorts.allocateUdp's own doc).
+        const conflictedTcpPorts = [];
+        const conflictedUdpPorts = [];
         try {
             for (let attempt = 0; attempt < MAX_START_ATTEMPTS; attempt++) {
                 const ports = await this.allocatePorts();
-                const name = `rz-${RunId.value}-${nextSequence()}`;
-                const spec = this.buildSpec(name, ports);
+                const name = nextSandboxName();
+                const spec = this.buildSpec(name, ports, hostUdpEgressPorts);
                 // Appended BEFORE create() — the ledger's `.sandboxes` file is always
                 // a superset of this run's live sandboxes, never a subset. `keepAlive`
                 // containers are never listed at all, so a sweep can never reach one
@@ -544,8 +672,9 @@ export class GenericContainer {
                         await untrackSandbox(name);
                     }
                     if (isPortBindConflict(err)) {
-                        // Quarantined, not released: see conflictedPorts above.
-                        conflictedPorts.push(...ports.values());
+                        // Quarantined, not released: see conflictedTcpPorts/conflictedUdpPorts above.
+                        conflictedTcpPorts.push(...ports.tcp.values());
+                        conflictedUdpPorts.push(...ports.udp.values());
                         lastConflict = err;
                         continue;
                     }
@@ -555,9 +684,12 @@ export class GenericContainer {
             }
         }
         finally {
-            for (const hostPort of conflictedPorts) {
+            for (const hostPort of conflictedTcpPorts) {
                 FreePorts.release(hostPort);
             }
+            for (const hostPort of conflictedUdpPorts) {
+                FreePorts.releaseUdp(hostPort);
+            }
         }
         if (handle === undefined || allocatedPorts === undefined) {
             throw new Error(`Failed to start '${this.image}' after ${MAX_START_ATTEMPTS} attempts: every attempt hit a host port already in use by another process.`, { cause: lastConflict });
@@ -566,7 +698,8 @@ export class GenericContainer {
         // even though readiness (below) hasn't been confirmed yet.
         this.handle = handle;
         this.backend = backend;
-        this.mappedPorts = allocatedPorts;
+        this.mappedPorts = allocatedPorts.tcp;
+        this.mappedUdpPorts = allocatedPorts.udp;
         this.running = true;
         // Real synchronous teardown, not a placeholder: if this process dies
         // before stop() ever runs (process.exit / SIGINT / SIGTERM), the exit
@@ -582,7 +715,10 @@ export class GenericContainer {
             registerSyncCleanup(handle, backend, () => backend.cleanupSync(handle.id));
         }
         try {
-            const links = this.network?.linksForNewMember() ?? [];
+            // The SAME links computed above, before create() — never recomputed
+            // here (see the comment where they were computed): the policy already
+            // baked into this container's own argv must be exactly what gets
+            // installed, not a freshly recomputed list.
             await backend.installNetworkLinks(handle, links);
             this.installedNetworkLinks = links;
             // Register AFTER links are computed/installed — a container must
@@ -614,10 +750,11 @@ export class GenericContainer {
         const dir = cacheDir();
         const hash = await this.computeReuseHash();
         const name = reuseName(hash);
-        const { handle, mappedPorts } = await this.adoptOrCreate(backend, dir, hash, name, false);
+        const { handle, mappedPorts, mappedUdpPorts } = await this.adoptOrCreate(backend, dir, hash, name, false);
         this.handle = handle;
         this.backend = backend;
         this.mappedPorts = mappedPorts;
+        this.mappedUdpPorts = mappedUdpPorts;
         this.running = true;
         // Deliberately no registerSyncCleanup and no ledger trackSandbox call —
         // a keepAlive sandbox must outlive this process, which is exactly what
@@ -676,8 +813,10 @@ export class GenericContainer {
         let lastConflict;
         // Same conflicted-port quarantine as the ordinary start path: a port that
         // just failed to bind stays out of the allocator until this retry loop
-        // exits, so no later attempt can re-pick it.
-        const conflictedPorts = [];
+        // exits, so no later attempt can re-pick it. Split by protocol for the
+        // same reason start()'s own loop is — see its comment.
+        const conflictedTcpPorts = [];
+        const conflictedUdpPorts = [];
         try {
             for (let attempt = 0; attempt < MAX_START_ATTEMPTS; attempt++) {
                 const ports = await this.allocatePorts();
@@ -696,8 +835,9 @@ export class GenericContainer {
                         await swallow(() => backend.remove(createdHandle));
                     }
                     if (isPortBindConflict(err)) {
-                        // Quarantined, not released: see conflictedPorts above.
-                        conflictedPorts.push(...ports.values());
+                        // Quarantined, not released: see conflictedTcpPorts/conflictedUdpPorts above.
+                        conflictedTcpPorts.push(...ports.tcp.values());
+                        conflictedUdpPorts.push(...ports.udp.values());
                         lastConflict = err;
                         continue;
                     }
@@ -719,16 +859,19 @@ export class GenericContainer {
             }
         }
         finally {
-            for (const hostPort of conflictedPorts) {
+            for (const hostPort of conflictedTcpPorts) {
                 FreePorts.release(hostPort);
             }
+            for (const hostPort of conflictedUdpPorts) {
+                FreePorts.releaseUdp(hostPort);
+            }
         }
         if (handle === undefined || allocatedPorts === undefined) {
             throw new Error(`Failed to start reuse container '${this.image}' after ${MAX_START_ATTEMPTS} attempts: every attempt hit a host port already in use by another process.`, { cause: lastConflict });
         }
         const ports = allocatedPorts;
         try {
-            await this.waitStrategy.waitUntilReady(this.waitTargetFor(backend, handle, ports));
+            await this.waitStrategy.waitUntilReady(this.waitTargetFor(backend, handle, ports.tcp));
         }
         catch (err) {
             await swallow(() => backend.stop(handle));
@@ -736,15 +879,19 @@ export class GenericContainer {
             this.releasePorts(ports);
             throw err;
         }
+        const udpPortsRecord = portsToRegistryRecord(ports.udp);
         const entry = {
             name,
             image: this.image,
-            ports: portsToRegistryRecord(ports),
+            ports: portsToRegistryRecord(ports.tcp),
             createdIso: new Date().toISOString(),
             backend: backend.name,
+            // Omitted when there are none, mirroring every other additive-optional
+            // field on this registry's sibling shapes.
+            ...(Object.keys(udpPortsRecord).length > 0 ? { udpPorts: udpPortsRecord } : {}),
         };
         await writeRegistryAtomic(dir, hash, entry);
-        return { handle, mappedPorts: ports };
+        return { handle, mappedPorts: ports.tcp, mappedUdpPorts: ports.udp };
     }
     /**
      * Registry hit → verify: confirm the name is actually running (backend
@@ -757,7 +904,10 @@ export class GenericContainer {
      */
     async tryAdopt(backend, dir, hash, name, entry) {
         const mappedPorts = registryRecordToPorts(entry.ports);
-        const spec = this.buildReuseSpec(name, mappedPorts);
+        // Absent on an entry written before UDP exposure existed — normalizes to
+        // no UDP ports, never a corrupt read (see isRegistryEntry in reuse/registry.ts).
+        const mappedUdpPorts = registryRecordToPorts(entry.udpPorts ?? {});
+        const spec = this.buildReuseSpec(name, { tcp: mappedPorts, udp: mappedUdpPorts });
         const handle = await backend.findRunning(spec).catch(() => undefined);
         if (handle === undefined) {
             await this.cleanupStaleReuse(backend, dir, hash, name);
@@ -770,7 +920,7 @@ export class GenericContainer {
             await this.cleanupStaleReuse(backend, dir, hash, name);
             return undefined;
         }
-        return { handle, mappedPorts };
+        return { handle, mappedPorts, mappedUdpPorts };
     }
     /** Best-effort: remove whatever's running under `name` (by name — this call never held a handle for it) and delete the registry file. Never throws. */
     async cleanupStaleReuse(backend, dir, hash, name) {
@@ -795,7 +945,10 @@ export class GenericContainer {
      * `findRunning` matches on `spec.name` alone.
      */
     async removeOrphanedRunningReuse(backend, name) {
-        const probePorts = new Map(this.exposedPorts.map((guestPort) => [guestPort, 0]));
+        const probePorts = {
+            tcp: new Map(this.exposedPorts.map((guestPort) => [guestPort, 0])),
+            udp: new Map(this.exposedUdpPorts.map((guestPort) => [guestPort, 0])),
+        };
         const probeSpec = this.buildReuseSpec(name, probePorts);
         const running = await backend.findRunning(probeSpec).catch(() => undefined);
         if (running !== undefined) {
@@ -846,14 +999,16 @@ export class GenericContainer {
             // simply stay marked issued for the rest of this process's lifetime;
             // only this instance's own view of them is cleared below.
             this.mappedPorts = new Map();
+            this.mappedUdpPorts = new Map();
             return;
         }
         await swallow(() => backend.stop(handle));
         await swallow(() => backend.remove(handle));
         unregisterSyncCleanup(handle.id);
         await untrackSandbox(handle.spec.name);
-        this.releasePorts(this.mappedPorts);
+        this.releasePorts({ tcp: this.mappedPorts, udp: this.mappedUdpPorts });
         this.mappedPorts = new Map();
+        this.mappedUdpPorts = new Map();
     }
     /** `= stop()`. What `await using c = await new GenericContainer(img).start()` calls at scope exit; never throws. */
     async [Symbol.asyncDispose]() {
@@ -871,10 +1026,14 @@ export class GenericContainer {
     get aliases() {
         return this.aliasNames;
     }
-    /** Every guest port this container published (set via `withExposedPorts`). Part of the `NetworkMember` contract `Network` uses to compute links. */
+    /** Every guest port this container published over TCP (set via `withExposedPorts`). Part of the `NetworkMember` contract `Network` uses to compute links; also what the default wait strategies probe — see `withExposedUdpPorts`' own doc on why UDP ports never appear here. */
     get exposedGuestPorts() {
         return this.exposedPorts;
     }
+    /** Every guest port this container published over UDP (set via `withExposedUdpPorts`) — a separate list from `exposedGuestPorts`, never merged with it. Part of the `NetworkMember` contract `Network` uses to compute links. */
+    get exposedUdpGuestPorts() {
+        return this.exposedUdpPorts;
+    }
     /**
      * The host port bound to `guestPort`. Throws distinct messages for the
      * two ways this can be wrong: not running at all ("call start() first"),
@@ -895,6 +1054,29 @@ export class GenericContainer {
     mappedPort(guestPort) {
         return this.getMappedPort(guestPort);
     }
+    /**
+     * The UDP counterpart of `getMappedPort` — reads from a SEPARATE
+     * per-protocol mapping store (`withExposedUdpPorts`), so exposing the same
+     * numeric guest port on both protocols (DNS's 53, say) never collides:
+     * `getMappedPort(53)` and `getMappedUdpPort(53)` can return two entirely
+     * different host ports. Throws the same two distinct-message shape as
+     * `getMappedPort`: not running at all, versus running but never exposed
+     * via `withExposedUdpPorts`.
+     */
+    getMappedUdpPort(guestPort) {
+        if (!this.running) {
+            throw new Error(`Container is not running — call start() first.`);
+        }
+        const port = this.mappedUdpPorts.get(guestPort);
+        if (port === undefined) {
+            throw new Error(`Port ${guestPort}/udp is not exposed — call withExposedUdpPorts(${guestPort}).`);
+        }
+        return port;
+    }
+    /** Alias for `getMappedUdpPort`, satisfying the `NetworkMember` shape (which names this method `mappedUdpPort`). */
+    mappedUdpPort(guestPort) {
+        return this.getMappedUdpPort(guestPort);
+    }
     requireHandle() {
         if (!this.running || this.handle === undefined || this.backend === undefined) {
             throw new Error(`Container is not running — call start() first.`);
@@ -912,21 +1094,48 @@ export class GenericContainer {
      * 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 (an absolute `<cacheDir>/checkpoints/rz-ckpt-<name>` path
-     * on microsandbox, `rightsize/checkpoint:<name>` on docker — see
+     * Passing `name` makes this checkpoint NAMED and durable: on docker the ref
+     * becomes deterministic (`rightsize/checkpoint:<name>` — see
      * `checkpointRef` — 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.
+     * a name that already has a registry entry REPLACES it: this best-effort
+     * clears whatever artifact the PRIOR checkpoint under `name` actually left
+     * behind, then overwrites the registry entry with the BACKEND'S OWN
+     * EFFECTIVE ref for the fresh checkpoint — the latest checkpoint under a
+     * name always wins. The prior artifact's real location comes from the
+     * existing registry entry itself (when one exists for a backend matching
+     * the currently active one) rather than a recomputed nominal ref: on
+     * docker the two are always the same deterministic value anyway, but on
+     * microsandbox (since 0.7.1) the effective ref is a content-addressed
+     * artifact path the nominal one never predicts (see
+     * `SandboxBackend.createCheckpoint`'s own doc), so reading it back from the
+     * registry is what makes this reliable there too — the same lookup
+     * `Checkpoints.remove(name)` itself uses.
+     *
+     * The PRIOR entry's real ref is only ever removed once the fresh
+     * checkpoint below has actually been created successfully (and, on a
+     * backend whose checkpoint reboots the workload, once the post-checkpoint
+     * re-wait below has succeeded too) — never before. When the prior ref and
+     * the freshly-minted nominal one are the SAME deterministic value (always
+     * true on docker), removing it earlier would just be removing the nominal
+     * ref that `createCheckpoint` is about to reuse anyway, so this method
+     * best-effort clears the nominal ref up front instead (a harmless no-op on
+     * microsandbox, where a name never predicts a real artifact); when the two
+     * differ (microsandbox's content-addressed case, or the rare coincidence
+     * of the two colliding on any backend), the prior ref is left completely
+     * untouched until the new one is confirmed both real and reachable. That
+     * ordering is what keeps a FAILED same-name re-checkpoint from destroying
+     * an otherwise-good, previously-restorable checkpoint: on any backend, a
+     * `createCheckpoint()` (or post-checkpoint re-wait) that throws leaves both
+     * the prior artifact and its registry entry completely untouched, exactly
+     * as if the failed call had never been attempted. Omitting `name` keeps
+     * the original behavior byte-for-byte: an ephemeral checkpoint with no
+     * registry entry, whose `Checkpoint.ref` is always the backend's own
+     * effective ref.
      *
      * On a backend whose `capabilities.checkpointRestartsWorkload` is `true`
      * (microsandbox: the stop/snapshot/reboot cycle boots a fresh microVM),
@@ -943,6 +1152,11 @@ export class GenericContainer {
      * BEFORE the wait-strategy re-run — the wait must gate a container that is
      * fully re-linked, not just booted.
      *
+     * If that re-wait (or the link re-install before it) fails, this container
+     * is torn down to completion via `stop()` — same as a failed `start()` —
+     * before the rejection propagates, so a revived-but-never-ready workload
+     * never sits around as an orphan.
+     *
      * 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.
@@ -968,33 +1182,147 @@ export class GenericContainer {
             throw new TmpfsRootCheckpointError();
         }
         const ref = checkpointRef(backend.name, name);
+        // Replace semantics: a prior checkpoint under this same name — if any —
+        // is cleared once the new one is confirmed to actually exist (see the
+        // deferred removal after `createCheckpoint`/the post-checkpoint re-wait
+        // below), never before — a failed re-checkpoint must never cost this
+        // container its previously-good, restorable checkpoint. The RELIABLE way
+        // to find where the prior checkpoint actually lives is the registry's
+        // own recorded entry (the same lookup `Checkpoints.remove(name)` uses),
+        // not a freshly-minted nominal ref: on docker the ref is deterministic
+        // from `name`, so the registry entry's `ref` and the nominal one below
+        // are always the same value anyway, but on microsandbox (since 0.7.1)
+        // the EFFECTIVE ref `createCheckpoint` returns is a content-addressed
+        // artifact path the nominal one never determines (see
+        // `SandboxBackend.createCheckpoint`'s own doc) — only the registry's
+        // recorded ref points at the real artifact there. Only consulted when
+        // the entry's own recorded backend matches the CURRENTLY active one — a
+        // foreign-backend ref means nothing to this backend's `removeCheckpoint`,
+        // same gate `find`/`remove` apply to the same mismatch. A missing or
+        // corrupt registry read is treated the same as "no entry" (best-effort:
+        // this must never fail the checkpoint itself), leaving only the
+        // nominal-ref removal below to run.
+        let priorRealRef;
         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.
+            try {
+                const registryRead = await readCheckpointRegistry(cacheDir(), name);
+                if (registryRead.kind === "found" && registryRead.entry.backend === backend.name) {
+                    priorRealRef = registryRead.entry.ref;
+                }
+            }
+            catch {
+                // Swallowed deliberately — see the comment above.
+            }
+            // Best-effort clear the freshly-minted NOMINAL ref up front, before
+            // creating the new checkpoint — exactly what this method did before
+            // the registry lookup above existed. On docker this nominal ref IS the
+            // prior checkpoint's real recorded ref (deterministic from `name`), so
+            // this is the only removal that ever runs there, and it must run here:
+            // `createCheckpoint` is about to reuse this exact ref, so there is no
+            // "after" at which removing it wouldn't also remove the checkpoint
+            // just created. On microsandbox this is a no-op against a path that
+            // was never real, same as before this method ever read the registry —
+            // so nothing new is destroyed here before the new checkpoint's success
+            // is confirmed.
             await swallow(() => backend.removeCheckpoint(ref));
         }
-        await backend.createCheckpoint(handle, ref);
+        // The EFFECTIVE ref: on docker this is always `ref` itself; on
+        // microsandbox (since 0.7.1) it is whatever real artifact path
+        // `createCheckpoint` discovered from `msb snapshot create`'s own stdout
+        // — never necessarily `ref`. Everything downstream (the registry entry,
+        // the returned `Checkpoint`) uses this, not the working `ref`.
+        //
+        // Captured BEFORE the call: a backend whose checkpoint reboots the
+        // workload under a fresh identity (msb's `createCheckpoint`, see its own
+        // doc) mutates `handle.id` IN PLACE once that reboot succeeds — the same
+        // carve-out `SandboxBackend.createCheckpoint`'s own interface doc
+        // documents. `registerSyncCleanup` (see start(), above) keyed its exit-path
+        // teardown entry by the OLD id; if the id just changed, that registration
+        // must be re-keyed to the new one too, or the old entry leaks in
+        // `cleanup.ts`'s registry forever (stop() below only ever unregisters by
+        // the CURRENT `handle.id`, which after a rename no longer matches what
+        // was registered) — silently breaking both the exit-path teardown for
+        // this container AND `liveContainers()`/diagnostics, which read that same
+        // registry.
+        const preCheckpointHandleId = handle.id;
+        const effectiveRef = await backend.createCheckpoint(handle, ref);
+        if (handle.id !== preCheckpointHandleId && !handle.spec.keepAlive) {
+            // Mirrors start()'s own keepAlive exclusion: a keepAlive container was
+            // never registered in the first place, so there is nothing to re-key.
+            // The cleanup closure below reads `handle.id` dynamically (see
+            // start()'s own registerSyncCleanup call), so re-registering it under
+            // the new id is automatically correct without capturing anything else.
+            unregisterSyncCleanup(preCheckpointHandleId);
+            registerSyncCleanup(handle, backend, () => backend.cleanupSync(handle.id));
+        }
         if (backend.capabilities.checkpointRestartsWorkload) {
-            if (this.installedNetworkLinks.length > 0) {
-                await backend.installNetworkLinks(handle, this.installedNetworkLinks);
+            // The backend checkpoint call above already succeeded — the artifact
+            // exists — but the reboot it triggered can still leave this container
+            // unusable: a revived workload that never becomes ready. Same shape as
+            // start()'s own post-boot wait (line ~722): a failure here must not
+            // leak the freshly-spawned workload (msb's revived `exec` child sits
+            // in `handle`'s attached slot from the moment the reboot reaches
+            // Running, well before this wait ever resolves). Tear this container
+            // down to completion via the same this.stop() start() uses, so the
+            // handle's attached child — and the sandbox itself — never outlive
+            // this rejection, before rethrowing.
+            try {
+                if (this.installedNetworkLinks.length > 0) {
+                    await backend.installNetworkLinks(handle, this.installedNetworkLinks);
+                }
+                await this.waitStrategy.waitUntilReady(this.asWaitTarget());
+            }
+            catch (err) {
+                await this.stop();
+                throw err;
             }
-            await this.waitStrategy.waitUntilReady(this.asWaitTarget());
         }
+        // The workload argv the backend captured from the guest during the
+        // createCheckpoint() call just above, when `handle.spec.command` was
+        // undefined — see `SandboxBackend.capturedWorkloadCommand`'s own doc.
+        // `undefined` on every backend that never captures one (docker, or msb
+        // when the source container already carried an explicit command).
+        const capturedCommand = backend.capturedWorkloadCommand?.(handle);
         if (name !== undefined) {
+            // Only reached once the fresh checkpoint above is confirmed both real
+            // (createCheckpoint succeeded) and reachable (the post-checkpoint
+            // re-wait above, when applicable, succeeded too) — a failure at either
+            // point already threw and returned above, before any of this ran. The
+            // PRIOR checkpoint's real recorded ref (see the registry lookup
+            // before createCheckpoint) is best-effort removed here, now that it is
+            // safe to: never when it's the SAME ref as the nominal one already
+            // cleared above (docker — clearing it again here would target the
+            // fresh checkpoint `createCheckpoint` just reused that exact ref for),
+            // and never when it happens to equal the fresh checkpoint's own
+            // EFFECTIVE ref (the rare case of two checkpoints content-addressing
+            // to the very same artifact on microsandbox — removing it would delete
+            // the checkpoint this call just created, not a prior one).
+            if (priorRealRef !== undefined && priorRealRef !== ref && priorRealRef !== effectiveRef) {
+                const realRef = priorRealRef;
+                await swallow(() => backend.removeCheckpoint(realRef));
+            }
             // 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,
+                ref: effectiveRef,
                 backend: backend.name,
                 createdIso: new Date().toISOString(),
                 spec: toCheckpointRegistrySpec(handle.spec),
+                ...(capturedCommand !== undefined ? { capturedCommand } : {}),
             };
             await writeCheckpointRegistryAtomic(cacheDir(), name, entry);
         }
-        return { ref, backend: backend.name, spec: handle.spec };
+        // `handle.spec.command` already covers an explicit command; only
+        // substitute the captured fallback when the source had none, so a later
+        // `fromCheckpoint(cp).start()` on THIS in-memory `Checkpoint` — unnamed
+        // or named, same process or not — already carries the fully-resolved
+        // workload argv a restore-side backend needs to revive it, the same
+        // merge `fromCheckpointRegistryEntry` applies for a registry-mediated
+        // restore.
+        const effectiveSpec = handle.spec.command !== undefined || capturedCommand === undefined ? handle.spec : { ...handle.spec, command: capturedCommand };
+        return { ref: effectiveRef, backend: backend.name, spec: effectiveSpec };
     }
     /**
      * Copies a host file or directory into this running container at