feat(conductor): add TPU production evidence contract

changelog.md

@@ -762,3 +762,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Added fixture-backed evidence obsolescence and refresh VOI with evidence age, drift, cadence, living-review, model-refresh, CLI, Astro documentation, and frontier-contract diagnostics.
 - Added fixture-backed strategic behavior and game-theoretic VOI with equilibrium, incentive, disclosure, bargaining, regret, adversarial, CLI, Astro documentation, and frontier-contract diagnostics.
 - Added unified accelerator evidence packet validation and deterministic indexing for passed GPU and blocked TPU/Metal runs, preserving CPU fallback and external-gate reasons.
+## Unreleased
+
+- Added a machine-readable TPU production-scale evidence contract with CPU
+  fallback, EVPI parity, compile/transfer overhead, deterministic indexing, and
+  an explicit Colab/gcloud availability gate.

conductor/tracks.md

@@ -592,7 +592,7 @@ Only the numbered `[ ]` entries in this section are eligible for automatic
 ## [ ] Track: TPU Production-Scale Colab Evidence
 *Link: [./tracks/tpu-production-scale-colab-evidence_20260625/](./tracks/tpu-production-scale-colab-evidence_20260625/)*
 *Execution order: 31 of 32*
-*Status: follow-through track for production-scale TPU benchmark evidence after compact Colab v5e visibility and parity proof.*
+*Status: repository-owned TPU/CPU packet schema, deterministic validator, CPU fallback, and explicit unavailable-runtime packet are in progress; production TPU speedup remains blocked on authenticated Colab/gcloud quota and allocation.*
 
 ---
 

conductor/tracks/tpu-production-scale-colab-evidence_20260625/handoff/packets/cpu-reference.json

@@ -0,0 +1 @@
+{"backend":"cpu","status":"passed","owner":"voiage-maintainers","source_command":"uv run python -m pytest tests/test_tpu_speedup_evidence.py --no-cov","timestamp":"2026-07-17T00:00:00Z","device_metadata":{"device":"host-cpu","runtime":"local"},"workload_hash":"sha256:tpu-production-reference","workload_scale":"production","warmup_iterations":2,"timing_seconds":1.0,"throughput":1.0,"cpu_baseline_seconds":1.0,"speedup":1.0,"transfer_overhead_seconds":0.0,"compile_overhead_seconds":0.0,"result_parity":true,"cpu_fallback":true,"claim_level":"reference"}

conductor/tracks/tpu-production-scale-colab-evidence_20260625/handoff/packets/tpu-blocked.json

@@ -0,0 +1 @@
+{"backend":"tpu","status":"blocked","owner":"voiage-maintainers","source_command":"colab TPU runtime / gcloud TPU allocation probe (not authenticated)","timestamp":"2026-07-17T00:00:00Z","device_metadata":{"device":"TPU v5e","runtime":"Colab or gcloud","visibility":"not verified"},"workload_hash":"sha256:tpu-production-blocked","workload_scale":"production","warmup_iterations":0,"timing_seconds":0.0,"throughput":0.0,"cpu_baseline_seconds":1.0,"speedup":0.0,"transfer_overhead_seconds":0.0,"compile_overhead_seconds":0.0,"result_parity":false,"cpu_fallback":true,"claim_level":"blocked","blocked_reason":"No authenticated Colab TPU runtime, gcloud project/quota, billing, and TPU allocation are available in this environment; compact v5e visibility/parity evidence cannot establish production-scale speedup."}

conductor/tracks/tpu-production-scale-colab-evidence_20260625/handoff/tpu-index.json

@@ -0,0 +1,19 @@
+{
+  "packets": [
+    {
+      "artifact_path": "packets/cpu-reference.json",
+      "backend": "cpu",
+      "claim_level": "reference",
+      "sha256": "4d00a30baab89d5d49ed62296fe5281b511a9242419da142f394c193ad479011",
+      "status": "passed"
+    },
+    {
+      "artifact_path": "packets/tpu-blocked.json",
+      "backend": "tpu",
+      "claim_level": "blocked",
+      "sha256": "a507b0dd77fdc7ed600f01a814bd7d0f91f765bcfd791af34124941cff86ab0d",
+      "status": "blocked"
+    }
+  ],
+  "schema_version": "v1"
+}

conductor/tracks/tpu-production-scale-colab-evidence_20260625/handoff/tpu-manifest.json

@@ -0,0 +1 @@
+{"schema_version":"v1","packets":[{"artifact_path":"packets/cpu-reference.json"},{"artifact_path":"packets/tpu-blocked.json"}]}

conductor/tracks/tpu-production-scale-colab-evidence_20260625/metadata.json

@@ -1,8 +1,8 @@
 {
   "track_id": "tpu-production-scale-colab-evidence_20260625",
   "type": "feature",
-  "status": "new",
+  "status": "in_progress",
   "created_at": "2026-06-25T00:00:00Z",
-  "updated_at": "2026-06-25T00:00:00Z",
+  "updated_at": "2026-07-17T16:45:00Z",
   "description": "Extend Colab v5e visibility and EVPI parity into production-scale TPU benchmark packets."
 }

conductor/tracks/tpu-production-scale-colab-evidence_20260625/plan.md

@@ -70,6 +70,12 @@
     - [ ] Keep external gates explicit and evidence-backed.
 - [ ] Task: Conductor - User Manual Verification 'Phase 4: Documentation, Review, And CI Closure' (Protocol in workflow.md)
 
+## Execution Evidence
+
+- Added `scripts/validate_tpu_speedup_evidence.py` and `specs/tpu-speedup-evidence/v1/schema.json`.
+- Added a deterministic CPU reference packet and a TPU blocked packet preserving compile/transfer overhead, EVPI parity, CPU fallback, and production-scale fields.
+- External gate: no authenticated Colab TPU runtime or gcloud project/quota/billing/TPU allocation is available; compact v5e visibility/parity evidence does not prove production speedup.
+
 ## Verification Commands
 
 - [ ] `uv run pytest tests/test_conductor_followthrough_tracks.py --no-cov`

docs/astro-site/src/content/docs/developer-guide/hpc-native-roadmap.mdx

@@ -56,6 +56,16 @@ compile overhead, result parity, and CPU fallback. Colab or cloud quota/runtime
 unavailability is recorded as blocked; a T4 visibility/parity packet is not a
 production-sized speedup claim.
 
+## TPU production-scale evidence
+
+The TPU follow-through track requires production-scale workload hashes, warm-up
+and repeated timings, throughput, CPU comparison, compile and transfer overhead,
+EVPI result parity, and CPU fallback. The current handoff contains a deterministic
+CPU reference and an explicit TPU blocked packet: compact Colab v5e visibility or
+parity does not prove speedup. A production TPU claim remains gated on an
+authenticated Colab TPU runtime or gcloud project with quota, billing, and TPU
+allocation.
+
 ## Contract rules
 
 - CPU behavior stays the reference path until an accelerator proves itself

scripts/validate_tpu_speedup_evidence.py

@@ -0,0 +1,144 @@
+"""Validate TPU production-scale benchmark packets."""
+
+from __future__ import annotations
+
+import argparse
+import hashlib
+import json
+from pathlib import Path
+from typing import Any
+
+REQUIRED = {
+    "backend",
+    "status",
+    "owner",
+    "source_command",
+    "timestamp",
+    "device_metadata",
+    "workload_hash",
+    "workload_scale",
+    "warmup_iterations",
+    "timing_seconds",
+    "throughput",
+    "cpu_baseline_seconds",
+    "speedup",
+    "transfer_overhead_seconds",
+    "compile_overhead_seconds",
+    "result_parity",
+    "cpu_fallback",
+    "claim_level",
+}
+
+
+def _load(path: Path) -> dict[str, Any]:
+    value = json.loads(path.read_text(encoding="utf-8"))
+    if not isinstance(value, dict):
+        raise TypeError(f"{path}: expected a JSON object")
+    return value
+
+
+def validate_manifest(path: Path) -> dict[str, Any]:
+    """Validate TPU/CPU packets and return a deterministic artifact index."""
+    manifest = _load(path)
+    packets = manifest.get("packets")
+    if not isinstance(packets, list) or not packets:
+        raise ValueError("manifest.packets must be a non-empty list")
+    root = path.parent.resolve()
+    index: list[dict[str, Any]] = []
+    for entry in packets:
+        if not isinstance(entry, dict) or not isinstance(
+            entry.get("artifact_path"), str
+        ):
+            raise TypeError("packet artifact_path must be a non-empty string")
+        artifact = entry["artifact_path"]
+        packet_path = (root / artifact).resolve()
+        try:
+            packet_path.relative_to(root)
+        except ValueError as exc:
+            raise ValueError(f"artifact escapes manifest root: {artifact}") from exc
+        if not packet_path.is_file():
+            raise ValueError(f"missing packet artifact: {artifact}")
+        packet = _load(packet_path)
+        missing = sorted(REQUIRED - packet.keys())
+        if missing:
+            raise ValueError(f"{artifact}: missing fields {missing}")
+        if packet["backend"] not in {"cpu", "tpu"}:
+            raise ValueError(f"{artifact}: backend must be cpu or tpu")
+        if packet["status"] not in {"passed", "blocked", "not_available", "failed"}:
+            raise ValueError(f"{artifact}: unsupported status")
+        if packet["claim_level"] not in {"reference", "blocked", "production_speedup"}:
+            raise ValueError(f"{artifact}: unsupported claim_level")
+        if (
+            not isinstance(packet["device_metadata"], dict)
+            or not packet["device_metadata"]
+        ):
+            raise ValueError(f"{artifact}: device_metadata must be non-empty")
+        if not isinstance(packet["owner"], str) or not packet["owner"].strip():
+            raise ValueError(f"{artifact}: owner must be non-empty")
+        if (
+            not isinstance(packet["workload_hash"], str)
+            or len(packet["workload_hash"]) < 8
+        ):
+            raise ValueError(f"{artifact}: workload_hash must identify workload")
+        if packet["workload_scale"] not in {"production", "representative", "smoke"}:
+            raise ValueError(f"{artifact}: invalid workload_scale")
+        if (
+            not isinstance(packet["warmup_iterations"], int)
+            or packet["warmup_iterations"] < 0
+        ):
+            raise ValueError(f"{artifact}: warmup_iterations must be non-negative")
+        if packet["status"] == "passed":
+            if packet["timing_seconds"] <= 0 or packet["throughput"] <= 0:
+                raise ValueError(
+                    f"{artifact}: passed packets require positive measurements"
+                )
+            if packet["cpu_baseline_seconds"] <= 0 or not packet["result_parity"]:
+                raise ValueError(
+                    f"{artifact}: passed packets require CPU baseline and parity"
+                )
+            if (
+                packet["transfer_overhead_seconds"] < 0
+                or packet["compile_overhead_seconds"] < 0
+            ):
+                raise ValueError(f"{artifact}: overhead values must be non-negative")
+            if packet["backend"] == "tpu" and packet["speedup"] <= 1:
+                raise ValueError(f"{artifact}: TPU packet requires speedup > 1")
+            if (
+                packet["claim_level"] == "production_speedup"
+                and packet["workload_scale"] != "production"
+            ):
+                raise ValueError(
+                    f"{artifact}: production speedup requires production workload"
+                )
+        elif not packet.get("blocked_reason"):
+            raise ValueError(f"{artifact}: non-passed packets require blocked_reason")
+        index.append(
+            {
+                "backend": packet["backend"],
+                "status": packet["status"],
+                "claim_level": packet["claim_level"],
+                "artifact_path": artifact,
+                "sha256": hashlib.sha256(packet_path.read_bytes()).hexdigest(),
+            }
+        )
+    return {"schema_version": manifest.get("schema_version", "v1"), "packets": index}
+
+
+def main() -> int:
+    """Validate a manifest and optionally write its deterministic index."""
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("manifest", type=Path)
+    parser.add_argument("--output", type=Path)
+    args = parser.parse_args()
+    output = (
+        json.dumps(validate_manifest(args.manifest), indent=2, sort_keys=True) + "\n"
+    )
+    if args.output:
+        args.output.write_text(output, encoding="utf-8")
+    else:
+        print(output, end="")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

specs/tpu-speedup-evidence/v1/schema.json

@@ -0,0 +1,17 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "voiage TPU production speedup evidence packet",
+  "type": "object",
+  "required": ["backend", "status", "owner", "source_command", "timestamp", "device_metadata", "workload_hash", "workload_scale", "warmup_iterations", "timing_seconds", "throughput", "cpu_baseline_seconds", "speedup", "transfer_overhead_seconds", "compile_overhead_seconds", "result_parity", "cpu_fallback", "claim_level"],
+  "properties": {
+    "backend": {"enum": ["cpu", "tpu"]},
+    "status": {"enum": ["passed", "blocked", "not_available", "failed"]},
+    "workload_scale": {"enum": ["production", "representative", "smoke"]},
+    "warmup_iterations": {"type": "integer", "minimum": 0},
+    "transfer_overhead_seconds": {"type": "number", "minimum": 0},
+    "compile_overhead_seconds": {"type": "number", "minimum": 0},
+    "result_parity": {"type": "boolean"},
+    "cpu_fallback": {"type": "boolean"},
+    "claim_level": {"enum": ["reference", "blocked", "production_speedup"]}
+  }
+}

tests/test_tpu_speedup_evidence.py

@@ -0,0 +1,37 @@
+"""Tests for TPU production evidence boundaries."""
+
+from pathlib import Path
+
+import pytest
+
+from scripts.validate_tpu_speedup_evidence import validate_manifest
+
+TRACK_ID = "tpu-production-scale-colab-evidence_20260625"
+MANIFEST = Path("conductor/tracks") / TRACK_ID / "handoff/tpu-manifest.json"
+
+
+def test_manifest_indexes_cpu_reference_and_tpu_gate() -> None:
+    index = validate_manifest(MANIFEST)
+    assert [item["backend"] for item in index["packets"]] == ["cpu", "tpu"]
+    assert [item["status"] for item in index["packets"]] == ["passed", "blocked"]
+    assert all(item["sha256"] for item in index["packets"])
+
+
+def test_validator_rejects_tpu_without_speedup(tmp_path: Path) -> None:
+    packet = tmp_path / "packet.json"
+    packet.write_text(
+        '{"backend":"tpu","status":"passed","owner":"test","source_command":"x",'
+        '"timestamp":"2026-07-17T00:00:00Z","device_metadata":{"device":"v5e"},'
+        '"workload_hash":"sha256:test","workload_scale":"production",'
+        '"warmup_iterations":1,"timing_seconds":1.0,"throughput":2.0,'
+        '"cpu_baseline_seconds":2.0,"speedup":1.0,"transfer_overhead_seconds":0.1,'
+        '"compile_overhead_seconds":0.1,"result_parity":true,"cpu_fallback":false,'
+        '"claim_level":"production_speedup"}',
+        encoding="utf-8",
+    )
+    manifest = tmp_path / "manifest.json"
+    manifest.write_text(
+        '{"packets":[{"artifact_path":"packet.json"}]}', encoding="utf-8"
+    )
+    with pytest.raises(ValueError, match="speedup"):
+        validate_manifest(manifest)

todo.md

@@ -7,7 +7,8 @@ This document lists the actionable tasks for `voiage` development. Agents should
 
 ## In Progress
 
-*None at the moment.*
+*   [ ] Complete the TPU production-scale Colab evidence track, preserving the
+    authenticated runtime/quota gate when production hardware is unavailable.
 
 ## Done