@lunora/container 1.0.0-alpha.10 → 1.0.0-alpha.12

package/README.md

@@ -10,6 +10,8 @@
 
 <!-- END_PACKAGE_OG_IMAGE_PLACEHOLDER -->
 
+> **Experimental** — this package is outside the Lunora 1.0 stability promise: its API may change in any release, without a major version bump.
+
 <br />
 
 <div align="center">

package/dist/bridge.d.mts

@@ -1,5 +1,8 @@
 import { LunoraError } from '@lunora/errors';
-/** A `fetch` implementation — defaults to the runtime global. */
+/**
+* A `fetch` implementation — defaults to the runtime global.
+* @experimental
+*/
 type FetchLike = (input: string, init: {
   body: string;
   headers: Record<string, string>;
@@ -10,6 +13,10 @@ type FetchLike = (input: string, init: {
   status: number;
   statusText?: string;
 }>;
+/**
+* `ContainerBridgeOptions` is part of the experimental `@lunora/container` API and may change without a major version bump.
+* @experimental
+*/
 interface ContainerBridgeOptions {
   /**
   * Base URL of the deployed Lunora Worker (no trailing `/_lunora/rpc`), e.g.
@@ -26,7 +33,10 @@ interface ContainerBridgeOptions {
   */
   token?: string;
 }
-/** Thrown when a Lunora function returns an error envelope. A `LunoraError` subclass carrying the wire `code`. */
+/**
+* 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);
 }
@@ -36,6 +46,7 @@ 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?: {
@@ -56,6 +67,10 @@ type ResultOfReference<Reference> = Reference extends {
     returns: infer Result;
   };
 } ? 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. */
   action: <Result = unknown>(functionPath: string, args?: Record<string, unknown>, shardKey?: string) => Promise<Result>;
@@ -85,6 +100,7 @@ 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,5 +1,8 @@
 import { LunoraError } from '@lunora/errors';
-/** A `fetch` implementation — defaults to the runtime global. */
+/**
+* A `fetch` implementation — defaults to the runtime global.
+* @experimental
+*/
 type FetchLike = (input: string, init: {
   body: string;
   headers: Record<string, string>;
@@ -10,6 +13,10 @@ type FetchLike = (input: string, init: {
   status: number;
   statusText?: string;
 }>;
+/**
+* `ContainerBridgeOptions` is part of the experimental `@lunora/container` API and may change without a major version bump.
+* @experimental
+*/
 interface ContainerBridgeOptions {
   /**
   * Base URL of the deployed Lunora Worker (no trailing `/_lunora/rpc`), e.g.
@@ -26,7 +33,10 @@ interface ContainerBridgeOptions {
   */
   token?: string;
 }
-/** Thrown when a Lunora function returns an error envelope. A `LunoraError` subclass carrying the wire `code`. */
+/**
+* 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);
 }
@@ -36,6 +46,7 @@ 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?: {
@@ -56,6 +67,10 @@ type ResultOfReference<Reference> = Reference extends {
     returns: infer Result;
   };
 } ? 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. */
   action: <Result = unknown>(functionPath: string, args?: Record<string, unknown>, shardKey?: string) => Promise<Result>;
@@ -85,6 +100,7 @@ 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,5 +1,5 @@
 import { DurableObject, WorkerEntrypoint } from 'cloudflare:workers';
-import { a as ContainerDefinition, D as DurableObjectJurisdiction } from "../packem_shared/jurisdiction.d-TwTGkgTg.mjs";
+import { a as ContainerDefinition, D as DurableObjectJurisdiction } from "../packem_shared/jurisdiction.d-CdUpqfc-.mjs";
 /**
  * ContainerStartOptions as they come from worker types
  */
@@ -500,6 +500,7 @@ type DurableObjectContext = ConstructorParameters<typeof Container>[0];
 *     }
 * }
 * ```
+* @experimental
 */
 declare class LunoraContainer<Env = unknown> extends Container<Env> {
   /**

package/dist/do/index.d.ts

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

package/dist/index.d.mts

@@ -1,6 +1,9 @@
-import { D as DurableObjectJurisdiction, C as ContainerConfig, a as ContainerDefinition, b as ContainerImageSource, N as NormalizedContainerImage } from "./packem_shared/jurisdiction.d-TwTGkgTg.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-TwTGkgTg.mjs";
-/** Options for explicitly starting an instance (mirrors `@cloudflare/containers`). */
+import { D as DurableObjectJurisdiction, C as ContainerConfig, a as ContainerDefinition, b as ContainerImageSource, N as NormalizedContainerImage } from "./packem_shared/jurisdiction.d-CdUpqfc-.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-CdUpqfc-.mjs";
+/**
+* Options for explicitly starting an instance (mirrors `@cloudflare/containers`).
+* @experimental
+*/
 interface ContainerStartOptions {
   /** Override outbound internet access for this start. */
   enableInternet?: boolean;
@@ -11,7 +14,10 @@ interface ContainerStartOptions {
   /** Metadata labels attached for metrics/observability. */
   labels?: Record<string, string>;
 }
-/** A container instance's runtime state, as returned by `getState()`. Structural — the platform adds fields over time. */
+/**
+* A container instance's runtime state, as returned by `getState()`. Structural — the platform adds fields over time.
+* @experimental
+*/
 interface ContainerInstanceState {
   [key: string]: unknown;
   /** Process exit code, present once the instance has `stopped_with_code`. */
@@ -36,7 +42,10 @@ interface ContainerStubLike {
   start?: (options?: ContainerStartOptions) => Promise<void>;
   stop?: (signal?: number | string) => Promise<void>;
 }
-/** What the client needs from a Durable Object namespace binding. */
+/**
+* What the client needs from a Durable Object namespace binding.
+* @experimental
+*/
 interface ContainerNamespaceLike {
   get: (id: unknown) => ContainerStubLike;
   idFromName: (name: string) => unknown;
@@ -46,7 +55,10 @@ interface ContainerNamespaceLike {
   */
   jurisdiction?: (jurisdiction: DurableObjectJurisdiction) => ContainerNamespaceLike;
 }
-/** A handle on one container instance (one Durable Object). */
+/**
+* A handle on one container instance (one Durable Object).
+* @experimental
+*/
 interface ContainerHandle {
   /**
   * Send an HTTP (or WebSocket-upgrade) request to the container. A path
@@ -70,6 +82,7 @@ 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). */
@@ -104,6 +117,7 @@ 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. */
@@ -119,7 +133,10 @@ interface ContainerEgressControls {
   /** Replace the entire deny-list. */
   setDenied: (hosts: ReadonlyArray<string>) => Promise<void>;
 }
-/** The per-definition accessor exposed as `ctx.containers.&lt;exportName>`. */
+/**
+* The per-definition accessor exposed as `ctx.containers.&lt;exportName>`.
+* @experimental
+*/
 interface ContainerAccessor {
   /**
   * A random instance from a fixed pool of `count` (defaults to the
@@ -159,7 +176,10 @@ interface ContainerAccessor {
   */
   pool: (options?: PoolOptions) => ContainerHandle;
 }
-/** Tuning for a pooled, retrying container handle. See {@link ContainerAccessor.pool}. */
+/**
+* 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. */
   attempts?: number;
@@ -185,6 +205,7 @@ 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 {
   /**
@@ -198,7 +219,10 @@ interface InstanceRetryOptions {
   /** Upper bound on a single backoff sleep, in ms. Default {@link DEFAULT_MAX_BACKOFF_MS} (30s). */
   maxBackoffMs?: number;
 }
-/** Wiring info for one definition, emitted by codegen into the generated DO. */
+/**
+* Wiring info for one definition, emitted by codegen into the generated DO.
+* @experimental
+*/
 interface ContainerBindingSpec {
   /** Durable Object binding name, e.g. `CONTAINER_TRANSCODER`. */
   binding: string;
@@ -209,13 +233,20 @@ interface ContainerBindingSpec {
 }
 /**
 * Build the `ctx.containers` record from the Worker `env`. Called by the
-* generated ShardDO with the specs codegen derived from
-* `lunora/containers.ts`. A missing binding doesn't throw here — only when the
-* handle is actually used — so one unprovisioned container never breaks
-* unrelated functions.
+* generated ShardDO with the specs codegen derived from `lunora/containers.ts`.
+* A missing binding doesn't throw here — only when the handle is actually used —
+* so one unprovisioned container never breaks unrelated functions.
+*
+* `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
 */
-declare const createContainerContext: (env: Record<string, unknown>, specs: ReadonlyArray<ContainerBindingSpec>, jurisdiction?: DurableObjectJurisdiction) => Record<string, ContainerAccessor>;
-/** A test handler: receives the request plus the targeted instance name. */
 type ContainerTestHandler = (request: Request, instance: {
   name: string;
 }) => Promise<Response> | Response;
@@ -229,6 +260,7 @@ type ContainerTestHandler = (request: Request, instance: {
 *     transcoder: (request) => new Response("ok"),
 * });
 * ```
+* @experimental
 */
 declare const createContainerTestContext: (handlers: Record<string, ContainerTestHandler>) => Record<string, ContainerAccessor>;
 /**
@@ -240,6 +272,7 @@ 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 `&lt;dir>/Dockerfile`.
+* @experimental
 */
 declare const normalizeContainerImage: (image: ContainerImageSource) => NormalizedContainerImage;
 /**
@@ -247,6 +280,7 @@ 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;
 /**
@@ -254,6 +288,7 @@ 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;
 /**
@@ -262,16 +297,25 @@ 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). */
+/**
+* True when a value is a `defineContainer` result (the runtime brand check).
+* @experimental
+*/
 declare const isContainerDefinition: (value: unknown) => value is ContainerDefinition;
 /**
 * The container's full environment at instance start: the static `env` block
 * 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 { type ContainerAccessor, type ContainerBindingSpec, type ContainerConfig, type ContainerDefinition, type ContainerEgressControls, type ContainerHandle, type ContainerImageSource, type ContainerInstanceHandle, type ContainerInstanceState, type ContainerNamespaceLike, type ContainerStartOptions, type ContainerTestHandler, type DurableObjectJurisdiction, type InstanceRetryOptions, type NormalizedContainerImage, type PoolOptions, containerBindingName, containerBuildTag, containerClassName, createContainerContext, createContainerTestContext, defineContainer, isContainerDefinition, normalizeContainerImage, resolveContainerEnvVariables as resolveContainerEnvVars };

package/dist/index.d.ts

@@ -1,6 +1,9 @@
-import { D as DurableObjectJurisdiction, C as ContainerConfig, a as ContainerDefinition, b as ContainerImageSource, N as NormalizedContainerImage } from "./packem_shared/jurisdiction.d-TwTGkgTg.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-TwTGkgTg.js";
-/** Options for explicitly starting an instance (mirrors `@cloudflare/containers`). */
+import { D as DurableObjectJurisdiction, C as ContainerConfig, a as ContainerDefinition, b as ContainerImageSource, N as NormalizedContainerImage } from "./packem_shared/jurisdiction.d-CdUpqfc-.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-CdUpqfc-.js";
+/**
+* Options for explicitly starting an instance (mirrors `@cloudflare/containers`).
+* @experimental
+*/
 interface ContainerStartOptions {
   /** Override outbound internet access for this start. */
   enableInternet?: boolean;
@@ -11,7 +14,10 @@ interface ContainerStartOptions {
   /** Metadata labels attached for metrics/observability. */
   labels?: Record<string, string>;
 }
-/** A container instance's runtime state, as returned by `getState()`. Structural — the platform adds fields over time. */
+/**
+* A container instance's runtime state, as returned by `getState()`. Structural — the platform adds fields over time.
+* @experimental
+*/
 interface ContainerInstanceState {
   [key: string]: unknown;
   /** Process exit code, present once the instance has `stopped_with_code`. */
@@ -36,7 +42,10 @@ interface ContainerStubLike {
   start?: (options?: ContainerStartOptions) => Promise<void>;
   stop?: (signal?: number | string) => Promise<void>;
 }
-/** What the client needs from a Durable Object namespace binding. */
+/**
+* What the client needs from a Durable Object namespace binding.
+* @experimental
+*/
 interface ContainerNamespaceLike {
   get: (id: unknown) => ContainerStubLike;
   idFromName: (name: string) => unknown;
@@ -46,7 +55,10 @@ interface ContainerNamespaceLike {
   */
   jurisdiction?: (jurisdiction: DurableObjectJurisdiction) => ContainerNamespaceLike;
 }
-/** A handle on one container instance (one Durable Object). */
+/**
+* A handle on one container instance (one Durable Object).
+* @experimental
+*/
 interface ContainerHandle {
   /**
   * Send an HTTP (or WebSocket-upgrade) request to the container. A path
@@ -70,6 +82,7 @@ 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). */
@@ -104,6 +117,7 @@ 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. */
@@ -119,7 +133,10 @@ interface ContainerEgressControls {
   /** Replace the entire deny-list. */
   setDenied: (hosts: ReadonlyArray<string>) => Promise<void>;
 }
-/** The per-definition accessor exposed as `ctx.containers.&lt;exportName>`. */
+/**
+* The per-definition accessor exposed as `ctx.containers.&lt;exportName>`.
+* @experimental
+*/
 interface ContainerAccessor {
   /**
   * A random instance from a fixed pool of `count` (defaults to the
@@ -159,7 +176,10 @@ interface ContainerAccessor {
   */
   pool: (options?: PoolOptions) => ContainerHandle;
 }
-/** Tuning for a pooled, retrying container handle. See {@link ContainerAccessor.pool}. */
+/**
+* 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. */
   attempts?: number;
@@ -185,6 +205,7 @@ 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 {
   /**
@@ -198,7 +219,10 @@ interface InstanceRetryOptions {
   /** Upper bound on a single backoff sleep, in ms. Default {@link DEFAULT_MAX_BACKOFF_MS} (30s). */
   maxBackoffMs?: number;
 }
-/** Wiring info for one definition, emitted by codegen into the generated DO. */
+/**
+* Wiring info for one definition, emitted by codegen into the generated DO.
+* @experimental
+*/
 interface ContainerBindingSpec {
   /** Durable Object binding name, e.g. `CONTAINER_TRANSCODER`. */
   binding: string;
@@ -209,13 +233,20 @@ interface ContainerBindingSpec {
 }
 /**
 * Build the `ctx.containers` record from the Worker `env`. Called by the
-* generated ShardDO with the specs codegen derived from
-* `lunora/containers.ts`. A missing binding doesn't throw here — only when the
-* handle is actually used — so one unprovisioned container never breaks
-* unrelated functions.
+* generated ShardDO with the specs codegen derived from `lunora/containers.ts`.
+* A missing binding doesn't throw here — only when the handle is actually used —
+* so one unprovisioned container never breaks unrelated functions.
+*
+* `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
 */
-declare const createContainerContext: (env: Record<string, unknown>, specs: ReadonlyArray<ContainerBindingSpec>, jurisdiction?: DurableObjectJurisdiction) => Record<string, ContainerAccessor>;
-/** A test handler: receives the request plus the targeted instance name. */
 type ContainerTestHandler = (request: Request, instance: {
   name: string;
 }) => Promise<Response> | Response;
@@ -229,6 +260,7 @@ type ContainerTestHandler = (request: Request, instance: {
 *     transcoder: (request) => new Response("ok"),
 * });
 * ```
+* @experimental
 */
 declare const createContainerTestContext: (handlers: Record<string, ContainerTestHandler>) => Record<string, ContainerAccessor>;
 /**
@@ -240,6 +272,7 @@ 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 `&lt;dir>/Dockerfile`.
+* @experimental
 */
 declare const normalizeContainerImage: (image: ContainerImageSource) => NormalizedContainerImage;
 /**
@@ -247,6 +280,7 @@ 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;
 /**
@@ -254,6 +288,7 @@ 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;
 /**
@@ -262,16 +297,25 @@ 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). */
+/**
+* True when a value is a `defineContainer` result (the runtime brand check).
+* @experimental
+*/
 declare const isContainerDefinition: (value: unknown) => value is ContainerDefinition;
 /**
 * The container's full environment at instance start: the static `env` block
 * 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 { type ContainerAccessor, type ContainerBindingSpec, type ContainerConfig, type ContainerDefinition, type ContainerEgressControls, type ContainerHandle, type ContainerImageSource, type ContainerInstanceHandle, type ContainerInstanceState, type ContainerNamespaceLike, type ContainerStartOptions, type ContainerTestHandler, type DurableObjectJurisdiction, type InstanceRetryOptions, type NormalizedContainerImage, type PoolOptions, containerBindingName, containerBuildTag, containerClassName, createContainerContext, createContainerTestContext, defineContainer, isContainerDefinition, normalizeContainerImage, resolveContainerEnvVariables as resolveContainerEnvVars };

package/dist/index.mjs

@@ -1,2 +1,2 @@
-export { createContainerContext, createContainerTestContext } from './packem_shared/createContainerContext-CIVzsY5m.mjs';
+export { createContainerContext, createContainerTestContext } from './packem_shared/createContainerContext-Cg53QGdf.mjs';
 export { containerBindingName, containerBuildTag, containerClassName, defineContainer, isContainerDefinition, normalizeContainerImage, resolveContainerEnvVars } from './packem_shared/containerBindingName-BiTrAF1J.mjs';

package/dist/otel.d.mts

@@ -1,4 +1,7 @@
-/** An attribute value carried on a span or log. */
+/**
+* An attribute value carried on a span or log.
+* @experimental
+*/
 type ContainerAttributeValue = boolean | number | string;
 /**
 * A `fetch` implementation — defaults to the runtime global. The exporter passes
@@ -6,6 +9,7 @@ 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;
@@ -19,7 +23,10 @@ type OtelFetchLike = (input: string, init: {
   ok: boolean;
   status: number;
 }>;
-/** A single span the container process asks the exporter to record. */
+/**
+* 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). */
   attributes?: Record<string, ContainerAttributeValue>;
@@ -35,7 +42,10 @@ interface ContainerSpanInput {
   /** Wall-clock millis when the operation started. */
   startMs: number;
 }
-/** A single log line the container process asks the exporter to record. */
+/**
+* A single log line the container process asks the exporter to record.
+* @experimental
+*/
 interface ContainerLogInput {
   /** Attributes attached to the log record. */
   attributes?: Record<string, ContainerAttributeValue>;
@@ -46,7 +56,10 @@ interface ContainerLogInput {
   /** Wall-clock millis the line was emitted; defaults to now. */
   ts?: number;
 }
-/** Options for {@link createContainerTelemetry}. */
+/**
+* Options for {@link createContainerTelemetry}.
+* @experimental
+*/
 interface ContainerTelemetryOptions {
   /** Base OTLP collector endpoint; defaults to the `LUNORA_OTLP_ENDPOINT` env var. */
   endpoint?: string;
@@ -62,8 +75,34 @@ interface ContainerTelemetryOptions {
   timeoutMs?: number;
   /** Bearer token sent as an `Authorization: Bearer` header; defaults to the `LUNORA_OTLP_TOKEN` env var. */
   token?: string;
+  /**
+  * W3C `traceparent` of the Worker RPC that invoked this container; defaults to
+  * the `LUNORA_TRACEPARENT` env var. When present (and well-formed) every span
+  * inherits its trace id and hangs off its span id, so container spans stitch
+  * under the Worker's trace instead of forming a fresh, disconnected trace.
+  *
+  * `@lunora/container` stamps this trace context as the **`traceparent` request
+  * header** on every proxied fetch (`ctx.containers.&lt;name>.…`), so a container
+  * that serves many requests should read it per request and create a telemetry
+  * instance scoped to that request — the trace context differs each call, so a
+  * single process-lifetime instance can't carry it:
+  *
+  * ```ts
+  * // inside the container's request handler
+  * const telemetry = createContainerTelemetry({ traceparent: request.headers.get("traceparent") ?? undefined });
+  * await telemetry.trace("transcode", () => transcode(job));
+  * await telemetry.flush();
+  * ```
+  *
+  * The `LUNORA_TRACEPARENT` env fallback fits a one-shot container that
+  * processes a single job per start (the value is fixed for the process).
+  */
+  traceparent?: string;
 }
-/** The exporter handle {@link createContainerTelemetry} returns. */
+/**
+* The exporter handle {@link createContainerTelemetry} returns.
+* @experimental
+*/
 interface ContainerTelemetry {
   /** Record one log line (no-op when disabled). */
   emitLog: (log: ContainerLogInput) => void;
@@ -90,6 +129,7 @@ interface ContainerTelemetry {
 * false`): `emitSpan`/`emitLog` no-op and `trace` still runs its work but records
 * nothing — so the same code runs unchanged locally and in the cloud.
 * @param options Exporter options; every field falls back to a `LUNORA_*` env var.
+* @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,4 +1,7 @@
-/** An attribute value carried on a span or log. */
+/**
+* An attribute value carried on a span or log.
+* @experimental
+*/
 type ContainerAttributeValue = boolean | number | string;
 /**
 * A `fetch` implementation — defaults to the runtime global. The exporter passes
@@ -6,6 +9,7 @@ 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;
@@ -19,7 +23,10 @@ type OtelFetchLike = (input: string, init: {
   ok: boolean;
   status: number;
 }>;
-/** A single span the container process asks the exporter to record. */
+/**
+* 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). */
   attributes?: Record<string, ContainerAttributeValue>;
@@ -35,7 +42,10 @@ interface ContainerSpanInput {
   /** Wall-clock millis when the operation started. */
   startMs: number;
 }
-/** A single log line the container process asks the exporter to record. */
+/**
+* A single log line the container process asks the exporter to record.
+* @experimental
+*/
 interface ContainerLogInput {
   /** Attributes attached to the log record. */
   attributes?: Record<string, ContainerAttributeValue>;
@@ -46,7 +56,10 @@ interface ContainerLogInput {
   /** Wall-clock millis the line was emitted; defaults to now. */
   ts?: number;
 }
-/** Options for {@link createContainerTelemetry}. */
+/**
+* Options for {@link createContainerTelemetry}.
+* @experimental
+*/
 interface ContainerTelemetryOptions {
   /** Base OTLP collector endpoint; defaults to the `LUNORA_OTLP_ENDPOINT` env var. */
   endpoint?: string;
@@ -62,8 +75,34 @@ interface ContainerTelemetryOptions {
   timeoutMs?: number;
   /** Bearer token sent as an `Authorization: Bearer` header; defaults to the `LUNORA_OTLP_TOKEN` env var. */
   token?: string;
+  /**
+  * W3C `traceparent` of the Worker RPC that invoked this container; defaults to
+  * the `LUNORA_TRACEPARENT` env var. When present (and well-formed) every span
+  * inherits its trace id and hangs off its span id, so container spans stitch
+  * under the Worker's trace instead of forming a fresh, disconnected trace.
+  *
+  * `@lunora/container` stamps this trace context as the **`traceparent` request
+  * header** on every proxied fetch (`ctx.containers.&lt;name>.…`), so a container
+  * that serves many requests should read it per request and create a telemetry
+  * instance scoped to that request — the trace context differs each call, so a
+  * single process-lifetime instance can't carry it:
+  *
+  * ```ts
+  * // inside the container's request handler
+  * const telemetry = createContainerTelemetry({ traceparent: request.headers.get("traceparent") ?? undefined });
+  * await telemetry.trace("transcode", () => transcode(job));
+  * await telemetry.flush();
+  * ```
+  *
+  * The `LUNORA_TRACEPARENT` env fallback fits a one-shot container that
+  * processes a single job per start (the value is fixed for the process).
+  */
+  traceparent?: string;
 }
-/** The exporter handle {@link createContainerTelemetry} returns. */
+/**
+* The exporter handle {@link createContainerTelemetry} returns.
+* @experimental
+*/
 interface ContainerTelemetry {
   /** Record one log line (no-op when disabled). */
   emitLog: (log: ContainerLogInput) => void;
@@ -90,6 +129,7 @@ interface ContainerTelemetry {
 * false`): `emitSpan`/`emitLog` no-op and `trace` still runs its work but records
 * nothing — so the same code runs unchanged locally and in the cloud.
 * @param options Exporter options; every field falls back to a `LUNORA_*` env var.
+* @experimental
 */
 declare const createContainerTelemetry: (options?: ContainerTelemetryOptions) => ContainerTelemetry;
 export { type ContainerAttributeValue, type ContainerLogInput, type ContainerSpanInput, type ContainerTelemetry, type ContainerTelemetryOptions, type OtelFetchLike, createContainerTelemetry };

package/dist/otel.mjs

@@ -20,6 +20,19 @@ const otlpRandomHex = (bytes) => {
   }
   return hex;
 };
+const HEX_ONLY = /^[0-9a-f]+$/;
+const parseTraceparent = (header) => {
+  if (header === null || header === void 0) {
+    return void 0;
+  }
+  const parts = header.trim().toLowerCase().split("-");
+  const [version, traceId, parentSpanId, flags] = parts;
+  if (parts.length < 4 || version === void 0 || version.length !== 2 || !HEX_ONLY.test(version) || version === "ff" || // Version 00 forbids trailing fields; only a future version may carry them.
+  version === "00" && parts.length !== 4 || traceId === void 0 || parentSpanId === void 0 || flags === void 0 || flags.length !== 2 || !HEX_ONLY.test(flags) || traceId.length !== 32 || parentSpanId.length !== 16 || !HEX_ONLY.test(traceId) || !HEX_ONLY.test(parentSpanId) || traceId === "00000000000000000000000000000000" || parentSpanId === "0000000000000000") {
+    return void 0;
+  }
+  return { parentSpanId, traceId };
+};
 const encodeAttribute = (key, value) => {
   if (typeof value === "boolean") {
     return { key, value: { boolValue: value } };
@@ -96,7 +109,7 @@ const resolveFetch = (injected) => {
   }
   return void 0;
 };
-const traceBody = (span, serviceName) => {
+const traceBody = (span, serviceName, parent) => {
   const attributes = encodeAttributes(span.attributes);
   if (span.error?.type !== void 0) {
     attributes.push(encodeAttribute("error.type", span.error.type));
@@ -107,11 +120,14 @@ const traceBody = (span, serviceName) => {
     // SPAN_KIND_INTERNAL — the container's own work, not a server/client edge.
     kind: 1,
     name: span.name,
+    // Always the span's own (child) id; with a parent, hang it off the parent
+    // span and inherit the parent's trace id so the spans stitch into one trace.
+    ...parent === void 0 ? {} : { parentSpanId: parent.parentSpanId },
     spanId: otlpRandomHex(8),
     startTimeUnixNano: otlpUnixNano(span.startMs),
     // STATUS_CODE_OK (1) / STATUS_CODE_ERROR (2).
     status: span.error === void 0 ? { code: 1 } : { code: 2, message: span.error.message },
-    traceId: otlpRandomHex(16)
+    traceId: parent?.traceId ?? otlpRandomHex(16)
   };
   return wrapResourceSpans(otlpSpan, "@lunora/container", serviceName);
 };
@@ -131,6 +147,7 @@ const createContainerTelemetry = (options = {}) => {
   const enabled = endpoint !== void 0 && endpoint.length > 0;
   const token = options.token ?? readEnv("LUNORA_OTLP_TOKEN");
   const serviceName = options.serviceName ?? readEnv("LUNORA_SERVICE_NAME") ?? "lunora-container";
+  const parent = parseTraceparent(options.traceparent ?? readEnv("LUNORA_TRACEPARENT"));
   const timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
   const fetchImpl = resolveFetch(options.fetch);
   const headers = mergeHeaders({ "content-type": "application/json" }, options.headers, token);
@@ -169,7 +186,7 @@ const createContainerTelemetry = (options = {}) => {
     if (!enabled) {
       return;
     }
-    send(tracesUrl, traceBody(span, serviceName));
+    send(tracesUrl, traceBody(span, serviceName, parent));
   };
   const emitLog = (log) => {
     if (!enabled) {

package/dist/packem_shared/{createContainerContext-CIVzsY5m.mjs → createContainerContext-Cg53QGdf.mjs}

@@ -7,11 +7,14 @@ const DEFAULT_MAX_BACKOFF_MS = 3e4;
 const DEFAULT_COLD_START_ATTEMPTS = 3;
 const DEFAULT_COLD_START_BACKOFF_MS = 500;
 const TARGET_PORT_HEADER = "cf-container-target-port";
-const toRequest = (input, init, port) => {
+const toRequest = (input, init, port, traceparent) => {
   const request = typeof input === "string" && input.startsWith("/") ? new Request(`http://container${input}`, init) : new Request(input, init);
   if (port !== void 0) {
     request.headers.set(TARGET_PORT_HEADER, String(port));
   }
+  if (traceparent !== void 0) {
+    request.headers.set("traceparent", traceparent);
+  }
   return request;
 };
 const sleep = async (ms) => {
@@ -62,7 +65,7 @@ const isColdStartTransient = async (response) => {
     return false;
   }
 };
-const coldStartRetryingHandle = (send, options = {}, port) => {
+const coldStartRetryingHandle = (send, options = {}, port, traceparent) => {
   const attempts = Math.max(1, options.attempts ?? DEFAULT_COLD_START_ATTEMPTS);
   const baseBackoff = options.backoffMs ?? DEFAULT_COLD_START_BACKOFF_MS;
   const maxBackoff = options.maxBackoffMs ?? DEFAULT_MAX_BACKOFF_MS;
@@ -76,7 +79,7 @@ const coldStartRetryingHandle = (send, options = {}, port) => {
           await sleep(Math.min(baseBackoff * 2 ** (attempt - 1), maxBackoff));
         }
         try {
-          const response = await send(toRequest(input, init, port));
+          const response = await send(toRequest(input, init, port, traceparent));
           if (isLastAttempt || !await isColdStartTransient(response)) {
             return response;
           }
@@ -89,10 +92,10 @@ const coldStartRetryingHandle = (send, options = {}, port) => {
       }
       throw lastError instanceof Error ? lastError : new Error("ctx.containers: cold-start retry exhausted");
     },
-    port: (targetPort) => coldStartRetryingHandle(send, options, targetPort)
+    port: (targetPort) => coldStartRetryingHandle(send, options, targetPort, traceparent)
   };
 };
-const handleFor = (namespace, instanceName, options) => coldStartRetryingHandle(async (request) => namespace.get(namespace.idFromName(instanceName)).fetch(request), options);
+const handleFor = (namespace, instanceName, options, traceparent) => coldStartRetryingHandle(async (request) => namespace.get(namespace.idFromName(instanceName)).fetch(request), options, void 0, traceparent);
 const lifecycleCall = async (stub, method, binding, argument) => {
   const rpc = stub[method];
   if (typeof rpc !== "function") {
@@ -110,10 +113,10 @@ const egressControlsFor = (stub, binding) => {
     setDenied: async (hosts) => lifecycleCall(stub(), "setDeniedHosts", binding, [...hosts])
   };
 };
-const instanceHandleFor = (namespace, spec, instanceName, options) => {
+const instanceHandleFor = (namespace, spec, instanceName, options, traceparent) => {
   const stub = () => namespace.get(namespace.idFromName(instanceName));
   return {
-    ...coldStartRetryingHandle(async (request) => stub().fetch(request), options),
+    ...coldStartRetryingHandle(async (request) => stub().fetch(request), options, void 0, traceparent),
     destroy: async () => lifecycleCall(stub(), "destroy", spec.binding),
     egress: egressControlsFor(stub, spec.binding),
     getState: async () => lifecycleCall(stub(), "getState", spec.binding),
@@ -127,7 +130,7 @@ const randomPoolName = (size) => (
   `pool-${String(Math.floor(Math.random() * size))}`
 );
 const retryOnServerError = (response) => response.status >= 500;
-const poolHandleFor = (namespace, spec, options = {}, port) => {
+const poolHandleFor = (namespace, spec, options = {}, port, traceparent) => {
   const size = options.size ?? spec.maxInstances ?? DEFAULT_POOL_SIZE;
   const attempts = Math.max(1, options.attempts ?? 3);
   const baseBackoff = options.backoffMs ?? 100;
@@ -141,7 +144,7 @@ const poolHandleFor = (namespace, spec, options = {}, port) => {
         if (attempt > 0) {
           await sleep(Math.min(baseBackoff * 2 ** (attempt - 1), maxBackoff));
         }
-        const request = toRequest(input, init, port);
+        const request = toRequest(input, init, port, traceparent);
         try {
           const response = await namespace.get(namespace.idFromName(randomPoolName(size))).fetch(request);
           if (attempt === totalAttempts - 1 || !shouldRetry(response)) {
@@ -153,14 +156,14 @@ const poolHandleFor = (namespace, spec, options = {}, port) => {
       }
       throw lastError instanceof Error ? lastError : new Error(`ctx.containers.${spec.exportName}.pool(): all ${String(totalAttempts)} attempts failed`);
     },
-    port: (targetPort) => poolHandleFor(namespace, spec, options, targetPort)
+    port: (targetPort) => poolHandleFor(namespace, spec, options, targetPort, traceparent)
   };
 };
-const accessorFor = (namespace, spec) => {
+const accessorFor = (namespace, spec, traceparent) => {
   return {
-    any: (count, options) => handleFor(namespace, randomPoolName(count ?? spec.maxInstances ?? DEFAULT_POOL_SIZE), options),
-    get: (name, options) => instanceHandleFor(namespace, spec, name, options),
-    pool: (options) => poolHandleFor(namespace, spec, options)
+    any: (count, options) => handleFor(namespace, randomPoolName(count ?? spec.maxInstances ?? DEFAULT_POOL_SIZE), options, traceparent),
+    get: (name, options) => instanceHandleFor(namespace, spec, name, options, traceparent),
+    pool: (options) => poolHandleFor(namespace, spec, options, void 0, traceparent)
   };
 };
 const missingBindingAccessor = (spec) => {
@@ -172,11 +175,11 @@ const missingBindingAccessor = (spec) => {
   };
   return { any: fail, get: fail, pool: fail };
 };
-const createContainerContext = (env, specs, jurisdiction) => {
+const createContainerContext = (env, specs, jurisdiction, traceparent) => {
   const containers = {};
   for (const spec of specs) {
     const binding = env[spec.binding];
-    containers[spec.exportName] = binding && typeof binding.idFromName === "function" && typeof binding.get === "function" ? accessorFor(applyJurisdiction(binding, jurisdiction), spec) : missingBindingAccessor(spec);
+    containers[spec.exportName] = binding && typeof binding.idFromName === "function" && typeof binding.get === "function" ? accessorFor(applyJurisdiction(binding, jurisdiction), spec, traceparent) : missingBindingAccessor(spec);
   }
   return containers;
 };

package/dist/packem_shared/{jurisdiction.d-TwTGkgTg.d.mts → jurisdiction.d-CdUpqfc-.d.mts}

@@ -5,12 +5,16 @@
 * it is safe to import from Node tooling (codegen, the config layer) as well
 * as from worker code.
 */
-/** Named instance types Cloudflare Containers provides. */
+/**
+* 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). */
@@ -20,8 +24,15 @@ interface CustomContainerInstanceType {
   /** vCPU count. Cloudflare's default is 0.0625 (1/16 vCPU). */
   vcpu?: number;
 }
+/**
+* `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. */
+/**
+* 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`). */
   gracePeriodSeconds?: number;
@@ -32,6 +43,7 @@ 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;
@@ -41,6 +53,7 @@ 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;
@@ -50,6 +63,7 @@ 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;
 /**
@@ -62,6 +76,7 @@ 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). */
@@ -71,6 +86,10 @@ interface ContainerReadinessCheck {
   /** HTTP status that means "ready". Defaults to `200`. */
   status?: number;
 }
+/**
+* `ContainerConfig` is part of the experimental `@lunora/container` API and may change without a major version bump.
+* @experimental
+*/
 interface ContainerConfig {
   /**
   * Hostnames the container may reach **even when {@link ContainerConfig.enableInternet}
@@ -227,12 +246,16 @@ 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. */
   readonly isLunoraContainer: true;
 }
-/** A normalized image source, as written into `wrangler.jsonc`. */
+/**
+* A normalized image source, as written into `wrangler.jsonc`.
+* @experimental
+*/
 type NormalizedContainerImage = {
   /** Build context directory (wrangler `image_build_context`). */
   buildContext: string;
@@ -251,6 +274,7 @@ 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";
 /**

package/dist/packem_shared/{jurisdiction.d-TwTGkgTg.d.ts → jurisdiction.d-CdUpqfc-.d.ts}

@@ -5,12 +5,16 @@
 * it is safe to import from Node tooling (codegen, the config layer) as well
 * as from worker code.
 */
-/** Named instance types Cloudflare Containers provides. */
+/**
+* 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). */
@@ -20,8 +24,15 @@ interface CustomContainerInstanceType {
   /** vCPU count. Cloudflare's default is 0.0625 (1/16 vCPU). */
   vcpu?: number;
 }
+/**
+* `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. */
+/**
+* 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`). */
   gracePeriodSeconds?: number;
@@ -32,6 +43,7 @@ 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;
@@ -41,6 +53,7 @@ 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;
@@ -50,6 +63,7 @@ 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;
 /**
@@ -62,6 +76,7 @@ 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). */
@@ -71,6 +86,10 @@ interface ContainerReadinessCheck {
   /** HTTP status that means "ready". Defaults to `200`. */
   status?: number;
 }
+/**
+* `ContainerConfig` is part of the experimental `@lunora/container` API and may change without a major version bump.
+* @experimental
+*/
 interface ContainerConfig {
   /**
   * Hostnames the container may reach **even when {@link ContainerConfig.enableInternet}
@@ -227,12 +246,16 @@ 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. */
   readonly isLunoraContainer: true;
 }
-/** A normalized image source, as written into `wrangler.jsonc`. */
+/**
+* A normalized image source, as written into `wrangler.jsonc`.
+* @experimental
+*/
 type NormalizedContainerImage = {
   /** Build context directory (wrangler `image_build_context`). */
   buildContext: string;
@@ -251,6 +274,7 @@ 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";
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lunora/container",
-  "version": "1.0.0-alpha.10",
+  "version": "1.0.0-alpha.12",
   "description": "Cloudflare Containers for Lunora: defineContainer, generated Container DO classes, and the ctx.containers action surface",
   "keywords": [
     "cloudflare",
@@ -56,7 +56,7 @@
     "access": "public"
   },
   "dependencies": {
-    "@lunora/errors": "1.0.0-alpha.4"
+    "@lunora/errors": "1.0.0-alpha.5"
   },
   "engines": {
     "node": "^22.15.0 || >=24.11.0"