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

`hash_desired_state` hashes resource FIELD STRINGS. For `content:` that is
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 box kept executing the previous copy. That is
the same class as the ENOSPC incident there, where a systemd unit was edited but
never actually deployed.

The planner now folds the content hash of the source file 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 resources differing ONLY in that field MUST
hash differently or plan will false-report NoOp.

Care taken:
  * The component is APPENDED, never inserted. Field order is hash identity;
    a reorder would invalidate every recorded hash on every machine.
  * It is pushed ONLY when `source:` is present, so source-less resources keep
    their existing hash exactly.
  * The path is 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.
  * An unreadable source folds its error in rather than hashing as absent, so a
    file appearing or disappearing changes the hash instead of staying pinned at
    "unchanged".

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

Verified end-to-end with the fixed binary: plan reports "update (state
changed)", apply deploys the new bytes with NO --force, and a third apply
returns to "unchanged" - the fixed point still holds.

Tests: 5 new in tests_hash_source.rs (content change, determinism, path
identity, source appearance, source-less non-regression). Full suite 12596
passed / 0 failed.

Contract: contracts/source-content-identity-v1.yaml - the completeness leg of
idempotent-apply-v1, which asserts "differing hash always plans Update": sound,
but vacuous if the hash cannot differ when the deployed artifact differs.
Deliberately declares NO Kani harness: the property quantifies over filesystem
contents, which is outside Kani's model, so a harness could only prove something
about a stubbed read. pv validate: 0 errors, 0 warnings.

Closes #206

Co-authored-by: Claude Opus 5 <noreply@anthropic.com>

Author: noahgift

CHANGELOG.md

@@ -7,6 +7,53 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [1.12.3] - 2026-08-10
+
+### Fixed
+
+- **`apply` deployed stale content while reporting "unchanged"** when a file
+  resource's `source:` file changed ([#206](https://github.com/paiml/forjar/issues/206)).
+
+  `hash_desired_state` hashes resource *field strings*. For `content:` that is
+  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:
+
+  ```console
+  $ echo VERSION-ONE > payload.txt && forjar apply -f repro.yaml --yes
+  Apply complete: 1 converged, 0 unchanged.
+  $ echo VERSION-TWO > payload.txt && forjar apply -f repro.yaml --yes
+  Apply complete: 0 converged, 1 unchanged.
+  $ cat /tmp/deployed          # -> VERSION-ONE   (stale)
+  ```
+
+  `--force` was the only workaround. For a tool whose contract is "converge to
+  declared state", silently not converging while printing success is the worst
+  available failure mode. Observed live in paiml/infra PMAT-204, where an edited
+  reconciler script reported "converged" three times while the machine kept
+  executing the previous copy.
+
+  The planner now folds the **content hash** of the `source:` file into the
+  desired state. The component is **appended**, and only for resources that
+  declare `source:`, so no recorded hash for any other resource on any machine is
+  invalidated. Path identity is preserved (same bytes at different paths still
+  hash differently), and a source that appears or disappears now changes the hash
+  rather than staying pinned at "unchanged".
+
+  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.
+
+### Added
+
+- `contracts/source-content-identity-v1.yaml` — the **completeness** leg of
+  `idempotent-apply-v1`. That contract asserts "differing hash always plans
+  Update", which is sound but vacuous if the hash cannot differ when the deployed
+  artifact differs. 7 falsification tests, including an end-to-end reproduction.
+- `src/core/planner/tests_hash_source.rs` — 5 tests covering content change,
+  determinism, path identity, source appearance, and non-regression of
+  source-less resources.
+
 ## [1.12.2] - 2026-07-29
 
 Four design defects, each one a place where forjar reported on something other

Cargo.lock

@@ -1,6 +1,6 @@
 [package]
 name = "forjar"
-version = "1.12.2"
+version = "1.12.3"
 edition.workspace = true
 rust-version = "1.89.0"
 authors = ["Pragmatic AI Labs"]

Cargo.toml

@@ -0,0 +1,152 @@
+---
+metadata:
+  version: "1.0.0"
+  kind: pattern
+  created: "2026-08-10"
+  author: "PAIML Engineering"
+  description: |
+    Source-content identity — the BYTES a `source:` names are part of the
+    desired state, not just the path string.
+
+    hash_desired_state hashes resource FIELD STRINGS. For `content:` that is
+    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` printed "unchanged" over stale content on the
+    machine.
+
+    This is the completeness leg of idempotent-apply-v1. That contract asserts
+    "Converged lock entry with differing hash always plans Update", which is
+    sound but vacuous if the hash cannot differ when the deployed artifact
+    differs. A declarative tool that reports success while not converging is
+    strictly worse than one that fails loudly.
+
+    IMPLEMENTATION NOTES
+
+    canonical_source_content returns the empty string when `source:` is absent,
+    and the component is pushed only when non-empty — APPENDING, never inserting,
+    because field order is hash identity and a reorder would invalidate every
+    recorded hash on every machine in the fleet.
+
+    The path is read exactly as written, matching resources::file's own
+    source_file_base64: both resolve relative to the process CWD, so the planner
+    hashes precisely the bytes that apply would upload.
+
+    An unreadable source folds its error into the component rather than hashing
+    as absent, so a file that appears or disappears changes the hash instead of
+    masquerading as "unchanged"; apply still fails loudly with
+    "cannot read source file".
+
+    Failure mode is plan_update rather than an assert: when the bytes differ the
+    resource simply plans Update, which is the correct convergent behaviour.
+
+    NO KANI HARNESS, DELIBERATELY. The property quantifies over the CONTENTS OF
+    THE FILESYSTEM, which is outside Kani's model — a harness here could only
+    prove something about a stubbed read, i.e. prove nothing about the bug. The
+    obligations are discharged by the seven falsification tests instead, of which
+    FALSIFY-SRC-006 is the end-to-end one that actually reproduces the reported
+    defect. Declaring an unrunnable harness to satisfy a schema would be exactly
+    the vacuous-contract failure this repo's review process exists to catch.
+  references:
+    - "issue: https://github.com/paiml/forjar/issues/206"
+    - "idempotent-apply-v1.yaml — the soundness leg this completes"
+    - "paiml/infra PMAT-204 — observed live: an edited reconciler script reported
+       'converged' three times while the machine kept running the previous copy"
+    - "src/core/planner/hashing.rs — canonical_source_content"
+
+equations:
+  source_content_identity:
+    formula: |
+      ∀ r ∈ Resource with r.source = Some(p):
+        bytes(p) ≠ bytes'(p) ⟹ hash_desired_state(r) ≠ hash_desired_state'(r)
+    domain: "r ∈ Resource, p ∈ Path"
+    codomain: "String ('blake3:' || hex digest)"
+    invariants:
+      - "Changing the bytes at `source:` changes the desired-state hash"
+      - "Identical bytes at an identical path hash identically (determinism)"
+      - "Identical bytes at DIFFERENT paths hash differently: the path remains
+         part of resource identity"
+      - "A source file appearing or disappearing changes the hash"
+
+  source_free_stability:
+    formula: |
+      ∀ r ∈ Resource with r.source = None:
+        hash_desired_state_after(r) = hash_desired_state_before(r)
+    domain: "r ∈ Resource without a source field"
+    codomain: "String"
+    invariants:
+      - "Resources without `source:` keep their pre-existing hash: the content
+         component is APPENDED and only when non-empty, so no recorded hash on
+         any machine in the fleet is invalidated"
+
+proof_obligations:
+  - type: completeness
+    property: "A change to deployed bytes is always observable in the hash"
+    formal: "bytes(p) ≠ bytes'(p) ⟹ hash ≠ hash'"
+    tolerance: 0.0
+    applies_to: "file resources declaring source:"
+  - type: determinism
+    property: "Hashing the same resource over unchanged bytes is stable"
+    formal: "hash_desired_state(r) = hash_desired_state(r)"
+    tolerance: 0.0
+    applies_to: all
+  - type: independence
+    property: "Path identity survives content equality"
+    formal: "p ≠ q ∧ bytes(p) = bytes(q) ⟹ hash(r_p) ≠ hash(r_q)"
+    tolerance: 0.0
+    applies_to: "file resources declaring source:"
+  - type: invariant
+    property: "Source-less resources retain their existing hash identity"
+    formal: "r.source = None ⟹ hash unchanged across this change"
+    tolerance: 0.0
+    applies_to: "resources without source:"
+
+falsification_tests:
+  - id: FALSIFY-SRC-001
+    rule: "Source content change is observable"
+    prediction: "Rewriting a source file changes hash_desired_state"
+    test: "src/core/planner/tests_hash_source.rs::source_content_change_changes_desired_hash"
+    if_fails: "plan reports NoOp and apply deploys stale content while printing 'unchanged'"
+  - id: FALSIFY-SRC-002
+    rule: "Determinism preserved"
+    prediction: "Two hashes over unchanged bytes are equal"
+    test: "src/core/planner/tests_hash_source.rs::identical_source_content_hashes_identically"
+    if_fails: "every apply re-uploads every source file — spurious churn, no fixed point"
+  - id: FALSIFY-SRC-003
+    rule: "Path remains part of identity"
+    prediction: "Same bytes at two paths hash differently"
+    test: "src/core/planner/tests_hash_source.rs::two_sources_with_same_content_but_different_paths_differ"
+    if_fails: "two resources collide whenever their sources happen to match"
+  - id: FALSIFY-SRC-004
+    rule: "Appearance of a source file is observable"
+    prediction: "missing → present changes the hash"
+    test: "src/core/planner/tests_hash_source.rs::missing_source_is_distinguishable_from_present_source"
+    if_fails: "a resource stays pinned at 'unchanged' after its source appears"
+  - id: FALSIFY-SRC-005
+    rule: "Source-less resources unaffected"
+    prediction: "package and inline-content resources hash as before"
+    test: "src/core/planner/tests_hash_source.rs::resource_without_source_is_unaffected"
+    if_fails: "every recorded hash on every machine in the fleet is invalidated"
+  - id: FALSIFY-SRC-006
+    rule: "End-to-end convergence"
+    prediction: "apply → edit source → apply deploys the NEW bytes without --force"
+    test: "manual: see contracts/README or the GH-206 reproduction; asserts deployed
+           content equals the edited source after a second plain apply"
+    if_fails: "the user-visible bug is still present regardless of unit-test status"
+  - id: FALSIFY-SRC-007
+    rule: "No regression in the existing suite"
+    prediction: "cargo test --lib reports 0 failures"
+    test: "cargo test --lib"
+    if_fails: "hash identity change broke planner, lock, or drift behaviour"
+
+qa_gate:
+  id: F-SRC-001
+  name: "Source Content Identity Contract"
+  description: "The bytes behind `source:` are part of the desired state"
+  checks:
+    - "source_content_identity"
+    - "source_free_stability"
+  pass_criteria: "All 7 falsification tests pass, including the end-to-end reproduction"
+  falsification: "Revert canonical_source_content to hashing only the path string;
+                  FALSIFY-SRC-001 and -004 must then fail"
+
+verification_level: L3

contracts/source-content-identity-v1.yaml

@@ -120,14 +120,56 @@ fn collect_phase2_fields<'a>(
 /// Compute a hash of the desired state for comparison.
 ///
 /// FJ-2200: Contract — determinism: same resource always produces same hash.
+/// GH-206: fold the CONTENT of a `source:` file into the desired state.
+///
+/// `source:` names a PATH, but the bytes it points at are what actually gets
+/// deployed. Hashing only the path meant editing the referenced file left the
+/// hash identical, so `plan` reported `NoOp` and `apply` skipped the resource
+/// while printing "unchanged" over stale content on the machine. For a tool
+/// whose entire contract is "converge to declared state", silently not
+/// converging while reporting success is the worst available failure mode.
+/// Observed live in paiml/infra PMAT-204.
+///
+/// This is exactly the invariant `canonical_overlay_hosts` below already states
+/// for a different field: two resources differing ONLY in that field MUST hash
+/// differently or `plan` will false-report `NoOp`.
+///
+/// Returns an EMPTY string when there is no `source:`, so nothing is appended
+/// and every source-less resource keeps its existing hash. Field order is hash
+/// identity; only resources that declare `source:` gain a component.
+///
+/// The path is read exactly as written, matching `resources::file`'s own
+/// `source_file_base64` - both resolve relative to the process CWD - so the
+/// planner hashes precisely the bytes apply would upload.
+fn canonical_source_content(resource: &Resource) -> String {
+    let Some(src) = resource.source.as_deref() else {
+        return String::new();
+    };
+    match hasher::hash_file(std::path::Path::new(src)) {
+        Ok(digest) => format!("source_content:{digest}"),
+        // Unreadable is itself part of the observed state: fold the error kind
+        // in so a source file appearing or disappearing changes the hash rather
+        // than leaving the resource pinned at "unchanged". apply still fails
+        // loudly with "cannot read source file".
+        Err(e) => format!("source_unreadable:{src}:{e}"),
+    }
+}
+
 pub fn hash_desired_state(resource: &Resource) -> String {
     let type_str = resource.resource_type.to_string();
     // Owned canonicalization of overlay_hosts; kept alive for the borrow below.
     let overlay_hosts_canon = canonical_overlay_hosts(resource);
+    // Owned; kept alive for the borrow below. Empty when there is no `source:`.
+    let source_content_canon = canonical_source_content(resource);
     let mut components: Vec<&str> = vec![&type_str];
 
     collect_core_fields(&mut components, resource);
     collect_phase2_fields(&mut components, resource, &overlay_hosts_canon);
+    // APPENDED last on purpose: inserting or reordering would invalidate every
+    // recorded hash on every machine (see the module header).
+    if !source_content_canon.is_empty() {
+        components.push(&source_content_canon);
+    }
 
     let joined = components.join("\0");
     let result = hasher::hash_string(&joined);

src/core/planner/hashing.rs

@@ -384,6 +384,8 @@ mod tests_hash;
 #[cfg(test)]
 mod tests_hash_b;
 #[cfg(test)]
+mod tests_hash_source;
+#[cfg(test)]
 mod tests_helpers;
 #[cfg(test)]
 mod tests_lifecycle;