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/webCaptureDiff.resources.test.ts

@@ -110,47 +110,3 @@ describe("web resource comparison identity and optional size", () => {
     });
   });
 });
-
-it.each([
-  [[128, 256], [128], [false, true], "unknown"],
-  [[128], [256], [true, true], "unknown"],
-  [[128], [128], [true, true], "unknown"],
-  [[128], [128, 256], [false, true], "changed"],
-  [[], [128], [false, true], "changed"],
-  [[128], [], [true, true], "unknown"],
-  [[128], [null], [false, true], "unknown"],
-] as const)(
-  "uses directional resource coverage for %j vs %j (limited=%j): %s",
-  (leftSizes, rightSizes, [leftLimited, rightLimited], status) => {
-    const before = capture(leftSizes.map((size) => resource(size)));
-    const after = capture(rightSizes.map((size) => resource(size)));
-    if (leftLimited) before.completeness.truncated_sections.push("resources");
-    if (rightLimited) after.completeness.truncated_sections.push("resources");
-    for (const [left, right] of [
-      [before, after],
-      [after, before],
-    ] as const)
-      expect(compareResources(left, right)).toMatchObject({
-        status,
-        total_changes: status === "changed" ? 1 : 0,
-        changes:
-          status === "changed"
-            ? [
-                {
-                  identity: expect.stringMatching(/^resg_/u),
-                  change:
-                    left.resources.length === 0
-                      ? "added"
-                      : right.resources.length === 0
-                        ? "removed"
-                        : "modified",
-                },
-              ]
-            : [],
-        reason:
-          status === "changed"
-            ? null
-            : expect.stringContaining("Resource inventory"),
-      });
-  },
-);

src/domain/webCaptureDiff.ts

@@ -213,8 +213,9 @@ const compareWebCaptureDimensions = (
     resources: compareResources(
       before.resources,
       after.resources,
-      sectionsComplete(before, ["resources"]),
-      sectionsComplete(after, ["resources"]),
+      sectionsComplete(before, ["resources"]) &&
+        sectionsComplete(after, ["resources"]),
+      "Resource inventory or content-size evidence was incomplete in at least one observation.",
     ),
     network: networkDimension(before, after),
     metadata: compareAggregate(
@@ -234,12 +235,9 @@ const compareWebCaptureDimensions = (
 const compareResources = (
   before: WebPageInspection["resources"],
   after: WebPageInspection["resources"],
-  beforeComplete: boolean,
-  afterComplete: boolean,
+  complete: boolean,
+  reason: string,
 ): Dimension => {
-  const reason =
-    "Resource inventory or content-size evidence was incomplete in at least one observation.";
-  const complete = beforeComplete && afterComplete;
   const left = resourceGroups(before);
   const right = resourceGroups(after);
   const changes: Change[] = [];
@@ -248,14 +246,12 @@ const compareResources = (
     const leftSizes = left.get(identity);
     const rightSizes = right.get(identity);
     if (leftSizes === undefined || rightSizes === undefined) {
-      const absenceProven =
-        leftSizes === undefined ? beforeComplete : afterComplete;
-      if (absenceProven)
+      if (!complete) unresolved = true;
+      else
         changes.push({
           identity,
           change: leftSizes === undefined ? "added" : "removed",
         });
-      else unresolved = true;
       continue;
     }
     // Stable inventories deduplicate identical observations. A null size also
@@ -265,12 +261,7 @@ const compareResources = (
       unresolved = true;
       continue;
     }
-    // A partial set can omit any size variant. Only a complete peer can
-    // contradict a retained variant, including when the other side is partial.
-    if (
-      (beforeComplete && !resourceSizesContained(rightSizes, leftSizes)) ||
-      (afterComplete && !resourceSizesContained(leftSizes, rightSizes))
-    )
+    if (!sameResourceSizes(leftSizes, rightSizes))
       changes.push({ identity, change: "modified" });
   }
   if (changes.length > 0)
@@ -301,10 +292,11 @@ const resourceGroups = (
   return groups;
 };
 
-const resourceSizesContained = (
-  observed: ReadonlySet<number | null>,
-  complete: ReadonlySet<number | null>,
-): boolean => [...observed].every((size) => complete.has(size));
+const sameResourceSizes = (
+  left: ReadonlySet<number | null>,
+  right: ReadonlySet<number | null>,
+): boolean =>
+  left.size === right.size && [...left].every((size) => right.has(size));
 
 type BodyShapeSources = {
   readonly request: boolean;