rightsize 0.7.9 → 0.7.12

package/dist/core/checkpoint/registry.js

@@ -39,6 +39,14 @@ export function isCheckpointRegistrySpec(value) {
     if (!Array.isArray(exposedPorts) || !exposedPorts.every((p) => typeof p === "number")) {
         return false;
     }
+    // Additive and optional (see CheckpointRegistrySpec's own doc): an entry
+    // written before UDP exposure existed simply omits the key, which reads as
+    // "no UDP ports" — only a PRESENT-but-malformed value (not an array of
+    // numbers) is corrupt.
+    const exposedUdpPorts = rec["exposedUdpPorts"];
+    if (exposedUdpPorts !== undefined && !(Array.isArray(exposedUdpPorts) && exposedUdpPorts.every((p) => typeof p === "number"))) {
+        return false;
+    }
     const memoryLimitMb = rec["memoryLimitMb"];
     if (memoryLimitMb !== null && typeof memoryLimitMb !== "number") {
         return false;
@@ -56,6 +64,13 @@ function isCheckpointRegistryEntry(value) {
         typeof rec["createdIso"] !== "string") {
         return false;
     }
+    // Additive and optional (see CheckpointRegistryEntry's own doc): an entry
+    // written before this field existed simply omits the key, which is fine —
+    // only a PRESENT-but-malformed value (not an array of strings) is corrupt.
+    const capturedCommand = rec["capturedCommand"];
+    if (capturedCommand !== undefined && !(Array.isArray(capturedCommand) && capturedCommand.every((c) => typeof c === "string"))) {
+        return false;
+    }
     return isCheckpointRegistrySpec(rec["spec"]);
 }
 /**
@@ -143,11 +158,16 @@ export function toCheckpointRegistrySpec(spec) {
     for (const [key, value] of spec.env) {
         env[key] = value;
     }
+    const exposedUdpPorts = spec.ports.filter((p) => p.protocol === "udp").map((p) => p.guestPort);
     return {
         env,
         command: spec.command ?? null,
-        exposedPorts: spec.ports.map((p) => p.guestPort),
+        exposedPorts: spec.ports.filter((p) => p.protocol === "tcp").map((p) => p.guestPort),
         memoryLimitMb: spec.memoryLimitMb ?? null,
+        // Omitted (not an empty array) when there are none — a spec that never
+        // exposes a UDP port serializes exactly as it did before this field
+        // existed.
+        ...(exposedUdpPorts.length > 0 ? { exposedUdpPorts } : {}),
     };
 }
 /**
@@ -163,14 +183,31 @@ export function toCheckpointRegistrySpec(spec) {
  * pointing at itself. `diskLimitMb`/`tmpfsRootMb`/`networkDisabled` are
  * placeholders too — the registry's pinned `CheckpointRegistrySpec` shape
  * doesn't carry them, same as it never carried `keepAlive`.
+ *
+ * `command` resolves with `entry.capturedCommand` as its fallback: when the
+ * source container had an explicit command, `entry.spec.command` already
+ * carries it and `capturedCommand` (never set for that case) never enters
+ * into it; when it did not, this substitutes whatever guest cmdline
+ * `checkpoint()` captured, so the restored `ContainerSpec`'s `command` is
+ * already the fully-resolved workload argv a restore-side backend (msb)
+ * needs to revive it, with no separate lookup needed at restore time. When
+ * NEITHER is present (an entry written before capture existed, or one whose
+ * capture attempt itself failed), `command` stays `undefined` exactly as
+ * before, and it is the restoring backend's own job to refuse rather than
+ * boot that sandbox silently idle (see `MsbCliBackend.bootRestoreOnce`).
  */
 export function fromCheckpointRegistryEntry(entry) {
     return {
         name: entry.name,
         image: entry.ref,
         env: envRecordToPairs(entry.spec.env),
-        command: entry.spec.command ?? undefined,
-        ports: entry.spec.exposedPorts.map((guestPort) => ({ hostPort: 0, guestPort })),
+        command: entry.spec.command ?? entry.capturedCommand ?? undefined,
+        ports: [
+            ...entry.spec.exposedPorts.map((guestPort) => ({ hostPort: 0, guestPort, protocol: "tcp" })),
+            // Absent on an entry written before UDP exposure existed — normalizes
+            // to no UDP ports, never a corrupt read (see isCheckpointRegistrySpec).
+            ...(entry.spec.exposedUdpPorts ?? []).map((guestPort) => ({ hostPort: 0, guestPort, protocol: "udp" })),
+        ],
         mounts: [],
         networkId: undefined,
         aliases: [],
@@ -181,6 +218,10 @@ export function fromCheckpointRegistryEntry(entry) {
         diskLimitMb: undefined,
         tmpfsRootMb: undefined,
         networkDisabled: false,
+        // Per-run wiring, never persisted — same placeholder treatment as
+        // networkDisabled/diskLimitMb/tmpfsRootMb above (see ContainerSpec's own
+        // doc on why this is never part of a checkpoint's identity).
+        hostUdpEgressPorts: [],
     };
 }
 //# sourceMappingURL=registry.js.map

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

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

package/dist/core/errors.d.ts

@@ -119,6 +119,34 @@ export declare class CheckpointBackendMismatchError extends Error {
 export declare class ReuseFromCheckpointError extends Error {
     constructor();
 }
+/**
+ * Thrown at `start()` when a container built via `GenericContainer.fromCheckpoint()`
+ * carries an env that no longer matches the checkpoint's own captured env —
+ * an extra `withEnv()` call, or one overriding a key the checkpoint already
+ * set — and the active backend has no way to apply that at restore time.
+ *
+ * msb is the one backend this affects: 0.7.1 replaced `run --from-snapshot`
+ * with a dedicated `msb restore` command that has no `-e`/`--env` flag at
+ * all (a disk-only restore replays the sandbox's own captured
+ * configuration). Before 0.7.1, an overridden or extended env silently
+ * reached the restored guest via `run -e`; since there is now no msb
+ * invocation this library could emit that would honor it, silently dropping
+ * it would let the workload boot with env the caller never asked for and
+ * without env it did ask for — a correctness bug, not a graceful
+ * degradation — so this throws instead, before any backend call. Restoring
+ * with the checkpoint's own env completely unchanged never hits this: only
+ * a call that actually changes what would be sent does. docker is
+ * unaffected — restoring there is an ordinary `docker create`/`run` against
+ * the committed image with a fresh env array, so this is never thrown when
+ * the active backend is `"docker"`.
+ */
+export declare class CheckpointRestoreEnvOverrideError extends Error {
+    /** The active backend's name — always `"microsandbox"` today, the one backend this affects. */
+    readonly backend: string;
+    constructor(
+    /** The active backend's name — always `"microsandbox"` today, the one backend this affects. */
+    backend: string);
+}
 /**
  * Thrown by `copyFileToContainer`/`copyContentToContainer`/
  * `copyFileFromContainer` when `containerPath` is not absolute — both
@@ -251,4 +279,25 @@ export declare class NetworkDisabledConflictError extends Error {
 export declare class TmpfsRootCheckpointError extends Error {
     constructor();
 }
+/**
+ * Thrown restoring a microsandbox checkpoint whose source container had no
+ * explicit command (the image's own default entrypoint was running) and
+ * whose registry entry carries no captured workload cmdline either —
+ * `msb restore` boots a restored sandbox with only its guest agent inside
+ * and never re-runs anything on its own (EMPIRICALLY VERIFIED against msb
+ * 0.7.1 — see `MsbCliBackend.bootRestoreOnce`'s own doc), so without EITHER
+ * source this library has no workload argv left to revive. Thrown instead of
+ * silently booting the sandbox idle — the checkpoint either predates
+ * workload-cmdline capture, or its capture attempt failed at checkpoint time
+ * (see `CheckpointRegistryEntry.capturedCommand`'s own doc on why a capture
+ * failure never fails the checkpoint that created it, only a later restore
+ * of it). Only ever thrown by the microsandbox backend.
+ */
+export declare class CheckpointWorkloadCommandMissingError extends Error {
+    /** The checkpoint ref being restored. */
+    readonly ref: string;
+    constructor(
+    /** The checkpoint ref being restored. */
+    ref: string);
+}
 //# sourceMappingURL=errors.d.ts.map

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

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

package/dist/core/errors.js

@@ -158,6 +158,40 @@ export class ReuseFromCheckpointError extends Error {
         this.name = "ReuseFromCheckpointError";
     }
 }
+/**
+ * Thrown at `start()` when a container built via `GenericContainer.fromCheckpoint()`
+ * carries an env that no longer matches the checkpoint's own captured env —
+ * an extra `withEnv()` call, or one overriding a key the checkpoint already
+ * set — and the active backend has no way to apply that at restore time.
+ *
+ * msb is the one backend this affects: 0.7.1 replaced `run --from-snapshot`
+ * with a dedicated `msb restore` command that has no `-e`/`--env` flag at
+ * all (a disk-only restore replays the sandbox's own captured
+ * configuration). Before 0.7.1, an overridden or extended env silently
+ * reached the restored guest via `run -e`; since there is now no msb
+ * invocation this library could emit that would honor it, silently dropping
+ * it would let the workload boot with env the caller never asked for and
+ * without env it did ask for — a correctness bug, not a graceful
+ * degradation — so this throws instead, before any backend call. Restoring
+ * with the checkpoint's own env completely unchanged never hits this: only
+ * a call that actually changes what would be sent does. docker is
+ * unaffected — restoring there is an ordinary `docker create`/`run` against
+ * the committed image with a fresh env array, so this is never thrown when
+ * the active backend is `"docker"`.
+ */
+export class CheckpointRestoreEnvOverrideError extends Error {
+    backend;
+    constructor(
+    /** The active backend's name — always `"microsandbox"` today, the one backend this affects. */
+    backend) {
+        super(`fromCheckpoint(...).withEnv(...) cannot override or extend a checkpoint's captured env when restoring ` +
+            `on the '${backend}' backend — its restore command has no way to inject env at boot time, so an ` +
+            `overridden or extended env would be silently dropped instead of reaching the restored workload. ` +
+            `Restore with the checkpoint's own env unchanged, or bake the desired env into a fresh checkpoint instead.`);
+        this.backend = backend;
+        this.name = "CheckpointRestoreEnvOverrideError";
+    }
+}
 /**
  * Thrown by `copyFileToContainer`/`copyContentToContainer`/
  * `copyFileFromContainer` when `containerPath` is not absolute — both
@@ -326,4 +360,31 @@ export class TmpfsRootCheckpointError extends Error {
         this.name = "TmpfsRootCheckpointError";
     }
 }
+/**
+ * Thrown restoring a microsandbox checkpoint whose source container had no
+ * explicit command (the image's own default entrypoint was running) and
+ * whose registry entry carries no captured workload cmdline either —
+ * `msb restore` boots a restored sandbox with only its guest agent inside
+ * and never re-runs anything on its own (EMPIRICALLY VERIFIED against msb
+ * 0.7.1 — see `MsbCliBackend.bootRestoreOnce`'s own doc), so without EITHER
+ * source this library has no workload argv left to revive. Thrown instead of
+ * silently booting the sandbox idle — the checkpoint either predates
+ * workload-cmdline capture, or its capture attempt failed at checkpoint time
+ * (see `CheckpointRegistryEntry.capturedCommand`'s own doc on why a capture
+ * failure never fails the checkpoint that created it, only a later restore
+ * of it). Only ever thrown by the microsandbox backend.
+ */
+export class CheckpointWorkloadCommandMissingError extends Error {
+    ref;
+    constructor(
+    /** The checkpoint ref being restored. */
+    ref) {
+        super(`sandbox restore from checkpoint '${ref}' has no explicit command and no captured workload cmdline in ` +
+            "its registry entry — this checkpoint predates workload-cmdline capture, or its capture attempt " +
+            "failed at checkpoint time, so there is no workload argv left to revive. Re-checkpoint the source " +
+            "container under a build that captures one.");
+        this.ref = ref;
+        this.name = "CheckpointWorkloadCommandMissingError";
+    }
+}
 //# 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;;;;;;;GAOG;AACH,MAAM,OAAO,0BAA2B,SAAQ,KAAK;IAGxC;IAFX;IACE,yDAAyD;IAChD,OAAe;QAExB,KAAK,CACH,yCAAyC,OAAO,kDAAkD;YAChG,kCAAkC,CACrC,CAAC;QALO,YAAO,GAAP,OAAO,CAAQ;QAMxB,IAAI,CAAC,IAAI,GAAG,4BAA4B,CAAC;IAC3C,CAAC;CACF;AAED;;;;;;GAMG;AACH,MAAM,OAAO,8BAA+B,SAAQ,KAAK;IAG5C;IAEA;IAJX;IACE,+CAA+C;IACtC,gBAAwB;IACjC,+CAA+C;IACtC,aAAqB;QAE9B,KAAK,CACH,uCAAuC,gBAAgB,sCAAsC;YAC3F,IAAI,aAAa,6BAA6B,gBAAgB,0CAA0C;YACxG,yBAAyB,aAAa,oBAAoB,CAC7D,CAAC;QARO,qBAAgB,GAAhB,gBAAgB,CAAQ;QAExB,kBAAa,GAAb,aAAa,CAAQ;QAO9B,IAAI,CAAC,IAAI,GAAG,gCAAgC,CAAC;IAC/C,CAAC;CACF;AAED;;;;;;;GAOG;AACH,MAAM,OAAO,wBAAyB,SAAQ,KAAK;IACjD;QACE,KAAK,CACH,8FAA8F;YAC5F,sGAAsG;YACtG,uDAAuD,CAC1D,CAAC;QACF,IAAI,CAAC,IAAI,GAAG,0BAA0B,CAAC;IACzC,CAAC;CACF;AAED;;;;;GAKG;AACH,MAAM,OAAO,0BAA2B,SAAQ,KAAK;IAGxC;IAFX;IACE,+CAA+C;IACtC,aAAqB;QAE9B,KAAK,CAAC,gDAAgD,aAAa,oDAAoD,CAAC,CAAC;QAFhH,kBAAa,GAAb,aAAa,CAAQ;QAG9B,IAAI,CAAC,IAAI,GAAG,4BAA4B,CAAC;IAC3C,CAAC;CACF;AAED;;;;;GAKG;AACH,MAAM,OAAO,0BAA2B,SAAQ,KAAK;IAGxC;IAFX;IACE,+CAA+C;IACtC,cAAsB;QAE/B,KAAK,CACH,oBAAoB,cAAc,wEAAwE;YACxG,qGAAqG;YACrG,2CAA2C,CAC9C,CAAC;QANO,mBAAc,GAAd,cAAc,CAAQ;QAO/B,IAAI,CAAC,IAAI,GAAG,4BAA4B,CAAC;IAC3C,CAAC;CACF;AAED;;;;;;GAMG;AACH,MAAM,OAAO,8BAA+B,SAAQ,KAAK;IAG5C;IAEA;IAJX;IACE,oFAAoF;IAC3E,GAAW;IACpB,qDAAqD;IAC5C,OAAe;QAExB,KAAK,CACH,6BAA6B,GAAG,qDAAqD,OAAO,YAAY;YACtG,oFAAoF,CACvF,CAAC;QAPO,QAAG,GAAH,GAAG,CAAQ;QAEX,YAAO,GAAP,OAAO,CAAQ;QAMxB,IAAI,CAAC,IAAI,GAAG,gCAAgC,CAAC;IAC/C,CAAC;CACF;AAED;;;;;;;;;GASG;AACH,MAAM,OAAO,sBAAuB,SAAQ,KAAK;IAGpC;IAEA;IAJX;IACE,wFAAwF;IAC/E,kBAA0B;IACnC,0DAA0D;IACjD,kBAA0B;QAEnC,KAAK,CACH,qBAAqB,kBAAkB,qBAAqB,kBAAkB,uBAAuB;YACnG,iBAAiB,kBAAkB,2CAA2C;YAC9E,2DAA2D,kBAAkB,IAAI,CACpF,CAAC;QARO,uBAAkB,GAAlB,kBAAkB,CAAQ;QAE1B,uBAAkB,GAAlB,kBAAkB,CAAQ;QAOnC,IAAI,CAAC,IAAI,GAAG,wBAAwB,CAAC;IACvC,CAAC;CACF;AAED;;;;;;;GAOG;AACH,MAAM,OAAO,+BAAgC,SAAQ,KAAK;IAG7C;IAEA;IAJX;IACE,iEAAiE;IACxD,WAAmB;IAC5B,6DAA6D;IACpD,MAAc;QAEvB,KAAK,CAAC,uBAAuB,WAAW,oBAAoB,MAAM,EAAE,CAAC,CAAC;QAJ7D,gBAAW,GAAX,WAAW,CAAQ;QAEnB,WAAM,GAAN,MAAM,CAAQ;QAGvB,IAAI,CAAC,IAAI,GAAG,iCAAiC,CAAC;IAChD,CAAC;CACF;AAED;;;;GAIG;AACH,MAAM,OAAO,qBAAsB,SAAQ,KAAK;IAC9C;QACE,KAAK,CACH,mGAAmG;YACjG,iCAAiC,CACpC,CAAC;QACF,IAAI,CAAC,IAAI,GAAG,uBAAuB,CAAC;IACtC,CAAC;CACF;AAED;;;;;;GAMG;AACH,MAAM,OAAO,2BAA4B,SAAQ,KAAK;IAGzC;IAEA;IAJX;IACE,4CAA4C;IACnC,OAAe;IACxB,mDAAmD;IAC1C,QAAgB;QAEzB,KAAK,CACH,iBAAiB,OAAO,6BAA6B,QAAQ,6CAA6C;YACxG,qBAAqB,CACxB,CAAC;QAPO,YAAO,GAAP,OAAO,CAAQ;QAEf,aAAQ,GAAR,QAAQ,CAAQ;QAMzB,IAAI,CAAC,IAAI,GAAG,6BAA6B,CAAC;IAC5C,CAAC;CACF;AAED;;;;GAIG;AACH,MAAM,OAAO,4BAA6B,SAAQ,KAAK;IACrD;QACE,KAAK,CACH,yGAAyG;YACvG,sBAAsB,CACzB,CAAC;QACF,IAAI,CAAC,IAAI,GAAG,8BAA8B,CAAC;IAC7C,CAAC;CACF;AAED;;;;;;;;;;GAUG;AACH,MAAM,OAAO,wBAAyB,SAAQ,KAAK;IACjD;QACE,KAAK,CACH,wGAAwG;YACtG,uEAAuE,CAC1E,CAAC;QACF,IAAI,CAAC,IAAI,GAAG,0BAA0B,CAAC;IACzC,CAAC;CACF"}
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../../src/core/errors.ts"],"names":[],"mappings":"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"}

package/dist/core/free-ports.d.ts

@@ -10,14 +10,32 @@
 export declare function allocate(): Promise<number>;
 /** Releases a port back to the pool. Releasing a port never issued by this process is a harmless no-op. */
 export declare function release(port: number): void;
+/**
+ * The UDP counterpart of `allocate`: same in-process-uniqueness contract,
+ * same retry shape, but proven free by binding a UDP socket (see
+ * `bindEphemeralUdpPort`) rather than a TCP listener — a TCP probe cannot
+ * stand in for this, since the two transports keep independent OS port
+ * tables.
+ */
+export declare function allocateUdp(): Promise<number>;
+/** Releases a UDP port back to its pool — the UDP counterpart of `release`. Releasing a port never issued by this process is a harmless no-op. */
+export declare function releaseUdp(port: number): void;
 /** Test-only observability seam: the ports currently considered issued. */
 export declare function issuedView(): ReadonlySet<number>;
+/** Test-only observability seam for the UDP pool — see `issuedView`. */
+export declare function issuedUdpView(): ReadonlySet<number>;
 export declare const FreePorts: {
     /** Allocates a host port this process has not already handed out — see `allocate` above. */
     allocate: typeof allocate;
     /** Releases a port back to the pool — see `release` above. */
     release: typeof release;
+    /** Allocates a UDP host port this process has not already handed out — see `allocateUdp` above. */
+    allocateUdp: typeof allocateUdp;
+    /** Releases a UDP port back to its pool — see `releaseUdp` above. */
+    releaseUdp: typeof releaseUdp;
     /** Test-only observability seam — see `issuedView` above. */
     issuedView: typeof issuedView;
+    /** Test-only observability seam for the UDP pool — see `issuedUdpView` above. */
+    issuedUdpView: typeof issuedUdpView;
 };
 //# sourceMappingURL=free-ports.d.ts.map

package/dist/core/free-ports.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"free-ports.d.ts","sourceRoot":"","sources":["../../src/core/free-ports.ts"],"names":[],"mappings":"AAgCA;;;;;;;;GAQG;AACH,wBAAsB,QAAQ,IAAI,OAAO,CAAC,MAAM,CAAC,CAShD;AAED,2GAA2G;AAC3G,wBAAgB,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAE1C;AAED,2EAA2E;AAC3E,wBAAgB,UAAU,IAAI,WAAW,CAAC,MAAM,CAAC,CAEhD;AAED,eAAO,MAAM,SAAS;IACpB,4FAA4F;;IAE5F,8DAA8D;;IAE9D,6DAA6D;;CAE9D,CAAC"}
+{"version":3,"file":"free-ports.d.ts","sourceRoot":"","sources":["../../src/core/free-ports.ts"],"names":[],"mappings":"AA+DA;;;;;;;;GAQG;AACH,wBAAsB,QAAQ,IAAI,OAAO,CAAC,MAAM,CAAC,CAShD;AAED,2GAA2G;AAC3G,wBAAgB,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAE1C;AAED;;;;;;GAMG;AACH,wBAAsB,WAAW,IAAI,OAAO,CAAC,MAAM,CAAC,CASnD;AAED,kJAAkJ;AAClJ,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAE7C;AAED,2EAA2E;AAC3E,wBAAgB,UAAU,IAAI,WAAW,CAAC,MAAM,CAAC,CAEhD;AAED,wEAAwE;AACxE,wBAAgB,aAAa,IAAI,WAAW,CAAC,MAAM,CAAC,CAEnD;AAED,eAAO,MAAM,SAAS;IACpB,4FAA4F;;IAE5F,8DAA8D;;IAE9D,mGAAmG;;IAEnG,qEAAqE;;IAErE,6DAA6D;;IAE7D,iFAAiF;;CAElF,CAAC"}

package/dist/core/free-ports.js

@@ -1,4 +1,5 @@
 import * as net from "node:net";
+import * as dgram from "node:dgram";
 const MAX_ALLOCATE_ATTEMPTS = 100;
 // Binds are loopback-only (127.0.0.1), not wildcard — the same conservative
 // choice used everywhere else a host port is touched (publishing, wait
@@ -24,7 +25,36 @@ function bindEphemeralPort() {
         });
     });
 }
+/**
+ * The UDP counterpart of `bindEphemeralPort`: a TCP `listen()` proves
+ * nothing about UDP's independent OS port table (and vice versa) — a port
+ * free on one transport can easily be bound on the other — so a UDP host
+ * port must be proven free by binding an actual UDP socket, not inferred
+ * from the TCP probe. Same shape as the TCP path: bind ephemeral, read the
+ * assigned port back, close, hand the number to the caller.
+ */
+function bindEphemeralUdpPort() {
+    return new Promise((resolvePort, rejectPort) => {
+        const socket = dgram.createSocket("udp4");
+        socket.once("error", (err) => {
+            rejectPort(err);
+        });
+        socket.bind(0, BIND_HOST, () => {
+            const address = socket.address();
+            const port = address.port;
+            socket.close(() => {
+                resolvePort(port);
+            });
+        });
+    });
+}
 const issued = new Set();
+// A separate issued set for UDP: TCP and UDP each have their own OS-level
+// port table, so the two pools track uniqueness independently — a port
+// issued on one transport says nothing about the other, and a container may
+// legitimately be handed the same numeric port on both (see `PortBinding`'s
+// own doc on the DNS-53 case).
+const issuedUdp = new Set();
 /**
  * Allocates a host port this process has not already handed out. Binding
  * `127.0.0.1:0` and immediately closing the socket leaves a window where
@@ -48,16 +78,47 @@ export async function allocate() {
 export function release(port) {
     issued.delete(port);
 }
+/**
+ * The UDP counterpart of `allocate`: same in-process-uniqueness contract,
+ * same retry shape, but proven free by binding a UDP socket (see
+ * `bindEphemeralUdpPort`) rather than a TCP listener — a TCP probe cannot
+ * stand in for this, since the two transports keep independent OS port
+ * tables.
+ */
+export async function allocateUdp() {
+    for (let attempt = 0; attempt < MAX_ALLOCATE_ATTEMPTS; attempt++) {
+        const port = await bindEphemeralUdpPort();
+        if (!issuedUdp.has(port)) {
+            issuedUdp.add(port);
+            return port;
+        }
+    }
+    throw new Error(`could not allocate a unique free UDP port after ${MAX_ALLOCATE_ATTEMPTS} attempts`);
+}
+/** Releases a UDP port back to its pool — the UDP counterpart of `release`. Releasing a port never issued by this process is a harmless no-op. */
+export function releaseUdp(port) {
+    issuedUdp.delete(port);
+}
 /** Test-only observability seam: the ports currently considered issued. */
 export function issuedView() {
     return new Set(issued);
 }
+/** Test-only observability seam for the UDP pool — see `issuedView`. */
+export function issuedUdpView() {
+    return new Set(issuedUdp);
+}
 export const FreePorts = {
     /** Allocates a host port this process has not already handed out — see `allocate` above. */
     allocate,
     /** Releases a port back to the pool — see `release` above. */
     release,
+    /** Allocates a UDP host port this process has not already handed out — see `allocateUdp` above. */
+    allocateUdp,
+    /** Releases a UDP port back to its pool — see `releaseUdp` above. */
+    releaseUdp,
     /** Test-only observability seam — see `issuedView` above. */
     issuedView,
+    /** Test-only observability seam for the UDP pool — see `issuedUdpView` above. */
+    issuedUdpView,
 };
 //# sourceMappingURL=free-ports.js.map

package/dist/core/free-ports.js.map

@@ -1 +1 @@
-{"version":3,"file":"free-ports.js","sourceRoot":"","sources":["../../src/core/free-ports.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,GAAG,MAAM,UAAU,CAAC;AAEhC,MAAM,qBAAqB,GAAG,GAAG,CAAC;AAElC,4EAA4E;AAC5E,uEAAuE;AACvE,2EAA2E;AAC3E,MAAM,SAAS,GAAG,WAAW,CAAC;AAE9B,SAAS,iBAAiB;IACxB,OAAO,IAAI,OAAO,CAAC,CAAC,WAAW,EAAE,UAAU,EAAE,EAAE;QAC7C,MAAM,MAAM,GAAG,GAAG,CAAC,YAAY,EAAE,CAAC;QAClC,MAAM,CAAC,IAAI,CAAC,OAAO,EAAE,CAAC,GAAG,EAAE,EAAE;YAC3B,UAAU,CAAC,GAAG,CAAC,CAAC;QAClB,CAAC,CAAC,CAAC;QACH,MAAM,CAAC,MAAM,CAAC,CAAC,EAAE,SAAS,EAAE,GAAG,EAAE;YAC/B,MAAM,OAAO,GAAG,MAAM,CAAC,OAAO,EAAE,CAAC;YACjC,IAAI,OAAO,KAAK,IAAI,IAAI,OAAO,OAAO,KAAK,QAAQ,EAAE,CAAC;gBACpD,MAAM,CAAC,KAAK,EAAE,CAAC;gBACf,UAAU,CAAC,IAAI,KAAK,CAAC,wDAAwD,CAAC,CAAC,CAAC;gBAChF,OAAO;YACT,CAAC;YACD,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC;YAC1B,MAAM,CAAC,KAAK,CAAC,GAAG,EAAE;gBAChB,WAAW,CAAC,IAAI,CAAC,CAAC;YACpB,CAAC,CAAC,CAAC;QACL,CAAC,CAAC,CAAC;IACL,CAAC,CAAC,CAAC;AACL,CAAC;AAED,MAAM,MAAM,GAAG,IAAI,GAAG,EAAU,CAAC;AAEjC;;;;;;;;GAQG;AACH,MAAM,CAAC,KAAK,UAAU,QAAQ;IAC5B,KAAK,IAAI,OAAO,GAAG,CAAC,EAAE,OAAO,GAAG,qBAAqB,EAAE,OAAO,EAAE,EAAE,CAAC;QACjE,MAAM,IAAI,GAAG,MAAM,iBAAiB,EAAE,CAAC;QACvC,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC;YACtB,MAAM,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;YACjB,OAAO,IAAI,CAAC;QACd,CAAC;IACH,CAAC;IACD,MAAM,IAAI,KAAK,CAAC,+CAA+C,qBAAqB,WAAW,CAAC,CAAC;AACnG,CAAC;AAED,2GAA2G;AAC3G,MAAM,UAAU,OAAO,CAAC,IAAY;IAClC,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;AACtB,CAAC;AAED,2EAA2E;AAC3E,MAAM,UAAU,UAAU;IACxB,OAAO,IAAI,GAAG,CAAC,MAAM,CAAC,CAAC;AACzB,CAAC;AAED,MAAM,CAAC,MAAM,SAAS,GAAG;IACvB,4FAA4F;IAC5F,QAAQ;IACR,8DAA8D;IAC9D,OAAO;IACP,6DAA6D;IAC7D,UAAU;CACX,CAAC"}
+{"version":3,"file":"free-ports.js","sourceRoot":"","sources":["../../src/core/free-ports.ts"],"names":[],"mappings":"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"}

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

@@ -26,6 +26,8 @@ export declare class GenericContainer implements AsyncDisposable, NetworkMember
     private readonly image;
     private envPairs;
     private 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. */
+    private exposedUdpPorts;
     private command;
     private network;
     private aliasNames;
@@ -40,9 +42,20 @@ export declare class GenericContainer implements AsyncDisposable, NetworkMember
     private requireIsolationRequested;
     private checkpointRef;
     private 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()`.
+     */
+    private checkpointCapturedEnv;
     private handle;
     private backend;
     private mappedPorts;
+    /** UDP counterpart of `mappedPorts` — a SEPARATE per-protocol store, never a shared bare-int-keyed map (see `getMappedUdpPort`). */
+    private mappedUdpPorts;
     private running;
     private installedNetworkLinks;
     /** Builds against `image` (e.g. `"redis:8.6-alpine"`); no I/O happens until `start()`. */
@@ -61,15 +74,42 @@ export declare class GenericContainer implements AsyncDisposable, NetworkMember
      * 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.
      */
     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. */
     withEnv(key: string, value: string): 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: number[]): 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: number[]): this;
     /** Overrides the image's default ENTRYPOINT/CMD. Omit this call entirely to run the image unmodified. */
     withCommand(...cmd: string[]): this;
     /** Joins a `Network`, making this container reachable from (and to) its running siblings by alias. */
@@ -162,6 +202,7 @@ export declare class GenericContainer implements AsyncDisposable, NetworkMember
      */
     protected currentBackend(): SandboxBackend;
     private resolveBackend;
+    /** `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. */
     private buildSpec;
     /** The reuse-active counterpart of `buildSpec`: always `keepAlive: true`, named `rz-reuse-<hash12>` rather than the run-scoped `rz-<runId>-<seq>`, and never joined to a `Network` (rejected earlier in `start()`). */
     private buildReuseSpec;
@@ -177,6 +218,8 @@ export declare class GenericContainer implements AsyncDisposable, NetworkMember
     private computeReuseHash;
     private allocatePorts;
     private releasePorts;
+    /** 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`. */
+    private buildPortBindings;
     /**
      * Fails fast — before any backend call — on the combinations
      * `withDiskLimit`, `withTmpfsRoot`, and `withNetworkDisabled` make
@@ -269,8 +312,10 @@ export declare class GenericContainer implements AsyncDisposable, NetworkMember
     get host(): string;
     /** Names this container answers to on its network (set via `withNetworkAliases`). Part of the `NetworkMember` contract `Network` uses to compute links. */
     get aliases(): ReadonlyArray<string>;
-    /** 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(): ReadonlyArray<number>;
+    /** 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(): ReadonlyArray<number>;
     /**
      * The host port bound to `guestPort`. Throws distinct messages for the
      * two ways this can be wrong: not running at all ("call start() first"),
@@ -280,6 +325,18 @@ export declare class GenericContainer implements AsyncDisposable, NetworkMember
     getMappedPort(guestPort: number): number;
     /** Alias for `getMappedPort`, satisfying the `NetworkMember`/`WaitTarget` shape (which name this method `mappedPort`). */
     mappedPort(guestPort: number): number;
+    /**
+     * 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: number): number;
+    /** Alias for `getMappedUdpPort`, satisfying the `NetworkMember` shape (which names this method `mappedUdpPort`). */
+    mappedUdpPort(guestPort: number): number;
     private requireHandle;
     /**
      * Captures this running container's state and returns a `Checkpoint` — a
@@ -292,21 +349,48 @@ export declare class GenericContainer implements AsyncDisposable, NetworkMember
      * 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),
@@ -323,6 +407,11 @@ export declare class GenericContainer implements AsyncDisposable, NetworkMember
      * 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.