clinkx 0.2.3 → 1.0.0

package/clinkx-workflows/dist/dashboard/context-run-reader.js

@@ -0,0 +1,1178 @@
+/**
+ * Bounded dashboard reader for the standalone / refine Context Run journal.
+ *
+ * This module enumerates and directly resolves stable row identities without
+ * exposing raw lifecycle state or manifest content.
+ *
+ * Two sources feed one projected row type:
+ *   1. `.context-runs/<contextRunId>/state.json` — authoritative live/terminal
+ *      H0 lifecycle snapshots written by the producer journal. Validated back
+ *      through the frozen schema; malformed rows are dropped.
+ *   2. Historical artifact run directories carrying `manifest.json` — a
+ *      terminal lifecycle row is SYNTHESIZED from the manifest for the exact
+ *      legacy 7-key and current 8-key artifact shapes; a 9-key (or larger)
+ *      manifest is surfaced as `compatibility: "legacy_unsupported"` with no
+ *      fabricated detail.
+ *
+ * Safety invariants:
+ *   - Every read goes through {@link readContainedRelativeFile} (no-follow,
+ *     containment-checked, size-capped). Symlinked entries and traversal names
+ *     are skipped or rejected.
+ *   - Workflow-owned records (`wfpre*` / `wfctx*`) are excluded from both
+ *     sources.
+ *   - Only safe scalar/enum/numeric fields are projected. Tasks, raw context,
+ *     full manifests, provider output, raw error strings, and arbitrary JSON are
+ *     NEVER read into a row. The single, deliberate path carve-out is the
+ *     top-level project-folder root: `roots[].path` is projected verbatim into
+ *     `ContextRunRow.projectFolders` (historical_manifest rows only) so the
+ *     detail page can show the folder the run was created for. Selected-context
+ *     file paths, task text, and all other manifest content stay private.
+ *
+ * Carve-out — bounded artifact-body reads (`readArtifact`): the invariant above
+ * applies to projected ROWS, which stay scalar-only. `readArtifact` is a
+ * separate, opt-in side channel that serves a single artifact file body
+ * (e.g. `bundle.md`) for an already-resolved run identity. It is allowlisted to
+ * the fixed artifact-key set, size-capped at the manifest ceiling, generation-
+ * pinned, and goes through the same no-follow containment read as rows. It does
+ * not enrich rows and is reached only via the dedicated HTTP route, never inline
+ * in list/detail projection.
+ */
+import { constants as fsConstants, } from "node:fs";
+import { lstat as fsLstat, open as fsOpen, readdir as fsReaddir, realpath as fsRealpath, } from "node:fs/promises";
+import { isAbsolute, join, relative, resolve, sep } from "node:path";
+import { CONTEXT_BUILDER_LIFECYCLE_DIRECTORY, CONTEXT_BUILDER_LIFECYCLE_STATE_FILENAME, isContextBuilderOperationId, parseContextBuilderLifecycleStateV1, } from "../context-builder-lifecycle-contract.js";
+import { containedFileFingerprintsEqual, ContainedFileChangedError, ContainedFilePolicyError, ContainedFileTooLargeError, readContainedRelativeFile, resolveOpenedDescriptorPath, } from "../contained-file.js";
+import { MAX_DASHBOARD_ROOTS } from "./contracts.js";
+import { deriveContextRunGeneration } from "./generation.js";
+import { classifyContextRunLiveness, isContextRunLivePin, } from "./context-run-liveness.js";
+const MANIFEST_FILENAME = "manifest.json";
+const CONTEXT_RUN_CATALOG_DIRECTORY = ".catalog";
+const CONTEXT_RUN_CATALOG_LEGACY_CUTOFF_FILENAME = ".legacy-before";
+const CONTEXT_RUN_CATALOG_MARKER_PATTERN = /^(\d{13})-([oa])-(.+)$/;
+const CONTEXT_BUILDER_ARTIFACT_ID_PATTERN = /^[A-Za-z0-9_-]{1,64}$/;
+const MAX_CONTEXT_RUN_PROJECTION_CACHE_ENTRIES = 1_000;
+/** Exact frozen legacy artifact key set (7 keys). */
+const LEGACY_ARTIFACT_KEYS = [
+    "manifest_json",
+    "bundle_md",
+    "tree_json",
+    "search_jsonl",
+    "slices_jsonl",
+    "codemap_jsonl",
+    "summary_json",
+];
+/** Exact current artifact key set (8 keys: legacy + selected_context). */
+const CURRENT_ARTIFACT_KEYS = [
+    "manifest_json",
+    "bundle_md",
+    "selected_context_jsonl",
+    "tree_json",
+    "search_jsonl",
+    "slices_jsonl",
+    "codemap_jsonl",
+    "summary_json",
+];
+/**
+ * Artifact key → on-disk filename. Duplicated from the producer
+ * (`src/context-builder/storage.ts`) by convention — the dashboard package does
+ * not import the producer. A parity test pins this copy to the producer export.
+ * `manifest_json` lives at `<runDir>/manifest.json`; every other key lives at
+ * `<runDir>/artifacts/<filename>` (see producer `resolveContextBuilderRunPaths`).
+ */
+export const CONTEXT_RUN_ARTIFACT_FILE_NAMES = Object.freeze({
+    manifest_json: "manifest.json",
+    bundle_md: "bundle.md",
+    selected_context_jsonl: "selected-context.jsonl",
+    tree_json: "tree.json",
+    search_jsonl: "search.jsonl",
+    slices_jsonl: "slices.jsonl",
+    codemap_jsonl: "codemap.jsonl",
+    summary_json: "summary.json",
+});
+export const CONTEXT_RUN_ARTIFACT_KEYS = Object.freeze(Object.keys(CONTEXT_RUN_ARTIFACT_FILE_NAMES));
+export const DEFAULT_CONTEXT_RUN_READER_MAX_ROWS = 500;
+export const DEFAULT_CONTEXT_RUN_READER_MAX_DIR_ENTRIES = 5_000;
+export const DEFAULT_CONTEXT_RUN_READER_MAX_STATE_BYTES = 64 * 1_024;
+export const DEFAULT_CONTEXT_RUN_READER_MAX_MANIFEST_BYTES = 4 * 1_024 * 1_024;
+/**
+ * Per-artifact-body cap for {@link readArtifact}. Sized above the producer's
+ * `max_total_bytes` ceiling (5_000_000, src/context-builder/schema.ts) so a
+ * producer-legal `bundle.md` / `selected-context.jsonl` is served rather than
+ * 413'd, while still bounding the body endpoint. Distinct from the manifest
+ * cap so each can move independently.
+ */
+export const DEFAULT_CONTEXT_RUN_READER_MAX_ARTIFACT_BYTES = 6 * 1_024 * 1_024;
+function attachContextRunLiveness(row, nowMs) {
+    return Object.freeze({
+        ...row,
+        ...classifyContextRunLiveness({
+            ...(row.lifecycle == null
+                ? {}
+                : {
+                    status: row.lifecycle.status,
+                    phase: row.lifecycle.phase,
+                    updatedAt: row.lifecycle.updatedAt,
+                }),
+            nowMs,
+        }),
+    });
+}
+function overlayContextRunRows(rows, nowMs) {
+    return rows.map((row) => attachContextRunLiveness(row, nowMs));
+}
+class ContextRunGenerationRaceError extends Error {
+}
+export class ContextRunSourceUnavailableError extends Error {
+    constructor() {
+        super("context runs source unavailable");
+        this.name = "ContextRunSourceUnavailableError";
+    }
+}
+/** Workflow-owned records are not Context Runs and must never be surfaced. */
+function isWorkflowOwnedId(id) {
+    return id.startsWith("wfctx") || id.startsWith("wfpre");
+}
+const defaultContextRunAuthorityFileSystem = {
+    open: fsOpen,
+    realpath: fsRealpath,
+};
+function resolveAuthority(options) {
+    return {
+        fileSystem: options.fileSystem ?? defaultContextRunAuthorityFileSystem,
+        descriptorPathVerifier: options.descriptorPathVerifier ??
+            resolveOpenedDescriptorPath,
+        readContainedFile: options.readContainedFile ?? readContainedRelativeFile,
+        beforeCommitVerification: options.beforeCommitVerification,
+        historicalProjectionCache: new Map(),
+        now: options.now ?? (() => new Date()),
+    };
+}
+export function createContextRunReader(options = {}) {
+    const authority = resolveAuthority(options);
+    return {
+        list: async (readerOptions) => await readContextRunsWithAuthority(readerOptions, authority),
+        readDetail: async (readerOptions, id, contextGeneration) => await readContextRunWithAuthority(readerOptions, id, contextGeneration, authority),
+        readArtifact: async (readerOptions, id, artifactKey, contextGeneration) => await readArtifactWithAuthority(readerOptions, id, artifactKey, contextGeneration, authority),
+    };
+}
+const defaultContextRunReader = createContextRunReader();
+export async function readContextRuns(options) {
+    return await defaultContextRunReader.list(options);
+}
+export async function readContextRunArtifact(options, id, artifactKey, contextGeneration) {
+    return await defaultContextRunReader.readArtifact(options, id, artifactKey, contextGeneration);
+}
+async function readContextRunsWithAuthority(options, authority) {
+    const resolved = resolveOptions(options);
+    if (await admitRunsRoot(resolved.runsDir) === "missing") {
+        return { rows: [], truncated: false };
+    }
+    const catalogBudget = {
+        entries: 0,
+        maxEntries: resolved.maxDirEntries,
+        truncated: false,
+    };
+    const legacyBudget = {
+        entries: 0,
+        maxEntries: resolved.maxDirEntries,
+        truncated: false,
+    };
+    // Resolved once and shared by both row readers: it is a per-list constant, and
+    // re-deriving it per row would reintroduce exactly the syscall the projection
+    // cache exists to avoid.
+    const rootIdentity = await resolveListRootIdentity(resolved, authority);
+    const catalog = await readCatalogRows(resolved, catalogBudget, authority, rootIdentity);
+    if (catalog.rows.length > resolved.maxRows) {
+        // Even on the catalog fast path, suppress historical rows linked to a
+        // journal row by artifactRunId before slicing — otherwise a busy catalog
+        // (operation marker + artifact marker per execution) surfaces duplicates.
+        const suppressed = overlayContextRunRows(suppressLinkedHistoricalRows(catalog.rows), authority.now().getTime());
+        suppressed.sort((left, right) => compareRowsNewestFirst(left, right, catalog.sortTimes));
+        return {
+            rows: suppressed.slice(0, resolved.maxRows),
+            truncated: true,
+        };
+    }
+    const journalRows = filterLegacyFallbackRows(await readJournalRows(resolved, legacyBudget, authority), catalog);
+    const historicalRows = filterLegacyFallbackRows(await readHistoricalRows(resolved, legacyBudget, authority, rootIdentity), catalog);
+    // Journal (ctxop_*) and historical (artifact run) IDs never collide by
+    // identity domain, so the first pass below keeps one row per (source, id).
+    const rowsByIdentity = new Map();
+    for (const row of [...catalog.rows, ...journalRows, ...historicalRows]) {
+        const identity = contextRunRowIdentity(row);
+        if (!rowsByIdentity.has(identity))
+            rowsByIdentity.set(identity, row);
+    }
+    // Second pass: one execution = one row. A journal operation and the artifact
+    // set it produced are the same context run, linked by the journal row's
+    // lifecycle.artifactRunId. The journal row is strictly more informative
+    // (real curator/finalizer status, accurate timestamps), so suppress the
+    // duplicate historical_manifest row — whether it came from the catalog
+    // markers or the top-level filesystem scan. `readDetail` still resolves the
+    // suppressed historical id directly (it is "out of the list, not gone").
+    // Note: this is a deliberate list-level suppression, distinct from the
+    // existing `truncated` cap; `truncated` is not flipped here.
+    const rows = overlayContextRunRows(suppressLinkedHistoricalRows([...rowsByIdentity.values()]), authority.now().getTime());
+    rows.sort((left, right) => compareRowsNewestFirst(left, right, catalog.sortTimes));
+    const overCap = rows.length > resolved.maxRows;
+    return {
+        rows: overCap ? rows.slice(0, resolved.maxRows) : rows,
+        truncated: catalog.truncated || catalogBudget.truncated ||
+            legacyBudget.truncated || overCap,
+    };
+}
+/**
+ * Drop `historical_manifest` rows that duplicate a journal row by
+ * `lifecycle.artifactRunId`. One execution = one row; the journal row wins.
+ * Operates over any union of sources (catalog markers, journal state, the
+ * filesystem scan) so the suppression is consistent regardless of which
+ * sources produced the input rows.
+ */
+function suppressLinkedHistoricalRows(rows) {
+    const linkedArtifactIds = new Set();
+    for (const row of rows) {
+        if (row.source === "journal" && row.lifecycle !== null) {
+            const artifactRunId = row.lifecycle.artifactRunId;
+            if (artifactRunId !== null)
+                linkedArtifactIds.add(artifactRunId);
+        }
+    }
+    if (linkedArtifactIds.size === 0)
+        return [...rows];
+    return rows.filter((row) => !(row.source === "historical_manifest" && linkedArtifactIds.has(row.id)));
+}
+function filterLegacyFallbackRows(rows, catalog) {
+    if (!catalog.hasValidMarkers || catalog.legacyCutoffMs === undefined) {
+        return rows;
+    }
+    return rows.filter((row) => {
+        const createdAt = row.lifecycle?.createdAt;
+        if (createdAt === null || createdAt === undefined)
+            return true;
+        const createdAtMs = Date.parse(createdAt);
+        return Number.isFinite(createdAtMs) && createdAtMs < catalog.legacyCutoffMs;
+    });
+}
+/** Resolve one stable row identity directly, independent of list limits/order. */
+export async function readContextRun(options, id, contextGeneration) {
+    return await defaultContextRunReader.readDetail(options, id, contextGeneration);
+}
+async function readContextRunWithAuthority(options, id, contextGeneration, authority) {
+    const resolved = resolveOptions(options);
+    if (await admitRunsRoot(resolved.runsDir) === "missing")
+        return { kind: "missing" };
+    if (isContextBuilderOperationId(id)) {
+        const state = await readJournalState(id, resolved, authority, contextGeneration);
+        if (state.kind !== "available") {
+            // state.json is sized at maxStateBytes; a too-large journal state is
+            // treated as malformed/missing rather than surfaced as a body result.
+            return state.kind === "content_too_large" ? { kind: "missing" } : state;
+        }
+        if (state.value.operation_kind === "workflow_preflight") {
+            return { kind: "missing" };
+        }
+        if (contextGeneration !== undefined &&
+            contextGeneration !== state.contextGeneration)
+            return { kind: "context_generation_changed" };
+        return { kind: "available", row: attachContextRunLiveness({
+                id,
+                contextGeneration: state.contextGeneration,
+                source: "journal",
+                compatibility: "current",
+                operationKind: state.value.operation_kind,
+                lifecycle: projectContextRunLifecycleState(state.value),
+                // Journal lifecycle state carries no roots (see ContextRunRow docs).
+                projectFolders: [],
+            }, authority.now().getTime()) };
+    }
+    if (!isHistoricalArtifactId(id) || isWorkflowOwnedId(id))
+        return { kind: "missing" };
+    const manifest = await readHistoricalManifest(id, resolved, authority, contextGeneration);
+    if (manifest.kind !== "available") {
+        // A manifest over maxManifestBytes cannot be classified; treat as missing
+        // for detail projection (the body endpoint surfaces it as content_too_large).
+        return manifest.kind === "content_too_large" ? { kind: "missing" } : manifest;
+    }
+    if (contextGeneration !== undefined &&
+        contextGeneration !== manifest.contextGeneration)
+        return { kind: "context_generation_changed" };
+    const row = synthesizeHistoricalRow(id, manifest.value, manifest.contextGeneration);
+    return row === undefined
+        ? { kind: "missing" }
+        : {
+            kind: "available",
+            row: attachContextRunLiveness(row, authority.now().getTime()),
+        };
+}
+/**
+ * Read a single artifact body for an already-resolved run identity. This is the
+ * bounded side channel documented in the module docstring: allowlisted key,
+ * size-capped, generation-pinned, no-follow containment. The artifact directory
+ * is resolved from the run row — for a journal row this is the linked
+ * `artifactRunId` (NOT the operation id), so a journal-state swap mid-read can
+ * serve a stale artifact; the caller (HTTP route) re-confirms via readDetail to
+ * close that TOCTOU.
+ */
+async function readArtifactWithAuthority(options, id, artifactKey, contextGeneration, authority) {
+    const resolved = resolveOptions(options);
+    if (await admitRunsRoot(resolved.runsDir) === "missing") {
+        return { kind: "missing" };
+    }
+    const detail = await readContextRunWithAuthority(resolved, id, contextGeneration, authority);
+    if (detail.kind === "context_generation_changed") {
+        return { kind: "context_generation_changed" };
+    }
+    if (detail.kind === "missing")
+        return { kind: "missing" };
+    if (detail.kind === "unavailable") {
+        return { kind: "unavailable", reason: "context_generation_race" };
+    }
+    const row = detail.row;
+    if (row.lifecycle === null)
+        return { kind: "missing" };
+    // The artifact set lives under <runsDir>/<artifactRunId>/, keyed by the
+    // journal state's artifact_run_id for journal rows, or the row's own id for
+    // historical rows. manifest.json sits at the run dir root; the other seven
+    // artifacts sit under <runDir>/artifacts/<filename> (producer
+    // resolveContextBuilderRunPaths).
+    const artifactRunId = row.source === "journal" ? row.lifecycle.artifactRunId : row.id;
+    if (artifactRunId === null)
+        return { kind: "missing" };
+    const filename = CONTEXT_RUN_ARTIFACT_FILE_NAMES[artifactKey];
+    const fileRelativePath = artifactKey === "manifest_json"
+        ? join(artifactRunId, filename)
+        : join(artifactRunId, "artifacts", filename);
+    const result = await readContextArtifact(resolved, authority, {
+        id: artifactRunId,
+        // The artifact set is always a top-level historical-style directory,
+        // even when reached via a journal row. Source is historical_manifest so
+        // the generation is derived from the artifact directory's identity
+        // (which is what we are pinning and re-verifying).
+        source: "historical_manifest",
+        directoryRelativePath: artifactRunId,
+        fileRelativePath,
+        maxBytes: resolved.maxArtifactBytes,
+        pathLabel: filename,
+    }, undefined);
+    switch (result.kind) {
+        case "available":
+            return {
+                kind: "available",
+                content: result.value,
+                artifactRunId,
+                contextGeneration: result.contextGeneration,
+            };
+        case "missing":
+            return { kind: "missing" };
+        case "context_generation_changed":
+            return { kind: "context_generation_changed" };
+        case "content_too_large":
+            return { kind: "content_too_large" };
+        case "unavailable":
+            return { kind: "unavailable", reason: "context_generation_race" };
+    }
+}
+async function admitRunsRoot(runsDir) {
+    try {
+        const root = await fsLstat(runsDir);
+        if (root.isSymbolicLink() || !root.isDirectory()) {
+            throw new ContextRunSourceUnavailableError();
+        }
+        if (process.platform !== "win32" && (root.mode & 0o077) !== 0) {
+            throw new ContextRunSourceUnavailableError();
+        }
+        const uid = process.getuid?.();
+        if (uid !== undefined && root.uid !== uid) {
+            throw new ContextRunSourceUnavailableError();
+        }
+        return "available";
+    }
+    catch (error) {
+        if (isFileSystemError(error, "ENOENT"))
+            return "missing";
+        if (error instanceof ContextRunSourceUnavailableError)
+            throw error;
+        throw new ContextRunSourceUnavailableError();
+    }
+}
+function isFileSystemError(error, code) {
+    return typeof error === "object" && error !== null &&
+        "code" in error && error.code === code;
+}
+function directoryIdentity(stats) {
+    return { dev: stats.dev, ino: stats.ino, birthtimeNs: stats.birthtimeNs };
+}
+function directoryIdentitiesEqual(left, right) {
+    return left.dev === right.dev && left.ino === right.ino &&
+        left.birthtimeNs === right.birthtimeNs;
+}
+async function inspectOpenedDirectory(handle) {
+    const stats = await handle.stat({ bigint: true });
+    if (!stats.isDirectory() || stats.nlink === 0n) {
+        throw new ContextRunGenerationRaceError();
+    }
+    return directoryIdentity(stats);
+}
+function isProperDescendant(root, candidate) {
+    const fromRoot = relative(root, candidate);
+    return fromRoot !== "" && fromRoot !== ".." &&
+        !fromRoot.startsWith(`..${sep}`) && !isAbsolute(fromRoot);
+}
+function generationFor(source, id, root, directory) {
+    return deriveContextRunGeneration(source, id, root, directory);
+}
+async function verifyCurrentDirectoryIdentity(authority, path, flags, expected) {
+    let handle;
+    try {
+        handle = await authority.fileSystem.open(path, flags);
+    }
+    catch {
+        throw new ContextRunGenerationRaceError();
+    }
+    try {
+        if (!directoryIdentitiesEqual(await inspectOpenedDirectory(handle), expected)) {
+            throw new ContextRunGenerationRaceError();
+        }
+    }
+    finally {
+        await handle.close();
+    }
+}
+async function readContextArtifact(options, authority, identity, expectedGeneration) {
+    const directoryFlags = fsConstants.O_RDONLY |
+        (fsConstants.O_DIRECTORY ?? 0) |
+        (fsConstants.O_NOFOLLOW ?? 0);
+    for (const attempt of [1, 2]) {
+        let rootHandle;
+        let directoryHandle;
+        try {
+            const canonicalRoot = await authority.fileSystem.realpath(options.runsDir);
+            rootHandle = await authority.fileSystem.open(canonicalRoot, directoryFlags);
+            const rootIdentity = await inspectOpenedDirectory(rootHandle);
+            const directoryPath = resolve(canonicalRoot, identity.directoryRelativePath);
+            if (!isProperDescendant(canonicalRoot, directoryPath))
+                return { kind: "missing" };
+            directoryHandle = await authority.fileSystem.open(directoryPath, directoryFlags);
+            const directoryIdentity = await inspectOpenedDirectory(directoryHandle);
+            const descriptorPath = await authority
+                .descriptorPathVerifier(directoryHandle.fd, directoryPath)
+                .catch(() => undefined);
+            if (descriptorPath !== directoryPath) {
+                throw new ContextRunGenerationRaceError();
+            }
+            const contextGeneration = generationFor(identity.source, identity.id, rootIdentity, directoryIdentity);
+            if (expectedGeneration !== undefined &&
+                expectedGeneration !== contextGeneration)
+                return { kind: "context_generation_changed" };
+            const read = await authority.readContainedFile(canonicalRoot, identity.fileRelativePath, {
+                wantContent: true,
+                requireRegular: true,
+                requireExactRequestedPath: true,
+                descriptorPathVerifier: authority.descriptorPathVerifier,
+                maxBytes: identity.maxBytes,
+                containerLabel: identity.source === "journal"
+                    ? "context run journal"
+                    : "context builder runs directory",
+                pathLabel: identity.pathLabel ??
+                    (identity.source === "journal" ? "state.json" : "manifest.json"),
+                beforeClose: async () => {
+                    await authority.beforeCommitVerification?.({
+                        id: identity.id,
+                        source: identity.source,
+                    });
+                    await verifyCurrentDirectoryIdentity(authority, directoryPath, directoryFlags, directoryIdentity);
+                    await verifyCurrentDirectoryIdentity(authority, canonicalRoot, directoryFlags, rootIdentity);
+                },
+            });
+            if (read.content === undefined)
+                return { kind: "missing" };
+            await verifyCurrentDirectoryIdentity(authority, directoryPath, directoryFlags, directoryIdentity);
+            await verifyCurrentDirectoryIdentity(authority, canonicalRoot, directoryFlags, rootIdentity);
+            return {
+                kind: "available",
+                value: read.content,
+                contextGeneration,
+                fingerprint: read.fingerprint,
+                rootIdentity,
+                directoryIdentity,
+            };
+        }
+        catch (error) {
+            if (error instanceof ContextRunGenerationRaceError ||
+                error instanceof ContainedFileChangedError) {
+                if (attempt === 2) {
+                    return { kind: "unavailable", reason: "context_generation_race" };
+                }
+                continue;
+            }
+            if (error instanceof ContainedFileTooLargeError) {
+                return { kind: "content_too_large" };
+            }
+            if (isFileSystemError(error, "ENOENT") ||
+                isFileSystemError(error, "ENOTDIR") ||
+                isFileSystemError(error, "ELOOP") ||
+                error instanceof ContainedFilePolicyError)
+                return { kind: "missing" };
+            return { kind: "unavailable", reason: "context_generation_race" };
+        }
+        finally {
+            await directoryHandle?.close().catch(() => undefined);
+            await rootHandle?.close().catch(() => undefined);
+        }
+    }
+    return { kind: "unavailable", reason: "context_generation_race" };
+}
+async function readCatalogRows(options, budget, authority, rootIdentity) {
+    const journalDir = join(options.runsDir, CONTEXT_BUILDER_LIFECYCLE_DIRECTORY);
+    const catalogDir = join(journalDir, CONTEXT_RUN_CATALOG_DIRECTORY);
+    let entries;
+    try {
+        const catalog = await fsLstat(catalogDir);
+        if (catalog.isSymbolicLink() || !catalog.isDirectory()) {
+            return {
+                rows: [],
+                sortTimes: new Map(),
+                truncated: false,
+                hasValidMarkers: false,
+                legacyCutoffMs: undefined,
+            };
+        }
+        entries = await fsReaddir(catalogDir, { withFileTypes: true });
+    }
+    catch (error) {
+        if (isFileSystemError(error, "ENOENT")) {
+            return {
+                rows: [],
+                sortTimes: new Map(),
+                truncated: false,
+                hasValidMarkers: false,
+                legacyCutoffMs: undefined,
+            };
+        }
+        return {
+            rows: [],
+            sortTimes: new Map(),
+            truncated: false,
+            hasValidMarkers: false,
+            legacyCutoffMs: undefined,
+        };
+    }
+    const cutoffRead = await readContainedRelativeFile(journalDir, CONTEXT_RUN_CATALOG_LEGACY_CUTOFF_FILENAME, {
+        wantContent: true,
+        requireRegular: true,
+        requireExactRequestedPath: true,
+        maxBytes: 32,
+        containerLabel: "context run journal",
+        pathLabel: "legacy cutoff",
+    }).catch(() => undefined);
+    const cutoffValue = cutoffRead?.content?.trim();
+    const parsedCutoff = cutoffValue === undefined ? Number.NaN : Number(cutoffValue);
+    const legacyCutoffMs = Number.isSafeInteger(parsedCutoff) && parsedCutoff >= 0
+        ? parsedCutoff
+        : undefined;
+    const rows = [];
+    const sortTimes = new Map();
+    let truncated = false;
+    let hasValidMarkers = false;
+    const ordered = entries
+        .filter((entry) => entry.isFile())
+        .map((entry) => entry.name)
+        .sort()
+        .reverse();
+    for (const name of ordered) {
+        if (budget.entries >= budget.maxEntries) {
+            budget.truncated = true;
+            truncated = true;
+            break;
+        }
+        budget.entries += 1;
+        const marker = parseCatalogMarkerName(name);
+        if (marker === undefined)
+            continue;
+        hasValidMarkers = true;
+        let row;
+        if (marker.kind === "operation") {
+            const state = await readJournalState(marker.id, options, authority);
+            if (state.kind === "available" &&
+                state.value.operation_kind !== "workflow_preflight") {
+                row = {
+                    id: marker.id,
+                    contextGeneration: state.contextGeneration,
+                    source: "journal",
+                    compatibility: "current",
+                    operationKind: state.value.operation_kind,
+                    lifecycle: projectContextRunLifecycleState(state.value),
+                    projectFolders: [],
+                };
+            }
+        }
+        else {
+            const cacheKey = historicalProjectionCacheKey(options.runsDir, marker.id);
+            // Captured BEFORE the reuse check, which evicts on any mismatch: the
+            // `missing` fallback below must keep serving exactly the row it served
+            // before this cache existed.
+            const cached = authority.historicalProjectionCache.get(cacheKey)?.row;
+            const reused = await reuseHistoricalProjection(options, authority, marker.id, rootIdentity);
+            if (reused.kind === "hit") {
+                row = reused.row;
+            }
+            else {
+                const manifest = await readHistoricalManifest(marker.id, options, authority);
+                if (manifest.kind === "available") {
+                    const projected = synthesizeHistoricalRow(marker.id, manifest.value, manifest.contextGeneration);
+                    if (projected !== undefined) {
+                        row = cacheHistoricalProjection(authority, cacheKey, projected, {
+                            manifestFingerprint: manifest.fingerprint,
+                            rootIdentity: manifest.rootIdentity,
+                            directoryIdentity: manifest.directoryIdentity,
+                            contextGeneration: manifest.contextGeneration,
+                        });
+                    }
+                }
+                else if (manifest.kind === "missing" && reused.kind === "miss") {
+                    // Unchanged fallback: the manifest is GONE, so there is nothing left
+                    // to fingerprint. Serve the last projection unrevalidated rather than
+                    // dropping a row the user can still open.
+                    //
+                    // Gated on `miss`. After `stale_generation` the run directory itself
+                    // was recreated, so `cached.contextGeneration` is provably wrong and
+                    // the identity-fenced detail route would 409 on it. Drop the row
+                    // instead of advertising an unopenable generation.
+                    row = cached;
+                }
+            }
+        }
+        if (row === undefined)
+            continue;
+        rows.push(row);
+        sortTimes.set(contextRunRowIdentity(row), marker.createdAtMs);
+        if (rows.length > options.maxRows) {
+            truncated = true;
+            break;
+        }
+    }
+    return { rows, sortTimes, truncated, hasValidMarkers, legacyCutoffMs };
+}
+function parseCatalogMarkerName(name) {
+    const match = CONTEXT_RUN_CATALOG_MARKER_PATTERN.exec(name);
+    if (match === null)
+        return undefined;
+    const createdAtMs = Number(match[1]);
+    const kind = match[2] === "o" ? "operation" : "artifact";
+    const id = match[3];
+    if (!Number.isSafeInteger(createdAtMs) || createdAtMs < 0)
+        return undefined;
+    if (kind === "operation") {
+        if (!isContextBuilderOperationId(id) || isWorkflowOwnedId(id))
+            return undefined;
+    }
+    else if (!isHistoricalArtifactId(id) || isWorkflowOwnedId(id)) {
+        return undefined;
+    }
+    return { createdAtMs, kind, id };
+}
+function contextRunRowIdentity(row) {
+    return `${row.source}:${row.id}`;
+}
+function historicalProjectionCacheKey(runsDir, id) {
+    return `${runsDir}\0${id}`;
+}
+function fingerprintFromStats(stats) {
+    return {
+        dev: stats.dev,
+        ino: stats.ino,
+        mtimeNs: stats.mtimeNs,
+        ctimeNs: stats.ctimeNs,
+        size: stats.size,
+        nlink: stats.nlink,
+    };
+}
+/**
+ * Resolve the runs-root identity ONCE per `list()`.
+ *
+ * `undefined` is a total cache bypass, never a weakening: every reuse check
+ * needs this term, so an unresolvable root simply means every lookup misses and
+ * every row goes through the full fenced read.
+ */
+async function resolveListRootIdentity(options, authority) {
+    try {
+        const canonicalRoot = await authority.fileSystem.realpath(options.runsDir);
+        const stats = await fsLstat(canonicalRoot, { bigint: true });
+        if (!stats.isDirectory() || stats.nlink === 0n)
+            return undefined;
+        return directoryIdentity(stats);
+    }
+    catch {
+        return undefined;
+    }
+}
+const HISTORICAL_REUSE_MISS = Object.freeze({ kind: "miss" });
+const HISTORICAL_REUSE_STALE_GENERATION = Object.freeze({
+    kind: "stale_generation",
+});
+async function reuseHistoricalProjection(options, authority, id, rootIdentity) {
+    if (rootIdentity === undefined)
+        return HISTORICAL_REUSE_MISS;
+    const key = historicalProjectionCacheKey(options.runsDir, id);
+    const entry = authority.historicalProjectionCache.get(key);
+    if (entry === undefined)
+        return HISTORICAL_REUSE_MISS;
+    try {
+        const directoryPath = join(options.runsDir, id);
+        const directoryStats = await fsLstat(directoryPath, { bigint: true });
+        if (!directoryStats.isDirectory() || directoryStats.nlink === 0n) {
+            authority.historicalProjectionCache.delete(key);
+            return HISTORICAL_REUSE_MISS;
+        }
+        const currentGeneration = generationFor("historical_manifest", id, rootIdentity, directoryIdentity(directoryStats));
+        if (currentGeneration !== entry.contextGeneration) {
+            authority.historicalProjectionCache.delete(key);
+            return HISTORICAL_REUSE_STALE_GENERATION;
+        }
+        const manifestStats = await fsLstat(join(directoryPath, MANIFEST_FILENAME), {
+            bigint: true,
+        });
+        if (!manifestStats.isFile() ||
+            !containedFileFingerprintsEqual(entry.manifestFingerprint, fingerprintFromStats(manifestStats))) {
+            authority.historicalProjectionCache.delete(key);
+            return HISTORICAL_REUSE_MISS;
+        }
+        // Caller-scoped size limit — see the doc comment: report a miss, do NOT
+        // evict. The stats are already in hand, so this costs no extra syscall.
+        if (entry.manifestFingerprint.size > BigInt(options.maxManifestBytes)) {
+            return HISTORICAL_REUSE_MISS;
+        }
+    }
+    catch {
+        authority.historicalProjectionCache.delete(key);
+        return HISTORICAL_REUSE_MISS;
+    }
+    // Re-insert to move the entry to the LRU tail.
+    authority.historicalProjectionCache.delete(key);
+    authority.historicalProjectionCache.set(key, entry);
+    return { kind: "hit", row: entry.row };
+}
+/**
+ * Store a projection ONLY when the fenced read that produced it carried all
+ * three revalidation terms. Malformed, missing, oversized, policy-rejected and
+ * generation-race outcomes never reach here — they are not `available`, so they
+ * are never cached and never served.
+ */
+function cacheHistoricalProjection(authority, key, row, evidence) {
+    const frozen = deepFreezeProjection(row);
+    const cache = authority.historicalProjectionCache;
+    cache.delete(key);
+    if (evidence.manifestFingerprint === undefined ||
+        evidence.rootIdentity === undefined ||
+        evidence.directoryIdentity === undefined) {
+        return frozen;
+    }
+    cache.set(key, {
+        manifestFingerprint: evidence.manifestFingerprint,
+        rootIdentity: evidence.rootIdentity,
+        directoryIdentity: evidence.directoryIdentity,
+        contextGeneration: evidence.contextGeneration,
+        row: frozen,
+    });
+    while (cache.size > MAX_CONTEXT_RUN_PROJECTION_CACHE_ENTRIES) {
+        const oldest = cache.keys().next().value;
+        if (oldest === undefined)
+            break;
+        cache.delete(oldest);
+    }
+    return frozen;
+}
+function deepFreezeProjection(value) {
+    if (value !== null && typeof value === "object" && !Object.isFrozen(value)) {
+        for (const child of Object.values(value)) {
+            deepFreezeProjection(child);
+        }
+        Object.freeze(value);
+    }
+    return value;
+}
+function resolveOptions(options) {
+    return {
+        runsDir: options.runsDir,
+        maxRows: boundedPositiveOption(options.maxRows, DEFAULT_CONTEXT_RUN_READER_MAX_ROWS, "maxRows"),
+        maxDirEntries: boundedPositiveOption(options.maxDirEntries, DEFAULT_CONTEXT_RUN_READER_MAX_DIR_ENTRIES, "maxDirEntries"),
+        maxStateBytes: boundedPositiveOption(options.maxStateBytes, DEFAULT_CONTEXT_RUN_READER_MAX_STATE_BYTES, "maxStateBytes"),
+        maxManifestBytes: boundedPositiveOption(options.maxManifestBytes, DEFAULT_CONTEXT_RUN_READER_MAX_MANIFEST_BYTES, "maxManifestBytes"),
+        maxArtifactBytes: boundedPositiveOption(options.maxArtifactBytes, DEFAULT_CONTEXT_RUN_READER_MAX_ARTIFACT_BYTES, "maxArtifactBytes"),
+    };
+}
+function boundedPositiveOption(value, maximum, label) {
+    const resolved = value ?? maximum;
+    if (!Number.isSafeInteger(resolved) || resolved < 1 || resolved > maximum) {
+        throw new TypeError(`context run reader ${label} must be an integer from 1 through ${String(maximum)}`);
+    }
+    return resolved;
+}
+async function readJournalRows(options, budget, authority) {
+    const journalDir = join(options.runsDir, CONTEXT_BUILDER_LIFECYCLE_DIRECTORY);
+    const entries = await fsReaddir(journalDir, {
+        withFileTypes: true,
+    }).catch(() => []);
+    const rows = [];
+    for (const entry of entries) {
+        if (budget.entries >= budget.maxEntries) {
+            budget.truncated = true;
+            break;
+        }
+        budget.entries += 1;
+        // isDirectory() is false for a symlink even when it targets a directory,
+        // so a swapped-in symlink is skipped here before any read.
+        if (!entry.isDirectory())
+            continue;
+        const name = entry.name;
+        if (!isContextBuilderOperationId(name) || isWorkflowOwnedId(name))
+            continue;
+        const state = await readJournalState(name, options, authority);
+        if (state.kind !== "available")
+            continue;
+        // Defensive: an operation dir that somehow persisted a workflow-owned kind
+        // is excluded — the journal is standalone/refine only.
+        if (state.value.operation_kind === "workflow_preflight")
+            continue;
+        rows.push({
+            id: name,
+            contextGeneration: state.contextGeneration,
+            source: "journal",
+            compatibility: "current",
+            operationKind: state.value.operation_kind,
+            lifecycle: projectContextRunLifecycleState(state.value),
+            projectFolders: [],
+        });
+    }
+    return rows;
+}
+async function readJournalState(name, options, authority, expectedGeneration) {
+    const result = await readContextArtifact(options, authority, {
+        id: name,
+        source: "journal",
+        directoryRelativePath: join(CONTEXT_BUILDER_LIFECYCLE_DIRECTORY, name),
+        fileRelativePath: join(CONTEXT_BUILDER_LIFECYCLE_DIRECTORY, name, CONTEXT_BUILDER_LIFECYCLE_STATE_FILENAME),
+        maxBytes: options.maxStateBytes,
+    }, expectedGeneration).catch(() => undefined);
+    if (result === undefined) {
+        return { kind: "unavailable", reason: "context_generation_race" };
+    }
+    if (result.kind !== "available")
+        return result;
+    const parsed = safeJsonParse(result.value);
+    if (parsed === undefined)
+        return { kind: "missing" };
+    try {
+        return {
+            kind: "available",
+            value: parseContextBuilderLifecycleStateV1(parsed),
+            contextGeneration: result.contextGeneration,
+        };
+    }
+    catch {
+        return { kind: "missing" };
+    }
+}
+async function readHistoricalRows(options, budget, authority, rootIdentity) {
+    const entries = await fsReaddir(options.runsDir, {
+        withFileTypes: true,
+    }).catch(() => []);
+    const rows = [];
+    for (const entry of entries) {
+        if (budget.entries >= budget.maxEntries) {
+            budget.truncated = true;
+            break;
+        }
+        budget.entries += 1;
+        if (!entry.isDirectory())
+            continue;
+        const name = entry.name;
+        if (name === CONTEXT_BUILDER_LIFECYCLE_DIRECTORY)
+            continue;
+        if (isWorkflowOwnedId(name))
+            continue;
+        // A ctxop_* operation ID is never a top-level artifact run dir.
+        if (isContextBuilderOperationId(name))
+            continue;
+        const reused = await reuseHistoricalProjection(options, authority, name, rootIdentity);
+        // No manifest-missing fallback on this path, so `stale_generation` and
+        // `miss` are both simply "fall through to the fenced read".
+        if (reused.kind === "hit") {
+            rows.push(reused.row);
+            continue;
+        }
+        const manifest = await readHistoricalManifest(name, options, authority);
+        if (manifest.kind !== "available")
+            continue;
+        const row = synthesizeHistoricalRow(name, manifest.value, manifest.contextGeneration);
+        if (row !== undefined) {
+            rows.push(cacheHistoricalProjection(authority, historicalProjectionCacheKey(options.runsDir, name), row, {
+                manifestFingerprint: manifest.fingerprint,
+                rootIdentity: manifest.rootIdentity,
+                directoryIdentity: manifest.directoryIdentity,
+                contextGeneration: manifest.contextGeneration,
+            }));
+        }
+    }
+    return rows;
+}
+async function readHistoricalManifest(name, options, authority, expectedGeneration) {
+    const result = await readContextArtifact(options, authority, {
+        id: name,
+        source: "historical_manifest",
+        directoryRelativePath: name,
+        fileRelativePath: join(name, MANIFEST_FILENAME),
+        maxBytes: options.maxManifestBytes,
+    }, expectedGeneration).catch(() => undefined);
+    if (result === undefined) {
+        return { kind: "unavailable", reason: "context_generation_race" };
+    }
+    if (result.kind !== "available")
+        return result;
+    const parsed = safeJsonParse(result.value);
+    return isRecord(parsed)
+        ? {
+            kind: "available",
+            value: parsed,
+            contextGeneration: result.contextGeneration,
+            fingerprint: result.fingerprint,
+            rootIdentity: result.rootIdentity,
+            directoryIdentity: result.directoryIdentity,
+        }
+        : { kind: "missing" };
+}
+function synthesizeHistoricalRow(name, manifest, contextGeneration) {
+    const artifacts = manifest["artifacts"];
+    if (!isRecord(artifacts))
+        return undefined;
+    const runId = manifest["run_id"];
+    // Artifact identity is both the directory key and manifest identity. Refuse
+    // mismatches rather than creating a route that cannot be resolved directly.
+    if (typeof runId !== "string" || runId !== name || !isHistoricalArtifactId(runId)) {
+        return undefined;
+    }
+    const compatibility = classifyArtifactKeys(Object.keys(artifacts));
+    if (compatibility === undefined)
+        return undefined;
+    const projectFolders = extractManifestRoots(manifest["roots"]);
+    if (compatibility === "legacy_unsupported") {
+        return {
+            id: runId,
+            contextGeneration,
+            source: "historical_manifest",
+            compatibility: "legacy_unsupported",
+            operationKind: "historical",
+            lifecycle: null,
+            projectFolders,
+        };
+    }
+    const status = manifestStatus(manifest["status"]);
+    if (status === undefined)
+        return undefined;
+    if (manifest["created_at"] !== undefined && validIso(manifest["created_at"]) === null) {
+        return undefined;
+    }
+    return {
+        id: runId,
+        contextGeneration,
+        source: "historical_manifest",
+        compatibility,
+        operationKind: "historical",
+        lifecycle: synthesizeTerminalLifecycle(manifest, status, runId),
+        projectFolders,
+    };
+}
+/**
+ * Extract project folder paths from the manifest `roots` array. Each root is a
+ * record `{ root_index, input_path, path }`; `path` is the resolved source root.
+ * Returns `[]` when roots are absent or malformed.
+ *
+ * The projection is BOUNDED to {@link MAX_DASHBOARD_ROOTS}, the same ceiling the
+ * wire contract enforces on `projectFolders`. Excess roots are DROPPED rather
+ * than erroring: an unbounded projection would produce a row that fails
+ * `ContextRunListResponseSchema.parse` at the route, and that parse throws — so
+ * one over-rooted manifest would fail the ENTIRE list/detail response, not just
+ * its own row. Input order is preserved and malformed entries are skipped
+ * without consuming budget. Sibling readers cap identically
+ * (`activity-reader.ts`, `scanner.ts`).
+ */
+function extractManifestRoots(value) {
+    if (!Array.isArray(value))
+        return [];
+    const folders = [];
+    for (const entry of value) {
+        if (!isRecord(entry))
+            continue;
+        const path = entry["path"];
+        if (typeof path === "string" && path.length > 0) {
+            folders.push(path);
+            if (folders.length >= MAX_DASHBOARD_ROOTS)
+                break;
+        }
+    }
+    return folders;
+}
+function isHistoricalArtifactId(id) {
+    return CONTEXT_BUILDER_ARTIFACT_ID_PATTERN.test(id);
+}
+function classifyArtifactKeys(keys) {
+    const unique = new Set(keys);
+    if (unique.size === 7 && LEGACY_ARTIFACT_KEYS.every((k) => unique.has(k))) {
+        return "legacy_synthesized";
+    }
+    if (unique.size === 8 && CURRENT_ARTIFACT_KEYS.every((k) => unique.has(k))) {
+        return "current";
+    }
+    // 9-key (or larger) manifests are a forward-incompatible artifact shape.
+    if (unique.size >= 9)
+        return "legacy_unsupported";
+    return undefined;
+}
+function synthesizeTerminalLifecycle(manifest, status, runId) {
+    const createdAt = validIso(manifest["created_at"]);
+    const metrics = isRecord(manifest["metrics"]) ? manifest["metrics"] : {};
+    const coverage = isRecord(manifest["coverage"])
+        ? manifest["coverage"]
+        : undefined;
+    return {
+        status,
+        phase: "complete",
+        createdAt,
+        updatedAt: createdAt,
+        startedAt: createdAt,
+        completedAt: createdAt,
+        durationMs: null,
+        // Live curator/finalizer stage identity is not recoverable from a committed
+        // manifest, so historical synthesis reports them as unexecuted rather than
+        // guessing.
+        curator: { status: "not_configured", score: null },
+        finalizer: { status: "not_configured", score: null },
+        cache: { lookup: "not_checked", write: "not_attempted" },
+        fallback: { status: "not_applicable" },
+        counts: {
+            filesSeen: safeCount(metrics["files_seen"]),
+            filesConsidered: safeCount(metrics["files_considered"]),
+            filesSelected: safeCount(metrics["files_selected"]),
+            filesOmitted: safeCount(metrics["files_omitted"]),
+            searchResults: 0,
+            bytesRead: safeCount(metrics["bytes_read"]),
+            bytesWritten: safeCount(metrics["bytes_written"]),
+        },
+        coverage: synthesizeCoverage(coverage),
+        reasonCodes: ["legacy_supported"],
+        artifactRunId: runId,
+    };
+}
+function synthesizeCoverage(coverage) {
+    const status = coverage?.["status"];
+    const policy = coverage?.["policy"];
+    if (status === "satisfied" ||
+        status === "degraded" ||
+        status === "not_evaluated") {
+        return {
+            policy: policy === "review_deep_v1" ? "review_deep_v1" : null,
+            status,
+            required: safeCount(coverage?.["required"]),
+            selected: safeCount(coverage?.["selected"]),
+            missing: safeCount(coverage?.["missing"]),
+        };
+    }
+    return { policy: null, status: "not_evaluated", required: 0, selected: 0, missing: 0 };
+}
+export function projectContextRunLifecycleState(state) {
+    return {
+        status: state.status,
+        phase: state.phase,
+        createdAt: state.created_at,
+        updatedAt: state.updated_at,
+        startedAt: state.started_at ?? null,
+        completedAt: state.completed_at ?? null,
+        durationMs: state.duration_ms ?? null,
+        curator: {
+            status: state.curator.execution_status,
+            score: state.curator.score ?? null,
+        },
+        finalizer: {
+            status: state.finalizer.execution_status,
+            score: state.finalizer.score ?? null,
+        },
+        cache: { lookup: state.cache.lookup, write: state.cache.write },
+        fallback: { status: state.fallback.status },
+        counts: {
+            filesSeen: state.counts.files_seen,
+            filesConsidered: state.counts.files_considered,
+            filesSelected: state.counts.files_selected,
+            filesOmitted: state.counts.files_omitted,
+            searchResults: state.counts.search_results,
+            bytesRead: state.counts.bytes_read,
+            bytesWritten: state.counts.bytes_written,
+        },
+        coverage: {
+            policy: state.coverage.policy,
+            status: state.coverage.status,
+            required: state.coverage.required,
+            selected: state.coverage.selected,
+            missing: state.coverage.missing,
+        },
+        reasonCodes: [...state.reason_codes],
+        artifactRunId: state.artifact_run_id ?? null,
+    };
+}
+/**
+ * Status tier for a context-run row: 0 = live pin (pending/running with a
+ * fresh `updatedAt`), 1 = everything else. Stale persisted `running` rows,
+ * `unknown` liveness, and `legacy_unsupported` sort with history so a
+ * wedged journal cannot occupy the live lane forever.
+ */
+function contextRunStatusTier(row) {
+    return isContextRunLivePin(row) ? 0 : 1;
+}
+/**
+ * Status-tiered, newest-first: active rows (pending/running) lead, terminal
+ * rows (succeeded/partial/failed/cancelled) follow. Within each tier, newest
+ * first by createdAt (updatedAt fallback), then by id descending.
+ */
+function compareRowsNewestFirst(left, right, sortTimes = new Map()) {
+    const tierOrder = contextRunStatusTier(left) - contextRunStatusTier(right);
+    if (tierOrder !== 0)
+        return tierOrder;
+    const leftTime = sortTimes.get(contextRunRowIdentity(left)) ?? rowSortTime(left);
+    const rightTime = sortTimes.get(contextRunRowIdentity(right)) ?? rowSortTime(right);
+    if (leftTime !== rightTime)
+        return rightTime - leftTime;
+    return left.id < right.id ? 1 : left.id > right.id ? -1 : 0;
+}
+function rowSortTime(row) {
+    const iso = row.lifecycle?.createdAt ?? row.lifecycle?.updatedAt ?? null;
+    if (iso === null)
+        return -1;
+    const parsed = Date.parse(iso);
+    return Number.isNaN(parsed) ? -1 : parsed;
+}
+function manifestStatus(value) {
+    return value === "succeeded" || value === "partial" ? value : undefined;
+}
+function validIso(value) {
+    if (typeof value !== "string")
+        return null;
+    if (!/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d+)?(?:Z|[+-]\d{2}:\d{2})$/.test(value))
+        return null;
+    return Number.isNaN(Date.parse(value)) ? null : value;
+}
+function safeCount(value) {
+    return typeof value === "number" && Number.isFinite(value) && value >= 0
+        ? Math.min(250_000_000, Math.trunc(value))
+        : 0;
+}
+function safeJsonParse(text) {
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return undefined;
+    }
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+//# sourceMappingURL=context-run-reader.js.map