clinkx 0.3.0 → 1.0.0

package/dist/context-builder/lifecycle-journal.js

@@ -0,0 +1,88 @@
+import { mkdir as fsMkdir, open as fsOpen, rename as fsRename, rm as fsRm, } from "node:fs/promises";
+import { randomBytes } from "node:crypto";
+import { logger } from "../logger.js";
+import { resolveContextBuilderRunsDir } from "./config.js";
+import { recordContextRunCatalogMarker } from "./context-run-catalog.js";
+import { createSessionLogGeneration } from "../../clinkx-workflows/dist/dashboard/session-log-identity.js";
+import { parseContextBuilderLifecycleStateV1, resolveContextBuilderLifecycleLocation, } from "./lifecycle-contract.js";
+const DEFAULT_JOURNAL_OPS = {
+    // `recursive` mkdir resolves to the first-created path; normalize to void so
+    // the ops contract stays a clean fire-and-forget.
+    mkdir: (dir, options) => fsMkdir(dir, options).then(() => undefined),
+    open: fsOpen,
+    rename: fsRename,
+    rm: fsRm,
+};
+export function createContextBuilderLifecycleJournal(options = {}) {
+    const ops = options.ops ?? DEFAULT_JOURNAL_OPS;
+    const resolveRunsDir = options.resolveRunsDir ??
+        ((runsDir) => resolveContextBuilderRunsDir(runsDir));
+    let runsDirPromise;
+    let journalDirValue;
+    let sessionLogGeneration;
+    let chain = Promise.resolve();
+    const persist = async (snapshot) => {
+        // Defensive re-validation: the controller already validated this snapshot,
+        // but the journal is the durable authority and must never persist a shape a
+        // reader cannot parse back through the frozen schema.
+        const validated = parseContextBuilderLifecycleStateV1(snapshot);
+        if (runsDirPromise === undefined) {
+            runsDirPromise = resolveRunsDir(options.runsDir);
+        }
+        const runsDir = await runsDirPromise;
+        const location = resolveContextBuilderLifecycleLocation(runsDir, validated.context_run_id);
+        journalDirValue = location.journal_dir;
+        await ops.mkdir(location.context_run_dir, {
+            recursive: true,
+            mode: 0o700,
+        });
+        if (sessionLogGeneration === undefined) {
+            sessionLogGeneration = await createSessionLogGeneration(location.context_run_dir);
+        }
+        await writeAtomicStateJson(location.state_json, `${JSON.stringify(validated)}\n`, ops);
+        await recordContextRunCatalogMarker({
+            runsDir,
+            kind: "operation",
+            id: validated.context_run_id,
+            createdAt: validated.created_at,
+        }).catch(() => {
+            logger.warn({ contextRunId: validated.context_run_id }, "context run catalog marker write failed");
+        });
+    };
+    const observe = (transition) => {
+        const next = chain.then(() => persist(transition.snapshot));
+        // Swallow on the shared chain so a rejected write never poisons a later
+        // one; the returned promise still rejects so the controller fails closed.
+        chain = next.catch(() => { });
+        return next;
+    };
+    return {
+        observe,
+        journalDir: () => journalDirValue,
+    };
+}
+async function writeAtomicStateJson(finalPath, content, ops) {
+    const tempPath = `${finalPath}.${randomBytes(8).toString("hex")}.tmp`;
+    let handle;
+    let renamed = false;
+    try {
+        // wx: fail if the temp already exists rather than clobber a concurrent
+        // writer's staging file.
+        handle = await ops.open(tempPath, "wx", 0o600);
+        await handle.writeFile(content, { encoding: "utf8" });
+        await handle.sync();
+        await handle.close();
+        handle = undefined;
+        await ops.rename(tempPath, finalPath);
+        renamed = true;
+    }
+    finally {
+        if (handle !== undefined) {
+            await handle.close().catch(() => { });
+        }
+        if (!renamed) {
+            await ops.rm(tempPath, { force: true }).catch(() => { });
+        }
+    }
+}
+//# sourceMappingURL=lifecycle-journal.js.map

package/dist/context-builder/lifecycle-journal.js.map

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

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

@@ -0,0 +1,102 @@
+import { type ContextBuilderLifecyclePhase, type ContextBuilderLifecycleReasonCode, type ContextBuilderLifecycleStateV1, type ContextBuilderLifecycleStatus, type ContextBuilderOperationKind } from "./lifecycle-contract.js";
+export interface ContextBuilderLifecycleTransition {
+    readonly previous: Readonly<ContextBuilderLifecycleStateV1> | null;
+    readonly snapshot: Readonly<ContextBuilderLifecycleStateV1>;
+}
+/**
+ * A successful return acknowledges the validated transition. Rejection is
+ * fail-closed: the producer stops and no best-effort notification is sent.
+ */
+export type ContextBuilderLifecycleObserver = (transition: ContextBuilderLifecycleTransition) => void | Promise<void>;
+export interface ContextBuilderLifecycleOrigin {
+    readonly context_run_id?: string;
+    readonly created_at?: string;
+}
+/**
+ * Session-log identity for context-builder delegate (curator/finalizer) calls.
+ * The workflow preflight path sources this from a generation sidecar the runner
+ * creates under the workflow run dir; the standalone path derives it from the
+ * journal dir.
+ */
+export interface ContextBuilderSessionLogContext {
+    readonly contextRunId: string;
+    readonly contextGeneration: string;
+}
+export interface ContextBuilderLifecycleInjection {
+    readonly observer: ContextBuilderLifecycleObserver;
+    readonly origin?: ContextBuilderLifecycleOrigin;
+}
+export interface ContextBuilderLifecycleExecutionConfig {
+    readonly curator: {
+        readonly configured: boolean;
+        readonly enabled: boolean;
+    };
+    readonly finalizer: {
+        readonly configured: boolean;
+        readonly enabled: boolean;
+    };
+}
+export interface ContextBuilderLifecycleControllerOptions {
+    readonly operationKind: ContextBuilderOperationKind;
+    readonly execution: ContextBuilderLifecycleExecutionConfig;
+    readonly observer?: ContextBuilderLifecycleObserver;
+    readonly notificationObserver?: ContextBuilderLifecycleObserver;
+    readonly origin?: ContextBuilderLifecycleOrigin;
+    readonly now?: () => Date;
+}
+export interface ContextBuilderLifecycleCounts {
+    readonly files_seen: number;
+    readonly files_considered: number;
+    readonly files_selected: number;
+    readonly files_omitted: number;
+    readonly search_results: number;
+    readonly bytes_read: number;
+    readonly bytes_written: number;
+}
+export interface ContextBuilderLifecycleCoverage {
+    readonly policy: "review_deep_v1" | null;
+    readonly status: "satisfied" | "degraded" | "not_evaluated";
+    readonly required: number;
+    readonly selected: number;
+    readonly missing: number;
+}
+type ExecutionStatus = ContextBuilderLifecycleStateV1["curator"]["execution_status"];
+export interface ContextBuilderLifecyclePatch {
+    readonly artifactRunId?: string;
+    readonly curatorStatus?: ExecutionStatus;
+    readonly curatorScore?: number;
+    readonly finalizerStatus?: ExecutionStatus;
+    readonly finalizerScore?: number;
+    readonly cache?: ContextBuilderLifecycleStateV1["cache"];
+    readonly fallback?: ContextBuilderLifecycleStateV1["fallback"];
+    readonly counts?: ContextBuilderLifecycleCounts;
+    readonly coverage?: ContextBuilderLifecycleCoverage;
+    readonly reasonCodes?: readonly ContextBuilderLifecycleReasonCode[];
+}
+export declare class ContextBuilderLifecycleObserverError extends Error {
+    constructor(cause: unknown);
+}
+/**
+ * Serial authoritative transition source. It validates every snapshot and
+ * monotonic edge before delivery. The observer is awaited first; the
+ * notification adapter runs only after observer acknowledgement.
+ */
+export declare class ContextBuilderLifecycleController {
+    private readonly now;
+    private readonly observer;
+    private readonly notificationObserver;
+    private readonly initial;
+    private current;
+    private chain;
+    private observerFailure;
+    constructor(options: ContextBuilderLifecycleControllerOptions);
+    get contextRunId(): string;
+    get operationKind(): ContextBuilderOperationKind;
+    get snapshot(): Readonly<ContextBuilderLifecycleStateV1> | undefined;
+    transition(phase: ContextBuilderLifecyclePhase, patch?: ContextBuilderLifecyclePatch): Promise<void>;
+    complete(status: Extract<ContextBuilderLifecycleStatus, "succeeded" | "partial">, patch?: ContextBuilderLifecyclePatch): Promise<void>;
+    fail(status: Extract<ContextBuilderLifecycleStatus, "failed" | "cancelled">, patch?: ContextBuilderLifecyclePatch): Promise<void>;
+    private enqueue;
+    private deliver;
+}
+export {};

package/dist/context-builder/lifecycle-observer.js

@@ -0,0 +1,258 @@
+import { CONTEXT_BUILDER_LIFECYCLE_SCHEMA_VERSION, generateContextBuilderOperationId, isLegalContextBuilderLifecycleTransition, parseContextBuilderLifecycleStateV1, validateContextBuilderOperationId, } from "./lifecycle-contract.js";
+export class ContextBuilderLifecycleObserverError extends Error {
+    constructor(cause) {
+        super("context builder lifecycle observer rejected a transition", { cause });
+        this.name = "ContextBuilderLifecycleObserverError";
+    }
+}
+/**
+ * Serial authoritative transition source. It validates every snapshot and
+ * monotonic edge before delivery. The observer is awaited first; the
+ * notification adapter runs only after observer acknowledgement.
+ */
+export class ContextBuilderLifecycleController {
+    now;
+    observer;
+    notificationObserver;
+    initial;
+    current;
+    chain = Promise.resolve();
+    observerFailure;
+    constructor(options) {
+        this.now = options.now ?? (() => new Date());
+        this.observer = options.observer;
+        this.notificationObserver = options.notificationObserver;
+        const createdAt = options.origin?.created_at ?? this.now().toISOString();
+        const contextRunId = options.origin?.context_run_id == null
+            ? generateContextBuilderOperationId({ now: () => new Date(createdAt) })
+            : validateContextBuilderOperationId(options.origin.context_run_id);
+        this.initial = parseContextBuilderLifecycleStateV1({
+            schema_version: CONTEXT_BUILDER_LIFECYCLE_SCHEMA_VERSION,
+            context_run_id: contextRunId,
+            operation_kind: options.operationKind,
+            status: "pending",
+            phase: "resolving",
+            created_at: createdAt,
+            updated_at: createdAt,
+            curator: initialExecutionState(options.execution.curator),
+            finalizer: initialExecutionState(options.execution.finalizer),
+            cache: { lookup: "not_checked", write: "not_attempted" },
+            fallback: {
+                status: options.execution.curator.enabled
+                    ? "not_used"
+                    : "not_applicable",
+            },
+            counts: emptyCounts(),
+            coverage: notEvaluatedCoverage(),
+            reason_codes: [],
+        });
+    }
+    get contextRunId() {
+        return this.initial.context_run_id;
+    }
+    get operationKind() {
+        return this.initial.operation_kind;
+    }
+    get snapshot() {
+        return this.current == null ? undefined : immutableSnapshot(this.current);
+    }
+    transition(phase, patch = {}) {
+        return this.enqueue(() => this.deliver(phase, "running", patch));
+    }
+    complete(status, patch = {}) {
+        return this.enqueue(() => this.deliver("complete", status, patch));
+    }
+    fail(status, patch = {}) {
+        return this.enqueue(() => this.deliver("terminal", status, patch));
+    }
+    enqueue(work) {
+        const next = this.chain.then(work);
+        this.chain = next.catch(() => { });
+        return next;
+    }
+    async deliver(phase, status, patch) {
+        if (this.observerFailure != null) {
+            throw this.observerFailure;
+        }
+        const previous = this.current;
+        if (previous != null && isSemanticDuplicate(previous, phase, status, patch)) {
+            return;
+        }
+        if (previous != null &&
+            (previous.status === "succeeded" || previous.status === "partial" ||
+                previous.status === "failed" || previous.status === "cancelled")) {
+            throw new Error(`illegal context builder lifecycle transition: ${previous.phase}/${previous.status} -> ${phase}/${status}`);
+        }
+        const timestamp = monotonicTimestamp(this.now().toISOString(), previous?.updated_at ?? this.initial.updated_at);
+        const base = previous ?? this.initial;
+        const terminal = status === "succeeded" || status === "partial" ||
+            status === "failed" || status === "cancelled";
+        const next = parseContextBuilderLifecycleStateV1({
+            ...base,
+            ...(patch.artifactRunId == null
+                ? {}
+                : { artifact_run_id: patch.artifactRunId }),
+            status,
+            phase,
+            updated_at: timestamp,
+            started_at: base.started_at ?? timestamp,
+            ...(terminal
+                ? {
+                    completed_at: timestamp,
+                    duration_ms: boundedDuration(base.created_at, timestamp),
+                }
+                : {}),
+            curator: patchExecutionState(base.curator, patch.curatorStatus, patch.curatorScore),
+            finalizer: patchExecutionState(base.finalizer, patch.finalizerStatus, patch.finalizerScore),
+            cache: patch.cache ?? base.cache,
+            fallback: patch.fallback ?? base.fallback,
+            counts: patch.counts ?? base.counts,
+            coverage: patch.coverage ?? base.coverage,
+            reason_codes: mergeReasonCodes(base.reason_codes, patch.reasonCodes),
+        });
+        if (previous != null && !isLegalContextBuilderLifecycleTransition(previous, next)) {
+            throw new Error(`illegal context builder lifecycle transition: ${previous.phase}/${previous.status} -> ${next.phase}/${next.status}`);
+        }
+        const transition = Object.freeze({
+            previous: previous == null ? null : immutableSnapshot(previous),
+            snapshot: immutableSnapshot(next),
+        });
+        if (this.observer != null) {
+            try {
+                await this.observer(transition);
+            }
+            catch (error) {
+                if (phase === "complete" && (status === "succeeded" || status === "partial")) {
+                    try {
+                        await this.observer(transition);
+                    }
+                    catch (retryError) {
+                        this.observerFailure =
+                            new ContextBuilderLifecycleObserverError(retryError);
+                        throw this.observerFailure;
+                    }
+                }
+                else {
+                    this.observerFailure = new ContextBuilderLifecycleObserverError(error);
+                    throw this.observerFailure;
+                }
+            }
+        }
+        this.current = next;
+        if (this.notificationObserver != null) {
+            try {
+                await this.notificationObserver(transition);
+            }
+            catch {
+                // Notification adapters are explicitly best-effort. Concrete adapters
+                // log their own diagnostics without changing the authoritative sequence.
+            }
+        }
+    }
+}
+function initialExecutionState(input) {
+    if (!input.configured) {
+        return {
+            configured: false,
+            effective_enabled: false,
+            execution_status: "not_configured",
+        };
+    }
+    if (!input.enabled) {
+        return {
+            configured: true,
+            effective_enabled: false,
+            execution_status: "disabled",
+        };
+    }
+    return {
+        configured: true,
+        effective_enabled: true,
+        execution_status: "pending",
+    };
+}
+function patchExecutionState(previous, status, score) {
+    const executionStatus = status ?? previous.execution_status;
+    const effectiveScore = score ??
+        (executionStatus === "succeeded" ? previous.score : undefined);
+    return {
+        configured: previous.configured,
+        effective_enabled: previous.effective_enabled,
+        execution_status: executionStatus,
+        ...(effectiveScore == null ? {} : { score: effectiveScore }),
+    };
+}
+function emptyCounts() {
+    return {
+        files_seen: 0,
+        files_considered: 0,
+        files_selected: 0,
+        files_omitted: 0,
+        search_results: 0,
+        bytes_read: 0,
+        bytes_written: 0,
+    };
+}
+function notEvaluatedCoverage() {
+    return {
+        policy: null,
+        status: "not_evaluated",
+        required: 0,
+        selected: 0,
+        missing: 0,
+    };
+}
+function mergeReasonCodes(previous, next) {
+    return [...new Set([...previous, ...(next ?? [])])];
+}
+function isSemanticDuplicate(previous, phase, status, patch) {
+    if (previous.phase !== phase || previous.status !== status)
+        return false;
+    if (patch.artifactRunId != null && patch.artifactRunId !== previous.artifact_run_id) {
+        return false;
+    }
+    if (patch.curatorStatus != null &&
+        patch.curatorStatus !== previous.curator.execution_status)
+        return false;
+    if (patch.curatorScore != null && patch.curatorScore !== previous.curator.score) {
+        return false;
+    }
+    if (patch.finalizerStatus != null &&
+        patch.finalizerStatus !== previous.finalizer.execution_status)
+        return false;
+    if (patch.finalizerScore != null && patch.finalizerScore !== previous.finalizer.score) {
+        return false;
+    }
+    if (patch.cache != null && JSON.stringify(patch.cache) !== JSON.stringify(previous.cache)) {
+        return false;
+    }
+    if (patch.fallback != null &&
+        JSON.stringify(patch.fallback) !== JSON.stringify(previous.fallback))
+        return false;
+    if (patch.counts != null && JSON.stringify(patch.counts) !== JSON.stringify(previous.counts)) {
+        return false;
+    }
+    if (patch.coverage != null &&
+        JSON.stringify(patch.coverage) !== JSON.stringify(previous.coverage))
+        return false;
+    return (patch.reasonCodes ?? []).every((code) => previous.reason_codes.includes(code));
+}
+function monotonicTimestamp(candidate, floor) {
+    return Date.parse(candidate) < Date.parse(floor) ? floor : candidate;
+}
+function boundedDuration(createdAt, completedAt) {
+    return Math.min(86_400_000, Math.max(0, Date.parse(completedAt) - Date.parse(createdAt)));
+}
+function immutableSnapshot(state) {
+    return deepFreeze(parseContextBuilderLifecycleStateV1(state));
+}
+function deepFreeze(value) {
+    if (value != null && typeof value === "object" && !Object.isFrozen(value)) {
+        for (const child of Object.values(value)) {
+            deepFreeze(child);
+        }
+        Object.freeze(value);
+    }
+    return value;
+}
+//# sourceMappingURL=lifecycle-observer.js.map

package/dist/context-builder/lifecycle-observer.js.map

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

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

@@ -0,0 +1,32 @@
+import { type ContextBuilderLifecycleStateV1 } from "./lifecycle-contract.js";
+export type ContextRunWorkerObservation = "live" | "dead" | "unknown";
+export interface ReconcileStaleContextBuilderJournalsResult {
+    readonly scanned: number;
+    readonly reconciled: number;
+    readonly skipped: number;
+    readonly failed: number;
+}
+export interface ReconcileStaleContextBuilderJournalsOptions {
+    readonly runsDir?: string;
+    readonly now?: () => Date;
+    readonly hostname?: string;
+    readonly isProcessAlive?: (pid: number) => boolean;
+}
+/**
+ * Terminalize standalone/refine journals frozen as pending/running whose
+ * same-host `.building.json` pid is dead. Foreign-host and missing/unparseable
+ * pid evidence is `unknown` and is never touched — same asymmetry as workflow
+ * `reconcileStaleRunDirectories`. Does not invent a dedicated worker lock;
+ * liveness is the building-json pid probe only.
+ *
+ * Writes `failed`/`terminal` + `internal_failure`. Never `cancelled`. Never
+ * rewrites curator/finalizer outcomes. Best-effort incomplete-artifact cleanup
+ * after the journal write. Idempotent. Log-and-continue on malformed rows.
+ */
+export declare function reconcileStaleContextBuilderJournals(options?: ReconcileStaleContextBuilderJournalsOptions): Promise<ReconcileStaleContextBuilderJournalsResult>;
+export declare function observeContextRunWorker(input: {
+    readonly runsDir: string;
+    readonly state: ContextBuilderLifecycleStateV1;
+    readonly hostname: string;
+    readonly isProcessAlive: (pid: number) => boolean;
+}): Promise<ContextRunWorkerObservation>;