@patronage/factory-ci 1.0.0-alpha.6 → 1.0.0-alpha.8

package/dist/index.d.ts

@@ -324,6 +324,13 @@ declare const FACTORY_PROOF_GATE_CHECK_NAME = "patronage-factory/pr-verify";
 declare const FACTORY_PROOF_GATE_APP_ID = "4314840";
 /** Step id the guard condition refers to. */
 declare const FACTORY_PROOF_GATE_STEP_ID = "factory-proof";
+/**
+ * Human-visible name of the gate step as the Actions jobs API serves it. A
+ * read-only run analyzer (`psf ci:analyze`, #647) matches on this name to
+ * classify a run as proof-reuse versus full fallback, so it is exported from
+ * exactly the module that writes it — matching on a re-typed copy would drift.
+ */
+declare const FACTORY_PROOF_GATE_STEP_NAME = "Check for factory proof of this head";
 /**
  * The shell the gate runs under, and it is a correctness requirement rather
  * than a preference.
@@ -750,6 +757,26 @@ declare const writeVitestProfile: (outputPath: string, profile: VitestProfile) =
  */
 declare const runVitestProfile: (options: VitestProfileOptions, dependencies?: VitestProfileDependencies) => Promise<VitestProfile>;
 //#endregion
+//#region src/vitest-profile-reader.d.ts
+/**
+ * Outcome of reading one candidate document. `unrecognized` carries the first
+ * reason the document failed — an analyzer reports it verbatim rather than
+ * treating an unreadable profile as an empty one.
+ */
+type VitestProfileReadResult = {
+  kind: "profile";
+  profile: VitestProfile;
+} | {
+  kind: "unrecognized";
+  reason: string;
+};
+/**
+ * Check one parsed JSON document against the profile contract the writer
+ * emits. Returns the typed profile on success and the first mismatch reason
+ * otherwise — never a partially-usable value.
+ */
+declare const readVitestProfileDocument: (value: unknown) => VitestProfileReadResult;
+//#endregion
 //#region src/workflow-shell-lint.d.ts
 /**
  * Parse-check the shell embedded in generated workflow YAML (#376).
@@ -801,4 +828,4 @@ declare const assertWorkflowShellParses: (yaml: string, options: {
   readonly source: string;
 }) => void;
 //#endregion
-export { type BundleAlchemyEntryOptions, type CheckoutStepOptions, type ExecuteAlchemyEntryOptions, type ExecuteAlchemyEntryResult, FACTORY_PROOF_GATE_APP_ID, FACTORY_PROOF_GATE_CHECK_NAME, FACTORY_PROOF_GATE_GUARD, FACTORY_PROOF_GATE_IF, FACTORY_PROOF_GATE_MODE_OUTPUT, FACTORY_PROOF_GATE_OUTPUT, FACTORY_PROOF_GATE_REASONS, FACTORY_PROOF_GATE_REASON_OUTPUT, FACTORY_PROOF_GATE_SHELL, FACTORY_PROOF_GATE_STEP_ID, type FactoryProofGateOptions, type FactoryProofGateReason, type FactoryProofGateStep, type FactoryWorkflowArtifact, type FactoryWorkflowOptions, type FactoryWorkflowSetupOptions, GitHubApiError, type GithubAppCredentials, type GithubAppTokenOptions, type InstallStepOptions, type LocalPreviewStage, type LocalPreviewStageOptions, NODE_PNPM_ACTION_FAMILY_NODE24, type NodePnpmActionFamily, type ParseLocalPreviewStageExpected, type ParsedLocalPreviewStage, type PinnedAction, type ProofReuseCommand, type ProofReuseCoverageInput, type ProofReuseCoverageReport, type SetupNodeStepOptions, VITEST_PROFILE_SCHEMA_VERSION, VITEST_PROFILE_TOOL, type VitestJsonReport, type VitestProfile, type VitestProfileDependencies, type VitestProfileDurationSummary, type VitestProfileEnvironment, VitestProfileError, type VitestProfileOptions, type VitestProfileSample, type VitestProfileSampleExecution, type VitestTestStatus, type WorkflowShellParseFailure, type WorkflowStep, assertProofReuseCoverage, assertWorkflowShellParses, bundleAlchemyEntry, captureVitestProfileEnvironment, executeAlchemyEntry, factoryProofGateScript, factoryProofGateStep, factoryWorkflow, githubAppJwt, isLocalPreviewStage, localPreviewStage, mintInstallationToken, normalizeVitestProfileSample, parseLocalPreviewStage, proofReuseCoverage, proofReuseRequiredCommands, resolveProofReuseCommands, runVitestProfile, workflowRunBlocks, workflowShellParseFailures, writeVitestProfile };
+export { type BundleAlchemyEntryOptions, type CheckoutStepOptions, type ExecuteAlchemyEntryOptions, type ExecuteAlchemyEntryResult, FACTORY_PROOF_GATE_APP_ID, FACTORY_PROOF_GATE_CHECK_NAME, FACTORY_PROOF_GATE_GUARD, FACTORY_PROOF_GATE_IF, FACTORY_PROOF_GATE_MODE_OUTPUT, FACTORY_PROOF_GATE_OUTPUT, FACTORY_PROOF_GATE_REASONS, FACTORY_PROOF_GATE_REASON_OUTPUT, FACTORY_PROOF_GATE_SHELL, FACTORY_PROOF_GATE_STEP_ID, FACTORY_PROOF_GATE_STEP_NAME, type FactoryProofGateOptions, type FactoryProofGateReason, type FactoryProofGateStep, type FactoryWorkflowArtifact, type FactoryWorkflowOptions, type FactoryWorkflowSetupOptions, GitHubApiError, type GithubAppCredentials, type GithubAppTokenOptions, type InstallStepOptions, type LocalPreviewStage, type LocalPreviewStageOptions, NODE_PNPM_ACTION_FAMILY_NODE24, type NodePnpmActionFamily, type ParseLocalPreviewStageExpected, type ParsedLocalPreviewStage, type PinnedAction, type ProofReuseCommand, type ProofReuseCoverageInput, type ProofReuseCoverageReport, type SetupNodeStepOptions, VITEST_PROFILE_SCHEMA_VERSION, VITEST_PROFILE_TOOL, type VitestJsonReport, type VitestProfile, type VitestProfileDependencies, type VitestProfileDurationSummary, type VitestProfileEnvironment, VitestProfileError, type VitestProfileOptions, type VitestProfileReadResult, type VitestProfileSample, type VitestProfileSampleExecution, type VitestTestStatus, type WorkflowShellParseFailure, type WorkflowStep, assertProofReuseCoverage, assertWorkflowShellParses, bundleAlchemyEntry, captureVitestProfileEnvironment, executeAlchemyEntry, factoryProofGateScript, factoryProofGateStep, factoryWorkflow, githubAppJwt, isLocalPreviewStage, localPreviewStage, mintInstallationToken, normalizeVitestProfileSample, parseLocalPreviewStage, proofReuseCoverage, proofReuseRequiredCommands, readVitestProfileDocument, resolveProofReuseCommands, runVitestProfile, workflowRunBlocks, workflowShellParseFailures, writeVitestProfile };

package/dist/index.js

@@ -435,6 +435,13 @@ const FACTORY_PROOF_GATE_APP_ID = "4314840";
 /** Step id the guard condition refers to. */
 const FACTORY_PROOF_GATE_STEP_ID = "factory-proof";
 /**
+* Human-visible name of the gate step as the Actions jobs API serves it. A
+* read-only run analyzer (`psf ci:analyze`, #647) matches on this name to
+* classify a run as proof-reuse versus full fallback, so it is exported from
+* exactly the module that writes it — matching on a re-typed copy would drift.
+*/
+const FACTORY_PROOF_GATE_STEP_NAME = "Check for factory proof of this head";
+/**
 * The shell the gate runs under, and it is a correctness requirement rather
 * than a preference.
 *
@@ -906,7 +913,7 @@ const factoryProofGateStep = (options) => Object.freeze({
 	}),
 	id: FACTORY_PROOF_GATE_STEP_ID,
 	if: FACTORY_PROOF_GATE_IF,
-	name: "Check for factory proof of this head",
+	name: FACTORY_PROOF_GATE_STEP_NAME,
 	run: factoryProofGateScript(options),
 	shell: FACTORY_PROOF_GATE_SHELL
 });
@@ -1261,6 +1268,120 @@ const runVitestProfile = async (options, dependencies = {}) => {
 	return profile;
 };
 //#endregion
+//#region src/vitest-profile-reader.ts
+const isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+const isFiniteNumber = (value) => typeof value === "number" && Number.isFinite(value);
+const durationSummaryFailure = (value, where) => {
+	if (!isRecord(value)) return `${where} is not an object`;
+	const missing = [
+		"maximum",
+		"mean",
+		"median",
+		"minimum"
+	].find((field) => !isFiniteNumber(value[field]));
+	return missing === void 0 ? void 0 : `${where}.${missing} is not a finite number`;
+};
+const environmentFailure = (value) => {
+	if (!isRecord(value)) return "environment is not an object";
+	if (!(typeof value.cpuModel === "string" || value.cpuModel === null)) return "environment.cpuModel is neither a string nor null";
+	if (!isFiniteNumber(value.cpuCount)) return "environment.cpuCount is not a finite number";
+};
+/** The count fields the writer emits; every one must be a finite number. */
+const COUNT_FIELDS = [
+	"failed",
+	"passed",
+	"pending",
+	"suites",
+	"tests",
+	"todo"
+];
+const runFailure = (value, index) => {
+	if (!isRecord(value)) return `runs[${index}] is not an object`;
+	if (!isFiniteNumber(value.durationMs)) return `runs[${index}].durationMs is not a finite number`;
+	if (value.counts === null) return;
+	if (!isRecord(value.counts)) return `runs[${index}].counts is neither an object nor null`;
+	const { counts } = value;
+	const missing = COUNT_FIELDS.find((field) => !isFiniteNumber(counts[field]));
+	return missing === void 0 ? void 0 : `runs[${index}].counts.${missing} is not a finite number`;
+};
+const slowEntryFailure = (value, where, labelField) => {
+	if (!isRecord(value)) return `${where} is not an object`;
+	if (typeof value[labelField] !== "string") return `${where}.${labelField} is not a string`;
+	if (labelField === "name" && typeof value.file !== "string") return `${where}.file is not a string`;
+	return durationSummaryFailure(value.durationMs, `${where}.durationMs`);
+};
+const summaryFailure = (value) => {
+	if (!isRecord(value)) return "summary is not an object";
+	const durations = durationSummaryFailure(value.durationMs, "summary.durationMs");
+	if (durations !== void 0) return durations;
+	if (!Array.isArray(value.slowFiles)) return "summary.slowFiles is not an array";
+	for (const [index, entry] of value.slowFiles.entries()) {
+		const failure = slowEntryFailure(entry, `summary.slowFiles[${index}]`, "path");
+		if (failure !== void 0) return failure;
+	}
+	if (!Array.isArray(value.slowTests)) return "summary.slowTests is not an array";
+	for (const [index, entry] of value.slowTests.entries()) {
+		const failure = slowEntryFailure(entry, `summary.slowTests[${index}]`, "name");
+		if (failure !== void 0) return failure;
+	}
+};
+/**
+* Check one parsed JSON document against the profile contract the writer
+* emits. Returns the typed profile on success and the first mismatch reason
+* otherwise — never a partially-usable value.
+*/
+const readVitestProfileDocument = (value) => {
+	if (!isRecord(value)) return {
+		kind: "unrecognized",
+		reason: "the document is not an object"
+	};
+	if (value.tool !== "factory-ci-vitest-profile") return {
+		kind: "unrecognized",
+		reason: `tool is ${JSON.stringify(value.tool)} rather than "${VITEST_PROFILE_TOOL}"`
+	};
+	if (value.schemaVersion !== 1) return {
+		kind: "unrecognized",
+		reason: `schemaVersion is ${JSON.stringify(value.schemaVersion)} rather than 1`
+	};
+	if (!(Array.isArray(value.command) && value.command.every((part) => typeof part === "string"))) return {
+		kind: "unrecognized",
+		reason: "command is not an array of strings"
+	};
+	const environment = environmentFailure(value.environment);
+	if (environment !== void 0) return {
+		kind: "unrecognized",
+		reason: environment
+	};
+	if (!isRecord(value.options)) return {
+		kind: "unrecognized",
+		reason: "options is not an object"
+	};
+	if (!isFiniteNumber(value.options.maxWorkers)) return {
+		kind: "unrecognized",
+		reason: "options.maxWorkers is not a finite number"
+	};
+	if (!Array.isArray(value.runs)) return {
+		kind: "unrecognized",
+		reason: "runs is not an array"
+	};
+	for (const [index, run] of value.runs.entries()) {
+		const failure = runFailure(run, index);
+		if (failure !== void 0) return {
+			kind: "unrecognized",
+			reason: failure
+		};
+	}
+	const summary = summaryFailure(value.summary);
+	if (summary !== void 0) return {
+		kind: "unrecognized",
+		reason: summary
+	};
+	return {
+		kind: "profile",
+		profile: value
+	};
+};
+//#endregion
 //#region src/workflow-shell-lint.ts
 const RUN_KEY = /^(?<indent>\s*)(?:-\s+)?run:(?<inline>.*)$/u;
 /**
@@ -1525,4 +1646,4 @@ const assertWorkflowShellParses = (yaml, options) => {
 	throw new Error(`${options.source} emits shell bash cannot parse; the runner would treat it as a no-op:\n${detail}`);
 };
 //#endregion
-export { FACTORY_PROOF_GATE_APP_ID, FACTORY_PROOF_GATE_CHECK_NAME, FACTORY_PROOF_GATE_GUARD, FACTORY_PROOF_GATE_IF, FACTORY_PROOF_GATE_MODE_OUTPUT, FACTORY_PROOF_GATE_OUTPUT, FACTORY_PROOF_GATE_REASONS, FACTORY_PROOF_GATE_REASON_OUTPUT, FACTORY_PROOF_GATE_SHELL, FACTORY_PROOF_GATE_STEP_ID, GitHubApiError, NODE_PNPM_ACTION_FAMILY_NODE24, VITEST_PROFILE_SCHEMA_VERSION, VITEST_PROFILE_TOOL, VitestProfileError, assertProofReuseCoverage, assertWorkflowShellParses, bundleAlchemyEntry, captureVitestProfileEnvironment, executeAlchemyEntry, factoryProofGateScript, factoryProofGateStep, factoryWorkflow, githubAppJwt, isLocalPreviewStage, localPreviewStage, mintInstallationToken, normalizeVitestProfileSample, parseLocalPreviewStage, proofReuseCoverage, proofReuseRequiredCommands, resolveProofReuseCommands, runVitestProfile, workflowRunBlocks, workflowShellParseFailures, writeVitestProfile };
+export { FACTORY_PROOF_GATE_APP_ID, FACTORY_PROOF_GATE_CHECK_NAME, FACTORY_PROOF_GATE_GUARD, FACTORY_PROOF_GATE_IF, FACTORY_PROOF_GATE_MODE_OUTPUT, FACTORY_PROOF_GATE_OUTPUT, FACTORY_PROOF_GATE_REASONS, FACTORY_PROOF_GATE_REASON_OUTPUT, FACTORY_PROOF_GATE_SHELL, FACTORY_PROOF_GATE_STEP_ID, FACTORY_PROOF_GATE_STEP_NAME, GitHubApiError, NODE_PNPM_ACTION_FAMILY_NODE24, VITEST_PROFILE_SCHEMA_VERSION, VITEST_PROFILE_TOOL, VitestProfileError, assertProofReuseCoverage, assertWorkflowShellParses, bundleAlchemyEntry, captureVitestProfileEnvironment, executeAlchemyEntry, factoryProofGateScript, factoryProofGateStep, factoryWorkflow, githubAppJwt, isLocalPreviewStage, localPreviewStage, mintInstallationToken, normalizeVitestProfileSample, parseLocalPreviewStage, proofReuseCoverage, proofReuseRequiredCommands, readVitestProfileDocument, resolveProofReuseCommands, runVitestProfile, workflowRunBlocks, workflowShellParseFailures, writeVitestProfile };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@patronage/factory-ci",
-  "version": "1.0.0-alpha.6",
+  "version": "1.0.0-alpha.8",
   "description": "Deep CI and deploy building blocks for Patronage factory projects: workflow source artifacts, hosted diff classification, Alchemy entry execution, and disposable-stage semantics",
   "keywords": [
     "alchemy",

package/src/index.ts

@@ -60,6 +60,7 @@ export {
   FACTORY_PROOF_GATE_REASONS,
   FACTORY_PROOF_GATE_SHELL,
   FACTORY_PROOF_GATE_STEP_ID,
+  FACTORY_PROOF_GATE_STEP_NAME,
   type FactoryProofGateOptions,
   type FactoryProofGateReason,
   factoryProofGateScript,
@@ -90,6 +91,10 @@ export {
   type VitestTestStatus,
   writeVitestProfile,
 } from "./vitest-profile.ts";
+export {
+  readVitestProfileDocument,
+  type VitestProfileReadResult,
+} from "./vitest-profile-reader.ts";
 export {
   assertWorkflowShellParses,
   workflowRunBlocks,

package/src/proof-reuse-gate.ts

@@ -57,6 +57,15 @@ export const FACTORY_PROOF_GATE_APP_ID = "4314840";
 /** Step id the guard condition refers to. */
 export const FACTORY_PROOF_GATE_STEP_ID = "factory-proof";
 
+/**
+ * Human-visible name of the gate step as the Actions jobs API serves it. A
+ * read-only run analyzer (`psf ci:analyze`, #647) matches on this name to
+ * classify a run as proof-reuse versus full fallback, so it is exported from
+ * exactly the module that writes it — matching on a re-typed copy would drift.
+ */
+export const FACTORY_PROOF_GATE_STEP_NAME =
+  "Check for factory proof of this head";
+
 /**
  * The shell the gate runs under, and it is a correctness requirement rather
  * than a preference.
@@ -619,7 +628,7 @@ export const factoryProofGateStep = (
     }),
     id: FACTORY_PROOF_GATE_STEP_ID,
     if: FACTORY_PROOF_GATE_IF,
-    name: "Check for factory proof of this head",
+    name: FACTORY_PROOF_GATE_STEP_NAME,
     run: factoryProofGateScript(options),
     // Never omit: the runner's default `run:` shell supplies `-e`, which
     // voids the fail-open design. See FACTORY_PROOF_GATE_SHELL.

package/src/vitest-profile-reader.test.ts

@@ -0,0 +1,208 @@
+import { describe, expect, it } from "vitest";
+
+import { readVitestProfileDocument } from "./vitest-profile-reader.ts";
+import type { VitestProfile } from "./vitest-profile.ts";
+
+const durations = {
+  maximum: 16_200,
+  mean: 15_800,
+  median: 15_700,
+  minimum: 15_300,
+};
+
+/** A document shaped exactly as `runVitestProfile` writes it. */
+const validProfile = (): VitestProfile => ({
+  command: ["vitest", "run", "--reporter=json", "--maxWorkers=2"],
+  endedAt: "2026-08-06T12:01:00.000Z",
+  environment: {
+    arch: "x64",
+    availableParallelism: 4,
+    cpuCount: 4,
+    cpuModel: "AMD EPYC 9R45",
+    gitDirty: false,
+    gitHead: "0123456789abcdef0123456789abcdef01234567",
+    node: "v24.0.0",
+    osRelease: "6.8.0",
+    platform: "linux",
+    totalMemoryBytes: 16_000_000_000,
+    vitest: "3.0.0",
+  },
+  options: { maxWorkers: 2, samples: 3, slowLimit: 20 },
+  rawReportDirectory: "/tmp/profile.raw/abc",
+  runs: [
+    {
+      counts: {
+        failed: 0,
+        passed: 900,
+        pending: 0,
+        suites: 80,
+        tests: 900,
+        todo: 0,
+      },
+      durationMs: 15_300,
+      endedAt: "2026-08-06T12:00:20.000Z",
+      exitCode: 0,
+      failure: null,
+      files: [{ durationMs: 900, path: "src/slow.test.ts", status: "passed" }],
+      reportAvailable: true,
+      sample: 1,
+      startedAt: "2026-08-06T12:00:00.000Z",
+      tests: [
+        {
+          durationMs: 450,
+          file: "src/slow.test.ts",
+          name: "slow case",
+          status: "passed",
+        },
+      ],
+    },
+  ],
+  schemaVersion: 1,
+  startedAt: "2026-08-06T12:00:00.000Z",
+  summary: {
+    durationMs: { ...durations },
+    slowFiles: [
+      { durationMs: { ...durations }, path: "src/slow.test.ts", samples: 3 },
+    ],
+    slowTests: [
+      {
+        durationMs: { ...durations },
+        file: "src/slow.test.ts",
+        name: "slow case",
+        samples: 3,
+      },
+    ],
+  },
+  tool: "factory-ci-vitest-profile",
+});
+
+describe("readVitestProfileDocument", () => {
+  it("accepts a document the writer emitted", () => {
+    const result = readVitestProfileDocument(validProfile());
+
+    expect(result.kind).toBe("profile");
+    if (result.kind === "profile") {
+      expect(result.profile.environment.cpuModel).toBe("AMD EPYC 9R45");
+      expect(result.profile.summary.durationMs.median).toBe(15_700);
+    }
+  });
+
+  it("names the tool mismatch instead of guessing", () => {
+    const result = readVitestProfileDocument({
+      ...validProfile(),
+      tool: "someone-elses-artifact",
+    });
+
+    expect(result).toEqual({
+      kind: "unrecognized",
+      reason:
+        'tool is "someone-elses-artifact" rather than "factory-ci-vitest-profile"',
+    });
+  });
+
+  it("refuses a future schema version rather than misreading it", () => {
+    const result = readVitestProfileDocument({
+      ...validProfile(),
+      schemaVersion: 2,
+    });
+
+    expect(result).toEqual({
+      kind: "unrecognized",
+      reason: "schemaVersion is 2 rather than 1",
+    });
+  });
+
+  it("refuses a document whose environment lost the cpuModel field", () => {
+    const document = validProfile() as unknown as {
+      environment: Record<string, unknown>;
+    };
+    delete document.environment.cpuModel;
+
+    expect(readVitestProfileDocument(document)).toEqual({
+      kind: "unrecognized",
+      reason: "environment.cpuModel is neither a string nor null",
+    });
+  });
+
+  it("refuses a run without a finite duration", () => {
+    const document = validProfile();
+    (document.runs[0] as unknown as Record<string, unknown>).durationMs =
+      "fast";
+
+    expect(readVitestProfileDocument(document)).toEqual({
+      kind: "unrecognized",
+      reason: "runs[0].durationMs is not a finite number",
+    });
+  });
+
+  it("refuses a summary without duration statistics", () => {
+    const document = validProfile() as unknown as {
+      summary: { durationMs: Record<string, unknown> };
+    };
+    delete document.summary.durationMs.median;
+
+    expect(readVitestProfileDocument(document)).toEqual({
+      kind: "unrecognized",
+      reason: "summary.durationMs.median is not a finite number",
+    });
+  });
+
+  it("refuses empty counts rather than serving undefined fields", () => {
+    const document = validProfile();
+    (document.runs[0] as unknown as Record<string, unknown>).counts = {};
+
+    expect(readVitestProfileDocument(document)).toEqual({
+      kind: "unrecognized",
+      reason: "runs[0].counts.failed is not a finite number",
+    });
+  });
+
+  it("refuses a null slowFiles entry rather than crashing projection", () => {
+    const document = validProfile() as unknown as {
+      summary: { slowFiles: unknown[] };
+    };
+    document.summary.slowFiles = [null];
+
+    expect(readVitestProfileDocument(document)).toEqual({
+      kind: "unrecognized",
+      reason: "summary.slowFiles[0] is not an object",
+    });
+  });
+
+  it("refuses a slow test whose duration summary is incomplete", () => {
+    const document = validProfile() as unknown as {
+      summary: { slowTests: { durationMs: Record<string, unknown> }[] };
+    };
+    const [slowTest] = document.summary.slowTests;
+    if (slowTest) {
+      delete slowTest.durationMs.median;
+    }
+
+    expect(readVitestProfileDocument(document)).toEqual({
+      kind: "unrecognized",
+      reason: "summary.slowTests[0].durationMs.median is not a finite number",
+    });
+  });
+
+  it("refuses a slow file without a path string", () => {
+    const document = validProfile() as unknown as {
+      summary: { slowFiles: Record<string, unknown>[] };
+    };
+    const [slowFile] = document.summary.slowFiles;
+    if (slowFile) {
+      delete slowFile.path;
+    }
+
+    expect(readVitestProfileDocument(document)).toEqual({
+      kind: "unrecognized",
+      reason: "summary.slowFiles[0].path is not a string",
+    });
+  });
+
+  it("refuses non-object input", () => {
+    expect(readVitestProfileDocument(null)).toEqual({
+      kind: "unrecognized",
+      reason: "the document is not an object",
+    });
+  });
+});

package/src/vitest-profile-reader.ts

@@ -0,0 +1,220 @@
+/**
+ * Read back a Vitest profile artifact (#647).
+ *
+ * `vitest-profile.ts` owns the writer; this module owns the matching
+ * schema-checked reader, so a consumer analyzing profile artifacts collected
+ * from CI (for example `psf ci:analyze`) never re-types the document shape.
+ * The reader is deliberately strict about the fields an analysis is built on —
+ * tool discriminator, schema version, environment capture, per-run durations,
+ * and the duration summary — and deliberately silent about everything else, so
+ * additive writer changes never invalidate old artifacts.
+ *
+ * Pure: no I/O, no dependencies. The caller decides where the bytes come from.
+ */
+
+import type {
+  VitestProfile,
+  VitestProfileDurationSummary,
+} from "./vitest-profile.ts";
+import {
+  VITEST_PROFILE_SCHEMA_VERSION,
+  VITEST_PROFILE_TOOL,
+} from "./vitest-profile.ts";
+
+/**
+ * Outcome of reading one candidate document. `unrecognized` carries the first
+ * reason the document failed — an analyzer reports it verbatim rather than
+ * treating an unreadable profile as an empty one.
+ */
+export type VitestProfileReadResult =
+  | { kind: "profile"; profile: VitestProfile }
+  | { kind: "unrecognized"; reason: string };
+
+const isRecord = (value: unknown): value is Record<string, unknown> =>
+  typeof value === "object" && value !== null && !Array.isArray(value);
+
+const isFiniteNumber = (value: unknown): value is number =>
+  typeof value === "number" && Number.isFinite(value);
+
+const durationSummaryFailure = (
+  value: unknown,
+  where: string
+): string | undefined => {
+  if (!isRecord(value)) {
+    return `${where} is not an object`;
+  }
+  const fields: (keyof VitestProfileDurationSummary)[] = [
+    "maximum",
+    "mean",
+    "median",
+    "minimum",
+  ];
+  const missing = fields.find((field) => !isFiniteNumber(value[field]));
+  return missing === undefined
+    ? undefined
+    : `${where}.${missing} is not a finite number`;
+};
+
+const environmentFailure = (value: unknown): string | undefined => {
+  if (!isRecord(value)) {
+    return "environment is not an object";
+  }
+  if (!(typeof value.cpuModel === "string" || value.cpuModel === null)) {
+    return "environment.cpuModel is neither a string nor null";
+  }
+  if (!isFiniteNumber(value.cpuCount)) {
+    return "environment.cpuCount is not a finite number";
+  }
+  return undefined;
+};
+
+/** The count fields the writer emits; every one must be a finite number. */
+const COUNT_FIELDS = [
+  "failed",
+  "passed",
+  "pending",
+  "suites",
+  "tests",
+  "todo",
+] as const;
+
+const runFailure = (value: unknown, index: number): string | undefined => {
+  if (!isRecord(value)) {
+    return `runs[${index}] is not an object`;
+  }
+  if (!isFiniteNumber(value.durationMs)) {
+    return `runs[${index}].durationMs is not a finite number`;
+  }
+  if (value.counts === null) {
+    return undefined;
+  }
+  if (!isRecord(value.counts)) {
+    return `runs[${index}].counts is neither an object nor null`;
+  }
+  const { counts } = value;
+  const missing = COUNT_FIELDS.find((field) => !isFiniteNumber(counts[field]));
+  return missing === undefined
+    ? undefined
+    : `runs[${index}].counts.${missing} is not a finite number`;
+};
+
+const slowEntryFailure = (
+  value: unknown,
+  where: string,
+  labelField: "name" | "path"
+): string | undefined => {
+  if (!isRecord(value)) {
+    return `${where} is not an object`;
+  }
+  if (typeof value[labelField] !== "string") {
+    return `${where}.${labelField} is not a string`;
+  }
+  if (labelField === "name" && typeof value.file !== "string") {
+    return `${where}.file is not a string`;
+  }
+  return durationSummaryFailure(value.durationMs, `${where}.durationMs`);
+};
+
+const summaryFailure = (value: unknown): string | undefined => {
+  if (!isRecord(value)) {
+    return "summary is not an object";
+  }
+  const durations = durationSummaryFailure(
+    value.durationMs,
+    "summary.durationMs"
+  );
+  if (durations !== undefined) {
+    return durations;
+  }
+  if (!Array.isArray(value.slowFiles)) {
+    return "summary.slowFiles is not an array";
+  }
+  for (const [index, entry] of value.slowFiles.entries()) {
+    const failure = slowEntryFailure(
+      entry,
+      `summary.slowFiles[${index}]`,
+      "path"
+    );
+    if (failure !== undefined) {
+      return failure;
+    }
+  }
+  if (!Array.isArray(value.slowTests)) {
+    return "summary.slowTests is not an array";
+  }
+  for (const [index, entry] of value.slowTests.entries()) {
+    const failure = slowEntryFailure(
+      entry,
+      `summary.slowTests[${index}]`,
+      "name"
+    );
+    if (failure !== undefined) {
+      return failure;
+    }
+  }
+  return undefined;
+};
+
+/**
+ * Check one parsed JSON document against the profile contract the writer
+ * emits. Returns the typed profile on success and the first mismatch reason
+ * otherwise — never a partially-usable value.
+ */
+export const readVitestProfileDocument = (
+  value: unknown
+): VitestProfileReadResult => {
+  if (!isRecord(value)) {
+    return { kind: "unrecognized", reason: "the document is not an object" };
+  }
+  if (value.tool !== VITEST_PROFILE_TOOL) {
+    return {
+      kind: "unrecognized",
+      reason: `tool is ${JSON.stringify(value.tool)} rather than "${VITEST_PROFILE_TOOL}"`,
+    };
+  }
+  if (value.schemaVersion !== VITEST_PROFILE_SCHEMA_VERSION) {
+    return {
+      kind: "unrecognized",
+      reason: `schemaVersion is ${JSON.stringify(value.schemaVersion)} rather than ${VITEST_PROFILE_SCHEMA_VERSION}`,
+    };
+  }
+  if (
+    !(
+      Array.isArray(value.command) &&
+      value.command.every((part) => typeof part === "string")
+    )
+  ) {
+    return {
+      kind: "unrecognized",
+      reason: "command is not an array of strings",
+    };
+  }
+  const environment = environmentFailure(value.environment);
+  if (environment !== undefined) {
+    return { kind: "unrecognized", reason: environment };
+  }
+  if (!isRecord(value.options)) {
+    return { kind: "unrecognized", reason: "options is not an object" };
+  }
+  if (!isFiniteNumber(value.options.maxWorkers)) {
+    return {
+      kind: "unrecognized",
+      reason: "options.maxWorkers is not a finite number",
+    };
+  }
+  if (!Array.isArray(value.runs)) {
+    return { kind: "unrecognized", reason: "runs is not an array" };
+  }
+  for (const [index, run] of value.runs.entries()) {
+    const failure = runFailure(run, index);
+    if (failure !== undefined) {
+      return { kind: "unrecognized", reason: failure };
+    }
+  }
+  const summary = summaryFailure(value.summary);
+  if (summary !== undefined) {
+    return { kind: "unrecognized", reason: summary };
+  }
+
+  return { kind: "profile", profile: value as unknown as VitestProfile };
+};