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/artifacts/EspFlashImageArtifactReader.test.ts

@@ -175,27 +175,6 @@ describe("ESP flash layout inventory", () => {
   });
 });
 
-it("inventories a zero-byte partition without reporting missing bytes", async () => {
-  const dump = espFlashDump({
-    bootloader: { at: 0, bytes: BOOTLOADER },
-    table: partitionTable([
-      ...TWO_OTA_PARTITIONS,
-      { label: "empty", type: 1, subtype: 0x82, offset: 0xa000, size: 0 },
-    ]),
-  });
-  const snapshot = await scanCanonicalArtifactInventory(await writeDump(dump));
-  expect(snapshot.coverage.status).toBe("complete");
-  expect(
-    snapshot.occurrences.find(
-      ({ logical_path }) => logical_path === "partitions/empty.bin",
-    ),
-  ).toMatchObject({
-    declared_size: 0,
-    limitations: ["partitions/empty.bin declares zero bytes."],
-    format_metadata: { flash_address: 0xa000, size: 0 },
-  });
-});
-
 describe("ESP flash layout coverage and selection", () => {
   it("keeps usable partitions beside a truncated and a missing one", async () => {
     const cut = DUMP.subarray(0, 0x2_8000);

src/artifacts/EspFlashImageArtifactReader.ts

@@ -272,17 +272,15 @@ const regionEntry = (
   declaredIntegrity: null,
   unpacked: false,
   limitations:
-    region.availability === "empty"
-      ? [`${region.path} declares zero bytes.`]
-      : region.availability === "missing"
+    region.available === 0
+      ? [
+          `${region.path} lies outside the dump: the file holds none of its ${String(region.length)} bytes.`,
+        ]
+      : region.available < region.length
         ? [
-            `${region.path} lies outside the dump: the file holds none of its ${String(region.length)} bytes.`,
+            `${region.path} is truncated: the dump holds ${String(region.available)} of its ${String(region.length)} bytes.`,
           ]
-        : region.availability === "truncated"
-          ? [
-              `${region.path} is truncated: the dump holds ${String(region.available)} of its ${String(region.length)} bytes.`,
-            ]
-          : [],
+        : [],
   adapterKey: `esp-flash-image:${region.path}`,
   ...(region.partition === undefined
     ? {}

src/domain/firmware/espFlashLayout.ts

@@ -38,8 +38,6 @@ export interface EspFlashRegion {
   readonly fileOffset: number;
   /** Bytes of the region the file holds, from `fileOffset`. */
   readonly available: number;
-  /** An empty declaration has no bytes to be missing from the dump. */
-  readonly availability: "empty" | "missing" | "truncated" | "complete";
   readonly partition: EspPartition | undefined;
 }
 
@@ -119,21 +117,12 @@ const partitionPaths = (
 
 const region = (
   input: EspFlashPlanInput,
-  fields: Omit<EspFlashRegion, "fileOffset" | "available" | "availability">,
+  fields: Omit<EspFlashRegion, "fileOffset" | "available">,
 ): EspFlashRegion => {
   const fileOffset = fields.flashAddress - input.origin.value;
   const start = Math.max(0, fileOffset);
   const end = Math.min(input.fileSize, fileOffset + fields.length);
-  const available = Math.max(0, end - start);
-  const availability =
-    fields.length === 0
-      ? "empty"
-      : available === 0
-        ? "missing"
-        : available < fields.length
-          ? "truncated"
-          : "complete";
-  return { ...fields, fileOffset, available, availability };
+  return { ...fields, fileOffset, available: Math.max(0, end - start) };
 };
 
 const rangeText = (address: number, length: number): string =>
@@ -222,15 +211,11 @@ export const planEspFlashLayout = (input: EspFlashPlanInput): EspFlashPlan => {
       limitations.push(
         `Partition ${name} at ${offsetText(part.offset)} begins before the dump's first byte at flash ${offsetText(input.origin.value)}; it is not read.`,
       );
-    else if (placed.availability === "empty")
-      limitations.push(
-        `Partition ${name} at ${offsetText(part.offset)} declares zero bytes.`,
-      );
-    else if (placed.availability === "missing")
+    else if (placed.available === 0)
       limitations.push(
         `Partition ${name} at ${rangeText(part.offset, part.size)} lies outside the dump, which ends at flash ${offsetText(input.origin.value + input.fileSize)}.`,
       );
-    else if (placed.availability === "truncated")
+    else if (placed.available < part.size)
       limitations.push(
         `Partition ${name} at ${rangeText(part.offset, part.size)} is truncated: the dump holds ${String(placed.available)} of its ${String(part.size)} bytes.`,
       );
@@ -283,7 +268,6 @@ const overlaps = (regions: readonly EspFlashRegion[]): string[] => {
   // The region reaching furthest so far, so a long one shows every overlap.
   let furthest: EspFlashRegion | undefined;
   for (const current of ordered) {
-    if (current.availability === "empty") continue;
     if (
       furthest !== undefined &&
       current.flashAddress < regionEnd(furthest) &&

src/domain/firmware/espFlashPlan.test.ts

@@ -179,38 +179,6 @@ describe("ESP flash layout plans", () => {
 });
 
 describe("ESP flash layout overlaps", () => {
-  it.each([
-    ["inside another partition", 0xa000],
-    ["at the end of the dump", 0x4_0000],
-  ])(
-    "retains a zero-byte partition %s as an empty declaration",
-    (_, offset) => {
-      const plan = planEspFlashLayout(
-        input({
-          table: table([
-            {
-              label: "data",
-              type: 1,
-              subtype: 2,
-              offset: 0x9000,
-              size: 0x4000,
-            },
-            { label: "empty", type: 1, subtype: 0x82, offset, size: 0 },
-          ]),
-        }),
-      );
-      expect(plan.regions.at(-1)).toMatchObject({
-        path: "partitions/empty.bin",
-        fileOffset: offset,
-        length: 0,
-        available: 0,
-      });
-      expect(plan.limitations).toEqual([
-        `Partition empty at 0x${offset.toString(16)} declares zero bytes.`,
-      ]);
-    },
-  );
-
   it("reports every region inside a longer one", () => {
     const plan = planEspFlashLayout(
       input({

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",