[taddyb]

The finding

ddrs plan fingerprinted a directory data source by hashing the sorted names of
its top-level entries. Every icechunk repository has the same top-level
entries (chunks, manifests, overwritten, repo, snapshots,
transactions), so the two committed Juniata stores

examples/juniata/data/juniata_qprime.ic
examples/juniata/data/juniata_obs.ic

both hashed to
blake3:b30974f8d1140506e419095f758f2e9ac0a22a6a4535e39d69d01eea6383c5b7. Two
different stores shared one fingerprint, and no content change inside any
directory source could ever be detected as drift: the lock recorded a name list,
not a version.

What this branch does

1. Icechunk repositories fingerprint as their main branch snapshot id.
   src/cli/fingerprint.rs::compute_fp detects an icechunk repo and returns
   fp = "icechunk:<snapshot id>" via the new
   src/data/store/icechunk.rs::main_branch_snapshot (a lookup_branch("main"),
   no Session, no zarr Store). The two Juniata stores now read
   icechunk:E0M3W6W1881H868V2KRG and icechunk:BPY4SW34FJGXWC3T806G. Because
   the fingerprint is the snapshot id, appending to a store shows up as drift
   on the next plan, which now prints one name: locked <fp> -> current <fp>
   line per source in both the warn path and the --strict abort path.

2. Any other directory store fingerprints by content shape. A recursive walk
   of relative paths and sizes, sorted, plus the bytes of the root metadata file
   (zarr.json / .zarray / .zgroup). Directory sources therefore always
   recompute rather than short-circuiting on (mtime, size): a directory's own
   mtime does not move when a chunk deep inside it does. Known limit, commented
   in the code and in the test: an in-place rewrite that preserves every file's
   length is invisible. Byte-hashing the multi-TB CONUS/global stores on every
   plan was the alternative, and the largest sources are icechunk, hence exact.

3. data_sources.pins (optional map, source name → snapshot id) opens
   streamflow and observations at VersionInfo::SnapshotId instead of the
   branch tip, so a run is reproducible after the store is appended to. Only
   those two names are pinnable (src/config.rs::validate_pins, a load-time
   error otherwise), and a pin on a path that sniffs as the zarr-v2 global
   product is refused at open (src/data/store/mod.rs::reject_pin_on_non_icechunk)
   rather than silently ignored. A malformed or absent id errors naming both the
   store path and the id.

4. The resolved snapshot is recorded whether or not the source is pinned.
   Fingerprint gained snapshot: Option<String>, written to
   .ddrs/sources.lock and to the run manifest as sources.<name>.snapshot;
   dataset open logs streamflow snapshot: <id> (pinned|main tip) next to the
   existing streamflow resolution: line. Every run from now on names the exact
   data version it read. The baseline reads the pinned version too
   (src/baseline/summed_q_prime.rs), so a pinned run is scored against a
   reference built from the same data, and
   src/baseline/cache.rs::cache_key now hashes the pins: re-pinning recomputes
   the summed-Q' baseline instead of reusing the previous snapshot's.

Backward compatibility

• snapshot is #[serde(default, skip_serializing_if = "Option::is_none")], so
  every existing sources.lock and run manifest.json still parses, and a
  snapshot-less fingerprint round-trips without emitting the key. Pinned by
  tests/cli_fingerprint.rs::fingerprint_json_without_snapshot_still_parses.
• Omitting pins: changes nothing: every source opens at the main tip exactly
  as before, and the unpinned baseline cache key is byte-identical to the one it
  has always had (the pins block is hashed only when present and non-empty, and
  BASELINE_ALGO_VERSION is deliberately not bumped, because the baseline
  computation did not change). No cached baseline under .ddrs/baselines/ is
  invalidated. Pinned by cache_key's three new unit tests, including a literal
  measured before the change.
• One-time consequence: existing sources.lock files will report drift once
  after this lands, because the fingerprint format for directory stores changed.
  That is expected. A ddrs plan relocks them; until it has, ddrs run --strict
  aborts with exit 4, and the new per-source drift lines make that abort
  self-explanatory.

Gates

Rebased onto master 419f307 (post #46/#47) before running any of these.

Gate	Result
cargo test --features fixtures --no-fail-fast (debug)	789 passed, 2 failed. The two are layer_b_step3_mc_forward_matches_ddr and layer_c_step2_gradients_match_ddr, both pre-existing on this workstation and green in CI. Nothing else failed.
cargo test --test ddr_sandbox_match --test gridded_bundle	ddr_sandbox_match 1 passed, gridded_bundle 5 passed
cargo run --release --example compare_ddr_sandbox	ABSOLUTE MATCH, max abs diff 1.526e-4 m³/s, max rel diff 2.41e-6
cargo test --release --test juniata_acceptance	routed NSE 0.7903 / KGE 0.8810, baseline NSE 0.6947 (the seed-42 reference values exactly)
python3 scripts/verify_doc_paths.py	0 unresolved in agent context

Nothing under src/routing/, src/sparse/, src/geometry.rs or src/nn/ is
touched; the change is confined to CLI fingerprinting, config validation, the
icechunk reader, and the baseline cache key.

Docs

CLAUDE.md §Data sources, and the ddrs-dev skill's references/config.md
(the pins block, its validation, and the baseline-cache consequence) and
references/testing.md (change-to-gate rows for src/cli/fingerprint.rs and the
icechunk reader / pins).

🤖 Generated with Claude Code

https://claude.ai/code/session_01GbK4a8dyT5eNDU97CUWHYZ