◉ · Fleet Control Plane · v0.1.0

“Claim a node, build, release.”

Arbitrated, cost-aware build capacity — the compute behind tetra-build.

Claim-Arbitration Control Plane for
Ephemeral BuildKit Fleets

forge-fleet provisions and arbitrates a pool of cloud build nodes — the 'fleet compute provider of tetra-build.

View Repository →Architecture Lifecycle Strategies Running it

Axioms

Crates

Lifecycle Strategies

Spiral Tensions

Foundations · .ontology/core.ncl

Five Axioms

The invariant set the control plane rests on.

A1 · protocol-as-shared-contract

Protocol as Shared Contract

One shared protocol crate — drift between daemon and agent is a compile error.

A2 · single-namespace-source

Single Namespace Source

Every NATS subject prefix lives in one file — re-namespacing is a one-file change.

A3 · daemon-decides-agent-executes

Daemon Decides, Agent Executes

Control plane owns decisions; the agent owns execution and reports.

A4 · pure-arbitration

Pure Claim Arbitration

Arbitration is a pure function — property-testable offline, deterministic.

A5 · cost-aware-lifecycle

Cost-Aware Lifecycle

Each pool runs an explicit, self-describing, cost-modeled Strategy.

4 Crates · Rust edition 2024 · MSRV 1.93

The Workspace

Four crates; daemon, agent and sim all depend on the shared protocol crate, nothing back.

Crate	Kind	Responsibility	Depends on
fleet-protocol	`lib`	Shared wire-types, KV schemas, subject builders, pure cost math. No I/O.	`—`
fleet-daemon	`lib + bin`	Control plane: arbitration, lifecycle strategy, KV state, TLS coherence, WS channel, HTTP.	`fleet-protocol`
fleet-agent	`lib + bin`	Node-side executor: WS channel to the daemon, runs commands, emits events, heartbeats.	`fleet-protocol`
fleet-sim	`lib + bin`	Offline cost simulator — ranks each strategy against a forecast.	`fleet-protocol`

consumer

lian-build's 'fleet adapter

claim.request→granted/rejected

fleet-daemon

arbitrates · NATS + JetStream

NodeCommand⇄NodeEvent

fleet-agent

executes · one per node

One Strategy per pool · fleet-sim ranks them

Six Lifecycle Strategies

The daemon drives one Strategy per pool; fleet-sim ranks them against a forecast.

ColdImage

Cold Image

Boot fresh from a provider image — cheapest idle, longest boot.

ColdSnapshot

Cold Snapshot

Boot from a pre-baked snapshot — same DAG, 5–7× faster boot.

AlwaysOnResize

Always-On Resize

One long-lived node, resized peak↔baseline — zero boot latency.

StoppedPool

Stopped Pool

N stopped nodes powered on per job — providers with free stop/start.

SpotEphemeral

Spot Ephemeral

Spot nodes per claim, retry on interruption — cheapest rate, interruption risk.

Hybrid

AlwaysOnResize primary + ColdSnapshot overflow — low-latency baseline plus burst.

Spiral Tensions · core.ncl

Four Tensions

A Spiral tension is a polarity to navigate, not a problem to solve.

T1 · cost-vs-latency

Cost vs Boot Latency

Cheap-idle strategies pay long boots; warm strategies cost while idle.

SynthesisMake the trade-off explicit (the catalog) and navigable (the simulator).

T2 · autonomy-vs-control

Agent Autonomy vs Daemon Control

The agent must act fast and local; the daemon must own all policy.

SynthesisBounded delegation — the daemon sets bounds, the agent executes within them.

T3 · repo-identity-vs-wire-identity

Repo Identity vs Wire Identity

The repo was renamed; the wire namespace was deliberately not.

SynthesisKeep the identities separate — the one-file namespace source makes both reversible.

T4 · protocol-faithful-vs-buildkitd-integrated

Protocol-Faithful vs buildkitd-Integrated Execution

The agent runs protocol verbs faithfully; buildkitd-bound verbs emit typed errors.

SynthesisCorrect now, completing later — buildkitd integration is tracked F.1 follow-on work.

Run · TOML-config driven

Running it

Both binaries are TOML-config driven; the simulator is offline.

# Build the whole workspace
cargo build --workspace

# Control plane — arbitrates claims, drives pool lifecycle
FLEET_DAEMON_CONFIG=./daemon.toml cargo run -p fleet-daemon

# Node-side agent — one per build node, dials the daemon channel
FLEET_AGENT_CONFIG=./agent.toml cargo run -p fleet-agent

# Offline cost simulation — rank strategies against a forecast
cargo run -p fleet-sim -- --config sim-input.json --out result.json

# The claim plane — every subject under the fleet.libre-forge. prefix
claim.request   fleet.libre-forge.claim.request.<workspace>.<id>
claim.granted   fleet.libre-forge.claim.granted.<workspace>.<id>
claim.released  fleet.libre-forge.claim.released.<workspace>.<id>

# lian-build's 'fleet adapter is the primary caller — it publishes a
# claim, receives an endpoint + per-claim age-encrypted mTLS, builds,
# and releases. forge-fleet never sees the build itself.

Ecosystem · part of tetra-build