@lunora/do 1.0.0-alpha.40 → 1.0.0-alpha.42

package/dist/index.d.mts

@@ -2378,14 +2378,69 @@ interface TraceAnchor {
   rootSpanId: string;
   traceId: string;
 }
+/**
+ * Minimal structural shape of one **Cloudflare custom span** — the object CF's
+ * `tracing.enterSpan(name, (span) => …)` callback receives (GA 2026-06-16). Only
+ * the surface the bridge touches is declared, so `@lunora/do` needs no runtime
+ * dependency on `cloudflare:workers`; the real platform span is structurally
+ * assignable.
+ */
+interface CloudflareSpanLike {
+  /**
+   * Whether this span is actually being recorded by the runtime's sampler.
+   * `false` off the traced path (unsampled) — the bridge skips its
+   * `setAttribute` work in that case rather than building attribute strings for
+   * a span nobody will read.
+   */
+  readonly isTraced: boolean;
+  /** Attach one primitive attribute to the CF span. */
+  setAttribute: (key: string, value: boolean | number | string | undefined) => void;
+}
+/**
+ * Minimal structural shape of the `tracing` namespace exported by
+ * `cloudflare:workers`. `enterSpan` opens a custom span that auto-nests under the
+ * runtime's ambient span and ends when `callback` settles.
+ */
+interface CloudflareTracingLike {
+  enterSpan: <T>(name: string, callback: (span: CloudflareSpanLike) => T) => T;
+}
+/**
+ * Resolves CF's `tracing` namespace, or `undefined` when it is unavailable —
+ * off-Cloudflare, on a compat date predating custom spans, or when
+ * `tracing.enterSpan` is not a function. **Injected, never imported here**, so the
+ * tracer stays pure and unit-testable without `cloudflare:workers`; the shard
+ * supplies the real resolver, tests a fake or `undefined`.
+ */
+type CloudflareTracingResolver = () => CloudflareTracingLike | Promise<CloudflareTracingLike | undefined> | undefined;
 /** What {@link createTracer} needs from the shard to build a span. */
 interface TracerDeps {
   /** The trace this ctx's spans belong to. */
   anchor: TraceAnchor;
   /** Function path the spans are attributed to. */
   functionPath: string;
+  /**
+   * **Opt-in, EXPERIMENTAL, default off.** When `true` *and*
+   * {@link TracerDeps.resolveCloudflareTracing} yields a working
+   * `tracing.enterSpan`, each `ctx.trace` span is ALSO emitted as a Cloudflare
+   * **custom span**, so it nests inside CF's native binding/fetch/handler trace
+   * tree on the hosted path. This only ADDS a CF-side span — the recorded
+   * {@link SpanEvent} (our `SpanBuffer`/`otlpSink`) is untouched and remains the
+   * source of truth plus the local studio waterfall. The `enterSpan` call itself
+   * is now workerd-validated as available and side-effect-free inside a Durable
+   * Object; CF's exported parent-linking under sampling remains unverified. See
+   * {@link createTracer} for the double-export and Durable-Object async-context
+   * caveats.
+   */
+  fuseCloudflareSpans?: boolean;
   /** Hand a finished span to the buffer + sink. */
   record: (span: SpanEvent) => void;
+  /**
+   * Injected resolver for CF's `tracing` namespace (see
+   * {@link CloudflareTracingResolver}). Only consulted when
+   * {@link TracerDeps.fuseCloudflareSpans} is `true`, so the default path never
+   * calls it.
+   */
+  resolveCloudflareTracing?: CloudflareTracingResolver;
   /** Shard key for single-shard calls; absent for the unnamed root DO. */
   shardKey: string | undefined;
   /** Read lazily — the acting user is resolved per span, not per ctx. */
@@ -2418,6 +2473,40 @@ interface MetricsDeps {
  * cleared in the dispatch `finally`, and a subscription re-run builds its ctx
  * during* the writing mutation's flush — so reading that shared field at span
  * time would file the re-run's spans under the mutation's trace.
+ *
+ * **Cloudflare custom-spans bridge (opt-in, EXPERIMENTAL).** When
+ * `deps.fuseCloudflareSpans` is `true` and `deps.resolveCloudflareTracing` yields
+ * a working `tracing.enterSpan` (`cloudflare:workers`, GA 2026-06-16), each span
+ * body runs inside a CF custom span so our span nests under CF's native
+ * binding/fetch/handler trace tree on the hosted path, and the finished span's
+ * key attributes are mirrored onto it (gated on `span.isTraced`). Two deliberate
+ * boundaries hold.
+ *
+ * **No double-export by default, and never a replacement.** The bridge only ADDS a
+ * CF-side span; the recorded {@link SpanEvent} handed to `record` (our
+ * `SpanBuffer`/`otlpSink`) is byte-for-byte the same as without the bridge and
+ * stays the source of truth. It is off unless explicitly enabled precisely
+ * because, once on, a deployment that ALSO ships our `otlpSink` to a collector
+ * AND lets CF export its trace tree emits the same logical span down two
+ * pipelines — an intentional, documented trade the operator opts into, not a
+ * default.
+ *
+ * **DO async-context caveat (EXPERIMENTAL, partially workerd-validated).**
+ * `tracing.enterSpan` is now confirmed to EXIST and RUN inside a real Durable
+ * Object under `@cloudflare/vitest-pool-workers` (see
+ * `__tests__/workerd/context-telemetry-cf-bridge.workerd.test.ts`): it resolves
+ * from `cloudflare:workers`, its callback executes and returns the body value
+ * without throwing, `span.isTraced` is a real boolean, and — the key additive
+ * guarantee — our recorded {@link SpanEvent} tree (parent/child via the threaded
+ * `parentSpanId`) is byte-for-byte identical with the bridge on vs off. What that
+ * harness CANNOT prove is CF's own *exported* parent-linking: with no trace head
+ * attached the run is unsampled (`isTraced === false`), so CF records nothing and
+ * its span tree is not introspectable. So `enterSpan`'s ambient-span parent-linking
+ * inside a DO stays unverified upstream, and this remains capability-probed: an
+ * absent/undefined `tracing`, a missing `enterSpan`, or an off-CF/unsampled run all
+ * resolve to `undefined`/no-op — exact prior behavior. If CF's ambient-span linkage
+ * misbehaves in a DO, the worst case is a mis-parented CF span; our own recorded
+ * waterfall is unaffected.
  */
 declare const createTracer: (deps: TracerDeps) => ContextTracer;
 /**
@@ -4324,6 +4413,20 @@ declare const subscriptionListDeltas: (previousJson: string, nextResult: unknown
  * `@lunora/runtime`'s `ObservabilitySink` without taking a dependency on it.
  */
 interface TelemetrySink {
+  /**
+   * **Opt-in, EXPERIMENTAL, default off.** When `true`, each `ctx.trace` span is
+   * ALSO emitted as a Cloudflare **custom span** (`tracing.enterSpan` from
+   * `cloudflare:workers`, GA 2026-06-16) so it nests inside CF's native trace
+   * tree on the hosted path — capability-probed, and a safe no-op off-CF / on an
+   * older compat date / when unsampled. This only ADDS a CF-side span; the
+   * `onSpan` event below (our `SpanBuffer`/`otlpSink`) is unchanged and stays the
+   * source of truth. The bridge is now workerd-validated as available and
+   * side-effect-free inside a real DO (our recorded spans stay intact); CF's
+   * exported parent-linking under sampling is still unverified, so it stays
+   * EXPERIMENTAL. Mirror of `@lunora/runtime`'s `ObservabilitySink`
+   * `fuseCloudflareTraces`; see {@link createTracer} for the double-export caveat.
+   */
+  fuseCloudflareTraces?: boolean;
   onLog?: (event: LogEventInput, context?: LogSinkContext) => void;
   onMetric?: (event: MetricEvent, context?: LogSinkContext) => void;
   onSpan?: (event: SpanEvent, context?: LogSinkContext) => void;
@@ -5921,6 +6024,9 @@ declare abstract class ShardDO {
    * `anchor` is the trace this ctx's spans belong to; omit it for a ctx with no
    * owning dispatch (an alarm, a subscription re-run) to mint a fresh anchor, so
    * `ctx.trace` still yields a coherent self-contained trace there.
+   *
+   * The Cloudflare custom-spans bridge is threaded here but stays off unless the
+   * resolved sink sets `fuseCloudflareTraces` (see {@link resolveCloudflareTracing}).
    */
   protected makeTracer(functionPath: string, sink?: TelemetrySink, anchor?: TraceAnchor): ContextTracer;
   /**

package/dist/index.d.ts

@@ -2378,14 +2378,69 @@ interface TraceAnchor {
   rootSpanId: string;
   traceId: string;
 }
+/**
+ * Minimal structural shape of one **Cloudflare custom span** — the object CF's
+ * `tracing.enterSpan(name, (span) => …)` callback receives (GA 2026-06-16). Only
+ * the surface the bridge touches is declared, so `@lunora/do` needs no runtime
+ * dependency on `cloudflare:workers`; the real platform span is structurally
+ * assignable.
+ */
+interface CloudflareSpanLike {
+  /**
+   * Whether this span is actually being recorded by the runtime's sampler.
+   * `false` off the traced path (unsampled) — the bridge skips its
+   * `setAttribute` work in that case rather than building attribute strings for
+   * a span nobody will read.
+   */
+  readonly isTraced: boolean;
+  /** Attach one primitive attribute to the CF span. */
+  setAttribute: (key: string, value: boolean | number | string | undefined) => void;
+}
+/**
+ * Minimal structural shape of the `tracing` namespace exported by
+ * `cloudflare:workers`. `enterSpan` opens a custom span that auto-nests under the
+ * runtime's ambient span and ends when `callback` settles.
+ */
+interface CloudflareTracingLike {
+  enterSpan: <T>(name: string, callback: (span: CloudflareSpanLike) => T) => T;
+}
+/**
+ * Resolves CF's `tracing` namespace, or `undefined` when it is unavailable —
+ * off-Cloudflare, on a compat date predating custom spans, or when
+ * `tracing.enterSpan` is not a function. **Injected, never imported here**, so the
+ * tracer stays pure and unit-testable without `cloudflare:workers`; the shard
+ * supplies the real resolver, tests a fake or `undefined`.
+ */
+type CloudflareTracingResolver = () => CloudflareTracingLike | Promise<CloudflareTracingLike | undefined> | undefined;
 /** What {@link createTracer} needs from the shard to build a span. */
 interface TracerDeps {
   /** The trace this ctx's spans belong to. */
   anchor: TraceAnchor;
   /** Function path the spans are attributed to. */
   functionPath: string;
+  /**
+   * **Opt-in, EXPERIMENTAL, default off.** When `true` *and*
+   * {@link TracerDeps.resolveCloudflareTracing} yields a working
+   * `tracing.enterSpan`, each `ctx.trace` span is ALSO emitted as a Cloudflare
+   * **custom span**, so it nests inside CF's native binding/fetch/handler trace
+   * tree on the hosted path. This only ADDS a CF-side span — the recorded
+   * {@link SpanEvent} (our `SpanBuffer`/`otlpSink`) is untouched and remains the
+   * source of truth plus the local studio waterfall. The `enterSpan` call itself
+   * is now workerd-validated as available and side-effect-free inside a Durable
+   * Object; CF's exported parent-linking under sampling remains unverified. See
+   * {@link createTracer} for the double-export and Durable-Object async-context
+   * caveats.
+   */
+  fuseCloudflareSpans?: boolean;
   /** Hand a finished span to the buffer + sink. */
   record: (span: SpanEvent) => void;
+  /**
+   * Injected resolver for CF's `tracing` namespace (see
+   * {@link CloudflareTracingResolver}). Only consulted when
+   * {@link TracerDeps.fuseCloudflareSpans} is `true`, so the default path never
+   * calls it.
+   */
+  resolveCloudflareTracing?: CloudflareTracingResolver;
   /** Shard key for single-shard calls; absent for the unnamed root DO. */
   shardKey: string | undefined;
   /** Read lazily — the acting user is resolved per span, not per ctx. */
@@ -2418,6 +2473,40 @@ interface MetricsDeps {
  * cleared in the dispatch `finally`, and a subscription re-run builds its ctx
  * during* the writing mutation's flush — so reading that shared field at span
  * time would file the re-run's spans under the mutation's trace.
+ *
+ * **Cloudflare custom-spans bridge (opt-in, EXPERIMENTAL).** When
+ * `deps.fuseCloudflareSpans` is `true` and `deps.resolveCloudflareTracing` yields
+ * a working `tracing.enterSpan` (`cloudflare:workers`, GA 2026-06-16), each span
+ * body runs inside a CF custom span so our span nests under CF's native
+ * binding/fetch/handler trace tree on the hosted path, and the finished span's
+ * key attributes are mirrored onto it (gated on `span.isTraced`). Two deliberate
+ * boundaries hold.
+ *
+ * **No double-export by default, and never a replacement.** The bridge only ADDS a
+ * CF-side span; the recorded {@link SpanEvent} handed to `record` (our
+ * `SpanBuffer`/`otlpSink`) is byte-for-byte the same as without the bridge and
+ * stays the source of truth. It is off unless explicitly enabled precisely
+ * because, once on, a deployment that ALSO ships our `otlpSink` to a collector
+ * AND lets CF export its trace tree emits the same logical span down two
+ * pipelines — an intentional, documented trade the operator opts into, not a
+ * default.
+ *
+ * **DO async-context caveat (EXPERIMENTAL, partially workerd-validated).**
+ * `tracing.enterSpan` is now confirmed to EXIST and RUN inside a real Durable
+ * Object under `@cloudflare/vitest-pool-workers` (see
+ * `__tests__/workerd/context-telemetry-cf-bridge.workerd.test.ts`): it resolves
+ * from `cloudflare:workers`, its callback executes and returns the body value
+ * without throwing, `span.isTraced` is a real boolean, and — the key additive
+ * guarantee — our recorded {@link SpanEvent} tree (parent/child via the threaded
+ * `parentSpanId`) is byte-for-byte identical with the bridge on vs off. What that
+ * harness CANNOT prove is CF's own *exported* parent-linking: with no trace head
+ * attached the run is unsampled (`isTraced === false`), so CF records nothing and
+ * its span tree is not introspectable. So `enterSpan`'s ambient-span parent-linking
+ * inside a DO stays unverified upstream, and this remains capability-probed: an
+ * absent/undefined `tracing`, a missing `enterSpan`, or an off-CF/unsampled run all
+ * resolve to `undefined`/no-op — exact prior behavior. If CF's ambient-span linkage
+ * misbehaves in a DO, the worst case is a mis-parented CF span; our own recorded
+ * waterfall is unaffected.
  */
 declare const createTracer: (deps: TracerDeps) => ContextTracer;
 /**
@@ -4324,6 +4413,20 @@ declare const subscriptionListDeltas: (previousJson: string, nextResult: unknown
  * `@lunora/runtime`'s `ObservabilitySink` without taking a dependency on it.
  */
 interface TelemetrySink {
+  /**
+   * **Opt-in, EXPERIMENTAL, default off.** When `true`, each `ctx.trace` span is
+   * ALSO emitted as a Cloudflare **custom span** (`tracing.enterSpan` from
+   * `cloudflare:workers`, GA 2026-06-16) so it nests inside CF's native trace
+   * tree on the hosted path — capability-probed, and a safe no-op off-CF / on an
+   * older compat date / when unsampled. This only ADDS a CF-side span; the
+   * `onSpan` event below (our `SpanBuffer`/`otlpSink`) is unchanged and stays the
+   * source of truth. The bridge is now workerd-validated as available and
+   * side-effect-free inside a real DO (our recorded spans stay intact); CF's
+   * exported parent-linking under sampling is still unverified, so it stays
+   * EXPERIMENTAL. Mirror of `@lunora/runtime`'s `ObservabilitySink`
+   * `fuseCloudflareTraces`; see {@link createTracer} for the double-export caveat.
+   */
+  fuseCloudflareTraces?: boolean;
   onLog?: (event: LogEventInput, context?: LogSinkContext) => void;
   onMetric?: (event: MetricEvent, context?: LogSinkContext) => void;
   onSpan?: (event: SpanEvent, context?: LogSinkContext) => void;
@@ -5921,6 +6024,9 @@ declare abstract class ShardDO {
    * `anchor` is the trace this ctx's spans belong to; omit it for a ctx with no
    * owning dispatch (an alarm, a subscription re-run) to mint a fresh anchor, so
    * `ctx.trace` still yields a coherent self-contained trace there.
+   *
+   * The Cloudflare custom-spans bridge is threaded here but stays off unless the
+   * resolved sink sets `fuseCloudflareTraces` (see {@link resolveCloudflareTracing}).
    */
   protected makeTracer(functionPath: string, sink?: TelemetrySink, anchor?: TraceAnchor): ContextTracer;
   /**

package/dist/index.mjs

@@ -3,7 +3,7 @@ export { AGGREGATE_SQL_FUNCTION, aggregateSqlFunction, matchesStaticWhere, norma
 export { aggregateTableName, coerceAggregateNumber, encodeAggregateKey, foldAggregateTally, readAggregateValue } from './packem_shared/aggregateTableName-CxNqY1Sl.mjs';
 export { CountRlsUnsupportedError, mergeWhere, planAggregateLookup, selectIndexForAggregate, selectIndexForCount, selectIndexForGroupBy } from './packem_shared/CountRlsUnsupportedError-BGxj0pgS.mjs';
 export { AUTH_METRICS_BUCKETS_TABLE, AUTH_METRICS_BUCKET_MS, AUTH_METRICS_BUCKET_RETENTION, AUTH_METRICS_TABLE, ensureAuthMetricsTables, readAuthMetrics, recordAuthEvent } from './packem_shared/AUTH_METRICS_BUCKETS_TABLE-CiHHYeJi.mjs';
-export { c as createMetrics, a as createTracer, d as dispatchRootSpan } from './packem_shared/context-telemetry-BVSDl6PU.mjs';
+export { c as createMetrics, a as createTracer, d as dispatchRootSpan } from './packem_shared/context-telemetry-CDpyil58.mjs';
 export { NotUniqueError, assertValidClientId, createShardCtxDb, normalizeIdStructurally } from './packem_shared/NotUniqueError-DbtlWwcG.mjs';
 export { DATA_MIGRATION_STATE_TABLE, readMigrationStatus, runDataMigration } from './packem_shared/DATA_MIGRATION_STATE_TABLE-CYwBpyTr.mjs';
 export { SCAN_DEP, createDependencyTracker, depKey } from './packem_shared/SCAN_DEP-DLJF8dsj.mjs';
@@ -28,7 +28,7 @@ export { RLS_UNWRAP_SYMBOL, RlsRequiredError, guardWriter } from './packem_share
 export { buildFtsMatch, ftsTableName, scoreDocument, stringifySearchText, tokenizeSearch } from './packem_shared/buildFtsMatch-BLEMawrp.mjs';
 export { M as MIN_ADMIN_TOKEN_LENGTH, a as MIN_AUTH_SECRET_LENGTH, b as buildSecurityAudit } from './packem_shared/security-audit-CucgBice.mjs';
 export { SESSION_DO_TTL_DEFAULT, SessionDO } from './packem_shared/SESSION_DO_TTL_DEFAULT-BnSKgVO4.mjs';
-export { ROOT_DO_SIZE_WARN_BYTES, ROOT_SHARD_NAME, ShardDO } from './packem_shared/ROOT_DO_SIZE_WARN_BYTES-COEnnBhO.mjs';
+export { ROOT_DO_SIZE_WARN_BYTES, ROOT_SHARD_NAME, ShardDO } from './packem_shared/ROOT_DO_SIZE_WARN_BYTES-B_zt4RQE.mjs';
 export { SHARD_REGISTRY_DO_NAME, ShardRegistryDO } from './packem_shared/SHARD_REGISTRY_DO_NAME-D99roc-r.mjs';
 export { MAX_SQL_ROWS, assertReadonly, runReadonlySql } from './packem_shared/MAX_SQL_ROWS-iFAA8FbD.mjs';
 export { createSystemReader } from './packem_shared/createSystemReader-D12eNH13.mjs';

package/dist/packem_shared/{ROOT_DO_SIZE_WARN_BYTES-COEnnBhO.mjs → ROOT_DO_SIZE_WARN_BYTES-B_zt4RQE.mjs}

@@ -2,7 +2,7 @@ import { LunoraError, toErrorBody } from '@lunora/errors';
 import { drizzle } from 'drizzle-orm/durable-sqlite';
 import { c as constantTimeEqual } from './constant-time-equal-BVRWZgES.mjs';
 import { j as jsonResponse } from './json-response-BdbtpOhm.mjs';
-import { n as normalizeLogFields, r as resolveTraceAnchor, p as parseTraceparent, a as createTracer, c as createMetrics, d as dispatchRootSpan } from './context-telemetry-BVSDl6PU.mjs';
+import { n as normalizeLogFields, r as resolveTraceAnchor, p as parseTraceparent, a as createTracer, c as createMetrics, d as dispatchRootSpan } from './context-telemetry-CDpyil58.mjs';
 import { e as encodeWire, d as decodeWire } from './wire-codec-CzQc1pvf.mjs';
 import { parseExportShardArgs, parseImportShardArgs } from './exportShardRows-Dy3oFZ26.mjs';
 import { recordAuthEvent, readAuthMetrics } from './AUTH_METRICS_BUCKETS_TABLE-CiHHYeJi.mjs';
@@ -356,7 +356,11 @@ const runSql$3 = (sql, query, ...parameters) => {
   return runner.call(sql, query, ...parameters);
 };
 const bucketFloor = (ts) => Math.floor(ts / METRIC_HISTORY_BUCKET_MS) * METRIC_HISTORY_BUCKET_MS;
+const ensuredHandles = /* @__PURE__ */ new WeakSet();
 const ensureMetricHistoryTable = (sql) => {
+  if (ensuredHandles.has(sql)) {
+    return;
+  }
   runSql$3(
     sql,
     `CREATE TABLE IF NOT EXISTS "${METRIC_HISTORY_TABLE}" (
@@ -377,12 +381,25 @@ const ensureMetricHistoryTable = (sql) => {
             PRIMARY KEY (series_key, bucket_ms)
         )`
   );
+  ensuredHandles.add(sql);
+};
+const KNOWN_BUCKETS_CAP = 4096;
+const knownBuckets = /* @__PURE__ */ new WeakMap();
+const knownBucketsFor = (sql) => {
+  let set = knownBuckets.get(sql);
+  if (set === void 0) {
+    set = /* @__PURE__ */ new Set();
+    knownBuckets.set(sql, set);
+  }
+  return set;
 };
 const recordMetricHistory = (sql, event, exemplarTraceId) => {
   ensureMetricHistoryTable(sql);
   const key = metricSeriesKey(event);
   const bucket = bucketFloor(event.ts);
-  const bucketExists = runSql$3(sql, `SELECT 1 AS c FROM "${METRIC_HISTORY_TABLE}" WHERE series_key = ? AND bucket_ms = ? LIMIT 1`, key, bucket).toArray().length > 0;
+  const cache = knownBucketsFor(sql);
+  const cacheKey = `${key}\0${bucket.toString()}`;
+  const bucketExists = cache.has(cacheKey) || runSql$3(sql, `SELECT 1 AS c FROM "${METRIC_HISTORY_TABLE}" WHERE series_key = ? AND bucket_ms = ? LIMIT 1`, key, bucket).toArray().length > 0;
   if (!bucketExists) {
     const seriesTracked = runSql$3(sql, `SELECT 1 AS c FROM "${METRIC_HISTORY_TABLE}" WHERE series_key = ? LIMIT 1`, key).toArray().length > 0;
     if (!seriesTracked) {
@@ -434,6 +451,12 @@ const recordMetricHistory = (sql, event, exemplarTraceId) => {
       key
     );
   }
+  if (bucketExists && !cache.has(cacheKey)) {
+    if (cache.size >= KNOWN_BUCKETS_CAP) {
+      cache.clear();
+    }
+    cache.add(cacheKey);
+  }
 };
 const parseAttributes = (raw) => {
   if (raw === "" || raw === "{}") {
@@ -1968,6 +1991,21 @@ const findDanglingReferences = (sql, storageColumns, liveKeys) => {
 const WS_KEEPALIVE_PING = "lunora-ping";
 const WS_KEEPALIVE_PONG = "lunora-pong";
 const REQUIRE_EPHEMERAL_ENV_VALUES = /* @__PURE__ */ new Set(["1", "enabled", "on", "true", "yes"]);
+let cloudflareTracingResolved = false;
+let cloudflareTracing;
+const resolveCloudflareTracing = async () => {
+  if (!cloudflareTracingResolved) {
+    cloudflareTracingResolved = true;
+    try {
+      const cloudflareModule = await import('cloudflare:workers');
+      const candidate = cloudflareModule.tracing;
+      cloudflareTracing = candidate !== null && typeof candidate === "object" && typeof candidate.enterSpan === "function" ? candidate : void 0;
+    } catch {
+      cloudflareTracing = void 0;
+    }
+  }
+  return cloudflareTracing;
+};
 const UNDELIVERED_BASELINE = "<undelivered>";
 const ROOT_DO_SIZE_WARN_BYTES = 1073741824;
 const CDC_RESUME_SCAN_LIMIT = 1e4;
@@ -4786,14 +4824,19 @@ class ShardDO {
    * `anchor` is the trace this ctx's spans belong to; omit it for a ctx with no
    * owning dispatch (an alarm, a subscription re-run) to mint a fresh anchor, so
    * `ctx.trace` still yields a coherent self-contained trace there.
+   *
+   * The Cloudflare custom-spans bridge is threaded here but stays off unless the
+   * resolved sink sets `fuseCloudflareTraces` (see {@link resolveCloudflareTracing}).
    */
   makeTracer(functionPath, sink, anchor) {
     return createTracer({
       anchor: anchor ?? resolveTraceAnchor(void 0),
+      fuseCloudflareSpans: sink?.fuseCloudflareTraces === true,
       functionPath,
       record: (span) => {
         this.recordSpan(span, sink);
       },
+      resolveCloudflareTracing,
       shardKey: this.state.id?.name,
       userId: () => this.getCurrentUserId()
     });

package/dist/packem_shared/{context-telemetry-BVSDl6PU.mjs → context-telemetry-CDpyil58.mjs}

@@ -63,8 +63,31 @@ const toErrorType = (error) => {
   return error instanceof Error ? error.constructor.name : "Error";
 };
 
+const applyCloudflareSpanAttributes = (span, meta) => {
+  if (!span.isTraced) {
+    return;
+  }
+  span.setAttribute("lunora.function_path", meta.functionPath);
+  span.setAttribute("lunora.ok", meta.ok);
+  span.setAttribute("lunora.duration_ms", meta.durationMs);
+  if (meta.shardKey !== void 0) {
+    span.setAttribute("lunora.shard_key", meta.shardKey);
+  }
+  if (meta.userId !== void 0) {
+    span.setAttribute("lunora.user_id", meta.userId);
+  }
+  if (meta.error !== void 0) {
+    span.setAttribute("lunora.error.type", meta.error.type);
+    span.setAttribute("lunora.error.message", meta.error.message);
+  }
+  for (const [key, value] of Object.entries(meta.attributes)) {
+    if (typeof value === "boolean" || typeof value === "number" || typeof value === "string") {
+      span.setAttribute(`lunora.attr.${key}`, value);
+    }
+  }
+};
 const createTracer = (deps) => {
-  const { anchor, functionPath, record, shardKey, userId } = deps;
+  const { anchor, fuseCloudflareSpans, functionPath, record, resolveCloudflareTracing, shardKey, userId } = deps;
   const tracerFor = (parentSpanId) => async (name, function_, attributes) => {
     const spanId = otlpRandomHex(8);
     const startTs = Date.now();
@@ -78,39 +101,64 @@ const createTracer = (deps) => {
         Object.assign(collected, normalizeLogFields(fields));
       }
     };
-    let ok = true;
-    let error;
-    try {
-      return await function_(tracerFor(spanId), spanHandle);
-    } catch (error_) {
-      ok = false;
-      error = {
-        message: error_ instanceof Error ? error_.message : String(error_),
-        // Prefer a LunoraError's stable `code` over the class name so
-        // spans group by the same taxonomy the RPC spans use.
-        type: toErrorType(error_)
-      };
-      throw error_;
-    } finally {
+    const runRecorded = async (cfSpan) => {
+      let ok = true;
+      let error;
       try {
+        return await function_(tracerFor(spanId), spanHandle);
+      } catch (error_) {
+        ok = false;
+        error = {
+          message: error_ instanceof Error ? error_.message : String(error_),
+          // Prefer a LunoraError's stable `code` over the class name
+          // so spans group by the same taxonomy the RPC spans use.
+          type: toErrorType(error_)
+        };
+        throw error_;
+      } finally {
+        const durationMs = Date.now() - startTs;
+        const resolvedUserId = userId();
         const merged = { ...normalized, ...collected };
-        record({
-          ...Object.keys(merged).length === 0 ? {} : { attributes: merged },
-          durationMs: Date.now() - startTs,
-          ...error === void 0 ? {} : { error },
-          functionPath,
-          name,
-          ok,
-          parentSpanId,
-          shardKey,
-          spanId,
-          startTs,
-          traceId: anchor.traceId,
-          userId: userId()
-        });
-      } catch {
+        try {
+          record({
+            ...Object.keys(merged).length === 0 ? {} : { attributes: merged },
+            durationMs,
+            ...error === void 0 ? {} : { error },
+            functionPath,
+            name,
+            ok,
+            parentSpanId,
+            shardKey,
+            spanId,
+            startTs,
+            traceId: anchor.traceId,
+            userId: resolvedUserId
+          });
+        } catch {
+        }
+        if (cfSpan !== void 0) {
+          try {
+            applyCloudflareSpanAttributes(cfSpan, {
+              attributes: merged,
+              durationMs,
+              error,
+              functionPath,
+              ok,
+              shardKey,
+              userId: resolvedUserId
+            });
+          } catch {
+          }
+        }
+      }
+    };
+    if (fuseCloudflareSpans === true && resolveCloudflareTracing !== void 0) {
+      const cfTracing = await resolveCloudflareTracing();
+      if (cfTracing !== void 0 && typeof cfTracing.enterSpan === "function") {
+        return await cfTracing.enterSpan(name, (span) => runRecorded(span));
       }
     }
+    return await runRecorded();
   };
   return tracerFor(anchor.rootSpanId);
 };
@@ -172,4 +220,4 @@ const dispatchRootSpan = (input) => {
   };
 };
 
-export { createTracer as a, createMetrics as c, dispatchRootSpan as d, normalizeLogFields as n, parseTraceparent as p, resolveTraceAnchor as r };
+export { createTracer as a, applyCloudflareSpanAttributes as b, createMetrics as c, dispatchRootSpan as d, normalizeLogFields as n, parseTraceparent as p, resolveTraceAnchor as r };

package/dist/packem_shared/createMetrics-C4I2Yanj.mjs

@@ -0,0 +1 @@
+export { b as applyCloudflareSpanAttributes, c as createMetrics, a as createTracer, d as dispatchRootSpan } from './context-telemetry-CDpyil58.mjs';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lunora/do",
-  "version": "1.0.0-alpha.40",
+  "version": "1.0.0-alpha.42",
   "description": "Lunora Durable Objects: ShardDO (SQLite, OCC, hibernated WebSocket subscriptions) and SessionDO",
   "keywords": [
     "cloudflare",

package/dist/packem_shared/createMetrics-DFADosgV.mjs

@@ -1 +0,0 @@
-export { c as createMetrics, a as createTracer, d as dispatchRootSpan } from './context-telemetry-BVSDl6PU.mjs';