agent-hitch 0.2.5 → 0.2.7

package/docs/schemas/environment-image-manifest.schema.json

@@ -0,0 +1,62 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://agent-hitch.local/schemas/environment-image-manifest.schema.json",
+  "title": "Hitch environment image manifest V1",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schema_version", "image_id", "source", "platform", "build", "output", "base_images", "created_at"],
+  "properties": {
+    "schema_version": { "const": "1" },
+    "image_id": { "$ref": "#/$defs/sha256" },
+    "source": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["kind", "benchmark_id", "benchmark_revision"],
+      "properties": {
+        "kind": { "enum": ["registry", "build-context", "compose-build"] },
+        "benchmark_id": { "type": "string", "minLength": 1 },
+        "benchmark_revision": { "type": "string", "minLength": 1 },
+        "task_id": { "type": "string", "minLength": 1 },
+        "context_digest": { "$ref": "#/$defs/sha256" },
+        "dockerfile_digest": { "$ref": "#/$defs/sha256" }
+      }
+    },
+    "platform": { "type": "string", "minLength": 1 },
+    "build": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["builder", "secret_names", "cache_key"],
+      "properties": {
+        "builder": { "const": "buildkit" },
+        "buildkit_version": { "type": "string", "minLength": 1 },
+        "builder_id": { "type": "string", "minLength": 1 },
+        "frontend": { "type": "string", "minLength": 1 },
+        "target": { "type": "string", "minLength": 1 },
+        "build_args_sha256": { "$ref": "#/$defs/sha256" },
+        "secret_names": { "type": "array", "items": { "type": "string", "pattern": "^[A-Za-z_][A-Za-z0-9_]*$" }, "uniqueItems": true },
+        "cache_key": { "$ref": "#/$defs/sha256" }
+      }
+    },
+    "output": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["reference", "manifest_digest"],
+      "properties": {
+        "reference": { "type": "string", "minLength": 1 },
+        "manifest_digest": { "$ref": "#/$defs/sha256" },
+        "config_digest": { "$ref": "#/$defs/sha256" }
+      }
+    },
+    "base_images": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["reference", "digest"],
+        "properties": { "reference": { "type": "string", "minLength": 1 }, "digest": { "$ref": "#/$defs/sha256" } }
+      }
+    },
+    "created_at": { "type": "string", "format": "date-time" }
+  },
+  "$defs": { "sha256": { "type": "string", "pattern": "^sha256:[a-f0-9]{64}$" } }
+}

package/docs/schemas/eval-control.schema.json

@@ -0,0 +1,36 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://agent-hitch.local/schemas/eval-control.schema.json",
+  "title": "Hitch control-plane eval state V1",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schema_version", "eval_id", "generation", "state", "requested_parallelism", "admitted_parallelism", "active_leases", "queued_work_items", "terminal_work_items", "created_at", "updated_at"],
+  "properties": {
+    "schema_version": { "const": "1" },
+    "eval_id": { "type": "string", "pattern": "^eval_[a-f0-9]{32}$" },
+    "generation": { "type": "integer", "minimum": 0 },
+    "state": { "enum": ["queued", "planning", "preparing", "running", "finalizing", "cancelling", "succeeded", "failed", "cancelled"] },
+    "requested_parallelism": { "type": "integer", "minimum": 1 },
+    "admitted_parallelism": { "type": "integer", "minimum": 0 },
+    "active_leases": { "$ref": "#/$defs/leases" },
+    "queued_work_items": { "$ref": "#/$defs/workItems" },
+    "terminal_work_items": { "$ref": "#/$defs/workItems" },
+    "allocation_id": { "type": "string", "pattern": "^allocation_[a-f0-9]{32}$" },
+    "cancel_requested_at": { "type": "string", "format": "date-time" },
+    "error": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["code", "message"],
+      "properties": {
+        "code": { "type": "string", "minLength": 1, "maxLength": 256 },
+        "message": { "type": "string", "maxLength": 4096 }
+      }
+    },
+    "created_at": { "type": "string", "format": "date-time" },
+    "updated_at": { "type": "string", "format": "date-time" }
+  },
+  "$defs": {
+    "leases": { "type": "array", "items": { "type": "string", "pattern": "^lease_[a-f0-9]{32}$" }, "uniqueItems": true },
+    "workItems": { "type": "array", "items": { "type": "string", "pattern": "^work_[a-f0-9]{32}$" }, "uniqueItems": true }
+  }
+}

package/docs/schemas/eval-execution-plan.schema.json

@@ -0,0 +1,216 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://agent-hitch.local/schemas/eval-execution-plan.schema.json",
+  "title": "Hitch eval execution plan V1",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "schema_version", "planner", "eval_id", "membership", "candidate_identity", "benchmark",
+    "provider", "max_parallelism", "default_trial_resources", "slots", "work_items", "retry_policy", "created_at"
+  ],
+  "properties": {
+    "schema_version": { "const": "1" },
+    "planner": { "const": "hitch-local-v1" },
+    "eval_id": { "$ref": "#/$defs/evalId" },
+    "membership": { "enum": ["known", "opaque"] },
+    "candidate_identity": { "$ref": "#/$defs/sha256" },
+    "benchmark": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["id", "revision", "verifier_identity"],
+      "properties": {
+        "id": { "type": "string", "minLength": 1 },
+        "revision": { "type": "string", "minLength": 1 },
+        "verifier_identity": { "$ref": "#/$defs/sha256" }
+      }
+    },
+    "provider": { "type": "string", "minLength": 1 },
+    "model_capture": { "$ref": "#/$defs/modelCapture" },
+    "max_parallelism": { "type": "integer", "minimum": 1 },
+    "default_trial_resources": { "$ref": "#/$defs/resources" },
+    "task_resources": {
+      "type": "array",
+      "items": { "$ref": "#/$defs/taskResources" }
+    },
+    "image_fallbacks": {
+      "type": "array",
+      "items": { "$ref": "#/$defs/imageFallback" }
+    },
+    "slots": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["schema_version", "slot_id", "eval_id", "task_id", "attempt", "candidate_identity", "state", "physical_execution"],
+        "properties": {
+          "schema_version": { "const": "1" },
+          "slot_id": { "type": "string", "pattern": "^slot_[a-f0-9]{32}$" },
+          "eval_id": { "$ref": "#/$defs/evalId" },
+          "task_id": { "type": "string", "minLength": 1 },
+          "task_digest": { "$ref": "#/$defs/sha256" },
+          "attempt": { "type": "integer", "minimum": 1 },
+          "candidate_identity": { "$ref": "#/$defs/sha256" },
+          "state": { "enum": ["pending", "blocked", "ready", "leased", "running", "collecting", "succeeded", "invalid", "failed", "cancelled"] },
+          "physical_execution": { "type": "integer", "minimum": 1 },
+          "authoritative_run_id": { "type": "string", "pattern": "^run_[a-f0-9]{32}$" },
+          "invalid_reason": { "type": "string", "minLength": 1 }
+        }
+      }
+    },
+    "work_items": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": [
+          "schema_version", "work_id", "eval_id", "backend", "logical_attempt", "task_ids", "slots",
+          "opaque_membership", "requested_parallelism", "reservation", "provider"
+        ],
+        "properties": {
+          "schema_version": { "const": "1" },
+          "work_id": { "type": "string", "pattern": "^work_[a-f0-9]{32}$" },
+          "eval_id": { "$ref": "#/$defs/evalId" },
+          "backend": { "const": "harbor" },
+          "logical_attempt": { "type": ["integer", "null"], "minimum": 1 },
+          "task_ids": { "type": "array", "items": { "type": "string", "minLength": 1 }, "uniqueItems": true },
+          "slots": { "type": "array", "items": { "type": "string", "pattern": "^slot_[a-f0-9]{32}$" }, "uniqueItems": true },
+          "opaque_membership": { "type": "boolean" },
+          "requested_parallelism": { "type": "integer", "minimum": 1 },
+          "reservation": { "$ref": "#/$defs/resources" },
+          "provider": { "type": "string", "minLength": 1 },
+          "image_refs": {
+            "type": "array",
+            "items": { "$ref": "#/$defs/imageUse" }
+          }
+        }
+      }
+    },
+    "retry_policy": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["infrastructure_retries", "infrastructure_retry_backoff_ms", "verifier_execution", "candidate_rerun_on_verifier_failure"],
+      "properties": {
+        "infrastructure_retries": { "type": "integer", "minimum": 0 },
+        "infrastructure_retry_backoff_ms": { "type": "number", "minimum": 0 },
+        "verifier_execution": { "const": "same-trial-verifier-only" },
+        "candidate_rerun_on_verifier_failure": { "const": false }
+      }
+    },
+    "created_at": { "type": "string", "format": "date-time" }
+  },
+  "$defs": {
+    "evalId": { "type": "string", "pattern": "^eval_[a-f0-9]{32}$" },
+    "sha256": { "type": "string", "pattern": "^sha256:[a-f0-9]{64}$" },
+    "modelCapture": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["requested_mode", "effective_mode", "required"],
+      "properties": {
+        "requested_mode": { "enum": ["off", "native", "proxy", "hybrid"] },
+        "effective_mode": { "enum": ["off", "native", "proxy", "hybrid"] },
+        "required": { "type": "boolean" },
+        "topology": { "enum": ["host-side", "in-sandbox"] },
+        "degraded_reason": { "type": "string", "minLength": 1 }
+      }
+    },
+    "resources": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["cpu_millis", "memory_bytes", "container_slots", "build_slots"],
+      "properties": {
+        "cpu_millis": { "type": "integer", "minimum": 0 },
+        "memory_bytes": { "type": "integer", "minimum": 0 },
+        "container_slots": { "type": "integer", "minimum": 0 },
+        "build_slots": { "type": "integer", "minimum": 0 },
+        "gpu_count": { "type": "integer", "minimum": 0 },
+        "ephemeral_disk_bytes": { "type": "integer", "minimum": 0 }
+      }
+    },
+    "resourceField": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["value", "source", "estimated"],
+      "properties": {
+        "value": { "type": "integer", "minimum": 0 },
+        "source": { "enum": ["task", "compose", "submission-default", "operator-default", "provider-policy", "derived-components"] },
+        "estimated": { "type": "boolean" }
+      }
+    },
+    "imageUse": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["task_ids", "image_id", "requested_reference", "reference", "manifest_digest", "platform", "resolution", "cache_hit"],
+      "properties": {
+        "task_ids": { "type": "array", "minItems": 1, "uniqueItems": true, "items": { "type": "string", "minLength": 1 } },
+        "image_id": { "$ref": "#/$defs/sha256" },
+        "requested_reference": { "type": "string", "minLength": 1, "maxLength": 1024 },
+        "reference": { "type": "string", "minLength": 1, "maxLength": 1024 },
+        "manifest_digest": { "$ref": "#/$defs/sha256" },
+        "platform": { "type": "string", "minLength": 1 },
+        "resolution": { "enum": ["registry", "prebuilt", "backend-build"] },
+        "cache_hit": { "type": "boolean" }
+      }
+    },
+    "imageFallback": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["task_id", "source", "service", "code"],
+      "properties": {
+        "task_id": { "type": "string", "minLength": 1 },
+        "source": { "enum": ["task", "verifier", "compose"] },
+        "service": { "type": "string", "minLength": 1 },
+        "code": { "enum": ["backend-build", "dynamic-image", "policy-backend", "resolver-unavailable", "resolution-failed"] }
+      }
+    },
+    "taskResources": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["task_id", "reservation", "main_limits", "fields", "components", "diagnostics"],
+      "properties": {
+        "task_id": { "type": "string", "minLength": 1 },
+        "reservation": { "$ref": "#/$defs/resources" },
+        "main_limits": { "$ref": "#/$defs/resources" },
+        "fields": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["cpu_millis", "memory_bytes", "container_slots", "build_slots"],
+          "properties": {
+            "cpu_millis": { "$ref": "#/$defs/resourceField" },
+            "memory_bytes": { "$ref": "#/$defs/resourceField" },
+            "container_slots": { "$ref": "#/$defs/resourceField" },
+            "build_slots": { "$ref": "#/$defs/resourceField" },
+            "gpu_count": { "$ref": "#/$defs/resourceField" },
+            "ephemeral_disk_bytes": { "$ref": "#/$defs/resourceField" }
+          }
+        },
+        "components": {
+          "type": "array",
+          "minItems": 1,
+          "items": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["name", "role", "replicas", "resources", "fields"],
+            "properties": {
+              "name": { "type": "string", "minLength": 1 },
+              "role": { "enum": ["main", "task-sidecar", "verifier", "provider-sidecar"] },
+              "replicas": { "type": "integer", "minimum": 1 },
+              "resources": { "$ref": "#/$defs/resources" },
+              "fields": {
+                "type": "object",
+                "additionalProperties": false,
+                "required": ["cpu_millis", "memory_bytes"],
+                "properties": {
+                  "cpu_millis": { "$ref": "#/$defs/resourceField" },
+                  "memory_bytes": { "$ref": "#/$defs/resourceField" },
+                  "gpu_count": { "$ref": "#/$defs/resourceField" },
+                  "ephemeral_disk_bytes": { "$ref": "#/$defs/resourceField" }
+                }
+              }
+            }
+          }
+        },
+        "diagnostics": { "type": "array", "items": { "type": "string", "minLength": 1 }, "uniqueItems": true }
+      }
+    }
+  }
+}

package/docs/schemas/eval-request.schema.json

@@ -15,6 +15,8 @@
     "model": { "type": "string" },
     "attempts": { "type": "integer", "minimum": 1 },
     "max_concurrent": { "type": "integer", "minimum": 1 },
+    "infrastructure_retries": { "type": "integer", "minimum": 0 },
+    "infrastructure_retry_backoff_ms": { "type": "number", "minimum": 0 },
     "timeout_ms": { "type": "number", "minimum": 0 },
     "setup_timeout_ms": { "type": "number", "minimum": 0 },
     "agent_args": { "type": "array", "items": { "type": "string" } },

package/docs/schemas/eval-rerun-result.schema.json

@@ -0,0 +1,53 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://agent-hitch.local/schemas/eval-rerun-result.schema.json",
+  "title": "Hitch eval rerun result V1",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "schema_version", "kind", "rerun_id", "rerun_type", "semantics", "eval_id", "status",
+    "selected_tasks", "repaired_tasks", "remaining_invalid_tasks", "selected_trials", "repaired_trials",
+    "remaining_invalid_trials", "eval_status", "started_at", "completed_at"
+  ],
+  "properties": {
+    "schema_version": { "const": "1" },
+    "kind": { "const": "eval-rerun" },
+    "rerun_id": { "type": "string", "pattern": "^rerun_[a-f0-9]{32}$" },
+    "rerun_type": { "enum": ["candidate-restart", "candidate-resume", "trajectory-replay", "verifier-only", "collect-only"] },
+    "semantics": { "$ref": "eval-rerun-submission.schema.json#/$defs/semantics" },
+    "eval_id": { "type": "string", "pattern": "^eval_[a-f0-9]{32}$" },
+    "status": { "const": "completed" },
+    "selected_tasks": { "type": "array", "items": { "type": "string" } },
+    "repaired_tasks": { "type": "array", "items": { "type": "string" } },
+    "remaining_invalid_tasks": { "type": "array", "items": { "type": "string" } },
+    "selected_trials": { "type": "array", "items": { "$ref": "#/$defs/trial" } },
+    "repaired_trials": { "type": "array", "items": { "$ref": "#/$defs/trial" } },
+    "remaining_invalid_trials": { "type": "array", "items": { "$ref": "#/$defs/trial" } },
+    "sources": { "type": "array", "items": { "$ref": "#/$defs/source" } },
+    "eval_status": { "enum": ["succeeded", "failed"] },
+    "started_at": { "type": "string", "format": "date-time" },
+    "completed_at": { "type": "string", "format": "date-time" }
+  },
+  "$defs": {
+    "trial": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["task_id", "attempt"],
+      "properties": {
+        "task_id": { "type": "string", "minLength": 1 },
+        "attempt": { "type": "integer", "minimum": 1 }
+      }
+    },
+    "source": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["source_trial_id", "source_run_id", "source_work_id", "source_backend_directory"],
+      "properties": {
+        "source_trial_id": { "type": "string", "minLength": 1 },
+        "source_run_id": { "type": "string", "pattern": "^run_[a-f0-9]{32}$" },
+        "source_work_id": { "type": "string", "pattern": "^work_[a-f0-9]{32}$" },
+        "source_backend_directory": { "type": "string", "pattern": "^harbor/work-items/work_[a-f0-9]{32}/epoch-[0-9]{6}$" }
+      }
+    }
+  }
+}

package/docs/schemas/eval-rerun-state.schema.json

@@ -0,0 +1,61 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://agent-hitch.local/schemas/eval-rerun-state.schema.json",
+  "title": "Hitch eval rerun state V1",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schema_version", "rerun_id", "eval_id", "rerun_type", "semantics", "status", "tasks", "repaired_tasks", "updated_at"],
+  "properties": {
+    "schema_version": { "const": "1" },
+    "rerun_id": { "type": "string", "pattern": "^rerun_[a-f0-9]{32}$" },
+    "eval_id": { "type": "string", "pattern": "^eval_[a-f0-9]{32}$" },
+    "rerun_type": { "enum": ["candidate-restart", "candidate-resume", "trajectory-replay", "verifier-only", "collect-only"] },
+    "semantics": { "$ref": "eval-rerun-submission.schema.json#/$defs/semantics" },
+    "status": { "enum": ["queued", "running", "completed", "failed", "cancelled"] },
+    "tasks": { "type": "array", "items": { "type": "string" } },
+    "trials": { "type": "array", "items": { "$ref": "#/$defs/trial" } },
+    "repaired_tasks": { "type": "array", "items": { "type": "string" } },
+    "repaired_trials": { "type": "array", "items": { "$ref": "#/$defs/trial" } },
+    "remaining_invalid_tasks": { "type": "array", "items": { "type": "string" } },
+    "remaining_invalid_trials": { "type": "array", "items": { "$ref": "#/$defs/trial" } },
+    "sources": { "type": "array", "items": { "$ref": "#/$defs/source" } },
+    "eval_status": { "enum": ["succeeded", "failed"] },
+    "admitted_parallelism": { "type": "integer", "minimum": 1 },
+    "allocation_id": { "type": "string", "pattern": "^allocation_[a-f0-9]{32}$" },
+    "error": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["code"],
+      "properties": {
+        "code": { "type": "string", "minLength": 1 },
+        "message": { "type": "string", "maxLength": 4096 }
+      }
+    },
+    "submitted_at": { "type": "string", "format": "date-time" },
+    "started_at": { "type": "string", "format": "date-time" },
+    "completed_at": { "type": "string", "format": "date-time" },
+    "updated_at": { "type": "string", "format": "date-time" }
+  },
+  "$defs": {
+    "trial": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["task_id", "attempt"],
+      "properties": {
+        "task_id": { "type": "string", "minLength": 1 },
+        "attempt": { "type": "integer", "minimum": 1 }
+      }
+    },
+    "source": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["source_trial_id", "source_run_id", "source_work_id", "source_backend_directory"],
+      "properties": {
+        "source_trial_id": { "type": "string", "minLength": 1 },
+        "source_run_id": { "type": "string", "pattern": "^run_[a-f0-9]{32}$" },
+        "source_work_id": { "type": "string", "pattern": "^work_[a-f0-9]{32}$" },
+        "source_backend_directory": { "type": "string", "pattern": "^harbor/work-items/work_[a-f0-9]{32}/epoch-[0-9]{6}$" }
+      }
+    }
+  }
+}

package/docs/schemas/eval-rerun-submission.schema.json

@@ -0,0 +1,58 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://agent-hitch.local/schemas/eval-rerun-submission.schema.json",
+  "title": "Hitch eval rerun submission V1",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schema_version", "rerun_id", "eval_id", "rerun_type", "semantics", "selector", "submitted_at"],
+  "properties": {
+    "schema_version": { "const": "1" },
+    "rerun_id": { "type": "string", "pattern": "^rerun_[a-f0-9]{32}$" },
+    "eval_id": { "type": "string", "pattern": "^eval_[a-f0-9]{32}$" },
+    "rerun_type": { "$ref": "#/$defs/rerunType" },
+    "semantics": { "$ref": "#/$defs/semantics" },
+    "selector": { "$ref": "#/$defs/selector" },
+    "submitted_at": { "type": "string", "format": "date-time" }
+  },
+  "$defs": {
+    "rerunType": {
+      "enum": ["candidate-restart", "candidate-resume", "trajectory-replay", "verifier-only", "collect-only"]
+    },
+    "semantics": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["candidate_action", "conversation_source", "sandbox_source", "candidate_executes"],
+      "properties": {
+        "candidate_action": { "enum": ["restart", "resume", "replay", "none"] },
+        "conversation_source": { "enum": ["original-instruction", "native-session", "canonical-trajectory", "none"] },
+        "sandbox_source": { "enum": ["clean", "checkpoint", "retained", "none"] },
+        "candidate_executes": { "type": "boolean" }
+      }
+    },
+    "selector": {
+      "oneOf": [
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["mode"],
+          "properties": { "mode": { "const": "invalid" } }
+        },
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["mode", "task_names"],
+          "properties": {
+            "mode": { "const": "tasks" },
+            "task_names": {
+              "type": "array",
+              "minItems": 1,
+              "maxItems": 10000,
+              "uniqueItems": true,
+              "items": { "type": "string", "minLength": 1, "maxLength": 1024 }
+            }
+          }
+        }
+      ]
+    }
+  }
+}

package/docs/schemas/eval-result.schema.json

@@ -37,10 +37,43 @@
         "harness_id": { "type": "string", "pattern": "^[a-z][a-z0-9-]*$" },
         "revision_identity": { "type": "string", "pattern": "^sha256:[0-9a-f]{64}$" },
         "platform": { "type": "string", "pattern": "^(?:linux|darwin|win32)-[a-z0-9_]+$" },
-        "source_type": { "enum": ["npm", "git"] }
+        "node_version": { "type": "string", "pattern": "^v[0-9]+\\.[0-9]+\\.[0-9]+$" },
+        "source_type": { "enum": ["npm", "git"] },
+        "storage": { "enum": ["host-artifact-store-v1", "harbor-artifact-cache-v2"] }
       },
       "additionalProperties": false
     },
+    "prepared_artifacts": {
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "type": "object",
+        "required": ["artifact_id", "artifact_integrity", "entrypoint_integrity", "harness_id", "revision_identity", "platform", "node_version", "source_type", "task_ids", "runtime_contract"],
+        "properties": {
+          "artifact_id": { "type": "string", "pattern": "^sha256:[0-9a-f]{64}$" },
+          "artifact_integrity": { "type": "string", "pattern": "^sha256:[0-9a-f]{64}$" },
+          "entrypoint_integrity": { "type": "string", "pattern": "^sha256:[0-9a-f]{64}$" },
+          "harness_id": { "type": "string", "pattern": "^[a-z][a-z0-9-]*$" },
+          "revision_identity": { "type": "string", "pattern": "^sha256:[0-9a-f]{64}$" },
+          "platform": { "type": "string", "pattern": "^(?:linux|darwin|win32)-[a-z0-9_]+$" },
+          "node_version": { "type": "string", "pattern": "^v[0-9]+\\.[0-9]+\\.[0-9]+$" },
+          "source_type": { "enum": ["npm", "git"] },
+          "storage": { "enum": ["host-artifact-store-v1", "harbor-artifact-cache-v2"] },
+          "task_ids": { "type": "array", "items": { "type": "string", "minLength": 1 }, "uniqueItems": true },
+          "runtime_contract": {
+            "type": "object",
+            "required": ["docker_platform", "artifact_platform", "node_version"],
+            "properties": {
+              "docker_platform": { "enum": ["linux/amd64", "linux/arm64"] },
+              "artifact_platform": { "enum": ["linux-x64", "linux-arm64"] },
+              "node_version": { "type": "string", "pattern": "^v[0-9]+\\.[0-9]+\\.[0-9]+$" }
+            },
+            "additionalProperties": false
+          }
+        },
+        "additionalProperties": false
+      }
+    },
     "trials": {
       "type": "array",
       "items": {

package/docs/schemas/eval-submission-input.schema.json

@@ -0,0 +1,14 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://agent-hitch.local/schemas/eval-submission-input.schema.json",
+  "title": "Hitch control-plane eval submission input V1",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["request"],
+  "properties": {
+    "schema_version": { "const": "1" },
+    "request": { "$ref": "eval-request.schema.json" },
+    "execution": { "$ref": "eval-submission.schema.json#/$defs/execution" },
+    "idempotency_key": { "type": "string", "minLength": 1, "maxLength": 256, "pattern": "^[!-~]+$" }
+  }
+}

package/docs/schemas/eval-submission.schema.json

@@ -0,0 +1,68 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://agent-hitch.local/schemas/eval-submission.schema.json",
+  "title": "Hitch control-plane eval submission V1",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schema_version", "eval_id", "request", "submission_digest", "submitted_at"],
+  "properties": {
+    "schema_version": { "const": "1" },
+    "eval_id": { "type": "string", "pattern": "^eval_[a-f0-9]{32}$" },
+    "request": { "$ref": "eval-request.schema.json" },
+    "execution": { "$ref": "#/$defs/execution" },
+    "submission_digest": { "type": "string", "pattern": "^sha256:[0-9a-f]{64}$" },
+    "idempotency_key_hash": { "type": "string", "pattern": "^sha256:[0-9a-f]{64}$" },
+    "submitted_at": { "type": "string", "format": "date-time" }
+  },
+  "$defs": {
+    "resources": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["cpu_millis", "memory_bytes", "container_slots", "build_slots"],
+      "properties": {
+        "cpu_millis": { "type": "integer", "minimum": 0 },
+        "memory_bytes": { "type": "integer", "minimum": 0 },
+        "container_slots": { "type": "integer", "minimum": 0 },
+        "build_slots": { "type": "integer", "minimum": 0 },
+        "gpu_count": { "type": "integer", "minimum": 0 },
+        "ephemeral_disk_bytes": { "type": "integer", "minimum": 0 }
+      }
+    },
+    "execution": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["provider", "max_parallelism", "resources", "build", "model_capture"],
+      "properties": {
+        "provider": { "type": "string", "minLength": 1 },
+        "max_parallelism": { "type": "integer", "minimum": 1 },
+        "resources": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["default_trial"],
+          "properties": {
+            "default_trial": { "$ref": "#/$defs/resources" },
+            "setup": { "$ref": "#/$defs/resources" }
+          }
+        },
+        "build": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["mode"],
+          "properties": {
+            "mode": { "enum": ["backend", "prebuild-preferred", "prebuild-required"] },
+            "remote_cache": { "type": "string", "minLength": 1 }
+          }
+        },
+        "model_capture": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["mode", "required"],
+          "properties": {
+            "mode": { "enum": ["off", "native", "proxy", "hybrid"] },
+            "required": { "type": "boolean" }
+          }
+        }
+      }
+    }
+  }
+}