Harness design

Native Rust verification with explicit boundaries between deterministic models, real processes and product platform acceptance.

Three layers

Layer Implementation and evidence

Transaction mechanisms src/harness.rs drives the production engine with FakeHost and an effect-aware store. tests/engine.rs and tests/simulation.rs check crash boundaries, predicates and recovery.

Real I/O and processes Download, durable storage, command controller, independent worker and acceptance integration suites. These use actual sockets, files and subprocesses.

Product acceptance Publisher tests for the real service manager, packaging, ownership, data and workload promises. A model pass cannot establish these facts.

Layer	Implementation and evidence
Transaction mechanisms	`src/harness.rs` drives the production engine with FakeHost and an effect-aware store. `tests/engine.rs` and `tests/simulation.rs` check crash boundaries, predicates and recovery.
Real I/O and processes	Download, durable storage, command controller, independent worker and acceptance integration suites. These use actual sockets, files and subprocesses.
Product acceptance	Publisher tests for the real service manager, packaging, ownership, data and workload promises. A model pass cannot establish these facts.

Native CLI

cargo run --locked --bin k-harness -- --help
cargo run --locked --bin k-harness -- --list --profile service --json
cargo run --locked --bin k-harness -- --profile service --json
cargo run --locked --bin k-harness -- sim --seed 42 --json
cargo run --locked --bin k-harness -- sim --seeds 256 --start-seed 1 --json

Profiles invoke named Rust integration suites through Cargo and require the crate source. They reject missing or zero-test suites and bound the overall run. Swap selects acquisition, durable storage, source, protocol, quarantine and serving; service additionally selects engine, runner, process, invariants, simulation and acceptance suites. --list describes this selection; it is not an inventory of every repository check.

External targets

Simulation and external acceptance execute inside the native CLI without invoking Cargo. Build the CLI once with cargo build --locked --release --bin k-harness.

k-harness --bin ./app --target ./k.target.json --target-version 2.0.0 --json

{"version":["--version"],"selfUpgrade":["upgrade"],"artifact":"app-2.0.0"}

The verifier copies the executable into an isolated directory, serves the supplied candidate over HTTP and sets K_RELEASE_BASE. Acceptance requires changed bytes and an exact next-run version. Commands are declared explicitly, never guessed. The service profile additionally requires a status command returning ProcessEvidence, TxnState and ConvergenceReport. Artifact paths are relative to the declaration.

k-harness --adapter ./controller --target ./adapter.json --json

{"stableArtifact":"service-1.0.0","candidateArtifact":"service-2.0.0",
 "brokenArtifact":"service-broken","stableVersion":"1.0.0",
 "targetVersion":"2.0.0","args":[]}

The controller speaks the v1 protocol. The verifier checks promotion, rollback with a genuinely broken candidate, recovery, live probe identity and rejection after stop. Cleanup failure fails acceptance. JSON declares data and native commands; it cannot load executable configuration modules. Use Rust ReadbackSurface and invariant integrations for custom workloads and lifecycle surfaces.

Seeds and mutation checks

Simulation exercises the production engine with deterministic effects and failures. Its output includes the seed and transcript hash. Failing seeds are merged atomically into .k-harness/sim-failures.json; --record-failures PATH changes the path. Replay the recorded seed before making a regression case. Nightly CI runs 50,000 seeds.

Mutation self-checks confirm that broken dual-run, stable-preservation, write-ahead, workload-preservation and resume behavior is detected. Real stalls, worker death, partial files and platform image replacement are separate tests. Simulation is not a power-loss or service-manager guarantee.

Invariants and scope

src/invariants.rs provides safety, liveness and workload checks. Receipts name the checks actually executed. A product must declare which service and workload properties apply; unspecified capabilities are never counted as passed. See the test plan for commands and platform gates.