kanea: Instructions file for Codex

AGENTS.md: Kanea

Guidance for AI agents (and humans) working in this repository. Read this before writing any code.

What this is

Kanea is a lightweight, single-binary container orchestration platform written in Go, "container orchestration in one binary." It runs services on containerd, networks them with its own eBPF datapath (nothing from the Kubernetes stack underneath, and since PRD v1.36 no Cilium either), terminates TLS with Let's Encrypt, and ships a React + shadcn/ui dashboard, an MCP server for AI agents, GitOps pipelines (kaniko), eBPF-driven autoscaling, and S3-backed state replication.

PRD.md is the north star. It is complete and internally consistent (v1.106). Every architectural decision, naming rule, milestone, and risk is specified there. When this file and the PRD disagree, the PRD wins, and the disagreement means one of them needs an amendment.

Current status

Every subsystem the PRD specifies is built and released. What is still owed before v1.0 is evidence rather than code: the real-hardware runs no test can stand in for are tracked, with dates, in docs/VALIDATION.md.

The decision record lives in docs/DECISIONS.md: the per-subsystem status table, the per-amendment "things a change is most likely to trip over" bullets, Deliberately not built, Known limits, and the spike log. Read that file's bullets for any area before changing it, and treat an apparent gap as a decision until that document says otherwise: several of the most tempting "fixes" in this codebase are listed there as refusals.

Recurring design rules

Cross-cutting patterns the decision record applies over and over. Each is one sentence here; the bullets in docs/DECISIONS.md carry the details and the history.

1. SpecHash discipline (the R23 lesson): a new Desired field needs omitempty and an explicit decision about whether it is hash material; a missing omitempty rolls every alloc on the node at upgrade, and pre-existing records must serialize byte-identically, pinned by test.
2. A record with an empty spec hash is adopted, never rolled - that is what stops a kanead upgrade from replacing every alloc on the node.
3. "No data" is never zero: absence and a measured zero lead to opposite decisions, in the time series, the evaluator, the exporter and the dashboard alike.
4. A control that cannot be enforced is refused, never silently dropped (R21).
5. Parse-time and apply-time checks are duplicated on purpose, with shared exported cores (CheckCapabilities, ParseEnvRef, ...) so the two paths cannot drift.
6. Client-side conversion never bakes in node-dependent values: toDesired runs in the CLI, MCP and the pipeline, so TLS modes, pull-policy defaults and their kin are resolved on the node.
7. Server-owned fields (Generation, PinnedImage) are carried over by handleApply, never reset by a client's apply.
8. Small constants are deliberately duplicated across package boundaries (CapabilityNone, ownershipRefusedBy, MaxBcryptCost) - matching them by import would point a dependency the wrong way; they are not DRY violations.
9. Attacker-chosen keys are never persisted, and every map keyed by one is bounded, with refusals counted: a cap nobody can see is indistinguishable from a leak.
10. Steady state writes nothing: an unchanged value is never rewritten, because a Store write is a CDC change and an S3 upload.
11. Anything added to a published snapshot must be added to its equality check, or it publishes exactly once and never again (the routesArePublished lesson).
12. A spec names a grant, never a path - GitOps deploys specs automatically, so a spec is an untrusted document and node-side config holds the mapping.
13. Config files come in two families and must not mix: the reload family (keep-last-good, content-fingerprinted - certificates, secret providers) and load-once kanea.hcl (absent is off, malformed is fatal).
14. Fail closed: a missing certificate, verifier or identity is a 503 or a drop, never open.
15. Every optional daemon dependency must be wired in cmd/kanea, pinned by tests that read the source - the recurring bug class is invisible in dev and fatal on the first real systemd node.