dsh-hashline-edit 0.1.0 → 0.2.0

package/src/store-kernel/settings.ts

@@ -1,233 +0,0 @@
-/**
- * SAFETY: store-kernel/settings — the janitor settings ladder: read, resolve per key, name the rung.
- *
- * WHY: this lives in the kernel rather than beside the writer because the resolved settings are what the
- * WHY: maintenance pass runs on: cadence, batch width and enable/disable are open-gate policy, and a
- * WHY: resolver that drifts from the store's own knobs would throttle the wrong sweep. The file's shape
- * WHY: (keys, scopes, the atomic preserving write) stays in `store-config.ts`; this module only reads.
- * WHY: Precedence is PER KEY — env, then project file, then global file, then the default — and a file
- * WHY: that exists but cannot be used warns through `onWarn` while the values fall through.
- */
-import {
-  isRecord,
-  readScopeConfig,
-  type ConfigOnWarn,
-  type ConfigRung,
-  type ConfigScope,
-} from "../json-config.js";
-
-export type StoreJanitorMode = "on" | "off";
-
-/** Environment overrides; each wins over both files for its OWN key. */
-export const STORE_JANITOR_ENV_VAR = "PI_BETTER_EDIT_STORE_JANITOR";
-export const STORE_JANITOR_INTERVAL_ENV_VAR = "PI_BETTER_EDIT_STORE_JANITOR_INTERVAL_MS";
-export const STORE_JANITOR_BATCH_ENV_VAR = "PI_BETTER_EDIT_STORE_JANITOR_BATCH_SIZE";
-
-/**
- * WHY a day: the committed design in `src/hash-store.ts` bounds the sweep at about once a day, and
- * this interval is the only thing that decides how often an open may pay for it.
- */
-export const STORE_JANITOR_INTERVAL_DEFAULT_MS = 24 * 60 * 60 * 1000;
-
-/** WHY 64: the snapshot store already deletes in statement batches of that width (`STAT_BATCH`). */
-export const STORE_JANITOR_BATCH_DEFAULT = 64;
-
-/**
- * One resolved setting: the value the store will use, and the rung of the ladder that supplied it.
- * NOT exported on its own — the keyed shape below is the interface a caller reads, and a bare pair
- * of fields has nothing to say without the key it belongs to.
- */
-interface ResolvedStoreJanitorSetting<T> {
-  readonly value: T;
-  readonly source: ConfigRung;
-}
-
-/**
- * Every janitor setting with its rung, keyed by the same three names `StoreJanitorSettings` uses, so
- * a caller that needs to say WHERE a value came from reads the ladder's answer instead of guessing
- * it from the two files (“the project file does not have the key, so the global one must have won”
- * is a second ladder, and a wrong one as soon as a value is outside its accepted shape).
- */
-export interface ResolvedStoreJanitorSettings {
-  readonly mode: ResolvedStoreJanitorSetting<StoreJanitorMode>;
-  readonly intervalMs: ResolvedStoreJanitorSetting<number>;
-  readonly batchSize: ResolvedStoreJanitorSetting<number>;
-}
-
-export interface StoreJanitorSettings {
-  readonly mode: StoreJanitorMode;
-  readonly intervalMs: number;
-  readonly batchSize: number;
-}
-
-/** The settings ONE scope's file carries — every key optional, because the ladder resolves per key. */
-export type StoreJanitorScopeSettings = Partial<StoreJanitorSettings>;
-
-/** The values an unconfigured store gets. */
-export const STORE_JANITOR_DEFAULTS: StoreJanitorSettings = {
-  mode: "on",
-  intervalMs: STORE_JANITOR_INTERVAL_DEFAULT_MS,
-  batchSize: STORE_JANITOR_BATCH_DEFAULT,
-};
-
-// WHY: one place maps a setting to its file key, so the read path and the write path cannot spell a
-// WHY: key differently — the failure a second hand-written literal would introduce.
-const STORE_JANITOR_KEYS = {
-  mode: "janitor",
-  intervalMs: "janitorIntervalMs",
-  batchSize: "janitorBatchSize",
-} as const satisfies Record<keyof StoreJanitorSettings, string>;
-
-/**
- * The key each setting is read from and written to under `store`, for a caller that has to NAME one
- * — the `/pi-better-edit` status text labels a key with the same spelling the ladder reads it by,
- * instead of a second copy of the literal that can drift from this one.
- */
-export const STORE_JANITOR_KEY_NAMES: Readonly<Record<keyof StoreJanitorSettings, string>> =
-  STORE_JANITOR_KEYS;
-
-export function isStoreJanitorMode(value: unknown): value is StoreJanitorMode {
-  return value === "on" || value === "off";
-}
-
-/**
- * A whole number of milliseconds at least 1: a fractional, non-finite, zero or negative interval
- * cannot express a cadence, and admitting one would silently turn every open into a sweep.
- */
-export function isIntervalMs(value: unknown): value is number {
-  return typeof value === "number" && Number.isInteger(value) && value >= 1;
-}
-
-/** A whole number of rows at least 1: a batch of zero rows deletes nothing and reports success. */
-export function isBatchSize(value: unknown): value is number {
-  return typeof value === "number" && Number.isInteger(value) && value >= 1;
-}
-
-/** A trimmed environment value, or `undefined` when the variable is unset. */
-function envText(name: string): string | undefined {
-  const raw = process.env[name];
-  return raw === undefined ? undefined : raw.trim();
-}
-
-function readEnvMode(): StoreJanitorMode | undefined {
-  const mode = envText(STORE_JANITOR_ENV_VAR)?.toLowerCase();
-  return mode !== undefined && isStoreJanitorMode(mode) ? mode : undefined;
-}
-
-function readEnvIntervalMs(): number | undefined {
-  const raw = envText(STORE_JANITOR_INTERVAL_ENV_VAR);
-  if (raw === undefined) return undefined;
-  const value = Number(raw);
-  return isIntervalMs(value) ? value : undefined;
-}
-
-function readEnvBatchSize(): number | undefined {
-  const raw = envText(STORE_JANITOR_BATCH_ENV_VAR);
-  if (raw === undefined) return undefined;
-  const value = Number(raw);
-  return isBatchSize(value) ? value : undefined;
-}
-
-/** The keys one scope's file actually carries, read once so a bad file warns once per scope. */
-function readScopeSettings(
-  scope: ConfigScope,
-  cwd: string,
-  onWarn?: ConfigOnWarn,
-): StoreJanitorScopeSettings {
-  const config = readScopeConfig(scope, cwd, onWarn);
-  if (config === undefined) return {};
-  const store = config.store;
-  if (!isRecord(store)) return {};
-  const mode = store[STORE_JANITOR_KEYS.mode];
-  const intervalMs = store[STORE_JANITOR_KEYS.intervalMs];
-  const batchSize = store[STORE_JANITOR_KEYS.batchSize];
-  // WHY: with `exactOptionalPropertyTypes` an unusable key is OMITTED rather than present as
-  // WHY: `undefined`, so "this scope said nothing about it" is one state, not two.
-  return {
-    ...(isStoreJanitorMode(mode) ? { mode } : {}),
-    ...(isIntervalMs(intervalMs) ? { intervalMs } : {}),
-    ...(isBatchSize(batchSize) ? { batchSize } : {}),
-  };
-}
-
-/**
- * Both scopes' raw settings, each scope present only when its file carries at least one accepted
- * key. Pure read: never creates the directory or the file, never throws. A warning names each file
- * that exists but could not be used.
- */
-export function readStoreJanitorConfig(
-  cwd: string,
-  onWarn?: ConfigOnWarn,
-): { project?: StoreJanitorScopeSettings; global?: StoreJanitorScopeSettings } {
-  const project = readScopeSettings("project", cwd, onWarn);
-  const global = readScopeSettings("global", cwd, onWarn);
-  return {
-    ...(Object.keys(project).length > 0 ? { project } : {}),
-    ...(Object.keys(global).length > 0 ? { global } : {}),
-  };
-}
-
-/**
- * The first rung that answered, with its own name: the ladder's three ORDERS are one comparison made
- * three times, so the rung labels and the precedence order cannot drift apart as two literals.
- */
-function fromRung<T>(
-  env: T | undefined,
-  project: T | undefined,
-  global: T | undefined,
-  fallback: T,
-): ResolvedStoreJanitorSetting<T> {
-  if (env !== undefined) return { value: env, source: "env" };
-  if (project !== undefined) return { value: project, source: "project" };
-  if (global !== undefined) return { value: global, source: "global" };
-  return { value: fallback, source: "default" };
-}
-
-/**
- * The effective janitor settings WITH the rung each one came from. Precedence is PER KEY — env, then
- * project, then global, then the default — so a file that tunes one knob does not have to restate the
- * others, and a caller that reports the settings can name the rung it should blame for each one.
- * Never throws. This is the ladder itself; `resolveStoreJanitorSettings` is its value half.
- */
-export function resolveStoreJanitorSettingsWithSources(
-  cwd: string,
-  onWarn?: ConfigOnWarn,
-): ResolvedStoreJanitorSettings {
-  const config = readStoreJanitorConfig(cwd, onWarn);
-  return {
-    mode: fromRung(
-      readEnvMode(),
-      config.project?.mode,
-      config.global?.mode,
-      STORE_JANITOR_DEFAULTS.mode,
-    ),
-    intervalMs: fromRung(
-      readEnvIntervalMs(),
-      config.project?.intervalMs,
-      config.global?.intervalMs,
-      STORE_JANITOR_DEFAULTS.intervalMs,
-    ),
-    batchSize: fromRung(
-      readEnvBatchSize(),
-      config.project?.batchSize,
-      config.global?.batchSize,
-      STORE_JANITOR_DEFAULTS.batchSize,
-    ),
-  };
-}
-
-/**
- * The effective janitor settings, without their provenance. Precedence is PER KEY — env, then
- * project, then global, then the default. Never throws.
- */
-export function resolveStoreJanitorSettings(
-  cwd: string,
-  onWarn?: ConfigOnWarn,
-): StoreJanitorSettings {
-  const resolved = resolveStoreJanitorSettingsWithSources(cwd, onWarn);
-  return {
-    mode: resolved.mode.value,
-    intervalMs: resolved.intervalMs.value,
-    batchSize: resolved.batchSize.value,
-  };
-}

package/src/store.ts

@@ -1,154 +0,0 @@
-import { DatabaseSync } from "node:sqlite";
-import { withBusyRetry as hashWithBusyRetry } from "./store-kernel/index.js";
-
-interface SnapshotStore {
-  get(path: string, checksum: string, lineCount: number): string[] | undefined;
-  put(
-    path: string,
-    checksum: string,
-    lineCount: number,
-    hashes: string[],
-    updatedAt?: number,
-  ): void;
-  delete(path: string): void;
-  allHashes(): Array<{ path: string; hashes: string }>;
-  allPaths(): Array<{ path: string }>;
-}
-
-// SAFETY: large-class — cohesive store owns DB and cache as single owner; split would scatter invariants.
-export class SQLiteSnapshotStore implements SnapshotStore {
-  constructor(private readonly db: DatabaseSync) {}
-
-  get(path: string, checksum: string, lineCount: number): string[] | undefined {
-    const row = this.db
-      .prepare("SELECT hashes FROM snapshots WHERE path = ? AND checksum = ? AND line_count = ?")
-      .get(path, checksum, lineCount) as { hashes?: string } | undefined;
-    if (!row?.hashes) return undefined;
-    try {
-      const parsed = JSON.parse(row.hashes) as unknown;
-      if (Array.isArray(parsed) && parsed.every((h) => typeof h === "string")) {
-        return parsed as string[];
-      }
-      return undefined;
-    } catch {
-      return undefined;
-    }
-  }
-
-  put(
-    path: string,
-    checksum: string,
-    lineCount: number,
-    hashes: string[],
-    updatedAt: number = Date.now(),
-  ): void {
-    const stmt = this.db.prepare(
-      "INSERT INTO snapshots (path, checksum, line_count, hashes, updated_at) VALUES (?, ?, ?, ?, ?) " +
-        "ON CONFLICT(path) DO UPDATE SET checksum = excluded.checksum, line_count = excluded.line_count, hashes = excluded.hashes, updated_at = excluded.updated_at",
-    );
-    hashWithBusyRetry(() => stmt.run(path, checksum, lineCount, JSON.stringify(hashes), updatedAt));
-  }
-
-  delete(path: string): void {
-    const stmt = this.db.prepare("DELETE FROM snapshots WHERE path = ?");
-    hashWithBusyRetry(() => stmt.run(path));
-  }
-
-  allHashes(): Array<{ path: string; hashes: string }> {
-    const rows = this.db.prepare("SELECT path, hashes FROM snapshots").all() as Array<{
-      path: string;
-      hashes: string;
-    }>;
-    return rows;
-  }
-
-  allPaths(): Array<{ path: string }> {
-    const rows = this.db
-      .prepare(
-        "SELECT path FROM snapshots UNION SELECT path FROM undo UNION SELECT path FROM file_undo UNION SELECT path FROM served",
-      )
-      .all() as Array<{ path: string }>;
-    return rows;
-  }
-}
-
-type SnapshotRow = {
-  checksum: string;
-  lineCount: number;
-  hashes: string;
-  updatedAt: number;
-};
-
-// SAFETY: large-class — in-memory store mirrors SQLite shape for test isolation; cohesive and not split.
-export class MemorySnapshotStore implements SnapshotStore {
-  private readonly data = new Map<string, SnapshotRow>();
-  private readonly extraPaths = new Set<string>();
-
-  get(path: string, checksum: string, lineCount: number): string[] | undefined {
-    const row = this.data.get(path);
-    if (!row) return undefined;
-    if (row.checksum !== checksum || row.lineCount !== lineCount) return undefined;
-    try {
-      const parsed = JSON.parse(row.hashes) as unknown;
-      if (Array.isArray(parsed) && parsed.every((h) => typeof h === "string")) {
-        return parsed as string[];
-      }
-      return undefined;
-    } catch {
-      return undefined;
-    }
-  }
-
-  put(
-    path: string,
-    checksum: string,
-    lineCount: number,
-    hashes: string[],
-    updatedAt: number = Date.now(),
-  ): void {
-    this.data.set(path, {
-      checksum,
-      lineCount,
-      hashes: JSON.stringify(hashes),
-      updatedAt,
-    });
-  }
-
-  delete(path: string): void {
-    this.data.delete(path);
-  }
-
-  allHashes(): Array<{ path: string; hashes: string }> {
-    const out: Array<{ path: string; hashes: string }> = [];
-    for (const [path, row] of this.data) {
-      out.push({ path, hashes: row.hashes });
-    }
-    return out;
-  }
-
-  allPaths(): Array<{ path: string }> {
-    const seen = new Set<string>();
-    const out: Array<{ path: string }> = [];
-    for (const p of this.data.keys()) {
-      seen.add(p);
-      out.push({ path: p });
-    }
-    for (const p of this.extraPaths) {
-      if (!seen.has(p)) out.push({ path: p });
-    }
-    return out;
-  }
-
-  __seedPath(path: string): void {
-    this.extraPaths.add(path);
-  }
-
-  __getRow(path: string): SnapshotRow | undefined {
-    return this.data.get(path);
-  }
-
-  clear(): void {
-    this.data.clear();
-    this.extraPaths.clear();
-  }
-}

package/src/tui-presenter.ts

@@ -1,134 +0,0 @@
-/** SAFETY: TuiPresenter — Framework adapter owning the pi TUI boundary. Deep module EditTool never imports pi-tui; all Text/Markdown, DebouncedPreview wiring, and SAFETY casts live here. Two adapters justify the seam: TuiPresenter in prod, Headless in tests. Graded surface: public createTuiPresenter(preview) returns renderCall/renderResult ready for pi's ToolDefinition. */
-
-import { Markdown, Text } from "@earendil-works/pi-tui";
-import type { ToolDefinition } from "@earendil-works/pi-coding-agent";
-import type { TSchema } from "typebox";
-import { DebouncedPreview, PREVIEW_DEBOUNCE_MS } from "./preview-controller.js";
-import {
-  buildAppliedText,
-  mkMdTheme,
-  fmtCall,
-  fmtResultMd,
-  getPreviewInput,
-  getResultText,
-  isApplied,
-  type RPreview,
-  type RRState,
-} from "./edit-render.js";
-import type { EditDetails } from "./edit-response.js";
-
-type TuiToolDef = ToolDefinition<TSchema, EditDetails, RRState> & {
-  renderShell?: "default" | "self";
-};
-
-export function reuseText(context: unknown, content: string): Text {
-  const ctx = context as { lastComponent: unknown };
-  const t = ctx.lastComponent instanceof Text ? ctx.lastComponent : new Text("", 0, 0);
-  t.setText(content);
-  return t;
-}
-
-export function reuseMarkdown(context: unknown, content: string, theme: unknown): Markdown {
-  const ctx = context as { lastComponent: unknown };
-  const m =
-    ctx.lastComponent instanceof Markdown
-      ? ctx.lastComponent
-      : new Markdown("", 0, 0, mkMdTheme(theme as never));
-  m.setText(content);
-  return m;
-}
-
-function isErrorContext(ctx: unknown): boolean {
-  // SAFETY: pi TUI context isError is untyped at boundary — cast isolated to adapter, validated by render error path
-  return (ctx as unknown as { isError: boolean }).isError;
-}
-
-function makeRenderCall(preview: DebouncedPreview) {
-  return (args: unknown, theme: unknown, context: unknown) => {
-    const ctx = context as {
-      lastComponent: unknown;
-      state: unknown;
-      expanded: unknown;
-    };
-    // SAFETY: pi TUI renderCall expects untyped context — cast isolates to adapter, validated by pi's runtime context shape
-    preview.renderCall(ctx as unknown as Parameters<DebouncedPreview["renderCall"]>[0], args);
-    const text = (ctx.lastComponent as Text | undefined) ?? new Text("", 0, 0);
-    // SAFETY: pi context carries untyped state/expanded — cast to RRState/boolean narrowed by getPreviewInput and theme contract
-    text.setText(
-      fmtCall(
-        getPreviewInput(args),
-        (ctx as unknown as { state: RRState }).state as RRState,
-        (ctx as unknown as { expanded: boolean }).expanded,
-        theme as never,
-      ),
-    );
-    return text;
-  };
-}
-
-function makeRenderResult(preview: DebouncedPreview) {
-  return (result: unknown, opts: { isPartial: boolean }, theme: unknown, context: unknown) => {
-    const ctx = context as {
-      lastComponent: unknown;
-      state: unknown;
-      isError: boolean;
-    };
-    if (opts.isPartial)
-      return reuseText(
-        ctx,
-        (theme as { fg: (a: string, b: string) => string }).fg("warning", "Editing..."),
-      );
-    const typedResult = result as {
-      content?: Array<{ type: string; text?: string }>;
-      details?: EditDetails;
-    };
-    const renderedText = getResultText(typedResult);
-    // SAFETY: pi TUI context state is untyped at boundary — cast to RRState narrowed by preview lifecycle (covers ctx and state casts)
-    const renderState = (ctx as unknown as { state: RRState | undefined }).state as
-      | RRState
-      | undefined;
-    if (renderState) preview.clearResult(renderState);
-    if (isErrorContext(ctx))
-      return renderedText
-        ? reuseText(
-            ctx,
-            `\n${(theme as { fg: (a: string, b: string) => string }).fg("error", renderedText)}`,
-          )
-        : new Text("", 0, 0);
-    if (isApplied(typedResult.details)) {
-      const appliedText = buildAppliedText(typedResult.details, theme as never);
-      return appliedText ? reuseText(ctx, appliedText) : new Text("", 0, 0);
-    }
-    if (!renderedText) return new Text("", 0, 0);
-    return reuseMarkdown(ctx, fmtResultMd(renderedText), theme as never);
-  };
-}
-
-export interface TuiPresenter {
-  renderCall: ReturnType<typeof makeRenderCall>;
-  renderResult: ReturnType<typeof makeRenderResult>;
-  preview: DebouncedPreview;
-  /** SAFETY: Returns pi ToolDefinition-typed renders — adapter owns the SAFETY casts */
-  asToolDef(): Pick<TuiToolDef, "renderCall" | "renderResult">;
-}
-
-export function createTuiPresenter(
-  previewFn: (request: unknown, cwd: string) => Promise<RPreview>,
-  getSessionId?: () => string | undefined,
-): TuiPresenter {
-  const preview = new DebouncedPreview(previewFn, PREVIEW_DEBOUNCE_MS, getSessionId);
-  const renderCall = makeRenderCall(preview);
-  const renderResult = makeRenderResult(preview);
-  return {
-    preview,
-    renderCall,
-    renderResult,
-    asToolDef() {
-      // SAFETY: ToolDef renderCall/renderResult typed strictly by pi — casts validated by ToolDef contract, owned by framework adapter seam. `NonNullable` names the always-defined renders this adapter owns (`ToolDefinition` declares them optional).
-      return {
-        renderCall: renderCall as unknown as NonNullable<TuiToolDef["renderCall"]>,
-        renderResult: renderResult as unknown as NonNullable<TuiToolDef["renderResult"]>,
-      };
-    },
-  };
-}

package/src/write-hook.ts

@@ -1,130 +0,0 @@
-/**
- * SAFETY: Guard + auto-read seam around `write`: the `tool_call` listener refuses
- * reproduced served rows before they can reach disk.
- * Ported from dsh@0.4.1 `src/write-hook.ts` adapted to pi's FileIO/session view.
- * @module pi-better-edit/write-hook
- */
-
-import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
-import { abortIf, splitLines } from "./utils.js";
-import { resolveTarget } from "./fs-write.js";
-import { toCwd } from "./paths.js";
-import { createSessionHandle, sessionKeyFor } from "./served-session/session.js";
-import {
-  findServedHashEcho,
-  buildServedWriteMessage,
-  trackServedWriteRefusal,
-} from "./served-session/serve-render.js";
-import { reportDiagnostic } from "./diagnostics.js";
-
-export { findServedHashEcho };
-
-export interface WriteHookIO {
-  resolve(path: string, cwd: string, signal?: AbortSignal): Promise<string>;
-}
-
-/**
- * SAFETY: Inspect one validated-looking built-in write request against session-scoped
- * served state. Returns a pre-dispatch denial reason only with evidence: the
- * candidate begins with a served anchor at any position AND reproduces the
- * served content for that anchor (GLOSSARY.md served hash echo). No canon data
- * means no evidence, so the check stays silent — never a shape refusal.
- */
-export async function servedHashEchoDenial(
-  io: WriteHookIO | null | undefined,
-  rawPath: string,
-  content: string,
-  cwd: string,
-  sessionKey: string,
-  signal?: AbortSignal,
-  mode: "general" | "literal" = "general",
-): Promise<string | undefined> {
-  abortIf(signal);
-  if (mode === "literal") return undefined;
-  let absolutePath: string;
-  if (io && typeof (io as WriteHookIO).resolve === "function") {
-    absolutePath = await (io as WriteHookIO).resolve(rawPath, cwd, signal);
-  } else {
-    absolutePath = await resolveTarget(toCwd(rawPath, cwd));
-  }
-  abortIf(signal);
-  const handle = createSessionHandle(sessionKey, absolutePath);
-  const served = await handle.load();
-  let canonDigests: (string | null)[] = [];
-  try {
-    canonDigests = await handle.loadCanonDigests();
-  } catch (error) {
-    reportDiagnostic("write-hook", "Failed to load served canon digests for write:", error);
-    canonDigests = [];
-  }
-  const lines = splitLines(content);
-  const reproduction = findServedHashEcho(lines, served, canonDigests, 1);
-  if (!reproduction) return undefined;
-  const offendingLine = lines[reproduction.k - 1] ?? "";
-  // WHY: verification side of the tally: this refusal runs pre-dispatch, so no bytes move
-  // WHY: and no clear is due — the clear belongs to the committed write, which re-serves
-  // WHY: the file (`lifecycle-hooks` post-write), never to this gate.
-  const count = trackServedWriteRefusal(sessionKey, absolutePath, offendingLine);
-  return buildServedWriteMessage({
-    path: rawPath,
-    line: reproduction.line,
-    hash: reproduction.hash,
-    servedLine: reproduction.servedLine,
-    count,
-  });
-}
-
-/**
- * SAFETY: Register the pre-write served hash echo guard on the calling extension's scope.
- * The guard denies before dispatch; infrastructure failures fail open so the
- * plugin never breaks an otherwise valid write.
- */
-export function registerWriteHook(pi: ExtensionAPI): void {
-  pi.on("tool_call", async (event, ctx) => {
-    if (event.toolName !== "write") return;
-    const input = event.input as Record<string, unknown> | undefined;
-    const rawPath = input?.path as unknown;
-    const content = input?.content as unknown;
-    if (typeof rawPath !== "string" || typeof content !== "string") return;
-    // WHY: pi's builtin `write` schema tolerates the extra top-level `mode` field
-    // WHY: (verified with TypeBox `Compile`: an additional `mode?: "general" | "literal"`
-    // WHY: property passes `additionalProperties` handling on the builtin schema, so the
-    // WHY: literal declaration rides the same input object with no schema change).
-    const modeValue = (input as Record<string, unknown>)?.mode;
-    const mode: "general" | "literal" = modeValue === "literal" ? "literal" : "general";
-
-    const cwd = ctx.cwd;
-    // SAFETY: ExtensionAPI ctx carries sessionManager at runtime; cast narrows to sessionKeyFor's expected shape which is validated by sessionKeyFor's internal guards.
-    const sessionKey = sessionKeyFor(
-      ctx as unknown as { sessionManager?: { getSessionId(): string } },
-    );
-    const signal = ctx.signal;
-    try {
-      const io: WriteHookIO = {
-        resolve: async (p: string, c: string, sig?: AbortSignal) => {
-          abortIf(sig);
-          return resolveTarget(toCwd(p, c));
-        },
-      };
-      const reason = await servedHashEchoDenial(
-        io,
-        rawPath,
-        content,
-        cwd,
-        sessionKey,
-        signal,
-        mode,
-      );
-      if (reason !== undefined) {
-        return { block: true, reason };
-      }
-    } catch (error) {
-      if (signal?.aborted) throw error;
-      reportDiagnostic(
-        "write-hook",
-        `pi-better-edit: pre-write served hash guard failed open: ${error instanceof Error ? error.message : String(error)}`,
-      );
-    }
-    return;
-  });
-}