Add DoE library HOWTO (cookbook entry 2), flag stale L8-DOE claims in bare_metal/README.md

Documents capsules/doe.4th's word-level DOE/EXEC-DOE entry points, CSV
format, and a verified-not-fixed caveat: the rep column doesn't track
actual repetition count when n-reps differs from the file's fixed N-REPS=30
constant (cfg is unaffected, only rep is misleading -- use run_id instead).

Also surfaces, but does not fix, a real staleness finding in
experiments/bare_metal/README.md: its documented L8-DOE/WL-HI/WL-LO
entry point and workload-dispatch mechanism does not exist anywhere in the
current capsule set. What "DoE" actually names today is three separate
mechanisms (doe.4th's word-level DOE, doe-campaign.4th's fleet-touch
campaigns, and artemis/init.4th's auto-run ART-STRESS-CAMPAIGN) -- this
HOWTO documents only the first, per explicit scope decision.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
This commit is contained in:
Robert Allan James
2026-08-19 05:11:12 -04:00
co-authored by Claude Sonnet 5
parent e40134da0d
commit d0a76420a5
2 changed files with 183 additions and 0 deletions
+43
View File
@@ -1642,3 +1642,46 @@ wasn't practical to sit through unattended for a demo capsule; the arithmetic an
are verified, the actual rendered image is not. HOWTO:
`docs/working/architecture/TURTLE-GRAPHICS-HOWTO-20260819.md`. Second cookbook entry (DoE
package/library + its own HOWTO) is next.
**Cookbook, second entry — `docs/working/architecture/DOE-LIBRARY-HOWTO-20260819.md`, and a
real README staleness finding.** Before writing, checked `experiments/bare_metal/README.md`
(marked "mandatory read before touching capsules") against the actual current capsule set —
found its core claim wrong, not just tracking drift: it describes an `L8-DOE ( seed reps -- )`
entry point with 16 `WL-LO`/`WL-HI` workload-dispatch slots, auto-invoked from `init.4th`. None
of `L8-DOE`/`WL-HI`/`WL-LO` exist anywhere in `capsules/` (confirmed via grep across the whole
tree, zero matches), and `init.4th` doesn't call any DoE mechanism at all — it loads
`lib.4th`/`fabric.4th`/`font.4th` and prints the boot banner, nothing else. Flagged, not fixed
(separate task from this cookbook entry).
What "DoE" actually names today turned out to be three separate, unrelated mechanisms: (1)
`doe.4th`'s word-level `DOE`/`EXEC-DOE` — a single embedded arithmetic workload run across the
16 L8 factor configs, not auto-run anywhere; (2) `doe-campaign.4th`'s `CAMPAIGN`/`SMOKE-
CAMPAIGN`/`THREE-VM-CAMPAIGN` — Compudynamics fleet-touch orchestrators spawning Hermes/
Artemis, also not auto-run; (3) `artemis/init.4th`'s `ART-STRESS-CAMPAIGN`, which *does* run
unconditionally at the bottom of that file every time Artemis is born — this is the actual
source of the live `[Artemis][DOE ]` CSV rows seen streaming during every kernel boot, and is
item 4.6's own campaign (Section H above), unrelated to either of the other two. Presented this
finding to the user before writing anything further; explicit decision: document mechanism (1)
only, matching "package/library" scope best — the other two are orchestration scripts, not a
self-contained capsule a user loads and calls with their own parameters.
Verified on the hosted build (pure arithmetic + serial `TYPE`/`EMIT`, no kernel-only words, so
hosted and kernel-side are identical code paths): both `DOE` (fixed `12345 3 EXEC-DOE`) and a
custom `54321 5 EXEC-DOE` complete with `DOE: complete`, zero VM errors, correct row counts (48
and 80 respectively — `n-reps × 16`, confirmed via `run_id`'s final value in each run).
**A second real, previously-undocumented behavior found and precisely characterized (not
fixed) while verifying, not just repeating the source's own claims:** `RUN-MATRIX` is allocated
and Fisher-Yates shuffled across a *fixed* 480 cells (`N-CFG`×the compile-time `N-REPS`=30
constant) regardless of what `n-reps` value is actually passed to `EXEC-DOE`. The loop's total
run count genuinely scales correctly with the runtime `n-reps` parameter (confirmed above), but
each row's `rep` column is decoded as `(shuffled full-range index) MOD 30` — not "which
repetition, 0 to n-reps1." Confirmed empirically, not just by reading the source: the `5`-rep
call's output included `rep` values `27`, `21`, `24`, `18`, nowhere near `0``4`. `cfg` is
unaffected (still correctly uniform across all 16 configs); only `rep` is misleading. Documented
in the HOWTO as a known caveat, with `run_id` recommended instead for anyone needing a
trustworthy per-row index.
This closes the cookbook track's two planned entries (turtle demo, DoE library). Next per the
user's own sequencing is SDK v1.9.0 scoping (VOCABULARY + FENCE) — not started, pending
explicit go-ahead, since it's a new, larger workstream.