@lunora/runtime 1.0.0-alpha.29 → 1.0.0-alpha.30

package/dist/index.d.mts

@@ -661,6 +661,123 @@ interface LogEvent {
   /** Acting userId, or absent when anonymous. */
   userId?: string;
 }
+/**
+ * What kind of instrument produced a measurement, which decides how a collector
+ * aggregates it:
+ *
+ * - `counter` — a monotonic delta to add up (requests, retries, bytes sent).
+ * - `gauge` — a point-in-time reading that replaces the last one (queue depth,
+ *   cache size).
+ * - `histogram` — a value whose *distribution* matters (latency, payload size),
+ *   giving percentiles rather than just a mean.
+ */
+type MetricKind = "counter" | "gauge" | "histogram";
+/**
+ * One measurement recorded from a function handler.
+ *
+ * Each `ctx.metrics.*` call produces exactly one of these — the runtime does no
+ * pre-aggregation, so counters carry **delta** temporality and a collector sums
+ * them. That keeps the sink model identical to logs and spans (one event, one
+ * export) at the cost of chattiness in a hot loop, where the handler should sum
+ * locally and record once.
+ */
+interface MetricEvent {
+  /**
+   * Structured attributes the caller attached, normalized to a fresh bag of
+   * JSON-safe primitives (see `shared/log-fields.ts`). These are the metric's
+   * dimensions — keep them low-cardinality; an id-valued attribute creates a
+   * distinct time series per id.
+   *
+   * Caller-controlled, so they MAY contain user input and they DO egress to
+   * whatever destination the sink ships to — the same caveat as a log line's
+   * `fields` and a span's `error.message`. Scrub upstream if that matters.
+   */
+  attributes?: LogFields;
+  /** Function path that recorded the measurement, e.g. `"orders:checkout"`. */
+  functionPath: string;
+  /** Instrument kind; see {@link MetricKind}. */
+  kind: MetricKind;
+  /** Instrument name, e.g. `"orders.placed"`. */
+  name: string;
+  /** Shard key for single-shard calls; absent for the unnamed root DO. */
+  shardKey?: string;
+  /** Wall-clock millis when the measurement was recorded. */
+  ts: number;
+  /**
+   * The measured value: the increment for a `counter`, the current reading for
+   * a `gauge`, the observed sample for a `histogram`.
+   */
+  value: number;
+}
+/**
+ * One span produced by a `ctx.trace(name, fn)` call, or the synthetic root span
+ * the shard records for the dispatch itself so a waterfall has a bar to hang
+ * its children under.
+ *
+ * Ids are the same lowercase-hex form the OTLP encoders and `traceparent` use
+ * (32-hex trace, 16-hex span), so a `SpanEvent` composes into an OTLP span with
+ * no reformatting.
+ */
+interface SpanEvent {
+  /**
+   * Structured attributes the caller attached, already normalized to a fresh
+   * bag of JSON-safe primitives (see `shared/log-fields.ts`) exactly like a log
+   * line's `fields`. Absent when the caller passed none.
+   */
+  attributes?: LogFields;
+  /** Wall-clock duration of the span body, in milliseconds. */
+  durationMs: number;
+  /**
+   * Populated when the span body threw. `type` is the error's constructor name
+   * (or its `LunoraError` code); `message` is the human-readable string and may
+   * include user input, so sinks shipping to third parties should scrub it.
+   */
+  error?: {
+    message: string;
+    type: string;
+  };
+  /**
+   * Function path the span was created under, e.g. `"messages:list"`. A span
+   * created inside a function invoked via `ctx.runQuery`/`runMutation`/
+   * `runAction` carries the OUTER entrypoint's path, since the composed call
+   * reuses its context — the same attribution rule `ctx.log` follows.
+   */
+  functionPath: string;
+  /** Caller-supplied span name, e.g. `"stripe.charge"`. */
+  name: string;
+  /** True when the span body returned without throwing. */
+  ok: boolean;
+  /**
+   * Span id of the enclosing span — the parent `ctx.trace` when nested, else
+   * the dispatch's own RPC span (from the inbound `traceparent`). A span with
+   * no inbound trace context is parented to a locally-minted root, so this is
+   * always set for a `ctx.trace` span; only the synthetic `dispatch` span below
+   * carries `""`, meaning "nothing above me in this trace".
+   */
+  parentSpanId: string;
+  /**
+   * True for the synthetic span representing the **dispatch itself**, which the
+   * shard records so a waterfall has a bar for the request to hang its
+   * `ctx.trace` spans under.
+   *
+   * Named for what it is rather than "root": it is not the root of the
+   * collector-side trace — the worker's own RPC span sits above it — and it is
+   * never exported to a sink, because the runtime already emits that dispatch
+   * via `onRpc` and a collector would otherwise show it twice. Locally it *is*
+   * the outermost span, which is why the fold prefers it as a trace's anchor.
+   */
+  dispatch?: boolean;
+  /** Shard key for single-shard calls; absent for the unnamed root DO. */
+  shardKey?: string;
+  /** This span's own id (16-hex). */
+  spanId: string;
+  /** Wall-clock millis when the span started. */
+  startTs: number;
+  /** Trace this span belongs to (32-hex) — shared with the dispatch's logs. */
+  traceId: string;
+  /** Acting userId, or absent when anonymous. */
+  userId?: string;
+}
 /**
  * Per-RPC dispatch event. Single-shard calls set `shardKey`; cross-shard
  * fan-outs set `fanOut` with the table being aggregated, shard count, and
@@ -726,8 +843,19 @@ type ObservabilitySinkContext = LogSinkContext;
 interface ObservabilitySink {
   /** Invoked once per `ctx.log.*` call from a function handler. */
   onLog?: (event: LogEvent, context?: ObservabilitySinkContext) => void;
+  /**
+   * Invoked once per `ctx.metrics.*` measurement. No pre-aggregation happens
+   * upstream, so counter values are deltas for the destination to sum.
+   */
+  onMetric?: (event: MetricEvent, context?: ObservabilitySinkContext) => void;
   /** Invoked once per dispatched RPC (single-shard or fan-out). */
   onRpc?: (event: ObservabilityEvent, context?: ObservabilitySinkContext) => void;
+  /**
+   * Invoked once per `ctx.trace(name, fn)` span, when the span body settles.
+   * Distinct from `onRpc`: that is the one SERVER span per dispatch, this is the
+   * INTERNAL spans a handler creates beneath it.
+   */
+  onSpan?: (event: SpanEvent, context?: ObservabilitySinkContext) => void;
 }
 /**
  * Invoke `sink.onRpc` with the given event, swallowing any error the sink
@@ -2678,7 +2806,7 @@ interface WebhookSinkOptions extends OnlyErrorsOption {
    */
   transform?: (event: ObservabilityEvent) => null | ObservabilityEvent | undefined;
   /**
-   * Optional redaction hook for `ctx.log` events (the {@link transform}
+   * Optional redaction hook for `ctx.log` events (the `transform`
    * counterpart for log lines). Same fail-closed contract: return the event to
    * ship it, `null`/`undefined` to drop it, and a throw drops it. When unset,
    * log events are shipped as-is (message + structured fields — which may carry
@@ -2855,9 +2983,11 @@ interface OtlpSinkOptions extends OnlyErrorsOption {
  * side lands in the same collector. Each RPC dispatch becomes one OTLP **span**
  * (`${endpoint}/v1/traces`) named after its `functionPath`, with start/end
  * derived from `durationMs` and status OK/ERROR; each `ctx.log.*` line becomes
- * one OTLP **log record** (`${endpoint}/v1/logs`). Trace/span ids are random
- * per span — real trace correlation (worker→container `traceparent`) is a later
- * phase.
+ * one OTLP **log record** (`${endpoint}/v1/logs`). Spans and log records reuse
+ * the dispatch's `traceId`/`spanId` (minted at dispatch entry and propagated to
+ * the shard and any container as a `traceparent`), so a handler's logs, its RPC
+ * span, and the container spans beneath it all stitch into one trace; ids are
+ * only randomised on paths that carry no trace context.
  *
  * Like {@link webhookSink}, each export is its own `fetch`, registered with the
  * request's `context.waitUntil` when present so it survives isolate teardown,
@@ -2881,4 +3011,4 @@ declare const otlpSink: (options: OtlpSinkOptions) => ObservabilitySink;
  */
 declare const combineSinks: (...sinks: ObservabilitySink[]) => ObservabilitySink;
 declare const VERSION: string;
-export { type AdminTableResolver, type AirbyteMessage, type AnalyticsEngineDataPointLike, type AnalyticsEngineDatasetLike, type AnalyticsEngineSinkOptions, type AuthAdmin, type AuthCapabilities, type AuthConfigInfo, type AuthImpersonation, type AuthPage, type AuthSession, type AuthUser, type AuthUserFieldSpec, type BackupManifest, type BackupStore, type ComposeIdentityResolversErrorMode, type ComposeIdentityResolversOptions, type ConnectorChange, type ConnectorSyncPage, type CorsOptions, type CronHandler, type CronJobDispatch, type CronJobInfo, type CrossShardCounter, type CrossShardReader, type CrossShardRelationCapabilities, type CrossShardRelationOptions, type CsrfOptions, DEFAULT_REGISTRY_CACHE_TTL_MS, type DurableObjectJurisdiction, type DynamicShardRegistry, type DynamicShardRegistryOptions, type ExecutionContextLike, type ExportFanOutRequest, type ExportFanOutResult, type FanOutRequest, type FanOutResult, type FanOutSpec, type FivetranResponse, type FrameworkHostHandler, type FrameworkWorkerOptions, type FrameworkWorkerOptionsInput, type FunctionDescriptor, type FunctionRegistryEntry, type FunctionRegistryLike, type GlobalExportFunction as GlobalExportFn, type GlobalImportFunction as GlobalImportFn, type GlobalIntrospector, type GlobalTableInfo as GlobalTableInfoMeta, type GlobalTablePage as GlobalTablePageMeta, type HttpActionContext, type HttpActionLike, type HttpRouterLike, type IdentityContractLike, type IdentityResolver, type IdentityValidation, type ImportFanOutRequest, type ImportFanOutResult, type KvIntrospector, type KvKeyEntry, type KvKeyListResult, type KvNamespaceSummary, type KvValueResult, type ListAuthUsersOptions, type LogEvent, type LogFields, type LogLevel, LunoraError, type LunoraErrorBody, type LunoraHandlerOptions, type LunoraWorker, type MergeStrategy, type MigrationFanOutRequest, type MigrationFanOutResult, NOOP_EXECUTION_CONTEXT, type ObservabilityEvent, type ObservabilitySink, type ObservabilitySinkContext, type OtlpSinkOptions, type PipelineLike, type PipelineLogSinkOptions, type QueryCoordinator, type QueryCoordinatorOptions, type RankFanOutRequest, type RankFanOutResult, type RankPageFanOutRequest, type RankPageFanOutResult, type ResolvedSecurity, type ResolvedShard, type Route, type RpcContext, type RpcEnvelope, SHARD_REGISTRY_DO_NAME, type ScheduledControllerLike, type SecurityHeadersOptions, type SecurityOptions, type SentrySinkOptions, type ShardError, type ShardExportOutcome, type ShardImportOutcome, type ShardMigrationOutcome, type ShardNamespaceLike, type ShardRankOutcome, type ShardRankPageOutcome, type ShardRegistry, type ShardTrafficEntry, type ShardTrafficFanOutRequest, type ShardTrafficFanOutResult, type ShardingInfo, type StorageListFunction as StorageListFn, type StorageObject, VERSION, type VectorIndexSummary, type VectorIntrospector, type VectorQueryMatch, type WebhookSinkOptions, type WorkerOptions, analyticsEngineSink, applyJurisdiction, combineSinks, composeIdentityResolvers, composeWorker, consoleSink, createCrossShardRelationCapabilities, createDynamicShardRegistry, createLunoraHandler, createQueryCoordinator, createStaticShardRegistry, createWorker, decorateResponse, defineRpcEnvelope, emitLogEvent, emitRpcEvent, enforceOrigin, handleCorsPreflight, mergeStrategyForAggregate, otlpSink, pipelineLogSink, resolveLunoraOptions, resolveSecurity, resolveShard, routeIdentityResolvers, sentrySink, toAirbyteMessages, toErrorResponse, toFivetranResponse, webhookSink, withFrameworkWorker };
+export { type AdminTableResolver, type AirbyteMessage, type AnalyticsEngineDataPointLike, type AnalyticsEngineDatasetLike, type AnalyticsEngineSinkOptions, type AuthAdmin, type AuthCapabilities, type AuthConfigInfo, type AuthImpersonation, type AuthPage, type AuthSession, type AuthUser, type AuthUserFieldSpec, type BackupManifest, type BackupStore, type ComposeIdentityResolversErrorMode, type ComposeIdentityResolversOptions, type ConnectorChange, type ConnectorSyncPage, type CorsOptions, type CronHandler, type CronJobDispatch, type CronJobInfo, type CrossShardCounter, type CrossShardReader, type CrossShardRelationCapabilities, type CrossShardRelationOptions, type CsrfOptions, DEFAULT_REGISTRY_CACHE_TTL_MS, type DurableObjectJurisdiction, type DynamicShardRegistry, type DynamicShardRegistryOptions, type ExecutionContextLike, type ExportFanOutRequest, type ExportFanOutResult, type FanOutRequest, type FanOutResult, type FanOutSpec, type FivetranResponse, type FrameworkHostHandler, type FrameworkWorkerOptions, type FrameworkWorkerOptionsInput, type FunctionDescriptor, type FunctionRegistryEntry, type FunctionRegistryLike, type GlobalExportFunction as GlobalExportFn, type GlobalImportFunction as GlobalImportFn, type GlobalIntrospector, type GlobalTableInfo as GlobalTableInfoMeta, type GlobalTablePage as GlobalTablePageMeta, type HttpActionContext, type HttpActionLike, type HttpRouterLike, type IdentityContractLike, type IdentityResolver, type IdentityValidation, type ImportFanOutRequest, type ImportFanOutResult, type KvIntrospector, type KvKeyEntry, type KvKeyListResult, type KvNamespaceSummary, type KvValueResult, type ListAuthUsersOptions, type LogEvent, type LogFields, type LogLevel, LunoraError, type LunoraErrorBody, type LunoraHandlerOptions, type LunoraWorker, type MergeStrategy, type MetricEvent, type MetricKind, type MigrationFanOutRequest, type MigrationFanOutResult, NOOP_EXECUTION_CONTEXT, type ObservabilityEvent, type ObservabilitySink, type ObservabilitySinkContext, type OtlpSinkOptions, type PipelineLike, type PipelineLogSinkOptions, type QueryCoordinator, type QueryCoordinatorOptions, type RankFanOutRequest, type RankFanOutResult, type RankPageFanOutRequest, type RankPageFanOutResult, type ResolvedSecurity, type ResolvedShard, type Route, type RpcContext, type RpcEnvelope, SHARD_REGISTRY_DO_NAME, type ScheduledControllerLike, type SecurityHeadersOptions, type SecurityOptions, type SentrySinkOptions, type ShardError, type ShardExportOutcome, type ShardImportOutcome, type ShardMigrationOutcome, type ShardNamespaceLike, type ShardRankOutcome, type ShardRankPageOutcome, type ShardRegistry, type ShardTrafficEntry, type ShardTrafficFanOutRequest, type ShardTrafficFanOutResult, type ShardingInfo, type SpanEvent, type StorageListFunction as StorageListFn, type StorageObject, VERSION, type VectorIndexSummary, type VectorIntrospector, type VectorQueryMatch, type WebhookSinkOptions, type WorkerOptions, analyticsEngineSink, applyJurisdiction, combineSinks, composeIdentityResolvers, composeWorker, consoleSink, createCrossShardRelationCapabilities, createDynamicShardRegistry, createLunoraHandler, createQueryCoordinator, createStaticShardRegistry, createWorker, decorateResponse, defineRpcEnvelope, emitLogEvent, emitRpcEvent, enforceOrigin, handleCorsPreflight, mergeStrategyForAggregate, otlpSink, pipelineLogSink, resolveLunoraOptions, resolveSecurity, resolveShard, routeIdentityResolvers, sentrySink, toAirbyteMessages, toErrorResponse, toFivetranResponse, webhookSink, withFrameworkWorker };

package/dist/index.d.ts

@@ -661,6 +661,123 @@ interface LogEvent {
   /** Acting userId, or absent when anonymous. */
   userId?: string;
 }
+/**
+ * What kind of instrument produced a measurement, which decides how a collector
+ * aggregates it:
+ *
+ * - `counter` — a monotonic delta to add up (requests, retries, bytes sent).
+ * - `gauge` — a point-in-time reading that replaces the last one (queue depth,
+ *   cache size).
+ * - `histogram` — a value whose *distribution* matters (latency, payload size),
+ *   giving percentiles rather than just a mean.
+ */
+type MetricKind = "counter" | "gauge" | "histogram";
+/**
+ * One measurement recorded from a function handler.
+ *
+ * Each `ctx.metrics.*` call produces exactly one of these — the runtime does no
+ * pre-aggregation, so counters carry **delta** temporality and a collector sums
+ * them. That keeps the sink model identical to logs and spans (one event, one
+ * export) at the cost of chattiness in a hot loop, where the handler should sum
+ * locally and record once.
+ */
+interface MetricEvent {
+  /**
+   * Structured attributes the caller attached, normalized to a fresh bag of
+   * JSON-safe primitives (see `shared/log-fields.ts`). These are the metric's
+   * dimensions — keep them low-cardinality; an id-valued attribute creates a
+   * distinct time series per id.
+   *
+   * Caller-controlled, so they MAY contain user input and they DO egress to
+   * whatever destination the sink ships to — the same caveat as a log line's
+   * `fields` and a span's `error.message`. Scrub upstream if that matters.
+   */
+  attributes?: LogFields;
+  /** Function path that recorded the measurement, e.g. `"orders:checkout"`. */
+  functionPath: string;
+  /** Instrument kind; see {@link MetricKind}. */
+  kind: MetricKind;
+  /** Instrument name, e.g. `"orders.placed"`. */
+  name: string;
+  /** Shard key for single-shard calls; absent for the unnamed root DO. */
+  shardKey?: string;
+  /** Wall-clock millis when the measurement was recorded. */
+  ts: number;
+  /**
+   * The measured value: the increment for a `counter`, the current reading for
+   * a `gauge`, the observed sample for a `histogram`.
+   */
+  value: number;
+}
+/**
+ * One span produced by a `ctx.trace(name, fn)` call, or the synthetic root span
+ * the shard records for the dispatch itself so a waterfall has a bar to hang
+ * its children under.
+ *
+ * Ids are the same lowercase-hex form the OTLP encoders and `traceparent` use
+ * (32-hex trace, 16-hex span), so a `SpanEvent` composes into an OTLP span with
+ * no reformatting.
+ */
+interface SpanEvent {
+  /**
+   * Structured attributes the caller attached, already normalized to a fresh
+   * bag of JSON-safe primitives (see `shared/log-fields.ts`) exactly like a log
+   * line's `fields`. Absent when the caller passed none.
+   */
+  attributes?: LogFields;
+  /** Wall-clock duration of the span body, in milliseconds. */
+  durationMs: number;
+  /**
+   * Populated when the span body threw. `type` is the error's constructor name
+   * (or its `LunoraError` code); `message` is the human-readable string and may
+   * include user input, so sinks shipping to third parties should scrub it.
+   */
+  error?: {
+    message: string;
+    type: string;
+  };
+  /**
+   * Function path the span was created under, e.g. `"messages:list"`. A span
+   * created inside a function invoked via `ctx.runQuery`/`runMutation`/
+   * `runAction` carries the OUTER entrypoint's path, since the composed call
+   * reuses its context — the same attribution rule `ctx.log` follows.
+   */
+  functionPath: string;
+  /** Caller-supplied span name, e.g. `"stripe.charge"`. */
+  name: string;
+  /** True when the span body returned without throwing. */
+  ok: boolean;
+  /**
+   * Span id of the enclosing span — the parent `ctx.trace` when nested, else
+   * the dispatch's own RPC span (from the inbound `traceparent`). A span with
+   * no inbound trace context is parented to a locally-minted root, so this is
+   * always set for a `ctx.trace` span; only the synthetic `dispatch` span below
+   * carries `""`, meaning "nothing above me in this trace".
+   */
+  parentSpanId: string;
+  /**
+   * True for the synthetic span representing the **dispatch itself**, which the
+   * shard records so a waterfall has a bar for the request to hang its
+   * `ctx.trace` spans under.
+   *
+   * Named for what it is rather than "root": it is not the root of the
+   * collector-side trace — the worker's own RPC span sits above it — and it is
+   * never exported to a sink, because the runtime already emits that dispatch
+   * via `onRpc` and a collector would otherwise show it twice. Locally it *is*
+   * the outermost span, which is why the fold prefers it as a trace's anchor.
+   */
+  dispatch?: boolean;
+  /** Shard key for single-shard calls; absent for the unnamed root DO. */
+  shardKey?: string;
+  /** This span's own id (16-hex). */
+  spanId: string;
+  /** Wall-clock millis when the span started. */
+  startTs: number;
+  /** Trace this span belongs to (32-hex) — shared with the dispatch's logs. */
+  traceId: string;
+  /** Acting userId, or absent when anonymous. */
+  userId?: string;
+}
 /**
  * Per-RPC dispatch event. Single-shard calls set `shardKey`; cross-shard
  * fan-outs set `fanOut` with the table being aggregated, shard count, and
@@ -726,8 +843,19 @@ type ObservabilitySinkContext = LogSinkContext;
 interface ObservabilitySink {
   /** Invoked once per `ctx.log.*` call from a function handler. */
   onLog?: (event: LogEvent, context?: ObservabilitySinkContext) => void;
+  /**
+   * Invoked once per `ctx.metrics.*` measurement. No pre-aggregation happens
+   * upstream, so counter values are deltas for the destination to sum.
+   */
+  onMetric?: (event: MetricEvent, context?: ObservabilitySinkContext) => void;
   /** Invoked once per dispatched RPC (single-shard or fan-out). */
   onRpc?: (event: ObservabilityEvent, context?: ObservabilitySinkContext) => void;
+  /**
+   * Invoked once per `ctx.trace(name, fn)` span, when the span body settles.
+   * Distinct from `onRpc`: that is the one SERVER span per dispatch, this is the
+   * INTERNAL spans a handler creates beneath it.
+   */
+  onSpan?: (event: SpanEvent, context?: ObservabilitySinkContext) => void;
 }
 /**
  * Invoke `sink.onRpc` with the given event, swallowing any error the sink
@@ -2678,7 +2806,7 @@ interface WebhookSinkOptions extends OnlyErrorsOption {
    */
   transform?: (event: ObservabilityEvent) => null | ObservabilityEvent | undefined;
   /**
-   * Optional redaction hook for `ctx.log` events (the {@link transform}
+   * Optional redaction hook for `ctx.log` events (the `transform`
    * counterpart for log lines). Same fail-closed contract: return the event to
    * ship it, `null`/`undefined` to drop it, and a throw drops it. When unset,
    * log events are shipped as-is (message + structured fields — which may carry
@@ -2855,9 +2983,11 @@ interface OtlpSinkOptions extends OnlyErrorsOption {
  * side lands in the same collector. Each RPC dispatch becomes one OTLP **span**
  * (`${endpoint}/v1/traces`) named after its `functionPath`, with start/end
  * derived from `durationMs` and status OK/ERROR; each `ctx.log.*` line becomes
- * one OTLP **log record** (`${endpoint}/v1/logs`). Trace/span ids are random
- * per span — real trace correlation (worker→container `traceparent`) is a later
- * phase.
+ * one OTLP **log record** (`${endpoint}/v1/logs`). Spans and log records reuse
+ * the dispatch's `traceId`/`spanId` (minted at dispatch entry and propagated to
+ * the shard and any container as a `traceparent`), so a handler's logs, its RPC
+ * span, and the container spans beneath it all stitch into one trace; ids are
+ * only randomised on paths that carry no trace context.
  *
  * Like {@link webhookSink}, each export is its own `fetch`, registered with the
  * request's `context.waitUntil` when present so it survives isolate teardown,
@@ -2881,4 +3011,4 @@ declare const otlpSink: (options: OtlpSinkOptions) => ObservabilitySink;
  */
 declare const combineSinks: (...sinks: ObservabilitySink[]) => ObservabilitySink;
 declare const VERSION: string;
-export { type AdminTableResolver, type AirbyteMessage, type AnalyticsEngineDataPointLike, type AnalyticsEngineDatasetLike, type AnalyticsEngineSinkOptions, type AuthAdmin, type AuthCapabilities, type AuthConfigInfo, type AuthImpersonation, type AuthPage, type AuthSession, type AuthUser, type AuthUserFieldSpec, type BackupManifest, type BackupStore, type ComposeIdentityResolversErrorMode, type ComposeIdentityResolversOptions, type ConnectorChange, type ConnectorSyncPage, type CorsOptions, type CronHandler, type CronJobDispatch, type CronJobInfo, type CrossShardCounter, type CrossShardReader, type CrossShardRelationCapabilities, type CrossShardRelationOptions, type CsrfOptions, DEFAULT_REGISTRY_CACHE_TTL_MS, type DurableObjectJurisdiction, type DynamicShardRegistry, type DynamicShardRegistryOptions, type ExecutionContextLike, type ExportFanOutRequest, type ExportFanOutResult, type FanOutRequest, type FanOutResult, type FanOutSpec, type FivetranResponse, type FrameworkHostHandler, type FrameworkWorkerOptions, type FrameworkWorkerOptionsInput, type FunctionDescriptor, type FunctionRegistryEntry, type FunctionRegistryLike, type GlobalExportFunction as GlobalExportFn, type GlobalImportFunction as GlobalImportFn, type GlobalIntrospector, type GlobalTableInfo as GlobalTableInfoMeta, type GlobalTablePage as GlobalTablePageMeta, type HttpActionContext, type HttpActionLike, type HttpRouterLike, type IdentityContractLike, type IdentityResolver, type IdentityValidation, type ImportFanOutRequest, type ImportFanOutResult, type KvIntrospector, type KvKeyEntry, type KvKeyListResult, type KvNamespaceSummary, type KvValueResult, type ListAuthUsersOptions, type LogEvent, type LogFields, type LogLevel, LunoraError, type LunoraErrorBody, type LunoraHandlerOptions, type LunoraWorker, type MergeStrategy, type MigrationFanOutRequest, type MigrationFanOutResult, NOOP_EXECUTION_CONTEXT, type ObservabilityEvent, type ObservabilitySink, type ObservabilitySinkContext, type OtlpSinkOptions, type PipelineLike, type PipelineLogSinkOptions, type QueryCoordinator, type QueryCoordinatorOptions, type RankFanOutRequest, type RankFanOutResult, type RankPageFanOutRequest, type RankPageFanOutResult, type ResolvedSecurity, type ResolvedShard, type Route, type RpcContext, type RpcEnvelope, SHARD_REGISTRY_DO_NAME, type ScheduledControllerLike, type SecurityHeadersOptions, type SecurityOptions, type SentrySinkOptions, type ShardError, type ShardExportOutcome, type ShardImportOutcome, type ShardMigrationOutcome, type ShardNamespaceLike, type ShardRankOutcome, type ShardRankPageOutcome, type ShardRegistry, type ShardTrafficEntry, type ShardTrafficFanOutRequest, type ShardTrafficFanOutResult, type ShardingInfo, type StorageListFunction as StorageListFn, type StorageObject, VERSION, type VectorIndexSummary, type VectorIntrospector, type VectorQueryMatch, type WebhookSinkOptions, type WorkerOptions, analyticsEngineSink, applyJurisdiction, combineSinks, composeIdentityResolvers, composeWorker, consoleSink, createCrossShardRelationCapabilities, createDynamicShardRegistry, createLunoraHandler, createQueryCoordinator, createStaticShardRegistry, createWorker, decorateResponse, defineRpcEnvelope, emitLogEvent, emitRpcEvent, enforceOrigin, handleCorsPreflight, mergeStrategyForAggregate, otlpSink, pipelineLogSink, resolveLunoraOptions, resolveSecurity, resolveShard, routeIdentityResolvers, sentrySink, toAirbyteMessages, toErrorResponse, toFivetranResponse, webhookSink, withFrameworkWorker };
+export { type AdminTableResolver, type AirbyteMessage, type AnalyticsEngineDataPointLike, type AnalyticsEngineDatasetLike, type AnalyticsEngineSinkOptions, type AuthAdmin, type AuthCapabilities, type AuthConfigInfo, type AuthImpersonation, type AuthPage, type AuthSession, type AuthUser, type AuthUserFieldSpec, type BackupManifest, type BackupStore, type ComposeIdentityResolversErrorMode, type ComposeIdentityResolversOptions, type ConnectorChange, type ConnectorSyncPage, type CorsOptions, type CronHandler, type CronJobDispatch, type CronJobInfo, type CrossShardCounter, type CrossShardReader, type CrossShardRelationCapabilities, type CrossShardRelationOptions, type CsrfOptions, DEFAULT_REGISTRY_CACHE_TTL_MS, type DurableObjectJurisdiction, type DynamicShardRegistry, type DynamicShardRegistryOptions, type ExecutionContextLike, type ExportFanOutRequest, type ExportFanOutResult, type FanOutRequest, type FanOutResult, type FanOutSpec, type FivetranResponse, type FrameworkHostHandler, type FrameworkWorkerOptions, type FrameworkWorkerOptionsInput, type FunctionDescriptor, type FunctionRegistryEntry, type FunctionRegistryLike, type GlobalExportFunction as GlobalExportFn, type GlobalImportFunction as GlobalImportFn, type GlobalIntrospector, type GlobalTableInfo as GlobalTableInfoMeta, type GlobalTablePage as GlobalTablePageMeta, type HttpActionContext, type HttpActionLike, type HttpRouterLike, type IdentityContractLike, type IdentityResolver, type IdentityValidation, type ImportFanOutRequest, type ImportFanOutResult, type KvIntrospector, type KvKeyEntry, type KvKeyListResult, type KvNamespaceSummary, type KvValueResult, type ListAuthUsersOptions, type LogEvent, type LogFields, type LogLevel, LunoraError, type LunoraErrorBody, type LunoraHandlerOptions, type LunoraWorker, type MergeStrategy, type MetricEvent, type MetricKind, type MigrationFanOutRequest, type MigrationFanOutResult, NOOP_EXECUTION_CONTEXT, type ObservabilityEvent, type ObservabilitySink, type ObservabilitySinkContext, type OtlpSinkOptions, type PipelineLike, type PipelineLogSinkOptions, type QueryCoordinator, type QueryCoordinatorOptions, type RankFanOutRequest, type RankFanOutResult, type RankPageFanOutRequest, type RankPageFanOutResult, type ResolvedSecurity, type ResolvedShard, type Route, type RpcContext, type RpcEnvelope, SHARD_REGISTRY_DO_NAME, type ScheduledControllerLike, type SecurityHeadersOptions, type SecurityOptions, type SentrySinkOptions, type ShardError, type ShardExportOutcome, type ShardImportOutcome, type ShardMigrationOutcome, type ShardNamespaceLike, type ShardRankOutcome, type ShardRankPageOutcome, type ShardRegistry, type ShardTrafficEntry, type ShardTrafficFanOutRequest, type ShardTrafficFanOutResult, type ShardingInfo, type SpanEvent, type StorageListFunction as StorageListFn, type StorageObject, VERSION, type VectorIndexSummary, type VectorIntrospector, type VectorQueryMatch, type WebhookSinkOptions, type WorkerOptions, analyticsEngineSink, applyJurisdiction, combineSinks, composeIdentityResolvers, composeWorker, consoleSink, createCrossShardRelationCapabilities, createDynamicShardRegistry, createLunoraHandler, createQueryCoordinator, createStaticShardRegistry, createWorker, decorateResponse, defineRpcEnvelope, emitLogEvent, emitRpcEvent, enforceOrigin, handleCorsPreflight, mergeStrategyForAggregate, otlpSink, pipelineLogSink, resolveLunoraOptions, resolveSecurity, resolveShard, routeIdentityResolvers, sentrySink, toAirbyteMessages, toErrorResponse, toFivetranResponse, webhookSink, withFrameworkWorker };

package/dist/index.mjs

@@ -1,10 +1,10 @@
 export { toAirbyteMessages, toFivetranResponse } from './packem_shared/toAirbyteMessages-DrHdplb4.mjs';
-export { composeWorker, createLunoraHandler, createWorker, defineRpcEnvelope, resolveLunoraOptions, withFrameworkWorker } from './packem_shared/composeWorker-Br4_GgSW.mjs';
+export { composeWorker, createLunoraHandler, createWorker, defineRpcEnvelope, resolveLunoraOptions, withFrameworkWorker } from './packem_shared/composeWorker-CqUlK17X.mjs';
 export { createCrossShardRelationCapabilities } from './packem_shared/createCrossShardRelationCapabilities-CbcWjkAn.mjs';
 export { DEFAULT_REGISTRY_CACHE_TTL_MS, SHARD_REGISTRY_DO_NAME, createDynamicShardRegistry } from './packem_shared/DEFAULT_REGISTRY_CACHE_TTL_MS-B3pA7aXp.mjs';
 export { LunoraError, toErrorResponse } from './packem_shared/LunoraError-Bpb9EFJ3.mjs';
 export { emitLogEvent, emitRpcEvent } from './packem_shared/emitLogEvent-pEdtqAK8.mjs';
-export { analyticsEngineSink, combineSinks, consoleSink, otlpSink, pipelineLogSink, sentrySink, webhookSink } from './packem_shared/analyticsEngineSink-DKZvbDFG.mjs';
+export { analyticsEngineSink, combineSinks, consoleSink, otlpSink, pipelineLogSink, sentrySink, webhookSink } from './packem_shared/analyticsEngineSink-DWUhiYHC.mjs';
 export { createQueryCoordinator, createStaticShardRegistry, mergeStrategyForAggregate } from './packem_shared/createQueryCoordinator-DNCJzOZE.mjs';
 export { applyJurisdiction, resolveShard } from './packem_shared/applyJurisdiction-BkZtTkct.mjs';
 export { decorateResponse, enforceOrigin, handleCorsPreflight, resolveSecurity } from './packem_shared/decorateResponse-DRWQFNhF.mjs';

package/dist/packem_shared/{analyticsEngineSink-DKZvbDFG.mjs → analyticsEngineSink-DWUhiYHC.mjs}

@@ -1,4 +1,4 @@
-import { m as mergeHeaders, o as otlpRandomHex, w as wrapResourceSpans, e as encodeAttribute, a as wrapResourceLogs, O as OTLP_SEVERITY, c as otlpUnixNano } from './otlp-0FQT3AI8.mjs';
+import { m as mergeHeaders, w as wrapResourceSpans, o as otlpRandomHex, a as wrapResourceMetrics, c as wrapResourceLogs, e as encodeAttribute, O as OTLP_SEVERITY, d as otlpUnixNano } from './otlp-DOLuy1Aj.mjs';
 
 const stringifyFieldValue = (value) => {
   if (typeof value === "string") {
@@ -44,22 +44,88 @@ const otlpTraceBody = (event, serviceName, endMs) => {
   };
   return wrapResourceSpans(span, "@lunora/runtime", serviceName);
 };
-const otlpLogBody = (event, serviceName) => {
-  const attributeByKey = /* @__PURE__ */ new Map();
-  attributeByKey.set("lunora.function_path", encodeAttribute("lunora.function_path", event.functionPath));
-  if (event.shardKey !== void 0) {
-    attributeByKey.set("lunora.shard_key", encodeAttribute("lunora.shard_key", event.shardKey));
+const encodeSignalAttributes = (reserved, caller) => {
+  const byKey = /* @__PURE__ */ new Map([["lunora.function_path", encodeAttribute("lunora.function_path", reserved.functionPath)]]);
+  if (reserved.shardKey !== void 0) {
+    byKey.set("lunora.shard_key", encodeAttribute("lunora.shard_key", reserved.shardKey));
   }
-  if (event.userId !== void 0) {
-    attributeByKey.set("lunora.user_id", encodeAttribute("lunora.user_id", event.userId));
+  if (reserved.userId !== void 0) {
+    byKey.set("lunora.user_id", encodeAttribute("lunora.user_id", reserved.userId));
   }
-  if (event.fields) {
-    for (const [key, value] of Object.entries(event.fields)) {
-      attributeByKey.set(key, encodeAttribute(key, coerceFieldValue(value)));
-    }
+  if (reserved.errorType !== void 0) {
+    byKey.set("error.type", encodeAttribute("error.type", reserved.errorType));
   }
+  for (const [key, value] of Object.entries(caller ?? {})) {
+    byKey.set(key, encodeAttribute(key, coerceFieldValue(value)));
+  }
+  return [...byKey.values()];
+};
+const otlpSpanBody = (event, serviceName) => {
+  const span = {
+    attributes: encodeSignalAttributes(
+      { errorType: event.error?.type, functionPath: event.functionPath, shardKey: event.shardKey, userId: event.userId },
+      event.attributes
+    ),
+    endTimeUnixNano: otlpUnixNano(event.startTs + event.durationMs),
+    // Always SPAN_KIND_INTERNAL: only `ctx.trace` spans reach a sink. The
+    // synthetic dispatch span is buffered for the Studio waterfall and never
+    // exported, because the runtime already emits that dispatch to `onRpc` as
+    // a SERVER span — encoding it here too would duplicate it in every trace.
+    kind: 1,
+    name: event.name,
+    parentSpanId: event.parentSpanId,
+    spanId: event.spanId,
+    startTimeUnixNano: otlpUnixNano(event.startTs),
+    // STATUS_CODE_OK (1) / STATUS_CODE_ERROR (2).
+    status: event.ok ? { code: 1 } : { code: 2, message: event.error?.message ?? "" },
+    traceId: event.traceId
+  };
+  return wrapResourceSpans(span, "@lunora/runtime", serviceName);
+};
+const otlpMetricBody = (event, serviceName) => {
+  const timeUnixNano = otlpUnixNano(event.ts);
+  const attributes = encodeSignalAttributes({ functionPath: event.functionPath, shardKey: event.shardKey }, event.attributes);
+  const dataPoint = { asDouble: event.value, attributes, timeUnixNano };
+  if (event.kind === "gauge") {
+    return wrapResourceMetrics({ gauge: { dataPoints: [dataPoint] }, name: event.name }, "@lunora/runtime", serviceName);
+  }
+  if (event.kind === "histogram") {
+    return wrapResourceMetrics(
+      {
+        histogram: {
+          aggregationTemporality: 1,
+          dataPoints: [
+            {
+              attributes,
+              bucketCounts: ["1"],
+              count: "1",
+              explicitBounds: [],
+              max: event.value,
+              min: event.value,
+              // `startTimeUnixNano` omitted for the same reason as
+              // the Sum data point above — see the comment there.
+              sum: event.value,
+              timeUnixNano
+            }
+          ]
+        },
+        name: event.name
+      },
+      "@lunora/runtime",
+      serviceName
+    );
+  }
+  return wrapResourceMetrics(
+    { name: event.name, sum: { aggregationTemporality: 1, dataPoints: [dataPoint], isMonotonic: true } },
+    "@lunora/runtime",
+    serviceName
+  );
+};
+const otlpLogBody = (event, serviceName) => {
   const logRecord = {
-    attributes: [...attributeByKey.values()],
+    // Caller-supplied structured fields become log-record attributes so a
+    // pipeline can filter/index on them; precedence per `encodeSignalAttributes`.
+    attributes: encodeSignalAttributes({ functionPath: event.functionPath, shardKey: event.shardKey, userId: event.userId }, event.fields),
     body: { stringValue: event.message },
     severityNumber: OTLP_SEVERITY[event.level],
     severityText: event.level.toUpperCase(),
@@ -93,6 +159,9 @@ const consoleSink = (options = {}) => {
         console.log("[lunora:log]", event.functionPath, event.message);
       }
     },
+    onMetric: (event) => {
+      console.log("[lunora:metric]", `${event.name}=${String(event.value)}`, event.kind, event.functionPath);
+    },
     onRpc: (event) => {
       if (shouldSkip(event, onlyErrors)) {
         return;
@@ -102,6 +171,10 @@ const consoleSink = (options = {}) => {
       } else {
         console.error("[lunora:rpc]", event);
       }
+    },
+    onSpan: (event) => {
+      const status = event.ok ? "ok" : `error ${event.error?.type ?? ""}`.trim();
+      console.log("[lunora:span]", event.name, `${String(event.durationMs)}ms`, status, event.functionPath);
     }
   };
 };
@@ -241,42 +314,51 @@ const otlpSink = (options) => {
   }
   const tracesUrl = `${base}/v1/traces`;
   const logsUrl = `${base}/v1/logs`;
+  const metricsUrl = `${base}/v1/metrics`;
   const mergedHeaders = mergeHeaders({ "content-type": "application/json" }, headers, token);
   return {
     onLog: (event, context) => {
       otlpPost(logsUrl, otlpLogBody(event, serviceName), mergedHeaders, context);
     },
+    onMetric: (event, context) => {
+      otlpPost(metricsUrl, otlpMetricBody(event, serviceName), mergedHeaders, context);
+    },
     onRpc: (event, context) => {
       if (shouldSkip(event, onlyErrors)) {
         return;
       }
       otlpPost(tracesUrl, otlpTraceBody(event, serviceName, Date.now()), mergedHeaders, context);
+    },
+    onSpan: (event, context) => {
+      otlpPost(tracesUrl, otlpSpanBody(event, serviceName), mergedHeaders, context);
     }
   };
 };
 const combineSinks = (...sinks) => {
+  const fanOut = (method, event, context) => {
+    for (const sink of sinks) {
+      const handler = sink[method];
+      if (!handler) {
+        continue;
+      }
+      try {
+        handler.call(sink, event, context);
+      } catch {
+      }
+    }
+  };
   return {
     onLog: (event, context) => {
-      for (const sink of sinks) {
-        if (!sink.onLog) {
-          continue;
-        }
-        try {
-          sink.onLog(event, context);
-        } catch {
-        }
-      }
+      fanOut("onLog", event, context);
+    },
+    onMetric: (event, context) => {
+      fanOut("onMetric", event, context);
     },
     onRpc: (event, context) => {
-      for (const sink of sinks) {
-        if (!sink.onRpc) {
-          continue;
-        }
-        try {
-          sink.onRpc(event, context);
-        } catch {
-        }
-      }
+      fanOut("onRpc", event, context);
+    },
+    onSpan: (event, context) => {
+      fanOut("onSpan", event, context);
     }
   };
 };

package/dist/packem_shared/{composeWorker-Br4_GgSW.mjs → composeWorker-CqUlK17X.mjs}

@@ -1,6 +1,6 @@
 import { isLunoraError, toErrorBody } from '@lunora/errors';
 import { NOOP_EXECUTION_CONTEXT } from './NOOP_EXECUTION_CONTEXT-CCTu0Bf1.mjs';
-import { o as otlpRandomHex, b as buildTraceparent } from './otlp-0FQT3AI8.mjs';
+import { o as otlpRandomHex, b as buildTraceparent } from './otlp-DOLuy1Aj.mjs';
 import { LunoraError, toErrorResponse } from './LunoraError-Bpb9EFJ3.mjs';
 import { wrapResolverWithContract } from './composeIdentityResolvers-XGjO7V1J.mjs';
 export { composeIdentityResolvers, routeIdentityResolvers } from './composeIdentityResolvers-XGjO7V1J.mjs';

package/dist/packem_shared/{otlp-0FQT3AI8.mjs → otlp-DOLuy1Aj.mjs}

@@ -81,5 +81,15 @@ const wrapResourceLogs = (logRecord, scopeName, serviceName) => {
     ]
   };
 };
+const wrapResourceMetrics = (metric, scopeName, serviceName) => {
+  return {
+    resourceMetrics: [
+      {
+        resource: { attributes: [encodeAttribute("service.name", serviceName)] },
+        scopeMetrics: [{ metrics: [metric], scope: { name: scopeName } }]
+      }
+    ]
+  };
+};
 
-export { OTLP_SEVERITY as O, wrapResourceLogs as a, buildTraceparent as b, otlpUnixNano as c, encodeAttribute as e, mergeHeaders as m, otlpRandomHex as o, wrapResourceSpans as w };
+export { OTLP_SEVERITY as O, wrapResourceMetrics as a, buildTraceparent as b, wrapResourceLogs as c, otlpUnixNano as d, encodeAttribute as e, mergeHeaders as m, otlpRandomHex as o, wrapResourceSpans as w };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lunora/runtime",
-  "version": "1.0.0-alpha.29",
+  "version": "1.0.0-alpha.30",
   "description": "Lunora Worker runtime: the RPC router, shard resolver, and query coordinator",
   "keywords": [
     "cloudflare",