FM-401: observed-state normalization, the difference model, and the planner

[Andreas-Froyland]

Closes #90 (FM-401). Part of epic #6.

What

• Difference model (fleet-core/src/difference.rs): the documented drift vocabulary — missing, extra, changed, unknown, unsupported — with one comparison point (compare_field) every normalizer funnels through. unknown and unsupported are honest terminal states: never coerced into changed, never actionable, and an unknown blocks the readiness claim while an unsupported field is reported without blocking it.
• Observed-state normalization (fleet-application/src/observed.rs): capability facts (tool presence + versions), checkout discoveries, and Skills Manager deployment status normalize into the desired resources' shapes through a provider-agnostic input surface. Normalization is total: every observation becomes a field value or an explicit unknown, never dropped silently. Desired tool sets are additive, not exclusive — an observed tool with no desired counterpart is not drift.
• Planner (fleet-application/src/planner.rs): a pure function from a difference set to dependency-ordered actions — clone before install before skills — with contiguous order numbering. unknown and unsupported differences are carried in the plan's unactionable list, reported and never acted on. The dry-run rendering is one serializer shared by the API, web, and fleetctl --output json, so the three surfaces cannot drift.
• No execution: the planner produces a plan document; nothing here creates an operation.

Tests

• Difference model: stable serialization of all five states, every comparison combination, actionability rules, canonicalization (sort + dedupe), convergence semantics.
• Normalization: fact shapes (versioned/unversioned tools), honest gaps, provider-agnostic checkout observations (unavailable is not an observation), per-agent skills, comparison coverage (match/change/missing/extra), unanswered inventory → honest unknown, converged machine → empty set.
• Planner: dependency order, contiguous numbering, unknown/unsupported refusal, purity (same set → same plan), dry-run round-trip, extra checkout plans a clone.

cargo xtask verify passes.

---

Summary by cubic

Implements FM-401's observed-state normalization, difference model, and apply planner so machine observations compare against desired resources into a five-state drift vocabulary and produce dependency-ordered dry-run plans. Closes #90.

Behavior

• Normalization is total: every observation becomes a field value or explicit unknown, and per-surface answered flags make an unanswered inventory, deployment status, or discovery an honest unknown, never an actionable absence.
• Tool facts keep their own availability — absent is always missing, regardless of any version string — and version output is canonicalized so an installed tool doesn't stay changed because of a command prefix.
• unknown and unsupported are terminal states: never planned, only unknown blocks readiness, and duplicate identities resolve toward these states so a planner can't act on a guess.
• Desired tool sets are additive; observed-only skills and checkouts are extra, and a checkout with no readable remote is unknown.
• The planner orders clone before install before skills; extra skills plan undeploy, while extra tools/checkouts and unresolved identities are reported as unsupported, never silently dropped.
• The plan is a document only, and one dry-run serializer is shared by the API, web, and fleetctl --output json.

Tests

• Adds coverage for the difference model, normalization edge cases, planner ordering and purity, and dry-run round-trip.

^{Written for commit d9591e3. Summary will update on new commits.}

[cubic-dev-ai]

All reported issues were addressed across 5 files

<sub>Reply with feedback, questions, or to request a fix.

Re-trigger cubic</sub>

[cubic-dev-ai]

2 issues found across 3 files (changes from recent commits).

Prompt for AI agents (unresolved issues)

Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="crates/fleet-application/src/observed.rs">

<violation number="1" location="crates/fleet-application/src/observed.rs:383">
P2: Custom agent: **Flag AI Slop and Fabricated Changes**

When no checkout is desired, a known checkout with `remote: None` is silently omitted because this loop only handles `Some(remote)`. Emit an explicit `unknown` for remote-less observations to preserve the module’s total-normalization contract.</violation>
</file>

<file name="crates/fleet-application/src/planner.rs">

<violation number="1" location="crates/fleet-application/src/planner.rs:305">
P2: Custom agent: **Flag AI Slop and Fabricated Changes**

The PR description says an extra checkout plans a clone, but this test now proves the shipped planner reports it as unsupported and creates no action. Update the PR description to describe the implemented behavior.</violation>
</file>

<sub>Reply with feedback, questions, or to request a fix.

Re-trigger cubic</sub>

[cubic-dev-ai]

P2: Custom agent: Flag AI Slop and Fabricated Changes

When no checkout is desired, a known checkout with remote: None is silently omitted because this loop only handles Some(remote). Emit an explicit unknown for remote-less observations to preserve the module’s total-normalization contract.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At crates/fleet-application/src/observed.rs, line 383:

<comment>When no checkout is desired, a known checkout with `remote: None` is silently omitted because this loop only handles `Some(remote)`. Emit an explicit `unknown` for remote-less observations to preserve the module’s total-normalization contract.</comment>

<file context>
@@ -155,69 +224,171 @@ pub fn normalize_skills(skill_id: &str, deployed_to: &[&str]) -> Vec<ObservedSki
+    if observed.checkouts_answered == Some(true) {
+        let desired_remote = desired.checkout.as_ref().map(|(remote, _)| remote);
+        for checkout in &observed.checkouts {
+            if let Some(remote) = &checkout.remote
+                && desired_remote != Some(remote)
+            {
</file context>

[cubic-dev-ai]

P2: Custom agent: Flag AI Slop and Fabricated Changes

The PR description says an extra checkout plans a clone, but this test now proves the shipped planner reports it as unsupported and creates no action. Update the PR description to describe the implemented behavior.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At crates/fleet-application/src/planner.rs, line 305:

<comment>The PR description says an extra checkout plans a clone, but this test now proves the shipped planner reports it as unsupported and creates no action. Update the PR description to describe the implemented behavior.</comment>

<file context>
@@ -268,12 +294,16 @@ mod tests {
         )]);
         let plan = plan(&set);
-        assert_eq!(plan.actions[0].kind, "projects.clone");
+        assert!(plan.actions.is_empty());
+        assert_eq!(plan.unactionable.len(), 1);
+        assert_eq!(plan.unactionable[0].state, DifferenceState::Unsupported);
</file context>

[Andreas-Froyland]

Amendment to the PR description: an extra checkout does NOT plan a clone — removing a checkout has no guarded path, so the planner classifies it as unsupported and reports it. The implemented behavior is proven by an_extra_checkout_is_reported_not_planned.

[cubic-dev-ai]

All reported issues were addressed across 2 files (changes from recent commits).

<sub>Tip: Review your code locally with the cubic CLI to iterate faster.

Re-trigger cubic</sub>