fix(planner): a source: file's CONTENT is part of the desired state (Refs #206)

[noahgift]

Fixes #206.

The bug

hash_desired_state hashes resource field strings. For content: that's correct — the content is the field. For source: the field is a path, so editing the referenced file left the hash identical, determine_present_action planned NoOp, and apply skipped the resource:

$ echo VERSION-ONE > payload.txt && forjar apply --yes
Apply complete: 1 converged, 0 unchanged.

$ echo VERSION-TWO > payload.txt && forjar apply --yes
Apply complete: 0 converged, 1 unchanged.

$ cat /tmp/deployed
VERSION-ONE          # <- stale

--force was the only workaround. For a tool whose entire contract is "converge to declared state", silently not converging while printing success is the worst available failure mode.

Found live in paiml/infra PMAT-204 — an edited reconciler script reported "converged" three times while the machine kept executing the previous copy. Same class as the ENOSPC incident there, where a systemd unit was edited but never actually deployed.

The fix

Fold the source file's content hash into the desired state via canonical_source_content(), following the existing canonical_overlay_hosts() pattern — whose doc comment already states this exact invariant for a different field:

two overlay_interface resources differing ONLY in overlay_hosts MUST hash differently or plan will false-report NoOp

source: was violating the same rule.

Care taken:

• Appended, never inserted. Field order is hash identity; a reorder would invalidate every recorded hash on every machine in the fleet.
• Pushed only when source: is present, so source-less resources keep their hash exactly.
• Path read as written, matching resources::file::source_file_base64 — both resolve against the process CWD — so the planner hashes precisely the bytes apply would upload.
• Unreadable sources fold their error in rather than hashing as absent, so a file appearing/disappearing changes the hash instead of staying pinned at "unchanged".

Verification

End-to-end, with the installed fixed binary:

$ forjar plan   # after editing the source
  ~ repro-file: update (state changed)
Plan: 0 to add, 1 to change, 0 to destroy, 0 unchanged.

$ forjar apply --yes        # NO --force
Apply complete: 1 converged, 0 unchanged.
$ cat /tmp/deployed
VERSION-TWO                 # correct

$ forjar apply --yes        # fixed point still holds
Apply complete: 0 converged, 1 unchanged.

New tests	5 in tests_hash_source.rs (RED-verified before the fix)
Full lib suite	12596 passed, 0 failed
cargo fmt --check	clean
cargo clippy	clean
TDG quality gates	no regressions
pv validate new contract	0 errors, 0 warnings

Contract

contracts/source-content-identity-v1.yaml — the completeness leg of idempotent-apply-v1. That contract asserts "differing hash always plans Update": sound, but vacuous if the hash cannot differ when the deployed artifact differs.

It deliberately declares no Kani harness. The property quantifies over filesystem contents, which is outside Kani's model — a harness could only prove something about a stubbed read, i.e. prove nothing about this bug. The 7 falsification tests discharge the obligations instead, including an end-to-end one that reproduces the reported defect.

Upgrade note

Source-based file resources will show one Update on the first apply after upgrading, as their hash gains the new component. That re-apply is convergent and expected.

Released as 1.12.3.

🤖 Generated with Claude Code