@decocms/start 2.28.2 → 2.29.0

package/src/sdk/logger.ts

@@ -0,0 +1,166 @@
+/**
+ * Pluggable structured logger for @decocms/start.
+ *
+ * Mirrors the public shape of `@deco/deco/o11y` logger so site code that
+ * does `logger.info("...", { key: "value" })` keeps working unchanged
+ * after the Fresh → TanStack migration.
+ *
+ * Backed by a `LoggerAdapter`. The default adapter writes one JSON line
+ * to `console.log` per call — that line is what Cloudflare Logs / Logpush
+ * captures, so logging works out of the box on Workers without any
+ * additional configuration.
+ *
+ * To dual-emit to OTLP (HyperDX, etc.), wrap the default with
+ * `createCompositeLogger([defaultLoggerAdapter, otelLoggerAdapter])`
+ * inside `instrumentWorker()`.
+ *
+ * @example
+ * ```ts
+ * import { logger } from "@decocms/start/sdk/logger";
+ *
+ * logger.info("checkout started", { orderFormId, items: cart.items.length });
+ * logger.warn("retrying vtex call", { attempt, host });
+ * logger.error("payment failed", { reason, code, traceId });
+ * ```
+ */
+
+export type LogLevel = "debug" | "info" | "warn" | "error";
+
+const LEVEL_RANK: Record<LogLevel, number> = {
+  debug: 10,
+  info: 20,
+  warn: 30,
+  error: 40,
+};
+
+export interface LoggerAdapter {
+  log(level: LogLevel, msg: string, attrs?: Record<string, unknown>): void;
+}
+
+// ---------------------------------------------------------------------------
+// Default adapter — structured JSON to console.log
+// ---------------------------------------------------------------------------
+
+/**
+ * Cloudflare-Logs-friendly default. One JSON object per call, on stdout.
+ * Always safe to use — never throws, never depends on env, never makes
+ * a network call.
+ */
+export const defaultLoggerAdapter: LoggerAdapter = {
+  log(level, msg, attrs) {
+    const payload: Record<string, unknown> = {
+      level,
+      msg,
+      timestamp: new Date().toISOString(),
+    };
+    if (attrs) {
+      // Spread last so explicit attrs win over our defaults except
+      // for `level` / `msg` / `timestamp` which we always want canonical.
+      for (const [k, v] of Object.entries(attrs)) {
+        if (k !== "level" && k !== "msg" && k !== "timestamp") {
+          payload[k] = v;
+        }
+      }
+    }
+    // Route by level so Cloudflare's log dashboard colorises correctly.
+    const fn =
+      level === "error"
+        ? console.error
+        : level === "warn"
+          ? console.warn
+          : level === "debug"
+            ? console.debug
+            : console.log;
+    try {
+      fn(JSON.stringify(payload));
+    } catch {
+      // Last-resort: fall back to plain string. Never crash the request
+      // because of a circular-ref or non-serialisable attribute.
+      fn(`${level} ${msg}`);
+    }
+  },
+};
+
+// ---------------------------------------------------------------------------
+// Configurable global state
+// ---------------------------------------------------------------------------
+
+let activeAdapter: LoggerAdapter = defaultLoggerAdapter;
+let minLevel: LogLevel = "info";
+
+/**
+ * Replace the active logger adapter.
+ * Call once at worker boot from `instrumentWorker()`.
+ */
+export function configureLogger(adapter: LoggerAdapter): void {
+  activeAdapter = adapter;
+}
+
+/**
+ * Get the current active logger adapter (for tests / advanced wiring).
+ */
+export function getLoggerAdapter(): LoggerAdapter {
+  return activeAdapter;
+}
+
+/**
+ * Set the minimum log level. Calls below this level are dropped before
+ * reaching any adapter — useful to silence `debug` in production.
+ *
+ * Defaults to `info`. Override per environment via `setLogLevel("debug")`
+ * or by reading an env var at boot.
+ */
+export function setLogLevel(level: LogLevel): void {
+  minLevel = level;
+}
+
+export function getLogLevel(): LogLevel {
+  return minLevel;
+}
+
+function shouldLog(level: LogLevel): boolean {
+  return LEVEL_RANK[level] >= LEVEL_RANK[minLevel];
+}
+
+// ---------------------------------------------------------------------------
+// Public logger surface
+// ---------------------------------------------------------------------------
+
+/**
+ * Mirrors `@deco/deco/o11y` logger:
+ *  - first arg is the message
+ *  - optional second arg is a flat attributes object
+ *
+ * Adapters decide the destination (stdout JSON, OTLP, both, …).
+ */
+export interface Logger {
+  debug(msg: string, attrs?: Record<string, unknown>): void;
+  info(msg: string, attrs?: Record<string, unknown>): void;
+  warn(msg: string, attrs?: Record<string, unknown>): void;
+  error(msg: string, attrs?: Record<string, unknown>): void;
+}
+
+function emit(level: LogLevel, msg: string, attrs?: Record<string, unknown>): void {
+  if (!shouldLog(level)) return;
+  try {
+    activeAdapter.log(level, msg, attrs);
+  } catch {
+    // Adapter blew up. Fall back to default so we don't lose the line.
+    if (activeAdapter !== defaultLoggerAdapter) {
+      try {
+        defaultLoggerAdapter.log(level, msg, attrs);
+      } catch {
+        /* swallow */
+      }
+    }
+  }
+}
+
+export const logger: Logger = {
+  debug: (msg, attrs) => emit("debug", msg, attrs),
+  info: (msg, attrs) => emit("info", msg, attrs),
+  warn: (msg, attrs) => emit("warn", msg, attrs),
+  error: (msg, attrs) => emit("error", msg, attrs),
+};
+
+export default logger;

package/src/sdk/observability.ts

@@ -0,0 +1,75 @@
+/**
+ * One-stop import for everything observability-related in `@decocms/start`.
+ *
+ * Consumers (sites, apps) should prefer importing from here so future
+ * re-organisations don't ripple through every site:
+ *
+ * ```ts
+ * import {
+ *   instrumentWorker,
+ *   logger,
+ *   setLogLevel,
+ *   withTracing,
+ *   recordRequestMetric,
+ *   recordCacheMetric,
+ *   MetricNames,
+ * } from "@decocms/start/sdk/observability";
+ * ```
+ *
+ * The granular modules (`@decocms/start/sdk/logger`, `.../otelAdapters`,
+ * `.../sampler`) remain importable for advanced use cases (custom adapters,
+ * tests, etc.) but the common path stays here.
+ */
+
+// Tracer / meter / request log primitives (re-exported from the middleware)
+export {
+  configureMeter,
+  configureTracer,
+  getActiveSpan,
+  getMeter,
+  getTracer,
+  logRequest,
+  type MeterAdapter,
+  MetricNames,
+  recordCacheMetric,
+  recordRequestMetric,
+  type Span,
+  setSpanAttribute,
+  type TracerAdapter,
+  withTracing,
+} from "../middleware/observability";
+// Composite helpers (for advanced multi-backend wiring)
+export { createCompositeLogger, createCompositeMeter } from "./composite";
+// Logger surface
+export {
+  configureLogger,
+  defaultLoggerAdapter,
+  getLoggerAdapter,
+  getLogLevel,
+  type Logger,
+  type LoggerAdapter,
+  type LogLevel,
+  logger,
+  setLogLevel,
+} from "./logger";
+// Worker-entry wrapper + adapter wiring
+export { instrumentWorker, type OtelOptions } from "./otel";
+// Adapters (for tests / custom wiring)
+export {
+  type AnalyticsEngineMeterAdapterOptions,
+  createAnalyticsEngineMeterAdapter,
+  createOtelLoggerAdapter,
+  createOtelMeterAdapter,
+  getRuntimeEnv,
+  type OtelLoggerAdapterOptions,
+  type OtelMeterAdapterOptions,
+  setRuntimeEnv,
+} from "./otelAdapters";
+// Sampler
+export {
+  createUrlBasedHeadSampler,
+  decodeSamplingConfig,
+  type SamplingConfig,
+  type SamplingRule,
+  URLBasedSampler,
+} from "./sampler";

package/src/sdk/otel.test.ts

@@ -0,0 +1,59 @@
+/**
+ * NOTE: full `instrumentWorker(...)` integration tests aren't feasible in
+ * plain vitest because `@microlabs/otel-cf-workers` imports `cloudflare:workers`,
+ * which only exists in the Workers runtime.
+ *
+ * The wiring is validated end-to-end on the lebiscuit canary (Section 2 of
+ * the otel-hyperdx-parity plan): hit the deployed preview, confirm log
+ * lines via `wrangler tail`, traces via the HyperDX UI, and AE data points
+ * via `wrangler analytics-engine sql`. If we ever migrate the framework
+ * test suite to `@cloudflare/vitest-pool-workers`, restore the in-process
+ * smoke test here.
+ *
+ * Until then this file just guards the public API shape of the granular
+ * modules so refactors that break the export surface fail loudly in CI.
+ * (We deliberately don't import `./observability` here — it transitively
+ * pulls in `@microlabs/otel-cf-workers` and therefore `cloudflare:workers`.)
+ */
+import { describe, expect, it } from "vitest";
+import * as observability from "../middleware/observability";
+import * as composite from "./composite";
+import * as logger from "./logger";
+import * as adapters from "./otelAdapters";
+import * as sampler from "./sampler";
+
+describe("observability granular modules", () => {
+  it("exports the logger surface", () => {
+    expect(typeof logger.logger.info).toBe("function");
+    expect(typeof logger.configureLogger).toBe("function");
+    expect(typeof logger.setLogLevel).toBe("function");
+    expect(typeof logger.defaultLoggerAdapter.log).toBe("function");
+  });
+
+  it("exports composite helpers", () => {
+    expect(typeof composite.createCompositeLogger).toBe("function");
+    expect(typeof composite.createCompositeMeter).toBe("function");
+  });
+
+  it("exports OTel adapter factories", () => {
+    expect(typeof adapters.createOtelLoggerAdapter).toBe("function");
+    expect(typeof adapters.createOtelMeterAdapter).toBe("function");
+    expect(typeof adapters.createAnalyticsEngineMeterAdapter).toBe("function");
+    expect(typeof adapters.setRuntimeEnv).toBe("function");
+    expect(typeof adapters.getRuntimeEnv).toBe("function");
+  });
+
+  it("exports sampler API", () => {
+    expect(typeof sampler.URLBasedSampler).toBe("function");
+    expect(typeof sampler.decodeSamplingConfig).toBe("function");
+    expect(typeof sampler.createUrlBasedHeadSampler).toBe("function");
+  });
+
+  it("exports observability primitives from middleware/observability", () => {
+    expect(typeof observability.withTracing).toBe("function");
+    expect(typeof observability.recordRequestMetric).toBe("function");
+    expect(typeof observability.recordCacheMetric).toBe("function");
+    expect(observability.MetricNames.HTTP_REQUEST_DURATION_MS).toBe("http_request_duration_ms");
+    expect(observability.MetricNames.RESOLVE_DURATION_MS).toBe("resolve_duration_ms");
+  });
+});

package/src/sdk/otel.ts

@@ -1,12 +1,19 @@
 /**
- * OpenTelemetry integration for Cloudflare Workers via @microlabs/otel-cf-workers.
+ * Single observability entry point for `@decocms/start` on Cloudflare Workers.
  *
- * Opt-in module that wraps a Worker handler with auto-instrumentation and
- * wires traces into @decocms/start's pluggable TracerAdapter.
+ * `instrumentWorker(handler, options)` wraps a Worker handler with:
+ *  - structured JSON logger (stdout → Cloudflare Logs / Logpush) — always
+ *  - OTLP/HTTP logs exporter (HyperDX) — when `OTEL_EXPORTER_OTLP_ENDPOINT` is set
+ *  - OTLP/HTTP metrics exporter (HyperDX) — same condition
+ *  - Workers Analytics Engine metrics — when `env.DECO_METRICS` binding exists
+ *  - OTel traces via `@microlabs/otel-cf-workers` — when OTLP endpoint is set,
+ *    or always-on for the framework's internal `withTracing()` calls.
+ *  - URL-based head sampler from `OTEL_SAMPLING_CONFIG`
+ *  - OTel `Resource` with service.* / cloud.* / deployment.environment /
+ *    deco.runtime.version attributes
  *
- * Requires peer dependencies:
- * - `@microlabs/otel-cf-workers`
- * - `@opentelemetry/api`
+ * Removing HyperDX = unsetting `OTEL_EXPORTER_OTLP_ENDPOINT`. The console-JSON
+ * logger and AE metrics keep flowing — this is the "no vendor lock-in" guarantee.
  *
  * @example
  * ```ts
@@ -18,30 +25,64 @@
  * export default instrumentWorker(handler, { serviceName: "my-store" });
  * ```
  *
- * Environment variables (read from `env` at request time):
- * - `OTEL_EXPORTER_OTLP_ENDPOINT` — OTLP endpoint (e.g. `https://in-otel.hyperdx.io`)
- * - `OTEL_EXPORTER_OTLP_HEADERS` — comma-separated `key=value` auth headers
+ * Wrangler bindings to add when enabling OTLP + AE:
+ * ```jsonc
+ * "version_metadata":         { "binding": "CF_VERSION_METADATA" },
+ * "analytics_engine_datasets": [{ "binding": "DECO_METRICS", "dataset": "deco_metrics_my_site" }]
+ * ```
+ *
+ * Required Worker secrets when OTLP is enabled:
+ *   wrangler secret put OTEL_EXPORTER_OTLP_ENDPOINT  # https://in-otel.hyperdx.io
+ *   wrangler secret put OTEL_EXPORTER_OTLP_HEADERS   # authorization=<token>
  */
 
 import { instrument, type ResolveConfigFn } from "@microlabs/otel-cf-workers";
 import { trace } from "@opentelemetry/api";
-import { configureTracer } from "../middleware/observability";
+import { type Resource, resourceFromAttributes } from "@opentelemetry/resources";
+
+import { configureMeter, configureTracer } from "../middleware/observability";
+import { createCompositeLogger, createCompositeMeter } from "./composite";
+import { configureLogger, defaultLoggerAdapter, logger } from "./logger";
+import {
+  createAnalyticsEngineMeterAdapter,
+  createOtelLoggerAdapter,
+  createOtelMeterAdapter,
+  setRuntimeEnv,
+} from "./otelAdapters";
+import { RequestContext } from "./requestContext";
+import { createUrlBasedHeadSampler, decodeSamplingConfig } from "./sampler";
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
 
 export interface OtelOptions {
-  serviceName: string;
-  /** OTLP endpoint. Defaults to env.OTEL_EXPORTER_OTLP_ENDPOINT. */
+  /** Logical service name. Falls back to `env.DECO_SITE_NAME`, then "deco-site". */
+  serviceName?: string;
+  /** Override OTLP endpoint. Defaults to `env.OTEL_EXPORTER_OTLP_ENDPOINT`. */
   endpoint?: string;
-  /** OTLP auth headers. Defaults to env.OTEL_EXPORTER_OTLP_HEADERS parsed. */
+  /** Override OTLP auth headers. Defaults to parsed `env.OTEL_EXPORTER_OTLP_HEADERS`. */
   headers?: Record<string, string>;
+  /** Env var name holding the AE binding. Defaults to `"DECO_METRICS"`. */
+  analyticsEngineBindingName?: string;
+  /** Set to `false` to disable AE even when the binding is present. */
+  analyticsEngineEnabled?: boolean;
+  /** Push interval for OTLP metrics, in ms. Defaults to env.OTEL_EXPORT_INTERVAL or 60_000. */
+  metricsExportIntervalMillis?: number;
+  /**
+   * Version of `@decocms/start` to advertise as `deco.runtime.version`.
+   * Falls back to a build-time constant; override only for tests.
+   */
+  decoRuntimeVersion?: string;
+  /** Optional `@decocms/apps` version, advertised as `deco.apps.version`. */
+  decoAppsVersion?: string;
 }
 
-/** Minimal Cloudflare Worker execution context. */
 interface WorkerExecutionContext {
   waitUntil(promise: Promise<unknown>): void;
   passThroughOnException(): void;
 }
 
-/** Handler shape returned by createDecoWorkerEntry. */
 interface WorkerHandler {
   fetch(
     request: Request,
@@ -50,19 +91,40 @@ interface WorkerHandler {
   ): Promise<Response>;
 }
 
+// ---------------------------------------------------------------------------
+// Boot state — guard against double-init across worker reloads
+// ---------------------------------------------------------------------------
+
+let booted = false;
+
+interface BootState {
+  serviceName: string;
+  otlpEndpoint: string | null;
+  otlpHeaders: Record<string, string>;
+  resource: Resource;
+}
+
+let bootState: BootState | null = null;
+
+// ---------------------------------------------------------------------------
+// instrumentWorker
+// ---------------------------------------------------------------------------
+
 /**
- * Wraps a Cloudflare Worker handler with OpenTelemetry auto-instrumentation
- * (fetch, KV, D1, waitUntil) and connects to @decocms/start's TracerAdapter
- * so that `withTracing()` / `createInstrumentedFetch()` emit real OTel spans.
+ * Wraps a Cloudflare Worker handler with the full @decocms/start
+ * observability stack. Idempotent — calling twice on the same handler
+ * is a no-op (returns the already-instrumented handler).
  */
 export function instrumentWorker(
   handler: WorkerHandler,
-  options: OtelOptions | ((env: Record<string, unknown>) => OtelOptions),
-) {
-  // Bridge @decocms/start TracerAdapter → @opentelemetry/api
+  options: OtelOptions | ((env: Record<string, unknown>) => OtelOptions) = {},
+): WorkerHandler {
+  // Bridge our pluggable TracerAdapter onto @opentelemetry/api so
+  // framework-internal `withTracing()` calls produce real OTel spans
+  // for whatever exporter is configured (OTLP, console, etc.).
   configureTracer({
     startSpan: (name, attrs) => {
-      const span = trace.getTracer("deco").startSpan(name, { attributes: attrs });
+      const span = trace.getTracer("@decocms/start").startSpan(name, { attributes: attrs });
       return {
         end: () => span.end(),
         setError: (error) => {
@@ -75,21 +137,178 @@ export function instrumentWorker(
 
   const resolveConfig: ResolveConfigFn = (env, _trigger) => {
     const opts = typeof options === "function" ? options(env as Record<string, unknown>) : options;
-    const endpoint = opts.endpoint || (env.OTEL_EXPORTER_OTLP_ENDPOINT as string);
-    const headers = opts.headers || parseHeaders(env.OTEL_EXPORTER_OTLP_HEADERS as string | undefined);
+    bootObservability(opts, env as Record<string, unknown>);
+
+    const state = bootState!;
+
+    // Sampling — base64 JSON via OTEL_SAMPLING_CONFIG, see sdk/sampler.ts
+    const samplingConfig = decodeSamplingConfig(env.OTEL_SAMPLING_CONFIG as string | undefined);
+    const headSampler = createUrlBasedHeadSampler(samplingConfig);
+
+    // microlabs requires an exporter even when we only want internal
+    // tracing. When OTLP isn't configured, we still set up a no-op
+    // collector — the URL we'd never reach so spans simply drop.
+    const exporterUrl = state.otlpEndpoint ?? "http://127.0.0.1:0/v1/traces";
 
     return {
-      exporter: { url: endpoint, headers },
-      service: { name: opts.serviceName },
+      exporter: {
+        url: joinPath(exporterUrl, "/v1/traces"),
+        headers: state.otlpHeaders,
+      },
+      service: {
+        name: state.serviceName,
+        version: (env.CF_VERSION_METADATA as { id?: string } | undefined)?.id,
+      },
+      sampling: { headSampler },
+      // microlabs auto-instruments globalThis.fetch + KV + waitUntil.
+      instrumentation: {
+        instrumentGlobalFetch: true,
+        instrumentGlobalCache: true,
+      },
     };
   };
 
-  // Cast through `any` — @microlabs/otel-cf-workers expects Cloudflare's
-  // ExportedHandler type, but we avoid depending on @cloudflare/workers-types.
+  const innerHandler: WorkerHandler = {
+    async fetch(request, env, ctx) {
+      // Stash env so request-scoped adapters (AE) can resolve their bindings.
+      // Done inside RequestContext.run wrapping in workerEntry.ts as well, but
+      // for instrumentWorker we re-stash in case this handler is wrapped over
+      // the top of a Worker that doesn't go through createDecoWorkerEntry.
+      const wrap = async () => {
+        setRuntimeEnv(env);
+        return handler.fetch(request, env, ctx);
+      };
+
+      // RequestContext may already be active (createDecoWorkerEntry sets it
+      // up). If so, run inline; otherwise wrap. Cheap to detect via current.
+      if (RequestContext.current) {
+        return wrap();
+      }
+      return RequestContext.run(request, wrap);
+    },
+  };
+
   // deno-lint-ignore no-explicit-any
-  return instrument(handler as any, resolveConfig);
+  return instrument(innerHandler as any, resolveConfig) as unknown as WorkerHandler;
+}
+
+// ---------------------------------------------------------------------------
+// Boot — wires the loggers/meters once (per worker isolate)
+// ---------------------------------------------------------------------------
+
+function bootObservability(opts: OtelOptions, env: Record<string, unknown>): void {
+  if (booted && bootState) return;
+
+  const serviceName = opts.serviceName ?? (env.DECO_SITE_NAME as string | undefined) ?? "deco-site";
+
+  const otlpEndpoint =
+    opts.endpoint ?? (env.OTEL_EXPORTER_OTLP_ENDPOINT as string | undefined) ?? null;
+  const otlpHeaders =
+    opts.headers ?? parseHeaders(env.OTEL_EXPORTER_OTLP_HEADERS as string | undefined);
+
+  const resource = buildResource({
+    serviceName,
+    serviceVersion: (env.CF_VERSION_METADATA as { id?: string } | undefined)?.id,
+    serviceInstanceId: cryptoRandomId(),
+    deploymentEnvironment: (env.DECO_ENV_NAME as string | undefined) ?? "production",
+    decoRuntimeVersion: opts.decoRuntimeVersion ?? DECO_RUNTIME_VERSION,
+    decoAppsVersion: opts.decoAppsVersion,
+  });
+
+  // ---- Logger ----------------------------------------------------------
+  const otelLogger =
+    otlpEndpoint != null
+      ? createOtelLoggerAdapter({
+          endpoint: otlpEndpoint,
+          headers: otlpHeaders,
+          resource,
+          name: serviceName,
+        })
+      : null;
+
+  configureLogger(createCompositeLogger([defaultLoggerAdapter, otelLogger]));
+
+  // ---- Meter -----------------------------------------------------------
+  const otelMeter =
+    otlpEndpoint != null
+      ? createOtelMeterAdapter({
+          endpoint: otlpEndpoint,
+          headers: otlpHeaders,
+          resource,
+          exportIntervalMillis:
+            opts.metricsExportIntervalMillis ?? numericEnv(env.OTEL_EXPORT_INTERVAL, 60_000),
+          name: serviceName,
+        })
+      : null;
+
+  const aeBindingName = opts.analyticsEngineBindingName ?? "DECO_METRICS";
+  const aeEnabled = opts.analyticsEngineEnabled !== false && Boolean(env[aeBindingName]);
+  const aeMeter = aeEnabled
+    ? createAnalyticsEngineMeterAdapter({ bindingName: aeBindingName })
+    : null;
+
+  configureMeter(createCompositeMeter([aeMeter, otelMeter]));
+
+  bootState = {
+    serviceName,
+    otlpEndpoint,
+    otlpHeaders,
+    resource,
+  };
+  booted = true;
+
+  // Single boot-time breadcrumb so operators can confirm the wiring at a
+  // glance from CF Logs without enabling debug.
+  logger.info("observability booted", {
+    service: serviceName,
+    otlp: Boolean(otlpEndpoint),
+    analyticsEngine: aeEnabled,
+    sampling: Boolean(env.OTEL_SAMPLING_CONFIG),
+    runtimeVersion: opts.decoRuntimeVersion ?? DECO_RUNTIME_VERSION,
+  });
 }
 
+// ---------------------------------------------------------------------------
+// Resource attributes
+// ---------------------------------------------------------------------------
+
+interface ResourceInput {
+  serviceName: string;
+  serviceVersion?: string;
+  serviceInstanceId: string;
+  deploymentEnvironment: string;
+  decoRuntimeVersion: string;
+  decoAppsVersion?: string;
+}
+
+function buildResource(input: ResourceInput): Resource {
+  const attrs: Record<string, string> = {
+    "service.name": input.serviceName,
+    "service.version": input.serviceVersion ?? "unknown",
+    "service.instance.id": input.serviceInstanceId,
+    "cloud.provider": "cloudflare",
+    "deployment.environment": input.deploymentEnvironment,
+    "deco.runtime.version": input.decoRuntimeVersion,
+  };
+  if (input.decoAppsVersion) attrs["deco.apps.version"] = input.decoAppsVersion;
+  return resourceFromAttributes(attrs);
+}
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Build-time @decocms/start version. Hand-bumped at release; we deliberately
+ * avoid `import("../../package.json")` to keep the module side-effect-free
+ * and JSON-import-quirk-free across the various build pipelines that
+ * consume @decocms/start.
+ *
+ * Drift is acceptable — this attribute is for operator triage, not for
+ * billing / SLOs.
+ */
+const DECO_RUNTIME_VERSION = "2.28.2";
+
 function parseHeaders(str?: string): Record<string, string> {
   if (!str) return {};
   return Object.fromEntries(
@@ -102,3 +321,25 @@ function parseHeaders(str?: string): Record<string, string> {
       .filter(([k]) => k.length > 0),
   );
 }
+
+function numericEnv(value: unknown, fallback: number): number {
+  const n = Number(value);
+  return Number.isFinite(n) && n > 0 ? n : fallback;
+}
+
+function joinPath(base: string, path: string): string {
+  if (!base) return path;
+  if (base.endsWith("/")) base = base.slice(0, -1);
+  if (!path.startsWith("/")) path = "/" + path;
+  if (base.toLowerCase().endsWith(path.toLowerCase())) return base;
+  return base + path;
+}
+
+function cryptoRandomId(): string {
+  // crypto.randomUUID is universally available in CF Workers + Node 19+.
+  try {
+    return crypto.randomUUID();
+  } catch {
+    return `inst-${Date.now().toString(36)}-${Math.random().toString(36).slice(2)}`;
+  }
+}