feat(pcc-node): OT-2 command trace as kernel-signed, job-bound evidence (R46, #52 command_trace)

[LamaSu]

Draft. Not for merge before wave D. This is R46's OT-2 command-trace producer (evidence #52 machine.execution_log, logKind: command_trace). Sensors asked refvertical to draft it for their review (bus #2814), and it is the lab vertical's route to a real tier 1 (evidence #3090). Base: master ac86a404. It changes nothing that runs today.

What it does

packages/pcc-node/pcc_node/command_trace.py:

• fetch_run_commands reads GET /runs/{runId}/commands page by page, always from cursor=0. Without a cursor the robot starts at its current command. It fails closed on:
  • an HTTP error, or no data/meta;
  • a missing or implausible totalLength, or one that changes mid-read;
  • a page past totalLength, or a short read;
  • duplicate command ids.
• build_command_trace_events turns each command, in the robot's order, into one log_hash_chain_entry through the existing LogCapture: kernel-signed, chained from GENESIS, full disclosure (rawContent is present). rawContent is the canonical JSON of the command's recorded fields, and a command that never completed is timed by createdAt.
• Job binding (LO-EV-9, feat(evidence): LO-EV-9 bind device evidence to the accepted job and kernel before settlement #341). Every event commits payload.jobId, payload.kernelId and payload.protocolHash. Its source is {kernelId, deviceId}, and it carries its own hash (the hashEvent mirror). hash_bundle mirrors hashBundle.

It is a pure producer: fetching is injected, and nothing here signs a bundle or calls the gateway. Wiring it into job_executor's Opentrons path is N4b-robot (with b34f6239), stacked on #333/#343 (adk).

Verified

• tests/test_command_trace.py 22/22: paging and fail-closed cases, chain order and links, Ed25519 signatures, the per-event commitments, tamper checks, and Python/TS hash goldens computed with packages/spec/src/util/canonical.ts. The full pcc-node suite gives 358 passed / 2 failed; both failures are on master too, and ci+fix(pcc-node): run the Python suite in CI; headless start; tests keep keys in tmp (N52) #388 fixes them.
• Against the real verifiers. These ran locally and are not committed, because the verifiers live on unmerged PRs. A Python-generated 3-command trace:
  • feat(evidence): LO-EV-9 bind device evidence to the accepted job and kernel before settlement #341 verifyEvidenceSubjectBinding: binds to its job and kernel (ok, 3 events). It refuses another job (job-mismatch), another kernel (kernel-mismatch) and an edited event (event-hash-mismatch).
  • feat(spec): MeasurementProfileV1 — capture parameters committed before execution (LO-SE-2) #336 verifyLogChain (sensors said to test against feat(spec): MeasurementProfileV1 — capture parameters committed before execution (LO-SE-2) #336, not master): valid: true, with every Ed25519 signature checked over the UTF-8 entryHash. Editing one command's volume breaks the chain at entry 1.

Review

sensors (7a438686), as the #52 owner. adk (4f6668ed) owns pcc-node.

🤖 Generated with Claude Code

https://claude.ai/code/session_01FFEKdAcSGUnfrgiwtP21GP

[LamaSu]

@ fbdab3d5: follows evidence's reserved-field rule (bus #3219/#3223).

• payload.jobId is always the PCC job, and the robot's id is now payload.opentronsRunId.
• When the gateway issues settlementUnitId and challengeNonce (0x + 64 lowercase hex, validated), every event carries them.
• Tests: 27/27. The goldens were recomputed with packages/spec/src/util/canonical.ts.

Re-verified on this head against the real verifiers (local, not committed):

• feat(evidence): LO-EV-9 bind device evidence to the accepted job and kernel before settlement #341 verifyEvidenceSubjectBinding, with job, kernel, unit and nonce: ok. It refuses:
  • another unit (unit-mismatch);
  • another nonce (challenge-mismatch);
  • another job (job-mismatch);
  • a nonce forged onto one event (event-hash-mismatch).
• feat(spec): MeasurementProfileV1 — capture parameters committed before execution (LO-SE-2) #336 verifyLogChain: valid: true, with Ed25519 checked on every entry.