clinkx 0.3.0 → 1.0.0

package/clinkx-workflows/dist/dashboard/scanner.js

@@ -0,0 +1,1110 @@
+import { createCipheriv, createDecipheriv, randomBytes } from "node:crypto";
+import { lstat, opendir } from "node:fs/promises";
+import { resolve } from "node:path";
+import { containedFileFingerprintsEqual, } from "../contained-file.js";
+import { validateRunId } from "../run-id.js";
+import { isPlanReviewRunState } from "../plan-review/admission.js";
+import { MAX_DASHBOARD_LIVE_RUNS, MAX_DASHBOARD_PAGE_SIZE, MAX_DASHBOARD_ROOTS, MAX_DASHBOARD_STAGE_MARKERS, } from "./contracts.js";
+import { createDashboardRunReader, DEFAULT_DASHBOARD_MAX_STATE_BYTES, } from "./read-model.js";
+import { assertValidDashboardArtifactCursor, buildDashboardArtifactReferenceIndex, DEFAULT_DASHBOARD_ARTIFACT_INDEX_BYTE_BUDGET, DEFAULT_DASHBOARD_ARTIFACT_REFERENCE_LIMIT, DashboardInvalidCursorError, } from "./artifact-index.js";
+import { createDashboardLazyContentReader, } from "./lazy-content.js";
+import { createDashboardWorkerLockObserver, } from "./worker-lock-observer.js";
+import { projectContextRunLifecycleState } from "./context-run-reader.js";
+export const DEFAULT_DASHBOARD_CANDIDATE_LIMIT = 10_000;
+export const DEFAULT_DASHBOARD_SCAN_BYTE_BUDGET = 256 * 1_024 * 1_024;
+export const DEFAULT_DASHBOARD_PROJECTION_CACHE_BYTE_BUDGET = 32 * 1_024 * 1_024;
+export const DEFAULT_DASHBOARD_DETAIL_CACHE_ENTRIES = 8;
+export const DEFAULT_DASHBOARD_DETAIL_CACHE_BYTE_BUDGET = 32 * 1_024 * 1_024;
+export const DEFAULT_DASHBOARD_DECODE_QUEUE_LIMIT = 32;
+export const DEFAULT_DASHBOARD_SCANNER_MAX_STATE_BYTES = DEFAULT_DASHBOARD_MAX_STATE_BYTES;
+const WORKER_LOCK_OBSERVATION_CONCURRENCY = 8;
+export class DashboardReadModelError extends Error {
+    code;
+    status;
+    constructor(code) {
+        super(code);
+        this.name = "DashboardReadModelError";
+        this.code = code;
+        this.status = 503;
+    }
+}
+class SerialSingleFlightScheduler {
+    #queueLimit;
+    #pending = new Map();
+    #queue = [];
+    #active = false;
+    constructor(queueLimit) {
+        this.#queueLimit = queueLimit;
+    }
+    run(key, task) {
+        const existing = this.#pending.get(key);
+        if (existing !== undefined)
+            return existing;
+        if (this.#active && this.#queue.length >= this.#queueLimit) {
+            return Promise.reject(new DashboardReadModelError("dashboard_busy"));
+        }
+        let resolveTask;
+        let rejectTask;
+        const promise = new Promise((resolvePromise, rejectPromise) => {
+            resolveTask = resolvePromise;
+            rejectTask = rejectPromise;
+        });
+        this.#pending.set(key, promise);
+        const scheduled = { key, task, resolve: resolveTask, reject: rejectTask };
+        if (this.#active) {
+            this.#queue.push(scheduled);
+        }
+        else {
+            this.#start(scheduled);
+        }
+        return promise;
+    }
+    #start(scheduled) {
+        this.#active = true;
+        void scheduled.task().then(scheduled.resolve, scheduled.reject).finally(() => {
+            this.#pending.delete(scheduled.key);
+            const next = this.#queue.shift();
+            if (next === undefined) {
+                this.#active = false;
+            }
+            else {
+                this.#start(next);
+            }
+        });
+    }
+}
+async function* defaultListCandidates(runsRoot) {
+    const directory = await opendir(runsRoot);
+    for await (const entry of directory)
+        yield entry;
+}
+const defaultScannerFileSystem = {
+    listCandidates: defaultListCandidates,
+    lstat: async (path) => await lstat(path, { bigint: true }),
+};
+function hasErrorCode(error, code) {
+    return error?.code === code;
+}
+async function mapWithFixedConcurrency(items, concurrency, mapper) {
+    const results = new Array(items.length);
+    let nextIndex = 0;
+    async function worker() {
+        while (nextIndex < items.length) {
+            const index = nextIndex;
+            nextIndex += 1;
+            results[index] = await mapper(items[index], index);
+        }
+    }
+    await Promise.all(Array.from({ length: Math.min(concurrency, items.length) }, async () => await worker()));
+    return results;
+}
+function directoryIdentity(stats) {
+    return { dev: stats.dev, ino: stats.ino, birthtimeNs: stats.birthtimeNs };
+}
+function fileFingerprint(stats) {
+    return {
+        dev: stats.dev,
+        ino: stats.ino,
+        mtimeNs: stats.mtimeNs,
+        ctimeNs: stats.ctimeNs,
+        size: stats.size,
+        nlink: stats.nlink,
+    };
+}
+function directoryIdentitiesEqual(left, right) {
+    return left.dev === right.dev && left.ino === right.ino && left.birthtimeNs === right.birthtimeNs;
+}
+function identityKey(identity) {
+    const directory = identity.directoryIdentity;
+    const root = identity.rootIdentity;
+    const file = identity.fingerprint;
+    return [
+        root.dev,
+        root.ino,
+        root.birthtimeNs,
+        directory.dev,
+        directory.ino,
+        directory.birthtimeNs,
+        file.dev,
+        file.ino,
+        file.mtimeNs,
+        file.ctimeNs,
+        file.size,
+        file.nlink,
+    ].join(":");
+}
+function timeOrFallback(value, fingerprint) {
+    if (value !== undefined) {
+        const parsed = Date.parse(value);
+        if (Number.isFinite(parsed))
+            return BigInt(parsed) * 1000000n;
+    }
+    return fingerprint.mtimeNs;
+}
+function compareStrings(left, right) {
+    return left < right ? -1 : left > right ? 1 : 0;
+}
+function compareAscending(left, right) {
+    return left.timeNs < right.timeNs
+        ? -1
+        : left.timeNs > right.timeNs
+            ? 1
+            : compareStrings(left.runId, right.runId);
+}
+function compareDescending(left, right) {
+    return left.timeNs > right.timeNs
+        ? -1
+        : left.timeNs < right.timeNs
+            ? 1
+            : compareStrings(right.runId, left.runId);
+}
+function encodeCursor(secret, key) {
+    const iv = randomBytes(12);
+    const cipher = createCipheriv("aes-256-gcm", secret, iv);
+    const ciphertext = Buffer.concat([
+        cipher.update(JSON.stringify([key.timeNs.toString(), key.runId]), "utf8"),
+        cipher.final(),
+    ]);
+    return Buffer.concat([iv, cipher.getAuthTag(), ciphertext]).toString("base64url");
+}
+function decodeCursor(secret, cursor) {
+    if (cursor.length === 0 || cursor.length > 1_024 || !/^[A-Za-z0-9_-]+$/.test(cursor)) {
+        return undefined;
+    }
+    try {
+        const packed = Buffer.from(cursor, "base64url");
+        if (packed.byteLength < 29)
+            return undefined;
+        const decipher = createDecipheriv("aes-256-gcm", secret, packed.subarray(0, 12));
+        decipher.setAuthTag(packed.subarray(12, 28));
+        const plaintext = Buffer.concat([
+            decipher.update(packed.subarray(28)),
+            decipher.final(),
+        ]).toString("utf8");
+        const decoded = JSON.parse(plaintext);
+        if (!Array.isArray(decoded) ||
+            decoded.length !== 2 ||
+            typeof decoded[0] !== "string" ||
+            !/^-?[0-9]+$/.test(decoded[0]) ||
+            typeof decoded[1] !== "string" ||
+            decoded[1].length === 0)
+            return undefined;
+        return { timeNs: BigInt(decoded[0]), runId: decoded[1] };
+    }
+    catch {
+        return undefined;
+    }
+}
+function requireHistoryCursor(secret, cursor) {
+    const decoded = decodeCursor(secret, cursor);
+    if (decoded === undefined) {
+        throw new DashboardInvalidCursorError("invalid dashboard history cursor");
+    }
+    return decoded;
+}
+function countStates(values) {
+    const counts = { pending: 0, running: 0, succeeded: 0, failed: 0, cancelled: 0 };
+    for (const value of values)
+        counts[value.state] += 1;
+    return counts;
+}
+function listProjection(admitted, stateRevision) {
+    const { state } = admitted;
+    const calls = state.stages.flatMap((stage) => stage.calls);
+    const projectFolders = projectFoldersFromVariables(state.variables?.cb_roots);
+    const stageMarkers = state.stages.slice(0, MAX_DASHBOARD_STAGE_MARKERS).map((stage) => ({
+        stageId: stage.stageId,
+        state: stage.state,
+    }));
+    return {
+        availability: "available",
+        runId: admitted.runId,
+        runGeneration: admitted.runGeneration,
+        stateRevision,
+        workflowName: state.workflowName,
+        workflowVersion: state.workflowVersion,
+        status: state.status,
+        orphaned: false,
+        resumable: state.resumable,
+        ...(state.startedAt === undefined ? {} : { startedAt: state.startedAt }),
+        ...(state.completedAt === undefined ? {} : { completedAt: state.completedAt }),
+        stateUpdatedAt: new Date(Number(admitted.stateFingerprint.mtimeNs / 1000000n)).toISOString(),
+        ...(state.failureClass === undefined ? {} : { failureClass: state.failureClass }),
+        async: state.async ?? false,
+        debugKeepArtifacts: state.debugKeepArtifacts ?? false,
+        retryCount: calls.reduce((sum, call) => sum + call.retryCount, 0),
+        reportedRunningCalls: calls.filter((call) => call.state === "running").length,
+        stageCounts: countStates(state.stages),
+        callCounts: countStates(calls),
+        stageMarkers,
+        additionalStageCount: state.stages.length - stageMarkers.length,
+        projectFolders,
+    };
+}
+/**
+ * Project the run's project folder(s) from persisted `variables.cb_roots`. The
+ * decoder guarantees a string array, but `variables` is `Record<string,unknown>`
+ * in the frozen state schema, so guard defensively and cap at the dashboard
+ * bound. Returns `[]` when no roots were recorded.
+ */
+function projectFoldersFromVariables(cbRoots) {
+    if (cbRoots === undefined)
+        return [];
+    const folders = [];
+    for (const entry of cbRoots) {
+        if (typeof entry === "string" && entry.length > 0) {
+            folders.push(entry);
+            if (folders.length >= MAX_DASHBOARD_ROOTS)
+                break;
+        }
+    }
+    return folders;
+}
+function detailProjection(admitted, listItem) {
+    const { state } = admitted;
+    const calls = state.stages.flatMap((stage) => stage.calls);
+    const failedCall = calls.find((call) => call.state === "failed");
+    const result = state.status === "pending"
+        ? { availability: "unavailable", reason: "run_pending" }
+        : state.status === "running"
+            ? { availability: "unavailable", reason: "run_running" }
+            : state.status === "failed"
+                ? { availability: "unavailable", reason: "run_failed" }
+                : state.status === "cancelled"
+                    ? { availability: "unavailable", reason: "run_cancelled" }
+                    : { availability: "unavailable", reason: "not_persisted" };
+    const preflightConfiguration = {
+        profile: state.variables?.cb_profile ?? null,
+        effectiveMode: state.initialContextPolicy?.effectiveMode ??
+            state.workflow_context?.context_builder.context_mode ??
+            null,
+        failurePolicy: state.initialContextPolicy?.effectiveDelegate === undefined
+            ? null
+            : state.initialContextPolicy.effectiveDelegate.failure_policy ?? "fallback",
+    };
+    return {
+        ...listItem,
+        contextPreflight: state.context_builder_lifecycle !== undefined
+            ? {
+                availability: "current",
+                ...projectContextRunLifecycleState(state.context_builder_lifecycle),
+                // The ctxop_… operation id pairs with the preflight session-log
+                // generation sidecar (<runDir>/.context-preflight); surfaced only for
+                // the workflow-embedded preflight (standalone rows carry it as `id`).
+                contextRunId: state.context_builder_lifecycle.context_run_id,
+                ...preflightConfiguration,
+            }
+            : state.workflow_context !== undefined
+                ? {
+                    availability: "legacy_without_telemetry",
+                    status: state.workflow_context.context_builder.status,
+                    ...preflightConfiguration,
+                }
+                : state.initialContextPolicy !== undefined
+                    ? {
+                        availability: state.initialContextPolicy.effectiveMode === "off" ||
+                            state.initialContextPolicy.effectiveMode === "disabled"
+                            ? "bypassed"
+                            : state.status === "pending" || state.status === "running"
+                                ? "awaiting_telemetry"
+                                : "telemetry_unavailable",
+                        ...preflightConfiguration,
+                        effectiveMode: state.initialContextPolicy.effectiveMode,
+                    }
+                    : { availability: "absent" },
+        snapshotEnrichment: state.workflowSnapshotPath === undefined
+            ? { availability: "unavailable", reason: "missing" }
+            : { availability: "unavailable", reason: "not_loaded" },
+        result,
+        ...(failedCall === undefined || (failedCall.failureClass ?? state.failureClass) === undefined
+            ? {}
+            : {
+                decisiveFailure: {
+                    stageId: failedCall.stageId,
+                    callId: failedCall.callId,
+                    failureClass: failedCall.failureClass ?? state.failureClass,
+                },
+            }),
+        card: {
+            kind: "generic",
+            stageCounts: countStates(state.stages),
+            callCounts: countStates(calls),
+        },
+        stages: state.stages.map((stage) => ({
+            stageId: stage.stageId,
+            state: stage.state,
+            ...(stage.startedAt === undefined ? {} : { startedAt: stage.startedAt }),
+            ...(stage.completedAt === undefined ? {} : { completedAt: stage.completedAt }),
+            calls: stage.calls.map((call) => ({
+                stageId: call.stageId,
+                callId: call.callId,
+                state: call.state,
+                retryCount: call.retryCount,
+                ...(call.attemptsConsumed === undefined ? {} : { attemptsConsumed: call.attemptsConsumed }),
+                ...(call.startedAt === undefined ? {} : { startedAt: call.startedAt }),
+                ...(call.completedAt === undefined ? {} : { completedAt: call.completedAt }),
+                ...(call.durationMs === undefined ? {} : { durationMs: call.durationMs }),
+                ...(call.failureClass === undefined ? {} : { failureClass: call.failureClass }),
+                hasWorkflowInput: call.materializedInputPath !== undefined,
+                hasOutput: call.outputInline !== undefined || call.outputPath !== undefined,
+                hasRawError: call.errorMessage !== undefined,
+                hasArtifactReference: call.artifactPath !== undefined,
+            })),
+        })),
+    };
+}
+function emptyRootCache() {
+    return {
+        entries: new Map(),
+        revisions: new Map(),
+        details: new Map(),
+        detailBytes: 0,
+        movedToHistory: new Set(),
+        artifactIndexFailed: false,
+    };
+}
+function candidateListingIdentity(stats) {
+    if (!stats.isDirectory() || stats.nlink === 0n)
+        return undefined;
+    return {
+        dev: stats.dev,
+        ino: stats.ino,
+        birthtimeNs: stats.birthtimeNs,
+        mtimeNs: stats.mtimeNs,
+        ctimeNs: stats.ctimeNs,
+        nlink: stats.nlink,
+    };
+}
+function candidateListingIdentitiesEqual(left, right) {
+    return left.dev === right.dev &&
+        left.ino === right.ino &&
+        left.birthtimeNs === right.birthtimeNs &&
+        left.mtimeNs === right.mtimeNs &&
+        left.ctimeNs === right.ctimeNs &&
+        left.nlink === right.nlink;
+}
+export function createDashboardRunScanner(options = {}) {
+    const fileSystem = options.fileSystem ?? defaultScannerFileSystem;
+    const runReader = options.runReader ?? createDashboardRunReader({
+        maxStateBytes: options.maxStateBytes ?? DEFAULT_DASHBOARD_SCANNER_MAX_STATE_BYTES,
+        includeUnavailableAdmissionMetadata: true,
+    });
+    const now = options.now ?? (() => new Date());
+    const generateStateRevision = options.generateStateRevision ??
+        (() => randomBytes(16).toString("base64url"));
+    const candidateLimit = options.candidateLimit ?? DEFAULT_DASHBOARD_CANDIDATE_LIMIT;
+    const scanByteBudget = options.scanByteBudget ?? DEFAULT_DASHBOARD_SCAN_BYTE_BUDGET;
+    const projectionCacheByteBudget = options.projectionCacheByteBudget ??
+        DEFAULT_DASHBOARD_PROJECTION_CACHE_BYTE_BUDGET;
+    const detailCacheEntries = options.detailCacheEntries ?? DEFAULT_DASHBOARD_DETAIL_CACHE_ENTRIES;
+    const detailCacheByteBudget = options.detailCacheByteBudget ??
+        DEFAULT_DASHBOARD_DETAIL_CACHE_BYTE_BUDGET;
+    const decodeQueueLimit = options.decodeQueueLimit ?? DEFAULT_DASHBOARD_DECODE_QUEUE_LIMIT;
+    const scheduler = new SerialSingleFlightScheduler(decodeQueueLimit);
+    const rootMutationSchedulers = new Map();
+    const liveRunLimit = options.liveRunLimit ?? MAX_DASHBOARD_LIVE_RUNS;
+    if (options.workerLockObserver !== undefined &&
+        options.observeWorkerLockObservation !== undefined) {
+        throw new TypeError("configure only one dashboard worker-lock observer seam");
+    }
+    const boundWorkerLockObserver = options.workerLockObserver ??
+        createDashboardWorkerLockObserver();
+    const legacyWorkerLockObserver = options.observeWorkerLockObservation;
+    const observeWorkerLock = legacyWorkerLockObserver === undefined
+        ? async (request) => await boundWorkerLockObserver.observe(request)
+        : async (request) => await legacyWorkerLockObserver(request.runsRoot, request.runId, request.runGeneration, request);
+    const roots = new Map();
+    const lazyContentReader = options.lazyContentReader ?? createDashboardLazyContentReader({
+        runReader,
+        stateRevisionFor: (runsRoot, admitted) => {
+            const rootKey = resolve(runsRoot);
+            const cache = roots.get(rootKey) ?? emptyRootCache();
+            const revision = revisionFor(cache, admitted);
+            roots.set(rootKey, cache);
+            return revision;
+        },
+    });
+    const artifactReferenceLimit = options.artifactReferenceLimit ??
+        DEFAULT_DASHBOARD_ARTIFACT_REFERENCE_LIMIT;
+    const artifactIndexByteBudget = options.artifactIndexByteBudget ??
+        DEFAULT_DASHBOARD_ARTIFACT_INDEX_BYTE_BUDGET;
+    const cursorSecret = randomBytes(32);
+    const artifactCursorSecret = randomBytes(32);
+    function serializeRootMutation(rootKey, operationKey, task) {
+        let rootScheduler = rootMutationSchedulers.get(rootKey);
+        if (rootScheduler === undefined) {
+            rootScheduler = new SerialSingleFlightScheduler(decodeQueueLimit);
+            rootMutationSchedulers.set(rootKey, rootScheduler);
+        }
+        return rootScheduler.run(operationKey, task);
+    }
+    async function readCandidateListingIdentity(runsRoot) {
+        try {
+            return candidateListingIdentity(await fileSystem.lstat(runsRoot));
+        }
+        catch (error) {
+            if (hasErrorCode(error, "ENOENT"))
+                return undefined;
+            throw error;
+        }
+    }
+    async function listStableCandidates(runsRoot) {
+        for (let attempt = 0; attempt < 2; attempt += 1) {
+            const before = await readCandidateListingIdentity(runsRoot);
+            const names = [];
+            for await (const candidate of fileSystem.listCandidates(runsRoot)) {
+                if (names.length >= candidateLimit) {
+                    throw new DashboardReadModelError("run_directory_limit_exceeded");
+                }
+                names.push(candidate.name);
+            }
+            const after = await readCandidateListingIdentity(runsRoot);
+            if (before !== undefined &&
+                after !== undefined &&
+                candidateListingIdentitiesEqual(before, after)) {
+                return names;
+            }
+        }
+        throw new DashboardReadModelError("dashboard_busy");
+    }
+    function revisionFor(cache, admitted) {
+        const current = cache.revisions.get(admitted.runId);
+        if (current !== undefined &&
+            current.fingerprint !== undefined &&
+            directoryIdentitiesEqual(current.directoryIdentity, admitted.directoryIdentity) &&
+            containedFileFingerprintsEqual(current.fingerprint, admitted.stateFingerprint))
+            return current.revision;
+        const revision = generateStateRevision();
+        cache.revisions.set(admitted.runId, {
+            fingerprint: admitted.stateFingerprint,
+            directoryIdentity: admitted.directoryIdentity,
+            revision,
+        });
+        return revision;
+    }
+    function unavailableRevisionFor(cache, runId, reason, directory, fingerprint) {
+        const current = cache.revisions.get(runId);
+        const fingerprintsEqual = current?.fingerprint === undefined && fingerprint === undefined ||
+            (current?.fingerprint !== undefined && fingerprint !== undefined &&
+                containedFileFingerprintsEqual(current.fingerprint, fingerprint));
+        if (current !== undefined &&
+            directoryIdentitiesEqual(current.directoryIdentity, directory) &&
+            current.unavailableReason === reason &&
+            fingerprintsEqual)
+            return current.revision;
+        const revision = generateStateRevision();
+        cache.revisions.set(runId, {
+            ...(fingerprint === undefined ? {} : { fingerprint }),
+            directoryIdentity: directory,
+            unavailableReason: reason,
+            revision,
+        });
+        return revision;
+    }
+    function insertDetail(cache, admitted, detail, enrichmentDependencies) {
+        const previous = cache.details.get(admitted.runId);
+        if (previous !== undefined) {
+            cache.details.delete(admitted.runId);
+            cache.detailBytes -= previous.sourceBytes;
+        }
+        if (admitted.sourceBytes > detailCacheByteBudget)
+            return;
+        cache.details.set(admitted.runId, {
+            fingerprint: admitted.stateFingerprint,
+            directoryIdentity: admitted.directoryIdentity,
+            rootIdentity: admitted.rootIdentity,
+            sourceBytes: admitted.sourceBytes,
+            state: admitted.state,
+            detail,
+            ...(enrichmentDependencies === undefined
+                ? {}
+                : { enrichmentDependencies: [...enrichmentDependencies] }),
+        });
+        cache.detailBytes += admitted.sourceBytes;
+        while (cache.details.size > detailCacheEntries || cache.detailBytes > detailCacheByteBudget) {
+            const oldestKey = cache.details.keys().next().value;
+            if (oldestKey === undefined)
+                break;
+            const oldest = cache.details.get(oldestKey);
+            cache.details.delete(oldestKey);
+            cache.detailBytes -= oldest.sourceBytes;
+        }
+    }
+    async function candidateIdentity(runsRoot, runId) {
+        try {
+            const [rootStats, runStats, stateStats] = await Promise.all([
+                fileSystem.lstat(runsRoot),
+                fileSystem.lstat(resolve(runsRoot, runId)),
+                fileSystem.lstat(resolve(runsRoot, runId, "state.json")),
+            ]);
+            if (!runStats.isDirectory() ||
+                !rootStats.isDirectory() ||
+                !stateStats.isFile() ||
+                runStats.nlink === 0n ||
+                stateStats.nlink === 0n)
+                return undefined;
+            return {
+                rootIdentity: directoryIdentity(rootStats),
+                directoryIdentity: directoryIdentity(runStats),
+                fingerprint: fileFingerprint(stateStats),
+            };
+        }
+        catch (error) {
+            if (hasErrorCode(error, "ENOENT"))
+                return undefined;
+            return undefined;
+        }
+    }
+    async function admit(runsRoot, runId, identity) {
+        const key = `${resolve(runsRoot)}\0${runId}\0${identity === undefined ? "unknown" : identityKey(identity)}`;
+        return await scheduler.run(key, async () => await runReader.read(runsRoot, runId));
+    }
+    async function withWorkerLockObservation(runsRoot, item, binding) {
+        if (item.availability === "unavailable")
+            return item;
+        if (item.status !== "pending" && item.status !== "running") {
+            return item.orphaned ? { ...item, orphaned: false } : item;
+        }
+        let workerLockObservation;
+        try {
+            workerLockObservation = await observeWorkerLock({
+                runsRoot,
+                runId: item.runId,
+                runGeneration: item.runGeneration,
+                ...binding,
+            });
+        }
+        catch {
+            workerLockObservation = "unknown";
+        }
+        if (legacyWorkerLockObserver !== undefined && workerLockObservation !== "unknown") {
+            const current = await candidateIdentity(runsRoot, item.runId);
+            if (current === undefined ||
+                !directoryIdentitiesEqual(current.rootIdentity, binding.rootIdentity) ||
+                !directoryIdentitiesEqual(current.directoryIdentity, binding.directoryIdentity) ||
+                !containedFileFingerprintsEqual(current.fingerprint, binding.stateFingerprint)) {
+                workerLockObservation = "unknown";
+            }
+        }
+        const orphaned = workerLockObservation === "orphaned";
+        return orphaned === item.orphaned &&
+            item.workerLockObservation === workerLockObservation
+            ? item
+            : { ...item, orphaned, workerLockObservation };
+    }
+    function entryFor(cache, admitted) {
+        const revision = revisionFor(cache, admitted);
+        const listItem = listProjection(admitted, revision);
+        const detail = detailProjection(admitted, listItem);
+        insertDetail(cache, admitted, detail);
+        const artifactSources = admitted.state.stages.flatMap((stage, stageOrdinal) => stage.calls.flatMap((call, callOrdinal) => {
+            const expectedPath = `artifacts/${stage.stageId}/${String(callOrdinal + 1).padStart(2, "0")}-${call.callId}.json`;
+            return call.artifactPath === expectedPath
+                ? [{
+                        runId: admitted.runId,
+                        runGeneration: admitted.runGeneration,
+                        stateRevision: revision,
+                        runBirthtimeNs: admitted.directoryIdentity.birthtimeNs,
+                        stageOrdinal,
+                        callOrdinal,
+                        stageId: stage.stageId,
+                        callId: call.callId,
+                    }]
+                : [];
+        }));
+        return {
+            runId: admitted.runId,
+            listItem,
+            sourceBytes: admitted.sourceBytes,
+            projectionBytes: Buffer.byteLength(JSON.stringify(listItem), "utf8"),
+            stateFingerprint: admitted.stateFingerprint,
+            directoryIdentity: admitted.directoryIdentity,
+            rootIdentity: admitted.rootIdentity,
+            liveSortKey: {
+                timeNs: timeOrFallback(admitted.state.startedAt, admitted.stateFingerprint),
+                runId: admitted.runId,
+            },
+            historySortKey: {
+                timeNs: timeOrFallback(admitted.state.completedAt, admitted.stateFingerprint),
+                runId: admitted.runId,
+            },
+            artifactSources,
+        };
+    }
+    function unavailableEntryFor(cache, result) {
+        const admission = result.admission;
+        if (admission === undefined)
+            return undefined;
+        const stateRevision = unavailableRevisionFor(cache, result.runId, result.reason, admission.directoryIdentity, admission.stateFingerprint);
+        const chronologyNs = admission.stateFingerprint?.mtimeNs;
+        const listItem = {
+            availability: "unavailable",
+            runId: result.runId,
+            runGeneration: admission.runGeneration,
+            stateRevision,
+            reason: result.reason,
+            ...(chronologyNs === undefined
+                ? {}
+                : { chronologyAt: new Date(Number(chronologyNs / 1000000n)).toISOString() }),
+        };
+        return {
+            runId: result.runId,
+            listItem,
+            sourceBytes: admission.sourceBytes,
+            projectionBytes: Buffer.byteLength(JSON.stringify(listItem), "utf8"),
+            ...(admission.stateFingerprint === undefined
+                ? {}
+                : { stateFingerprint: admission.stateFingerprint }),
+            directoryIdentity: admission.directoryIdentity,
+            rootIdentity: admission.rootIdentity,
+            liveSortKey: { timeNs: 0n, runId: result.runId },
+            historySortKey: {
+                timeNs: chronologyNs ?? 0n,
+                runId: result.runId,
+            },
+            artifactSources: [],
+        };
+    }
+    async function readEnrichedHealthyDetail(runsRoot, runId, runGeneration, cache) {
+        const enrichment = await lazyContentReader.readStructuredProjection({
+            runsRoot,
+            runId,
+            runGeneration,
+        });
+        if (enrichment.kind === "run_generation_changed")
+            return enrichment;
+        if (enrichment.kind === "run_state_changed")
+            return enrichment;
+        if (enrichment.kind === "unavailable")
+            return { kind: "missing" };
+        const admitted = enrichment.admission;
+        const revision = revisionFor(cache, admitted);
+        let detail = detailProjection(admitted, listProjection(admitted, revision));
+        if (detail.availability !== "available")
+            return { kind: "missing" };
+        if (enrichment.snapshot.availability === "available") {
+            const identities = new Map(enrichment.snapshot.projection.stages.flatMap((stage) => stage.calls.map((call) => [
+                `${stage.stageId}\0${call.callId}`,
+                { adapter: call.adapter, role: call.role },
+            ])));
+            detail = {
+                ...detail,
+                snapshotEnrichment: {
+                    availability: "available",
+                    stages: enrichment.snapshot.projection.stages.map((stage) => ({
+                        stageId: stage.stageId,
+                        ...(stage.label === undefined ? {} : { label: stage.label }),
+                        dependsOn: [...stage.dependsOn],
+                    })),
+                },
+                stages: detail.stages.map((stage) => ({
+                    ...stage,
+                    calls: stage.calls.map((call) => ({
+                        ...call,
+                        snapshotIdentity: identities.get(`${stage.stageId}\0${call.callId}`),
+                    })),
+                })),
+            };
+        }
+        else {
+            detail = {
+                ...detail,
+                snapshotEnrichment: enrichment.snapshot,
+            };
+        }
+        if (enrichment.genericResult !== undefined) {
+            detail = { ...detail, result: enrichment.genericResult };
+        }
+        if (enrichment.planReviewCard?.kind === "council-plan-review") {
+            detail = {
+                ...detail,
+                result: { availability: "available", kind: "plan_review" },
+                card: enrichment.planReviewCard,
+            };
+        }
+        else if (isPlanReviewRunState(admitted.state)) {
+            detail = {
+                ...detail,
+                result: { availability: "unavailable", reason: "invalid" },
+            };
+        }
+        insertDetail(cache, admitted, detail, enrichment.enrichmentDependencies);
+        return {
+            kind: "available",
+            detail: await withWorkerLockObservation(runsRoot, detail, admitted),
+            ...(cache.movedToHistory.has(runId) ? { notice: "moved_to_history" } : {}),
+        };
+    }
+    const scanner = {
+        async resolveCurrent(runsRoot, runId) {
+            try {
+                validateRunId(runId);
+            }
+            catch {
+                return { kind: "missing" };
+            }
+            const rootKey = resolve(runsRoot);
+            return await serializeRootMutation(rootKey, JSON.stringify(["resolve-current", runId]), async () => {
+                const identity = await candidateIdentity(runsRoot, runId);
+                const result = await admit(runsRoot, runId, identity);
+                if (result.kind === "missing")
+                    return { kind: "missing" };
+                if (result.kind === "unavailable") {
+                    return result.admission === undefined
+                        ? { kind: "unavailable" }
+                        : {
+                            kind: "resolved",
+                            runId,
+                            runGeneration: result.admission.runGeneration,
+                        };
+                }
+                return {
+                    kind: "resolved",
+                    runId,
+                    runGeneration: result.runGeneration,
+                };
+            });
+        },
+        async scan(runsRoot, query = {}) {
+            const limit = query.limit ?? 100;
+            if (!Number.isInteger(limit) || limit < 1 || limit > MAX_DASHBOARD_PAGE_SIZE) {
+                throw new TypeError("dashboard history limit must be an integer from 1 through 500");
+            }
+            const cursor = query.before === undefined
+                ? undefined
+                : requireHistoryCursor(cursorSecret, query.before);
+            const rootKey = resolve(runsRoot);
+            return await serializeRootMutation(rootKey, JSON.stringify(["scan", limit, query.before ?? null]), async () => {
+                const committed = roots.get(rootKey) ?? emptyRootCache();
+                const staged = {
+                    entries: new Map(),
+                    revisions: new Map(committed.revisions),
+                    details: new Map(committed.details),
+                    detailBytes: committed.detailBytes,
+                    movedToHistory: new Set(committed.movedToHistory),
+                    artifactIndex: committed.artifactIndex,
+                    artifactIndexFailed: committed.artifactIndexFailed,
+                };
+                let candidates;
+                try {
+                    candidates = await listStableCandidates(runsRoot);
+                }
+                catch (error) {
+                    if (hasErrorCode(error, "ENOENT")) {
+                        for (const runId of committed.entries.keys()) {
+                            runReader.forget(runsRoot, runId);
+                            boundWorkerLockObserver.forget(runsRoot, runId);
+                        }
+                        roots.delete(rootKey);
+                        return { live: [], history: [], serverNow: now().toISOString() };
+                    }
+                    throw error;
+                }
+                let admittedBytes = 0;
+                let projectionBytes = 0;
+                for (const runId of candidates) {
+                    try {
+                        validateRunId(runId);
+                    }
+                    catch {
+                        continue;
+                    }
+                    const identity = await candidateIdentity(runsRoot, runId);
+                    const cached = committed.entries.get(runId);
+                    let entry;
+                    if (identity !== undefined &&
+                        cached !== undefined &&
+                        cached.stateFingerprint !== undefined &&
+                        directoryIdentitiesEqual(identity.rootIdentity, cached.rootIdentity) &&
+                        directoryIdentitiesEqual(identity.directoryIdentity, cached.directoryIdentity) &&
+                        containedFileFingerprintsEqual(identity.fingerprint, cached.stateFingerprint)) {
+                        entry = cached;
+                    }
+                    else {
+                        const result = await admit(runsRoot, runId, identity);
+                        if (result.kind === "admitted")
+                            entry = entryFor(staged, result);
+                        else if (result.kind === "unavailable")
+                            entry = unavailableEntryFor(staged, result);
+                    }
+                    if (entry === undefined)
+                        continue;
+                    staged.entries.set(runId, entry);
+                    admittedBytes += entry.sourceBytes;
+                    projectionBytes += entry.projectionBytes;
+                    if (admittedBytes > scanByteBudget) {
+                        throw new DashboardReadModelError("scan_byte_budget_exceeded");
+                    }
+                    if (projectionBytes > projectionCacheByteBudget) {
+                        throw new DashboardReadModelError("projection_cache_budget_exceeded");
+                    }
+                }
+                const present = new Set(staged.entries.keys());
+                for (const runId of staged.revisions.keys()) {
+                    if (!present.has(runId))
+                        staged.revisions.delete(runId);
+                }
+                for (const [runId, detail] of staged.details) {
+                    if (present.has(runId))
+                        continue;
+                    staged.details.delete(runId);
+                    staged.detailBytes -= detail.sourceBytes;
+                }
+                for (const runId of staged.movedToHistory) {
+                    if (!present.has(runId))
+                        staged.movedToHistory.delete(runId);
+                }
+                for (const [runId, entry] of staged.entries) {
+                    const previous = committed.entries.get(runId);
+                    const isLive = entry.listItem.availability === "available" &&
+                        (entry.listItem.status === "pending" || entry.listItem.status === "running");
+                    const wasLive = previous?.listItem.availability === "available" &&
+                        (previous.listItem.status === "pending" || previous.listItem.status === "running");
+                    if (isLive || (previous !== undefined &&
+                        previous.listItem.runGeneration !== entry.listItem.runGeneration)) {
+                        staged.movedToHistory.delete(runId);
+                    }
+                    else if (wasLive) {
+                        staged.movedToHistory.add(runId);
+                    }
+                }
+                const liveEntries = [...staged.entries.values()]
+                    .filter((entry) => entry.listItem.availability === "available" &&
+                    (entry.listItem.status === "pending" || entry.listItem.status === "running") &&
+                    entry.stateFingerprint !== undefined)
+                    .sort((left, right) => compareAscending(left.liveSortKey, right.liveSortKey));
+                if (liveEntries.length > liveRunLimit) {
+                    throw new DashboardReadModelError("live_run_limit_exceeded");
+                }
+                const historyEntries = [...staged.entries.values()]
+                    .filter((entry) => entry.listItem.availability === "unavailable" ||
+                    (entry.listItem.status !== "pending" && entry.listItem.status !== "running"))
+                    .sort((left, right) => compareDescending(left.historySortKey, right.historySortKey));
+                const afterCursor = cursor === undefined
+                    ? historyEntries
+                    : historyEntries.filter((entry) => compareDescending(entry.historySortKey, cursor) > 0);
+                const page = afterCursor.slice(0, limit);
+                const observedLive = await mapWithFixedConcurrency(liveEntries, WORKER_LOCK_OBSERVATION_CONCURRENCY, async (entry) => await withWorkerLockObservation(runsRoot, entry.listItem, entry));
+                const response = {
+                    live: observedLive,
+                    history: page.map((entry) => entry.listItem),
+                    ...(afterCursor.length > page.length && page.length > 0
+                        ? { nextBefore: encodeCursor(cursorSecret, page.at(-1).historySortKey) }
+                        : {}),
+                    serverNow: now().toISOString(),
+                };
+                for (const runId of committed.entries.keys()) {
+                    if (!present.has(runId)) {
+                        runReader.forget(runsRoot, runId);
+                        boundWorkerLockObserver.forget(runsRoot, runId);
+                    }
+                }
+                const artifactIndex = buildDashboardArtifactReferenceIndex([...staged.entries.values()].flatMap((entry) => entry.artifactSources), {
+                    referenceLimit: artifactReferenceLimit,
+                    byteBudget: artifactIndexByteBudget,
+                    now,
+                    cursorSecret: artifactCursorSecret,
+                });
+                if (artifactIndex.kind === "available") {
+                    staged.artifactIndex = artifactIndex.index;
+                    staged.artifactIndexFailed = false;
+                }
+                else {
+                    staged.artifactIndex = undefined;
+                    staged.artifactIndexFailed = true;
+                }
+                roots.set(rootKey, staged);
+                return response;
+            });
+        },
+        async readDetail(runsRoot, runId, runGeneration) {
+            try {
+                validateRunId(runId);
+            }
+            catch {
+                return { kind: "missing" };
+            }
+            const rootKey = resolve(runsRoot);
+            return await serializeRootMutation(rootKey, JSON.stringify(["detail", runId, runGeneration]), async () => {
+                const cache = roots.get(rootKey) ?? emptyRootCache();
+                const identity = await candidateIdentity(runsRoot, runId);
+                const projection = cache.entries.get(runId);
+                if (identity !== undefined &&
+                    projection !== undefined &&
+                    projection.stateFingerprint !== undefined &&
+                    directoryIdentitiesEqual(identity.rootIdentity, projection.rootIdentity) &&
+                    directoryIdentitiesEqual(identity.directoryIdentity, projection.directoryIdentity) &&
+                    containedFileFingerprintsEqual(identity.fingerprint, projection.stateFingerprint)) {
+                    if (projection.listItem.runGeneration !== runGeneration) {
+                        return { kind: "run_generation_changed" };
+                    }
+                    if (projection.listItem.availability === "unavailable") {
+                        return {
+                            kind: "available",
+                            detail: projection.listItem,
+                            ...(cache.movedToHistory.has(runId) ? { notice: "moved_to_history" } : {}),
+                        };
+                    }
+                    const cachedDetail = cache.details.get(runId);
+                    if (cachedDetail !== undefined &&
+                        directoryIdentitiesEqual(cachedDetail.directoryIdentity, identity.directoryIdentity) &&
+                        containedFileFingerprintsEqual(cachedDetail.fingerprint, identity.fingerprint)) {
+                        cache.details.delete(runId);
+                        cache.details.set(runId, cachedDetail);
+                        if (cachedDetail.enrichmentDependencies !== undefined &&
+                            lazyContentReader.validateEnrichmentDependencies !== undefined) {
+                            const admitted = {
+                                kind: "admitted",
+                                runId,
+                                runGeneration,
+                                state: cachedDetail.state,
+                                sourceBytes: cachedDetail.sourceBytes,
+                                stateFingerprint: cachedDetail.fingerprint,
+                                directoryIdentity: cachedDetail.directoryIdentity,
+                                rootIdentity: cachedDetail.rootIdentity,
+                            };
+                            if (await lazyContentReader.validateEnrichmentDependencies({ runsRoot, runId, runGeneration }, admitted, cachedDetail.enrichmentDependencies)) {
+                                return {
+                                    kind: "available",
+                                    detail: await withWorkerLockObservation(runsRoot, cachedDetail.detail, {
+                                        rootIdentity: cachedDetail.rootIdentity,
+                                        directoryIdentity: cachedDetail.directoryIdentity,
+                                        stateFingerprint: cachedDetail.fingerprint,
+                                    }),
+                                    ...(cache.movedToHistory.has(runId)
+                                        ? { notice: "moved_to_history" }
+                                        : {}),
+                                };
+                            }
+                        }
+                        if (cachedDetail.state.workflowSnapshotPath === undefined &&
+                            !isPlanReviewRunState(cachedDetail.state) &&
+                            cachedDetail.state.status !== "succeeded") {
+                            return {
+                                kind: "available",
+                                detail: await withWorkerLockObservation(runsRoot, cachedDetail.detail, {
+                                    rootIdentity: cachedDetail.rootIdentity,
+                                    directoryIdentity: cachedDetail.directoryIdentity,
+                                    stateFingerprint: cachedDetail.fingerprint,
+                                }),
+                                ...(cache.movedToHistory.has(runId) ? { notice: "moved_to_history" } : {}),
+                            };
+                        }
+                        const enriched = await readEnrichedHealthyDetail(runsRoot, runId, runGeneration, cache);
+                        roots.set(rootKey, cache);
+                        return enriched;
+                    }
+                }
+                const result = await admit(runsRoot, runId, identity);
+                if (result.kind === "missing")
+                    return { kind: "missing" };
+                if (result.kind === "unavailable") {
+                    const entry = unavailableEntryFor(cache, result);
+                    if (entry === undefined)
+                        return { kind: "missing" };
+                    if (entry.listItem.availability !== "unavailable")
+                        return { kind: "missing" };
+                    if (projection?.listItem.availability === "available" &&
+                        (projection.listItem.status === "pending" || projection.listItem.status === "running") &&
+                        projection.listItem.runGeneration === entry.listItem.runGeneration) {
+                        cache.movedToHistory.add(runId);
+                    }
+                    else if (projection !== undefined &&
+                        projection.listItem.runGeneration !== entry.listItem.runGeneration) {
+                        cache.movedToHistory.delete(runId);
+                    }
+                    if (projection !== undefined &&
+                        (!directoryIdentitiesEqual(projection.directoryIdentity, entry.directoryIdentity) ||
+                            !directoryIdentitiesEqual(projection.rootIdentity, entry.rootIdentity) ||
+                            projection.stateFingerprint === undefined ||
+                            entry.stateFingerprint === undefined ||
+                            !containedFileFingerprintsEqual(projection.stateFingerprint, entry.stateFingerprint))) {
+                        cache.entries.delete(runId);
+                        const staleDetail = cache.details.get(runId);
+                        if (staleDetail !== undefined) {
+                            cache.details.delete(runId);
+                            cache.detailBytes -= staleDetail.sourceBytes;
+                        }
+                    }
+                    if (entry.listItem.runGeneration !== runGeneration)
+                        return { kind: "run_generation_changed" };
+                    roots.set(rootKey, cache);
+                    return {
+                        kind: "available",
+                        detail: entry.listItem,
+                        ...(cache.movedToHistory.has(runId) ? { notice: "moved_to_history" } : {}),
+                    };
+                }
+                if (projection !== undefined &&
+                    (!directoryIdentitiesEqual(projection.directoryIdentity, result.directoryIdentity) ||
+                        !directoryIdentitiesEqual(projection.rootIdentity, result.rootIdentity) ||
+                        projection.stateFingerprint === undefined ||
+                        !containedFileFingerprintsEqual(projection.stateFingerprint, result.stateFingerprint))) {
+                    if (projection.listItem.availability === "available" &&
+                        (projection.listItem.status === "pending" || projection.listItem.status === "running") &&
+                        projection.listItem.runGeneration === result.runGeneration &&
+                        result.state.status !== "pending" &&
+                        result.state.status !== "running") {
+                        cache.movedToHistory.add(runId);
+                    }
+                    else if (projection.listItem.runGeneration !== result.runGeneration) {
+                        cache.movedToHistory.delete(runId);
+                    }
+                    cache.entries.delete(runId);
+                }
+                if (result.runGeneration !== runGeneration) {
+                    roots.set(rootKey, cache);
+                    return { kind: "run_generation_changed" };
+                }
+                if (result.state.workflowSnapshotPath === undefined &&
+                    !isPlanReviewRunState(result.state) &&
+                    result.state.status !== "succeeded") {
+                    const revision = revisionFor(cache, result);
+                    const projected = detailProjection(result, listProjection(result, revision));
+                    insertDetail(cache, result, projected);
+                    roots.set(rootKey, cache);
+                    return {
+                        kind: "available",
+                        detail: await withWorkerLockObservation(runsRoot, projected, result),
+                        ...(cache.movedToHistory.has(runId) ? { notice: "moved_to_history" } : {}),
+                    };
+                }
+                const detail = await readEnrichedHealthyDetail(runsRoot, runId, runGeneration, cache);
+                roots.set(rootKey, cache);
+                return detail;
+            });
+        },
+        async readCallContent(request) {
+            return await serializeRootMutation(resolve(request.runsRoot), JSON.stringify([
+                "call",
+                request.runId,
+                request.runGeneration,
+                request.stageId,
+                request.callId,
+                request.kind,
+            ]), async () => await lazyContentReader.readCallContent(request));
+        },
+        async readResult(request) {
+            return await serializeRootMutation(resolve(request.runsRoot), JSON.stringify(["result", request.runId, request.runGeneration]), async () => await lazyContentReader.readResult(request));
+        },
+        async listArtifacts(runsRoot, query = {}) {
+            if (query.before !== undefined) {
+                assertValidDashboardArtifactCursor(artifactCursorSecret, query.before);
+            }
+            await scanner.scan(runsRoot);
+            const cache = roots.get(resolve(runsRoot));
+            if (cache === undefined) {
+                return { artifacts: [], serverNow: now().toISOString() };
+            }
+            if (cache.artifactIndexFailed) {
+                throw new DashboardReadModelError("artifact_catalog_limit_exceeded");
+            }
+            return cache.artifactIndex?.list(query) ?? {
+                artifacts: [],
+                serverNow: now().toISOString(),
+            };
+        },
+    };
+    return scanner;
+}
+//# sourceMappingURL=scanner.js.map