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:
co-authored by
Claude Sonnet 5
parent
e40134da0d
commit
d0a76420a5
+43
@@ -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-reps−1." 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.
|
||||
|
||||
Reference in New Issue
Block a user