clinkx 0.3.0 → 1.1.0

package/clinkx-workflows/dist/dashboard/context-builder-invocation-contract.js

@@ -0,0 +1,69 @@
+import { z } from "zod";
+import { InvocationAuditReadSchema, InvocationAuditV1Schema, } from "./invocation-contract.js";
+import { validateContextBuilderOperationId } from "../context-builder-lifecycle-contract.js";
+export const CONTEXT_BUILDER_INVOCATION_AUDIT_FILENAME = "invocation-audit.json";
+export const WORKFLOW_CONTEXT_PREFLIGHT_SNAPSHOT_DIRECTORY = ".context-preflight";
+export const MAX_CONTEXT_BUILDER_INVOCATION_AUDIT_BYTES = 8 * 1_024;
+export const CONTEXT_BUILDER_INVOCATION_AUDIT_V1_SCHEMA_VERSION = "context-builder-invocation-audit-v1";
+export const CONTEXT_BUILDER_INVOCATION_AUDIT_V2_SCHEMA_VERSION = "context-builder-invocation-audit-v2";
+/** Exact decoder for already-persisted sidecars. */
+export const ContextBuilderInvocationAuditV1Schema = z.object({
+    schema_version: z.literal(CONTEXT_BUILDER_INVOCATION_AUDIT_V1_SCHEMA_VERSION),
+    curator: InvocationAuditV1Schema.optional(),
+    finalizer: InvocationAuditV1Schema.optional(),
+}).strict();
+/**
+ * Canonical new sidecar. Seat-level read unions permit a writer to promote an
+ * existing V1 document without rewriting or inventing its already-recorded
+ * audit. The sidecar remains separate from manifests and receipts.
+ */
+export const ContextBuilderInvocationAuditV2Schema = z.object({
+    schema_version: z.literal(CONTEXT_BUILDER_INVOCATION_AUDIT_V2_SCHEMA_VERSION),
+    curator: InvocationAuditReadSchema.optional(),
+    finalizer: InvocationAuditReadSchema.optional(),
+}).strict();
+export const ContextBuilderInvocationAuditReadSchema = z.union([
+    ContextBuilderInvocationAuditV2Schema,
+    ContextBuilderInvocationAuditV1Schema,
+]);
+/**
+ * Decode persisted audit bytes without repairing malformed UTF-8. Keeping the
+ * BOM as data preserves the prior JSON rejection behavior, while the explicit
+ * roundtrip makes byte-preserving promotion and snapshot publication provable.
+ */
+export function decodeContextBuilderInvocationAuditBytes(bytes) {
+    let serialized;
+    try {
+        serialized = new TextDecoder("utf-8", {
+            fatal: true,
+            ignoreBOM: true,
+        }).decode(bytes);
+    }
+    catch {
+        throw new SyntaxError("context builder invocation audit is not valid UTF-8");
+    }
+    if (!Buffer.from(serialized, "utf8").equals(Buffer.from(bytes))) {
+        throw new SyntaxError("context builder invocation audit changed during UTF-8 decoding");
+    }
+    const parsed = JSON.parse(serialized);
+    return {
+        document: ContextBuilderInvocationAuditReadSchema.parse(parsed),
+        serialized,
+    };
+}
+export function workflowContextBuilderInvocationAuditRelativePath(contextRunId) {
+    return `${WORKFLOW_CONTEXT_PREFLIGHT_SNAPSHOT_DIRECTORY}/${validateContextBuilderOperationId(contextRunId)}/${CONTEXT_BUILDER_INVOCATION_AUDIT_FILENAME}`;
+}
+/**
+ * Encode canonical V2 bytes and enforce the same cap used by contained-file
+ * readers. Callers decide whether an over-cap write is best-effort or fatal.
+ */
+export function serializeContextBuilderInvocationAuditV2(document) {
+    const serialized = `${JSON.stringify(ContextBuilderInvocationAuditV2Schema.parse(document))}\n`;
+    if (Buffer.byteLength(serialized, "utf8") >
+        MAX_CONTEXT_BUILDER_INVOCATION_AUDIT_BYTES) {
+        throw new RangeError("context builder invocation audit exceeds 8 KiB");
+    }
+    return serialized;
+}
+//# sourceMappingURL=context-builder-invocation-contract.js.map

package/clinkx-workflows/dist/dashboard/context-builder-invocation-contract.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"context-builder-invocation-contract.js","sourceRoot":"","sources":["../../src/dashboard/context-builder-invocation-contract.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,OAAO,EACL,yBAAyB,EACzB,uBAAuB,GACxB,MAAM,0BAA0B,CAAC;AAClC,OAAO,EAAE,iCAAiC,EAAE,MAAM,0CAA0C,CAAC;AAE7F,MAAM,CAAC,MAAM,yCAAyC,GACpD,uBAAgC,CAAC;AACnC,MAAM,CAAC,MAAM,6CAA6C,GACxD,oBAA6B,CAAC;AAChC,MAAM,CAAC,MAAM,0CAA0C,GAAG,CAAC,GAAG,KAAK,CAAC;AAEpE,MAAM,CAAC,MAAM,kDAAkD,GAC7D,qCAA8C,CAAC;AACjD,MAAM,CAAC,MAAM,kDAAkD,GAC7D,qCAA8C,CAAC;AAEjD,oDAAoD;AACpD,MAAM,CAAC,MAAM,qCAAqC,GAAG,CAAC,CAAC,MAAM,CAAC;IAC5D,cAAc,EAAE,CAAC,CAAC,OAAO,CACvB,kDAAkD,CACnD;IACD,OAAO,EAAE,uBAAuB,CAAC,QAAQ,EAAE;IAC3C,SAAS,EAAE,uBAAuB,CAAC,QAAQ,EAAE;CAC9C,CAAC,CAAC,MAAM,EAAE,CAAC;AAEZ;;;;GAIG;AACH,MAAM,CAAC,MAAM,qCAAqC,GAAG,CAAC,CAAC,MAAM,CAAC;IAC5D,cAAc,EAAE,CAAC,CAAC,OAAO,CACvB,kDAAkD,CACnD;IACD,OAAO,EAAE,yBAAyB,CAAC,QAAQ,EAAE;IAC7C,SAAS,EAAE,yBAAyB,CAAC,QAAQ,EAAE;CAChD,CAAC,CAAC,MAAM,EAAE,CAAC;AAEZ,MAAM,CAAC,MAAM,uCAAuC,GAAG,CAAC,CAAC,KAAK,CAAC;IAC7D,qCAAqC;IACrC,qCAAqC;CACtC,CAAC,CAAC;AAYH;;;;GAIG;AACH,MAAM,UAAU,wCAAwC,CACtD,KAAiB;IAKjB,IAAI,UAAkB,CAAC;IACvB,IAAI,CAAC;QACH,UAAU,GAAG,IAAI,WAAW,CAAC,OAAO,EAAE;YACpC,KAAK,EAAE,IAAI;YACX,SAAS,EAAE,IAAI;SAChB,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;IACnB,CAAC;IAAC,MAAM,CAAC;QACP,MAAM,IAAI,WAAW,CAAC,qDAAqD,CAAC,CAAC;IAC/E,CAAC;IACD,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,UAAU,EAAE,MAAM,CAAC,CAAC,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC;QAChE,MAAM,IAAI,WAAW,CAAC,gEAAgE,CAAC,CAAC;IAC1F,CAAC;IAED,MAAM,MAAM,GAAY,IAAI,CAAC,KAAK,CAAC,UAAU,CAAC,CAAC;IAC/C,OAAO;QACL,QAAQ,EAAE,uCAAuC,CAAC,KAAK,CAAC,MAAM,CAAC;QAC/D,UAAU;KACX,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,iDAAiD,CAC/D,YAAoB;IAEpB,OAAO,GAAG,6CAA6C,IAAI,iCAAiC,CAC1F,YAAY,CACb,IAAI,yCAAyC,EAAE,CAAC;AACnD,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,wCAAwC,CACtD,QAAyC;IAEzC,MAAM,UAAU,GAAG,GAAG,IAAI,CAAC,SAAS,CAClC,qCAAqC,CAAC,KAAK,CAAC,QAAQ,CAAC,CACtD,IAAI,CAAC;IACN,IACE,MAAM,CAAC,UAAU,CAAC,UAAU,EAAE,MAAM,CAAC;QACnC,0CAA0C,EAC5C,CAAC;QACD,MAAM,IAAI,UAAU,CAAC,gDAAgD,CAAC,CAAC;IACzE,CAAC;IACD,OAAO,UAAU,CAAC;AACpB,CAAC"}

package/clinkx-workflows/dist/dashboard/context-run-liveness.d.ts

@@ -0,0 +1,37 @@
+import { type ContextBuilderLifecyclePhase, type ContextBuilderLifecycleStatus } from "../context-builder-lifecycle-contract.js";
+/**
+ * Write-like phases have no long-running subprocess. Matches the producer
+ * mutation-lock stale window (`CONTEXT_BUILDER_STALE_MUTATION_LOCK_MS` in
+ * `src/context-builder/storage.ts`) — duplicated here because the dashboard
+ * package does not import the producer.
+ */
+export declare const CONTEXT_RUN_WRITE_STALE_AFTER_MS: number;
+/** Any other active phase uses the contract duration ceiling. */
+export declare const CONTEXT_RUN_ACTIVE_STALE_AFTER_MS = 86400000;
+export type ContextRunLiveness = "live" | "orphaned" | "unknown";
+export type ContextRunLivenessOverlay = Readonly<{
+    orphaned: boolean;
+    liveness: ContextRunLiveness;
+}>;
+/**
+ * Read-time liveness overlay. Never persist the result.
+ *
+ * Terminal / missing lifecycle → `unknown` (never death). Active
+ * (`pending`/`running`) with a missing or unparseable `updatedAt` → `unknown`.
+ * Active with a parseable `updatedAt` uses a phase-aware age: write-like
+ * phases stale after 10 minutes, every other active phase after 24h. A
+ * producer clock slightly ahead (negative age) stays `live`.
+ */
+export declare function classifyContextRunLiveness(input: Readonly<{
+    status?: ContextBuilderLifecycleStatus | null;
+    phase?: ContextBuilderLifecyclePhase | null;
+    updatedAt?: string | null;
+    nowMs: number;
+}>): ContextRunLivenessOverlay;
+export declare function isContextRunLivePin(row: Readonly<{
+    orphaned?: boolean;
+    liveness?: ContextRunLiveness;
+    lifecycle?: Readonly<{
+        status: string;
+    }> | null;
+}>): boolean;

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

@@ -0,0 +1,49 @@
+import { MAX_CONTEXT_BUILDER_LIFECYCLE_DURATION_MS, } from "../context-builder-lifecycle-contract.js";
+/**
+ * Write-like phases have no long-running subprocess. Matches the producer
+ * mutation-lock stale window (`CONTEXT_BUILDER_STALE_MUTATION_LOCK_MS` in
+ * `src/context-builder/storage.ts`) — duplicated here because the dashboard
+ * package does not import the producer.
+ */
+export const CONTEXT_RUN_WRITE_STALE_AFTER_MS = 10 * 60 * 1_000;
+/** Any other active phase uses the contract duration ceiling. */
+export const CONTEXT_RUN_ACTIVE_STALE_AFTER_MS = MAX_CONTEXT_BUILDER_LIFECYCLE_DURATION_MS;
+const WRITE_LIKE_PHASES = new Set([
+    "writing",
+    "committing",
+    "materializing",
+]);
+/**
+ * Read-time liveness overlay. Never persist the result.
+ *
+ * Terminal / missing lifecycle → `unknown` (never death). Active
+ * (`pending`/`running`) with a missing or unparseable `updatedAt` → `unknown`.
+ * Active with a parseable `updatedAt` uses a phase-aware age: write-like
+ * phases stale after 10 minutes, every other active phase after 24h. A
+ * producer clock slightly ahead (negative age) stays `live`.
+ */
+export function classifyContextRunLiveness(input) {
+    if (input.status !== "pending" && input.status !== "running") {
+        return { orphaned: false, liveness: "unknown" };
+    }
+    if (input.updatedAt == null) {
+        return { orphaned: false, liveness: "unknown" };
+    }
+    const updatedMs = Date.parse(input.updatedAt);
+    if (!Number.isFinite(updatedMs)) {
+        return { orphaned: false, liveness: "unknown" };
+    }
+    const thresholdMs = input.phase != null && WRITE_LIKE_PHASES.has(input.phase)
+        ? CONTEXT_RUN_WRITE_STALE_AFTER_MS
+        : CONTEXT_RUN_ACTIVE_STALE_AFTER_MS;
+    if (input.nowMs - updatedMs <= thresholdMs) {
+        return { orphaned: false, liveness: "live" };
+    }
+    return { orphaned: true, liveness: "orphaned" };
+}
+export function isContextRunLivePin(row) {
+    const status = row.lifecycle?.status;
+    return ((status === "pending" || status === "running") &&
+        row.liveness === "live");
+}
+//# sourceMappingURL=context-run-liveness.js.map

package/clinkx-workflows/dist/dashboard/context-run-liveness.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"context-run-liveness.js","sourceRoot":"","sources":["../../src/dashboard/context-run-liveness.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,yCAAyC,GAG1C,MAAM,0CAA0C,CAAC;AAElD;;;;;GAKG;AACH,MAAM,CAAC,MAAM,gCAAgC,GAAG,EAAE,GAAG,EAAE,GAAG,KAAK,CAAC;AAEhE,iEAAiE;AACjE,MAAM,CAAC,MAAM,iCAAiC,GAC5C,yCAAyC,CAAC;AAE5C,MAAM,iBAAiB,GAA8C,IAAI,GAAG,CAAC;IAC3E,SAAS;IACT,YAAY;IACZ,eAAe;CAChB,CAAC,CAAC;AASH;;;;;;;;GAQG;AACH,MAAM,UAAU,0BAA0B,CAAC,KAKzC;IACA,IAAI,KAAK,CAAC,MAAM,KAAK,SAAS,IAAI,KAAK,CAAC,MAAM,KAAK,SAAS,EAAE,CAAC;QAC7D,OAAO,EAAE,QAAQ,EAAE,KAAK,EAAE,QAAQ,EAAE,SAAS,EAAE,CAAC;IAClD,CAAC;IACD,IAAI,KAAK,CAAC,SAAS,IAAI,IAAI,EAAE,CAAC;QAC5B,OAAO,EAAE,QAAQ,EAAE,KAAK,EAAE,QAAQ,EAAE,SAAS,EAAE,CAAC;IAClD,CAAC;IACD,MAAM,SAAS,GAAG,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,SAAS,CAAC,CAAC;IAC9C,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,SAAS,CAAC,EAAE,CAAC;QAChC,OAAO,EAAE,QAAQ,EAAE,KAAK,EAAE,QAAQ,EAAE,SAAS,EAAE,CAAC;IAClD,CAAC;IACD,MAAM,WAAW,GAAG,KAAK,CAAC,KAAK,IAAI,IAAI,IAAI,iBAAiB,CAAC,GAAG,CAAC,KAAK,CAAC,KAAK,CAAC;QAC3E,CAAC,CAAC,gCAAgC;QAClC,CAAC,CAAC,iCAAiC,CAAC;IACtC,IAAI,KAAK,CAAC,KAAK,GAAG,SAAS,IAAI,WAAW,EAAE,CAAC;QAC3C,OAAO,EAAE,QAAQ,EAAE,KAAK,EAAE,QAAQ,EAAE,MAAM,EAAE,CAAC;IAC/C,CAAC;IACD,OAAO,EAAE,QAAQ,EAAE,IAAI,EAAE,QAAQ,EAAE,UAAU,EAAE,CAAC;AAClD,CAAC;AAED,MAAM,UAAU,mBAAmB,CAAC,GAIlC;IACA,MAAM,MAAM,GAAG,GAAG,CAAC,SAAS,EAAE,MAAM,CAAC;IACrC,OAAO,CACL,CAAC,MAAM,KAAK,SAAS,IAAI,MAAM,KAAK,SAAS,CAAC;QAC9C,GAAG,CAAC,QAAQ,KAAK,MAAM,CACxB,CAAC;AACJ,CAAC"}

package/clinkx-workflows/dist/dashboard/context-run-reader.d.ts

@@ -0,0 +1,256 @@
+/**
+ * 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 { type FileHandle } from "node:fs/promises";
+import { type ContextBuilderLifecycleStateV1, type ContextBuilderOperationKind } from "../context-builder-lifecycle-contract.js";
+import { readContainedRelativeFile, type ContainedFileFingerprint, type OpenedDescriptorPathVerifier } from "../contained-file.js";
+import { type ContextBuilderInvocationAuditRead } from "./context-builder-invocation-contract.js";
+import { type ContextRunLiveness } from "./context-run-liveness.js";
+/**
+ * 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 declare const CONTEXT_RUN_ARTIFACT_FILE_NAMES: Readonly<{
+    readonly manifest_json: "manifest.json";
+    readonly bundle_md: "bundle.md";
+    readonly selected_context_jsonl: "selected-context.jsonl";
+    readonly tree_json: "tree.json";
+    readonly search_jsonl: "search.jsonl";
+    readonly slices_jsonl: "slices.jsonl";
+    readonly codemap_jsonl: "codemap.jsonl";
+    readonly summary_json: "summary.json";
+}>;
+export type ContextRunArtifactKey = keyof typeof CONTEXT_RUN_ARTIFACT_FILE_NAMES;
+export declare const CONTEXT_RUN_ARTIFACT_KEYS: readonly ContextRunArtifactKey[];
+export declare const DEFAULT_CONTEXT_RUN_READER_MAX_ROWS = 500;
+export declare const DEFAULT_CONTEXT_RUN_READER_MAX_DIR_ENTRIES = 5000;
+export declare const DEFAULT_CONTEXT_RUN_READER_MAX_STATE_BYTES: number;
+export declare const DEFAULT_CONTEXT_RUN_READER_MAX_MANIFEST_BYTES: number;
+/**
+ * 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 declare const DEFAULT_CONTEXT_RUN_READER_MAX_ARTIFACT_BYTES: number;
+export type ContextRunSource = "journal" | "historical_manifest";
+export type ContextRunCompatibility = "current" | "legacy_synthesized" | "legacy_unsupported";
+export interface ContextRunCounts {
+    readonly filesSeen: number;
+    readonly filesConsidered: number;
+    readonly filesSelected: number;
+    readonly filesOmitted: number;
+    readonly searchResults: number;
+    readonly bytesRead: number;
+    readonly bytesWritten: number;
+}
+export interface ContextRunCoverage {
+    readonly policy: ContextBuilderLifecycleStateV1["coverage"]["policy"];
+    readonly status: ContextBuilderLifecycleStateV1["coverage"]["status"];
+    readonly required: number;
+    readonly selected: number;
+    readonly missing: number;
+}
+export interface ContextRunLifecycleProjection {
+    readonly status: ContextBuilderLifecycleStateV1["status"];
+    readonly phase: ContextBuilderLifecycleStateV1["phase"];
+    readonly createdAt: string | null;
+    readonly updatedAt: string | null;
+    readonly startedAt: string | null;
+    readonly completedAt: string | null;
+    readonly durationMs: number | null;
+    readonly curator: {
+        readonly status: ContextBuilderLifecycleStateV1["curator"]["execution_status"];
+        readonly score: number | null;
+    };
+    readonly finalizer: {
+        readonly status: ContextBuilderLifecycleStateV1["finalizer"]["execution_status"];
+        readonly score: number | null;
+    };
+    readonly cache: {
+        readonly lookup: ContextBuilderLifecycleStateV1["cache"]["lookup"];
+        readonly write: ContextBuilderLifecycleStateV1["cache"]["write"];
+    };
+    readonly fallback: {
+        readonly status: ContextBuilderLifecycleStateV1["fallback"]["status"];
+    };
+    readonly counts: ContextRunCounts;
+    readonly coverage: ContextRunCoverage;
+    readonly reasonCodes: ContextBuilderLifecycleStateV1["reason_codes"];
+    readonly artifactRunId: string | null;
+}
+export interface ContextRunRow {
+    /** Operation ID for journal rows; artifact run_id for historical rows. */
+    readonly id: string;
+    /** Opaque identity for the current source-directory incarnation. */
+    readonly contextGeneration: string;
+    readonly source: ContextRunSource;
+    readonly compatibility: ContextRunCompatibility;
+    readonly operationKind: ContextBuilderOperationKind;
+    /** Null only when the shape is `legacy_unsupported`. */
+    readonly lifecycle: ContextRunLifecycleProjection | null;
+    /**
+     * Project folder(s) the context run operated on, from the manifest
+     * `roots[].path`. A narrow, deliberate exception to the "no paths in a row"
+     * rule: historical_manifest rows carry the persisted roots verbatim, while
+     * journal (`current`) rows report `[]` (their lifecycle state lives apart
+     * from the manifest and reading it per detail fetch is not worth the cost).
+     */
+    readonly projectFolders: readonly string[];
+    /**
+     * Read-time overlay. Never persisted. Terminal / unsupported rows are
+     * `liveness: "unknown"`; a stale active journal is `orphaned`.
+     */
+    readonly orphaned: boolean;
+    readonly liveness: ContextRunLiveness;
+}
+export interface ContextRunInvocationAudit {
+    readonly curator?: ContextBuilderInvocationAuditRead["curator"];
+    readonly finalizer?: ContextBuilderInvocationAuditRead["finalizer"];
+}
+/**
+ * Detail projection only. List rows stay the lean {@link ContextRunRow}
+ * shape and never carry `invocationAudit`.
+ */
+export interface ContextRunDetailRow extends ContextRunRow {
+    readonly invocationAudit?: ContextRunInvocationAudit;
+}
+export interface ContextBuilderInvocationAuditDependency {
+    readonly artifactRunId: string;
+    readonly contextGeneration: string;
+    readonly fingerprint: ContainedFileFingerprint;
+}
+export type ContextBuilderInvocationAuditArtifactResult = Readonly<{
+    kind: "available";
+    audit: ContextBuilderInvocationAuditRead;
+    dependency: ContextBuilderInvocationAuditDependency;
+}> | Readonly<{
+    kind: "missing";
+}> | Readonly<{
+    kind: "context_generation_changed";
+}> | Readonly<{
+    kind: "unavailable";
+    reason: "context_generation_race";
+}>;
+export interface ContextRunReadResult {
+    readonly rows: readonly ContextRunRow[];
+    /** A directory / row cap was hit; the listing is not exhaustive. */
+    readonly truncated: boolean;
+}
+export interface ContextRunReaderOptions {
+    readonly runsDir: string;
+    readonly maxRows?: number;
+    readonly maxDirEntries?: number;
+    readonly maxStateBytes?: number;
+    readonly maxManifestBytes?: number;
+    readonly maxArtifactBytes?: number;
+}
+export type ContextRunDetailResult = Readonly<{
+    kind: "available";
+    row: ContextRunDetailRow;
+}> | Readonly<{
+    kind: "missing";
+}> | Readonly<{
+    kind: "context_generation_changed";
+}> | Readonly<{
+    kind: "unavailable";
+    reason: "context_generation_race";
+}>;
+/**
+ * Result of a bounded artifact-body read. The `artifactRunId` is the directory
+ * the body was actually read from (the journal row's linked artifact run, or the
+ * historical row's own id); callers re-confirm via readDetail to close a
+ * journal-state-swap TOCTOU. `contextGeneration` is the generation pinned to the
+ * artifact directory at read time.
+ */
+export type ContextRunArtifactResult = Readonly<{
+    kind: "available";
+    content: string;
+    artifactRunId: string;
+    contextGeneration: string;
+}> | Readonly<{
+    kind: "missing";
+}> | Readonly<{
+    kind: "context_generation_changed";
+}> | Readonly<{
+    kind: "content_too_large";
+}> | Readonly<{
+    kind: "unavailable";
+    reason: "context_generation_race";
+}>;
+export interface ContextRunReader {
+    readonly list: (options: ContextRunReaderOptions) => Promise<ContextRunReadResult>;
+    readonly readDetail: (options: ContextRunReaderOptions, id: string, contextGeneration?: string) => Promise<ContextRunDetailResult>;
+    readonly readArtifact: (options: ContextRunReaderOptions, id: string, artifactKey: ContextRunArtifactKey, contextGeneration?: string) => Promise<ContextRunArtifactResult>;
+    /**
+     * Detail-only bridge for a lifecycle-validated artifact identity. This does
+     * not enumerate or admit the artifact as a Context Run row.
+     */
+    readonly readInvocationAuditArtifact?: (options: ContextRunReaderOptions, artifactRunId: string, contextGeneration?: string) => Promise<ContextBuilderInvocationAuditArtifactResult>;
+}
+interface ContextRunAuthorityFileSystem {
+    readonly open: (path: string, flags: number) => Promise<FileHandle>;
+    readonly realpath: (path: string) => Promise<string>;
+}
+export interface ContextRunReaderAuthorityOptions {
+    readonly fileSystem?: ContextRunAuthorityFileSystem | undefined;
+    readonly descriptorPathVerifier?: OpenedDescriptorPathVerifier | undefined;
+    readonly readContainedFile?: typeof readContainedRelativeFile | undefined;
+    /** Deterministic race-injection seam; never used by production callers. */
+    readonly beforeCommitVerification?: ((identity: Readonly<{
+        id: string;
+        source: ContextRunSource;
+    }>) => void | Promise<void>) | undefined;
+    /** Injectable clock for the read-time liveness overlay. */
+    readonly now?: () => Date;
+}
+export declare class ContextRunSourceUnavailableError extends Error {
+    constructor();
+}
+export declare function createContextRunReader(options?: ContextRunReaderAuthorityOptions): ContextRunReader;
+export declare function readContextRuns(options: ContextRunReaderOptions): Promise<ContextRunReadResult>;
+export declare function readContextRunArtifact(options: ContextRunReaderOptions, id: string, artifactKey: ContextRunArtifactKey, contextGeneration?: string): Promise<ContextRunArtifactResult>;
+/** Resolve one stable row identity directly, independent of list limits/order. */
+export declare function readContextRun(options: ContextRunReaderOptions, id: string, contextGeneration?: string): Promise<ContextRunDetailResult>;
+export declare function projectContextRunLifecycleState(state: ContextBuilderLifecycleStateV1): ContextRunLifecycleProjection;
+export {};