clinkx 0.2.3 → 1.0.0

package/dist/context-builder/storage.js

@@ -0,0 +1,1003 @@
+import { link as fsLink, open as fsOpen, mkdir as fsMkdir, readdir as fsReaddir, readFile as fsReadFile, rename as fsRename, rm as fsRm, stat as fsStat, writeFile as fsWriteFile, } from "node:fs/promises";
+import { randomBytes } from "node:crypto";
+import { hostname } from "node:os";
+import { basename, dirname, isAbsolute, join, relative, resolve } from "node:path";
+import { CancellationError, ExecutionError, InvalidParamsError } from "../errors.js";
+import { validateProspectiveChildPath } from "../paths.js";
+import { contextBuilderInternalCapsForManifest, CONTEXT_BUILDER_INTERNAL_CAP_DEFAULTS, resolveContextBuilderRunsDir, } from "./config.js";
+import { boundContextBuilderOmissions, boundContextBuilderWarnings, } from "./diagnostics.js";
+import { cloneContextBuilderDelegateReceiptMetadata, CONTEXT_BUILDER_DELEGATE_SCHEMA_VERSION, CONTEXT_BUILDER_LEGACY_ARTIFACT_KEYS, CONTEXT_BUILDER_NO_DELEGATE_ARTIFACT_KEYS, CONTEXT_BUILDER_NO_DELEGATE_SCHEMA_VERSION, CONTEXT_BUILDER_SCHEMA_VERSION, isContextBuilderDelegateReceiptMetadata, } from "./receipt.js";
+import { validateCallerRunId } from "./run-id.js";
+import { scanSecretPath } from "./secrets.js";
+export const CONTEXT_BUILDER_ARTIFACT_FILE_NAMES = Object.freeze({
+    manifest_json: "manifest.json",
+    bundle_md: "bundle.md",
+    selected_context_jsonl: "selected-context.jsonl",
+    tree_json: "tree.json",
+    search_jsonl: "search.jsonl",
+    slices_jsonl: "slices.jsonl",
+    codemap_jsonl: "codemap.jsonl",
+    summary_json: "summary.json",
+});
+const DEFAULT_STORAGE_OPS = {
+    mkdir: fsMkdir,
+    writeFile: fsWriteFile,
+    readFile: fsReadFile,
+    rename: fsRename,
+    rm: fsRm,
+    open: fsOpen,
+    link: fsLink,
+    stat: fsStat,
+    readdir: fsReaddir,
+};
+const CONTEXT_BUILDER_METRIC_TYPES = Object.freeze({
+    files_seen: "number",
+    files_considered: "number",
+    files_selected: "number",
+    files_omitted: "number",
+    scan_cap_hit: "boolean",
+    search_cap_hit: "boolean",
+    discovery_byte_cap_hit: "boolean",
+    discovery_candidate_cap_hit: "boolean",
+    candidate_cap_hit: "boolean",
+    bytes_read: "number",
+    bytes_written: "number",
+    estimated_tokens: "number",
+    truncated: "boolean",
+});
+const CONTEXT_BUILDER_INTERNAL_CAP_KEYS = Object.keys(CONTEXT_BUILDER_INTERNAL_CAP_DEFAULTS);
+const CONTEXT_BUILDER_MUTATION_LOCK_SUFFIX = ".mutation.lock";
+const CONTEXT_BUILDER_MUTATION_LOCK_ATTEMPTS = 1_000;
+const CONTEXT_BUILDER_MUTATION_LOCK_RETRY_MS = 10;
+const CONTEXT_BUILDER_STALE_MUTATION_LOCK_MS = 10 * 60 * 1_000;
+export const WORKFLOW_CONTEXT_CACHE_MAX_ENTRIES_ENV = "CLINKX_WORKFLOWS_CONTEXT_CACHE_MAX_ENTRIES";
+export const WORKFLOW_CONTEXT_CACHE_TTL_SECONDS_ENV = "CLINKX_WORKFLOWS_CONTEXT_CACHE_TTL_SECONDS";
+export const DEFAULT_WORKFLOW_CONTEXT_CACHE_MAX_ENTRIES = 50;
+export const DEFAULT_WORKFLOW_CONTEXT_CACHE_TTL_SECONDS = 86_400;
+const DEFAULT_WORKFLOW_CONTEXT_TEMP_TTL_SECONDS = 3_600;
+export function resolveContextBuilderRunPaths(runsDir, runId) {
+    validateCallerRunId(runId);
+    const resolvedRunsDir = resolve(runsDir);
+    const runDir = validateProspectiveChildPath(resolvedRunsDir, runId);
+    if (dirname(runDir) !== resolvedRunsDir || basename(runDir) !== runId) {
+        throw new InvalidParamsError("context_builder run_id escaped runs directory");
+    }
+    const artifactDir = join(runDir, "artifacts");
+    const artifacts = Object.fromEntries(CONTEXT_BUILDER_NO_DELEGATE_ARTIFACT_KEYS.map((key) => [
+        key,
+        key === "manifest_json"
+            ? join(runDir, CONTEXT_BUILDER_ARTIFACT_FILE_NAMES[key])
+            : join(artifactDir, CONTEXT_BUILDER_ARTIFACT_FILE_NAMES[key]),
+    ]));
+    return {
+        runId,
+        runsDir: resolvedRunsDir,
+        runDir,
+        artifactDir,
+        buildingJson: join(runDir, ".building.json"),
+        manifestJson: artifacts.manifest_json,
+        artifacts,
+    };
+}
+export async function createContextBuilderRun(input, ops = DEFAULT_STORAGE_OPS) {
+    const runsDir = await resolveContextBuilderRunsDir(input.runsDir);
+    const ownerNonce = input.ownerNonce ?? randomBytes(16).toString("hex");
+    const paths = {
+        ...resolveContextBuilderRunPaths(runsDir, input.runId),
+        ownerNonce,
+    };
+    let claimedRunDir = false;
+    try {
+        await claimContextBuilderRunDir(paths, ops);
+        claimedRunDir = true;
+        await writeAtomicText(paths.buildingJson, `${JSON.stringify({
+            schema_version: CONTEXT_BUILDER_SCHEMA_VERSION,
+            run_id: input.runId,
+            pid: process.pid,
+            hostname: hostname(),
+            created_at: input.createdAt,
+            owner_nonce: ownerNonce,
+        })}\n`, ops);
+        await ops.mkdir(paths.artifactDir, { recursive: false, mode: 0o700 });
+    }
+    catch (error) {
+        if (claimedRunDir) {
+            const cleanupDecision = await canRemoveIncompleteRunDir(paths, ownerNonce, ops);
+            if (cleanupDecision.removable) {
+                await (ops.rm ?? fsRm)(paths.runDir, {
+                    recursive: true,
+                    force: true,
+                }).catch(() => { });
+            }
+            else {
+                throw new ExecutionError(`context_builder refused setup cleanup for ${input.runId}: ${cleanupDecision.reason}`);
+            }
+        }
+        throw error;
+    }
+    return paths;
+}
+export async function writeContextBuilderArtifact(storage, key, content, ops = DEFAULT_STORAGE_OPS) {
+    const canonicalStorage = canonicalizeContextBuilderStorage(storage);
+    await withContextBuilderMutationLock(canonicalStorage, ops, async () => {
+        await assertManifestAbsentForMutation(canonicalStorage, ops);
+        await writeAtomicText(canonicalStorage.artifacts[key], content, ops, {
+            mustNotExistPath: canonicalStorage.manifestJson,
+        });
+    }, { ownerNonce: canonicalStorage.ownerNonce });
+}
+export async function commitContextBuilderRun(storage, manifest, optionsOrOps = {}, maybeOps = DEFAULT_STORAGE_OPS) {
+    const { options, ops } = normalizeCommitArguments(optionsOrOps, maybeOps);
+    const canonicalStorage = canonicalizeContextBuilderStorage(storage);
+    const ownerNonce = options.ownerNonce ?? canonicalStorage.ownerNonce;
+    await withContextBuilderMutationLock(canonicalStorage, ops, async () => {
+        await assertManifestAbsentForMutation(canonicalStorage, ops);
+        await assertRequiredArtifactsReadable(canonicalStorage, ops);
+        throwIfCancelledBeforeManifest(options);
+        const internalCaps = contextBuilderInternalCapsForManifest(manifest.internal_caps);
+        const { delegate, ...manifestWithoutDelegate } = manifest;
+        const boundedDelegate = normalizeManifestDelegateMetadata(delegate);
+        const completeManifest = {
+            ...manifestWithoutDelegate,
+            schema_version: schemaVersionForManifestDelegate(boundedDelegate),
+            run_id: canonicalStorage.runId,
+            internal_caps: internalCaps,
+            artifacts: { ...canonicalStorage.artifacts },
+            warnings: boundContextBuilderWarnings(normalizeContextBuilderWarnings(manifest.warnings), internalCaps),
+            omissions: boundContextBuilderOmissions(normalizeContextBuilderOmissions(manifest.omissions), internalCaps),
+            ...(boundedDelegate == null ? {} : { delegate: boundedDelegate }),
+        };
+        await writeExclusiveText(canonicalStorage.manifestJson, `${JSON.stringify(completeManifest)}\n`, ops, options.signal === undefined ? {} : { signal: options.signal });
+    }, { ownerNonce });
+}
+export async function writeContextBuilderArtifactsAndCommit(storage, contents, manifest, options = {}) {
+    const ops = options.ops ?? DEFAULT_STORAGE_OPS;
+    const canonicalStorage = canonicalizeContextBuilderStorage(storage);
+    const ownerNonce = options.ownerNonce ?? canonicalStorage.ownerNonce;
+    await withContextBuilderMutationLock(canonicalStorage, ops, async () => {
+        await assertManifestAbsentForMutation(canonicalStorage, ops);
+        for (const [key, content] of Object.entries(contents)) {
+            if (options.signal?.aborted === true) {
+                throw new CancellationError();
+            }
+            await writeAtomicText(canonicalStorage.artifacts[key], content, ops, { mustNotExistPath: canonicalStorage.manifestJson });
+        }
+        throwIfCancelledBeforeManifest(options.signal === undefined ? {} : { signal: options.signal });
+        await assertRequiredArtifactsReadable(canonicalStorage, ops);
+        await options.beforeManifestCommit?.();
+        const internalCaps = contextBuilderInternalCapsForManifest(manifest.internal_caps);
+        const { delegate, ...manifestWithoutDelegate } = manifest;
+        const boundedDelegate = normalizeManifestDelegateMetadata(delegate);
+        const completeManifest = {
+            ...manifestWithoutDelegate,
+            schema_version: schemaVersionForManifestDelegate(boundedDelegate),
+            run_id: canonicalStorage.runId,
+            internal_caps: internalCaps,
+            artifacts: { ...canonicalStorage.artifacts },
+            warnings: boundContextBuilderWarnings(normalizeContextBuilderWarnings(manifest.warnings), internalCaps),
+            omissions: boundContextBuilderOmissions(normalizeContextBuilderOmissions(manifest.omissions), internalCaps),
+            ...(boundedDelegate == null ? {} : { delegate: boundedDelegate }),
+        };
+        await writeExclusiveText(canonicalStorage.manifestJson, `${JSON.stringify(completeManifest)}\n`, ops, options.signal === undefined ? {} : { signal: options.signal });
+    }, { ownerNonce });
+}
+export async function promoteContextBuilderRun(tempRunDir, targetRunId, ops = DEFAULT_STORAGE_OPS) {
+    const resolvedTempRunDir = resolve(tempRunDir);
+    const tempManifest = await readContextBuilderManifest(join(resolvedTempRunDir, "manifest.json"), ops);
+    const tempStorage = resolveContextBuilderRunPaths(dirname(resolvedTempRunDir), tempManifest.run_id);
+    if (tempStorage.runDir !== resolvedTempRunDir
+        || !await isContextBuilderRunCommitted(resolvedTempRunDir, ops)) {
+        throw new ExecutionError("context_builder cannot promote an uncommitted or mismatched temp run");
+    }
+    const targetStorage = resolveContextBuilderRunPaths(tempStorage.runsDir, targetRunId);
+    await claimContextBuilderRunDir(targetStorage, ops);
+    try {
+        await ops.mkdir(targetStorage.artifactDir, { recursive: false, mode: 0o700 });
+        await withContextBuilderMutationLock(targetStorage, ops, async () => {
+            await assertManifestAbsentForMutation(targetStorage, ops);
+            const artifactEntries = Object.entries(tempManifest.artifacts);
+            for (const [key, sourcePath] of artifactEntries) {
+                if (key === "manifest_json") {
+                    continue;
+                }
+                const targetPath = targetStorage.artifacts[key];
+                const sourceContent = await ops.readFile(sourcePath, "utf8");
+                const targetContent = key === "summary_json"
+                    ? rewriteContextBuilderSummaryRunId(sourceContent, targetRunId)
+                    : sourceContent;
+                await writeAtomicText(targetPath, targetContent, ops, {
+                    mustNotExistPath: targetStorage.manifestJson,
+                });
+            }
+            const targetArtifacts = Object.fromEntries(Object.keys(tempManifest.artifacts).map((key) => [
+                key,
+                targetStorage.artifacts[key],
+            ]));
+            const targetManifest = {
+                ...tempManifest,
+                run_id: targetRunId,
+                artifacts: targetArtifacts,
+            };
+            await writeExclusiveText(targetStorage.manifestJson, `${JSON.stringify(targetManifest)}\n`, ops);
+        });
+        if (!await isContextBuilderRunCommitted(targetStorage.runDir, ops)) {
+            throw new ExecutionError(`context_builder promoted run failed validation: ${targetRunId}`);
+        }
+    }
+    catch (error) {
+        // The target dir was claimed above, so always clean it up on failure.
+        await (ops.rm ?? fsRm)(targetStorage.runDir, {
+            recursive: true,
+            force: true,
+        }).catch(() => { });
+        await syncDirectoryBestEffort(targetStorage.runsDir, ops);
+        throw error;
+    }
+    await (ops.rm ?? fsRm)(resolvedTempRunDir, { recursive: true, force: true })
+        .catch(() => { });
+    await syncDirectoryBestEffort(tempStorage.runsDir, ops);
+    return targetStorage;
+}
+export async function evictWorkflowContextRuns(runsDir, options = {}) {
+    const ops = options.ops ?? DEFAULT_STORAGE_OPS;
+    const readdir = ops.readdir ?? fsReaddir;
+    const stat = ops.stat ?? fsStat;
+    const resolvedRunsDir = await resolveContextBuilderRunsDir(runsDir);
+    const bounds = resolveWorkflowContextEvictionBounds(options);
+    const nowMs = options.nowMs ?? Date.now();
+    const protectedRunIds = new Set(options.protectedRunIds ?? []);
+    const entries = await readdir(resolvedRunsDir, { withFileTypes: true });
+    const committedCacheEntries = [];
+    const removeSet = new Map();
+    let scanned = 0;
+    let skipped = 0;
+    let failed = 0;
+    for (const entry of entries) {
+        if (!entry.isDirectory() || !isWorkflowContextRunId(entry.name)) {
+            continue;
+        }
+        scanned += 1;
+        try {
+            const storage = resolveContextBuilderRunPaths(resolvedRunsDir, entry.name);
+            const runStat = await stat(storage.runDir).catch((error) => {
+                if (isNodeError(error) && error.code === "ENOENT") {
+                    return undefined;
+                }
+                throw error;
+            });
+            if (runStat === undefined) {
+                skipped += 1;
+                continue;
+            }
+            if (!await isContextBuilderRunCommitted(storage.runDir, ops)) {
+                skipped += 1;
+                continue;
+            }
+            const isProtected = protectedRunIds.has(storage.runId);
+            if (entry.name.startsWith("wfctx-")) {
+                // Protected cache entries are excluded from LRU survivor accounting so
+                // they can never be selected for the max-entries trim below either.
+                if (!isProtected) {
+                    committedCacheEntries.push({ storage, mtimeMs: runStat.mtimeMs });
+                }
+                if (nowMs - runStat.mtimeMs > bounds.cacheTtlMs) {
+                    if (isProtected) {
+                        skipped += 1;
+                    }
+                    else {
+                        removeSet.set(storage.runId, storage);
+                    }
+                }
+                continue;
+            }
+            if (nowMs - runStat.mtimeMs > bounds.tempTtlMs) {
+                if (isProtected) {
+                    skipped += 1;
+                }
+                else {
+                    removeSet.set(storage.runId, storage);
+                }
+            }
+        }
+        catch {
+            failed += 1;
+        }
+    }
+    const cacheSurvivors = committedCacheEntries
+        .filter(({ storage }) => !removeSet.has(storage.runId))
+        .sort((a, b) => a.mtimeMs - b.mtimeMs)
+        .map(({ storage }) => storage);
+    cacheSurvivors
+        .slice(0, Math.max(0, cacheSurvivors.length - bounds.maxEntries))
+        .forEach((storage) => removeSet.set(storage.runId, storage));
+    let evicted = 0;
+    for (const storage of removeSet.values()) {
+        try {
+            const didRemove = await removeCommittedWorkflowContextRun(storage, ops);
+            if (didRemove) {
+                evicted += 1;
+            }
+            else {
+                skipped += 1;
+            }
+        }
+        catch (error) {
+            if (isNodeError(error) && error.code === "ENOENT") {
+                skipped += 1;
+            }
+            else {
+                failed += 1;
+            }
+        }
+    }
+    if (evicted > 0) {
+        await syncDirectoryBestEffort(resolvedRunsDir, ops);
+    }
+    return { scanned, evicted, skipped, failed };
+}
+export async function cleanupContextBuilderIncompleteRun(storage, ownerNonce, ops = DEFAULT_STORAGE_OPS) {
+    const canonicalStorage = canonicalizeContextBuilderStorage(storage);
+    return withContextBuilderMutationLock(canonicalStorage, ops, async () => cleanupContextBuilderIncompleteRunLocked(canonicalStorage, ownerNonce, ops), {
+        ownerNonce,
+        recoverStaleForCleanup: true,
+    });
+}
+/**
+ * Hold the existing per-run mutation lock while a committed run is consumed.
+ * Writers and pruning use the same lock, so the callback may safely materialize
+ * artifact paths without the run directory disappearing underneath it.
+ */
+export async function withContextBuilderRunMutationLease(storage, callback, ops = DEFAULT_STORAGE_OPS) {
+    const canonicalStorage = canonicalizeContextBuilderStorage(storage);
+    return await withContextBuilderMutationLock(canonicalStorage, ops, callback);
+}
+async function cleanupContextBuilderIncompleteRunLocked(storage, ownerNonce, ops) {
+    if (!await mayRemoveIncompleteRunDir(storage, ownerNonce, ops)) {
+        return false;
+    }
+    await (ops.rm ?? fsRm)(storage.runDir, {
+        recursive: true,
+        force: true,
+    });
+    await syncDirectoryBestEffort(storage.runsDir, ops);
+    return true;
+}
+export async function isContextBuilderRunCommitted(runDir, ops = DEFAULT_STORAGE_OPS) {
+    try {
+        const resolvedRunDir = resolve(runDir);
+        const parsed = JSON.parse(await ops.readFile(join(resolvedRunDir, "manifest.json"), "utf8"));
+        if (!isValidContextBuilderManifest(parsed, basename(resolvedRunDir))) {
+            return false;
+        }
+        const expectedStorage = resolveContextBuilderRunPaths(dirname(resolvedRunDir), parsed.run_id);
+        if (expectedStorage.runDir !== resolvedRunDir) {
+            return false;
+        }
+        const artifactKeys = supportedArtifactKeys(parsed.artifacts);
+        if (artifactKeys == null
+            || !artifactPathsExactlyMatch(parsed.artifacts, expectedStorage.artifacts, artifactKeys)) {
+            return false;
+        }
+        await assertRequiredArtifactsReadable(expectedStorage, ops, artifactKeys);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function canonicalizeContextBuilderStorage(storage) {
+    const expected = resolveContextBuilderRunPaths(storage.runsDir, storage.runId);
+    if (storage.runDir !== expected.runDir
+        || storage.artifactDir !== expected.artifactDir
+        || storage.buildingJson !== expected.buildingJson
+        || storage.manifestJson !== expected.manifestJson
+        || !artifactPathsExactlyMatch(storage.artifacts, expected.artifacts, CONTEXT_BUILDER_NO_DELEGATE_ARTIFACT_KEYS)) {
+        throw new ExecutionError("context_builder storage paths do not match run_id and runs_dir");
+    }
+    return storage.ownerNonce === undefined
+        ? expected
+        : { ...expected, ownerNonce: storage.ownerNonce };
+}
+async function readContextBuilderManifest(manifestPath, ops) {
+    let parsed;
+    try {
+        parsed = JSON.parse(await ops.readFile(manifestPath, "utf8"));
+    }
+    catch (error) {
+        throw new ExecutionError(`context_builder cannot read manifest for promotion: ${nodeErrorCode(error)}`);
+    }
+    const parsedRunId = parsed !== null && typeof parsed === "object"
+        ? parsed.run_id
+        : undefined;
+    if (typeof parsedRunId !== "string"
+        || !isValidContextBuilderManifest(parsed, parsedRunId)) {
+        throw new ExecutionError("context_builder cannot promote run with an invalid manifest");
+    }
+    return parsed;
+}
+function rewriteContextBuilderSummaryRunId(summaryText, targetRunId) {
+    let parsed;
+    try {
+        parsed = JSON.parse(summaryText);
+    }
+    catch {
+        throw new ExecutionError("context_builder cannot promote run with an invalid summary artifact");
+    }
+    if (parsed === null || typeof parsed !== "object") {
+        throw new ExecutionError("context_builder cannot promote run with an invalid summary artifact");
+    }
+    return `${JSON.stringify({
+        ...parsed,
+        run_id: targetRunId,
+    })}\n`;
+}
+async function mayRemoveIncompleteRunDir(storage, ownerNonce, ops) {
+    return (await canRemoveIncompleteRunDir(storage, ownerNonce, ops)).removable;
+}
+async function canRemoveIncompleteRunDir(storage, ownerNonce, ops) {
+    const resolvedRunsDir = resolve(storage.runsDir);
+    const resolvedRunDir = resolve(storage.runDir);
+    if (!isPathInsideDirectory(resolvedRunDir, resolvedRunsDir)) {
+        return { removable: false, reason: "run directory is outside runs directory" };
+    }
+    const manifestDecision = await manifestCleanupDecision(storage, ops);
+    if (!manifestDecision.removable) {
+        return manifestDecision;
+    }
+    let building;
+    try {
+        building = JSON.parse(await ops.readFile(storage.buildingJson, "utf8"));
+    }
+    catch {
+        return { removable: false, reason: "missing marker" };
+    }
+    if (building === null
+        || typeof building !== "object"
+        || building.owner_nonce !== ownerNonce) {
+        return { removable: false, reason: "owner mismatch" };
+    }
+    return { removable: true };
+}
+async function manifestCleanupDecision(storage, ops) {
+    try {
+        await ops.readFile(storage.manifestJson, "utf8");
+        return { removable: false, reason: "manifest exists" };
+    }
+    catch (error) {
+        if (isNodeError(error) && error.code === "ENOENT") {
+            return { removable: true };
+        }
+        return {
+            removable: false,
+            reason: `manifest unreadable: ${nodeErrorCode(error)}`,
+        };
+    }
+}
+async function claimContextBuilderRunDir(paths, ops) {
+    try {
+        await ops.mkdir(paths.runDir, { recursive: false, mode: 0o700 });
+    }
+    catch (error) {
+        if (isNodeError(error) && error.code === "EEXIST") {
+            if (await isContextBuilderRunCommitted(paths.runDir, ops)) {
+                throw new InvalidParamsError(`context_builder run_id already exists: ${paths.runId}`);
+            }
+            throw new ExecutionError(`context_builder run_id conflicts with an incomplete or active run: ${paths.runId}`);
+        }
+        throw error;
+    }
+}
+function throwIfCancelledBeforeManifest(options) {
+    if (options.signal?.aborted !== true) {
+        return;
+    }
+    throw new CancellationError();
+}
+function normalizeCommitArguments(optionsOrOps, maybeOps) {
+    if (isStorageOps(optionsOrOps)) {
+        return { options: {}, ops: optionsOrOps };
+    }
+    return { options: optionsOrOps, ops: maybeOps };
+}
+function isStorageOps(value) {
+    return ("mkdir" in value
+        || "writeFile" in value
+        || "readFile" in value
+        || "rename" in value
+        || "rm" in value
+        || "open" in value
+        || "link" in value);
+}
+async function withContextBuilderMutationLock(storage, ops, callback, options = {}) {
+    const lockPath = mutationLockPathForStorage(storage);
+    const lockHandle = await acquireContextBuilderMutationLock(storage, lockPath, ops, options);
+    try {
+        return await callback();
+    }
+    finally {
+        await lockHandle.close().catch(() => { });
+        await (ops.rm ?? fsRm)(lockPath, { force: true }).catch(() => { });
+    }
+}
+async function acquireContextBuilderMutationLock(storage, lockPath, ops, options) {
+    const open = ops.open ?? fsOpen;
+    for (let attempt = 0; attempt < CONTEXT_BUILDER_MUTATION_LOCK_ATTEMPTS; attempt += 1) {
+        try {
+            const handle = await open(lockPath, "wx", 0o600);
+            try {
+                await writeMutationLockMetadata(handle, options.ownerNonce);
+                return handle;
+            }
+            catch (error) {
+                await handle.close().catch(() => { });
+                await (ops.rm ?? fsRm)(lockPath, { force: true }).catch(() => { });
+                throw error;
+            }
+        }
+        catch (error) {
+            if (isNodeError(error) && error.code === "EEXIST") {
+                if (options.recoverStaleForCleanup === true
+                    && await breakStaleCleanupMutationLock(storage, lockPath, options.ownerNonce, ops)) {
+                    continue;
+                }
+                await delay(CONTEXT_BUILDER_MUTATION_LOCK_RETRY_MS);
+                continue;
+            }
+            throw error;
+        }
+    }
+    throw new ExecutionError("context_builder timed out waiting for the run mutation lock");
+}
+function mutationLockPathForStorage(storage) {
+    validateCallerRunId(storage.runId);
+    const resolvedRunsDir = resolve(storage.runsDir);
+    const resolvedRunDir = resolve(storage.runDir);
+    if (!isPathInsideDirectory(resolvedRunDir, resolvedRunsDir)) {
+        throw new ExecutionError("context_builder refused mutation lock outside runs directory");
+    }
+    return join(resolvedRunsDir, `.${storage.runId}${CONTEXT_BUILDER_MUTATION_LOCK_SUFFIX}`);
+}
+async function writeMutationLockMetadata(handle, ownerNonce) {
+    const metadata = {
+        pid: process.pid,
+        hostname: hostname(),
+        created_at: new Date().toISOString(),
+        ...(ownerNonce == null ? {} : { owner_nonce: ownerNonce }),
+    };
+    await handle.writeFile(`${JSON.stringify(metadata)}\n`, { encoding: "utf8" });
+}
+async function breakStaleCleanupMutationLock(storage, lockPath, ownerNonce, ops) {
+    if (ownerNonce == null) {
+        return false;
+    }
+    const cleanupDecision = await canRemoveIncompleteRunDir(storage, ownerNonce, ops);
+    if (!cleanupDecision.removable) {
+        return false;
+    }
+    if (!await isMutationLockOldEnough(lockPath, ops)) {
+        return false;
+    }
+    const metadata = await readMutationLockMetadata(lockPath, ops);
+    if (metadata !== "invalid" && !isStaleMutationLockMetadata(metadata)) {
+        return false;
+    }
+    await (ops.rm ?? fsRm)(lockPath, { force: true }).catch(() => { });
+    return true;
+}
+async function isMutationLockOldEnough(lockPath, ops) {
+    const stat = ops.stat ?? fsStat;
+    try {
+        const lockStat = await stat(lockPath);
+        return Date.now() - lockStat.mtimeMs >= CONTEXT_BUILDER_STALE_MUTATION_LOCK_MS;
+    }
+    catch {
+        return false;
+    }
+}
+async function readMutationLockMetadata(lockPath, ops) {
+    let parsed;
+    try {
+        parsed = JSON.parse(await ops.readFile(lockPath, "utf8"));
+    }
+    catch {
+        return "invalid";
+    }
+    if (parsed === null || typeof parsed !== "object") {
+        return "invalid";
+    }
+    const metadata = parsed;
+    if (typeof metadata.pid !== "number"
+        || !Number.isInteger(metadata.pid)
+        || typeof metadata.hostname !== "string"
+        || typeof metadata.created_at !== "string") {
+        return "invalid";
+    }
+    if (metadata.owner_nonce !== undefined
+        && typeof metadata.owner_nonce !== "string") {
+        return "invalid";
+    }
+    return {
+        pid: metadata.pid,
+        hostname: metadata.hostname,
+        created_at: metadata.created_at,
+        ...(metadata.owner_nonce === undefined
+            ? {}
+            : { owner_nonce: metadata.owner_nonce }),
+    };
+}
+function isStaleMutationLockMetadata(metadata) {
+    const createdAtMs = Date.parse(metadata.created_at);
+    if (!Number.isFinite(createdAtMs)
+        || Date.now() - createdAtMs < CONTEXT_BUILDER_STALE_MUTATION_LOCK_MS) {
+        return false;
+    }
+    if (metadata.hostname !== hostname()) {
+        return false;
+    }
+    return !isProcessAlive(metadata.pid);
+}
+function isProcessAlive(pid) {
+    if (pid <= 0) {
+        return false;
+    }
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (error) {
+        return !(isNodeError(error) && error.code === "ESRCH");
+    }
+}
+async function assertRequiredArtifactsReadable(storage, ops, artifactKeys = CONTEXT_BUILDER_NO_DELEGATE_ARTIFACT_KEYS) {
+    const missing = [];
+    for (const key of artifactKeys) {
+        if (key === "manifest_json") {
+            continue;
+        }
+        try {
+            await ops.readFile(storage.artifacts[key], "utf8");
+        }
+        catch {
+            missing.push(key);
+        }
+    }
+    if (missing.length > 0) {
+        throw new Error(`context_builder cannot commit before required artifacts exist: ${missing.join(", ")}`);
+    }
+}
+async function assertManifestAbsentForMutation(storage, ops) {
+    try {
+        await ops.readFile(storage.manifestJson, "utf8");
+    }
+    catch (error) {
+        if (isNodeError(error) && error.code === "ENOENT") {
+            return;
+        }
+        throw new ExecutionError(`context_builder cannot mutate committed run: manifest unreadable (${nodeErrorCode(error)})`);
+    }
+    throw new ExecutionError("context_builder cannot mutate committed run: manifest already exists");
+}
+function artifactPathsExactlyMatch(actual, expected, artifactKeys) {
+    if (!hasExactArtifactKeys(actual, artifactKeys)) {
+        return false;
+    }
+    for (const key of artifactKeys) {
+        if (actual[key] !== expected[key]) {
+            return false;
+        }
+    }
+    return true;
+}
+function isValidContextBuilderManifest(value, expectedRunId) {
+    if (value === null || typeof value !== "object") {
+        return false;
+    }
+    const manifest = value;
+    const hasDelegate = Object.prototype.hasOwnProperty.call(manifest, "delegate");
+    const hasValidDelegate = isContextBuilderDelegateReceiptMetadata(manifest.delegate);
+    const hasValidVersionedDelegate = (manifest.schema_version === CONTEXT_BUILDER_NO_DELEGATE_SCHEMA_VERSION
+        && !hasDelegate)
+        || (manifest.schema_version === CONTEXT_BUILDER_DELEGATE_SCHEMA_VERSION
+            && hasDelegate
+            && hasValidDelegate);
+    return (hasValidVersionedDelegate
+        && manifest.run_id === expectedRunId
+        && (manifest.status === "succeeded" || manifest.status === "partial")
+        && hasRequiredInternalCaps(manifest.internal_caps)
+        && hasRequiredArtifactPaths(manifest.artifacts)
+        && hasRequiredMetrics(manifest.metrics)
+        && Array.isArray(manifest.warnings)
+        && Array.isArray(manifest.omissions));
+}
+function normalizeManifestDelegateMetadata(delegate) {
+    if (delegate === undefined) {
+        return undefined;
+    }
+    if (delegate === null || typeof delegate !== "object") {
+        throw new ExecutionError("context_builder manifest delegate metadata is invalid");
+    }
+    const bounded = cloneContextBuilderDelegateReceiptMetadata(delegate);
+    if (!isContextBuilderDelegateReceiptMetadata(bounded)) {
+        throw new ExecutionError("context_builder manifest delegate metadata is invalid");
+    }
+    return bounded;
+}
+function schemaVersionForManifestDelegate(delegate) {
+    return delegate == null
+        ? CONTEXT_BUILDER_NO_DELEGATE_SCHEMA_VERSION
+        : CONTEXT_BUILDER_DELEGATE_SCHEMA_VERSION;
+}
+function hasRequiredInternalCaps(value) {
+    if (value === null || typeof value !== "object") {
+        return false;
+    }
+    const caps = value;
+    return CONTEXT_BUILDER_INTERNAL_CAP_KEYS.every((key) => (typeof caps[key] === "number"));
+}
+function hasRequiredArtifactPaths(value) {
+    if (value === null || typeof value !== "object") {
+        return false;
+    }
+    const artifacts = value;
+    const artifactKeys = supportedArtifactKeys(artifacts);
+    return artifactKeys != null && artifactKeys.every((key) => (typeof artifacts[key] === "string"));
+}
+function supportedArtifactKeys(value) {
+    if (hasExactArtifactKeys(value, CONTEXT_BUILDER_NO_DELEGATE_ARTIFACT_KEYS)) {
+        return CONTEXT_BUILDER_NO_DELEGATE_ARTIFACT_KEYS;
+    }
+    if (hasExactArtifactKeys(value, CONTEXT_BUILDER_LEGACY_ARTIFACT_KEYS)) {
+        return CONTEXT_BUILDER_LEGACY_ARTIFACT_KEYS;
+    }
+    return undefined;
+}
+function hasExactArtifactKeys(value, expectedArtifactKeys) {
+    const expectedKeys = new Set(expectedArtifactKeys);
+    const actualKeys = Object.keys(value);
+    return (actualKeys.length === expectedArtifactKeys.length
+        && actualKeys.every((key) => expectedKeys.has(key)));
+}
+function hasRequiredMetrics(value) {
+    if (value === null || typeof value !== "object") {
+        return false;
+    }
+    const metrics = value;
+    return Object.entries(CONTEXT_BUILDER_METRIC_TYPES).every(([key, expectedType]) => typeof metrics[key] === expectedType);
+}
+async function writeAtomicText(finalPath, content, ops, options = {}) {
+    let tempPath = "";
+    let handle;
+    try {
+        const opened = await openExclusiveTempFile(finalPath, ops);
+        tempPath = opened.tempPath;
+        handle = opened.handle;
+        await handle.writeFile(content, { encoding: "utf8" });
+        await handle.sync();
+        await handle.close();
+        handle = undefined;
+        if (options.mustNotExistPath != null) {
+            await assertPathAbsentForMutation(options.mustNotExistPath, ops);
+        }
+        await ops.rename(tempPath, finalPath);
+        tempPath = "";
+        await syncDirectoryBestEffort(dirname(finalPath), ops);
+    }
+    finally {
+        if (handle !== undefined) {
+            await handle.close().catch(() => { });
+        }
+        if (tempPath !== "") {
+            await (ops.rm ?? fsRm)(tempPath, { force: true }).catch(() => { });
+        }
+    }
+}
+async function writeExclusiveText(finalPath, content, ops, options = {}) {
+    let tempPath = "";
+    let handle;
+    try {
+        const opened = await openExclusiveTempFile(finalPath, ops);
+        tempPath = opened.tempPath;
+        handle = opened.handle;
+        await handle.writeFile(content, { encoding: "utf8" });
+        await handle.sync();
+        await handle.close();
+        handle = undefined;
+        throwIfCancelledBeforeManifest(options);
+        await linkNoClobber(tempPath, finalPath, ops);
+        await (ops.rm ?? fsRm)(tempPath, { force: true }).catch(() => { });
+        tempPath = "";
+        await syncDirectoryBestEffort(dirname(finalPath), ops);
+    }
+    finally {
+        if (handle !== undefined) {
+            await handle.close().catch(() => { });
+        }
+        if (tempPath !== "") {
+            await (ops.rm ?? fsRm)(tempPath, { force: true }).catch(() => { });
+        }
+    }
+}
+async function linkNoClobber(existingPath, newPath, ops) {
+    const link = ops.link ?? fsLink;
+    try {
+        await link(existingPath, newPath);
+    }
+    catch (error) {
+        if (isNodeError(error) && error.code === "EEXIST") {
+            throw new ExecutionError("context_builder cannot mutate committed run: manifest already exists");
+        }
+        throw error;
+    }
+}
+async function assertPathAbsentForMutation(path, ops) {
+    try {
+        await ops.readFile(path, "utf8");
+    }
+    catch (error) {
+        if (isNodeError(error) && error.code === "ENOENT") {
+            return;
+        }
+        throw new ExecutionError(`context_builder cannot mutate committed run: manifest unreadable (${nodeErrorCode(error)})`);
+    }
+    throw new ExecutionError("context_builder cannot mutate committed run: manifest already exists");
+}
+async function openExclusiveTempFile(finalPath, ops) {
+    const open = ops.open ?? fsOpen;
+    for (let attempt = 0; attempt < 10; attempt += 1) {
+        const tempPath = `${finalPath}.${process.pid}.${randomBytes(8).toString("hex")}.tmp`;
+        try {
+            return {
+                tempPath,
+                handle: await open(tempPath, "wx", 0o600),
+            };
+        }
+        catch (error) {
+            if (isNodeError(error) && error.code === "EEXIST") {
+                continue;
+            }
+            throw error;
+        }
+    }
+    throw new Error("context_builder failed to create an exclusive temp file");
+}
+async function syncDirectoryBestEffort(path, ops) {
+    let handle;
+    const open = ops.open ?? fsOpen;
+    try {
+        handle = await open(path, "r");
+        await handle.sync();
+    }
+    catch {
+        return;
+    }
+    finally {
+        if (handle !== undefined) {
+            await handle.close().catch(() => { });
+        }
+    }
+}
+async function removeCommittedWorkflowContextRun(storage, ops) {
+    if (!isWorkflowContextRunId(storage.runId)) {
+        return false;
+    }
+    return await withContextBuilderMutationLock(storage, ops, async () => {
+        if (!await isContextBuilderRunCommitted(storage.runDir, ops)) {
+            return false;
+        }
+        await (ops.rm ?? fsRm)(storage.runDir, { recursive: true, force: true });
+        return true;
+    });
+}
+function isWorkflowContextRunId(runId) {
+    return runId.startsWith("wfctx-") || runId.startsWith("wfpre-");
+}
+function resolveWorkflowContextEvictionBounds(options) {
+    const env = options.env ?? process.env;
+    const maxEntries = normalizeNonNegativeInteger(options.maxEntries, parseNonNegativeInteger(env[WORKFLOW_CONTEXT_CACHE_MAX_ENTRIES_ENV], DEFAULT_WORKFLOW_CONTEXT_CACHE_MAX_ENTRIES));
+    const cacheTtlSeconds = normalizeNonNegativeInteger(options.cacheTtlSeconds, parseNonNegativeInteger(env[WORKFLOW_CONTEXT_CACHE_TTL_SECONDS_ENV], DEFAULT_WORKFLOW_CONTEXT_CACHE_TTL_SECONDS));
+    const tempTtlSeconds = normalizeNonNegativeInteger(options.tempTtlSeconds, Math.min(cacheTtlSeconds, DEFAULT_WORKFLOW_CONTEXT_TEMP_TTL_SECONDS));
+    return {
+        maxEntries,
+        cacheTtlMs: cacheTtlSeconds * 1_000,
+        // Provenance-only temp runs are useful for debugging recent misses, but they
+        // are not reusable cache entries, so they get a shorter bounded lifetime.
+        tempTtlMs: tempTtlSeconds * 1_000,
+    };
+}
+function parseNonNegativeInteger(value, fallback) {
+    if (value == null || value.trim() === "") {
+        return fallback;
+    }
+    const parsed = Number(value);
+    return normalizeNonNegativeInteger(parsed, fallback);
+}
+function normalizeNonNegativeInteger(value, fallback) {
+    if (value === undefined) {
+        return fallback;
+    }
+    return Number.isSafeInteger(value) && value >= 0 ? value : fallback;
+}
+function isNodeError(error) {
+    return error instanceof Error && "code" in error;
+}
+function nodeErrorCode(error) {
+    return isNodeError(error) && typeof error.code === "string"
+        ? error.code
+        : "unknown";
+}
+function normalizeContextBuilderWarnings(warnings) {
+    return warnings.map((warning) => {
+        if (isRecord(warning)) {
+            return {
+                code: diagnosticText(warning.code, "warning"),
+                message: diagnosticText(warning.message, "warning"),
+            };
+        }
+        return {
+            code: "warning",
+            message: diagnosticText(warning, "warning"),
+        };
+    });
+}
+function normalizeContextBuilderOmissions(omissions) {
+    return omissions.map((omission) => {
+        if (isRecord(omission)) {
+            const rootIndex = normalizeContextBuilderRootIndex(omission.root_index);
+            return {
+                ...(rootIndex == null ? {} : { root_index: rootIndex }),
+                reason: diagnosticText(omission.reason, "omission"),
+                message: diagnosticText(omission.message, "omission"),
+                ...(Array.isArray(omission.paths)
+                    ? { paths: omission.paths.map(normalizeContextBuilderOmissionPath) }
+                    : {}),
+            };
+        }
+        return {
+            reason: "omission",
+            message: diagnosticText(omission, "omission"),
+        };
+    });
+}
+function normalizeContextBuilderRootIndex(rootIndex) {
+    return typeof rootIndex === "number"
+        && Number.isInteger(rootIndex)
+        && rootIndex >= 0
+        ? rootIndex
+        : undefined;
+}
+function normalizeContextBuilderOmissionPath(path) {
+    if (typeof path !== "string") {
+        return "[redacted-sensitive-path]";
+    }
+    const text = diagnosticText(path, "");
+    return scanSecretPath(text).length > 0 ? "[redacted-sensitive-path]" : text;
+}
+function diagnosticText(value, fallback) {
+    if (typeof value === "string") {
+        return value;
+    }
+    if (value == null) {
+        return fallback;
+    }
+    if (typeof value === "number" || typeof value === "boolean") {
+        return String(value);
+    }
+    try {
+        const serialized = JSON.stringify(value);
+        return serialized ?? fallback;
+    }
+    catch {
+        return fallback;
+    }
+}
+function isRecord(value) {
+    return value !== null && typeof value === "object";
+}
+async function delay(ms) {
+    await new Promise((resolve) => setTimeout(resolve, ms));
+}
+function isPathInsideDirectory(candidate, directory) {
+    const relation = relative(directory, candidate);
+    return relation !== "" && !relation.startsWith("..") && !isAbsolute(relation);
+}
+//# sourceMappingURL=storage.js.map