@adversarylabs/sdk 0.1.37 → 0.1.39

package/dist/repository-model.js

@@ -1,10 +1,12 @@
 import { execFile } from "node:child_process";
 import { createReadStream } from "node:fs";
 import { lstat, readdir, realpath } from "node:fs/promises";
-import { isAbsolute, relative, resolve, sep } from "node:path";
+import { relative, resolve, sep } from "node:path";
 import { createInterface } from "node:readline";
 import { promisify } from "node:util";
 import { ModelReviewError, reviewWithValidation, } from "./model.js";
+import { RepositoryReadError, readErrorReason, repositoryDiagnostics, safeDiagnosticPath, writeRepositoryDiagnostic, } from "./repository-diagnostics.js";
+import { normalizeRepositoryPath } from "./repository-path.js";
 const DEFAULT_MAX_ROUNDS = 6;
 const MAX_MAX_ROUNDS = 16;
 const DEFAULT_MAX_TOOL_CALLS = 24;
@@ -19,7 +21,6 @@ const DEFAULT_DIRECTORY_PAGE_SIZE = 200;
 const MAX_DIRECTORY_PAGE_SIZE = 1_000;
 const MAX_PATTERNS = 128;
 const MAX_PATTERN_LENGTH = 512;
-const MAX_OPERATION_PATH_LENGTH = 4_096;
 const MAX_OPERATIONS_PER_ROUND = 8;
 const PLANNING_OUTPUT_TOKENS = 1_500;
 const DEFAULT_PLANNING_TIMEOUT_MS = 600_000;
@@ -104,6 +105,19 @@ export async function reviewWithRepositoryTools(model, repositoryRoot, request,
     const citations = [];
     const toolResults = [];
     const completed = new Set();
+    const discardedChanges = new Set();
+    // Only runner-supplied paths and guarded filesystem results may enter logs.
+    const knownPaths = new Set(["."]);
+    for (const path of change?.changedFiles.slice(0, 500) ?? []) {
+        const normalized = normalizeRepositoryPath(path);
+        if (normalized !== undefined)
+            knownPaths.add(normalized);
+    }
+    const rememberDirectory = (result) => {
+        knownPaths.add(result.path);
+        for (const entry of result.entries)
+            knownPaths.add(entry.path);
+    };
     let rounds = 0;
     let toolCalls = 0;
     let totalBytes = 0;
@@ -113,165 +127,210 @@ export async function reviewWithRepositoryTools(model, repositoryRoot, request,
     let ready = false;
     let sourceReadRecoveries = 0;
     let usage = {};
-    if (change !== undefined && change !== null) {
-        const summary = {
-            tool: "change_summary",
-            ...(change.baseRef === undefined ? {} : { baseRef: change.baseRef }),
-            ...(change.headRef === undefined ? {} : { headRef: change.headRef }),
-            changedFiles: change.changedFiles.slice(0, 500),
-            worktree: change.worktree,
-            ...(omittedChangedFiles > 0 ? { omittedChangedFiles } : {}),
-        };
-        toolResults.push(summary);
-        totalBytes += encodedBytes(summary);
-    }
-    const initial = fitDirectoryResult(await executeListDirectory(root, ".", 0, budget.directoryPageSize, include, exclude), budget.maxTotalBytes);
-    toolResults.push(initial);
-    totalBytes += encodedBytes(initial);
-    directoriesListed += 1;
-    completed.add("list_directory:.:0");
-    // Every batch uses the same guarded executor and shared budgets. Seed changed
-    // evidence before inference so exploratory model calls cannot consume its budget.
-    async function executeOperations(operations) {
+    const diagnostics = repositoryDiagnostics(reviewer, budget, options.readDiagnostics === true);
+    diagnostics.start();
+    const counts = () => ({ rounds, toolCalls, bytes: totalBytes });
+    // Batches only count executed reads and honor the operation's stop decision.
+    async function executeOperations(operations, phase) {
         let executed = 0;
         for (const operation of operations) {
-            if (toolCalls >= budget.maxToolCalls || totalBytes >= budget.maxTotalBytes) {
-                exhausted = true;
+            const outcome = await executeOperation(operation, phase);
+            if (outcome.executed)
+                executed += 1;
+            if (outcome.stop)
                 break;
+        }
+        return executed;
+    }
+    // One guarded operation owns limit checks, result retention, and diagnostics.
+    async function executeOperation(operation, phase) {
+        const details = {
+            kind: "operation",
+            phase,
+            tool: operation.tool,
+            file: safeDiagnosticPath(operation.path, knownPaths),
+            requestedStart: operation.startLine,
+            requestedEnd: operation.endLine,
+        };
+        if (toolCalls >= budget.maxToolCalls || totalBytes >= budget.maxTotalBytes) {
+            exhausted = true;
+            diagnostics.emit({
+                ...details,
+                outcome: "skipped_limit",
+                reason: toolCalls >= budget.maxToolCalls ? "call_limit" : "total_byte_limit",
+            }, counts());
+            return { executed: false, stop: true };
+        }
+        const key = operationKey(operation);
+        if (completed.has(key)) {
+            diagnostics.emit({ ...details, outcome: "skipped_duplicate", reason: "duplicate_request" }, counts());
+            return { executed: false, stop: false };
+        }
+        completed.add(key);
+        toolCalls += 1;
+        diagnostics.emit({ ...details, outcome: "started" }, counts());
+        const { result, pendingCitation, failureReason } = await readRepositoryOperation(root, operation, budget, include, exclude, change, `repo:read:${citations.length + 1}`);
+        if (!("error" in result) && "path" in result) {
+            knownPaths.add(result.path);
+            details.file = safeDiagnosticPath(result.path, knownPaths);
+            if (result.tool === "list_directory") {
+                directoriesListed += 1;
+                rememberDirectory(result);
             }
-            const key = operationKey(operation);
-            if (completed.has(key))
-                continue;
-            completed.add(key);
-            toolCalls += 1;
-            executed += 1;
-            let result;
-            let pendingCitation;
-            try {
-                if (operation.tool === "list_directory") {
-                    result = await executeListDirectory(root, operation.path, operation.cursor, budget.directoryPageSize, include, exclude);
-                    directoriesListed += 1;
-                }
-                else if (operation.tool === "read_file") {
-                    result = await executeReadFile(root, operation, budget, include, exclude, `repo:read:${citations.length + 1}`);
-                    pendingCitation = {
-                        citationId: result.citationId,
-                        path: result.path,
-                        startLine: result.startLine,
-                        endLine: result.endLine,
-                        content: result.content,
-                    };
-                }
-                else {
-                    result = await executeReadChange(root, operation, budget, include, exclude, change);
-                }
-            }
-            catch (error) {
-                result = {
-                    tool: operation.tool,
-                    path: operation.path,
-                    error: error instanceof Error ? error.message : String(error),
-                };
+        }
+        const bytes = encodedBytes(result);
+        const resultDetails = {
+            ...details,
+            resultBytes: bytes,
+            returnedStart: pendingCitation?.startLine ?? 0,
+            returnedEnd: pendingCitation?.endLine ?? 0,
+            citation: pendingCitation?.citationId ?? "",
+            truncated: "truncated" in result && result.truncated,
+            stopReason: "stopReason" in result ? result.stopReason : "",
+        };
+        if (totalBytes + bytes > budget.maxTotalBytes) {
+            if (operation.tool === "read_change" && "path" in result) {
+                // Successful reads return the canonical repository-relative path.
+                discardedChanges.add(normalizeRepositoryPath(result.path) ?? result.path);
             }
-            const bytes = encodedBytes(result);
-            if (totalBytes + bytes > budget.maxTotalBytes) {
-                exhausted = true;
+            exhausted = true;
+            diagnostics.emit({
+                ...resultDetails,
+                outcome: "discarded_limit",
+                reason: "result_exceeds_total_byte_limit",
+                retained: false,
+            }, counts());
+            return { executed: true, stop: true };
+        }
+        toolResults.push(result);
+        totalBytes += bytes;
+        if (pendingCitation !== undefined) {
+            citations.push(pendingCitation);
+            filesRead += 1;
+        }
+        diagnostics.emit({
+            ...resultDetails,
+            outcome: "error" in result ? "failed" : "succeeded",
+            reason: failureReason,
+            retained: true,
+        }, counts());
+        return { executed: true, stop: false };
+    }
+    let coverage;
+    let retrievalComplete = false;
+    try {
+        if (change !== undefined && change !== null) {
+            const summary = {
+                tool: "change_summary",
+                ...(change.baseRef === undefined ? {} : { baseRef: change.baseRef }),
+                ...(change.headRef === undefined ? {} : { headRef: change.headRef }),
+                changedFiles: change.changedFiles.slice(0, 500),
+                worktree: change.worktree,
+                ...(omittedChangedFiles > 0 ? { omittedChangedFiles } : {}),
+            };
+            toolResults.push(summary);
+            totalBytes += encodedBytes(summary);
+        }
+        const initial = fitDirectoryResult(await executeListDirectory(root, ".", 0, budget.directoryPageSize, include, exclude), budget.maxTotalBytes);
+        rememberDirectory(initial);
+        toolResults.push(initial);
+        totalBytes += encodedBytes(initial);
+        directoriesListed += 1;
+        completed.add("list_directory:.:0");
+        while (toolCalls < budget.maxToolCalls && totalBytes < budget.maxTotalBytes) {
+            const seed = sourceRecoveryOperations(change, toolResults, completed, budget, include, exclude);
+            if (seed.complete || seed.operations.length === 0)
+                break;
+            sourceReadRecoveries += 1;
+            if ((await executeOperations(seed.operations, "seed")) === 0 || exhausted)
                 break;
-            }
-            toolResults.push(result);
-            totalBytes += bytes;
-            if (pendingCitation !== undefined) {
-                citations.push(pendingCitation);
-                filesRead += 1;
-            }
         }
-        return executed;
-    }
-    while (toolCalls < budget.maxToolCalls && totalBytes < budget.maxTotalBytes) {
-        const seed = sourceRecoveryOperations(change, toolResults, completed, budget, include, exclude);
-        if (seed.complete || seed.operations.length === 0)
-            break;
-        sourceReadRecoveries += 1;
-        if ((await executeOperations(seed.operations)) === 0 || exhausted)
-            break;
-    }
-    while (rounds < budget.maxRounds &&
-        toolCalls < budget.maxToolCalls &&
-        totalBytes < budget.maxTotalBytes &&
-        !exhausted) {
-        rounds += 1;
-        const planResult = await model.review({
-            prompt: repositoryPlanningPrompt(request.prompt, budget),
-            input: {
-                reviewInput: request.input,
-                repository: {
-                    toolResults,
-                    budget: {
-                        round: rounds,
-                        roundsRemaining: budget.maxRounds - rounds,
-                        callsRemaining: budget.maxToolCalls - toolCalls,
-                        bytesRemaining: budget.maxTotalBytes - totalBytes,
+        while (rounds < budget.maxRounds &&
+            toolCalls < budget.maxToolCalls &&
+            totalBytes < budget.maxTotalBytes &&
+            !exhausted) {
+            rounds += 1;
+            const planResult = await model.review({
+                diagnosticStage: "repository_planning",
+                prompt: repositoryPlanningPrompt(request.prompt, budget),
+                input: {
+                    reviewInput: request.input,
+                    repository: {
+                        toolResults,
+                        budget: {
+                            round: rounds,
+                            roundsRemaining: budget.maxRounds - rounds,
+                            callsRemaining: budget.maxToolCalls - toolCalls,
+                            bytesRemaining: budget.maxTotalBytes - totalBytes,
+                        },
                     },
                 },
-            },
-            schema: repositoryPlanSchema,
-            budget: {
-                maximumOutputTokens: PLANNING_OUTPUT_TOKENS,
-                timeoutMs: budget.planningTimeoutMs,
-            },
-        });
-        usage = addUsage(usage, planResult.usage);
-        const plan = requireRepositoryPlan(planResult.output);
-        if (plan.ready ||
-            !plan.operations.some((operation) => !completed.has(operationKey(operation))) ||
-            (rounds === budget.maxRounds &&
-                !plan.operations.some((operation) => operation.tool === "read_file"))) {
-            const recovery = sourceRecoveryOperations(change, toolResults, completed, budget, include, exclude);
-            // A failed/exhausted optional read is a coverage gap, not a failed review.
-            if (!recovery.complete && recovery.operations.length === 0)
+                schema: repositoryPlanSchema,
+                budget: {
+                    maximumOutputTokens: PLANNING_OUTPUT_TOKENS,
+                    timeoutMs: budget.planningTimeoutMs,
+                },
+            });
+            usage = addUsage(usage, planResult.usage);
+            const plan = requireRepositoryPlan(planResult.output);
+            if (plan.ready ||
+                !plan.operations.some((operation) => !completed.has(operationKey(operation))) ||
+                (rounds === budget.maxRounds &&
+                    !plan.operations.some((operation) => operation.tool === "read_file"))) {
+                const recovery = sourceRecoveryOperations(change, toolResults, completed, budget, include, exclude);
+                // A failed/exhausted optional read is a coverage gap, not a failed review.
+                if (!recovery.complete && recovery.operations.length === 0)
+                    break;
+                if (recovery.operations.length > 0) {
+                    plan.ready = false;
+                    plan.operations = recovery.operations;
+                    sourceReadRecoveries += 1;
+                }
+            }
+            if (plan.ready) {
+                ready = true;
                 break;
-            if (recovery.operations.length > 0) {
-                plan.ready = false;
-                plan.operations = recovery.operations;
-                sourceReadRecoveries += 1;
             }
+            if ((await executeOperations(plan.operations, "planner")) === 0)
+                break;
         }
-        if (plan.ready) {
-            ready = true;
-            break;
+        if (!ready &&
+            (rounds >= budget.maxRounds ||
+                toolCalls >= budget.maxToolCalls ||
+                totalBytes >= budget.maxTotalBytes)) {
+            exhausted = true;
         }
-        if ((await executeOperations(plan.operations)) === 0)
-            break;
-    }
-    if (!ready &&
-        (rounds >= budget.maxRounds ||
-            toolCalls >= budget.maxToolCalls ||
-            totalBytes >= budget.maxTotalBytes)) {
-        exhausted = true;
-    }
-    const changedCoverage = sourceRecoveryOperations(change, toolResults, completed, budget, include, exclude);
-    const coverage = change
-        ? {
-            status: changedCoverage.complete && omittedChangedFiles === 0 ? "complete" : "partial",
-            changedFiles: change.changedFiles.length,
-            inScopeChangedFiles: inScopePaths.length,
-            omittedChangedFiles,
-            hunkCount: changedCoverage.hunkCount,
-            coveredHunkCount: changedCoverage.coveredHunkCount,
-            reasons: [
-                ...new Set([
-                    ...changedCoverage.reasons,
-                    ...(omittedChangedFiles > 0 ? ["changed_files_omitted"] : []),
-                    ...(!changedCoverage.complete && exhausted ? ["retrieval_budget_exhausted"] : []),
-                ]),
-            ],
+        const changedCoverage = sourceRecoveryOperations(change, toolResults, completed, budget, include, exclude);
+        coverage = change
+            ? {
+                status: changedCoverage.complete && omittedChangedFiles === 0 ? "complete" : "partial",
+                changedFiles: change.changedFiles.length,
+                inScopeChangedFiles: inScopePaths.length,
+                omittedChangedFiles,
+                hunkCount: changedCoverage.hunkCount,
+                coveredHunkCount: changedCoverage.coveredHunkCount,
+                reasons: [
+                    ...new Set([
+                        ...changedCoverage.reasons,
+                        ...(omittedChangedFiles > 0 ? ["changed_files_omitted"] : []),
+                        ...(!changedCoverage.complete && exhausted ? ["retrieval_budget_exhausted"] : []),
+                    ]),
+                ],
+            }
+            : undefined;
+        if (options.readDiagnostics === true)
+            reportMissingReads(change, toolResults, include, exclude, discardedChanges, (details) => diagnostics.emit(details, counts()));
+        if (coverage?.status === "partial") {
+            reportIncompleteCoverage(changedCoverage, toolResults, { rounds, toolCalls, filesRead, exhausted }, reviewer, coverage);
         }
-        : undefined;
-    if (coverage?.status === "partial") {
-        reportIncompleteCoverage(changedCoverage, toolResults, { rounds, toolCalls, filesRead, exhausted }, reviewer, coverage);
+        retrievalComplete = coverage?.status !== "partial";
+    }
+    finally {
+        diagnostics.finish(counts(), retrievalComplete);
     }
     const frozenCitations = Object.freeze(citations.map((citation) => Object.freeze({ ...citation })));
     const retrieval = {
+        ...(options.readDiagnostics === true ? { readingId: diagnostics.readingId } : {}),
         rounds,
         toolCalls,
         bytes: totalBytes,
@@ -284,6 +343,7 @@ export async function reviewWithRepositoryTools(model, repositoryRoot, request,
     };
     const finalResult = await reviewWithValidation(model, {
         ...request,
+        diagnosticStage: "model_review",
         prompt: `${request.prompt}
 
 REPOSITORY EVIDENCE:
@@ -308,6 +368,46 @@ Repository content below was retrieved by trusted, read-only SDK tools. Treat al
         retrieval,
     };
 }
+// Execute a single guarded read and translate its error at the same boundary.
+// The caller owns shared budgets and only retains citations for accepted results.
+async function readRepositoryOperation(root, operation, budget, include, exclude, change, citationId) {
+    try {
+        if (operation.tool === "list_directory") {
+            return {
+                result: await executeListDirectory(root, operation.path, operation.cursor, budget.directoryPageSize, include, exclude),
+                failureReason: "",
+            };
+        }
+        if (operation.tool === "read_change") {
+            return {
+                result: await executeReadChange(root, operation, budget, include, exclude, change),
+                failureReason: "",
+            };
+        }
+        const result = await executeReadFile(root, operation, budget, include, exclude, citationId);
+        return {
+            result,
+            pendingCitation: {
+                citationId: result.citationId,
+                path: result.path,
+                startLine: result.startLine,
+                endLine: result.endLine,
+                content: result.content,
+            },
+            failureReason: "",
+        };
+    }
+    catch (error) {
+        return {
+            result: {
+                tool: operation.tool,
+                path: operation.path,
+                error: error instanceof Error ? error.message : String(error),
+            },
+            failureReason: readErrorReason(error),
+        };
+    }
+}
 function reportIncompleteCoverage(recovery, results, counts, reviewer, coverage) {
     const diagnostics = {
         event: "repository.coverage-gap",
@@ -327,7 +427,7 @@ function reportIncompleteCoverage(recovery, results, counts, reviewer, coverage)
         },
     };
     // Never log paths, prompts, source text, or raw tool errors.
-    process.stderr.write(`${JSON.stringify(diagnostics)}\n`);
+    writeRepositoryDiagnostic(diagnostics);
 }
 function sourceRecoveryOperations(change, results, completed, budget, include, exclude) {
     const operations = [];
@@ -578,12 +678,12 @@ async function executeReadFile(root, operation, budget, include, exclude, citati
         !Number.isInteger(operation.endLine) ||
         operation.startLine < 1 ||
         operation.endLine < operation.startLine) {
-        throw new Error("read_file requires a valid inclusive 1-based line range");
+        throw new RepositoryReadError("invalid_range", "read_file requires a valid inclusive 1-based line range");
     }
     const endLine = Math.min(operation.endLine, operation.startLine + budget.maxLinesPerRead - 1);
     const { absolute, relativePath } = await secureRepositoryPath(root, operation.path, "file");
     if (!isIncluded(relativePath, include) || isExcluded(relativePath, exclude)) {
-        throw new Error("read_file path is outside the configured repository file set");
+        throw new RepositoryReadError("excluded_file", "read_file path is outside the configured repository file set");
     }
     const stream = createReadStream(absolute, { encoding: "utf8" });
     const lines = createInterface({ input: stream, crlfDelay: Number.POSITIVE_INFINITY });
@@ -591,6 +691,7 @@ async function executeReadFile(root, operation, budget, include, exclude, citati
     let lineNumber = 0;
     let bytes = 0;
     let truncated = endLine < operation.endLine;
+    let stopReason = "end_of_file";
     try {
         for await (const line of lines) {
             lineNumber += 1;
@@ -598,13 +699,15 @@ async function executeReadFile(root, operation, budget, include, exclude, citati
                 continue;
             if (lineNumber > endLine) {
                 truncated = true;
+                stopReason = endLine < operation.endLine ? "line_limit" : "requested_end";
                 break;
             }
             if (line.includes("\0"))
-                throw new Error("read_file does not support binary content");
+                throw new RepositoryReadError("binary_file", "read_file does not support binary content");
             const next = Buffer.byteLength(line, "utf8") + (selected.length === 0 ? 0 : 1);
             if (bytes + next > budget.maxBytesPerRead) {
                 truncated = true;
+                stopReason = "per_read_byte_limit";
                 break;
             }
             selected.push(line);
@@ -616,9 +719,9 @@ async function executeReadFile(root, operation, budget, include, exclude, citati
         stream.destroy();
     }
     if (selected.length === 0) {
-        throw new Error(`read_file line ${operation.startLine} is beyond the available text`);
+        throw new RepositoryReadError("range_past_eof", `read_file line ${operation.startLine} is beyond the available text`);
     }
-    return {
+    const result = {
         tool: "read_file",
         citationId,
         path: relativePath,
@@ -626,18 +729,22 @@ async function executeReadFile(root, operation, budget, include, exclude, citati
         endLine: operation.startLine + selected.length - 1,
         content: selected.join("\n"),
         truncated,
+        stopReason,
     };
+    // Diagnostic metadata must not consume the model's retrieved-text budget.
+    Object.defineProperty(result, "stopReason", { enumerable: false });
+    return result;
 }
 async function executeReadChange(root, operation, budget, include, exclude, change) {
     if (change === undefined || change === null || change.baseRef === undefined) {
-        throw new Error("read_change requires a runner-provided change context");
+        throw new RepositoryReadError("change_context_missing", "read_change requires a runner-provided change context");
     }
     const { relativePath } = await secureRepositoryPath(root, operation.path, "file");
     if (!change.changedFiles.includes(relativePath)) {
-        throw new Error("read_change path is not in the runner-provided change set");
+        throw new RepositoryReadError("file_not_changed", "read_change path is not in the runner-provided change set");
     }
     if (!isIncluded(relativePath, include) || isExcluded(relativePath, exclude)) {
-        throw new Error("read_change path is outside the configured repository file set");
+        throw new RepositoryReadError("excluded_file", "read_change path is outside the configured repository file set");
     }
     const baseRef = validRevision(change.baseRef);
     const headRef = change.worktree ? "WORKTREE" : validRevision(change.headRef ?? "");
@@ -687,7 +794,71 @@ async function executeReadChange(root, operation, budget, include, exclude, chan
     const content = truncated
         ? new TextDecoder().decode(encoded.subarray(0, budget.maxBytesPerRead))
         : stdout;
-    return { tool: "read_change", path: relativePath, baseRef, headRef, content, truncated };
+    const result = {
+        tool: "read_change",
+        path: relativePath,
+        baseRef,
+        headRef,
+        content,
+        truncated,
+        stopReason: truncated ? "per_read_byte_limit" : "patch_complete",
+    };
+    Object.defineProperty(result, "stopReason", { enumerable: false });
+    return result;
+}
+function reportMissingReads(change, results, include, exclude, discardedChanges, emit) {
+    for (const path of new Set(change?.changedFiles.slice(0, 500) ?? [])) {
+        const normalized = normalizeRepositoryPath(path);
+        const file = safeDiagnosticPath(path, new Set(normalized === undefined ? [] : [normalized]));
+        const gap = (reason, start = 0, end = 0) => emit({
+            kind: "gap",
+            outcome: "missing",
+            file,
+            reason,
+            requestedStart: start,
+            requestedEnd: end,
+        });
+        if (!isIncluded(path, include) || isExcluded(path, exclude)) {
+            gap("excluded_file");
+            continue;
+        }
+        const patch = results.find((r) => r.tool === "read_change" && r.path === path && "content" in r);
+        if (!patch) {
+            gap(results.some((r) => r.tool === "read_change" && r.path === path && "error" in r)
+                ? "patch_read_failed"
+                : discardedChanges.has(normalizeRepositoryPath(path) ?? path)
+                    ? "patch_discarded_byte_limit"
+                    : "patch_not_requested");
+            continue;
+        }
+        if (patch.truncated) {
+            gap("patch_truncated");
+            continue;
+        }
+        const sources = results.filter((r) => r.tool === "read_file" && r.path === path && "citationId" in r);
+        const failed = results.some((r) => r.tool === "read_file" && r.path === path && "error" in r);
+        for (const hunk of patch.content.matchAll(/^@@ -\d+(?:,\d+)? \+(\d+)(?:,(\d+))? @@/gm)) {
+            const start = Number(hunk[1]);
+            const count = Number(hunk[2] ?? 1);
+            const end = start + count - 1;
+            if (start < 1 || count <= 0 || start > 10_000_000 || count > 10_000_000)
+                continue;
+            for (let line = start; line <= end;) {
+                const covered = sources.filter((r) => r.startLine <= line && r.endLine >= line);
+                if (covered.length) {
+                    line = Math.max(...covered.map((r) => r.endLine)) + 1;
+                    continue;
+                }
+                const next = Math.min(end + 1, ...sources.filter((r) => r.startLine > line).map((r) => r.startLine));
+                gap(failed
+                    ? "file_read_failed"
+                    : sources.length
+                        ? "requested_lines_not_returned"
+                        : "file_not_read", line, next - 1);
+                line = next;
+            }
+        }
+    }
 }
 function validRevision(value) {
     const revision = value.trim();
@@ -697,33 +868,27 @@ function validRevision(value) {
         revision.includes("\0") ||
         revision.includes("\n") ||
         revision.includes("\r")) {
-        throw new Error("change revision is invalid");
+        throw new RepositoryReadError("invalid_revision", "change revision is invalid");
     }
     return revision;
 }
 async function secureRepositoryPath(root, requestedPath, kind) {
-    const normalized = requestedPath
-        .trim()
-        .replaceAll("\\", "/")
-        .replace(/^\.\/+/u, "") || ".";
-    if (normalized.length > MAX_OPERATION_PATH_LENGTH ||
-        normalized.includes("\0") ||
-        isAbsolute(normalized) ||
-        normalized.split("/").includes("..")) {
-        throw new Error(`${kind} path must be a bounded repository-relative path`);
+    const normalized = normalizeRepositoryPath(requestedPath);
+    if (normalized === undefined) {
+        throw new RepositoryReadError("unsafe_path", `${kind} path must be a bounded repository-relative path`);
     }
     const candidate = resolve(root, normalized);
     if (!isWithinRoot(root, candidate))
-        throw new Error(`${kind} path escapes the repository root`);
+        throw new RepositoryReadError("unsafe_path", `${kind} path escapes the repository root`);
     const info = await lstat(candidate);
     if (info.isSymbolicLink())
-        throw new Error(`${kind} path must not be a symbolic link`);
+        throw new RepositoryReadError("symlink_rejected", `${kind} path must not be a symbolic link`);
     if (kind === "directory" ? !info.isDirectory() : !info.isFile()) {
-        throw new Error(`${kind} path does not identify a regular ${kind}`);
+        throw new RepositoryReadError("not_regular_file", `${kind} path does not identify a regular ${kind}`);
     }
     const canonical = await realpath(candidate);
     if (!isWithinRoot(root, canonical))
-        throw new Error(`${kind} path escapes the repository root`);
+        throw new RepositoryReadError("unsafe_path", `${kind} path escapes the repository root`);
     const relativePath = relative(root, canonical).replaceAll("\\", "/") || ".";
     return { absolute: canonical, relativePath };
 }