# HPT initialization adapter

`hpt-initialization-adapter` is the protected one-shot path for destructive
HPT media 2.0 whole-card initialization. It replaces the legacy practice of
writing firmware-private request variables through a debugger.

The adapter requires all of the following before it can publish:

- a non-fixture campaign assignment at `BASELINE_SCRUB_PASSED`;
- the latest valid campaign CID capture and the exact expected raw CID;
- an immutable `HPT_INITIALIZE` authorization envelope confirming stable
  non-heating state and explicit whole-card erasure authority;
- exact bundle, S-record, diagnostic mapping, controller registry, assembly,
  probe, hardware variant, and live full-flash identity;
- an idle fixed initialization mailbox/acknowledgement/status interface;
- a stable boot-session witness and initialization-eligible media state.

The durable machine intent contains unique operation and request UUIDs,
strictly increasing command/publication sequences, the exact CID, boot
witness, bundle/artifact/mapping hashes, and authorization expiry. Publication
writes only the 256-byte fixed mailbox using aligned `w4` operations. The
firmware SD owner validates and consumes that mailbox exactly once.

After any mailbox write, replay is prohibited. The adapter uses only read-only
reconciliation, requires two coherent terminal observations, and records
immutable transcript/result evidence. A passing result additionally requires
a fresh post-initialization controller snapshot and CID capture with raw CID,
protocol/CID/sector validity, manufacturer/MID, OEM ID, product/revision,
serial, and manufacturing date.

The service is disabled by default:

```dotenv
SDQ_HPT_INITIALIZATION_CONTROLLER_ROLES=
SDQ_CONTROLLER_A_HPT_INITIALIZATION_ENDPOINT=
SDQ_CONTROLLER_B_HPT_INITIALIZATION_ENDPOINT=
```

Campaigns are created fixture-only. After the exact baseline scrub passes, bind
the immutable post-scrub flash/CID observation to that scrub. This advances
only the exact assignment to `BASELINE_SCRUB_PASSED` and never contacts the
target:

```sh
docker compose run --rm web \
  python manage.py bind_post_baseline_scrub_observation \
  --campaign-id CAMPAIGN_UUID --sample-label SAMPLE --controller-role A \
  --observation-operation-id OBSERVATION_UUID --result-sha256 RESULT_SHA256 \
  --expected-cid RAW_CID --full-address-scrub-operation-id SCRUB_UUID \
  --operator STAFF_USER
```

Before an initialization envelope can be recorded, the protected promotion
command must bind one exact expendable sample to its passed baseline scrub,
post-scrub flash/CID observation, firmware bundle, controller registry
identity, isolated non-heating bench fact, and external authorization
reference. Promotion accepts the pre-run `INTAKE`/`BASELINE_READY` path or an
already-running campaign only when its durable coordinator is idle and waiting
at the exact controller initialization node. Promotion never contacts the
target and is irreversible through this command:

```sh
docker compose run --rm web \
  python manage.py promote_hpt_initialization_campaign \
  --campaign-id CAMPAIGN_UUID --sample-label SAMPLE --controller-role A \
  --bundle-id BUNDLE --expected-cid RAW_CID --operator STAFF_USER \
  --authorization-reference REVIEW_REFERENCE \
  --confirm-isolated-non-heating-bench \
  --authorize-live-controller-media-operation
```

This transition does not enable a controller registry role or endpoint, admit
HPT2 endurance profiles, or publish an initialization mailbox. Those remain
separate exact-operation gates.

Approval and execution are intentionally separate:

An authenticated reviewer or administrator may create the exact envelope from
the campaign-sample page after the server confirms the assignment is at
`BASELINE_SCRUB_PASSED` and derives the bundle, role, and latest complete CID
from durable records. The form requires both safe-state and whole-card erasure
confirmation. It records an append-only campaign event with
`target_access_started=false`.

The page displays the active envelope plus immutable operation and phase
history, but exposes no preparation, publication, execution, or reconciliation
action. The web container has no controller endpoint. Machine-intent creation
still begins with the one-shot tools service because initialization preparation
includes a fresh read-only target preflight.

The equivalent bounded command-line envelope path remains available:

```sh
docker compose --profile tools run --rm hpt-initialization-adapter \
  python manage.py approve_hpt_initialization_envelope \
  --campaign-id CAMPAIGN_UUID --sample-label SAMPLE --controller-role A \
  --bundle-id BUNDLE --expected-cid RAW_CID --expires-at ISO_TIMESTAMP \
  --operator USER --reference REVIEW_REFERENCE \
  --confirm-non-heating-safe-state --authorize-whole-card-erasure

docker compose --profile tools run --rm hpt-initialization-adapter \
  python manage.py hpt_initialize \
  --operation-id NEW_UUID --campaign-id CAMPAIGN_UUID \
  --sample-label SAMPLE --controller-role A --bundle-id BUNDLE \
  --expected-cid RAW_CID --actor USER \
  --authorization-envelope-id ENVELOPE_UUID
```

If publication becomes ambiguous, do not run `hpt_initialize` again. Continue
only with:

```sh
docker compose --profile tools run --rm hpt-initialization-adapter \
  python manage.py reconcile_hpt_initialization OPERATION_UUID
```

The adapter does not reset or program a controller, operate power, move media,
or permit powered SD removal/insertion.
