@lunora/container 1.0.0-alpha.1 → 1.0.0-alpha.11

package/dist/index.d.ts

@@ -1,14 +1,5 @@
-import { a as ContainerConfig, C as ContainerDefinition, b as ContainerImageSource, N as NormalizedContainerImage } from "./packem_shared/types.d-D2l2SYol.js";
-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.js";
-/**
-* 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.
-*/
+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`). */
 interface ContainerStartOptions {
   /** Override outbound internet access for this start. */
@@ -23,13 +14,25 @@ interface ContainerStartOptions {
 /** A container instance's runtime state, as returned by `getState()`. Structural — the platform adds fields over time. */
 interface ContainerInstanceState {
   [key: string]: unknown;
+  /** Process exit code, present once the instance has `stopped_with_code`. */
+  exitCode?: number;
+  /** Epoch-ms of the last state transition. */
   lastChange?: number;
+  /** Lifecycle status. Widening union — Cloudflare adds values over time. */
+  status?: "healthy" | "running" | "stopped" | "stopped_with_code" | "stopping";
 }
-/** What a handle needs from a Durable Object stub — `fetch` plus the optional lifecycle RPCs the container DO exposes. */
+/** What a handle needs from a Durable Object stub — `fetch` plus the optional lifecycle/egress RPCs the container DO exposes. */
 interface ContainerStubLike {
+  allowHost?: (hostname: string) => Promise<void>;
+  denyHost?: (hostname: string) => Promise<void>;
   destroy?: () => Promise<void>;
   fetch: (input: Request) => Promise<Response>;
   getState?: () => Promise<ContainerInstanceState>;
+  removeAllowedHost?: (hostname: string) => Promise<void>;
+  removeDeniedHost?: (hostname: string) => Promise<void>;
+  renewActivityTimeout?: () => Promise<void>;
+  setAllowedHosts?: (hosts: string[]) => Promise<void>;
+  setDeniedHosts?: (hosts: string[]) => Promise<void>;
   start?: (options?: ContainerStartOptions) => Promise<void>;
   stop?: (signal?: number | string) => Promise<void>;
 }
@@ -37,6 +40,11 @@ interface ContainerStubLike {
 interface ContainerNamespaceLike {
   get: (id: unknown) => ContainerStubLike;
   idFromName: (name: string) => unknown;
+  /**
+  * Derive a jurisdiction-restricted subnamespace. Optional because older
+  * workers-types releases (and test doubles) may not expose it.
+  */
+  jurisdiction?: (jurisdiction: DurableObjectJurisdiction) => ContainerNamespaceLike;
 }
 /** A handle on one container instance (one Durable Object). */
 interface ContainerHandle {
@@ -46,6 +54,15 @@ interface ContainerHandle {
   * `Request`/URL passes through unchanged.
   */
   fetch: (input: Request | string, init?: RequestInit) => Promise<Response>;
+  /**
+  * Return a handle that routes every request to `targetPort` on the
+  * container instead of the definition's `defaultPort` — for multi-port
+  * containers (declare the ports in `requiredPorts`). Sets the
+  * `cf-container-target-port` header the way `@cloudflare/containers`'
+  * `switchPort` does, so it composes with `.get()`, `.any()`, and `.pool()`:
+  * `ctx.containers.app.get("u1").port(9090).fetch("/admin")`.
+  */
+  port: (targetPort: number) => ContainerHandle;
 }
 /**
 * A handle on a *named* instance (from `.get(name)`) — `fetch` plus explicit
@@ -57,23 +74,76 @@ interface ContainerHandle {
 interface ContainerInstanceHandle extends ContainerHandle {
   /** Stop and discard the instance (its ephemeral disk is lost). */
   destroy: () => Promise<void>;
+  /**
+  * Adjust this instance's egress allow/deny lists at runtime — the dynamic
+  * counterpart to the static `allowedHosts`/`deniedHosts` config. Useful for
+  * per-tenant egress policy. Requires the worker to export `ContainerProxy`
+  * (codegen re-exports it from the generated container file whenever any
+  * container is defined, so the runtime controls always work).
+  */
+  egress: ContainerEgressControls;
   /** Read the instance's current runtime state. */
   getState: () => Promise<ContainerInstanceState>;
+  /**
+  * Reset the instance's `sleepAfter` idle timer. The platform renews it on
+  * each proxied request, and because `@lunora/container` proxies WebSocket
+  * frames through the Durable Object, message traffic on an open socket
+  * renews it too (the WebSocket-keepalive gap of cloudflare/containers#147 is
+  * closed in the bundled base). This manual control is the escape hatch for
+  * keeping a container awake during activity that is neither an HTTP request
+  * nor a WS message — e.g. a long out-of-band job running inside it.
+  */
+  renewActivityTimeout: () => Promise<void>;
   /** 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>;
 }
+/**
+* Runtime egress-firewall controls for a named instance (`handle.egress.*`).
+* 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.
+*/
+interface ContainerEgressControls {
+  /** Add one hostname (or glob) to the allow-list. */
+  allow: (hostname: string) => Promise<void>;
+  /** Add one hostname (or glob) to the deny-list. */
+  deny: (hostname: string) => Promise<void>;
+  /** Remove one hostname from the allow-list. */
+  removeAllowed: (hostname: string) => Promise<void>;
+  /** Remove one hostname from the deny-list. */
+  removeDenied: (hostname: string) => Promise<void>;
+  /** Replace the entire allow-list. */
+  setAllowed: (hosts: ReadonlyArray<string>) => Promise<void>;
+  /** Replace the entire deny-list. */
+  setDenied: (hosts: ReadonlyArray<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.
+  *
+  * Like `.get()`, a path/URL-string fetch transparently retries the
+  * cold-start "instance is provisioning" transients (cloudflare/containers#45,
+  * #139); pass {@link InstanceRetryOptions} to tune or disable it.
+  */
+  any: (count?: number, options?: InstanceRetryOptions) => ContainerHandle;
+  /**
+  * The instance for `name` — one container per entity (user, room, job…),
+  * with lifecycle control.
+  *
+  * A path/URL-string fetch transparently retries the platform's cold-start
+  * transients — "there is no Container instance available" / "container is
+  * not listening" while an instance is still provisioning
+  * (cloudflare/containers#45, #139) — on the *same* instance with backoff,
+  * since the request never reached the app. Pass {@link InstanceRetryOptions}
+  * to tune attempts/backoff or disable it (`{ attempts: 1 }`). A pre-built
+  * `Request` (possibly a one-shot stream body) is sent once, never retried.
   */
-  any: (count?: number) => ContainerHandle;
-  /** The instance for `name` — one container per entity (user, room, job…), with lifecycle control. */
-  get: (name: string) => ContainerInstanceHandle;
+  get: (name: string, options?: InstanceRetryOptions) => 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
@@ -110,6 +180,24 @@ interface PoolOptions {
   /** Pool size to spread picks across. Defaults to the definition's `maxInstances`, else 3. */
   size?: number;
 }
+/**
+* Tuning for the cold-start retry on a `.get()`/`.any()` handle. The retry fires
+* 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.
+*/
+interface InstanceRetryOptions {
+  /**
+  * Total attempts on a cold-start transient before the last outcome is
+  * surfaced as-is. `1` disables the retry. Default
+  * {@link DEFAULT_COLD_START_ATTEMPTS}.
+  */
+  attempts?: number;
+  /** Base backoff in ms between attempts; doubles each retry (0 disables the wait). Default {@link DEFAULT_COLD_START_BACKOFF_MS}. */
+  backoffMs?: number;
+  /** 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. */
 interface ContainerBindingSpec {
   /** Durable Object binding name, e.g. `CONTAINER_TRANSCODER`. */
@@ -121,12 +209,15 @@ 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.
 */
-declare const createContainerContext: (env: Record<string, unknown>, specs: ReadonlyArray<ContainerBindingSpec>) => Record<string, ContainerAccessor>;
+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. */
 type ContainerTestHandler = (request: Request, instance: {
   name: string;
@@ -186,4 +277,4 @@ declare const isContainerDefinition: (value: unknown) => value is ContainerDefin
 * 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 };
+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-ChDD53ys.mjs';
-export { containerBindingName, containerBuildTag, containerClassName, defineContainer, isContainerDefinition, normalizeContainerImage, resolveContainerEnvVars } from './packem_shared/containerBindingName-BGdSdFNA.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

@@ -0,0 +1,118 @@
+/** An attribute value carried on a span or log. */
+type ContainerAttributeValue = boolean | number | string;
+/**
+* A `fetch` implementation — defaults to the runtime global. The exporter passes
+* an abort `signal` (for the per-request timeout) and, once the promise settles,
+* 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.
+*/
+type OtelFetchLike = (input: string, init: {
+  body: string;
+  headers: Record<string, string>;
+  method: string;
+  signal?: AbortSignal;
+}) => Promise<{
+  body?: {
+    cancel: () => Promise<void>;
+  } | null;
+  ok: boolean;
+  status: number;
+}>;
+/** A single span the container process asks the exporter to record. */
+interface ContainerSpanInput {
+  /** Attributes attached to the span (rendered under the OTLP `attributes` list). */
+  attributes?: Record<string, ContainerAttributeValue>;
+  /** Wall-clock millis when the operation ended. */
+  endMs: number;
+  /** When set, the span is marked errored with this message (and optional `error.type`). */
+  error?: {
+    message: string;
+    type?: string;
+  };
+  /** Span name — the operation being timed, e.g. `"transcode"`. */
+  name: string;
+  /** Wall-clock millis when the operation started. */
+  startMs: number;
+}
+/** A single log line the container process asks the exporter to record. */
+interface ContainerLogInput {
+  /** Attributes attached to the log record. */
+  attributes?: Record<string, ContainerAttributeValue>;
+  /** Severity — defaults to `"info"`. */
+  level?: "debug" | "error" | "info" | "warn";
+  /** The log message body. */
+  message: string;
+  /** Wall-clock millis the line was emitted; defaults to now. */
+  ts?: number;
+}
+/** Options for {@link createContainerTelemetry}. */
+interface ContainerTelemetryOptions {
+  /** Base OTLP collector endpoint; defaults to the `LUNORA_OTLP_ENDPOINT` env var. */
+  endpoint?: string;
+  /** Injectable `fetch` (tests / non-global runtimes). Defaults to `globalThis.fetch`. */
+  fetch?: OtelFetchLike;
+  /** Extra headers merged onto every POST — e.g. deployment/org correlation. `content-type` is set by default. */
+  headers?: Record<string, string>;
+  /** Called with any send failure so the caller can surface it; the export itself always swallows. */
+  onError?: (error: unknown) => void;
+  /** `service.name` resource attribute; defaults to the `LUNORA_SERVICE_NAME` env var then `"lunora-container"`. */
+  serviceName?: string;
+  /** Per-POST timeout in ms; a collector that never responds aborts after this so a stuck send can't stall `flush()`. Defaults to {@link DEFAULT_TIMEOUT_MS} (10s). */
+  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. */
+interface ContainerTelemetry {
+  /** Record one log line (no-op when disabled). */
+  emitLog: (log: ContainerLogInput) => void;
+  /** Record one span (no-op when disabled). */
+  emitSpan: (span: ContainerSpanInput) => void;
+  /** True when an endpoint resolved and exports are actually sent. */
+  readonly enabled: boolean;
+  /** Await all in-flight sends — call before the process exits. */
+  flush: () => Promise<void>;
+  /** Time `run()`, recording a span named `name` (ok, or errored if it throws). Always runs `run()`, even when disabled. */
+  trace: <T>(name: string, run: () => Promise<T>, attributes?: Record<string, ContainerAttributeValue>) => Promise<T>;
+}
+/**
+* Create a zero-config OTLP exporter for the container process.
+*
+* ```ts
+* const telemetry = createContainerTelemetry(); // reads LUNORA_OTLP_ENDPOINT / _TOKEN
+* await telemetry.trace("transcode", () => transcode(job), { jobId: job.id });
+* telemetry.emitLog({ level: "info", message: "done", attributes: { jobId: job.id } });
+* await telemetry.flush(); // before the process exits
+* ```
+*
+* With no endpoint resolvable the returned exporter is disabled (`enabled ===
+* 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.
+*/
+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

@@ -0,0 +1,118 @@
+/** An attribute value carried on a span or log. */
+type ContainerAttributeValue = boolean | number | string;
+/**
+* A `fetch` implementation — defaults to the runtime global. The exporter passes
+* an abort `signal` (for the per-request timeout) and, once the promise settles,
+* 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.
+*/
+type OtelFetchLike = (input: string, init: {
+  body: string;
+  headers: Record<string, string>;
+  method: string;
+  signal?: AbortSignal;
+}) => Promise<{
+  body?: {
+    cancel: () => Promise<void>;
+  } | null;
+  ok: boolean;
+  status: number;
+}>;
+/** A single span the container process asks the exporter to record. */
+interface ContainerSpanInput {
+  /** Attributes attached to the span (rendered under the OTLP `attributes` list). */
+  attributes?: Record<string, ContainerAttributeValue>;
+  /** Wall-clock millis when the operation ended. */
+  endMs: number;
+  /** When set, the span is marked errored with this message (and optional `error.type`). */
+  error?: {
+    message: string;
+    type?: string;
+  };
+  /** Span name — the operation being timed, e.g. `"transcode"`. */
+  name: string;
+  /** Wall-clock millis when the operation started. */
+  startMs: number;
+}
+/** A single log line the container process asks the exporter to record. */
+interface ContainerLogInput {
+  /** Attributes attached to the log record. */
+  attributes?: Record<string, ContainerAttributeValue>;
+  /** Severity — defaults to `"info"`. */
+  level?: "debug" | "error" | "info" | "warn";
+  /** The log message body. */
+  message: string;
+  /** Wall-clock millis the line was emitted; defaults to now. */
+  ts?: number;
+}
+/** Options for {@link createContainerTelemetry}. */
+interface ContainerTelemetryOptions {
+  /** Base OTLP collector endpoint; defaults to the `LUNORA_OTLP_ENDPOINT` env var. */
+  endpoint?: string;
+  /** Injectable `fetch` (tests / non-global runtimes). Defaults to `globalThis.fetch`. */
+  fetch?: OtelFetchLike;
+  /** Extra headers merged onto every POST — e.g. deployment/org correlation. `content-type` is set by default. */
+  headers?: Record<string, string>;
+  /** Called with any send failure so the caller can surface it; the export itself always swallows. */
+  onError?: (error: unknown) => void;
+  /** `service.name` resource attribute; defaults to the `LUNORA_SERVICE_NAME` env var then `"lunora-container"`. */
+  serviceName?: string;
+  /** Per-POST timeout in ms; a collector that never responds aborts after this so a stuck send can't stall `flush()`. Defaults to {@link DEFAULT_TIMEOUT_MS} (10s). */
+  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. */
+interface ContainerTelemetry {
+  /** Record one log line (no-op when disabled). */
+  emitLog: (log: ContainerLogInput) => void;
+  /** Record one span (no-op when disabled). */
+  emitSpan: (span: ContainerSpanInput) => void;
+  /** True when an endpoint resolved and exports are actually sent. */
+  readonly enabled: boolean;
+  /** Await all in-flight sends — call before the process exits. */
+  flush: () => Promise<void>;
+  /** Time `run()`, recording a span named `name` (ok, or errored if it throws). Always runs `run()`, even when disabled. */
+  trace: <T>(name: string, run: () => Promise<T>, attributes?: Record<string, ContainerAttributeValue>) => Promise<T>;
+}
+/**
+* Create a zero-config OTLP exporter for the container process.
+*
+* ```ts
+* const telemetry = createContainerTelemetry(); // reads LUNORA_OTLP_ENDPOINT / _TOKEN
+* await telemetry.trace("transcode", () => transcode(job), { jobId: job.id });
+* telemetry.emitLog({ level: "info", message: "done", attributes: { jobId: job.id } });
+* await telemetry.flush(); // before the process exits
+* ```
+*
+* With no endpoint resolvable the returned exporter is disabled (`enabled ===
+* 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.
+*/
+declare const createContainerTelemetry: (options?: ContainerTelemetryOptions) => ContainerTelemetry;
+export { type ContainerAttributeValue, type ContainerLogInput, type ContainerSpanInput, type ContainerTelemetry, type ContainerTelemetryOptions, type OtelFetchLike, createContainerTelemetry };

package/dist/otel.mjs

@@ -0,0 +1,220 @@
+const OTLP_SEVERITY = {
+  debug: 5,
+  // DEBUG
+  error: 17,
+  // ERROR
+  info: 9,
+  // INFO
+  log: 9,
+  // INFO
+  warn: 13
+  // WARN
+};
+const otlpUnixNano = (ms) => `${String(Math.round(ms))}000000`;
+const otlpRandomHex = (bytes) => {
+  const buffer = new Uint8Array(bytes);
+  crypto.getRandomValues(buffer);
+  let hex = "";
+  for (const byte of buffer) {
+    hex += byte.toString(16).padStart(2, "0");
+  }
+  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 } };
+  }
+  if (typeof value === "number") {
+    if (!Number.isFinite(value)) {
+      return { key, value: { stringValue: String(value) } };
+    }
+    return Number.isSafeInteger(value) ? { key, value: { intValue: String(value) } } : { key, value: { doubleValue: value } };
+  }
+  return { key, value: { stringValue: value } };
+};
+const encodeAttributes = (attributes) => {
+  if (attributes === void 0) {
+    return [];
+  }
+  return Object.entries(attributes).map(([key, value]) => encodeAttribute(key, value));
+};
+const mergeHeaders = (defaults, overrides, token) => {
+  const merged = {};
+  const seen = /* @__PURE__ */ new Map();
+  const put = (name, value) => {
+    const lower = name.toLowerCase();
+    const existing = seen.get(lower);
+    if (existing === void 0) {
+      seen.set(lower, name);
+      merged[name] = value;
+    } else {
+      merged[existing] = value;
+    }
+  };
+  for (const [name, value] of Object.entries(defaults)) {
+    put(name, value);
+  }
+  for (const [name, value] of Object.entries(overrides ?? {})) {
+    put(name, value);
+  }
+  if (token !== void 0 && token.length > 0) {
+    put("authorization", `Bearer ${token}`);
+  }
+  return merged;
+};
+const wrapResourceSpans = (span, scopeName, serviceName) => {
+  return {
+    resourceSpans: [
+      {
+        resource: { attributes: [encodeAttribute("service.name", serviceName)] },
+        scopeSpans: [{ scope: { name: scopeName }, spans: [span] }]
+      }
+    ]
+  };
+};
+const wrapResourceLogs = (logRecord, scopeName, serviceName) => {
+  return {
+    resourceLogs: [
+      {
+        resource: { attributes: [encodeAttribute("service.name", serviceName)] },
+        scopeLogs: [{ logRecords: [logRecord], scope: { name: scopeName } }]
+      }
+    ]
+  };
+};
+
+const DEFAULT_TIMEOUT_MS = 1e4;
+const readEnv = (name) => {
+  return process.env[name];
+};
+const resolveFetch = (injected) => {
+  if (injected !== void 0) {
+    return injected;
+  }
+  if (typeof globalThis.fetch === "function") {
+    return globalThis.fetch;
+  }
+  return void 0;
+};
+const traceBody = (span, serviceName, parent) => {
+  const attributes = encodeAttributes(span.attributes);
+  if (span.error?.type !== void 0) {
+    attributes.push(encodeAttribute("error.type", span.error.type));
+  }
+  const otlpSpan = {
+    attributes,
+    endTimeUnixNano: otlpUnixNano(span.endMs),
+    // 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: parent?.traceId ?? otlpRandomHex(16)
+  };
+  return wrapResourceSpans(otlpSpan, "@lunora/container", serviceName);
+};
+const logBody = (log, serviceName, nowMs) => {
+  const level = log.level ?? "info";
+  const record = {
+    attributes: encodeAttributes(log.attributes),
+    body: { stringValue: log.message },
+    severityNumber: OTLP_SEVERITY[level],
+    severityText: level.toUpperCase(),
+    timeUnixNano: otlpUnixNano(log.ts ?? nowMs)
+  };
+  return wrapResourceLogs(record, "@lunora/container", serviceName);
+};
+const createContainerTelemetry = (options = {}) => {
+  const endpoint = options.endpoint ?? readEnv("LUNORA_OTLP_ENDPOINT");
+  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);
+  let base = endpoint ?? "";
+  while (base.endsWith("/")) {
+    base = base.slice(0, -1);
+  }
+  const tracesUrl = `${base}/v1/traces`;
+  const logsUrl = `${base}/v1/logs`;
+  const inflight = /* @__PURE__ */ new Set();
+  const send = (url, body) => {
+    if (fetchImpl === void 0) {
+      options.onError?.(new TypeError("createContainerTelemetry: no `fetch` available — pass `fetch` in options for this runtime."));
+      return;
+    }
+    const dispatch = async () => {
+      try {
+        const response = await fetchImpl(url, { body: JSON.stringify(body), headers, method: "POST", signal: AbortSignal.timeout(timeoutMs) });
+        if (!response.ok) {
+          options.onError?.(new Error(`createContainerTelemetry: OTLP export to ${url} failed with status ${String(response.status)}.`));
+        }
+        try {
+          await response.body?.cancel();
+        } catch {
+        }
+      } catch (error) {
+        options.onError?.(error);
+      }
+    };
+    const settled = dispatch().finally(() => {
+      inflight.delete(settled);
+    });
+    inflight.add(settled);
+  };
+  const emitSpan = (span) => {
+    if (!enabled) {
+      return;
+    }
+    send(tracesUrl, traceBody(span, serviceName, parent));
+  };
+  const emitLog = (log) => {
+    if (!enabled) {
+      return;
+    }
+    send(logsUrl, logBody(log, serviceName, Date.now()));
+  };
+  const trace = async (name, run, attributes) => {
+    const startMs = Date.now();
+    try {
+      const result = await run();
+      emitSpan({ attributes, endMs: Date.now(), name, startMs });
+      return result;
+    } catch (error) {
+      emitSpan({
+        attributes,
+        endMs: Date.now(),
+        error: { message: error instanceof Error ? error.message : String(error), type: error instanceof Error ? error.name : void 0 },
+        name,
+        startMs
+      });
+      throw error;
+    }
+  };
+  const flush = async () => {
+    await Promise.allSettled(inflight);
+  };
+  return { emitLog, emitSpan, enabled, flush, trace };
+};
+
+export { createContainerTelemetry };