119 lines
6.6 KiB
Markdown
119 lines
6.6 KiB
Markdown
# acdream documentation map
|
||
|
||
This page is the entry point for project documentation. It distinguishes
|
||
current sources of truth from implementation history so an old plan or issue
|
||
banner cannot silently override the current program state.
|
||
|
||
## Current snapshot — 2026-07-24
|
||
|
||
- **Milestone state:** M3, “Cast a spell,” landed 2026-07-21. M4, “Live in the
|
||
world,” is active.
|
||
- **M4 gameplay program (paused while the authorized performance program
|
||
executes):** the pre-M4 world-interaction completion program
|
||
in
|
||
[`plans/2026-07-23-world-interaction-completion.md`](plans/2026-07-23-world-interaction-completion.md).
|
||
The eight-slice `GameWindow` decomposition and its connected visual matrix
|
||
are complete.
|
||
- **Current active engineering program:** Slices A–E of
|
||
[`plans/2026-07-24-modern-runtime-architecture.md`](plans/2026-07-24-modern-runtime-architecture.md)
|
||
are complete. Production world-mesh streaming consumes the validated
|
||
prepared package, typed residency is bounded/accounted, and streaming now
|
||
has typed admission plus immediate old-generation quiescence, metered
|
||
retirement, and retained cursor-budgeted publication across render, physics,
|
||
statics, building registries, collision/reflood, and EnvCells. The canonical
|
||
reveal generation now owns an exact destination reservation across every
|
||
typed budget dimension; incomplete destinations remain in portal space and
|
||
receive retail's centered wait cue instead of forced early reveal. E6's
|
||
deterministic/resource gates and capped, uncapped, and dense-Arwic
|
||
physical-local routes pass. Slices F–L, including the F/G and J approval
|
||
gates, were explicitly authorized 2026-07-24; Slice F is active.
|
||
Their post-E evidence, ownership map, shadow-comparison design, cutover
|
||
sequence, and acceptance matrix are implementation-ready in the
|
||
[F/G render-scene plan](plans/2026-07-24-modern-runtime-slices-f-g-render-scene.md).
|
||
See also the [Slice E streaming report](research/2026-07-24-slice-e-cost-budgeted-streaming-report.md).
|
||
- **Completed gates:** R6 locomotion/collision/projectile/teleport/radar and
|
||
the final two-client portal-out/materialization observer comparison (`#218`).
|
||
- **Separate visual verification:** the shared-alpha lifestone/particle result
|
||
in `#225`; its connected resource-lifetime and performance routes pass.
|
||
- **Carried behavior debt:** `#153` (far teleport onto an unstreamed edge),
|
||
`#116` (two narrowed slide-response cases), and divergence rows TS-50/TS-51.
|
||
- **Active engineering track:** render ECS/MP3 is executing from the
|
||
implementation-ready F/G plan, followed by the approved Linux/headless
|
||
automation slices. The pre-F/G runtime rollback anchor is `e7d9d6fa`.
|
||
- **Divergence audit:** 178 active rows — IA 17, AD 37, AP 85, TS 34,
|
||
and UN 5 — plus the retained retired TS-37 history note.
|
||
- **Latest automated baseline:** Release build succeeds; 8,164 tests pass and
|
||
five are intentionally skipped. The capped, uncapped, and dense-Arwic
|
||
physical prepared-asset routes all completed their portal/input/lifetime
|
||
assertions and disconnected gracefully.
|
||
|
||
## Sources of truth
|
||
|
||
Read these in this order when deciding what to do next:
|
||
|
||
1. [`plans/2026-05-12-milestones.md`](plans/2026-05-12-milestones.md) — the
|
||
active playable outcome, freeze boundaries, and visual gates.
|
||
2. [`plans/2026-04-11-roadmap.md`](plans/2026-04-11-roadmap.md) — strategic
|
||
phase ledger: shipped, active, deferred, and future work.
|
||
3. [`ISSUES.md`](ISSUES.md) — tactical defects and small follow-ups. The status
|
||
inside an issue is authoritative; physical order is not.
|
||
4. [`architecture/retail-divergence-register.md`](architecture/retail-divergence-register.md)
|
||
— every known place runtime behavior can differ from retail.
|
||
5. [`architecture/acdream-architecture.md`](architecture/acdream-architecture.md)
|
||
and [`architecture/code-structure.md`](architecture/code-structure.md) —
|
||
ownership, dependency, update-thread, and extraction rules.
|
||
6. [`architecture/worldbuilder-inventory.md`](architecture/worldbuilder-inventory.md)
|
||
— rendering/DAT code already owned in-tree versus mechanisms still ours to
|
||
port.
|
||
|
||
If these disagree, milestones control the current outcome, the roadmap controls
|
||
work ordering, the issue status controls the individual defect, and the
|
||
architecture documents control implementation shape. Reconcile the stale
|
||
document in the same change; do not leave both claims standing.
|
||
|
||
## Research and implementation records
|
||
|
||
- [`research/named-retail/`](research/named-retail/) is the primary retail
|
||
oracle: named pseudo-C, headers, symbols, and types from the Sept 2013 build.
|
||
- [`research/decompiled/`](research/decompiled/) is the older Ghidra fallback.
|
||
- [`research/`](research/) contains focused pseudocode, traces, fixtures, and
|
||
gate reports. A dated research note records evidence; it does not become a
|
||
new roadmap.
|
||
- [`superpowers/specs/`](superpowers/specs/) and
|
||
[`superpowers/plans/`](superpowers/plans/) are per-slice design and execution
|
||
records. Completed plans remain historical.
|
||
- [`audit/`](audit/) contains completion and conformance audits.
|
||
|
||
## Durable memory
|
||
|
||
- [`../claude-memory/MEMORY.md`](../claude-memory/MEMORY.md) indexes the live
|
||
subsystem memories and the render/physics digests. Read a domain digest
|
||
before changing that subsystem, especially its DO-NOT-RETRY table.
|
||
- [`../memory/`](../memory/) contains stable engineering references such as the
|
||
modern rendering pipeline, two-tier streaming, and toolchain notes.
|
||
|
||
Memory accelerates recall; it does not outrank the canonical documents above.
|
||
When current truth changes, update the relevant canonical document and distill
|
||
only the durable lesson into memory.
|
||
|
||
## Historical and deprecated documents
|
||
|
||
- [`bugs.md`](bugs.md) is the April 2026 bug snapshot. It is preserved for
|
||
archaeology and is not an active ledger.
|
||
- Dated plans and specs describe the decision at that time. Their completion
|
||
wording is historical unless the current milestone/roadmap explicitly links
|
||
the item as active.
|
||
- Old `R1→R8` architecture sequencing is superseded. Current execution comes
|
||
from the milestones and strategic roadmap.
|
||
|
||
## Documentation maintenance rules
|
||
|
||
- Update milestone, roadmap, issue, divergence, architecture, and memory claims
|
||
in the same commit when a shipped change affects them.
|
||
- Keep one issue ID per defect. Narrow an issue in place; do not reuse another
|
||
issue's number as a shorthand.
|
||
- Mark automated, connected, and visual gates separately. An automated pass is
|
||
not a visual acceptance, and an RDP throughput sample is not a local-display
|
||
visual comparison.
|
||
- Preserve research history, but remove stale “current/next” claims from living
|
||
documents once the state advances.
|