Files
LithosAnanke/docs/v4.0.0/plans/2026-11-17-emergency-diagnostic-build.md
T
Claude 45b11aec25 feat(v4, ci): the fault dump on a node's stop, and the EMERGENCY diagnostic build after a failed stage
Captain Bob's CI directive (2026-11-17) and the design he ruled point by point
(docs/v4.0.0/plans/2026-11-17-emergency-diagnostic-build.md).

- v4/system/dump.c, v4/include/v4/dump.h: what a node was doing when it stopped -- the fault's kind,
  address and count; P A B; the data stack, T first; the return stack, R first, each entry named by
  the word it falls in (the backtrace; ROM and below-every-word said so); the running line. Bounded
  dictionary walk; no C library. Ruled: every build, on a stop only (a handled fault keeps its line).
- kernel/src/v4/sk_v4.c: the dump before each of the three halts (not started; POST's blocks not
  let go; a node stopped on a fault) -- Hera and any stopped node. kernel/Makefile links dump.o.
- scripts/nightly.sh diagnose [<stage>]: after a failed stage, that configuration built again with
  EMERGENCY_CONSOLE_ENABLED=1 -- build only, nothing booted (ruled) -- its artifacts kept in
  logs/<TS>/diagnose/ only from a build that passed, with a README saying how to launch it with
  --log-level=debug. Always exits 0: evidence, never a result. The protocol runs it after a failed
  stage and still exits with that stage's code; acceptance.yml, nightly.yml and release.yml run it
  `if: failure()`, before the logs are kept. Any failed stage triggers it (ruled).
- capsules/BLOCK_MAP.md: as the build writes it -- the v4:physics.4th row, missing since 28ffed8f
  (ruled: commit the regenerated map).
- Test first: test_dump.c failed with no dump.c (logs/20261117-dump), then 15 checks at both widths
  and under ASan+UBSan. The diagnose stage: a real EMERGENCY amd64 build; a failing build exits 0 and
  keeps no artifacts (a defect found and fixed this way); the protocol path keeps the stage's exit.
- Also the write-up of the regression at 046ce0be, for ruling.

Not yet: acceptance on a clean tree (the next run); the kernel's stop wiring is compile-tested only
-- no boot reaches a stop on purpose.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_017RzZgrf7V7Zk2iczBXDRbm
2026-11-17 19:14:40 +00:00

82 lines
5.2 KiB
Markdown

# The failure-triggered EMERGENCY diagnostic build -- design, for ruling
Written 2026-11-17 from Captain Bob's CI directive ("Emergency Console -- Separate Build
Configuration") and his order: "inspect the debug build first, then write the design".
**Nothing here is built.** The open points are put to Captain Bob one at a time, as he ruled the same
day.
## 1. What exists today (inspected 2026-11-17, read only)
| What | Where | What it does |
|---|---|---|
| `EMERGENCY_CONSOLE_ENABLED` (build parameter) | `Kconfig.heartbeat:70`, default n; `kernel/Makefile:429` | Gives a console at boot with no login, and makes an error recover instead of halting. On v4 the screen is live from the start and there is no headless wait (`kernel/src/v4/sk_v4.c:258, 348, 366`; `sk_v4_identity.c:463, 504`). **It adds no diagnostics.** |
| `--log-level=debug` (boot argument) | `kernel/src/boot/cmdline.c:135`; `kernel_args.h:25` | v3 only: a trace of every word (`ECW: w=... func=... 'NAME'`, `kernel/src/vm/vm_core.c:872`). This is very slow. **Nothing on the v4 path reads `log_level`.** |
| `SK_PARITY_DEBUG` (build parameter) | `kernel/Makefile:524` | v3's parity debugging. |
| The CPU's fault handlers (every build) | `kernel/src/arch/*/interrupts.c` | Print the vector or cause, then halt. amd64 prints RIP, CR2, RSP, RBP, the word on the stack, and the executing word on a #GP. aarch64 prints ELR_EL1; riscv64 prints sepc. |
| A v4 node that faults | `v4/include/v4/node.h:129-134`; `kernel/src/v4/sk_v4.c:407` | The node records its fault's kind, its address and a count. The kernel prints only "StarForth v4: the node stopped on a fault" and halts. **Nothing prints P, A, B, the stacks, the return stack (the node's backtrace) or the fault's kind and address.** |
| Acceptance and nightly on failure | `.gitea/workflows/acceptance.yml`, `nightly.yml`; `scripts/nightly.sh` | The failed step fails the job and the logs are kept. **No diagnostic build follows.** |
So the directive's diagnostics (stack states and contents, pointers and execution state, backtraces,
full logs) exist on v4 today only as fields in the node that nothing prints. On v3 they exist only as
the per-word trace, which a boot argument turns on.
## 2. The design
**A. The trigger.** A normal build or validation fails. Its step has failed, so the job's result is
already failed.
- A following step runs, `if: failure()` in the workflows, and the same call in
`scripts/nightly.sh protocol`: `scripts/nightly.sh diagnose <what failed>`.
- It builds the failed configuration again with `EMERGENCY_CONSOLE_ENABLED=1` and diagnostic logging
on (B).
- It keeps the result and the artifacts under `logs/<TS>/diagnose/`:
- the ELF with symbols;
- the ISO or the image;
- the `.config`;
- the capsule map;
- the build log;
- its own result.
- Nothing it does can change the job's result: the step only gathers evidence, and the failed step
stays the reported failure.
**B. What the diagnostic build carries** (it needs building, and a ruling):
- On a node's fault or stop, the kernel prints:
- the fault's kind and address, and the fault count;
- P, A, B, T and S;
- the whole data stack;
- the whole return stack, with each address named by the dictionary word it falls in. That list is
the node's backtrace.
- the line that was running.
- Diagnostic logging on the v4 path: what the node is doing, word by word, as v3's per-word trace is.
It is allowed to be slow.
**C. Building is not launching.** The diagnostic step builds and keeps the artifacts. It does not boot
an emergency console. Launching one is a separate act: a person's, or a stage made for it.
**D. Failure categories.** Each is its own named step and its own line in PROTOCOL.md:
1. source: a `.f18` that does not assemble or a `.4th` that does not compile (POST);
2. the kernel's build and unit tests;
3. ASan and UBSan;
4. QEMU, per architecture;
5. the emergency diagnostic build.
## 3. Open points, to be put one at a time
1. ~~Diagnostic logging is a boot argument today (`--log-level`). Should the diagnostic build turn it
on as a build parameter instead?~~ **Withdrawn 2026-11-17. It was not a discrepancy.**
- The directive forbids only a boot argument standing in for the EMERGENCY *build* (`--sos`).
- `--log-level` stands in for nothing: it is how logging has always been chosen.
- I made a problem out of established practice by reading the directive too widely.
- The diagnostic build is EMERGENCY at build time, with `--log-level=debug` as it has always been.
2. ~~Should the diagnostic step build only (C), or also boot that build once?~~ **Ruled 2026-11-17
(Captain Bob): build only.** The step builds the diagnostic configuration and keeps its artifacts.
Launching it is a person's act.
3. ~~Should B be printed in every build, or only in the EMERGENCY build?~~ **Ruled 2026-11-17 (Captain
Bob): every build.** The fault dump prints in any build on a node's fault, as the CPU's fault
handlers already do. The slow word-by-word log stays behind `--log-level=debug`.
4. ~~Which stage does the trigger cover?~~ **Ruled 2026-11-17 (Captain Bob): any failed stage.** The
diagnostic build of that configuration follows whatever fails.
All four open points are settled. The design waits for Captain Bob's word to build it.