@lunora/server 1.0.0-alpha.28 → 1.0.0-alpha.29

package/dist/index.d.mts

@@ -1,7 +1,7 @@
 import { Validator, Infer, ValidatorMap, InferValidatorMap, v } from '@lunora/values';
 export { type ColumnValidator, type Id, type Infer, ValidationError, type Validator, type ValidatorKind, v } from '@lunora/values';
 import { ArgsValidator, InferArgs, RegisteredAction, X402ProcedureConfig, ActionCtx, MutationCtx, RegisteredMutation, QueryCtx, RegisteredQuery, RegisteredStream, FunctionKind, Secrets, LifecycleEvent, RegisteredLifecycleHook, TableDefinition, RegisteredFunction, VectorIndexDefinition, Schema, AggregateOp, DurableObjectJurisdiction, RelationDefinition, GlobalBackend, OnDeleteAction, ExternalSourceDefinition, TriggerBuilder, TriggerDefinition, VectorEmbedder, VectorMetric, AggregateIndexDefinition, RankIndexDefinition } from "./types.mjs";
-export { type AnyApi, type AuthState, type CachePurge, type DatabaseReader, type DatabaseWriter, type FunctionVisibility, type IndexDefinition, type IndexRangeBuilder, type LifecycleEventKind, type LogFields, type LunoraLogMethod, type LunoraLogger, type PaginationOptions, type PaginationResult, type RankSortKey, type ReadOnlyStorage, type ScheduledFunctionDoc, type ScheduledJob, type Scheduler, type SearchFilterBuilder, type SearchIndexDefinition, type ShardMode, type Storage, type StorageMetadata, type SystemDatabaseReader, type SystemDoc, type SystemQuery, type SystemTableName, type TableReader, type TableVectorIndex, type TriggerAggregateOptions, type TriggerCtx, type TriggerDatabase, type TriggerDeleteEvent, type TriggerEvent, type TriggerGroupByEntry, type TriggerGroupByOptions, type TriggerHandler, type TriggerInsertEvent, type TriggerOp, type TriggerQueryArgs, type TriggerQueryPage, type TriggerRankOptions, type TriggerRankPageOptions, type TriggerRankResult, type TriggerRow, type TriggerTiming, type TriggerUpdateEvent, type VectorMatch, type VectorMatches, type VectorQueryInput, type VectorRecord, type VectorSearch, type VectorSearchReader, type VectorUpsertInput, type WorkflowCreateOptions, type WorkflowHandle, type WorkflowInstance, type WorkflowInstanceStatus, type WorkflowStatusResult, type Workflows, anyApi } from "./types.mjs";
+export { type AnyApi, type AuthState, type CachePurge, type DatabaseReader, type DatabaseWriter, type FunctionVisibility, type IndexDefinition, type IndexRangeBuilder, type LifecycleEventKind, type LogFields, type LunoraLogMethod, type LunoraLogger, type LunoraMetrics, type LunoraTracer, type PaginationOptions, type PaginationResult, type RankSortKey, type ReadOnlyStorage, type ScheduledFunctionDoc, type ScheduledJob, type Scheduler, type SearchFilterBuilder, type SearchIndexDefinition, type ShardMode, type Storage, type StorageMetadata, type SystemDatabaseReader, type SystemDoc, type SystemQuery, type SystemTableName, type TableReader, type TableVectorIndex, type TriggerAggregateOptions, type TriggerCtx, type TriggerDatabase, type TriggerDeleteEvent, type TriggerEvent, type TriggerGroupByEntry, type TriggerGroupByOptions, type TriggerHandler, type TriggerInsertEvent, type TriggerOp, type TriggerQueryArgs, type TriggerQueryPage, type TriggerRankOptions, type TriggerRankPageOptions, type TriggerRankResult, type TriggerRow, type TriggerTiming, type TriggerUpdateEvent, type VectorMatch, type VectorMatches, type VectorQueryInput, type VectorRecord, type VectorSearch, type VectorSearchReader, type VectorUpsertInput, type WorkflowCreateOptions, type WorkflowHandle, type WorkflowInstance, type WorkflowInstanceStatus, type WorkflowStatusResult, type Workflows, anyApi } from "./types.mjs";
 import { LunoraError as LunoraError$1, LunoraErrorCode } from '@lunora/errors';
 export type { LunoraErrorCode } from '@lunora/errors';
 import { Context, Hono } from 'hono';

package/dist/index.d.ts

@@ -1,7 +1,7 @@
 import { Validator, Infer, ValidatorMap, InferValidatorMap, v } from '@lunora/values';
 export { type ColumnValidator, type Id, type Infer, ValidationError, type Validator, type ValidatorKind, v } from '@lunora/values';
 import { ArgsValidator, InferArgs, RegisteredAction, X402ProcedureConfig, ActionCtx, MutationCtx, RegisteredMutation, QueryCtx, RegisteredQuery, RegisteredStream, FunctionKind, Secrets, LifecycleEvent, RegisteredLifecycleHook, TableDefinition, RegisteredFunction, VectorIndexDefinition, Schema, AggregateOp, DurableObjectJurisdiction, RelationDefinition, GlobalBackend, OnDeleteAction, ExternalSourceDefinition, TriggerBuilder, TriggerDefinition, VectorEmbedder, VectorMetric, AggregateIndexDefinition, RankIndexDefinition } from "./types.js";
-export { type AnyApi, type AuthState, type CachePurge, type DatabaseReader, type DatabaseWriter, type FunctionVisibility, type IndexDefinition, type IndexRangeBuilder, type LifecycleEventKind, type LogFields, type LunoraLogMethod, type LunoraLogger, type PaginationOptions, type PaginationResult, type RankSortKey, type ReadOnlyStorage, type ScheduledFunctionDoc, type ScheduledJob, type Scheduler, type SearchFilterBuilder, type SearchIndexDefinition, type ShardMode, type Storage, type StorageMetadata, type SystemDatabaseReader, type SystemDoc, type SystemQuery, type SystemTableName, type TableReader, type TableVectorIndex, type TriggerAggregateOptions, type TriggerCtx, type TriggerDatabase, type TriggerDeleteEvent, type TriggerEvent, type TriggerGroupByEntry, type TriggerGroupByOptions, type TriggerHandler, type TriggerInsertEvent, type TriggerOp, type TriggerQueryArgs, type TriggerQueryPage, type TriggerRankOptions, type TriggerRankPageOptions, type TriggerRankResult, type TriggerRow, type TriggerTiming, type TriggerUpdateEvent, type VectorMatch, type VectorMatches, type VectorQueryInput, type VectorRecord, type VectorSearch, type VectorSearchReader, type VectorUpsertInput, type WorkflowCreateOptions, type WorkflowHandle, type WorkflowInstance, type WorkflowInstanceStatus, type WorkflowStatusResult, type Workflows, anyApi } from "./types.js";
+export { type AnyApi, type AuthState, type CachePurge, type DatabaseReader, type DatabaseWriter, type FunctionVisibility, type IndexDefinition, type IndexRangeBuilder, type LifecycleEventKind, type LogFields, type LunoraLogMethod, type LunoraLogger, type LunoraMetrics, type LunoraTracer, type PaginationOptions, type PaginationResult, type RankSortKey, type ReadOnlyStorage, type ScheduledFunctionDoc, type ScheduledJob, type Scheduler, type SearchFilterBuilder, type SearchIndexDefinition, type ShardMode, type Storage, type StorageMetadata, type SystemDatabaseReader, type SystemDoc, type SystemQuery, type SystemTableName, type TableReader, type TableVectorIndex, type TriggerAggregateOptions, type TriggerCtx, type TriggerDatabase, type TriggerDeleteEvent, type TriggerEvent, type TriggerGroupByEntry, type TriggerGroupByOptions, type TriggerHandler, type TriggerInsertEvent, type TriggerOp, type TriggerQueryArgs, type TriggerQueryPage, type TriggerRankOptions, type TriggerRankPageOptions, type TriggerRankResult, type TriggerRow, type TriggerTiming, type TriggerUpdateEvent, type VectorMatch, type VectorMatches, type VectorQueryInput, type VectorRecord, type VectorSearch, type VectorSearchReader, type VectorUpsertInput, type WorkflowCreateOptions, type WorkflowHandle, type WorkflowInstance, type WorkflowInstanceStatus, type WorkflowStatusResult, type Workflows, anyApi } from "./types.js";
 import { LunoraError as LunoraError$1, LunoraErrorCode } from '@lunora/errors';
 export type { LunoraErrorCode } from '@lunora/errors';
 import { Context, Hono } from 'hono';

package/dist/types.d.mts

@@ -1164,7 +1164,7 @@ interface VectorSearch extends VectorSearchReader {
 }
 /**
  * Structured, filterable key/value fields attached to a log line — the second
- * argument of a `ctx.log.<level>(message, fields)` call, or the fields bound by
+ * argument of a `ctx.log.&lt;level>(message, fields)` call, or the fields bound by
  * `ctx.log.with(fields)`. They travel to an `ObservabilitySink`'s `onLog` and,
  * for a network sink, become OTLP log-record attributes a log pipeline (or the
  * Cloud log viewer) can filter and index on. Primitive values pass through;
@@ -1174,10 +1174,8 @@ type LogFields = Record<string, unknown>;
 /**
  * One `ctx.log` severity method. Two call forms:
  *
- * - **Structured** — `ctx.log.info("order placed", { orderId, total })`: a
- *   message string plus a `fields` object. The fields are indexed as attributes.
- * - **Console-style** — `ctx.log.info("state", value, other)`: any number of
- *   values, joined into the display message exactly like `console.log`.
+ * - **Structured** — `ctx.log.info("order placed", { orderId, total })`: a message string plus a `fields` object. The fields are indexed as attributes.
+ * - **Console-style** — `ctx.log.info("state", value, other)`: any number of values, joined into the display message exactly like `console.log`.
  *
  * The structured form is matched when the second argument is a plain object;
  * otherwise the call is treated as console-style, so existing `console`-shaped
@@ -1225,6 +1223,91 @@ interface LunoraLogger {
    */
   readonly with: (fields: LogFields) => LunoraLogger;
 }
+/**
+ * Span factory on every function `ctx`. Wraps a sub-operation so it becomes its
+ * own **span** nested under the dispatch's RPC span, giving a trace real shape:
+ * without it a slow request is one opaque bar, with it you see which part was
+ * slow.
+ *
+ * ```ts
+ * const charge = await ctx.trace("stripe.charge", () => stripe.charges.create(…), { orderId });
+ * ```
+ *
+ * **Nesting is explicit.** The body receives a tracer bound to its own span;
+ * calling *that* is what makes a child:
+ *
+ * ```ts
+ * await ctx.trace("fulfil", async (trace) => {
+ *     // Children of "fulfil" — including under Promise.all, where an ambient
+ *     // "currently open span" would mis-record these as nested inside each other.
+ *     await Promise.all([trace("reserve.stock", …), trace("email.receipt", …)]);
+ * });
+ * ```
+ *
+ * Calling `ctx.trace` again inside a body (rather than the passed tracer) is not
+ * an error — that span is simply parented to the dispatch instead of to the
+ * enclosing span, which is flatter but never wrong.
+ *
+ * Spans share the dispatch's trace id with its `ctx.log` lines and any container
+ * the handler calls (the same `traceparent` is propagated), so one trace spans
+ * worker, shard, and container.
+ *
+ * The span is recorded when the body settles, and the body's value is returned
+ * unchanged. A throw is recorded as an error span and then **re-thrown** — this
+ * is instrumentation, never flow control. Recording is best-effort: a failing
+ * sink can't turn a working handler into a broken one.
+ * @param name Span name, e.g. `"stripe.charge"`. Prefer a low-cardinality name
+ * and put the varying part in `attributes` — a name built from an id makes every
+ * span its own group in a collector.
+ * @param fn The body to time, receiving a tracer bound to this span for any
+ * nested spans. May be sync or async; the result is awaited.
+ * @param attributes Structured attributes to stamp on the span, normalized like
+ * a log line's `fields`.
+ */
+type LunoraTracer = <T>(name: string, function_: (trace: LunoraTracer) => Promise<T> | T, attributes?: LogFields) => Promise<T>;
+/**
+ * Application metrics on every function `ctx` — the third signal alongside
+ * `ctx.log` and `ctx.trace`. Each call records one measurement that flows to an
+ * `ObservabilitySink`'s `onMetric`, and from `otlpSink` to a collector's
+ * `/v1/metrics`.
+ *
+ * ```ts
+ * ctx.metrics.count("orders.placed", 1, { plan: user.plan });
+ * ctx.metrics.record("checkout.latency_ms", Date.now() - started);
+ * ctx.metrics.gauge("cart.items", cart.items.length);
+ * ```
+ *
+ * Pick the instrument by the question you want to answer: `count` for "how many"
+ * (summed over time), `gauge` for "how many right now" (replaces the last
+ * reading), `record` for "what's the distribution" (percentiles, not just a
+ * mean).
+ *
+ * `attributes` are the metric's dimensions. Keep them **low-cardinality** — an
+ * attribute valued by user id or order id creates a distinct time series per id,
+ * which is how a metrics backend gets expensive. Put identifiers on a log line or
+ * a span instead.
+ *
+ * No pre-aggregation happens: one call is one exported measurement, with counter
+ * deltas for the collector to sum. In a hot loop, sum locally and record once
+ * rather than calling per iteration.
+ */
+interface LunoraMetrics {
+  /**
+   * Add to a monotonic counter (default `1`) — requests served, retries,
+   * bytes sent. The collector sums successive deltas.
+   */
+  readonly count: (name: string, value?: number, attributes?: LogFields) => void;
+  /**
+   * Report a point-in-time reading that replaces the previous one — queue
+   * depth, cache size, connections open.
+   */
+  readonly gauge: (name: string, value: number, attributes?: LogFields) => void;
+  /**
+   * Observe one sample of a distribution — latency, payload size. Use this,
+   * not a counter, when percentiles matter.
+   */
+  readonly record: (name: string, value: number, attributes?: LogFields) => void;
+}
 interface QueryCtx {
   readonly auth: AuthState;
   readonly db: DatabaseReader;
@@ -1245,6 +1328,8 @@ interface QueryCtx {
   readonly ip?: string;
   /** Structured, function-attributed logger; see {@link LunoraLogger}. */
   readonly log: LunoraLogger;
+  /** Application counters, gauges, and histograms; see {@link LunoraMetrics}. */
+  readonly metrics: LunoraMetrics;
   /**
    * Wall-clock time (epoch ms) the function began, captured once so the whole
    * handler sees a single stable value. Query/mutation handlers must be
@@ -1265,6 +1350,8 @@ interface QueryCtx {
   /** Read account-level secrets from Cloudflare Secrets Store; see {@link Secrets}. */
   readonly secrets: Secrets;
   readonly storage: ReadOnlyStorage;
+  /** Wrap a sub-operation in its own nested span; see {@link LunoraTracer}. */
+  readonly trace: LunoraTracer;
   readonly vectors: VectorSearchReader;
 }
 interface MutationCtx {
@@ -1287,6 +1374,8 @@ interface MutationCtx {
   readonly ip?: string;
   /** Structured, function-attributed logger; see {@link LunoraLogger}. */
   readonly log: LunoraLogger;
+  /** Application counters, gauges, and histograms; see {@link LunoraMetrics}. */
+  readonly metrics: LunoraMetrics;
   /**
    * Wall-clock time (epoch ms) the function began, captured once so the whole
    * handler sees a single stable value. Mutation handlers must be deterministic
@@ -1315,6 +1404,8 @@ interface MutationCtx {
   /** Read account-level secrets from Cloudflare Secrets Store; see {@link Secrets}. */
   readonly secrets: Secrets;
   readonly storage: ReadOnlyStorage;
+  /** Wrap a sub-operation in its own nested span; see {@link LunoraTracer}. */
+  readonly trace: LunoraTracer;
   readonly vectors: VectorSearch;
   /** Start / resume / inspect durable workflows; see {@link Workflows}. */
   readonly workflows: Workflows;
@@ -1347,6 +1438,8 @@ interface ActionCtx {
   readonly ip?: string;
   /** Structured, function-attributed logger; see {@link LunoraLogger}. */
   readonly log: LunoraLogger;
+  /** Application counters, gauges, and histograms; see {@link LunoraMetrics}. */
+  readonly metrics: LunoraMetrics;
   /**
    * Wall-clock time (epoch ms) the action began, captured once for convenience
    * and parity with query/mutation `ctx.now`. Actions run exactly once, so they
@@ -1360,6 +1453,8 @@ interface ActionCtx {
   /** Read account-level secrets from Cloudflare Secrets Store; see {@link Secrets}. */
   readonly secrets: Secrets;
   readonly storage: Storage;
+  /** Wrap a sub-operation in its own nested span; see {@link LunoraTracer}. */
+  readonly trace: LunoraTracer;
   readonly vectors: VectorSearch;
   /** Start / resume / inspect durable workflows; see {@link Workflows}. */
   readonly workflows: Workflows;
@@ -1370,4 +1465,4 @@ interface ActionCtx {
  */
 type AnyApi = Record<string, Record<string, RegisteredFunction<ArgsValidator, unknown, FunctionKind>>>;
 declare const anyApi: AnyApi;
-export { type ActionCtx, type AggregateIndexDefinition, type AggregateOp, type AnyApi, type ArgsValidator, type AuthState, type CachePurge, type DatabaseReader, type DatabaseWriter, type DurableObjectJurisdiction, type ExternalSourceCursor, type ExternalSourceDefinition, type ExternalSourceMode, type ExternalSourceRefresh, type FunctionKind, type FunctionVisibility, type GlobalBackend, type IndexDefinition, type IndexRangeBuilder, type InferArgs, type LifecycleEvent, type LifecycleEventKind, type LogFields, type LunoraLogMethod, type LunoraLogger, type MutationCtx, type OnDeleteAction, type PaginationOptions, type PaginationResult, type QueryCtx, type RankIndexDefinition, type RankSortKey, type ReadOnlyStorage, type RegisteredAction, type RegisteredFunction, type RegisteredLifecycleHook, type RegisteredMutation, type RegisteredQuery, type RegisteredStream, type RelationDefinition, type ScheduledFunctionDoc, type ScheduledJob, type Scheduler, type Schema, type SearchFilterBuilder, type SearchIndexDefinition, type Secrets, type SecretsStoreSecretLike, type ShardMode, type Storage, type StorageMetadata, type SystemDatabaseReader, type SystemDoc, type SystemQuery, type SystemTableName, type TableDefinition, type TableReader, type TableVectorIndex, type TriggerAggregateOptions, type TriggerBuilder, type TriggerCtx, type TriggerDatabase, type TriggerDefinition, type TriggerDeleteEvent, type TriggerEvent, type TriggerGroupByEntry, type TriggerGroupByOptions, type TriggerHandler, type TriggerInsertEvent, type TriggerOp, type TriggerQueryArgs, type TriggerQueryPage, type TriggerRankOptions, type TriggerRankPageOptions, type TriggerRankResult, type TriggerRow, type TriggerTiming, type TriggerUpdateEvent, type VectorEmbedder, type VectorIndexDefinition, type VectorMatch, type VectorMatches, type VectorMetric, type VectorQueryInput, type VectorRecord, type VectorSearch, type VectorSearchReader, type VectorUpsertInput, type WorkflowCreateOptions, type WorkflowHandle, type WorkflowInstance, type WorkflowInstanceStatus, type WorkflowStatusResult, type Workflows, type X402ProcedureConfig, anyApi };
+export { type ActionCtx, type AggregateIndexDefinition, type AggregateOp, type AnyApi, type ArgsValidator, type AuthState, type CachePurge, type DatabaseReader, type DatabaseWriter, type DurableObjectJurisdiction, type ExternalSourceCursor, type ExternalSourceDefinition, type ExternalSourceMode, type ExternalSourceRefresh, type FunctionKind, type FunctionVisibility, type GlobalBackend, type IndexDefinition, type IndexRangeBuilder, type InferArgs, type LifecycleEvent, type LifecycleEventKind, type LogFields, type LunoraLogMethod, type LunoraLogger, type LunoraMetrics, type LunoraTracer, type MutationCtx, type OnDeleteAction, type PaginationOptions, type PaginationResult, type QueryCtx, type RankIndexDefinition, type RankSortKey, type ReadOnlyStorage, type RegisteredAction, type RegisteredFunction, type RegisteredLifecycleHook, type RegisteredMutation, type RegisteredQuery, type RegisteredStream, type RelationDefinition, type ScheduledFunctionDoc, type ScheduledJob, type Scheduler, type Schema, type SearchFilterBuilder, type SearchIndexDefinition, type Secrets, type SecretsStoreSecretLike, type ShardMode, type Storage, type StorageMetadata, type SystemDatabaseReader, type SystemDoc, type SystemQuery, type SystemTableName, type TableDefinition, type TableReader, type TableVectorIndex, type TriggerAggregateOptions, type TriggerBuilder, type TriggerCtx, type TriggerDatabase, type TriggerDefinition, type TriggerDeleteEvent, type TriggerEvent, type TriggerGroupByEntry, type TriggerGroupByOptions, type TriggerHandler, type TriggerInsertEvent, type TriggerOp, type TriggerQueryArgs, type TriggerQueryPage, type TriggerRankOptions, type TriggerRankPageOptions, type TriggerRankResult, type TriggerRow, type TriggerTiming, type TriggerUpdateEvent, type VectorEmbedder, type VectorIndexDefinition, type VectorMatch, type VectorMatches, type VectorMetric, type VectorQueryInput, type VectorRecord, type VectorSearch, type VectorSearchReader, type VectorUpsertInput, type WorkflowCreateOptions, type WorkflowHandle, type WorkflowInstance, type WorkflowInstanceStatus, type WorkflowStatusResult, type Workflows, type X402ProcedureConfig, anyApi };

package/dist/types.d.ts

@@ -1164,7 +1164,7 @@ interface VectorSearch extends VectorSearchReader {
 }
 /**
  * Structured, filterable key/value fields attached to a log line — the second
- * argument of a `ctx.log.<level>(message, fields)` call, or the fields bound by
+ * argument of a `ctx.log.&lt;level>(message, fields)` call, or the fields bound by
  * `ctx.log.with(fields)`. They travel to an `ObservabilitySink`'s `onLog` and,
  * for a network sink, become OTLP log-record attributes a log pipeline (or the
  * Cloud log viewer) can filter and index on. Primitive values pass through;
@@ -1174,10 +1174,8 @@ type LogFields = Record<string, unknown>;
 /**
  * One `ctx.log` severity method. Two call forms:
  *
- * - **Structured** — `ctx.log.info("order placed", { orderId, total })`: a
- *   message string plus a `fields` object. The fields are indexed as attributes.
- * - **Console-style** — `ctx.log.info("state", value, other)`: any number of
- *   values, joined into the display message exactly like `console.log`.
+ * - **Structured** — `ctx.log.info("order placed", { orderId, total })`: a message string plus a `fields` object. The fields are indexed as attributes.
+ * - **Console-style** — `ctx.log.info("state", value, other)`: any number of values, joined into the display message exactly like `console.log`.
  *
  * The structured form is matched when the second argument is a plain object;
  * otherwise the call is treated as console-style, so existing `console`-shaped
@@ -1225,6 +1223,91 @@ interface LunoraLogger {
    */
   readonly with: (fields: LogFields) => LunoraLogger;
 }
+/**
+ * Span factory on every function `ctx`. Wraps a sub-operation so it becomes its
+ * own **span** nested under the dispatch's RPC span, giving a trace real shape:
+ * without it a slow request is one opaque bar, with it you see which part was
+ * slow.
+ *
+ * ```ts
+ * const charge = await ctx.trace("stripe.charge", () => stripe.charges.create(…), { orderId });
+ * ```
+ *
+ * **Nesting is explicit.** The body receives a tracer bound to its own span;
+ * calling *that* is what makes a child:
+ *
+ * ```ts
+ * await ctx.trace("fulfil", async (trace) => {
+ *     // Children of "fulfil" — including under Promise.all, where an ambient
+ *     // "currently open span" would mis-record these as nested inside each other.
+ *     await Promise.all([trace("reserve.stock", …), trace("email.receipt", …)]);
+ * });
+ * ```
+ *
+ * Calling `ctx.trace` again inside a body (rather than the passed tracer) is not
+ * an error — that span is simply parented to the dispatch instead of to the
+ * enclosing span, which is flatter but never wrong.
+ *
+ * Spans share the dispatch's trace id with its `ctx.log` lines and any container
+ * the handler calls (the same `traceparent` is propagated), so one trace spans
+ * worker, shard, and container.
+ *
+ * The span is recorded when the body settles, and the body's value is returned
+ * unchanged. A throw is recorded as an error span and then **re-thrown** — this
+ * is instrumentation, never flow control. Recording is best-effort: a failing
+ * sink can't turn a working handler into a broken one.
+ * @param name Span name, e.g. `"stripe.charge"`. Prefer a low-cardinality name
+ * and put the varying part in `attributes` — a name built from an id makes every
+ * span its own group in a collector.
+ * @param fn The body to time, receiving a tracer bound to this span for any
+ * nested spans. May be sync or async; the result is awaited.
+ * @param attributes Structured attributes to stamp on the span, normalized like
+ * a log line's `fields`.
+ */
+type LunoraTracer = <T>(name: string, function_: (trace: LunoraTracer) => Promise<T> | T, attributes?: LogFields) => Promise<T>;
+/**
+ * Application metrics on every function `ctx` — the third signal alongside
+ * `ctx.log` and `ctx.trace`. Each call records one measurement that flows to an
+ * `ObservabilitySink`'s `onMetric`, and from `otlpSink` to a collector's
+ * `/v1/metrics`.
+ *
+ * ```ts
+ * ctx.metrics.count("orders.placed", 1, { plan: user.plan });
+ * ctx.metrics.record("checkout.latency_ms", Date.now() - started);
+ * ctx.metrics.gauge("cart.items", cart.items.length);
+ * ```
+ *
+ * Pick the instrument by the question you want to answer: `count` for "how many"
+ * (summed over time), `gauge` for "how many right now" (replaces the last
+ * reading), `record` for "what's the distribution" (percentiles, not just a
+ * mean).
+ *
+ * `attributes` are the metric's dimensions. Keep them **low-cardinality** — an
+ * attribute valued by user id or order id creates a distinct time series per id,
+ * which is how a metrics backend gets expensive. Put identifiers on a log line or
+ * a span instead.
+ *
+ * No pre-aggregation happens: one call is one exported measurement, with counter
+ * deltas for the collector to sum. In a hot loop, sum locally and record once
+ * rather than calling per iteration.
+ */
+interface LunoraMetrics {
+  /**
+   * Add to a monotonic counter (default `1`) — requests served, retries,
+   * bytes sent. The collector sums successive deltas.
+   */
+  readonly count: (name: string, value?: number, attributes?: LogFields) => void;
+  /**
+   * Report a point-in-time reading that replaces the previous one — queue
+   * depth, cache size, connections open.
+   */
+  readonly gauge: (name: string, value: number, attributes?: LogFields) => void;
+  /**
+   * Observe one sample of a distribution — latency, payload size. Use this,
+   * not a counter, when percentiles matter.
+   */
+  readonly record: (name: string, value: number, attributes?: LogFields) => void;
+}
 interface QueryCtx {
   readonly auth: AuthState;
   readonly db: DatabaseReader;
@@ -1245,6 +1328,8 @@ interface QueryCtx {
   readonly ip?: string;
   /** Structured, function-attributed logger; see {@link LunoraLogger}. */
   readonly log: LunoraLogger;
+  /** Application counters, gauges, and histograms; see {@link LunoraMetrics}. */
+  readonly metrics: LunoraMetrics;
   /**
    * Wall-clock time (epoch ms) the function began, captured once so the whole
    * handler sees a single stable value. Query/mutation handlers must be
@@ -1265,6 +1350,8 @@ interface QueryCtx {
   /** Read account-level secrets from Cloudflare Secrets Store; see {@link Secrets}. */
   readonly secrets: Secrets;
   readonly storage: ReadOnlyStorage;
+  /** Wrap a sub-operation in its own nested span; see {@link LunoraTracer}. */
+  readonly trace: LunoraTracer;
   readonly vectors: VectorSearchReader;
 }
 interface MutationCtx {
@@ -1287,6 +1374,8 @@ interface MutationCtx {
   readonly ip?: string;
   /** Structured, function-attributed logger; see {@link LunoraLogger}. */
   readonly log: LunoraLogger;
+  /** Application counters, gauges, and histograms; see {@link LunoraMetrics}. */
+  readonly metrics: LunoraMetrics;
   /**
    * Wall-clock time (epoch ms) the function began, captured once so the whole
    * handler sees a single stable value. Mutation handlers must be deterministic
@@ -1315,6 +1404,8 @@ interface MutationCtx {
   /** Read account-level secrets from Cloudflare Secrets Store; see {@link Secrets}. */
   readonly secrets: Secrets;
   readonly storage: ReadOnlyStorage;
+  /** Wrap a sub-operation in its own nested span; see {@link LunoraTracer}. */
+  readonly trace: LunoraTracer;
   readonly vectors: VectorSearch;
   /** Start / resume / inspect durable workflows; see {@link Workflows}. */
   readonly workflows: Workflows;
@@ -1347,6 +1438,8 @@ interface ActionCtx {
   readonly ip?: string;
   /** Structured, function-attributed logger; see {@link LunoraLogger}. */
   readonly log: LunoraLogger;
+  /** Application counters, gauges, and histograms; see {@link LunoraMetrics}. */
+  readonly metrics: LunoraMetrics;
   /**
    * Wall-clock time (epoch ms) the action began, captured once for convenience
    * and parity with query/mutation `ctx.now`. Actions run exactly once, so they
@@ -1360,6 +1453,8 @@ interface ActionCtx {
   /** Read account-level secrets from Cloudflare Secrets Store; see {@link Secrets}. */
   readonly secrets: Secrets;
   readonly storage: Storage;
+  /** Wrap a sub-operation in its own nested span; see {@link LunoraTracer}. */
+  readonly trace: LunoraTracer;
   readonly vectors: VectorSearch;
   /** Start / resume / inspect durable workflows; see {@link Workflows}. */
   readonly workflows: Workflows;
@@ -1370,4 +1465,4 @@ interface ActionCtx {
  */
 type AnyApi = Record<string, Record<string, RegisteredFunction<ArgsValidator, unknown, FunctionKind>>>;
 declare const anyApi: AnyApi;
-export { type ActionCtx, type AggregateIndexDefinition, type AggregateOp, type AnyApi, type ArgsValidator, type AuthState, type CachePurge, type DatabaseReader, type DatabaseWriter, type DurableObjectJurisdiction, type ExternalSourceCursor, type ExternalSourceDefinition, type ExternalSourceMode, type ExternalSourceRefresh, type FunctionKind, type FunctionVisibility, type GlobalBackend, type IndexDefinition, type IndexRangeBuilder, type InferArgs, type LifecycleEvent, type LifecycleEventKind, type LogFields, type LunoraLogMethod, type LunoraLogger, type MutationCtx, type OnDeleteAction, type PaginationOptions, type PaginationResult, type QueryCtx, type RankIndexDefinition, type RankSortKey, type ReadOnlyStorage, type RegisteredAction, type RegisteredFunction, type RegisteredLifecycleHook, type RegisteredMutation, type RegisteredQuery, type RegisteredStream, type RelationDefinition, type ScheduledFunctionDoc, type ScheduledJob, type Scheduler, type Schema, type SearchFilterBuilder, type SearchIndexDefinition, type Secrets, type SecretsStoreSecretLike, type ShardMode, type Storage, type StorageMetadata, type SystemDatabaseReader, type SystemDoc, type SystemQuery, type SystemTableName, type TableDefinition, type TableReader, type TableVectorIndex, type TriggerAggregateOptions, type TriggerBuilder, type TriggerCtx, type TriggerDatabase, type TriggerDefinition, type TriggerDeleteEvent, type TriggerEvent, type TriggerGroupByEntry, type TriggerGroupByOptions, type TriggerHandler, type TriggerInsertEvent, type TriggerOp, type TriggerQueryArgs, type TriggerQueryPage, type TriggerRankOptions, type TriggerRankPageOptions, type TriggerRankResult, type TriggerRow, type TriggerTiming, type TriggerUpdateEvent, type VectorEmbedder, type VectorIndexDefinition, type VectorMatch, type VectorMatches, type VectorMetric, type VectorQueryInput, type VectorRecord, type VectorSearch, type VectorSearchReader, type VectorUpsertInput, type WorkflowCreateOptions, type WorkflowHandle, type WorkflowInstance, type WorkflowInstanceStatus, type WorkflowStatusResult, type Workflows, type X402ProcedureConfig, anyApi };
+export { type ActionCtx, type AggregateIndexDefinition, type AggregateOp, type AnyApi, type ArgsValidator, type AuthState, type CachePurge, type DatabaseReader, type DatabaseWriter, type DurableObjectJurisdiction, type ExternalSourceCursor, type ExternalSourceDefinition, type ExternalSourceMode, type ExternalSourceRefresh, type FunctionKind, type FunctionVisibility, type GlobalBackend, type IndexDefinition, type IndexRangeBuilder, type InferArgs, type LifecycleEvent, type LifecycleEventKind, type LogFields, type LunoraLogMethod, type LunoraLogger, type LunoraMetrics, type LunoraTracer, type MutationCtx, type OnDeleteAction, type PaginationOptions, type PaginationResult, type QueryCtx, type RankIndexDefinition, type RankSortKey, type ReadOnlyStorage, type RegisteredAction, type RegisteredFunction, type RegisteredLifecycleHook, type RegisteredMutation, type RegisteredQuery, type RegisteredStream, type RelationDefinition, type ScheduledFunctionDoc, type ScheduledJob, type Scheduler, type Schema, type SearchFilterBuilder, type SearchIndexDefinition, type Secrets, type SecretsStoreSecretLike, type ShardMode, type Storage, type StorageMetadata, type SystemDatabaseReader, type SystemDoc, type SystemQuery, type SystemTableName, type TableDefinition, type TableReader, type TableVectorIndex, type TriggerAggregateOptions, type TriggerBuilder, type TriggerCtx, type TriggerDatabase, type TriggerDefinition, type TriggerDeleteEvent, type TriggerEvent, type TriggerGroupByEntry, type TriggerGroupByOptions, type TriggerHandler, type TriggerInsertEvent, type TriggerOp, type TriggerQueryArgs, type TriggerQueryPage, type TriggerRankOptions, type TriggerRankPageOptions, type TriggerRankResult, type TriggerRow, type TriggerTiming, type TriggerUpdateEvent, type VectorEmbedder, type VectorIndexDefinition, type VectorMatch, type VectorMatches, type VectorMetric, type VectorQueryInput, type VectorRecord, type VectorSearch, type VectorSearchReader, type VectorUpsertInput, type WorkflowCreateOptions, type WorkflowHandle, type WorkflowInstance, type WorkflowInstanceStatus, type WorkflowStatusResult, type Workflows, type X402ProcedureConfig, anyApi };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lunora/server",
-  "version": "1.0.0-alpha.28",
+  "version": "1.0.0-alpha.29",
   "description": "Server primitives for Lunora: defineSchema, defineTable, query, mutation, and action",
   "keywords": [
     "backend",