dsh-hashline-edit 0.1.0 → 0.2.0

package/src/read.ts

@@ -1,865 +0,0 @@
-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");
-      }
-    },
-  });
-}