fix(python): validate shared pyc header facts

src/application/frida/FridaInstrumentationService.test.ts

@@ -100,7 +100,6 @@ it("keeps default Frida status identity and messages and refreshes every summary
     messages: [{ observed: 1 }],
     messages_truncated: false,
   });
-  expect(complete.value.normalized_result).not.toHaveProperty("capture_limits");
   expect(complete.value.limitations.join("\n")).not.toContain(
     "no runtime override",
   );
@@ -121,7 +120,6 @@ it("keeps default Frida status identity and messages and refreshes every summary
     },
   });
   expect(JSON.stringify(summary.value)).not.toContain('"messages":');
-  expect(JSON.stringify(summary.value)).not.toContain('"capture_limits":');
   expect(reads).toBe(2);
   const parent = [...records.values()][0];
   expect(parent?.normalized_result).toMatchObject({
@@ -129,7 +127,7 @@ it("keeps default Frida status identity and messages and refreshes every summary
   });
   expect(parent?.limitations).toEqual(
     expect.arrayContaining([
-      expect.stringContaining("selected value is unknown"),
+      expect.stringContaining("16777216"),
       expect.stringContaining(
         "Already discarded observations cannot be recovered",
       ),
@@ -164,9 +162,7 @@ it("names the Frida field cap and ignores flags inside a caller payload", () =>
   });
   if (!result.ok) throw result.error;
   const text = result.value.limitations.join("\n");
-  expect(text).toContain("capture_limits.message_text_bytes");
-  expect(text).toContain("selected value is unknown");
-  expect(text).not.toContain("32768");
+  expect(text).toContain("32768");
   expect(text).not.toContain("16777216");
   expect(text).not.toContain("4096");
 });

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/contracts/fridaToolContracts.test.ts

@@ -1,6 +1,6 @@
 import { describe, expect, it } from "vitest";
 
-import { toolContract, TOOL_CONTRACTS } from "./toolContracts.js";
+import { TOOL_CONTRACTS } from "./toolContracts.js";
 import { FRIDA_KEEPALIVE_INTERVAL_DESCRIPTION } from "./fridaToolContracts.js";
 import { isValidFridaRemoteAddress } from "../domain/fridaRemoteAddress.js";
 
@@ -168,48 +168,3 @@ describe("Frida tool contracts", () => {
     expect(isValidFridaRemoteAddress("user@frida-target")).toBe(false);
   });
 });
-
-it("keeps request defaults out of observed Frida policies", () => {
-  const start = toolContract("start_frida_session");
-  const identity = {
-    session_id: "00000000-0000-4000-8000-000000000001",
-    device_id: "fixture",
-    target: "fixture",
-    pid: 1,
-    mode: "attach",
-    state: "detached",
-  };
-  expect(
-    start.inputSchema.parse({
-      mode: "attach",
-      pid: 1,
-      capture_limits: { session_bytes: 12345 },
-    }),
-  ).toEqual({
-    mode: "attach",
-    pid: 1,
-    capture_limits: { session_bytes: 12345 },
-  });
-  expect(start.outputSchema.parse(identity)).not.toHaveProperty(
-    "capture_limits",
-  );
-  for (const capture_limits of [
-    {},
-    { session_bytes: 12345 },
-    { session_bytes: -1 },
-  ])
-    expect(
-      start.outputSchema.safeParse({ ...identity, capture_limits }).success,
-    ).toBe(false);
-  const capture_limits = {
-    session_bytes: 12345,
-    message_type_bytes: 456,
-    message_text_bytes: 789,
-    json_nodes: 100,
-    json_depth: 10,
-  };
-  expect(start.outputSchema.parse({ ...identity, capture_limits })).toEqual({
-    ...identity,
-    capture_limits,
-  });
-});

src/domain/fridaCapturePolicy.ts

@@ -7,8 +7,8 @@ export const FRIDA_CAPTURE_MAX_JSON_DEPTH = MAX_JSON_DEPTH - 8;
 const CAPTURE_POLICY_DESCRIPTION =
   "Retention budgets selected before attaching or spawning, fixed for this session. Defaults: 16 MiB session, 4 KiB type, 32 KiB error text, 250000 JSON nodes and depth64. Session bytes include JSON/base64 expansion and capture metadata; a budget too small for one event retains no event. Raising these cannot recover already discarded observations or raise MCP/client delivery limits. Select larger budgets before a new explicitly chosen experiment; no REA restart is required.";
 
-/** Defaults belong to the session owner, before attachment. */
-const sessionCapturePolicySchema = z
+/** Capture policy is accepted before attachment and remains fixed for that session. */
+export const fridaCapturePolicySchema = z
   .strictObject({
     session_bytes: z
       .int()
@@ -27,31 +27,31 @@ const sessionCapturePolicySchema = z
   })
   .describe(CAPTURE_POLICY_DESCRIPTION);
 
-/** Observations report a full policy or omit it; omitted facts have no defaults. */
-export const fridaCapturePolicySchema = z
-  .strictObject({
-    session_bytes:
-      sessionCapturePolicySchema.shape.session_bytes.removeDefault(),
-    message_type_bytes:
-      sessionCapturePolicySchema.shape.message_type_bytes.removeDefault(),
-    message_text_bytes:
-      sessionCapturePolicySchema.shape.message_text_bytes.removeDefault(),
-    json_nodes: sessionCapturePolicySchema.shape.json_nodes.removeDefault(),
-    json_depth: sessionCapturePolicySchema.shape.json_depth.removeDefault(),
-  })
-  .describe(
-    "Retention budgets reported by the session owner. An omitted policy is unknown.",
-  );
-
 /** Request fields preserve omission; defaults are resolved only by the session owner. */
-export const fridaCapturePolicyInputSchema = fridaCapturePolicySchema
-  .partial()
+export const fridaCapturePolicyInputSchema = z
+  .strictObject({
+    session_bytes: fridaCapturePolicySchema.shape.session_bytes
+      .removeDefault()
+      .optional(),
+    message_type_bytes: fridaCapturePolicySchema.shape.message_type_bytes
+      .removeDefault()
+      .optional(),
+    message_text_bytes: fridaCapturePolicySchema.shape.message_text_bytes
+      .removeDefault()
+      .optional(),
+    json_nodes: fridaCapturePolicySchema.shape.json_nodes
+      .removeDefault()
+      .optional(),
+    json_depth: fridaCapturePolicySchema.shape.json_depth
+      .removeDefault()
+      .optional(),
+  })
   .describe(CAPTURE_POLICY_DESCRIPTION);
 
-export const resolveFridaCapturePolicy = (input: unknown) =>
-  sessionCapturePolicySchema.safeParse(input);
-
 export type FridaCapturePolicy = z.output<typeof fridaCapturePolicySchema>;
 export type FridaCapturePolicyInput = z.input<
   typeof fridaCapturePolicyInputSchema
 >;
+export const DEFAULT_FRIDA_CAPTURE_POLICY = Object.freeze(
+  fridaCapturePolicySchema.parse({}),
+);

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/frida/FridaInstrumentationManager.test.ts

@@ -268,13 +268,11 @@ describe("FridaInstrumentationManager", () => {
     expect(fridaCaptureLimitations({ messages_truncated: false })).toEqual([]);
     expect(
       fridaCaptureLimitations({ messages_truncated: true }).join("\n"),
-    ).toContain("selected value is unknown");
+    ).toContain("16777216");
     const field = fridaCaptureLimitations({
       messages: [{ type_truncated: true }],
     }).join("\n");
-    expect(field).toContain("capture_limits.message_type_bytes");
-    expect(field).toContain("selected value is unknown");
-    expect(field).not.toContain("4096");
+    expect(field).toContain("4096");
     expect(field).not.toContain("16777216");
     const text = fridaCaptureLimitations({
       messages: [
@@ -284,9 +282,7 @@ describe("FridaInstrumentationManager", () => {
         },
       ],
     }).join("\n");
-    expect(text).toContain("capture_limits.message_text_bytes");
-    expect(text).toContain("selected value is unknown");
-    expect(text).not.toContain("32768");
+    expect(text).toContain("32768");
     expect(text).not.toContain("16777216");
     expect(text).not.toContain("4096");
     expect(
@@ -1931,21 +1927,3 @@ it("retries only unresolved sessions and resolves the typed close aggregate", as
   expect(calls).toEqual([2, 1]);
   expect(failure.cleanupIncomplete).toBe(false);
 });
-
-// Malformed or partial observations do not establish the session's policy.
-it.each([{}, { session_bytes: 12345 }, { session_bytes: -1 }])(
-  "keeps observed capture policy unknown for %j",
-  (capture_limits) => {
-    const text = fridaCaptureLimitations({
-      capture_limits,
-      messages_truncated: true,
-      messages: [{ type_truncated: true, description_truncated: true }],
-    }).join("\n");
-    expect(text).toContain("selected value is unknown");
-    for (const invented of ["16777216", "4096", "32768"])
-      expect(text).not.toContain(invented);
-    expect(text).toContain(
-      "Already discarded observations cannot be recovered",
-    );
-  },
-);

src/frida/FridaInstrumentationManager.ts

@@ -49,7 +49,7 @@ import {
   type FridaOwnedCaptureLimit,
 } from "./fridaCaptureLimits.js";
 import {
-  resolveFridaCapturePolicy,
+  fridaCapturePolicySchema,
   type FridaCapturePolicy,
 } from "../domain/fridaCapturePolicy.js";
 import { analysisInputErrorFromIssues } from "../domain/inputIssueProjection.js";
@@ -305,7 +305,9 @@ export class FridaInstrumentationManager implements FridaInstrumentationPort {
   async #startSession(
     input: StartFridaSessionInput,
   ): Promise<Result<FridaSessionObservation, AnalysisError>> {
-    const policy = resolveFridaCapturePolicy(input.captureLimits ?? {});
+    const policy = fridaCapturePolicySchema.safeParse(
+      input.captureLimits ?? {},
+    );
     if (!policy.success)
       return err(
         analysisInputErrorFromIssues(

src/frida/fridaCaptureLimits.ts

@@ -1,4 +1,5 @@
 import {
+  DEFAULT_FRIDA_CAPTURE_POLICY,
   fridaCapturePolicySchema,
   FRIDA_CAPTURE_MAX_JSON_DEPTH,
   type FridaCapturePolicy,
@@ -31,35 +32,28 @@ const namedLimit = (value: unknown): FridaOwnedCaptureLimit | undefined =>
 
 const limitationFor = (
   limit: FridaOwnedCaptureLimit,
-  policy: FridaCapturePolicy | undefined,
+  policy: FridaCapturePolicy,
 ): string => {
-  const recover = (
-    field: string,
-    value: number | undefined,
-    unit: string,
-  ): string =>
-    value === undefined
-      ? `Frida capture reached capture_limits.${field}; its selected value is unknown because the observation did not report a valid capture policy. Select capture_limits.${field} before starting a new explicitly chosen session or instrument_with_frida experiment. Already discarded observations cannot be recovered. Session bytes and MCP/client delivery budgets remain independent.`
-      : `Frida capture reached capture_limits.${field} (${String(value)} ${unit}). Select a larger capture_limits.${field} before starting a new explicitly chosen session or instrument_with_frida experiment; no REA restart is required. Already discarded observations cannot be recovered. Session bytes and MCP/client delivery budgets remain independent.`;
+  const recover = (field: string, value: number, unit: string): string =>
+    `Frida capture reached capture_limits.${field} (${String(value)} ${unit}). Select a larger capture_limits.${field} before starting a new explicitly chosen session or instrument_with_frida experiment; no REA restart is required. Already discarded observations cannot be recovered. Session bytes and MCP/client delivery budgets remain independent.`;
   switch (limit) {
     case "session_bytes":
     case "payload_bytes":
     case "binary_bytes":
       return recover(
         "session_bytes",
-        policy?.session_bytes,
+        policy.session_bytes,
         "bytes including JSON/base64 expansion and metadata",
       );
     case "message_type":
-      return recover("message_type_bytes", policy?.message_type_bytes, "bytes");
+      return recover("message_type_bytes", policy.message_type_bytes, "bytes");
     case "message_text":
-      return recover("message_text_bytes", policy?.message_text_bytes, "bytes");
+      return recover("message_text_bytes", policy.message_text_bytes, "bytes");
     case "json_nodes":
-      return recover("json_nodes", policy?.json_nodes, "nodes");
+      return recover("json_nodes", policy.json_nodes, "nodes");
     case "json_depth":
-      return policy === undefined ||
-        policy.json_depth < FRIDA_CAPTURE_MAX_JSON_DEPTH
-        ? recover("json_depth", policy?.json_depth, "levels") +
+      return policy.json_depth < FRIDA_CAPTURE_MAX_JSON_DEPTH
+        ? recover("json_depth", policy.json_depth, "levels") +
             ` The maximum is ${String(FRIDA_CAPTURE_MAX_JSON_DEPTH)} levels, reserving the surrounding Evidence envelope.`
         : `Frida capture reached capture_limits.json_depth (${String(policy.json_depth)} levels), the shared JSON representation allowance after reserving the Evidence envelope. No higher depth is supported. Select a script that sends shallower payloads for a new explicitly chosen experiment. Already discarded observations cannot be recovered.`;
     case "unrepresentable":
@@ -106,7 +100,8 @@ export const fridaCaptureLimitations = (result: unknown): readonly string[] => {
     typeof result === "object" && result !== null && "capture_limits" in result
       ? fridaCapturePolicySchema.safeParse(result.capture_limits)
       : undefined;
-  const policy = selected?.success === true ? selected.data : undefined;
+  const policy =
+    selected?.success === true ? selected.data : DEFAULT_FRIDA_CAPTURE_POLICY;
   collectOwnedCaps(result, caps);
   return FRIDA_OWNED_CAPTURE_LIMITS.flatMap((limit) =>
     caps.has(limit) ? [limitationFor(limit, policy)] : [],