# 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 `. - 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//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.