Executable build foundation

This document describes the maintained clean-checkout build foundation introduced in Phase 1 and used by the completed Phase 2 delivery surface. It turns the checked-in Rust, Protobuf, and WIT interfaces into compilable generated surfaces while retaining Phase 0 evidence as historical artifacts rather than live execution paths.

Scope

The foundation provides:

• one locked Rust workspace with exact dependency versions;
• build-generated Rust messages plus Tonic clients and servers for every checked-in Protobuf file;
• build-generated Wasmtime host bindings for the aggregate platform runtime world and the maintained echo fixture;
• build-generated Rust guest bindings for the aggregate platform runtime world;
• deterministic test utilities for current-thread async execution, child-process capture, temporary workspaces, IDs, clocks, and current-process resource snapshots;
• repository validation for path-dependency cycles, exhaustive code-generation inputs, generated-output ownership, and generated-source boundaries;
• pull-request CI for formatting, compilation, Clippy, tests, contracts, and SDK surfaces.

Code generation runs only as a Cargo build step and writes generated Rust to OUT_DIR; linking its output allocates no runtime resources. The implemented scheduler, execution cells, adapters, and Linux service process are separate consumers of this foundation. See the current API surface and standalone node for their runtime ownership and startup boundaries.

Pinned Rust inputs

The exact dependency baseline is recorded in both the root Cargo.toml and tools/toolchain.toml:

Area	Version
Rust toolchain / MSRV	1.97.1 / 1.94.1
Tokio	1.53.1
Prost	0.14.4
Tonic / Tonic Prost	0.14.6 / 0.14.6
Tonic Prost Build	0.14.6
Vendored protoc	3.2.0
Tracing / tracing-subscriber	0.1.44 / 0.3.23
Wasmtime	47.0.4
wit-bindgen	0.62.0

The committed root Cargo.lock is authoritative. Local commands and CI use --locked; they do not silently replace the dependency graph.

Code-generation ownership

Protobuf

api/proto/ is authoritative. api/proto/latent-api.protos is a sorted and exhaustive manifest of every .proto input. crates/latent-rpc/build.rs verifies that the manifest and directory are identical, uses the pinned vendored protoc, and emits messages, clients, servers, and a descriptor set into Cargo OUT_DIR.

Generated Rust is exposed by latent-rpc as:

• latent_rpc::control::v1;
• latent_rpc::invocation::v1;
• latent_rpc::FILE_DESCRIPTOR_SET.

The integration test in crates/latent-rpc/tests/generated_services.rs type-checks every generated client surface, every generated server trait/server wrapper, and the descriptor set. Adding a Protobuf service without generated compilable Rust therefore fails the workspace build.

Component Model WIT

Checked-in WIT remains authoritative. crates/latent-component-bindings/build.rs is the single shared staging and generation owner for:

• wit/platform/runtime plus every platform dependency;
• examples/echo-contract/wit plus its context and log dependencies.

It emits bindings into OUT_DIR and exposes:

• latent_component_bindings::host::runtime;
• latent_component_bindings::host::echo;
• latent_component_bindings::guest::runtime on Wasm targets.

latent-wasmtime consumes the shared aggregate-runtime host bindings for its allowed context, log, and clock imports, plus the Phase 3 binding types for configured async local-service and HTTP adapters, and the shared echo host bindings for the retained Phase 0 signature check. Generic guest calls use Wasmtime's validated dynamic export indices. latent-toolchain-smoke consumes the shared aggregate runtime bindings for compile probes; its executable fixtures generate canonical ABI exports in their final guest crates from maintained WIT.

latent-angular-renderer-adapter is a fixed Wasm-only guest crate. It generates the public async web export and its private composition interface from maintained WIT. Handwritten code denies unsafe operations; a source tripwire permits only the exact generated ABI module to relax that lint. This guest exception does not add a native deserializer or weaken the audited Wasmtime loader boundary.

Generated-output boundary

No generated Rust is committed under api/proto, wit, or an example wit directory. The foundation validator requires the two generation owners above, rejects the superseded duplicate build scripts, and rejects unlisted Protobuf files or generated language sources inside contract-authority directories.

Generated build products belong in ignored locations such as Cargo OUT_DIR, target/contracts/, SDK compiler output directories, and target/capsules/. The explicit test-fixture exception is crates/latent-wasmtime/src/values/types.wasm, a small type-only Component Model binary checked in beside authoritative types.wat. This lets ordinary codec unit tests inspect types without an external parser. The contract gate regenerates the binary with pinned wasm-tools, compares its bytes with the checked-in fixture, and validates it.

Dependency graph boundary

tools/validate_foundation.py resolves all workspace path dependencies and performs cycle detection before contract compilation. A cycle is a validation error with the concrete dependency path. Missing path dependencies remain covered by the repository validator.

Test foundation

latent-testkit exposes reusable primitives whose resources are created only by explicit calls:

• DeterministicIds, ManualClock, TempWorkspace, and the calling-thread block_on executor;
• AsyncTestRuntime, an explicitly constructed Tokio current-thread runtime with no worker pool;
• ProcessHarness and CapturedProcess for command construction and output, plus OwnedProcess for capped asynchronous pipe capture, child watchdogs, and explicit wait/termination that reaps the child and joins its readers;
• CurrentProcessProbe for portable current-process observations, and ChildProcessProbe for bounded Linux measurements tied to a retained child's PID/start time and owned socket inodes;
• BorrowedBackendHarness, InvocationConformanceSuite, ScopedNodeHarness, and ObservedInvariantProbe for selected checks using supplied managers, backends, inventory and telemetry sources; and
• versioned conformance records, fixed case definitions, shared work counters, and bounded serialization for the selected Phase 1 profile.

A test creates these utilities explicitly. Merely linking a service crate creates no thread, process, socket, listener, or runtime. The bounded profile records selected behavior and child resources; scaling, soak, calibrated-baseline and broader equivalence evidence remain outside that selected profile. The Phase 1 completion report combines its coverage with the retained full measurements, controlled comparison and owning suites.

Clean-checkout sequence

The supported reference environment is Linux or WSL. Install the pinned Rust toolchains and targets, Python 3.13.5, wasm-tools 1.254.0, Buf 1.72.0, and the language SDK prerequisites documented in toolchain.md. A system protoc is not required because Rust generation uses the pinned vendored binary.

Run:

rustup toolchain install 1.97.1 --profile minimal --component rustfmt,clippy \
  --target wasm32-wasip2,wasm32-unknown-unknown
rustup toolchain install 1.94.1 --profile minimal

python3.13 -m venv .venv
. .venv/bin/activate
python -m pip install --requirement tools/requirements.lock

make phase1-foundation
make sdks

make validate is the equivalent complete command. The foundation-only command expands to:

cargo fmt --all --check
cargo check --workspace --all-targets --all-features --locked
cargo clippy --workspace --all-targets --all-features --locked
cargo test --workspace --all-targets --all-features --locked
tools/validate_contracts.sh

Focused generation checks are available as:

make rpc-bindings
make component-bindings
make guest-bindings

CI contract

.github/workflows/ci.yml runs for every pull request, pushes to development, and manual dispatches. Its Rust job verifies formatting, the whole workspace, host and guest Component Model bindings, RPC generation, Clippy and tests, followed by bounded Phase 2 operator, native-currentness, offline and resource workflows. Separate jobs verify the MSRV, repository contracts, catalog/routing regressions, OCI TLS/observed-build integration and all language SDK surfaces.

CI / Repository contracts builds the maintained contract fixtures and runs the current repository contract checks. The retired Phase 0 executable outcome matrix and dedicated Phase 0 workflows are no longer part of current CI. The durable 100,000-release catalog probe still runs only when CI is dispatched with run_catalog_scale: true; ordinary checks leave it ignored.

Historical Phase 0 evidence

The Phase 0 feasibility result remains part of the project history, but its spike, baseline, soak, calibration and gate runners are no longer maintained execution surfaces in the current tree. The checked-in evidence under benchmarks/phase0, together with its validators and aggregation code under tools/, remains available for integrity checks without being compiled into latentd or executed by normal CI.

The maintained echo fixture and reproducibility commands remain supported because current contract, supply-chain and integration tests still consume that fixture:

Command	Status	Purpose
make echo-capsule	maintained	Build and validate the maintained echo component
make echo-capsule-reproducibility	maintained	Verify same-host byte reproducibility

Reproducing an original Phase 0 workload requires checking out the exact source revision recorded by the corresponding retained evidence.