clinkx 0.3.0 → 1.0.0

package/dist/context-builder/workflow-runner.js

@@ -0,0 +1,1051 @@
+import { randomUUID } from "node:crypto";
+import { realpathSync, statSync } from "node:fs";
+import { copyFile, mkdir, readFile, realpath, rename, rm, utimes, } from "node:fs/promises";
+import { isAbsolute, join, relative, resolve } from "node:path";
+// ---------------------------------------------------------------------------
+// Deep `clinkx-workflows/dist` imports (one-way dependency, build-order coupled)
+//
+// The next four imports pull cache-key, preflight-contract, config, and
+// workspace-signature helpers from the COMPILED output of the sibling
+// `clinkx-workflows` package rather than from a published entry point. This is
+// deliberate and safe:
+//
+//   - The dependency arrow points one way: root -> clinkx-workflows. The
+//     workflows package defines only the `ContextBuilderRunner` callback
+//     interface and never statically imports the root `context-builder/`
+//     modules, so there is no import cycle. See docs/architecture.md, "Module
+//     boundary (no dependency cycle)".
+//   - `clinkx-workflows` is a separate tsc project with no package `exports`
+//     map; its public runtime surface is its `dist/*.js` files. Importing its
+//     source `.ts` would violate the NodeNext + `.js`-extension ESM contract.
+//
+// BUILD ORDER: `clinkx-workflows/dist` MUST be built before the root package is
+// built or run. `npm run build:all` enforces this (clinkx-workflows first, then
+// root). A bare `npm run build` assumes dist already exists; a missing dist
+// surfaces as ERR_MODULE_NOT_FOUND at import time, not a compile error.
+// ---------------------------------------------------------------------------
+import { computeCacheKey, computeInputsHash, deriveWfctxId, } from "../../clinkx-workflows/dist/context-cache-key.js";
+import { resolveWorkspaceRoot as resolveWorkflowWorkspaceRoot } from "../../clinkx-workflows/dist/config.js";
+import { createSessionLogGeneration, readSessionLogGeneration, } from "../../clinkx-workflows/dist/dashboard/session-log-identity.js";
+import { getSignatureCoveredPaths, workspaceSignature as computeWorkspaceSignature, } from "../../clinkx-workflows/dist/workspace-signature.js";
+import { isArtifactOnlyAllowedRootEntry, isPathWithinAllowedRoots, } from "../allowed-roots.js";
+import { CancellationError, ExecutionError, InvalidParamsError } from "../errors.js";
+import { logger } from "../logger.js";
+import { getCurrentAllowedRoots } from "../paths.js";
+import { CONTEXT_BUILDER_RENDERER_VERSION } from "./bundle.js";
+import { CONTEXT_DELEGATE_PROMPT_VERSION, CONTEXT_DISCOVERY_ALGORITHM_VERSION, } from "./versions.js";
+import { getSharedContextBuilderSemaphore, resolveContextBuilderRunsDir, } from "./config.js";
+import { handleContextBuilder } from "./handler.js";
+import { CONTEXT_BUILDER_INTENT_PROFILE_DEFAULTS, CONTEXT_BUILDER_INTENT_PROFILES, resolveContextBuilderAdapterBudgetInput, } from "./schema.js";
+import { assertNoHighConfidenceSecretsInTask, resolveAllowSecrets, } from "./secrets.js";
+import { CONTEXT_BUILDER_DELEGATE_SCHEMA_VERSION, CONTEXT_BUILDER_NO_DELEGATE_SCHEMA_VERSION, createContextBuilderReceipt, } from "./receipt.js";
+import { notEvaluatedCoverageReport, } from "./review-coverage.js";
+import { isContextBuilderRunCommitted, evictWorkflowContextRuns, promoteContextBuilderRun, resolveContextBuilderRunPaths, withContextBuilderRunMutationLease, } from "./storage.js";
+import { ContextBuilderLifecycleController, ContextBuilderLifecycleObserverError, } from "./lifecycle-observer.js";
+export function createWorkflowContextBuilderRunner(options = {}) {
+    const cb = options.handleContextBuilder ?? handleContextBuilder;
+    // Default to the SHARED process-wide context_builder gate so workflow
+    // preflight, standalone context_builder, and refine_context_run all contend
+    // for one CLINKX_CONTEXT_BUILDER_MAX_CONCURRENT permit pool. Tests may inject
+    // their own semaphore for isolation.
+    const semaphore = options.semaphore ?? getSharedContextBuilderSemaphore();
+    const runIdFactory = options.runIdFactory ?? generateWorkflowPreflightRunId;
+    const workspaceRootResolver = options.resolveWorkspaceRoot ?? resolveWorkflowWorkspaceRoot;
+    const workspaceSignature = options.workspaceSignature ?? computeWorkspaceSignature;
+    const signatureCoveredPaths = options.getSignatureCoveredPaths ?? getSignatureCoveredPaths;
+    const rendererVersion = options.rendererVersion ?? CONTEXT_BUILDER_RENDERER_VERSION;
+    const discoveryAlgorithmVersion = options.discoveryAlgorithmVersion ?? CONTEXT_DISCOVERY_ALGORITHM_VERSION;
+    const delegatePromptVersion = options.delegatePromptVersion ?? CONTEXT_DELEGATE_PROMPT_VERSION;
+    const registry = options.registry;
+    return {
+        assertRootsAllowed(roots) {
+            assertExplicitRootsWithinAllowed(roots);
+        },
+        assertTaskSecretsAllowed(variables) {
+            const rawFlag = variables["cb_allow_secrets"];
+            const explicit = typeof rawFlag === "boolean" ? rawFlag : undefined;
+            if (resolveAllowSecrets(explicit)) {
+                return;
+            }
+            for (const key of ["cb_task", "user_request"]) {
+                const value = variables[key];
+                if (typeof value === "string" && value.length > 0) {
+                    assertNoHighConfidenceSecretsInTask(value);
+                }
+            }
+        },
+        async runOrReuse(input, opts) {
+            let lifecycle;
+            try {
+                throwIfAborted(opts.signal);
+                const mappedInput = await mapPreflightContextInput(input, {
+                    resolveWorkspaceRoot: workspaceRootResolver,
+                });
+                const mapped = input.context_budget_adapter == null ||
+                    input.context_budget_adapter.trim() === ""
+                    ? mappedInput
+                    : {
+                        ...mappedInput,
+                        budget: resolveContextBuilderAdapterBudgetInput({
+                            adapterDefaults: resolveAdapterBudgetDefaults(registry, input.context_budget_adapter),
+                            profile: mappedInput.profile,
+                            explicit: mappedInput.budget,
+                        }),
+                    };
+                const lifecycleInjection = options.lifecycleFactory?.(input);
+                lifecycle = lifecycleInjection == null
+                    ? undefined
+                    : new ContextBuilderLifecycleController({
+                        operationKind: "workflow_preflight",
+                        execution: workflowLifecycleExecutionConfig(mapped),
+                        observer: lifecycleInjection.observer,
+                        ...(lifecycleInjection.origin == null
+                            ? {}
+                            : { origin: lifecycleInjection.origin }),
+                        ...(options.lifecycleNow == null
+                            ? {}
+                            : { now: options.lifecycleNow }),
+                    });
+                await lifecycle?.transition("resolving");
+                // The controller has now minted the preflight operation id
+                // (lifecycle.contextRunId). Pair it with a generation sidecar created under
+                // the workflow run dir so the dashboard can later locate the preflight's
+                // session-log subtree. Only the injected-lifecycle (workflow) path builds
+                // this; the standalone path derives its own identity from its journal.
+                const preflightSessionLogContext = lifecycle == null
+                    ? undefined
+                    : await resolvePreflightSessionLogContext(input.runDir, lifecycle.contextRunId);
+                const cacheInput = {
+                    ...mapped,
+                    roots: await normalizeCacheRoots(mapped.roots),
+                };
+                const includeSelectedContext = input.includeSelectedContext === true;
+                const effectiveSchemaVersion = mapped.delegate.enabled === true
+                    ? CONTEXT_BUILDER_DELEGATE_SCHEMA_VERSION
+                    : CONTEXT_BUILDER_NO_DELEGATE_SCHEMA_VERSION;
+                const cacheSchemaVersion = options.cbSchemaVersion ?? effectiveSchemaVersion;
+                const runsDir = await resolveContextBuilderRunsDir(options.runsDir);
+                let preSig = await workspaceSignature(mapped.roots);
+                throwIfAborted(opts.signal);
+                let cache = deriveCacheCoordinates(cacheInput, preSig, runsDir, {
+                    rendererVersion,
+                    cbSchemaVersion: cacheSchemaVersion,
+                    discoveryAlgorithmVersion,
+                    delegatePromptVersion,
+                });
+                let cacheReason = "cache_miss";
+                if (await isContextBuilderRunCommitted(cache.targetStorage.runDir)) {
+                    const postSig = await workspaceSignature(mapped.roots);
+                    throwIfAborted(opts.signal);
+                    if (postSig === preSig) {
+                        const hit = await withContextBuilderRunMutationLease(cache.targetStorage, async () => {
+                            // The unleased probe above is only an optimization. Pruning may
+                            // win before this lease is acquired, so re-check under the lock
+                            // before reading the manifest or materializing any artifact.
+                            if (!await isContextBuilderRunCommitted(cache.targetStorage.runDir)) {
+                                return undefined;
+                            }
+                            // Refresh directory mtime so LRU eviction treats this as recently used.
+                            try {
+                                const now = new Date();
+                                await utimes(cache.targetStorage.runDir, now, now);
+                            }
+                            catch {
+                                // best-effort — a hit must not fail because utimes failed
+                            }
+                            return await synthesizePreflightResultFromCommittedRun({
+                                storage: cache.targetStorage,
+                                runDir: input.runDir,
+                                keyPrefix: cache.keyPrefix,
+                                schemaVersion: effectiveSchemaVersion,
+                                budgetCaps: mapped.budget,
+                                includeSelectedContext,
+                                ...(lifecycle == null ? {} : { lifecycle }),
+                            });
+                        });
+                        if (hit !== undefined) {
+                            await lifecycle?.complete(workflowLifecycleTerminalStatus(hit), {
+                                artifactRunId: hit.source_run_id,
+                                ...workflowResultLifecyclePatch(hit, lifecycle, true),
+                            });
+                            return hit;
+                        }
+                        cacheReason = "cache_stale";
+                    }
+                    else {
+                        cacheReason = "cache_stale";
+                        preSig = postSig;
+                        cache = deriveCacheCoordinates(cacheInput, preSig, runsDir, {
+                            rendererVersion,
+                            cbSchemaVersion: cacheSchemaVersion,
+                            discoveryAlgorithmVersion,
+                            delegatePromptVersion,
+                        });
+                    }
+                }
+                await lifecycle?.transition("cache_lookup", {
+                    cache: {
+                        lookup: "miss",
+                        write: "not_attempted",
+                        reason_code: cacheReason,
+                    },
+                    reasonCodes: [cacheReason],
+                });
+                const tempId = runIdFactory();
+                const tempInput = { ...mapped, run_id: tempId };
+                const response = await cb(tempInput, {
+                    runsDir,
+                    semaphore,
+                    ...(registry == null ? {} : { registry }),
+                    ...(input.allowRootWideDiscovery == null
+                        ? {}
+                        : { allowRootWideDiscovery: input.allowRootWideDiscovery }),
+                    ...(opts.signal == null ? {} : { signal: opts.signal }),
+                    ...(lifecycle == null ? {} : { lifecycleController: lifecycle }),
+                    ...(preflightSessionLogContext == null
+                        ? {}
+                        : { sessionLogContext: preflightSessionLogContext }),
+                });
+                throwIfAborted(opts.signal);
+                const receipt = parseReceiptResponse(response);
+                const tempStorage = resolveContextBuilderRunPaths(runsDir, tempId);
+                // The id of the run this call will return as its live source. Eviction in
+                // the finally must protect it so small/zero retention bounds cannot delete
+                // the run whose source_artifact_dir we are about to hand back.
+                let liveSourceRunId = tempId;
+                try {
+                    const tempManifest = await readManifest(tempStorage.manifestJson);
+                    // Degraded fallback selections (delegate failure_policy:"fallback") must
+                    // NEVER enter the shared wfctx cache: a cached fallback would be replayed
+                    // for a later fail-closed failure_policy:"fail" request (silently
+                    // succeeding instead of failing) and would mask genuine delegated
+                    // successes. Not caching also lets a later identical request retry
+                    // delegation rather than reusing a stale degraded bundle. The manifest
+                    // is the authoritative persisted source; fall back to the receipt.
+                    const fallbackUsed = tempManifest.delegate?.fallback_used === true ||
+                        receipt.delegate?.fallback_used === true;
+                    const selectedPaths = await resolveSelectedContextPaths(tempManifest, mapped.roots);
+                    const gate = await evaluatePostCbPromotionGate({
+                        roots: mapped.roots,
+                        selectedPaths,
+                        workspaceSignature,
+                        signatureCoveredPaths,
+                    });
+                    throwIfAborted(opts.signal);
+                    if (!fallbackUsed && gate?.selectedFilesCovered === true && gate.postSig === preSig) {
+                        try {
+                            await lifecycle?.transition("materializing");
+                            const promoted = await promoteContextBuilderRun(tempStorage.runDir, cache.wfctxId);
+                            // Promote succeeded and renamed temp → wfctx: protect the wfctx run
+                            // immediately so a later throw (e.g. copyBundleArtifactsIntoRun) can
+                            // never leave the freshly-promoted run unprotected against zero/small
+                            // retention eviction in the finally.
+                            liveSourceRunId = cache.wfctxId;
+                            // Copy from the PROMOTED wfctx run (the temp dir is now deleted) so
+                            // the fanned manifest's run_id matches the returned source_run_id and
+                            // its artifact paths point at live files.
+                            const promotedManifest = await readManifest(promoted.manifestJson);
+                            const resultBeforeMaterialization = buildPreflightResult({
+                                receipt: createReceiptFromManifest(promotedManifest, promoted),
+                                sourceRunId: cache.wfctxId,
+                                sourceArtifactDir: promoted.runDir,
+                                cache: {
+                                    hit: false,
+                                    write: true,
+                                    target_id: cache.wfctxId,
+                                    key_prefix: cache.keyPrefix,
+                                },
+                                copiedPaths: [],
+                                schemaVersion: effectiveSchemaVersion,
+                                observability: preflightObservabilityFromManifest(tempManifest, mapped.budget),
+                                coverage: coverageFromManifest(tempManifest),
+                            });
+                            const copiedPaths = await copyBundleArtifactsIntoRun(promotedManifest.artifacts, input.runDir, {
+                                includeSelectedContext,
+                                ...(lifecycle == null
+                                    ? {}
+                                    : {
+                                        beforeManifestCommit: async () => {
+                                            await lifecycle?.transition("committing", {
+                                                artifactRunId: resultBeforeMaterialization.source_run_id,
+                                                cache: {
+                                                    lookup: "miss",
+                                                    write: "written",
+                                                    reason_code: cacheReason,
+                                                },
+                                                ...workflowResultLifecyclePatch(resultBeforeMaterialization, lifecycle),
+                                            });
+                                        },
+                                    }),
+                            });
+                            const result = {
+                                ...resultBeforeMaterialization,
+                                copied_paths: copiedPaths,
+                            };
+                            await lifecycle?.complete(workflowLifecycleTerminalStatus(result), {
+                                artifactRunId: result.source_run_id,
+                                ...workflowResultLifecyclePatch(result, lifecycle),
+                            });
+                            return result;
+                        }
+                        catch (error) {
+                            if (!isPromoteClaimConflict(error)) {
+                                throw error;
+                            }
+                        }
+                    }
+                    // Non-promote (or promote-claim-conflict) path: copy from the surviving
+                    // temp run, which is the authoritative source for the returned id.
+                    await lifecycle?.transition("materializing");
+                    const resultBeforeMaterialization = buildPreflightResult({
+                        receipt: createReceiptFromManifest(tempManifest, tempStorage),
+                        sourceRunId: tempId,
+                        sourceArtifactDir: tempStorage.runDir,
+                        cache: {
+                            hit: false,
+                            write: false,
+                            target_id: null,
+                            key_prefix: cache.keyPrefix,
+                        },
+                        copiedPaths: [],
+                        schemaVersion: effectiveSchemaVersion,
+                        observability: preflightObservabilityFromManifest(tempManifest, mapped.budget),
+                        coverage: coverageFromManifest(tempManifest),
+                    });
+                    const copiedPaths = await copyBundleArtifactsIntoRun(tempManifest.artifacts, input.runDir, {
+                        includeSelectedContext,
+                        ...(lifecycle == null
+                            ? {}
+                            : {
+                                beforeManifestCommit: async () => {
+                                    await lifecycle?.transition("committing", {
+                                        artifactRunId: resultBeforeMaterialization.source_run_id,
+                                        cache: {
+                                            lookup: "miss",
+                                            write: "skipped",
+                                            reason_code: cacheReason,
+                                        },
+                                        ...workflowResultLifecyclePatch(resultBeforeMaterialization, lifecycle),
+                                    });
+                                },
+                            }),
+                    });
+                    const result = {
+                        ...resultBeforeMaterialization,
+                        copied_paths: copiedPaths,
+                    };
+                    await lifecycle?.complete(workflowLifecycleTerminalStatus(result), {
+                        artifactRunId: result.source_run_id,
+                        ...workflowResultLifecyclePatch(result, lifecycle),
+                    });
+                    return result;
+                }
+                finally {
+                    // Best-effort, prefix-scoped/TTL-guarded eviction on every completed
+                    // MISS path (promote and non-promote). The active source run of this
+                    // call is protected so zero/small retention bounds cannot self-delete
+                    // the run whose source_artifact_dir we just returned.
+                    await evictWorkflowContextRuns(runsDir, {
+                        protectedRunIds: [liveSourceRunId],
+                    })
+                        .then((eviction) => {
+                        if (eviction.failed > 0) {
+                            logger.warn({ runsDir, eviction }, "workflow context_builder cache eviction had delete failures");
+                        }
+                    })
+                        .catch((err) => {
+                        logger.warn({ err, runsDir }, "workflow context_builder cache eviction failed");
+                    });
+                }
+            }
+            catch (error) {
+                if (lifecycle != null && !(error instanceof ContextBuilderLifecycleObserverError)) {
+                    const cancelled = error instanceof CancellationError || opts.signal?.aborted === true;
+                    const delegateFailed = workflowDelegateExecutionActive(lifecycle);
+                    await lifecycle.fail(cancelled ? "cancelled" : "failed", {
+                        ...workflowTerminalExecutionPatch(lifecycle, cancelled),
+                        reasonCodes: [
+                            cancelled
+                                ? "operation_cancelled"
+                                : delegateFailed
+                                    ? "delegate_failed"
+                                    : "internal_failure",
+                        ],
+                        ...(!cancelled && delegateFailed
+                            ? {
+                                fallback: {
+                                    status: "failed",
+                                    reason_code: "delegate_failed",
+                                },
+                            }
+                            : {}),
+                    });
+                }
+                // Rethrow the ORIGINAL error object, never a wrapper: markers set by
+                // the handler (e.g. ExecutionError.failureClass:"transient" on a
+                // delegate timeout) must reach the workflow engine's failure
+                // classifier intact.
+                throw error;
+            }
+        },
+    };
+}
+/**
+ * Subdirectory of the workflow run dir holding the preflight session-log
+ * generation sidecar. The dashboard reads this back to locate the preflight's
+ * session-log subtree and to pair it with the persisted lifecycle context_run_id.
+ */
+const PREFLIGHT_SESSION_LOG_DIR = ".context-preflight";
+/**
+ * Create-or-read the preflight session-log generation sidecar under the workflow
+ * run dir, then pair it with the controller-minted operation id. Create-or-read
+ * (rather than exclusive-create) keeps the generation stable across retries of
+ * the same run. Best-effort: any failure resolves to undefined, and the preflight
+ * renders without a `[ log ]` affordance (the prior telemetry-only contract).
+ */
+async function resolvePreflightSessionLogContext(runDir, contextRunId) {
+    try {
+        const sidecarDir = join(runDir, PREFLIGHT_SESSION_LOG_DIR);
+        await mkdir(sidecarDir, { recursive: true, mode: 0o700 });
+        const existing = await readSessionLogGeneration(sidecarDir);
+        const contextGeneration = existing.kind === "available"
+            ? existing.sessionLogGeneration
+            : await createSessionLogGeneration(sidecarDir);
+        return { contextRunId, contextGeneration };
+    }
+    catch {
+        return undefined;
+    }
+}
+function workflowLifecycleExecutionConfig(input) {
+    if (input.delegate.enabled !== true) {
+        return {
+            curator: { configured: false, enabled: false },
+            finalizer: { configured: false, enabled: false },
+        };
+    }
+    const finalizerEnabled = input.delegate.finalizer.enabled ??
+        (input.profile == null
+            ? true
+            : CONTEXT_BUILDER_INTENT_PROFILE_DEFAULTS[input.profile].finalizer_enabled);
+    return {
+        curator: { configured: true, enabled: true },
+        finalizer: { configured: true, enabled: finalizerEnabled },
+    };
+}
+function workflowLifecycleTerminalStatus(result) {
+    return result.delegate?.fallback_used === true || result.status === "partial"
+        ? "partial"
+        : "succeeded";
+}
+function workflowResultLifecyclePatch(result, lifecycle, cacheHit = false) {
+    const coverage = result.coverage ?? notEvaluatedCoverageReport();
+    const required = coverage.required_when_available.length;
+    const missing = coverage.missing_required.length;
+    const snapshot = lifecycle?.snapshot;
+    const executionPatch = cacheHit
+        ? {
+            ...(snapshot?.curator.effective_enabled === true
+                ? { curatorStatus: "skipped" }
+                : {}),
+            ...(snapshot?.finalizer.effective_enabled === true
+                ? { finalizerStatus: "skipped" }
+                : {}),
+        }
+        : result.delegate?.fallback_used === true
+            ? {
+                ...(snapshot?.curator.effective_enabled === true
+                    ? { curatorStatus: "failed" }
+                    : {}),
+                ...(snapshot?.finalizer.effective_enabled === true
+                    ? { finalizerStatus: "skipped" }
+                    : {}),
+                fallback: {
+                    status: "used",
+                    reason_code: "delegate_fallback",
+                },
+                reasonCodes: ["delegate_fallback"],
+            }
+            : {
+                ...(snapshot?.curator.effective_enabled === true &&
+                    snapshot.curator.execution_status === "pending"
+                    ? { curatorStatus: "succeeded" }
+                    : {}),
+                ...(snapshot?.finalizer.effective_enabled === true &&
+                    snapshot.finalizer.execution_status === "pending"
+                    ? { finalizerStatus: "succeeded" }
+                    : {}),
+            };
+    return {
+        ...executionPatch,
+        counts: {
+            files_seen: cacheHit ? 0 : result.metrics.files_seen,
+            files_considered: cacheHit ? 0 : result.metrics.files_considered,
+            files_selected: result.metrics.files_selected,
+            files_omitted: cacheHit ? 0 : result.metrics.files_omitted,
+            search_results: cacheHit ? 0 : snapshot?.counts.search_results ?? 0,
+            bytes_read: cacheHit ? 0 : result.metrics.bytes_read,
+            bytes_written: result.metrics.bytes_written,
+        },
+        coverage: {
+            policy: coverage.policy_id,
+            status: coverage.status,
+            required,
+            selected: Math.max(0, required - missing),
+            missing,
+        },
+        ...(coverage.status === "degraded"
+            ? { reasonCodes: [...(executionPatch.reasonCodes ?? []), "coverage_degraded"] }
+            : {}),
+    };
+}
+function workflowTerminalExecutionPatch(lifecycle, cancelled) {
+    const snapshot = lifecycle.snapshot;
+    if (snapshot == null)
+        return {};
+    const terminalStatus = cancelled ? "cancelled" : "failed";
+    return {
+        ...(snapshot.curator.execution_status === "running"
+            ? { curatorStatus: terminalStatus }
+            : snapshot.curator.execution_status === "pending"
+                ? { curatorStatus: "skipped" }
+                : {}),
+        ...(snapshot.finalizer.execution_status === "running"
+            ? { finalizerStatus: terminalStatus }
+            : snapshot.finalizer.execution_status === "pending"
+                ? { finalizerStatus: "skipped" }
+                : {}),
+    };
+}
+function workflowDelegateExecutionActive(lifecycle) {
+    const snapshot = lifecycle.snapshot;
+    return snapshot?.curator.execution_status === "running" ||
+        snapshot?.finalizer.execution_status === "running";
+}
+export async function copyBundleIntoRun(receipt, runDir, options = {}) {
+    return copyBundleArtifactsIntoRun(receipt.artifacts, runDir, options);
+}
+export async function copyBundleArtifactsIntoRun(artifacts, runDir, options = {}) {
+    const runRoot = await realpath(runDir);
+    const contextDir = join(runRoot, "artifacts", "context");
+    await mkdir(contextDir, { recursive: true });
+    const realContextDir = await realpath(contextDir);
+    const bundleDest = await copyArtifactIntoContextDir(await resolveArtifactPath(artifacts, "bundle_md", "bundle.md"), realContextDir, "bundle.md");
+    const selectedContextDest = options.includeSelectedContext === true
+        ? await copyArtifactIntoContextDir(await resolveArtifactPath(artifacts, "selected_context_jsonl", "selected-context.jsonl"), realContextDir, "selected-context.jsonl")
+        : undefined;
+    const manifestSource = await resolveArtifactPath(artifacts, "manifest_json", "manifest.json");
+    await options.beforeManifestCommit?.();
+    const manifestDest = await copyArtifactIntoContextDir(manifestSource, realContextDir, "manifest.json");
+    return selectedContextDest == null
+        ? [bundleDest, manifestDest]
+        : [bundleDest, selectedContextDest, manifestDest];
+}
+export async function mapPreflightContextInput(input, options) {
+    assertExplicitRootsWithinAllowed(input.roots);
+    const task = input.cb_task.trim() === "" ? input.user_request : input.cb_task;
+    const roots = input.roots.length > 0
+        ? [...input.roots]
+        : [await resolveFallbackRoot(options.resolveWorkspaceRoot)];
+    const profile = validateProfile(input.profile);
+    return {
+        task,
+        roots,
+        focus_paths: [...input.focus_paths],
+        include_globs: [...input.include_globs],
+        exclude_globs: [...input.exclude_globs],
+        search_terms: [...input.search_terms],
+        allow_secrets: resolveAllowSecrets(input.allow_secrets),
+        budget: input.budget ?? {},
+        delegate: input.delegate ?? { enabled: false },
+        ...(options.run_id == null ? {} : { run_id: options.run_id }),
+        ...(profile == null ? {} : { profile }),
+    };
+}
+// cb_budget_adapter is intentionally backend-agnostic: this only reads numeric
+// context_builder.budget_defaults and NEVER executes the adapter, so app_server
+// adapters are permitted here even though they are rejected for execution.
+function resolveAdapterBudgetDefaults(registry, name) {
+    const trimmed = name?.trim();
+    if (trimmed == null || trimmed === "") {
+        return {};
+    }
+    if (registry == null) {
+        throw new InvalidParamsError(`cb_budget_adapter "${trimmed}" set but no adapter registry is available`);
+    }
+    const budgetDefaults = registry.resolveAdapter(trimmed).context_builder?.budget_defaults ?? {};
+    return {
+        ...(budgetDefaults.max_estimated_tokens == null
+            ? {}
+            : { max_estimated_tokens: budgetDefaults.max_estimated_tokens }),
+        ...(budgetDefaults.max_files == null
+            ? {}
+            : { max_files: budgetDefaults.max_files }),
+        ...(budgetDefaults.max_scan_files == null
+            ? {}
+            : { max_scan_files: budgetDefaults.max_scan_files }),
+        ...(budgetDefaults.max_bytes_per_file == null
+            ? {}
+            : { max_bytes_per_file: budgetDefaults.max_bytes_per_file }),
+        ...(budgetDefaults.max_total_bytes == null
+            ? {}
+            : { max_total_bytes: budgetDefaults.max_total_bytes }),
+        ...(budgetDefaults.max_search_results == null
+            ? {}
+            : { max_search_results: budgetDefaults.max_search_results }),
+    };
+}
+function deriveCacheCoordinates(mappedInput, workspaceSig, runsDir, versions) {
+    const inputsHash = computeInputsHash(mappedInput);
+    const cacheKey = computeCacheKey({
+        inputsHash,
+        workspaceSig,
+        rendererVersion: versions.rendererVersion,
+        cbSchemaVersion: versions.cbSchemaVersion,
+        discoveryAlgorithmVersion: versions.discoveryAlgorithmVersion,
+        delegatePromptVersion: versions.delegatePromptVersion,
+    });
+    const wfctxId = deriveWfctxId(cacheKey);
+    return {
+        workspaceSig,
+        cacheKey,
+        wfctxId,
+        keyPrefix: cacheKey.slice(0, 16),
+        targetStorage: resolveContextBuilderRunPaths(runsDir, wfctxId),
+    };
+}
+async function synthesizePreflightResultFromCommittedRun(input) {
+    try {
+        const manifest = await readManifest(input.storage.manifestJson);
+        // A committed fallback bundle is degraded (delegate failure_policy:"fallback")
+        // and must NEVER be served, especially to a fail-closed failure_policy:"fail"
+        // request (failure_policy is intentionally not in the cache key). A poisoned
+        // wfctx entry can exist from a mixed-version/older writer, an external/manual
+        // artifact, or a future code path. Treat it as a cache MISS (return undefined,
+        // the same value the ENOENT/not-usable case returns) so runOrReuse falls
+        // through and re-runs the builder; a real "fail" policy then fails closed.
+        if (manifest.delegate?.fallback_used === true) {
+            return undefined;
+        }
+        const receipt = createReceiptFromManifest(manifest, input.storage);
+        const resultBeforeMaterialization = buildPreflightResult({
+            receipt,
+            sourceRunId: input.storage.runId,
+            sourceArtifactDir: input.storage.runDir,
+            cache: {
+                hit: true,
+                write: false,
+                target_id: input.storage.runId,
+                key_prefix: input.keyPrefix,
+            },
+            copiedPaths: [],
+            schemaVersion: input.schemaVersion,
+            observability: preflightObservabilityFromManifest(manifest, input.budgetCaps),
+            coverage: coverageFromManifest(manifest),
+        });
+        await input.lifecycle?.transition("cache_lookup", {
+            artifactRunId: resultBeforeMaterialization.source_run_id,
+            cache: { lookup: "hit", write: "skipped" },
+            ...workflowResultLifecyclePatch(resultBeforeMaterialization, input.lifecycle, true),
+        });
+        await input.lifecycle?.transition("materializing");
+        const copiedPaths = await copyBundleArtifactsIntoRun(manifest.artifacts, input.runDir, {
+            includeSelectedContext: input.includeSelectedContext,
+            ...(input.lifecycle == null
+                ? {}
+                : {
+                    beforeManifestCommit: async () => {
+                        await input.lifecycle?.transition("committing");
+                    },
+                }),
+        });
+        return buildPreflightResult({
+            receipt,
+            sourceRunId: input.storage.runId,
+            sourceArtifactDir: input.storage.runDir,
+            cache: {
+                hit: true,
+                write: false,
+                target_id: input.storage.runId,
+                key_prefix: input.keyPrefix,
+            },
+            copiedPaths,
+            schemaVersion: input.schemaVersion,
+            observability: preflightObservabilityFromManifest(manifest, input.budgetCaps),
+            coverage: coverageFromManifest(manifest),
+        });
+    }
+    catch (error) {
+        if (isNodeError(error)
+            && error.code === "ENOENT"
+            && input.lifecycle?.snapshot?.cache.lookup !== "hit") {
+            return undefined;
+        }
+        throw error;
+    }
+}
+function createReceiptFromManifest(manifest, storage) {
+    return createContextBuilderReceipt({
+        run_id: storage.runId,
+        status: manifest.status,
+        artifact_dir: storage.artifactDir,
+        artifacts: { ...manifest.artifacts },
+        metrics: manifest.metrics,
+        warnings: [...manifest.warnings],
+        omissions: [...manifest.omissions],
+        ...(manifest.delegate == null ? {} : { delegate: manifest.delegate }),
+    });
+}
+function buildPreflightResult(input) {
+    // The request-derived effective schema (input.schemaVersion) must match the
+    // receipt's own schema. A divergence means a handler-contract violation (e.g.
+    // a delegate-enabled request whose handler returned a no-delegate v1 receipt),
+    // which would otherwise emit schema_version:2 with no delegate metadata. Fail
+    // loudly rather than emit a contradictory result.
+    if (input.schemaVersion !== input.receipt.schema_version) {
+        throw new ExecutionError("context_builder schema mismatch: request-derived schema_version " +
+            `${input.schemaVersion} does not match receipt schema_version ` +
+            `${input.receipt.schema_version}`);
+    }
+    // A delegate schema_version that carries no delegate metadata is contradictory
+    // (a delegated build that lost its delegate provenance). Fail loudly rather
+    // than silently emitting delegate: undefined, which would erase fallback_used.
+    if (input.receipt.schema_version === CONTEXT_BUILDER_DELEGATE_SCHEMA_VERSION
+        && input.receipt.delegate == null) {
+        throw new ExecutionError("context_builder receipt has delegate schema_version but no delegate metadata");
+    }
+    const delegate = input.receipt.schema_version === CONTEXT_BUILDER_DELEGATE_SCHEMA_VERSION
+        && input.receipt.delegate != null
+        ? {
+            enabled: true,
+            status: input.receipt.delegate.status,
+            fallback_used: input.receipt.delegate.fallback_used,
+        }
+        : undefined;
+    return {
+        receipt: input.receipt,
+        source_run_id: input.sourceRunId,
+        source_artifact_dir: input.sourceArtifactDir,
+        cache: input.cache,
+        schema_version: input.schemaVersion,
+        status: input.receipt.status,
+        copied_paths: input.copiedPaths,
+        coverage: input.coverage,
+        metrics: input.receipt.metrics,
+        warning_count: input.receipt.warnings.length,
+        omission_count: input.receipt.omissions.length,
+        ...(delegate == null ? {} : { delegate }),
+        ...(input.observability == null
+            ? {}
+            : { observability: input.observability }),
+    };
+}
+function preflightObservabilityFromManifest(manifest, budgetCaps) {
+    const raw = manifest["observability"];
+    const record = raw !== null && typeof raw === "object"
+        ? raw
+        : {};
+    return {
+        curator_ms: nullableNonNegativeNumber(record["curator_ms"]),
+        finalizer_ms: nullableNonNegativeNumber(record["finalizer_ms"]),
+        candidate_pool_size: nonNegativeInteger(record["candidate_pool_size"]),
+        delegate_packet_size: nonNegativeInteger(record["delegate_packet_size"]),
+        budget_caps: budgetCapsFromManifest(manifest["budget"], budgetCaps),
+    };
+}
+function coverageFromManifest(manifest) {
+    const value = manifest["coverage"];
+    if (value === null || typeof value !== "object") {
+        return notEvaluatedCoverageReport();
+    }
+    const coverage = value;
+    if (!isCoveragePolicyId(coverage["policy_id"])
+        || !isCoverageStatus(coverage["status"])
+        || !isEvidenceClassArray(coverage["required_when_available"])
+        || !isEvidenceClassArray(coverage["available"])
+        || !isEvidenceClassArray(coverage["selected"])
+        || !isEvidenceClassArray(coverage["missing_required"])
+        || !isEvidenceClassArray(coverage["advisory_missing"])
+        || !isEvidenceClassArray(coverage["unclassifiable"])) {
+        return notEvaluatedCoverageReport();
+    }
+    if (!isSemanticallyConsistentCoverage(coverage)) {
+        return notEvaluatedCoverageReport();
+    }
+    return {
+        policy_id: coverage["policy_id"],
+        status: coverage["status"],
+        required_when_available: [...coverage["required_when_available"]],
+        available: [...coverage["available"]],
+        selected: [...coverage["selected"]],
+        missing_required: [...coverage["missing_required"]],
+        advisory_missing: [...coverage["advisory_missing"]],
+        unclassifiable: [...coverage["unclassifiable"]],
+    };
+}
+function isSemanticallyConsistentCoverage(coverage) {
+    const policyId = coverage["policy_id"];
+    const status = coverage["status"];
+    const available = new Set(coverage["available"]);
+    const selected = coverage["selected"];
+    const missing = coverage["missing_required"];
+    if (policyId === null) {
+        return (status === "not_evaluated" &&
+            available.size === 0 &&
+            selected.length === 0 &&
+            missing.length === 0);
+    }
+    if (status === "not_evaluated") {
+        return false;
+    }
+    if (selected.some((evidenceClass) => !available.has(evidenceClass))) {
+        return false;
+    }
+    if (status === "satisfied") {
+        return missing.length === 0 && available.has("review_target");
+    }
+    return missing.length > 0;
+}
+function isCoveragePolicyId(value) {
+    return value === null || value === "review_deep_v1";
+}
+function isCoverageStatus(value) {
+    return value === "satisfied" || value === "degraded" || value === "not_evaluated";
+}
+function isEvidenceClassArray(value) {
+    return Array.isArray(value) && value.every(isEvidenceClass);
+}
+function isEvidenceClass(value) {
+    return value === "review_target"
+        || value === "public_entrypoint"
+        || value === "reverse_consumer"
+        || value === "configuration"
+        || value === "dependency"
+        || value === "regression_test";
+}
+function budgetCapsFromManifest(value, fallback) {
+    if (value === null || typeof value !== "object") {
+        return { ...fallback };
+    }
+    const record = value;
+    return {
+        ...optionalPositiveIntegerCap(record, "max_estimated_tokens"),
+        ...optionalPositiveIntegerCap(record, "max_files"),
+        ...optionalPositiveIntegerCap(record, "max_scan_files"),
+        ...optionalPositiveIntegerCap(record, "max_bytes_per_file"),
+        ...optionalPositiveIntegerCap(record, "max_total_bytes"),
+        ...optionalPositiveIntegerCap(record, "max_search_results"),
+    };
+}
+function optionalPositiveIntegerCap(record, key) {
+    const value = record[key];
+    return typeof value === "number" && Number.isInteger(value) && value > 0
+        ? { [key]: value }
+        : {};
+}
+function nullableNonNegativeNumber(value) {
+    return typeof value === "number" && Number.isFinite(value) && value >= 0
+        ? value
+        : null;
+}
+function nonNegativeInteger(value) {
+    return typeof value === "number" && Number.isInteger(value) && value >= 0
+        ? value
+        : 0;
+}
+async function readManifest(manifestPath) {
+    return JSON.parse(await readFile(manifestPath, "utf8"));
+}
+async function resolveSelectedContextPaths(manifest, roots) {
+    const selected = Array.isArray(manifest["selected_context"])
+        ? manifest["selected_context"]
+        : [];
+    const absolutePaths = [];
+    for (const entry of selected) {
+        if (entry === null || typeof entry !== "object") {
+            throw new ExecutionError("context_builder manifest selected_context entry is invalid");
+        }
+        const rootIndex = entry.root_index;
+        const selectedPath = entry.path;
+        if (typeof rootIndex !== "number"
+            || !Number.isInteger(rootIndex)
+            || rootIndex < 0
+            || rootIndex >= roots.length
+            || typeof selectedPath !== "string"
+            || selectedPath.trim() === "") {
+            throw new ExecutionError("context_builder manifest selected_context entry is invalid");
+        }
+        const logicalPath = resolve(roots[rootIndex], selectedPath);
+        const realPath = await normalizeExistingPath(logicalPath);
+        absolutePaths.push({
+            logicalPath,
+            realPath,
+            traversedSymlink: realPath !== logicalPath,
+        });
+    }
+    return absolutePaths;
+}
+async function evaluatePostCbPromotionGate(input) {
+    try {
+        const coveredPaths = await input.signatureCoveredPaths(input.roots);
+        const selectedFilesCovered = 
+        // Empty selections carry no realized-file evidence, so they are not promotable.
+        input.selectedPaths.length > 0 &&
+            input.selectedPaths.every((path) => !path.traversedSymlink && coveredPaths.has(path.realPath));
+        const postSig = await input.workspaceSignature(input.roots);
+        return { selectedFilesCovered, postSig };
+    }
+    catch {
+        return undefined;
+    }
+}
+async function normalizeCacheRoots(roots) {
+    const normalized = [];
+    for (const root of roots.length === 0 ? [process.cwd()] : roots) {
+        const absolute = resolve(root);
+        normalized.push(await normalizeExistingPath(absolute));
+    }
+    return Array.from(new Set(normalized)).sort();
+}
+async function normalizeExistingPath(path) {
+    const absolute = resolve(path);
+    try {
+        return await realpath(absolute);
+    }
+    catch {
+        return absolute;
+    }
+}
+function isPromoteClaimConflict(error) {
+    return (error instanceof InvalidParamsError
+        && error.message.startsWith("context_builder run_id already exists:")) || (error instanceof ExecutionError
+        && error.message.startsWith("context_builder run_id conflicts with an incomplete or active run:"));
+}
+function throwIfAborted(signal) {
+    if (signal?.aborted === true) {
+        throw new CancellationError();
+    }
+}
+function isNodeError(error) {
+    return error instanceof Error && "code" in error;
+}
+function generateWorkflowPreflightRunId() {
+    return `wfpre-${randomUUID()}`;
+}
+async function resolveFallbackRoot(resolveWorkspaceRoot) {
+    const workspaceRoot = resolveWorkspaceRoot?.() ?? resolveWorkflowWorkspaceRoot();
+    const resolvedWorkspaceRoot = await realpath(workspaceRoot).catch(() => resolve(workspaceRoot));
+    const sourceAllowedRoots = getContextBuilderSourceAllowedRoots();
+    if (!isPathWithinAllowedRoots(resolvedWorkspaceRoot, sourceAllowedRoots)) {
+        throw new InvalidParamsError(`context_builder fallback root is outside source allowed roots: ${resolvedWorkspaceRoot}. ` +
+            `Allowed: ${sourceAllowedRoots.join(", ")}`);
+    }
+    return resolvedWorkspaceRoot;
+}
+function assertExplicitRootsWithinAllowed(roots) {
+    if (roots.length === 0)
+        return;
+    const allowed = getContextBuilderSourceAllowedRoots();
+    for (const root of roots) {
+        const resolved = realpathSyncBestEffort(resolve(process.cwd(), root));
+        if (!isPathWithinAllowedRoots(resolved, allowed)) {
+            throw new InvalidParamsError(`context_builder root is outside allowed roots: ${root}`);
+        }
+        let stat;
+        try {
+            stat = statSync(resolved);
+        }
+        catch {
+            throw new InvalidParamsError(`context_builder root does not exist: ${root}`);
+        }
+        if (!stat.isDirectory()) {
+            throw new InvalidParamsError(`context_builder root is not a directory: ${root}`);
+        }
+    }
+}
+function getContextBuilderSourceAllowedRoots() {
+    const raw = process.env["CLINKX_ALLOWED_ROOTS"];
+    if (raw == null || raw.trim() === "") {
+        return getCurrentAllowedRoots();
+    }
+    const cwd = resolve(process.cwd());
+    const roots = [];
+    const seen = new Set();
+    for (const entry of raw
+        .split(",")
+        .map((root) => root.trim())
+        .filter((root) => root.length > 0)) {
+        if (isArtifactOnlyAllowedRootEntry(entry)) {
+            continue;
+        }
+        const resolved = resolve(cwd, entry);
+        const canonical = realpathSyncBestEffort(resolved);
+        if (!seen.has(canonical)) {
+            seen.add(canonical);
+            roots.push(canonical);
+        }
+    }
+    return roots;
+}
+function realpathSyncBestEffort(path) {
+    try {
+        return realpathSync(path);
+    }
+    catch {
+        return path;
+    }
+}
+function validateProfile(profile) {
+    if (profile == null || profile.trim() === "") {
+        return undefined;
+    }
+    if (isContextBuilderProfile(profile)) {
+        return profile;
+    }
+    throw new InvalidParamsError(`Unknown context_builder profile "${profile}". ` +
+        `Allowed: ${CONTEXT_BUILDER_INTENT_PROFILES.join(", ")}`);
+}
+function isContextBuilderProfile(profile) {
+    return CONTEXT_BUILDER_INTENT_PROFILES.includes(profile);
+}
+async function resolveArtifactPath(artifacts, key, label) {
+    const artifactPath = artifacts[key];
+    if (typeof artifactPath !== "string" || artifactPath.trim() === "") {
+        throw new ExecutionError(`context_builder receipt is missing ${label}`);
+    }
+    return realpath(artifactPath);
+}
+async function copyArtifactIntoContextDir(source, contextDir, fileName) {
+    const target = resolve(contextDir, fileName);
+    assertContainedPath(contextDir, target, `context_builder copy target escaped: ${target}`);
+    const tempTarget = resolve(contextDir, `.${fileName}.${process.pid}.${randomUUID()}.tmp`);
+    assertContainedPath(contextDir, tempTarget, `context_builder temp copy target escaped: ${tempTarget}`);
+    try {
+        await copyFile(source, tempTarget);
+        await rename(tempTarget, target);
+    }
+    catch (error) {
+        await rm(tempTarget, { force: true }).catch(() => { });
+        throw error;
+    }
+    const realTarget = await realpath(target);
+    assertContainedPath(contextDir, realTarget, `context_builder copied artifact escaped context directory: ${realTarget}`);
+    return realTarget;
+}
+function assertContainedPath(parent, child, message) {
+    if (!isAbsolute(child)) {
+        throw new ExecutionError(message);
+    }
+    const rel = relative(parent, child);
+    if (rel === "" || rel.startsWith("..") || isAbsolute(rel)) {
+        throw new ExecutionError(message);
+    }
+}
+function parseReceiptResponse(response) {
+    const receiptText = response.content[0]?.text;
+    if (typeof receiptText !== "string") {
+        throw new ExecutionError("context_builder returned no receipt text");
+    }
+    return JSON.parse(receiptText);
+}
+//# sourceMappingURL=workflow-runner.js.map