# Spike: Cross-workspace SD qualification and Renesas target control architecture

Status: complete
Type: spike
Updated: 2026-07-27
Next Action: none; implementation continues in `PC-Redemption/sd-qualification`
Campaign Reason: Historical record from campaign 014-complete-standalone-sd-qualifier-acceptance; retained independently after campaign closure and requires no separate owner-queue execution.
Campaign: standalone
Parent: work/maps/map-smi-firmware-stabilization-and-qualification.md
Disposition: documented
Produces: none; this firmware workspace owns no implementation artifact from this architecture spike
Cross-Workspace Follow-Up: `PC-Redemption/sd-qualification/work/maps/map-standalone-sd-qualification-appliance.md` and `PC-Redemption/sd-qualification/work/wp/active/wp-standalone-pi-qualification-appliance-foundation.md`

## Question

How should `/home/jong/dev/sd_qualification` become the authoritative,
web-operated qualification system for SMI now and DDS later while reusing the
existing J-Link and HPT Lab Power Control methods, keeping firmware programming
useful outside qualification, and publishing trustworthy results back to each
firmware workspace?

## Timebox

Discussion and architecture capture only. Do not implement adapters, publish
firmware, program controllers, cycle power, initialize media, or run
qualification from this spike.

## Observed Current State

- `/home/jong/dev/sd_qualification` is a deployed fixture-first Django
  application with PostgreSQL, durable command and notification workers,
  Front Door routing, evidence publication, campaign/sample concepts, and
  fixture reports.
- Its current documentation explicitly excludes physical J-Link, programming,
  power, fault-injection, shell, and block-device adapters.
- The connected J-Links and USB devices are physically local to
  `srv-rpi00.local`.
- The current proven J-Link route uses serial-bound remote-server endpoints:
  Controller A uses J-Link `69664082` at `srv-rpi00.local:19120`; Controller B
  uses J-Link `69660123` at `srv-rpi00.local:19121`.
- The existing Windows-side firmware scripts already use those endpoints for
  programming, verification, target reads, reset, and qualification
  orchestration.
- HPT Lab Power Control already owns the qualified coordinated power sequence.
  The qualifier should call its narrow API and must not directly operate
  Shelly, GPIO, relays, or cables.
- e2 studio and Synergy project generation remain Windows build concerns.
  Linux SEGGER tooling can connect, program, verify, reset, and read target
  state from an already-built firmware bundle without e2.

## Architecture Discussed

Separate the system into these boundaries:

1. `sd_qualification` owns card-family/sample intake, campaigns, assignments,
   authorization, workflow, outcomes, review, immutable evidence registration,
   and qualification reports.
2. A general Renesas target-control component on `srv-rpi00.local` owns
   registered firmware bundles, probe locking, serial-bound J-Link operations,
   target identity, programming, verification, reset, and named diagnostic
   snapshots. It remains useful for development and recovery outside an SD
   campaign.
3. HPT Lab Power Control remains a separate least-privilege service. The
   qualifier coordinates it through the existing versioned API.
4. A USB adapter on `srv-rpi00.local` owns exact-device discovery, safe
   read-only collection, mount-state checks, and separately authorized
   destructive host-media actions.
5. Firmware workspaces produce immutable firmware bundles and consume compact
   qualifier result manifests. They do not duplicate the qualifier's raw
   evidence.

The qualifier should request only named, versioned actions. Browser requests
must never contain arbitrary shell commands, J-Link commands, memory
addresses, relay operations, or mutable firmware paths.

## Multiple-Firmware Profile Model

The qualifier must support multiple products and firmware generations. Freeze
these independent versioned inputs into every campaign:

- platform profile, such as Renesas S7G2/SWD/reset mechanics;
- product profile, such as SMI or DDS capabilities and diagnostic mappings;
- immutable firmware bundle;
- qualification test catalog/profile and acceptance thresholds;
- controller/fixture assignment.

Do not require SMI and DDS to share internal C symbol names. Standardize
semantic observations instead, for example:

- `target.hardware_variant`
- `target.firmware.version`
- `target.firmware.build_id`
- `target.safe_state`
- `target.reset_witness`
- `sd.protocol_status`
- `sd.cid_valid`
- `sd.sector_read_valid`
- `sd.identity.raw_cid`
- `hpt.format_version`
- `hpt.store_status`
- `hpt.lane_count`
- `hpt.active_lane_count`
- `hpt.retired_segments`
- `hpt.io_errors`
- `hpt.first_failure`
- `hpt.wrap_count`
- `qualification.state`
- `qualification.progress`
- `qualification.terminal_result`

Each product profile maps these semantic names to its exact implementation.
For current SMI, a legacy mapping generated from the exact ELF/map may be used.
For future SMI and DDS builds, prefer one versioned exported diagnostic root
such as `gQualificationApi`, containing magic, schema version, structure size,
capability bits, build identity, target status, SD identity, HPT status, and
run state. Commands should use a separate narrow mailbox with explicit safety
and timeout rules.

## Firmware Bundle Contract

Every qualifying build should publish one immutable, hash-bound bundle:

```text
<product>-<version>-<build-id>/
  firmware.srec
  firmware.elf
  firmware.map
  qualification-manifest.json
  symbols.json
  test-compatibility.json
  SHA256SUMS
```

The manifest should record product, platform profile, firmware version,
source/freeze commit, build configuration, diagnostic-contract version, and
the SHA-256 of every artifact. `symbols.json` should be generated from the
exact ELF so live runs do not depend on stale hand-maintained addresses.

Registered bundles should live outside repositories in a content-addressed,
read-only store such as:

```text
/var/lib/renesas-target-control/firmware/sha256/<bundle-hash>/
```

The qualifier stores the registered bundle ID and hashes. The browser selects
an already verified bundle rather than supplying a filesystem path.
Programming remains a separately authorized action even after a bundle is
registered.

## J-Link and e2 Boundary

- e2/Synergy remains responsible for authoritative generation and builds on
  Windows.
- `srv-rpi00.local` does not need e2 to program, verify, reset, or inspect an
  already-built target through SEGGER tools.
- Qualification should not depend on interactive source-level debugging.
  It should use semantic snapshots decoded through the hash-matched symbol
  manifest or versioned diagnostic ABI.
- A local Pi process cannot directly acquire a probe while the existing remote
  server owns it. Initial implementation should reuse the proven remote-server
  route or introduce an explicit, qualified probe-ownership handoff.
- Reusing the existing Windows runner is a viable first implementation:
  it receives only named actions, uses the established remote endpoints, and
  returns structured evidence. A later Linux implementation can satisfy the
  same adapter contract without changing campaigns or UI behavior.

## General Target-Control Boundary

Firmware loading should be available from `srv-rpi00.local` without making
`sd_qualification` a general programmer. A separate target-control CLI/service
should provide narrow operations such as:

```text
probe_identity
target_identity
read_firmware_identity
read_safe_state
read_sd_identity
read_qualification_status
program_registered_bundle
verify_registered_bundle
normal_reset
start_named_profile
request_bounded_stop
collect_named_snapshot
```

It should enforce per-probe locks, expected controller/probe identity,
registered bundle hashes, bounded timeouts, structured JSON results, and
immutable logs. The qualification UI may invoke these operations through a
short-lived authorization bound to the campaign, controller, bundle, and
action. A separate CLI can invoke them for development or recovery under its
own explicit authorization and audit context.

## Qualification Web Workflow Needed

The web application ultimately needs to cover:

1. procurement receipt and physical package/label inventory;
2. card-family and specimen creation;
3. power-off card assignment to a controller;
4. boot-time service-467 or equivalent CID identity capture;
5. firmware bundle and controller identity verification;
6. safe-state, recovery, evidence-storage, and authorization gates;
7. programming when the campaign requires it;
8. named test execution, live events, heartbeat, and bounded stop;
9. coordinated power-cycle operations where separately authorized;
10. terminal result ingestion and first-failure preservation;
11. specimen/family/systemic failure disposition;
12. reviewer approval or rejection;
13. compact immutable report and manifest publication.

Powered SD-card removal or insertion remains prohibited. Replacement and
reinsertion require controller power off. Identity must be captured at the run
baseline and after relevant replacement, power-off reinsertion,
initialization, or reboot.

## Cross-Workspace Result Contract

The qualifier should publish a compact result bundle containing:

- schema and tool versions;
- campaign, run, test, specimen, controller, firmware, and authorization IDs;
- controller/J-Link/firmware/card/CID snapshots;
- start/end timestamps and elapsed duration;
- final state, terminal reason, and first failure;
- measured counters and evaluated outcomes;
- missing evidence;
- raw-evidence locations and SHA-256 hashes;
- failure disposition and reviewer decision;
- report and manifest paths and hashes.

Each firmware repository should use a read-only synchronization/import command
to fetch the reviewed terminal result and manifest over an authenticated API
or approved Samba evidence location. It writes only a small versioned evidence
manifest under `work/evidence/`; raw logs remain owned by the qualifier.

## Proposed Implementation Sequence

1. Finalize the common semantic signal schema and real HPT media 2.0 test
   catalog.
2. Define the immutable firmware-bundle schema and produce the first SMI
   bundle from the exact candidate artifacts.
3. Implement qualifier result export and firmware-workspace import before
   physical automation.
4. Add read-only J-Link target/firmware/safe-state/CID/status operations and
   prove serial-bound A/B routing.
5. Add exact local USB inventory and read-only evidence collection.
6. Connect the existing HPT Lab Power Control API through a separate adapter.
7. Rehearse the complete workflow, reconnect, timeout, stop, failure, and
   authorization behavior with fixtures.
8. Qualify named diagnostic actions and target-control recovery.
9. Qualify registered-bundle programming and verification.
10. Enable destructive media and power-interruption profiles only after their
    exact safety, recovery, evidence, and authorization gates pass.
11. Add the DDS product profile and shared diagnostic ABI when DDS firmware is
    updated.

## Open Decisions

- Should initial J-Link execution use a persistent Windows qualification runner
  over the existing remote endpoints, or should the Pi gain qualified local
  probe ownership?
- Should the general target-control component be a new repository such as
  `/home/jong/dev/renesas-target-control`, or an appropriately generic
  extension of an existing J-Link hub project?
- Which immutable storage provider will own registered firmware bundles and raw
  evidence?
- What authentication and transport will be used between the qualifier,
  Windows runner, target-control service, and firmware-workspace importer?
- Which current SMI globals form the first semantic mapping, and which future
  release first exports the shared diagnostic ABI?
- Which operations are allowed from the standalone target-control CLI versus
  only from an authorized qualification campaign?

## Recommendation

Treat `sd_qualification` as the authoritative qualification owner, but keep
firmware programming and low-level J-Link control in a reusable,
least-privilege target-control boundary. Standardize bundles, semantic
observations, result envelopes, and the future diagnostic ABI across SMI and
DDS. Reuse the already-qualified power and serial-bound J-Link methods during
the first implementation rather than creating competing hardware ownership.

## Follow-Up

The following items belong to `PC-Redemption/sd-qualification`, not this
firmware workspace. Their paths are intended routing targets and are not local
Tool Shed outputs.

- [ ] Review this capture in `/home/jong/dev/sd_qualification`.
- [ ] Decide the target-control repository/service boundary.
- [ ] Convert accepted architecture into qualifier-owned ADRs and a workpackage.
- [ ] Define the firmware-bundle and semantic-signal schemas.
- [ ] Define the cross-workspace terminal-result import contract.
- [ ] Keep all physical programming, power, and destructive-media execution
  blocked until separately planned and authorized.
