threadwire 0.1.21 → 0.1.22

package/src/evidence-index.js

@@ -0,0 +1,664 @@
+// @ts-check
+
+import {createHash} from "node:crypto"
+import {lstatSync} from "node:fs"
+import {chmod, lstat, rename, unlink} from "node:fs/promises"
+import {DatabaseSync} from "node:sqlite"
+import {redactText} from "./redaction.js"
+
+const INDEX_VERSION = 1
+const INDEX_SUFFIX = ".index"
+const PENDING_INDEX_SUFFIX = ".index.pending"
+
+const MAX_SUMMARY_LENGTH = 1_024
+const MAX_METADATA_BYTES = 4_096
+const MAX_PROVIDER_LENGTH = 64
+const MAX_RUN_ID_LENGTH = 256
+const MAX_DESTINATION_ID_LENGTH = 256
+const MAX_ARTIFACT_ID_LENGTH = 64
+
+const ALLOWED_EVENT_KINDS = new Set([
+  "prompt", "provider_stdout", "provider_stderr", "assistant", "tool",
+  "lifecycle", "diagnostic", "context_metrics", "provider_result"
+])
+
+const ALLOWED_TERMINAL_STATES = new Set(["completed", "failed"])
+
+// SQLite pages are typically 4 KiB; reserve a small allowance per event write
+// and settle against the real file size so growth is bounded and accounted.
+const INDEX_EVENT_ALLOWANCE_BYTES = 8 * 1024
+
+/** @param {string} runId */
+export function runHash(runId) {
+  return createHash("sha256").update(runId, "utf8").digest("base64url")
+}
+
+/** @param {string} name */
+export function isReadyIndexName(name) {
+  return /^[A-Za-z0-9_-]{43}\.index$/u.test(name)
+}
+
+/** @param {string} name */
+export function isPendingIndexName(name) {
+  return /^[A-Za-z0-9_-]{43}\.index\.pending$/u.test(name)
+}
+
+/** @param {string} name */
+export function isIndexJournalName(name) {
+  return /^[A-Za-z0-9_-]{43}\.index-journal$/u.test(name)
+    || /^[A-Za-z0-9_-]{43}\.index\.pending-journal$/u.test(name)
+}
+
+/** @param {string} name @returns {string | undefined} */
+export function readyIndexRunHash(name) {
+  const match = /^([A-Za-z0-9_-]{43})\.index$/u.exec(name)
+  return match?.[1]
+}
+
+export class EvidenceIndexError extends Error {
+  /** @param {string} message */
+  constructor(message) {
+    super(message)
+    this.name = "EvidenceIndexError"
+  }
+}
+
+/**
+ * Per-run SQLite evidence index. Created in a pending state, finalized by
+ * rename. Uses DELETE journal mode so SQLite transient sidecars are removed
+ * on commit/close and can be cleaned during reconciliation if they survive
+ * a crash.
+ */
+export class RunIndex {
+  /** @type {import("./evidence-store.js").EvidenceStore} */
+  #store
+  /** @type {object} */
+  #owner
+  /** @type {string | null} */
+  #provider
+  /** @type {string} */
+  #pendingPath
+  /** @type {string} */
+  #readyPath
+  /** @type {DatabaseSync | null} */
+  #db = null
+  /** @type {boolean} */
+  #finalized = false
+  /** @type {boolean} */
+  #closed = false
+  /** @type {number} */
+  #eventOrder = 0
+  /** @type {number} */
+  #createdAt
+  /** @type {number} */
+  #expiresAt
+  /** @type {string} */
+  #runId
+  /** @type {number} */
+  #reservedBytes
+  /** @type {string[] | undefined} */
+  #redactions
+  /** @type {{chmod: typeof chmod, stat: typeof lstat}} */
+  #fileSystem
+
+  /**
+   * @param {import("./evidence-store.js").EvidenceStore} store
+   * @param {object} owner
+   * @param {{provider?: string, createdAt?: number, expiresAt?: number, fileSystem?: {chmod: typeof chmod, stat: typeof lstat}}} [options]
+   * @param {number} [initialReservedBytes]
+   */
+  constructor(store, owner, options = {}, initialReservedBytes = 0) {
+    this.#store = store
+    this.#owner = owner
+    this.#provider = boundString(options.provider, MAX_PROVIDER_LENGTH) ?? null
+    this.#createdAt = options.createdAt ?? store.clock()
+    this.#expiresAt = options.expiresAt ?? this.#createdAt + store.limits.retentionMs
+    this.#runId = /** @type {{runId: string}} */ (owner).runId
+    this.#reservedBytes = initialReservedBytes
+    this.#fileSystem = options.fileSystem ?? {chmod, stat: lstat}
+    const hash = runHash(this.#runId)
+    this.#pendingPath = store.path(hash, PENDING_INDEX_SUFFIX)
+    this.#readyPath = store.path(hash, INDEX_SUFFIX)
+  }
+
+  get owner() {
+    return this.#owner
+  }
+
+  get provider() {
+    return this.#provider
+  }
+
+  set provider(value) {
+    if (this.#finalized || this.#closed) throw new EvidenceIndexError("Run index is already settled")
+    this.#provider = boundString(value, MAX_PROVIDER_LENGTH)
+  }
+
+  /** @param {string[]} redactions */
+  setRedactions(redactions) {
+    if (this.#finalized || this.#closed) throw new EvidenceIndexError("Run index is already settled")
+    if (!Array.isArray(redactions) || redactions.some((value) => typeof value !== "string")) {
+      throw new EvidenceIndexError("Invalid evidence redactions")
+    }
+    this.#redactions = redactions
+  }
+
+  get pendingPath() {
+    return this.#pendingPath
+  }
+
+  get readyPath() {
+    return this.#readyPath
+  }
+
+  get finalized() {
+    return this.#finalized
+  }
+
+  #accountSize() {
+    const stats = lstatSync(this.#pendingPath)
+    const delta = stats.size - this.#reservedBytes
+    if (delta !== 0) {
+      this.#store.reserve(this.#runId, delta, 0)
+      this.#reservedBytes += delta
+    }
+  }
+
+  /**
+   * @param {Record<string, unknown> | undefined} metadata
+   * @returns {Record<string, unknown> | undefined}
+   */
+  #redactMetadata(metadata) {
+    const redactions = this.#redactions
+    if (metadata === undefined || redactions === undefined || redactions.length === 0) return metadata
+    /** @type {(value: unknown) => unknown} */
+    const walk = (value) => {
+      if (typeof value === "string") return redactText(value, redactions).text
+      if (Array.isArray(value)) return value.map(walk)
+      if (value !== null && typeof value === "object" && Object.getPrototypeOf(value) === Object.prototype) {
+        return Object.fromEntries(Object.entries(value).map(([key, entry]) => [key, walk(entry)]))
+      }
+      return value
+    }
+    return /** @type {Record<string, unknown>} */ (walk(metadata))
+  }
+
+  /** @param {EvidenceIndexEvent} event */
+  async recordEvent(event) {
+    if (this.#finalized || this.#closed) throw new EvidenceIndexError("Run index is already settled")
+    const validated = validateEvent(event)
+    const timestamp = event.timestamp ?? this.#store.clock()
+    const artifactId = boundString(event.artifactId, MAX_ARTIFACT_ID_LENGTH)
+    const summary = boundString(
+      this.#redactions === undefined || validated.summary === undefined
+        ? validated.summary
+        : redactText(validated.summary, this.#redactions).text,
+      MAX_SUMMARY_LENGTH
+    )
+    const redactedMetadata = this.#redactMetadata(validated.metadata)
+    const metadata = redactedMetadata === undefined ? null : JSON.stringify(redactedMetadata)
+    if (metadata !== null && Buffer.byteLength(metadata, "utf8") > MAX_METADATA_BYTES) {
+      throw new EvidenceIndexError("Event metadata exceeds the bounded index limit")
+    }
+    this.#open()
+    this.#store.reserve(this.#runId, INDEX_EVENT_ALLOWANCE_BYTES, 0)
+    try {
+      const db = /** @type {import("node:sqlite").DatabaseSync} */ (this.#db)
+      const order = this.#eventOrder + 1
+      this.#eventOrder = order
+      const insert = db.prepare("INSERT INTO events (kind, timestamp, order_index, artifact_id, summary, metadata) VALUES (?, ?, ?, ?, ?, ?)")
+      insert.run(validated.kind, timestamp, order, artifactId, summary, metadata)
+      this.#accountSize()
+    } catch (error) {
+      this.#store.reserve(this.#runId, -INDEX_EVENT_ALLOWANCE_BYTES, 0)
+      await this.abort().catch(() => {})
+      throw error
+    }
+    this.#store.reserve(this.#runId, -INDEX_EVENT_ALLOWANCE_BYTES, 0)
+  }
+
+  /** @param {{state: "completed" | "failed", exitCode: number}} terminal */
+  async finalize(terminal) {
+    if (this.#finalized || this.#closed) throw new EvidenceIndexError("Run index is already settled")
+    if (!ALLOWED_TERMINAL_STATES.has(terminal.state) || !Number.isSafeInteger(terminal.exitCode) || terminal.exitCode < 0) {
+      throw new EvidenceIndexError("Invalid terminal run state")
+    }
+    this.#open()
+    this.#store.reserve(this.#runId, INDEX_EVENT_ALLOWANCE_BYTES, 0)
+    try {
+      const db = /** @type {import("node:sqlite").DatabaseSync} */ (this.#db)
+      const update = db.prepare("UPDATE manifest SET terminal_state = ?, terminal_exit_code = ?, finalized_at = ? WHERE version = ?")
+      update.run(terminal.state, terminal.exitCode, this.#store.clock(), INDEX_VERSION)
+      this.#accountSize()
+      db.close()
+      this.#closed = true
+    } catch (error) {
+      this.#store.reserve(this.#runId, -INDEX_EVENT_ALLOWANCE_BYTES, 0)
+      await this.abort().catch(() => {})
+      throw error
+    }
+    this.#store.reserve(this.#runId, -INDEX_EVENT_ALLOWANCE_BYTES, 0)
+    try {
+      await this.#verifyPermissions()
+    } catch (error) {
+      await this.abort().catch(() => {})
+      throw error
+    }
+    this.#finalized = true
+    await rename(this.#pendingPath, this.#readyPath)
+  }
+
+  async abort() {
+    if (this.#finalized) return
+    this.#closeDb()
+    if (this.#reservedBytes > 0) {
+      this.#store.reserve(this.#runId, -this.#reservedBytes, 0)
+      this.#reservedBytes = 0
+    }
+    await safeUnlink(this.#pendingPath)
+  }
+
+  releaseAccounting() {
+    if (this.#reservedBytes > 0) {
+      this.#store.reserve(this.#runId, -this.#reservedBytes, 0)
+      this.#reservedBytes = 0
+    }
+  }
+
+  async remove() {
+    this.releaseAccounting()
+    this.#closeDb()
+    await safeUnlink(this.#pendingPath)
+    await safeUnlink(this.#readyPath)
+  }
+
+  #open() {
+    if (this.#db !== null) return
+    this.#db = new DatabaseSync(this.#pendingPath)
+    this.#db.exec("PRAGMA journal_mode = DELETE")
+    this.#db.exec(`
+      CREATE TABLE IF NOT EXISTS manifest (
+        version INTEGER NOT NULL,
+        run_id TEXT NOT NULL,
+        destination_id TEXT NOT NULL,
+        provider TEXT,
+        terminal_state TEXT,
+        terminal_exit_code INTEGER,
+        created_at INTEGER NOT NULL,
+        expires_at INTEGER NOT NULL,
+        finalized_at INTEGER
+      )
+    `)
+    this.#db.exec(`
+      CREATE TABLE IF NOT EXISTS events (
+        id INTEGER PRIMARY KEY AUTOINCREMENT,
+        kind TEXT NOT NULL,
+        timestamp INTEGER NOT NULL,
+        order_index INTEGER NOT NULL,
+        artifact_id TEXT,
+        summary TEXT,
+        metadata TEXT
+      )
+    `)
+    this.#db.exec("CREATE INDEX IF NOT EXISTS idx_events_kind ON events(kind)")
+    this.#db.exec("CREATE INDEX IF NOT EXISTS idx_events_order ON events(order_index)")
+    const count = /** @type {{count: number}} */ (
+      this.#db.prepare("SELECT COUNT(*) AS count FROM manifest").get()
+    )
+    if (count.count === 0) {
+      const insert = this.#db.prepare("INSERT INTO manifest (version, run_id, destination_id, provider, created_at, expires_at) VALUES (?, ?, ?, ?, ?, ?)")
+      insert.run(
+        INDEX_VERSION,
+        boundString(/** @type {{runId: string}} */ (this.#owner).runId, MAX_RUN_ID_LENGTH),
+        boundString(/** @type {{destinationId: string}} */ (this.#owner).destinationId, MAX_DESTINATION_ID_LENGTH),
+        this.#provider,
+        this.#createdAt,
+        this.#expiresAt
+      )
+    }
+    this.#accountSize()
+  }
+
+  #closeDb() {
+    if (this.#db === null) return
+    try {
+      this.#db.close()
+    } catch {
+      /* Ignore close errors during abort. */
+    }
+    this.#closed = true
+    this.#db = null
+  }
+
+  async #verifyPermissions() {
+    const {chmod: chmodFile, stat: lstatFile} = this.#fileSystem
+    await chmodFile(this.#pendingPath, 0o600)
+    const stats = await lstatFile(this.#pendingPath)
+    if ((stats.mode & 0o777) !== 0o600) {
+      throw new EvidenceIndexError("Run index permissions are not restricted to owner")
+    }
+  }
+}
+
+/**
+ * Inspect a finalized per-run index at the given ready path.
+ * @param {string} readyPath
+ * @param {EvidenceInspectRequest} request
+ * @param {{clock: () => number}} store
+ * @returns {EvidenceInspectResult}
+ */
+export function inspectIndex(readyPath, request, store) {
+  const db = new DatabaseSync(readyPath)
+  try {
+    const manifest = readManifest(db)
+    if (manifest.expiresAt <= store.clock()) {
+      throw new EvidenceAccessErrorForIndex()
+    }
+    if (request.summary) {
+      return summarize(db, manifest)
+    }
+    if (request.events) {
+      return queryEvents(db, request.events)
+    }
+    if (request.failures) {
+      return queryFailures(db, request.failures)
+    }
+    throw new EvidenceIndexError("Invalid inspect selector")
+  } finally {
+    db.close()
+  }
+}
+
+class EvidenceAccessErrorForIndex extends Error {
+  constructor() {
+    super("Evidence index is unavailable")
+    this.name = "EvidenceAccessError"
+  }
+}
+
+/** @param {import("node:sqlite").DatabaseSync} db */
+function readManifest(db) {
+  const row = /** @type {ManifestRow | undefined} */ (
+    db.prepare("SELECT * FROM manifest LIMIT 1").get()
+  )
+  if (row === undefined) throw new EvidenceAccessErrorForIndex()
+  return {
+    version: row.version,
+    runId: row.run_id,
+    destinationId: row.destination_id,
+    provider: row.provider,
+    terminalState: row.terminal_state,
+    terminalExitCode: row.terminal_exit_code,
+    createdAt: row.created_at,
+    expiresAt: row.expires_at,
+    finalizedAt: row.finalized_at
+  }
+}
+
+/**
+ * @param {import("node:sqlite").DatabaseSync} db
+ * @param {ReturnType<typeof readManifest>} _manifest
+ */
+function summarize(db, _manifest) {
+  const counts = /** @type {Array<{kind: string, count: number}>} */ (
+    db.prepare("SELECT kind, COUNT(*) AS count FROM events GROUP BY kind").all()
+  )
+  const eventCounts = Object.fromEntries(counts.map((row) => [row.kind, row.count]))
+  const total = /** @type {{total: number}} */ (
+    db.prepare("SELECT COUNT(*) AS total FROM events").get()
+  )
+  return {
+    version: 1,
+    provider: _manifest.provider,
+    terminal: _manifest.terminalState === null ? null : {state: /** @type {"completed" | "failed"} */ (_manifest.terminalState), exitCode: _manifest.terminalExitCode ?? 0},
+    createdAt: _manifest.createdAt,
+    expiresAt: _manifest.expiresAt,
+    finalizedAt: _manifest.finalizedAt,
+    totalEvents: total.total,
+    eventCounts
+  }
+}
+
+/**
+ * @param {import("node:sqlite").DatabaseSync} db
+ * @param {NonNullable<EvidenceInspectRequest["events"]>} options
+ */
+function queryEvents(db, options) {
+  const limit = Math.min(Math.max(1, options.limit ?? 100), 1_000)
+  const conditions = ["1 = 1"]
+  const params = []
+  if (options.kind !== undefined) {
+    conditions.push("kind = ?")
+    params.push(options.kind)
+  }
+  if (options.after !== undefined) {
+    conditions.push("order_index > ?")
+    params.push(options.after)
+  }
+  if (options.before !== undefined) {
+    conditions.push("order_index < ?")
+    params.push(options.before)
+  }
+  const sql = `SELECT kind, timestamp, order_index, artifact_id, summary, metadata FROM events WHERE ${conditions.join(" AND ")} ORDER BY order_index ASC LIMIT ?`
+  const rows = /** @type {EventRow[]} */ (db.prepare(sql).all(...params, limit + 1))
+  const truncated = rows.length > limit
+  const selected = rows.slice(0, limit)
+  return {
+    events: selected.map((row) => ({
+      kind: row.kind,
+      timestamp: row.timestamp,
+      order: row.order_index,
+      artifactId: row.artifact_id,
+      summary: row.summary,
+      metadata: row.metadata === null ? undefined : JSON.parse(row.metadata)
+    })),
+    truncated,
+    ...(selected.length > 0 && truncated ? {nextOrder: selected[selected.length - 1]?.order_index} : {})
+  }
+}
+
+/**
+ * @param {import("node:sqlite").DatabaseSync} db
+ * @param {NonNullable<EvidenceInspectRequest["failures"]>} options
+ */
+function queryFailures(db, options) {
+  const limit = Math.min(Math.max(1, options.limit ?? 100), 1_000)
+  const params = []
+  const afterClause = options.after !== undefined ? (params.push(options.after), "AND order_index > ?") : ""
+  const sql = `
+    SELECT kind, timestamp, order_index, artifact_id, summary, metadata FROM events
+    WHERE (
+      (kind = 'diagnostic' AND json_extract(metadata, '$.level') = 'error')
+      OR (kind = 'tool' AND json_extract(metadata, '$.phase') = 'finished')
+    ) ${afterClause}
+    ORDER BY order_index ASC
+    LIMIT ?
+  `
+  const rows = /** @type {EventRow[]} */ (db.prepare(sql).all(...params, limit + 1))
+  const selected = rows.slice(0, limit)
+  return {
+    failures: selected.map((row) => ({
+      kind: row.kind,
+      timestamp: row.timestamp,
+      order: row.order_index,
+      artifactId: row.artifact_id,
+      summary: row.summary,
+      metadata: row.metadata === null ? undefined : JSON.parse(row.metadata)
+    })),
+    truncated: rows.length > limit
+  }
+}
+
+/** @param {string} path */
+async function safeUnlink(path) {
+  try {
+    await unlink(path)
+  } catch (error) {
+    if (/** @type {NodeJS.ErrnoException} */ (error).code !== "ENOENT") throw error
+  }
+}
+
+/**
+ * @param {unknown} value
+ * @param {number} limit
+ * @returns {string | null}
+ */
+function boundString(value, limit) {
+  if (value === undefined || value === null) return null
+  if (typeof value !== "string") throw new EvidenceIndexError("Expected a string value")
+  if (value.length > limit) throw new EvidenceIndexError("String value exceeds bounded length")
+  return value
+}
+
+/** @param {unknown} event @returns {EvidenceIndexEvent} */
+function validateEvent(event) {
+  if (!plainObject(event)) throw new EvidenceIndexError("Invalid evidence index event")
+  const record = /** @type {Record<string, unknown>} */ (event)
+  if (typeof record.kind !== "string" || !ALLOWED_EVENT_KINDS.has(record.kind)) {
+    throw new EvidenceIndexError("Invalid evidence index event kind")
+  }
+  const kind = /** @type {EvidenceIndexEvent["kind"]} */ (record.kind)
+  if (record.timestamp !== undefined && record.timestamp !== null && (!Number.isSafeInteger(record.timestamp) || /** @type {number} */ (record.timestamp) < 0)) {
+    throw new EvidenceIndexError("Invalid evidence index event timestamp")
+  }
+  if (record.artifactId !== undefined && (typeof record.artifactId !== "string" || record.artifactId.length > MAX_ARTIFACT_ID_LENGTH)) {
+    throw new EvidenceIndexError("Invalid evidence index event artifactId")
+  }
+  let summary
+  if (record.summary !== undefined) {
+    if (typeof record.summary !== "string" || record.summary.length > MAX_SUMMARY_LENGTH) {
+      throw new EvidenceIndexError("Invalid evidence index event summary")
+    }
+    summary = record.summary
+  }
+  let metadata
+  if (record.metadata !== undefined) {
+    if (!plainObject(record.metadata)) throw new EvidenceIndexError("Invalid evidence index event metadata")
+    metadata = record.metadata
+  }
+  return {kind, summary, metadata}
+}
+
+/** @param {unknown} request @returns {EvidenceInspectRequest} */
+export function validateInspectRequest(request) {
+  if (!plainObject(request)) throw new EvidenceIndexError("Invalid evidence inspect request")
+  const record = /** @type {Record<string, unknown>} */ (request)
+  const handleDescriptor = Object.getOwnPropertyDescriptor(record, "handle")
+  if (
+    !handleDescriptor || handleDescriptor.get !== undefined || handleDescriptor.set !== undefined
+    || typeof handleDescriptor.value !== "string" || !/^evidence_[A-Za-z0-9_-]{43}$/u.test(handleDescriptor.value)
+  ) {
+    throw new EvidenceIndexError("Invalid evidence handle")
+  }
+  const selectors = ["summary", "events", "failures"].filter((field) => Object.prototype.hasOwnProperty.call(record, field))
+  if (selectors.length !== 1) throw new EvidenceIndexError("Evidence inspect requires exactly one fixed selector")
+  if (record.summary !== undefined && record.summary !== true) {
+    throw new EvidenceIndexError("Invalid summary selector")
+  }
+  if (record.events !== undefined) {
+    if (!plainObject(record.events)) throw new EvidenceIndexError("Invalid events selector")
+    const events = /** @type {Record<string, unknown>} */ (record.events)
+    if (events.kind !== undefined && typeof events.kind !== "string") {
+      throw new EvidenceIndexError("Invalid events kind filter")
+    }
+    if (events.kind !== undefined && !ALLOWED_EVENT_KINDS.has(events.kind)) {
+      throw new EvidenceIndexError("Invalid events kind filter")
+    }
+    for (const bound of ["after", "before"]) {
+      const value = events[bound]
+      if (value !== undefined && value !== null && (!Number.isSafeInteger(value) || /** @type {number} */ (value) < 0)) {
+        throw new EvidenceIndexError(`Invalid events ${bound} bound`)
+      }
+    }
+    if (events.limit !== undefined && events.limit !== null && (!Number.isSafeInteger(events.limit) || /** @type {number} */ (events.limit) < 1)) {
+      throw new EvidenceIndexError("Invalid events limit")
+    }
+  }
+  if (record.failures !== undefined) {
+    if (!plainObject(record.failures)) throw new EvidenceIndexError("Invalid failures selector")
+    const failures = /** @type {Record<string, unknown>} */ (record.failures)
+    if (failures.after !== undefined && failures.after !== null && (!Number.isSafeInteger(failures.after) || /** @type {number} */ (failures.after) < 0)) {
+      throw new EvidenceIndexError("Invalid failures after bound")
+    }
+    if (failures.limit !== undefined && failures.limit !== null && (!Number.isSafeInteger(failures.limit) || /** @type {number} */ (failures.limit) < 1)) {
+      throw new EvidenceIndexError("Invalid failures limit")
+    }
+  }
+  return /** @type {EvidenceInspectRequest} */ (request)
+}
+
+/** @param {unknown} value @returns {value is Record<string, unknown>} */
+function plainObject(value) {
+  if (value === null || typeof value !== "object" || Array.isArray(value)) return false
+  const prototype = Object.getPrototypeOf(value)
+  return prototype === Object.prototype || prototype === null
+}
+
+/**
+ * @typedef {{
+ *   kind: "prompt" | "provider_stdout" | "provider_stderr" | "assistant" | "tool" | "lifecycle" | "diagnostic" | "context_metrics" | "provider_result",
+ *   provider?: string,
+ *   artifactId?: string,
+ *   timestamp?: number,
+ *   summary?: string | undefined,
+ *   metadata?: Record<string, unknown> | undefined
+ * }} EvidenceIndexEvent
+ */
+
+/**
+ * @typedef {{
+ *   handle: string,
+ *   summary?: true,
+ *   events?: {kind?: string, after?: number, before?: number, limit?: number},
+ *   failures?: {after?: number, limit?: number}
+ * }} EvidenceInspectRequest
+ */
+
+/**
+ * @typedef {{
+ *   version?: number,
+ *   provider?: string | null,
+ *   terminal?: {state: "completed" | "failed", exitCode: number} | null,
+ *   createdAt?: number,
+ *   expiresAt?: number,
+ *   finalizedAt?: number | null,
+ *   totalEvents?: number,
+ *   eventCounts?: Record<string, number>,
+ *   events?: Array<{kind: string, timestamp: number, order: number, artifactId: string | null, summary: string | null, metadata?: Record<string, unknown> | undefined}>,
+ *   truncated?: boolean,
+ *   nextOrder?: number | undefined,
+ *   failures?: Array<{kind: string, timestamp: number, order: number, artifactId: string | null, summary: string | null, metadata?: Record<string, unknown> | undefined}>
+ * }} EvidenceInspectResult
+ */
+
+/**
+ * Convert a normalized worker event into a bounded evidence-index event.
+ * @param {import("./types.js").WorkerEvent} event
+ * @param {string} provider
+ * @returns {EvidenceIndexEvent}
+ */
+export function workerEventToIndexEvent(event, provider) {
+  if (event.type === "text-delta") {
+    return {kind: "assistant", provider, metadata: {streamId: event.streamId, length: event.text.length}}
+  }
+  if (event.type === "tool") {
+    return {
+      kind: "tool",
+      provider,
+      metadata: {
+        phase: event.phase,
+        name: event.name,
+        key: event.key,
+        ...(event.detail === undefined ? {} : {detail: event.detail.slice(0, 256)}),
+        ...(event.output === undefined ? {} : {outputLength: event.output.length})
+      }
+    }
+  }
+  if (event.type === "lifecycle") {
+    return {kind: "lifecycle", provider, metadata: {phase: event.phase, summary: event.summary.slice(0, 256)}}
+  }
+  return {kind: "diagnostic", provider, metadata: {level: event.level, summary: event.summary.slice(0, 256)}}
+}
+
+/** @typedef {{version: number, run_id: string, destination_id: string, provider: string | null, terminal_state: string | null, terminal_exit_code: number | null, created_at: number, expires_at: number, finalized_at: number | null}} ManifestRow */
+/** @typedef {{kind: string, timestamp: number, order_index: number, artifact_id: string | null, summary: string | null, metadata: string | null}} EventRow */