@decocms/blocks 7.62.4 → 7.63.0

package/package.json

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

package/src/middleware/observability.ts

@@ -282,6 +282,10 @@ export const MetricNames = {
   // Labels on this counter use short keys (status/profile/layer/provider) —
   // the metric name already provides the deco.cache.* namespace.
   CACHE_REQUESTS: "deco.cache.requests",
+  // Size in bytes of the values moving through a cache, dimensioned by `op`.
+  // Exponential (base-2) aggregation — see METRIC_METADATA for the scale and
+  // why an explicit-bounds histogram is the wrong shape here.
+  CACHE_SIZE: "deco.cache.size",
   RESOLVE_DURATION: "deco.cms.resolve.duration",
   LOADER_DURATION: "deco.loader.duration",
   LOADER_ERRORS: "deco.loader.errors",
@@ -339,7 +343,21 @@ export const DURATION_BUCKET_BOUNDARIES_SECONDS: readonly number[] = [
  */
 export const METRIC_METADATA: Record<
   string,
-  { description: string; unit: string; boundaries?: readonly number[] }
+  {
+    description: string;
+    unit: string;
+    boundaries?: readonly number[];
+    /**
+     * Histogram aggregation. Omitted means `"explicit"` — bucket into
+     * `boundaries`. `"exponential"` selects an OTel base-2 exponential
+     * histogram at {@link scale}, where bucket `i` covers
+     * `(2^(2^-scale))^i .. ^(i+1)]`. Adapters that don't implement it are free
+     * to keep treating the metric as an ordinary histogram.
+     */
+    aggregation?: "explicit" | "exponential";
+    /** Exponential-histogram scale. Fixed per metric; adapters never rescale. */
+    scale?: number;
+  }
 > = {
   [MetricNames.HTTP_SERVER_REQUEST_DURATION]: {
     description: "Duration of HTTP server requests handled at the Worker entry point.",
@@ -355,6 +373,19 @@ export const METRIC_METADATA: Record<
     description: "Cache lookups, dimensioned by status (hit/stale/miss/bypass).",
     unit: "{request}",
   },
+  [MetricNames.CACHE_SIZE]: {
+    description: "Size in bytes of values written to / read from a cache, dimensioned by op.",
+    unit: "By",
+    // Exponential rather than explicit bounds: entries span 512 B (the
+    // cachedLoader floor) to the 32 MB cap — five decades. Any fixed bound set
+    // wide enough for the top is useless at the bottom.
+    aggregation: "exponential",
+    // scale -1 => base 4, so buckets land on 512 B · 2 K · 8 K · 32 K · 128 K ·
+    // 512 K · 2 M · 8 M · 32 M: ~9 buckets over the real range, ~1.7 per
+    // decade. scale 0 (base 2) would double the series count without saying
+    // anything new about a size distribution.
+    scale: -1,
+  },
   [MetricNames.RESOLVE_DURATION]: {
     description: "Duration of `deco.cms.resolvePage` — CMS route to block tree resolution.",
     unit: "s",
@@ -590,6 +621,22 @@ export function recordCacheMetric(
   m.counterInc(MetricNames.CACHE_REQUESTS, 1, labels);
 }
 
+/**
+ * Record the size of a value moving through a cache, in BYTES — not seconds,
+ * so unlike the duration helpers this one does not divide.
+ *
+ * `profile` deliberately reuses the label key {@link recordCacheMetric} already
+ * uses for the `cachedLoader` layer (there it carries the loader name), so
+ * `deco.cache.size` joins `deco.cache.requests{layer="cachedLoader"}` on
+ * `profile` with no renaming in the query.
+ *
+ * Only `op: "set"` is emitted today; the label exists so a future read-side
+ * measurement lands on the same series without a breaking dashboard change.
+ */
+export function recordCacheSizeMetric(bytes: number, profile: string, op: "set" | "get" = "set") {
+  getState().meter?.histogramRecord?.(MetricNames.CACHE_SIZE, bytes, { op, profile });
+}
+
 /**
  * Labels for the outbound commerce sample recorded on
  * `http.client.request.duration`. Owned by the framework so apps-start (and

package/src/sdk/cachedLoader.ts

@@ -13,6 +13,7 @@
 
 import {
   recordCacheMetric,
+  recordCacheSizeMetric,
   recordLoaderError,
   recordLoaderMetric,
   withTracing,
@@ -78,7 +79,6 @@ export interface LoaderModule<TProps = any, TResult = any> {
   cacheKey?: (props: TProps, req?: Request) => string | null;
 }
 
-
 interface CacheEntry<T = unknown> {
   value: T;
   createdAt: number;
@@ -102,16 +102,41 @@ const DEFAULT_MAX_AGE = 60_000;
 const DEFAULT_MAX_CACHE_BYTES = 32 * 1024 * 1024;
 
 function resolveMaxBytes(): number {
-  const env = typeof globalThis.process !== "undefined"
-    ? globalThis.process.env
-    : undefined;
+  const env = typeof globalThis.process !== "undefined" ? globalThis.process.env : undefined;
   const raw = env?.DECO_LOADER_CACHE_MAX_BYTES;
   if (!raw) return DEFAULT_MAX_CACHE_BYTES;
   const parsed = Number.parseInt(raw, 10);
   return Number.isFinite(parsed) && parsed > 0 ? parsed : DEFAULT_MAX_CACHE_BYTES;
 }
 
-const MAX_CACHE_BYTES = resolveMaxBytes();
+let maxCacheBytes = resolveMaxBytes();
+
+/**
+ * Override the loader cache byte cap at runtime.
+ *
+ * The `DECO_LOADER_CACHE_MAX_BYTES` env override above only lands when the
+ * Worker's `compatibility_date` is new enough for `nodejs_compat` to populate
+ * `process.env`. Verified in workerd: with `2024-09-23` it is empty both at
+ * module scope and inside the handler; with `2025-06-01` it is populated. Sites
+ * pinned to an older date — a common thing to do, since the date also gates
+ * behaviour flags they may have tuned deliberately — had a documented knob that
+ * silently did nothing.
+ *
+ * Call this from the site's `setup.ts`, before any loader is wrapped.
+ *
+ * Sizing note: the cap is per ISOLATE, not per site, and a Worker isolate has
+ * 128 MB total, shared with the bundle, the V8 heap and the render working set.
+ * Setting it at or near 128 MB does not give headroom — it removes the ceiling.
+ */
+export function setLoaderCacheMaxBytes(bytes: number): void {
+  if (!Number.isFinite(bytes) || bytes <= 0) return;
+  maxCacheBytes = bytes;
+}
+
+/** Current byte cap — exported for diagnostics and tests. */
+export function getLoaderCacheMaxBytes(): number {
+  return maxCacheBytes;
+}
 
 const cache = new Map<string, CacheEntry>();
 let cacheBytes = 0;
@@ -147,7 +172,13 @@ function estimateBytes(value: unknown): number {
   }
 }
 
-function setCacheEntry<T>(key: string, entry: CacheEntry<T>) {
+/**
+ * The single write path into the cache — both the cold-miss and the SWR
+ * background-refresh callers route through here, which is why the size metric
+ * is emitted at this chokepoint rather than at each call site.
+ */
+function setCacheEntry<T>(key: string, entry: CacheEntry<T>, name: string) {
+  recordCacheSizeMetric(entry.estimatedBytes, name);
   const prev = cache.get(key);
   if (prev) cacheBytes -= prev.estimatedBytes;
   cacheBytes += entry.estimatedBytes;
@@ -162,13 +193,11 @@ function deleteCacheEntry(key: string) {
 }
 
 function evictIfNeeded() {
-  if (cacheBytes <= MAX_CACHE_BYTES) return;
-  const oldest = [...cache.entries()].sort(
-    (a, b) => a[1].createdAt - b[1].createdAt,
-  );
+  if (cacheBytes <= maxCacheBytes) return;
+  const oldest = [...cache.entries()].sort((a, b) => a[1].createdAt - b[1].createdAt);
   for (const [key] of oldest) {
     deleteCacheEntry(key);
-    if (cacheBytes <= MAX_CACHE_BYTES) break;
+    if (cacheBytes <= maxCacheBytes) break;
   }
 }
 
@@ -246,11 +275,10 @@ export function createCachedLoader<TProps, TResult>(
       recordCacheMetric(false, name, undefined, "cachedLoader");
       const devStart = performance.now();
       const promise = withInflightTimeout(
-        withTracing(
-          "deco.cachedLoader",
-          () => loaderFn(props),
-          { "deco.loader": name, "deco.cache.policy": "no-cache-dev" },
-        ),
+        withTracing("deco.cachedLoader", () => loaderFn(props), {
+          "deco.loader": name,
+          "deco.cache.policy": "no-cache-dev",
+        }),
         `cachedLoader:dev ${cacheKey}`,
       )
         .then((r) => {
@@ -296,12 +324,16 @@ export function createCachedLoader<TProps, TResult>(
             // Skip the write if a purge cleared the cache mid-refresh — otherwise
             // we'd re-insert pre-purge data the purge was meant to drop.
             if (gen !== cacheGeneration) return;
-            setCacheEntry(cacheKey, {
-              value: result,
-              createdAt: Date.now(),
-              refreshing: false,
-              estimatedBytes: estimateBytes(result),
-            });
+            setCacheEntry(
+              cacheKey,
+              {
+                value: result,
+                createdAt: Date.now(),
+                refreshing: false,
+                estimatedBytes: estimateBytes(result),
+              },
+              name,
+            );
             evictIfNeeded();
           })
           .catch(() => {
@@ -341,12 +373,16 @@ export function createCachedLoader<TProps, TResult>(
         // Skip caching if a purge landed while this loader was in flight — still
         // return the fresh value to the caller, just don't persist a raced entry.
         if (gen === cacheGeneration) {
-          setCacheEntry(cacheKey, {
-            value: result,
-            createdAt: Date.now(),
-            refreshing: false,
-            estimatedBytes: estimateBytes(result),
-          });
+          setCacheEntry(
+            cacheKey,
+            {
+              value: result,
+              createdAt: Date.now(),
+              refreshing: false,
+              estimatedBytes: estimateBytes(result),
+            },
+            name,
+          );
           evictIfNeeded();
         }
         return result;
@@ -374,7 +410,6 @@ export function createCachedLoader<TProps, TResult>(
   };
 }
 
-
 // ---------------------------------------------------------------------------
 // Module loader dedup (the `@decocms/apps` cache/cacheKey convention)
 //
@@ -404,11 +439,12 @@ export function createCachedLoaderFromModule<TProps, TResult>(
   name: string,
   mod: LoaderModule<TProps, TResult>,
 ): (props: TProps, req?: Request) => Promise<TResult> {
-  const policy: CachePolicy = typeof mod.cache === "string"
-    ? mod.cache
-    : mod.cache && typeof mod.cache === "object"
-      ? "stale-while-revalidate"
-      : "no-store";
+  const policy: CachePolicy =
+    typeof mod.cache === "string"
+      ? mod.cache
+      : mod.cache && typeof mod.cache === "object"
+        ? "stale-while-revalidate"
+        : "no-store";
 
   // Only `stale-while-revalidate` (or `{ maxAge }`) opts into dedup — matching
   // `@decocms/apps`/deco, where `no-store` (the default) and `no-cache` both
@@ -459,9 +495,7 @@ export function createLoaderEntry<TProps = any, TResult = any>(
   // first-calls — exactly the N-sections-per-render case — share one import
   // instead of racing into N. Reset on failure so a transient import error can
   // retry rather than poisoning the entry forever.
-  let wrappedPromise:
-    | Promise<(props: TProps, req?: Request) => Promise<TResult>>
-    | undefined;
+  let wrappedPromise: Promise<(props: TProps, req?: Request) => Promise<TResult>> | undefined;
   return (props: TProps, req?: Request): Promise<TResult> => {
     if (!wrappedPromise) {
       wrappedPromise = importFn()
@@ -498,6 +532,6 @@ export function getLoaderCacheStats() {
     entries: cache.size,
     inflight: inflightRequests.size,
     estimatedBytes: cacheBytes,
-    maxBytes: MAX_CACHE_BYTES,
+    maxBytes: maxCacheBytes,
   };
 }

package/src/sdk/cachedLoaderMaxBytes.test.ts

@@ -0,0 +1,23 @@
+import { describe, expect, it } from "vitest";
+import { getLoaderCacheMaxBytes, setLoaderCacheMaxBytes } from "./cachedLoader";
+
+describe("loader cache byte cap", () => {
+  it("defaults to 32 MB", () => {
+    // process.env is empty in workerd unless compatibility_date is new enough,
+    // which is exactly why the setter below exists.
+    expect(getLoaderCacheMaxBytes()).toBe(32 * 1024 * 1024);
+  });
+
+  it("can be raised programmatically", () => {
+    setLoaderCacheMaxBytes(64 * 1024 * 1024);
+    expect(getLoaderCacheMaxBytes()).toBe(64 * 1024 * 1024);
+  });
+
+  it("ignores nonsense instead of disabling eviction", () => {
+    setLoaderCacheMaxBytes(64 * 1024 * 1024);
+    for (const bad of [0, -1, Number.NaN, Number.POSITIVE_INFINITY]) {
+      setLoaderCacheMaxBytes(bad);
+      expect(getLoaderCacheMaxBytes()).toBe(64 * 1024 * 1024);
+    }
+  });
+});

package/src/sdk/cachedLoaderSizeMetric.test.ts

@@ -0,0 +1,93 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { configureMeter, MetricNames } from "../middleware/observability";
+import { clearLoaderCache, createCachedLoader } from "./cachedLoader";
+
+type Sample = { name: string; value: number; labels?: Record<string, unknown> };
+
+function fakeMeter(samples: Sample[]) {
+  return {
+    counterInc: () => {},
+    gaugeSet: () => {},
+    histogramRecord: (name: string, value: number, labels?: Record<string, unknown>) => {
+      samples.push({ name, value, labels });
+    },
+  };
+}
+
+const sizeSamples = (samples: Sample[]) => samples.filter((s) => s.name === MetricNames.CACHE_SIZE);
+
+describe("deco.cache.size — emitted on every loader cache write", () => {
+  let samples: Sample[];
+
+  beforeEach(() => {
+    clearLoaderCache();
+    samples = [];
+    configureMeter(fakeMeter(samples));
+  });
+
+  afterEach(() => {
+    clearLoaderCache();
+    configureMeter({ counterInc: () => {} }); // drop the recorder
+    vi.useRealTimers();
+    vi.restoreAllMocks();
+  });
+
+  it("records one sample on the cold-miss write, labelled op=set + the loader name", async () => {
+    const cached = createCachedLoader("t/size-miss", async (p: { id: number }) => ({ v: p.id }), {
+      policy: "stale-while-revalidate",
+      maxAge: 60_000,
+    });
+
+    await cached({ id: 1 });
+
+    const sizes = sizeSamples(samples);
+    expect(sizes).toHaveLength(1);
+    expect(sizes[0].labels).toEqual({ op: "set", profile: "t/size-miss" });
+    // Bytes, not seconds — and floored at MIN_ENTRY_BYTES for a tiny payload.
+    expect(sizes[0].value).toBe(512);
+  });
+
+  it("does not re-record on a HIT — only writes are measured", async () => {
+    const cached = createCachedLoader("t/size-hit", async (p: { id: number }) => ({ v: p.id }), {
+      policy: "stale-while-revalidate",
+      maxAge: 60_000,
+    });
+
+    await cached({ id: 1 }); // MISS -> write
+    await cached({ id: 1 }); // HIT  -> no write
+
+    expect(sizeSamples(samples)).toHaveLength(1);
+  });
+
+  it("records the SWR background-refresh write too, not just the cold miss", async () => {
+    vi.useFakeTimers();
+    vi.setSystemTime(new Date("2026-05-18T16:00:00.000Z"));
+
+    const cached = createCachedLoader("t/size-swr", async (p: { id: number }) => ({ v: p.id }), {
+      policy: "stale-while-revalidate",
+      maxAge: 1_000,
+    });
+
+    await cached({ id: 1 }); // MISS -> write #1
+    vi.setSystemTime(new Date("2026-05-18T16:00:05.000Z")); // now stale
+    await cached({ id: 1 }); // STALE-HIT -> background refresh
+    await vi.runAllTimersAsync(); // let the refresh settle
+
+    const sizes = sizeSamples(samples);
+    expect(sizes).toHaveLength(2); // write #2 came from the refresh
+    expect(sizes.every((s) => s.labels?.op === "set")).toBe(true);
+    expect(sizes.every((s) => s.labels?.profile === "t/size-swr")).toBe(true);
+  });
+
+  it("scales with the payload so a fat loader is distinguishable from a thin one", async () => {
+    const big = { blob: "x".repeat(50_000) };
+    const cached = createCachedLoader("t/size-big", async () => big, {
+      policy: "stale-while-revalidate",
+      maxAge: 60_000,
+    });
+
+    await cached({});
+
+    expect(sizeSamples(samples)[0].value).toBeGreaterThan(50_000);
+  });
+});

package/src/sdk/observability.ts

@@ -64,6 +64,7 @@ export {
   type MeterAdapter,
   MetricNames,
   recordCacheMetric,
+  recordCacheSizeMetric,
   recordCommerceMetric,
   recordLoaderError,
   recordLoaderMetric,

package/src/sdk/otelHttpMeter.test.ts

@@ -63,6 +63,15 @@ function buildAdapter(
     nowMs?: () => number;
     onError?: (kind: "flush" | "overflow" | "kind-mismatch", err: unknown) => void;
     histogramBounds?: number[];
+    metricMetadata?: Record<
+      string,
+      {
+        description?: string;
+        unit?: string;
+        aggregation?: "explicit" | "exponential";
+        scale?: number;
+      }
+    >;
   } = {},
 ) {
   return createOtlpHttpMeterAdapter({
@@ -78,6 +87,7 @@ function buildAdapter(
     nowMs: overrides.nowMs,
     onError: overrides.onError,
     histogramBounds: overrides.histogramBounds,
+    metricMetadata: overrides.metricMetadata,
   });
 }
 
@@ -290,3 +300,166 @@ describe("createOtlpHttpMeterAdapter — buffer + flush", () => {
     expect(slow).toHaveBeenCalledTimes(1);
   });
 });
+
+// ---------------------------------------------------------------------------
+// Exponential histograms (deco.cache.size)
+// ---------------------------------------------------------------------------
+
+interface ExpHistogramMetric {
+  name: string;
+  unit?: string;
+  histogram?: unknown;
+  exponentialHistogram?: {
+    aggregationTemporality: number;
+    dataPoints: Array<{
+      attributes: Array<{ key: string; value: Record<string, unknown> }>;
+      count: string;
+      sum: number;
+      min: number;
+      max: number;
+      scale: number;
+      zeroCount: string;
+      positive: { offset: number; bucketCounts: string[] };
+    }>;
+  };
+}
+
+function metricsFrom(calls: Array<{ init?: RequestInit }>): ExpHistogramMetric[] {
+  const payload = JSON.parse(calls[0].init!.body as string) as {
+    resourceMetrics: Array<{ scopeMetrics: Array<{ metrics: ExpHistogramMetric[] }> }>;
+  };
+  return payload.resourceMetrics[0].scopeMetrics[0].metrics;
+}
+
+const CACHE_SIZE_META = {
+  "deco.cache.size": {
+    description: "Size in bytes of values written to / read from a cache, dimensioned by op.",
+    unit: "By",
+    aggregation: "exponential" as const,
+    // base 4 — the scale the framework declares for byte sizes.
+    scale: -1,
+  },
+};
+
+describe("createOtlpHttpMeterAdapter — exponential histogram", () => {
+  beforeEach(() => {
+    vi.useFakeTimers();
+    vi.setSystemTime(new Date("2026-05-18T16:00:00.000Z"));
+  });
+
+  afterEach(() => {
+    vi.useRealTimers();
+    vi.restoreAllMocks();
+  });
+
+  it("buckets byte sizes at scale -1 and exports OTLP exponentialHistogram", async () => {
+    const { impl, calls } = captureFetch();
+    const meter = buildAdapter({ fetchImpl: impl, metricMetadata: CACHE_SIZE_META });
+
+    // base 4. Bucket i covers (4^i, 4^(i+1)], upper-inclusive:
+    //   512  -> index 4  (256, 1024]
+    //   1024 -> index 4  (256, 1024]  — exact power of the base stays LOW
+    //   4096 -> index 5  (1024, 4096]
+    const labels = { op: "set", profile: "productList" };
+    meter.histogramRecord("deco.cache.size", 512, labels);
+    meter.histogramRecord("deco.cache.size", 1024, labels);
+    meter.histogramRecord("deco.cache.size", 4096, labels);
+
+    await meter.flush();
+
+    const m = metricsFrom(calls)[0];
+    expect(m.name).toBe("deco.cache.size");
+    expect(m.unit).toBe("By");
+    // Must NOT be serialized as an explicit-bounds histogram.
+    expect(m.histogram).toBeUndefined();
+
+    const dp = m.exponentialHistogram!.dataPoints[0];
+    expect(m.exponentialHistogram!.aggregationTemporality).toBe(2); // CUMULATIVE
+    expect(dp.scale).toBe(-1);
+    expect(dp.count).toBe("3");
+    expect(dp.sum).toBe(512 + 1024 + 4096);
+    expect(dp.min).toBe(512);
+    expect(dp.max).toBe(4096);
+    expect(dp.zeroCount).toBe("0");
+    // offset is the index of bucketCounts[0]; two counts in bucket 4, one in 5.
+    expect(dp.positive.offset).toBe(4);
+    expect(dp.positive.bucketCounts).toEqual(["2", "1"]);
+    expect(dp.attributes.map((a) => a.key)).toEqual(["op", "profile"]);
+  });
+
+  it("fills gaps between populated buckets so offset+i stays aligned", async () => {
+    const { impl, calls } = captureFetch();
+    const meter = buildAdapter({ fetchImpl: impl, metricMetadata: CACHE_SIZE_META });
+
+    // 512 -> index 4, 32 MB -> index 12. Everything between must be zero-filled,
+    // otherwise the consumer reads the top bucket at the wrong boundary.
+    meter.histogramRecord("deco.cache.size", 512, { op: "set" });
+    meter.histogramRecord("deco.cache.size", 32 * 1024 * 1024, { op: "set" });
+
+    await meter.flush();
+
+    const dp = metricsFrom(calls)[0].exponentialHistogram!.dataPoints[0];
+    expect(dp.positive.offset).toBe(4);
+    expect(dp.positive.bucketCounts).toEqual(["1", "0", "0", "0", "0", "0", "0", "0", "1"]);
+  });
+
+  it("splits series per attr-key, like the explicit histogram does", async () => {
+    const { impl, calls } = captureFetch();
+    const meter = buildAdapter({ fetchImpl: impl, metricMetadata: CACHE_SIZE_META });
+
+    meter.histogramRecord("deco.cache.size", 512, { op: "set", profile: "a" });
+    meter.histogramRecord("deco.cache.size", 512, { op: "set", profile: "b" });
+
+    await meter.flush();
+
+    expect(metricsFrom(calls)[0].exponentialHistogram!.dataPoints).toHaveLength(2);
+    expect(meter.pendingDatapointCount()).toBe(2);
+  });
+
+  it("folds non-positive observations into zeroCount instead of a bucket", async () => {
+    const { impl, calls } = captureFetch();
+    const meter = buildAdapter({ fetchImpl: impl, metricMetadata: CACHE_SIZE_META });
+
+    meter.histogramRecord("deco.cache.size", 0, { op: "set" });
+    meter.histogramRecord("deco.cache.size", 512, { op: "set" });
+
+    await meter.flush();
+
+    const dp = metricsFrom(calls)[0].exponentialHistogram!.dataPoints[0];
+    expect(dp.zeroCount).toBe("1");
+    expect(dp.count).toBe("2");
+    expect(dp.positive.bucketCounts).toEqual(["1"]);
+  });
+
+  it("leaves histograms without exponential metadata on the explicit-bounds path", async () => {
+    const { impl, calls } = captureFetch();
+    const meter = buildAdapter({
+      fetchImpl: impl,
+      histogramBounds: [10, 100],
+      metricMetadata: CACHE_SIZE_META,
+    });
+
+    meter.histogramRecord("deco.loader.duration", 50, { name: "x" });
+
+    await meter.flush();
+
+    const m = metricsFrom(calls)[0] as ExpHistogramMetric & {
+      histogram?: { dataPoints: Array<{ bucketCounts: string[]; explicitBounds: number[] }> };
+    };
+    expect(m.exponentialHistogram).toBeUndefined();
+    expect(m.histogram!.dataPoints[0].explicitBounds).toEqual([10, 100]);
+    expect(m.histogram!.dataPoints[0].bucketCounts).toEqual(["0", "1", "0"]);
+  });
+
+  it("rejects reusing an exponential-histogram name as a counter", async () => {
+    const onError = vi.fn();
+    const { impl } = captureFetch();
+    const meter = buildAdapter({ fetchImpl: impl, metricMetadata: CACHE_SIZE_META, onError });
+
+    meter.histogramRecord("deco.cache.size", 512, { op: "set" });
+    meter.counterInc("deco.cache.size", 1, { op: "set" });
+
+    expect(onError).toHaveBeenCalledWith("kind-mismatch", expect.any(Error));
+    expect(meter.pendingDatapointCount()).toBe(1);
+  });
+});

package/src/sdk/otelHttpMeter.ts

@@ -84,8 +84,19 @@ export interface OtlpHttpMeterOptions {
    * The framework owns the lookup; callers MUST NOT pass metadata at
    * record time. See `MetricNames` / `METRIC_METADATA` in
    * `middleware/observability.ts`.
+   *
+   * `aggregation: "exponential"` also routes `histogramRecord` for that name
+   * to a base-2 exponential histogram at `scale` — no separate adapter method,
+   * so call sites are identical for both aggregations.
    */
-  metricMetadata?: Record<string, { description?: string; unit?: string }>;
+  metricMetadata?: Record<string, MetricMetadata>;
+}
+
+export interface MetricMetadata {
+  description?: string;
+  unit?: string;
+  aggregation?: "explicit" | "exponential";
+  scale?: number;
 }
 
 export interface OtlpHttpMeter extends MeterAdapter {
@@ -103,7 +114,7 @@ export interface OtlpHttpMeter extends MeterAdapter {
 // Internal buffer shapes
 // ---------------------------------------------------------------------------
 
-type MetricKind = "counter" | "gauge" | "histogram";
+type MetricKind = "counter" | "gauge" | "histogram" | "expHistogram";
 
 interface CounterPoint {
   value: number;
@@ -125,11 +136,26 @@ interface HistogramPoint {
   startTimeUnixNano: string;
 }
 
+interface ExpHistogramPoint {
+  count: number;
+  sum: number;
+  min: number;
+  max: number;
+  zeroCount: number;
+  /** Sparse index -> count. Densified to `positive.bucketCounts` at flush. */
+  buckets: Map<number, number>;
+  attrs: Labels;
+  startTimeUnixNano: string;
+}
+
 interface MetricEntry {
   kind: MetricKind;
   counter?: Map<string, CounterPoint>;
   gauge?: Map<string, GaugePoint>;
   histogram?: Map<string, HistogramPoint>;
+  expHistogram?: Map<string, ExpHistogramPoint>;
+  /** Only set for `expHistogram`, captured from metadata at first record. */
+  scale?: number;
 }
 
 // ---------------------------------------------------------------------------
@@ -143,6 +169,18 @@ const DEFAULT_HISTOGRAM_BOUNDS = [
   5, 10, 25, 50, 75, 100, 250, 500, 1000,
 ];
 
+/** Fallback scale when a metric declares `exponential` without one: base 2. */
+const DEFAULT_EXPONENTIAL_SCALE = 0;
+
+/**
+ * Defensive cap on distinct buckets per exponential series. At the scales we
+ * use (base 4 for byte sizes) the real range needs ~9, so hitting this means
+ * the metric is being fed values it wasn't sized for. Rather than let the
+ * sparse Map grow unbounded per isolate, clamp out-of-range indices into the
+ * edge buckets — the distribution's tails stay visible, the memory doesn't.
+ */
+const MAX_EXPONENTIAL_BUCKETS = 160;
+
 export function createOtlpHttpMeterAdapter(options: OtlpHttpMeterOptions): OtlpHttpMeter {
   const endpoint = options.endpoint;
   const resourceAttributes = options.resourceAttributes;
@@ -206,6 +244,7 @@ export function createOtlpHttpMeterAdapter(options: OtlpHttpMeterOptions): OtlpH
     const entry: MetricEntry = { kind };
     if (kind === "counter") entry.counter = new Map();
     else if (kind === "gauge") entry.gauge = new Map();
+    else if (kind === "expHistogram") entry.expHistogram = new Map();
     else entry.histogram = new Map();
     metrics.set(name, entry);
     return entry;
@@ -217,6 +256,7 @@ export function createOtlpHttpMeterAdapter(options: OtlpHttpMeterOptions): OtlpH
       if (entry.counter) n += entry.counter.size;
       if (entry.gauge) n += entry.gauge.size;
       if (entry.histogram) n += entry.histogram.size;
+      if (entry.expHistogram) n += entry.expHistogram.size;
     }
     return n;
   }
@@ -263,6 +303,10 @@ export function createOtlpHttpMeterAdapter(options: OtlpHttpMeterOptions): OtlpH
   }
 
   function histogramRecord(name: string, value: number, labels?: Labels) {
+    if (metricMetadata[name]?.aggregation === "exponential") {
+      expHistogramRecord(name, value, labels);
+      return;
+    }
     const { entry: existing, isNewName } = checkAdmissibility(name, "histogram");
     if (existing === null && !isNewName) return; // kind mismatch
     const key = attrKey(labels);
@@ -301,6 +345,61 @@ export function createOtlpHttpMeterAdapter(options: OtlpHttpMeterOptions): OtlpH
     point.bucketCounts[bucketIdx] += 1;
   }
 
+  function expHistogramRecord(name: string, value: number, labels?: Labels) {
+    const { entry: existing, isNewName } = checkAdmissibility(name, "expHistogram");
+    if (existing === null && !isNewName) return; // kind mismatch
+    const key = attrKey(labels);
+    const isNewDatapoint = !existing?.expHistogram?.has(key);
+    if (isNewDatapoint && pendingDatapointCount() >= maxBuffer) {
+      onError?.("overflow", new Error(`metric buffer at cap (${maxBuffer}) — dropping "${name}"`));
+      return;
+    }
+    const entry = existing ?? materializeEntry(name, "expHistogram");
+    if (!entry.expHistogram) return;
+    const scale = metricMetadata[name]?.scale ?? DEFAULT_EXPONENTIAL_SCALE;
+    entry.scale = scale;
+    let point = entry.expHistogram.get(key);
+    if (!point) {
+      point = {
+        count: 0,
+        sum: 0,
+        min: Number.POSITIVE_INFINITY,
+        max: Number.NEGATIVE_INFINITY,
+        zeroCount: 0,
+        buckets: new Map(),
+        attrs: labels ? { ...labels } : {},
+        startTimeUnixNano: msToNs(isolateStartMs),
+      };
+      entry.expHistogram.set(key, point);
+    }
+    point.count += 1;
+    point.sum += value;
+    if (value < point.min) point.min = value;
+    if (value > point.max) point.max = value;
+
+    // Non-positive values have no base-2 bucket. Per the OTel spec zero goes to
+    // `zeroCount`; we send negatives there too rather than emit a `negative`
+    // range no metric of ours can produce.
+    if (value <= 0) {
+      point.zeroCount += 1;
+      return;
+    }
+
+    // Spec mapping for base 2^(2^-scale): bucket `i` covers (base^i, base^(i+1)],
+    // i.e. upper-inclusive, so an exact power of the base lands in the LOWER
+    // bucket. Hence ceil(...) - 1 and not floor(...).
+    let index = Math.ceil(Math.log2(value) * 2 ** scale) - 1;
+    // Clamp into the existing range once the series is at its bucket budget —
+    // see MAX_EXPONENTIAL_BUCKETS.
+    if (!point.buckets.has(index) && point.buckets.size >= MAX_EXPONENTIAL_BUCKETS) {
+      const indices = [...point.buckets.keys()];
+      const lo = Math.min(...indices);
+      const hi = Math.max(...indices);
+      index = index < lo ? lo : hi;
+    }
+    point.buckets.set(index, (point.buckets.get(index) ?? 0) + 1);
+  }
+
   async function doFlush(): Promise<void> {
     if (metrics.size === 0) return;
 
@@ -410,7 +509,7 @@ interface SerializeOpts {
   scopeVersion: string;
   histogramBounds: number[];
   flushAtNs: string;
-  metricMetadata: Record<string, { description?: string; unit?: string }>;
+  metricMetadata: Record<string, MetricMetadata>;
 }
 
 function serializeOtlp(
@@ -482,6 +581,44 @@ function serializeOtlp(
           dataPoints,
         },
       });
+    } else if (entry.kind === "expHistogram" && entry.expHistogram) {
+      const dataPoints: unknown[] = [];
+      for (const point of entry.expHistogram.values()) {
+        // Densify the sparse index->count map into OTLP's
+        // `positive: { offset, bucketCounts }`: counts run contiguously from
+        // `offset`, so gaps between populated indices must be filled with 0.
+        const indices = [...point.buckets.keys()].sort((a, b) => a - b);
+        const lo = indices[0] ?? 0;
+        const hi = indices[indices.length - 1] ?? -1;
+        const bucketCounts: string[] = [];
+        for (let i = lo; i <= hi; i++) bucketCounts.push(String(point.buckets.get(i) ?? 0));
+        dataPoints.push({
+          attributes: attrsToOtlp(point.attrs),
+          startTimeUnixNano: point.startTimeUnixNano,
+          timeUnixNano: opts.flushAtNs,
+          count: String(point.count),
+          sum: point.sum,
+          min: point.min === Number.POSITIVE_INFINITY ? 0 : point.min,
+          max: point.max === Number.NEGATIVE_INFINITY ? 0 : point.max,
+          scale: entry.scale ?? 0,
+          zeroCount: String(point.zeroCount),
+          // OTLP: bucketCounts[i] counts values in
+          // (base^(offset+i), base^(offset+i+1)] — the same half-open interval
+          // our record-time index uses, so offset is the first index as-is.
+          positive: { offset: lo, bucketCounts },
+          // No `negative` range: every metric on this path is non-negative,
+          // and sub-zero observations are folded into zeroCount at record time.
+        });
+      }
+      otlpMetrics.push({
+        name,
+        description,
+        unit,
+        exponentialHistogram: {
+          aggregationTemporality: 2, // CUMULATIVE
+          dataPoints,
+        },
+      });
     }
   }