@lunora/container 1.0.0-alpha.31 → 1.0.0-alpha.32

package/dist/bridge.d.mts

@@ -1,7 +1,6 @@
 import { LunoraError } from '@lunora/errors';
 /**
  * A `fetch` implementation — defaults to the runtime global.
- * @experimental
  */
 type FetchLike = (input: string, init: {
   body: string;
@@ -15,7 +14,6 @@ type FetchLike = (input: string, init: {
 }>;
 /**
  * `ContainerBridgeOptions` is part of the experimental `@lunora/container` API and may change without a major version bump.
- * @experimental
  */
 interface ContainerBridgeOptions {
   /**
@@ -35,7 +33,6 @@ interface ContainerBridgeOptions {
 }
 /**
  * Thrown when a Lunora function returns an error envelope. A `LunoraError` subclass carrying the wire `code`.
- * @experimental
  */
 declare class ContainerBridgeError extends LunoraError {
   constructor(code: string, message: string);
@@ -46,7 +43,6 @@ declare class ContainerBridgeError extends LunoraError {
  * imported) so the bridge stays dependency-free and its `.d.ts` is
  * self-contained; the `__lunoraPhantom` shape matches, so a real `api.x.y`
  * reference is assignable and its arg/return types are inferable.
- * @experimental
  */
 interface BridgeFunctionReference<Args = unknown, Result = unknown> {
   readonly __lunoraPhantom?: {
@@ -69,7 +65,6 @@ type ResultOfReference<Reference> = Reference extends {
 } ? Result : never;
 /**
  * `ContainerBridge` is part of the experimental `@lunora/container` API and may change without a major version bump.
- * @experimental
  */
 interface ContainerBridge {
   /** Call an `action` by `namespace:fn` path. Alias of {@link ContainerBridge.call} for intent. */
@@ -100,7 +95,6 @@ interface ContainerBridge {
  * `query`/`mutation`/`action` are intent-revealing aliases of one `call` — the
  * wire is identical and the server dispatches by the function's registered
  * kind, so a query path called via `.mutation(...)` still runs as a query.
- * @experimental
  */
 declare const createContainerBridge: (options: ContainerBridgeOptions) => ContainerBridge;
 export { type BridgeFunctionReference, type ContainerBridge, ContainerBridgeError, type ContainerBridgeOptions, type FetchLike, createContainerBridge };

package/dist/bridge.d.ts

@@ -1,7 +1,6 @@
 import { LunoraError } from '@lunora/errors';
 /**
  * A `fetch` implementation — defaults to the runtime global.
- * @experimental
  */
 type FetchLike = (input: string, init: {
   body: string;
@@ -15,7 +14,6 @@ type FetchLike = (input: string, init: {
 }>;
 /**
  * `ContainerBridgeOptions` is part of the experimental `@lunora/container` API and may change without a major version bump.
- * @experimental
  */
 interface ContainerBridgeOptions {
   /**
@@ -35,7 +33,6 @@ interface ContainerBridgeOptions {
 }
 /**
  * Thrown when a Lunora function returns an error envelope. A `LunoraError` subclass carrying the wire `code`.
- * @experimental
  */
 declare class ContainerBridgeError extends LunoraError {
   constructor(code: string, message: string);
@@ -46,7 +43,6 @@ declare class ContainerBridgeError extends LunoraError {
  * imported) so the bridge stays dependency-free and its `.d.ts` is
  * self-contained; the `__lunoraPhantom` shape matches, so a real `api.x.y`
  * reference is assignable and its arg/return types are inferable.
- * @experimental
  */
 interface BridgeFunctionReference<Args = unknown, Result = unknown> {
   readonly __lunoraPhantom?: {
@@ -69,7 +65,6 @@ type ResultOfReference<Reference> = Reference extends {
 } ? Result : never;
 /**
  * `ContainerBridge` is part of the experimental `@lunora/container` API and may change without a major version bump.
- * @experimental
  */
 interface ContainerBridge {
   /** Call an `action` by `namespace:fn` path. Alias of {@link ContainerBridge.call} for intent. */
@@ -100,7 +95,6 @@ interface ContainerBridge {
  * `query`/`mutation`/`action` are intent-revealing aliases of one `call` — the
  * wire is identical and the server dispatches by the function's registered
  * kind, so a query path called via `.mutation(...)` still runs as a query.
- * @experimental
  */
 declare const createContainerBridge: (options: ContainerBridgeOptions) => ContainerBridge;
 export { type BridgeFunctionReference, type ContainerBridge, ContainerBridgeError, type ContainerBridgeOptions, type FetchLike, createContainerBridge };

package/dist/do/index.d.mts

@@ -1,4 +1,4 @@
-import { a as ContainerDefinition, D as DurableObjectJurisdiction } from "../packem_shared/jurisdiction.d-DeQ3rtYK.mjs";
+import { C as ContainerDefinition, D as DurableObjectJurisdiction } from "../packem_shared/jurisdiction.d-KcQu2ZT_.mjs";
 import { DurableObject, WorkerEntrypoint } from 'cloudflare:workers';
 /**
  * ContainerStartOptions as they come from worker types
@@ -500,7 +500,6 @@ type DurableObjectContext = ConstructorParameters<typeof Container>[0];
  *     }
  * }
  * ```
- * @experimental
  */
 declare class LunoraContainer<Env = unknown> extends Container<Env> {
   /**

package/dist/do/index.d.ts

@@ -1,4 +1,4 @@
-import { a as ContainerDefinition, D as DurableObjectJurisdiction } from "../packem_shared/jurisdiction.d-DeQ3rtYK.js";
+import { C as ContainerDefinition, D as DurableObjectJurisdiction } from "../packem_shared/jurisdiction.d-KcQu2ZT_.js";
 import { DurableObject, WorkerEntrypoint } from 'cloudflare:workers';
 /**
  * ContainerStartOptions as they come from worker types
@@ -500,7 +500,6 @@ type DurableObjectContext = ConstructorParameters<typeof Container>[0];
  *     }
  * }
  * ```
- * @experimental
  */
 declare class LunoraContainer<Env = unknown> extends Container<Env> {
   /**

package/dist/index.d.mts

@@ -1,8 +1,74 @@
-import { D as DurableObjectJurisdiction, C as ContainerConfig, a as ContainerDefinition, b as ContainerImageSource, N as NormalizedContainerImage } from "./packem_shared/jurisdiction.d-DeQ3rtYK.mjs";
-export type { B as BuildImageSource, c as ContainerInstanceType, d as ContainerReadinessCheck, e as ContainerRollout, f as CustomContainerInstanceType, g as NamedContainerInstanceType, R as RegistryImageSource } from "./packem_shared/jurisdiction.d-DeQ3rtYK.mjs";
+import { D as DurableObjectJurisdiction, a as ContainerConfig, C as ContainerDefinition, b as ContainerImageSource, N as NormalizedContainerImage } from "./packem_shared/jurisdiction.d-KcQu2ZT_.mjs";
+export type { B as BuildImageSource, c as ContainerInstanceType, d as ContainerReadinessCheck, e as ContainerRollout, f as CustomContainerInstanceType, g as NamedContainerInstanceType, R as RegistryImageSource } from "./packem_shared/jurisdiction.d-KcQu2ZT_.mjs";
+/**
+ * Per-call options for `ContainerHandle.exec`.
+ */
+interface ContainerExecOptions {
+  /** Arguments passed to `command`, unshelled — the container must not concatenate them into a shell string. */
+  args?: ReadonlyArray<string>;
+  /** Working directory for the command, relative to the container's own root. */
+  cwd?: string;
+  /** Extra environment for this command only, merged over the container's env. */
+  env?: Readonly<Record<string, string>>;
+  /**
+   * Cap on the response body, in bytes. The whole `{code,stdout,stderr}`
+   * document has to be held in memory to be parsed, and a build box or job
+   * runner routinely writes tens of megabytes — a single unbounded `exec`
+   * that returns more than the isolate's memory limit kills the isolate and
+   * every other in-flight request sharing it, not just this call. So a
+   * runner that overruns the cap fails the call loudly rather than taking
+   * the shard down with it; raise this (or have the runner cap its own
+   * output) when a command legitimately produces more.
+   *
+   * Default {@link DEFAULT_EXEC_MAX_OUTPUT_BYTES} (1MB).
+   */
+  maxOutputBytes?: number;
+  /**
+   * Abort the call. Composed with {@link ContainerExecOptions.timeoutMs} when
+   * both are given — whichever fires first wins.
+   */
+  signal?: AbortSignal;
+  /**
+   * Give up after this many ms. Covers the whole call — the request *and*
+   * reading the response body, since `fetch` resolves on headers and a
+   * runner that answers `200` and then stalls mid-body would otherwise sit
+   * past the deadline. Sent to the container as well, so a well-behaved
+   * runner can kill the process rather than leak it when the caller walks
+   * away.
+   */
+  timeoutMs?: number;
+}
+/**
+ * The outcome of a `ContainerHandle.exec` call.
+ *
+ * A non-zero `code` is **not** an error: a command that ran and failed is a
+ * result, and the caller decides what to do with it. Only a failure to *run*
+ * the command — transport, a non-2xx from the runner, an unparseable body —
+ * throws.
+ */
+interface ContainerExecResult {
+  /** Process exit code. Non-zero means the command ran and failed. */
+  code: number;
+  /** Everything the command wrote to stderr. */
+  stderr: string;
+  /** Everything the command wrote to stdout. */
+  stdout: string;
+}
+/**
+ * The route `ContainerHandle.exec` POSTs to. Namespaced under
+ * `/__lunora/` so it cannot collide with an application route the container
+ * already serves — the previous ad-hoc convention was a bare `/exec`, which an
+ * app could plausibly own for its own purposes.
+ *
+ * Exported because it is a *contract*, not an implementation detail: a
+ * container image has to serve exactly this route, and `@lunora/agent`'s
+ * human-in-the-loop gate has to recognise it. Both had it hard-coded as a
+ * second literal, which drifts silently — and on the gate's side, drift
+ * un-gates model-chosen command execution.
+ */
+declare const CONTAINER_EXEC_PATH = "/__lunora/exec";
 /**
  * Options for explicitly starting an instance (mirrors `@cloudflare/containers`).
- * @experimental
  */
 interface ContainerStartOptions {
   /** Override outbound internet access for this start. */
@@ -16,7 +82,6 @@ interface ContainerStartOptions {
 }
 /**
  * A container instance's runtime state, as returned by `getState()`. Structural — the platform adds fields over time.
- * @experimental
  */
 interface ContainerInstanceState {
   [key: string]: unknown;
@@ -44,7 +109,6 @@ interface ContainerStubLike {
 }
 /**
  * What the client needs from a Durable Object namespace binding.
- * @experimental
  */
 interface ContainerNamespaceLike {
   get: (id: unknown) => ContainerStubLike;
@@ -57,9 +121,24 @@ interface ContainerNamespaceLike {
 }
 /**
  * A handle on one container instance (one Durable Object).
- * @experimental
  */
 interface ContainerHandle {
+  /**
+   * Run a command inside the container and return its exit code and output.
+   *
+   * A container is an HTTP server, so there is no platform-level exec to call:
+   * the command is POSTed to `/__lunora/exec` and the container app
+   * serves that route. What this method adds over hand-rolling that fetch is
+   * the **contract** — a pinned path, a typed request and response, and the
+   * distinction between "the command failed" (a `code`) and "the command could
+   * not be run" (a throw). Before it existed every caller invented its own
+   * `/exec` convention and read the raw body back as if it were output, which
+   * silently turned a runner's 500 into a successful-looking result.
+   *
+   * The container side must accept `{ args, command, cwd, env, timeoutMs }`
+   * and answer `{ code, stdout, stderr }` as JSON.
+   */
+  exec: (command: string, options?: ContainerExecOptions) => Promise<ContainerExecResult>;
   /**
    * Send an HTTP (or WebSocket-upgrade) request to the container. A path
    * string (`"/transcode"`) is resolved against a synthetic origin; a full
@@ -82,7 +161,6 @@ interface ContainerHandle {
  * game, a job runner per id) often needs to tear down or inspect the instance
  * rather than wait for `sleepAfter`, so these wrap the container DO's
  * `start`/`stop`/`destroy`/`getState`.
- * @experimental
  */
 interface ContainerInstanceHandle extends ContainerHandle {
   /** Stop and discard the instance (its ephemeral disk is lost). */
@@ -117,7 +195,6 @@ interface ContainerInstanceHandle extends ContainerHandle {
  * Each maps to the corresponding `@cloudflare/containers` `Container` RPC, so
  * an app can tighten or relax a single instance's allowed/denied hosts after
  * start without redeploying.
- * @experimental
  */
 interface ContainerEgressControls {
   /** Add one hostname (or glob) to the allow-list. */
@@ -135,7 +212,6 @@ interface ContainerEgressControls {
 }
 /**
  * The per-definition accessor exposed as `ctx.containers.<exportName>`.
- * @experimental
  */
 interface ContainerAccessor {
   /**
@@ -178,7 +254,6 @@ interface ContainerAccessor {
 }
 /**
  * Tuning for a pooled, retrying container handle. See {@link ContainerAccessor.pool}.
- * @experimental
  */
 interface PoolOptions {
   /** Total attempts before giving up (each on a freshly-picked instance). Default 3. */
@@ -195,6 +270,10 @@ interface PoolOptions {
    * Whether a *returned* response should be retried on another instance.
    * Defaults to retrying any `5xx`. A thrown error (network/start failure) is
    * always retried regardless of this predicate.
+   *
+   * Applies to `fetch` only. `exec` retries on the cold-start transients
+   * alone, because its caller never chose the request and a command that
+   * already ran must not be re-run just because the runner failed afterwards.
    */
   retryOn?: (response: Response) => boolean;
   /** Pool size to spread picks across. Defaults to the definition's `maxInstances`, else 3. */
@@ -205,7 +284,6 @@ interface PoolOptions {
  * only on the platform's provisioning transients (no-instance / not-listening /
  * rate-limited — see {@link isColdStartTransient}), which is why it's safe by
  * default: those responses mean the request never reached the container.
- * @experimental
  */
 interface InstanceRetryOptions {
   /**
@@ -221,7 +299,6 @@ interface InstanceRetryOptions {
 }
 /**
  * Wiring info for one definition, emitted by codegen into the generated DO.
- * @experimental
  */
 interface ContainerBindingSpec {
   /** Durable Object binding name, e.g. `CONTAINER_TRANSCODER`. */
@@ -240,12 +317,10 @@ interface ContainerBindingSpec {
  * `traceparent` (the inbound RPC's W3C trace context, forwarded by the runtime
  * and read off the request by the DO) is stamped onto every outbound container
  * `fetch`, so the container's own spans stitch under the Worker's trace.
- * @experimental
  */
 declare const createContainerContext: (env: Record<string, unknown>, specs: ReadonlyArray<ContainerBindingSpec>, jurisdiction?: DurableObjectJurisdiction, traceparent?: string) => Record<string, ContainerAccessor>;
 /**
  * A test handler: receives the request plus the targeted instance name.
- * @experimental
  */
 type ContainerTestHandler = (request: Request, instance: {
   name: string;
@@ -260,7 +335,6 @@ type ContainerTestHandler = (request: Request, instance: {
  *     transcoder: (request) => new Response("ok"),
  * });
  * ```
- * @experimental
  */
 declare const createContainerTestContext: (handlers: Record<string, ContainerTestHandler>) => Record<string, ContainerAccessor>;
 /**
@@ -272,7 +346,6 @@ declare const createContainerTestContext: (handlers: Record<string, ContainerTes
  * `Dockerfile.dev` also counts) is used as-is with its directory as the build
  * context; any other path is treated as the build-context directory and the
  * Dockerfile is expected at `<dir>/Dockerfile`.
- * @experimental
  */
 declare const normalizeContainerImage: (image: ContainerImageSource) => NormalizedContainerImage;
 /**
@@ -280,7 +353,6 @@ declare const normalizeContainerImage: (image: ContainerImageSource) => Normaliz
  * `transcoder` → `TranscoderContainer`. wrangler's `containers[].class_name`
  * and the Durable Object binding's `class_name` both reference it, so codegen
  * and the config layer MUST derive it identically — always via this helper.
- * @experimental
  */
 declare const containerClassName: (exportName: string) => string;
 /**
@@ -288,7 +360,6 @@ declare const containerClassName: (exportName: string) => string;
  * `CONTAINER_TRANSCODER`, `imageResizer` → `CONTAINER_IMAGE_RESIZER`. The
  * `CONTAINER_` prefix namespaces these away from `SHARD`/`SESSION`/`SCHEDULER`
  * so a container export can never collide with the built-in bindings.
- * @experimental
  */
 declare const containerBindingName: (exportName: string) => string;
 /**
@@ -297,17 +368,14 @@ declare const containerBindingName: (exportName: string) => string;
  * it as the wrangler `containers[].image`, and `lunora deploy` builds that tag
  * with Railpack and `wrangler containers push`es it before deploying — so all
  * three derive the tag from this one helper and can never disagree.
- * @experimental
  */
 declare const containerBuildTag: (exportName: string) => string;
 /**
  * `defineContainer` is part of the experimental `@lunora/container` API and may change without a major version bump.
- * @experimental
  */
 declare const defineContainer: (config: ContainerConfig) => ContainerDefinition;
 /**
  * True when a value is a `defineContainer` result (the runtime brand check).
- * @experimental
  */
 declare const isContainerDefinition: (value: unknown) => value is ContainerDefinition;
 /**
@@ -315,10 +383,9 @@ declare const isContainerDefinition: (value: unknown) => value is ContainerDefin
  * plus every declared secret resolved from the Worker `env`. A declared secret
  * missing from the Worker env fails fast — starting the container without a
  * credential it was promised yields far worse errors downstream.
- * @experimental
  */
 declare const resolveContainerEnvVariables: (definition: ContainerDefinition, workerEnv: Record<string, unknown>, exportName?: string) => Record<string, string>;
-export {
+export { CONTAINER_EXEC_PATH,
 /**
  * `@lunora/container` — Cloudflare Containers for Lunora.
  *
@@ -351,7 +418,7 @@ type ContainerBindingSpec, type ContainerConfig, type ContainerDefinition,
  * (which pulls in `@cloudflare/containers` → `cloudflare:workers`) lives
  * behind the `@lunora/container/do` subpath.
  */
-type ContainerEgressControls,
+type ContainerEgressControls, type ContainerExecOptions, type ContainerExecResult,
 /**
  * `@lunora/container` — Cloudflare Containers for Lunora.
  *

package/dist/index.d.ts

@@ -1,8 +1,74 @@
-import { D as DurableObjectJurisdiction, C as ContainerConfig, a as ContainerDefinition, b as ContainerImageSource, N as NormalizedContainerImage } from "./packem_shared/jurisdiction.d-DeQ3rtYK.js";
-export type { B as BuildImageSource, c as ContainerInstanceType, d as ContainerReadinessCheck, e as ContainerRollout, f as CustomContainerInstanceType, g as NamedContainerInstanceType, R as RegistryImageSource } from "./packem_shared/jurisdiction.d-DeQ3rtYK.js";
+import { D as DurableObjectJurisdiction, a as ContainerConfig, C as ContainerDefinition, b as ContainerImageSource, N as NormalizedContainerImage } from "./packem_shared/jurisdiction.d-KcQu2ZT_.js";
+export type { B as BuildImageSource, c as ContainerInstanceType, d as ContainerReadinessCheck, e as ContainerRollout, f as CustomContainerInstanceType, g as NamedContainerInstanceType, R as RegistryImageSource } from "./packem_shared/jurisdiction.d-KcQu2ZT_.js";
+/**
+ * Per-call options for `ContainerHandle.exec`.
+ */
+interface ContainerExecOptions {
+  /** Arguments passed to `command`, unshelled — the container must not concatenate them into a shell string. */
+  args?: ReadonlyArray<string>;
+  /** Working directory for the command, relative to the container's own root. */
+  cwd?: string;
+  /** Extra environment for this command only, merged over the container's env. */
+  env?: Readonly<Record<string, string>>;
+  /**
+   * Cap on the response body, in bytes. The whole `{code,stdout,stderr}`
+   * document has to be held in memory to be parsed, and a build box or job
+   * runner routinely writes tens of megabytes — a single unbounded `exec`
+   * that returns more than the isolate's memory limit kills the isolate and
+   * every other in-flight request sharing it, not just this call. So a
+   * runner that overruns the cap fails the call loudly rather than taking
+   * the shard down with it; raise this (or have the runner cap its own
+   * output) when a command legitimately produces more.
+   *
+   * Default {@link DEFAULT_EXEC_MAX_OUTPUT_BYTES} (1MB).
+   */
+  maxOutputBytes?: number;
+  /**
+   * Abort the call. Composed with {@link ContainerExecOptions.timeoutMs} when
+   * both are given — whichever fires first wins.
+   */
+  signal?: AbortSignal;
+  /**
+   * Give up after this many ms. Covers the whole call — the request *and*
+   * reading the response body, since `fetch` resolves on headers and a
+   * runner that answers `200` and then stalls mid-body would otherwise sit
+   * past the deadline. Sent to the container as well, so a well-behaved
+   * runner can kill the process rather than leak it when the caller walks
+   * away.
+   */
+  timeoutMs?: number;
+}
+/**
+ * The outcome of a `ContainerHandle.exec` call.
+ *
+ * A non-zero `code` is **not** an error: a command that ran and failed is a
+ * result, and the caller decides what to do with it. Only a failure to *run*
+ * the command — transport, a non-2xx from the runner, an unparseable body —
+ * throws.
+ */
+interface ContainerExecResult {
+  /** Process exit code. Non-zero means the command ran and failed. */
+  code: number;
+  /** Everything the command wrote to stderr. */
+  stderr: string;
+  /** Everything the command wrote to stdout. */
+  stdout: string;
+}
+/**
+ * The route `ContainerHandle.exec` POSTs to. Namespaced under
+ * `/__lunora/` so it cannot collide with an application route the container
+ * already serves — the previous ad-hoc convention was a bare `/exec`, which an
+ * app could plausibly own for its own purposes.
+ *
+ * Exported because it is a *contract*, not an implementation detail: a
+ * container image has to serve exactly this route, and `@lunora/agent`'s
+ * human-in-the-loop gate has to recognise it. Both had it hard-coded as a
+ * second literal, which drifts silently — and on the gate's side, drift
+ * un-gates model-chosen command execution.
+ */
+declare const CONTAINER_EXEC_PATH = "/__lunora/exec";
 /**
  * Options for explicitly starting an instance (mirrors `@cloudflare/containers`).
- * @experimental
  */
 interface ContainerStartOptions {
   /** Override outbound internet access for this start. */
@@ -16,7 +82,6 @@ interface ContainerStartOptions {
 }
 /**
  * A container instance's runtime state, as returned by `getState()`. Structural — the platform adds fields over time.
- * @experimental
  */
 interface ContainerInstanceState {
   [key: string]: unknown;
@@ -44,7 +109,6 @@ interface ContainerStubLike {
 }
 /**
  * What the client needs from a Durable Object namespace binding.
- * @experimental
  */
 interface ContainerNamespaceLike {
   get: (id: unknown) => ContainerStubLike;
@@ -57,9 +121,24 @@ interface ContainerNamespaceLike {
 }
 /**
  * A handle on one container instance (one Durable Object).
- * @experimental
  */
 interface ContainerHandle {
+  /**
+   * Run a command inside the container and return its exit code and output.
+   *
+   * A container is an HTTP server, so there is no platform-level exec to call:
+   * the command is POSTed to `/__lunora/exec` and the container app
+   * serves that route. What this method adds over hand-rolling that fetch is
+   * the **contract** — a pinned path, a typed request and response, and the
+   * distinction between "the command failed" (a `code`) and "the command could
+   * not be run" (a throw). Before it existed every caller invented its own
+   * `/exec` convention and read the raw body back as if it were output, which
+   * silently turned a runner's 500 into a successful-looking result.
+   *
+   * The container side must accept `{ args, command, cwd, env, timeoutMs }`
+   * and answer `{ code, stdout, stderr }` as JSON.
+   */
+  exec: (command: string, options?: ContainerExecOptions) => Promise<ContainerExecResult>;
   /**
    * Send an HTTP (or WebSocket-upgrade) request to the container. A path
    * string (`"/transcode"`) is resolved against a synthetic origin; a full
@@ -82,7 +161,6 @@ interface ContainerHandle {
  * game, a job runner per id) often needs to tear down or inspect the instance
  * rather than wait for `sleepAfter`, so these wrap the container DO's
  * `start`/`stop`/`destroy`/`getState`.
- * @experimental
  */
 interface ContainerInstanceHandle extends ContainerHandle {
   /** Stop and discard the instance (its ephemeral disk is lost). */
@@ -117,7 +195,6 @@ interface ContainerInstanceHandle extends ContainerHandle {
  * Each maps to the corresponding `@cloudflare/containers` `Container` RPC, so
  * an app can tighten or relax a single instance's allowed/denied hosts after
  * start without redeploying.
- * @experimental
  */
 interface ContainerEgressControls {
   /** Add one hostname (or glob) to the allow-list. */
@@ -135,7 +212,6 @@ interface ContainerEgressControls {
 }
 /**
  * The per-definition accessor exposed as `ctx.containers.<exportName>`.
- * @experimental
  */
 interface ContainerAccessor {
   /**
@@ -178,7 +254,6 @@ interface ContainerAccessor {
 }
 /**
  * Tuning for a pooled, retrying container handle. See {@link ContainerAccessor.pool}.
- * @experimental
  */
 interface PoolOptions {
   /** Total attempts before giving up (each on a freshly-picked instance). Default 3. */
@@ -195,6 +270,10 @@ interface PoolOptions {
    * Whether a *returned* response should be retried on another instance.
    * Defaults to retrying any `5xx`. A thrown error (network/start failure) is
    * always retried regardless of this predicate.
+   *
+   * Applies to `fetch` only. `exec` retries on the cold-start transients
+   * alone, because its caller never chose the request and a command that
+   * already ran must not be re-run just because the runner failed afterwards.
    */
   retryOn?: (response: Response) => boolean;
   /** Pool size to spread picks across. Defaults to the definition's `maxInstances`, else 3. */
@@ -205,7 +284,6 @@ interface PoolOptions {
  * only on the platform's provisioning transients (no-instance / not-listening /
  * rate-limited — see {@link isColdStartTransient}), which is why it's safe by
  * default: those responses mean the request never reached the container.
- * @experimental
  */
 interface InstanceRetryOptions {
   /**
@@ -221,7 +299,6 @@ interface InstanceRetryOptions {
 }
 /**
  * Wiring info for one definition, emitted by codegen into the generated DO.
- * @experimental
  */
 interface ContainerBindingSpec {
   /** Durable Object binding name, e.g. `CONTAINER_TRANSCODER`. */
@@ -240,12 +317,10 @@ interface ContainerBindingSpec {
  * `traceparent` (the inbound RPC's W3C trace context, forwarded by the runtime
  * and read off the request by the DO) is stamped onto every outbound container
  * `fetch`, so the container's own spans stitch under the Worker's trace.
- * @experimental
  */
 declare const createContainerContext: (env: Record<string, unknown>, specs: ReadonlyArray<ContainerBindingSpec>, jurisdiction?: DurableObjectJurisdiction, traceparent?: string) => Record<string, ContainerAccessor>;
 /**
  * A test handler: receives the request plus the targeted instance name.
- * @experimental
  */
 type ContainerTestHandler = (request: Request, instance: {
   name: string;
@@ -260,7 +335,6 @@ type ContainerTestHandler = (request: Request, instance: {
  *     transcoder: (request) => new Response("ok"),
  * });
  * ```
- * @experimental
  */
 declare const createContainerTestContext: (handlers: Record<string, ContainerTestHandler>) => Record<string, ContainerAccessor>;
 /**
@@ -272,7 +346,6 @@ declare const createContainerTestContext: (handlers: Record<string, ContainerTes
  * `Dockerfile.dev` also counts) is used as-is with its directory as the build
  * context; any other path is treated as the build-context directory and the
  * Dockerfile is expected at `<dir>/Dockerfile`.
- * @experimental
  */
 declare const normalizeContainerImage: (image: ContainerImageSource) => NormalizedContainerImage;
 /**
@@ -280,7 +353,6 @@ declare const normalizeContainerImage: (image: ContainerImageSource) => Normaliz
  * `transcoder` → `TranscoderContainer`. wrangler's `containers[].class_name`
  * and the Durable Object binding's `class_name` both reference it, so codegen
  * and the config layer MUST derive it identically — always via this helper.
- * @experimental
  */
 declare const containerClassName: (exportName: string) => string;
 /**
@@ -288,7 +360,6 @@ declare const containerClassName: (exportName: string) => string;
  * `CONTAINER_TRANSCODER`, `imageResizer` → `CONTAINER_IMAGE_RESIZER`. The
  * `CONTAINER_` prefix namespaces these away from `SHARD`/`SESSION`/`SCHEDULER`
  * so a container export can never collide with the built-in bindings.
- * @experimental
  */
 declare const containerBindingName: (exportName: string) => string;
 /**
@@ -297,17 +368,14 @@ declare const containerBindingName: (exportName: string) => string;
  * it as the wrangler `containers[].image`, and `lunora deploy` builds that tag
  * with Railpack and `wrangler containers push`es it before deploying — so all
  * three derive the tag from this one helper and can never disagree.
- * @experimental
  */
 declare const containerBuildTag: (exportName: string) => string;
 /**
  * `defineContainer` is part of the experimental `@lunora/container` API and may change without a major version bump.
- * @experimental
  */
 declare const defineContainer: (config: ContainerConfig) => ContainerDefinition;
 /**
  * True when a value is a `defineContainer` result (the runtime brand check).
- * @experimental
  */
 declare const isContainerDefinition: (value: unknown) => value is ContainerDefinition;
 /**
@@ -315,10 +383,9 @@ declare const isContainerDefinition: (value: unknown) => value is ContainerDefin
  * plus every declared secret resolved from the Worker `env`. A declared secret
  * missing from the Worker env fails fast — starting the container without a
  * credential it was promised yields far worse errors downstream.
- * @experimental
  */
 declare const resolveContainerEnvVariables: (definition: ContainerDefinition, workerEnv: Record<string, unknown>, exportName?: string) => Record<string, string>;
-export {
+export { CONTAINER_EXEC_PATH,
 /**
  * `@lunora/container` — Cloudflare Containers for Lunora.
  *
@@ -351,7 +418,7 @@ type ContainerBindingSpec, type ContainerConfig, type ContainerDefinition,
  * (which pulls in `@cloudflare/containers` → `cloudflare:workers`) lives
  * behind the `@lunora/container/do` subpath.
  */
-type ContainerEgressControls,
+type ContainerEgressControls, type ContainerExecOptions, type ContainerExecResult,
 /**
  * `@lunora/container` — Cloudflare Containers for Lunora.
  *

package/dist/index.mjs

@@ -1 +1 @@
-import{createContainerContext as t,createContainerTestContext as a}from"./packem_shared/createContainerContext-C8pmlFAX.mjs";import{containerBindingName as o,containerBuildTag as r,containerClassName as C,defineContainer as m,isContainerDefinition as s,normalizeContainerImage as c,resolveContainerEnvVars as f}from"./packem_shared/containerBindingName-D01FopQt.mjs";export{o as containerBindingName,r as containerBuildTag,C as containerClassName,t as createContainerContext,a as createContainerTestContext,m as defineContainer,s as isContainerDefinition,c as normalizeContainerImage,f as resolveContainerEnvVars};
+import{createContainerContext as o,createContainerTestContext as r}from"./packem_shared/createContainerContext-LXvczcU0.mjs";import{containerBindingName as a,containerBuildTag as i,containerClassName as C,defineContainer as m,isContainerDefinition as s,normalizeContainerImage as c,resolveContainerEnvVars as f}from"./packem_shared/containerBindingName-D01FopQt.mjs";import{C as l}from"./packem_shared/exec-BjOpQOTW.mjs";export{l as CONTAINER_EXEC_PATH,a as containerBindingName,i as containerBuildTag,C as containerClassName,o as createContainerContext,r as createContainerTestContext,m as defineContainer,s as isContainerDefinition,c as normalizeContainerImage,f as resolveContainerEnvVars};

package/dist/otel.d.mts

@@ -1,6 +1,5 @@
 /**
  * An attribute value carried on a span or log.
- * @experimental
  */
 type ContainerAttributeValue = boolean | number | string;
 /**
@@ -9,7 +8,6 @@ type ContainerAttributeValue = boolean | number | string;
  * cancels the response `body` so Node/undici can release the socket for
  * keep-alive reuse instead of leaving it occupied by an unread stream. It reads
  * `ok`/`status` to detect a rejected export and nothing else from the response.
- * @experimental
  */
 type OtelFetchLike = (input: string, init: {
   body: string;
@@ -25,7 +23,6 @@ type OtelFetchLike = (input: string, init: {
 }>;
 /**
  * A single span the container process asks the exporter to record.
- * @experimental
  */
 interface ContainerSpanInput {
   /** Attributes attached to the span (rendered under the OTLP `attributes` list). */
@@ -44,7 +41,6 @@ interface ContainerSpanInput {
 }
 /**
  * A single log line the container process asks the exporter to record.
- * @experimental
  */
 interface ContainerLogInput {
   /** Attributes attached to the log record. */
@@ -58,7 +54,6 @@ interface ContainerLogInput {
 }
 /**
  * Options for {@link createContainerTelemetry}.
- * @experimental
  */
 interface ContainerTelemetryOptions {
   /**
@@ -124,7 +119,6 @@ interface ContainerTelemetryOptions {
 }
 /**
  * The exporter handle {@link createContainerTelemetry} returns.
- * @experimental
  */
 interface ContainerTelemetry {
   /** Record one log line (no-op when disabled). */
@@ -155,7 +149,6 @@ interface ContainerTelemetry {
  * `serviceName`, `traceparent`) always fall back to their `LUNORA_*` env var;
  * resource fields (`serviceVersion`, `deploymentEnvironment`) only do so under
  * `detectResources: true`.
- * @experimental
  */
 declare const createContainerTelemetry: (options?: ContainerTelemetryOptions) => ContainerTelemetry;
 export { type ContainerAttributeValue, type ContainerLogInput, type ContainerSpanInput, type ContainerTelemetry, type ContainerTelemetryOptions, type OtelFetchLike, createContainerTelemetry };

package/dist/otel.d.ts

@@ -1,6 +1,5 @@
 /**
  * An attribute value carried on a span or log.
- * @experimental
  */
 type ContainerAttributeValue = boolean | number | string;
 /**
@@ -9,7 +8,6 @@ type ContainerAttributeValue = boolean | number | string;
  * cancels the response `body` so Node/undici can release the socket for
  * keep-alive reuse instead of leaving it occupied by an unread stream. It reads
  * `ok`/`status` to detect a rejected export and nothing else from the response.
- * @experimental
  */
 type OtelFetchLike = (input: string, init: {
   body: string;
@@ -25,7 +23,6 @@ type OtelFetchLike = (input: string, init: {
 }>;
 /**
  * A single span the container process asks the exporter to record.
- * @experimental
  */
 interface ContainerSpanInput {
   /** Attributes attached to the span (rendered under the OTLP `attributes` list). */
@@ -44,7 +41,6 @@ interface ContainerSpanInput {
 }
 /**
  * A single log line the container process asks the exporter to record.
- * @experimental
  */
 interface ContainerLogInput {
   /** Attributes attached to the log record. */
@@ -58,7 +54,6 @@ interface ContainerLogInput {
 }
 /**
  * Options for {@link createContainerTelemetry}.
- * @experimental
  */
 interface ContainerTelemetryOptions {
   /**
@@ -124,7 +119,6 @@ interface ContainerTelemetryOptions {
 }
 /**
  * The exporter handle {@link createContainerTelemetry} returns.
- * @experimental
  */
 interface ContainerTelemetry {
   /** Record one log line (no-op when disabled). */
@@ -155,7 +149,6 @@ interface ContainerTelemetry {
  * `serviceName`, `traceparent`) always fall back to their `LUNORA_*` env var;
  * resource fields (`serviceVersion`, `deploymentEnvironment`) only do so under
  * `detectResources: true`.
- * @experimental
  */
 declare const createContainerTelemetry: (options?: ContainerTelemetryOptions) => ContainerTelemetry;
 export { type ContainerAttributeValue, type ContainerLogInput, type ContainerSpanInput, type ContainerTelemetry, type ContainerTelemetryOptions, type OtelFetchLike, createContainerTelemetry };

package/dist/packem_shared/CONTAINER_EXEC_PATH-bHAyYUZk.mjs

@@ -0,0 +1 @@
+import{C,e as E}from"./exec-BjOpQOTW.mjs";export{C as CONTAINER_EXEC_PATH,E as execViaFetch};

package/dist/packem_shared/createContainerContext-LXvczcU0.mjs

@@ -0,0 +1 @@
+import{LunoraError as R}from"@lunora/errors";import{containerBindingName as k}from"./containerBindingName-D01FopQt.mjs";import{e as F,r as U}from"./exec-BjOpQOTW.mjs";import{a as I}from"./jurisdiction-DtE9s70w.mjs";const N=3,D=3e4,q=3,W=500,j="cf-container-target-port",v="__lunora",p=t=>t.split("/").find(e=>e!=="")??"",C=(t,e)=>{const o=typeof t=="string"?t:t.url,n=URL.parse(o.startsWith("/")?`http://container${o}`:o);if(n===null)return;const{pathname:r}=n;let s=r;try{s=decodeURIComponent(r)}catch{}if(p(r)===v||p(s)===v)throw new R("BAD_REQUEST",`${e}: \`/${v}/*\` is reserved for Lunora's own container routes and cannot be reached with \`fetch\`. Use \`exec\` to run a command.`)},P=(t,e,o,n)=>{const r=typeof t=="string"&&t.startsWith("/")?new Request(`http://container${t}`,e):new Request(t,e);return o!==void 0&&r.headers.set(j,String(o)),n!==void 0&&r.headers.set("traceparent",n),r},L=async t=>{t<=0||await new Promise(e=>{setTimeout(e,t)})},Y=/no container instance|not listening|try again later|rate.?limit|provision/i,z="no Container instance available",G="Failed to start container:",K=1024,V=async t=>(await U(t.clone().body,K)).text,O=t=>t instanceof Error&&Y.test(t.message),H=async t=>{if(t.status===429)return!0;if(t.status!==500&&t.status!==503)return!1;try{const e=await V(t);return e.includes(z)||e.startsWith(G)}catch{return!1}},w=t=>`ctx.containers.${t.exportName}`,S=(t,e,o={},n,r)=>{const s=Math.max(1,o.attempts??q),a=o.backoffMs??W,A=o.maxBackoffMs??D,g=async(i,f)=>{const T=typeof i=="string"?s:1;let l;for(let d=0;d<T;d+=1){const u=d===T-1;d>0&&await L(Math.min(a*2**(d-1),A));try{const m=await t(P(i,f,n,r));if(u||!await H(m))return m}catch(m){if(l=m,u||!O(m))throw m}}throw l instanceof Error?l:new Error("ctx.containers: cold-start retry exhausted")};return{exec:F(g,e),fetch:async(i,f)=>(C(i,e),g(i,f)),port:i=>S(t,e,o,i,r)}},x=(t,e,o,n,r)=>S(async s=>t.get(t.idFromName(e)).fetch(s),o,n,void 0,r),c=async(t,e,o,n)=>{const r=t[e];if(typeof r!="function")throw new TypeError(`ctx.containers: the "${o}" container DO does not expose ${e}() — is @lunora/container/do up to date?`);return r(n)},J=(t,e)=>({allow:async o=>c(t(),"allowHost",e,o),deny:async o=>c(t(),"denyHost",e,o),removeAllowed:async o=>c(t(),"removeAllowedHost",e,o),removeDenied:async o=>c(t(),"removeDeniedHost",e,o),setAllowed:async o=>c(t(),"setAllowedHosts",e,[...o]),setDenied:async o=>c(t(),"setDeniedHosts",e,[...o])}),b=(t,e,o,n,r)=>{const s=()=>t.get(t.idFromName(o));return{...S(async a=>s().fetch(a),w(e),n,void 0,r),destroy:async()=>c(s(),"destroy",e.binding),egress:J(s,e.binding),getState:async()=>c(s(),"getState",e.binding),renewActivityTimeout:async()=>c(s(),"renewActivityTimeout",e.binding),start:async a=>c(s(),"start",e.binding,a),stop:async a=>c(s(),"stop",e.binding,a)}},B=t=>`pool-${String(Math.floor(Math.random()*t))}`,Q=t=>t.status>=500,M=(t,e,o={},n,r)=>{const s=o.size??e.maxInstances??N,a=Math.max(1,o.attempts??3),A=o.backoffMs??100,g=o.maxBackoffMs??D,i=`${w(e)}.pool()`,f=(l,d)=>async(u,m)=>{const E=typeof u=="string"?a:1;let _;for(let h=0;h<E;h+=1){h>0&&await L(Math.min(A*2**(h-1),g));const $=P(u,m,n,r);try{const y=await t.get(t.idFromName(B(s))).fetch($);if(h===E-1||!await l(y))return y}catch(y){if(_=y,!d(y))throw y}}throw _ instanceof Error?_:new Error(`ctx.containers.${e.exportName}.pool(): all ${String(E)} attempts failed`)},T=f(o.retryOn??Q,()=>!0);return{exec:F(f(H,O),i),fetch:async(l,d)=>(C(l,i),T(l,d)),port:l=>M(t,e,o,l,r)}},X=(t,e,o)=>({any:(n,r)=>x(t,B(n??e.maxInstances??N),w(e),r,o),get:(n,r)=>b(t,e,n,r,o),pool:n=>M(t,e,n,void 0,o)}),Z=t=>{const e=()=>{throw new R("INTERNAL",`ctx.containers.${t.exportName}: no "${t.binding}" Durable Object binding found. Run \`lunora dev\` (or \`lunora deploy\`) to reconcile wrangler.jsonc, and make sure the worker entry re-exports the generated container classes.`)};return{any:e,get:e,pool:e}},st=(t,e,o,n)=>{const r={};for(const s of e){const a=t[s.binding];r[s.exportName]=a&&typeof a.idFromName=="function"&&typeof a.get=="function"?X(I(a,o),s,n):Z(s)}return r},tt=t=>{const e=o=>({allowHost:()=>Promise.resolve(),denyHost:()=>Promise.resolve(),destroy:()=>Promise.resolve(),fetch:n=>Promise.resolve(t(n,{name:o})),getState:()=>Promise.resolve({lastChange:0}),removeAllowedHost:()=>Promise.resolve(),removeDeniedHost:()=>Promise.resolve(),renewActivityTimeout:()=>Promise.resolve(),setAllowedHosts:()=>Promise.resolve(),setDeniedHosts:()=>Promise.resolve(),start:()=>Promise.resolve(),stop:()=>Promise.resolve()});return{get:o=>e(String(o)),idFromName:o=>o}},at=t=>{const e={};for(const[o,n]of Object.entries(t)){const r=tt(n),s={binding:k(o),exportName:o};e[o]={any:()=>x(r,"pool-0",w(s),{attempts:1}),get:a=>b(r,s,a,{attempts:1}),pool:()=>x(r,"pool-0",`${w(s)}.pool()`,{attempts:1})}}return e};export{st as createContainerContext,at as createContainerTestContext};

package/dist/packem_shared/exec-BjOpQOTW.mjs

@@ -0,0 +1 @@
+import{LunoraError as d}from"@lunora/errors";const w=async(o,r,t)=>{if(o===null)return{overflowed:!1,text:""};const e=o.getReader(),n=new TextDecoder,a=()=>{e.cancel().catch(()=>{})};t?.addEventListener("abort",a);let s="",c=0,u=!1;try{for(;t?.aborted!==!0;){const{done:f,value:i}=await e.read();if(f)break;if(c+i.byteLength>r){u=!0,s+=n.decode(i.subarray(0,r-c),{stream:!0});break}c+=i.byteLength,s+=n.decode(i,{stream:!0})}s+=n.decode()}finally{t?.removeEventListener("abort",a),e.cancel().catch(()=>{})}if(t?.aborted===!0)throw t.reason;return{overflowed:u,text:s}},l="/__lunora/exec",E=512,b=1e6,v="<redacted>",h=(o,r)=>{if(r===void 0)return o;let t=o;for(const e of Object.values(r))e.length>0&&(t=t.split(e).join(v));return t},x=o=>{if(o===null||typeof o!="object")return;const{code:r,stderr:t,stdout:e}=o;if(typeof r=="number")return{code:r,stderr:typeof t=="string"?t:"",stdout:typeof e=="string"?e:""}},m=(o,r)=>{if(r===void 0)return{dispose:()=>{},signal:o};const t=new AbortController,e=setTimeout(()=>{t.abort(new d("INTERNAL",`ctx.containers: exec timed out after ${String(r)}ms`))},r);return{dispose:()=>{clearTimeout(e)},signal:o===void 0?t.signal:AbortSignal.any([o,t.signal])}},T=(o,r)=>async(t,e={})=>{if(typeof t!="string"||t.length===0)throw new d("BAD_REQUEST",`${r}: exec requires a non-empty \`command\``);const n=e.maxOutputBytes??b;if(!Number.isSafeInteger(n)||n<=0)throw new d("BAD_REQUEST",`${r}: exec \`maxOutputBytes\` must be a positive whole number of bytes, got ${String(n)}`);const a=m(e.signal,e.timeoutMs);try{const s=await o(l,{body:JSON.stringify({args:e.args??[],command:t,...e.cwd===void 0?{}:{cwd:e.cwd},...e.env===void 0?{}:{env:e.env},...e.timeoutMs===void 0?{}:{timeoutMs:e.timeoutMs}}),headers:{"content-type":"application/json"},method:"POST",...a.signal===void 0?{}:{signal:a.signal}});if(!s.ok){const i=await w(s.body,E,a.signal).then(y=>h(y.text,e.env),()=>"<unreadable body>");throw new d("INTERNAL",`${r}: exec failed — the container answered ${String(s.status)} for POST ${l}. Does it serve that route? Body: ${i}`)}const c=await w(s.body,n,a.signal);if(c.overflowed)throw new d("INTERNAL",`${r}: exec response exceeded ${String(n)} bytes and was abandoned — it is buffered whole to be parsed, so an unbounded one would exhaust the isolate. Cap the command's output, or raise \`maxOutputBytes\`.`);let u;try{u=JSON.parse(c.text)}catch{throw new d("INTERNAL",`${r}: exec response was not JSON — expected {"code","stdout","stderr"} from POST ${l}`)}const f=x(u);if(f===void 0)throw new d("INTERNAL",`${r}: exec response is missing a numeric \`code\` — expected {"code","stdout","stderr"} from POST ${l}`);return f}finally{a.dispose()}};export{l as C,T as e,w as r};

package/dist/packem_shared/{jurisdiction.d-DeQ3rtYK.d.mts → jurisdiction.d-KcQu2ZT_.d.mts}

@@ -7,14 +7,12 @@
  */
 /**
  * Named instance types Cloudflare Containers provides.
- * @experimental
  */
 type NamedContainerInstanceType = "basic" | "lite" | "standard-1" | "standard-2" | "standard-3" | "standard-4";
 /**
  * A custom instance type. Cloudflare's bounds at the time of writing: up to
  * 4 vCPU, 12 GiB memory, 20 GB disk, ≥ 3 GiB memory per vCPU and ≤ 2 GB disk
  * per GiB memory. The config-layer validator enforces the documented ranges.
- * @experimental
  */
 interface CustomContainerInstanceType {
   /** Disk in MB. Cloudflare's default is 2000 (2 GB). */
@@ -26,12 +24,10 @@ interface CustomContainerInstanceType {
 }
 /**
  * `ContainerInstanceType` is part of the experimental `@lunora/container` API and may change without a major version bump.
- * @experimental
  */
 type ContainerInstanceType = CustomContainerInstanceType | NamedContainerInstanceType;
 /**
  * Rolling-deploy tuning for a container.
- * @experimental
  */
 interface ContainerRollout {
   /** Seconds an active instance runs before it's eligible for update (wrangler `rollout_active_grace_period`). */
@@ -43,7 +39,6 @@ interface ContainerRollout {
  * A pre-built image pulled from a registry — the Cloudflare Registry, Docker
  * Hub, or Amazon ECR (the registries `wrangler deploy` supports). The
  * reference must be fully qualified, e.g. `docker.io/acme/transcoder:1.4`.
- * @experimental
  */
 interface RegistryImageSource {
   registry: string;
@@ -53,7 +48,6 @@ interface RegistryImageSource {
  * source directory and `lunora deploy` builds an OCI image with Railpack
  * (needs a BuildKit instance) and pushes it to the Cloudflare Registry before
  * wrangler runs. Opt-in — the Dockerfile path is the zero-extra-deps default.
- * @experimental
  */
 interface BuildImageSource {
   build: string;
@@ -63,7 +57,6 @@ interface BuildImageSource {
  * either a directory containing a `Dockerfile` (normalized to
  * `<dir>/Dockerfile` with the directory as the build context) or a path to
  * the Dockerfile itself — while `{ registry }` is a pre-built image reference.
- * @experimental
  */
 type ContainerImageSource = BuildImageSource | RegistryImageSource | string;
 /**
@@ -76,7 +69,6 @@ type ContainerImageSource = BuildImageSource | RegistryImageSource | string;
  * functions), so codegen and the config layer can read it without evaluating
  * code. (Upstream cloudflare/containers#188 expresses the same idea as handler
  * functions; the Lunora config is data-only, so it's modelled as descriptors.)
- * @experimental
  */
 interface ContainerReadinessCheck {
   /** HTTP path probed on the container, e.g. `"/ready"` (a leading slash is optional). */
@@ -88,7 +80,6 @@ interface ContainerReadinessCheck {
 }
 /**
  * `ContainerConfig` is part of the experimental `@lunora/container` API and may change without a major version bump.
- * @experimental
  */
 interface ContainerConfig {
   /**
@@ -246,7 +237,6 @@ interface ContainerConfig {
 /**
  * The value `defineContainer` returns: the validated config plus a brand the
  * codegen discovery and the generated Container DO class key on.
- * @experimental
  */
 interface ContainerDefinition extends ContainerConfig {
   /** Brand marking a value as a Lunora container definition. */
@@ -254,7 +244,6 @@ interface ContainerDefinition extends ContainerConfig {
 }
 /**
  * A normalized image source, as written into `wrangler.jsonc`.
- * @experimental
  */
 type NormalizedContainerImage = {
   /** Build context directory (wrangler `image_build_context`). */
@@ -275,7 +264,6 @@ type NormalizedContainerImage = {
  * Cloudflare Durable Object data-residency jurisdiction. Widening union —
  * Cloudflare adds values over time.
  * @see https://developers.cloudflare.com/durable-objects/reference/data-location/
- * @experimental
  */
 type DurableObjectJurisdiction = "eu" | "fedramp" | "us";
-export { BuildImageSource as B, ContainerConfig as C, DurableObjectJurisdiction as D, NormalizedContainerImage as N, RegistryImageSource as R, ContainerDefinition as a, ContainerImageSource as b, ContainerInstanceType as c, ContainerReadinessCheck as d, ContainerRollout as e, CustomContainerInstanceType as f, NamedContainerInstanceType as g };
+export { BuildImageSource as B, ContainerDefinition as C, DurableObjectJurisdiction as D, NormalizedContainerImage as N, RegistryImageSource as R, ContainerConfig as a, ContainerImageSource as b, ContainerInstanceType as c, ContainerReadinessCheck as d, ContainerRollout as e, CustomContainerInstanceType as f, NamedContainerInstanceType as g };

package/dist/packem_shared/{jurisdiction.d-DeQ3rtYK.d.ts → jurisdiction.d-KcQu2ZT_.d.ts}

@@ -7,14 +7,12 @@
  */
 /**
  * Named instance types Cloudflare Containers provides.
- * @experimental
  */
 type NamedContainerInstanceType = "basic" | "lite" | "standard-1" | "standard-2" | "standard-3" | "standard-4";
 /**
  * A custom instance type. Cloudflare's bounds at the time of writing: up to
  * 4 vCPU, 12 GiB memory, 20 GB disk, ≥ 3 GiB memory per vCPU and ≤ 2 GB disk
  * per GiB memory. The config-layer validator enforces the documented ranges.
- * @experimental
  */
 interface CustomContainerInstanceType {
   /** Disk in MB. Cloudflare's default is 2000 (2 GB). */
@@ -26,12 +24,10 @@ interface CustomContainerInstanceType {
 }
 /**
  * `ContainerInstanceType` is part of the experimental `@lunora/container` API and may change without a major version bump.
- * @experimental
  */
 type ContainerInstanceType = CustomContainerInstanceType | NamedContainerInstanceType;
 /**
  * Rolling-deploy tuning for a container.
- * @experimental
  */
 interface ContainerRollout {
   /** Seconds an active instance runs before it's eligible for update (wrangler `rollout_active_grace_period`). */
@@ -43,7 +39,6 @@ interface ContainerRollout {
  * A pre-built image pulled from a registry — the Cloudflare Registry, Docker
  * Hub, or Amazon ECR (the registries `wrangler deploy` supports). The
  * reference must be fully qualified, e.g. `docker.io/acme/transcoder:1.4`.
- * @experimental
  */
 interface RegistryImageSource {
   registry: string;
@@ -53,7 +48,6 @@ interface RegistryImageSource {
  * source directory and `lunora deploy` builds an OCI image with Railpack
  * (needs a BuildKit instance) and pushes it to the Cloudflare Registry before
  * wrangler runs. Opt-in — the Dockerfile path is the zero-extra-deps default.
- * @experimental
  */
 interface BuildImageSource {
   build: string;
@@ -63,7 +57,6 @@ interface BuildImageSource {
  * either a directory containing a `Dockerfile` (normalized to
  * `<dir>/Dockerfile` with the directory as the build context) or a path to
  * the Dockerfile itself — while `{ registry }` is a pre-built image reference.
- * @experimental
  */
 type ContainerImageSource = BuildImageSource | RegistryImageSource | string;
 /**
@@ -76,7 +69,6 @@ type ContainerImageSource = BuildImageSource | RegistryImageSource | string;
  * functions), so codegen and the config layer can read it without evaluating
  * code. (Upstream cloudflare/containers#188 expresses the same idea as handler
  * functions; the Lunora config is data-only, so it's modelled as descriptors.)
- * @experimental
  */
 interface ContainerReadinessCheck {
   /** HTTP path probed on the container, e.g. `"/ready"` (a leading slash is optional). */
@@ -88,7 +80,6 @@ interface ContainerReadinessCheck {
 }
 /**
  * `ContainerConfig` is part of the experimental `@lunora/container` API and may change without a major version bump.
- * @experimental
  */
 interface ContainerConfig {
   /**
@@ -246,7 +237,6 @@ interface ContainerConfig {
 /**
  * The value `defineContainer` returns: the validated config plus a brand the
  * codegen discovery and the generated Container DO class key on.
- * @experimental
  */
 interface ContainerDefinition extends ContainerConfig {
   /** Brand marking a value as a Lunora container definition. */
@@ -254,7 +244,6 @@ interface ContainerDefinition extends ContainerConfig {
 }
 /**
  * A normalized image source, as written into `wrangler.jsonc`.
- * @experimental
  */
 type NormalizedContainerImage = {
   /** Build context directory (wrangler `image_build_context`). */
@@ -275,7 +264,6 @@ type NormalizedContainerImage = {
  * Cloudflare Durable Object data-residency jurisdiction. Widening union —
  * Cloudflare adds values over time.
  * @see https://developers.cloudflare.com/durable-objects/reference/data-location/
- * @experimental
  */
 type DurableObjectJurisdiction = "eu" | "fedramp" | "us";
-export { BuildImageSource as B, ContainerConfig as C, DurableObjectJurisdiction as D, NormalizedContainerImage as N, RegistryImageSource as R, ContainerDefinition as a, ContainerImageSource as b, ContainerInstanceType as c, ContainerReadinessCheck as d, ContainerRollout as e, CustomContainerInstanceType as f, NamedContainerInstanceType as g };
+export { BuildImageSource as B, ContainerDefinition as C, DurableObjectJurisdiction as D, NormalizedContainerImage as N, RegistryImageSource as R, ContainerConfig as a, ContainerImageSource as b, ContainerInstanceType as c, ContainerReadinessCheck as d, ContainerRollout as e, CustomContainerInstanceType as f, NamedContainerInstanceType as g };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lunora/container",
-  "version": "1.0.0-alpha.31",
+  "version": "1.0.0-alpha.32",
   "description": "Cloudflare Containers for Lunora: defineContainer, generated Container DO classes, and the ctx.containers action surface",
   "keywords": [
     "cloudflare",

package/dist/packem_shared/createContainerContext-C8pmlFAX.mjs

@@ -1 +0,0 @@
-import{LunoraError as F}from"@lunora/errors";import{containerBindingName as p}from"./containerBindingName-D01FopQt.mjs";import{a as N}from"./jurisdiction-DtE9s70w.mjs";const h=3,v=3e4,C=3,O=500,P="cf-container-target-port",_=(t,e,o,n)=>{const r=typeof t=="string"&&t.startsWith("/")?new Request(`http://container${t}`,e):new Request(t,e);return o!==void 0&&r.headers.set(P,String(o)),n!==void 0&&r.headers.set("traceparent",n),r},E=async t=>{t<=0||await new Promise(e=>{setTimeout(e,t)})},H=/no container instance|not listening|try again later|rate.?limit|provision/i,L="no Container instance available",b="Failed to start container:",B=1024,M=async t=>{const e=t.clone().body;if(e===null)return"";const o=e.getReader(),n=new TextDecoder;let r="";try{for(;r.length<B;){const{done:s,value:a}=await o.read();if(s)break;r+=n.decode(a,{stream:!0})}}finally{await o.cancel()}return r},k=t=>t instanceof Error&&H.test(t.message),$=async t=>{if(t.status===429)return!0;if(t.status!==500&&t.status!==503)return!1;try{const e=await M(t);return e.includes(L)||e.startsWith(b)}catch{return!1}},A=(t,e={},o,n)=>{const r=Math.max(1,e.attempts??C),s=e.backoffMs??O,a=e.maxBackoffMs??v;return{fetch:async(m,T)=>{const u=typeof m=="string"?r:1;let l;for(let d=0;d<u;d+=1){const f=d===u-1;d>0&&await E(Math.min(s*2**(d-1),a));try{const i=await t(_(m,T,o,n));if(f||!await $(i))return i}catch(i){if(l=i,f||!k(i))throw i}}throw l instanceof Error?l:new Error("ctx.containers: cold-start retry exhausted")},port:m=>A(t,e,m,n)}},w=(t,e,o,n)=>A(async r=>t.get(t.idFromName(e)).fetch(r),o,void 0,n),c=async(t,e,o,n)=>{const r=t[e];if(typeof r!="function")throw new TypeError(`ctx.containers: the "${o}" container DO does not expose ${e}() — is @lunora/container/do up to date?`);return r(n)},I=(t,e)=>({allow:async o=>c(t(),"allowHost",e,o),deny:async o=>c(t(),"denyHost",e,o),removeAllowed:async o=>c(t(),"removeAllowedHost",e,o),removeDenied:async o=>c(t(),"removeDeniedHost",e,o),setAllowed:async o=>c(t(),"setAllowedHosts",e,[...o]),setDenied:async o=>c(t(),"setDeniedHosts",e,[...o])}),S=(t,e,o,n,r)=>{const s=()=>t.get(t.idFromName(o));return{...A(async a=>s().fetch(a),n,void 0,r),destroy:async()=>c(s(),"destroy",e.binding),egress:I(s,e.binding),getState:async()=>c(s(),"getState",e.binding),renewActivityTimeout:async()=>c(s(),"renewActivityTimeout",e.binding),start:async a=>c(s(),"start",e.binding,a),stop:async a=>c(s(),"stop",e.binding,a)}},x=t=>`pool-${String(Math.floor(Math.random()*t))}`,q=t=>t.status>=500,R=(t,e,o={},n,r)=>{const s=o.size??e.maxInstances??h,a=Math.max(1,o.attempts??3),m=o.backoffMs??100,T=o.maxBackoffMs??v,u=o.retryOn??q;return{fetch:async(l,d)=>{const f=typeof l=="string"?a:1;let i;for(let y=0;y<f;y+=1){y>0&&await E(Math.min(m*2**(y-1),T));const D=_(l,d,n,r);try{const g=await t.get(t.idFromName(x(s))).fetch(D);if(y===f-1||!u(g))return g}catch(g){i=g}}throw i instanceof Error?i:new Error(`ctx.containers.${e.exportName}.pool(): all ${String(f)} attempts failed`)},port:l=>R(t,e,o,l,r)}},U=(t,e,o)=>({any:(n,r)=>w(t,x(n??e.maxInstances??h),r,o),get:(n,r)=>S(t,e,n,r,o),pool:n=>R(t,e,n,void 0,o)}),j=t=>{const e=()=>{throw new F("INTERNAL",`ctx.containers.${t.exportName}: no "${t.binding}" Durable Object binding found. Run \`lunora dev\` (or \`lunora deploy\`) to reconcile wrangler.jsonc, and make sure the worker entry re-exports the generated container classes.`)};return{any:e,get:e,pool:e}},G=(t,e,o,n)=>{const r={};for(const s of e){const a=t[s.binding];r[s.exportName]=a&&typeof a.idFromName=="function"&&typeof a.get=="function"?U(N(a,o),s,n):j(s)}return r},Y=t=>{const e=o=>({allowHost:()=>Promise.resolve(),denyHost:()=>Promise.resolve(),destroy:()=>Promise.resolve(),fetch:n=>Promise.resolve(t(n,{name:o})),getState:()=>Promise.resolve({lastChange:0}),removeAllowedHost:()=>Promise.resolve(),removeDeniedHost:()=>Promise.resolve(),renewActivityTimeout:()=>Promise.resolve(),setAllowedHosts:()=>Promise.resolve(),setDeniedHosts:()=>Promise.resolve(),start:()=>Promise.resolve(),stop:()=>Promise.resolve()});return{get:o=>e(String(o)),idFromName:o=>o}},J=t=>{const e={};for(const[o,n]of Object.entries(t)){const r=Y(n),s={binding:p(o)};e[o]={any:()=>w(r,"pool-0",{attempts:1}),get:a=>S(r,s,a,{attempts:1}),pool:()=>w(r,"pool-0",{attempts:1})}}return e};export{G as createContainerContext,J as createContainerTestContext};