clinkx 1.0.0 → 1.1.0

package/dist/context-builder/invocation-sidecar.js

@@ -0,0 +1,189 @@
+import { randomBytes } from "node:crypto";
+import { open, rename, rm } from "node:fs/promises";
+import { basename, dirname, join, resolve } from "node:path";
+import { CONTEXT_BUILDER_INVOCATION_AUDIT_FILENAME, CONTEXT_BUILDER_INVOCATION_AUDIT_V2_SCHEMA_VERSION, decodeContextBuilderInvocationAuditBytes, MAX_CONTEXT_BUILDER_INVOCATION_AUDIT_BYTES, serializeContextBuilderInvocationAuditV2, } from "../../clinkx-workflows/dist/dashboard/context-builder-invocation-contract.js";
+import { ContainedFilePolicyError, ContainedFileTooLargeError, containedFileFingerprintsEqual, readContainedRelativeFile, } from "../../clinkx-workflows/dist/contained-file.js";
+import { logger } from "../logger.js";
+import { withContextBuilderMutationLock } from "./mutation-lock.js";
+// Shared retries sleep 10 ms; cap best-effort audit contention at ~100 ms.
+const CONTEXT_BUILDER_INVOCATION_AUDIT_LOCK_ATTEMPTS = 10;
+export { CONTEXT_BUILDER_INVOCATION_AUDIT_FILENAME, MAX_CONTEXT_BUILDER_INVOCATION_AUDIT_BYTES, };
+export const CONTEXT_BUILDER_INVOCATION_AUDIT_SCHEMA_VERSION = CONTEXT_BUILDER_INVOCATION_AUDIT_V2_SCHEMA_VERSION;
+class InvocationAuditSidecarError extends Error {
+    reasonCode;
+    constructor(reasonCode) {
+        super("context_builder invocation audit sidecar rejected");
+        this.name = "InvocationAuditSidecarError";
+        this.reasonCode = reasonCode;
+    }
+}
+/**
+ * True only when a sidecar read proved the existing artifact invalid or unsafe.
+ * Transient I/O failures remain distinguishable so callers cannot treat bytes
+ * they failed to inspect as authoritative invalid content.
+ */
+export function isContextBuilderInvocationAuditSidecarProvenInvalid(error) {
+    if (!(error instanceof InvocationAuditSidecarError))
+        return false;
+    return error.reasonCode === "invalid_document" ||
+        error.reasonCode === "oversized_file" ||
+        error.reasonCode === "unsafe_file";
+}
+/**
+ * Read an optional invocation audit through the shared descriptor-bound,
+ * no-follow contained-file reader and the shared strict V1/V2 decoder.
+ *
+ * Missing is the only non-error absence. Existing malformed, future-version,
+ * oversized, symlink, and non-regular entries all fail closed.
+ */
+export async function readContextBuilderInvocationAuditSidecar(artifactRunDir) {
+    let bytes;
+    let fingerprint;
+    try {
+        const read = await readContainedRelativeFile(artifactRunDir, CONTEXT_BUILDER_INVOCATION_AUDIT_FILENAME, {
+            wantBytes: true,
+            requireRegular: true,
+            requireExactRequestedPath: true,
+            maxBytes: MAX_CONTEXT_BUILDER_INVOCATION_AUDIT_BYTES,
+            containerLabel: "context_builder run directory",
+            pathLabel: CONTEXT_BUILDER_INVOCATION_AUDIT_FILENAME,
+        });
+        if (read.bytes === undefined) {
+            throw new InvocationAuditSidecarError("read_failed");
+        }
+        bytes = read.bytes;
+        fingerprint = read.fingerprint;
+    }
+    catch (error) {
+        if (isEnoent(error)) {
+            return undefined;
+        }
+        if (error instanceof ContainedFileTooLargeError) {
+            throw new InvocationAuditSidecarError("oversized_file");
+        }
+        if (error instanceof ContainedFilePolicyError) {
+            throw new InvocationAuditSidecarError("unsafe_file");
+        }
+        if (error instanceof InvocationAuditSidecarError) {
+            throw error;
+        }
+        throw new InvocationAuditSidecarError("read_failed");
+    }
+    let decoded;
+    try {
+        decoded = decodeContextBuilderInvocationAuditBytes(bytes);
+    }
+    catch {
+        throw new InvocationAuditSidecarError("invalid_document");
+    }
+    return {
+        document: decoded.document,
+        fingerprint,
+        serialized: decoded.serialized,
+    };
+}
+/**
+ * Persist a strict value-only curator/finalizer invocation audit next to the
+ * run. This remains outside manifest and receipt metadata.
+ *
+ * Best-effort: one rejected seat update must never change delegate execution or
+ * the run outcome. An existing invalid sidecar is never repaired or replaced;
+ * its bytes remain authoritative for offline diagnosis.
+ */
+export async function recordContextInvocationAudit(artifactRunDir, seat, audit, options = {}) {
+    const runDir = resolve(artifactRunDir);
+    const lockTarget = {
+        runId: basename(runDir),
+        runsDir: dirname(runDir),
+        runDir,
+    };
+    try {
+        await withContextBuilderMutationLock(lockTarget, {}, async () => {
+            const existing = await readContextBuilderInvocationAuditSidecar(runDir);
+            let serialized;
+            try {
+                const base = {
+                    schema_version: CONTEXT_BUILDER_INVOCATION_AUDIT_V2_SCHEMA_VERSION,
+                    ...(existing?.document.curator === undefined
+                        ? {}
+                        : { curator: existing.document.curator }),
+                    ...(existing?.document.finalizer === undefined
+                        ? {}
+                        : { finalizer: existing.document.finalizer }),
+                };
+                const document = seat === "curator"
+                    ? { ...base, curator: audit }
+                    : { ...base, finalizer: audit };
+                serialized = serializeContextBuilderInvocationAuditV2(document);
+            }
+            catch {
+                throw new InvocationAuditSidecarError("invalid_seat_update");
+            }
+            await writeAtomicText(join(runDir, CONTEXT_BUILDER_INVOCATION_AUDIT_FILENAME), serialized, existing, options.beforeCommit);
+        }, {
+            maxAttempts: CONTEXT_BUILDER_INVOCATION_AUDIT_LOCK_ATTEMPTS,
+            onContention: options.onLockContention,
+        });
+    }
+    catch (error) {
+        warnSkippedSeatUpdate(seat, sidecarFailureCode(error, "write_failed"));
+    }
+}
+async function writeAtomicText(targetPath, content, admittedPredecessor, beforeCommit) {
+    const tempPath = `${targetPath}.${process.pid}.${randomBytes(8).toString("hex")}.tmp`;
+    const handle = await open(tempPath, "wx", 0o600);
+    let cleanupTemp = true;
+    try {
+        await handle.writeFile(content, { encoding: "utf8" });
+        await handle.sync();
+        await handle.close();
+        await beforeCommit?.();
+        await assertAdmittedPredecessorUnchanged(dirname(targetPath), admittedPredecessor);
+        await rename(tempPath, targetPath);
+        cleanupTemp = false;
+    }
+    catch (error) {
+        await handle.close().catch(() => { });
+        if (cleanupTemp) {
+            await rm(tempPath, { force: true }).catch(() => { });
+        }
+        throw error;
+    }
+}
+async function assertAdmittedPredecessorUnchanged(artifactRunDir, admitted) {
+    // The per-run lease excludes cooperative writers and pruners. Re-admission
+    // binds this commit to the exact prior descriptor/content (or exact absence),
+    // but pathname rename is not a hostile-filesystem CAS.
+    const current = await readContextBuilderInvocationAuditSidecar(artifactRunDir);
+    if (admitted === undefined) {
+        if (current !== undefined) {
+            throw new InvocationAuditSidecarError("predecessor_changed");
+        }
+        return;
+    }
+    if (current === undefined
+        || current.serialized !== admitted.serialized
+        || !containedFileFingerprintsEqual(current.fingerprint, admitted.fingerprint)) {
+        throw new InvocationAuditSidecarError("predecessor_changed");
+    }
+}
+function warnSkippedSeatUpdate(seat, reasonCode) {
+    try {
+        logger.warn({ seat, reason_code: reasonCode }, "failed to record context_builder invocation audit sidecar");
+    }
+    catch {
+        // Diagnostics must not fail the delegate.
+    }
+}
+function sidecarFailureCode(error, fallback) {
+    return error instanceof InvocationAuditSidecarError
+        ? error.reasonCode
+        : fallback;
+}
+function isEnoent(error) {
+    return (error != null &&
+        typeof error === "object" &&
+        "code" in error &&
+        error.code === "ENOENT");
+}
+//# sourceMappingURL=invocation-sidecar.js.map

package/dist/context-builder/invocation-sidecar.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"invocation-sidecar.js","sourceRoot":"","sources":["../../src/context-builder/invocation-sidecar.ts"],"names":[],"mappings":"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"}

package/dist/context-builder/lifecycle-contract.d.ts

@@ -118,28 +118,28 @@ export declare const ContextBuilderLifecycleStateV1Schema: z.ZodEffects<z.ZodObj
         reason_code: z.ZodOptional<z.ZodEnum<["cache_disabled", "cache_miss", "cache_stale", "delegate_disabled", "delegate_failed", "delegate_fallback", "delegate_invalid", "delegate_timeout", "coverage_degraded", "empty_selection", "operation_cancelled", "internal_failure", "legacy_supported", "legacy_unsupported", "generation_replaced"]>>;
     }, "strict", z.ZodTypeAny, {
         write: "skipped" | "not_attempted" | "written";
-        lookup: "hit" | "not_checked" | "miss";
-        reason_code?: "delegate_fallback" | "cache_disabled" | "cache_miss" | "cache_stale" | "delegate_disabled" | "delegate_failed" | "delegate_invalid" | "delegate_timeout" | "coverage_degraded" | "empty_selection" | "operation_cancelled" | "internal_failure" | "legacy_supported" | "legacy_unsupported" | "generation_replaced" | undefined;
+        lookup: "not_checked" | "miss" | "hit";
+        reason_code?: "cache_disabled" | "cache_miss" | "cache_stale" | "delegate_disabled" | "delegate_failed" | "delegate_fallback" | "delegate_invalid" | "delegate_timeout" | "coverage_degraded" | "empty_selection" | "operation_cancelled" | "internal_failure" | "legacy_supported" | "legacy_unsupported" | "generation_replaced" | undefined;
     }, {
         write: "skipped" | "not_attempted" | "written";
-        lookup: "hit" | "not_checked" | "miss";
-        reason_code?: "delegate_fallback" | "cache_disabled" | "cache_miss" | "cache_stale" | "delegate_disabled" | "delegate_failed" | "delegate_invalid" | "delegate_timeout" | "coverage_degraded" | "empty_selection" | "operation_cancelled" | "internal_failure" | "legacy_supported" | "legacy_unsupported" | "generation_replaced" | undefined;
+        lookup: "not_checked" | "miss" | "hit";
+        reason_code?: "cache_disabled" | "cache_miss" | "cache_stale" | "delegate_disabled" | "delegate_failed" | "delegate_fallback" | "delegate_invalid" | "delegate_timeout" | "coverage_degraded" | "empty_selection" | "operation_cancelled" | "internal_failure" | "legacy_supported" | "legacy_unsupported" | "generation_replaced" | undefined;
     }>;
     fallback: z.ZodEffects<z.ZodObject<{
         status: z.ZodEnum<["not_applicable", "not_used", "used", "failed"]>;
         reason_code: z.ZodOptional<z.ZodEnum<["cache_disabled", "cache_miss", "cache_stale", "delegate_disabled", "delegate_failed", "delegate_fallback", "delegate_invalid", "delegate_timeout", "coverage_degraded", "empty_selection", "operation_cancelled", "internal_failure", "legacy_supported", "legacy_unsupported", "generation_replaced"]>>;
     }, "strict", z.ZodTypeAny, {
         status: "failed" | "not_applicable" | "not_used" | "used";
-        reason_code?: "delegate_fallback" | "cache_disabled" | "cache_miss" | "cache_stale" | "delegate_disabled" | "delegate_failed" | "delegate_invalid" | "delegate_timeout" | "coverage_degraded" | "empty_selection" | "operation_cancelled" | "internal_failure" | "legacy_supported" | "legacy_unsupported" | "generation_replaced" | undefined;
+        reason_code?: "cache_disabled" | "cache_miss" | "cache_stale" | "delegate_disabled" | "delegate_failed" | "delegate_fallback" | "delegate_invalid" | "delegate_timeout" | "coverage_degraded" | "empty_selection" | "operation_cancelled" | "internal_failure" | "legacy_supported" | "legacy_unsupported" | "generation_replaced" | undefined;
     }, {
         status: "failed" | "not_applicable" | "not_used" | "used";
-        reason_code?: "delegate_fallback" | "cache_disabled" | "cache_miss" | "cache_stale" | "delegate_disabled" | "delegate_failed" | "delegate_invalid" | "delegate_timeout" | "coverage_degraded" | "empty_selection" | "operation_cancelled" | "internal_failure" | "legacy_supported" | "legacy_unsupported" | "generation_replaced" | undefined;
+        reason_code?: "cache_disabled" | "cache_miss" | "cache_stale" | "delegate_disabled" | "delegate_failed" | "delegate_fallback" | "delegate_invalid" | "delegate_timeout" | "coverage_degraded" | "empty_selection" | "operation_cancelled" | "internal_failure" | "legacy_supported" | "legacy_unsupported" | "generation_replaced" | undefined;
     }>, {
         status: "failed" | "not_applicable" | "not_used" | "used";
-        reason_code?: "delegate_fallback" | "cache_disabled" | "cache_miss" | "cache_stale" | "delegate_disabled" | "delegate_failed" | "delegate_invalid" | "delegate_timeout" | "coverage_degraded" | "empty_selection" | "operation_cancelled" | "internal_failure" | "legacy_supported" | "legacy_unsupported" | "generation_replaced" | undefined;
+        reason_code?: "cache_disabled" | "cache_miss" | "cache_stale" | "delegate_disabled" | "delegate_failed" | "delegate_fallback" | "delegate_invalid" | "delegate_timeout" | "coverage_degraded" | "empty_selection" | "operation_cancelled" | "internal_failure" | "legacy_supported" | "legacy_unsupported" | "generation_replaced" | undefined;
     }, {
         status: "failed" | "not_applicable" | "not_used" | "used";
-        reason_code?: "delegate_fallback" | "cache_disabled" | "cache_miss" | "cache_stale" | "delegate_disabled" | "delegate_failed" | "delegate_invalid" | "delegate_timeout" | "coverage_degraded" | "empty_selection" | "operation_cancelled" | "internal_failure" | "legacy_supported" | "legacy_unsupported" | "generation_replaced" | undefined;
+        reason_code?: "cache_disabled" | "cache_miss" | "cache_stale" | "delegate_disabled" | "delegate_failed" | "delegate_fallback" | "delegate_invalid" | "delegate_timeout" | "coverage_degraded" | "empty_selection" | "operation_cancelled" | "internal_failure" | "legacy_supported" | "legacy_unsupported" | "generation_replaced" | undefined;
     }>;
     counts: z.ZodObject<{
         files_seen: z.ZodNumber;
@@ -154,17 +154,17 @@ export declare const ContextBuilderLifecycleStateV1Schema: z.ZodEffects<z.ZodObj
         files_considered: number;
         files_selected: number;
         files_omitted: number;
+        search_results: number;
         bytes_read: number;
         bytes_written: number;
-        search_results: number;
     }, {
         files_seen: number;
         files_considered: number;
         files_selected: number;
         files_omitted: number;
+        search_results: number;
         bytes_read: number;
         bytes_written: number;
-        search_results: number;
     }>;
     coverage: z.ZodEffects<z.ZodObject<{
         policy: z.ZodNullable<z.ZodLiteral<"review_deep_v1">>;
@@ -175,33 +175,33 @@ export declare const ContextBuilderLifecycleStateV1Schema: z.ZodEffects<z.ZodObj
     }, "strict", z.ZodTypeAny, {
         missing: number;
         status: "satisfied" | "degraded" | "not_evaluated";
-        selected: number;
         policy: "review_deep_v1" | null;
         required: number;
+        selected: number;
     }, {
         missing: number;
         status: "satisfied" | "degraded" | "not_evaluated";
-        selected: number;
         policy: "review_deep_v1" | null;
         required: number;
+        selected: number;
     }>, {
         missing: number;
         status: "satisfied" | "degraded" | "not_evaluated";
-        selected: number;
         policy: "review_deep_v1" | null;
         required: number;
+        selected: number;
     }, {
         missing: number;
         status: "satisfied" | "degraded" | "not_evaluated";
-        selected: number;
         policy: "review_deep_v1" | null;
         required: number;
+        selected: number;
     }>;
-    reason_codes: z.ZodEffects<z.ZodArray<z.ZodEnum<["cache_disabled", "cache_miss", "cache_stale", "delegate_disabled", "delegate_failed", "delegate_fallback", "delegate_invalid", "delegate_timeout", "coverage_degraded", "empty_selection", "operation_cancelled", "internal_failure", "legacy_supported", "legacy_unsupported", "generation_replaced"]>, "many">, ("delegate_fallback" | "cache_disabled" | "cache_miss" | "cache_stale" | "delegate_disabled" | "delegate_failed" | "delegate_invalid" | "delegate_timeout" | "coverage_degraded" | "empty_selection" | "operation_cancelled" | "internal_failure" | "legacy_supported" | "legacy_unsupported" | "generation_replaced")[], ("delegate_fallback" | "cache_disabled" | "cache_miss" | "cache_stale" | "delegate_disabled" | "delegate_failed" | "delegate_invalid" | "delegate_timeout" | "coverage_degraded" | "empty_selection" | "operation_cancelled" | "internal_failure" | "legacy_supported" | "legacy_unsupported" | "generation_replaced")[]>;
+    reason_codes: z.ZodEffects<z.ZodArray<z.ZodEnum<["cache_disabled", "cache_miss", "cache_stale", "delegate_disabled", "delegate_failed", "delegate_fallback", "delegate_invalid", "delegate_timeout", "coverage_degraded", "empty_selection", "operation_cancelled", "internal_failure", "legacy_supported", "legacy_unsupported", "generation_replaced"]>, "many">, ("cache_disabled" | "cache_miss" | "cache_stale" | "delegate_disabled" | "delegate_failed" | "delegate_fallback" | "delegate_invalid" | "delegate_timeout" | "coverage_degraded" | "empty_selection" | "operation_cancelled" | "internal_failure" | "legacy_supported" | "legacy_unsupported" | "generation_replaced")[], ("cache_disabled" | "cache_miss" | "cache_stale" | "delegate_disabled" | "delegate_failed" | "delegate_fallback" | "delegate_invalid" | "delegate_timeout" | "coverage_degraded" | "empty_selection" | "operation_cancelled" | "internal_failure" | "legacy_supported" | "legacy_unsupported" | "generation_replaced")[]>;
 }, "strict", z.ZodTypeAny, {
     fallback: {
         status: "failed" | "not_applicable" | "not_used" | "used";
-        reason_code?: "delegate_fallback" | "cache_disabled" | "cache_miss" | "cache_stale" | "delegate_disabled" | "delegate_failed" | "delegate_invalid" | "delegate_timeout" | "coverage_degraded" | "empty_selection" | "operation_cancelled" | "internal_failure" | "legacy_supported" | "legacy_unsupported" | "generation_replaced" | undefined;
+        reason_code?: "cache_disabled" | "cache_miss" | "cache_stale" | "delegate_disabled" | "delegate_failed" | "delegate_fallback" | "delegate_invalid" | "delegate_timeout" | "coverage_degraded" | "empty_selection" | "operation_cancelled" | "internal_failure" | "legacy_supported" | "legacy_unsupported" | "generation_replaced" | undefined;
     };
     status: "succeeded" | "failed" | "cancelled" | "running" | "partial" | "pending";
     curator: {
@@ -216,33 +216,33 @@ export declare const ContextBuilderLifecycleStateV1Schema: z.ZodEffects<z.ZodObj
         execution_status: "succeeded" | "failed" | "cancelled" | "running" | "skipped" | "pending" | "disabled" | "not_configured";
         score?: number | undefined;
     };
-    schema_version: "clinkx-context-builder-lifecycle-v1";
-    created_at: string;
     coverage: {
         missing: number;
         status: "satisfied" | "degraded" | "not_evaluated";
-        selected: number;
         policy: "review_deep_v1" | null;
         required: number;
+        selected: number;
     };
-    reason_codes: ("delegate_fallback" | "cache_disabled" | "cache_miss" | "cache_stale" | "delegate_disabled" | "delegate_failed" | "delegate_invalid" | "delegate_timeout" | "coverage_degraded" | "empty_selection" | "operation_cancelled" | "internal_failure" | "legacy_supported" | "legacy_unsupported" | "generation_replaced")[];
+    updated_at: string;
+    schema_version: "clinkx-context-builder-lifecycle-v1";
+    reason_codes: ("cache_disabled" | "cache_miss" | "cache_stale" | "delegate_disabled" | "delegate_failed" | "delegate_fallback" | "delegate_invalid" | "delegate_timeout" | "coverage_degraded" | "empty_selection" | "operation_cancelled" | "internal_failure" | "legacy_supported" | "legacy_unsupported" | "generation_replaced")[];
     context_run_id: string;
     operation_kind: "standalone" | "refine" | "workflow_preflight" | "historical";
     phase: "resolving" | "terminal" | "complete" | "cache_lookup" | "validating" | "scanning" | "searching" | "selecting" | "curating" | "finalizing" | "writing" | "materializing" | "committing";
-    updated_at: string;
+    created_at: string;
     cache: {
         write: "skipped" | "not_attempted" | "written";
-        lookup: "hit" | "not_checked" | "miss";
-        reason_code?: "delegate_fallback" | "cache_disabled" | "cache_miss" | "cache_stale" | "delegate_disabled" | "delegate_failed" | "delegate_invalid" | "delegate_timeout" | "coverage_degraded" | "empty_selection" | "operation_cancelled" | "internal_failure" | "legacy_supported" | "legacy_unsupported" | "generation_replaced" | undefined;
+        lookup: "not_checked" | "miss" | "hit";
+        reason_code?: "cache_disabled" | "cache_miss" | "cache_stale" | "delegate_disabled" | "delegate_failed" | "delegate_fallback" | "delegate_invalid" | "delegate_timeout" | "coverage_degraded" | "empty_selection" | "operation_cancelled" | "internal_failure" | "legacy_supported" | "legacy_unsupported" | "generation_replaced" | undefined;
     };
     counts: {
         files_seen: number;
         files_considered: number;
         files_selected: number;
         files_omitted: number;
+        search_results: number;
         bytes_read: number;
         bytes_written: number;
-        search_results: number;
     };
     artifact_run_id?: string | undefined;
     started_at?: string | undefined;
@@ -251,7 +251,7 @@ export declare const ContextBuilderLifecycleStateV1Schema: z.ZodEffects<z.ZodObj
 }, {
     fallback: {
         status: "failed" | "not_applicable" | "not_used" | "used";
-        reason_code?: "delegate_fallback" | "cache_disabled" | "cache_miss" | "cache_stale" | "delegate_disabled" | "delegate_failed" | "delegate_invalid" | "delegate_timeout" | "coverage_degraded" | "empty_selection" | "operation_cancelled" | "internal_failure" | "legacy_supported" | "legacy_unsupported" | "generation_replaced" | undefined;
+        reason_code?: "cache_disabled" | "cache_miss" | "cache_stale" | "delegate_disabled" | "delegate_failed" | "delegate_fallback" | "delegate_invalid" | "delegate_timeout" | "coverage_degraded" | "empty_selection" | "operation_cancelled" | "internal_failure" | "legacy_supported" | "legacy_unsupported" | "generation_replaced" | undefined;
     };
     status: "succeeded" | "failed" | "cancelled" | "running" | "partial" | "pending";
     curator: {
@@ -266,33 +266,33 @@ export declare const ContextBuilderLifecycleStateV1Schema: z.ZodEffects<z.ZodObj
         execution_status: "succeeded" | "failed" | "cancelled" | "running" | "skipped" | "pending" | "disabled" | "not_configured";
         score?: number | undefined;
     };
-    schema_version: "clinkx-context-builder-lifecycle-v1";
-    created_at: string;
     coverage: {
         missing: number;
         status: "satisfied" | "degraded" | "not_evaluated";
-        selected: number;
         policy: "review_deep_v1" | null;
         required: number;
+        selected: number;
     };
-    reason_codes: ("delegate_fallback" | "cache_disabled" | "cache_miss" | "cache_stale" | "delegate_disabled" | "delegate_failed" | "delegate_invalid" | "delegate_timeout" | "coverage_degraded" | "empty_selection" | "operation_cancelled" | "internal_failure" | "legacy_supported" | "legacy_unsupported" | "generation_replaced")[];
+    updated_at: string;
+    schema_version: "clinkx-context-builder-lifecycle-v1";
+    reason_codes: ("cache_disabled" | "cache_miss" | "cache_stale" | "delegate_disabled" | "delegate_failed" | "delegate_fallback" | "delegate_invalid" | "delegate_timeout" | "coverage_degraded" | "empty_selection" | "operation_cancelled" | "internal_failure" | "legacy_supported" | "legacy_unsupported" | "generation_replaced")[];
     context_run_id: string;
     operation_kind: "standalone" | "refine" | "workflow_preflight" | "historical";
     phase: "resolving" | "terminal" | "complete" | "cache_lookup" | "validating" | "scanning" | "searching" | "selecting" | "curating" | "finalizing" | "writing" | "materializing" | "committing";
-    updated_at: string;
+    created_at: string;
     cache: {
         write: "skipped" | "not_attempted" | "written";
-        lookup: "hit" | "not_checked" | "miss";
-        reason_code?: "delegate_fallback" | "cache_disabled" | "cache_miss" | "cache_stale" | "delegate_disabled" | "delegate_failed" | "delegate_invalid" | "delegate_timeout" | "coverage_degraded" | "empty_selection" | "operation_cancelled" | "internal_failure" | "legacy_supported" | "legacy_unsupported" | "generation_replaced" | undefined;
+        lookup: "not_checked" | "miss" | "hit";
+        reason_code?: "cache_disabled" | "cache_miss" | "cache_stale" | "delegate_disabled" | "delegate_failed" | "delegate_fallback" | "delegate_invalid" | "delegate_timeout" | "coverage_degraded" | "empty_selection" | "operation_cancelled" | "internal_failure" | "legacy_supported" | "legacy_unsupported" | "generation_replaced" | undefined;
     };
     counts: {
         files_seen: number;
         files_considered: number;
         files_selected: number;
         files_omitted: number;
+        search_results: number;
         bytes_read: number;
         bytes_written: number;
-        search_results: number;
     };
     artifact_run_id?: string | undefined;
     started_at?: string | undefined;
@@ -301,7 +301,7 @@ export declare const ContextBuilderLifecycleStateV1Schema: z.ZodEffects<z.ZodObj
 }>, {
     fallback: {
         status: "failed" | "not_applicable" | "not_used" | "used";
-        reason_code?: "delegate_fallback" | "cache_disabled" | "cache_miss" | "cache_stale" | "delegate_disabled" | "delegate_failed" | "delegate_invalid" | "delegate_timeout" | "coverage_degraded" | "empty_selection" | "operation_cancelled" | "internal_failure" | "legacy_supported" | "legacy_unsupported" | "generation_replaced" | undefined;
+        reason_code?: "cache_disabled" | "cache_miss" | "cache_stale" | "delegate_disabled" | "delegate_failed" | "delegate_fallback" | "delegate_invalid" | "delegate_timeout" | "coverage_degraded" | "empty_selection" | "operation_cancelled" | "internal_failure" | "legacy_supported" | "legacy_unsupported" | "generation_replaced" | undefined;
     };
     status: "succeeded" | "failed" | "cancelled" | "running" | "partial" | "pending";
     curator: {
@@ -316,33 +316,33 @@ export declare const ContextBuilderLifecycleStateV1Schema: z.ZodEffects<z.ZodObj
         execution_status: "succeeded" | "failed" | "cancelled" | "running" | "skipped" | "pending" | "disabled" | "not_configured";
         score?: number | undefined;
     };
-    schema_version: "clinkx-context-builder-lifecycle-v1";
-    created_at: string;
     coverage: {
         missing: number;
         status: "satisfied" | "degraded" | "not_evaluated";
-        selected: number;
         policy: "review_deep_v1" | null;
         required: number;
+        selected: number;
     };
-    reason_codes: ("delegate_fallback" | "cache_disabled" | "cache_miss" | "cache_stale" | "delegate_disabled" | "delegate_failed" | "delegate_invalid" | "delegate_timeout" | "coverage_degraded" | "empty_selection" | "operation_cancelled" | "internal_failure" | "legacy_supported" | "legacy_unsupported" | "generation_replaced")[];
+    updated_at: string;
+    schema_version: "clinkx-context-builder-lifecycle-v1";
+    reason_codes: ("cache_disabled" | "cache_miss" | "cache_stale" | "delegate_disabled" | "delegate_failed" | "delegate_fallback" | "delegate_invalid" | "delegate_timeout" | "coverage_degraded" | "empty_selection" | "operation_cancelled" | "internal_failure" | "legacy_supported" | "legacy_unsupported" | "generation_replaced")[];
     context_run_id: string;
     operation_kind: "standalone" | "refine" | "workflow_preflight" | "historical";
     phase: "resolving" | "terminal" | "complete" | "cache_lookup" | "validating" | "scanning" | "searching" | "selecting" | "curating" | "finalizing" | "writing" | "materializing" | "committing";
-    updated_at: string;
+    created_at: string;
     cache: {
         write: "skipped" | "not_attempted" | "written";
-        lookup: "hit" | "not_checked" | "miss";
-        reason_code?: "delegate_fallback" | "cache_disabled" | "cache_miss" | "cache_stale" | "delegate_disabled" | "delegate_failed" | "delegate_invalid" | "delegate_timeout" | "coverage_degraded" | "empty_selection" | "operation_cancelled" | "internal_failure" | "legacy_supported" | "legacy_unsupported" | "generation_replaced" | undefined;
+        lookup: "not_checked" | "miss" | "hit";
+        reason_code?: "cache_disabled" | "cache_miss" | "cache_stale" | "delegate_disabled" | "delegate_failed" | "delegate_fallback" | "delegate_invalid" | "delegate_timeout" | "coverage_degraded" | "empty_selection" | "operation_cancelled" | "internal_failure" | "legacy_supported" | "legacy_unsupported" | "generation_replaced" | undefined;
     };
     counts: {
         files_seen: number;
         files_considered: number;
         files_selected: number;
         files_omitted: number;
+        search_results: number;
         bytes_read: number;
         bytes_written: number;
-        search_results: number;
     };
     artifact_run_id?: string | undefined;
     started_at?: string | undefined;
@@ -351,7 +351,7 @@ export declare const ContextBuilderLifecycleStateV1Schema: z.ZodEffects<z.ZodObj
 }, {
     fallback: {
         status: "failed" | "not_applicable" | "not_used" | "used";
-        reason_code?: "delegate_fallback" | "cache_disabled" | "cache_miss" | "cache_stale" | "delegate_disabled" | "delegate_failed" | "delegate_invalid" | "delegate_timeout" | "coverage_degraded" | "empty_selection" | "operation_cancelled" | "internal_failure" | "legacy_supported" | "legacy_unsupported" | "generation_replaced" | undefined;
+        reason_code?: "cache_disabled" | "cache_miss" | "cache_stale" | "delegate_disabled" | "delegate_failed" | "delegate_fallback" | "delegate_invalid" | "delegate_timeout" | "coverage_degraded" | "empty_selection" | "operation_cancelled" | "internal_failure" | "legacy_supported" | "legacy_unsupported" | "generation_replaced" | undefined;
     };
     status: "succeeded" | "failed" | "cancelled" | "running" | "partial" | "pending";
     curator: {
@@ -366,33 +366,33 @@ export declare const ContextBuilderLifecycleStateV1Schema: z.ZodEffects<z.ZodObj
         execution_status: "succeeded" | "failed" | "cancelled" | "running" | "skipped" | "pending" | "disabled" | "not_configured";
         score?: number | undefined;
     };
-    schema_version: "clinkx-context-builder-lifecycle-v1";
-    created_at: string;
     coverage: {
         missing: number;
         status: "satisfied" | "degraded" | "not_evaluated";
-        selected: number;
         policy: "review_deep_v1" | null;
         required: number;
+        selected: number;
     };
-    reason_codes: ("delegate_fallback" | "cache_disabled" | "cache_miss" | "cache_stale" | "delegate_disabled" | "delegate_failed" | "delegate_invalid" | "delegate_timeout" | "coverage_degraded" | "empty_selection" | "operation_cancelled" | "internal_failure" | "legacy_supported" | "legacy_unsupported" | "generation_replaced")[];
+    updated_at: string;
+    schema_version: "clinkx-context-builder-lifecycle-v1";
+    reason_codes: ("cache_disabled" | "cache_miss" | "cache_stale" | "delegate_disabled" | "delegate_failed" | "delegate_fallback" | "delegate_invalid" | "delegate_timeout" | "coverage_degraded" | "empty_selection" | "operation_cancelled" | "internal_failure" | "legacy_supported" | "legacy_unsupported" | "generation_replaced")[];
     context_run_id: string;
     operation_kind: "standalone" | "refine" | "workflow_preflight" | "historical";
     phase: "resolving" | "terminal" | "complete" | "cache_lookup" | "validating" | "scanning" | "searching" | "selecting" | "curating" | "finalizing" | "writing" | "materializing" | "committing";
-    updated_at: string;
+    created_at: string;
     cache: {
         write: "skipped" | "not_attempted" | "written";
-        lookup: "hit" | "not_checked" | "miss";
-        reason_code?: "delegate_fallback" | "cache_disabled" | "cache_miss" | "cache_stale" | "delegate_disabled" | "delegate_failed" | "delegate_invalid" | "delegate_timeout" | "coverage_degraded" | "empty_selection" | "operation_cancelled" | "internal_failure" | "legacy_supported" | "legacy_unsupported" | "generation_replaced" | undefined;
+        lookup: "not_checked" | "miss" | "hit";
+        reason_code?: "cache_disabled" | "cache_miss" | "cache_stale" | "delegate_disabled" | "delegate_failed" | "delegate_fallback" | "delegate_invalid" | "delegate_timeout" | "coverage_degraded" | "empty_selection" | "operation_cancelled" | "internal_failure" | "legacy_supported" | "legacy_unsupported" | "generation_replaced" | undefined;
     };
     counts: {
         files_seen: number;
         files_considered: number;
         files_selected: number;
         files_omitted: number;
+        search_results: number;
         bytes_read: number;
         bytes_written: number;
-        search_results: number;
     };
     artifact_run_id?: string | undefined;
     started_at?: string | undefined;

package/dist/context-builder/mutation-lock.d.ts

@@ -0,0 +1,32 @@
+import { type FileHandle } from "node:fs/promises";
+import type { BigIntStats } from "node:fs";
+export type ContextBuilderMutationLockTarget = {
+    runId: string;
+    runsDir: string;
+    runDir: string;
+};
+export type ContextBuilderMutationLockOps = {
+    open?(path: string, flags: string, mode?: number): Promise<FileHandle>;
+    lstat?(path: string, options: {
+        bigint: true;
+    }): Promise<BigIntStats>;
+    rm?(path: string, options: {
+        force?: boolean;
+    }): Promise<void>;
+};
+export type ContextBuilderMutationLockOptions = {
+    ownerNonce?: string | undefined;
+    /** Keep the storage default unless a best-effort caller needs a tighter bound. */
+    maxAttempts?: number | undefined;
+    /** Deterministic contention seam; production callers leave this unset. */
+    onContention?: (() => void | Promise<void>) | undefined;
+    /** Storage cleanup supplies its existing owner/manifest admission check. */
+    canRecoverStale?: (() => Promise<boolean>) | undefined;
+    /** Deterministic seam after stale-lock qualification, before final admission/removal. */
+    beforeStaleRemoval?: (() => void | Promise<void>) | undefined;
+};
+/**
+ * Serialize cooperative mutations of one context_builder run. The lock lives
+ * beside the run directory so it also survives removal of that directory.
+ */
+export declare function withContextBuilderMutationLock<T>(target: ContextBuilderMutationLockTarget, ops: ContextBuilderMutationLockOps, callback: () => Promise<T>, options?: ContextBuilderMutationLockOptions): Promise<T>;