This directory documents a research artifact: a falsifiable test of LLM-augmented systems engineering at one-person scale, operationalized as a moddable simulation engine with declared invariants. The full research framing is in the root README; the engine exists to stress-test the methodology under non-trivial workload.
Three documents carry the primary research weight: METHODOLOGY describes the pipeline as designed; PIPELINE_METRICS records the operational data measured while running it; MOD_OS_ARCHITECTURE describes the capability-based mod isolation as an OS-style architecture; NATIVE_CORE_EXPERIMENT records a measured negative result with criterion reformulation. The remaining documents below describe the engine that supports the claim.
Before reading the source layout, read ARCHITECTURE and CONTRACTS. Without them the assembly structure looks excessive.
Technical documents describing the engine that stress-tests the methodology: layers, contracts, ECS core, event buses, multithreading, and isolation.
- ARCHITECTURE — the four layers, dependency rules, assembly diagram.
- MOD_OS_ARCHITECTURE — v1.5 LOCKED. Mod system as a small operating system: capabilities, shared ALC, three-level contracts, bridge replacement, three-tier versioning, hot reload, threat model. Drives the M1–M10 migration plan in ROADMAP.
- VULKAN_SUBSTRATE — v1.0 LOCKED. Unified Vulkan substrate (V) — rendering + compute use cases on one VkInstance/VkDevice per Q-G-1 LOCK (supersedes prior RUNTIME_ARCHITECTURE.md v1.0 + GPU_COMPUTE.md v2.0). Substrate primitives V0 (foundation, includes rendering migration phases R.0..R.8 — formerly M9.0..M9.8) / V1 (diffusion shader) / V2 (wave shader). M-V demonstrations (M-V1 mana, M-V2 electricity, M-V7 movement, M-V8 local avoidance) per Q-R-1 format. Domain layer preserved verbatim.
- CONTRACTS — marker interfaces, six domain buses, evolution and versioning.
- ECS —
World,EntityId,Component,SparseSet,Query,SystemBase. - EVENT_BUS — domain buses, the two-step Intent→Granted/Refused model, batch processing.
- THREADING —
DependencyGraph, phases, tick rates, the ban onasync. - ISOLATION —
SystemExecutionContext, the isolation guard, DEBUG vs RELEASE, types of violations. - GODOT_INTEGRATION (historical) —
PresentationBridge,IRenderCommand,InputRouter, the main thread. Superseded by VULKAN_SUBSTRATE §2.2 per Q-G-1 LOCK. - VISUAL_ENGINE (historical) — DevKit vs Native, the
IRenderer/ISceneLoader/IInputSourcecontracts, the.dfsceneformat. Superseded by VULKAN_SUBSTRATE per Q-G-1 LOCK.
Documents required to reproduce the work or contribute to it: methodology, modding, performance, coding standards, and tests.
- METHODOLOGY — the pipeline, contracts as IPC between agents, verification cycle, threat model, economics, boundaries of applicability.
- PIPELINE_METRICS — pipeline configuration, empirical metrics, throughput, subscription headroom, reproducibility requirements. Companion to METHODOLOGY.
- MODDING —
IMod,IModApi,AssemblyLoadContext,IModContract, the mod manifest. - MOD_PIPELINE — the integration pipeline,
ContractValidator,ModRegistry, atomicity. - PERFORMANCE — target metrics, profiling, hot paths, caches.
- VULKAN_SUBSTRATE §3-§5 — Compute use case of V substrate (consolidates former GPU_COMPUTE.md v2.0 content). Field-based GPU compute as a foundational architectural capability (Domain A: mana / electricity / water / heat / sound / scent on V1/V2 primitives), with
ProjectileSystempreserved as Domain B (entity-keyed bulk compute, substrate disposition deferred to M-V5 amendment). K9 field storage abstraction + V0/V1/V2 substrate primitives per Q-G-2 reductions. - CODING_STANDARDS — naming, file-scoped namespaces, nullable, member order.
- TESTING_STRATEGY — unit, integration, isolation, modding, performance.
- DEVELOPMENT_HYGIENE — the hygiene checklist for every PR, the engine/game boundary, red flags.
- NATIVE_CORE_EXPERIMENT — the C++ core experiment, the P/Invoke boundary, benchmark results, plan for the batching API in Phase 9.
- PERSISTENCE — save-compression algorithms: tile RLE, component quantization, entity range encoding, StringPool.
Work organization: phase order and acceptance criteria.
- ROADMAP — closed phases 0–4 plus the Mod-OS Migration (M0–M10), with acceptance criteria and what each phase unlocks next.
- MAXIMUM_ENGINEERING_REFACTOR — v1.0 RATIFIED. Three-track discipline escalation brief: formal verification (Track A), type-theoretic architecture (Track B), methodology replication kit (Track C). Activation deferred per-track; each track requires its own brief at activation time.
Self-teaching artifacts produced after each substantial phase closes (see METHODOLOGY §4.5).
- learning/PHASE_1 — C# and multithreading through the lens of Core ECS: class vs struct, generics, attributes via reflection, nullable,
ThreadLocal, race conditions, stack traces, tests as invariant proof. Includes a 14-day study path.
Verbatim logs of phase reviews and other key pipeline sessions. Not subject to post-hoc editing — they serve as an audit trail.
- SESSION_PHASE_4_CLOSURE_REVIEW — Phase 4 closure conducted by Opus 4.7: diagnostic validation, 6 architectural decisions, 17 new tests, 7 atomic commits. (Russian-language audit trail; preserved verbatim per the i18n campaign rules.)
Second-revision architecture additions: resource models, composite requests, feedback through tick lag, deterministic damage resolution, golem ownership transitions.
- RESOURCE_MODELS — Intent vs Lease, the choice rule, reserve-then-consume.
- COMPOSITE_REQUESTS — two-phase commit for multi-bus requests,
CompositeResolutionSystem. - FEEDBACK_LOOPS —
Mana[N-1], snapshots of the previous tick. - COMBO_RESOLUTION —
ComboResolutionSystem, deterministic sort ofDamageIntent. - OWNERSHIP_TRANSITION —
GolemBondComponentstates, transition table.