118 lines
6.6 KiB
Markdown
118 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-26
|
||
|
||
- **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–I and J0–J5 of
|
||
[`plans/2026-07-24-modern-runtime-architecture.md`](plans/2026-07-24-modern-runtime-architecture.md)
|
||
are complete. Production uses prepared world/collision packages, typed
|
||
residence, retained render-scene/delta submission, bounded frame owners, and
|
||
flat-authoritative collision without parsed-graph production residency.
|
||
Runtime owns canonical session/transport, entity/object lifetime, J4
|
||
gameplay state, selection/interaction transactions, and combat/magic intent.
|
||
App materialized projections and retained widgets borrow exact Runtime
|
||
identity and action owners. Runtime also owns the sole per-session physics,
|
||
collision, body/host, remote/projectile simulation, and cell-commit graph.
|
||
J5 closed at `cdee7a4b` with one combined simulation ledger, a
|
||
Runtime-only movement/use/combat/cast/projectile host, 8,596 complete
|
||
Release tests / 5 skips, and exact-binary lifecycle plus nine-stop gates.
|
||
J6 world/portal/environment and projection-handshake ownership is active in
|
||
[`plans/2026-07-25-modern-runtime-slice-j.md`](plans/2026-07-25-modern-runtime-slice-j.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:** complete Slice J's world handshake,
|
||
composition root, and no-window closeout, then build the approved
|
||
Linux/headless multi-session host in Slice K. J5.7's exact rollback is
|
||
`git revert cdee7a4b49addb5e1500753f6a885f7c899bd0f0`.
|
||
- **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,596 tests pass and
|
||
five are intentionally skipped. The exact J5.7 lifecycle/reconnect and
|
||
canonical nine-stop gates match embedded binary/source commit, converge
|
||
every backlog, and complete with graceful zero-code exits and zero failures.
|
||
|
||
## 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.
|