炼 · Alchemical Refinement · v0.1.0 Beta

“Fire without the ash.”

Ephemeral crucibles that refine code into reproducible artifacts.

Ephemeral Build Substrate for
Provider-Pluggable BuildKit Sessions

Callers (provisioning, vapora, workspace CI) supply BuildDirectives in NCL. lian-build controls compute provisioning, OCI cache flow, and multi-actor session namespacing. Compute (hcloud / proxmox / docker-local) and registry (zot / harbor / ghcr) are plug-in slots, not hard dependencies.

View Repository →Architecture CLI Reference

Axioms

Spiral Tensions

Sizing Tiers

Hard Constraints

Foundations · .ontology/core.ncl

Four Axioms

The invariant set the rest of the system is built on. Each is declared in .ontology/core.ncl with invariant = true; violating one is an architectural break, not a routine refactor.

A1 · ephemeral-builds

Ephemeral Builds

Build environments are spawned on demand, torn down after completion. No persistent build state exists outside the content-addressed cache and the registry. This prevents environment drift and makes builds reproducible by construction.

A2 · provider-pluggability

Provider Pluggability

Compute and registry are plug-in slots, not hard dependencies.

A3 · cache-content-addressed

Content-Addressed Cache

All build cache is stored as OCI artifacts, keyed by content hash.

A4 · caller-supplies-directives

Caller Supplies Directives

lian-build does not decide what to build or how — callers do.

Build Flow · src/main.rs::main

Architecture

A single binary orchestrates an external HTTP service, drives a spawned VM over SSH, and emits lifecycle events on NATS.

Module	Responsibility
`main.rs`	CLI parsing, top-level orchestration, NATS event dispatch, OOM-retry control flow.
`orchestrator_client.rs`	HTTP client: spawn/destroy/p95/record_metrics, wrapping responses in ApiResponse<T>.
`buildctl_runner.rs`	Drives the spawned VM over SSH. Rsyncs primary context and named extra_contexts (local paths → /build/extra-contexts/<name>/; image refs as docker-image://). Runs buildctl remotely, detects OOM via exit 137.
`sizing.rs`	Three-tier sizing resolution: explicit spec → P95 × 1.2 → language defaults.
`retry.rs`	OOM-retry policy: MAX_OOM_RETRIES = 1 (ADR-039). Tier walk cx22→cx32→cx42→cx52.
`nats_events.rs`	BuildEventPublisher over platform-nats::EventStream. Publishes started/completed/failed.

Cache Model · schemas/cache_policy.ncl

Cache Namespace Split

Sessions read both ci/* and their own dev/*; CI never imports from dev/*.

ci/<workspace>/*

Canonical · Read-only for sessions

Written by CI. Sessions import but never write back.

dev/<actor-id>-<workspace>/*

Ephemeral · Per session actor

One namespace per SessionActor. Disposition: export / discard / rollback.

Sizing · src/sizing.rs::resolve

Three-Tier Resolution

First match wins.

Explicit BuildSpec

.build-spec.ncl in the build context, validated against schemas/build_spec.ncl. Parsed via nickel export --format json.

P95 Historical × 1.2

OrchestratorClient::get_p95(workspace) returns measured P95 from prior runs.

Language Defaults

RunnerSize::language_default(lang).

Lift-out Boundary · ADR-001 · ADR-007

Four Hard Constraints

All four are grep-checked. ADR-001 defines the lift-out boundary; ADR-007 enforces the named BuildKit context protocol.

C1 · no-provisioning-lib-import · Hard

lian-build source code must not import any crate from the provisioning workspace as a library dependency.

grep -rE 'platform-config|provisioning|stratum-' Cargo.toml src/ → must be empty

Note: platform-nats from stratumiops is allowed; constraint targets provisioning + stratum- crates.

C2 · build-directives-ncl-vocabulary · Hard

Callers must supply intent via lian-build's NCL BuildDirectives schema.

grep -rE 'provisioning_workspace|vapora_|woodpecker_' src/ → must be empty

Caller-specific logic stays in caller-supplied directives, not in core.

C3 · extra-contexts-remote-path-convention · Hard · ADR-007

Local-path extra_contexts entries must be rsynced to /build/extra-contexts/<name>/ on the remote runner.

grep '/build/extra-contexts/' src/buildctl_runner.rs → must be non-empty

Dockerfile authors address contexts by name only. Changing this path breaks every cross-project layer build silently.

C4 · is-local-context-detection-rule · Hard · ADR-007

A value in extra_contexts is local iff it starts with /, ./, or ../; everything else is an OCI image ref passed as docker-image://.

grep 'is_local_context' src/buildctl_runner.rs → must be non-empty

Callers rely on this rule to predict rsync vs. registry-pull behavior. Changing it without caller updates causes silent build failures.

Invocation · single binary

CLI Reference

The current entry is flat CLI args.

lian-build \
  --workspace <name>              # required, env BUILDKIT_WORKSPACE
  --context <dir>                 # required, build context (rsynced to runner)
  --image <ref>                   # required, fully-qualified target image
  --ssh-key <path>                # required, env BUILDKIT_SSH_KEY
  [--dockerfile Dockerfile]       # relative to context
  [--cache-from <ref>] [--cache-to <ref>]
  [--language rust|go|java|...]   # sizing hint (tier 3)
  [--runner-image <id>]           # env BUILDKIT_RUNNER_IMAGE
  [--orchestrator-url <url>]      # default http://localhost:9011
  [--nats-url <url>]              # omit to disable event publishing
  [--nats-nkey-seed <seed>]
  [--nats-subject-prefix <p>]     # default lian-build

Ecosystem · the lian family

Sibling Projects

lian-build is the build driver at the centre of tetra-build — forge-fleet supplies the compute, lamina the build-time layers, solera the runtime images.

Fleet Control Plane

forge-fleet

The compute provider. A claim-arbitration daemon that turns a pool of cloud machines into ephemeral buildkitd capacity behind lian-build's 'fleet adapter.

More information →