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

package/dist/index.d.mts

@@ -1,3 +1,4 @@
+import { R2SqlClient } from '@lunora/bindings/r2sql';
 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';
@@ -661,6 +662,172 @@ interface LogEvent {
   /** Acting userId, or absent when anonymous. */
   userId?: string;
 }
+/**
+ * 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;
+/**
+ * Wire constants for the durable log archive, shared between the server route
+ * (`@lunora/runtime`'s `log-archive-admin-routes`) and the Studio Archive feed
+ * (`@lunora/studio`). Kept here — not in `@lunora/runtime` — because the studio
+ * is a browser bundle that must not import a runtime *value* (which would drag
+ * the DO/R2-SQL runtime into the browser). This file is dependency-free and
+ * bundler-inlined into each consumer, so both sides share one source of truth
+ * with no dependency edge.
+ */
+/**
+ * The error `code` the archive route returns (400) when the operator has wired
+ * no archive table (`logArchive`) or the `R2_SQL_*` credentials are missing. The
+ * Studio keys its "not configured" empty state off this exact value.
+ */
+declare const LOG_ARCHIVE_NOT_CONFIGURED = "LOG_ARCHIVE_NOT_CONFIGURED";
+/** The route the studio's `queryLogArchive` client method POSTs to. */
+declare const LOG_ARCHIVE_PATH = "/_lunora/admin/logs/archive";
+/**
+ * The app-level archive config the worker passes through: which Data Catalog
+ * table the Pipeline writes log records to (the read-side of `pipelineLogSink`),
+ * plus optional namespace / physical-column overrides. The R2 SQL *credentials*
+ * are NOT here — they live on `env` (`R2_SQL_*`), read per request.
+ */
+interface LogArchiveConfig {
+  /** Override any physical column name that diverges from the {@link createPipelineLogReader} default mapping. */
+  columnMap?: PipelineLogColumnMap;
+  /** The Iceberg namespace (R2 Data Catalog database) the table lives in; omit when `table` already carries it. */
+  namespace?: string;
+  /** The Iceberg table the Pipeline writes log records to (e.g. `"logs"`). */
+  table: string;
+}
 /**
  * What kind of instrument produced a measurement, which decides how a collector
  * aggregates it:
@@ -2274,6 +2441,15 @@ interface WorkerOptions {
    * Omit it and those endpoints respond `KV_NOT_CONFIGURED`.
    */
   kvIntrospector?: KvIntrospector;
+  /**
+   * The durable log archive's read config — the R2 Data Catalog (Iceberg)
+   * table `pipelineLogSink` writes to, so the studio Logs panel's Archive feed
+   * (and the `/_lunora/admin/logs/archive` route) can read it back via R2 SQL.
+   * The R2 SQL credentials come from `env` (`R2_SQL_ACCOUNT_ID` / `R2_SQL_TOKEN`
+   * / `R2_SQL_BUCKET`); this only names the table (+ optional namespace / column
+   * overrides). Absent → the Archive feed reports "not configured".
+   */
+  logArchive?: LogArchiveConfig;
   /**
    * Optional telemetry sink. When supplied, the worker emits one
    * `onRpc` event per dispatched RPC (single-shard forward or fan-out)
@@ -2924,6 +3100,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 +3120,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 +3144,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}. */
@@ -3011,4 +3213,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 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, LOG_ARCHIVE_NOT_CONFIGURED, LOG_ARCHIVE_PATH, type ListAuthUsersOptions, type LogArchiveConfig, 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

@@ -1,3 +1,4 @@
+import { R2SqlClient } from '@lunora/bindings/r2sql';
 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';
@@ -661,6 +662,172 @@ interface LogEvent {
   /** Acting userId, or absent when anonymous. */
   userId?: string;
 }
+/**
+ * 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;
+/**
+ * Wire constants for the durable log archive, shared between the server route
+ * (`@lunora/runtime`'s `log-archive-admin-routes`) and the Studio Archive feed
+ * (`@lunora/studio`). Kept here — not in `@lunora/runtime` — because the studio
+ * is a browser bundle that must not import a runtime *value* (which would drag
+ * the DO/R2-SQL runtime into the browser). This file is dependency-free and
+ * bundler-inlined into each consumer, so both sides share one source of truth
+ * with no dependency edge.
+ */
+/**
+ * The error `code` the archive route returns (400) when the operator has wired
+ * no archive table (`logArchive`) or the `R2_SQL_*` credentials are missing. The
+ * Studio keys its "not configured" empty state off this exact value.
+ */
+declare const LOG_ARCHIVE_NOT_CONFIGURED = "LOG_ARCHIVE_NOT_CONFIGURED";
+/** The route the studio's `queryLogArchive` client method POSTs to. */
+declare const LOG_ARCHIVE_PATH = "/_lunora/admin/logs/archive";
+/**
+ * The app-level archive config the worker passes through: which Data Catalog
+ * table the Pipeline writes log records to (the read-side of `pipelineLogSink`),
+ * plus optional namespace / physical-column overrides. The R2 SQL *credentials*
+ * are NOT here — they live on `env` (`R2_SQL_*`), read per request.
+ */
+interface LogArchiveConfig {
+  /** Override any physical column name that diverges from the {@link createPipelineLogReader} default mapping. */
+  columnMap?: PipelineLogColumnMap;
+  /** The Iceberg namespace (R2 Data Catalog database) the table lives in; omit when `table` already carries it. */
+  namespace?: string;
+  /** The Iceberg table the Pipeline writes log records to (e.g. `"logs"`). */
+  table: string;
+}
 /**
  * What kind of instrument produced a measurement, which decides how a collector
  * aggregates it:
@@ -2274,6 +2441,15 @@ interface WorkerOptions {
    * Omit it and those endpoints respond `KV_NOT_CONFIGURED`.
    */
   kvIntrospector?: KvIntrospector;
+  /**
+   * The durable log archive's read config — the R2 Data Catalog (Iceberg)
+   * table `pipelineLogSink` writes to, so the studio Logs panel's Archive feed
+   * (and the `/_lunora/admin/logs/archive` route) can read it back via R2 SQL.
+   * The R2 SQL credentials come from `env` (`R2_SQL_ACCOUNT_ID` / `R2_SQL_TOKEN`
+   * / `R2_SQL_BUCKET`); this only names the table (+ optional namespace / column
+   * overrides). Absent → the Archive feed reports "not configured".
+   */
+  logArchive?: LogArchiveConfig;
   /**
    * Optional telemetry sink. When supplied, the worker emits one
    * `onRpc` event per dispatched RPC (single-shard forward or fan-out)
@@ -2924,6 +3100,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 +3120,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 +3144,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}. */
@@ -3011,4 +3213,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 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, LOG_ARCHIVE_NOT_CONFIGURED, LOG_ARCHIVE_PATH, type ListAuthUsersOptions, type LogArchiveConfig, 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

@@ -1,13 +1,16 @@
 export { toAirbyteMessages, toFivetranResponse } from './packem_shared/toAirbyteMessages-DrHdplb4.mjs';
-export { composeWorker, createLunoraHandler, createWorker, defineRpcEnvelope, resolveLunoraOptions, withFrameworkWorker } from './packem_shared/composeWorker-CqUlK17X.mjs';
+export { composeWorker, createLunoraHandler, createWorker, defineRpcEnvelope, resolveLunoraOptions, withFrameworkWorker } from './packem_shared/composeWorker-DHyRiFho.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 { LOG_ARCHIVE_PATH } from './packem_shared/LOG_ARCHIVE_PATH-iKUShT0P.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 { D as DEFAULT_LOG_COLUMNS, a as DEFAULT_LOG_LIMIT, c as createPipelineLogReader } from './packem_shared/pipeline-log-reader-BXULGNC3.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';
+export { LOG_ARCHIVE_NOT_CONFIGURED } from './packem_shared/LOG_ARCHIVE_NOT_CONFIGURED-acNcguqc.mjs';
 export { NOOP_EXECUTION_CONTEXT } from './packem_shared/NOOP_EXECUTION_CONTEXT-CCTu0Bf1.mjs';
 export { composeIdentityResolvers, routeIdentityResolvers } from './packem_shared/composeIdentityResolvers-XGjO7V1J.mjs';
 

package/dist/packem_shared/DEFAULT_LOG_COLUMNS-B7H3YdJ3.mjs

@@ -0,0 +1,2 @@
+import '@lunora/bindings/r2sql';
+export { D as DEFAULT_LOG_COLUMNS, a as DEFAULT_LOG_LIMIT, c as createPipelineLogReader } from './pipeline-log-reader-BXULGNC3.mjs';

package/dist/packem_shared/LOG_ARCHIVE_NOT_CONFIGURED-acNcguqc.mjs

@@ -0,0 +1,3 @@
+const LOG_ARCHIVE_NOT_CONFIGURED = "LOG_ARCHIVE_NOT_CONFIGURED";
+
+export { LOG_ARCHIVE_NOT_CONFIGURED };

package/dist/packem_shared/LOG_ARCHIVE_PATH-iKUShT0P.mjs

@@ -0,0 +1,111 @@
+import { createR2Sql } from '@lunora/bindings/r2sql';
+import { LOG_ARCHIVE_NOT_CONFIGURED } from './LOG_ARCHIVE_NOT_CONFIGURED-acNcguqc.mjs';
+import { L as LOG_LEVEL_ORDER, c as createPipelineLogReader } from './pipeline-log-reader-BXULGNC3.mjs';
+import { LunoraError } from './LunoraError-Bpb9EFJ3.mjs';
+
+const LOG_ARCHIVE_PATH = "/_lunora/admin/logs/archive";
+const LOG_LEVELS = new Set(LOG_LEVEL_ORDER);
+const optionalString = (value) => typeof value === "string" && value !== "" ? value : void 0;
+const parseLevel = (value, field) => {
+  if (value === void 0) {
+    return void 0;
+  }
+  if (typeof value !== "string" || !LOG_LEVELS.has(value)) {
+    throw new LunoraError(`logs archive: invalid \`${field}\` — expected one of ${LOG_LEVEL_ORDER.join(", ")}`, { code: "BAD_REQUEST", status: 400 });
+  }
+  return value;
+};
+const parseFiniteNumber = (value, field) => {
+  if (value === void 0) {
+    return void 0;
+  }
+  if (typeof value !== "number" || !Number.isFinite(value)) {
+    throw new LunoraError(`logs archive: invalid \`${field}\` — expected a finite number`, { code: "BAD_REQUEST", status: 400 });
+  }
+  return value;
+};
+const parseQuery = (body) => {
+  const query = {};
+  const assignString = (field) => {
+    const value = optionalString(body[field]);
+    if (value !== void 0) {
+      query[field] = value;
+    }
+  };
+  assignString("functionPath");
+  assignString("functionPathPrefix");
+  assignString("traceId");
+  assignString("shardKey");
+  assignString("userId");
+  const level = parseLevel(body["level"], "level");
+  if (level !== void 0) {
+    query.level = level;
+  }
+  const minLevel = parseLevel(body["minLevel"], "minLevel");
+  if (minLevel !== void 0) {
+    query.minLevel = minLevel;
+  }
+  const sinceTs = parseFiniteNumber(body["sinceTs"], "sinceTs");
+  if (sinceTs !== void 0) {
+    query.sinceTs = sinceTs;
+  }
+  const untilTs = parseFiniteNumber(body["untilTs"], "untilTs");
+  if (untilTs !== void 0) {
+    query.untilTs = untilTs;
+  }
+  const limit = parseFiniteNumber(body["limit"], "limit");
+  if (limit !== void 0) {
+    query.limit = limit;
+  }
+  const rawCursor = body["cursor"];
+  if (typeof rawCursor === "object" && rawCursor !== null) {
+    const cursorTs = parseFiniteNumber(rawCursor["ts"], "cursor.ts");
+    if (cursorTs !== void 0) {
+      query.cursor = { ts: cursorTs };
+    }
+  }
+  return query;
+};
+const resolveCredentials = (environment) => {
+  const accountId = environment.R2_SQL_ACCOUNT_ID ?? environment.CLOUDFLARE_ACCOUNT_ID;
+  const apiToken = environment.R2_SQL_TOKEN;
+  const bucket = environment.R2_SQL_BUCKET;
+  const missing = [];
+  if (accountId === void 0 || accountId === "") {
+    missing.push("R2_SQL_ACCOUNT_ID");
+  }
+  if (apiToken === void 0 || apiToken === "") {
+    missing.push("R2_SQL_TOKEN");
+  }
+  if (bucket === void 0 || bucket === "") {
+    missing.push("R2_SQL_BUCKET");
+  }
+  if (missing.length > 0) {
+    throw new LunoraError(
+      `log archive not configured (missing ${missing.join(", ")}). The Pipeline must write to an R2 Data Catalog (Iceberg) table, and R2_SQL_ACCOUNT_ID / R2_SQL_TOKEN / R2_SQL_BUCKET must be set — see the observability docs.`,
+      { code: LOG_ARCHIVE_NOT_CONFIGURED, status: 400 }
+    );
+  }
+  return { accountId, apiToken, bucket };
+};
+const buildLogArchiveAdminRoutes = (deps) => {
+  const { createReader = createPipelineLogReader, readJsonBody, requireAdminOption } = deps;
+  const handleLogArchive = async (request, env) => {
+    if (request.method !== "POST") {
+      throw new LunoraError("Log-archive endpoint requires POST", { code: "METHOD_NOT_ALLOWED", status: 405 });
+    }
+    const config = requireAdminOption(request, deps.logArchive, {
+      code: LOG_ARCHIVE_NOT_CONFIGURED,
+      message: "log archive requires a `logArchive` config (an R2 Data Catalog table) on the worker — see the observability docs"
+    });
+    const { accountId, apiToken, bucket } = resolveCredentials(env ?? {});
+    const query = parseQuery(await readJsonBody(request));
+    const client = createR2Sql({ accountId, apiToken, bucket });
+    const reader = createReader(client, { columnMap: config.columnMap, namespace: config.namespace, table: config.table });
+    const page = await reader.query(query);
+    return Response.json(page, { headers: { "content-type": "application/json" }, status: 200 });
+  };
+  return { [LOG_ARCHIVE_PATH]: handleLogArchive };
+};
+
+export { LOG_ARCHIVE_NOT_CONFIGURED, LOG_ARCHIVE_PATH, buildLogArchiveAdminRoutes };

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/dist/packem_shared/{composeWorker-CqUlK17X.mjs → composeWorker-DHyRiFho.mjs}

@@ -4,6 +4,7 @@ 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';
+import { buildLogArchiveAdminRoutes } from './LOG_ARCHIVE_PATH-iKUShT0P.mjs';
 import { emitRpcEvent } from './emitLogEvent-pEdtqAK8.mjs';
 import { resolveShard, applyJurisdiction } from './applyJurisdiction-BkZtTkct.mjs';
 import { resolveSecurity, handleCorsPreflight, enforceOrigin, decorateResponse, enforceWebSocketOrigin } from './decorateResponse-DRWQFNhF.mjs';
@@ -2569,6 +2570,11 @@ const createWorker = (options) => {
     readJsonBody: readJsonBodyWithLimit,
     requireAdminOption
   });
+  const logArchiveAdminRoutes = buildLogArchiveAdminRoutes({
+    logArchive: options.logArchive,
+    readJsonBody: readJsonBodyWithLimit,
+    requireAdminOption
+  });
   const introspectionAdminRoutes = buildIntrospectionAdminRoutes({
     assertAdmin: assertAdminAuthorized,
     options: {
@@ -3208,6 +3214,7 @@ const createWorker = (options) => {
     ...storageAdminRoutes,
     ...vectorAdminRoutes,
     ...kvAdminRoutes,
+    ...logArchiveAdminRoutes,
     ...introspectionAdminRoutes,
     // `/_lunora/admin/auth/*` — the whole user-management plane, one route per
     // `AuthAdmin` op, dispatched by the descriptor table in `./auth-admin-routes`.

package/dist/packem_shared/pipeline-log-reader-BXULGNC3.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 as D, LOG_LEVEL_ORDER as L, DEFAULT_LOG_LIMIT as a, createPipelineLogReader as c };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lunora/runtime",
-  "version": "1.0.0-alpha.30",
+  "version": "1.0.0-alpha.32",
   "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": {