diff --git a/.gitattributes b/.gitattributes new file mode 100644 index 0000000..dc20dcc --- /dev/null +++ b/.gitattributes @@ -0,0 +1,5 @@ +* text=auto +*.sh text eol=lf +*.yaml text eol=lf +*.yml text eol=lf +Dockerfile text eol=lf diff --git a/.gitea/workflows/build.yaml b/.gitea/workflows/build.yaml index b8017cf..f4ee6a9 100644 --- a/.gitea/workflows/build.yaml +++ b/.gitea/workflows/build.yaml @@ -1,40 +1,69 @@ -name: Build and publish AEvolution +name: Foundation on: push: branches: [main] pull_request: + workflow_dispatch: + +permissions: + code: read + +env: + UBUNTU_IMAGE: ${{ vars.UBUNTU_IMAGE || 'ubuntu:24.04' }} jobs: - verify: - runs-on: ubuntu-22.04 + checks: + runs-on: ${{ vars.CI_RUNNER_LABEL || 'ubuntu-22.04' }} + timeout-minutes: 40 + strategy: + fail-fast: false + matrix: + suite: [checks, tsan] steps: - - uses: actions/checkout@v4 - - name: Install build dependencies - run: sudo apt-get update && sudo apt-get install -y --no-install-recommends cmake ninja-build g++-14 - - name: Configure release build - run: cmake --preset release -B build/ci - - name: Build - run: cmake --build build/ci --parallel 2 - - name: Test - run: ctest --test-dir build/ci --output-on-failure --no-tests=error --timeout 120 + - name: Checkout + uses: https://github.com/actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2 + with: + persist-credentials: false + - name: Build and execute Linux checks + env: + CHECK_SUITE: ${{ matrix.suite }} + run: | + set -eu + docker version + docker build --progress=plain --file deploy/docker/Dockerfile \ + --build-arg "UBUNTU_IMAGE=$UBUNTU_IMAGE" \ + --target "ci-$CHECK_SUITE" . - publish: - if: gitea.event_name == 'push' - needs: verify - runs-on: ubuntu-22.04 + image: + needs: [checks] + runs-on: ${{ vars.CI_RUNNER_LABEL || 'ubuntu-22.04' }} + timeout-minutes: 30 steps: - - uses: actions/checkout@v4 - - name: Check Docker - run: docker version - - uses: docker/login-action@v3 + - name: Checkout + uses: https://github.com/actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2 with: - registry: ${{ vars.HARBOR_HOST }} - username: ${{ secrets.HARBOR_USERNAME }} - password: ${{ secrets.HARBOR_PASSWORD }} - - uses: docker/build-push-action@v6 - with: - context: . - file: deploy/docker/Dockerfile - push: true - tags: ${{ vars.HARBOR_HOST }}/${{ vars.HARBOR_PROJECT }}/aevolution:${{ gitea.sha }} + persist-credentials: false + - name: Build and smoke-test runtime + run: | + set -eu + image="aevolution-proof:${GITHUB_SHA}-${GITHUB_RUN_ID}-${GITHUB_RUN_ATTEMPT}" + docker build --progress=plain --file deploy/docker/Dockerfile \ + --build-arg "UBUNTU_IMAGE=$UBUNTU_IMAGE" \ + --label "org.opencontainers.image.revision=$GITHUB_SHA" \ + --label "org.opencontainers.image.source=https://git.aeternalisgames.com/dingo/AEvolution" \ + --tag "$image" . + docker run --rm --network none --read-only --cap-drop ALL \ + --security-opt no-new-privileges "$image" \ + --seed 123456 --entities 8 --ticks 1000 --verify-replay + - name: Publish configured main build to Harbor + if: ${{ gitea.ref == 'refs/heads/main' && gitea.event_name != 'pull_request' && vars.HARBOR_PROJECT != '' }} + env: + HARBOR_PROJECT: ${{ vars.HARBOR_PROJECT }} + HARBOR_REPOSITORY: ${{ vars.HARBOR_REPOSITORY || 'aevolution' }} + HARBOR_USERNAME: ${{ secrets.HARBOR_USERNAME }} + HARBOR_PASSWORD: ${{ secrets.HARBOR_PASSWORD }} + run: bash tools/ci/publish-image.sh + - name: Explain unconfigured publishing + if: ${{ vars.HARBOR_PROJECT == '' }} + run: echo 'Image build/smoke only. Set HARBOR_PROJECT and Harbor robot secrets to enable main publishing. See deploy/README.md.' diff --git a/README.md b/README.md index 631304f..936c31b 100644 --- a/README.md +++ b/README.md @@ -17,6 +17,7 @@ network service or running Kubernetes deployment. - [Actionable milestones 0–4 and later gates](docs/ROADMAP.md) - [Open design questions](docs/architecture/OPEN_QUESTIONS.md) - [Actual validation results](docs/engineering/VALIDATION.md) +- [Current delivery status and next steps](docs/STATUS.md) Read [AGENTS.md](AGENTS.md) before changing code. Architecture and contracts are authoritative over implementation. No external runtime library is needed for @@ -78,8 +79,9 @@ fuzz and measurement programs. Future biology, world, networking and persistence modules are documented boundaries; they are added when they have real behavior. World0 is persistent state. No normal configure, build, test or CI job may create, -reset, deploy to or delete it. Kubernetes and GitOps are designed here; deployment -requires actual cluster inventory, credentials, storage and backup decisions. +reset, deploy to or delete it. Gitea builds the proof image for Harbor; a bounded +dev verification Job and manual Argo templates are in [deploy/](deploy/README.md). +Persistent-world deployment still requires storage, ownership and backup gates. The project license has not been selected. Do not infer an open-source license from a public dependency's license. diff --git a/deploy/README.md b/deploy/README.md index 061aedc..f9dac58 100644 --- a/deploy/README.md +++ b/deploy/README.md @@ -1,36 +1,97 @@ -# Container and delivery foundation +# Build and dev delivery -M0 builds/tests evo-sim. It deploys no Kubernetes resources, publishes no image, -connects no database and supplies no persistent region server. +The maintainer has configured Gitea, Harbor and Argo. Gitea run +[1399](https://git.aeternalisgames.com/dingo/AEvolution/actions/runs/1399) +successfully built, tested and published commit `8ab48d3`. This repository adds +broader checks and a bounded **stateless proof Job**. It is not a region server. +Cluster execution must be recorded separately from image publication. + +## Gitea and Harbor + +The single workflow is `.gitea/workflows/build.yaml`. The existing runner label +is `ubuntu-22.04`; this does not imply its compiler version. Checks use explicit +Ubuntu 24.04 Docker stages with GCC14 and LLVM19. The runner needs Git, Node20 for +checkout, Bash and a working Docker builder. + +| Setting | Kind | Value / purpose | +|---|---|---| +| HARBOR_HOST | Existing variable | registry.aeternalisgames.com; publishing is scoped to this host | +| HARBOR_PROJECT | Existing variable | aeternalis | +| HARBOR_USERNAME / HARBOR_PASSWORD | Existing secrets | Harbor push robot; values never belong in Git | +| HARBOR_REPOSITORY | Optional variable | Defaults to aevolution | +| CI_RUNNER_LABEL | Optional variable | Defaults to the verified ubuntu-22.04 label | +| UBUNTU_IMAGE | Optional variable | Defaults to ubuntu:24.04; prefer a reviewed base digest | + +Checks include Debug/Release CTest, format, clang-tidy, ASan/UBSan, a million +synthetic ticks and bounded seeded libFuzzer. TSan runs separately. No failure +is ignored. Windows MSVC checks use `tools/windows-check.ps1`. The image job waits +for checks and executes a restricted runtime smoke test. Only main push/manual +runs publish, using a temporary Docker credential directory. + +Published tags use `sha--run--` to distinguish rebuilds. +This replaces the original commit-only tag convention. The job prints the +registry digest in its logs/summary. GitOps references the digest, never latest. +CI does not receive cluster credentials or automatically commit/sync GitOps. +Use isolated runners for untrusted pull requests; Docker access is privileged. + +## Local container checks ```sh -docker build --file deploy/docker/Dockerfile --tag aeternalis-evo:dev . +docker build --progress=plain -f deploy/docker/Dockerfile --target ci-checks . +docker build --progress=plain -f deploy/docker/Dockerfile --target ci-tsan . +docker build -f deploy/docker/Dockerfile -t 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 + --seed 123456 --entities 8 --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. +Runtime UID/GID is 10001; JSON goes to stdout. Builder package versions are in +`/usr/share/evo/build-packages.txt`; file output needs an explicit writable mount. +Source COPY operations exclude local chat logs, `.git` and credentials. Ubuntu +security packages move: production promotion still needs pinned provenance, +SBOM, scan/signature and retention. TSan on this sequential proof validates +instrumentation, not future concurrency. Record actual results in VALIDATION.md. -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. +## Argo settings and promotion -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). +Reuse the maintainer's application once its GitOps source is confirmed. For an +application watching this repository directly: -Harbor, Argo CD, Argo Workflows and Kubernetes follow +| Field | Value | +|---|---| +| Repository | https://git.aeternalisgames.com/dingo/AEvolution.git | +| Revision | main; review the resolved commit before syncing | +| Path | deploy/kubernetes/dev | +| Destination namespace | evolution-dev | +| Project | aevolution-dev, or an equivalently restricted project | +| Sync | Manual full sync; no automated prune/self-heal | + +Bootstrap examples in `deploy/argocd/*.yaml.example` are outside the workload +path. Replace the Argo namespace and registered cluster API URL, or use its UI. +Create evolution-dev separately. Configure Argo's private Git read credential +and a **pull-only** harbor-pull Secret in that namespace. Neither is the CI push +credential. The project allows only Job, ServiceAccount and NetworkPolicy there. + +Before syncing: + +1. Wait for successful checks and publication of the intended commit. +2. Replace the digest marker in `deploy/kubernetes/dev/kustomization.yaml` with + the published `sha256:<64 hex>` digest, review and commit it. The marker is + intentionally invalid and cannot launch an accidental fallback image. +3. Run `kubectl kustomize deploy/kubernetes/dev`. Check exactly three resources, + all in evolution-dev, the selected digest and no unresolved marker. +4. Full-sync the dev app. Selective sync skips hooks. +5. Verify Job aevolution-dev-proof completes with exit 0 and JSON + `replay_verified: true`, seed 123456, 8 entities and 100000 ticks. Record the + digest, source commit and result in the validation report. + +The Job has a five-minute deadline, no retries, token mount, network access or +writable root, and bounded resources. NetworkPolicy requires CNI enforcement; +node-level image pulling is separate from pod egress. No Service, port, PVC or +persistent world is included. BeforeHookCreation retains the latest Job until +the next full sync replaces it; collect logs first. Kubernetes can execute a Job +more than once: harmless here, not an exactly-once persistence mechanism. + +World0 is unchanged. Persistent deployment follows [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. +and [operations gates](../docs/infrastructure/OPERATIONS.md). diff --git a/deploy/argocd/application.yaml.example b/deploy/argocd/application.yaml.example new file mode 100644 index 0000000..a3673cb --- /dev/null +++ b/deploy/argocd/application.yaml.example @@ -0,0 +1,18 @@ +apiVersion: argoproj.io/v1alpha1 +kind: Application +metadata: + name: aevolution-dev + namespace: REPLACE_ARGO_NAMESPACE +spec: + project: aevolution-dev + source: + repoURL: https://git.aeternalisgames.com/dingo/AEvolution.git + targetRevision: main + path: deploy/kubernetes/dev + destination: + server: REPLACE_REGISTERED_CLUSTER_API_URL + namespace: evolution-dev + syncPolicy: + syncOptions: + - FailOnSharedResource=true +# Manual full sync; no automated policy or cascade deletion finalizer. diff --git a/deploy/argocd/namespace.yaml.example b/deploy/argocd/namespace.yaml.example new file mode 100644 index 0000000..2eca71a --- /dev/null +++ b/deploy/argocd/namespace.yaml.example @@ -0,0 +1,5 @@ +apiVersion: v1 +kind: Namespace +metadata: + name: evolution-dev +# Bootstrap separately. Do not include this in the workload Application source. diff --git a/deploy/argocd/project.yaml.example b/deploy/argocd/project.yaml.example new file mode 100644 index 0000000..f716b64 --- /dev/null +++ b/deploy/argocd/project.yaml.example @@ -0,0 +1,20 @@ +apiVersion: argoproj.io/v1alpha1 +kind: AppProject +metadata: + name: aevolution-dev + namespace: REPLACE_ARGO_NAMESPACE +spec: + description: Bounded Aeternalis foundation proof in evolution-dev + sourceRepos: + - https://git.aeternalisgames.com/dingo/AEvolution.git + destinations: + - server: REPLACE_REGISTERED_CLUSTER_API_URL + namespace: evolution-dev + clusterResourceWhitelist: [] + namespaceResourceWhitelist: + - group: "" + kind: ServiceAccount + - group: batch + kind: Job + - group: networking.k8s.io + kind: NetworkPolicy diff --git a/deploy/docker/Dockerfile b/deploy/docker/Dockerfile index a2bd49a..b597eba 100644 --- a/deploy/docker/Dockerfile +++ b/deploy/docker/Dockerfile @@ -1,12 +1,33 @@ # Development bootstrap tag. Promotion requires an approved immutable digest. ARG UBUNTU_IMAGE=ubuntu:24.04 -FROM ${UBUNTU_IMAGE} AS build +FROM ${UBUNTU_IMAGE} AS toolchain 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 . . +COPY CMakeLists.txt CMakePresets.json .clang-format .clang-tidy ./ +COPY cmake/ cmake/ +COPY include/ include/ +COPY src/ src/ +COPY apps/ apps/ +COPY tests/ tests/ +COPY tools/ tools/ + +FROM toolchain AS ci-toolchain +RUN apt-get update \ + && apt-get install -y --no-install-recommends clang-19 clang-format-19 \ + clang-tidy-19 libclang-rt-19-dev \ + && rm -rf /var/lib/apt/lists/* +RUN dpkg-query -W + +FROM ci-toolchain AS ci-checks +RUN bash tools/ci/linux-check.sh checks + +FROM ci-toolchain AS ci-tsan +RUN bash tools/ci/linux-check.sh tsan + +FROM toolchain AS build 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 \ diff --git a/deploy/kubernetes/dev/job.yaml b/deploy/kubernetes/dev/job.yaml new file mode 100644 index 0000000..ffee97b --- /dev/null +++ b/deploy/kubernetes/dev/job.yaml @@ -0,0 +1,44 @@ +apiVersion: batch/v1 +kind: Job +metadata: + name: aevolution-dev-proof + annotations: + argocd.argoproj.io/hook: Sync + argocd.argoproj.io/hook-delete-policy: BeforeHookCreation + argocd.argoproj.io/sync-wave: "0" +spec: + completions: 1 + parallelism: 1 + backoffLimit: 0 + activeDeadlineSeconds: 300 + template: + metadata: + labels: + app.kubernetes.io/name: aevolution-proof + spec: + serviceAccountName: aevolution-proof + automountServiceAccountToken: false + restartPolicy: Never + securityContext: + runAsNonRoot: true + runAsUser: 10001 + runAsGroup: 10001 + seccompProfile: + type: RuntimeDefault + containers: + - name: evo-sim + image: evo-sim + imagePullPolicy: IfNotPresent + args: ["--seed", "123456", "--entities", "8", "--ticks", "100000", "--verify-replay"] + securityContext: + allowPrivilegeEscalation: false + readOnlyRootFilesystem: true + capabilities: + drop: [ALL] + resources: + requests: + cpu: 100m + memory: 64Mi + limits: + cpu: "1" + memory: 256Mi diff --git a/deploy/kubernetes/dev/kustomization.yaml b/deploy/kubernetes/dev/kustomization.yaml new file mode 100644 index 0000000..a27dfbe --- /dev/null +++ b/deploy/kubernetes/dev/kustomization.yaml @@ -0,0 +1,11 @@ +apiVersion: kustomize.config.k8s.io/v1beta1 +kind: Kustomization +namespace: evolution-dev +resources: + - serviceaccount.yaml + - networkpolicy.yaml + - job.yaml +images: + - name: evo-sim + newName: registry.aeternalisgames.com/aeternalis/aevolution + digest: sha256:REPLACE_WITH_PUBLISHED_64_HEX_DIGEST diff --git a/deploy/kubernetes/dev/networkpolicy.yaml b/deploy/kubernetes/dev/networkpolicy.yaml new file mode 100644 index 0000000..7f1b63f --- /dev/null +++ b/deploy/kubernetes/dev/networkpolicy.yaml @@ -0,0 +1,13 @@ +apiVersion: networking.k8s.io/v1 +kind: NetworkPolicy +metadata: + name: aevolution-proof-deny-all + annotations: + argocd.argoproj.io/sync-wave: "-1" +spec: + podSelector: + matchLabels: + app.kubernetes.io/name: aevolution-proof + policyTypes: [Ingress, Egress] + ingress: [] + egress: [] diff --git a/deploy/kubernetes/dev/serviceaccount.yaml b/deploy/kubernetes/dev/serviceaccount.yaml new file mode 100644 index 0000000..155cec8 --- /dev/null +++ b/deploy/kubernetes/dev/serviceaccount.yaml @@ -0,0 +1,10 @@ +apiVersion: v1 +kind: ServiceAccount +metadata: + name: aevolution-proof + annotations: + argocd.argoproj.io/sync-wave: "-1" +automountServiceAccountToken: false +# Create this pull-only Secret separately in evolution-dev; never commit credentials. +imagePullSecrets: + - name: harbor-pull diff --git a/docs/ROADMAP.md b/docs/ROADMAP.md index 843890d..0413946 100644 --- a/docs/ROADMAP.md +++ b/docs/ROADMAP.md @@ -16,7 +16,7 @@ independent reviews; dependent tasks begin after their contracts are settled. | 0.4 Add owned-code checks | .clang-format, .clang-tidy, CMake presets | 0.3 | Format and static analysis runnable; warnings-as-errors scoped | Run format/tidy and record tool versions | Noisy analysis can cause ignored warnings | | 0.5 Add test and measurement harness | tests/, benchmarks/, core/telemetry | 0.3 | Release-safe checks, CTest, benchmark metadata and bounded structured logs | Deliberate invalid data fails; benchmark completes | Home-grown harness grows into framework | | 0.6 Add sanitizers and fuzz entry | CMake options, tests/fuzz/ | 0.4–0.5 | ASan/UBSan, separate TSan configs, bounded codec fuzz target | Instrumented test jobs; fuzz smoke where toolchain supports it | Platform sanitizer gaps | -| 0.7 Container and CI skeleton | deploy/docker/, .github/workflows/, tools/ | 0.3–0.6 | Build/test/analyze/container workflow; no implicit cluster deployment | Local checks; container job when daemon available | Unpinned images, CI mistaken for executed validation | +| 0.7 Container and CI skeleton | deploy/docker/, .gitea/workflows/, tools/ | 0.3–0.6 | Build/test/analyze/container workflow; stateless dev Job via reviewed GitOps | Local checks; Gitea container jobs; dev Job evidence separately | Unpinned images, CI mistaken for executed validation | | 0.8 Close foundation increment | README.md, engineering/VALIDATION.md | 0.1–0.7 | Exact tested/untested status, commands and next task recorded | Reproduce from clean build | Claiming production readiness prematurely | ## M1 — Universal simulation kernel diff --git a/docs/STATUS.md b/docs/STATUS.md new file mode 100644 index 0000000..afd50bc --- /dev/null +++ b/docs/STATUS.md @@ -0,0 +1,58 @@ +# Project status and next steps + +Updated 2026-09-19. The repository contains an engineering foundation and a +deterministic headless proof. It does not yet contain cellular gameplay or a +persistent simulation server. The founding vision remains unchanged. + +## Completed implementation + +- Vision, architectural pillars, risks, open-question register, architecture + diagrams, biological contracts, engineering constitution and 20 ADRs. + Proposed/deferred choices remain distinct from accepted proof decisions. +- M0–M4 task breakdowns with dependencies, acceptance evidence and risks, + plus M5–M14 gates in [ROADMAP.md](ROADMAP.md). +- C++23 CMake/Ninja library and CLI with no graphics, networking, database or + Kubernetes dependency. Versioned fixed ticks, stable entity IDs, component + lifecycle and explicit per-entity seeded randomness. +- Bounded canonical snapshots and restore, plus replay verification. An independent + reference fingerprint and Release-active tests cover lifecycle, malformed data, + overflow, seeded properties and CLI save/load. +- Formatter, static analysis, sanitizer presets, codec fuzz entry point, benchmark, + structured host logging and metrics output. Benchmark compiler metadata now + resets numeric formatting after printing its hexadecimal state hash. + +## Delivery and verification + +Git remote is `https://git.aeternalisgames.com/dingo/AEvolution.git`. The maintainer +added a working Gitea/Harbor workflow; run 1399 on `8ab48d3` successfully verified +and published. The foundation update extends that single workflow with Linux +analysis/sanitizers/fuzzing and runtime smoke verification. Images target +`registry.aeternalisgames.com/aeternalis/aevolution`. + +The maintainer reports Argo is configured. This workspace has no kubeconfig; +the app/source mapping and completed dev Job are not yet independently verified. +The repository supplies a restricted dev Job and bootstrap examples; image +publication does not demonstrate a Kubernetes rollout or world recovery. + +See [VALIDATION.md](engineering/VALIDATION.md) for actual commands/results and +[deploy/README.md](../deploy/README.md) for image promotion and application setup. +Local `INITIAL_BRIEF.md` and `OpenAI_ChatLog.md` are maintainer-provided untracked +material and are not automatically included in commits. + +## Next reviewable increments, in order + +| Priority | Work | Completion evidence | +|---|---|---| +| 1 | Close M0 delivery: run expanded Gitea checks, select a successful image digest and verify the existing dev Argo mapping | Green checks, digest recorded, dev Job Complete with replay_verified=true; no World0 changes | +| 2 | M1.5 ECS evaluation: compare the bounded store with a pinned mature ECS in an isolated benchmark using sparse biological capability workloads | Iteration/lifecycle/memory/serialization measurements, license review and updated ADR-0005; no automatic adoption | +| 3 | M1.6 scheduler/input contract: ratify phase order and command admission before implementing a sequential scheduler | Stable input order, one writer, deterministic merges and replay equivalence | +| 4 | M1.7 local spatial contract | Neighborhood queries checked against brute force, wrap/boundary/unit tests and measured workload | +| 5 | M2.1 energy/matter ledger | Agreed units/ranges, atomic transfers, nonnegative balances and conservation tests before organisms | +| 6 | M2.2–2.6 first headless energy cycle | Explicit source → producer → consumer → death → decomposition → nutrients; seeded million-tick ledger evidence | + +Before biology, resolve the relevant heredity and energetic contracts rather +than treating proof particles as organisms. Exact game tick rate, NPC mutation, +logout treatment, species/extinction rules and multicellular transition remain +open decisions. Renderer/networking remain later milestones. Deployment +availability does not complete M7/M8: fenced ownership, durable outcomes, backup +restore and world-version migration require their own implementation/fault tests. diff --git a/docs/adr/0020-foundation-delivery.md b/docs/adr/0020-foundation-delivery.md new file mode 100644 index 0000000..b038b2c --- /dev/null +++ b/docs/adr/0020-foundation-delivery.md @@ -0,0 +1,74 @@ +# ADR-0020: Gitea delivery and a manual dev verification Job + +## Status + +Accepted for the foundation delivery requested by the maintainer. This does not +adopt a persistent server deployment. Registry/runner placeholders are explicitly +permitted; the maintainer will create the Argo application manually. + +## Context + +The repository is hosted at git.aeternalisgames.com/dingo/AEvolution. Harbor is +registry.aeternalisgames.com, project aeternalis, repository aevolution. The +maintainer's successful run 1399 confirms the ubuntu-22.04 runner label and robot +secret names. The Argo source is not yet inspected. The executable is a finite headless +proof; it has neither a serving loop nor durable world ownership. + +## Decision + +Use native Gitea Actions with a configurable Linux Docker runner. Build Linux +checks in explicit container stages: GCC14 Debug/Release, LLVM19 formatting and +analysis, ASan/UBSan, seeded bounded fuzzing, and a separate TSan job. Keep the +existing Windows check script for the verified MSVC development workflow. + +After checks, build and smoke-test the runtime image. Publish from main only when +the Harbor project is configured, using separately scoped robot secrets. Emit a +unique commit/run tag and the registry digest. No cluster or Argo credentials go +into CI. Review and commit the digest to dev Kustomize before manual Argo sync. + +Deploy the proof as a finite, stateless Sync-hook Job in evolution-dev. No Service, +PVC, database, region process, scheduled run or World0 resource is introduced. +Keep bootstrap Argo/project/namespace templates outside the workload source path. +An unresolved image marker deliberately cannot run. The operator must replace it. + +## Alternatives Considered + +GitHub workflows would target the wrong forge. A Deployment would restart a +successful finite process. A CronJob introduces unrequested recurring work. +Cluster build privileges and Argo credentials are unnecessary for this manual +delivery path. Host-installed compilers are less explicit than container stages. +Argo Workflows remains the later orchestrator for soak/clone/migration jobs. + +## Benefits + +One executable crosses build, container and Kubernetes boundaries without adding +simulation dependencies. Publishing and deployment remain independently reviewable. +The application needs no runtime network access or persistent state. + +## Costs + +The existing Linux Docker runner and Harbor project/robots are reused. +Container checks consume builder cache and require trusted package repositories. +Dev bootstrap uses an Ubuntu tag; distro package versions are captured, not fully +reproducible. Production promotion requires a reviewed base digest, retained SBOM, +scan/signature and package provenance; this scaffold is not that release gate. + +## Risks + +Docker access is privileged: use isolated runners for untrusted contributions and +never grant them production credentials. TSan may expose host-runtime limitations; +do not bypass a failed job or weaken host security to conceal them. Jobs can run +more than once; this is safe only because the proof has no external side effects. +Manual sync is an operational action even though the workload is bounded. + +## Consequences + +The latest completed hook stays available until the next full sync replaces it. +Collect logs first; selective sync skips hooks. No automated sync, prune, cascade +finalizer or namespace-creation option is enabled. Persistent deployment decisions +remain under ADR-0018 and M7/M8 gates. A workflow existing is not evidence it ran. + +Sources: [Gitea variables](https://docs.gitea.com/usage/actions/actions-variables/), +[Gitea runner](https://docs.gitea.com/runner/), +[Argo hooks](https://argo-cd.readthedocs.io/en/stable/user-guide/resource_hooks/), +[Kubernetes Jobs](https://kubernetes.io/docs/concepts/workloads/controllers/job/). diff --git a/docs/adr/README.md b/docs/adr/README.md index 2409201..0c6cf3a 100644 --- a/docs/adr/README.md +++ b/docs/adr/README.md @@ -11,7 +11,8 @@ Proof choices do not silently settle gameplay or production infrastructure. Records 0001–0015 cover language, build, dependencies, tests/benchmarks, ECS, ticks, randomness, serialization, units, errors, threads, logging, PostgreSQL, messaging and metrics. 0016–0019 cover durability/ownership, networking/security, -infrastructure and voxels. Each record has the eight required sections. +infrastructure and voxels. 0020 scopes Gitea delivery and the stateless dev Job. +Each record has the eight required sections. Every dependency adoption records exact version/commit and integrity hash, transitive license obligations, maintenance/security review, owner and removal diff --git a/docs/architecture/INFRASTRUCTURE_ARCHITECTURE.md b/docs/architecture/INFRASTRUCTURE_ARCHITECTURE.md index 82413dc..65bc03e 100644 --- a/docs/architecture/INFRASTRUCTURE_ARCHITECTURE.md +++ b/docs/architecture/INFRASTRUCTURE_ARCHITECTURE.md @@ -100,5 +100,7 @@ S3 semantics, durability and independent restore. [Official MinIO repository](ht Before M8: validate inventory, storage class/reclaim behavior, DNS/TLS/ingress, Harbor/Argo integration, least privilege, resource budgets and off-host recovery. -Then kill a region pod and demonstrate automatic fenced restore. No manifests -with fabricated endpoints, secrets or storage classes are deployed in M0. +Then kill a region pod and demonstrate automatic fenced restore. ADR-0020 adds +a stateless M0 verification Job in evolution-dev through the existing Gitea/Harbor +setup. It is not a persistent region or evidence of the M8 recovery gate. +Templates with unresolved destination/image markers must not be synced. diff --git a/docs/engineering/VALIDATION.md b/docs/engineering/VALIDATION.md index 28fd733..0ea233c 100644 --- a/docs/engineering/VALIDATION.md +++ b/docs/engineering/VALIDATION.md @@ -1,71 +1,64 @@ # Validation report -Status: **no validation run has been recorded for this tree.** Nothing in this -document reports an executed check. Every entry below is a required check with -its exact command and an explicit not-run marker, per -[testing strategy](TEST_STRATEGY.md): unexecuted configurations are not -validation. +Recorded 2026-09-19. Native checks apply to base commit `8ab48d3` plus the +foundation-delivery working changes committed with this report. Simulation rules +and snapshot format remain version 1; the only C++ change is benchmark metadata. +Results below distinguish executed checks from pending Linux/cluster gates. -This file is the record required by ROADMAP task 0.8 and by AGENTS.md. Replace -the status markers with real results, exact tool versions and observed -limitations at the end of each foundation change. Do not mark a row passed -unless that command actually ran on the commit being recorded. +## Tools and host -## Toolchain actually used +- Windows NT 10.0.26200, AMD Ryzen 7 9800X3D, 8 cores / 16 logical processors. +- MSVC 19.44.35217.0, CMake 3.31.6-msvc6, Ninja 1.12.1. +- clang-format and clang-tidy 19.1.5 (Visual Studio LLVM tools). +- kubectl 1.31.4 / Kustomize 5.4.2 for offline manifest rendering. -| Item | Required | Recorded version | -|---|---|---| -| CMake | 3.28+ | Not recorded | -| Generator | Ninja | Not recorded | -| Linux compiler | GCC 14 (initial CI target) | Not recorded | -| Windows compiler | MSVC 19.44+ | Not recorded | -| clang-format / clang-tidy | major 19 baseline | Not recorded | -| Host OS / CPU | — | Not recorded | -| Commit under test | — | Not recorded | +## Executed native checks -## Check status +| Command | Observed result | +|---|---| +| `./tools/windows-check.ps1 -Preset debug -Action check` | Configure/build passed; 5/5 CTests passed | +| `./tools/windows-check.ps1 -Preset release -Action check` | Configure/build passed; 5/5 CTests passed under NDEBUG | +| `./tools/windows-check.ps1 -Preset analysis -Action check` | clang-tidy/warnings-as-errors build passed; 5/5 CTests passed | +| `./tools/windows-check.ps1 -Preset asan -Action check` | MSVC AddressSanitizer build passed; 5/5 CTests passed; this is NOT UBSan | +| `./tools/windows-check.ps1 -Preset debug -Action format` | Passed with clang-format 19; repeated twice in one shell after helper fix | +| `./build/release/evo-sim --seed 123456 --entities 8 --ticks 1000000 --verify-replay` | Exit 0; replay_verified=true; hash fab22c2e8ae1c379 | +| `./build/release/evo-benchmark` | Exit 0; MSVC 1944 Release, seed 123456, 10000 entities, 1000 ticks, 0.0210666 seconds, hash 3bad6db1612cbd1 | +| Git Bash `bash -n tools/ci/linux-check.sh` and `bash -n tools/ci/publish-image.sh` | Syntax checks passed; no Linux execution implied | +| `kubectl kustomize deploy/kubernetes/dev` | Rendered Job, ServiceAccount and NetworkPolicy in evolution-dev; image marker intentionally unresolved | -| Check | Command | Status | -|---|---|---| -| Debug configure | `cmake --preset debug` | Not run | -| Debug build | `cmake --build --preset debug` | Not run | -| Debug tests | `ctest --preset debug` | Not run | -| Replay verification | `evo-sim --seed 123456 --entities 8 --ticks 1000 --verify-replay` | Not run | -| Save/load continuation | `evo-sim ... --save state.evo` then `--load state.evo` | Not run | -| Format check | `cmake --build --preset debug --target format-check` | Not run | -| clang-tidy analysis | `cmake --preset analysis && cmake --build --preset analysis` | Not run | -| ASan/UBSan | `cmake --preset asan && cmake --build --preset asan && ctest --preset asan` | Not run | -| TSan | `cmake --preset tsan && cmake --build --preset tsan && ctest --preset tsan` | Not run | -| Release build and tests | `cmake --preset release && cmake --build --preset release && ctest --preset release` | Not run | -| Benchmark | `./build/release/evo-benchmark` | Not run | -| Snapshot fuzz (optional) | Clang libFuzzer snapshot restore target | Not run | -| Container build | `deploy/docker/Dockerfile` | Not run | +CTest covers the independently frozen 1000-tick fingerprint d61ad5bf0c928c76, +seeded replay properties, malformed/semantic snapshot rejection, entity lifecycle, +capacity/overflow, telemetry and CLI file continuation/alias protection. The +expected-failure harness confirms tests remain active in Release. -## Expected reference fixture +The benchmark is a single uncontrolled wall-clock observation, not a performance +threshold or an MMO capacity estimate. Its initial compiler output accidentally +used hexadecimal; the stream now returns to decimal and reports MSVC 1944. -Documented in [testing strategy](TEST_STRATEGY.md), **not verified here**: seed -123456, 8 particles created at (0,0), 1,000 ticks, rules/format 1 yields -canonical payload FNV-1a `d61ad5bf0c928c76`. When recording a real run, state -whether the observed hash matched this value. +## Gitea evidence -## Known scope limits +The maintainer's [run 1399](https://git.aeternalisgames.com/dingo/AEvolution/actions/runs/1399) +on `8ab48d3a5639121693f5881b600482e870b49f05` completed successfully. API job records +confirm verify (configure/build/CTest) and publish (Docker build/push) succeeded +on runner theraborn-runners-runner-0, label ubuntu-22.04. This is evidence for the +original workflow, not the expanded sanitizer/analysis jobs added in this change. +Exact Linux tool versions must come from the expanded job logs; a runner label +is not a compiler version. -These are absent from the tree by design, not failures, and no gate below may -be reported as passing: +## Limitations and next gates -- No biological regression evidence. Synthetic particles are not an ecosystem; - this category begins at M2. -- No network, protocol or load evidence. No network service exists. -- No disaster recovery or backup restore evidence. No persistent service or - database exists. -- No Kubernetes deployment is running. `deploy/` is scaffold only. -- Benchmarks carry no portable wall-clock threshold; record seed, count, ticks, - time and compiler instead. +- Local Docker Desktop has no running Linux engine. Container checks must run on + the configured Gitea runner; no local container success is claimed. +- Expanded Linux GCC14/Clang19, ASan/UBSan, TSan and libFuzzer jobs are pending a + pushed workflow run. A configured job is not a passing check. +- Sandbox process restrictions stalled native Ninja and blocked Git Bash signal + pipes. Those attempts were stopped; checks reran successfully outside sandbox. +- Repeated VsDevCmd initialization grew PATH beyond cmd's limit. The helper now + reuses the matching x64 environment and deduplicates PATH; repeated checks pass. +- The maintainer reports Argo setup, but this workspace has no Kubernetes context. + No dev Job completion or cluster admission result is recorded yet. +- No biology, network/load, durable server recovery or backup restore exists. + Those remain M2, M7/M8 and later gates, not failing or passing foundation tests. -## Recording procedure - -For each foundation change, record: the commit hash, exact tool versions, each -command as invoked, its observed result, and any environmental limitation that -prevented a check from running (missing compiler, absent container daemon, -unavailable sanitizer). An environmental limit is recorded as a limit, never -silently omitted and never reported as a pass. +Update this report with run URL, tested commit, image digest and Job result when +those checks execute. Never overwrite a golden merely to make CI pass. diff --git a/tests/benchmarks/simulation_benchmark.cpp b/tests/benchmarks/simulation_benchmark.cpp index 0909666..e484257 100644 --- a/tests/benchmarks/simulation_benchmark.cpp +++ b/tests/benchmarks/simulation_benchmark.cpp @@ -26,7 +26,7 @@ int main() try { std::cout << "{\"benchmark\":\"synthetic_tick\",\"seed\":" << seed << ",\"entities\":" << count << ",\"ticks\":" << ticks << ",\"seconds\":" << elapsed.count() << ",\"state_hash\":\"" << std::hex - << world.state_hash() << "\",\"compiler\":\"" + << world.state_hash() << std::dec << "\",\"compiler\":\"" #if defined(__clang__) << "Clang " << __clang_version__ #elif defined(_MSC_VER) diff --git a/tools/ci/linux-check.sh b/tools/ci/linux-check.sh new file mode 100644 index 0000000..79b1797 --- /dev/null +++ b/tools/ci/linux-check.sh @@ -0,0 +1,49 @@ +#!/usr/bin/env bash +set -euo pipefail + +# Run inside the Dockerfile's ci-toolchain stage, not an arbitrary host shell. +suite="${1:?Expected checks or tsan}" +cmake --version +g++-14 --version +clang++-19 --version +clang-format-19 --version +clang-tidy-19 --version +uname -a + +check_preset() { + local preset="$1" + local compiler="$2" + cmake --preset "$preset" "-DCMAKE_CXX_COMPILER=$compiler" + cmake --build --preset "$preset" --parallel 2 + ctest --preset "$preset" --no-tests=error --timeout 120 +} + +case "$suite" in + checks) + check_preset debug g++-14 + cmake --build --preset debug --target format-check + check_preset release g++-14 + check_preset analysis clang++-19 + check_preset asan clang++-19 + ./build/release/evo-benchmark + ./build/release/evo-sim --seed 123456 --entities 8 --ticks 1000000 --verify-replay + + cmake --preset debug -B build/fuzz -DCMAKE_CXX_COMPILER=clang++-19 \ + -DEVO_BUILD_FUZZER=ON + cmake --build build/fuzz --target evo-snapshot-fuzz --parallel 2 + mkdir -p build/fuzz/corpus + ./build/release/evo-sim --seed 0 --entities 0 --ticks 0 \ + --save build/fuzz/corpus/empty.evo + ./build/release/evo-sim --seed 123456 --entities 8 --ticks 1000 \ + --save build/fuzz/corpus/eight.evo + ./build/fuzz/evo-snapshot-fuzz build/fuzz/corpus -seed=123456 \ + -runs=10000 -max_len=65536 -timeout=10 -rss_limit_mb=1024 + ;; + tsan) + check_preset tsan clang++-19 + ;; + *) + echo 'Expected checks or tsan' >&2 + exit 2 + ;; +esac diff --git a/tools/ci/publish-image.sh b/tools/ci/publish-image.sh new file mode 100644 index 0000000..8e8ab18 --- /dev/null +++ b/tools/ci/publish-image.sh @@ -0,0 +1,34 @@ +#!/usr/bin/env bash +set -euo pipefail + +: "${HARBOR_USERNAME:?Set the HARBOR_USERNAME repository secret}" +: "${HARBOR_PASSWORD:?Set the HARBOR_PASSWORD repository secret}" +: "${HARBOR_PROJECT:?Set the HARBOR_PROJECT repository variable}" +: "${HARBOR_REPOSITORY:?Set HARBOR_REPOSITORY or use evo-sim}" +: "${RUNNER_TEMP:?This script runs in Gitea Actions}" + +if [[ ! "$HARBOR_PROJECT" =~ ^[a-z0-9][a-z0-9_-]*$ ]] || + [[ ! "$HARBOR_REPOSITORY" =~ ^[a-z0-9][a-z0-9._-]*$ ]]; then + echo 'Harbor project/repository must be single lowercase path segments.' >&2 + exit 2 +fi + +# Never replace a shared runner's Docker credentials. This directory is ours alone. +export DOCKER_CONFIG +DOCKER_CONFIG="$(mktemp -d "$RUNNER_TEMP/aevolution-docker.XXXXXX")" +trap 'rm -rf -- "$DOCKER_CONFIG"' EXIT +printf '%s' "$HARBOR_PASSWORD" | docker login registry.aeternalisgames.com \ + --username "$HARBOR_USERNAME" --password-stdin +source_image="aevolution-proof:${GITHUB_SHA}-${GITHUB_RUN_ID}-${GITHUB_RUN_ATTEMPT}" +target_image="registry.aeternalisgames.com/${HARBOR_PROJECT}/${HARBOR_REPOSITORY}:sha-${GITHUB_SHA}-run-${GITHUB_RUN_NUMBER}-${GITHUB_RUN_ATTEMPT}" +docker tag "$source_image" "$target_image" +docker push "$target_image" +repository="registry.aeternalisgames.com/${HARBOR_PROJECT}/${HARBOR_REPOSITORY}" +digest="$(docker image inspect --format '{{range .RepoDigests}}{{println .}}{{end}}' "$target_image" | grep -F "$repository@sha256:")" +if [[ ! "$digest" =~ ^registry\.aeternalisgames\.com/.+@sha256:[a-f0-9]{64}$ ]]; then + echo 'Registry digest was not resolved; do not promote this image.' >&2 + exit 1 +fi +printf 'Published commit %s as %s\nDigest: %s\n' "$GITHUB_SHA" "$target_image" "$digest" +printf 'Commit: `%s`\n\nImage: `%s`\n\nDigest: `%s`\n' \ + "$GITHUB_SHA" "$target_image" "$digest" >> "$GITHUB_STEP_SUMMARY" diff --git a/tools/windows-check.ps1 b/tools/windows-check.ps1 index 5d8ac3d..2fb3590 100644 --- a/tools/windows-check.ps1 +++ b/tools/windows-check.ps1 @@ -12,17 +12,20 @@ $visualStudioRoot = & $vswherePath -latest -version '[17.0,18.0)' -products '*' if (!$visualStudioRoot) { throw 'Visual Studio 2022 C++ build tools are required' } $developerScript = Join-Path $visualStudioRoot 'Common7\Tools\VsDevCmd.bat' # cmd only initializes compiler environment; all filesystem work stays in PowerShell/CMake. -$environmentCommand = 'call "{0}" -no_logo -arch=x64 -host_arch=x64 && set' -f $developerScript -$environmentLines = & $env:ComSpec /d /c $environmentCommand -if ($LASTEXITCODE -ne 0) { throw 'Visual Studio environment initialization failed' } -foreach ($line in $environmentLines) { - if ($line -match '^([^=]+)=(.*)$') { - [Environment]::SetEnvironmentVariable($matches[1], $matches[2], 'Process') +$configuredRoot = if ($env:VSINSTALLDIR) { $env:VSINSTALLDIR.TrimEnd('\') } else { '' } +if (!$env:VSCMD_VER -or $env:VSCMD_ARG_TGT_ARCH -ne 'x64' -or $configuredRoot -ne $visualStudioRoot.TrimEnd('\')) { + $environmentCommand = 'call "{0}" -no_logo -arch=x64 -host_arch=x64 && set' -f $developerScript + $environmentLines = & $env:ComSpec /d /c $environmentCommand + if ($LASTEXITCODE -ne 0) { throw 'Visual Studio environment initialization failed' } + foreach ($line in $environmentLines) { + if ($line -match '^([^=]+)=(.*)$') { + [Environment]::SetEnvironmentVariable($matches[1], $matches[2], 'Process') + } } } $cmakeRoot = Join-Path $visualStudioRoot 'Common7\IDE\CommonExtensions\Microsoft\CMake' $llvmRoot = Join-Path $visualStudioRoot 'VC\Tools\Llvm\x64\bin' -$env:Path = "$cmakeRoot\CMake\bin;$cmakeRoot\Ninja;$llvmRoot;$env:Path" +$env:Path = ((@("$cmakeRoot\CMake\bin", "$cmakeRoot\Ninja", $llvmRoot) + $env:Path.Split(';')) | Select-Object -Unique) -join ';' Push-Location -LiteralPath $repositoryRoot try { if ($Action -in @('configure', 'check')) {