dsh-hashline-edit 0.2.1 → 0.2.2

package/src/read.ts

@@ -0,0 +1,865 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { createReadTool, createReadToolDefinition } from "@earendil-works/pi-coding-agent";
+import type { TruncationResult } from "@earendil-works/pi-coding-agent";
+import { truncateToWidth, visibleWidth, type Component } from "@earendil-works/pi-tui";
+import { Type, type Static } from "typebox";
+import { MAX_READ_WINDOWS, SERVED_MAX_LINES } from "./constants.js";
+import { HASH_LEN } from "./hashline/alphabet.js";
+import type { ServedRow } from "./served-session/serve-render.js";
+import { loadHashStore, type HashStore } from "./hash-store.js";
+import { sessionFromContext, sessionKeyFor } from "./served-session/index.js";
+import { contentChecksum } from "./hashline/hasher.js";
+import { abortIf } from "./utils.js";
+import { loadP, loadGuide } from "./prompts.js";
+import {
+  decodeNormText,
+  loadFileKindAndText,
+  prepareFile,
+  type LFile,
+  type NormText,
+  type PrepareResult,
+} from "./file-content/index.js";
+import {
+  DEFAULT_ANCHOR_RADIUS,
+  DEFAULT_WINDOW_LIMIT,
+  admitReadRequest,
+  normalizeReadPayload,
+  planWindows,
+  type AdmittedRequest,
+  type AnchorResolver,
+  type RawReadParams,
+  type RenderMode,
+  type WindowPlan,
+} from "./file-content/admission.js";
+import { formatPageHeader } from "./file-content/served-header.js";
+import { toCwd } from "./paths.js";
+import { DomainError, withPayloadSubject } from "./domain-errors.js";
+import { notifyServedSpans, servedRowsToSpans } from "./served-spans.js";
+import { fileSnap } from "./file-reader.js";
+import {
+  adoptStatSnapshotFor,
+  snapshotHashFor,
+  snapshotIOFor,
+  upsertSnapshotsFor,
+} from "./snapshot-store";
+import { lineHashes } from "./hashline/hash-identity.js";
+import { reportDiagnostic, reportWarning } from "./diagnostics.js";
+import { visibleLineTotal, walkLines } from "./file-content/line-walker.js";
+import {
+  applyExpansions,
+  expansionNotes,
+  foldWindows,
+  widenWindow,
+  TRIGGER_MAX,
+  type ExpandedRead,
+  type ExpansionDecision,
+  type FoldedWindow,
+  type OffsetWindow,
+  type SpanProvider,
+  type WidenedBlock,
+} from "./read-expansion/span-expansion.js";
+import {
+  recordReadExpansion,
+  recordReadExpansionRuntimeAbsent,
+  recordReadExpansionToggleOff,
+  type ReadExpansionLogEntry,
+} from "./read-expansion/audit.js";
+import {
+  resolveReadExpansionMode,
+  resolveReadExpansionModeWithSource,
+} from "./read-expansion-config.js";
+// WHY: Facade re-export for callers still importing preview directly
+export { fmtReadPreview } from "./file-content/preview.js";
+
+const R_DESC = loadP("../prompts/read.md");
+const R_SNIPPET = loadP("../prompts/read-snippet.md");
+
+function readGuide(): string[] {
+  return loadGuide("../prompts/read-guidelines.md");
+}
+
+const renderModeSchema = Type.Union([Type.Literal("served"), Type.Literal("verbatim")], {
+  description: `Render mode: "served" (default) returns each line as a ${HASH_LEN}-char anchor plus content; "verbatim" returns plain text with no anchor prefix.`,
+});
+
+const readOffsetWindowSchema = Type.Object(
+  {
+    offset: Type.Optional(
+      Type.Integer({ minimum: 1, description: "Start line number (1-indexed). Defaults to 1." }),
+    ),
+    limit: Type.Optional(
+      Type.Integer({
+        minimum: 1,
+        description: `Number of lines to read. Defaults to ${DEFAULT_WINDOW_LIMIT} when \`offset\` is given.`,
+      }),
+    ),
+  },
+  // WHY: the union's two members must stay disjoint: both offset properties are optional, so without
+  // WHY: this an `{ around_anchor }` window would also satisfy the offset member and slip past the
+  // WHY: anchor's own length check at the seam.
+  { additionalProperties: false },
+);
+
+const readAnchorWindowSchema = Type.Object(
+  {
+    around_anchor: Type.String({
+      minLength: HASH_LEN,
+      maxLength: HASH_LEN,
+      description: `A ${HASH_LEN}-character anchor this session served: the window centres on its line.`,
+    }),
+    radius: Type.Optional(
+      Type.Integer({
+        minimum: 1,
+        default: DEFAULT_ANCHOR_RADIUS,
+        description: `Lines before and after the anchor (default ${DEFAULT_ANCHOR_RADIUS}).`,
+      }),
+    ),
+  },
+  { additionalProperties: false },
+);
+
+const readWindowSchema = Type.Union([readAnchorWindowSchema, readOffsetWindowSchema]);
+
+// WHY: one file per call (ADR-0041 D1): `file` names it, `windows` scopes it, `mode` renders
+// WHY: it. Parallel reads are parallel tool calls — there is no outer array and no per-file mode.
+// WHY: A payload without `file` fails validation before admission runs.
+export const readToolSchema = Type.Object({
+  file: Type.String({ description: "Path to the file to read (relative or absolute)." }),
+  windows: Type.Optional(
+    Type.Array(readWindowSchema, {
+      maxItems: MAX_READ_WINDOWS,
+      description:
+        "One or more line ranges in this file, each either { offset, limit } or { around_anchor, radius }; in the default `served` mode every window's rows are served, so anchors from all of them work in a single `edit`",
+    }),
+  ),
+  mode: Type.Optional(renderModeSchema),
+});
+
+// WHY: the builtin renderers key on `file_path ?? path` plus `offset`/`limit`; our payload
+// WHY: field is `file` (ADR-0041 D1/D4), but recorded history (`files`-shaped per ADR-0040, or a
+// WHY: legacy `file`/`path` caller per ADR-0040 D3) must still render, so the seam accepts every
+// WHY: key. The D5 fallback order is exactly `file ?? path ?? files?.[0]?.file`.
+type ReadRenderWindowTarget = {
+  offset?: number;
+  limit?: number;
+  around_anchor?: string;
+  radius?: number;
+};
+type ReadRenderArgs = {
+  file?: string;
+  path?: string;
+  windows?: ReadonlyArray<ReadRenderWindowTarget>;
+  mode?: string;
+  /** Retired outer shape (ADR-0040): history tolerance only, never produced anymore. */
+  files?: ReadonlyArray<{ file?: string }>;
+};
+/** Project the flat single-file payload onto the builtin renderer's keys (ADR-0041 D4/D5).
+ * Path is the call's own `file`, falling back through recorded-history shapes for rendering
+ * only. A range is derived only from exactly one simple `{ offset, limit }` window; anything
+ * else (multi-window, `around_anchor`) leaves the range absent rather than fabricating one.
+ * A multi-window call additionally reports its window count, which the caller appends to the
+ * call line. The result is a new object — `context.args` is never mutated. */
+function projectReadRenderArgs(args: ReadRenderArgs | undefined): {
+  path: string | undefined;
+  offset?: number;
+  limit?: number;
+  windowsCount?: number;
+} {
+  const windowCount = args?.windows?.length ?? 0;
+  const only = windowCount === 1 ? args!.windows![0] : undefined;
+  const ranged =
+    typeof only?.offset === "number" && typeof only?.limit === "number" ? only : undefined;
+  return {
+    path: args?.file ?? args?.path ?? args?.files?.[0]?.file,
+    ...(ranged !== undefined ? { offset: ranged.offset, limit: ranged.limit } : {}),
+    ...(windowCount >= 2 ? { windowsCount: windowCount } : {}),
+  };
+}
+
+interface PreparedTarget {
+  /** The path the caller named: the page header is the only chrome, and it names the file with this. */
+  file: string;
+  mode: RenderMode;
+  plan: WindowPlan;
+  prepared: PrepareResult;
+  /** The page's truncation, or `undefined` when the file rendered no page at all. */
+  truncation?: TruncationResult;
+  nextOffset?: number;
+  snapshotId?: string | undefined;
+  /** The merged runs this read widened to, absent for an exact read. */
+  widenedBlocks?: WidenedBlock[];
+}
+
+/** The `E_UNSUPPORTED_FILE` a non-text file owes, shaped exactly like the single-file read's. */
+function unsupportedFile(target: AdmittedRequest, prepared: PrepareResult): DomainError {
+  if (prepared.kind === "directory") {
+    return new DomainError("E_UNSUPPORTED_FILE", { path: target.file, kind: "directory" });
+  }
+  if (prepared.kind === "binary") {
+    return new DomainError("E_UNSUPPORTED_FILE", {
+      path: target.file,
+      kind: "binary",
+      ...(prepared.description !== undefined ? { description: prepared.description } : {}),
+    });
+  }
+  return new DomainError("E_UNSUPPORTED_FILE", { path: target.file, kind: "image" });
+}
+
+/** A file the read could not prepare at all (missing, unreadable, over budget, not text). */
+interface FailedTarget {
+  file: string;
+  /** The refusal text: a `DomainError`'s own message, or `file: message` for a foreign throw. */
+  message: string;
+}
+
+/** One entry of the result, in request order: a rendered file, or the failure that replaced it. */
+type FileResult = PreparedTarget | FailedTarget;
+
+function isPrepared(result: FileResult): result is PreparedTarget {
+  return "prepared" in result;
+}
+
+/** An image block the builtin read owns: this repo routes it, never decodes it. */
+interface DelegatedImageBlock {
+  type: "image";
+  data: string;
+  mimeType: string;
+}
+
+/** One entry of the call's `content` array: rendered text, or a routed image block. */
+type RoutedContent = { type: "text"; text: string } | DelegatedImageBlock;
+
+/** One target's outcome in request order: a rendered file (or its refusal), or routed image blocks. */
+type OrderedOutcome =
+  | { kind: "file"; entry: FileResult }
+  | { kind: "image"; blocks: RoutedContent[] };
+/**
+ * WHY: the page header names the range this read actually rendered (#149, read-chrome): the shown
+ * WHY: range, the file's total, and — when the byte budget cut the page — where it stopped. A page
+ * WHY: covering the whole file states the count alone, because a range would only restate it.
+ */
+function fileHeader(entry: PreparedTarget): string {
+  const shown = entry.prepared.shownRange;
+  return formatPageHeader({
+    file: entry.file,
+    totalLines: entry.prepared.lineTotals.visible,
+    ...(shown !== undefined ? { shownRange: shown } : {}),
+    ...(entry.mode === "verbatim" ? { verbatim: true } : {}),
+    ...(entry.truncation?.truncatedBy === "bytes" && shown !== undefined
+      ? { stoppedAtBytes: entry.truncation.maxBytes }
+      : {}),
+  });
+}
+
+/** One prepared file's section: its header, widening notes, inline warnings, then its rows. */
+function preparedSection(entry: PreparedTarget): string {
+  const header = fileHeader(entry);
+  // WHY: notes are content, not chrome: they tell the model which structural blocks the rows are.
+  // WHY: No expansion means no note and no byte change.
+  const notes = expansionNotes(entry.widenedBlocks ?? [], entry.prepared.shownRange);
+  const lead = [header, ...notes].join("\n");
+  if (entry.plan.omittedAll) return `${lead}\n${entry.plan.warnings.join("\n")}`;
+  if (entry.plan.warnings.length === 0) return `${lead}\n${entry.prepared.preview}`;
+  return `${lead}\n${entry.plan.warnings.join("\n")}\n\n${entry.prepared.preview}`;
+}
+
+/** Whether an original requested window sits inside a folded span. */
+function windowInside(outer: OffsetWindow, inner: OffsetWindow): boolean {
+  return (
+    inner.offset >= outer.offset && inner.offset + inner.limit - 1 <= outer.offset + outer.limit - 1
+  );
+}
+
+/** One audit record for an applied or refused expansion attempt. */
+function auditEntryFor(
+  decision: ExpansionDecision,
+  group: FoldedWindow,
+  file: string,
+  mode: RenderMode,
+): ReadExpansionLogEntry {
+  const base = { file, mode, requested: group.requested, outcome: decision.outcome } as const;
+  if (decision.outcome === "applied") {
+    const { window, record } = decision.expansion;
+    return {
+      ...base,
+      served: { startLine: window.offset, endLine: window.offset + window.limit - 1 },
+      label: `${record.kind} ${record.name}`,
+      kind: record.kind,
+      name: record.name,
+      source: record.source,
+      ...(record.clamped === true ? { clamped: true } : {}),
+      ...(record.source === "md" ? { section: record.span } : {}),
+    };
+  }
+  return {
+    ...base,
+    reason: decision.reason,
+    ...(decision.span === undefined ? {} : { section: decision.span }),
+    ...(decision.kind === undefined ? {} : { kind: decision.kind }),
+    ...(decision.name === undefined ? {} : { name: decision.name }),
+    ...(decision.source === undefined ? {} : { source: decision.source }),
+    ...(decision.language === undefined ? {} : { language: decision.language }),
+    ...(decision.blockSize === undefined ? {} : { blockSize: decision.blockSize }),
+    ...(decision.kind === undefined || decision.name === undefined
+      ? {}
+      : { label: `${decision.kind} ${decision.name}` }),
+  };
+}
+
+/** One file's section: its rows when it prepared, its refusal when it did not. */
+function sectionText(entry: FileResult): string {
+  return isPrepared(entry) ? preparedSection(entry) : entry.message;
+}
+
+/**
+ * The call's `content` array when an image is present: consecutive text sections stay joined as
+ * one text block, and the builtin's own note-plus-image blocks land in request order between them.
+ */
+function routedContent(ordered: OrderedOutcome[]): RoutedContent[] {
+  const blocks: RoutedContent[] = [];
+  let pending: string[] = [];
+  const flush = (): void => {
+    if (pending.length > 0) {
+      blocks.push({ type: "text", text: pending.join("\n\n") });
+      pending = [];
+    }
+  };
+  for (const outcome of ordered) {
+    if (outcome.kind === "image") {
+      flush();
+      blocks.push(...outcome.blocks);
+      continue;
+    }
+    pending.push(sectionText(outcome.entry));
+  }
+  flush();
+  return blocks;
+}
+/** One file's rows for the served-state channels: nothing when the file rendered no page. */
+function servedRowsOf(entry: PreparedTarget): ServedRow[] {
+  return entry.plan.omittedAll ? [] : entry.prepared.served;
+}
+
+/**
+ * The whole file's anchors for a content-hash materialization (ADR-0043).
+ *
+ * A stat-adopted page resolved only the anchors it served, so an entry that must fall back to content
+ * hashing re-derives the rest through the usual cache path. That is the rare race — its snapshot lost
+ * to a concurrent vacuum or re-stamp between the lookup and the adoption — never the common read.
+ */
+async function fullHashesFor(
+  entry: PreparedTarget,
+  store: HashStore | undefined,
+): Promise<string[]> {
+  const prepared = entry.prepared;
+  if (prepared.fileHashes.length === prepared.lineTotals.split) return prepared.fileHashes;
+  const hashStore = store ?? (await loadHashStore());
+  // WHY: not persisted here — the caller's single batch transaction is the only writer allowed to
+  // WHY: materialize this read (spec §3.1.2); a pre-write would split the snapshot from its leases.
+  return lineHashes(
+    prepared.normalized,
+    prepared.absolutePath,
+    undefined,
+    snapshotIOFor(hashStore),
+    false,
+  );
+}
+
+// WHY: the provider is optional so the shipped entry point (`regRead(pi)`) performs no expansion
+// WHY: until a parser ticket injects one; a null answer is likewise today's exact read.
+export function regRead(pi: ExtensionAPI, options?: { spanProvider?: SpanProvider }): void {
+  const spanProvider = options?.spanProvider;
+  // WHY: session_start warms the grammars off the read path; a read still waits only its budget.
+  pi.on?.("session_start", (_event, ctx) => {
+    if (ctx.cwd === undefined || resolveReadExpansionMode(ctx.cwd) === "off") return;
+    void spanProvider?.prefetch?.(ctx.cwd);
+  });
+  // WHY: pi falls back to the builtin `read` renderer by tool name, but that renderer keys on
+  // WHY: `file_path ?? path` plus `offset`/`limit`. Our payload field is `file` (ADR-0041 D1), so
+  // WHY: project it for rendering only — the call line shows the filename, and `args` is never
+  // WHY: mutated. The `file ?? path ?? files?.[0]?.file` fallback is permanent tolerance for
+  // WHY: recorded transcripts (ADR-0040 D3/D5), not dead code.
+  // WHY: Pi reuses lastComponent; its builtin needs the Text behind our wrapper.
+  const readCallBases = new WeakMap<Component, Component>();
+  const builtinReadDef = createReadToolDefinition("");
+  const builtinRenderCall = builtinReadDef.renderCall as any;
+  const builtinRenderResult = builtinReadDef.renderResult as any;
+  pi.registerTool({
+    name: "read",
+    label: "Read",
+    description: R_DESC,
+    promptSnippet: R_SNIPPET,
+    promptGuidelines: readGuide(),
+    // SAFETY: the builtin renderers are keyed on `file_path ?? path` plus `offset`/`limit`;
+    // SAFETY: projectReadRenderArgs derives the path from the flat `file` (D4) and the range
+    // SAFETY: from a single simple window, without mutating the caller's `args`. Multi-window reads
+    // SAFETY: get their count appended below — the builtin has no chrome for them.
+    renderCall: (args: ReadRenderArgs, theme, context) => {
+      const projected = projectReadRenderArgs(args);
+      const lastComponent = context.lastComponent;
+      const call: Component = builtinRenderCall({ ...args, ...projected }, theme, {
+        ...context,
+        lastComponent: lastComponent
+          ? (readCallBases.get(lastComponent) ?? lastComponent)
+          : lastComponent,
+      });
+      // WHY: 1:1 honesty (ADR-0041 D4) — the builtin renders `read <path>[:start-end]` but has no
+      // WHY: multi-window chrome, so the call line carries the count itself. Single anchor-window and
+      // WHY: whole-file reads render the bare path (no range is ever fabricated).
+      if (projected.windowsCount === undefined) return call;
+      const suffix = ` (${projected.windowsCount} windows)`;
+      const suffixWidth = visibleWidth(suffix);
+      const wrapped: Component = {
+        invalidate: () => call.invalidate(),
+        render: (width: number): string[] => {
+          if (width <= 0) return [];
+          if (width <= suffixWidth) return [truncateToWidth(suffix.trimStart(), width)];
+          const budget = width - suffixWidth;
+          return call
+            .render(budget)
+            .map((line, index) => truncateToWidth(line, budget) + (index === 0 ? suffix : ""));
+        },
+      };
+      readCallBases.set(wrapped, call);
+      return wrapped;
+    },
+    renderResult: (result, options, theme, context) => {
+      // SAFETY: renderers receive raw call args, not the validated payload, so `context.args` may
+      // SAFETY: carry a retired shape that `Static<TParams>` does not model; the projection keys on
+      // SAFETY: `file`/`path`/`windows`/`files`, so history still renders (ADR-0041 D5).
+      const args = context.args as ReadRenderArgs;
+      return builtinRenderResult(result, options, theme, {
+        ...context,
+        args: { ...args, ...projectReadRenderArgs(args) },
+      });
+    },
+    parameters: readToolSchema,
+    // WHY: recorded flat payloads (`path`/`offset`/`limit`) reach execute through replay, and the
+    // WHY: model-facing schema deliberately stays the canonical `{ file, windows, mode }` shape.
+    // SAFETY: the normalizer returns the canonical shape when it can; an invalid legacy payload
+    // SAFETY: falls through to schema validation, which is exactly where it must be refused.
+    prepareArguments: (args: unknown) =>
+      normalizeReadPayload(args as RawReadParams) as unknown as Static<typeof readToolSchema>,
+
+    async execute(_toolCallId, params, signal, _onUpdate, ctx) {
+      try {
+        const request = admitReadRequest(params as RawReadParams);
+        const cwd = ctx.cwd as string;
+        const sessionCtx = ctx as { sessionManager?: { getSessionId(): string } };
+        abortIf(signal);
+        // WHY: spec §4.3 resolves `around_anchor` against the target file's active lineage for the
+        // WHY: session and carries NO mode qualifier, so the store opens for an anchor window whether or
+        // WHY: not the target serves rows. A call naming neither a served target nor an anchor window
+        // WHY: still opens nothing, so the read that serves nothing pays nothing.
+        const needsStore =
+          request.mode === "served" ||
+          request.windows?.some((window) => window.kind === "anchor") === true;
+        const store = needsStore ? await loadHashStore() : undefined;
+        const ordered: OrderedOutcome[] = [];
+        // WHY: delegation, not reimplementation — the builtin owns image bytes, so this repo only
+        // WHY: routes `prepared.kind === "image"` to it. Built lazily so a text-only call pays nothing
+        // WHY: and its path stays untouched.
+        let builtinImageRead: ReturnType<typeof createReadTool> | undefined;
+        const readImageViaBuiltin = async (absolutePath: string) => {
+          builtinImageRead ??= createReadTool(cwd);
+          return builtinImageRead.execute(_toolCallId, { path: absolutePath }, signal);
+        };
+        // WHY: spec §4.2 — the read draws on the call's 200,000-line served budget, so a file that
+        // WHY: cannot afford what is left is refused inline instead of every prepared anchor,
+        // WHY: normalized text and hash staying alive until the return.
+        let remainingServedLines = SERVED_MAX_LINES;
+
+        // WHY: one file per call (ADR-0041 D1) — no fan-out loop, no sibling fallbacks: the single
+        // WHY: target below is the call, so its outcome is the call's outcome.
+        {
+          const target = request;
+          abortIf(signal);
+          const mode = request.mode;
+          // WHY: the served cap bounds the anchor space a read materializes; a verbatim file serves no
+          // WHY: anchors, so it carries no cap here (the decode gate is the served path's).
+          const cap = mode === "served" ? { maxLines: remainingServedLines } : {};
+          // WHY: an anchor window must resolve BEFORE the file is prepared (its offset is not known
+          // WHY: yet), so the file is read once here and handed to the seam below — never twice.
+          const wantsAnchor = target.windows?.some((window) => window.kind === "anchor") === true;
+          let preloaded: LFile | undefined = wantsAnchor
+            ? await loadFileKindAndText(toCwd(target.file, cwd), {
+                ...cap,
+                displayPath: target.file,
+              })
+            : undefined;
+          // WHY: decode once and share it — an anchor window resolves against these bytes and an
+          // WHY: expansion measures its span against the same visible line count.
+          let resolvedText: NormText | undefined;
+          if (preloaded !== undefined && preloaded.kind === "text") {
+            resolvedText = await decodeNormText(target.file, cwd, {
+              ...(signal !== undefined ? { signal } : {}),
+              ...cap,
+              preloadedFile: preloaded,
+            });
+          }
+          let resolver: AnchorResolver | undefined;
+          // WHY: resolution is lineage-scoped, not mode-scoped (spec §4.3): the store now opens for an
+          // WHY: anchor window of a verbatim target too, so this guard is the safety net for a window
+          // WHY: whose file could not be loaded as text — that window falls through to the same §4.3
+          // WHY: "not found" warning instead of dereferencing a store that is not there.
+          if (store !== undefined && resolvedText !== undefined) {
+            resolver = {
+              sessionKey: sessionFromContext(sessionCtx, resolvedText.absolutePath).sessionKey,
+              absolutePath: resolvedText.absolutePath,
+              normalized: resolvedText.normalized,
+              store,
+            };
+          }
+          const plan = planWindows(target, resolver);
+          // WHY: expansion is mode-independent (D11/D19): served adds leases, verbatim adds none;
+          // WHY: both serve the same widened range and note. Fold first, then trigger (D12), then
+          // WHY: expand each folded span and union the answers so one row is never served twice.
+          // WHY: D23 placement — this runs after the content load and before `prepareFile` hashes
+          // WHY: or dispatches on render mode. The 80/80/40 caps bound expansion; SERVED_MAX_LINES
+          // WHY: sizes the served admission, never the widening decision.
+          let expandedRead: ExpandedRead | undefined;
+          const readExpansion =
+            spanProvider !== undefined && plan.windows !== undefined && plan.windows.length > 0
+              ? resolveReadExpansionModeWithSource(cwd, (reason) =>
+                  reportWarning("read-expansion", reason),
+                )
+              : undefined;
+          if (
+            spanProvider !== undefined &&
+            readExpansion?.value === "on" &&
+            plan.windows !== undefined &&
+            plan.windows.length > 0
+          ) {
+            const folded = foldWindows(plan.windows);
+            const needsText = folded.some((group) => group.window.limit <= TRIGGER_MAX);
+            let totalLines = 0;
+            let textReady = true;
+            if (needsText) {
+              preloaded ??= await loadFileKindAndText(toCwd(target.file, cwd), {
+                ...cap,
+                displayPath: target.file,
+              });
+              textReady = preloaded.kind === "text";
+              if (textReady) {
+                resolvedText ??= await decodeNormText(target.file, cwd, {
+                  ...(signal !== undefined ? { signal } : {}),
+                  ...cap,
+                  preloadedFile: preloaded,
+                });
+                totalLines = visibleLineTotal(
+                  resolvedText.normalized,
+                  walkLines(resolvedText.normalized).total,
+                );
+              }
+            }
+            const auditSessionKey = sessionKeyFor(sessionCtx);
+            const decisions: ExpansionDecision[] = [];
+            for (const group of folded) {
+              const decision: ExpansionDecision =
+                group.window.limit > TRIGGER_MAX
+                  ? { outcome: "refused", reason: "above_trigger" }
+                  : !textReady
+                    ? { outcome: "refused", reason: "not_text" }
+                    : await widenWindow({
+                        file: toCwd(target.file, cwd),
+                        totalLines,
+                        window: group.window,
+                        requested: group.requested,
+                        provider: spanProvider,
+                      });
+              decisions.push(decision);
+              const runtimeDeclined =
+                decision.outcome === "refused" && decision.reason === "runtime_absent";
+              if (runtimeDeclined) {
+                recordReadExpansionRuntimeAbsent(
+                  auditEntryFor(decision, group, target.file, mode),
+                  auditSessionKey,
+                  readExpansion.source,
+                );
+              } else {
+                recordReadExpansion(
+                  auditEntryFor(decision, group, target.file, mode),
+                  auditSessionKey,
+                  readExpansion.source,
+                );
+              }
+            }
+            const servedWindows = plan.windows.map((window) => {
+              const index = folded.findIndex((group) => windowInside(group.window, window));
+              const decision = index < 0 ? undefined : decisions[index];
+              return decision?.outcome === "applied" ? decision.expansion.window : window;
+            });
+            const applied = decisions.flatMap((decision) =>
+              decision.outcome === "applied" ? [decision.expansion] : [],
+            );
+            expandedRead = applyExpansions(servedWindows, applied);
+          } else if (
+            spanProvider !== undefined &&
+            readExpansion?.value === "off" &&
+            plan.windows !== undefined &&
+            plan.windows.length > 0
+          ) {
+            // WHY: off still answers "why did this read not widen?" without touching provider work.
+            const auditSessionKey = sessionKeyFor(sessionCtx);
+            for (const group of foldWindows(plan.windows)) {
+              recordReadExpansionToggleOff(
+                auditEntryFor(
+                  { outcome: "refused", reason: "toggle_off" },
+                  group,
+                  target.file,
+                  mode,
+                ),
+                auditSessionKey,
+                readExpansion.source,
+              );
+            }
+          }
+          const effectivePlan =
+            expandedRead === undefined ? plan : { ...plan, windows: expandedRead.windows };
+          // WHY: single-window reads render as one §4.4 page (a header, no sub-banner, no
+          // WHY: continuation token): the flattening unified the old page chrome onto the header-only
+          // WHY: shape, a visible change for `files`-shaped singles that rendered the bounded-ask
+          // WHY: sub-banner at base. Multi-window reads keep their per-section headers.
+          const singlePage =
+            expandedRead !== undefined
+              ? expandedRead.windows.length === 1
+                ? expandedRead.windows[0]
+                : undefined
+              : target.windows?.length === 1 && target.windows[0]?.kind === "offset"
+                ? { offset: target.windows[0].offset, limit: target.windows[0].limit }
+                : undefined;
+          // WHY: Deep seam: one call handles kind detection, decode, normalize, hash, preview.
+          // WHY: `noPersist` defers the authoritative materialization until the served windows are
+          // WHY: known, so the snapshots + lineage + retirement + lease grants below commit as the ONE
+          // WHY: transaction spec §3.1.2 mandates instead of materializing first and leasing later.
+          const prepared = await prepareFile(target.file, cwd, {
+            ...(signal !== undefined ? { signal } : {}),
+            ...(singlePage !== undefined
+              ? { offset: singlePage.offset, limit: singlePage.limit }
+              : effectivePlan.windows !== undefined
+                ? { windows: effectivePlan.windows }
+                : {}),
+            // WHY: the served cap stays the served budget (independent of the anchor space): the paged
+            // WHY: walk still retains one anchor per hashed line (see `src/constants.ts`), so the budget
+            // WHY: survives paging — while verbatim skips the cap and the store (no anchors to bound).
+            maxLines: remainingServedLines,
+            ...(mode === "served" && store !== undefined ? { store } : {}),
+            noPersist: true,
+            render: mode,
+            ...(preloaded === undefined ? {} : { preloadedFile: preloaded }),
+          });
+          if (prepared.kind === "image") {
+            // WHY: the interception point — the image never becomes a `results` entry, so no image
+            // WHY: content enters the served / hash / snapshot / lease paths below. The lone image
+            // WHY: delegates directly to the builtin and returns its image block.
+            const imageResult = await readImageViaBuiltin(prepared.absolutePath);
+            return imageResult;
+          }
+          if (prepared.kind !== "text") throw unsupportedFile(target, prepared);
+          ordered.push({
+            kind: "file",
+            entry: {
+              file: target.file,
+              mode,
+              plan: effectivePlan,
+              ...(expandedRead === undefined
+                ? {}
+                : {
+                    widenedBlocks: expandedRead.blocks,
+                  }),
+              prepared,
+              ...(effectivePlan.omittedAll
+                ? {}
+                : {
+                    ...(prepared.truncation !== undefined
+                      ? { truncation: prepared.truncation }
+                      : {}),
+                    ...(prepared.nextOffset !== undefined
+                      ? { nextOffset: prepared.nextOffset }
+                      : {}),
+                  }),
+            },
+          });
+          // WHY: a served file draws the WHOLE file's line count off the call's budget, not its page —
+          // WHY: the paged walk retained one anchor per hashed line, which is what the budget bounds.
+          // WHY: A verbatim file takes no cap and so draws nothing.
+          if (mode === "served") remainingServedLines -= prepared.lineTotals.split;
+        }
+        const results: FileResult[] = ordered.flatMap((outcome) =>
+          outcome.kind === "file" ? [outcome.entry] : [],
+        );
+        const preparedFiles = results.filter(isPrepared);
+        for (const entry of preparedFiles) {
+          if (entry.mode !== "served" || entry.plan.omittedAll) continue;
+          const adopted = entry.prepared.statAdoption;
+          if (adopted !== undefined) {
+            // WHY: (ADR-0043) the epoch names the same bytes `fileSnap` would describe — the checksum
+            // WHY: comes from the stat-matched snapshot, so adoption does not re-hash the content just
+            // WHY: to state which version it read.
+            entry.snapshotId = adopted.snapshotId;
+            continue;
+          }
+          try {
+            entry.snapshotId = (
+              await fileSnap(
+                entry.prepared.absolutePath,
+                contentChecksum(entry.prepared.normalized),
+                entry.prepared.stats,
+              )
+            ).snapshotId;
+          } catch {
+            entry.snapshotId = undefined;
+          }
+        }
+
+        const single = results.length === 1 ? preparedFiles[0] : undefined;
+        const firstTruncation = preparedFiles.find(
+          (entry) => entry.truncation !== undefined,
+        )?.truncation;
+        const anyTruncated = firstTruncation !== undefined;
+        // WHY: a text-only call keeps the one joined text section byte-identical; with an image
+        // WHY: present the blocks aggregate in request order around the builtin's own blocks.
+        const content: RoutedContent[] = ordered.every((outcome) => outcome.kind === "file")
+          ? [{ type: "text", text: results.map(sectionText).join("\n\n") }]
+          : routedContent(ordered);
+        const metrics = {
+          truncated: anyTruncated,
+          ...(single?.nextOffset !== undefined ? { next_offset: single.nextOffset } : {}),
+        };
+
+        const servedEntries = preparedFiles.filter(
+          (entry) => entry.mode === "served" && !entry.plan.omittedAll,
+        );
+        // WHY: a verbatim-only call shares admission/normalization but must not touch served state —
+        // WHY: no lease, snapshot, epoch, drift clear, or span notification. Return before any of it.
+        if (servedEntries.length === 0) {
+          return {
+            content,
+            details:
+              single?.mode === "verbatim"
+                ? {
+                    ...(single.truncation !== undefined ? { truncation: single.truncation } : {}),
+                    ...(single.nextOffset !== undefined ? { nextOffset: single.nextOffset } : {}),
+                    metrics,
+                  }
+                : {
+                    ...(firstTruncation !== undefined ? { truncation: firstTruncation } : {}),
+                    metrics,
+                  },
+          };
+        }
+
+        const sessionKey = sessionFromContext(
+          sessionCtx,
+          servedEntries[0]!.prepared.absolutePath,
+        ).sessionKey;
+        // WHY: the materialization (spec §3.1.2 steps 4-6): the file's snapshot + lineage +
+        // WHY: retirement + served leases commit in ONE `BEGIN IMMEDIATE`, so a read can never lease
+        // WHY: anchors without its snapshot.
+        // WHY: Best-effort — a store failure never fails the read; the next call re-materializes.
+        try {
+          // WHY: (ADR-0043) a stat-matched page already names a committed snapshot: adopting it on the
+          // WHY: same identity commits the leases and mirror a materialization owns without hashing the
+          // WHY: content or splitting its lines again. A `false` (the row lost a race with a vacuum or a
+          // WHY: re-stamp) folds the entry back into the content-hash batch below, which is the only
+          // WHY: writer allowed to decide what this content's identity is.
+          const unmatched: PreparedTarget[] = [];
+          for (const entry of servedEntries) {
+            const adopted = entry.prepared.statAdoption;
+            const statKey = entry.prepared.statKey;
+            if (adopted === undefined || statKey === undefined) {
+              unmatched.push(entry);
+              continue;
+            }
+            const committed = await adoptStatSnapshotFor(
+              {
+                path: entry.prepared.absolutePath,
+                statKey,
+                snapshotHash: adopted.snapshotHash,
+              },
+              { retireLeases: true, leases: { sessionKey, rows: servedRowsOf(entry) } },
+            );
+            if (!committed) unmatched.push(entry);
+          }
+          if (unmatched.length > 0) {
+            const enrollments = await Promise.all(
+              unmatched.map(async (entry) => ({
+                descriptor: {
+                  path: entry.prepared.absolutePath,
+                  snapshotHash: snapshotHashFor(entry.prepared.normalized),
+                  lineCount: entry.prepared.lineTotals.split,
+                  hashes: await fullHashesFor(entry, store),
+                  content: entry.prepared.normalized,
+                },
+                options: {
+                  retireLeases: true,
+                  leases: { sessionKey, rows: servedRowsOf(entry) },
+                  // WHY: stamp the version this read actually observed, so the next read of an
+                  // WHY: unchanged file adopts on stat identity instead of content hashing again.
+                  ...(entry.prepared.statKey !== undefined
+                    ? { statKey: entry.prepared.statKey }
+                    : {}),
+                },
+              })),
+            );
+            await upsertSnapshotsFor(enrollments);
+          }
+        } catch (error) {
+          // SAFETY: best-effort post-read materialization — the preview rows are already computed
+          // SAFETY: and the served mirror below still records them; a missed snapshot/lease degrades
+          // SAFETY: to the fail-closed path the next edit would take anyway.
+          reportDiagnostic("read", "Failed to commit read-path snapshot materialization:", error);
+        }
+        for (const entry of servedEntries) {
+          const session = sessionFromContext(sessionCtx, entry.prepared.absolutePath);
+          const isFullRead = entry.plan.windows === undefined && entry.truncation === undefined;
+          // WHY: one file per call, so a session-write failure for the lone file stays the call's
+          // WHY: failure — the single-file contract pins it, exactly as the base multi-file code did
+          // WHY: for lone reads.
+          // WHY: mirror-only — the leases already committed in the transaction above, so no
+          // WHY: `contentHash` is passed and no third transaction remains on the read path. Canon
+          // WHY: evidence needs no write at all: it is derived from those leases (#151).
+          await session.recordEpoch({
+            rows: servedRowsOf(entry),
+            lineCount: entry.prepared.lineTotals.visible,
+            // WHY: (ADR-0043) a stat-adopted page holds only the anchors it served. A full read
+            // WHY: resolved every line (its one range is the whole file), so the array is whole exactly
+            // WHY: then; a partial read never consumes these hashes, so it passes none.
+            ...(isFullRead ? { fullReadHashes: entry.prepared.fileHashes } : {}),
+            ...(isFullRead && entry.snapshotId !== undefined
+              ? { snapshotId: entry.snapshotId }
+              : {}),
+            isFullRead,
+          });
+          if (isFullRead) await session.clearDrift();
+          // WHY: fire-and-forget by design — the seam snapshots its observers and isolates each one, so
+          // WHY: this read's return value and timing are unchanged whether or not an observer is attached.
+          notifyServedSpans({
+            filePath: entry.prepared.absolutePath,
+            spans: servedRowsToSpans(entry.prepared.served),
+            source: "read",
+            // WHY: the verbatim normalized bytes let the mirror hash caller evidence in memory instead
+            // WHY: of re-reading the file; the anchored preview is never the source of a line hash.
+            content: entry.prepared.normalized,
+          });
+        }
+        return {
+          content,
+          details: single
+            ? {
+                ...(single.truncation !== undefined ? { truncation: single.truncation } : {}),
+                ...(single.snapshotId !== undefined ? { snapshotId: single.snapshotId } : {}),
+                ...(single.nextOffset !== undefined ? { nextOffset: single.nextOffset } : {}),
+                metrics,
+              }
+            : {
+                ...(firstTruncation !== undefined ? { truncation: firstTruncation } : {}),
+                metrics,
+              },
+        };
+      } catch (error) {
+        throw withPayloadSubject(error, "read");
+      }
+    },
+  });
+}