canic-host

canic-host owns operator-machine artifact builds, current desired-state Fleet reconciliation, network/ICP transport, evidence policy and supporting local state. It is not a canister runtime.

Normal operators use the installed canic binary. Direct Rust consumers may use the build and fleet_ensure modules when embedding the same current contract.

Build

canic build <app> <role> --profile release

Every managed package declares exact App/role metadata. Artifact builds are non-incremental for deterministic Wasm. An explicit RUSTC_WRAPPER wins; otherwise the host discovers sccache on PATH. Before starting Cargo compilation with that implicit cache, Canic probes compiler startup directly and through the cache using rustc -vV (or the environment-selected RUSTC, including RUSTC_WORKSPACE_WRAPPER). The probes inherit the build directory, toolchain environment and command environment. A cache probe failure retains the original error and points to RUSTC_WRAPPER= canic build <app> <role> --profile release for direct compilation. An explicitly empty or custom RUSTC_WRAPPER bypasses implicit cache probing. Canic does not retry a failed build with a different wrapper. The probe checks compiler startup, not every later cache operation or Cargo configuration override; ordinary Cargo/compiler failures remain intact.

Fleet Ensure

Production Fleet convergence uses the maintained Ensure owner:

canic fleet ensure <fleet> --desired <path>
canic fleet ensure <fleet> --desired <path> --apply <plan_sha256>

canic fleet generate --fresh can first create or replay a durable, effect-free logical seed for an empty estate. It does not install anything or own a second mutation path. The generated document enters the same reviewed plan/apply journal above; create results are retained before dependent controller and treasury references are resolved.

The host modules follow the strict boundary:

CLI -> workflow -> policy
                +-> ops -> model

• model owns the current v1 plan, journal and conservation records.
• policy validates desired/live inputs and compiles the immutable plan.
• ops owns artifact hashing, current state files and one platform effect.
• workflow persists intent, reconciles replay and publishes terminal state.

Historical install plans, release-pair loaders, role journals, repair receipts, recovery bundles, adoption paths and installed-Fleet caches are not read.

Cycle Safety

The plan records exact controlled balances, canister dispositions, scheduled transfers, fees, funding and bounded burn. Every mutating platform call has a durable intent first. Ledger and configured drain effects use exact replay identities. Apply refuses a changed plan, unsafe live drift or a debit/burn above the reviewed maximum.

A controller cannot pull cycles from an arbitrary canister. Material replacement/deletion therefore requires an exact treasury-bound idempotent drain endpoint. Without it, policy returns NoSafeDrain and leaves the canister untouched. Stop and delete remain separate effects with fresh status and residual-balance checks.

The complete desired document and operator procedure are documented in Fleet ensure.

ICP Identity

When ICP CLI uses password storage, pass its supported identity password file through the individual operator environment. Canic forwards the path to ICP CLI and does not read or render the password contents. Keep credentials outside the repository.

Operator Component provisioning is available through component_operation: the host retains exact review and submission authority while Root owns its lifecycle. See the Component operation guide.

Frontend browser artifacts and external native-cycle preflight are owned by frontend. See the frontend handoff guide and independent SDK consumer.

The Fleet observatory supplies independent role observations and bounded public reports from the host.

Persistent local Fleet

The optional local-fleet feature exposes LocalFleetSession for a persistent PocketIC-backed Fleet with separate application subnets, exact release-bound preparation, ordinary Fleet Ensure convergence and a fixed browser gateway. The packaged local_fleet example uses only public library APIs. It accepts bounded JSON-line commands for seed/generation, convergence, current role/subnet discovery, frontend export, status, restart, time advance and shutdown; reset binds one exact former session. See the local Fleet guide for configuration, executable fingerprinting, resource limits and simulation fidelity. Production canisters do not gain a testing dependency.