# Build the independent HPT media validator for Pi qualification Workpackage

Status: active
Type: workpackage
Updated: 2026-08-02
Next Action: wait for an explicitly selected expendable card, identified external Pi reader, and separate powered-off transfer/read-only authorization before Stage 6; do not use the installed Controller A/B control cards
Campaign Reason: Historical record from campaign 012-prove-independent-hpt-media-validation; retained independently after campaign closure and requires no separate owner-queue execution.
Campaign: standalone
Project Map: work/maps/map-smi-firmware-stabilization-and-qualification.md
Canonical Truth: `jong@srv-rpi00.local:~/dev/HPT-Embedded-Log-Store/README.md`, `docs/`, and public headers

## Planning Authority and Repository Boundary

This workpackage in `E:/dev/high_point/7520553_SMI_FW/work/` is the sole active
Tool Shed plan for development of the HPT portable core and independent Pi
media validator. Source, tests, tools, specifications, releases, and host/raw-
media evidence remain authoritative in
`jong@srv-rpi00.local:~/dev/HPT-Embedded-Log-Store`.

The HPT repository does not own Renesas firmware, controller/J-Link access,
campaign orchestration, operator UI, card inventory, email, power control, or
qualification approval. Its validator supplies measured media facts to the
`sd_qualification` application through a pinned executable/library release and
a versioned machine-readable result contract.

## Current Baseline

- Released portable core and validator: v0.5.0, tag commit
  `d7b1dbe88917e6e8afb59ca2104f6fb411b16d8d`, with release documentation on
  clean `main` at `0705d6ef028cde31308e2277d7ead202f35ef714`.
- Released media contract: media format 2.0, triple-mirrored circular.
- Existing capabilities: portable block-device API, file-image and Linux
  raw-block adapters, bounded recovery/iteration, inspect/recover/export tools,
  deterministic vectors, fault injection, raw-SD preflight, and raw-media
  evidence.
- Required controller contract: the adopted SMI HPT media-2.0 layout,
  triple-mirror/quorum behavior, circular retention/reclaim semantics, and
  controller-generated records.
- PR #2 merged the specification/vector audit, fail-closed metadata
  corrections, retention/pin behavior, and bounded validator. The v0.5.0
  release publishes source archives and a Linux aarch64 tool bundle containing
  the result/evidence schemas and compatibility vector. Corruption, I/O,
  timeout, malformed-output, partial-scan, and tamper negatives pass. This is
  an immutable software release, not controller or physical-card evidence.
- `/sd-qualifier` imports outer manifest
  `91135e68053a0bc019cfc9e3471ba3544eb882cb16114ebede521712de76e7c7`
  and fixture-admits executable
  `040b8646600ccd0784d2a24f74bbe6e78425da341363c9eb9fde5f3ff7e7d3a4`.
  Invocation and result ingestion remain open; raw-device admission remains
  disabled.

Media-1.0 success must not be represented as validation of media 2.0. The
validator must share exact compatibility vectors and a pinned format identity
with the SMI adoption before its result can influence a campaign.

## Goal

Publish a portable, independently testable HPT media-2.0 core and a read-only
validator that `/sd-qualifier` can invoke after an operator powers off a
controller and moves the exact SD card into an identified Pi reader. The
validator must inspect the medium without trusting the controller's own HPT
interpretation and return bounded, machine-readable facts for the campaign.

The intended path is:

```text
Controller powered off and card identity recorded
                |
Operator moves the card to an identified Pi reader
                |
/sd-qualifier proves device/card identity and read-only admission
                |
Pinned HPT validator inspects the exact device read-only
                |
Versioned result manifest and evidence return to /sd-qualifier
                |
Reviewer compares independent media facts with controller results
```

## Service Contract

### Inputs owned by `/sd-qualifier`

- explicit stable device path or immutable image path;
- expected card sample/CID and campaign identity;
- expected HPT media-format and validator release identity;
- expected geometry and bounded scan/profile limits;
- evidence destination supplied through a confined server-side interface;
- proof that the controller is powered off for any physical card move;
- proof that the source is unmounted, not the Pi boot/system device, and
  admitted read-only.

The validator must never discover or choose a device from enumeration order,
a broad glob, or browser input.

### Outputs owned by the HPT validator

The versioned result must include at least:

- validator version, source commit, executable/archive SHA-256, and schema ID;
- source identity, logical geometry, scan bounds, timestamps, and exit status;
- media-format identity and supported/unsupported determination;
- all media-2.0 mirror/header identities and their validity;
- quorum selection, disagreement, generation, and recovery state;
- lane/segment/reclaim/retirement state and first structural or I/O error;
- committed sequence range, record count, continuity, CRC/integrity outcomes,
  retained-window completeness, and bounded-scan completion;
- explicit `PASS`, `FAIL`, `BLOCKED`, or `INCONCLUSIVE` classification derived
  only from recorded facts and the selected reviewed profile;
- small evidence-manifest paths and hashes without embedding raw customer data
  or a raw card image.

### Explicit exclusions

The validator does not:

- program, reset, halt, inspect, or command a controller;
- mount, repair, format, write, discard, or automatically modify the SD card;
- select a block device or bypass `/sd-qualifier` admission;
- operate relays or determine controller power state;
- send email or request operator actions;
- approve a card family or firmware release;
- treat CID or a certificate as proof of authenticity.

## Integration Requirements

- `/sd-qualifier` imports a pinned HPT validator bundle using the same
  content-addressed and review/admission principles as firmware bundles.
- The Pi app owns the operator page, intervention state, exact device/card
  binding, command lease, timeout, cancellation, result storage, and reviewer
  disposition.
- The validator returns structured facts; Django templates and operators do
  not declare pass/admission state.
- A timeout, partial scan, unsupported format, identity mismatch, missing
  mirror, storage error, or absent terminal manifest cannot become `PASS`.
- Controller-observed results and Pi-observed media results remain separate
  evidence sources and are compared explicitly.
- Reinsert the card only while the controller is powered off and capture a
  fresh controller CID identity after reboot before associating later results.

## Delivery Stages

| Stage | Outcome | Exit Gate |
| --- | --- | --- |
| 0. Consolidate planning authority | This workpackage carries HPT development; remote `work/` is historical/reference | Local map/index and remote directives agree without losing existing dirty planning edits |
| 1. Reconcile media-2.0 truth | SMI format implementation, portable spec, resource limits, and vectors agree | Reviewed format/API contract and byte-exact positive/negative vectors exist |
| 2. Implement portable media-2.0 reader | Core opens and scans controller-compatible images read-only with bounded memory | GCC/Clang, warnings, sanitizers, static analysis, deterministic vectors, corruption tests, and randomized recovery tests pass |
| 3. Implement validator CLI/API | Explicit image/device input produces one stable JSON result and evidence manifest | Read-only, wrong-device, unsupported-version, partial-scan, timeout, corruption, and I/O-negative tests pass |
| 4. Publish immutable release | Source, executable/tool bundle, schema, vectors, and hashes are released | Tag, commit, archive/tool hashes, release notes, and compatibility matrix agree |
| 5. Integrate fixture mode | `/sd-qualifier` imports and invokes the pinned validator against images/fixtures | App admission, command, result, evidence, and UI tests pass without raw devices |
| 6. Qualify read-only physical inspection | One explicitly selected expendable card is inspected through the Pi reader | Stable identity, unmounted/system-device exclusion, complete scan, evidence, and safe removal/reinsertion gates pass |
| 7. Use in standalone campaigns | Independent validation is a normal post-controller campaign stage | Results survive restart, remain version-bound, compare cleanly with controller evidence, and cannot silently approve on missing data |

Stages 0-5 are complete as of 2026-08-02. The firmware/portable byte-equivalence
audit, deterministic vector, portable reader, fail-closed CLI/result/evidence
contract, host matrix, immutable v0.5.0 release, and Pi fixture admission pass.
The deployed Pi app invokes the admitted tool against an immutable fixture
image and persists its bounded terminal result/evidence without enabling a
block device. Stage 6 remains gated because no external reader/card is present
and the installed A/B cards are controls, not expendable specimens. See
`work/evidence/hpt-media2-v0-5-0-release-and-pi-fixture-admission-20260802.md`.

## Current Tasks

- [x] Retain `HPT-Embedded-Log-Store` as the portable-core and independent
  media-validator repository.
- [x] Move active HPT development planning into this Tool Shed.
- [x] Preserve the media-2.0 implementation checkpoint as clean, tested draft
  PR #2 without promoting it as a release or qualification result.
- [x] Audit the committed media-2.0 checkpoint against the adopted SMI truth
  without promoting or discarding it.
- [x] Reconcile the actual SMI media-2.0 encoding and compatibility vectors.
- [x] Implement bounded read-only media-2.0 open, quorum, traversal, and
  integrity validation.
- [x] Finish the validator JSON result and evidence-manifest negative contract,
  including corruption, I/O, timeout, malformed-output, partial-scan, and
  tamper cases.
- [x] Add an explicit raw-device read-only frontend that refuses unsafe or
  ambiguous sources.
- [x] Publish immutable media-2.0 core/validator release v0.5.0.
- [x] Integrate the pinned validator with `/sd-qualifier` fixture campaigns,
  including bounded invocation, terminal result/evidence publication, UI
  presentation, and a real deployed v0.5.0 fixture PASS.
- [ ] Add operator UI and intervention handling for physical card transfer,
  independent validation, reinsertion, and fresh CID capture.
- [ ] Run a separately authorized physical read-only validation campaign.
- [ ] Demonstrate standalone operation with this workspace disconnected.

## Completion Standard

Complete when `/sd-qualifier` can invoke a pinned HPT media-2.0 validator on an
explicitly identified Pi-attached card or immutable image, obtain complete and
bounded read-only results independent of the controller, preserve their exact
tool/card/campaign/evidence identity, and use them in a reviewed qualification
decision without giving the validator orchestration, physical-action, or
approval authority.
