172 lines
13 KiB
Markdown
172 lines
13 KiB
Markdown
# Architecture and documentation assessment
|
||
|
||
Status: **complete at the recorded baseline**.
|
||
|
||
## Declared authority order
|
||
|
||
The repository declares milestones authoritative for the active outcome, the
|
||
roadmap authoritative for ordering, issues authoritative per defect, and
|
||
architecture documents authoritative for implementation shape. Research and
|
||
dated plans are historical evidence. This is a reasonable model, but the
|
||
current documents duplicate enough mutable state that the order does not
|
||
resolve contradictions reliably.
|
||
|
||
## Initial architecture-to-repository observations
|
||
|
||
| Subject | Documented current contract | Repository evidence | Initial assessment |
|
||
|---|---|---|---|
|
||
| Graphics backend | Vulkan only; OpenGL deleted | App references `Silk.NET.Vulkan`; Vulkan/RHI source exists | architecture matches code; public README is stale |
|
||
| Gameplay UI | one retained stack; ImGui deleted | no `AcDream.UI.ImGui` project; retained UI in App | architecture matches code; README and some rule wording are stale |
|
||
| Runtime boundary | Runtime may depend on Core, Core.Net, Content, Platform, Plugin.Abstractions; never App/UI/backend | project/source graph matches; dependency guards pass | confirmed |
|
||
| Headless boundary | Headless directly references Runtime only | project graph and executed loaded-assembly guards match | confirmed; operability exceptions recorded separately |
|
||
| Platform boundary | Platform has zero references | project graph and complete two-file source review match | confirmed |
|
||
| Reference workflow | six vendored reference projects | only uninitialized WorldBuilder gitlink exists | documented process is not reproducible |
|
||
| GameWindow shell | architecture checkpoint says 1,622 lines | current file is 1,860 lines | still primarily a composition/callback shell, but checkpoint and navigability claim have drifted |
|
||
| UI abstraction | backend-neutral panel/input seam | directly references Runtime and Silk input; old panel renderer has no implementation | boundary name and owned concerns no longer match |
|
||
| Presentation stacks | one retained retail UI | retained retail UI ships, but unreachable `IPanelRenderer`/ImGui-era panels remain compiled and tested | dead second design obscures the shipping stack |
|
||
| Build authority | .NET 10 solution with warnings-as-errors | no pinned SDK/locked restore/central build settings; policy copied inconsistently across 44 projects | a commit is not a reproducible toolchain definition |
|
||
| Issue authority | one authoritative status per defect | 380 headings/378 IDs, about two-thirds closed history, 29 broken links | tactical queue is also an archive and research journal |
|
||
|
||
## Documentation-system concerns under review
|
||
|
||
1. `README.md` currently contradicts the architecture on the most basic user
|
||
prerequisite: Vulkan versus OpenGL and the existence of ImGui.
|
||
2. `docs/README.md` is presented as a current-state guard but predates completed
|
||
work linked from the same page.
|
||
3. `AGENTS.md` is 1,615 lines and embeds a long commit-by-commit status ledger,
|
||
rollback commands, local credentials, machine paths, tool instructions,
|
||
architectural rules, and reference tutorials. Its normative rules are hard
|
||
to distinguish from stale operational history.
|
||
4. The architecture document similarly combines stable dependency rules with
|
||
current phase state, historical campaign checkpoints, test totals, exact
|
||
commits, and future target designs.
|
||
5. Required links into `claude-memory/` and `.claude/skills/` are absent from
|
||
the baseline worktree.
|
||
6. The current milestone, roadmap, and world-interaction plan each preserve a
|
||
different pre-closeout state even though the plan itself has a later closeout
|
||
section. Authority precedence cannot resolve a contradiction inside every
|
||
claimed authority.
|
||
7. The mandatory WorldBuilder inventory still gives OpenGL and ImGui design
|
||
direction after both were deleted.
|
||
8. The issue ledger's status convention is not mechanically enforceable: two
|
||
duplicate IDs, nine missing/nonstandard status blocks, and broken links sit
|
||
inside a 19,073-line file every session is instructed to scan.
|
||
9. The active-document link check found three broken links even before the
|
||
historical corpus: the missing `claude-memory/MEMORY.md` map and two missing
|
||
Phase O documents linked from roadmap line 505.
|
||
10. The retail-divergence authority has correct headline row counts but is not
|
||
maintainable as a review surface: 809 KB in 525 physical lines, 243 lines
|
||
longer than 1,000 characters, a 45,240-character heading, and 11 unique
|
||
unresolved source/test paths among 843 path citations. Its title is six
|
||
weeks behind its own latest entries.
|
||
11. The approved plugin architecture reads as an implemented contract but is
|
||
mostly aspirational. The manifest accepts every positive API version,
|
||
declared dependencies are unused, the promised abstractions package has no
|
||
pack/version metadata, and callback-fault/hot-reload behavior differs from
|
||
the design.
|
||
12. The launcher consumes a production GitHub Release manifest, but the
|
||
repository contains no production release workflow or manifest generator,
|
||
no tags/central product version, and no contribution, security, changelog,
|
||
or code-ownership documents.
|
||
13. `AGENTS.md` explicitly claims to be synchronized from `CLAUDE.md`, but the
|
||
files differ by 255 insertions and 27 deletions. The stale copy restarts a
|
||
completed interaction slice and disagrees about reference count, retired
|
||
AC2D status, and streaming-radius configuration. This makes the executing
|
||
assistant, rather than the repository commit, select project truth.
|
||
14. Tracked `memory/` documents labeled “current truth” still prescribe ImGui
|
||
frame submission, the deleted UI.ImGui project, OpenGL bindless capability
|
||
gates, and resuming the now-complete interaction Slice 4. Because root
|
||
instructions route work into these files, they are active contradictions,
|
||
not harmless archived notes.
|
||
15. A repository-wide scan of all 1,014 tracked Markdown files found 397
|
||
broken relative-link occurrences, representing 357 distinct file/target
|
||
pairs. Historical records account for most of the debt: 197 pairs in
|
||
`docs/research` and 130 in `docs/superpowers`. The current authority layer
|
||
has a much smaller but material set: `docs/README.md` points at the absent
|
||
`claude-memory/MEMORY.md`; the roadmap points at two absent Phase O
|
||
records; one old handoff points at a deleted VFX test; and one tracked
|
||
memory index points at a missing phase audit. `docs/ISSUES.md` contributes
|
||
25 distinct broken Markdown-link pairs. Historical link rot should be
|
||
repaired or frozen by support tier, but it is not equivalent in severity
|
||
to a broken current-authority link.
|
||
16. The dated plans/specs/research system is now 80 top-level plans, 100
|
||
`superpowers/plans`, 96 specs, and 700 research Markdown files. Recent
|
||
campaign plans do generally put status near the top, which is good, but
|
||
several preserve contradictory status prose in-place (for example an
|
||
`IN FLIGHT` label followed immediately by a later `CAMPAIGN CLOSED`
|
||
clause). There is no generated active/archive index or schema validation;
|
||
readers must interpret narrative amendments to decide which paragraph is
|
||
operative.
|
||
|
||
## Source-structure census
|
||
|
||
The project-reference graph is acyclic and the primary declared assembly
|
||
boundaries are present: Platform has no references, Headless references Runtime
|
||
only, and Runtime has no App/UI/backend reference. The maintainability risk is
|
||
inside several of those correct graph boxes. Source hotspots are highly
|
||
concentrated: App has 37 files above 1,000 lines, Runtime 20, Core 13, and the
|
||
five largest owned files range from 3,754 to 6,345 lines. Campaign/history
|
||
language also remains densest in those owners (2,349 rough source occurrences
|
||
in App, 698 in Core, and 491 in Runtime).
|
||
|
||
| Assembly | Primary assessment at this checkpoint |
|
||
|---|---|
|
||
| `AcDream.App` | Layer role is valid, but composition/render/UI/network sidecars remain too concentrated; dead presentation/backend seams, source-shape tests, static diagnostics, and the unconditional smoke-plugin publish make the shipping boundary hard to reason about. |
|
||
| `AcDream.Runtime` | Project boundary is real and well guarded, but `RuntimeSetPositionState` (6,283 lines) and several 2,500–3,200-line gameplay/entity owners combine algorithms, state machines, ledgers, and diagnostics beyond a human-scale change unit. |
|
||
| `AcDream.Core` | Contains valuable faithful ports with strong oracle citations, but giant physics units, process-static diagnostics, external-type leakage, and campaign/issue narrative obscure the stable algorithms. |
|
||
| `AcDream.Core.Net` | Protocol/session ownership is coherent; `WorldSession` remains a 3,754-line transport/lifecycle owner with dense historical comments, direct environment probes, and synchronous shutdown risk that warrants focused refactoring only after behavior is pinned. |
|
||
| `AcDream.Content` | Prepared-content boundary is conceptually clean, but public mesh DTOs still expose Chorizite types and GL-ABI vocabulary despite a Vulkan-only consumer. |
|
||
| `AcDream.Headless` | Presentation dependency guard is strong. Silent plugin callback failure and process-static/config conventions weaken operability; three files exceed 1,000 lines. |
|
||
| `AcDream.Launcher.Core` / `Launcher` | Update/install security and transaction design are unusually thorough, but the full-suite lock inversion is a release blocker and there is no owned production release publisher. Several view-model/orchestrator/update owners are oversized. |
|
||
| `AcDream.Platform` | Small, cohesive, and dependency-free as documented. |
|
||
| `AcDream.Plugin.Abstractions` | BCL-only and small, but not yet a versioned/published compatibility contract; the approved design substantially overstates the implemented surface. |
|
||
| `AcDream.UI.Abstractions` | Input/keybinding pieces remain useful; the project also retains a dead ImGui-era panel stack and directly depends on Runtime/Core, so its name no longer describes one neutral abstraction layer. |
|
||
| Bake / CLI / tools | Bake's transaction boundary is understandable though its runner is 1,067 lines. CLI and most forensic tools are campaign utilities without a support tier; many are excluded from the solution or require developer-local paths. |
|
||
|
||
## Recommended documentation information architecture
|
||
|
||
1. Keep `README.md` public and release-oriented: supported platforms/backend,
|
||
install/run path, actual maturity, credential-storage disclosure, licence,
|
||
and links to release/security/contribution documents. Do not duplicate
|
||
campaign state or rolling test totals there.
|
||
2. Make `docs/README.md` a stable navigation page plus a generated, dated
|
||
status block sourced from one structured milestone ledger. A CI check should
|
||
fail when the block, project graph, backend, links, or reported gate command
|
||
disagrees with the repository.
|
||
3. Restrict architecture documents to durable component ownership, dependency
|
||
rules, threading/lifetime contracts, data flow, and intentional seams. Move
|
||
commits, rollback recipes, test counts, and campaign closeout narrative into
|
||
dated decision/closeout records.
|
||
4. Replace duplicated `AGENTS.md`/`CLAUDE.md` bodies with one tool-neutral
|
||
maintained instruction source and generated thin adapters. Agent-only tool
|
||
syntax should not carry product truth.
|
||
5. Normalize issues and retail divergences into one record per stable ID with
|
||
machine-readable status, owner, current rationale, oracle, live symbol/path,
|
||
and review date. Generate compact active indexes; archive amendment history
|
||
separately.
|
||
6. Treat plans, specs, research, probes, raw captures, and memory as explicit
|
||
support tiers: active, superseded, immutable evidence, or external artifact.
|
||
Validate relative links only against the promises of each tier and prevent a
|
||
historical document from calling itself “current truth.”
|
||
7. Add one owned release runbook and automation for pinned clean restore/build,
|
||
the complete bounded test matrix, installed-DAT/live/manual lanes, per-RID
|
||
packages, manifest/checksum/SBOM/provenance generation, rollback, and public
|
||
publication.
|
||
|
||
## Positive architecture findings
|
||
|
||
- The project-reference graph is acyclic and the most important assembly
|
||
boundaries are real: Platform is dependency-free, Headless references
|
||
Runtime only, Runtime does not reference App/UI/backend assemblies, and
|
||
Plugin.Abstractions is BCL-only.
|
||
- `GameRuntime` ownership, generation gating, teardown ledgers, updater
|
||
transaction design, path traversal/hash validation, and credential redaction
|
||
have unusually substantial adversarial test coverage.
|
||
- The named-retail oracle is committed and searchable, so the core retail-
|
||
fidelity workflow does not depend entirely on the missing external reference
|
||
checkouts. The weakness is provenance/licensing and surrounding reference
|
||
reproducibility, not absence of the primary algorithm corpus.
|
||
- Production code builds without warnings at the baseline; all 26 rebuild
|
||
warnings are confined to test projects. Current package-source vulnerability
|
||
lookup reported no known vulnerable direct or transitive packages, although
|
||
the unpinned restore prevents treating that as a permanent commit property.
|