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

package/dist/index.d.mts

@@ -2,6 +2,7 @@ import { RankDirection, RankPageRow, DatabaseWriterLike } from '@lunora/do';
 export type { RankDirection as RankPageDirection, RankPageRowKey as RankPageKey, RankPageRow, ShardRankPageResult } from '@lunora/do';
 import { WorkflowsRestClient } from '@lunora/workflow';
 import { LunoraError as LunoraError$1, ErrorBody } from '@lunora/errors';
+import { R2SqlClient } from '@lunora/bindings/r2sql';
 /**
  * Turn-key incremental-sync source helpers for warehouse connectors
  * (Fivetran custom functions, Airbyte incremental sources).
@@ -2924,6 +2925,17 @@ interface PipelineLike {
 interface PipelineLogSinkOptions {
   /** The Cloudflare Pipeline binding each log record is durably sent to. */
   pipeline: PipelineLike;
+  /**
+   * When true, `fields` is written as a **JSON string** (`JSON.stringify`)
+   * rather than a nested object. Defaults to `false` for back-compatibility.
+   *
+   * Turn it on when the destination Iceberg table types `fields` as a `string`
+   * column so the archive stays queryable (R2 SQL can `LIKE`/compare a string
+   * column, but not index into an arbitrarily-shaped struct). The reader
+   * (`createPipelineLogReader`) parses such a JSON string back to an object on
+   * read. Leave it off when the table types `fields` as a native struct.
+   */
+  serializeFields?: boolean;
 }
 /**
  * A sink that durably persists each `ctx.log` line to a Cloudflare Pipeline
@@ -2933,6 +2945,20 @@ interface PipelineLogSinkOptions {
  * structured record (message, level, function path, fields, trace ids, shard,
  * user, timestamp) in object storage under the app's own account.
  *
+ * **Written-column contract.** Each record is a flat object; this is the exact
+ * read-side schema `createPipelineLogReader` (`pipeline-log-reader.ts`) mirrors
+ * in its `DEFAULT_LOG_COLUMNS`. Keep the two in lockstep — a column added here
+ * must gain a default there:
+ * - `functionPath` (string) — always present
+ * - `level` (string severity) — always present
+ * - `message` (string) — always present
+ * - `ts` (number, epoch-millis) — always present
+ * - `fields` (nested object, or a JSON string when `serializeFields`) — when set
+ * - `shardKey` (string) — when set
+ * - `userId` (string) — when set
+ * - `traceId` (string) — when set
+ * - `spanId` (string) — when set
+ *
  * Only `onLog` is implemented — RPC-span metrics belong in
  * {@link analyticsEngineSink}. `Pipeline.send` is durable/fire-and-forget on the
  * platform; the call is registered with the request's `context.waitUntil` when
@@ -2943,7 +2969,8 @@ interface PipelineLogSinkOptions {
  * Privacy: the persisted record carries `message` + structured `fields` (not the
  * raw positional args). They may include user input — the R2 bucket is your own,
  * but treat it as a log store and gate PII upstream if that is a concern.
- * @param options Sink options: `pipeline` is the Cloudflare Pipeline binding.
+ * @param options Sink options: `pipeline` is the Cloudflare Pipeline binding;
+ * `serializeFields` stores `fields` as a queryable JSON string.
  */
 declare const pipelineLogSink: (options: PipelineLogSinkOptions) => ObservabilitySink;
 /** Options for {@link otlpSink}. */
@@ -3010,5 +3037,140 @@ declare const otlpSink: (options: OtlpSinkOptions) => ObservabilitySink;
  * @param sinks The sinks to fan out to.
  */
 declare const combineSinks: (...sinks: ObservabilitySink[]) => ObservabilitySink;
+/**
+ * The written-column contract: every field `pipelineLogSink` emits, mapped to the
+ * column it is stored under by default (the identity mapping). Also the source of
+ * truth for the {@link PipelineLogField} union. Mirrors the record built in
+ * `pipelineLogSink` — the read side of the same contract.
+ */
+declare const DEFAULT_COLUMNS: {
+  readonly fields: "fields";
+  readonly functionPath: "functionPath";
+  readonly level: "level";
+  readonly message: "message";
+  readonly shardKey: "shardKey";
+  readonly spanId: "spanId";
+  readonly traceId: "traceId";
+  readonly ts: "ts";
+  readonly userId: "userId";
+};
+/**
+ * The canonical field names of one persisted log record — the keys
+ * `pipelineLogSink` writes. Used as the {@link PipelineLogColumnMap} keys and the
+ * {@link PipelineLogRow} shape, so the reader stays decoupled from whatever
+ * physical column names the operator's Iceberg table happens to use.
+ */
+type PipelineLogField = keyof typeof DEFAULT_COLUMNS;
+/**
+ * Field-to-column-name map. Defaults to the identity mapping (each field stored
+ * under its own name, matching what `pipelineLogSink` writes). Override per-field
+ * when the Iceberg schema renames a column; unspecified fields keep their
+ * default. This is the single knob that lets one reader serve differently shaped
+ * Data Catalog tables.
+ */
+type PipelineLogColumnMap = Partial<Record<PipelineLogField, string>>;
+/** An opaque keyset cursor: the `ts` of the row after the last one returned. */
+interface PipelineLogCursor {
+  /** Epoch-millis boundary; the next page is every row strictly older than this. */
+  ts: number;
+}
+/** Filters for one {@link PipelineLogReader} query. Every value is inlined safely (`lit`/`sql`). */
+interface PipelineLogQuery {
+  /** Continue after a previous page (keyset on `ts DESC`). Combined with the other filters. */
+  cursor?: PipelineLogCursor;
+  /** Match only this exact function path's records. Prefer `functionPathPrefix` for a namespace sweep. */
+  functionPath?: string;
+  /** Match records whose `functionPath` starts with this string (rendered as a `LIKE 'prefix%'`). */
+  functionPathPrefix?: string;
+  /** Match only this exact severity. When set, `minLevel` is ignored for the same field. */
+  level?: ContextLogLevel;
+  /** Max rows to return. Clamped to `[1, 10000]`; defaults to {@link DEFAULT_LOG_LIMIT}. */
+  limit?: number;
+  /** Severity floor: keep every level at or above this in {@link LOG_LEVEL_ORDER} (e.g. `warn` keeps warn, error, fatal). */
+  minLevel?: ContextLogLevel;
+  /** Match only this shard key. */
+  shardKey?: string;
+  /** Lower time bound, inclusive (`ts` at or after this), epoch-millis. */
+  sinceTs?: number;
+  /** Match only this trace id. */
+  traceId?: string;
+  /** Upper time bound, inclusive (`ts` at or before this), epoch-millis. */
+  untilTs?: number;
+  /** Match only this acting user id. */
+  userId?: string;
+}
+/**
+ * One decoded log record. Always keyed by the canonical {@link PipelineLogField}
+ * names regardless of the physical columns (the reader remaps via `columnMap`),
+ * so consumers never see the operator's storage names.
+ */
+interface PipelineLogRow {
+  /**
+   * Structured fields, when the record carried them. A `serializeFields` sink
+   * stores these as a JSON string, which the reader parses back to an object;
+   * a plain string that is not valid JSON is returned verbatim.
+   */
+  fields?: unknown;
+  /** Function path that emitted the line, e.g. `"messages:list"`. */
+  functionPath: string;
+  /** Severity the line was logged at. */
+  level: ContextLogLevel;
+  /** Rendered message. */
+  message: string;
+  /** Shard key for single-shard calls, when present. */
+  shardKey?: string;
+  /** Span id the line was emitted under, when present. */
+  spanId?: string;
+  /** Trace id the line belongs to, when present. */
+  traceId?: string;
+  /** Epoch-millis the line was emitted. */
+  ts: number;
+  /** Acting user id, when present. */
+  userId?: string;
+}
+/** One page of {@link PipelineLogRow}s, newest first, plus the cursor for the next page (absent means last page). */
+interface PipelineLogPage {
+  /** The cursor to pass as {@link PipelineLogQuery} `cursor` for the following page; absent when this is the last page. */
+  nextCursor?: PipelineLogCursor;
+  /** The rows, ordered `ts DESC` (newest first). At most `limit` of them. */
+  rows: PipelineLogRow[];
+}
+/** Options for {@link createPipelineLogReader}. */
+interface PipelineLogReaderOptions {
+  /**
+   * Override any physical column name that diverges from the default (identity)
+   * mapping. Unspecified fields keep their {@link DEFAULT_LOG_COLUMNS} name.
+   */
+  columnMap?: PipelineLogColumnMap;
+  /**
+   * The Iceberg namespace the `table` lives in (R2 Data Catalog database).
+   * Combined as `namespace.table` in the `FROM` clause; omit when `table`
+   * already carries its namespace.
+   */
+  namespace?: string;
+  /** The Iceberg table name the Pipeline writes log records to (e.g. `"logs"`). */
+  table: string;
+}
+/** The reader surface: a single keyset-paginated {@link PipelineLogPage} query. */
+interface PipelineLogReader {
+  /** Run one filtered, keyset-paginated read and return a {@link PipelineLogPage}. */
+  query: (query?: PipelineLogQuery) => Promise<PipelineLogPage>;
+}
+/** The written-column contract exposed publicly: canonical field to default physical column name. */
+declare const DEFAULT_LOG_COLUMNS: Readonly<Record<PipelineLogField, string>>;
+/** Default page size when a query omits `limit`. */
+declare const DEFAULT_LOG_LIMIT: number;
+/**
+ * Build a durable-log reader over one R2 Data Catalog (Iceberg) table.
+ *
+ * The returned {@link PipelineLogReader} compiles each call to a safe
+ * `SELECT ... WHERE ... ORDER BY ts DESC LIMIT n` (over-fetching by one) and
+ * decodes the rows back to the canonical {@link PipelineLogRow} shape. All value
+ * filters are escaped through `@lunora/bindings/r2sql`'s `sql`/`lit`; column
+ * names come from `options.columnMap` (operator config), spliced with `raw`.
+ * @param client An {@link R2SqlClient} (`createR2Sql({ accountId, apiToken, bucket })`).
+ * @param options The target `table` (plus optional `namespace`) and any `columnMap` overrides.
+ */
+declare const createPipelineLogReader: (client: R2SqlClient, options: PipelineLogReaderOptions) => PipelineLogReader;
 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 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 };
+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_LOG_COLUMNS, DEFAULT_LOG_LIMIT, 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 PipelineLogColumnMap, type PipelineLogCursor, type PipelineLogField, type PipelineLogPage, type PipelineLogQuery, type PipelineLogReader, type PipelineLogReaderOptions, type PipelineLogRow, 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, createPipelineLogReader, 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

@@ -2,6 +2,7 @@ import { RankDirection, RankPageRow, DatabaseWriterLike } from '@lunora/do';
 export type { RankDirection as RankPageDirection, RankPageRowKey as RankPageKey, RankPageRow, ShardRankPageResult } from '@lunora/do';
 import { WorkflowsRestClient } from '@lunora/workflow';
 import { LunoraError as LunoraError$1, ErrorBody } from '@lunora/errors';
+import { R2SqlClient } from '@lunora/bindings/r2sql';
 /**
  * Turn-key incremental-sync source helpers for warehouse connectors
  * (Fivetran custom functions, Airbyte incremental sources).
@@ -2924,6 +2925,17 @@ interface PipelineLike {
 interface PipelineLogSinkOptions {
   /** The Cloudflare Pipeline binding each log record is durably sent to. */
   pipeline: PipelineLike;
+  /**
+   * When true, `fields` is written as a **JSON string** (`JSON.stringify`)
+   * rather than a nested object. Defaults to `false` for back-compatibility.
+   *
+   * Turn it on when the destination Iceberg table types `fields` as a `string`
+   * column so the archive stays queryable (R2 SQL can `LIKE`/compare a string
+   * column, but not index into an arbitrarily-shaped struct). The reader
+   * (`createPipelineLogReader`) parses such a JSON string back to an object on
+   * read. Leave it off when the table types `fields` as a native struct.
+   */
+  serializeFields?: boolean;
 }
 /**
  * A sink that durably persists each `ctx.log` line to a Cloudflare Pipeline
@@ -2933,6 +2945,20 @@ interface PipelineLogSinkOptions {
  * structured record (message, level, function path, fields, trace ids, shard,
  * user, timestamp) in object storage under the app's own account.
  *
+ * **Written-column contract.** Each record is a flat object; this is the exact
+ * read-side schema `createPipelineLogReader` (`pipeline-log-reader.ts`) mirrors
+ * in its `DEFAULT_LOG_COLUMNS`. Keep the two in lockstep — a column added here
+ * must gain a default there:
+ * - `functionPath` (string) — always present
+ * - `level` (string severity) — always present
+ * - `message` (string) — always present
+ * - `ts` (number, epoch-millis) — always present
+ * - `fields` (nested object, or a JSON string when `serializeFields`) — when set
+ * - `shardKey` (string) — when set
+ * - `userId` (string) — when set
+ * - `traceId` (string) — when set
+ * - `spanId` (string) — when set
+ *
  * Only `onLog` is implemented — RPC-span metrics belong in
  * {@link analyticsEngineSink}. `Pipeline.send` is durable/fire-and-forget on the
  * platform; the call is registered with the request's `context.waitUntil` when
@@ -2943,7 +2969,8 @@ interface PipelineLogSinkOptions {
  * Privacy: the persisted record carries `message` + structured `fields` (not the
  * raw positional args). They may include user input — the R2 bucket is your own,
  * but treat it as a log store and gate PII upstream if that is a concern.
- * @param options Sink options: `pipeline` is the Cloudflare Pipeline binding.
+ * @param options Sink options: `pipeline` is the Cloudflare Pipeline binding;
+ * `serializeFields` stores `fields` as a queryable JSON string.
  */
 declare const pipelineLogSink: (options: PipelineLogSinkOptions) => ObservabilitySink;
 /** Options for {@link otlpSink}. */
@@ -3010,5 +3037,140 @@ declare const otlpSink: (options: OtlpSinkOptions) => ObservabilitySink;
  * @param sinks The sinks to fan out to.
  */
 declare const combineSinks: (...sinks: ObservabilitySink[]) => ObservabilitySink;
+/**
+ * The written-column contract: every field `pipelineLogSink` emits, mapped to the
+ * column it is stored under by default (the identity mapping). Also the source of
+ * truth for the {@link PipelineLogField} union. Mirrors the record built in
+ * `pipelineLogSink` — the read side of the same contract.
+ */
+declare const DEFAULT_COLUMNS: {
+  readonly fields: "fields";
+  readonly functionPath: "functionPath";
+  readonly level: "level";
+  readonly message: "message";
+  readonly shardKey: "shardKey";
+  readonly spanId: "spanId";
+  readonly traceId: "traceId";
+  readonly ts: "ts";
+  readonly userId: "userId";
+};
+/**
+ * The canonical field names of one persisted log record — the keys
+ * `pipelineLogSink` writes. Used as the {@link PipelineLogColumnMap} keys and the
+ * {@link PipelineLogRow} shape, so the reader stays decoupled from whatever
+ * physical column names the operator's Iceberg table happens to use.
+ */
+type PipelineLogField = keyof typeof DEFAULT_COLUMNS;
+/**
+ * Field-to-column-name map. Defaults to the identity mapping (each field stored
+ * under its own name, matching what `pipelineLogSink` writes). Override per-field
+ * when the Iceberg schema renames a column; unspecified fields keep their
+ * default. This is the single knob that lets one reader serve differently shaped
+ * Data Catalog tables.
+ */
+type PipelineLogColumnMap = Partial<Record<PipelineLogField, string>>;
+/** An opaque keyset cursor: the `ts` of the row after the last one returned. */
+interface PipelineLogCursor {
+  /** Epoch-millis boundary; the next page is every row strictly older than this. */
+  ts: number;
+}
+/** Filters for one {@link PipelineLogReader} query. Every value is inlined safely (`lit`/`sql`). */
+interface PipelineLogQuery {
+  /** Continue after a previous page (keyset on `ts DESC`). Combined with the other filters. */
+  cursor?: PipelineLogCursor;
+  /** Match only this exact function path's records. Prefer `functionPathPrefix` for a namespace sweep. */
+  functionPath?: string;
+  /** Match records whose `functionPath` starts with this string (rendered as a `LIKE 'prefix%'`). */
+  functionPathPrefix?: string;
+  /** Match only this exact severity. When set, `minLevel` is ignored for the same field. */
+  level?: ContextLogLevel;
+  /** Max rows to return. Clamped to `[1, 10000]`; defaults to {@link DEFAULT_LOG_LIMIT}. */
+  limit?: number;
+  /** Severity floor: keep every level at or above this in {@link LOG_LEVEL_ORDER} (e.g. `warn` keeps warn, error, fatal). */
+  minLevel?: ContextLogLevel;
+  /** Match only this shard key. */
+  shardKey?: string;
+  /** Lower time bound, inclusive (`ts` at or after this), epoch-millis. */
+  sinceTs?: number;
+  /** Match only this trace id. */
+  traceId?: string;
+  /** Upper time bound, inclusive (`ts` at or before this), epoch-millis. */
+  untilTs?: number;
+  /** Match only this acting user id. */
+  userId?: string;
+}
+/**
+ * One decoded log record. Always keyed by the canonical {@link PipelineLogField}
+ * names regardless of the physical columns (the reader remaps via `columnMap`),
+ * so consumers never see the operator's storage names.
+ */
+interface PipelineLogRow {
+  /**
+   * Structured fields, when the record carried them. A `serializeFields` sink
+   * stores these as a JSON string, which the reader parses back to an object;
+   * a plain string that is not valid JSON is returned verbatim.
+   */
+  fields?: unknown;
+  /** Function path that emitted the line, e.g. `"messages:list"`. */
+  functionPath: string;
+  /** Severity the line was logged at. */
+  level: ContextLogLevel;
+  /** Rendered message. */
+  message: string;
+  /** Shard key for single-shard calls, when present. */
+  shardKey?: string;
+  /** Span id the line was emitted under, when present. */
+  spanId?: string;
+  /** Trace id the line belongs to, when present. */
+  traceId?: string;
+  /** Epoch-millis the line was emitted. */
+  ts: number;
+  /** Acting user id, when present. */
+  userId?: string;
+}
+/** One page of {@link PipelineLogRow}s, newest first, plus the cursor for the next page (absent means last page). */
+interface PipelineLogPage {
+  /** The cursor to pass as {@link PipelineLogQuery} `cursor` for the following page; absent when this is the last page. */
+  nextCursor?: PipelineLogCursor;
+  /** The rows, ordered `ts DESC` (newest first). At most `limit` of them. */
+  rows: PipelineLogRow[];
+}
+/** Options for {@link createPipelineLogReader}. */
+interface PipelineLogReaderOptions {
+  /**
+   * Override any physical column name that diverges from the default (identity)
+   * mapping. Unspecified fields keep their {@link DEFAULT_LOG_COLUMNS} name.
+   */
+  columnMap?: PipelineLogColumnMap;
+  /**
+   * The Iceberg namespace the `table` lives in (R2 Data Catalog database).
+   * Combined as `namespace.table` in the `FROM` clause; omit when `table`
+   * already carries its namespace.
+   */
+  namespace?: string;
+  /** The Iceberg table name the Pipeline writes log records to (e.g. `"logs"`). */
+  table: string;
+}
+/** The reader surface: a single keyset-paginated {@link PipelineLogPage} query. */
+interface PipelineLogReader {
+  /** Run one filtered, keyset-paginated read and return a {@link PipelineLogPage}. */
+  query: (query?: PipelineLogQuery) => Promise<PipelineLogPage>;
+}
+/** The written-column contract exposed publicly: canonical field to default physical column name. */
+declare const DEFAULT_LOG_COLUMNS: Readonly<Record<PipelineLogField, string>>;
+/** Default page size when a query omits `limit`. */
+declare const DEFAULT_LOG_LIMIT: number;
+/**
+ * Build a durable-log reader over one R2 Data Catalog (Iceberg) table.
+ *
+ * The returned {@link PipelineLogReader} compiles each call to a safe
+ * `SELECT ... WHERE ... ORDER BY ts DESC LIMIT n` (over-fetching by one) and
+ * decodes the rows back to the canonical {@link PipelineLogRow} shape. All value
+ * filters are escaped through `@lunora/bindings/r2sql`'s `sql`/`lit`; column
+ * names come from `options.columnMap` (operator config), spliced with `raw`.
+ * @param client An {@link R2SqlClient} (`createR2Sql({ accountId, apiToken, bucket })`).
+ * @param options The target `table` (plus optional `namespace`) and any `columnMap` overrides.
+ */
+declare const createPipelineLogReader: (client: R2SqlClient, options: PipelineLogReaderOptions) => PipelineLogReader;
 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 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 };
+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_LOG_COLUMNS, DEFAULT_LOG_LIMIT, 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 PipelineLogColumnMap, type PipelineLogCursor, type PipelineLogField, type PipelineLogPage, type PipelineLogQuery, type PipelineLogReader, type PipelineLogReaderOptions, type PipelineLogRow, 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, createPipelineLogReader, 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

@@ -4,7 +4,8 @@ export { createCrossShardRelationCapabilities } from './packem_shared/createCros
 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-DWUhiYHC.mjs';
+export { analyticsEngineSink, combineSinks, consoleSink, otlpSink, pipelineLogSink, sentrySink, webhookSink } from './packem_shared/analyticsEngineSink-Bn7p0URe.mjs';
+export { DEFAULT_LOG_COLUMNS, DEFAULT_LOG_LIMIT, createPipelineLogReader } from './packem_shared/DEFAULT_LOG_COLUMNS-J94BHDTf.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/DEFAULT_LOG_COLUMNS-J94BHDTf.mjs

@@ -0,0 +1,135 @@
+import { raw, sql, desc } from '@lunora/bindings/r2sql';
+
+const LOG_LEVEL_ORDER = ["trace", "debug", "log", "info", "warn", "error", "fatal"];
+
+const DEFAULT_COLUMNS = {
+  fields: "fields",
+  functionPath: "functionPath",
+  level: "level",
+  message: "message",
+  shardKey: "shardKey",
+  spanId: "spanId",
+  traceId: "traceId",
+  ts: "ts",
+  userId: "userId"
+};
+const DEFAULT_LIMIT = 500;
+const MAX_LIMIT = 1e4;
+const clampLimit = (limit) => {
+  if (limit === void 0 || !Number.isFinite(limit)) {
+    return DEFAULT_LIMIT;
+  }
+  const floored = Math.floor(limit);
+  if (floored < 1) {
+    return 1;
+  }
+  if (floored > MAX_LIMIT) {
+    return MAX_LIMIT;
+  }
+  return floored;
+};
+const toTs = (value) => typeof value === "number" ? value : Number(value);
+const renderCell = (value) => value === null || value === void 0 ? "" : String(value);
+const decodeFields = (value) => {
+  if (typeof value !== "string") {
+    return value;
+  }
+  try {
+    return JSON.parse(value);
+  } catch {
+    return value;
+  }
+};
+const DEFAULT_LOG_COLUMNS = DEFAULT_COLUMNS;
+const DEFAULT_LOG_LIMIT = DEFAULT_LIMIT;
+const createPipelineLogReader = (client, options) => {
+  const columns = { ...DEFAULT_COLUMNS, ...options.columnMap };
+  const tableReference = options.namespace === void 0 ? options.table : `${options.namespace}.${options.table}`;
+  return {
+    query: async (query = {}) => {
+      const limit = clampLimit(query.limit);
+      const fetchLimit = Math.min(limit + 1, MAX_LIMIT);
+      const builder = client.from(tableReference).select(
+        raw(columns.functionPath),
+        raw(columns.level),
+        raw(columns.message),
+        raw(columns.ts),
+        raw(columns.fields),
+        raw(columns.shardKey),
+        raw(columns.userId),
+        raw(columns.traceId),
+        raw(columns.spanId)
+      );
+      if (query.sinceTs !== void 0) {
+        builder.where(sql`${raw(columns.ts)} >= ${query.sinceTs}`);
+      }
+      if (query.untilTs !== void 0) {
+        builder.where(sql`${raw(columns.ts)} <= ${query.untilTs}`);
+      }
+      if (query.level !== void 0) {
+        builder.where(sql`${raw(columns.level)} = ${query.level}`);
+      } else if (query.minLevel !== void 0) {
+        const floorIndex = LOG_LEVEL_ORDER.indexOf(query.minLevel);
+        const allowed = floorIndex === -1 ? [...LOG_LEVEL_ORDER] : LOG_LEVEL_ORDER.slice(floorIndex);
+        builder.where(sql`${raw(columns.level)} IN ${allowed}`);
+      }
+      if (query.functionPath !== void 0) {
+        builder.where(sql`${raw(columns.functionPath)} = ${query.functionPath}`);
+      }
+      if (query.functionPathPrefix !== void 0) {
+        builder.where(sql`${raw(columns.functionPath)} LIKE ${`${query.functionPathPrefix}%`}`);
+      }
+      if (query.traceId !== void 0) {
+        builder.where(sql`${raw(columns.traceId)} = ${query.traceId}`);
+      }
+      if (query.shardKey !== void 0) {
+        builder.where(sql`${raw(columns.shardKey)} = ${query.shardKey}`);
+      }
+      if (query.userId !== void 0) {
+        builder.where(sql`${raw(columns.userId)} = ${query.userId}`);
+      }
+      if (query.cursor !== void 0) {
+        builder.where(sql`${raw(columns.ts)} < ${query.cursor.ts}`);
+      }
+      builder.orderBy(desc(raw(columns.ts))).limit(fetchLimit);
+      const { rows } = await builder.run();
+      const hasMore = rows.length > limit;
+      const pageRows = hasMore ? rows.slice(0, limit) : rows;
+      const overflow = hasMore ? rows[limit] : void 0;
+      const decoded = pageRows.map((row) => {
+        const out = {
+          functionPath: renderCell(row[columns.functionPath]),
+          // The stored `level` is one of the canonical severities; the
+          // reader trusts the writer's contract here rather than re-validating.
+          level: renderCell(row[columns.level]),
+          message: renderCell(row[columns.message]),
+          ts: toTs(row[columns.ts])
+        };
+        const fields = row[columns.fields];
+        if (fields !== void 0 && fields !== null) {
+          out.fields = decodeFields(fields);
+        }
+        const shardKey = row[columns.shardKey];
+        if (shardKey !== void 0 && shardKey !== null) {
+          out.shardKey = renderCell(shardKey);
+        }
+        const userId = row[columns.userId];
+        if (userId !== void 0 && userId !== null) {
+          out.userId = renderCell(userId);
+        }
+        const traceId = row[columns.traceId];
+        if (traceId !== void 0 && traceId !== null) {
+          out.traceId = renderCell(traceId);
+        }
+        const spanId = row[columns.spanId];
+        if (spanId !== void 0 && spanId !== null) {
+          out.spanId = renderCell(spanId);
+        }
+        return out;
+      });
+      return overflow === void 0 ? { rows: decoded } : { nextCursor: { ts: toTs(overflow[columns.ts]) }, rows: decoded };
+    }
+  };
+};
+
+export { DEFAULT_LOG_COLUMNS, DEFAULT_LOG_LIMIT, createPipelineLogReader };

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

@@ -270,7 +270,7 @@ const analyticsEngineSink = (options) => {
   };
 };
 const pipelineLogSink = (options) => {
-  const { pipeline } = options;
+  const { pipeline, serializeFields } = options;
   return {
     onLog: (event, context) => {
       try {
@@ -281,7 +281,7 @@ const pipelineLogSink = (options) => {
           ts: event.ts
         };
         if (event.fields) {
-          record.fields = event.fields;
+          record.fields = serializeFields === true ? JSON.stringify(event.fields) : event.fields;
         }
         if (event.shardKey !== void 0) {
           record.shardKey = event.shardKey;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lunora/runtime",
-  "version": "1.0.0-alpha.30",
+  "version": "1.0.0-alpha.31",
   "description": "Lunora Worker runtime: the RPC router, shard resolver, and query coordinator",
   "keywords": [
     "cloudflare",
@@ -46,6 +46,7 @@
     "access": "public"
   },
   "dependencies": {
+    "@lunora/bindings": "1.0.0-alpha.9",
     "@lunora/errors": "1.0.0-alpha.6"
   },
   "engines": {