//! The plan: one typed, immutable document that is the input to every
//! landing write.
//!
//! The document keeps five kinds apart, and an addition inside one kind
//! is additive. Evidence is what was observed. Analysis is what the
//! engine derived from it: the operations, the compatibility, the
//! guidance. Policy is the requirement each precondition carries.
//! Decisions are workflow state the operator owns. Postconditions are
//! what proves completion. `rk reconcile plan` computes one and prints
//! it; nothing here writes into a target.
pub mod apply;
pub mod classify;
pub mod compatibility;
pub mod evidence;
pub mod fingerprint;
pub mod gather;
pub mod guidance;
pub mod lock;
pub mod operation;
pub mod planner;
pub mod readiness;
pub mod store;
use std::collections::BTreeMap;
use serde::{Deserialize, Serialize};
pub use classify::{Classification, Finding, Verdict};
pub use evidence::{EvidenceItem, EvidenceKind};
pub use operation::Operation;
pub use readiness::{Evaluation, Precondition, Readiness, Requirement};
use crate::digest::Digest;
use crate::landing::Kind;
/// The version of the plan's shape.
pub const PLAN_SCHEMA: &str = "rk.plan/3";
/// What the caller asked the plan to be: the open reconciliation, or one
/// of the three fronts, each of which fixes what the plan may contain.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "kebab-case")]
pub enum Intent {
/// `rk reconcile plan`: the classification decides.
Reconcile,
/// `rk init`: a first landing, refused over a record.
Setup,
/// `rk upgrade`: a recorded target takes the candidate, refused
/// without a record.
Upgrade,
/// `rk adopt`: the record and the configuration alone, every
/// destination verified and none written.
Adopt,
}
impl Intent {
/// The wire form, identical to the serde rendering.
#[must_use]
pub const fn as_str(self) -> &'static str {
match self {
Self::Reconcile => "reconcile",
Self::Setup => "setup",
Self::Upgrade => "upgrade",
Self::Adopt => "adopt",
}
}
}
/// The plan, whole.
#[derive(Debug, Serialize, Deserialize)]
pub struct Plan {
/// The shape version of this document.
pub schema: std::borrow::Cow<'static, str>,
/// Who computed it, when, under which id.
pub identity: Identity,
/// Which procedure this plan is.
pub classification: Classification,
/// What the classification compresses.
pub findings: Vec<Finding>,
/// What the target is asked to converge toward.
pub desired_state: DesiredState,
/// What the target was found to be.
pub observed_state: ObservedState,
/// The candidate bundle and what is known about it.
pub release: Release,
/// The typed changes, in apply order.
pub operations: Vec<Operation>,
/// Each with its requirement and its evaluation.
pub preconditions: Vec<Precondition>,
/// The questions the operator owns, with their selected answers.
pub decisions: Vec<Decision>,
/// The typed checks an apply runs at the end and reports.
pub postconditions: Vec<Postcondition>,
/// Every observed value, cited by the fields above.
pub evidence: Vec<EvidenceItem>,
/// Whether the plan may be applied.
pub readiness: Readiness,
/// One canonical digest over the semantic inputs.
pub input_fingerprint: Digest,
}
/// Who computed the plan, when, and under which id.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct Identity {
/// Derived from the fingerprint and the creation instant, so two
/// plans over the same inputs are distinguishable and one plan is
/// not stored twice by accident.
pub plan_id: String,
/// The instant the plan was computed, RFC 3339.
pub created_at: String,
/// The engine that computed it.
pub engine_version: String,
}
/// What the target is asked to converge toward.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct DesiredState {
/// What the caller asked the plan to be.
pub intent: Intent,
/// The selector as the operator gave it: `embedded`, `latest`, or an
/// exact version.
pub selector: String,
/// What the selector resolved to, once, frozen here.
pub release: ResolvedRelease,
/// The landing configuration the projection renders under, or the
/// reason none resolved.
#[serde(skip_serializing_if = "Option::is_none")]
pub configuration: Option<Configuration>,
/// Why the configuration did not resolve, where it did not.
#[serde(skip_serializing_if = "Option::is_none")]
pub unresolved: Option<String>,
}
/// One exact release, resolved at plan time and never again.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct ResolvedRelease {
/// The exact version.
pub version: String,
/// Where it was read from: `embedded`, `crates`, or `directory`.
pub venue: String,
/// The bundle's aggregate digest.
pub payload_sha256: Digest,
/// The bundle's protocol version.
pub payload_schema: u32,
}
/// The landing parameters, resolved, with the layer each one came from.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct Configuration {
/// The payload binding.
pub tech: String,
/// The forge.
pub forge: String,
/// The project path on the forge.
pub repo: String,
/// The working-copy mode.
pub workflow: String,
/// The release style, where one is answered.
#[serde(skip_serializing_if = "Option::is_none")]
pub style: Option<String>,
/// Whether the landing carries the Nix capability.
pub nix: bool,
/// The one permanent branch.
pub trunk: String,
/// The release-line prefix.
pub line_prefix: String,
/// The security contact the policy names, empty for the forge's own.
pub security_contact: String,
/// The acknowledgment window the policy promises.
pub security_response: String,
/// Which layer answered each parameter: `flag`, `configuration`,
/// `record`, `detected`, or `default`.
pub sources: BTreeMap<String, String>,
/// The evidence the resolution read.
pub evidence_refs: Vec<String>,
}
/// What the target was found to be.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct ObservedState {
/// The repository's own state.
pub repository: Repository,
/// What release-kit landed there, as far as the disk says.
pub installation: Installation,
/// The engine and the host.
pub host: Host,
/// What the forge said, where it was asked.
pub forge: ForgeState,
}
/// The repository's own state, read off the disk and git.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct Repository {
/// The target directory.
pub target: String,
/// Whether the target is a git repository.
pub git: bool,
/// How many tags it holds.
pub tags: usize,
/// Long-lived branches beside the trunk.
pub long_lived_branches: Vec<String>,
/// Other tools' release markers present.
pub release_markers: Vec<String>,
/// Payload destinations already present.
pub collisions: Vec<String>,
/// The technology the version file names, where one is found.
#[serde(skip_serializing_if = "Option::is_none")]
pub tech: Option<String>,
/// The forge the origin remote maps to, where one is recognized.
#[serde(skip_serializing_if = "Option::is_none")]
pub forge: Option<String>,
/// The project path from the origin remote, where one exists.
#[serde(skip_serializing_if = "Option::is_none")]
pub repo: Option<String>,
/// The corpus verdict the facts above earn.
pub verdict: Verdict,
/// The evidence these facts rest on.
pub evidence_refs: Vec<String>,
}
/// What release-kit landed at the target.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct Installation {
/// The landing record.
pub record: RecordState,
/// The committed configuration.
pub configuration: ConfigurationState,
/// Every destination the candidate or the record names, as found.
pub destinations: Vec<Destination>,
/// The evidence the installation rests on.
pub evidence_refs: Vec<String>,
}
/// The landing record, as found.
#[derive(Debug, Clone, Serialize, Deserialize)]
#[serde(tag = "state", rename_all = "kebab-case")]
pub enum RecordState {
/// No record at the target.
Absent,
/// A record this engine read.
Present {
/// The binary that wrote it.
rk_version: String,
/// The payload that landed.
payload_sha256: Digest,
/// The record's schema.
schema_version: u64,
/// How the record came to exist.
origin: String,
/// The digest of the record's bytes.
sha256: Digest,
},
/// A record this engine could not read.
Invalid {
/// Why.
reason: String,
},
}
/// The committed configuration, as found.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct ConfigurationState {
/// Whether `.release-kit/config.toml` exists.
pub present: bool,
/// The digest of its bytes, where present.
#[serde(skip_serializing_if = "Option::is_none")]
pub sha256: Option<Digest>,
/// Why it did not read, where it did not.
#[serde(skip_serializing_if = "Option::is_none")]
pub invalid: Option<String>,
/// Keys whose configured answers the record has yet to take up.
pub pending: Vec<String>,
}
/// One destination, as found.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct Destination {
/// The destination, relative to the target.
pub path: String,
/// Whether the file, or the marked block, is present.
pub present: bool,
/// The digest of what is there, where present.
#[serde(skip_serializing_if = "Option::is_none")]
pub sha256: Option<Digest>,
/// The kind the record declares for it, where the record names it.
#[serde(skip_serializing_if = "Option::is_none")]
pub recorded_kind: Option<Kind>,
}
/// The engine and the host.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct Host {
/// This engine's version.
pub engine_version: String,
/// The pin the wired manager records for `rk`, where one does.
#[serde(skip_serializing_if = "Option::is_none")]
pub pin: Option<PinState>,
/// The evidence the host facts rest on.
pub evidence_refs: Vec<String>,
}
/// The `rk` pin a tool manager records.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct PinState {
/// The manager.
pub manager: String,
/// The file that records it.
pub file: String,
/// The version, as the manager records it.
pub version: String,
}
/// What the forge said, where it was asked.
#[derive(Debug, Clone, Serialize, Deserialize)]
#[serde(tag = "state", rename_all = "kebab-case")]
pub enum ForgeState {
/// The forge was not asked, and the reason says why.
NotObserved {
/// Why.
reason: String,
},
/// The forge was asked.
Observed {
/// The trunk the read asked about.
trunk: String,
/// The trunk's tip at the remote, where it has one.
#[serde(skip_serializing_if = "Option::is_none")]
remote_tip: Option<String>,
/// The evidence the read produced.
evidence_refs: Vec<String>,
},
}
/// The candidate bundle and what is known about it.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct Release {
/// The candidate's identity.
pub candidate: BundleIdentity,
/// How the candidate was verified.
pub verification: Verification,
/// The recorded release's bundle, for the three-way comparison.
pub baseline: BaselineState,
/// What the engine can say about reading this bundle.
pub compatibility: Compatibility,
/// The guidance the bundle carries for this target.
pub guidance: Guidance,
}
/// One bundle's identity.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct BundleIdentity {
/// The release's version.
pub version: String,
/// The aggregate digest.
pub payload_sha256: Digest,
/// The protocol version.
pub payload_schema: u32,
/// How many artifacts the bundle carries.
pub artifacts: usize,
/// The evidence the identity rests on.
pub evidence_refs: Vec<String>,
}
/// How a bundle was verified.
#[derive(Debug, Clone, Serialize, Deserialize)]
#[serde(tag = "method", rename_all = "kebab-case")]
pub enum Verification {
/// The bundle is the one compiled into this engine.
Embedded,
/// The archive digested to the registry's checksum.
RegistryChecksum {
/// The checksum the index named.
cksum: Digest,
},
/// A directory laid out as a bundle, read as is.
Directory,
}
/// The recorded release's bundle, as read for the baseline.
#[derive(Debug, Clone, Serialize, Deserialize)]
#[serde(tag = "state", rename_all = "kebab-case")]
pub enum BaselineState {
/// No record, so no baseline is needed.
NotNeeded,
/// The recorded payload is the one compiled into this engine.
Embedded,
/// The recorded release's bundle was read from the release cache.
Cached {
/// The recorded version.
version: String,
},
/// The recorded release's bundle could not be read, and the reason
/// says why.
NotObserved {
/// Why.
reason: String,
},
}
/// What the engine can say about landing this bundle here.
///
/// The protocol axis, and the four axes the bundle declares beyond it.
/// The facts live here; the preconditions carry each axis's requirement
/// and evaluation.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct Compatibility {
/// The engine's protocol version.
pub engine_schema: u32,
/// The bundle's protocol version.
pub bundle_schema: u32,
/// Whether the engine reads the bundle.
pub readable: bool,
/// The oldest engine the bundle names, where it names one.
#[serde(skip_serializing_if = "Option::is_none")]
pub engine_minimum: Option<String>,
/// The generator the binding's committed artifact needs, where the
/// technology has one.
#[serde(skip_serializing_if = "Option::is_none")]
pub generator: Option<GeneratorFact>,
/// The forge floor the landed files rest on, where the bundle declares
/// one for the configured forge.
#[serde(skip_serializing_if = "Option::is_none")]
pub forge_floor: Option<ForgeFloor>,
/// The releases between the record and the candidate that a landing
/// must pass through.
pub intermediate: Vec<IntermediateFact>,
/// The evidence the axes rest on.
pub evidence_refs: Vec<String>,
}
/// The generator axis, as observed.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct GeneratorFact {
/// The tool, as `versions.toml` names it.
pub name: String,
/// The version the candidate bundle pins.
pub pin: String,
/// The committed artifact it regenerates.
pub artifact: String,
/// The version found on the host, where one was.
#[serde(skip_serializing_if = "Option::is_none")]
pub host: Option<String>,
}
/// The forge axis, as declared and observed.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct ForgeFloor {
/// The forge.
pub forge: String,
/// The floor the bundle declares.
pub minimum: String,
/// The version the forge reported, where it was asked.
#[serde(skip_serializing_if = "Option::is_none")]
pub observed: Option<String>,
}
/// One release the landing must pass through.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct IntermediateFact {
/// The version.
pub version: String,
/// Why it cannot be skipped.
pub reason: String,
}
/// The guidance the bundle carries for this target.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct Guidance {
/// How much of the interval the bundle describes.
pub coverage: Coverage,
/// The releases the selection spans, where a record bounds it.
#[serde(skip_serializing_if = "Option::is_none")]
pub interval: Option<Interval>,
/// The steps that concern a destination this target has, in version
/// order.
pub steps: Vec<GuidanceStep>,
/// How many steps in the interval concern no destination here.
pub excluded: usize,
/// The evidence the selection rests on.
pub evidence_refs: Vec<String>,
}
/// How much of the interval the bundle describes. `covered` with no step
/// is "no applicable steps", and it is not `unavailable`.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[serde(tag = "state", rename_all = "kebab-case")]
pub enum Coverage {
/// No record bounds an interval, so there is nothing to describe.
NotNeeded,
/// Every release in the interval is described.
Covered,
/// The interval reaches below the release the bundle describes from.
Partial {
/// The release above which the bundle describes every release.
since: String,
},
/// The bundle carries no guidance at all.
Unavailable,
}
/// The releases a selection spans: above `from`, up to and including
/// `to`.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct Interval {
/// The recorded release.
pub from: String,
/// The candidate release.
pub to: String,
}
/// One release's step, as the target needs it.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct GuidanceStep {
/// The release that introduced the change.
pub version: String,
/// The file's heading.
pub title: String,
/// The landed paths it concerns, all of them, as authored.
pub destinations: Vec<String>,
/// `operator-step` or `plan-operation`.
pub action: String,
/// The authored text below the fields.
pub body: String,
}
/// One question the operator owns.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct Decision {
/// A stable id that survives re-planning.
pub id: String,
/// The question, one line.
pub question: String,
/// The answers, each with its consequence.
pub choices: Vec<Choice>,
/// The answer selected, where one is.
#[serde(skip_serializing_if = "Option::is_none")]
pub selected: Option<String>,
}
/// One answer to a decision.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct Choice {
/// The answer word.
pub answer: String,
/// What selecting it means.
pub consequence: String,
}
/// Every decision this engine asks, with the closed set of answers each
/// one takes.
///
/// A decision is a question the operator owns, and its choices are the
/// whole of what answers it. The catalogue is the one place that pairing
/// lives, so the parse that reads `--decide` and the evaluation that
/// judges a stored answer agree by construction. A decision the planner
/// adds without an entry here fails
/// [`every_decision_the_planner_asks_is_in_the_catalogue`].
pub const DECISION_CHOICES: [(&str, &[&str]); 6] = [
("workflow-mode", &["worktree", "branches"]),
("release-style", &["trunk", "lines"]),
("release-activity", &["history", "migrate"]),
("partial-baseline", &["accept", "fetch"]),
(guidance::PARTIAL_GUIDANCE_DECISION, &["accept"]),
(compatibility::PIN_MANAGER_DECISION, &["wire", "host"]),
];
/// The answers one decision takes, where the catalogue names it.
#[must_use]
pub fn decision_choices(id: &str) -> Option<&'static [&'static str]> {
DECISION_CHOICES
.iter()
.find(|(known, _)| *known == id)
.map(|(_, choices)| *choices)
}
/// Whether `answer` is one this decision declares.
///
/// An id the catalogue does not name answers `false`: an unknown
/// decision has no answer that satisfies it.
#[must_use]
pub fn decision_answered(id: &str, answer: Option<&str>) -> bool {
match (decision_choices(id), answer) {
(Some(choices), Some(answer)) => choices.contains(&answer),
_ => false,
}
}
/// One typed check an apply runs at the end and reports.
#[derive(Debug, Clone, Serialize, Deserialize)]
#[serde(tag = "check", rename_all = "kebab-case")]
pub enum Postcondition {
/// The record reads back at the planned digest.
RecordReadsBack {
/// The planned digest.
sha256: Digest,
},
/// A destination holds the planned bytes.
DestinationHolds {
/// The destination.
path: String,
/// The planned digest.
sha256: Digest,
},
/// `rk status --check` exits 0.
StatusCheckClean,
/// The wired manager records the planned version.
PinReads {
/// The manager.
manager: String,
/// The planned version.
version: String,
},
}
/// One request to compute a plan, as the store keeps it beside the plan
/// so an apply can compute the same plan again and compare.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct PlanRequest {
/// The target, absolute and symlink-resolved, so a stored plan names
/// one checkout and never whichever directory an apply runs in.
pub target: camino::Utf8PathBuf,
/// What the caller asked the plan to be.
pub intent: Intent,
/// The selector as given: `embedded`, `latest`, or an exact version.
pub selector: String,
/// Whether a recorded release the cache does not hold is fetched.
pub fetch: bool,
/// Whether the forge is read.
pub observe_forge: bool,
/// The explicit answers.
pub flags: gather::Flags,
/// The decisions selected, by id.
pub decisions: BTreeMap<String, String>,
}
impl PlanRequest {
/// The same request with its target resolved to an absolute,
/// symlink-free path.
///
/// Every construction site takes this before the request reaches the
/// planner or the store. A relative target would otherwise resolve
/// against whichever directory an apply runs in, so a plan approved
/// against one checkout could land in another whose content happens
/// to match, which the fingerprint alone cannot catch.
///
/// # Errors
///
/// [`RkError::Usage`] where the target does not exist or cannot be
/// resolved, and [`RkError::Other`] where the resolved path is not
/// valid UTF-8.
pub fn canonicalized(mut self) -> Result<Self, crate::error::RkError> {
self.target = canonical_target(&self.target)?;
Ok(self)
}
}
/// One target directory as an absolute, symlink-free path.
///
/// # Errors
///
/// [`RkError::Usage`] where the path does not exist or cannot be
/// resolved, and [`RkError::Other`] where it is not valid UTF-8.
pub fn canonical_target(
target: &camino::Utf8Path,
) -> Result<camino::Utf8PathBuf, crate::error::RkError> {
let resolved = std::fs::canonicalize(target).map_err(|error| {
crate::error::RkError::Usage(format!(
"the target {target} does not resolve to a directory: {error}"
))
})?;
camino::Utf8PathBuf::from_path_buf(resolved).map_err(|path| {
crate::error::RkError::Other(anyhow::anyhow!(
"the target resolves to {}, which is not valid UTF-8",
path.display()
))
})
}
/// A computed plan with the bytes its operations name, and what the
/// three-way comparison decided per destination, for the fronts that
/// render a per-file report.
#[derive(Debug)]
pub struct Planned {
/// The plan.
pub plan: Plan,
/// Every byte the plan names, by digest: what an operation writes,
/// what a destination holds now, and the baseline where it was read.
pub blobs: BTreeMap<Digest, Vec<u8>>,
/// What the comparison decided for each projected destination, in
/// projection order.
pub outcomes: Vec<DestinationOutcome>,
/// The configuration an apply writes, where the parameters resolved.
pub config: Option<crate::config::Plan>,
/// The Nix destinations withheld at this target, each with why.
pub withheld: Vec<crate::landing::Withheld>,
}
/// What the three-way comparison decided for one projected destination.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct DestinationOutcome {
/// The destination, relative to the target.
pub path: String,
/// The kind the candidate declares.
pub kind: Kind,
/// Whether the record names it.
pub recorded: bool,
/// What happens to it.
pub disposition: Disposition,
}
/// The closed set of things the comparison decides for a destination.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum Disposition {
/// The candidate's bytes are written.
Write,
/// The destination already holds what the candidate would write, or
/// what the record left there.
Unchanged,
/// The target's own bytes stay: a seeded or state file it tuned.
Kept,
/// A recorded seeded file moved away from its baseline and stays.
Drift,
/// A recorded state file, never compared.
State,
/// The target edited a file release-kit owns.
Conflict,
/// The record names a file the disk does not hold.
Missing,
}
impl Disposition {
/// The word a report prints.
#[must_use]
pub const fn as_str(self) -> &'static str {
match self {
Self::Write => "write",
Self::Unchanged => "unchanged",
Self::Kept => "kept",
Self::Drift => "drift",
Self::State => "state",
Self::Conflict => "conflict",
Self::Missing => "missing",
}
}
}
#[cfg(test)]
mod tests {
use std::collections::BTreeMap;
use super::{
BaselineState, BundleIdentity, Choice, Classification, Compatibility, Configuration,
ConfigurationState, Coverage, DECISION_CHOICES, Decision, DesiredState, Destination,
Evaluation, ForgeFloor, ForgeState, GeneratorFact, Guidance, GuidanceStep, Host, Identity,
Installation, Intent, IntermediateFact, Interval, Operation, PLAN_SCHEMA, PinState, Plan,
Postcondition, Precondition, Readiness, RecordState, Release, Repository, Requirement,
ResolvedRelease, Verdict, Verification, decision_answered, decision_choices,
};
use crate::digest::Digest;
use crate::landing::Kind;
use crate::plan::classify::Finding;
use crate::plan::evidence::{EvidenceItem, EvidenceKind};
/// The complete `rk.plan/3` shape, every section present, held by
/// snapshot: a field rename or removal fails here and becomes a
/// deliberate schema bump.
#[test]
#[allow(
clippy::too_many_lines,
reason = "the snapshot builds every section of the plan once, and cutting it would hide a section from the one test that holds the shape"
)]
fn the_plan_schema_is_versioned_and_snapshot_tested() {
let a = Digest::of(b"a");
let b = Digest::of(b"b");
let plan = Plan {
schema: PLAN_SCHEMA.into(),
identity: Identity {
plan_id: "0123456789abcdef".into(),
created_at: "2026-01-01T00:00:00Z".into(),
engine_version: "0.0.0".into(),
},
classification: Classification::Upgrade,
findings: vec![Finding {
code: "payload-collision".into(),
detail: "SECURITY.md".into(),
}],
desired_state: DesiredState {
intent: Intent::Reconcile,
selector: "embedded".into(),
release: ResolvedRelease {
version: "0.0.0".into(),
venue: "embedded".into(),
payload_sha256: a.clone(),
payload_schema: 1,
},
configuration: Some(Configuration {
tech: "rust".into(),
forge: "github".into(),
repo: "acme/widget".into(),
workflow: "worktree".into(),
style: Some("trunk".into()),
nix: false,
trunk: "master".into(),
line_prefix: "release/".into(),
security_contact: String::new(),
security_response: "best-effort".into(),
sources: BTreeMap::from([("tech".to_owned(), "record".to_owned())]),
evidence_refs: vec!["record".into()],
}),
unresolved: None,
},
observed_state: super::ObservedState {
repository: Repository {
target: "/tmp/t".into(),
git: true,
tags: 0,
long_lived_branches: vec![],
release_markers: vec![],
collisions: vec!["SECURITY.md".into()],
tech: Some("rust".into()),
forge: Some("github".into()),
repo: Some("acme/widget".into()),
verdict: Verdict::Brownfield,
evidence_refs: vec!["repository".into()],
},
installation: Installation {
record: RecordState::Present {
rk_version: "0.0.0".into(),
payload_sha256: a.clone(),
schema_version: 6,
origin: "init".into(),
sha256: b.clone(),
},
configuration: ConfigurationState {
present: true,
sha256: Some(b.clone()),
invalid: None,
pending: vec![],
},
destinations: vec![Destination {
path: "SECURITY.md".into(),
present: true,
sha256: Some(a.clone()),
recorded_kind: Some(Kind::Rendered),
}],
evidence_refs: vec!["record".into(), "configuration".into()],
},
host: Host {
engine_version: "0.0.0".into(),
pin: Some(PinState {
manager: "mise".into(),
file: "mise.toml".into(),
version: "0.0.0".into(),
}),
evidence_refs: vec!["host".into()],
},
forge: ForgeState::NotObserved {
reason: "not requested".into(),
},
},
release: Release {
candidate: BundleIdentity {
version: "0.0.0".into(),
payload_sha256: a.clone(),
payload_schema: 1,
artifacts: 1,
evidence_refs: vec!["candidate-bundle".into()],
},
verification: Verification::Embedded,
baseline: BaselineState::Embedded,
compatibility: Compatibility {
engine_schema: 1,
bundle_schema: 1,
readable: true,
engine_minimum: Some("0.0.0".into()),
generator: Some(GeneratorFact {
name: "cargo-dist".into(),
pin: "0.32.0".into(),
artifact: "dist-workspace.toml".into(),
host: Some("0.32.0".into()),
}),
forge_floor: Some(ForgeFloor {
forge: "gitlab".into(),
minimum: "18.2".into(),
observed: Some("18.2.0".into()),
}),
intermediate: vec![IntermediateFact {
version: "0.0.0".into(),
reason: "the record changed shape".into(),
}],
evidence_refs: vec!["candidate-bundle".into()],
},
guidance: Guidance {
coverage: Coverage::Partial {
since: "0.0.0".into(),
},
interval: Some(Interval {
from: "0.0.0".into(),
to: "0.0.0".into(),
}),
steps: vec![GuidanceStep {
version: "0.0.0".into(),
title: "release-kit 0.0.0".into(),
destinations: vec![".envrc".into()],
action: "operator-step".into(),
body: "## What to do".into(),
}],
excluded: 1,
evidence_refs: vec!["candidate-bundle".into()],
},
},
operations: vec![Operation::WriteRecord {
before: Some(b.clone()),
after: a.clone(),
}],
preconditions: vec![Precondition {
id: "record-readable".into(),
requirement: Requirement::Required,
evaluation: Evaluation::Satisfied,
decision: None,
evidence_refs: vec!["record".into()],
}],
decisions: vec![Decision {
id: "workflow-mode".into(),
question: "which working-copy mode".into(),
choices: vec![Choice {
answer: "worktree".into(),
consequence: "every branch in a linked worktree".into(),
}],
selected: Some("worktree".into()),
}],
postconditions: vec![Postcondition::RecordReadsBack { sha256: a.clone() }],
evidence: vec![EvidenceItem {
id: "record".into(),
kind: EvidenceKind::Record,
producer: "rk".into(),
observed_at: "2026-01-01T00:00:00Z".into(),
sha256: Some(b.clone()),
method: "read".into(),
}],
readiness: Readiness::Ready,
input_fingerprint: a.clone(),
};
let json = serde_json::to_string(&plan).expect("a plan serializes");
let expected = format!(
r###"{{"schema":"rk.plan/3","identity":{{"plan_id":"0123456789abcdef","created_at":"2026-01-01T00:00:00Z","engine_version":"0.0.0"}},"classification":"upgrade","findings":[{{"code":"payload-collision","detail":"SECURITY.md"}}],"desired_state":{{"intent":"reconcile","selector":"embedded","release":{{"version":"0.0.0","venue":"embedded","payload_sha256":"{a}","payload_schema":1}},"configuration":{{"tech":"rust","forge":"github","repo":"acme/widget","workflow":"worktree","style":"trunk","nix":false,"trunk":"master","line_prefix":"release/","security_contact":"","security_response":"best-effort","sources":{{"tech":"record"}},"evidence_refs":["record"]}}}},"observed_state":{{"repository":{{"target":"/tmp/t","git":true,"tags":0,"long_lived_branches":[],"release_markers":[],"collisions":["SECURITY.md"],"tech":"rust","forge":"github","repo":"acme/widget","verdict":"brownfield","evidence_refs":["repository"]}},"installation":{{"record":{{"state":"present","rk_version":"0.0.0","payload_sha256":"{a}","schema_version":6,"origin":"init","sha256":"{b}"}},"configuration":{{"present":true,"sha256":"{b}","pending":[]}},"destinations":[{{"path":"SECURITY.md","present":true,"sha256":"{a}","recorded_kind":"rendered"}}],"evidence_refs":["record","configuration"]}},"host":{{"engine_version":"0.0.0","pin":{{"manager":"mise","file":"mise.toml","version":"0.0.0"}},"evidence_refs":["host"]}},"forge":{{"state":"not-observed","reason":"not requested"}}}},"release":{{"candidate":{{"version":"0.0.0","payload_sha256":"{a}","payload_schema":1,"artifacts":1,"evidence_refs":["candidate-bundle"]}},"verification":{{"method":"embedded"}},"baseline":{{"state":"embedded"}},"compatibility":{{"engine_schema":1,"bundle_schema":1,"readable":true,"engine_minimum":"0.0.0","generator":{{"name":"cargo-dist","pin":"0.32.0","artifact":"dist-workspace.toml","host":"0.32.0"}},"forge_floor":{{"forge":"gitlab","minimum":"18.2","observed":"18.2.0"}},"intermediate":[{{"version":"0.0.0","reason":"the record changed shape"}}],"evidence_refs":["candidate-bundle"]}},"guidance":{{"coverage":{{"state":"partial","since":"0.0.0"}},"interval":{{"from":"0.0.0","to":"0.0.0"}},"steps":[{{"version":"0.0.0","title":"release-kit 0.0.0","destinations":[".envrc"],"action":"operator-step","body":"## What to do"}}],"excluded":1,"evidence_refs":["candidate-bundle"]}}}},"operations":[{{"op":"write-record","before":"{b}","after":"{a}"}}],"preconditions":[{{"id":"record-readable","requirement":"required","evaluation":{{"state":"satisfied"}},"evidence_refs":["record"]}}],"decisions":[{{"id":"workflow-mode","question":"which working-copy mode","choices":[{{"answer":"worktree","consequence":"every branch in a linked worktree"}}],"selected":"worktree"}}],"postconditions":[{{"check":"record-reads-back","sha256":"{a}"}}],"evidence":[{{"id":"record","kind":"record","producer":"rk","observed_at":"2026-01-01T00:00:00Z","sha256":"{b}","method":"read"}}],"readiness":"ready","input_fingerprint":"{a}"}}"###
);
assert_eq!(json, expected);
}
/// Every decision the planner asks carries its choices in the
/// catalogue, and every catalogued answer is one a choice declares.
///
/// The catalogue is what the parse and the evaluation both read, so
/// a decision added to the planner without an entry here would take
/// any answer at the parse and satisfy nothing at the evaluation.
#[test]
fn every_decision_the_planner_asks_is_in_the_catalogue() {
let sources = [
include_str!("planner.rs"),
include_str!("compatibility.rs"),
include_str!("guidance.rs"),
];
// Every id the catalogue names is asked somewhere, so an entry
// does not outlive the decision it describes.
for (id, choices) in DECISION_CHOICES {
assert!(
sources.iter().any(|source| source.contains(id)),
"the catalogue names {id} and no module asks it"
);
assert!(!choices.is_empty(), "{id} declares no answer");
for answer in choices {
assert!(
decision_answered(id, Some(answer)),
"{id} does not take its own declared answer {answer}"
);
}
assert!(
!decision_answered(id, Some("not-a-declared-answer")),
"{id} takes an answer it does not declare"
);
}
assert!(decision_choices("not-a-decision").is_none());
assert!(!decision_answered("not-a-decision", Some("anything")));
}
}