engenho

Pangea declares the supercontinent's shape; magma realizes it on cloud substrate; engenho is the engine that runs the land (terreno) — the typed, attested, Rust-native Kubernetes runtime.

One single-binary Kubernetes distribution, wire-compatible with kubectl / CRI / CNI / etcd-v3. Resource catalog mechanically generated from upstream OpenAPI v3 via kube-forge (Pillar 12 — generation over composition). Caixa M2/M3 slots reconciled natively without Helm intermediation. Secrets flow through cofre (no plaintext k8s Secrets). Compliance via tameshi + sekiban + kensa at admission. Pods can be OCI containers OR tatara tlisp programs via runwasi.

Status: Draft v1, pre-implementation (M0.0 in flight). The destination doc — pleme-io/theory/ENGENHO.md — is canonical; read it before touching anything load-bearing.

Repo docs:

• CLAUDE.md — agent-facing repo guide (architecture, build, anti-patterns)
• docs/M0-ROADMAP.md — local M0.0.1 → M0.0.4 path-down
• theory/ENGENHO.md — destination, typed surface, compatibility contract, phases
• theory/ENGENHO-LOCAL.md — the canonical operator local-dev path: kasou + kikai → working k8s cluster on every nix run .#rebuild

Quick start — the canonical path

The default first way to run engenho is via the kasou + kikai substrate: a typed kasou-managed Linux VM on macOS, running k3s today as a 1:1 wire-compat bridge → engenho once M0.4 ships. Full spec at theory/ENGENHO-LOCAL.md.

One Nix declaration on the operator's nodes/<host>/engenho-local.nix:

blackmatter.components.kubernetes.clusters.engenho-local = {
  enable    = true;
  vmMode    = "engenho";      # → routes to k3s today; native engenho M0.4+
  autoStart = true;
  cpus      = 4;
  memory    = 8192;
  diskSize  = "50G";
  apiPort   = 6443;
};

After nix run .#rebuild:

$ kubectl --context engenho-local get nodes
NAME            STATUS   ROLES                  AGE   VERSION
engenho-local   Ready    control-plane,master   2m    v1.34.5+k3s1

Build the binary itself

cargo build --workspace
cargo test  --workspace      # 12 unit + 5 manifest + 3 proptests (768 cases)

nix build                    # hermetic release build via substrate's
                             # rust-workspace-release-flake.nix
./result/bin/engenho         # M0.0 placeholder — prints destination pointer

Architecture (target — theory/ENGENHO.md §II.1)

engenho (workspace root)
├── engenho-types         — generated from upstream OpenAPI v3 via kube-forge.
│                           ONE #[derive(KubeResource, TataraDomain)] per kind.
├── engenho-datastore     — fjall-backed local KV + tonic-served etcd-v3 gRPC
│                           shim (Range / Txn / Watch / Lease) speaking
│                           revision-MVCC. openraft + fjall in HA tier (M1).
├── engenho-apiserver     — Axum + tonic + tokio + rustls. Authn (JWT-SA),
│                           RBAC, admission chain, OpenAPIv3 emitter,
│                           watch broadcast, SSA + JSONPatch + StrategicMergePatch.
├── engenho-controllers   — 18 controllers, ONE #[derive(TataraController)] per
│                           kind. Workqueue / leader election via shigoto + Lease.
├── engenho-scheduler     — 11-plugin default profile. Filter+Score+Reserve+Bind.
├── engenho-kubelet       — CRI gRPC client (tonic against containerd today,
│                           youki+oci-distribution direct M3+). Evented PLEG.
├── engenho-cni           — bridge + IPAM + portmap + loopback (M0). VXLAN (M0.5).
├── engenho-kubeproxy     — rustables/nftnl-rs netlink. Pure-Rust nftables only.
├── engenho-dns           — hickory-dns + KubernetesAuthority. Drop-in CoreDNS.
├── engenho-localpath     — local-path-provisioner-equivalent (M0).
├── engenho-ca            — rcgen built-in CA + CSR signer.
├── engenho-caixa         — native Caixa M2/M3 reconcilers (M1+).
├── engenho-mesh          — native Aplicacao mesh (M3+).
├── engenho-gateway       — pingora-based Gateway API (M3+).
├── engenho-attest        — tameshi integration; sekiban admission webhook.
├── engenho-cli           — kubectl-shaped operator CLI.
└── engenho               — Umbrella binary; one ~30-50 MB Rust binary.

Today (M0.0): engenho-types + engenho binary only.

Wire compatibility (theory/ENGENHO.md §III)

CNCF Certified Kubernetes target — M4

The certified-conformance e2e suite (~300 [Conformance] tests, zero skips) is the M4 release gate. Engenho aims to be the first non-Go distribution to pass.

Substrate integration (no escape hatches)

Phases (theory/ENGENHO.md §X)

License

MIT.