caixa

Typed package + lifecycle primitive for the pleme-io substrate. Author surface is (defcaixa …); substrate-side renderers generate every cluster artifact mechanically. Cargo-shaped semantics

• Erlang/OTP-shaped lifecycles + Lunatic-shaped sandboxing + Unison-shaped content addressing — all unified under one typed authoring surface.

(defcaixa
  :nome      "hello-rio"
  :versao    "0.1.0"
  :kind      Servico
  :limits    ((:memory "64MiB") (:fuel 1000000) (:wall-clock "30s"))
  :behavior  ((:on-call "lib/handlers.lisp"))
  :servicos  ("servicos/hello-rio.computeunit.yaml"))

That's the whole authoring surface for a service. CI builds the wasm component, publishes the OCI image, tags the git ref. feira deploy --cluster rio --apply writes the cluster manifest, FluxCD reconciles, the operator deploys the pod. All typed; all generated.

What it is

caixa is a typed package primitive: every author-authored unit of compute on the substrate is a caixa, identified by a hash of its fully-resolved AST (lacre BLAKE3 closure), authored as a single tatara-lisp (defcaixa …) form, and rendered to whatever cluster shape the :kind selects:

• Biblioteca — a tatara-lisp library that other caixas (importar :caixa "name"). Rendered to (nothing — it's source).
• Binario — a locally-invokable CLI. Rendered to a nix-built binary.
• Servico — a long-running wasm component on the cluster. Rendered to: OCI image, K8s ComputeUnit CR, lareira-<nome> Helm chart.
• Supervisor — a typed parent of N child caixas with an Erlang/OTP-shaped restart strategy (OneForOne | OneForAll | RestForOne | SimpleOneForOne). Rendered to: hierarchical reconciliation by the wasm-operator.
• Aplicacao — a typed mesh of Servicos with WIT-typed inter- Servico contracts, mesh policies (timeouts, retries, mTLS, rate limits, circuit breakers), placement strategy (single-node / replicated / sharded), and external entry. Rendered to: programs.yaml fan-out + Cilium NetworkPolicies + K8s Gateway/HTTPRoute.
• Acao — a typed CI run: a :ci slot carrying a canteiro_types::CiRun (typed CI nodes + their dependency edges). Runs no code and owns no lib/exe/servicos surface. Rendered to: nothing yet — caixa-actions is validate-only at M0, decomposing the DAG and rejecting duplicate names, dangling deps, and cycles.

The runtime substrate (the wasm-engine + wasm-operator + lareira-tatara-stack on Kubernetes, with Cilium for identity-based mesh authorization) turns the rendered artifacts into running pods. All of it composes out of one typed authoring surface.

Why

Containers couple code with state, capabilities, identity, and deployment shape. caixa decouples all four: code is content-addressed (lacre BLAKE3), state is explicit (PVC / event-sourced log / KV), capabilities are typed tokens (:capabilities slot), identity is the lacre closure root (becomes Cilium SPIFFE ID directly). Every axis is named, typed, and independently composable.

The result: you can change one without disturbing the others. Hot upgrades become typed migrations (:upgrade-from), cross-cluster migration becomes a placement strategy change (:placement :replicated → :sharded), credential rotation requires no restart (:capabilities updated, downward API propagates). The pattern catalog in theory/RUNTIME-PATTERNS.md lists ~30 concrete patterns the substrate enables; the prior-art catalog in theory/INSPIRATIONS.md maps each one to the tradition (Erlang/OTP, Lunatic, Common Lisp, Smalltalk, Unison, Pony, Akka, Orleans, CRIU, eBPF) it absorbs.

Quickstart

# Scaffold a new Servico:
nix run github:pleme-io/caixa#feira -- init my-service --path .
$EDITOR caixa.lisp                    # set :kind, :descricao, :limits, etc.

# Author the K8s ComputeUnit runtime contract:
mkdir -p servicos
$EDITOR servicos/my-service.computeunit.yaml

# Wire CI (5 lines):
mkdir -p .github/workflows && cat > .github/workflows/release.yml <<'EOF'
name: release
on: { push: { branches: [main] }, workflow_dispatch: {} }
jobs:
  release:
    uses: pleme-io/substrate/.github/workflows/caixa-publish.yml@main
    secrets: inherit
    permissions: { contents: write, packages: write }
EOF

# Verify locally:
nix run github:pleme-io/cse-lint -- repo . --strict
nix run github:pleme-io/caixa#feira -- lint
nix run github:pleme-io/caixa#feira -- chart    # render lareira-my-service/

# Push:
git add caixa.lisp servicos/ .github/workflows/release.yml
git commit -m "init: my-service caixa Servico"
git push origin main

# CI builds the wasm component, publishes the OCI image, tags v0.1.0.
# To deploy:
nix run github:pleme-io/caixa#feira -- deploy --cluster rio --apply

For an Aplicacao composing N Servicos, swap :kind Servico for :kind Aplicacao and use feira app graph / feira app deploy instead. See examples/checkout-aplicacao/ for the canonical demonstration.

Repo layout

Documentation

Skills

• caixa-author (in blackmatter-pleme) — invoke when scaffolding any new caixa or composing an Aplicacao
• tatara-lisp-program (companion) — Lisp-source program internals (snapshot/receive-state, runtime cookbook patterns)

License

MIT — see LICENSE.