@decocms/blocks 7.30.0 → 7.31.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@decocms/blocks",
-  "version": "7.30.0",
+  "version": "7.31.1",
   "type": "module",
   "engines": {
     "node": ">=24"

package/src/cms/draftSource.test.ts

@@ -75,27 +75,45 @@ describe("previewApiOriginForHost", () => {
     expect(previewApiOriginForHost("abc.local.studio.decocms.com", {})).toBe(
       "https://abc.local.studio.decocms.com",
     );
-    expect(previewApiOriginForHost("abc.localhost:60534", {})).toBe("http://abc.localhost:60534");
+    expect(previewApiOriginForHost("abc.localhost:60534", {})).toBe(
+      "http://abc.localhost:60534",
+    );
+    // -stg is its own suffix, not a substring match of .preview-studio.decocms.com —
+    // both must be listed explicitly (regressed once: staging draft pointers
+    // silently fell back to published content with no visible error).
+    expect(
+      previewApiOriginForHost("abc.preview-studio-stg.decocms.com", {}),
+    ).toBe("https://abc.preview-studio-stg.decocms.com");
   });
 
   it("rejects hosts outside the domains — the token proposes, config disposes", () => {
     expect(previewApiOriginForHost("evil.example", {})).toBeNull();
     // Dot-prefixed suffixes guarantee a label boundary: a lookalike domain
     // that merely ends with the same characters cannot pass.
-    expect(previewApiOriginForHost("evil-preview-studio.decocms.com", {})).toBeNull();
+    expect(
+      previewApiOriginForHost("evil-preview-studio.decocms.com", {}),
+    ).toBeNull();
     // The domain itself (no label in front) is not a draft host.
-    expect(previewApiOriginForHost("preview-studio.decocms.com", {})).toBeNull();
+    expect(
+      previewApiOriginForHost("preview-studio.decocms.com", {}),
+    ).toBeNull();
   });
 
   it("allows an explicit port only under localhost-ish domains", () => {
     // A public-domain token must not steer the fetch at odd ports.
-    expect(previewApiOriginForHost("abc.preview-studio.decocms.com:8500", {})).toBeNull();
+    expect(
+      previewApiOriginForHost("abc.preview-studio.decocms.com:8500", {}),
+    ).toBeNull();
   });
 
   it("honours a configured override instead of the defaults", () => {
     const env = { DECO_PREVIEW_API_DOMAINS: ".staging.example" };
-    expect(previewApiOriginForHost("abc.staging.example", env)).toBe("https://abc.staging.example");
-    expect(previewApiOriginForHost("abc.preview-studio.decocms.com", env)).toBeNull();
+    expect(previewApiOriginForHost("abc.staging.example", env)).toBe(
+      "https://abc.staging.example",
+    );
+    expect(
+      previewApiOriginForHost("abc.preview-studio.decocms.com", env),
+    ).toBeNull();
   });
 });
 
@@ -129,7 +147,9 @@ describe("resolveDraftDecofile", () => {
     });
 
     expect(blocks).toEqual({ "pages-home": { title: "draft" } });
-    expect(calls).toEqual(["https://abc.preview-studio.decocms.com/_sandbox/decofile"]);
+    expect(calls).toEqual([
+      "https://abc.preview-studio.decocms.com/_sandbox/decofile",
+    ]);
   });
 
   it("is inert without a host allowlist — no fetch at all", async () => {
@@ -168,8 +188,16 @@ describe("resolveDraftDecofile", () => {
     }) as unknown as typeof fetch;
     const P = "abc.preview-studio.decocms.com";
 
-    const a = await resolveDraftDecofile({ pointer: `${P}@v1`, env: ENV_ON, fetchImpl });
-    const b = await resolveDraftDecofile({ pointer: `${P}@v1`, env: ENV_ON, fetchImpl });
+    const a = await resolveDraftDecofile({
+      pointer: `${P}@v1`,
+      env: ENV_ON,
+      fetchImpl,
+    });
+    const b = await resolveDraftDecofile({
+      pointer: `${P}@v1`,
+      env: ENV_ON,
+      fetchImpl,
+    });
     expect(fetches).toBe(1);
     expect(b).toBe(a);
 
@@ -186,7 +214,11 @@ describe("resolveDraftDecofile", () => {
     const P = "abc.preview-studio.decocms.com";
 
     for (const v of ["v1", "v2", "v3", "v4"]) {
-      await resolveDraftDecofile({ pointer: `${P}@${v}`, env: ENV_ON, fetchImpl });
+      await resolveDraftDecofile({
+        pointer: `${P}@${v}`,
+        env: ENV_ON,
+        fetchImpl,
+      });
     }
     expect(fetches).toBe(4);
     await resolveDraftDecofile({ pointer: `${P}@v1`, env: ENV_ON, fetchImpl });
@@ -225,6 +257,7 @@ describe("DEFAULT_PREVIEW_API_DOMAINS", () => {
   it("ships the deco-operated origins, dot-prefixed", () => {
     expect(DEFAULT_PREVIEW_API_DOMAINS).toEqual([
       ".preview-studio.decocms.com",
+      ".preview-studio-stg.decocms.com",
       ".local.studio.decocms.com",
       ".localhost",
     ]);
@@ -261,10 +294,17 @@ describe("site-block preview hosts", () => {
 
 describe("draftPointerFromRequest", () => {
   it("reads the pointer from the __deco_draft cookie (in-preview navigation)", () => {
-    const req = new Request("https://preview.example/deco/invoke/site/loaders/x.ts", {
-      headers: { cookie: "a=1; __deco_draft=abc.preview-studio.decocms.com@v1; b=2" },
-    });
-    expect(draftPointerFromRequest(req)).toBe("abc.preview-studio.decocms.com@v1");
+    const req = new Request(
+      "https://preview.example/deco/invoke/site/loaders/x.ts",
+      {
+        headers: {
+          cookie: "a=1; __deco_draft=abc.preview-studio.decocms.com@v1; b=2",
+        },
+      },
+    );
+    expect(draftPointerFromRequest(req)).toBe(
+      "abc.preview-studio.decocms.com@v1",
+    );
   });
 
   it("lets ?__draft= win over the cookie", () => {
@@ -282,26 +322,35 @@ describe("draftPointerFromRequest", () => {
   });
 
   it("returns null with neither param nor cookie", () => {
-    expect(draftPointerFromRequest(new Request("https://preview.example/p"))).toBeNull();
+    expect(
+      draftPointerFromRequest(new Request("https://preview.example/p")),
+    ).toBeNull();
   });
 });
 
 describe("resolveDraftForRequest", () => {
   const ENV = { DECO_ALLOWED_PREVIEW_HOSTS: "preview.example" };
   function invokeReq(host = "preview.example"): Request {
-    return new Request("https://preview.example/deco/invoke/site/loaders/x.ts", {
-      method: "POST",
-      headers: {
-        "x-forwarded-host": host,
-        cookie: "__deco_draft=abc.preview-studio.decocms.com@v1",
+    return new Request(
+      "https://preview.example/deco/invoke/site/loaders/x.ts",
+      {
+        method: "POST",
+        headers: {
+          "x-forwarded-host": host,
+          cookie: "__deco_draft=abc.preview-studio.decocms.com@v1",
+        },
       },
-    });
+    );
   }
 
   it("binds the draft when host is allowed and the pointer resolves", async () => {
     const fetchImpl = (async () =>
-      jsonResponse({ "site/x": { value: "draft" } })) as unknown as typeof fetch;
-    expect(await resolveDraftForRequest(invokeReq(), { env: ENV, fetchImpl })).toEqual({
+      jsonResponse({
+        "site/x": { value: "draft" },
+      })) as unknown as typeof fetch;
+    expect(
+      await resolveDraftForRequest(invokeReq(), { env: ENV, fetchImpl }),
+    ).toEqual({
       "site/x": { value: "draft" },
     });
   });
@@ -312,7 +361,9 @@ describe("resolveDraftForRequest", () => {
       called = true;
       return jsonResponse({});
     }) as unknown as typeof fetch;
-    expect(await resolveDraftForRequest(invokeReq(), { env: {}, fetchImpl })).toBeNull();
+    expect(
+      await resolveDraftForRequest(invokeReq(), { env: {}, fetchImpl }),
+    ).toBeNull();
     expect(called).toBe(false);
   });
 
@@ -323,21 +374,29 @@ describe("resolveDraftForRequest", () => {
       return jsonResponse({});
     }) as unknown as typeof fetch;
     expect(
-      await resolveDraftForRequest(invokeReq("prod.example"), { env: ENV, fetchImpl }),
+      await resolveDraftForRequest(invokeReq("prod.example"), {
+        env: ENV,
+        fetchImpl,
+      }),
     ).toBeNull();
     expect(called).toBe(false);
   });
 
   it("returns null when the request carries no draft pointer", async () => {
-    const req = new Request("https://preview.example/deco/invoke/site/loaders/x.ts", {
-      headers: { "x-forwarded-host": "preview.example" },
-    });
+    const req = new Request(
+      "https://preview.example/deco/invoke/site/loaders/x.ts",
+      {
+        headers: { "x-forwarded-host": "preview.example" },
+      },
+    );
     let called = false;
     const fetchImpl = (async () => {
       called = true;
       return jsonResponse({});
     }) as unknown as typeof fetch;
-    expect(await resolveDraftForRequest(req, { env: ENV, fetchImpl })).toBeNull();
+    expect(
+      await resolveDraftForRequest(req, { env: ENV, fetchImpl }),
+    ).toBeNull();
     expect(called).toBe(false);
   });
 });

package/src/cms/draftSource.ts

@@ -39,7 +39,8 @@ export interface DraftPointer {
 }
 
 /** Lowercase DNS hostname, at least two labels (a bare label can't match any domain). */
-const HOST_RE = /^[a-z0-9]([a-z0-9-]*[a-z0-9])?(\.[a-z0-9]([a-z0-9-]*[a-z0-9])?)+$/;
+const HOST_RE =
+  /^[a-z0-9]([a-z0-9-]*[a-z0-9])?(\.[a-z0-9]([a-z0-9-]*[a-z0-9])?)+$/;
 const PORT_RE = /^[0-9]{1,5}$/;
 const VERSION_RE = /^[A-Za-z0-9._-]{1,64}$/;
 
@@ -48,7 +49,9 @@ const VERSION_RE = /^[A-Za-z0-9._-]{1,64}$/;
  * back to published content. Requires EXACTLY one `@`: a naive split accepts
  * `a@b@c` and silently uses the first two segments.
  */
-export function parseDraftPointer(raw: string | null | undefined): DraftPointer | null {
+export function parseDraftPointer(
+  raw: string | null | undefined,
+): DraftPointer | null {
   if (!raw) return null;
   const parts = raw.split("@");
   if (parts.length !== 2) return null;
@@ -71,6 +74,7 @@ export function parseDraftPointer(raw: string | null | undefined): DraftPointer
  */
 export const DEFAULT_PREVIEW_API_DOMAINS = [
   ".preview-studio.decocms.com",
+  ".preview-studio-stg.decocms.com",
   ".local.studio.decocms.com",
   ".localhost",
 ];
@@ -161,7 +165,9 @@ export function isDraftHostAllowed(
   env?: Record<string, string | undefined>,
 ): boolean {
   if (!host) return false;
-  return readAllowedHosts(envOrProcess(env)).includes(host.trim().toLowerCase());
+  return readAllowedHosts(envOrProcess(env)).includes(
+    host.trim().toLowerCase(),
+  );
 }
 
 /**
@@ -170,7 +176,9 @@ export function isDraftHostAllowed(
  * unconfigured site never loses static/ISR rendering. The per-request host
  * match happens later, in `isDraftHostAllowed`.
  */
-export function isDraftPreviewEnabled(env?: Record<string, string | undefined>): boolean {
+export function isDraftPreviewEnabled(
+  env?: Record<string, string | undefined>,
+): boolean {
   return readAllowedHosts(envOrProcess(env)).length > 0;
 }
 
@@ -179,7 +187,8 @@ function envOrProcess(
 ): Record<string, string | undefined> {
   return (
     env ??
-    (globalThis as { process?: { env?: Record<string, string | undefined> } }).process?.env ??
+    (globalThis as { process?: { env?: Record<string, string | undefined> } })
+      .process?.env ??
     {}
   );
 }
@@ -277,7 +286,10 @@ export const DRAFT_COOKIE_NAME = "__deco_draft";
 export const DRAFT_QUERY_PARAM = "__draft";
 
 /** Read one cookie value out of a raw `Cookie:` header. */
-function readCookieValue(cookieHeader: string | null | undefined, name: string): string | null {
+function readCookieValue(
+  cookieHeader: string | null | undefined,
+  name: string,
+): string | null {
   if (!cookieHeader) return null;
   for (const part of cookieHeader.split(";")) {
     const eq = part.indexOf("=");
@@ -331,7 +343,8 @@ export async function resolveDraftForRequest(
   if (readAllowedHosts(env).length === 0) return null;
   const pointer = draftPointerFromRequest(request);
   if (!pointer) return null;
-  const host = request.headers.get("x-forwarded-host") ?? request.headers.get("host");
+  const host =
+    request.headers.get("x-forwarded-host") ?? request.headers.get("host");
   if (!isDraftHostAllowed(host, env)) return null;
   return resolveDraftDecofile({ pointer, env, fetchImpl: options.fetchImpl });
 }
@@ -357,6 +370,9 @@ export function setDraftOverrideGetter(getter: DraftOverrideGetter): void {
 }
 
 /** The current request's draft blocks, if a binding registered one. */
-export function getRequestDraftOverride(): Record<string, unknown> | null | undefined {
+export function getRequestDraftOverride():
+  | Record<string, unknown>
+  | null
+  | undefined {
   return getDraftOverride();
 }

package/src/sdk/observability.ts

@@ -78,7 +78,13 @@ export {
   withTracing,
 } from "../middleware/observability";
 // Worker-entry wrapper + adapter wiring
-export { instrumentWorker, type OtelOptions } from "./otel";
+export {
+  bootObservability,
+  flushObservability,
+  instrumentWorker,
+  instrumentWorkflowRun,
+  type OtelOptions,
+} from "./otel";
 // Direct-POST OTLP trace exporter (Phase 3 / D-12). Exported for sites
 // that need to wire a custom traces endpoint outside `instrumentWorker`,
 // and for the audit tooling that asserts framework spans are flowing.

package/src/sdk/otel.test.ts

@@ -14,7 +14,12 @@ import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 import * as composite from "./composite";
 import * as logger from "./logger";
 import * as observability from "./observability";
-import { _resetBootStateForTests, instrumentWorker } from "./otel";
+import {
+  _resetBootStateForTests,
+  flushObservability,
+  instrumentWorker,
+  instrumentWorkflowRun,
+} from "./otel";
 import * as adapters from "./otelAdapters";
 import { createClickhouseCollectorAdapter } from "./otelAdapters/clickhouseCollector";
 
@@ -524,3 +529,108 @@ describe("instrumentWorker — OTLP/HTTP error-log channel wiring", () => {
     expect(calls).toHaveLength(0);
   });
 });
+
+describe("instrumentWorkflowRun / flushObservability — Workflow entrypoints", () => {
+  beforeEach(() => {
+    _resetBootStateForTests();
+  });
+
+  afterEach(() => {
+    _resetBootStateForTests();
+  });
+
+  it("flushObservability resolves without throwing when no adapters are configured", async () => {
+    await expect(flushObservability()).resolves.toBeUndefined();
+  });
+
+  it("instrumentWorkflowRun returns fn's result and does not throw with no OTel env vars set", async () => {
+    const fn = vi.fn().mockResolvedValue("step-result");
+    const result = await instrumentWorkflowRun({}, undefined, fn);
+
+    expect(result).toBe("step-result");
+    expect(fn).toHaveBeenCalledOnce();
+  });
+
+  function makeFetchSpy() {
+    const calls: Array<{ url: string; body: string }> = [];
+    const impl = vi.fn(async (input: string | URL | Request, init?: RequestInit) => {
+      calls.push({ url: String(input), body: String(init?.body ?? "") });
+      return new Response("{}", { status: 200 });
+    });
+    return { impl: impl as unknown as typeof fetch, calls };
+  }
+
+  it("rethrows fn's rejection but still flushes buffered metrics", async () => {
+    const { impl, calls } = makeFetchSpy();
+    const fn = vi.fn(async () => {
+      observability.recordRequestMetric("WORKFLOW", "/batch-product", 500, 9);
+      throw new Error("workflow step failed");
+    });
+    const env = { DECO_OTEL_METRICS_ENDPOINT: "https://ingest.test/v1/metrics" };
+
+    await expect(
+      instrumentWorkflowRun(env, { otlpMetricsFetchImpl: impl }, fn),
+    ).rejects.toThrow("workflow step failed");
+
+    expect(calls).toHaveLength(1);
+    expect(calls[0].url).toBe("https://ingest.test/v1/metrics");
+  });
+
+  it("still flushes when fn throws synchronously instead of returning a rejected promise", async () => {
+    const { impl, calls } = makeFetchSpy();
+    const fn = vi.fn(() => {
+      observability.recordRequestMetric("WORKFLOW", "/batch-product", 500, 9);
+      throw new Error("sync boom");
+    }) as unknown as () => Promise<string>;
+    const env = { DECO_OTEL_METRICS_ENDPOINT: "https://ingest.test/v1/metrics" };
+
+    await expect(
+      instrumentWorkflowRun(env, { otlpMetricsFetchImpl: impl }, fn),
+    ).rejects.toThrow("sync boom");
+
+    expect(calls).toHaveLength(1);
+  });
+
+  it("wires and flushes the OTLP metrics exporter, same as instrumentWorker's channel", async () => {
+    const { impl, calls } = makeFetchSpy();
+    const fn = vi.fn(async () => {
+      observability.recordRequestMetric("WORKFLOW", "/batch-product", 200, 12);
+      return "done";
+    });
+
+    const env = {
+      DECO_OTEL_METRICS_ENDPOINT: "https://ingest.test/v1/metrics",
+    } as unknown as Record<string, unknown>;
+
+    const result = await instrumentWorkflowRun(
+      env,
+      { serviceName: "workflow-smoke", otlpMetricsFetchImpl: impl },
+      fn,
+    );
+
+    expect(result).toBe("done");
+    expect(calls).toHaveLength(1);
+    expect(calls[0].url).toBe("https://ingest.test/v1/metrics");
+  });
+
+  it("forces the flush past the per-isolate cooldown across consecutive replay legs", async () => {
+    // Regression test: instrumentWorkflowRun forces its exit-time flush past
+    // the ~5s default cooldown each OTLP adapter otherwise enforces, since a
+    // Workflow run() only gets one flush attempt per leg — no next request
+    // to retry on like a fetch handler has.
+    const { impl, calls } = makeFetchSpy();
+    const env = { DECO_OTEL_METRICS_ENDPOINT: "https://ingest.test/v1/metrics" };
+    const opts = { otlpMetricsFetchImpl: impl };
+
+    await instrumentWorkflowRun(env, opts, async () => {
+      observability.recordRequestMetric("WORKFLOW", "/leg-1", 200, 5);
+    });
+    // A second replay leg immediately after — well within the default
+    // cooldown window — must still flush, not get silently skipped.
+    await instrumentWorkflowRun(env, opts, async () => {
+      observability.recordRequestMetric("WORKFLOW", "/leg-2", 200, 5);
+    });
+
+    expect(calls).toHaveLength(2);
+  });
+});

package/src/sdk/otel.ts

@@ -446,34 +446,98 @@ export function instrumentWorker(
         // ctx.waitUntil so no POST blocks the response. Each exporter
         // throttles itself per isolate — calling on every request is
         // cheap; the network only fires when the cooldown elapses or
-        // the buffer fills.
+        // the buffer fills. Skip the waitUntil call entirely when no
+        // adapter is configured (nothing to flush).
         const state = getBootState();
-        if (state.otlpMeter) {
+        if (state.otlpMeter || state.otlpLog || state.otlpTracer) {
           try {
-            ctx.waitUntil(state.otlpMeter.flush());
+            ctx.waitUntil(flushObservability());
           } catch {
             /* ctx.waitUntil throwing is benign — never block the response */
           }
         }
-        if (state.otlpLog) {
-          try {
-            ctx.waitUntil(state.otlpLog.flush());
-          } catch {
-            /* swallow */
-          }
-        }
-        if (state.otlpTracer) {
-          try {
-            ctx.waitUntil(state.otlpTracer.flush());
-          } catch {
-            /* swallow */
-          }
-        }
       }
     },
   };
 }
 
+/**
+ * Drains the OTLP metrics + error-log + traces buffers (whichever are
+ * configured for this isolate). Extracted out of `instrumentWorker`'s
+ * `finally` block so callers without a `{fetch}`/`ctx.waitUntil` lifecycle —
+ * e.g. Cloudflare Workflow `run()` handlers — can flush explicitly too. See
+ * `instrumentWorkflowRun` below.
+ *
+ * Each adapter's `flush()` is throttled by a per-isolate cooldown (default
+ * 5s) so a busy fetch handler doesn't fire a POST per request — pass
+ * `force: true` to bypass that cooldown for callers that only get one flush
+ * attempt with no next request to retry on (Workflow `run()` exit).
+ */
+export async function flushObservability(force = false): Promise<void> {
+  const state = getBootState();
+  await Promise.allSettled([
+    state.otlpMeter?.flush(force),
+    state.otlpLog?.flush(force),
+    state.otlpTracer?.flush(force),
+  ]);
+}
+
+/**
+ * Boots observability (same env-var-driven wiring `instrumentWorker` uses)
+ * and runs `fn`, flushing on the way out — the Workflow-entrypoint
+ * equivalent of `instrumentWorker`. Cloudflare Workflows have no `{fetch}` /
+ * `ctx.waitUntil` lifecycle, so this awaits the flush directly instead.
+ *
+ * Deliberately does NOT open a root span around `fn()`. Code in a
+ * `WorkflowEntrypoint.run(event, step)` outside `step.do`/`step.sleep`
+ * re-executes on every hibernate/wake replay — a span opened here would get
+ * a fresh random trace ID on every replay leg, producing disconnected
+ * traces instead of one coherent run. Create spans for individual
+ * `step.do(...)` callbacks with `withTracing` instead (each step only truly
+ * runs once, since `step.do` memoizes across replays), tagging them with
+ * `event.instanceId` so a backend can group replay legs under one logical
+ * run.
+ *
+ * The exit-time flush is `force`d (bypasses the per-isolate cooldown other
+ * `flush()` callers respect) — a Workflow `run()` invocation gets exactly
+ * one flush attempt on the way out, unlike a fetch handler where the next
+ * request's `ctx.waitUntil(flush())` can pick up whatever a cooldown-skipped
+ * flush left behind. Without forcing, a workflow with several replay legs in
+ * quick succession could have its final leg's flush silently skipped by the
+ * cooldown, losing that leg's buffered spans/metrics if the isolate is torn
+ * down before the next wake.
+ *
+ * @example
+ * ```ts
+ * async run(event: WorkflowEvent<Params>, step: WorkflowStep) {
+ *   return instrumentWorkflowRun(this.env, undefined, async () => {
+ *     await step.do("fetch-product", () =>
+ *       withTracing("deco.workflow.step", () => fetchProduct(), {
+ *         "workflow.instance_id": event.instanceId,
+ *         "workflow.step": "fetch-product",
+ *       }),
+ *     );
+ *   });
+ * }
+ * ```
+ */
+export async function instrumentWorkflowRun<T>(
+  env: Record<string, unknown>,
+  options: OtelOptions | undefined,
+  fn: () => Promise<T>,
+): Promise<T> {
+  configureTracer(buildOtelApiTracer());
+  bootObservability(options ?? {}, env);
+  try {
+    // Awaiting inside this try (rather than `return fn().finally(...)`)
+    // ensures a synchronous throw from `fn` — not just a rejected promise —
+    // still reaches the `finally` below instead of skipping it.
+    return await fn();
+  } finally {
+    await flushObservability(true);
+  }
+}
+
 /**
  * Build the legacy `@opentelemetry/api` global-tracer bridge. Stays a
  * no-op when no global TracerProvider is registered — same outcome as
@@ -639,7 +703,18 @@ function patchConsole(state: BootState): void {
   console.debug = (...args: unknown[]) => forward("debug", args);
 }
 
-function bootObservability(opts: OtelOptions, env: Record<string, unknown>): void {
+/**
+ * Boots the observability stack for the current isolate: resolves the
+ * `DECO_OTEL` on/off/auto switch, builds the resource-attribute floor
+ * (service name/version/instance, deployment environment, cloud platform),
+ * and — gated per env var — wires the AE meter and OTLP metrics/logs/traces
+ * adapters. Idempotent per isolate (`BootState.booted` guards re-entry).
+ *
+ * Exported so callers with a lifecycle `instrumentWorker` doesn't fit
+ * (Cloudflare Workflows — see `instrumentWorkflowRun`) can boot the same
+ * stack directly.
+ */
+export function bootObservability(opts: OtelOptions, env: Record<string, unknown>): void {
   const state = getBootState();
   if (state.booted) return;
 

package/src/sdk/otelHttpLog.ts

@@ -107,8 +107,8 @@ export interface OtlpHttpLogOptions {
 
 export interface OtlpHttpLog {
   adapter: LoggerAdapter;
-  /** Force a flush, subject to the per-isolate cooldown. */
-  flush(): Promise<void>;
+  /** Flush, subject to the per-isolate cooldown unless `force` is true. */
+  flush(force?: boolean): Promise<void>;
   /** Pending log record count. For tests + audit. */
   pendingRecordCount(): number;
 }
@@ -324,12 +324,12 @@ export function createOtlpHttpLogAdapter(options: OtlpHttpLogOptions): OtlpHttpL
     }
   }
 
-  async function flush(): Promise<void> {
+  async function flush(force = false): Promise<void> {
     if (inflight) return inflight;
 
     const elapsed = now() - lastFlushAt;
     const overCap = buffer.length >= maxBuffer;
-    if (!overCap && elapsed < minFlushIntervalMs) return;
+    if (!force && !overCap && elapsed < minFlushIntervalMs) return;
 
     inflight = doFlush().finally(() => {
       lastFlushAt = now();

package/src/sdk/otelHttpMeter.ts

@@ -93,8 +93,8 @@ export interface OtlpHttpMeter extends MeterAdapter {
   gaugeSet(name: string, value: number, labels?: Labels): void;
   /** Always defined on this adapter — declared required to drop the `?.` at call sites. */
   histogramRecord(name: string, value: number, labels?: Labels): void;
-  /** Force a flush, subject to the per-isolate cooldown. */
-  flush(): Promise<void>;
+  /** Flush, subject to the per-isolate cooldown unless `force` is true. */
+  flush(force?: boolean): Promise<void>;
   /** Pending datapoint count across all metric kinds. For tests + audit. */
   pendingDatapointCount(): number;
 }
@@ -341,7 +341,7 @@ export function createOtlpHttpMeterAdapter(options: OtlpHttpMeterOptions): OtlpH
     }
   }
 
-  async function flush(): Promise<void> {
+  async function flush(force = false): Promise<void> {
     // If a flush is in flight, reuse it — concurrent requests should not
     // pile up POSTs. The in-flight POST already snapshotted the buffer at
     // its enqueue time; new datapoints land in the buffer and will go out
@@ -350,8 +350,11 @@ export function createOtlpHttpMeterAdapter(options: OtlpHttpMeterOptions): OtlpH
 
     const elapsed = now() - lastFlushAt;
     const overCap = pendingDatapointCount() >= maxBuffer;
-    if (!overCap && elapsed < minFlushIntervalMs) {
-      // Cooldown not elapsed and buffer is not at the cap — skip.
+    if (!force && !overCap && elapsed < minFlushIntervalMs) {
+      // Cooldown not elapsed and buffer is not at the cap — skip. `force`
+      // bypasses this for callers with no next-request opportunity to
+      // retry the flush (e.g. a Cloudflare Workflow's `run()` exit — see
+      // `instrumentWorkflowRun` in `otel.ts`).
       return;
     }
 

package/src/sdk/otelHttpTracer.ts

@@ -233,8 +233,8 @@ export interface OtlpHttpTracerOptions {
 }
 
 export interface OtlpHttpTracer extends TracerAdapter {
-  /** Drain the buffer (subject to cooldown). */
-  flush(): Promise<void>;
+  /** Drain the buffer, subject to cooldown unless `force` is true. */
+  flush(force?: boolean): Promise<void>;
   /** For tests + the audit channel. */
   pendingSpanCount(): number;
   /**
@@ -433,11 +433,11 @@ export function createOtlpHttpTracerAdapter(options: OtlpHttpTracerOptions): Otl
     }
   }
 
-  async function flush(): Promise<void> {
+  async function flush(force = false): Promise<void> {
     if (inflight) return inflight;
     const elapsed = now() - lastFlushAt;
     const overCap = spans.length >= maxBuffer;
-    if (!overCap && elapsed < minFlushIntervalMs) return;
+    if (!force && !overCap && elapsed < minFlushIntervalMs) return;
     inflight = doFlush().finally(() => {
       lastFlushAt = now();
       inflight = null;