fix: manifest.jsonl schema has no canonical machine-readable definition (#720)

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

STATE.md

@@ -39,3 +39,4 @@
 - [2026-03-15] fix FitnessEvaluator.t.sol broken on Base mainnet fork (#780)
 - [2026-03-15] No generic flag dispatch: only `token_value_inflation` is ever zero-rated (#723)
 - [2026-03-15] `llm`-origin entries in manifest have null fitness and no evaluation path (#724): evaluate-seeds.sh scores null-fitness seeds and writes results back to manifest.jsonl
+- [2026-03-15] manifest.jsonl schema has no canonical machine-readable definition (#720)

tools/push3-evolution/evolve.sh

@@ -144,6 +144,7 @@ mkdir -p "$OUTPUT_DIR"
 LOG="$OUTPUT_DIR/evolution.log"
 
 # Seeds pool — persistent candidate pool across all runs
+# manifest.jsonl schema: tools/push3-evolution/seeds/manifest.schema.json
 SEEDS_DIR="$SCRIPT_DIR/seeds"
 POOL_MANIFEST="$SEEDS_DIR/manifest.jsonl"
 ADMISSION_THRESHOLD=6000000000000000000000  # 6e21 wei

tools/push3-evolution/seeds/manifest.schema.json

@@ -0,0 +1,45 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "tools/push3-evolution/seeds/manifest.schema.json",
+  "title": "Push3 seed pool manifest entry",
+  "description": "Each line of manifest.jsonl must conform to this schema. The file is newline-delimited JSON (JSONL); validate one parsed object per non-empty line.",
+  "type": "object",
+  "required": ["file", "origin", "date"],
+  "additionalProperties": false,
+  "properties": {
+    "file": {
+      "type": "string",
+      "description": "Filename of the Push3 seed relative to the seeds/ directory (e.g. optimizer_v3.push3)."
+    },
+    "fitness": {
+      "type": ["integer", "null"],
+      "description": "Raw fitness score returned by the evaluator (wei-scale integer). null when the seed has not yet been evaluated."
+    },
+    "fitness_flags": {
+      "type": ["string", "null"],
+      "description": "Space-separated flags that qualify or invalidate the fitness value (e.g. token_value_inflation). null when no flags apply."
+    },
+    "origin": {
+      "type": "string",
+      "enum": ["hand-written", "evolved", "llm"],
+      "description": "How this seed was produced: hand-written by a developer, evolved by the evolutionary loop, or generated by an LLM."
+    },
+    "run": {
+      "type": ["string", "null"],
+      "description": "Zero-padded run identifier from which this seed was admitted (e.g. '007'). null for hand-written and llm seeds."
+    },
+    "generation": {
+      "type": ["integer", "null"],
+      "description": "Generation index within the run at which this candidate was produced. null for hand-written and llm seeds."
+    },
+    "date": {
+      "type": "string",
+      "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}$",
+      "description": "ISO 8601 date (YYYY-MM-DD) on which this entry was added to the manifest."
+    },
+    "note": {
+      "type": ["string", "null"],
+      "description": "Human-readable description of the seed strategy or noteworthy behaviour. null when no annotation is needed."
+    }
+  }
+}