@fitchmultz/pi-subagents 0.44.7 → 0.46.0

package/src/history/run-queries.ts

@@ -0,0 +1,199 @@
+import {
+  HistoryIndexError,
+  type HistoryRunOptions,
+  type HistoryRunPage,
+  type HistoryRunRow,
+} from "./types.ts";
+import { integer, pageLimit, hasText } from "./text.ts";
+import { number, text, type Row, type IndexInput } from "./rows.ts";
+import { parseRunRow } from "./wire-models.ts";
+import type { QueryScope, Cursor } from "./query-scope.ts";
+
+interface RunFilter {
+  readonly clauses: readonly string[];
+  readonly params: readonly IndexInput[];
+  readonly childWhere: string;
+  readonly childParams: readonly IndexInput[];
+}
+function validate(options: HistoryRunOptions): void {
+  if (
+    options.state !== undefined &&
+    !["live", "completed", "paused", "blocked", "failed", "unknown"].includes(options.state)
+  ) {
+    throw new HistoryIndexError("INVALID", "Unsupported run state.");
+  }
+  validateFilters(options);
+}
+function validateFilters(options: HistoryRunOptions): void {
+  if (
+    (options.text?.length ?? 0) > 256 ||
+    (options.agent?.length ?? 0) > 256 ||
+    (options.latestTasksOnly !== undefined && typeof options.latestTasksOnly !== "boolean")
+  ) {
+    throw new HistoryIndexError("INVALID", "Invalid run filter.");
+  }
+}
+function queryKey(scope: Readonly<QueryScope>, options: HistoryRunOptions, sort: string): string {
+  return scope.key([
+    "runs",
+    sort,
+    options.agent ?? null,
+    options.state ?? null,
+    options.text?.toLowerCase() ?? null,
+    options.latestTasksOnly ?? false,
+  ]);
+}
+function filters(options: HistoryRunOptions): RunFilter {
+  const clauses: string[] = [];
+  const params: IndexInput[] = [];
+  const childClauses: string[] = [];
+  const childParams: IndexInput[] = [];
+  if (hasText(options.agent)) {
+    childClauses.push("c.agent=?");
+    childParams.push(options.agent);
+  }
+  if (hasText(options.text)) {
+    childClauses.push("instr(c.filter_text,?)>0");
+    childParams.push(options.text.toLowerCase());
+  }
+  if (options.latestTasksOnly === true) {
+    childClauses.push(
+      "NOT EXISTS(SELECT 1 FROM runs successor WHERE successor.predecessor_id=c.run_id AND successor.predecessor_index=c.child_index)",
+    );
+  }
+  const childWhere = childClauses.length > 0 ? ` AND ${childClauses.join(" AND ")}` : "";
+  if (childWhere.length > 0) {
+    clauses.push(`EXISTS(SELECT 1 FROM children c WHERE c.run_id=r.id${childWhere})`);
+    params.push(...childParams);
+  }
+  if (hasText(options.state)) {
+    clauses.push("r.state=?");
+    params.push(options.state);
+  }
+  return { clauses, params, childWhere, childParams };
+}
+function columns(sort: HistoryRunOptions["sort"]): readonly string[] {
+  if (sort === "attention") {
+    return ["attention", "negative_updated", "id"];
+  }
+  return [sort === "newest" ? "negative_updated" : "updated", "id"];
+}
+function runSort(value: HistoryRunOptions["sort"]): NonNullable<HistoryRunOptions["sort"]> {
+  const sort = value ?? "attention";
+  if (!["attention", "newest", "oldest"].includes(sort)) {
+    throw new HistoryIndexError("INVALID", "Unsupported run sort.");
+  }
+  return sort;
+}
+function seek(filter: RunFilter, cursor: Cursor | undefined, order: readonly string[]): RunFilter {
+  if (!cursor) {
+    return filter;
+  }
+  if (cursor.keys.length !== order.length) {
+    throw new HistoryIndexError("INVALID_CURSOR", "Invalid run seek tuple.");
+  }
+  return {
+    ...filter,
+    clauses: [
+      ...filter.clauses,
+      `(${order.map((column) => `r.${column}`).join(",")}) > (${order.map(() => "?").join(",")})`,
+    ],
+    params: [...filter.params, ...cursor.keys],
+  };
+}
+export class RunQueries {
+  private readonly scope: Readonly<QueryScope>;
+  constructor(scope: Readonly<QueryScope>) {
+    this.scope = scope;
+  }
+  private view(row: Row, filter: RunFilter): HistoryRunRow {
+    const value: unknown = JSON.parse(text(row, "view"));
+    const view = parseRunRow(value);
+    const matchedChildIndexes =
+      filter.childWhere.length > 0
+        ? this.scope.store
+            .all(
+              `SELECT child_index FROM children c WHERE c.run_id=?${filter.childWhere} ORDER BY child_index`,
+              view.runId,
+              ...filter.childParams,
+            )
+            .map((child) => number(child, "child_index"))
+        : view.matchedChildIndexes;
+    return {
+      ...view,
+      ...(matchedChildIndexes === undefined ? {} : { matchedChildIndexes }),
+      children: view.children.map((child) => {
+        const { source } = this.scope.child(view.runId, child.index);
+        if (!source) {
+          return child;
+        }
+        const boundary =
+          child.state === "live"
+            ? {}
+            : {
+                terminalEntryId: child.result?.terminalEntryId,
+                endedAt:
+                  (child.result?.terminalEntryId?.length ?? 0) > 0 ? undefined : view.updatedAt,
+                leaf: child.result?.terminalLeafId,
+              };
+        return Object.assign({}, child, {
+          nativeConfiguration: this.scope.configuration(source, boundary, false),
+        });
+      }),
+    };
+  }
+  private nextPage(
+    query: string,
+    order: readonly string[],
+    page: readonly Row[],
+    position: number,
+  ): Pick<HistoryRunPage, "nextOffset" | "nextCursor"> {
+    const last = page.at(-1);
+    return last
+      ? {
+          nextOffset: position + page.length,
+          nextCursor: this.scope.cursor(
+            query,
+            order.map((column) => (column === "id" ? text(last, column) : number(last, column))),
+            position + page.length,
+          ),
+        }
+      : {};
+  }
+  list(options: HistoryRunOptions): HistoryRunPage {
+    validate(options);
+    const limit = pageLimit(options.limit, 20);
+    const offset = integer(options.offset, 0);
+    const sort = runSort(options.sort);
+    const query = queryKey(this.scope, options, sort);
+    const cursor = this.scope.parseCursor(options.cursor, query);
+    if (cursor && options.offset !== undefined) {
+      throw new HistoryIndexError("INVALID", "Use cursor or offset, not both.");
+    }
+    const filter = filters(options);
+    const total = number(
+      this.scope.store.require(
+        `SELECT COUNT(*) AS total FROM runs r ${filter.clauses.length > 0 ? `WHERE ${filter.clauses.join(" AND ")}` : ""}`,
+        ...filter.params,
+      ),
+      "total",
+    );
+    const order = columns(sort);
+    const selected = seek(filter, cursor, order);
+    const rows = this.scope.store.all(
+      `SELECT * FROM runs r ${selected.clauses.length > 0 ? `WHERE ${selected.clauses.join(" AND ")}` : ""} ORDER BY ${order.map((column) => `r.${column}`).join(",")} LIMIT ? OFFSET ?`,
+      ...selected.params,
+      limit + 1,
+      cursor ? 0 : offset,
+    );
+    const page = rows.slice(0, limit);
+    const position = cursor?.offset ?? offset;
+    return {
+      rows: page.map((row) => this.view(row, filter)),
+      total,
+      offset: position,
+      ...this.scope.info(),
+      ...this.nextPage(query, order, rows.length > limit ? page : [], position),
+    };
+  }
+}

package/src/history/schema.ts

@@ -0,0 +1,34 @@
+import { randomUUID } from "node:crypto";
+import type { DatabaseSync } from "node:sqlite";
+
+export const HISTORY_SCHEMA_VERSION = 5;
+
+/** One schema version owns the row, FTS and cursor publication contracts together. */
+export function createHistorySchema(db: DatabaseSync): void {
+  db.exec(`
+    CREATE TABLE meta(key TEXT PRIMARY KEY,value TEXT NOT NULL);
+    INSERT INTO meta VALUES ('generation','${randomUUID()}'),('version','0'),('indexedAt','0');
+    CREATE TABLE runs(id TEXT PRIMARY KEY,attention INTEGER NOT NULL,updated INTEGER NOT NULL,negative_updated INTEGER NOT NULL,state TEXT NOT NULL,filter_text TEXT NOT NULL,view TEXT NOT NULL,predecessor_id TEXT,predecessor_index INTEGER);
+    CREATE INDEX runs_predecessor ON runs(predecessor_id,predecessor_index);
+    CREATE INDEX runs_attention ON runs(attention,negative_updated,id);
+    CREATE INDEX runs_newest ON runs(negative_updated,id);
+    CREATE INDEX runs_oldest ON runs(updated,id);
+    CREATE INDEX runs_state ON runs(state,attention,negative_updated,id);
+    CREATE TABLE sources(id TEXT PRIMARY KEY,path TEXT NOT NULL UNIQUE,generation INTEGER NOT NULL DEFAULT 1,identity TEXT,stamp TEXT,session_id TEXT,header_digest TEXT,cursor INTEGER NOT NULL DEFAULT 0,prefix_digest TEXT,state TEXT NOT NULL DEFAULT 'pending',error TEXT,malformed INTEGER NOT NULL DEFAULT 0,complexity INTEGER NOT NULL DEFAULT 0,checked_at INTEGER,format_version INTEGER);
+    CREATE TABLE children(run_id TEXT NOT NULL REFERENCES runs(id) ON DELETE CASCADE,child_index INTEGER NOT NULL,agent TEXT NOT NULL,source_id TEXT REFERENCES sources(id),filter_text TEXT NOT NULL,output_digest TEXT,terminal_entry_id TEXT,ended_at INTEGER,PRIMARY KEY(run_id,child_index));
+    CREATE INDEX children_source ON children(source_id);
+    CREATE INDEX children_agent ON children(agent,run_id);
+    CREATE TABLE entries(rowid INTEGER PRIMARY KEY,source_id TEXT NOT NULL REFERENCES sources(id),generation INTEGER NOT NULL,id TEXT NOT NULL,native_id TEXT,parent_id TEXT,start INTEGER NOT NULL,end INTEGER NOT NULL,digest TEXT NOT NULL,timestamp INTEGER,type TEXT NOT NULL,preview TEXT NOT NULL,published INTEGER NOT NULL DEFAULT 0,role TEXT,assistant_text INTEGER NOT NULL DEFAULT 0,visible_id TEXT,human_id TEXT,configuration_model TEXT,configuration_thinking TEXT,UNIQUE(source_id,generation,id),UNIQUE(source_id,generation,start));
+    CREATE INDEX entries_page ON entries(source_id,generation,published,start);
+    CREATE INDEX entries_time ON entries(source_id,generation,published,timestamp,start);
+    CREATE INDEX entries_human ON entries(source_id,generation,human_id,start);
+    CREATE TABLE answers(entry_rowid INTEGER NOT NULL REFERENCES entries(rowid) ON DELETE CASCADE,digest TEXT NOT NULL,item_id TEXT NOT NULL,PRIMARY KEY(entry_rowid,digest));
+    CREATE INDEX answers_digest ON answers(digest,entry_rowid);
+    CREATE TABLE tools(entry_rowid INTEGER NOT NULL REFERENCES entries(rowid) ON DELETE CASCADE,source_id TEXT NOT NULL,generation INTEGER NOT NULL,call_id TEXT NOT NULL,kind TEXT NOT NULL);
+    CREATE INDEX tools_lookup ON tools(source_id,generation,call_id,kind);
+    CREATE TABLE documents(id INTEGER PRIMARY KEY,entry_rowid INTEGER NOT NULL REFERENCES entries(rowid) ON DELETE CASCADE,field TEXT NOT NULL,text_start INTEGER NOT NULL,text_end INTEGER NOT NULL,preview TEXT NOT NULL);
+    CREATE INDEX documents_entry ON documents(entry_rowid);
+    CREATE VIRTUAL TABLE corpus USING fts5(text,content='',contentless_delete=1,tokenize='unicode61');
+    PRAGMA user_version=${HISTORY_SCHEMA_VERSION};
+  `);
+}

package/src/history/search-queries.ts

@@ -0,0 +1,216 @@
+import {
+  HistoryIndexError,
+  type HistorySearchInput,
+  type HistorySearchPage,
+  type HistorySearchMatch,
+} from "./types.ts";
+import { integer, pageLimit, hasText } from "./text.ts";
+import { number, nullableNumber, nullableText, text, type Row, type IndexInput } from "./rows.ts";
+import type { QueryScope, Cursor } from "./query-scope.ts";
+
+function searchGrammar(query: string): readonly string[] {
+  if (typeof query !== "string" || query.trim().length === 0 || query.length > 1024) {
+    throw new HistoryIndexError(
+      "INVALID_QUERY",
+      "Search requires 1–12 tokens or one quoted phrase.",
+    );
+  }
+  const value = query.trim();
+  const phrase = value.startsWith('"') && value.endsWith('"');
+  const words = (phrase ? value.slice(1, -1) : value).trim().split(/\s+/u);
+  if (
+    words.length === 0 ||
+    words.length > 12 ||
+    words.some(
+      (word) =>
+        !/^[\p{L}\p{N}\p{M}]{1,64}$/u.test(word) ||
+        (!phrase && ["AND", "OR", "NOT", "NEAR"].includes(word)),
+    )
+  ) {
+    throw new HistoryIndexError(
+      "INVALID_QUERY",
+      "Only lexical tokens or one quoted phrase are supported; operators, punctuation, and prefixes are not allowed.",
+    );
+  }
+  return phrase ? [`"${words.join(" ")}"`] : [...new Set(words.map((word) => `"${word}"`))];
+}
+function match(row: Row): HistorySearchMatch {
+  return {
+    id: number(row, "document_id"),
+    runId: text(row, "run_id"),
+    index: number(row, "child_index"),
+    agent: text(row, "agent"),
+    entryId: text(row, "id"),
+    nativeId: nullableText(row, "native_id"),
+    sessionId: nullableText(row, "session_id"),
+    sessionFile: text(row, "path"),
+    timestamp: nullableNumber(row, "timestamp"),
+    ref: {
+      sourceId: text(row, "source_id"),
+      generation: number(row, "generation"),
+      start: number(row, "start"),
+      end: number(row, "end"),
+      digest: text(row, "digest"),
+    },
+    preview: text(row, "document_preview"),
+    field: text(row, "field"),
+    textStart: number(row, "text_start"),
+    textEnd: number(row, "text_end"),
+    score: number(row, "score"),
+  };
+}
+interface SearchPlan {
+  readonly clauses: readonly string[];
+  readonly params: readonly IndexInput[];
+  readonly eligible: string;
+  readonly eligibleParams: readonly IndexInput[];
+}
+function plan(
+  input: HistorySearchInput,
+  expression: readonly string[],
+  cursor: Cursor | undefined,
+  score: string,
+): SearchPlan {
+  const clauses = [
+    "e.published=1",
+    "e.generation=s.generation",
+    "(c.terminal_entry_id IS NULL OR e.start<=terminal.start)",
+    "(c.ended_at IS NULL OR e.timestamp<=c.ended_at)",
+  ];
+  const params: IndexInput[] = [...expression];
+  if (hasText(input.runId)) {
+    clauses.push("c.run_id=?");
+    params.push(input.runId);
+  }
+  if (input.index !== undefined) {
+    clauses.push("c.child_index=?");
+    params.push(input.index);
+  }
+  if (hasText(input.agent)) {
+    if (input.agent.length > 256) {
+      throw new HistoryIndexError("INVALID", "Agent filter is too long.");
+    }
+    clauses.push("c.agent=?");
+    params.push(input.agent);
+  }
+  // Scope physical records once before aggregation; bm25 still uses the whole corpus.
+  const eligible =
+    hasText(input.runId) || hasText(input.agent)
+      ? `eligible AS MATERIALIZED (SELECT e.rowid FROM entries e JOIN sources s ON s.id=e.source_id WHERE e.published=1 AND e.generation=s.generation AND e.source_id IN (SELECT c.source_id FROM children c WHERE ${clauses.slice(4).join(" AND ")})),`
+      : "";
+  const eligibleParams = eligible.length > 0 ? params.slice(expression.length) : [];
+  if (cursor) {
+    if (cursor.keys.length !== 4) {
+      throw new HistoryIndexError("INVALID_CURSOR", "Invalid search seek tuple.");
+    }
+    clauses.push(`(${score},d.id,c.run_id,c.child_index)>(?,?,?,?)`);
+    params.push(...cursor.keys);
+  }
+  return { clauses, params, eligible, eligibleParams };
+}
+function queryKey(
+  scope: Readonly<QueryScope>,
+  input: HistorySearchInput,
+  expression: readonly string[],
+  sort: string,
+): string {
+  return scope.key([
+    "search",
+    expression,
+    sort,
+    input.runId ?? null,
+    input.index ?? null,
+    input.agent ?? null,
+  ]);
+}
+export class SearchQueries {
+  private readonly scope: Readonly<QueryScope>;
+  constructor(scope: Readonly<QueryScope>) {
+    this.scope = scope;
+  }
+  private validateScope(input: HistorySearchInput): void {
+    if (input.index !== undefined && !hasText(input.runId)) {
+      throw new HistoryIndexError("INVALID", "A child search requires runId.");
+    }
+    if (!hasText(input.runId)) {
+      return;
+    }
+    if (!this.scope.store.get("SELECT id FROM runs WHERE id=?", input.runId)) {
+      throw new HistoryIndexError("OWNERSHIP", "Run is not admitted by the current owner.");
+    }
+    if (input.index !== undefined) {
+      this.scope.child(input.runId, integer(input.index, 0));
+    }
+    this.checkAttemptBoundaries(input);
+  }
+  private checkAttemptBoundaries(input: Pick<HistorySearchInput, "runId" | "index">): void {
+    for (const child of this.scope.store.all(
+      `SELECT source_id,terminal_entry_id,ended_at FROM children WHERE run_id=?${input.index !== undefined ? " AND child_index=?" : ""}`,
+      input.runId ?? "",
+      ...(input.index !== undefined ? [input.index] : []),
+    )) {
+      const sourceId = nullableText(child, "source_id");
+      const source = sourceId === null ? undefined : this.scope.store.source(sourceId);
+      if (source) {
+        this.scope.boundary(source, {
+          terminalEntryId: nullableText(child, "terminal_entry_id") ?? undefined,
+          endedAt: nullableNumber(child, "ended_at") ?? undefined,
+        });
+      }
+    }
+  }
+  private rows(
+    expression: readonly string[],
+    filter: SearchPlan,
+    score: string,
+    limit: number,
+  ): readonly Row[] {
+    // Match every token across a record's visible windows; a quoted phrase cannot span fields.
+    // Ranking/filters precede LIMIT. The parent owns the hard deadline for a costly FTS scan.
+    return this.scope.store.all(
+      `WITH ${filter.eligible} hits AS MATERIALIZED (
+      ${expression.map((_term, index) => `SELECT d.id,d.entry_rowid,bm25(corpus) AS score,${index} AS term FROM corpus JOIN documents d ON d.id=corpus.rowid WHERE corpus MATCH ?${filter.eligible.length > 0 ? " AND d.entry_rowid IN (SELECT rowid FROM eligible)" : ""}`).join(" UNION ALL ")}
+    ), terms AS (SELECT entry_rowid,term,MIN(score) AS score FROM hits GROUP BY entry_rowid,term),
+    matched AS (SELECT entry_rowid,SUM(score) AS score FROM terms GROUP BY entry_rowid HAVING COUNT(*)=${expression.length}),
+    excerpts AS (SELECT id,entry_rowid,ROW_NUMBER() OVER (PARTITION BY entry_rowid ORDER BY score,id) AS choice FROM hits)
+    SELECT d.*,${score} AS score,e.*,d.id AS document_id,s.path,s.session_id,c.run_id,c.child_index,c.agent,d.preview AS document_preview FROM matched JOIN excerpts ON excerpts.entry_rowid=matched.entry_rowid AND excerpts.choice=1 JOIN documents d ON d.id=excerpts.id JOIN entries e ON e.rowid=matched.entry_rowid JOIN sources s ON s.id=e.source_id JOIN children c ON c.source_id=s.id LEFT JOIN entries terminal ON terminal.source_id=s.id AND terminal.generation=s.generation AND terminal.id=c.terminal_entry_id AND terminal.published=1 WHERE ${filter.clauses.join(" AND ")} ORDER BY score,d.id,c.run_id,c.child_index LIMIT ?`,
+      ...filter.eligibleParams,
+      ...filter.params,
+      limit + 1,
+    );
+  }
+  search(input: HistorySearchInput): HistorySearchPage {
+    const expression = searchGrammar(input.query);
+    const limit = pageLimit(input.limit, 20);
+    const sort = input.sort ?? "relevance";
+    if (!["relevance", "newest"].includes(sort)) {
+      throw new HistoryIndexError("INVALID", "Unsupported search sort.");
+    }
+    this.validateScope(input);
+    const query = queryKey(this.scope, input, expression, sort);
+    const cursor = this.scope.parseCursor(input.cursor, query);
+    const score = sort === "relevance" ? "matched.score" : "-COALESCE(e.timestamp,0)";
+    const filter = plan(input, expression, cursor, score);
+    const rows = this.rows(expression, filter, score, limit);
+    const page = rows.slice(0, limit);
+    const last = page.at(-1);
+    return {
+      ...this.scope.info(),
+      matches: page.map(match),
+      ...(rows.length > limit && last
+        ? {
+            nextCursor: this.scope.cursor(
+              query,
+              [
+                number(last, "score"),
+                number(last, "document_id"),
+                text(last, "run_id"),
+                number(last, "child_index"),
+              ],
+              (cursor?.offset ?? 0) + page.length,
+            ),
+          }
+        : {}),
+    };
+  }
+}

package/src/history/selected-record.ts

@@ -0,0 +1,140 @@
+import * as fs from "node:fs";
+import { createHash } from "node:crypto";
+import { JsonProjection } from "../shared/journal-reader.ts";
+import { HistoryIndexError } from "./types.ts";
+import type { EntryRow, SourceRow } from "./rows.ts";
+import { identity } from "./source-file.ts";
+import { previewLimits, previewProjection } from "./preview.ts";
+import { parseObject } from "./values.ts";
+import { isRecord, hasErrorCode } from "../shared/unknown.ts";
+
+function validateHeader(fd: number, source: SourceRow): void {
+  const hash = createHash("sha256");
+  const bytes = Buffer.allocUnsafe(64 * 1024);
+  let position = 0;
+  let complete = false;
+  while (!complete && position < 1024 * 1024) {
+    const count = fs.readSync(fd, bytes, 0, bytes.length, position);
+    if (count === 0) {
+      break;
+    }
+    const newline = bytes.subarray(0, count).indexOf(10);
+    const length = newline < 0 ? count : newline + 1;
+    hash.update(bytes.subarray(0, length));
+    position += length;
+    complete = newline >= 0;
+  }
+  if (!complete || hash.digest("hex") !== source.header_digest) {
+    throw new HistoryIndexError(
+      "SOURCE_CHANGED",
+      "Selected native header changed or exceeds its validation budget.",
+    );
+  }
+}
+function readBody(
+  fd: number,
+  row: EntryRow,
+  full: boolean,
+): { readonly finish: () => Readonly<Record<string, unknown>>; readonly digest: string } {
+  const digest = createHash("sha256");
+  const parser = new JsonProjection(previewProjection, undefined, undefined, previewLimits);
+  const bytes = Buffer.allocUnsafe(64 * 1024);
+  const body: Buffer[] = [];
+  const decoder = new TextDecoder("utf8", { fatal: true });
+  for (let position = row.start; position < row.end;) {
+    const count = fs.readSync(fd, bytes, 0, Math.min(bytes.length, row.end - position), position);
+    if (count === 0) {
+      throw new HistoryIndexError(
+        "SOURCE_CHANGED",
+        "Selected record was truncated during validation.",
+      );
+    }
+    const chunk = bytes.subarray(0, count);
+    digest.update(chunk);
+    if (full) {
+      body.push(Buffer.from(chunk));
+    } else {
+      parser.write(decoder.decode(chunk, { stream: true }));
+    }
+    position += count;
+  }
+  return {
+    digest: digest.digest("hex"),
+    finish: () => {
+      if (full) {
+        return parseObject(new TextDecoder("utf8", { fatal: true }).decode(Buffer.concat(body)));
+      }
+      parser.write(decoder.decode());
+      const projected = parser.finish();
+      if (!isRecord(projected)) {
+        throw new HistoryIndexError("SOURCE_CHANGED", "Selected record is not an object.");
+      }
+      return projected;
+    },
+  };
+}
+function validateSnapshot(
+  fd: number,
+  source: SourceRow,
+  row: EntryRow,
+  snapshot: { readonly before: fs.BigIntStats; readonly digest: string },
+): void {
+  const { before, digest } = snapshot;
+  const current = fs.statSync(source.path, { bigint: true });
+  const after = fs.fstatSync(fd, { bigint: true });
+  if (
+    identity(current) !== identity(before) ||
+    current.size < BigInt(row.end) ||
+    (after.ctimeNs !== before.ctimeNs && after.size <= before.size) ||
+    digest !== row.digest
+  ) {
+    throw new HistoryIndexError(
+      "SOURCE_CHANGED",
+      "Selected record changed; refresh history before reading details.",
+    );
+  }
+}
+/** Revalidate physical identity, native header and exact selected bytes before exposing detail. */
+export function validateRecord(
+  source: SourceRow,
+  row: EntryRow,
+  full: boolean,
+): Readonly<Record<string, unknown>> {
+  let fd: number | undefined;
+  try {
+    fd = fs.openSync(source.path, "r");
+    const stat = fs.fstatSync(fd, { bigint: true });
+    if (identity(stat) !== source.identity || Number(stat.size) < row.end) {
+      throw new HistoryIndexError(
+        "SOURCE_CHANGED",
+        "Selected conversation was replaced or truncated.",
+      );
+    }
+    validateHeader(fd, source);
+    if (full && row.end - row.start > 16 * 1024 * 1024) {
+      throw new HistoryIndexError(
+        "RECORD_TOO_LARGE",
+        "Selected full record exceeds the 16 MiB detail budget; use its validated preview.",
+      );
+    }
+    const body = readBody(fd, row, full);
+    validateSnapshot(fd, source, row, { before: stat, digest: body.digest });
+    // Physical validation wins over full JSON/UTF-8 decode errors if the file changed during reading.
+    return body.finish();
+  } catch (error) {
+    if (hasErrorCode(error, "ENOENT")) {
+      throw new HistoryIndexError("SOURCE_CHANGED", "Selected conversation is missing.");
+    }
+    if (error instanceof RangeError) {
+      throw new HistoryIndexError(
+        "RECORD_COMPLEXITY",
+        "Selected preview exceeds bounded history structure budgets.",
+      );
+    }
+    throw error;
+  } finally {
+    if (fd !== undefined) {
+      fs.closeSync(fd);
+    }
+  }
+}

package/src/history/source-file.ts

@@ -0,0 +1,51 @@
+import * as fs from "node:fs";
+import type { HistoryStore, SourceRow } from "./store.ts";
+import { HistoryIndexError } from "./types.ts";
+
+export function identity(stat: fs.BigIntStats): string {
+  return `${stat.dev}:${stat.ino}`;
+}
+export function stamp(stat: fs.BigIntStats): string {
+  return `${identity(stat)}:${stat.size}:${stat.mtimeNs}:${stat.ctimeNs}`;
+}
+export function requireSource(store: Readonly<HistoryStore>, id: string): SourceRow {
+  const source = store.source(id);
+  if (!source) {
+    throw new HistoryIndexError("SOURCE_CHANGED", "Source was removed before ingestion.");
+  }
+  return source;
+}
+/** Acquires the writer lock before reading any cursor or clearing shared staging. */
+export function openSource(
+  store: Readonly<HistoryStore>,
+  id: string,
+): { readonly fd: number; readonly initial: fs.BigIntStats; readonly source: SourceRow } {
+  store.beginIngest();
+  let fd: number | undefined;
+  try {
+    let source = requireSource(store, id);
+    store.count("sourceChecks");
+    store.count("sourceOpens");
+    fd = fs.openSync(source.path, "r");
+    const initial = fs.fstatSync(fd, { bigint: true });
+    if (!initial.isFile() || initial.size > BigInt(Number.MAX_SAFE_INTEGER)) {
+      throw new Error("Journal is not a supported regular file.");
+    }
+    if (
+      source.identity !== null &&
+      (source.identity !== identity(initial) || Number(initial.size) < source.cursor)
+    ) {
+      store.resetSource(id);
+      source = requireSource(store, id);
+    }
+    store.clearUnpublished(id);
+    store.run("DELETE FROM pending_text");
+    return { fd, initial, source };
+  } catch (error) {
+    if (fd !== undefined) {
+      fs.closeSync(fd);
+    }
+    store.endIngest();
+    throw error;
+  }
+}