Runnable native example

A native application, controller and independently supervised installer. The application has no K dependency.

Run the walkthrough

From the repository root, with the pinned Rust toolchain and Python 3:

python3 scripts/verify-native-examples.py

The script builds actual 1.0.0 and 2.0.0 binaries, serves verified release metadata on an ephemeral loopback HTTP server, seeds stable, starts the service, upgrades through a separate worker, replays the receipt and probes the live process. It also checks the self-updating CLI. Installer execution uses PATH=/nonexistent; compilation happens first. Temporary files, servers and resident processes are cleaned in a finally block.

Four native pieces

Source Role

examples/native-service.rs Versioned service with an authenticated per-incarnation loopback probe and cooperative stop.

examples/native-controller.rs Implements fence, quiesce, stop, start, probe and resume. Copies the executable outside the slots before running it.

examples/native-installer.rs Seeds stable or supervises an independent copy of itself. Its worker validates one request before constructing a Runner.

examples/native-swap.rs Verified HTTP download and atomic replacement for a CLI, without a resident service transaction.

Source	Role
`examples/native-service.rs`	Versioned service with an authenticated per-incarnation loopback probe and cooperative stop.
`examples/native-controller.rs`	Implements fence, quiesce, stop, start, probe and resume. Copies the executable outside the slots before running it.
`examples/native-installer.rs`	Seeds stable or supervises an independent copy of itself. Its worker validates one request before constructing a Runner.
`examples/native-swap.rs`	Verified HTTP download and atomic replacement for a CLI, without a resident service transaction.

Requests and configuration

The installer reads trusted K_EXAMPLE_ROOT, K_EXAMPLE_CONTROLLER and K_RELEASE_BASE configuration. The root must be absolute. The walkthrough supplies these values and release metadata; arbitrary input cannot select controller code or a release URL.

{"protocolVersion":1,"action":"upgrade","id":"demo-v2","targetVersion":"2.0.0","consented":true}
{"protocolVersion":1,"action":"status"}
{"protocolVersion":1,"action":"recover","expected":{"id":"demo-v2","targetVersion":"2.0.0"}}

Repeating the same id and target returns the existing receipt without another handover. Status is historical, so the walkthrough separately asks the controller for a live probe. Bootstrap initializes a fallback; it does not manufacture an upgrade receipt.

Recovery and fault tests

cargo test --locked --test process --test engine --test acceptance

These suites exercise killed and hung workers, bounded recovery, receipt mismatch, corrupt retained workers, bad candidates, rollback and live controller behavior. supervisor::resume_runner verifies retained worker bytes and recovers without release distribution.

Product integration

The example controller is not a service manager. Replace it with actual launchd, systemd or Windows service integration, ownership checks and any promised workload preservation. On Windows call host::isolate_standard_handles before spawning children; keep the running executable outside slot directories. The runtime copy is not another rollback slot.

See integration and distribution and external target verification.