clinkx 0.3.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

@@ -0,0 +1,424 @@
+import { z } from "zod";
+export declare const CONTEXT_BUILDER_LIFECYCLE_SCHEMA_VERSION: "clinkx-context-builder-lifecycle-v1";
+export declare const CONTEXT_BUILDER_LIFECYCLE_RUNS_DIR_ENV: "CLINKX_CONTEXT_BUILDER_RUNS_DIR";
+export declare const CONTEXT_BUILDER_LIFECYCLE_DIRECTORY: ".context-runs";
+export declare const CONTEXT_BUILDER_LIFECYCLE_STATE_FILENAME: "state.json";
+export declare const MAX_CONTEXT_BUILDER_LIFECYCLE_DURATION_MS = 86400000;
+export declare const MAX_CONTEXT_BUILDER_LIFECYCLE_REASON_CODES = 16;
+export declare const CONTEXT_BUILDER_OPERATION_KINDS: readonly ["standalone", "refine", "workflow_preflight", "historical"];
+export declare const CONTEXT_BUILDER_LIFECYCLE_STATUSES: readonly ["pending", "running", "succeeded", "partial", "failed", "cancelled"];
+export declare const CONTEXT_BUILDER_LIFECYCLE_PHASES: readonly ["resolving", "cache_lookup", "validating", "scanning", "searching", "selecting", "curating", "finalizing", "writing", "materializing", "committing", "complete", "terminal"];
+export declare const CONTEXT_BUILDER_EXECUTION_STATUSES: readonly ["not_configured", "disabled", "pending", "running", "succeeded", "failed", "cancelled", "skipped"];
+export declare const CONTEXT_BUILDER_FALLBACK_STATUSES: readonly ["not_applicable", "not_used", "used", "failed"];
+export declare const CONTEXT_BUILDER_LIFECYCLE_REASON_CODES: readonly ["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"];
+/**
+ * Frozen legal phase paths. A producer may omit intermediate phases, but an
+ * emitted phase must move forward on one path. Failure/cancellation may move
+ * from any non-terminal phase directly to `terminal`.
+ */
+export declare const CONTEXT_BUILDER_LIFECYCLE_STAGE_PATHS: Readonly<{
+    deterministic: readonly ["resolving", "validating", "scanning", "searching", "selecting", "writing", "committing", "complete"];
+    delegated: readonly ["resolving", "validating", "scanning", "searching", "selecting", "curating", "finalizing", "writing", "committing", "complete"];
+    workflow_cache_miss: readonly ["resolving", "cache_lookup", "validating", "scanning", "searching", "selecting", "curating", "finalizing", "writing", "materializing", "committing", "complete"];
+    workflow_cache_hit: readonly ["resolving", "cache_lookup", "materializing", "committing", "complete"];
+    refine: readonly ["resolving", "validating", "selecting", "writing", "committing", "complete"];
+    historical_success: readonly ["complete"];
+    historical_terminal: readonly ["terminal"];
+}>;
+export declare const CONTEXT_BUILDER_LIFECYCLE_V1_DESCRIPTOR: Readonly<{
+    schema_version: "clinkx-context-builder-lifecycle-v1";
+    runs_dir_env: "CLINKX_CONTEXT_BUILDER_RUNS_DIR";
+    lifecycle_directory: ".context-runs";
+    state_filename: "state.json";
+    operation_kinds: readonly ["standalone", "refine", "workflow_preflight", "historical"];
+    statuses: readonly ["pending", "running", "succeeded", "partial", "failed", "cancelled"];
+    phases: readonly ["resolving", "cache_lookup", "validating", "scanning", "searching", "selecting", "curating", "finalizing", "writing", "materializing", "committing", "complete", "terminal"];
+    execution_statuses: readonly ["not_configured", "disabled", "pending", "running", "succeeded", "failed", "cancelled", "skipped"];
+    fallback_statuses: readonly ["not_applicable", "not_used", "used", "failed"];
+    reason_codes: readonly ["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"];
+    max_duration_ms: 86400000;
+    max_reason_codes: 16;
+    stage_paths: Readonly<{
+        deterministic: readonly ["resolving", "validating", "scanning", "searching", "selecting", "writing", "committing", "complete"];
+        delegated: readonly ["resolving", "validating", "scanning", "searching", "selecting", "curating", "finalizing", "writing", "committing", "complete"];
+        workflow_cache_miss: readonly ["resolving", "cache_lookup", "validating", "scanning", "searching", "selecting", "curating", "finalizing", "writing", "materializing", "committing", "complete"];
+        workflow_cache_hit: readonly ["resolving", "cache_lookup", "materializing", "committing", "complete"];
+        refine: readonly ["resolving", "validating", "selecting", "writing", "committing", "complete"];
+        historical_success: readonly ["complete"];
+        historical_terminal: readonly ["terminal"];
+    }>;
+}>;
+export declare const ContextBuilderLifecycleStateV1Schema: z.ZodEffects<z.ZodObject<{
+    schema_version: z.ZodLiteral<"clinkx-context-builder-lifecycle-v1">;
+    context_run_id: z.ZodEffects<z.ZodString, string, string>;
+    artifact_run_id: z.ZodOptional<z.ZodString>;
+    operation_kind: z.ZodEnum<["standalone", "refine", "workflow_preflight", "historical"]>;
+    status: z.ZodEnum<["pending", "running", "succeeded", "partial", "failed", "cancelled"]>;
+    phase: z.ZodEnum<["resolving", "cache_lookup", "validating", "scanning", "searching", "selecting", "curating", "finalizing", "writing", "materializing", "committing", "complete", "terminal"]>;
+    created_at: z.ZodString;
+    updated_at: z.ZodString;
+    started_at: z.ZodOptional<z.ZodString>;
+    completed_at: z.ZodOptional<z.ZodString>;
+    duration_ms: z.ZodOptional<z.ZodNumber>;
+    curator: z.ZodEffects<z.ZodObject<{
+        configured: z.ZodBoolean;
+        effective_enabled: z.ZodBoolean;
+        execution_status: z.ZodEnum<["not_configured", "disabled", "pending", "running", "succeeded", "failed", "cancelled", "skipped"]>;
+        score: z.ZodOptional<z.ZodNumber>;
+    }, "strict", z.ZodTypeAny, {
+        configured: boolean;
+        effective_enabled: boolean;
+        execution_status: "succeeded" | "failed" | "cancelled" | "running" | "skipped" | "pending" | "disabled" | "not_configured";
+        score?: number | undefined;
+    }, {
+        configured: boolean;
+        effective_enabled: boolean;
+        execution_status: "succeeded" | "failed" | "cancelled" | "running" | "skipped" | "pending" | "disabled" | "not_configured";
+        score?: number | undefined;
+    }>, {
+        configured: boolean;
+        effective_enabled: boolean;
+        execution_status: "succeeded" | "failed" | "cancelled" | "running" | "skipped" | "pending" | "disabled" | "not_configured";
+        score?: number | undefined;
+    }, {
+        configured: boolean;
+        effective_enabled: boolean;
+        execution_status: "succeeded" | "failed" | "cancelled" | "running" | "skipped" | "pending" | "disabled" | "not_configured";
+        score?: number | undefined;
+    }>;
+    finalizer: z.ZodEffects<z.ZodObject<{
+        configured: z.ZodBoolean;
+        effective_enabled: z.ZodBoolean;
+        execution_status: z.ZodEnum<["not_configured", "disabled", "pending", "running", "succeeded", "failed", "cancelled", "skipped"]>;
+        score: z.ZodOptional<z.ZodNumber>;
+    }, "strict", z.ZodTypeAny, {
+        configured: boolean;
+        effective_enabled: boolean;
+        execution_status: "succeeded" | "failed" | "cancelled" | "running" | "skipped" | "pending" | "disabled" | "not_configured";
+        score?: number | undefined;
+    }, {
+        configured: boolean;
+        effective_enabled: boolean;
+        execution_status: "succeeded" | "failed" | "cancelled" | "running" | "skipped" | "pending" | "disabled" | "not_configured";
+        score?: number | undefined;
+    }>, {
+        configured: boolean;
+        effective_enabled: boolean;
+        execution_status: "succeeded" | "failed" | "cancelled" | "running" | "skipped" | "pending" | "disabled" | "not_configured";
+        score?: number | undefined;
+    }, {
+        configured: boolean;
+        effective_enabled: boolean;
+        execution_status: "succeeded" | "failed" | "cancelled" | "running" | "skipped" | "pending" | "disabled" | "not_configured";
+        score?: number | undefined;
+    }>;
+    cache: z.ZodObject<{
+        lookup: z.ZodEnum<["not_checked", "miss", "hit"]>;
+        write: z.ZodEnum<["not_attempted", "skipped", "written"]>;
+        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: "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: "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?: "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?: "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?: "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?: "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;
+        files_considered: z.ZodNumber;
+        files_selected: z.ZodNumber;
+        files_omitted: z.ZodNumber;
+        search_results: z.ZodNumber;
+        bytes_read: z.ZodNumber;
+        bytes_written: z.ZodNumber;
+    }, "strict", z.ZodTypeAny, {
+        files_seen: number;
+        files_considered: number;
+        files_selected: number;
+        files_omitted: number;
+        search_results: number;
+        bytes_read: number;
+        bytes_written: number;
+    }, {
+        files_seen: number;
+        files_considered: number;
+        files_selected: number;
+        files_omitted: number;
+        search_results: number;
+        bytes_read: number;
+        bytes_written: number;
+    }>;
+    coverage: z.ZodEffects<z.ZodObject<{
+        policy: z.ZodNullable<z.ZodLiteral<"review_deep_v1">>;
+        status: z.ZodEnum<["satisfied", "degraded", "not_evaluated"]>;
+        required: z.ZodNumber;
+        selected: z.ZodNumber;
+        missing: z.ZodNumber;
+    }, "strict", z.ZodTypeAny, {
+        missing: number;
+        status: "satisfied" | "degraded" | "not_evaluated";
+        policy: "review_deep_v1" | null;
+        required: number;
+        selected: number;
+    }, {
+        missing: number;
+        status: "satisfied" | "degraded" | "not_evaluated";
+        policy: "review_deep_v1" | null;
+        required: number;
+        selected: number;
+    }>, {
+        missing: number;
+        status: "satisfied" | "degraded" | "not_evaluated";
+        policy: "review_deep_v1" | null;
+        required: number;
+        selected: number;
+    }, {
+        missing: number;
+        status: "satisfied" | "degraded" | "not_evaluated";
+        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">, ("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?: "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: {
+        configured: boolean;
+        effective_enabled: boolean;
+        execution_status: "succeeded" | "failed" | "cancelled" | "running" | "skipped" | "pending" | "disabled" | "not_configured";
+        score?: number | undefined;
+    };
+    finalizer: {
+        configured: boolean;
+        effective_enabled: boolean;
+        execution_status: "succeeded" | "failed" | "cancelled" | "running" | "skipped" | "pending" | "disabled" | "not_configured";
+        score?: number | undefined;
+    };
+    coverage: {
+        missing: number;
+        status: "satisfied" | "degraded" | "not_evaluated";
+        policy: "review_deep_v1" | null;
+        required: number;
+        selected: number;
+    };
+    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";
+    created_at: string;
+    cache: {
+        write: "skipped" | "not_attempted" | "written";
+        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;
+    };
+    artifact_run_id?: string | undefined;
+    started_at?: string | undefined;
+    completed_at?: string | undefined;
+    duration_ms?: number | undefined;
+}, {
+    fallback: {
+        status: "failed" | "not_applicable" | "not_used" | "used";
+        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: {
+        configured: boolean;
+        effective_enabled: boolean;
+        execution_status: "succeeded" | "failed" | "cancelled" | "running" | "skipped" | "pending" | "disabled" | "not_configured";
+        score?: number | undefined;
+    };
+    finalizer: {
+        configured: boolean;
+        effective_enabled: boolean;
+        execution_status: "succeeded" | "failed" | "cancelled" | "running" | "skipped" | "pending" | "disabled" | "not_configured";
+        score?: number | undefined;
+    };
+    coverage: {
+        missing: number;
+        status: "satisfied" | "degraded" | "not_evaluated";
+        policy: "review_deep_v1" | null;
+        required: number;
+        selected: number;
+    };
+    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";
+    created_at: string;
+    cache: {
+        write: "skipped" | "not_attempted" | "written";
+        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;
+    };
+    artifact_run_id?: string | undefined;
+    started_at?: string | undefined;
+    completed_at?: string | undefined;
+    duration_ms?: number | undefined;
+}>, {
+    fallback: {
+        status: "failed" | "not_applicable" | "not_used" | "used";
+        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: {
+        configured: boolean;
+        effective_enabled: boolean;
+        execution_status: "succeeded" | "failed" | "cancelled" | "running" | "skipped" | "pending" | "disabled" | "not_configured";
+        score?: number | undefined;
+    };
+    finalizer: {
+        configured: boolean;
+        effective_enabled: boolean;
+        execution_status: "succeeded" | "failed" | "cancelled" | "running" | "skipped" | "pending" | "disabled" | "not_configured";
+        score?: number | undefined;
+    };
+    coverage: {
+        missing: number;
+        status: "satisfied" | "degraded" | "not_evaluated";
+        policy: "review_deep_v1" | null;
+        required: number;
+        selected: number;
+    };
+    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";
+    created_at: string;
+    cache: {
+        write: "skipped" | "not_attempted" | "written";
+        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;
+    };
+    artifact_run_id?: string | undefined;
+    started_at?: string | undefined;
+    completed_at?: string | undefined;
+    duration_ms?: number | undefined;
+}, {
+    fallback: {
+        status: "failed" | "not_applicable" | "not_used" | "used";
+        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: {
+        configured: boolean;
+        effective_enabled: boolean;
+        execution_status: "succeeded" | "failed" | "cancelled" | "running" | "skipped" | "pending" | "disabled" | "not_configured";
+        score?: number | undefined;
+    };
+    finalizer: {
+        configured: boolean;
+        effective_enabled: boolean;
+        execution_status: "succeeded" | "failed" | "cancelled" | "running" | "skipped" | "pending" | "disabled" | "not_configured";
+        score?: number | undefined;
+    };
+    coverage: {
+        missing: number;
+        status: "satisfied" | "degraded" | "not_evaluated";
+        policy: "review_deep_v1" | null;
+        required: number;
+        selected: number;
+    };
+    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";
+    created_at: string;
+    cache: {
+        write: "skipped" | "not_attempted" | "written";
+        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;
+    };
+    artifact_run_id?: string | undefined;
+    started_at?: string | undefined;
+    completed_at?: string | undefined;
+    duration_ms?: number | undefined;
+}>;
+export type ContextBuilderOperationKind = (typeof CONTEXT_BUILDER_OPERATION_KINDS)[number];
+export type ContextBuilderLifecycleStatus = (typeof CONTEXT_BUILDER_LIFECYCLE_STATUSES)[number];
+export type ContextBuilderLifecyclePhase = (typeof CONTEXT_BUILDER_LIFECYCLE_PHASES)[number];
+export type ContextBuilderLifecycleReasonCode = (typeof CONTEXT_BUILDER_LIFECYCLE_REASON_CODES)[number];
+export type ContextBuilderLifecycleStateV1 = z.infer<typeof ContextBuilderLifecycleStateV1Schema>;
+export interface ContextBuilderOperationIdGeneratorOptions {
+    readonly now?: () => Date;
+    readonly randomHex?: () => string;
+}
+export interface ContextBuilderLifecycleLocation {
+    readonly runs_dir: string;
+    readonly journal_dir: string;
+    readonly context_run_dir: string;
+    readonly state_json: string;
+}
+export declare function parseContextBuilderLifecycleStateV1(value: unknown): ContextBuilderLifecycleStateV1;
+export declare function isContextBuilderOperationId(value: string): boolean;
+export declare function validateContextBuilderOperationId(value: string): string;
+export declare function generateContextBuilderOperationId(options?: ContextBuilderOperationIdGeneratorOptions): string;
+/** Pure location contract only; H0 performs no filesystem writes. */
+export declare function resolveContextBuilderLifecycleLocation(runsDir: string, contextRunId: string): ContextBuilderLifecycleLocation;
+export declare function isTerminalContextBuilderLifecycleStatus(status: ContextBuilderLifecycleStatus): boolean;
+export declare function isLegalContextBuilderLifecycleTransition(previous: ContextBuilderLifecycleStateV1, next: ContextBuilderLifecycleStateV1): boolean;