Skip to content
86 changes: 83 additions & 3 deletions docs/plans/power-on-sequence-model.md
Original file line number Diff line number Diff line change
Expand Up @@ -243,7 +243,7 @@ The differences found when Mt. Jade lands become the onboarding checklist.

## 10. Implementation slices

1. **A: the power-on account, replacing every string finding and `HostBootObservation`, after #13041 lands.** It includes:
1. **A (#13117): the power-on account, replacing every string finding and `HostBootObservation`, after #13041 lands.** Former slice B (#13058's error records) is folded in, and §10a records the decisions. It includes:
- the public readers: opaque `CP:` (`gunbc.machine_intake_ampere_checkpoint_console_observation`), and the EFI stub and kernel lines (`extdeps.linux.efi_stub`, `extdeps.linux.boot_console`, read by `gunbc.machine_intake_linux_boot_console_observation`);
- the `AttemptConfigurationReceipt` (frozen before power-on, including the human completion/inspection receipt for manual changes), and coverage;
- the account;
Expand All @@ -252,11 +252,91 @@ The differences found when Mt. Jade lands become the onboarding checklist.
- every census row in §6, plus the REDs of §5.

Fixtures are committed excerpts from the `mtcollins1-captures-2026-10-03` evidence branch, including step 3 as the new-firmware positive control, and the run 37062170720 / 37069907299 artifacts. A pre-review draft of the readers and a fold exists on `session/calm-lynx-884-slice-a-wip`. It predates these rulings (it uses a scalar ending, stage attribution from the DRAM banner, and its own SMpro pair rule) and will be reworked, not landed as-is.
2. **B: SMpro/PMpro error records** into `Socket{k}` and degradations, gated on #13058.
2. **B: the attempt-configuration receipt's live inputs**: the applied stimulus, current population and pre-power-on firmware readback (decided Q4). The error records originally planned as B landed in A.
3. **C: NVPARAM** as UEFI-subject context, gated on #13059.
4. **D: `ManagedHost`**, gated on #13055. If #13055 lands before A, it is folded into A.
5. **P: the gunbc-private refinement slice** (§8).

## 10a. Decisions taken while implementing slice A (#13117)

These were settled while building slice A and through its side-chat reviews. Each one is enforced by a witness in #13117 and recorded here so this plan stays the authority.

- **Cycles open only on typed boundary evidence.** Each SEL boot record gets a `SelBootBoundaryStanding` from an ordered fold with no look-ahead:
- the first record corroborates the confirmed power-on when it is a power-up;
- the first record is `BoundaryAmbiguous` when it is a restart after a confirmed power-on. It opens no cycle and becomes an open question, because this MegaRAC can log the power-on's own first boot as "System Restart" (step 1);
- every later record, including a second power-up, is a distinct boundary.

Console banners only bind spans to cycles, and only when the counts agree; otherwise the binding is `ConsoleSpansUnbound`. The BMC clock is never joined to ours.
- **Stated failures are counted per occurrence.**
- Panics and initrd failures are read per printed line.
- Firmware statements, GRUB reports and module refusals are read by their owning readers over each console span's own lines.
- Each error carries its cycle. Only a failure in the last cycle can choose the ending, and the furthest one there wins. Earlier and unbound errors stay as history.
- **A loop is distinguished from progress after a restart.** `RestartedRepeatedly` applies only when the last cycle got no further than an earlier one. Otherwise the ending is `StoppedWithoutRestart { restarts_before }`.
- **Topology, population and absence are judged only against the receipt.**
- The expected topology is `ExpectedSockets`, or `ExpectedTopologyNotRecorded` (production today).
- Processors are checked once per expected socket: missing, duplicated, or unreadable socket ID.
- Memory is checked per socket, over the union of expected-populated and observed sockets, against `SlotRow { label, socket, populated }`.
- Sensor absence counts only for an expected socket.
- Health states reported by the BMC stay unconditional.
- **SMpro.**
- Passes are reported per pass, not placed into cycles.
- #13058's records are placed by their gate (pending → stated error plus degradation; ungated → anomaly plus open question).
- Pending warnings are kept.
- The error-record registers have their own coverage carrier, separate from the boot-stage pair.
- **Each milestone carries provenance.** It has its capture digest and a `DeclarationRef` to its reader. A one-variant nullary sum does not resolve in the substrate, so a declaration citation is used instead.
- **Convergence refuses UEFI followed by a loop.** It reads the whole-account readback. A UEFI milestone followed by a `RestartedRepeatedly` ending refuses as `BootReachedUefiThenRestartedRepeatedly`.
- **#13025's `secondary_checkpoints` is deleted (Q3).** The per-socket CP classification belongs to the private refinement slice.
- **The receipt's live inputs are slice B (Q4).** Slice B adds the boot-workflow input for the applied stimulus (with a human inspection receipt through the operator-attested route), the current population, and the pre-power-on firmware readback. Until it lands, those fields are `NotRecorded` and every question needing them is open.

## 12. Slice B: the attempt receipt's live inputs (plan, for review before code)

Slice B fills the `AttemptConfigurationReceipt` fields that slice A records as `NotRecorded` (decided Q4). The boot run takes its host as a `ManagedHost` / `ManagedHostBinding` (`gunbc.managed_host`), not as mtcollins1 constants; cut 4d of the managed-host untangle will re-root the rest of the run. Code waits on Q6 and this section's approval.

**Two records, each minted only by its checks.**

```
AttemptConfigurationPlan (sole constructor) {
subject: ManagedHost, attempt: AttemptPlanId,
expected: ExpectedTopology, requested: StimulusRequest, // expected and requested are stated ONCE, here
fixed_at: ObserverTimestamp,
}
AttemptInspectionReceipt (sole constructor) {
plan: AttemptConfigurationPlan,
applied: StimulusApplication, cpus: PopulationReading<SocketCpuRow>, dimms: PopulationReading<SlotRow>,
completed_at: ObserverTimestamp, evidence: ReceiptEvidence, witnessed_by: NonEmptyStr,
}
ReceiptEvidence { path, digest: Sha256FileDigest, commit } // the committed file the run read
```

The run mints an `AttemptInspectionReceipt` only after every check passes, and each failed check refuses as its own typed cause:
- the file's digest matches what was read;
- the subject is the host this run's `ManagedHostBinding` bound;
- the attempt is the plan the dispatch input named;
- the plan's identity is the one the receipt carries;
- the ordering holds: `fixed_at` before `completed_at` before the power write.

The pre-power-on firmware readback is bound to the same plan (`FirmwareReadBeforeActuation { plan, rows }`), so a readback from another attempt cannot fill this one. A receipt that is absent or refused leaves the fields `NotRecorded` or refused with their cause. The boot never proceeds on a guessed configuration.

**The operator-attested route** follows `std.human_intervention`:
- The inspection is a `HumanIntervention` step with `HumanSurfaceOnly`, because a physical change has no API.
- Its `DischargedAt { evidence }` cites the evidence PRODUCER: the fail-closed reader that mints `AttemptInspectionReceipt` from the committed file, a `DeclarationRef` to that function. It does not cite a flag or a boolean standing.

**The pre-power-on Redfish population read is not live by default.** A controller reading taken before power-on may be the BMC's cache from the last POST, so it is `PopulationControllerReading { freshness: FreshnessEstablished | CachePossible, rows }`:
- It can corroborate the inspection or conflict with it. A conflict is `PopulationConflicted`, an open question, never resolved by preference.
- Only `FreshnessEstablished` counts as a live reading. Nothing on main establishes that freshness today, so today's reading is `CachePossible`.

**Field routes.**

| Field | Route |
|---|---|
| expected topology and requested stimulus | the plan, stated once |
| applied stimulus and population | the inspection receipt; the controller reading only corroborates or conflicts |
| firmware | a new pre-power-on `hpm check` read through `extdeps.bmc.ipmi` (none exists on main; `gunbc.fleet.mtcollins_firmware_converge` only renders a dry argv), plus the SMpro version word where it answers, both bound to the plan |

**Delivery (Q5, decided by eager-gull-22 on 2026-10-03).** The plan and the inspection receipt are committed JSON under `artifacts/receipts/`, reviewed and versioned like any change. eager-gull-22 authors them from what the operator reports about the physical change. One fleet-converge dispatch input names the receipt file, and the boot run reads it from the checkout with the fail-closed typed reader above. Inline JSON in a dispatch input is refused because it is not reviewable. Adding that input is Q6, which is open.

## 11. Questions

None open. Q1 and Q2 were decided by the side chat on `75f0bd113c` and are encoded in §1, §3 and §5.
Q1 and Q2 were decided by the side chat on `75f0bd113c` and are encoded in §1, §3 and §5. Q3 (delete `secondary_checkpoints`) and Q4 (add the receipt inputs, as slice B) were decided during slice A (§10a). Open:
- **Q5 (decided by eager-gull-22, 2026-10-03):** the plan and the inspection receipt are committed JSON under `artifacts/receipts/`, read from the checkout by a fail-closed typed reader that records the file's digest. One dispatch input names the file. Inline JSON in a dispatch input is refused.
- **Q6 (open, with the operator):** adding that dispatch input to the fleet-converge workflow surface.
Loading