# Runbook: Autonomous HPT SD qualification integration

Status: superseded
Type: runbook
Updated: 2026-09-23
Next Action: none; retained as history; any new execution requires a new explicit owner instruction
Campaign Reason: Cross-campaign coordination or operating guidance; intentionally tracked outside any single owner campaign.
Campaign: standalone
Parent: work/wp/active/wp-triple-mirrored-circular-hpt-log-store.md
Project Map: work/maps/map-smi-firmware-stabilization-and-qualification.md

## Boundary

This firmware repository does not implement or own HPT Lab Power Control. The
external system runs on `srv-rpi00.local` and supplies power sequencing. This
runbook defines only the stable integration contract needed by firmware
qualification and the evidence that must be collected.

The separate `sd_qualification` workspace on `srv-rpi00.local` is the runtime
consumer of this contract. It owns live orchestration and generated campaign
evidence after its foundation and controller-adapter gates pass. This firmware
workspace publishes the firmware-side contract and reviews returned manifests;
it does not directly schedule or execute G-PWR campaign cases.

The canonical external repository and deployed API were inspected on
2026-07-25. Use only the service-owned API/client; do not bypass it with direct
Shelly, GPIO, USB, relay, or J-Link service commands.

## Fixed topology

- Relay-controlled USB 5 V powers the J-Link.
- Relay-controlled line voltage feeds the controller's 24 VDC power supply.
- J-Link USB data/ground and target ribbon remain connected to the controller.
- Intended sequence:
  1. J-Link USB 5 V off.
  2. Wait 10 seconds.
  3. Controller PSU line voltage off.
  4. Keep both off for 30 seconds.
  5. Controller PSU line voltage on.
  6. Wait 10 seconds for normal boot.
  7. J-Link USB 5 V on.

## External interface

| Operation | Canonical command | Required result |
| --- | --- | --- |
| Read relay/status state | `GET /api/v1/controllers/A/status` | hostname, channels, commanded/observed state, timestamp |
| Run qualified full-off cycle | `POST /api/v1/controllers/A/coordinated/cycle` | unique operation ID and timestamped verified sequence |
| Emergency all-off | `POST /api/v1/emergency-off` | controller and J-Link power reported off; separately authorized |
| Read cycle/result | `GET /api/v1/operations/{operation_id}` | durable machine-readable terminal state and failure reason |

All access must use `srv-rpi00.local` or another stable hostname advertised by
the external project, never a hard-coded LAN address.

## G-PWR qualification gate

`G-PWR-A: Automated Group A power-down method qualified` passes only when:

- [x] Final wiring and the always-connected USB data/ground and target ribbon
  topology are recorded.
- [x] The canonical hostname-based API/client and machine-readable result schema are
  captured here.
- [x] At least three consecutive non-writing RAM-witness cycles prove a true
  controller reset with no surviving volatile armed/command/status state.
- [x] Each cycle records relay command and observed timestamps for all seven
  sequence steps.
- [x] Each recovery shows normal startup, HPT reopen, matching card CID,
  diagnostic availability, and resumed logging.
- [x] The already-qualified data-durable-before-commit boundary is repeated
  once using the automation as correlation evidence.
- [x] Any witness failure, relay-state mismatch, timeout, target mismatch, or
  unavailable diagnostic leaves G-PWR failed and blocks dependent runs.

The prior manually disconnected SWD witness is useful historical evidence but
does not qualify this permanently connected automation topology.

Qualification evidence:
`work/evidence/hpt-log-store-circular-mirror/controller-a/g-pwr-20260725/qualification-result.md`.

## Group B result and boundary

`G-PWR-B` passed fully on the current firmware with three independent
reset-witness cycles, exact Plug 2/J-Link/SWD verification, and identical
baseline/post-reboot CID captures. Evidence:
`work/evidence/hpt-log-store-circular-mirror/controller-b/g-pwr-full-20260725/qualification-result.md`.

This removes the Group B power/reset gate. Controller B's installed card
remains FAT/FileX media and was not destructively initialized, so HPT
media/data/endurance qualification remains a separate post-freeze activity.

## Autonomous run preflight

The approved campaign slice is represented by one immutable human
authorization envelope. The Pi mints a new short-lived, non-replayable machine
intent for every allowed Start, Stop, scrub, initialization, or interruption.
Read-only observation, preflight, polling, evidence publication, cleanup, and
reconciliation are automatic continuation. Request operator authorization again
only for changed identity/scope, an unlisted destructive action, replay of a
state-changing command, envelope expiry/revocation, physical intervention,
safety judgment, or credentials.

- Exact controller assembly, J-Link serial, firmware commit and image hashes.
- Service-467/equivalent CID block: protocol status, CID-valid and sector-read
  status, manufacturer/MID, OEM/application ID, product name/revision, serial,
  manufacture date, and raw 128-bit CID.
- Card sample/lot/capacity and authorization.
- HPT media generation, retained range, lane state, retirements, first storage
  error, and baseline full-address scrub result.
- Power-controller status, G-PWR evidence link, stop controls, isolated-bench
  fixture identity, and recovery route. Controllers A and B have no heater,
  load, or production connection; do not repeat a heat/alarm review per run.

## Per-interruption evidence

Record a unique cycle/run ID, armed firmware boundary, last acknowledged
sequence, relay timestamps/states, J-Link target status, boot/reset witness,
post-boot CID, HPT reopen state, recovered tail, lane/quorum state, retirements,
errors, resumed sequence, and export/readback checks.

Capture CID after every reboot, initialization, power-off reinsertion,
replacement, or other identity-relevant transition. Powered SD-card hot swap is
prohibited; simulate in-service media loss or use qualified whole-controller
power interruption instead. CID is identity evidence, not authenticity proof.

## Stop conditions

Stop and latch the run on:

- failed reset witness or power-state mismatch;
- controller/J-Link/card identity mismatch;
- unsafe or heating state;
- lost acknowledged data or false committed data;
- diagnostic/J-Link loss beyond the defined timeout;
- HPT reopen failure, unbounded failure count, or operator stop.

Power must remain in the safest known state and the run result must state
whether manual recovery is required.

## Execution order after G-PWR

1. Run the CID-pinned baseline full-address scrub before destructive
   authorization or HPT initialization.
2. Confirm the exact-scope authorization and initialize the assigned
   expendable sample.
3. Execute deterministic Controller A cuts at record data write, segment
   header/seal, reclaim/next-segment, and retirement-snapshot boundaries.
4. Run accelerated wrap/reclaim/readback/export with scheduled interruptions.
5. Run the post-endurance full-address scrub.
6. Program the identical frozen image on Controller B and repeat its firmware,
   CID, HPT, and data-integrity gates using the passed G-PWR-B method.
7. Execute the approved adaptive retail-card matrix with the initial pair
   split across A and B. Add a third or later sample only for a reviewed
   replacement, investigation, inconclusive, infrastructure-damaged, or
   additional-coverage reason.

## Owner-directed reconciliation — 2026-09-23

Historical external-qualifier coordination instruction retired following owner withdrawal of WP-0001/WP-0002 and the sample/family programme. Preserve its technical and no-replay rules as history; no remote runtime or campaign mutation is performed.

Authorization: Owner instruction in this conversation on 2026-09-23 to close/abandon the named work and mitigate older active records.

Previous header retained for evidence interpretation:

> Status: ready external integration contract; G-PWR-A and G-PWR-B methods passed fully
> Next Action: none in this firmware workspace; the srv-rpi00.local qualifier may invoke the service-owned API/client only after its live-controller readiness gate and case-specific authorization pass

Earlier observations, unchecked historical criteria, and procedures below/above remain history. This administrative disposition does not qualify a new firmware candidate, physical card, thermal system, ECO, or release. Current 00.05.01 obligations in IDEA-0006, IDEA-0007, MAP-0009, and CAMP-0028 remain unchanged.
