Design

Execution and trust

The processes are drawn and named in the guide. The obligations on that layout:

• The runner and its dependencies live outside the application slots and service unit. Stopping the application must leave the worker alive. A child process can still belong to a systemd cgroup or Windows job; the publisher must arrange isolation.
• The supervisor retains recovery code until settlement. Installation state persists. An OS hook or operator must restart installation after reboot.
• The adapter is fixed at build time. Requests select an action and a target version, never code, commands or download URLs.
• The publisher authenticates distribution metadata and caller authority. K checks artifact SHA-256 and size; these checks do not establish publisher identity. See packaging.

Components

Runner::new(store, host, source) assembles the transaction. serve::serve_runner validates input before constructing it. supervisor::{supervise_release,supervise_bytes} return a structured LaunchResult; resume_runner verifies retained bytes and performs operation-bound offline recovery.

Transaction and recovery

Each installation has one lock, stable and experiment executable slots, and a journal. Application data belongs outside the slots. The walkthrough is in the guide, one upgrade start to finish and when something goes wrong; the obligations:

• The phases are, in order, idle, staged, handing-over, running-experiment, readback, then promoted or rolled-back. Intent is journaled before effects.
• Recovery takes the same lock and uses existing slot bytes without release lookup. Before durable promote intent it restores stable; after it, it replays commit idempotently.
• Every started operation has an owner that waits for a durable terminal result or explicitly reports unresolved recovery. An installer invocation settles unfinished work before admitting a new upgrade; recovering an interrupted operation does not retry its requested upgrade.

A running candidate alone does not authorize commit. Corrupt or unknown state, and another live lock owner, prevent conflicting operations. Filesystem durability and controller behavior determine the real platform guarantees.

The supervisor

• runs outside the application service unit;
• retains the verified runner while the operation is active;
• enforces execution and recovery budgets (values);
• starts a recovery worker after an abnormal exit;
• stops supervising after completion or an explicit unresolved result.

Recovery attempts and total elapsed time are bounded. Exhaustion preserves state and provides a recovery command rather than reporting success.

Takeover and binding

Observe exit first

Before starting a successor, the supervisor must observe the prior worker exit. The recovery worker then takes the lock and fences outstanding controller effects before replaying lifecycle actions. An expired deadline alone is insufficient; an unconfirmed exit forbids takeover.

Bind to the original id

Recovery must bind to the original operation id under K's transaction lock. If another operation has since run, recovery inspects or replays the original result without modifying the newer operation. Recovery reuses the existing journal and receipts; supervision does not create another transaction log.

Clean up after settlement

Persist the outcome, release owned resources, then remove disposable code. Never delete slots, a live owner's lock, or recovery logs to make an interrupted operation appear complete. If recovery remains unresolved, preserve the evidence and a verified means to invoke it again.

Budget every host call

Every engine host call has a positive budget. Uncertain effects retain the worker's lock until it exits. Bundled workers exit after flushing their response; custom in-process callers must also exit on Error::Uncertain rather than reuse that worker.

Local lock only

The lock is a local filesystem protocol requiring atomic creation and coherent directory reads (details). It is not a distributed or NFS lock. Operation ids, receipt archival and replay rules are in the reference.

Repair boundary

They do not forbid a product installer from repairing a machine K cannot, provided the repair stays outside K's transaction and keeps these obligations:

Settle first

Run recovery to its terminal or unresolved result before repairing. Repair is never the response to a rolled-back or failed upgrade; it is the response to records that cannot be settled or read.

Never under a live lock

Liveness is decided by the lock protocol, not by age.

Retain recovery inputs until settled

Slots, journal, lock, receipts and recovery logs move aside intact in one atomic rename, under K's lock, including records K itself cannot read (quarantine::quarantine_state with allow_unreadable). This protects an unfinished repair; it is not permanent backup retention. After verified replacement and a durable terminal receipt, the product installer removes obsolete owned payloads and quarantine copies, retaining only necessary small replay/attribution records. Cleanup must be restartable and must not touch active operations or application data.

Attribution and receipt

Repair runs as its own request or on a broken machine, never on a machine that can be upgraded, and its receipt records what it displaced, what it installed and who ran it.

Re-enter K

Repair ends with storage::bootstrap_stable on the installed bytes and verified process evidence: a live service when one was running, or a fresh candidate self-check when it was stopped. Until then no upgrade may be admitted.

No rollback claim

Repair is reported as a repair, never as a promoted upgrade.

K supplies storage::bootstrap_stable, quarantine::quarantine_state and the lock protocol; the installer decides when to repair.

Hooks::prepare_candidate(artifact, release) runs under the transaction lock after verified acquisition and before the first handover intent. Product installers use this bounded hook to check the executable's platform and self-reported version and persist operation-bound service/setup state. It must not stop, publish or start the installed service. Failure produces a settled failed receipt without handover; replay and offline recovery do not repeat the hook.

Host control contract

Runner::new requires a host::Host. Its operations and the controller's obligations:

• The controller must work while the old application is down.
• start returning does not establish readiness; the probe does. In stopped-service mode the adapter publishes the selected bytes without starting a resident. Its probe launches those bytes for a bounded self-check; the receipt distinguishes this evidence from a running service.
• K probes once before handover and records that incarnation's startId with the handing-over intent. Readback evidence carrying the same startId is refused and rolls back: the old service was not replaced.
• start must not execute the artifact in place inside the slot on Windows; promotion renames slot directories and a running executable locks its directory. Copy or hard-link to a runtime path outside the slots.
• A stateless service satisfies quiesce and resume by acknowledging. The obligations apply to workloads the product promises to preserve.
• Adapters with no effects surviving their worker may omit fence. All other adapters must supply it and test it against their real service manager. CommandHost always delivers fence; a command controller that queues nothing acknowledges it.
• If OS lifecycle surfaces are declared, K also requires them to reference the promoted artifact before retiring their previous manager. Undeclared surfaces are not observed.

CommandHost runs an external controller via argv without a shell, records the controller pid durably before each call, and drains recorded controllers before fence during recovery. Wire format, bounds and pid handling are in the reference. The recorded pid is never used to kill an arbitrary process. fence acknowledgement is a product contract, not something K infers from process exit. Fire-and-forget stop cannot establish termination.

Product responsibilities

The adapter defines release lookup, installation ownership, consent and compatibility policy. K restores executables; products provide data-migration compatibility, backup and restore, and any promised workload continuity. What the installer around K should do for each entry and outcome is the advisory installer contract.