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 since28ffed8f(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 at046ce0be, 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
82 lines
5.2 KiB
Markdown
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.
|