Module install 

agent-runtime install body. Plan 04 Sprint 1 Tasks 1.2 / 1.3.

Layout:

• link_map — parser for targets/<product>/link-map.yaml with per-entry validation that mirrors the JSON Schema in agent-runtime-kit/core/docs/schemas/link-map.schema.json.
• overlay — optional .private/link-map.overrides.yaml parser plus the per-entry-replace merge function. Applied before plan generation.
• plan — builder that turns a (post-overlay-merge) LinkMap into a flat ordered InstallPlan, expanding recursive: true directory entries into one action per file. Non-recursive symlinked-file entries intentionally accept either file or directory sources and become one symlink action at the declared destination.
• executor — walks the plan and reconciles the runtime home to the plan. Re-running on a clean install is a byte-identical no-op.

The CLI wrapper lives in commands::install. Task 1.3 layers --live-home, --tag, and --no-overlay on top of the Task 1.2 Rust API without rewriting the contract.

Re-exports

pub use executor::AppliedChange;

pub use executor::ApplyError;

pub use executor::Mode;

pub use executor::is_trusted_tag;

pub use link_map::LinkMap;

pub use link_map::LinkMapError;

pub use overlay::LinkMapOverlay;

pub use overlay::OVERLAY_REL_PATH;

pub use overlay::OverlaySummary;

pub use plan::InstallPlan;

pub use plan::PlanError;

Modules

executor

Apply executor for the install plan. Walks each PlanAction in order, mutating the filesystem only when the current state diverges from the desired state. Second-run-is-a-no-op idempotence is the load-bearing invariant Plan 04 Sprint 1 Task 1.2 ships against — see the integration test in tests/integration/install_pipeline.rs.

link_map

targets/<product>/link-map.yaml parser.

overlay

.private/link-map.overrides.yaml overlay parser. Plan 04 Sprint 1 Task 1.3.

plan

Install plan: the deterministic struct that both the dry-run printer and the apply executor consume. Plan 04 Sprint 1 Task 1.2.

Structs

InstallOptions

Per-run knobs threaded through to the executor. Plan 04 Sprint 1 Task 1.3 introduces these; later sprints (gc-backups, doctor) keep extending the struct rather than the positional run signature.

InstallOutcome

Full outcome of an install::run cycle. The CLI consumes the overlay field to print a one-line operator-visible notice when an overlay was merged (architecture-doc requirement: dry-run must expose the post-merge effective config).

Enums

InstallError

Top-level error returned by run. Each variant wraps the typed error from the contributing module so callers can match on the root cause if they need to.

Functions

run

Execute one install cycle. Builds the plan from the link-map at <source_root>/targets/<product>/link-map.yaml, then either prints it (Mode::DryRun) or applies it (Mode::Apply). home and state_home must be absolute. now is injected so the backup-dir timestamp stays deterministic in tests.