# Semantic Configuration Validation and Recovery Workpackage

Status: completed
Type: workpackage
Updated: 2026-09-23
Next Action: none; retained as history; any new execution requires a new explicit owner instruction
Campaign Reason: Historical record from campaign 010-qualify-firmware-negative-and-recovery-behavior; retained independently after campaign closure and requires no separate owner-queue execution.
Campaign: standalone

Canonical Truth: E:/dev/high_point/7520553_SMI_FW/docs/configuration-validation-and-recovery.md
Project Map: work/maps/map-smi-firmware-stabilization-and-qualification.md

## Current Context

`PowerOnGetConfig()` reads two 2,048-byte VEEPROM blocks at `0x40100000` and
`0x40100800`. A block is currently accepted when `Sys_ConfigVersion` equals
`APP_CONFIG_VERSION` and its CRC is valid. `APP_CONFIG_VERSION` is the generic
value 1, which is also used by DispTest and multiple incompatible historical
layouts. CRC proves only that the stored bytes are intact; it does not identify
which firmware schema produced them.

The observed no-heat configuration is consistent with this collision. SMI can
accept a valid-CRC foreign or older record, then `Thread_Misc_entry.c` changes
only `Sys_MachineType` to SMI and saves it. Model 0, an empty Part ID, disabled
main-temperature operation/control, zero PID gains, and an all-zero I-limit
profile can remain.

The supported field mitigation has historically been factory reset. The control
must nevertheless boot far enough to show diagnostics, reach the service screen,
load firmware, and execute that reset. This workpackage therefore does not
attempt to recognize or migrate DispTest, DDS, or every older SMI layout. Those
firmware stacks and formats remain unchanged ecosystem inputs.

The persistence audit also found that both flash blocks are independently built
from mutable `gRamConfig`, `Sys_UpdateCount` is not advanced, two valid divergent
blocks always prefer block 1, save requests can be lost during a write, failures
are ignored, and writes are not read back. The current semantic validator also
mutates live requested settings and can persistently disable heating. Prior
implementation/build evidence is retained as history but is superseded for
release readiness.

## Approved Direction

New SMI asks only one lineage question:

> Is this definitely a valid configuration written by the supported current SMI schema?

- If yes, preserve it, subject to non-mutating safety validation.
- If no, automatically construct and commit complete SMI factory defaults.
- If reset/commit cannot be verified, run a configuration-independent recovery
  boot with heat inhibited and the HMI, service screen, firmware loader, and
  manual factory-reset path available.

The fingerprint identifies a configuration schema, not an exact firmware build.
Compatible maintenance releases retain the same fingerprint and preserve
settings. A deliberate schema change receives a new fingerprint and therefore a
one-time factory reset unless a separate migration is explicitly approved later.

Owner approval recorded 2026-07-15:

- Preserve only a CRC-valid record carrying the complete supported current-SMI
  schema fingerprint.
- Automatically install clean SMI defaults for every nonmatching record,
  accepting a one-time loss of saved settings on the first fingerprinted upgrade.
- Do not preserve any field from a nonmatching/untrusted record.
- Reset serial number to 0 / Not Configured unless an independently trusted
  serial source is identified later.
- If a fingerprinted current-SMI record is semantically unsafe, preserve it for
  diagnosis, force effective heat off, and enter service recovery rather than
  automatically erasing it.
- Recovery must retain the HMI, service screen, firmware loader, manual factory
  reset, and a diagnostic reason.

## Mitigation Design

### 1. Positive Current-SMI Fingerprint

Replace the generic version-1 acceptance rule with an SMI-owned schema identity.
At minimum, use a unique 32-bit value in `Sys_ConfigVersion`; strengthen it with
reserved system words for magic, `sizeof(S_Config)`, and a layout revision. The
existing block CRC covers the fingerprint.

A block is current SMI only when all fingerprint fields, expected structure
size/layout, machine type, and CRC match. Do not infer current SMI from plausible
PID values, model number, Part ID, or other mutable settings. DispTest, DDS,
older SMI, blank, corrupt, and ambiguous records all intentionally fail the same
positive test; SMI does not need to identify which one produced the bytes.

### 2. Startup Decision

Read and validate both blocks before publishing `gRamConfig`:

| Stored blocks | SMI action |
| --- | --- |
| Two fingerprinted, CRC-valid current-SMI blocks | Select the newest valid generation and preserve it |
| One fingerprinted, CRC-valid current-SMI block | Load it and transactionally repair redundancy |
| No fingerprinted, CRC-valid current-SMI block | Build complete clean SMI factory defaults and commit them |
| Matching fingerprint but unsafe semantic values | Preserve stored request, inhibit effective heat, and enter visible recovery according to the approved rule |
| Default/repair commit fails verification | Continue from safe RAM defaults in recovery boot; heat remains inhibited |

Remove the late non-SMI-to-SMI conversion in `Thread_Misc_entry.c`. Startup must
never legitimize foreign bytes by changing only `Sys_MachineType`.

### 3. Clean Factory-Default Construction

Separate default construction from persistence:

- `BuildSmiFactoryDefaults(S_Config *destination)` creates a fresh zeroed local
  structure and populates every required SMI default, including the fingerprint,
  enable states, setpoint, PID gains, complete I-limit profile, alarms, sensor
  configuration, access codes, model-0 commissioning state, and Part ID.
- Automatic incompatible-record reset must not copy fields from the rejected
  `gRamConfig`. Existing RTC/log preservation and the soft-reset restore list
  require separate validation and must not be used on untrusted layouts.
- Identity handling such as serial number must follow the approved hard-reset
  contract or another independently trusted source; it must not be assumed to
  occupy the same offset in foreign data.
- Only publish the new configuration after its commit succeeds. If flash fails,
  use the complete RAM defaults solely for recovery UI operation and keep heat off.

### 4. Transactional Two-Block Persistence

All saves use one immutable snapshot through one configuration owner:

1. Increment a monotonic generation (`Sys_UpdateCount` or a dedicated field).
2. Calculate fingerprint and CRC once for the snapshot.
3. Write the inactive/older block first.
4. Read it back and verify bytes, fingerprint, generation, and CRC.
5. Only then update and verify the second block.
6. At startup, select the newest valid generation rather than fixed block 1.
7. Preserve a dirty/save request that arrives while a save is active.
8. Return and expose erase, write, and readback failures.

A power interruption must leave at least one previously verified current-SMI
record or result in a clean-reset/recovery decision on the next boot.

### 5. Requested Versus Effective Heating

A matching fingerprint allows settings to be preserved but does not bypass
safety validation. Bounds-check model indexes/enums, reject non-finite or unsafe
control values, and keep stored `MainTemp_IsControlEnabled` separate from runtime
heater permission. A configuration or sensor fault may force effective output to
zero and display a message, but must not silently persist a disabled request.

## Scope Boundary

In scope:

- Changes only in `7520553_SMI_FW`.
- Positive current-SMI schema fingerprinting.
- One-time automatic hard reset for every nonmatching record.
- Clean defaults, recovery boot, safe heater gating, and transactional storage.
- Qualification using records left by the existing ecosystem.

Out of scope:

- Changes to DispTest, DDS, older SMI, or any other personality.
- Family-wide record standards or shared headers.
- Personality-specific conversion or preservation of foreign settings.
- Legacy SMI field migration under the selected factory-reset policy.
- PID retuning and the deferred RTD/temperature-sensor watchdog implementation.

## Current State

Completed:

- Diagnosed the CRC-valid no-heat state and shared version/layout collision.
- Confirmed full SMI defaults contain enabled main temperature control, usable
  PID values, and a complete I-limit schedule.
- Identified the unsafe late machine-type conversion and persistence defects.
- Disabled internal data flash in the shared SMI J-Flash profile.
- Selected the SMI-only fingerprint-or-factory-reset policy.
- Approved nonmatch reset, no untrusted-field preservation, serial reset to Not
  Configured, and preserve-with-heat-off recovery for unsafe fingerprinted SMI data.
- Captured the overlapping dirty-worktree baseline and pre-implementation hashes.
- Selected schema `0x534D4902`, magic `0x534D4943`, layout revision 1, stored
  structure size, SMI machine type, generation, and CRC as the complete fingerprint.
- Implemented fingerprint-or-clean-reset startup, validation on a copy, recovery
  warning, effective heater gating, generation selection, inactive-first
  readback-verified writes, save-request retention, and removal of the late
  machine-type conversion.
- Refactored hard defaults into a pure destination builder that never reads a
  rejected record; locked the current `S_Config` layout at 1,436 bytes.
- Passed 16 source-contract checks, all 14 executable fingerprint-policy
  fixtures, and an isolated clean Debug build with versioned packaging; see
  `work/evidence/fingerprint-mitigation-implementation-20260715.md`.
- Inventoried connected J-Link/target read-only. The controller is live with
  nonzero heater demand. The owner approved programming; exact load verification,
  legacy-record reset, redundant commit, and cold-power-cycle preservation passed;
  see `work/evidence/setup-a/fingerprint-candidate-load-20260715.md`.
- Diagnosed the service-510 save reset as a deterministic MPU stack fault: two
  1,436-byte local configuration copies exceeded the Misc thread's 1,024-byte
  stack before flash code ran. Moved all full-record save/startup/reset workspaces
  to module storage, rebuilt and loaded the candidate, then proved an unattended
  SMI6/SLM622 commit and controlled reboot readback with identical generation-3
  redundant records; see
  `work/evidence/setup-a/service510-stack-fault-fix-20260715.md`.
- Completed the physical service-510 touchscreen regression with SMI7/SLM722,
  then passed a physical power cycle and read-only post-cycle health check:
  redundant records agreed, configuration was operational, RTD/control were
  active, SD was READY, and system/reset errors were clear.
- Passed a same-SMI load/boot preservation test: J-Link verified the exact
  qualified image already matched, the complete 4 KiB VEEPROM region had zero
  differing bytes before/after reset, and SMI7/SLM722 plus operational health
  remained intact. This is verification/reboot coverage, not destructive
  code-flash rewrite coverage; see
  `work/evidence/setup-a/same-smi-preservation-20260715.md`.

Incomplete:

- Remaining ecosystem transitions, injected flash/block faults, and
  power-interruption qualification.

## Goal

New SMI preserves settings only when a redundant VEEPROM record positively
identifies the supported current SMI schema and passes CRC and safety validation.
Every other record receives complete clean SMI factory defaults. Storage failure
cannot enable heat or prevent access to diagnostics, firmware loading, the
service screen, and manual factory reset.

## Delivery Stages

| Stage | Outcome | Exit Evidence |
| --- | --- | --- |
| 1 | Fingerprint/reset contract | Exact schema constants, compatible-release policy, identity reset behavior, and startup table are approved |
| 2 | Pure default and validation helpers | Executable tests prove deterministic complete defaults, positive-only fingerprint acceptance, and non-mutating safety findings |
| 3 | Startup and recovery integration | Current SMI is preserved; every nonmatch resets; failed persistence reaches service recovery with heat off |
| 4 | Transactional persistence | Immutable generation-based inactive-first writes, readback verification, dirty retention, and error reporting pass fault tests |
| 5 | Hardware qualification | Ecosystem sequence, reset, update, reboot, concurrency, and interruption matrices pass on inventoried targets |

## Rough Sequence

1. Reserve and document the SMI schema fingerprint fields and compatible-release rule.
2. Capture representative current-SMI, DispTest, DDS, older-SMI, blank, corrupt,
   and mixed-block fixtures only as negative/positive test inputs.
3. Extract a pure complete factory-default builder and define hard-reset identity behavior.
4. Implement pure fingerprint/CRC/generation selection and semantic-check helpers.
5. Integrate safe startup before other threads consume `gRamConfig`; remove the
   Misc-thread machine-type conversion.
6. Implement single-owner, snapshot-based, inactive-first, verified persistence.
7. Add recovery diagnostics and requested-versus-effective heat gating.
8. Run the ecosystem, power-interruption, flash-failure, concurrency, reset, and
   reboot tests; retain exact image hashes and raw before/after records.

## Milestones

### Milestone 1: Fingerprint and Reset Contract Approved

- [x] Unique SMI schema value, magic, stored size, and layout revision are defined.
- [x] Only proven byte-layout/interpretation-compatible SMI releases may share the fingerprint.
- [x] Any record without the complete fingerprint receives clean hard defaults.
- [x] Automatic reset preserves no untrusted fields and sets serial to 0 / Not Configured.
- [x] Unsafe fingerprinted SMI data is preserved for diagnosis with effective heat off.
- [x] Recovery retains HMI, service, firmware loading, manual reset, and diagnostic reason.

### Milestone 2: Implementation Complete

- [x] A clean builder produces complete defaults without reading rejected configuration.
- [x] Startup publishes operational permission only after positive identification or clean construction.
- [x] Late machine-type conversion is removed.
- [x] Matching records retain requested settings unless an explicit reset is invoked.
- [x] Unsafe matching records inhibit effective heat without silently persisting disable.
- [x] Saves use one immutable snapshot and monotonic generation.
- [x] Startup selects the newest verified generation.
- [x] Writes are inactive-first and readback verified.
- [x] Concurrent save requests are retained and storage failures are surfaced.

### Milestone 3: Executable Qualification Complete

- [x] Current fingerprinted SMI -> new SMI preserves settings.
- [x] DispTest/non-SMI executable fixture -> new SMI installs complete SMI defaults; owner accepted fixture coverage without a physical DispTest capture.
- [x] Older SMI -> new SMI installs complete SMI defaults.
- [x] New SMI -> old SMI -> new SMI results in a clean reset unless the old
  firmware preserved the complete supported fingerprint and layout unchanged;
  owner accepted the existing foreign-layout executable coverage for release.
- [x] DDS/non-SMI executable fixture -> new SMI installs complete SMI defaults; owner accepted fixture coverage without a physical DDS capture.
- [x] Blank, corrupt, ambiguous, and mixed-personality blocks install defaults or enter the specified evidence-preserving recovery state.
- [x] One current valid block repairs the other; two different valid generations select newest; same-generation divergent blocks enter heat-inhibited recovery.
- [x] Owner accepted representative erase-loop, write-loop, verified-block, concurrent-save, and held physical power-cut coverage for this release; exhaustive every-boundary testing was explicitly waived.
- [x] Readback/flash failure keeps heat off while service UI and manual reset
  work; representative interruption/recovery coverage passed and the owner
  explicitly waived exhaustive boundary and direct driver-failure injection.
- [x] Factory/commanded reset, reboot persistence, and concurrent-save tests pass on Setup A.
- [x] First-time clean defaults retain approved normal main-temperature operation while exposing Not Configured/commissioning-required state; unsafe fingerprinted data inhibits heat.
- [x] Representative J-Link interruption, physical power-cut, recovery results, and exact image hashes are retained.

## Open Questions

- Which exact release range is proven byte-layout and interpretation compatible
  after the implementation is finalized?
- Should `Sys_UpdateCount` become the durable generation or should a dedicated
  fingerprinted generation field be allocated?
- Are the serial-numbered J-Flash profiles active, and should they mirror the
  shared profile's data-flash exclusion?

## Completion Standard

This workpackage is complete when only positively fingerprinted, CRC-valid,
supported current-SMI records are preserved; every nonmatching ecosystem record
receives complete clean defaults; redundant saves are generation-based and
readback verified; invalid or failed storage cannot energize heat or block the
service recovery path; and executable plus representative-hardware evidence
covers the full stated firmware-install sequence. A clean build or regex check
alone is insufficient.

## Related Artifacts

- SMI stabilization map: `work/maps/map-smi-firmware-stabilization-and-qualification.md`
- Incident evidence: `work/evidence/temperature-issue-diagnosis-20260713.md`
- Prior implementation/build evidence: `work/evidence/implementation-and-build-20260714.md` (superseded for release readiness)
- Fingerprint implementation evidence: `work/evidence/fingerprint-mitigation-implementation-20260715.md`
- Deferred profile tuning: `work/wp/deferred/wp-temperature-control-profile-recovery-and-steady-state-regulation.md`
- Deferred sensor watchdog: `work/wp/deferred/wp-temperature-sensor-validity-interlock-and-rtd-transport-recovery.md`

## Closeout Routing

- Current truth promoted to: `E:/dev/high_point/7520553_SMI_FW/docs/configuration-validation-and-recovery.md`
- Historical context remains in: this workpackage and linked evidence
- Runtime/status evidence: `work/evidence/`
- Cleanup deferred to: unrelated UI redesign and temperature-loop retuning

## 2026-07-20 completion

The accepted semantic contract, executable fixtures, representative Setup A
fault/recovery matrix, physical power interruption, redundant persistence, and
coverage decisions were integrated into engineering candidate 00.04.13. Clean
Debug and Release builds and packaging passed. The candidate was loaded on both
current controller assemblies; each booted and performed nominal SD/mirrored
logging without system or SD errors. The integrated release-closeout condition
is therefore satisfied, and this workpackage is complete. Remaining negative
update, SD/media, UI/export, and endurance gates belong to their active owning
workpackages rather than this one.

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

Reconcile stale active lifecycle to the previously documented completed disposition; no new test or broader acceptance claim.

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: complete; representative release qualification and accepted coverage integrated into 00.04.13
> Next Action: none; retain the settled contract and qualification evidence

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.
