# C-001 integrated reference harness

This is a CPU-safe, offline teaching harness for the complete C-001 path:

```text
Hermes request
→ repository and context
→ route and precision choice
→ prefix lookup
→ prefill
→ attention and MoE routing
→ operator and compiler lowering
→ kernel artifact slots
→ registers / shared memory / TMEM / L2 / HBM
→ KV placement and NIXL or NCCL movement
→ decode
→ tool execution
→ verifier
→ power, cooling, water, and cost receipt
```

The default output is architecture-only. It performs no network requests, does
not load GLM-5.2 weights, does not execute a GPU kernel, and emits:

```json
{
  "schema_version": "touchdown.hbm-c001-architecture-plan.v1",
  "fixture_id": "C-001",
  "run_id": null,
  "capture_kind": "architecture_only",
  "banner": "ARCHITECTURE ONLY / RUN NOT CAPTURED"
}
```

This architecture plan is not a run receipt. The harness emits
`touchdown.hbm-run-receipt.v1` only after explicit capture mode validates a
real non-placeholder run ID, synchronized clocks, and every required artifact.

Run it:

```bash
python3 c001_reference_harness.py --pretty
python3 -m unittest -v test_c001_reference_harness.py
python3 -m unittest -v test_c001_joined_resource_receipt.py
```

## Fail-closed capture mode

Capture mode exists only to join artifacts that already exist. It never starts
Hermes, a serving engine, a compiler, a GPU profiler, or a facility meter.

```bash
python3 c001_reference_harness.py \
  --capture-manifest /absolute/path/capture-manifest.json \
  --artifacts-dir /absolute/path/artifacts \
  --run-id <real-run-id> \
  --pretty
```

The capture manifest must use
`touchdown.hbm-c001-capture-artifacts.v1`, declare `capture_scope` as
`real_workload`, carry the same C-001 run ID, and provide every required
artifact kind with a SHA-256 that matches the file on disk. JSON artifacts that
contain a `run_id` must match the manifest. Every artifact entry itself must
carry that same run ID and all three independent evidence, coverage, and
observation states. The verifier controls the outcome; the harness never
converts file presence into acceptance.

The manifest also needs a synchronized-clock declaration. This is an explicit
receipt from the capture system, not a time source invented by this harness:

```json
{
  "schema_version": "touchdown.hbm-c001-capture-artifacts.v1",
  "fixture_id": "C-001",
  "comparison_id": "CMP-C001-V001",
  "capture_scope": "real_workload",
  "run_id": "<real-run-id>",
  "captured_at": "<RFC-3339 timestamp from the capture system>",
  "clock": {
    "status": "synchronized",
    "source": "<named time source or monotonic-to-wall mapping>",
    "max_skew_ms": 0,
    "artifact_timestamps_checked": true
  },
  "artifacts": [
    {
      "kind": "request",
      "run_id": "<real-run-id>",
      "path": "request.json",
      "sha256": "<64 lowercase hex characters>",
      "evidence_state": "measured",
      "coverage_state": "live_validated",
      "observation_state": "measured"
    }
  ]
}
```

The abbreviated example above is intentionally incomplete; capture mode still
requires every kind listed below. Paths must stay below `--artifacts-dir`.

Required kinds:

```text
request context route prefix_cache engine_trace operator_trace
compiler_artifacts kernel_profile memory_placement fabric tool verifier
power facility cost
```

Even in capture mode, missing numeric measurements remain `null`. GPU device
power is not added to a parent PDU meter. Coolant circulation, site-water
consumption, and electricity-generation water remain separate ledgers. Numeric
power, facility, or cost claims also require an `accounting` object declaring
that the double-counting check passed and water boundaries were kept separate.

A prefix-cache hit, miss, or partial-hit claim is rejected unless the artifact
identifies the exact model, tokenizer, engine, prefix digest, KV layout, and
precision. An accepted outcome is rejected unless the verifier explicitly says
`status: accepted`, `accepted: true`, and `tests_passed: true`, names the
acceptance boundary and checks, and carries measured, live-validated evidence.