Documentation Errata

Documentation Errata

This page audits documentation in the sw-mlpl source repository. Original audit: 2026-08-01. Resolution pass: 2026-08-02 -- the source docs were repaired against this list in commit 7a985122 (saga E4 step 009). Follow-up reconciliation: 2026-08-02 -- E4 subsequently closed in df7731b5 and the roadmap was reordered in 16f0d78f. The tables below preserve both the original findings and later status drift.

Resolution status (2026-08-02)

Finding	Status	How it was addressed
E-001 CUDA guide "planned"	Resolved	docs/using-cuda.md now opens with a SUPERSEDED banner pointing at the shipped scope (saga-cuda-foundation.md, saga-cuda-demo-parity.md); the stale status block was removed
E-002 broad GPU-training wording	Resolved for MLX; open for CUDA	E4 closed on 2026-08-02 with general resident-tape MLX training. CUDA still uses recognized gpu_step shapes until the deferred cuda-resident-tensors saga
E-003 root build commands	Resolved	README Quick Start and Development sections rewritten for component workspaces / --manifest-path
E-004 configurations eras	Resolved (banner)	docs/configurations.md opens with an errata note superseding the "planned" server sections and old install paths
E-005 architecture pre-CUDA	Resolved (banner)	docs/architecture.md opens with an errata note: in-process CUDA slice shipped; peer service/distributed still future
E-006 MLX guide staleness	Resolved (banner)	docs/using-mlx.md errata note: LoRA shipped, CUDA slice shipped, path mapping, and the E4 resident-tape supersession of the perf caveat; the LoRA section status flipped to SHIPPED
E-007 old monolith paths	Partially resolved	Banners in the affected guides state the components/<name>/crates/* mapping; a mechanical per-line path sweep remains future work
E-008 status.md scoreboard	Resolved as historical; banner drifted	docs/status.md is correctly marked HISTORICAL and points to current sources, but its banner still says E4 is active and mHC planned-soon; see E-013
E-009 Engram planned/implemented split	Resolved; status advanced	E1-E3 remain complete; E4 is now complete and E5 engram-mlx is the next substrate saga. E6-E9 and Engram CUDA remain deferred
E-010 mHC status	Superseded by roadmap reorder	mHC is not planned-soon now. CPU phases are parked behind MTP; MLX and CUDA phases are deferred. See E-014
E-011 README counts conflict	Resolved	Hard-coded playground counts removed from README (generated content, labeled as such)
E-012 README backend roadmap	Resolved	README roadmap section rewritten: MLX/CUDA/Ollama framed by shipped scope with per-guide caveats

Process rule instituted (same step): repository CLAUDE.md now carries a "Wiki errata discipline" section and the /mw-cp checkpoint playbook gained a docs-gate item -- any step that documents new features or flips a doc claim must update this page (and the affected wiki pages) in the same step.

Follow-up reconciliation after the repair commit

The source repository moved again after the E-001 through E-012 repair. These are the current corrections as of 2026-08-02:

Finding	Severity	Status	Current source of truth
E-013 historical status banner drift	Medium	Resolved (2026-08-02, 0767c0d5)	docs/status.md banner no longer restates live roadmap state; it links to CHANGES.md / saga.md / benchmarks.md / future-sagas-queue.md instead
E-014 mHC priority changed	Medium	Resolved in roadmap	docs/future-sagas-queue.md is the sole source for ordering; user-facing source docs do not advertise mHC work
E-015 E4 completion changed MLX scope	High	Resolved in current architecture/design docs	docs/architecture.md, docs/future-saga-gpu-training.md, docs/saga.md, and docs/benchmarks.md now describe resident MLX training
E-017 user-facing dev-jargon purge	Medium	Substantially resolved (2026-08-02, ec26f5a8); README residuals in E-022	Glossary, language reference, README feature text, demo text, and essays were swept at roughly 70 sites; the rule now lives in repo CLAUDE.md, while the README documentation index still contains development-status phrasing
E-021 (feature note)	Low	Recorded 2026-08-04	Data-forge landed: grade_up/grade_down/compress (G2), rand_ints, dedupe_rows, the kg_* task oracle, keyword field names, and a new Data Forge demo category (rejection sampling, graph multi-hop, arithmetic curriculum)
E-020 (feature note)	Low	Recorded 2026-08-03	E5 engram-on-MLX benchmarks + seam profiles published in docs/benchmarks.md ("Saga E5" section); Apple-Silicon wiki page updated with the resident-engram capability line
E-019 glossary concept coverage	Low	Resolved (2026-08-02, 775c4eb2)	ICRL and 15 more project-direction concepts (MTP, rejection sampling, test-time compute, knowledge graphs, scaffolding, synthetic data, Pareto frontier, TRM/HRM/BDH/mHC, EBM/Hopfield/JEPA/world models) added as educational glossary entries
E-018 glossary builtin coverage	Medium	Resolved (2026-08-02, b4fa5acf)	User report: running_product absent from the online glossary; audit found 12 catalog builtins never mentioned. 12 entries added + a coverage test (every catalog builtin must be mentioned in docs/glossary.md); the ~40 heading-less builtins are queued maintenance. Same day: glossary search became a filtered all-matches view (82b6d704)
E-016 (feature note, not an erratum)	Low	Recorded 2026-08-02	Playground gained the "Thinking in Arrays" APL2 demo (data-loop vs time-loop pedagogy, commit c909864f); Life/attention demo text updated to match -- wiki Demos page updated in the same step
E-018 wiki user-facing dev-jargon purge	Medium	Resolved in this reconciliation	Public wiki pages now state capabilities and unsupported boundaries in present tense; saga, roadmap, milestone, planned/deferred, and development-status material is confined to this errata page
E-019 deprecated names in examples	Low	Resolved in this reconciliation	Wiki examples now use range rather than the deprecated iota; no wiki example used the deprecated cumprod alias (running_product is the preferred name)
E-020 glossary builtin coverage gaps	Medium	Resolved (2026-08-02, b4fa5acf)	Missing entries were added for 13 catalog names, and a test now requires every documented builtin to be mentioned in docs/glossary.md
E-021 glossary concept gaps	Medium	Resolved (2026-08-02, 775c4eb2)	Sixteen project-vocabulary concepts were added, including ICRL, MTP, mHC, test-time compute, reasoning architectures, energy models, and world models
E-022 README accuracy after documentation sweep	High	Open	README still contains a deprecated iota example, old apps/mlpl-web path, root-incompatible Cargo examples, development-status prose, and contradictory count policy; details below
E-023 undocumented svg() types + broken + concat example	Medium	Resolved (2026-08-12)	Downstream report: six svg() render types shipped but were absent from docs/lang-reference.md -- scatter3d, plotly3d, heatmap_grid, life, waffle, attention_overlay. All six are now documented (shapes verified against components/viz/crates/mlpl-viz/src/svg.rs and each renderer), and the svg(data, type, aux) row now names the 3-argument types that read aux. Same fix: a control-flow example used "hello " + name, which does not run (+ is not string concatenation); rewritten to str_concat("hello ", name)

Documentation-error pattern

The repairs reveal a recurring family of documentation errors rather than isolated wrong sentences:

Error kind	Why it confuses users	Preferred form
Development chronology in reference text	Saga names, step numbers, release stamps, and ship dates explain repository history instead of the feature	State what the feature does and how to invoke it
Roadmap promises in capability descriptions	“Planned,” “deferred,” and “future enhancement” blur the boundary between usable and imagined behavior	Say “not supported,” “not implemented,” or omit the non-feature
Live status copied into stable pages	“Active,” “next,” and ordered phase lists become stale as soon as priorities change	Keep ordering only in dedicated planning/status records
Historical implementation paths	Old apps/*, root crates/*, or service paths send users to files that no longer exist	Link the current component workspace or user command
Version-bound stable concepts	Labels such as “v0.19 builtin” make permanent syntax read like temporary release notes	Name the builtin, type, or command without a version
Generated counts written by hand	Demo, lesson, and glossary counts disagree after content changes	Avoid counts or generate them from the registry
Backend scope without residency detail	A device block can be mistaken for proof that an entire training graph ran on that accelerator	State the supported execution path and the CPU fallback boundary directly
Research notes linked as user guidance	Exploratory designs expose abandoned names and hypothetical APIs	Link runnable examples, reference docs, or source components instead
Search/reference coverage gaps	A builtin or core concept exists but cannot be found by its expected name	Test catalog coverage and add direct, cross-linked glossary entries

Current project sequence relevant to this audit

flowchart LR
    E4[E4 resident MLX complete] --> E5[E5 Engram on MLX next]
    E5 --> KV[KV cache]
    KV --> MTP[MTP training]
    MTP --> Spec[MTP self-speculation]
    Spec --> MHC[mHC CPU phases parked behind MTP]
    MHC --> MHCAccel[mHC accelerator phases deferred]
    E5 --> EngramLater[Engram E6-E9 deferred]
    EngramLater --> EngramCuda[Engram CUDA deferred]

Loading

E-013: the docs/status.md historical banner became stale

Severity: Medium. Status: resolved (2026-08-02, commit 0767c0d5). The historical banner added by the repair commit was directionally correct, but it froze two fast-moving statements: “E4 active” and “mHC planned-soon.” Later on 2026-08-02, E4 completed and the roadmap parked mHC behind MTP. The revised banner follows the recommendation below: it no longer duplicates live roadmap state and links to the living sources instead.

This does not make the old scoreboard authoritative again. Its pointers to CHANGES.md, docs/saga.md, docs/benchmarks.md, and docs/future-sagas-queue.md remain correct. The banner now avoids duplicating live roadmap state.

E-014: mHC is parked, not next

Severity: Medium. Status: roadmap corrected. The original audit requested an explicit mHC status, and the first repair described it as a bounded planned-soon track. User direction on 2026-08-02 reordered the queue:

• E5 engram-mlx remains next.
• The MTP program follows E5: generation-state/KV cache, MTP training, then MTP self-speculation.
• mhc-p1-constrained-transforms and mhc-p2-cpu-layer are parked behind MTP, not cancelled.
• mhc-p3-mlx-resident and mhc-cuda are deferred.

The authoritative record is the future sagas queue, not the older docs/status.md banner or research transcripts.

E-015: E4 completed general resident training on MLX only

Severity: High. Status: resolved in current source docs. E4 replaced the eager per-operation MLX training path with a TensorHandle seam and device-resident autograd/optimizer state. General MLX models can now train resident; the old bespoke fast paths were demoted beneath the resident path. A small number of exact CPU kernels, notably fused cross-entropy backward, still cross the seam and are observable through counters.

The correction is backend-specific: CUDA has not yet implemented the resident DeviceOps seam and still relies on recognized per-shape GPU training routes. Current sources now state this distinction in architecture, the landed GPU-training design, the saga history, and benchmarks.

E-017 and E-018: development language leaked into user documentation

Severity: Medium. Status: resolved in the source and wiki sweeps. The source cleanup found roughly 70 instances across the README, glossary, language reference, essays, and demo text. The wiki repeated the same pattern in its home page, capability matrix, backend pages, demo catalog, language tour, use cases, architecture links, and resource index.

The corrected user-facing material now follows three rules:

1. Describe implemented behavior in present tense.
2. Describe an unavailable boundary as “not supported” or “not implemented,” without promising when it changes.
3. Keep chronology, prioritization, and implementation history on this errata page or in dedicated source planning/status records.

The wiki sweep also replaced the deprecated iota examples with range, removed development-plan links from user resource lists, corrected MLX general-training coverage, and retained CUDA's exact CPU-fallback boundary.

E-020 and E-021: glossary terms were missing

Severity: Medium. Status: resolved. A user report that running_product could not be found exposed a wider reference-coverage gap. The builtin audit added direct entries for argtop_k, emit_frame, engram_stats, flatten, floor/ceil/round, knn_graph, loss_curve, loss_landscape, pi/e, range, running_product, and train_val_curve. The running_sum builtin was added with its own language-reference and glossary entries.

The glossary data crate now tests every documented inspect-catalog builtin for at least one glossary mention. This prevents a builtin from becoming completely undiscoverable, although it does not require a dedicated heading for every builtin.

A separate vocabulary audit added ICRL, Multi-Token Prediction, rejection sampling, test-time compute, knowledge graphs, scaffolded reasoning, synthetic data, Pareto frontiers, TRM, HRM, Dragon Hatchling, mHC, energy-based models, Hopfield networks, JEPA, and world models. Entries use present-tense capability notes: concepts without MLPL support say “Not in MLPL” rather than referring to development intentions.

E-022: README is improved but not fully accurate

Severity: High. Status: open. The README's component-workspace Quick Start is correct, its glossary search description matches the all-results behavior, and its hard-coded glossary/demo counts were removed. The following issues remain:

• The feature example still calls deprecated iota(6) instead of range(6).
• The repository summary says the browser playground “runs both via WASM,” an editing error that obscures the simple claim that it runs via WASM.
• The REPL feature description points to apps/mlpl-web; the current crate is components/web/crates/mlpl-web.
• The Demo Scripts block uses root-style cargo run -p mlpl-repl commands even though the repository has no root Cargo.toml. If run inside components/cli, its demos/... paths are also wrong.
• The parity-test command and some development commands omit the owning component workspace or --manifest-path.
• The backend documentation section still uses “shipped,” “planned,” “future work,” and saga-record links despite the user-facing documentation rule.
• The text says generated-content counts are not hard-coded, but the Tutorial section hard-codes “58 lessons.” The number currently matches lessons.toml; the policy statement and implementation still contradict each other.
• “Demos that walk through every language feature end-to-end” is broader than the repository's actual coverage guarantee. The glossary test guarantees that every documented builtin is mentioned, not that every language feature has a complete demo.
• “Compile to Rust / native (v0.8.0)” attaches a release stamp to a stable capability.

The README remains usable for its manifest-path Quick Start and high-level tour, but it should not be treated as the sole authority for paths, backend boundaries, or exhaustive feature coverage until these items are corrected.

---

The original audit follows, unchanged except for this header.

Entries identify contradictions or likely stale material and point to stronger current evidence.

How to use this page

flowchart LR
    Claim[Documentation claim] --> Current{Matches current source and history?}
    Current -->|Yes| Use[Use as reference]
    Current -->|No| Errata[Check this errata]
    Errata --> Evidence[Prefer source, tests, CHANGES, completed saga]
    Evidence --> Scope[Separate shipped slice from future scope]

Loading

Severity meanings:

• High: likely to cause a failed build, wrong platform decision, or materially false capability claim.
• Medium: wrong paths, versions, status, or counts that confuse navigation and onboarding.
• Low: historical wording or internal inconsistency with limited operational impact.

Summary

Area	Severity	Stale or inconsistent claim	Current evidence
CUDA guide	High	CUDA is planned and not shipped	CUDA foundation and demo-parity sagas, crates, tests, and demos are present
GPU training scope	High	Broad wording can imply arbitrary MLX/CUDA training	General GPU-training design says only recognized shapes are accelerated today
Root build instructions	High	Run cargo build at repository root	Current repository has cellular component workspaces and no root Cargo.toml
Configuration guide	High	CLI server and connected web remain planned	Server, SSE, cancel, persistence, reattach, visualization storage, and web connect mode shipped
Architecture guide	High	CUDA in-process is planned/deferred	CUDA-enabled evaluator/server vertical slice is implemented
MLX guide	Medium	LoRA is planned; CUDA is the future second backend	LoRA and a CUDA vertical slice have shipped; persistent MLX tensor work is active
Paths throughout docs	Medium	apps/mlpl-web, root crates/mlpl-*, and services/mlpl-mlx-serve	Current code lives primarily under components/*/crates/*
Status scoreboard	High	Stops at v0.20-era roadmap and lists Engram only as generic planned Saga 18	Engram E1-E3 completed, E4 is active, later Engram phases remain planned
Engram status	Medium	Older docs say Engram has no concrete API	engram, apply_engram, engram_stats, hashes/gathers, tape path, and demos exist, while the overall track remains in progress
mHC status	Medium	Research documents discuss mHC without a current status landing page	mHC is planned soon, not shipped
Playground counts	Low	README says both 382 glossary entries and 377 alphabetical entries	Counts contradict within the same file and generated content changes frequently

Detailed findings

E-001: docs/using-cuda.md predates the CUDA implementation

Severity: High. The CUDA guide says “planned,” “not yet shipped,” and describes Saga 17 as future work. The current repository contains components/cuda-rt, components/cuda-model, and components/cuda-eval, plus demos/lora_finetune_cuda.mlpl, published CUDA literate pages, and real-GPU parity tests.

Use CUDA foundation and CUDA demo parity for current implemented scope. Preserve an important qualification: a separate generalized CUDA service/distributed layer and arbitrary-model GPU autograd are not complete.

E-002: broad accelerator wording overstates general training

Severity: High. The README and older MLX/status prose can be read as saying autograd, optimizers, and train work generally on MLX. The actual backend design uses special accelerated paths for recognized LoRA and MLP shapes; an unsupported model can fall through to the CPU tape. The same issue applies to CUDA.

The authoritative limitation is documented in future general GPU training. The active persistent-tensor work is addressing this foundation. Documentation should eventually distinguish “same language remains correct,” “forward op dispatched,” and “entire training graph GPU-resident.”

E-003: root quick-start commands no longer match the cellular monorepo

Severity: High. The README shows root-level commands such as cargo build, cargo run -p mlpl-repl, and cargo bench -p mlpl-bench. The repository root currently has no Cargo.toml. Binaries and tools live in component workspaces such as components/cli, components/serve, and components/dev-tools.

Users must change into the owning component workspace or pass --manifest-path. Demo file paths must then be adjusted relative to that workspace.

E-004: docs/configurations.md contains mutually inconsistent eras

Severity: High. The header says it is current through v0.18.0 and early sections acknowledge shipped server/MLX-service slices. Later sections still title the CLI server “planned” and list mlpl-serve, mlpl-repl --connect, and web origin routing as planned. Those later claims are superseded by Saga 21 and 21.5 implementation.

The same file refers to old install paths such as apps/mlpl-repl. Use the CLI server guide for the shipped REST/SSE, cancellation, persistence, reattach, visualization, and connected-browser surface, while also applying path erratum E-007.

E-005: docs/architecture.md is a pre-CUDA topology snapshot

Severity: High. The architecture guide labels in-process CUDA planned/deferred and presents R2/R3 as the only CUDA future. The current code has an in-process CUDA feature and a CUDA-enabled mlpl-serve vertical slice on Linux/NVIDIA.

The future separate CUDA peer service, multi-GPU/distributed operations, and discovery are still not shipped. A future documentation update should show both the current in-process CUDA server and the planned symmetric peer topology.

E-006: docs/using-mlx.md mixes a v0.11 retrospective with obsolete future claims

Severity: Medium. The MLX guide correctly documents early MLX behavior and poor eager round-trip performance, but still calls LoRA planned and CUDA a future backend. Both have since gained shipped slices. Its old crates/mlpl-mlx and crates/mlpl-eval paths also predate component decomposition.

The performance caveat remains valuable. It should now be paired with the active persistent-tensor/Metal work and with a precise distinction between supported fast paths and general training.

E-007: many code paths point to the former monolithic layout

Severity: Medium. Examples include:

• apps/mlpl-web in the README, REPL guide, server guide, and configuration guide.
• crates/mlpl-eval, crates/mlpl-serve, crates/mlpl-cli, and crates/mlpl-bench in multiple guides.
• services/mlpl-mlx-serve in status/architecture-era prose.

Current equivalents generally live under a component workspace, for example components/web/crates/mlpl-web, components/eval/crates/mlpl-eval, components/serve/crates/mlpl-serve, and components/dev-tools/crates/mlpl-bench. Exact crate ownership should be resolved from current component manifests because decomposition continues.

E-008: docs/status.md is no longer a complete current scoreboard

Severity: High. The status page ends its completed table around v0.20 and presents CUDA-as-a-service as wholly planned. It does not capture the later CUDA foundation/demo parity work or the active Engram E1-E4 sequence recorded in CHANGES.md, docs/saga.md, and .agentrail/plan.md.

It remains useful as historical release context but should not be used alone to answer “what exists today?”

E-009: Engram documentation spans obsolete “planned” and current implemented states

Severity: Medium. Older files such as docs/status.md, docs/plan.md, docs/missing-demos.md, docs/gaps-to-be-addressed.md, and docs/are-we-driven-yet.md describe Engram generically as future research or lacking an API. Current source and references contain:

• ngram_hash and gather_rows primitives.
• engram(...), apply_engram(...), and engram_stats(...).
• Differentiation and training through the Engram path.
• Engram Hash, Learnable Phrase Memory, and Tiny LM + Engram demos.
• Completed E1-E3 records.

The correction is not “Engram is finished.” The Engram saga plan is a multi-stage E1-E10 effort. E4 persistent GPU tensors is active, with MLX, import/retrofit, large-model, checkpoint/scaling, and CUDA phases still ahead.

E-010: mHC needs an explicit planned-soon status

Severity: Medium. Research and paper-driven documents discuss mHC, and are-we-driven-yet correctly identifies only partial prerequisites such as ModelSpec; constrained projections and the mHC architecture graph do not exist as completed capability.

At this snapshot, mHC is planned soon. It should be clearly listed in a current roadmap/status document before readers can reliably distinguish it from implemented paper-driven features.

E-011: README playground counts conflict internally

Severity: Low. The README introduction says the playground has 63 demos, 58 lessons, and a 382-entry glossary. Its glossary section later says 377 alphabetical entries. At least the glossary counts cannot both describe the same snapshot. Demos, lessons, and glossary data are generated/evolving, so hard-coded counts should be generated during the page build or labeled with a build date.

E-012: README backend-roadmap section is stale

Severity: Medium. The README groups using-mlx.md and using-cuda.md under "forward-looking, not yet shipped," despite MLX having shipped long ago and the current CUDA vertical slice being implemented. using-ollama.md is similarly framed by an older Saga-19 status even though llm_call and :ask work exist in native paths.

Original maintenance recommendations and current remainder

The original maintenance list is retained here as an audit record. Items 1-7 were addressed by the 2026-08-02 repair commit through rewrites, generated-count removal, or explicit supersession banners:

1. Fix root build/install commands for component workspaces.
2. Replace docs/using-cuda.md with a current shipped-scope guide.
3. Rewrite the configuration and architecture matrices around current local/server/peer modes.
4. Add explicit GPU-residency and fallback language to every accelerator claim.
5. Refresh docs/status.md with CUDA, post-v0.20 work, Engram E1-E4, and mHC planned-soon status.
6. Mechanically update former apps, crates, and services paths.
7. Generate playground content counts from the registry at build time.

The remaining current documentation work is narrower:

1. Update the docs/status.md historical banner done 2026-08-02 (0767c0d5): the banner now links to living sources instead of restating roadmap state.
2. Continue the mechanical old-path sweep beyond the high-visibility banners.
3. Keep CUDA wording explicit that general resident-tape training awaits cuda-resident-tensors.
4. Avoid copying fast-moving roadmap ordering into historical status pages; link to docs/future-sagas-queue.md instead.

Audit boundary

This audit focuses on high-visibility user, deployment, backend, architecture, status, Engram, and mHC documentation. It is not a line-by-line verification of every historical plan or research transcript. Planning files are expected to preserve historical ideas; the issue is when they are linked or labeled as current reference without a supersession notice.

E-023: REPL-command documentation was incomplete and drift-prone (RESOLVED 2026-08-05)

User review found the Usage Guide REPL table missing entries (:history, :tokenizers, :3d reset, the :disp(expr) call form, four long-form aliases) and several undocumented behaviors (--help only worked on one surface; :describe rejected colon spellings; unknown colon lines silently evaluated). Resolved in the sw-mlpl repo across commits 84ac3271..5417f229: the table is now PINNED to the runtime command registry by usage_table_tests (drift fails the build), --help is exhaustive over every command, and the colon-forms trichotomy is documented in the Usage Guide with a matching glossary entry.

E-024: Capability Matrix lacked the extension C-ABI adapter (RESOLVED 2026-08-09)

The Capability Matrix listed the native extension registry only for safe-Rust static providers. sw-mlpl now also accepts a #[repr(C)] provider descriptor: a statically linked provider whose C entry returns an ExtensionDescriptorV1 registers via register_c_extension, and its functions dispatch through the interpreter with the same namespace:function spelling (scalar values; arrays/handles and dynamic loading remain out of scope). Added a matching Capability Matrix row so the matrix and the shipped surface agree.

E-025: MLPB codec gained a v2 integrity checksum (RESOLVED 2026-08-09)

The Capability Matrix described the typed-native binary codec without integrity checking. to_native now emits MLPB v2, which appends a CRC32 (little-endian u32) over the payload; parse_native verifies it and rejects a corrupted payload that would otherwise decode as a valid-but-wrong value. Reads remain backward compatible: a v1 buffer (no checksum) still decodes. Updated the matrix row to note the v2 CRC32 integrity and v1 read support.