okengine 0.11.2 → 0.13.0

package/src/runs/parquet.test.ts

@@ -0,0 +1,110 @@
+/**
+ * Parquet partition types must stay stable across flushes.
+ *
+ * `read_json_auto` infers all-null `error_code` as JSON and a later
+ * `"Unauthorized"` as VARCHAR — Console `listRuns` then 500s.
+ */
+
+import { afterEach, describe, expect, test } from "bun:test";
+import { mkdtemp, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+import { duckPath, openDuckDB } from "./duckdb.ts";
+import { createRunsRuntime } from "./runtime.ts";
+import { readParquet, wideEventToRow, writeParquet, type ParquetRow } from "./parquet.ts";
+import type { WideEvent } from "./types.ts";
+
+const temps: string[] = [];
+
+afterEach(async () => {
+  for (const t of temps.splice(0)) {
+    await rm(t, { recursive: true, force: true }).catch(() => undefined);
+  }
+});
+
+async function tmpDir(): Promise<string> {
+  const d = await mkdtemp(join(tmpdir(), "oke-pq-test-"));
+  temps.push(d);
+  return d;
+}
+
+function sample(id: string, errorCode: string | null): WideEvent {
+  return {
+    id,
+    flow: "console.session.login",
+    trigger: "http",
+    plane: "operator",
+    gates: [],
+    cache: "none",
+    effects: [],
+    logs: [],
+    error: errorCode === null ? null : { code: errorCode },
+    durationMs: 10,
+    startedAt: Date.now(),
+    endedAt: Date.now() + 10,
+    dimensions: { flow: "console.session.login", error_code: errorCode },
+  };
+}
+
+/** Old writer — `read_json_auto` with no type pin (existing on-disk partitions). */
+async function writeLegacyParquet(path: string, rows: readonly ParquetRow[]): Promise<void> {
+  const jsonl = `${path}.jsonl`;
+  await Bun.write(jsonl, rows.map((r) => JSON.stringify(r)).join("\n"));
+  const session = await openDuckDB();
+  try {
+    await session.conn.run(
+      `COPY (SELECT * FROM read_json_auto('${duckPath(jsonl)}')) TO '${duckPath(path)}' (FORMAT PARQUET, COMPRESSION ZSTD)`,
+    );
+  } finally {
+    session.close();
+    await rm(jsonl, { force: true }).catch(() => undefined);
+  }
+}
+
+describe("parquet error_code types", () => {
+  test("readParquet unions all-null JSON error_code with VARCHAR Unauthorized", async () => {
+    const dir = await tmpDir();
+    const okPath = join(dir, "ok.parquet");
+    const failPath = join(dir, "fail.parquet");
+    await writeLegacyParquet(okPath, [wideEventToRow(sample("ok", null))]);
+    await writeLegacyParquet(failPath, [wideEventToRow(sample("fail", "Unauthorized"))]);
+
+    const rows = await readParquet([okPath, failPath]);
+    const byId = new Map(rows.map((r) => [String(r.id), r]));
+    expect(byId.get("ok")?.error_code ?? null).toBeNull();
+    expect(byId.get("fail")?.error_code).toBe("Unauthorized");
+  });
+
+  test("writeParquet pins error_code so a later Unauthorized flush still reads", async () => {
+    const dir = await tmpDir();
+    const okPath = join(dir, "ok.parquet");
+    const failPath = join(dir, "fail.parquet");
+    await writeParquet(okPath, [wideEventToRow(sample("ok", null))]);
+    await writeParquet(failPath, [wideEventToRow(sample("fail", "Unauthorized"))]);
+
+    const rows = await readParquet([okPath, failPath]);
+    expect(rows.map((r) => String(r.id)).sort()).toEqual(["fail", "ok"]);
+  });
+
+  test("files driver lists runs after a success flush then an Unauthorized flush", async () => {
+    const root = await tmpDir();
+    const runs = createRunsRuntime({ driver: "files", localRoot: root });
+    await runs.open();
+    await runs.append(sample("ok", null));
+    await runs.flush();
+    await runs.append(sample("fail", "Unauthorized"));
+    await runs.flush();
+
+    const all = await runs.all();
+    expect(all.map((e) => e.id).sort()).toEqual(["fail", "ok"]);
+    expect(all.find((e) => e.id === "fail")?.error?.code).toBe("Unauthorized");
+    expect(all.find((e) => e.id === "ok")?.error).toBeNull();
+
+    const rows = await runs.query("SELECT id, error_code FROM runs ORDER BY id");
+    expect(rows.map((r) => String(r.id))).toEqual(["fail", "ok"]);
+    expect(rows[0]?.error_code).toBe("Unauthorized");
+    expect(rows[1]?.error_code ?? null).toBeNull();
+    await runs.close();
+  });
+});

package/src/runs/parquet.ts

@@ -8,9 +8,51 @@
 import { mkdir, unlink, writeFile } from "node:fs/promises";
 import { dirname, join } from "node:path";
 
-import { duckPath, duckQuery, openDuckDB } from "./duckdb.ts";
+import { duckIdent, duckPath, duckQuery, openDuckDB, type DuckSession } from "./duckdb.ts";
 import type { WideEvent } from "./types.ts";
 
+/**
+ * Columns that must stay VARCHAR across partitions.
+ *
+ * `read_json_auto` infers all-null batches as JSON; a later file with
+ * `"Unauthorized"` is VARCHAR. DuckDB then fails the union.
+ */
+const PARQUET_VARCHAR_COLUMNS = [
+  "id",
+  "parent_id",
+  "flow",
+  "unit",
+  "trigger",
+  "plane",
+  "tenant",
+  "principal",
+  "subject_id",
+  "gates",
+  "cache",
+  "replica",
+  "build_version",
+  "error_code",
+  "error_message",
+  "input",
+  "output",
+  "effects",
+  "logs",
+  "archived",
+  "dimensions",
+] as const;
+
+/** Numeric wide-event columns — all-null batches must not become JSON. */
+const PARQUET_DOUBLE_COLUMNS = [
+  "replica_lag_ms",
+  "cost",
+  "input_tokens",
+  "output_tokens",
+  "prompt_version",
+  "duration_ms",
+  "started_at",
+  "ended_at",
+] as const;
+
 /** Flattened Parquet / SQL row. */
 export type ParquetRow = Record<string, string | number | boolean | null>;
 
@@ -38,11 +80,14 @@ export function wideEventToRow(event: WideEvent): ParquetRow {
     replica: event.replica ?? null,
     replica_lag_ms: event.replicaLagMs ?? null,
     cost: event.cost ?? null,
+    input_tokens: event.inputTokens ?? null,
+    output_tokens: event.outputTokens ?? null,
     prompt_version: event.promptVersion ?? null,
     build_version: event.buildVersion ?? null,
     error_code: event.error?.code ?? null,
     error_message: event.error?.message ?? null,
     input: event.input === undefined ? null : JSON.stringify(event.input),
+    output: event.output === undefined ? null : JSON.stringify(event.output),
     effects: JSON.stringify(event.effects),
     logs: JSON.stringify(event.logs),
     duration_ms: event.durationMs,
@@ -54,7 +99,7 @@ export function wideEventToRow(event: WideEvent): ParquetRow {
   for (const [k, v] of Object.entries(event.dimensions)) {
     const col = `dim_${k}`;
     if (row[col] !== undefined) continue;
-    if (v === undefined) continue;
+    if (v === undefined || v === null) continue;
     row[col] =
       typeof v === "string" || typeof v === "number" || typeof v === "boolean"
         ? v
@@ -95,6 +140,8 @@ export function rowToWideEvent(row: Record<string, unknown>): WideEvent {
     ...(row.replica != null ? { replica: row.replica as "primary" | "replica" } : {}),
     ...(row.replica_lag_ms != null ? { replicaLagMs: Number(row.replica_lag_ms) } : {}),
     ...(row.cost != null ? { cost: Number(row.cost) } : {}),
+    ...(row.input_tokens != null ? { inputTokens: Number(row.input_tokens) } : {}),
+    ...(row.output_tokens != null ? { outputTokens: Number(row.output_tokens) } : {}),
     ...(row.prompt_version != null ? { promptVersion: Number(row.prompt_version) } : {}),
     ...(row.build_version != null ? { buildVersion: String(row.build_version) } : {}),
     error:
@@ -112,6 +159,14 @@ export function rowToWideEvent(row: Record<string, unknown>): WideEvent {
               : (row.input as unknown),
         }
       : {}),
+    ...(row.output != null && row.output !== ""
+      ? {
+          output:
+            typeof row.output === "string"
+              ? (JSON.parse(row.output) as unknown)
+              : (row.output as unknown),
+        }
+      : {}),
     effects: parseJsonArray(row.effects) as WideEvent["effects"],
     logs: parseJsonArray(row.logs) as WideEvent["logs"],
     durationMs: Number(row.duration_ms ?? 0),
@@ -135,8 +190,9 @@ export async function writeParquet(path: string, rows: readonly ParquetRow[]): P
   await writeFile(jsonl, rows.map((r) => JSON.stringify(r)).join("\n"));
   const session = await openDuckDB();
   try {
+    const replace = parquetWriteReplaceSql();
     await session.conn.run(
-      `COPY (SELECT * FROM read_json_auto('${duckPath(jsonl)}')) TO '${duckPath(path)}' (FORMAT PARQUET, COMPRESSION ZSTD)`,
+      `COPY (SELECT * REPLACE (${replace}) FROM read_json_auto('${duckPath(jsonl)}')) TO '${duckPath(path)}' (FORMAT PARQUET, COMPRESSION ZSTD)`,
     );
   } finally {
     session.close();
@@ -144,6 +200,28 @@ export async function writeParquet(path: string, rows: readonly ParquetRow[]): P
   }
 }
 
+/**
+ * SQL that reads one or more Parquet files as one relation.
+ *
+ * Per-file JSON columns (all-null `read_json_auto` inference) are cast
+ * before `UNION ALL BY NAME` so VARCHAR `"Unauthorized"` and JSON null
+ * can sit in the same `error_code` column.
+ *
+ * @param conn - Open DuckDB connection
+ * @param paths - Absolute Parquet paths
+ */
+export async function parquetUnionSql(
+  conn: DuckSession["conn"],
+  paths: readonly string[],
+): Promise<string> {
+  if (paths.length === 0) return "SELECT * FROM (SELECT 1 WHERE FALSE)";
+  const selects: string[] = [];
+  for (const path of paths) {
+    selects.push(await parquetFileSelectSql(conn, path));
+  }
+  return selects.length === 1 ? selects[0]! : selects.join(" UNION ALL BY NAME ");
+}
+
 /**
  * Read all rows from one or more Parquet files.
  *
@@ -153,11 +231,8 @@ export async function readParquet(paths: readonly string[]): Promise<ParquetRow[
   if (paths.length === 0) return [];
   const session = await openDuckDB();
   try {
-    const list = paths.map((p) => `'${duckPath(p)}'`).join(", ");
-    const rows = await duckQuery(
-      session.conn,
-      `SELECT * FROM read_parquet([${list}], union_by_name = true)`,
-    );
+    const sql = await parquetUnionSql(session.conn, paths);
+    const rows = await duckQuery(session.conn, sql);
     return rows as ParquetRow[];
   } finally {
     session.close();
@@ -187,6 +262,52 @@ export function partitionObjectKey(day: string, id: string): string {
   return join("runs", `day=${day}`, `${id}.parquet`);
 }
 
+function parquetWriteReplaceSql(): string {
+  const varchar = PARQUET_VARCHAR_COLUMNS.map(
+    (col) => `CAST(${duckIdent(col)} AS VARCHAR) AS ${duckIdent(col)}`,
+  );
+  const doubles = PARQUET_DOUBLE_COLUMNS.map(
+    (col) => `CAST(${duckIdent(col)} AS DOUBLE) AS ${duckIdent(col)}`,
+  );
+  return [...varchar, ...doubles].join(", ");
+}
+
+async function parquetFileSelectSql(conn: DuckSession["conn"], path: string): Promise<string> {
+  const from = `read_parquet('${duckPath(path)}')`;
+  const described = await duckQuery(conn, `DESCRIBE SELECT * FROM ${from}`);
+  const replacements: string[] = [];
+  for (const row of described) {
+    const name = columnNameOf(row);
+    if (name === undefined) continue;
+    const type = columnTypeOf(row);
+    if (type === undefined) continue;
+    const ident = duckIdent(name);
+    if ((PARQUET_VARCHAR_COLUMNS as readonly string[]).includes(name)) {
+      replacements.push(`CAST(${ident} AS VARCHAR) AS ${ident}`);
+      continue;
+    }
+    if ((PARQUET_DOUBLE_COLUMNS as readonly string[]).includes(name)) {
+      replacements.push(`CAST(${ident} AS DOUBLE) AS ${ident}`);
+      continue;
+    }
+    if (type.toUpperCase() === "JSON") {
+      replacements.push(`CAST(${ident} AS VARCHAR) AS ${ident}`);
+    }
+  }
+  if (replacements.length === 0) return `SELECT * FROM ${from}`;
+  return `SELECT * REPLACE (${replacements.join(", ")}) FROM ${from}`;
+}
+
+function columnNameOf(row: Record<string, unknown>): string | undefined {
+  const name = row.column_name ?? row.Column;
+  return typeof name === "string" && name.length > 0 ? name : undefined;
+}
+
+function columnTypeOf(row: Record<string, unknown>): string | undefined {
+  const type = row.column_type ?? row.Type;
+  return typeof type === "string" && type.length > 0 ? type : undefined;
+}
+
 function parseJsonArray(value: unknown): unknown[] {
   if (Array.isArray(value)) return value;
   if (typeof value === "string" && value.length > 0) {

package/src/runs/retention.test.ts

@@ -0,0 +1,24 @@
+/**
+ * Retention helpers — keep window vs partition day keys.
+ */
+
+import { describe, expect, test } from "bun:test";
+import { partitionDayFromKey, retentionKeepMs, shouldDropPartition } from "./retention.ts";
+
+describe("runs retention helpers", () => {
+  test("retentionKeepMs parses durations and forever", () => {
+    expect(retentionKeepMs("forever")).toBeNull();
+    expect(retentionKeepMs(undefined)).toBeNull();
+    expect(retentionKeepMs("7d")).toBe(7 * 86_400_000);
+    expect(retentionKeepMs("30d")).toBe(30 * 86_400_000);
+    expect(retentionKeepMs("nope")).toBeNull();
+  });
+
+  test("shouldDropPartition uses day= in the object key", () => {
+    const now = Date.parse("2026-08-16T12:00:00.000Z");
+    const keep = 7 * 86_400_000;
+    expect(shouldDropPartition("runs/day=2026-08-01/a.parquet", now, keep)).toBe(true);
+    expect(shouldDropPartition("runs/day=2026-08-15/a.parquet", now, keep)).toBe(false);
+    expect(partitionDayFromKey("runs/day=2026-08-15/x.parquet")).toBe("2026-08-15");
+  });
+});

package/src/runs/retention.ts

@@ -0,0 +1,42 @@
+/**
+ * Runs Parquet retention — delete partitions older than `keep`.
+ */
+
+import { parseDurationMs } from "../elements/clock/duration.ts";
+
+/**
+ * Parse {@link import("./types.ts").RunsRetention.keep} into milliseconds.
+ * `"forever"` / unset / unparseable → `null` (no deletion).
+ *
+ * @param keep - Duration or `"forever"`
+ */
+export function retentionKeepMs(keep: string | undefined): number | null {
+  if (keep === undefined || keep === "forever") return null;
+  const ms = parseDurationMs(keep);
+  return ms > 0 ? ms : null;
+}
+
+/**
+ * Extract the UTC partition day from a runs object key.
+ *
+ * @param key - Object key (`runs/day=YYYY-MM-DD/…`)
+ */
+export function partitionDayFromKey(key: string): string | undefined {
+  const match = /day=(\d{4}-\d{2}-\d{2})/.exec(key);
+  return match?.[1];
+}
+
+/**
+ * Whether a Parquet partition is older than the keep window.
+ *
+ * @param key - Object key
+ * @param now - Epoch-ms
+ * @param keepMs - Keep window
+ */
+export function shouldDropPartition(key: string, now: number, keepMs: number): boolean {
+  const day = partitionDayFromKey(key);
+  if (!day) return false;
+  const start = Date.parse(`${day}T00:00:00.000Z`);
+  if (!Number.isFinite(start)) return false;
+  return now - start > keepMs;
+}

package/src/runs/runs.test.ts

@@ -29,6 +29,7 @@ import {
   revealArchived,
   seedOutlierDataset,
   subjectKeyName,
+  type WideEvent,
 } from "./index.ts";
 
 const temps: string[] = [];
@@ -61,6 +62,7 @@ describe("zero-instrumentation dimensions", () => {
       http.get("/book").gate(member),
       flow("bookings.create", {
         plane: "user",
+        cache: false,
         effects: { reads: ["sql:bookings"] },
         do: async (_input, fx) => {
           fx.log.info("booking started", { step: 1 });
@@ -104,6 +106,7 @@ describe("zero-instrumentation dimensions", () => {
     expect(e.dimensions.flow).toBe("bookings.create");
     expect(e.dimensions.tenant).toBe("org_a41");
     expect(e.dimensions.cache).toBe("hit");
+    expect(e.output).toEqual({ ok: true });
 
     await runs.close();
   });
@@ -269,6 +272,104 @@ describe("crypto-shredding erasure", () => {
   });
 });
 
+describe("files persistence — reopen + retention", () => {
+  function sample(id: string, startedAt: number): WideEvent {
+    return {
+      id,
+      flow: "ping",
+      trigger: "http",
+      plane: "user",
+      gates: [],
+      cache: "none",
+      effects: [],
+      logs: [],
+      error: null,
+      durationMs: 4,
+      startedAt,
+      endedAt: startedAt + 4,
+      dimensions: { flow: "ping" },
+    };
+  }
+
+  test("reopen the same localRoot sees prior Parquet (not just in-process catalog)", async () => {
+    const root = await tmpDir();
+    const first = createRunsRuntime({ driver: "files", localRoot: root });
+    await first.open();
+    await first.append(sample("keep-me", Date.now()));
+    await first.flush();
+    await first.close();
+
+    const second = createRunsRuntime({ driver: "files", localRoot: root });
+    await second.open();
+    const rows = await second.query("SELECT id FROM runs");
+    expect(rows.map((r) => String(r.id))).toEqual(["keep-me"]);
+    const all = await second.all();
+    expect(all.map((e) => e.id)).toEqual(["keep-me"]);
+    await second.close();
+  });
+
+  test("all() includes older Parquet after a new write in the same process", async () => {
+    const root = await tmpDir();
+    const first = createRunsRuntime({ driver: "files", localRoot: root });
+    await first.open();
+    await first.append(sample("old", Date.now() - 1000));
+    await first.flush();
+    await first.close();
+
+    const second = createRunsRuntime({ driver: "files", localRoot: root });
+    await second.open();
+    await second.append(sample("new", Date.now()));
+    await second.flush();
+    const ids = (await second.all()).map((e) => e.id).sort();
+    expect(ids).toEqual(["new", "old"]);
+    await second.close();
+  });
+
+  test("retention.keep deletes partitions older than the window", async () => {
+    const root = await tmpDir();
+    const now = Date.parse("2026-08-16T12:00:00.000Z");
+    const runs = createRunsRuntime({
+      driver: "files",
+      localRoot: root,
+      retention: { keep: "7d" },
+      now: () => now,
+    });
+    await runs.open();
+    await runs.append(sample("stale", Date.parse("2026-08-01T12:00:00.000Z")));
+    await runs.append(sample("fresh", Date.parse("2026-08-15T12:00:00.000Z")));
+    await runs.flush();
+    const ids = (await runs.all()).map((e) => e.id);
+    expect(ids).toEqual(["fresh"]);
+    await runs.close();
+  });
+});
+
+describe("memory driver — lazy DuckDB", () => {
+  test("all() works without opening DuckDB; query() still works", async () => {
+    const runs = createRunsRuntime({ driver: "memory" });
+    await runs.open();
+    await runs.append({
+      id: "m1",
+      flow: "x",
+      trigger: "internal",
+      plane: "user",
+      gates: [],
+      cache: "none",
+      effects: [],
+      logs: [],
+      error: null,
+      durationMs: 1,
+      startedAt: 1,
+      endedAt: 2,
+      dimensions: { flow: "x" },
+    });
+    expect((await runs.all()).map((e) => e.id)).toEqual(["m1"]);
+    const rows = await runs.query("SELECT id FROM runs");
+    expect(rows.map((r) => String(r.id))).toEqual(["m1"]);
+    await runs.close();
+  });
+});
+
 describe("optional drivers", () => {
   test("postgres driver appends and queries", async () => {
     const runs = createRunsRuntime({ driver: "postgres" });

package/src/runs/runtime.ts

@@ -13,6 +13,7 @@ import type {
   RunsDriver,
   RunsDriverId,
   RunsOpenOptions,
+  RunsQueryOptions,
   RunsRow,
   RunsStore,
   WideEvent,
@@ -60,7 +61,7 @@ export interface RunsRuntime {
    *
    * @param sql - SQL (`FROM runs` for files/memory)
    */
-  query(sql: string): Promise<RunsRow[]>;
+  query(sql: string, options?: RunsQueryOptions): Promise<RunsRow[]>;
   /** All events (small stores / tests). */
   all(): Promise<WideEvent[]>;
   /**
@@ -158,6 +159,7 @@ export function createRunsRuntime(options: CreateRunsRuntimeOptions = {}): RunsR
         ...(archived !== undefined ? { archived } : {}),
       });
       await s.append(event);
+      await s.flush();
       return event;
     },
     async append(event) {
@@ -168,9 +170,9 @@ export function createRunsRuntime(options: CreateRunsRuntimeOptions = {}): RunsR
       const s = await ensureStore();
       await s.flush();
     },
-    async query(sql) {
+    async query(sql, options) {
       const s = await ensureStore();
-      return s.query(sql);
+      return s.query(sql, options);
     },
     async all() {
       const s = await ensureStore();

package/src/runs/types.ts

@@ -63,6 +63,10 @@ export interface WideEvent {
   readonly replicaLagMs?: number;
   /** AI cost accrued during the run. */
   readonly cost?: number;
+  /** Driver-reported input tokens when `fx.ask` supplied them. */
+  readonly inputTokens?: number;
+  /** Driver-reported output tokens when `fx.ask` supplied them. */
+  readonly outputTokens?: number;
   /** Prompt version when `fx.ask` was used. */
   readonly promptVersion?: number;
   /** Build / release version when known. */
@@ -74,13 +78,18 @@ export interface WideEvent {
    * Declared personal fields may be crypto-shredded into {@link archived}.
    */
   readonly input?: unknown;
+  /**
+   * Flow return value snapshot when the run completed successfully.
+   * Absent on failures / in-flight sleeps — never invent a response.
+   */
+  readonly output?: unknown;
   /** Effect ledger snapshot. */
   readonly effects: readonly EffectEntry[];
   /**
    * `fx.log` lines — a field on the run, not a parallel stream.
    */
   readonly logs: readonly RunLogLine[];
-  /** Wall duration in milliseconds. */
+  /** Handler duration in milliseconds (high-res; may be fractional). */
   readonly durationMs: number;
   /** Epoch-ms start. */
   readonly startedAt: number;
@@ -98,11 +107,15 @@ export interface WideEvent {
   readonly dimensions: RunDimensions;
 }
 
+/** Default on-disk root for the `files` runs driver (gitignored under `.oke/`). */
+export const DEFAULT_RUNS_LOCAL_ROOT = ".oke/runs";
+
 /** Retention / redaction policy (lifecycle — not locality). */
 export interface RunsRetention {
   /**
-   * Keep operational runs for this duration, or `"forever"` (default).
-   * Deletion is a compliance action, not a cleanup job.
+   * Keep operational Parquet partitions for this duration, or `"forever"`.
+   * Driver default is `"forever"`; `bindRuns` applies `7d` (`dev`) / `30d`
+   * (`prod`) when the app does not set `runs.keep`.
    */
   readonly keep?: string | "forever";
   /** Redact personal fields older than these durations. */
@@ -112,6 +125,19 @@ export interface RunsRetention {
 /** One SQL result row. */
 export type RunsRow = Record<string, unknown>;
 
+/**
+ * Optional execution controls for {@link RunsStore.query}.
+ * Console uses `sandbox` + timeout; Flow `fx.runs.query` omits them.
+ */
+export interface RunsQueryOptions {
+  /** Disable DuckDB filesystem / extension access for the user statement. */
+  readonly sandbox?: boolean;
+  /** Wall-clock timeout in milliseconds. */
+  readonly timeoutMs?: number;
+  /** Slice the result after execute (hard ceiling). */
+  readonly maxRows?: number;
+}
+
 /** Runs store handle — append wide events and query them. */
 export interface RunsStore {
   /** Protocol driver id. */
@@ -130,8 +156,9 @@ export interface RunsStore {
    * Run SQL against all visible partitions (local + object storage).
    *
    * @param sql - DuckDB / driver SQL
+   * @param options - Optional sandbox / timeout / row ceiling
    */
-  query(sql: string): Promise<RunsRow[]>;
+  query(sql: string, options?: RunsQueryOptions): Promise<RunsRow[]>;
   /**
    * Materialise all events (test helper / small stores).
    */
@@ -170,6 +197,8 @@ export interface RunsOpenOptions {
   readonly hotWindowMs?: number;
   /** Retention policy (compliance). */
   readonly retention?: RunsRetention;
+  /** Clock for retention / locality (tests). Default `Date.now`. */
+  readonly now?: () => number;
   /** Postgres connection URL or injected client. */
   readonly url?: string;
   /** Injected client for postgres / clickhouse fakes. */