@lunora/container 0.0.0 → 1.0.0-alpha.1

package/dist/bridge.d.mts

@@ -0,0 +1,90 @@
+/** A `fetch` implementation — defaults to the runtime global. */
+type FetchLike = (input: string, init: {
+  body: string;
+  headers: Record<string, string>;
+  method: string;
+}) => Promise<{
+  json: () => Promise<unknown>;
+  ok: boolean;
+  status: number;
+  statusText?: string;
+}>;
+interface ContainerBridgeOptions {
+  /**
+  * Base URL of the deployed Lunora Worker (no trailing `/_lunora/rpc`), e.g.
+  * `https://my-app.workers.dev`. In a Lunora container, surface it as an
+  * `env` value on the definition.
+  */
+  baseUrl: string;
+  /** Injectable `fetch` (tests / non-global runtimes). Defaults to `globalThis.fetch`. */
+  fetch?: FetchLike;
+  /**
+  * Bearer token sent as `Authorization: Bearer &lt;token>`. Your Worker's
+  * `resolveIdentity` maps it to the identity the called functions run as.
+  * Pass it to the container as a `secret`, never bake it into the image.
+  */
+  token?: string;
+}
+/** Thrown when a Lunora function returns an error envelope. Carries the wire `code`. */
+declare class ContainerBridgeError extends Error {
+  readonly code: string;
+  constructor(code: string, message: string);
+}
+/**
+* Structural mirror of `@lunora/client`'s `FunctionReference` — the typed
+* handle the generated `_generated/api` object carries. Declared locally (not
+* 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.
+*/
+interface BridgeFunctionReference<Args = unknown, Result = unknown> {
+  readonly __lunoraPhantom?: {
+    args: Args;
+    returns: Result;
+  };
+  readonly __lunoraRef: string;
+}
+/** Infer the args type from a {@link BridgeFunctionReference} (or a `@lunora/client` reference). */
+type ArgsOfReference<Reference> = Reference extends {
+  __lunoraPhantom?: {
+    args: infer Args;
+  };
+} ? Args : never;
+/** Infer the result type from a {@link BridgeFunctionReference} (or a `@lunora/client` reference). */
+type ResultOfReference<Reference> = Reference extends {
+  __lunoraPhantom?: {
+    returns: infer Result;
+  };
+} ? Result : never;
+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>;
+  /** Call any Lunora function by `namespace:fn` path; the server resolves its kind. */
+  call: <Result = unknown>(functionPath: string, args?: Record<string, unknown>, shardKey?: string) => Promise<Result>;
+  /** Call a `mutation` by `namespace:fn` path. Alias of {@link ContainerBridge.call} for intent. */
+  mutation: <Result = unknown>(functionPath: string, args?: Record<string, unknown>, shardKey?: string) => Promise<Result>;
+  /** Call a `query` by `namespace:fn` path. Alias of {@link ContainerBridge.call} for intent. */
+  query: <Result = unknown>(functionPath: string, args?: Record<string, unknown>, shardKey?: string) => Promise<Result>;
+  /**
+  * Fully-typed call via a generated function reference. Pass a reference from
+  * the project's `_generated/api` (e.g. `api.messages.list`) and the args +
+  * result are inferred from it — the typed counterpart to {@link ContainerBridge.call}
+  * for JS/TS containers that can import the generated `api`.
+  */
+  run: <Reference extends BridgeFunctionReference>(reference: Reference, args: ArgsOfReference<Reference>, shardKey?: string) => Promise<ResultOfReference<Reference>>;
+}
+/**
+* Build a container→Lunora bridge bound to a Worker URL + token.
+*
+* ```ts
+* const lunora = createContainerBridge({ baseUrl: process.env.LUNORA_URL!, token: process.env.LUNORA_TOKEN });
+* const messages = await lunora.query("messages:list", { limit: 20 });
+* await lunora.mutation("messages:markProcessed", { id });
+* ```
+*
+* `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.
+*/
+declare const createContainerBridge: (options: ContainerBridgeOptions) => ContainerBridge;
+export { type BridgeFunctionReference, type ContainerBridge, ContainerBridgeError, type ContainerBridgeOptions, type FetchLike, createContainerBridge };

package/dist/bridge.d.ts

@@ -0,0 +1,90 @@
+/** A `fetch` implementation — defaults to the runtime global. */
+type FetchLike = (input: string, init: {
+  body: string;
+  headers: Record<string, string>;
+  method: string;
+}) => Promise<{
+  json: () => Promise<unknown>;
+  ok: boolean;
+  status: number;
+  statusText?: string;
+}>;
+interface ContainerBridgeOptions {
+  /**
+  * Base URL of the deployed Lunora Worker (no trailing `/_lunora/rpc`), e.g.
+  * `https://my-app.workers.dev`. In a Lunora container, surface it as an
+  * `env` value on the definition.
+  */
+  baseUrl: string;
+  /** Injectable `fetch` (tests / non-global runtimes). Defaults to `globalThis.fetch`. */
+  fetch?: FetchLike;
+  /**
+  * Bearer token sent as `Authorization: Bearer &lt;token>`. Your Worker's
+  * `resolveIdentity` maps it to the identity the called functions run as.
+  * Pass it to the container as a `secret`, never bake it into the image.
+  */
+  token?: string;
+}
+/** Thrown when a Lunora function returns an error envelope. Carries the wire `code`. */
+declare class ContainerBridgeError extends Error {
+  readonly code: string;
+  constructor(code: string, message: string);
+}
+/**
+* Structural mirror of `@lunora/client`'s `FunctionReference` — the typed
+* handle the generated `_generated/api` object carries. Declared locally (not
+* 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.
+*/
+interface BridgeFunctionReference<Args = unknown, Result = unknown> {
+  readonly __lunoraPhantom?: {
+    args: Args;
+    returns: Result;
+  };
+  readonly __lunoraRef: string;
+}
+/** Infer the args type from a {@link BridgeFunctionReference} (or a `@lunora/client` reference). */
+type ArgsOfReference<Reference> = Reference extends {
+  __lunoraPhantom?: {
+    args: infer Args;
+  };
+} ? Args : never;
+/** Infer the result type from a {@link BridgeFunctionReference} (or a `@lunora/client` reference). */
+type ResultOfReference<Reference> = Reference extends {
+  __lunoraPhantom?: {
+    returns: infer Result;
+  };
+} ? Result : never;
+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>;
+  /** Call any Lunora function by `namespace:fn` path; the server resolves its kind. */
+  call: <Result = unknown>(functionPath: string, args?: Record<string, unknown>, shardKey?: string) => Promise<Result>;
+  /** Call a `mutation` by `namespace:fn` path. Alias of {@link ContainerBridge.call} for intent. */
+  mutation: <Result = unknown>(functionPath: string, args?: Record<string, unknown>, shardKey?: string) => Promise<Result>;
+  /** Call a `query` by `namespace:fn` path. Alias of {@link ContainerBridge.call} for intent. */
+  query: <Result = unknown>(functionPath: string, args?: Record<string, unknown>, shardKey?: string) => Promise<Result>;
+  /**
+  * Fully-typed call via a generated function reference. Pass a reference from
+  * the project's `_generated/api` (e.g. `api.messages.list`) and the args +
+  * result are inferred from it — the typed counterpart to {@link ContainerBridge.call}
+  * for JS/TS containers that can import the generated `api`.
+  */
+  run: <Reference extends BridgeFunctionReference>(reference: Reference, args: ArgsOfReference<Reference>, shardKey?: string) => Promise<ResultOfReference<Reference>>;
+}
+/**
+* Build a container→Lunora bridge bound to a Worker URL + token.
+*
+* ```ts
+* const lunora = createContainerBridge({ baseUrl: process.env.LUNORA_URL!, token: process.env.LUNORA_TOKEN });
+* const messages = await lunora.query("messages:list", { limit: 20 });
+* await lunora.mutation("messages:markProcessed", { id });
+* ```
+*
+* `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.
+*/
+declare const createContainerBridge: (options: ContainerBridgeOptions) => ContainerBridge;
+export { type BridgeFunctionReference, type ContainerBridge, ContainerBridgeError, type ContainerBridgeOptions, type FetchLike, createContainerBridge };

package/dist/bridge.mjs

@@ -0,0 +1,76 @@
+const RPC_PATH = "/_lunora/rpc";
+class ContainerBridgeError extends Error {
+  code;
+  constructor(code, message) {
+    super(message);
+    this.name = "ContainerBridgeError";
+    this.code = code;
+  }
+}
+const joinUrl = (baseUrl, path) => {
+  let base = baseUrl;
+  while (base.endsWith("/")) {
+    base = base.slice(0, -1);
+  }
+  return `${base}${path}`;
+};
+const statusError = (functionPath, response) => new Error(
+  `createContainerBridge: request to "${functionPath}" failed (status ${String(response.status)}${response.statusText ? ` ${response.statusText}` : ""})`
+);
+const parseResponseBody = async (response, functionPath) => {
+  try {
+    return await response.json();
+  } catch {
+    if (!response.ok) {
+      throw statusError(functionPath, response);
+    }
+    throw new Error(`createContainerBridge: request to "${functionPath}" returned a non-JSON response (status ${String(response.status)})`);
+  }
+};
+const createContainerBridge = (options) => {
+  if (typeof options.baseUrl !== "string" || options.baseUrl.length === 0) {
+    throw new TypeError("createContainerBridge: `baseUrl` must be a non-empty Worker URL (e.g. https://my-app.workers.dev) — is the URL env var set?");
+  }
+  const fetchImpl = options.fetch ?? globalThis.fetch;
+  const call = async (functionPath, args = {}, shardKey) => {
+    if (typeof fetchImpl !== "function") {
+      throw new TypeError("createContainerBridge: no `fetch` available — pass `fetch` in options for this runtime.");
+    }
+    const headers = { "content-type": "application/json" };
+    if (options.token !== void 0) {
+      headers.authorization = `Bearer ${options.token}`;
+    }
+    const response = await fetchImpl(joinUrl(options.baseUrl, RPC_PATH), {
+      body: JSON.stringify({ args, functionPath, shardKey }),
+      headers,
+      method: "POST"
+    });
+    const body = await parseResponseBody(response, functionPath);
+    if (typeof body === "object" && body !== null && "error" in body) {
+      const { error } = body;
+      if (typeof error === "object" && error !== null) {
+        const { code, message } = error;
+        if (typeof code === "string" && typeof message === "string") {
+          throw new ContainerBridgeError(code, message);
+        }
+      }
+      let detail;
+      try {
+        detail = JSON.stringify(error);
+      } catch {
+        detail = String(error);
+      }
+      throw new Error(
+        `createContainerBridge: request to "${functionPath}" returned a malformed error envelope (status ${String(response.status)}): ${detail}`
+      );
+    }
+    if (!response.ok) {
+      throw statusError(functionPath, response);
+    }
+    return body.result;
+  };
+  const run = async (reference, args, shardKey) => call(reference.__lunoraRef, args, shardKey);
+  return { action: call, call, mutation: call, query: call, run };
+};
+
+export { ContainerBridgeError, createContainerBridge };

package/dist/do/index.d.mts

@@ -0,0 +1,43 @@
+import { Container, StopParams } from '@cloudflare/containers';
+import { C as ContainerDefinition } from "../packem_shared/types.d-D2l2SYol.mjs";
+type DurableObjectContext = ConstructorParameters<typeof Container>[0];
+/**
+* Base class for the generated Container DO classes. Applies a
+* `defineContainer` definition onto `@cloudflare/containers`' `Container`:
+* port, sleep timeout, internet access, and the container environment (static
+* `env` merged with the declared Worker secrets — a declared-but-unset secret
+* fails fast here rather than starting a container without its credential).
+*
+* Generated subclasses stay one line of behavior:
+*
+* ```ts
+* export class TranscoderContainer extends LunoraContainer {
+*     constructor(ctx: DurableObjectState, env: Env) {
+*         super(ctx, env, transcoder, "transcoder");
+*     }
+* }
+* ```
+*/
+declare class LunoraContainer<Env = unknown> extends Container<Env> {
+  /** The `lunora/containers.ts` export name, for lifecycle log correlation. */
+  private readonly lunoraName;
+  constructor(context: DurableObjectContext, env: Env, definition: ContainerDefinition, exportName?: string);
+  override onError(error: unknown): unknown;
+  override onStart(): Promise<void>;
+  override onStop(parameters: StopParams): Promise<void>;
+  /**
+  * Best-effort push of `envelope` into the root ShardDO's log buffer so it
+  * also appears in the Studio Logs panel (the terminal already has it via
+  * `emitContainerLifecycle`). Fire-and-forget and fully swallowed: a missing
+  * `SHARD` binding, a missing admin token, or a fetch failure NEVER throws
+  * out of a lifecycle hook — the `console` path stays the source of truth.
+  */
+  private surfaceInStudioLogs;
+  /**
+  * Per-instance correlation id: the Durable Object id, which Cloudflare also
+  * injects into the container as `CLOUDFLARE_DURABLE_OBJECT_ID`. Read
+  * defensively — the id shape varies and isn't worth crashing a hook over.
+  */
+  private instanceId;
+}
+export { LunoraContainer as default };

package/dist/do/index.d.ts

@@ -0,0 +1,43 @@
+import { Container, StopParams } from '@cloudflare/containers';
+import { C as ContainerDefinition } from "../packem_shared/types.d-D2l2SYol.js";
+type DurableObjectContext = ConstructorParameters<typeof Container>[0];
+/**
+* Base class for the generated Container DO classes. Applies a
+* `defineContainer` definition onto `@cloudflare/containers`' `Container`:
+* port, sleep timeout, internet access, and the container environment (static
+* `env` merged with the declared Worker secrets — a declared-but-unset secret
+* fails fast here rather than starting a container without its credential).
+*
+* Generated subclasses stay one line of behavior:
+*
+* ```ts
+* export class TranscoderContainer extends LunoraContainer {
+*     constructor(ctx: DurableObjectState, env: Env) {
+*         super(ctx, env, transcoder, "transcoder");
+*     }
+* }
+* ```
+*/
+declare class LunoraContainer<Env = unknown> extends Container<Env> {
+  /** The `lunora/containers.ts` export name, for lifecycle log correlation. */
+  private readonly lunoraName;
+  constructor(context: DurableObjectContext, env: Env, definition: ContainerDefinition, exportName?: string);
+  override onError(error: unknown): unknown;
+  override onStart(): Promise<void>;
+  override onStop(parameters: StopParams): Promise<void>;
+  /**
+  * Best-effort push of `envelope` into the root ShardDO's log buffer so it
+  * also appears in the Studio Logs panel (the terminal already has it via
+  * `emitContainerLifecycle`). Fire-and-forget and fully swallowed: a missing
+  * `SHARD` binding, a missing admin token, or a fetch failure NEVER throws
+  * out of a lifecycle hook — the `console` path stays the source of truth.
+  */
+  private surfaceInStudioLogs;
+  /**
+  * Per-instance correlation id: the Durable Object id, which Cloudflare also
+  * injects into the container as `CLOUDFLARE_DURABLE_OBJECT_ID`. Read
+  * defensively — the id shape varies and isn't worth crashing a hook over.
+  */
+  private instanceId;
+}
+export { LunoraContainer as default };

package/dist/do/index.mjs

@@ -0,0 +1,119 @@
+import { Container } from '@cloudflare/containers';
+import { resolveContainerEnvVars as resolveContainerEnvVariables } from '../packem_shared/containerBindingName-BGdSdFNA.mjs';
+
+const LUNORA_EVENT_SOURCE = "lunora";
+const buildContainerLifecycleEvent = (container, instance, event, message) => {
+  return {
+    container,
+    event,
+    instance,
+    level: event === "error" ? "error" : "info",
+    message,
+    source: LUNORA_EVENT_SOURCE,
+    ts: Date.now(),
+    type: "container"
+  };
+};
+const emitContainerLifecycle = (container, instance, event, message) => {
+  const envelope = buildContainerLifecycleEvent(container, instance, event, message);
+  const line = JSON.stringify(envelope);
+  if (event === "error") {
+    console.error(line);
+  } else {
+    console.log(line);
+  }
+  return envelope;
+};
+
+const RECORD_CONTAINER_EVENT_OP = "__lunora_admin__:recordContainerEvent";
+const ROOT_SHARD_NAME = "__root__";
+const isShardNamespace = (value) => {
+  if (value === null || typeof value !== "object") {
+    return false;
+  }
+  const candidate = value;
+  return typeof candidate.get === "function" && typeof candidate.idFromName === "function";
+};
+const resolveRootShard = (namespace) => {
+  if (typeof namespace.getByName === "function") {
+    return namespace.getByName(ROOT_SHARD_NAME);
+  }
+  return namespace.get(namespace.idFromName(ROOT_SHARD_NAME));
+};
+const reportContainerLifecycle = async (env, envelope) => {
+  try {
+    const envRecord = env ?? {};
+    const namespace = envRecord["SHARD"];
+    if (!isShardNamespace(namespace)) {
+      return;
+    }
+    const adminBearer = typeof envRecord["LUNORA_ADMIN_TOKEN"] === "string" ? envRecord["LUNORA_ADMIN_TOKEN"] : void 0;
+    if (!adminBearer || adminBearer.length === 0) {
+      return;
+    }
+    const request = new Request("https://shard.internal/rpc", {
+      body: JSON.stringify({ args: { event: envelope }, functionPath: RECORD_CONTAINER_EVENT_OP }),
+      headers: { authorization: `Bearer ${adminBearer}`, "content-type": "application/json" },
+      method: "POST"
+    });
+    await resolveRootShard(namespace).fetch(request);
+  } catch {
+  }
+};
+
+class LunoraContainer extends Container {
+  /** The `lunora/containers.ts` export name, for lifecycle log correlation. */
+  lunoraName;
+  constructor(context, env, definition, exportName) {
+    super(context, env, {
+      defaultPort: definition.defaultPort,
+      envVars: resolveContainerEnvVariables(definition, env, exportName),
+      sleepAfter: definition.sleepAfter
+    });
+    if (definition.enableInternet !== void 0) {
+      this.enableInternet = definition.enableInternet;
+    }
+    this.lunoraName = exportName ?? "container";
+  }
+  onError(error) {
+    const envelope = emitContainerLifecycle(this.lunoraName, this.instanceId(), "error", error instanceof Error ? error.message : String(error));
+    this.surfaceInStudioLogs(envelope);
+    return super.onError(error);
+  }
+  async onStart() {
+    const envelope = emitContainerLifecycle(this.lunoraName, this.instanceId(), "start");
+    this.surfaceInStudioLogs(envelope);
+    await super.onStart();
+  }
+  async onStop(parameters) {
+    const envelope = emitContainerLifecycle(this.lunoraName, this.instanceId(), "stop", `${parameters.reason} (exit ${String(parameters.exitCode)})`);
+    this.surfaceInStudioLogs(envelope);
+    await super.onStop(parameters);
+  }
+  /**
+   * Best-effort push of `envelope` into the root ShardDO's log buffer so it
+   * also appears in the Studio Logs panel (the terminal already has it via
+   * `emitContainerLifecycle`). Fire-and-forget and fully swallowed: a missing
+   * `SHARD` binding, a missing admin token, or a fetch failure NEVER throws
+   * out of a lifecycle hook — the `console` path stays the source of truth.
+   */
+  surfaceInStudioLogs(envelope) {
+    reportContainerLifecycle(this.env, envelope).catch(() => {
+    });
+  }
+  /**
+   * Per-instance correlation id: the Durable Object id, which Cloudflare also
+   * injects into the container as `CLOUDFLARE_DURABLE_OBJECT_ID`. Read
+   * defensively — the id shape varies and isn't worth crashing a hook over.
+   */
+  instanceId() {
+    try {
+      const { id } = this.ctx;
+      return typeof id?.toString === "function" ? id.toString() : "unknown";
+    } catch {
+      return "unknown";
+    }
+  }
+}
+
+export { LunoraContainer as default };

package/dist/index.d.mts

@@ -0,0 +1,189 @@
+import { a as ContainerConfig, C as ContainerDefinition, b as ContainerImageSource, N as NormalizedContainerImage } from "./packem_shared/types.d-D2l2SYol.mjs";
+export type { B as BuildImageSource, c as ContainerInstanceType, d as ContainerRollout, e as CustomContainerInstanceType, f as NamedContainerInstanceType, R as RegistryImageSource } from "./packem_shared/types.d-D2l2SYol.mjs";
+/**
+* The `ctx.containers` action surface: typed handles over the `CONTAINER_*`
+* Durable Object namespace bindings the config layer reconciles.
+*
+* Deliberately structural (no `@cloudflare/containers` import): a Durable
+* Object namespace stub is all that is needed to route a request to a
+* container-enabled DO, so this module stays Node-safe and the test double
+* below can satisfy the exact same shape without a workerd runtime.
+*/
+/** Options for explicitly starting an instance (mirrors `@cloudflare/containers`). */
+interface ContainerStartOptions {
+  /** Override outbound internet access for this start. */
+  enableInternet?: boolean;
+  /** Override the container entrypoint. */
+  entrypoint?: string[];
+  /** Per-instance environment, merged over the definition's `env`/secrets. */
+  envVars?: Record<string, string>;
+  /** 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. */
+interface ContainerInstanceState {
+  [key: string]: unknown;
+  lastChange?: number;
+}
+/** What a handle needs from a Durable Object stub — `fetch` plus the optional lifecycle RPCs the container DO exposes. */
+interface ContainerStubLike {
+  destroy?: () => Promise<void>;
+  fetch: (input: Request) => Promise<Response>;
+  getState?: () => Promise<ContainerInstanceState>;
+  start?: (options?: ContainerStartOptions) => Promise<void>;
+  stop?: (signal?: number | string) => Promise<void>;
+}
+/** What the client needs from a Durable Object namespace binding. */
+interface ContainerNamespaceLike {
+  get: (id: unknown) => ContainerStubLike;
+  idFromName: (name: string) => unknown;
+}
+/** A handle on one container instance (one Durable Object). */
+interface ContainerHandle {
+  /**
+  * Send an HTTP (or WebSocket-upgrade) request to the container. A path
+  * string (`"/transcode"`) is resolved against a synthetic origin; a full
+  * `Request`/URL passes through unchanged.
+  */
+  fetch: (input: Request | string, init?: RequestInit) => Promise<Response>;
+}
+/**
+* A handle on a *named* instance (from `.get(name)`) — `fetch` plus explicit
+* lifecycle control. The per-entity pattern (a sandbox per user, a room per
+* 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`.
+*/
+interface ContainerInstanceHandle extends ContainerHandle {
+  /** Stop and discard the instance (its ephemeral disk is lost). */
+  destroy: () => Promise<void>;
+  /** Read the instance's current runtime state. */
+  getState: () => Promise<ContainerInstanceState>;
+  /** Explicitly start the instance, optionally with per-instance env/entrypoint. */
+  start: (options?: ContainerStartOptions) => Promise<void>;
+  /** Stop the instance (optionally with a signal); it can start again on the next request. */
+  stop: (signal?: number | string) => Promise<void>;
+}
+/** The per-definition accessor exposed as `ctx.containers.&lt;exportName>`. */
+interface ContainerAccessor {
+  /**
+  * A random instance from a fixed pool of `count` (defaults to the
+  * definition's `maxInstances`, else 3 — mirroring `getRandom` from
+  * `@cloudflare/containers`). For stateless, interchangeable workloads.
+  */
+  any: (count?: number) => ContainerHandle;
+  /** The instance for `name` — one container per entity (user, room, job…), with lifecycle control. */
+  get: (name: string) => ContainerInstanceHandle;
+  /**
+  * A resilient handle over the pool: each `fetch` picks a random instance and,
+  * on a thrown error or a retryable response (5xx by default), retries on a
+  * freshly-picked instance with exponential backoff. Until Cloudflare ships
+  * native autoscaling + health-aware routing this is the recommended way to
+  * call a stateless container pool — it rides over a single cold/unhealthy
+  * instance instead of failing the whole request.
+  *
+  * Because a retry re-issues the request, pass a **replayable** body — a path
+  * string plus an `init.body` string/`ArrayBuffer` (re-created each attempt).
+  * A pre-built `Request` carrying a stream body can only be sent once, so it
+  * is not retry-safe here; use `.get()`/`.any()` for those.
+  */
+  pool: (options?: PoolOptions) => ContainerHandle;
+}
+/** Tuning for a pooled, retrying container handle. See {@link ContainerAccessor.pool}. */
+interface PoolOptions {
+  /** Total attempts before giving up (each on a freshly-picked instance). Default 3. */
+  attempts?: number;
+  /** Base backoff in ms between attempts; doubles each retry (0 disables the wait). Default 100. */
+  backoffMs?: number;
+  /**
+  * Upper bound on a single backoff sleep, in ms. The doubling delay is clamped
+  * to this ceiling so a large `attempts` count can't produce an unboundedly
+  * long wait. Default {@link DEFAULT_MAX_BACKOFF_MS} (30s).
+  */
+  maxBackoffMs?: number;
+  /**
+  * 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.
+  */
+  retryOn?: (response: Response) => boolean;
+  /** Pool size to spread picks across. Defaults to the definition's `maxInstances`, else 3. */
+  size?: number;
+}
+/** Wiring info for one definition, emitted by codegen into the generated DO. */
+interface ContainerBindingSpec {
+  /** Durable Object binding name, e.g. `CONTAINER_TRANSCODER`. */
+  binding: string;
+  /** The `lunora/containers.ts` export name, e.g. `transcoder`. */
+  exportName: string;
+  /** Pool size default for `.any()`. */
+  maxInstances?: number;
+}
+/**
+* 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.
+*/
+declare const createContainerContext: (env: Record<string, unknown>, specs: ReadonlyArray<ContainerBindingSpec>) => Record<string, ContainerAccessor>;
+/** A test handler: receives the request plus the targeted instance name. */
+type ContainerTestHandler = (request: Request, instance: {
+  name: string;
+}) => Promise<Response> | Response;
+/**
+* Docker-free test double for `ctx.containers`: each export name maps to a
+* fetch handler that plays the container. Mirrors the real shape exactly, so
+* action handlers under test can't tell the difference.
+*
+* ```ts
+* const containers = createContainerTestContext({
+*     transcoder: (request) => new Response("ok"),
+* });
+* ```
+*/
+declare const createContainerTestContext: (handlers: Record<string, ContainerTestHandler>) => Record<string, ContainerAccessor>;
+/**
+* Normalize a `ContainerImageSource` into the shape wrangler wants: a
+* Dockerfile path + build context for local builds, or a fully-qualified
+* reference for pre-built images.
+*
+* A local-path string whose basename starts with `Dockerfile` (so
+* `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`.
+*/
+declare const normalizeContainerImage: (image: ContainerImageSource) => NormalizedContainerImage;
+/**
+* The generated Container DO class name for a `lunora/containers.ts` export:
+* `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.
+*/
+declare const containerClassName: (exportName: string) => string;
+/**
+* The Durable Object binding name for a container export: `transcoder` →
+* `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.
+*/
+declare const containerBindingName: (exportName: string) => string;
+/**
+* The local image tag a Railpack `{ build }` container is built and pushed
+* under: `transcoder` → `lunora-transcoder:build`. The config reconciler writes
+* 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.
+*/
+declare const containerBuildTag: (exportName: string) => string;
+declare const defineContainer: (config: ContainerConfig) => ContainerDefinition;
+/** True when a value is a `defineContainer` result (the runtime brand check). */
+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.
+*/
+declare const resolveContainerEnvVariables: (definition: ContainerDefinition, workerEnv: Record<string, unknown>, exportName?: string) => Record<string, string>;
+export { type ContainerAccessor, type ContainerBindingSpec, type ContainerConfig, type ContainerDefinition, type ContainerHandle, type ContainerImageSource, type ContainerInstanceHandle, type ContainerInstanceState, type ContainerNamespaceLike, type ContainerStartOptions, type ContainerTestHandler, type NormalizedContainerImage, type PoolOptions, containerBindingName, containerBuildTag, containerClassName, createContainerContext, createContainerTestContext, defineContainer, isContainerDefinition, normalizeContainerImage, resolveContainerEnvVariables as resolveContainerEnvVars };