fix(python): validate shared pyc header facts

src/application/analysisView/BrowserScenarioViews.test.ts

@@ -1,8 +1,4 @@
 import { createHash } from "node:crypto";
-import { Ajv2020 } from "ajv/dist/2020.js";
-import { z } from "zod";
-
-import { ANALYSIS_VIEW_TOOL_CONTRACTS } from "../../contracts/analysisViewToolContracts.js";
 
 import { describe, expect, it } from "vitest";
 
@@ -83,57 +79,6 @@ const view = async (
   return projected.value.normalized_result as Record<string, unknown>;
 };
 
-it("summarizes every three-digit status bucket within the advertised output contract", async () => {
-  const contract = ANALYSIS_VIEW_TOOL_CONTRACTS.find(
-    ({ name }) => name === "inspect_analysis_view",
-  );
-  if (contract === undefined)
-    throw new Error("Missing inspect_analysis_view contract");
-  const validateOutput = new Ajv2020({
-    strict: false,
-    validateFormats: false,
-    inlineRefs: false,
-    code: { optimize: false },
-  }).compile(z.toJSONSchema(contract.outputSchema));
-  for (const [status, statusClass] of [
-    [100, "1xx"],
-    [200, "2xx"],
-    [300, "3xx"],
-    [400, "4xx"],
-    [599, "5xx"],
-    [600, "6xx"],
-    [700, "7xx"],
-    [800, "8xx"],
-    [999, "9xx"],
-  ] as const) {
-    const capture = scenarioCaptureFixture([
-      { method: "GET", url: "/status", status },
-    ]);
-    const original = JSON.stringify(capture);
-    const result = await inspectAnalysisView({
-      source: { kind: "inline", evidence: scenarioCaptureEvidence(capture) },
-      view: { kind: "summary" },
-    });
-    if (!result.ok) throw result.error;
-    expect(result.value.normalized_result).toMatchObject({
-      summary: {
-        network: {
-          by_status_class: [{ status_class: statusClass, transactions: 1 }],
-        },
-      },
-    });
-    expect(contract.outputSchema.safeParse(result.value).success).toBe(true);
-    expect(
-      validateOutput(result.value),
-      JSON.stringify(validateOutput.errors),
-    ).toBe(true);
-    expect(JSON.stringify(capture)).toBe(original);
-    expect(capture.events.items).toContainEqual(
-      expect.objectContaining({ kind: "response", status }),
-    );
-  }
-});
-
 describe("browser scenario analysis views", () => {
   it("counts inherited Evidence limitations alongside capture-local caveats", async () => {
     const capture = scenarioCaptureFixture();

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/analysisView/browserScenarioNetworkView.ts

@@ -4,23 +4,15 @@ import { isImmutableJsonSnapshot } from "../immutableJson.js";
 import { compareAsciiStrings } from "../canonicalOrdering.js";
 
 const count = z.int().nonnegative();
-const statusClass = z
-  .enum([
-    "1xx",
-    "2xx",
-    "3xx",
-    "4xx",
-    "5xx",
-    "6xx",
-    "7xx",
-    "8xx",
-    "9xx",
-    "failed",
-    "unknown",
-  ])
-  .describe(
-    "Numeric hundreds bucket of the recorded three-digit status. The 6xx through 9xx buckets retain nonstandard source values without assigning standard HTTP semantics.",
-  );
+const statusClass = z.enum([
+  "1xx",
+  "2xx",
+  "3xx",
+  "4xx",
+  "5xx",
+  "failed",
+  "unknown",
+]);
 
 /** Counts concern retained transaction identities, including those without a request event. */
 export const browserScenarioNetworkSummarySchema = z.strictObject({
@@ -115,7 +107,9 @@ export const browserScenarioTransactionGroups = (
             : null,
         status_class:
           group.statuses.size === 1 && status !== undefined
-            ? statusClass.parse(`${String(Math.floor(status / 100))}xx`)
+            ? (`${String(Math.floor(status / 100))}xx` as z.infer<
+                typeof statusClass
+              >)
             : group.statuses.size === 0 && group.failed
               ? "failed"
               : "unknown",

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