fix(python): validate shared pyc header facts

src/application/python/PythonPycService.test.ts

@@ -66,6 +66,28 @@ const report: PythonPyc = {
   ],
 };
 
+it.each([
+  {
+    flags: 1,
+    hash_based: true,
+    source_hash_hex: "",
+    source_mtime: null,
+    source_size: null,
+  },
+  { flags: 1 },
+])("refuses inconsistent provider header facts %j", async (header) => {
+  const result = await new PythonPycService({
+    close: async () => {},
+    identity,
+    inspect: async () =>
+      ok({ ...report, header: { ...report.header, ...header } }),
+  }).inspect({ path: report.artifact.path });
+  expect(result).toMatchObject({
+    ok: false,
+    error: { _tag: "AnalysisOutputError" },
+  });
+});
+
 it("rejects a relative path and extra arguments before reading", async () => {
   let calls = 0;
   const service = new PythonPycService({

src/domain/python/pythonPyc.test.ts

@@ -3,9 +3,49 @@ import {
   inspectPythonPycInputSchema,
   pythonPycMarshalProfile,
   PYTHON_PYC_MARSHAL_PROFILES,
+  pythonPycHeaderSchema,
 } from "./pythonPyc.js";
 import { pythonBytecodeIdentity } from "./pythonBytecodeIdentity.js";
 
+const hashHeader = {
+  magic: 3531,
+  python_version: "3.12",
+  code_layout: "py311",
+  flags: 3,
+  hash_based: true,
+  check_source: true,
+  source_hash_hex: "0123456789abcdef",
+  source_mtime: null,
+  source_size: null,
+};
+
+it.each(["", "ab", "g".repeat(16)])(
+  "rejects an invalid source hash %j",
+  (source_hash_hex) => {
+    expect(
+      pythonPycHeaderSchema.safeParse({ ...hashHeader, source_hash_hex })
+        .success,
+    ).toBe(false);
+  },
+);
+
+it.each([
+  { hash_based: false },
+  { check_source: false },
+  { source_hash_hex: null },
+  { source_mtime: 0 },
+  { source_size: 0 },
+])("keeps header facts consistent with the recorded flags: %j", (changed) => {
+  expect(
+    pythonPycHeaderSchema.safeParse({ ...hashHeader, ...changed }).success,
+  ).toBe(false);
+});
+
+it("preserves unknown raw header flags and valid hash bytes", () => {
+  const header = { ...hashHeader, flags: 0x80000003 };
+  expect(pythonPycHeaderSchema.parse(header)).toEqual(header);
+});
+
 it("keeps pinned CPython identity separate from standalone marshal coverage", () => {
   expect(pythonPycMarshalProfile(3394)).toEqual({
     code_layout: "py37",

src/domain/python/pythonPyc.ts

@@ -205,17 +205,53 @@ const pythonCodeObjectSchema = z.strictObject({
 });
 export type PythonPycCodeObject = z.infer<typeof pythonCodeObjectSchema>;
 
-export const pythonPycHeaderSchema = z.strictObject({
-  magic: z.number().int().min(0).max(0xffff),
-  python_version: z.string().min(1),
-  code_layout: z.enum(PYTHON_PYC_CODE_LAYOUTS),
-  flags: uint,
-  hash_based: z.boolean(),
-  check_source: z.boolean(),
-  source_hash_hex: z.string().nullable(),
-  source_mtime: uint.nullable(),
-  source_size: uint.nullable(),
-});
+export const pythonPycHeaderSchema = z
+  .strictObject({
+    magic: z.number().int().min(0).max(0xffff),
+    python_version: z.string().min(1),
+    code_layout: z.enum(PYTHON_PYC_CODE_LAYOUTS),
+    flags: uint,
+    hash_based: z.boolean(),
+    check_source: z.boolean(),
+    source_hash_hex: z
+      .string()
+      .regex(/^[0-9a-f]{16}$/u)
+      .nullable(),
+    source_mtime: uint.nullable(),
+    source_size: uint.nullable(),
+  })
+  .superRefine((header, context) => {
+    for (const [field, flag] of [
+      ["hash_based", PYTHON_PYC_HASH_BASED],
+      ["check_source", PYTHON_PYC_CHECK_SOURCE],
+    ] as const)
+      if (header[field] !== ((header.flags & flag) !== 0))
+        context.addIssue({
+          code: "custom",
+          path: [field],
+          message: `${field} disagrees with its recorded header flag.`,
+        });
+    if (header.hash_based === (header.source_hash_hex === null))
+      context.addIssue({
+        code: "custom",
+        path: ["source_hash_hex"],
+        message:
+          "Hash-based pycs require an 8-byte source hash; others must omit it.",
+      });
+    if (header.hash_based === (header.source_mtime !== null))
+      context.addIssue({
+        code: "custom",
+        path: ["source_mtime"],
+        message: "Timestamp pycs require mtime; hash-based pycs must omit it.",
+      });
+    if (header.hash_based === (header.source_size !== null))
+      context.addIssue({
+        code: "custom",
+        path: ["source_size"],
+        message:
+          "Timestamp pycs require source_size; hash-based pycs must omit it.",
+      });
+  });
 
 /** Bounded CPython 3.7–3.13 pyc observation; marshal is walked, bytecode is not decompiled. */
 export const pythonPycSchema = z
@@ -253,29 +289,6 @@ export const pythonPycSchema = z
         message: "Marshal byte count disagrees with the header-stripped file.",
       });
     }
-    if (report.header.hash_based === (report.header.source_hash_hex === null)) {
-      context.addIssue({
-        code: "custom",
-        path: ["header", "source_hash_hex"],
-        message:
-          "Hash-based pycs require an 8-byte source hash; others must omit it.",
-      });
-    }
-    if (report.header.hash_based === (report.header.source_mtime !== null)) {
-      context.addIssue({
-        code: "custom",
-        path: ["header", "source_mtime"],
-        message: "Timestamp pycs require mtime; hash-based pycs must omit it.",
-      });
-    }
-    if (report.header.hash_based === (report.header.source_size !== null)) {
-      context.addIssue({
-        code: "custom",
-        path: ["header", "source_size"],
-        message:
-          "Timestamp pycs require source_size; hash-based pycs must omit it.",
-      });
-    }
     if (report.coverage.code_objects !== report.code_objects.length) {
       context.addIssue({
         code: "custom",

src/domain/reconstructionVerification.test.ts

@@ -615,108 +615,3 @@ it("keeps a valid comparison selected for the wrong claim kind as caller input",
     });
   }
 });
-
-describe("retained reconstruction source coverage", () => {
-  const omittedTerminalCapture = {
-    ...EMPTY_PROCESS_CAPTURE_EXAMPLE,
-    truncated: true,
-    truncation_details: {
-      ...EMPTY_PROCESS_CAPTURE_EXAMPLE.truncation_details,
-      raw_terminal: {
-        ...EMPTY_PROCESS_CAPTURE_EXAMPLE.truncation_details.raw_terminal,
-        observed_frames: 1,
-        observed_bytes: 1,
-      },
-    },
-  };
-
-  it("keeps old unchanged terminal and overall claims unknown while retaining unrelated claims", () => {
-    const left = source("1", "controlled-replay");
-    const right = source("2", "controlled-replay", "observed", {
-      captureResult: omittedTerminalCapture,
-    });
-    const comparison = processComparison(left, right, processResult());
-    const bundle = createEvidenceBundle([left, right, comparison]);
-    const before = JSON.stringify(bundle);
-    const result = verifyReconstruction(
-      {
-        name: "Retained capture coverage",
-        claims: ["terminal", "overall", "exit", "interaction"].map(
-          (dimension) => ({
-            kind: "behavioral",
-            claim_id: dimension,
-            title: dimension,
-            dimension,
-            comparison_evidence_id: comparison.evidence_id,
-          }),
-        ),
-      },
-      bundle,
-    );
-    expect(
-      result.claims.items.map(({ claim_id, status }) => [claim_id, status]),
-    ).toEqual([
-      ["exit", "pass"],
-      ["interaction", "pass"],
-      ["overall", "unknown"],
-      ["terminal", "unknown"],
-    ]);
-    expect(
-      result.claims.items.find(({ claim_id }) => claim_id === "terminal")
-        ?.limitations,
-    ).toContain(
-      `Source ${right.evidence_id}: terminal observation coverage is incomplete.`,
-    );
-    expect(JSON.stringify(bundle)).toBe(before);
-  });
-
-  it("retains a decisive changed claim despite omitted terminal observations", () => {
-    const left = source("1", "controlled-replay");
-    const right = source("2", "controlled-replay", "observed", {
-      captureResult: omittedTerminalCapture,
-    });
-    const comparison = processComparison(left, right, processResult("changed"));
-    const claims = ["terminal", "overall"].map((dimension) => ({
-      kind: "behavioral",
-      claim_id: dimension,
-      title: dimension,
-      dimension,
-      comparison_evidence_id: comparison.evidence_id,
-    }));
-    expect(
-      verifyReconstruction(
-        { name: "Observed disagreement", claims },
-        createEvidenceBundle([left, right, comparison]),
-      ),
-    ).toMatchObject({
-      status: "fail",
-      summary: { failed: 2, unknown: 0 },
-    });
-  });
-
-  it.each(["status", "kind"] as const)(
-    "rejects a summary inconsistent with actual claim %s",
-    (field) => {
-      const left = source("1", "controlled-replay");
-      const right = source("2", "controlled-replay");
-      const comparison = processComparison(left, right, processResult());
-      const result = verifyReconstruction(
-        behavioralSpec(comparison),
-        createEvidenceBundle([left, right, comparison]),
-      );
-      const inconsistent = {
-        ...result,
-        claims: {
-          items: result.claims.items.map((claim) =>
-            field === "status"
-              ? { ...claim, status: "fail", observed_status: "changed" }
-              : { ...claim, kind: "structural-function" },
-          ),
-        },
-      };
-      expect(
-        reconstructionVerificationResultSchema.safeParse(inconsistent).success,
-      ).toBe(false);
-    },
-  );
-});

src/domain/reconstructionVerification.ts

@@ -15,16 +15,7 @@ import { analysisInputErrorFromIssues } from "./inputIssueProjection.js";
 import { readEvidencePayload } from "./evidenceValidation.js";
 import { functionDossierSchema } from "./native/functionDossier.js";
 import { assessFunctionCallCoverage } from "./functionCallCoverage.js";
-import {
-  processCaptureSchema,
-  type UnverifiedProcessCapture,
-} from "./process/processCapture.js";
-import { processSourceTruncated } from "./process/processCaptureCoverage.js";
-import {
-  PROCESS_COMPARISON_DIMENSIONS,
-  type ProcessComparisonDimension,
-} from "./process/processComparison.js";
-import type { ProcessObservationSource } from "./process/processObservation.js";
+import { processCaptureSchema } from "./process/processCapture.js";
 import { digestCanonicalValue } from "./canonicalDigest.js";
 import {
   reconstructionClaimResultSchema,
@@ -54,14 +45,6 @@ interface FunctionSourceFacts {
   readonly callCoverageDiagnostics: readonly string[];
 }
 
-interface ValidatedSourceFacts {
-  readonly functions: readonly FunctionSourceFacts[];
-  readonly processes: readonly {
-    readonly evidence_id: string;
-    readonly capture: UnverifiedProcessCapture;
-  }[];
-}
-
 /** Verify only explicitly declared claims; no global equivalence is inferred. */
 export const verifyReconstruction = (
   specificationInput: unknown,
@@ -161,18 +144,17 @@ const evaluateClaim = (
       );
     return source;
   });
-  const sourceFacts = readValidatedSourceFacts(claim, sources);
+  const functionSourceFacts = readValidatedSourceFacts(claim, sources);
   const observation = comparisonObservation(claim, comparison);
   const observed = observation.status;
   const callCoverage = sourceCallCoverage(
     claim,
-    sourceFacts.functions,
+    functionSourceFacts,
     observation.hasIndependentFunctionChange === true,
   );
   const blockers = [
     ...authorityLimitations(claim, sources, sides),
     ...callCoverage.blockers,
-    ...sourceProcessCoverage(claim, sourceFacts.processes, observed),
   ];
   const relevantUnknowns = reconstructionClaimUnknowns(
     heads,
@@ -207,7 +189,7 @@ const evaluateClaim = (
 const readValidatedSourceFacts = (
   claim: Claim,
   sources: readonly Evidence[],
-): ValidatedSourceFacts => {
+): readonly FunctionSourceFacts[] => {
   const isExpectedType = (source: Evidence): boolean => {
     if (claim.kind === "behavioral")
       return (
@@ -234,7 +216,6 @@ const readValidatedSourceFacts = (
       },
     );
   const functionSources: FunctionSourceFacts[] = [];
-  const processSources: ValidatedSourceFacts["processes"][number][] = [];
   for (const source of sources) {
     if (claim.kind === "behavioral") {
       const capture = readEvidencePayload(
@@ -242,10 +223,6 @@ const readValidatedSourceFacts = (
         source.normalized_result,
       );
       if (!capture.ok) throw capture.error;
-      processSources.push({
-        evidence_id: source.evidence_id,
-        capture: capture.value,
-      });
     } else if (claim.kind === "structural-function") {
       const parsedDossier = readEvidencePayload(
         functionDossierSchema,
@@ -279,7 +256,7 @@ const readValidatedSourceFacts = (
       }
     }
   }
-  return { functions: functionSources, processes: processSources };
+  return functionSources;
 };
 
 const validateComparisonIdentity = (
@@ -427,44 +404,6 @@ const authorityLimitations = (
   return limitations;
 };
 
-const processObservationSourceByDimension: Readonly<
-  Record<ProcessComparisonDimension, ProcessObservationSource>
-> = {
-  terminal: "terminal_rendered",
-  interaction: "interaction",
-  exit: "lifecycle",
-  filesystem: "filesystem",
-  process: "process",
-};
-
-const sourceProcessCoverage = (
-  claim: Claim,
-  sources: ValidatedSourceFacts["processes"],
-  observed: ObservedStatus,
-): string[] => {
-  if (
-    claim.kind !== "behavioral" ||
-    ["changed", "added", "removed", "contradiction"].includes(observed)
-  )
-    return [];
-  const dimensions =
-    claim.dimension === "overall"
-      ? PROCESS_COMPARISON_DIMENSIONS
-      : [claim.dimension];
-  return sources.flatMap(({ evidence_id, capture }) =>
-    dimensions.flatMap((dimension) =>
-      processSourceTruncated(
-        capture,
-        processObservationSourceByDimension[dimension],
-      )
-        ? [
-            `Source ${evidence_id}: ${dimension} observation coverage is incomplete.`,
-          ]
-        : [],
-    ),
-  );
-};
-
 const sourceCallCoverage = (
   claim: Claim,
   functionSources: readonly FunctionSourceFacts[],

src/domain/reconstructionVerificationSchemas.ts

@@ -118,28 +118,9 @@ export const reconstructionVerificationResultSchema = z
   })
   .superRefine((result, context) => {
     const { summary } = result;
-    const claims = result.claims.items;
     const expectedStatus =
       summary.failed > 0 ? "fail" : summary.unknown > 0 ? "unknown" : "pass";
     const issues = [
-      [
-        summary.passed !==
-          claims.filter(({ status }) => status === "pass").length ||
-          summary.failed !==
-            claims.filter(({ status }) => status === "fail").length ||
-          summary.unknown !==
-            claims.filter(({ status }) => status === "unknown").length,
-        "Claim status counts must summarize retained claims",
-        ["summary"],
-      ],
-      [
-        summary.behavioral !==
-          claims.filter(({ kind }) => kind === "behavioral").length ||
-          summary.structural !==
-            claims.filter(({ kind }) => kind !== "behavioral").length,
-        "Claim kind counts must summarize retained claims",
-        ["summary"],
-      ],
       [
         summary.total !== summary.passed + summary.failed + summary.unknown,
         "Claim status counts must equal the summary total",