@arnilo/prism-tools 0.0.0-stage → 0.13.1

package/coding/src/agent/delete.ts

@@ -0,0 +1,237 @@
+import { lstat, readdir, rmdir, unlink } from "node:fs/promises";
+import type { JsonObject, ToolDefinition, ToolExecutionContext, ToolResult } from "@arnilo/prism";
+import { CODING_LOCAL_EFFECT } from "./effects.js";
+import type { ExecutionPolicy } from "./execution-policy.js";
+import { enforceExecutionPolicy } from "./execution-policy.js";
+import { withFileMutationQueue } from "./file-mutation-queue.js";
+import type { CodingLifecycleEvent } from "./lifecycle-events.js";
+import { resolveContainedMutationPath } from "./mutation-path.js";
+
+export interface MutationStat {
+  isFile(): boolean;
+  isDirectory(): boolean;
+  isSymbolicLink(): boolean;
+  size: number;
+}
+
+export interface DeleteOperations {
+  lstat: (absolutePath: string, options?: { signal?: AbortSignal }) => Promise<MutationStat>;
+  unlink: (absolutePath: string, options?: { signal?: AbortSignal }) => Promise<void>;
+  rmdir: (absolutePath: string, options?: { signal?: AbortSignal }) => Promise<void>;
+  readdir: (absolutePath: string, options?: { signal?: AbortSignal }) => Promise<readonly string[]>;
+}
+
+export interface DeleteToolOptions {
+  executionPolicy?: ExecutionPolicy;
+  operations?: DeleteOperations;
+  /** Optional consumer-gated lifecycle listener (file_changed / permission_denied). */
+  onEvent?: (event: CodingLifecycleEvent) => void;
+}
+
+// Per-call recursive-delete fan-out cap: default 10,000 entries, hard 100,000.
+// ponytail: single global constants (not tunable options) — the recursive flag is
+// per-call opt-in; hosts that need a different ceiling can deny via executionPolicy.
+const DEFAULT_MAX_RECURSIVE_DELETE_ENTRIES = 10_000;
+const HARD_MAX_RECURSIVE_DELETE_ENTRIES = 100_000;
+
+const defaultDeleteOperations: DeleteOperations = {
+  lstat: async (path) => {
+    const st = await lstat(path);
+    return {
+      isFile: () => st.isFile(),
+      isDirectory: () => st.isDirectory(),
+      isSymbolicLink: () => st.isSymbolicLink(),
+      size: st.size,
+    };
+  },
+  unlink: (path) => unlink(path).then(() => {}),
+  rmdir: (path) => rmdir(path).then(() => {}),
+  readdir: (path) => readdir(path),
+};
+
+function errorResult(toolCallId: string, message: string): ToolResult {
+  return {
+    toolCallId,
+    name: "delete",
+    content: [{ type: "text", text: message }],
+    error: { message },
+  };
+}
+
+export function createDeleteTool(cwd: string, options?: DeleteToolOptions): ToolDefinition {
+  const ops = options?.operations ?? defaultDeleteOperations;
+
+  return {
+    name: "delete",
+    kind: "delete",
+    effect: CODING_LOCAL_EFFECT,
+    effects: ["write"],
+    description:
+      "High-risk: permanently delete a single file or empty directory in the workspace. Non-empty directories are rejected unless recursive: true (opt-in per call; recursive refuses symlinked-directory traversal and enforces a per-call fan-out cap, default 10,000 entries). No trash/recycle — host undo is not automatic. Prefer edit/write when content can be fixed in place.",
+    parameters: {
+      type: "object",
+      properties: {
+        path: {
+          type: "string",
+          description: "Path to the file, empty directory, or (with recursive: true) directory tree to delete (relative or absolute)",
+        },
+        recursive: {
+          type: "boolean",
+          description:
+            "Opt-in per-call recursive directory delete (default false). Symlink children are unlinked as links, never followed; fan-out capped.",
+        },
+        maxEntries: {
+          type: "number",
+          description: `Per-call recursive fan-out cap (default ${DEFAULT_MAX_RECURSIVE_DELETE_ENTRIES}, hard ${HARD_MAX_RECURSIVE_DELETE_ENTRIES})`,
+        },
+      },
+      required: ["path"],
+      additionalProperties: false,
+    } as JsonObject,
+    async execute(args, context: ToolExecutionContext): Promise<ToolResult> {
+      const toolCallId = context.toolCallId;
+      const path = typeof args.path === "string" ? args.path : "";
+      const recursive = args.recursive === true;
+      let maxEntries = DEFAULT_MAX_RECURSIVE_DELETE_ENTRIES;
+      if (args.maxEntries !== undefined) {
+        const raw = args.maxEntries as number;
+        if (!Number.isInteger(raw) || raw < 1 || raw > HARD_MAX_RECURSIVE_DELETE_ENTRIES) {
+          return errorResult(toolCallId, `maxEntries must be an integer between 1 and ${HARD_MAX_RECURSIVE_DELETE_ENTRIES}`);
+        }
+        maxEntries = raw;
+      }
+      if (path.length === 0) {
+        return errorResult(toolCallId, "path is required and must be a non-empty string.");
+      }
+
+      try {
+        let absolutePath: string;
+        try {
+          absolutePath = await resolveContainedMutationPath(cwd, path);
+        } catch (error) {
+          const err = error as NodeJS.ErrnoException;
+          if (err.code === "ENOENT") return errorResult(toolCallId, `No such file or directory: ${path}`);
+          throw error;
+        }
+
+        const policyCheck = await enforceExecutionPolicy(
+          options?.executionPolicy,
+          {
+            kind: "delete",
+            operation: "delete",
+            paths: [absolutePath],
+            risk: "high",
+            metadata: { sessionId: context.sessionId, runId: context.runId, signal: context.signal },
+          },
+          toolCallId,
+          "delete",
+          (denied) => options?.onEvent?.({ type: "permission_denied", ...denied }),
+        );
+        if (!policyCheck.allowed) return policyCheck.result;
+        const allowedPath = policyCheck.action.paths?.[0] ?? absolutePath;
+
+        return await withFileMutationQueue(allowedPath, async () => {
+          if (context.signal?.aborted) return errorResult(toolCallId, "Operation aborted");
+
+          let st: MutationStat;
+          try {
+            st = await ops.lstat(allowedPath, { signal: context.signal });
+          } catch (error) {
+            const err = error as NodeJS.ErrnoException;
+            if (err.code === "ENOENT") return errorResult(toolCallId, `No such file or directory: ${path}`);
+            const message = error instanceof Error ? error.message : String(error);
+            return errorResult(toolCallId, message);
+          }
+
+          if (context.signal?.aborted) return errorResult(toolCallId, "Operation aborted");
+
+          if (st.isFile() || st.isSymbolicLink()) {
+            await ops.unlink(allowedPath, { signal: context.signal });
+            options?.onEvent?.({ type: "file_changed", path: allowedPath, op: "delete", toolCallId });
+            return {
+              toolCallId,
+              name: "delete",
+              content: [{ type: "text", text: `Successfully deleted ${allowedPath}` }],
+              metadata: { path: allowedPath, kind: st.isSymbolicLink() ? "symlink" : "file", bytes: st.size },
+            };
+          }
+
+          if (st.isDirectory()) {
+            const entries = await ops.readdir(allowedPath, { signal: context.signal });
+            if (entries.length > 0 && !recursive) {
+              return errorResult(
+                toolCallId,
+                `Directory is not empty: ${path}. Recursive delete is not supported (set recursive: true to opt in per call).`,
+              );
+            }
+            if (entries.length === 0) {
+              await ops.rmdir(allowedPath, { signal: context.signal });
+              options?.onEvent?.({ type: "file_changed", path: allowedPath, op: "delete", toolCallId });
+              return {
+                toolCallId,
+                name: "delete",
+                content: [{ type: "text", text: `Successfully deleted empty directory ${allowedPath}` }],
+                metadata: { path: allowedPath, kind: "directory" },
+              };
+            }
+
+            // Recursive delete: iterative post-order walk. Symlink children are
+            // UNLINKED as links and never followed — a symlinked directory can
+            // never drag the deletion outside the workspace root. The walk counts
+            // every entry against the per-call fan-out cap and checks the abort
+            // signal per entry; exceeding the cap stops with an error naming it.
+            const stack: Array<{ dir: string }> = [{ dir: allowedPath }];
+            const dirs: string[] = [allowedPath];
+            let count = 0;
+            while (stack.length > 0) {
+              if (context.signal?.aborted) {
+                return errorResult(toolCallId, `Operation aborted after deleting ${count} entries`);
+              }
+              const frame = stack.pop();
+              if (frame === undefined) break;
+              const { dir } = frame;
+              const children = await ops.readdir(dir, { signal: context.signal });
+              for (const child of children) {
+                count++;
+                if (count > maxEntries) {
+                  return errorResult(
+                    toolCallId,
+                    `Recursive delete exceeded the per-call fan-out cap of ${maxEntries} entries after deleting ${count - 1} entries; nothing beyond the cap was touched.`,
+                  );
+                }
+                const childPath = `${dir}/${child}`;
+                const childStat = await ops.lstat(childPath, { signal: context.signal });
+                if (childStat.isDirectory()) {
+                  dirs.push(childPath);
+                  stack.push({ dir: childPath });
+                } else {
+                  await ops.unlink(childPath, { signal: context.signal });
+                  options?.onEvent?.({ type: "file_changed", path: childPath, op: "delete", toolCallId });
+                }
+              }
+            }
+            // Remove directories deepest-first, then the root directory itself.
+            for (let i = dirs.length - 1; i >= 0; i--) {
+              if (context.signal?.aborted) {
+                return errorResult(toolCallId, `Operation aborted after deleting ${count} entries`);
+              }
+              await ops.rmdir(dirs[i], { signal: context.signal });
+              options?.onEvent?.({ type: "file_changed", path: dirs[i], op: "delete", toolCallId });
+            }
+            return {
+              toolCallId,
+              name: "delete",
+              content: [{ type: "text", text: `Successfully deleted ${allowedPath} (${count} entries)` }],
+              metadata: { path: allowedPath, kind: "directory", recursive: true, entriesDeleted: count },
+            };
+          }
+
+          return errorResult(toolCallId, `Unsupported file type: ${path}`);
+        });
+      } catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        return errorResult(toolCallId, message);
+      }
+    },
+  };
+}

package/coding/src/agent/diagnostics-tool.ts

@@ -0,0 +1,163 @@
+/**
+ * `diagnostics` tool: the host-configured language server's diagnostics for one file, as
+ * `path:line:col severity message`. Opt-in — no `language.servers` config means no tool and no
+ * server process. Commands come from host config only; the model supplies a path.
+ */
+
+import type { JsonObject, ToolDefinition, ToolExecutionContext, ToolResult } from "@arnilo/prism";
+import { resolveDiagnosticsLimits } from "./diagnostics.js";
+import { CODING_OBSERVATION_EFFECT } from "./effects.js";
+import type { ExecutionPolicy } from "./execution-policy.js";
+import { createLanguageIntelligence, type LanguageIntelligence, type LanguageServerSpec } from "./language/index.js";
+import { languageIdForPath } from "./language/intelligence.js";
+
+/** How long a push-only server gets to publish after the document opens. */
+const DIAGNOSTICS_SETTLE_MS = 500;
+const DIAGNOSTICS_POLL_MS = 25;
+
+export interface DiagnosticsToolOptions {
+  /** Host-configured servers, keyed by name. The model never supplies `command`. */
+  readonly servers: Readonly<Record<string, LanguageServerSpec>>;
+  /** Policy for server-initiated edits. Diagnostics reads; a rename never runs from this tool. */
+  readonly policy?: ExecutionPolicy;
+  readonly maxDiagnosticsPerFile?: number;
+  readonly maxMessageBytes?: number;
+  /** Called once per server that fails to start, so the host can warn without failing the run. */
+  readonly onServerFailure?: (server: string, message: string) => void;
+}
+
+/** The tool plus the handle that stops its servers (agent dispose, last session closed). */
+export interface DiagnosticsToolHandle {
+  readonly tool: ToolDefinition;
+  /** Stops every language server; the next call starts them again. Idempotent. */
+  dispose(): Promise<void>;
+}
+
+function errorResult(toolCallId: string, message: string): ToolResult {
+  return {
+    toolCallId,
+    name: "diagnostics",
+    content: [{ type: "text", text: message }],
+    error: { message },
+  };
+}
+
+function serverNameForFile(servers: Readonly<Record<string, LanguageServerSpec>>, file: string): string | undefined {
+  const languageId = languageIdForPath(file);
+  for (const [name, spec] of Object.entries(servers)) {
+    if (spec.languages.includes(languageId)) return name;
+  }
+  return undefined;
+}
+
+/** The fields both the LSP view and the normalized delta carry. */
+interface DiagnosticLine {
+  readonly file: string;
+  readonly line: number;
+  readonly character: number;
+  readonly severity: string;
+  readonly message: string;
+}
+
+/** LSP positions are 0-based; every other tool in this package prints 1-based lines. */
+function formatDiagnostic(diagnostic: DiagnosticLine): string {
+  return `${diagnostic.file}:${diagnostic.line + 1}:${diagnostic.character + 1} ${diagnostic.severity} ${diagnostic.message}`;
+}
+
+export function createDiagnosticsTool(cwd: string, options: DiagnosticsToolOptions): DiagnosticsToolHandle {
+  const limits = resolveDiagnosticsLimits({
+    maxDiagnosticsPerFile: options.maxDiagnosticsPerFile,
+    maxMessageBytes: options.maxMessageBytes,
+  });
+  const servers = options.servers;
+  const warned = new Set<string>();
+  let language: LanguageIntelligence | undefined;
+
+  function getLanguage(): LanguageIntelligence {
+    if (language !== undefined) return language;
+    language = createLanguageIntelligence({
+      workspaceRoot: cwd,
+      servers,
+      ...(options.policy !== undefined ? { policy: options.policy } : {}),
+    });
+    return language;
+  }
+
+  const tool: ToolDefinition = {
+    name: "diagnostics",
+    kind: "search",
+    effect: CODING_OBSERVATION_EFFECT,
+    effects: ["read"],
+    description: `Report the language server's diagnostics for one file as "path:line:col severity message" (1-based line and column). Servers are configured by the host; the first call for a language starts its server, and a server that fails to start is reported as a tool error. Use it after an edit to check the file you just wrote. Caps the diagnostic count and message length.`,
+    parameters: {
+      type: "object",
+      properties: {
+        path: { type: "string", description: "Workspace-relative file to check" },
+      },
+      required: ["path"],
+      additionalProperties: false,
+    } as JsonObject,
+    async execute(args, context: ToolExecutionContext): Promise<ToolResult> {
+      const toolCallId = context.toolCallId;
+      if (context.signal?.aborted) return errorResult(toolCallId, "Operation aborted");
+      const file = typeof args.path === "string" ? args.path : "";
+      if (file.length === 0) return errorResult(toolCallId, "path is required and must be a non-empty string.");
+
+      const server = serverNameForFile(servers, file);
+      let lang: LanguageIntelligence;
+      try {
+        lang = getLanguage();
+      } catch (error) {
+        return errorResult(toolCallId, error instanceof Error ? error.message : String(error));
+      }
+
+      try {
+        // didOpen/didChange first: push servers publish only after the document is known.
+        await lang.syncDocument(file, { signal: context.signal });
+        let diagnostics: readonly DiagnosticLine[] = [];
+        const delta = await lang.diagnosticDelta({ files: [file] }, { signal: context.signal });
+        const deltaEntry = delta.files[file];
+        if (deltaEntry !== undefined) diagnostics = [...deltaEntry.added, ...deltaEntry.unchanged];
+        if (diagnostics.length === 0) {
+          const deadline = Date.now() + DIAGNOSTICS_SETTLE_MS;
+          while (diagnostics.length === 0 && Date.now() < deadline) {
+            await new Promise((resolve) => setTimeout(resolve, DIAGNOSTICS_POLL_MS));
+            diagnostics = await lang.diagnostics(file, { signal: context.signal });
+          }
+        }
+        if (diagnostics.length === 0) {
+          return { toolCallId, name: "diagnostics", content: [{ type: "text", text: `No diagnostics for ${file}.` }] };
+        }
+        const kept = [...diagnostics].sort((a, b) => a.line - b.line || a.character - b.character || a.message.localeCompare(b.message));
+        const shown = kept.slice(0, limits.maxDiagnosticsPerFile);
+        const lines = shown.map(formatDiagnostic);
+        const more = kept.length - shown.length;
+        if (more > 0) lines.push(`(… ${more} more diagnostics)`);
+        return {
+          toolCallId,
+          name: "diagnostics",
+          content: [{ type: "text", text: lines.join("\n") }],
+          value: { file, diagnostics: shown.length, truncated: more > 0 },
+        };
+      } catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        // A server that cannot start is a host-config problem: name it once, never fail the run.
+        const name = server ?? "language server";
+        if (server !== undefined && !warned.has(server) && !message.includes("No host server registered")) {
+          warned.add(server);
+          options.onServerFailure?.(server, message);
+        }
+        return errorResult(toolCallId, `language server "${name}": ${message}`);
+      }
+    },
+  };
+
+  return {
+    tool,
+    async dispose() {
+      const current = language;
+      language = undefined;
+      if (current !== undefined) await current.dispose();
+    },
+  };
+}

package/coding/src/agent/diagnostics.ts

@@ -0,0 +1,262 @@
+/**
+ * Bounded normalization of host-parsed check diagnostics and deterministic
+ * added/removed/unchanged deltas between generations. No language/tool-
+ * specific parser catalog: hosts parse check output into RawDiagnostic and
+ * this module validates, bounds, and fingerprints it.
+ */
+
+import { isAbsolute, relative, resolve } from "node:path";
+import {
+  DEFAULT_MAX_DIAGNOSTIC_MESSAGE_BYTES,
+  DEFAULT_MAX_REVIEW_DIAGNOSTICS,
+  HARD_MAX_DIAGNOSTIC_MESSAGE_BYTES,
+  HARD_MAX_REVIEW_DIAGNOSTICS,
+  validateCodingLimit,
+} from "./limits.js";
+
+export interface ResolvedDiagnosticsLimits {
+  readonly maxDiagnosticsPerFile: number;
+  readonly maxMessageBytes: number;
+}
+
+export function resolveDiagnosticsLimits(options?: {
+  readonly maxDiagnosticsPerFile?: number;
+  readonly maxMessageBytes?: number;
+}): ResolvedDiagnosticsLimits {
+  return {
+    maxDiagnosticsPerFile: validateCodingLimit(
+      "maxDiagnosticsPerFile",
+      options?.maxDiagnosticsPerFile ?? DEFAULT_MAX_REVIEW_DIAGNOSTICS,
+      HARD_MAX_REVIEW_DIAGNOSTICS,
+    ),
+    maxMessageBytes: validateCodingLimit(
+      "maxMessageBytes",
+      options?.maxMessageBytes ?? DEFAULT_MAX_DIAGNOSTIC_MESSAGE_BYTES,
+      HARD_MAX_DIAGNOSTIC_MESSAGE_BYTES,
+    ),
+  };
+}
+
+export type DiagnosticSeverity = "error" | "warning" | "info" | "hint";
+
+export interface RawDiagnostic {
+  readonly file: string;
+  readonly line?: number;
+  readonly character?: number;
+  readonly endLine?: number;
+  readonly endCharacter?: number;
+  readonly severity?: DiagnosticSeverity;
+  readonly message: string;
+  readonly source?: string;
+  readonly code?: string | number;
+}
+
+/** Normalized diagnostic: workspace-relative file, bounded fields, generation tag. */
+export interface NormalizedDiagnostic {
+  readonly file: string;
+  readonly line: number;
+  readonly character: number;
+  readonly endLine: number;
+  readonly endCharacter: number;
+  readonly severity: DiagnosticSeverity;
+  readonly message: string;
+  readonly source: string;
+  readonly code?: string | number;
+  /** Monotonic producer generation (document version for LSP, host counter for checks). */
+  readonly generation: number;
+}
+
+export interface NormalizeDiagnosticsOptions {
+  /** Workspace root for containment; host-supplied, absolute. */
+  readonly workspaceRoot: string;
+  /** Diagnostics per file cap (default/hard 500/5000). */
+  readonly maxDiagnosticsPerFile?: number;
+  /** Message byte cap (default/hard 4096/16384). */
+  readonly maxMessageBytes?: number;
+  /** Generation stamped onto every normalized diagnostic. */
+  readonly generation: number;
+}
+
+export interface DiagnosticDelta {
+  readonly generation: number;
+  readonly added: readonly NormalizedDiagnostic[];
+  readonly removed: readonly NormalizedDiagnostic[];
+  readonly unchanged: readonly NormalizedDiagnostic[];
+  /** True when every input was deduplicated/truncated to the caps. */
+  readonly truncated: boolean;
+}
+
+export interface DiagnosticDeltaRequest {
+  /** Newest diagnostics, already normalized (generation must be >= previous). */
+  readonly next: readonly NormalizedDiagnostic[];
+  /** Prior generation view; entries older than next's generation are stale. */
+  readonly previous?: readonly NormalizedDiagnostic[];
+  /** Deterministic identity: file:source:line:character:code (default) or custom key. */
+  readonly identity?: (diagnostic: NormalizedDiagnostic) => string;
+}
+
+const CONTROL_PATTERN = /[\u0000-\u0008\u000b\u000c\u000e-\u001f\u007f]/g;
+const TRUNCATE_SUFFIX = "…";
+
+/** Stable identity key; the delta treats two diagnostics with the same key as one item. */
+export function diagnosticIdentity(diagnostic: NormalizedDiagnostic): string {
+  const code = diagnostic.code === undefined ? "" : String(diagnostic.code);
+  return `${diagnostic.file}:${diagnostic.source}:${diagnostic.line}:${diagnostic.character}:${code}`;
+}
+
+/**
+ * Validate and bound host-parsed diagnostics. Throws nothing on malformed
+ * entries: each is dropped fail-closed (never partially normalized).
+ * Out-of-workspace paths, control characters, and non-finite positions are
+ * rejected per entry; overflow charges the per-file cap.
+ */
+export function normalizeDiagnostics(raw: readonly RawDiagnostic[], options: NormalizeDiagnosticsOptions): readonly NormalizedDiagnostic[] {
+  const limits: ResolvedDiagnosticsLimits = resolveDiagnosticsLimits({
+    maxDiagnosticsPerFile: options.maxDiagnosticsPerFile,
+    maxMessageBytes: options.maxMessageBytes,
+  });
+  const root = resolve(options.workspaceRoot);
+  const perFileCounts: Record<string, number> = {};
+  const out: NormalizedDiagnostic[] = [];
+
+  for (const entry of raw) {
+    if (!entry || typeof entry !== "object") {
+      continue;
+    }
+    const file = normalizeFile(root, entry.file);
+    if (!file) {
+      continue;
+    }
+    if (typeof entry.message !== "string" || entry.message.length === 0) {
+      continue;
+    }
+    const severity = entry.severity ?? "error";
+    if (severity !== "error" && severity !== "warning" && severity !== "info" && severity !== "hint") {
+      continue;
+    }
+    const line = finiteInt(entry.line, 0);
+    const character = finiteInt(entry.character, 0);
+    const endLine = finiteInt(entry.endLine, line);
+    const endCharacter = finiteInt(entry.endCharacter, character);
+    // negative or non-finite positions are rejected, never clamped
+    if (
+      !Number.isSafeInteger(line) ||
+      !Number.isSafeInteger(character) ||
+      !Number.isSafeInteger(endLine) ||
+      !Number.isSafeInteger(endCharacter)
+    ) {
+      continue;
+    }
+    if (endLine < line || (endLine === line && endCharacter < character)) {
+      continue;
+    }
+    const message = truncateUtf8(entry.message.replace(CONTROL_PATTERN, ""), limits.maxMessageBytes);
+    if (message.length === 0) {
+      continue;
+    }
+    const code = validCode(entry.code) ? entry.code : undefined;
+    const source = truncateUtf8(String(entry.source ?? "check"), limits.maxMessageBytes);
+    const diagnostic: NormalizedDiagnostic = {
+      file,
+      line,
+      character,
+      endLine,
+      endCharacter,
+      severity,
+      message,
+      source,
+      code,
+      generation: options.generation,
+    };
+    const count = perFileCounts[file] ?? 0;
+    if (count >= limits.maxDiagnosticsPerFile) {
+      continue;
+    }
+    perFileCounts[file] = count + 1;
+    out.push(diagnostic);
+  }
+  return out;
+}
+
+/**
+ * Deterministic added/removed/unchanged delta between two diagnostic
+ * generations. Identity is `diagnosticIdentity` (file:source:position:code);
+ * message/severity changes keep the same identity and count as unchanged —
+ * the delta tracks presence, not content edits (hosts diff content on demand).
+ * Stale previous entries (generation >= next's generation) are ignored.
+ */
+export function diagnosticDelta(request: DiagnosticDeltaRequest): DiagnosticDelta {
+  const identity = request.identity ?? diagnosticIdentity;
+  const nextGeneration = request.next[0]?.generation ?? 0;
+  const nextKeys = new Map<string, NormalizedDiagnostic>();
+  const previousKeys = new Map<string, NormalizedDiagnostic>();
+  let truncated = false;
+
+  for (const d of request.next) {
+    if (!d || typeof d !== "object") {
+      truncated = true;
+      continue;
+    }
+    const key = identity(d);
+    if (nextKeys.has(key)) {
+      truncated = true;
+      continue;
+    }
+    nextKeys.set(key, d);
+  }
+  for (const d of request.previous ?? []) {
+    if (!d || typeof d !== "object") continue;
+    if (d.generation > nextGeneration) continue; // stale: newer than the new view
+    const key = identity(d);
+    if (!previousKeys.has(key)) previousKeys.set(key, d);
+  }
+
+  const added: NormalizedDiagnostic[] = [];
+  const unchanged: NormalizedDiagnostic[] = [];
+  for (const d of nextKeys.values()) {
+    (previousKeys.has(identity(d)) ? unchanged : added).push(d);
+  }
+  const removed: NormalizedDiagnostic[] = [];
+  for (const d of previousKeys.values()) {
+    if (!nextKeys.has(identity(d))) removed.push(d);
+  }
+
+  return { generation: nextGeneration, added, removed, unchanged, truncated };
+}
+
+function normalizeFile(root: string, file: unknown): string | undefined {
+  if (typeof file !== "string" || file.length === 0) return undefined;
+  if (file.includes("\0")) return undefined;
+  if (isAbsolute(file)) {
+    const rel = relative(root, file);
+    if (rel.startsWith("..") || isAbsolute(rel)) return undefined;
+    return rel.split("\\").join("/");
+  }
+  const abs = resolve(root, file);
+  const rel = relative(root, abs);
+  if (rel.startsWith("..") || isAbsolute(rel)) return undefined;
+  return rel.split("\\").join("/");
+}
+
+function finiteInt(value: unknown, fallback: number): number {
+  if (value === undefined) return fallback; // absent position defaults
+  if (typeof value !== "number" || !Number.isFinite(value)) return Number.NaN; // malformed rejected
+  const floored = Math.floor(value);
+  if (floored < 0) return Number.NaN; // negative positions rejected
+  return floored;
+}
+
+function validCode(value: unknown): value is string | number {
+  return typeof value === "string" || (typeof value === "number" && Number.isFinite(value));
+}
+
+function truncateUtf8(text: string, maxBytes: number): string {
+  let bytes = Buffer.byteLength(text, "utf8");
+  if (bytes <= maxBytes) return text;
+  let result = text;
+  while (bytes > maxBytes && result.length > 0) {
+    result = result.slice(0, result.length - 1);
+    bytes = Buffer.byteLength(result, "utf8");
+  }
+  return result + TRUNCATE_SUFFIX;
+}