@inflexa-ai/harness 0.43.1 → 0.45.0

package/dist/state/analyses-metrics.js

@@ -1,9 +1,11 @@
 /**
- * Cross-entity aggregate reads used by `routes/analyses-metrics.ts` to build
- * the per-analysis metrics view. Each query touches one table; the view is
- * the batch shape callers want.
+ * Cross-entity aggregate reads for a list of analyses. Each read takes the ids
+ * of a page and sends one statement, whatever the length of the list: an
+ * embedder builds the per-analysis summary of a list from these reads, never
+ * from one read for each analysis.
  */
 import { okAsync } from "neverthrow";
+import { profileDatasetFileCount } from "../app/data-profile-view.js";
 import { tryQuery } from "../lib/db-result.js";
 export function queryRunCountsByAnalyses(pool, analysisIds) {
     if (analysisIds.length === 0)
@@ -41,19 +43,152 @@ export function queryThreadCountsByAnalyses(pool, analysisIds) {
         }));
     });
 }
+/** A plan title as text: trimmed with `trim()`, and `null` when it is blank. The SQL gives the title only when it is a string. */
+function titleOf(title) {
+    const trimmed = title?.trim() ?? "";
+    return trimmed === "" ? null : trimmed;
+}
+/**
+ * The columns of a run summary over a run alias `r`, and the plan alias `p` and
+ * the step count alias `s` of `RUN_PROGRESS_JOINS`. The two reads of a run
+ * summary put these after their own selection of `r`, thus the title rule and
+ * the step count rule have one text.
+ */
+const RUN_PROGRESS_COLUMNS = `r.analysis_id, r.run_id, r.status, r.started_at, r.completed_at,
+                    CASE WHEN jsonb_typeof(p.plan->'title') = 'string' THEN p.plan->>'title' END AS plan_title,
+                    s.done_steps, s.total_steps`;
+/** The plan join and the step count subquery for a run alias `r` that selects `analysis_id`, `run_id`, and `plan_id`. */
+const RUN_PROGRESS_JOINS = `LEFT JOIN cortex_plans p ON p.plan_id = r.plan_id AND p.analysis_id = r.analysis_id
+             CROSS JOIN LATERAL (
+                 SELECT COUNT(*)::int AS total_steps,
+                        (COUNT(*) FILTER (WHERE status = 'completed'))::int AS done_steps
+                 FROM cortex_step_executions
+                 WHERE run_id = r.run_id
+             ) s`;
+function toRunSummary(row) {
+    return {
+        analysisId: row.analysis_id,
+        runId: row.run_id,
+        status: row.status,
+        planTitle: titleOf(row.plan_title),
+        doneSteps: row.done_steps,
+        totalSteps: row.total_steps,
+        startedAt: row.started_at,
+        completedAt: row.completed_at,
+    };
+}
+/**
+ * The newest run of each analysis of a list, in one statement. An analysis with
+ * no run has no entry. The newest run has the latest `started_at`, and `run_id`
+ * breaks a tie in descending order. The `LATERAL` subquery reads
+ * `idx_cortex_runs_analysis_started`, thus one index entry for each analysis
+ * and not a sort of the run history.
+ *
+ * The plan joins on `plan_id` and `analysis_id`: a plan of a different analysis
+ * gives no title, the scope rule of `loadPlan`. The statement gives the title
+ * only when it is a string, and the row mapping trims it with `trim()`, the
+ * rule of the cli `planTitleOf`. A blank title or a title that is not a string
+ * reads as `null`. The step counts
+ * cover the ledger rows of the selected run only, the reserved synthesis row
+ * included.
+ */
+export function queryLatestRunsByAnalyses(pool, analysisIds) {
+    if (analysisIds.length === 0)
+        return okAsync([]);
+    return tryQuery("analysesMetrics.queryLatestRunsByAnalyses", async () => {
+        const result = await pool.query({
+            text: `SELECT ${RUN_PROGRESS_COLUMNS}
+             FROM unnest($1::text[]) AS a(id)
+             CROSS JOIN LATERAL (
+                 SELECT analysis_id, run_id, status, started_at, completed_at, plan_id
+                 FROM cortex_runs
+                 WHERE analysis_id = a.id
+                 ORDER BY started_at DESC, run_id DESC
+                 LIMIT 1
+             ) r
+             ${RUN_PROGRESS_JOINS}`,
+            values: [analysisIds],
+        });
+        return result.rows.map(toRunSummary);
+    });
+}
+/**
+ * The progress of each run of a list of run ids, in one statement. An id with
+ * no run row has no entry. The entries come newest first by `started_at`, and
+ * `run_id` breaks a tie in descending order. The plan title and the step counts
+ * follow the rules of `queryLatestRunsByAnalyses`, and each entry adds the
+ * thread of the run.
+ */
+export function queryRunProgressByRuns(pool, runIds) {
+    if (runIds.length === 0)
+        return okAsync([]);
+    return tryQuery("analysesMetrics.queryRunProgressByRuns", async () => {
+        const result = await pool.query({
+            text: `SELECT ${RUN_PROGRESS_COLUMNS}, r.thread_id
+             FROM cortex_runs r
+             ${RUN_PROGRESS_JOINS}
+             WHERE r.run_id = ANY($1::text[])
+             ORDER BY r.started_at DESC, r.run_id DESC`,
+            values: [runIds],
+        });
+        return result.rows.map((row) => ({ ...toRunSummary(row), threadId: row.thread_id }));
+    });
+}
+/**
+ * The newest `limit` terminal runs of every analysis that ended at or after
+ * `since`, newest completion first, with `run_id` breaking a tie in descending
+ * order. `since` is in the form of `toISOString()`, the form of each
+ * `completed_at` stamp, thus the text comparison is the time comparison. The
+ * statement walks `idx_cortex_runs_completed`.
+ */
+export function queryRunsEndedSince(pool, input) {
+    return tryQuery("analysesMetrics.queryRunsEndedSince", async () => {
+        const result = await pool.query({
+            text: `SELECT analysis_id, run_id, status, completed_at
+             FROM cortex_runs
+             WHERE status IN ('completed', 'partial', 'failed', 'canceled', 'suspended_insufficient_funds')
+               AND completed_at >= $1
+             ORDER BY completed_at DESC, run_id DESC
+             LIMIT $2`,
+            values: [input.since, input.limit],
+        });
+        return result.rows.map((row) => ({
+            analysisId: row.analysis_id,
+            runId: row.run_id,
+            status: row.status,
+            completedAt: row.completed_at,
+        }));
+    });
+}
+/**
+ * The profile state of each analysis of a list, in one statement. An analysis
+ * with no ledger row, or with a cleared row whose status is null, has no entry:
+ * the same collapsed absence as `loadDataProfileStatus`. The statement selects
+ * only the three parts of the stored result that the file count reads, and the
+ * count itself is `profileDatasetFileCount`.
+ */
 export function queryDataProfileStatusByAnalyses(pool, analysisIds) {
     if (analysisIds.length === 0)
         return okAsync([]);
     return tryQuery("analysesMetrics.queryDataProfileStatusByAnalyses", async () => {
         const result = await pool.query({
-            text: `SELECT analysis_id, data_profile_status
+            text: `SELECT analysis_id, data_profile_status, data_profile_completed_at,
+                    data_profile_result->'partition' AS partition,
+                    data_profile_result->'coverage' AS coverage,
+                    data_profile_result->'kinds' AS kinds
              FROM cortex_analysis_state
-             WHERE analysis_id = ANY($1::text[])`,
+             WHERE analysis_id = ANY($1::text[]) AND data_profile_status IS NOT NULL`,
             values: [analysisIds],
         });
         return result.rows.map((r) => ({
             analysisId: r.analysis_id,
-            status: r.data_profile_status ?? null,
+            status: r.data_profile_status,
+            completedAt: r.data_profile_completed_at ?? null,
+            profiledFiles: profileDatasetFileCount({
+                ...(r.partition === null ? {} : { partition: r.partition }),
+                ...(r.coverage === null ? {} : { coverage: r.coverage }),
+                ...(r.kinds === null ? {} : { kinds: r.kinds }),
+            }),
         }));
     });
 }

package/dist/state/artifacts.d.ts

@@ -5,7 +5,7 @@
 import type { ResultAsync } from "neverthrow";
 import { type DbError } from "../lib/db-result.js";
 import type { Querier } from "./db.js";
-import type { ArtifactRow } from "./schema.js";
+import type { ArtifactRole, ArtifactRow } from "./schema.js";
 export interface RegisterArtifactInput {
     resourceId: string;
     path: string;
@@ -75,8 +75,55 @@ export interface AnalysisArtifactRef {
  * false.
  */
 export declare function queryAnalysisArtifacts(pool: Querier, analysisId: string): ResultAsync<AnalysisArtifactRef[], DbError>;
-/** Count step-output artifacts produced by a run — for the run-completed card. */
-export declare function countArtifactsForRun(pool: Querier, analysisId: string, runId: string): ResultAsync<number, DbError>;
+/** The sort of {@link queryArtifactPage}: `path` is path order, `recent` is newest registration first. */
+export type ArtifactPageSort = "path" | "recent";
+/** The filters, the sort, and the window of {@link queryArtifactPage}. A filter that is absent selects each row. */
+export interface ArtifactPageQuery {
+    runId?: string;
+    stepId?: string;
+    fileType?: string;
+    /** A part of the path, with no regard to case. Each character matches only itself. */
+    q?: string;
+    sort: ArtifactPageSort;
+    limit: number;
+    offset: number;
+}
+/** One ledger row of {@link queryArtifactPage}. */
+export interface ArtifactPageEntry {
+    /** Workspace-root-relative path (`runs/{runId}/{stepId}/output/de.csv`). */
+    path: string;
+    /** Bytes. */
+    size: number;
+    fileType: string | null;
+    role: ArtifactRole;
+    runId: string | null;
+    stepId: string | null;
+    createdAt: string;
+}
+/** One page of the ledger, and the count of the rows that the filters select. */
+export interface ArtifactPage {
+    entries: ArtifactPageEntry[];
+    total: number;
+}
+/**
+ * One page of the artifact ledger of an analysis, in two statements: the count of the rows that the filters
+ * select, and the page. The count is a separate statement because a page past the end has no row to carry it.
+ *
+ * Every row of the analysis is a member, an `input` row and a row with `unrecoverable_at` included. The cost
+ * grows with the ledger of the one analysis, because the count reads each filtered row.
+ */
+export declare function queryArtifactPage(pool: Querier, analysisId: string, query: ArtifactPageQuery): ResultAsync<ArtifactPage, DbError>;
+/** The step-output count of one run, from {@link countArtifactsByRuns}. */
+export interface RunArtifactCount {
+    runId: string;
+    count: number;
+}
+/**
+ * The step-output count of each run of a list, in one statement. A run with no step output has no entry,
+ * and a caller reads it as 0. An `input` row never counts. The run-completed card and a list of runs use
+ * this one rule.
+ */
+export declare function countArtifactsByRuns(pool: Querier, analysisId: string, runIds: readonly string[]): ResultAsync<RunArtifactCount[], DbError>;
 export declare function updateArtifactId(pool: Querier, resourceId: string, path: string, artifactId: string, fileType?: string | null): ResultAsync<void, DbError>;
 export declare function updateFileIds(pool: Querier, pairs: Array<{
     artifactId: string;

package/dist/state/artifacts.js

@@ -179,16 +179,76 @@ export function queryAnalysisArtifacts(pool, analysisId) {
         return result.rows.map((r) => ({ path: r.path, hash: r.hash, fileType: r.file_type ?? null }));
     });
 }
-/** Count step-output artifacts produced by a run — for the run-completed card. */
-export function countArtifactsForRun(pool, analysisId, runId) {
-    return tryQuery("artifacts.countArtifactsForRun", async () => {
+/**
+ * One page of the artifact ledger of an analysis, in two statements: the count of the rows that the filters
+ * select, and the page. The count is a separate statement because a page past the end has no row to carry it.
+ *
+ * Every row of the analysis is a member, an `input` row and a row with `unrecoverable_at` included. The cost
+ * grows with the ledger of the one analysis, because the count reads each filtered row.
+ */
+export function queryArtifactPage(pool, analysisId, query) {
+    return tryQuery("artifacts.queryArtifactPage", async () => {
+        const values = [analysisId];
+        const conditions = ["analysis_id = $1"];
+        const bind = (value) => {
+            values.push(value);
+            return `$${values.length}`;
+        };
+        if (query.runId !== undefined)
+            conditions.push(`source_run = ${bind(query.runId)}`);
+        if (query.stepId !== undefined)
+            conditions.push(`source_step = ${bind(query.stepId)}`);
+        if (query.fileType !== undefined)
+            conditions.push(`file_type = ${bind(query.fileType)}`);
+        // `LIKE` would turn `%` and `_` of the input into wildcards.
+        if (query.q !== undefined)
+            conditions.push(`strpos(lower(path), lower(${bind(query.q)}::text)) > 0`);
+        const where = conditions.join(" AND ");
+        const countResult = await pool.query({
+            text: `SELECT COUNT(*)::int AS total FROM cortex_artifacts WHERE ${where}`,
+            values,
+        });
+        // `path` is unique in one analysis, thus it breaks each tie and two pages never overlap.
+        const order = query.sort === "recent" ? "created_at DESC, path ASC" : "path ASC";
+        const rowsResult = await pool.query({
+            text: `SELECT path, size, file_type, role, source_run, source_step, created_at
+          FROM cortex_artifacts
+          WHERE ${where}
+          ORDER BY ${order}
+          LIMIT ${bind(query.limit)} OFFSET ${bind(query.offset)}`,
+            values,
+        });
+        return {
+            entries: rowsResult.rows.map((r) => ({
+                path: r.path,
+                size: Number(r.size),
+                fileType: r.file_type ?? null,
+                role: r.role,
+                runId: r.source_run ?? null,
+                stepId: r.source_step ?? null,
+                createdAt: r.created_at,
+            })),
+            total: Number(countResult.rows[0]?.total ?? 0),
+        };
+    });
+}
+/**
+ * The step-output count of each run of a list, in one statement. A run with no step output has no entry,
+ * and a caller reads it as 0. An `input` row never counts. The run-completed card and a list of runs use
+ * this one rule.
+ */
+export function countArtifactsByRuns(pool, analysisId, runIds) {
+    return tryQuery("artifacts.countArtifactsByRuns", async () => {
+        if (runIds.length === 0)
+            return [];
         const result = await pool.query({
-            text: `SELECT COUNT(*)::text AS n
+            text: `SELECT source_run, COUNT(*)::int AS n
           FROM cortex_artifacts
-          WHERE analysis_id = $1 AND source_run = $2 AND role = 'step_output'`,
-            values: [analysisId, runId],
+          WHERE analysis_id = $1 AND source_run = ANY($2::text[]) AND role = 'step_output'
+          GROUP BY source_run`,
+            values: [analysisId, [...runIds]],
         });
-        return Number(result.rows[0]?.n ?? 0);
+        return result.rows.map((r) => ({ runId: r.source_run, count: Number(r.n) }));
     });
 }
 export function updateArtifactId(pool, resourceId, path, artifactId, fileType) {

package/dist/state/data-profile.d.ts

@@ -101,12 +101,14 @@ export declare function recordDataProfileWorkflowId(pool: Querier, analysisId: s
  * write per `running` claim, so `stamped: true` is the exactly-once point of a
  * profile's terminal transition. It carries the `data_profile_started_at` of the
  * claim it closed, so the caller measures the profile from the ledger's own start.
+ * It also carries the `data_profile_completed_at` that the write stamped.
  */
 export type DataProfileTerminalWrite = {
     readonly stamped: false;
 } | {
     readonly stamped: true;
     readonly startedAt: string | null;
+    readonly completedAt: string;
 };
 /**
  * Stamp a claimed-`running` row `completed` and record its result — a terminal
@@ -124,7 +126,7 @@ export type DataProfileTerminalWrite = {
  * guard only ever refuses a row another writer already moved on from.
  *
  * `stamped: true` when this call stamped the row, with the `data_profile_started_at`
- * of the claim it closed; `stamped: false` when the guard refused it (the row was
+ * of the claim it closed and the `data_profile_completed_at` it stamped; `stamped: false` when the guard refused it (the row was
  * cleared/expired/replayed away) — a no-op the caller logs, not an error.
  */
 export declare function completeDataProfile(pool: Querier, analysisId: string, result?: DataProfileResult): ResultAsync<DataProfileTerminalWrite, DbError>;
@@ -137,7 +139,7 @@ export declare function completeDataProfile(pool: Querier, analysisId: string, r
  * prior profile survives the failure (the re-profile/retry route can keep serving it).
  *
  * `stamped: true` when this call stamped the row, with the `data_profile_started_at`
- * of the claim it closed; `stamped: false` when the guard refused it — a logged
+ * of the claim it closed and the `data_profile_completed_at` it stamped; `stamped: false` when the guard refused it — a logged
  * no-op, not an error.
  */
 export declare function failDataProfile(pool: Querier, analysisId: string, error: string): ResultAsync<DataProfileTerminalWrite, DbError>;

package/dist/state/data-profile.js

@@ -144,7 +144,9 @@ export function recordDataProfileWorkflowId(pool, analysisId, workflowId) {
 }
 function terminalWriteOf(rows) {
     const row = rows[0];
-    return row === undefined ? { stamped: false } : { stamped: true, startedAt: row.data_profile_started_at ?? null };
+    return row === undefined
+        ? { stamped: false }
+        : { stamped: true, startedAt: row.data_profile_started_at ?? null, completedAt: row.data_profile_completed_at };
 }
 /**
  * Stamp a claimed-`running` row `completed` and record its result — a terminal
@@ -162,7 +164,7 @@ function terminalWriteOf(rows) {
  * guard only ever refuses a row another writer already moved on from.
  *
  * `stamped: true` when this call stamped the row, with the `data_profile_started_at`
- * of the claim it closed; `stamped: false` when the guard refused it (the row was
+ * of the claim it closed and the `data_profile_completed_at` it stamped; `stamped: false` when the guard refused it (the row was
  * cleared/expired/replayed away) — a no-op the caller logs, not an error.
  */
 export function completeDataProfile(pool, analysisId, result) {
@@ -173,7 +175,7 @@ export function completeDataProfile(pool, analysisId, result) {
             SET data_profile_status = 'completed', data_profile_completed_at = $1,
                 data_profile_result = $2::jsonb
             WHERE analysis_id = $3 AND data_profile_status = 'running'
-            RETURNING data_profile_started_at`,
+            RETURNING data_profile_started_at, data_profile_completed_at`,
             values: [now, result ? JSON.stringify(result) : null, analysisId],
         });
         return terminalWriteOf(res.rows);
@@ -188,7 +190,7 @@ export function completeDataProfile(pool, analysisId, result) {
  * prior profile survives the failure (the re-profile/retry route can keep serving it).
  *
  * `stamped: true` when this call stamped the row, with the `data_profile_started_at`
- * of the claim it closed; `stamped: false` when the guard refused it — a logged
+ * of the claim it closed and the `data_profile_completed_at` it stamped; `stamped: false` when the guard refused it — a logged
  * no-op, not an error.
  */
 export function failDataProfile(pool, analysisId, error) {
@@ -199,7 +201,7 @@ export function failDataProfile(pool, analysisId, error) {
             SET data_profile_status = 'failed', data_profile_error = $1,
                 data_profile_completed_at = $2
             WHERE analysis_id = $3 AND data_profile_status = 'running'
-            RETURNING data_profile_started_at`,
+            RETURNING data_profile_started_at, data_profile_completed_at`,
             values: [error, now, analysisId],
         });
         return terminalWriteOf(res.rows);

package/dist/state/index.d.ts

@@ -9,20 +9,21 @@
 export { initCortexState } from "./init.js";
 export type { Querier } from "./db.js";
 export { upsertAnalysis, suspendAnalysis, resumeAnalysis, loadAnalysisStatus } from "./analyses.js";
-export { upsertArtifact, upsertArtifacts, queryInputArtifacts, queryStepArtifactPaths, queryUnsyncedStepArtifacts, updateArtifactId, updateFileIds, countArtifactsForRun, } from "./artifacts.js";
-export type { RegisterArtifactInput, InputArtifactMeta, StepArtifactRef } from "./artifacts.js";
-export { insertRun, reserveRunById, RunDedupCollisionError, RunIdentityCollisionError, updateRunStatus, markRunCanceledIfActive, promoteFailedToPartial, setRunMandate, // oss-core-managed-ok: run-mandate ledger (nullable; OSS leaves null)
-setRunSynthesisOutcome, queryRun, queryActiveRun, queryNonTerminalRunsByAnalysis, queryRunsForInspection, queryRunsByAnalysis, queryRunsByThread, } from "./runs.js";
+export { upsertArtifact, upsertArtifacts, queryInputArtifacts, queryStepArtifactPaths, queryUnsyncedStepArtifacts, updateArtifactId, updateFileIds, queryArtifactPage, countArtifactsByRuns, } from "./artifacts.js";
+export type { RegisterArtifactInput, InputArtifactMeta, StepArtifactRef, ArtifactPage, ArtifactPageEntry, ArtifactPageQuery, ArtifactPageSort, RunArtifactCount, } from "./artifacts.js";
+export { insertRun, reserveRunById, RunDedupCollisionError, RunIdentityCollisionError, updateRunStatus, reconcileOrphanedRuns, ORPHANED_RUN_GRACE_MS, markRunCanceledIfActive, promoteFailedToPartial, setRunMandate, // oss-core-managed-ok: run-mandate ledger (nullable; OSS leaves null)
+setRunSynthesisOutcome, queryRun, queryActiveRun, queryNonTerminalRunsByAnalysis, queryRunsForInspection, queryRunsByAnalysis, queryRunsByThread, queryRunIdsByPlan, } from "./runs.js";
 export type { InsertRunInput, RunPage, RunReservation } from "./runs.js";
 export { insertStepExecution, seedStepExecutions, sweepPendingStepExecutions, updateStepExecution, queryStepsByRun } from "./step-executions.js";
 export type { InsertStepExecutionInput, SeedStepExecutionRow, UpdateStepExecutionInput } from "./step-executions.js";
 export { setSandboxRef, clearSandboxRef, reconcileReapedSandbox } from "./active-sandboxes.js";
-export { insertPlan, upsertPlan, loadPlan } from "./plans.js";
-export type { InsertPlanInput, UpsertPlanInput } from "./plans.js";
+export { insertPlan, upsertPlan, loadPlan, loadPlanRecord } from "./plans.js";
+export type { InsertPlanInput, UpsertPlanInput, PlanRecord } from "./plans.js";
 export { tryStartDataProfile, tryRetryDataProfile, tryRerunDataProfile, completeDataProfile, failDataProfile, expireStaleDataProfile, reconcileOrphanedDataProfile, clearDataProfile, completeEmptyDataProfile, loadDataProfileStatus, loadSeedInputFileIds, recordDataProfileWorkflowId, } from "./data-profile.js";
 export type { DataProfileStatus, DataProfileTerminalWrite, DataProfileResult, DataProfileChecked, DataProfileCompanionCompleteness, DataProfileDimension, DataProfileGroup, DataProfileGroupSlot, DataProfileFile, DataProfileMemberAnnotation, DataProfileObservation, DataProfilePartition, DataProfileProbeReport, DataProfileQualityAssessment, DataProfileQuarantine, DataProfileRecipeStep, DataProfileKind, DataProfileAxis, DataProfileInputSignature, DataProfileCoverage, } from "./data-profile.js";
-export { queryRunCountsByAnalyses, queryThreadCountsByAnalyses, queryDataProfileStatusByAnalyses } from "./analyses-metrics.js";
+export { queryRunCountsByAnalyses, queryThreadCountsByAnalyses, queryDataProfileStatusByAnalyses, queryLatestRunsByAnalyses, queryRunProgressByRuns, queryRunsEndedSince, } from "./analyses-metrics.js";
+export type { DataProfileSummary, EndedRunSummary, LatestRunSummary, RunProgressSummary } from "./analyses-metrics.js";
 export { createAnalysisPurge } from "./purge-analysis.js";
 export type { AnalysisPurge, AnalysisPurgeDeps, AnalysisPurgeOutcome } from "./purge-analysis.js";
 export { AnalysisStateRowSchema, ArtifactRole, ArtifactRowSchema, RunStatus, StepExecutionStatus, SynthesisStatus, CortexRunRowSchema, StepExecutionRowSchema, CortexPlanRowSchema, } from "./schema.js";
-export type { AnalysisStateRow, ArtifactRow, CortexRunRow, StepExecutionRow, CortexPlanRow } from "./schema.js";
+export type { AnalysisStateRow, ArtifactRow, CortexRunRow, StepExecutionRow, CortexPlanRow, TerminalRunStatus } from "./schema.js";

package/dist/state/index.js

@@ -8,14 +8,14 @@
  */
 export { initCortexState } from "./init.js";
 export { upsertAnalysis, suspendAnalysis, resumeAnalysis, loadAnalysisStatus } from "./analyses.js";
-export { upsertArtifact, upsertArtifacts, queryInputArtifacts, queryStepArtifactPaths, queryUnsyncedStepArtifacts, updateArtifactId, updateFileIds, countArtifactsForRun, } from "./artifacts.js";
-export { insertRun, reserveRunById, RunDedupCollisionError, RunIdentityCollisionError, updateRunStatus, markRunCanceledIfActive, promoteFailedToPartial, setRunMandate, // oss-core-managed-ok: run-mandate ledger (nullable; OSS leaves null)
-setRunSynthesisOutcome, queryRun, queryActiveRun, queryNonTerminalRunsByAnalysis, queryRunsForInspection, queryRunsByAnalysis, queryRunsByThread, } from "./runs.js";
+export { upsertArtifact, upsertArtifacts, queryInputArtifacts, queryStepArtifactPaths, queryUnsyncedStepArtifacts, updateArtifactId, updateFileIds, queryArtifactPage, countArtifactsByRuns, } from "./artifacts.js";
+export { insertRun, reserveRunById, RunDedupCollisionError, RunIdentityCollisionError, updateRunStatus, reconcileOrphanedRuns, ORPHANED_RUN_GRACE_MS, markRunCanceledIfActive, promoteFailedToPartial, setRunMandate, // oss-core-managed-ok: run-mandate ledger (nullable; OSS leaves null)
+setRunSynthesisOutcome, queryRun, queryActiveRun, queryNonTerminalRunsByAnalysis, queryRunsForInspection, queryRunsByAnalysis, queryRunsByThread, queryRunIdsByPlan, } from "./runs.js";
 export { insertStepExecution, seedStepExecutions, sweepPendingStepExecutions, updateStepExecution, queryStepsByRun } from "./step-executions.js";
 export { setSandboxRef, clearSandboxRef, reconcileReapedSandbox } from "./active-sandboxes.js";
-export { insertPlan, upsertPlan, loadPlan } from "./plans.js";
+export { insertPlan, upsertPlan, loadPlan, loadPlanRecord } from "./plans.js";
 export { tryStartDataProfile, tryRetryDataProfile, tryRerunDataProfile, completeDataProfile, failDataProfile, expireStaleDataProfile, reconcileOrphanedDataProfile, clearDataProfile, completeEmptyDataProfile, loadDataProfileStatus, loadSeedInputFileIds, recordDataProfileWorkflowId, } from "./data-profile.js";
-export { queryRunCountsByAnalyses, queryThreadCountsByAnalyses, queryDataProfileStatusByAnalyses } from "./analyses-metrics.js";
+export { queryRunCountsByAnalyses, queryThreadCountsByAnalyses, queryDataProfileStatusByAnalyses, queryLatestRunsByAnalyses, queryRunProgressByRuns, queryRunsEndedSince, } from "./analyses-metrics.js";
 // Not per-entity: one analysis's whole Postgres footprint, reached from its id
 // alone, with the workflow ledger behind an injected seam.
 export { createAnalysisPurge } from "./purge-analysis.js";

package/dist/state/migrations/20261012120000_index_the_runs_by_start.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Index the runs of an analysis by their start time, thus the read of the
+ * newest run of each analysis of a list reads one index entry for each
+ * analysis, and its cost does not grow with the run history. The index on
+ * `analysis_id` alone stays: a drop is a separate decision.
+ */
+import type { Migration } from "kysely/migration";
+export declare const indexTheRunsByStart: Migration;

package/dist/state/migrations/20261012120000_index_the_runs_by_start.js

@@ -0,0 +1,12 @@
+/**
+ * Index the runs of an analysis by their start time, thus the read of the
+ * newest run of each analysis of a list reads one index entry for each
+ * analysis, and its cost does not grow with the run history. The index on
+ * `analysis_id` alone stays: a drop is a separate decision.
+ */
+import { sql } from "kysely";
+export const indexTheRunsByStart = {
+    async up(db) {
+        await sql `CREATE INDEX IF NOT EXISTS idx_cortex_runs_analysis_started ON cortex_runs(analysis_id, started_at DESC, run_id DESC)`.execute(db);
+    },
+};

package/dist/state/migrations/20261013120000_index_the_ended_runs_and_the_recent_threads.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Index the runs by their completion time and the live threads by their update
+ * time, thus the reads over each analysis walk an index and do not sort the
+ * whole history. The thread index is partial on the live rows, the predicate of
+ * the read.
+ */
+import type { Migration } from "kysely/migration";
+export declare const indexTheEndedRunsAndTheRecentThreads: Migration;

package/dist/state/migrations/20261013120000_index_the_ended_runs_and_the_recent_threads.js

@@ -0,0 +1,13 @@
+/**
+ * Index the runs by their completion time and the live threads by their update
+ * time, thus the reads over each analysis walk an index and do not sort the
+ * whole history. The thread index is partial on the live rows, the predicate of
+ * the read.
+ */
+import { sql } from "kysely";
+export const indexTheEndedRunsAndTheRecentThreads = {
+    async up(db) {
+        await sql `CREATE INDEX IF NOT EXISTS idx_cortex_runs_completed ON cortex_runs(completed_at DESC, run_id DESC)`.execute(db);
+        await sql `CREATE INDEX IF NOT EXISTS idx_cortex_analysis_threads_recent ON cortex_analysis_threads(updated_at DESC, thread_id) WHERE deleted_at IS NULL`.execute(db);
+    },
+};

package/dist/state/migrations/20261013180000_narrow_the_active_run_index.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Narrow the one-active-run index to the `running` status. A run that a host
+ * suspended is terminal, thus it no longer blocks a new run of its plan. A drop
+ * and a new index replace the index, because Postgres cannot change the
+ * predicate of an index.
+ */
+import type { Migration } from "kysely/migration";
+export declare const narrowTheActiveRunIndex: Migration;

package/dist/state/migrations/20261013180000_narrow_the_active_run_index.js

@@ -0,0 +1,13 @@
+/**
+ * Narrow the one-active-run index to the `running` status. A run that a host
+ * suspended is terminal, thus it no longer blocks a new run of its plan. A drop
+ * and a new index replace the index, because Postgres cannot change the
+ * predicate of an index.
+ */
+import { sql } from "kysely";
+export const narrowTheActiveRunIndex = {
+    async up(db) {
+        await sql `DROP INDEX IF EXISTS idx_cortex_runs_active_plan`.execute(db);
+        await sql `CREATE UNIQUE INDEX idx_cortex_runs_active_plan ON cortex_runs(analysis_id, plan_id) WHERE status = 'running'`.execute(db);
+    },
+};

package/dist/state/migrations/20261014120000_index_the_plans_by_parent_and_the_runs_by_plan.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Index the plans by their parent, thus the read of the plan that replaced a
+ * plan, and the key check when a plan row goes away, read one index entry.
+ * Index the runs by their plan, thus the read of the run ids of a plan reads
+ * only the runs of that plan.
+ */
+import type { Migration } from "kysely/migration";
+export declare const indexThePlansByParentAndTheRunsByPlan: Migration;

package/dist/state/migrations/20261014120000_index_the_plans_by_parent_and_the_runs_by_plan.js

@@ -0,0 +1,13 @@
+/**
+ * Index the plans by their parent, thus the read of the plan that replaced a
+ * plan, and the key check when a plan row goes away, read one index entry.
+ * Index the runs by their plan, thus the read of the run ids of a plan reads
+ * only the runs of that plan.
+ */
+import { sql } from "kysely";
+export const indexThePlansByParentAndTheRunsByPlan = {
+    async up(db) {
+        await sql `CREATE INDEX IF NOT EXISTS idx_cortex_plans_parent ON cortex_plans(parent_plan_id)`.execute(db);
+        await sql `CREATE INDEX IF NOT EXISTS idx_cortex_runs_plan ON cortex_runs(analysis_id, plan_id, started_at DESC, run_id DESC)`.execute(db);
+    },
+};

package/dist/state/migrations/index.js

@@ -8,10 +8,18 @@
 import { baseline } from "./20260927120000_baseline.js";
 import { threadTitleSetByUser } from "./20260927180000_thread_title_set_by_user.js";
 import { dropActiveExecTracking } from "./20261005120000_drop_the_active_exec_tracking.js";
+import { indexTheRunsByStart } from "./20261012120000_index_the_runs_by_start.js";
+import { indexTheEndedRunsAndTheRecentThreads } from "./20261013120000_index_the_ended_runs_and_the_recent_threads.js";
+import { narrowTheActiveRunIndex } from "./20261013180000_narrow_the_active_run_index.js";
+import { indexThePlansByParentAndTheRunsByPlan } from "./20261014120000_index_the_plans_by_parent_and_the_runs_by_plan.js";
 export function cortexMigrations(logger) {
     return {
         "20260927120000_baseline": baseline(logger),
         "20260927180000_thread_title_set_by_user": threadTitleSetByUser,
         "20261005120000_drop_the_active_exec_tracking": dropActiveExecTracking,
+        "20261012120000_index_the_runs_by_start": indexTheRunsByStart,
+        "20261013120000_index_the_ended_runs_and_the_recent_threads": indexTheEndedRunsAndTheRecentThreads,
+        "20261013180000_narrow_the_active_run_index": narrowTheActiveRunIndex,
+        "20261014120000_index_the_plans_by_parent_and_the_runs_by_plan": indexThePlansByParentAndTheRunsByPlan,
     };
 }

package/dist/state/plans.d.ts

@@ -54,3 +54,24 @@ export declare function upsertPlan(pool: Querier, input: UpsertPlanInput): Resul
 export declare function loadPlan(pool: Querier, planId: string, opts: {
     analysisId: string;
 }): ResultAsync<unknown | null, DbError>;
+/** A stored plan with its lineage, as {@link loadPlanRecord} reads it. */
+export interface PlanRecord {
+    planId: string;
+    /** The stored document, as the store holds it. A reader parses it. */
+    plan: unknown;
+    parentPlanId: string | null;
+    /** The newest plan of the same analysis that names this plan as its parent. */
+    supersededBy: string | null;
+    createdAt: string;
+}
+/**
+ * Analysis-scoped read of one plan with its parent and the newest plan that
+ * replaced it, in one statement. Returns `ok(null)` for an unknown planId OR a
+ * planId of a different analysis, as {@link loadPlan} does.
+ *
+ * `created_at` is ISO 8601 text, thus the text order is the time order; the plan
+ * id breaks a tie so that the answer is stable.
+ */
+export declare function loadPlanRecord(pool: Querier, planId: string, opts: {
+    analysisId: string;
+}): ResultAsync<PlanRecord | null, DbError>;

package/dist/state/plans.js

@@ -115,3 +115,28 @@ export function loadPlan(pool, planId, opts) {
         return result.rows[0]?.plan ?? null;
     });
 }
+/**
+ * Analysis-scoped read of one plan with its parent and the newest plan that
+ * replaced it, in one statement. Returns `ok(null)` for an unknown planId OR a
+ * planId of a different analysis, as {@link loadPlan} does.
+ *
+ * `created_at` is ISO 8601 text, thus the text order is the time order; the plan
+ * id breaks a tie so that the answer is stable.
+ */
+export function loadPlanRecord(pool, planId, opts) {
+    return tryQuery("plans.loadPlanRecord", async () => {
+        const result = await pool.query({
+            text: `SELECT p.plan, p.parent_plan_id, p.created_at,
+                     (SELECT c.plan_id FROM cortex_plans c
+                       WHERE c.parent_plan_id = p.plan_id AND c.analysis_id = p.analysis_id
+                       ORDER BY c.created_at DESC, c.plan_id DESC LIMIT 1) AS superseded_by
+                FROM cortex_plans p
+               WHERE p.plan_id = $1 AND p.analysis_id = $2`,
+            values: [planId, opts.analysisId],
+        });
+        const row = result.rows[0];
+        if (!row)
+            return null;
+        return { planId, plan: row.plan, parentPlanId: row.parent_plan_id, supersededBy: row.superseded_by, createdAt: row.created_at };
+    });
+}