Initial commit: architecture docs and headless engineering proof

Aeternalis Evolution, a custom-engine persistent evolutionary MMO.

This first commit establishes the project skeleton:

- Architecture and design docs: project vision, system overview,
  engineering constitution, roadmap, 19 ADRs, and the simulation,
  world, network, persistence and infrastructure architectures.
- Headless engineering proof: deterministic synthetic particles,
  component lifecycle, explicit PRNG streams, canonical snapshots
  and restored execution.
- Build and tooling: CMake 3.28+ / Ninja presets, C++23 feature
  check, clang-format and clang-tidy config, format check script,
  Windows check script, and a Docker build context.
- Tests: unit tests, benchmarks, a snapshot fuzz target and CLI
  integration wiring.

No gameplay, renderer, network service or running deployment yet.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
This commit is contained in:
dingo
2026-09-14 15:44:41 -04:00
co-authored by Claude Opus 5
commit d5b4bd068e
63 changed files with 3531 additions and 0 deletions
+36
View File
@@ -0,0 +1,36 @@
# Container and delivery foundation
M0 builds/tests evo-sim. It deploys no Kubernetes resources, publishes no image,
connects no database and supplies no persistent region server.
```sh
docker build --file deploy/docker/Dockerfile --tag aeternalis-evo:dev .
docker run --rm --network none --read-only --cap-drop ALL \
--security-opt no-new-privileges aeternalis-evo:dev \
--seed 123456 --ticks 1000 --verify-replay
```
The GCC14 build stage runs CTest before producing the non-root UID/GID10001 runtime.
It includes the executable and system runtime libraries. Builder package versions
are recorded at /usr/share/evo/build-packages.txt. Output is stdout; file outputs
require an explicitly mounted writable destination.
CI covers GCC14 Debug/Release, MSVC, LLVM19 format/tidy, ASan/UBSan, separate TSan,
bounded seeded libFuzzer and image build/smoke. TSan validates its configuration
on the current sequential kernel, not a future scheduler. Runtime/runner failures
must be diagnosed, never marked passing. Retain useful fuzz reproducers and add
longer campaigns when decoder complexity warrants them.
Scaffold limits: hosted runners, Ubuntu tag and distro security packages move.
Before publishing, review/pass UBUNTU_IMAGE as an immutable digest, retain package
manifests/results, produce an SBOM, scan/sign and promote the final digest through
reviewed GitOps. The pinned checkout action also needs normal security updates.
[GCC14 package](https://packages.ubuntu.com/noble/g%2B%2B-14),
[LLVM packages](https://packages.ubuntu.com/clang),
[checkout v4.2.2 commit](https://github.com/actions/checkout/commit/11bd71901bbe5b1630ceea73d27597364c9af683).
Harbor, Argo CD, Argo Workflows and Kubernetes follow
[infrastructure architecture](../docs/architecture/INFRASTRUCTURE_ARCHITECTURE.md)
and [operations gates](../docs/infrastructure/OPERATIONS.md). World0 promotion is
manual; state is protected from routine cleanup. No fake endpoints/credentials or
unvalidated storage-class manifests are supplied.
+29
View File
@@ -0,0 +1,29 @@
# Development bootstrap tag. Promotion requires an approved immutable digest.
ARG UBUNTU_IMAGE=ubuntu:24.04
FROM ${UBUNTU_IMAGE} AS build
ENV DEBIAN_FRONTEND=noninteractive
RUN apt-get update \
&& apt-get install -y --no-install-recommends ca-certificates cmake ninja-build g++-14 \
&& rm -rf /var/lib/apt/lists/*
WORKDIR /source
COPY . .
RUN cmake --preset release -B build/container \
-DCMAKE_CXX_COMPILER=g++-14 -DCMAKE_RUNTIME_OUTPUT_DIRECTORY=/opt/evo/bin \
&& cmake --build build/container --parallel 2 \
&& ctest --test-dir build/container --output-on-failure --no-tests=error --timeout 120
RUN dpkg-query -W > /opt/evo/build-packages.txt
FROM ${UBUNTU_IMAGE} AS runtime
ENV DEBIAN_FRONTEND=noninteractive
RUN apt-get update \
&& apt-get install -y --no-install-recommends libstdc++6 libgcc-s1 \
&& rm -rf /var/lib/apt/lists/* \
&& groupadd --gid 10001 evo \
&& useradd --uid 10001 --gid 10001 --no-create-home \
--home-dir /nonexistent --shell /usr/sbin/nologin evo
COPY --from=build /opt/evo/bin/evo-sim /usr/local/bin/evo-sim
COPY --from=build /opt/evo/build-packages.txt /usr/share/evo/build-packages.txt
USER 10001:10001
WORKDIR /tmp
ENTRYPOINT ["/usr/local/bin/evo-sim"]
CMD ["--seed", "123456", "--ticks", "1000"]