clinkx 0.3.0 → 1.0.0

package/dist/context-builder/refine-handler.js

@@ -0,0 +1,790 @@
+import { createHash } from "node:crypto";
+import { readFile as fsReadFile, realpath as fsRealpath, stat as fsStat, } from "node:fs/promises";
+import path from "node:path";
+import { zodToJsonSchema } from "zod-to-json-schema";
+import { isSamePathOrDescendant, parseAllowedRootsEnv } from "../allowed-roots.js";
+import { CancellationError, InvalidParamsError } from "../errors.js";
+import { logger } from "../logger.js";
+import { writeContextBuilderFinalArtifacts, } from "./bundle.js";
+import { CONTEXT_BUILDER_INTERNAL_CAP_DEFAULTS, getSharedContextBuilderSemaphore, resolveContextBuilderRunsDir, } from "./config.js";
+import { splitTextLines, } from "./discovery.js";
+import { resolveContextBuilderRoots } from "./paths.js";
+import { createContextBuilderReceiptTextResponse, } from "./receipt.js";
+import { generateContextBuilderRunId } from "./run-id.js";
+import { recordContextRunCatalogMarker } from "./context-run-catalog.js";
+import { appendLifecycleCompletionWarning } from "./lifecycle-recovery.js";
+import { withContextBuilderWriteWatchdog } from "./write-watchdog.js";
+import { normalizeContextBuilderPublicBudget, RefineContextRunInputSchema, } from "./schema.js";
+import { coalesceRanges, } from "./slice-range-math.js";
+import { resolveAllowSecrets, sanitizeHighConfidenceSecretContent, scanSecretPath, } from "./secrets.js";
+import { cleanupContextBuilderIncompleteRun, createContextBuilderRun, resolveContextBuilderRunPaths, } from "./storage.js";
+import { estimateContextBuilderTokensFromUtf8Bytes } from "./token-estimate.js";
+import { ContextBuilderLifecycleController, ContextBuilderLifecycleObserverError, } from "./lifecycle-observer.js";
+import { createContextBuilderLifecycleJournal } from "./lifecycle-journal.js";
+export async function handleRefineContextRun(args, options = {}) {
+    const input = parseRefineContextRunInput(args);
+    const semaphore = options.semaphore ?? getDefaultRefineSemaphore();
+    semaphore.acquire();
+    let lifecycle;
+    let storage;
+    let committed = false;
+    try {
+        // Resolve the runs dir up front so a broad/forbidden runs_dir is rejected
+        // with its canonical error before any lifecycle transition, and so the
+        // journal reuses this one already-validated path.
+        const runsDir = await resolveContextBuilderRunsDir(options.runsDir);
+        // A refine operation that owns its lifecycle (no injected observer) persists
+        // authoritatively through the .context-runs journal.
+        const journal = options.lifecycle == null
+            ? createContextBuilderLifecycleJournal({
+                runsDir,
+                resolveRunsDir: async () => runsDir,
+            })
+            : undefined;
+        lifecycle = new ContextBuilderLifecycleController({
+            operationKind: "refine",
+            execution: {
+                curator: { configured: false, enabled: false },
+                finalizer: { configured: false, enabled: false },
+            },
+            ...(options.lifecycle != null
+                ? {
+                    observer: options.lifecycle.observer,
+                    ...(options.lifecycle.origin == null
+                        ? {}
+                        : { origin: options.lifecycle.origin }),
+                }
+                : journal == null
+                    ? {}
+                    : { observer: journal.observe }),
+            ...(options.now == null ? {} : { now: options.now }),
+        });
+        await lifecycle?.transition("resolving");
+        await lifecycle?.transition("validating");
+        const allowSecrets = resolveAllowSecrets(input.allow_secrets ?? options.allowSecrets);
+        const priorStorage = resolveContextBuilderRunPaths(runsDir, input.prior_run_id);
+        const priorManifest = await readPriorManifest(priorStorage.manifestJson);
+        const roots = await validatePriorRoots(priorManifest);
+        const selection = reconstructSelection(priorManifest);
+        applyRefineOps(selection, input.ops, roots);
+        await lifecycle?.transition("selecting");
+        const createdAt = (options.now?.() ?? new Date()).toISOString();
+        const runId = generateContextBuilderRunId();
+        const internalCaps = options.internalCaps ?? CONTEXT_BUILDER_INTERNAL_CAP_DEFAULTS;
+        const budget = normalizeManifestBudget(priorManifest);
+        const priorFingerprints = priorFingerprintMap(priorManifest);
+        const warnings = [];
+        const omissions = [];
+        const materialized = await materializeSelection({
+            selection: [...selection.values()],
+            roots,
+            budget,
+            priorFingerprints,
+            warnings,
+            omissions,
+            allowSecrets,
+            ...(options.signal == null ? {} : { signal: options.signal }),
+        });
+        const budgeted = applyBudget({
+            files: materialized,
+            budget,
+            omissions,
+        });
+        const metrics = buildMetrics({
+            consideredCount: selection.size,
+            rawBytesRead: materialized.reduce((total, file) => total + file.rawByteLength, 0),
+            selected: budgeted.selected,
+            omittedCount: omissions.length,
+        });
+        const renderInput = {
+            run_id: runId,
+            created_at: createdAt,
+            task: `Refine context_builder run ${input.prior_run_id}`,
+            allowSecrets,
+            roots,
+            inputs: {
+                prior_run_id: input.prior_run_id,
+                ops: input.ops,
+                resolved_budget: budget,
+            },
+            budget,
+            internal_caps: internalCaps,
+            tree: budgeted.tree,
+            search: [],
+            slices: budgeted.slices,
+            selected_context: budgeted.selected,
+            omissions,
+            warnings,
+            metrics,
+            open_questions: [],
+            observability: {
+                curator_ms: null,
+                finalizer_ms: null,
+                candidate_pool_size: materialized.length,
+                // Deprecated alias of delegate_packet_estimated_tokens (see
+                // ContextBuilderObservabilityMetrics); refine runs never build a packet.
+                delegate_packet_size: 0,
+                delegate_packet_estimated_tokens: 0,
+            },
+            parent_run_id: input.prior_run_id,
+            refine_ops: input.ops,
+            file_fingerprints: budgeted.fingerprints,
+        };
+        await lifecycle?.transition("writing", {
+            artifactRunId: runId,
+            counts: lifecycleCounts(metrics),
+        });
+        const writingStorage = await createContextBuilderRun({
+            runsDir,
+            runId,
+            createdAt,
+        });
+        storage = writingStorage;
+        const committingLifecycle = lifecycle;
+        const receipt = await withContextBuilderWriteWatchdog((signal) => writeContextBuilderFinalArtifacts(writingStorage, {
+            ...renderInput,
+            debug: true,
+            debug_diagnostics: {
+                counters: {
+                    parent_run_id_recorded: 1,
+                },
+            },
+        }, {
+            signal,
+            ...(writingStorage.ownerNonce == null ? {} : { ownerNonce: writingStorage.ownerNonce }),
+            // Capture into a const so the closure keeps the narrowed non-undefined
+            // type (the outer binding is a reassignable let).
+            ...(committingLifecycle == null
+                ? {}
+                : { beforeManifestCommit: () => committingLifecycle.transition("committing") }),
+        }), options.signal == null ? {} : { signal: options.signal });
+        committed = true;
+        await recordContextRunCatalogMarker({
+            runsDir,
+            kind: "artifact",
+            id: receipt.run_id,
+            createdAt,
+        }).catch(() => {
+            logger.warn({ contextRunId: receipt.run_id }, "context run catalog marker write failed");
+        });
+        let responseReceipt = receipt;
+        try {
+            await lifecycle?.complete(receipt.status, {
+                artifactRunId: receipt.run_id,
+                counts: lifecycleCounts(receipt.metrics),
+            });
+        }
+        catch (error) {
+            if (!(error instanceof ContextBuilderLifecycleObserverError))
+                throw error;
+            logger.warn({ contextRunId: lifecycle?.contextRunId }, "context run lifecycle completion unavailable after retry");
+            responseReceipt = appendLifecycleCompletionWarning(receipt, internalCaps.max_warnings);
+        }
+        return createContextBuilderReceiptTextResponse(responseReceipt);
+    }
+    catch (error) {
+        if (storage != null && !committed && storage.ownerNonce != null) {
+            await cleanupContextBuilderIncompleteRun(storage, storage.ownerNonce).catch(() => { });
+        }
+        if (lifecycle != null && !(error instanceof ContextBuilderLifecycleObserverError)) {
+            const cancelled = error instanceof CancellationError || options.signal?.aborted === true;
+            await lifecycle.fail(cancelled ? "cancelled" : "failed", {
+                reasonCodes: [cancelled ? "operation_cancelled" : "internal_failure"],
+            });
+        }
+        throw error;
+    }
+    finally {
+        semaphore.release();
+    }
+}
+function lifecycleCounts(metrics) {
+    return {
+        files_seen: metrics.files_seen,
+        files_considered: metrics.files_considered,
+        files_selected: metrics.files_selected,
+        files_omitted: metrics.files_omitted,
+        search_results: 0,
+        bytes_read: metrics.bytes_read,
+        bytes_written: metrics.bytes_written,
+    };
+}
+export function refineContextRunJsonSchema() {
+    return zodToJsonSchema(RefineContextRunInputSchema, {
+        target: "jsonSchema7",
+        $refStrategy: "none",
+    });
+}
+function parseRefineContextRunInput(input) {
+    const result = RefineContextRunInputSchema.safeParse(input);
+    if (!result.success) {
+        throw new InvalidParamsError(`Invalid refine_context_run input: ${result.error.issues
+            .map((issue) => issue.message)
+            .join("; ")}`);
+    }
+    return result.data;
+}
+async function readPriorManifest(manifestPath) {
+    try {
+        return JSON.parse(await fsReadFile(manifestPath, "utf8"));
+    }
+    catch {
+        throw new InvalidParamsError("refine_context_run prior_run_id does not identify a readable context_builder run");
+    }
+}
+async function validatePriorRoots(manifest) {
+    const roots = manifestRoots(manifest);
+    const resolution = await resolveContextBuilderRoots(roots.map((root) => root.path), {
+        allowedRoots: parseAllowedRootsEnv({ includeArtifactOnly: false }),
+    });
+    return resolution.roots.map((root) => ({
+        root_index: root.root_index,
+        input_path: roots[root.root_index]?.input_path ?? root.input_path,
+        path: root.path,
+    }));
+}
+function manifestRoots(manifest) {
+    const raw = manifest["roots"];
+    if (!Array.isArray(raw) || raw.length === 0) {
+        throw new InvalidParamsError("refine_context_run prior manifest has no recorded roots");
+    }
+    return raw
+        .map((entry) => {
+        if (!isRecord(entry) || typeof entry["path"] !== "string") {
+            throw new InvalidParamsError("refine_context_run prior manifest root entry is invalid");
+        }
+        return {
+            root_index: typeof entry["root_index"] === "number" ? entry["root_index"] : 0,
+            ...(typeof entry["input_path"] === "string"
+                ? { input_path: entry["input_path"] }
+                : {}),
+            path: entry["path"],
+        };
+    })
+        .sort((left, right) => left.root_index - right.root_index);
+}
+function reconstructSelection(manifest) {
+    const raw = manifest["selected_context"];
+    if (!Array.isArray(raw)) {
+        throw new InvalidParamsError("refine_context_run prior manifest selected_context is invalid");
+    }
+    const selection = new Map();
+    for (const entry of raw) {
+        const selected = parseManifestSelectedFile(entry);
+        const selectionEntry = {
+            root_index: selected.root_index,
+            path: selected.path,
+            ranges: coalesceRanges(selected.ranges ?? []),
+            disposition: selected.disposition ?? "slices",
+        };
+        selection.set(selectionKey(selectionEntry), selectionEntry);
+    }
+    return selection;
+}
+function selectionKey(entry) {
+    return fingerprintKey(entry);
+}
+function parseManifestSelectedFile(input) {
+    if (!isRecord(input) ||
+        typeof input["root_index"] !== "number" ||
+        typeof input["path"] !== "string") {
+        throw new InvalidParamsError("refine_context_run prior manifest selected_context entry is invalid");
+    }
+    return {
+        root_index: input["root_index"],
+        path: normalizeRefinePath(input["path"]),
+        ranges: Array.isArray(input["ranges"])
+            ? input["ranges"].map(parseManifestRange)
+            : [],
+        ...(typeof input["bytes"] === "number" ? { bytes: input["bytes"] } : {}),
+        ...(typeof input["estimated_tokens"] === "number"
+            ? { estimated_tokens: input["estimated_tokens"] }
+            : {}),
+        ...(input["source"] === "focus" || input["source"] === "search"
+            ? { source: input["source"] }
+            : {}),
+        ...(isSelectionDisposition(input["disposition"])
+            ? { disposition: input["disposition"] }
+            : {}),
+    };
+}
+function parseManifestRange(input) {
+    if (!isRecord(input) ||
+        typeof input["start_line"] !== "number" ||
+        typeof input["end_line"] !== "number") {
+        throw new InvalidParamsError("refine_context_run prior manifest selected range is invalid");
+    }
+    return {
+        start_line: input["start_line"],
+        end_line: input["end_line"],
+    };
+}
+function applyRefineOps(selection, ops, roots) {
+    for (const op of ops) {
+        switch (op.op) {
+            case "add":
+                if (op.mode === "slices") {
+                    // `add` materializes a whole-file selection (full or codemap_only);
+                    // it carries no ranges, so an empty-range "slices" add would be
+                    // silently dropped. Direct ranged additions to set_slices.
+                    throw new InvalidParamsError("refine_context_run add does not support mode:\"slices\"; use set_slices to add ranged selections");
+                }
+                for (const rawPath of op.paths) {
+                    const selectedPath = normalizeRefinePath(rawPath);
+                    const existing = resolveOpTarget(selection, roots, selectedPath);
+                    const entry = {
+                        root_index: existing?.root_index ?? newEntryRootIndex(roots, selectedPath),
+                        path: selectedPath,
+                        ranges: existing?.ranges ?? [],
+                        disposition: op.mode,
+                    };
+                    setSelectionEntry(selection, existing, entry);
+                }
+                break;
+            case "remove":
+                for (const rawPath of op.paths) {
+                    const selectedPath = normalizeRefinePath(rawPath);
+                    const existing = resolveOpTarget(selection, roots, selectedPath);
+                    if (existing != null) {
+                        selection.delete(selectionKey(existing));
+                    }
+                }
+                break;
+            case "set_slices": {
+                const selectedPath = normalizeRefinePath(op.path);
+                const existing = resolveOpTarget(selection, roots, selectedPath);
+                const entry = {
+                    root_index: existing?.root_index ?? newEntryRootIndex(roots, selectedPath),
+                    path: selectedPath,
+                    ranges: coalesceRanges(op.ranges),
+                    disposition: "slices",
+                };
+                setSelectionEntry(selection, existing, entry);
+                break;
+            }
+            case "promote":
+                for (const rawPath of op.paths) {
+                    const selectedPath = normalizeRefinePath(rawPath);
+                    const existing = resolveOpTarget(selection, roots, selectedPath);
+                    const entry = {
+                        root_index: existing?.root_index ?? newEntryRootIndex(roots, selectedPath),
+                        path: selectedPath,
+                        ranges: [],
+                        disposition: "full",
+                    };
+                    setSelectionEntry(selection, existing, entry);
+                }
+                break;
+            case "demote":
+                for (const rawPath of op.paths) {
+                    const selectedPath = normalizeRefinePath(rawPath);
+                    const existing = resolveOpTarget(selection, roots, selectedPath);
+                    const entry = {
+                        root_index: existing?.root_index ?? newEntryRootIndex(roots, selectedPath),
+                        path: selectedPath,
+                        ranges: [],
+                        disposition: "codemap_only",
+                    };
+                    setSelectionEntry(selection, existing, entry);
+                }
+                break;
+        }
+    }
+}
+// Resolve a bare op path to the single existing selection entry it targets.
+// Returns undefined when the path is not selected. Throws if the bare path is
+// ambiguous (selected under 2+ roots) — fail closed rather than guess a root.
+function resolveOpTarget(selection, roots, selectedPath) {
+    const matches = [...selection.values()].filter((entry) => entry.path === selectedPath);
+    if (matches.length >= 2) {
+        throw new InvalidParamsError(`refine_context_run path "${selectedPath}" is ambiguous: selected under ${matches.length} roots. ` +
+            "Refine each root's run separately.");
+    }
+    return matches[0];
+}
+// Root index for a not-yet-selected path. Unambiguous only when the run has a
+// single root; otherwise fail closed (never silently default to root 0).
+function newEntryRootIndex(roots, selectedPath) {
+    if (roots.length === 1) {
+        const only = roots[0];
+        if (only == null) {
+            throw new InvalidParamsError("refine_context_run prior manifest has no usable roots");
+        }
+        return only.root_index;
+    }
+    throw new InvalidParamsError(`refine_context_run cannot add "${selectedPath}" without a root: ${roots.length} roots are available. ` +
+        "Disambiguate by refining a single-root run.");
+}
+function setSelectionEntry(selection, existing, entry) {
+    if (existing != null && existing.root_index !== entry.root_index) {
+        selection.delete(selectionKey(existing));
+    }
+    selection.set(selectionKey(entry), entry);
+}
+async function materializeSelection(input) {
+    const materialized = [];
+    for (const entry of input.selection) {
+        throwIfCancelled(input.signal);
+        const resolved = await resolveEntryFile(entry, input.roots);
+        if (resolved == null) {
+            input.omissions.push(omission(entry, "missing_root", "Recorded root is unavailable"));
+            continue;
+        }
+        if (resolved.kind === "missing") {
+            input.omissions.push(omission(entry, "missing_file", "Refined file no longer exists"));
+            input.warnings.push({
+                code: "refine_missing_file",
+                message: `Refined file no longer exists: ${entry.path}`,
+            });
+            continue;
+        }
+        const { root, realPath } = resolved;
+        if (!isSamePathOrDescendant(realPath, root.path)) {
+            input.omissions.push(omission(entry, "path_escape", "Refined file resolved outside its root"));
+            input.warnings.push({
+                code: "refine_path_escape",
+                message: `Refined file resolved outside its recorded root: ${entry.path}`,
+            });
+            continue;
+        }
+        const pathSecrets = input.allowSecrets ? [] : scanSecretPath(entry.path);
+        if (pathSecrets.length > 0) {
+            input.omissions.push(omission(entry, "secret_path", "Refined file path matched a secret-path rule"));
+            input.warnings.push({
+                code: "refine_secret_path",
+                message: `Refined file omitted by secret-path filter: ${entry.path}`,
+            });
+            continue;
+        }
+        // Stat before read: reject an over-cap in-root file without ever reading or
+        // hashing the whole body. Slice-level budget checks still run in applyBudget.
+        // By design, a file whose RAW size exceeds max_bytes_per_file is omitted
+        // WHOLE and cannot be narrowed via a refine set_slices op — it fails safe as
+        // a max_bytes_per_file omission (partial run), unlike standalone focus
+        // head-slicing.
+        const stats = await fsStat(realPath).catch(() => undefined);
+        if (stats != null && stats.size > input.budget.max_bytes_per_file) {
+            input.omissions.push(omission(entry, "max_bytes_per_file", "Refined file exceeds max_bytes_per_file before read; rejected without loading the full body"));
+            continue;
+        }
+        const raw = await fsReadFile(realPath).catch(() => undefined);
+        if (raw == null) {
+            input.omissions.push(omission(entry, "unreadable_file", "Refined file is not readable"));
+            continue;
+        }
+        // Post-read recheck closes the stat→read TOCTOU: a file that grew or was
+        // swapped between the size guard above and this read must NOT be decoded,
+        // hashed, or secret-scanned at over-cap size. Make the cap hard on the
+        // actual bytes returned, before any whole-body processing.
+        if (raw.byteLength > input.budget.max_bytes_per_file) {
+            input.omissions.push(omission(entry, "max_bytes_per_file", "Refined file grew past max_bytes_per_file between stat and read; rejected after read, before decode/hash/scan."));
+            continue;
+        }
+        const rawText = raw.toString("utf8");
+        const fingerprint = {
+            root_index: root.root_index,
+            path: entry.path,
+            sha256: createHash("sha256").update(raw).digest("hex"),
+            byte_length: raw.byteLength,
+        };
+        warnOnDrift(entry, fingerprint, input.priorFingerprints, input.warnings);
+        const sanitized = input.allowSecrets
+            ? { status: "unchanged", content: rawText, findings: [] }
+            : sanitizeHighConfidenceSecretContent(rawText);
+        if (sanitized.status === "blocked") {
+            input.omissions.push(omission(entry, "content_secret", "Refined file content matched a high-confidence secret rule"));
+            input.warnings.push({
+                code: "refine_content_secret",
+                message: `Refined file omitted by high-confidence secret filter: ${entry.path}`,
+            });
+            continue;
+        }
+        const content = sanitized.content;
+        materialized.push(buildMaterializedFile({
+            entry,
+            root,
+            content,
+            rawByteLength: raw.byteLength,
+            fingerprint,
+            warnings: input.warnings,
+            omissions: input.omissions,
+        }));
+    }
+    return materialized;
+}
+async function resolveEntryFile(entry, roots) {
+    // Resolve ONLY against the entry's recorded root. Never fall through to a
+    // different root that happens to hold the same relative path — that would
+    // expose wrong-root content.
+    const root = roots.find((candidate) => candidate.root_index === entry.root_index);
+    if (root == null) {
+        return undefined;
+    }
+    const absolutePath = path.join(root.path, entry.path);
+    const realPath = await fsRealpath(absolutePath).catch(() => undefined);
+    if (realPath == null) {
+        return { kind: "missing" };
+    }
+    return { kind: "found", root, realPath };
+}
+function buildMaterializedFile(input) {
+    const lines = splitTextLines(input.content);
+    const ranges = rangesForDisposition(input.entry, lines.length, input.warnings, input.omissions);
+    // Budget contract: `full` and `codemap_only` are BOTH budgeted on full-body
+    // bytes, even though `codemap_only` only renders an outline. This is an
+    // intentional, conservative over-charge — it can never exceed budget, and it
+    // avoids a speculative codemap pre-render sizing path. Only `slices` is
+    // budgeted on its narrowed payload.
+    const selectedContent = input.entry.disposition === "slices"
+        ? contentForRanges(lines, ranges)
+        : input.content;
+    const selectedBytes = Buffer.byteLength(selectedContent, "utf8");
+    const slices = input.entry.disposition === "codemap_only"
+        ? []
+        : ranges.map((range) => ({
+            root_index: input.root.root_index,
+            path: input.entry.path,
+            start_line: range.start_line,
+            end_line: range.end_line,
+            source: "focus",
+            content: contentForRanges(lines, [range]),
+        }));
+    return {
+        selected: {
+            root_index: input.root.root_index,
+            path: input.entry.path,
+            ranges,
+            content: selectedContent,
+            bytes: selectedBytes,
+            estimated_tokens: estimateContextBuilderTokensFromUtf8Bytes(selectedBytes),
+            source: "focus",
+            disposition: input.entry.disposition,
+        },
+        tree: {
+            root_index: input.root.root_index,
+            path: input.entry.path,
+            size_bytes: input.rawByteLength,
+            eligible: true,
+            content_eligible: input.entry.disposition !== "codemap_only",
+        },
+        slices,
+        fingerprint: input.fingerprint,
+        rawByteLength: input.rawByteLength,
+    };
+}
+function rangesForDisposition(entry, lineCount, warnings, omissions) {
+    if (entry.disposition === "full" || entry.disposition === "codemap_only") {
+        return lineCount === 0 ? [] : [{ start_line: 1, end_line: lineCount }];
+    }
+    const ranges = clampRanges(entry.ranges, lineCount, entry, warnings);
+    if (ranges.length === 0) {
+        omissions.push(omission(entry, "stale_slice_range", "All refined slice ranges are outside the current file"));
+    }
+    return ranges;
+}
+function clampRanges(ranges, lineCount, entry, warnings) {
+    const clamped = [];
+    for (const range of coalesceRanges(ranges)) {
+        if (lineCount === 0 || range.start_line > lineCount) {
+            warnings.push({
+                code: "refine_slice_range_stale",
+                message: `Dropped stale slice range for ${entry.path}: ${range.start_line}-${range.end_line}`,
+            });
+            continue;
+        }
+        const endLine = Math.min(range.end_line, lineCount);
+        if (endLine !== range.end_line) {
+            warnings.push({
+                code: "refine_slice_range_clamped",
+                message: `Clamped stale slice range for ${entry.path}: ${range.start_line}-${range.end_line}`,
+            });
+        }
+        clamped.push({ start_line: range.start_line, end_line: endLine });
+    }
+    return clamped;
+}
+function applyBudget(input) {
+    const selected = [];
+    const tree = [];
+    const slices = [];
+    const fingerprints = [];
+    let totalBytes = 0;
+    let totalTokens = 0;
+    for (const file of input.files) {
+        const budgetReason = budgetRejectionReason(file.selected, input.budget, selected.length, totalBytes, totalTokens);
+        if (budgetReason != null) {
+            input.omissions.push(omission(file.selected, budgetReason, budgetOmissionMessage(budgetReason)));
+            continue;
+        }
+        selected.push(file.selected);
+        tree.push(file.tree);
+        slices.push(...file.slices);
+        fingerprints.push(file.fingerprint);
+        totalBytes += file.selected.bytes;
+        totalTokens += file.selected.estimated_tokens;
+    }
+    return { selected, tree, slices, fingerprints };
+}
+function budgetRejectionReason(file, budget, selectedCount, totalBytes, totalTokens) {
+    if (selectedCount >= budget.max_files) {
+        return "max_files";
+    }
+    if (file.bytes > budget.max_bytes_per_file) {
+        return "max_bytes_per_file";
+    }
+    if (totalBytes + file.bytes > budget.max_total_bytes) {
+        return "max_total_bytes";
+    }
+    if (totalTokens + file.estimated_tokens > budget.target_estimated_tokens) {
+        return "target_estimated_tokens";
+    }
+    return undefined;
+}
+function budgetOmissionMessage(reason) {
+    switch (reason) {
+        case "max_files":
+            return "Refined selection omitted by max_files budget";
+        case "max_bytes_per_file":
+            return "Refined selection omitted by max_bytes_per_file budget";
+        case "max_total_bytes":
+            return "Refined selection omitted by max_total_bytes budget";
+        case "target_estimated_tokens":
+            return "Refined selection omitted by target_estimated_tokens budget";
+        default:
+            return "Refined selection omitted by budget";
+    }
+}
+function buildMetrics(input) {
+    return {
+        files_seen: input.consideredCount,
+        files_considered: input.consideredCount,
+        files_selected: input.selected.length,
+        files_omitted: input.omittedCount,
+        scan_cap_hit: false,
+        search_cap_hit: false,
+        discovery_byte_cap_hit: false,
+        discovery_candidate_cap_hit: false,
+        candidate_cap_hit: false,
+        bytes_read: input.rawBytesRead,
+        bytes_written: 0,
+        estimated_tokens: input.selected.reduce((total, file) => total + file.estimated_tokens, 0),
+        truncated: input.omittedCount > 0,
+    };
+}
+function normalizeManifestBudget(manifest) {
+    const budget = manifest["budget"];
+    return normalizeContextBuilderPublicBudget(isRecord(budget) ? budget : undefined);
+}
+function priorFingerprintMap(manifest) {
+    const result = new Map();
+    const raw = manifest["file_fingerprints"];
+    if (Array.isArray(raw)) {
+        for (const entry of raw) {
+            if (isRecord(entry) &&
+                typeof entry["root_index"] === "number" &&
+                typeof entry["path"] === "string" &&
+                typeof entry["sha256"] === "string" &&
+                typeof entry["byte_length"] === "number") {
+                const fingerprint = {
+                    root_index: entry["root_index"],
+                    path: normalizeRefinePath(entry["path"]),
+                    sha256: entry["sha256"],
+                    byte_length: entry["byte_length"],
+                };
+                result.set(fingerprintKey(fingerprint), fingerprint);
+            }
+        }
+        return result;
+    }
+    // v1 manifests before refine_context_run did not record content hashes.
+    // For those parents, drift detection is limited to selected payload bytes,
+    // which can miss same-size edits and slice-vs-full differences.
+    const selected = manifest["selected_context"];
+    if (Array.isArray(selected)) {
+        for (const entry of selected) {
+            if (isRecord(entry) &&
+                typeof entry["root_index"] === "number" &&
+                typeof entry["path"] === "string" &&
+                typeof entry["bytes"] === "number") {
+                const fingerprint = {
+                    root_index: entry["root_index"],
+                    path: normalizeRefinePath(entry["path"]),
+                    sha256: "",
+                    byte_length: entry["bytes"],
+                };
+                result.set(fingerprintKey(fingerprint), fingerprint);
+            }
+        }
+    }
+    return result;
+}
+function warnOnDrift(entry, current, priorFingerprints, warnings) {
+    const prior = priorFingerprints.get(fingerprintKey(current));
+    if (prior == null) {
+        return;
+    }
+    if (prior.sha256.length > 0) {
+        // v2: authoritative raw-content hash + raw byte_length comparison.
+        if (prior.sha256 !== current.sha256 ||
+            prior.byte_length !== current.byte_length) {
+            warnings.push({
+                code: "refine_content_drift",
+                message: `Refined file changed since prior run: ${entry.path}`,
+            });
+        }
+        return;
+    }
+    // v1 fallback: the parent recorded only SELECTED payload bytes, which cannot
+    // be compared to current RAW bytes without false positives on sliced files
+    // (selected bytes < raw bytes even when unchanged). Emit a low-confidence,
+    // non-definitive note instead of asserting drift.
+    if (prior.byte_length !== current.byte_length) {
+        warnings.push({
+            code: "refine_drift_unverified",
+            message: `Cannot confirm whether ${entry.path} changed since prior run: parent run predates content hashing`,
+        });
+    }
+}
+function contentForRanges(lines, ranges) {
+    return ranges
+        .flatMap((range) => lines.slice(range.start_line - 1, range.end_line))
+        .join("\n");
+}
+function normalizeRefinePath(input) {
+    const normalized = path.posix
+        .normalize(input.replaceAll("\\", "/").replace(/^\.\/+/, ""))
+        .replace(/^\.\//, "");
+    if (normalized === "." ||
+        normalized === ".." ||
+        normalized.startsWith("../") ||
+        path.posix.isAbsolute(normalized)) {
+        throw new InvalidParamsError(`refine_context_run path must be root-relative: ${input}`);
+    }
+    return normalized;
+}
+function omission(file, reason, message) {
+    return {
+        root_index: file.root_index,
+        reason,
+        message,
+        paths: [file.path],
+    };
+}
+function fingerprintKey(input) {
+    return `${input.root_index}\u0000${input.path}`;
+}
+function isSelectionDisposition(input) {
+    return input === "full" || input === "slices" || input === "codemap_only";
+}
+function isRecord(input) {
+    return typeof input === "object" && input !== null && !Array.isArray(input);
+}
+function throwIfCancelled(signal) {
+    if (signal?.aborted === true) {
+        throw new CancellationError();
+    }
+}
+function getDefaultRefineSemaphore() {
+    return getSharedContextBuilderSemaphore();
+}
+//# sourceMappingURL=refine-handler.js.map