seeds: pin maxItems to job.count for symmetric bounds

Address Yeming's review feedback on #40. The minItems pin alone left
the schema asymmetric (e.g. minItems=27, maxItems=2000), which
technically allows the model to over-generate. Over-generation isn't
the failure mode that motivated the PR, but pinning both bounds keeps
the schema's stated shape aligned with the prompt's stated count.

- seeds_response_schema now accepts an optional max_items override; the
  default behavior (maxItems=2000) is preserved when callers don't pass
  one, matching the existing seed-validation safety net.
- _generate_records now pins both bounds to job.count so each batch
  produces exactly the requested number of seeds.
- Two new unit tests cover the pinned-bounds case and the non-positive
  override fallback. 30/30 seed-schema tests pass.

Author: jakepresent

p2m/stages/seeds.py

@@ -159,18 +159,25 @@ def _validate_tool_source(tool_source: str, target: TargetConfig | None) -> None
 def seeds_response_schema(
     tool_source: str = TOOL_SOURCE_RUNTIME,
     min_items: int | None = None,
+    max_items: int | None = None,
 ) -> dict[str, Any]:
     """Full response schema wrapping seeds in a ``{"seeds": [...]}`` envelope.
 
     When ``min_items`` is provided, the schema requires the model to return at
     least that many seeds. Without this lower bound, gpt-5.4-mini frequently
     returns N-1 items for batches larger than ~10, since the schema previously
     allowed 0-2000 items regardless of the prompt's stated count.
+
+    When ``max_items`` is provided, it overrides the default 2000 ceiling so
+    callers can pin both bounds to the exact target count. Pinning both bounds
+    keeps the schema symmetric with the prompt's stated count and prevents the
+    model from over-generating in the (unlikely) inverse failure mode.
     """
     item_schema = SEED_SCHEMA_WITH_TOOLS if tool_source == TOOL_SOURCE_PER_SEED else SEED_SCHEMA
+    resolved_max = max_items if (max_items is not None and max_items > 0) else 2000
     seeds_schema: dict[str, Any] = {
         "type": "array",
-        "maxItems": 2000,
+        "maxItems": resolved_max,
         "items": item_schema,
     }
     if min_items is not None and min_items > 0:
@@ -663,7 +670,9 @@ async def _process(job: SeedJob) -> dict[str, Any]:
         )
         slug = slugify(str(job.behavior.get("name") or ""))
         behavior_name = str(job.behavior.get("name") or "")
-        job_schema = seeds_response_schema(tool_source, min_items=job.count)
+        job_schema = seeds_response_schema(
+            tool_source, min_items=job.count, max_items=job.count
+        )
 
         response = await generate_structured(
             model,

tests/test_seed_sampling_characterization.py

@@ -135,6 +135,7 @@ def test_schema_wraps_seeds_array(self) -> None:
     def test_schema_omits_min_items_by_default(self) -> None:
         schema = seeds_response_schema()
         self.assertNotIn("minItems", schema["properties"]["seeds"])
+        self.assertEqual(schema["properties"]["seeds"]["maxItems"], 2000)
 
     def test_schema_pins_min_items_when_count_supplied(self) -> None:
         schema = seeds_response_schema(min_items=27)
@@ -146,6 +147,16 @@ def test_schema_ignores_non_positive_min_items(self) -> None:
             schema = seeds_response_schema(min_items=value)
             self.assertNotIn("minItems", schema["properties"]["seeds"])
 
+    def test_schema_pins_both_bounds_when_min_and_max_match(self) -> None:
+        schema = seeds_response_schema(min_items=500, max_items=500)
+        self.assertEqual(schema["properties"]["seeds"]["minItems"], 500)
+        self.assertEqual(schema["properties"]["seeds"]["maxItems"], 500)
+
+    def test_schema_ignores_non_positive_max_items(self) -> None:
+        for value in (0, -1):
+            schema = seeds_response_schema(max_items=value)
+            self.assertEqual(schema["properties"]["seeds"]["maxItems"], 2000)
+
 
 class LabelEntrySchemaTest(unittest.TestCase):
     def test_schema_enumerates_present_factors_only(self) -> None: