Files
aevolution/docs/adr/0020-foundation-delivery.md
T

99 lines
5.3 KiB
Markdown

# 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/).
### TSan test-container exception (2026-09-19)
Run 1400 demonstrated Clang19 failing before main because Docker's build sandbox
blocked personality(ADDR_NO_RANDOMIZE). Compile TSan in the image build, then run
CTest in a non-root, networkless, capability-free container with a read-only root
and bounded tmpfs test-output directories. No host ASLR/sysctl change and no
seccomp=unconfined or privileged container is used.
The CI profile generator downloads Moby's maintained Apache-2.0 default seccomp
profile at commit 245180c51918481c0525424b3ee025d2b435d46c and verifies SHA256
785b2429264afba4d594320337cb17f144f3c7d51585f9805eef72e28f4f9334. It adds exactly one
argument-constrained allow rule: personality(0x40000), PER_LINUX with
ADDR_NO_RANDOMIZE. This deliberately disables ASLR only for sanitizer processes
requiring a fixed shadow layout. All other default rules remain. The profile is
not part of the game image or Kubernetes runtime configuration. Review/removal
owner: foundation/toolchain maintainers when TSan no longer requires this call.
The tradeoff is a pinned upstream network fetch and profile maintenance, rather
than vendoring a large allowlist or permitting every syscall. Failed tests still
block publication.
Evidence: [Docker seccomp](https://docs.docker.com/engine/security/seccomp/),
[LLVM19 runtime](https://github.com/llvm/llvm-project/blob/llvmorg-19.1.1/compiler-rt/lib/tsan/rtl/tsan_platform_linux.cpp),
[pinned Moby profile](https://github.com/moby/profiles/blob/245180c51918481c0525424b3ee025d2b435d46c/seccomp/default.json).