@lunora/container 1.0.0-alpha.7 → 1.0.0-alpha.71

package/dist/do/index.d.mts

@@ -1,5 +1,5 @@
-import { DurableObject, WorkerEntrypoint } from 'cloudflare:workers';
-import { a as ContainerDefinition } from "../packem_shared/types.d-BlNwNY44.mjs";
+import { d as ContainerRuntimeInstanceType, C as ContainerDefinition, D as DurableObjectJurisdiction, b as ContainerSnapshot, e as ContainerSpawnRequest } from "../packem_shared/jurisdiction.d-BwpauCoI.mjs";
+import { DurableObject, WorkerEntrypoint, RpcTarget } from 'cloudflare:workers';
 /**
  * ContainerStartOptions as they come from worker types
  */
@@ -119,7 +119,7 @@ type OutboundHandler<E = Cloudflare.Env, P = unknown> = {
 type OutboundHandlerParams = Record<string, unknown>;
 type OutboundHandlerParamsOf<THandler> = THandler extends ((req: Request, env: unknown, ctx: OutboundHandlerContext<infer Params>) => Promise<Response> | Response) ? Params : never;
 declare function outboundParams<THandler extends OutboundHandler<unknown, unknown>>(_handler: THandler, params: OutboundHandlerParamsOf<THandler>): OutboundHandlerParamsOf<THandler>;
-type OutboundHandlers<ParamsByMethod extends OutboundHandlerParams, E = Cloudflare.Env> = { [Method in keyof ParamsByMethod]?: OutboundHandler<E, ParamsByMethod[Method]> };
+type OutboundHandlers<ParamsByMethod extends OutboundHandlerParams, E = Cloudflare.Env> = { [Method in keyof ParamsByMethod]?: OutboundHandler<E, ParamsByMethod[Method]>; };
 type OutboundHandlerOverride<Params = unknown> = {
   method: string;
 } & ([Params] extends [undefined] ? {
@@ -345,7 +345,7 @@ declare class Container<Env = Cloudflare.Env> extends DurableObject<Env> {
    * When the counter transitions to 0, renew the activity timeout so the
    * inactivity window starts fresh from the moment the last request completes.
    */
-  private decrementInflight;
+  protected decrementInflight(): void;
   /**
    * Schedule a task to be executed in the future.
    *
@@ -387,10 +387,17 @@ declare class Container<Env = Cloudflare.Env> extends DurableObject<Env> {
   private onStopCalled;
   private state;
   private monitor;
-  private startInFlight;
+  protected startInFlight?: Promise<unknown>;
   private monitoredPromise;
   private sleepAfterMs;
-  private inflightRequests;
+  protected inflightRequests: number;
+  /** Patched (Lunora): the `durable_object`-policy image reference and size `start()` forwards. */
+  protected image?: string;
+  protected instance?: string | {
+    vcpu: number;
+    memoryMib: number;
+    diskMb: number;
+  };
   private outboundByHostOverrides;
   private outboundHandlerOverride?;
   private allowedHostsOverride?;
@@ -483,129 +490,384 @@ declare class Container<Env = Cloudflare.Env> extends DurableObject<Env> {
   getSchedule<T = string>(id: string): Promise<Schedule<T> | undefined>;
   private isActivityExpired;
 }
+/** The runtime's `ExecProcess`, structurally — only what a spawned process uses. */
+interface NativeProcess {
+  exitCode: Promise<number>;
+  isPty?: boolean;
+  kill: (signal?: number) => void;
+  pid?: number;
+  resize?: (cols: number, rows: number) => void;
+  stderr?: ReadableStream | null;
+  stdin?: WritableStream | null;
+  stdout?: ReadableStream | null;
+}
 /**
-* Cloudflare Durable Object data-residency jurisdiction. Widening union —
-* Cloudflare adds values over time.
-* @see https://developers.cloudflare.com/durable-objects/reference/data-location/
-*/
-type DurableObjectJurisdiction = "eu" | "fedramp" | "us";
-/**
-* Forward one lifecycle envelope to the root ShardDO's log buffer, best-effort.
-*
-* `env` is the Container DO's worker `env`: we read the `SHARD` namespace and
-* the `LUNORA_ADMIN_TOKEN` from it. Returns a promise that NEVER rejects — every
-* failure path (missing binding, missing token, fetch error) resolves to
-* `undefined` — so the caller can `void` it from a lifecycle hook safely.
-*/
+ * Control half of a spawned process, returned to the caller as an RPC stub.
+ * The streams travel next to it in {@link SpawnedProcess}: a stream can cross
+ * RPC only once, so it is handed over directly rather than exposed through a
+ * property that could be read twice.
+ */
+declare class ContainerProcessControl extends RpcTarget {
+  #private;
+  constructor(process: NativeProcess, exit: Promise<number>);
+  /** Resolves with the exit code once the process ends. */
+  exitCode(): Promise<number>;
+  /** Send `signal` (default `SIGTERM`) to the process. A no-op once it has exited. */
+  kill(signal?: number): void;
+  /** Resize a PTY process's terminal. Throws for a process spawned without `pty`. */
+  resize(cols: number, rows: number): void;
+}
+/** What `lunoraSpawn` returns over RPC. */
+interface SpawnedProcess {
+  control: ContainerProcessControl;
+  isPty: boolean;
+  pid: number;
+  /** `null` under `pty`, where stderr is merged into the terminal output. */
+  stderr: ReadableStream<Uint8Array> | null;
+  /** A writable stdin when the request asked for `stdin: true`, else `null`. */
+  stdin: WritableStream<Uint8Array> | null;
+  stdout: ReadableStream<Uint8Array> | null;
+}
+/** What an explicit `start()` chose that later restarts must reuse. */
+interface StartOverride {
+  /** Replaces the declared env, `secrets` and `secretsStore` wholesale. */
+  envVars?: Record<string, string>;
+  /** A key of the definition's `images`, or a managed `cloudflare/…` image. */
+  image?: string;
+  instanceType?: ContainerRuntimeInstanceType;
+}
 type DurableObjectContext = ConstructorParameters<typeof Container>[0];
+/** The runtime's `ctx.container`, once known to be present. */
+type ContainerRuntime = NonNullable<DurableObjectContext["container"]>;
+/** A running container plus the release for the in-flight count taken on it. See `LunoraContainer.lunoraAcquire`. */
+interface AcquiredContainer {
+  container: ContainerRuntime;
+  /** Drop the in-flight count. Idempotent. */
+  release: () => void;
+}
+/**
+ * The `start()` options `LunoraContainer` accepts on top of the base's: the
+ * `durable_object`-policy image, size and snapshot to restore.
+ */
+type LunoraStartOptions = NonNullable<Parameters<Container["start"]>[0]> & Pick<StartOverride, "image" | "instanceType"> & {
+  snapshot?: ContainerSnapshot;
+};
 /**
-* Base class for the generated Container DO classes. Applies a
-* `defineContainer` definition onto `@cloudflare/containers`' `Container`:
-* port, sleep timeout, internet access, and the container environment (static
-* `env` merged with the declared Worker secrets — a declared-but-unset secret
-* fails fast here rather than starting a container without its credential).
-*
-* Generated subclasses stay one line of behavior:
-*
-* ```ts
-* export class TranscoderContainer extends LunoraContainer {
-*     constructor(ctx: DurableObjectState, env: Env) {
-*         super(ctx, env, transcoder, "transcoder");
-*     }
-* }
-* ```
-*/
+ * Base class for the generated Container DO classes. Applies a
+ * `defineContainer` definition onto `@cloudflare/containers`' `Container`:
+ * port, sleep timeout, internet access, and the container environment (static
+ * `env` merged with the declared Worker secrets — a declared-but-unset secret
+ * fails fast here rather than starting a container without its credential).
+ *
+ * Generated subclasses stay one line of behavior:
+ *
+ * ```ts
+ * export class TranscoderContainer extends LunoraContainer {
+ *     constructor(ctx: DurableObjectState, env: Env) {
+ *         super(ctx, env, transcoder, "transcoder");
+ *     }
+ * }
+ * ```
+ */
 declare class LunoraContainer<Env = unknown> extends Container<Env> {
+  /** The `lunora/containers.ts` export name, for lifecycle log correlation and error messages. */
+  protected readonly lunoraName: string;
   /**
-  * Data-residency jurisdiction the app's DOs are pinned to (codegen passes the
-  * schema's `.jurisdiction("…")`). Used to pin the best-effort lifecycle report
-  * to the same region as the root shard. `undefined` ⇒ un-pinned.
-  */
+   * Data-residency jurisdiction the app's DOs are pinned to (codegen passes the
+   * schema's `.jurisdiction("…")`). Used to pin the best-effort lifecycle report
+   * to the same region as the root shard. `undefined` ⇒ un-pinned.
+   */
   private readonly lunoraJurisdiction?;
-  /** The `lunora/containers.ts` export name, for lifecycle log correlation. */
-  private readonly lunoraName;
   /** Default port the readiness probes target when a check omits its own `port`. */
   private readonly lunoraDefaultPort?;
   /** Hard-cap lifetime in whole seconds (from the `hardTimeout` config), or `undefined`. */
   private readonly lunoraHardTimeoutSeconds?;
+  /** In-flight `readyOn` gate for the current start; cleared when it fails. See `awaitReadinessGate`. */
+  private lunoraReadiness?;
   /** Declarative readiness probes that gate request proxying (from the `readyOn` config). */
   private readonly lunoraReadyOn;
   /** Map of container env-var name → Worker Secrets Store binding name (from the `secretsStore` config). */
   private readonly lunoraSecretsStore?;
-  /** Memoised Secrets Store resolution: run once, then merged into `envVars` before the first start. */
+  /** The definition's `env` + `secrets`, as resolved at construction — the env a start uses absent an override. */
+  private readonly lunoraDeclaredEnv;
+  /** The persisted start override, once loaded. See {@link START_OVERRIDE_KEY}. */
+  private lunoraOverride?;
+  /** Whether the override field reflects storage (read once per DO instance, then kept in step). */
+  private lunoraOverrideLoaded;
+  /** Memoised Secrets Store resolution: the resolved `name → value` map, fetched once. */
   private lunoraSecretsStoreResolved?;
+  /** Whether the definition uses the `durable_object` scheduling policy. */
+  private readonly lunoraDurableObjectScheduled;
+  /** The definition's default image name and instance size (`durable_object` policy only). */
+  private readonly lunoraDefaultSelection;
+  /**
+   * Count of runs observed to have ENDED, bumped by the `onStop` hook. Read
+   * across a start: a bump means the run that start snapshotted is over,
+   * whatever the `running` flag said at snapshot time. See `beginStart`.
+   */
+  private lunoraStops;
   constructor(context: DurableObjectContext, env: Env, definition: ContainerDefinition, exportName?: string, jurisdiction?: DurableObjectJurisdiction);
   /**
-  * Proxy entry for every `ctx.containers.&lt;name>` fetch. Resolves the
-  * `secretsStore` bindings into `envVars` before delegating, so the values
-  * are present when the base implicitly starts the container for this
-  * request — a no-op when `secretsStore` is unset.
-  */
+   * Save the running container's filesystem (`durable_object` policy only).
+   * The handle is plain data: store it and pass it to `start({ snapshot })` to
+   * restore it here or in another instance. Memory and processes are not
+   * captured — a restored container runs its entrypoint again.
+   */
+  lunoraSnapshot(options?: {
+    name?: string;
+  }): Promise<ContainerSnapshot>;
+  /**
+   * HTTP entry for every request to this Durable Object. Refuses the reserved
+   * `/__lunora/*` namespace unconditionally: `exec` reaches it only through
+   * the {@link lunoraExec} RPC, so no header, path spelling, or inbound request
+   * an app forwards as-is (`env.CONTAINER_X.get(id).fetch(request)`) opens it.
+   * The client-side path guard is the first line; this is the second.
+   */
+  override fetch(request: Request): Promise<Response>;
+  /**
+   * Proxy entry for every `ctx.containers.<name>` fetch — and a public RPC on
+   * the stub in its own right, so it applies the same `/__lunora/*` refusal
+   * as {@link fetch} rather than trusting that every caller came through it.
+   * The base starts the container for this request through
+   * {@link startAndWaitForPorts}, which is where the `secretsStore` resolution
+   * lives — a request that finds the container already healthy needs no
+   * resolution at all.
+   */
   override containerFetch(...args: Parameters<Container<Env>["containerFetch"]>): Promise<Response>;
   /**
-  * Explicit start (`ctx.containers.&lt;name>.get(id).start()`). Resolves the
-  * `secretsStore` bindings into `envVars` first, mirroring
-  * {@link containerFetch}. A per-instance `start({ envVars })` replaces the
-  * env set wholesale (base behavior), so the injected values only apply to a
-  * bare `start()` — same as the static `env`/`secrets`. When the caller
-  * supplies its own `envVars` we skip resolution entirely: those values would
-  * be discarded anyway, so a missing/unreadable binding shouldn't fail a start
-  * that never uses them.
-  */
-  override start(...args: Parameters<Container<Env>["start"]>): Promise<void>;
+   * The exec entry: `handle.exec` delivers its `POST /__lunora/exec` here, as
+   * an RPC, never over {@link fetch}. An RPC can only be invoked by code that
+   * holds the Durable Object binding, which is what makes the exec route
+   * unreachable from request content. Accepts exactly the exec route and
+   * nothing else under the reserved namespace, and honours a `.port(n)`
+   * handle's target-port header the way the base `fetch` does.
+   */
+  lunoraExec(request: Request): Promise<Response>;
+  /**
+   * Start a process and stream it (`handle.spawn()`), through the runtime's
+   * native `ctx.container.exec()`. Starts the container first when it is not
+   * running, and counts the process in flight until it exits, so `sleepAfter`
+   * cannot stop the container under it. The process's streams and a control
+   * stub (`exitCode` / `kill` / `resize`) cross back over RPC.
+   */
+  lunoraSpawn(request: ContainerSpawnRequest): Promise<SpawnedProcess>;
+  /**
+   * The start path `containerFetch` takes (and the one an app can call itself).
+   * Resolves the `secretsStore` bindings into `envVars` first — `doStartContainer`
+   * reads `this.envVars`, so a container started this way would otherwise boot
+   * without its Secrets Store values.
+   *
+   * The base's last act is `blockConcurrencyWhile(… onStart())`, so this
+   * override resumes on the far side of that gate — which is where
+   * {@link afterContainerStart} has to run. See its docblock.
+   */
+  override startAndWaitForPorts(...args: Parameters<Container<Env>["startAndWaitForPorts"]>): Promise<void>;
+  /**
+   * Explicit start (`ctx.containers.<name>.get(id).start()`).
+   *
+   * A per-instance `start({ envVars })` REPLACES the declared env (`env`,
+   * `secrets`, `secretsStore` — the Secrets Store is not even read) and is
+   * PERSISTED: every later start of this instance, explicit or implicit (a
+   * `fetch`/`exec` after the container slept, crashed or hit `hardTimeout`),
+   * boots with the same variables until `destroy()`. That is what makes
+   * `start({ envVars: {} })` a credential-free sandbox rather than one that
+   * gets its credentials back on the next restart.
+   *
+   * A start with `envVars` that differ from what the instance is running (or
+   * starting) with is REJECTED rather than silently joined: the base would
+   * return early on a live container, reporting a start whose env never took
+   * effect. `stop()` it first, or `destroy()` it to drop the override.
+   */
+  override start(options?: LunoraStartOptions, waitOptions?: Parameters<Container<Env>["start"]>[1]): Promise<void>;
+  /**
+   * Stop the container and forget this instance's start override, so the next
+   * start uses the declared env, image and size again.
+   */
+  override destroy(): Promise<void>;
   override onActivityExpired(): Promise<void>;
   override onError(error: unknown): unknown;
   override onStart(): Promise<void>;
   /**
-  * Hook run when the container's `hardTimeout` elapses (dispatched by the base
-  * scheduler via the run-generation-stamped schedule armed in
-  * {@link onStart}). Default: stop the instance. Override to drain/checkpoint
-  * first. A stale schedule from a previous run, or an already-stopped
-  * instance, is ignored (upstream cloudflare/containers#85).
-  */
+   * Hook run when the container's `hardTimeout` elapses (dispatched by the base
+   * scheduler via the run-generation-stamped schedule armed in
+   * {@link onStart}). Default: stop the instance. Override to drain/checkpoint
+   * first. A stale schedule from a previous run, or an already-stopped
+   * instance, is ignored (upstream cloudflare/containers#85).
+   *
+   * `stop()` sends SIGTERM and returns; nothing escalates to `destroy()`. The
+   * cap is therefore a signal, not a bound — a container that traps or ignores
+   * SIGTERM keeps running, and the schedule is ONE-SHOT (the base deletes the
+   * row once it fires), so nothing signals it a second time either: an ignored
+   * SIGTERM means the cap is spent, not retried. Override this hook and follow
+   * the stop with a `destroy()` after a grace period if your workload needs a
+   * real ceiling.
+   */
   onHardTimeoutExpired(payload?: {
     generation?: number;
   }): Promise<void>;
   override onStop(parameters: StopParams): Promise<void>;
   /**
-  * Arm the hard-timeout kill via the base scheduler (so it integrates with
-  * the container's own alarm machinery instead of fighting it). Bumps the run
-  * generation and stamps the schedule with it, so {@link onHardTimeoutExpired}
-  * can tell a fresh schedule from a stale one. No-op without a `hardTimeout`.
-  */
+   * Get the container running for an operation that talks to it through
+   * `ctx.container` rather than over HTTP (`spawn`, and the sandbox helpers),
+   * and count the operation in flight so `sleepAfter` cannot stop the
+   * container underneath it. Goes through the same readiness gate a proxied
+   * request does, and through {@link start} when the container is stopped —
+   * `start()` returns once the container runs, so a container that serves no
+   * port starts here too. The caller must call `release` when the operation
+   * ends, including when the result is a stream that outlives this call.
+   */
+  protected lunoraAcquire(operation: string): Promise<AcquiredContainer>;
+  /**
+   * Runs on every start path after the env and image are settled and before
+   * the base starts the container — which is also before the base installs
+   * its outbound interception. A subclass that has to register an outbound
+   * intercept ahead of the base's catch-all does it here. No-op by default.
+   */
+  protected beforeContainerStart(): Promise<void>;
+  /** A 403 for a path under the reserved namespace, else `undefined`. */
+  private refuseReserved;
+  /**
+   * Arm the hard timeout and block on the `readyOn` probes — the work that has
+   * to happen once per real start, **outside** the base's start gate.
+   *
+   * It cannot live in `onStart`, which is the obvious home for it: the base
+   * invokes that hook as `blockConcurrencyWhile(async () => { … onStart() })`
+   * (`@cloudflare/containers`, both `start()` and `startAndWaitForPorts()`),
+   * and workerd treats a *rejecting* `blockConcurrencyWhile` closure as
+   * unrecoverable — it aborts the Durable Object, discards its in-memory state
+   * and every hibernating socket on it, and flattens the error to a plain
+   * `Error`. A readiness timeout is an ordinary, diagnosable failure: it must
+   * surface as the `LunoraError` naming the check, the port and the budget,
+   * not cost the object its life and arrive as an opaque message. (The same
+   * reasoning, and the same settle-outside-the-gate remedy, is written up on
+   * `ShardHost.runSerialized` in `@lunora/platform-cloudflare`.) A 30-second
+   * wait also has no business inside a gate that blocks every other dispatch
+   * to the object.
+   *
+   * Both start entry points call this immediately after `super`, so it runs
+   * once per start. It does NOT gate proxying on its own: the base commits the
+   * healthy state inside the start gate, before this runs, so a concurrent
+   * request would sail past `containerFetch`'s status check. That is what
+   * `awaitReadinessGate` is for, and it is the seam the move cost us —
+   * the in-gate placement got this for free from `blockConcurrencyWhile`.
+   */
+  private afterContainerStart;
+  /**
+   * Decide — synchronously, before anything is started — whether this start
+   * begins a NEW container run, and drop the previous run's readiness gate when
+   * it does. Returns whether the container was already running.
+   *
+   * The gate has to be keyed on the run, and `onStop` alone cannot key it:
+   * `@cloudflare/containers` reaches `onStop` only through
+   * `syncPendingStoppedEvents`, which `start()` never calls (only
+   * `startAndWaitForPorts`, `stop()` and the alarm loop do), while the monitor
+   * callback that observes a container exit merely records the state. So a
+   * `start()` in the up-to-three-minute window before the next alarm found the
+   * finished run's settled gate and skipped BOTH `armHardTimeout` and the
+   * `readyOn` probes — run 2 ran uncapped and was proxied to before it reported
+   * ready. A `hardTimeout` firing its own SIGTERM lands in exactly that window.
+   *
+   * The mirror case is why the answer is not "always re-arm": a start that finds
+   * the container already up begins no run, and re-arming there moves the cap
+   * (see {@link afterContainerStart}).
+   *
+   * Read with no `await` between it and `super`, so two concurrent starts of a
+   * stopped container both observe `false` and the second joins the first's
+   * gate instead of arming a second schedule — and so the flag is as fresh as
+   * it can be. It is a snapshot either way, and the run can end after it: the
+   * base's own pre-start work (`getPortsToCheck`, `syncPendingStoppedEvents`)
+   * still runs on the far side of it, and a start that came in on a live
+   * container would then arm nothing for the run the base goes on to start.
+   * Hence the second half of the answer, in the callers: an `onStop` observed
+   * ACROSS the base call ({@link lunoraStops}) demotes the snapshot, because
+   * the run it described is over. What that does not cover is an exit inside
+   * `start()`'s own base call — that path never syncs pending stop events, so
+   * nothing reports the exit until the next alarm or `startAndWaitForPorts`,
+   * and the cap for such a run is armed only when one of those arrives.
+   */
+  private beginStart;
+  /**
+   * Block until the `readyOn` probes for the current start have passed.
+   *
+   * Necessary because the base marks the container healthy *inside* the start
+   * gate — `startAndWaitForPorts` runs `setHealthy()` immediately before
+   * `onStart()` — while our probes run after it returns. `containerFetch`
+   * skips the start path entirely once it observes
+   * `container.running && status === "healthy"`, so without this a request
+   * arriving mid-probe would proxy to a container that never reported ready,
+   * and a request arriving after a *failed* probe would do so permanently.
+   * Holding `setHealthy` and the probes together the way the base does would
+   * mean putting the probes back inside the gate, which is the defect this
+   * whole path exists to avoid.
+   */
+  private awaitReadinessGate;
+  /**
+   * Arm the hard-timeout kill via the base scheduler (so it integrates with
+   * the container's own alarm machinery instead of fighting it). Bumps the run
+   * generation and stamps the schedule with it, so {@link onHardTimeoutExpired}
+   * can tell a fresh schedule from a stale one. No-op without a `hardTimeout`.
+   */
   private armHardTimeout;
   /**
-  * Resolve the `secretsStore` bindings (async `.get()`) once and merge the
-  * values into `envVars`, so they're present when the base starts the
-  * container. Memoised on the first call — every later start reuses the
-  * resolved promise. A missing binding or a non-string value fails fast (the
-  * start surfaces the error), the same fail-closed stance the static
-  * `secrets` resolution takes for a missing Worker secret. No-op without
-  * `secretsStore`.
-  */
+   * Resolve the `secretsStore` bindings (async `.get()`) once and merge the
+   * values into `envVars`, so they're present when the base starts the
+   * container. Memoised on the first call — every later start reuses the
+   * resolved promise. A missing binding or a non-string value fails fast (the
+   * start surfaces the error), the same fail-closed stance the static
+   * `secrets` resolution takes for a missing Worker secret. No-op without
+   * `secretsStore`.
+   */
   private resolveSecretsStoreEnv;
+  /** The persisted start override, read from storage once per instance lifetime. */
+  private readOverride;
+  /**
+   * Validate an explicit start's choices and persist them — merged over the
+   * stored override, so `start({ instanceType })` alone keeps a chosen image.
+   * Everything is checked before the one write, so a rejected start stores
+   * nothing. A start whose choices differ from what a running (or starting)
+   * container has is REJECTED rather than silently joined: the base would
+   * return early on a live container, reporting a start that never took
+   * effect. A snapshot restore only applies to a fresh start, so it is refused
+   * on a busy one.
+   */
+  private recordStartOverride;
+  /**
+   * Set `envVars` for the start about to happen: the persisted override when
+   * there is one (the Secrets Store is not read), else the declared env plus
+   * the resolved Secrets Store values.
+   */
+  private applyStartEnv;
   /**
-  * Block until every `readyOn` probe responds with its expected status, or
-  * throw once the readiness budget is spent. Probes run in parallel and hit
-  * the container's TCP port directly (NOT `containerFetch`, which would
-  * recurse back into the start path). No-op without `readyOn`.
-  */
+   * Resolve the image reference and instance size for the start about to
+   * happen (`durable_object` policy only): the persisted explicit choice, else
+   * the definition default. A fresh boot with neither an image nor a snapshot
+   * would be rejected by the runtime, so it fails here with the fix instead.
+   */
+  private applyStartSelection;
+  /** Map an image name to the reference `ctx.container.start()` takes, via `ctx.container.images`. */
+  private resolveImage;
+  /**
+   * Block until every `readyOn` probe responds with its expected status, or
+   * throw once the readiness budget is spent. Probes run in parallel and hit
+   * the container's TCP port directly (NOT `containerFetch`, which would
+   * recurse back into the start path). No-op without `readyOn`.
+   */
   private awaitContainerReadiness;
   /** Poll one readiness probe until it returns its expected status or the shared deadline passes. */
   private awaitReadinessCheck;
   /**
-  * Best-effort push of `envelope` into the root ShardDO's log buffer so it
-  * also appears in the Studio Logs panel (the terminal already has it via
-  * `emitContainerLifecycle`). Fire-and-forget and fully swallowed: a missing
-  * `SHARD` binding, a missing admin token, or a fetch failure NEVER throws
-  * out of a lifecycle hook — the `console` path stays the source of truth.
-  */
+   * Best-effort push of `envelope` into the root ShardDO's log buffer so it
+   * also appears in the Studio Logs panel (the terminal already has it via
+   * `emitContainerLifecycle`). Fire-and-forget and fully swallowed: a missing
+   * `SHARD` binding, a missing admin token, or a fetch failure NEVER throws
+   * out of a lifecycle hook — the `console` path stays the source of truth.
+   */
   private surfaceInStudioLogs;
   /**
-  * Per-instance correlation id: the Durable Object id, which Cloudflare also
-  * injects into the container as `CLOUDFLARE_DURABLE_OBJECT_ID`. Read
-  * defensively — the id shape varies and isn't worth crashing a hook over.
-  */
+   * Per-instance correlation id: the Durable Object id, which Cloudflare also
+   * injects into the container as `CLOUDFLARE_DURABLE_OBJECT_ID`. Read
+   * defensively — the id shape varies and isn't worth crashing a hook over.
+   */
   private instanceId;
 }
 export { ContainerProxy, LunoraContainer, type OutboundHandler, type OutboundHandlerContext, type OutboundHandlerParams, type OutboundHandlerParamsOf, type OutboundHandlers, outboundParams };