@inflexa-ai/harness 0.44.0 → 0.45.1

package/dist/schemas/workflow-state.js

@@ -6,6 +6,50 @@
  */
 import { z } from "zod";
 // ── Plan structures ─────────────────────────────────────────────────
+/**
+ * One scientific setting of a grounded step: a parameter of the procedure
+ * that `knowledge_recommend` returned, with the procedure step it belongs to
+ * and the source of its value. The host binds the settings to the template
+ * of the step at dispatch, thus a template default never replaces a plan
+ * decision silently.
+ */
+export const GroundingSettingSchema = z.object({
+    step: z.string().describe("The procedure step the setting belongs to (for example `differential_expression` or `normalize`)."),
+    name: z.string().describe("The parameter name as the procedure names it (for example `alpha` or `lfc_shrink`)."),
+    value: z.union([z.string(), z.number(), z.boolean(), z.array(z.string())]).describe("The value the procedure sets."),
+    source: z.string().optional().describe("The source of the value (a doi or a document) when the procedure names one. Absent otherwise."),
+});
+/**
+ * The grounding of one method step: the claim identifiers and the snapshot
+ * digest that `knowledge_recommend` returned in this run, the template the
+ * step renders, the settings of the procedure, and a one-line reason.
+ * Optional on both step schemas, thus a stored plan and a plan made without
+ * the knowledge service load and validate as before. Phase 0 validates the
+ * shape only. An empty field is visible: the evaluation counts a method step
+ * without a value as ungrounded.
+ */
+export const GroundingSchema = z.object({
+    status: z
+        .enum(["grounded", "ungrounded", "flagged"])
+        .describe("`grounded` when the step follows a returned procedure; `ungrounded` when no rule covered it or the service did not answer; `flagged` when a rule changed the outcome of the step."),
+    snapshot: z.string().describe("The `snapshot.digest` that `knowledge_recommend` returned in this run, or `none`."),
+    claims: z
+        .array(z.string())
+        .describe("The claim identifiers of the step as `knowledge_recommend` returned them (for example `R-0031@e7d0`). Empty when ungrounded."),
+    template: z
+        .string()
+        .optional()
+        .describe("The template id with its version (for example `tpl-deseq2-two-group@1.0.0`) when the step renders a template. Absent otherwise."),
+    settings: z
+        .array(GroundingSettingSchema)
+        .optional()
+        .describe("The scientific settings of the step: the parameters of the procedure steps the plan step holds, as `knowledge_recommend` returned them. " +
+        "Copy the `grounding.settings` of the skeleton step as it is, one entry per parameter, with its step, name, value, and source. " +
+        "Do not restate a setting as prose only, and do not change a value here: state a different value in the step and its reason. Absent when the step is ungrounded."),
+    reason: z
+        .string()
+        .describe("One line: the situation and the method with the rule that selects it, the side chosen for a disputed rule, or why the step is ungrounded or flagged."),
+});
 /**
  * A step of an analysis plan. `PlanStepSchema` (schemas/plan-schemas.ts) narrows
  * this into the planner's output contract and emits it as the `submit_plan`
@@ -52,8 +96,18 @@ export const AnalysisStepSchema = z.object({
     })
         .optional()
         .describe("Resources the step needs. Ground the estimate in the actual data size — see the resource-estimation rules."),
+    grounding: GroundingSchema.optional().describe("The knowledge grounding of a method step: fill it from the answer of `knowledge_recommend` when that tool is attached. Omit it when no knowledge tool is attached."),
     // Execution fields
     agent: z.string().optional().describe("Assigned sandbox agent name from registry"),
+    // Optional on the persistence schema so a plan stored before this field still parses.
+    // `PlanStepSchema` re-requires it for planner output. The launch reads it with the agent id to
+    // resolve what reference data the capability declares — refer to `capabilityDataRequirement`.
+    capability: z
+        .string()
+        .optional()
+        .describe("The one capability phrase of the assigned agent that this step uses, copied EXACTLY from the agent catalog. " +
+        "One phrase, verbatim — never a paraphrase, never a list, never your own wording. " +
+        "The launch resolves the reference data that the capability declares before the run starts, so a reworded phrase loses that check and the step discovers an absent source itself."),
     timeout: z.number().optional().describe("Execution timeout in seconds (falls back to image default)"),
     maxSteps: z.number().describe("Max LLM agentic steps for sandbox agent"),
     description: z.string().optional().describe("Human-readable description of what the step produces."),

package/dist/state/analyses-metrics.d.ts

@@ -1,11 +1,44 @@
 /**
- * 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 { type ResultAsync } from "neverthrow";
+import type { DataProfileLifecycleStatus } from "../contracts/data-profile.js";
 import { type DbError } from "../lib/db-result.js";
 import type { Querier } from "./db.js";
+import type { RunStatus, TerminalRunStatus } from "./schema.js";
+/** The newest run of one analysis, with the title of its plan and the counts of its step rows. */
+export interface LatestRunSummary {
+    readonly analysisId: string;
+    readonly runId: string;
+    readonly status: RunStatus;
+    readonly planTitle: string | null;
+    readonly doneSteps: number;
+    readonly totalSteps: number;
+    readonly startedAt: string;
+    readonly completedAt: string | null;
+}
+/** A run of a list of run ids, with the fields of the newest-run read and the thread of the run. */
+export interface RunProgressSummary extends LatestRunSummary {
+    /** The thread of the run as the ledger stores it, or `null`. */
+    readonly threadId: string | null;
+}
+/** A terminal run that ended at or after a time. */
+export interface EndedRunSummary {
+    readonly analysisId: string;
+    readonly runId: string;
+    readonly status: TerminalRunStatus;
+    readonly completedAt: string;
+}
+/** The data profile state of one analysis that has a profile status. */
+export interface DataProfileSummary {
+    readonly analysisId: string;
+    readonly status: DataProfileLifecycleStatus;
+    readonly completedAt: string | null;
+    readonly profiledFiles: number | null;
+}
 export declare function queryRunCountsByAnalyses(pool: Querier, analysisIds: string[]): ResultAsync<Array<{
     analysisId: string;
     status: string;
@@ -15,7 +48,46 @@ export declare function queryThreadCountsByAnalyses(pool: Querier, analysisIds:
     analysisId: string;
     count: number;
 }>, DbError>;
-export declare function queryDataProfileStatusByAnalyses(pool: Querier, analysisIds: string[]): ResultAsync<Array<{
-    analysisId: string;
-    status: string | null;
-}>, DbError>;
+/**
+ * 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 declare function queryLatestRunsByAnalyses(pool: Querier, analysisIds: string[]): ResultAsync<LatestRunSummary[], DbError>;
+/**
+ * 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 declare function queryRunProgressByRuns(pool: Querier, runIds: string[]): ResultAsync<RunProgressSummary[], DbError>;
+/**
+ * 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 declare function queryRunsEndedSince(pool: Querier, input: {
+    since: string;
+    limit: number;
+}): ResultAsync<EndedRunSummary[], DbError>;
+/**
+ * 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 declare function queryDataProfileStatusByAnalyses(pool: Querier, analysisIds: string[]): ResultAsync<DataProfileSummary[], DbError>;

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,71 @@ 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;
+    /** The whole path, with case. It selects the one row of that path. */
+    path?: string;
+    /**
+     * Extensions in lower case, with no dot. A row is selected when the extension of its path is a member. A row with
+     * no extension never matches, and an empty list selects each row. The read compares the members as they are.
+     */
+    extensions?: readonly 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;
+}
+/** The count of the selected rows that have one extension. */
+export interface ArtifactExtensionCount {
+    /** The extension in lower case with no dot, or `null` for the rows that have no extension. */
+    extension: string | null;
+    count: number;
+}
+/** One page of the ledger, and the count of the rows that the filters select. */
+export interface ArtifactPage {
+    entries: ArtifactPageEntry[];
+    total: number;
+    /** The selected rows by extension, in the order of the extension with `null` last. The counts sum to `total`. */
+    extensionCounts: ArtifactExtensionCount[];
+}
+/**
+ * One page of the artifact ledger of an analysis, in two statements: the count of the rows that the filters
+ * select, grouped by extension, and the page. The count is a separate statement because a page past the end has no
+ * row to carry it. `total` is the sum of the groups.
+ *
+ * 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,94 @@ 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 () => {
+/**
+ * The extension of `path` in lower case: the text after the last dot of the file name, which is the part after the
+ * last `/`. The pattern needs one character or more before that dot and one or more after it, thus a name with no dot,
+ * a name whose only dot is its first character, and a name that ends with a dot give `NULL`.
+ */
+const EXTENSION_SQL = `lower(substring(regexp_replace(path, '^.*/', '') from '^.+\\.([^.]+)$'))`;
+/**
+ * One page of the artifact ledger of an analysis, in two statements: the count of the rows that the filters
+ * select, grouped by extension, and the page. The count is a separate statement because a page past the end has no
+ * row to carry it. `total` is the sum of the groups.
+ *
+ * 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`);
+        if (query.path !== undefined)
+            conditions.push(`path = ${bind(query.path)}`);
+        if (query.extensions !== undefined && query.extensions.length > 0) {
+            conditions.push(`${EXTENSION_SQL} = ANY(${bind([...query.extensions])}::text[])`);
+        }
+        const where = conditions.join(" AND ");
+        const countResult = await pool.query({
+            text: `SELECT ${EXTENSION_SQL} AS extension, COUNT(*)::int AS n
+          FROM cortex_artifacts
+          WHERE ${where}
+          GROUP BY 1
+          ORDER BY 1 ASC NULLS LAST`,
+            values,
+        });
+        const extensionCounts = countResult.rows.map((r) => ({ extension: r.extension ?? null, count: Number(r.n) }));
+        // `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: extensionCounts.reduce((sum, e) => sum + e.count, 0),
+            extensionCounts,
+        };
+    });
+}
+/**
+ * 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, ArtifactExtensionCount, 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, countRunsByAnalysis, queryRunsByThread, queryRunIdsByPlan, queryNewestPlanRun, } 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";