@inflexa-ai/harness 0.1.1 → 0.3.0

package/dist/schemas/plan-schemas.d.ts

@@ -11,6 +11,13 @@ export declare const PlanStepSchema: z.ZodObject<{
     id: z.ZodString;
     context: z.ZodOptional<z.ZodString>;
     description: z.ZodOptional<z.ZodString>;
+    track: z.ZodString;
+    step_type: z.ZodString;
+    question: z.ZodString;
+    constraints: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    acceptance_criteria: z.ZodArray<z.ZodString>;
+    caveats: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    depends_on: z.ZodArray<z.ZodString>;
     resources: z.ZodNonOptional<z.ZodOptional<z.ZodObject<{
         cpu: z.ZodNumber;
         memoryGb: z.ZodNumber;
@@ -18,13 +25,6 @@ export declare const PlanStepSchema: z.ZodObject<{
             count: z.ZodNumber;
         }, z.core.$strip>>;
     }, z.core.$strip>>>;
-    constraints: z.ZodOptional<z.ZodArray<z.ZodString>>;
-    track: z.ZodString;
-    step_type: z.ZodString;
-    question: z.ZodString;
-    acceptance_criteria: z.ZodArray<z.ZodString>;
-    caveats: z.ZodOptional<z.ZodArray<z.ZodString>>;
-    depends_on: z.ZodArray<z.ZodString>;
     agent: z.ZodEnum<{
         [x: string]: string;
     }>;
@@ -43,6 +43,13 @@ export declare const PlannerPlanSchema: z.ZodObject<{
         id: z.ZodString;
         context: z.ZodOptional<z.ZodString>;
         description: z.ZodOptional<z.ZodString>;
+        track: z.ZodString;
+        step_type: z.ZodString;
+        question: z.ZodString;
+        constraints: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        acceptance_criteria: z.ZodArray<z.ZodString>;
+        caveats: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        depends_on: z.ZodArray<z.ZodString>;
         resources: z.ZodNonOptional<z.ZodOptional<z.ZodObject<{
             cpu: z.ZodNumber;
             memoryGb: z.ZodNumber;
@@ -50,13 +57,6 @@ export declare const PlannerPlanSchema: z.ZodObject<{
                 count: z.ZodNumber;
             }, z.core.$strip>>;
         }, z.core.$strip>>>;
-        constraints: z.ZodOptional<z.ZodArray<z.ZodString>>;
-        track: z.ZodString;
-        step_type: z.ZodString;
-        question: z.ZodString;
-        acceptance_criteria: z.ZodArray<z.ZodString>;
-        caveats: z.ZodOptional<z.ZodArray<z.ZodString>>;
-        depends_on: z.ZodArray<z.ZodString>;
         agent: z.ZodEnum<{
             [x: string]: string;
         }>;
@@ -84,6 +84,13 @@ export declare const PlanningAgentOutputSchema: z.ZodObject<{
             id: z.ZodString;
             context: z.ZodOptional<z.ZodString>;
             description: z.ZodOptional<z.ZodString>;
+            track: z.ZodString;
+            step_type: z.ZodString;
+            question: z.ZodString;
+            constraints: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            acceptance_criteria: z.ZodArray<z.ZodString>;
+            caveats: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            depends_on: z.ZodArray<z.ZodString>;
             resources: z.ZodNonOptional<z.ZodOptional<z.ZodObject<{
                 cpu: z.ZodNumber;
                 memoryGb: z.ZodNumber;
@@ -91,13 +98,6 @@ export declare const PlanningAgentOutputSchema: z.ZodObject<{
                     count: z.ZodNumber;
                 }, z.core.$strip>>;
             }, z.core.$strip>>>;
-            constraints: z.ZodOptional<z.ZodArray<z.ZodString>>;
-            track: z.ZodString;
-            step_type: z.ZodString;
-            question: z.ZodString;
-            acceptance_criteria: z.ZodArray<z.ZodString>;
-            caveats: z.ZodOptional<z.ZodArray<z.ZodString>>;
-            depends_on: z.ZodArray<z.ZodString>;
             agent: z.ZodEnum<{
                 [x: string]: string;
             }>;

package/dist/schemas/plan-schemas.js

@@ -19,13 +19,19 @@ export const PlanStepSchema = AnalysisStepSchema.omit({
 })
     .required({ agent: true, resources: true })
     .extend({
-    agent: z.enum(plannableAgentIds).describe("Sandbox agent ID from the available agents list"),
+    agent: z.enum(plannableAgentIds).describe("Sandbox agent ID, routed by the step's primary data object. Must be one of the available agents."),
 });
 /** Plan schema for planner output — uses PlanStepSchema for steps and requires
  *  a concise title (optional on the persistence schema for historical plans). */
 export const PlannerPlanSchema = AnalysisPlanSchema.extend({
-    title: z.string().min(1).max(80).describe("Concise human-readable plan name (3–8 words)"),
-    steps: z.array(PlanStepSchema),
+    title: z
+        .string()
+        .min(1)
+        .max(80)
+        .describe('Concise plan name (3–8 words) naming the analysis by what it does — e.g. "AD lesional vs control DE + pathways", ' +
+        '"scRNA immune deconvolution". Ground it in the actual research question and conditions; it is shown as the run\'s heading in chat. ' +
+        'Not a generic name like "Transcriptomics analysis".'),
+    steps: z.array(PlanStepSchema).describe("The steps of the plan, as a DAG wired by depends_on."),
 });
 /** Hydrate slim planner output into a full AnalysisPlan with execution-time defaults. */
 export function hydratePlanSteps(plannerPlan) {

package/dist/schemas/run-synthesis.d.ts

@@ -4,6 +4,10 @@
  * Produced by the synthesis step after all sandbox steps complete.
  * Combines computational findings from step summaries with literature
  * evidence from the literature-reviewer agent.
+ *
+ * This schema is the synthesizer's output contract: it is emitted as the
+ * `submit_synthesis` tool's arg schema, so every field's meaning must live in
+ * `.describe()` — a JSDoc comment here reaches no model.
  */
 import { z } from "zod";
 export declare const LiteratureReferenceSchema: z.ZodObject<{
@@ -27,11 +31,11 @@ export declare const SynthesizedFindingSchema: z.ZodObject<{
         low: "low";
     }>;
     noveltyStatus: z.ZodEnum<{
-        expected: "expected";
         novel: "novel";
         confirmed: "confirmed";
         partially_confirmed: "partially_confirmed";
         contradicted: "contradicted";
+        expected: "expected";
     }>;
     literatureInterpretation: z.ZodString;
     references: z.ZodArray<z.ZodObject<{
@@ -53,7 +57,6 @@ export declare const SynthesizedFindingSchema: z.ZodObject<{
             "clinical-evidence": "clinical-evidence";
         }>;
         actionType: z.ZodOptional<z.ZodEnum<{
-            none: "none";
             "therapeutic-target": "therapeutic-target";
             "predictive-biomarker": "predictive-biomarker";
             "prognostic-biomarker": "prognostic-biomarker";
@@ -62,6 +65,7 @@ export declare const SynthesizedFindingSchema: z.ZodObject<{
             "resistance-mechanism": "resistance-mechanism";
             "patient-stratification": "patient-stratification";
             "mechanism-of-action": "mechanism-of-action";
+            none: "none";
         }>>;
         rationale: z.ZodString;
     }, z.core.$strip>>;
@@ -88,11 +92,11 @@ export declare const RunSynthesisSchema: z.ZodObject<{
             low: "low";
         }>;
         noveltyStatus: z.ZodEnum<{
-            expected: "expected";
             novel: "novel";
             confirmed: "confirmed";
             partially_confirmed: "partially_confirmed";
             contradicted: "contradicted";
+            expected: "expected";
         }>;
         literatureInterpretation: z.ZodString;
         references: z.ZodArray<z.ZodObject<{
@@ -114,7 +118,6 @@ export declare const RunSynthesisSchema: z.ZodObject<{
                 "clinical-evidence": "clinical-evidence";
             }>;
             actionType: z.ZodOptional<z.ZodEnum<{
-                none: "none";
                 "therapeutic-target": "therapeutic-target";
                 "predictive-biomarker": "predictive-biomarker";
                 "prognostic-biomarker": "prognostic-biomarker";
@@ -123,6 +126,7 @@ export declare const RunSynthesisSchema: z.ZodObject<{
                 "resistance-mechanism": "resistance-mechanism";
                 "patient-stratification": "patient-stratification";
                 "mechanism-of-action": "mechanism-of-action";
+                none: "none";
             }>>;
             rationale: z.ZodString;
         }, z.core.$strip>>;

package/dist/schemas/run-synthesis.js

@@ -4,35 +4,51 @@
  * Produced by the synthesis step after all sandbox steps complete.
  * Combines computational findings from step summaries with literature
  * evidence from the literature-reviewer agent.
+ *
+ * This schema is the synthesizer's output contract: it is emitted as the
+ * `submit_synthesis` tool's arg schema, so every field's meaning must live in
+ * `.describe()` — a JSDoc comment here reaches no model.
  */
 import { z } from "zod";
 export const LiteratureReferenceSchema = z.object({
-    pmid: z.string(),
-    citation: z.string(),
-    relevance: z.string(),
-    concordance: z.enum(["supports", "contradicts", "extends", "contextualizes"]),
+    pmid: z.string().describe("Numeric PubMed ID. Must come from a literature_reviewer response — never invented."),
+    citation: z.string().describe('Short citation for the paper, e.g. "Smith 2020".'),
+    relevance: z.string().describe("Why this paper matters to the finding — what it establishes, challenges, or contextualizes."),
+    concordance: z
+        .enum(["supports", "contradicts", "extends", "contextualizes"])
+        .describe("How the paper relates to the finding. " +
+        "supports: the paper directly supports the finding. " +
+        "contradicts: the paper reports a conflicting result. " +
+        "extends: the paper builds on the finding in another context. " +
+        "contextualizes: the paper provides background but does not directly address the finding."),
 });
 export const SynthesizedFindingSchema = z.object({
-    /** Which step produced this finding. */
-    stepId: z.string(),
-    /** Finding title from the step summary. */
-    title: z.string(),
-    /** Finding description from the step summary. */
-    description: z.string(),
-    /** Confidence from the step summary. */
-    confidence: z.enum(["high", "medium", "low"]),
-    /** Novelty assessment based on literature review. */
-    noveltyStatus: z.enum(["novel", "confirmed", "partially_confirmed", "contradicted", "expected"]),
-    /** How this finding relates to existing literature. */
-    literatureInterpretation: z.string(),
-    /** Supporting or contradicting references. */
-    references: z.array(LiteratureReferenceSchema),
-    /** Translational proximity and actionability assessment. */
+    stepId: z.string().describe("Which step produced this finding. Must be a stepId present in the input summaries."),
+    title: z.string().describe("Finding title from the step summary."),
+    description: z.string().describe("Finding description from the step summary."),
+    confidence: z
+        .enum(["high", "medium", "low"])
+        .describe("Confidence from the step summary — reflect the summary's own stated confidence, not a re-assessment. " +
+        "If the summary states none, use medium; use high only for findings the summary treats as robust."),
+    noveltyStatus: z
+        .enum(["novel", "confirmed", "partially_confirmed", "contradicted", "expected"])
+        .describe("Novelty assessment based on literature review. " +
+        "novel: the literature does not describe this result in this context. " +
+        "confirmed: the literature independently establishes this result. " +
+        "partially_confirmed: the literature supports related but not identical claims (e.g. same gene, different tissue). " +
+        "contradicted: the literature reports the opposite direction or effect. " +
+        "expected: a standard, well-known result (housekeeping genes, canonical QC outcomes) — not a discovery."),
+    literatureInterpretation: z.string().describe("How this finding relates to existing literature."),
+    references: z.array(LiteratureReferenceSchema).describe("Supporting or contradicting references."),
     translationalRelevance: z
         .object({
-        /** How close this finding is to clinical application. */
-        stage: z.enum(["discovery", "preclinical-validation", "biomarker-candidate", "clinical-evidence"]),
-        /** What type of translational action this finding supports. */
+        stage: z
+            .enum(["discovery", "preclinical-validation", "biomarker-candidate", "clinical-evidence"])
+            .describe("How close this finding is to clinical application. " +
+            "discovery: novel biology with no direct clinical path yet. " +
+            "preclinical-validation: known target/pathway with existing preclinical evidence but no clinical data in this context. " +
+            "biomarker-candidate: measurable, differential, with a biologically plausible mechanism linking it to outcome. " +
+            "clinical-evidence: supported by or directly relevant to clinical trial data or approved therapeutics."),
         actionType: z
             .enum([
             "therapeutic-target",
@@ -45,43 +61,63 @@ export const SynthesizedFindingSchema = z.object({
             "mechanism-of-action",
             "none",
         ])
-            .optional(),
-        /** Brief rationale for the stage and action type. */
-        rationale: z.string(),
+            .optional()
+            .describe("What type of translational action this finding supports. " +
+            "therapeutic-target: gene/protein/pathway suitable for drug intervention. " +
+            "predictive-biomarker: differentiates treatment responders from non-responders (requires treatment x marker interaction evidence). " +
+            "prognostic-biomarker: predicts outcome regardless of treatment. " +
+            "pharmacodynamic-biomarker: measures target engagement or drug effect over time. " +
+            "safety-signal: suggests potential toxicity, adverse effect, or off-target liability. " +
+            "resistance-mechanism: explains non-response or acquired resistance. " +
+            "patient-stratification: enables subgroup identification for enrichment strategies. " +
+            "mechanism-of-action: illuminates how a drug or intervention works. " +
+            "none: biological value but no direct translational path."),
+        rationale: z
+            .string()
+            .describe("ONE sentence on why this stage and action type were assigned. " +
+            "Must reference specific evidence (existing drugs, clinical trials, biomarker properties, literature)."),
     })
-        .optional(),
+        .optional()
+        .describe("Translational proximity and actionability. Populate only for findings with genuine translational implications — " +
+        "omit for purely technical or methodological findings."),
 });
 export const BiologicalThemeSchema = z.object({
-    /** Theme name, e.g. "Immune dysregulation", "Metabolic reprogramming". */
-    name: z.string(),
-    /** Findings that contribute to this theme (by stepId + title). */
-    findings: z.array(z.object({ stepId: z.string(), title: z.string() })),
-    /** How these findings connect into a coherent biological story. */
-    narrative: z.string(),
+    name: z
+        .string()
+        .describe('Theme name — a conclusion, not a topic label. "ECM remodeling drives the NAFLD-to-NASH transition" is a theme; ' +
+        '"Differential expression results" is not.'),
+    findings: z
+        .array(z.object({ stepId: z.string(), title: z.string() }))
+        .describe("Findings that contribute to this theme. Each entry must match an entry in findings[] by stepId + title."),
+    narrative: z.string().describe("How these findings connect into a coherent biological story — 3-5 sentences connecting them, not restating them."),
 });
 export const RunSynthesisSchema = z.object({
-    runId: z.string(),
-    /** Brief (2-4 sentence) summary of the run's scope and top-line result. */
-    overview: z.string(),
-    /**
-     * Integrated interpretation: what the run establishes, what is novel,
-     * what is actionable from a translational perspective. This is the
-     * primary interpretive section — the "so what" of the analysis.
-     */
-    conclusions: z.string(),
-    /**
-     * Selective findings — only novel, contradicted, or high-impact results
-     * that warrant individual attention. NOT a per-step catalog.
-     */
-    findings: z.array(SynthesizedFindingSchema),
-    /** Cross-step biological themes. */
-    themes: z.array(BiologicalThemeSchema),
-    /** Methodological and translational caveats. */
-    limitations: z.array(z.string()),
-    /** Key references across all findings. */
-    keyReferences: z.array(z.object({
-        pmid: z.string(),
-        citation: z.string(),
-        description: z.string(),
-    })),
+    runId: z.string().describe("The run being synthesized. Must equal the runId given in the prompt."),
+    overview: z
+        .string()
+        .describe("2-4 sentences: the run's scope, the top-line result, and the most important takeaway. " +
+        "An abstract's conclusion, not its body — do NOT enumerate counts, gene lists, or per-step results."),
+    conclusions: z
+        .string()
+        .describe("The PRIMARY interpretive section — the 'so what' — as connected prose (3-5 paragraphs). " +
+        "What the run establishes and what is novel vs confirmatory; what is actionable translationally (therapeutic-target candidates, " +
+        "biomarker candidates, safety signals, resistance mechanisms); how findings connect into a biological story; where computational " +
+        "predictions agree or disagree with clinical evidence; and an honest assessment of the translational distance."),
+    findings: z
+        .array(SynthesizedFindingSchema)
+        .describe("SELECTIVE — only novel, contradicted, high-impact, or unexpected results that warrant individual attention. " +
+        "NOT a per-step catalog. Target 3-7 for a typical run."),
+    themes: z
+        .array(BiologicalThemeSchema)
+        .describe("Cross-step biological themes. Target 2-4. Return fewer (or zero) rather than forcing findings that do not converge."),
+    limitations: z
+        .array(z.string())
+        .describe("Concrete methodological and translational caveats — not generic disclaimers. " + "Each names what it affects and why it matters. Target 3-6."),
+    keyReferences: z
+        .array(z.object({
+        pmid: z.string().describe("Numeric PubMed ID. Must already appear in at least one finding's references[]."),
+        citation: z.string().describe('Short citation for the paper, e.g. "Smith 2020".'),
+        description: z.string().describe("What the paper establishes and why it is key to this run."),
+    }))
+        .describe("The 5-10 most important papers across all findings. Prioritize those that directly validate, contradict, or extend the findings — do not pad with background citations."),
 });

package/dist/schemas/validate-plan.js

@@ -26,7 +26,7 @@ export function deriveOutputPrefix(stepId) {
     return stepId
         .toLowerCase()
         .replace(/[^a-z0-9]+/g, "-")
-        .replace(/^-+|-+$/g, "");
+        .replace(/^-|-$/g, "");
 }
 /**
  * Validate an analysis plan for structural correctness.

package/dist/schemas/workflow-state.d.ts

@@ -5,6 +5,12 @@
  * and the completion schemas that validate LLM structured output.
  */
 import { z } from "zod";
+/**
+ * A step of an analysis plan. `PlanStepSchema` (schemas/plan-schemas.ts) narrows
+ * this into the planner's output contract and emits it as the `validate_plan` /
+ * `submit_plan` arg schema — so each field's meaning belongs in `.describe()`,
+ * not in a comment the model never sees.
+ */
 export declare const AnalysisStepSchema: z.ZodObject<{
     id: z.ZodString;
     name: z.ZodString;
@@ -220,8 +226,8 @@ export declare const SuspensionPayloadSchema: z.ZodObject<{
     message: z.ZodOptional<z.ZodString>;
     severity: z.ZodOptional<z.ZodEnum<{
         error: "error";
-        warning: "warning";
         info: "info";
+        warning: "warning";
     }>>;
     content: z.ZodOptional<z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
         type: z.ZodLiteral<"markdown">;

package/dist/schemas/workflow-state.js

@@ -6,17 +6,27 @@
  */
 import { z } from "zod";
 // ── Plan structures ─────────────────────────────────────────────────
+/**
+ * A step of an analysis plan. `PlanStepSchema` (schemas/plan-schemas.ts) narrows
+ * this into the planner's output contract and emits it as the `validate_plan` /
+ * `submit_plan` arg schema — so each field's meaning belongs in `.describe()`,
+ * not in a comment the model never sees.
+ */
 export const AnalysisStepSchema = z.object({
-    id: z.string().describe("Step ID in format T{track}S{step}"),
-    name: z.string(),
-    track: z.string(),
-    step_type: z.string(),
-    question: z.string(),
-    context: z.string().optional(),
-    constraints: z.array(z.string()).optional(),
-    acceptance_criteria: z.array(z.string()),
-    caveats: z.array(z.string()).optional(),
-    depends_on: z.array(z.string()),
+    id: z.string().describe("Step ID in format T{track}S{step} (e.g. T1S1, T1S2, T2S1). Unique within the plan and usable as a directory-name segment."),
+    name: z.string().describe("Short human-readable step name."),
+    track: z.string().describe("The track this step belongs to. Steps in the same track share a logical theme; steps in different tracks are independent."),
+    step_type: z.string().describe('Short label for the kind of work the step does (e.g. "analysis").'),
+    question: z
+        .string()
+        .describe("The specific question this step answers, framed with the actual condition names and comparisons from the experimental design."),
+    context: z.string().optional().describe("Background the sandbox agent needs to do the work."),
+    constraints: z.array(z.string()).optional().describe("Requirements the sandbox agent must follow exactly — not suggestions."),
+    acceptance_criteria: z.array(z.string()).describe("What the result must satisfy for the step to count as successful."),
+    caveats: z.array(z.string()).optional().describe("Pitfalls the sandbox agent should watch for."),
+    depends_on: z
+        .array(z.string())
+        .describe("IDs of steps in this plan that must complete before this one runs. Empty when the step has no prerequisites. The graph must be acyclic."),
     status: z.enum(["pending", "running", "completed", "failed", "skipped"]).default("pending"),
     // Optional on the persistence schema so historical plans (pre-resources)
     // still parse on the read side. `PlanStepSchema` re-requires it for planner
@@ -24,16 +34,17 @@ export const AnalysisStepSchema = z.object({
     // resources (no silent default) and clamps to cluster limits before use.
     resources: z
         .object({
-        cpu: z.number(),
-        memoryGb: z.number(),
-        gpu: z.object({ count: z.number() }).optional(),
+        cpu: z.number().describe("CPU cores the step needs."),
+        memoryGb: z.number().describe("Memory in GB the step needs."),
+        gpu: z.object({ count: z.number() }).optional().describe("GPUs the step needs. Omit unless the step genuinely requires one."),
     })
-        .optional(),
+        .optional()
+        .describe("Resources the step needs. Ground the estimate in the actual data size — see the resource-estimation rules."),
     // Execution fields
     agent: z.string().optional().describe("Assigned sandbox agent name from registry"),
     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 does"),
+    description: z.string().optional().describe("Human-readable description of what the step produces."),
     // Step result fields (populated during execution)
     summary: z.string().optional().describe("Execution result summary"),
     artifactIds: z.array(z.string()).optional().describe("Artifact IDs produced by this step"),
@@ -43,11 +54,14 @@ export const AnalysisPlanSchema = z.object({
     // Optional on the persistence schema so historical plans (pre-title) still
     // parse on the read side. `PlannerPlanSchema` re-requires it for new plans.
     title: z.string().optional().describe("Concise human-readable plan name"),
-    analytical_narrative: z.string(),
+    analytical_narrative: z
+        .string()
+        .describe("Brief narrative of the logical flow: why these steps, in this order, address the research question. " +
+        "Reference the data characteristics that informed the choices."),
     steps: z.array(AnalysisStepSchema),
-    created_at: z.string(),
-    omicsType: z.string().optional().describe("Detected omics data type (e.g., transcriptomics, proteomics)"),
-    omicsSubtype: z.string().optional().describe("Detected subtype (e.g., bulk-rna-seq, single-cell)"),
+    created_at: z.string().describe("ISO-8601 timestamp for when the plan was created."),
+    omicsType: z.string().optional().describe("Omics data type detected from the data context (e.g. transcriptomics, proteomics, metabolomics)."),
+    omicsSubtype: z.string().optional().describe("Subtype detected from the data context (e.g. bulk-rna-seq, single-cell, microarray)."),
 });
 // ── Suspension Payload ──────────────────────────────────────────────
 /**

package/dist/state/artifacts.d.ts

@@ -44,6 +44,19 @@ export interface InputArtifactMeta {
  */
 export declare function queryInputArtifacts(pool: Querier, analysisId: string, paths: string[]): Promise<InputArtifactMeta[]>;
 export declare function queryUnsyncedStepArtifacts(pool: Querier, resourceId: string, runId: string, stepId: string): Promise<ArtifactRow[]>;
+/** One registered step output, as a downstream consumer needs to name it. */
+export interface StepArtifactRef {
+    /** Workspace-root-relative path (`runs/{runId}/{stepId}/output/de.csv`). */
+    path: string;
+    fileType: string | null;
+}
+/**
+ * The artifacts a completed step registered, most consequential first. Ordered
+ * by artifact kind (outputs, then figures, notebooks, scripts, logs) and then by
+ * path, so a `limit` truncates the tail of the list rather than an arbitrary
+ * slice of it — and so the same call replays to the same rows.
+ */
+export declare function queryStepArtifactPaths(pool: Querier, resourceId: string, runId: string, stepId: string, limit: number): Promise<StepArtifactRef[]>;
 /** Count step-output artifacts produced by a run — for the run-completed card. */
 export declare function countArtifactsForRun(pool: Querier, analysisId: string, runId: string): Promise<number>;
 export declare function updateArtifactId(pool: Querier, resourceId: string, path: string, artifactId: string, fileType?: string | null): Promise<void>;

package/dist/state/artifacts.js

@@ -121,6 +121,33 @@ export async function queryUnsyncedStepArtifacts(pool, resourceId, runId, stepId
     });
     return result.rows.map(mapArtifactRow);
 }
+/**
+ * The artifacts a completed step registered, most consequential first. Ordered
+ * by artifact kind (outputs, then figures, notebooks, scripts, logs) and then by
+ * path, so a `limit` truncates the tail of the list rather than an arbitrary
+ * slice of it — and so the same call replays to the same rows.
+ */
+export async function queryStepArtifactPaths(pool, resourceId, runId, stepId, limit) {
+    if (limit <= 0)
+        return [];
+    const result = await pool.query({
+        text: `SELECT path, file_type
+          FROM cortex_artifacts
+          WHERE analysis_id = $1 AND source_run = $2 AND source_step = $3
+            AND role = 'step_output'
+          ORDER BY CASE file_type
+                     WHEN 'output' THEN 0
+                     WHEN 'figure' THEN 1
+                     WHEN 'notebook' THEN 2
+                     WHEN 'script' THEN 3
+                     ELSE 4
+                   END,
+                   path
+          LIMIT $4`,
+        values: [resourceId, runId, stepId, limit],
+    });
+    return result.rows.map((r) => ({ path: r.path, fileType: r.file_type ?? null }));
+}
 /** Count step-output artifacts produced by a run — for the run-completed card. */
 export async function countArtifactsForRun(pool, analysisId, runId) {
     const result = await pool.query({

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

@@ -5,6 +5,7 @@
  */
 import type { ResultAsync } from "neverthrow";
 import { type DbError } from "../lib/db-result.js";
+import type { Organism } from "../schemas/data-profile-schemas.js";
 import type { Querier } from "./db.js";
 /**
  * One profiled input file's **drift signature**. `fileId` is a path identity the
@@ -18,13 +19,53 @@ export interface DataProfileInputFile {
     size: number;
     mtimeMs: number;
 }
-/** The profile snapshot `completeDataProfile` persists and `loadDataProfileStatus` reads back. */
+/**
+ * One profiled file's persisted record.
+ *
+ * `path` + `description` are the original pair every snapshot carries. Everything
+ * below them is **optional on read** for the same reason `DataProfileResult.inputFiles`
+ * is: a snapshot written before the record was widened carries only the pair, and a
+ * reader must render that row rather than reject it. A writer fills in whatever the
+ * profiler reported.
+ */
+export interface DataProfileFile {
+    path: string;
+    description: string;
+    /** Semantic data type (count-matrix, variants, clinical-metadata, document, …). */
+    dataType?: string;
+    /** File format (CSV, h5ad, VCF, BAM, …). */
+    format?: string;
+    rows?: number | null;
+    cols?: number | null;
+    /** Searchable labels the profiler attached. */
+    tags?: string[];
+    /** Quality issues specific to this file. */
+    warnings?: string[];
+    /** Flat format-specific metrics (sparsity, medianLibrarySize, tiTvRatio, …). */
+    metrics?: Record<string, string | number | boolean>;
+}
+/** Dataset-wide quality findings the profiler recorded. */
+export interface DataProfileQualityAssessment {
+    concerns: string[];
+    strengths: string[];
+}
+/**
+ * The profile snapshot `completeDataProfile` persists and `loadDataProfileStatus` reads back.
+ *
+ * This row is the **only** durable home of the profile: the profiler's `runs/data-profile/`
+ * scratch tree is wiped when profiling completes, so there is no file to fall back on. It
+ * therefore carries the profiler's full finding, not a summary of it — anything dropped here
+ * is destroyed, and a downstream agent can only recover it by re-reading the raw input files.
+ *
+ * Every field past `summary` / `files` / `inputFileIds` / `profiledAt` is **optional on read**:
+ * a snapshot written before the record was widened carries only those four, and a reader must
+ * render it rather than throw. There is no parse at the read boundary (the jsonb column is cast
+ * straight to this type), so optionality *is* the compatibility mechanism — exactly as it
+ * already is for `inputFiles`.
+ */
 export interface DataProfileResult {
     summary: string;
-    files: Array<{
-        path: string;
-        description: string;
-    }>;
+    files: DataProfileFile[];
     /** Which files the profile covered — the audit record. */
     inputFileIds: string[];
     /**
@@ -35,6 +76,24 @@ export interface DataProfileResult {
      */
     inputFiles?: DataProfileInputFile[];
     profiledAt: string;
+    /** Scientific domain (transcriptomics, cheminformatics, clinical, …). */
+    domain?: string;
+    /** Specific subtype within the domain (bulk-rna-seq, single-cell, LC-MS/MS, …). */
+    subtype?: string;
+    /**
+     * Subject organism with its provenance and confidence. Explicit `null` is a real,
+     * distinct value — the profiler looked and no input identified an organism — as
+     * opposed to absent, which means the snapshot predates this field.
+     */
+    organism?: Organism | null;
+    tissue?: string | null;
+    cellType?: string | null;
+    condition?: string | null;
+    /** Public dataset accessions found in any input (GSE/SRP/PRJNA/E-MTAB/phs/EGAS). */
+    accessions?: string[];
+    /** Conditions, groups, comparisons, replicates, pairing. */
+    experimentalDesign?: string;
+    qualityAssessment?: DataProfileQualityAssessment;
 }
 export interface DataProfileStatus {
     status: "pending" | "running" | "completed" | "failed";

package/dist/state/index.d.ts

@@ -9,8 +9,8 @@
 export { initCortexState } from "./init.js";
 export type { Querier } from "./db.js";
 export { upsertAnalysis, resolveAnalysisBilling, suspendAnalysis, resumeAnalysis, loadAnalysisStatus } from "./analyses.js";
-export { upsertArtifact, upsertArtifacts, queryInputArtifacts, queryUnsyncedStepArtifacts, updateArtifactId, updateFileIds, countArtifactsForRun, } from "./artifacts.js";
-export type { RegisterArtifactInput, InputArtifactMeta } from "./artifacts.js";
+export { upsertArtifact, upsertArtifacts, queryInputArtifacts, queryStepArtifactPaths, queryUnsyncedStepArtifacts, updateArtifactId, updateFileIds, countArtifactsForRun, } from "./artifacts.js";
+export type { RegisterArtifactInput, InputArtifactMeta, StepArtifactRef } from "./artifacts.js";
 export { insertRun, RunDedupCollisionError, updateRunStatus, promoteFailedToPartial, setRunMandate, // oss-core-managed-ok: run-mandate ledger (nullable; OSS leaves null)
 queryRun, queryActiveRun, queryRunsByAnalysis, queryRunsByThread, } from "./runs.js";
 export type { InsertRunInput } from "./runs.js";
@@ -21,7 +21,7 @@ export type { ActiveSandboxRow } from "./active-sandboxes.js";
 export { insertPlan, loadPlan } from "./plans.js";
 export type { InsertPlanInput } from "./plans.js";
 export { tryStartDataProfile, tryRetryDataProfile, tryRerunDataProfile, completeDataProfile, failDataProfile, expireStaleDataProfile, reconcileOrphanedDataProfile, clearDataProfile, loadDataProfileStatus, loadSeedInputFileIds, } from "./data-profile.js";
-export type { DataProfileStatus, DataProfileResult, DataProfileInputFile } from "./data-profile.js";
+export type { DataProfileStatus, DataProfileResult, DataProfileInputFile, DataProfileFile, DataProfileQualityAssessment } from "./data-profile.js";
 export { queryRunCountsByAnalyses, queryThreadCountsByAnalyses, queryDataProfileStatusByAnalyses } from "./analyses-metrics.js";
 export { AnalysisStateRowSchema, ArtifactRole, ArtifactRowSchema, RunStatus, StepExecutionStatus, CortexRunRowSchema, StepExecutionRowSchema, CortexPlanRowSchema, } from "./schema.js";
 export type { AnalysisStateRow, ArtifactRow, CortexRunRow, StepExecutionRow, CortexPlanRow } from "./schema.js";