docs+test(pipeline): PR#9 final polish -- CallSiteKey completeness + identity_migration design note

Two small, low-risk finishing touches now that slices A-D + the churn
regression test have all landed and been verified:

- golden_graph_equivalence.rs's CallSiteKey gains callee_start_rel/
  callee_end_rel alongside the pre-existing absolute byte fields, per the
  plan's own explicit instruction to update this struct in lockstep with
  the v3 schema. The existing suite already passed without this (slice
  D's position-refresh fix keeps callee_start_byte/callee_end_byte always
  current, which was sufficient for the mutation-round tests to catch the
  real bug they caught), but comparing the relative columns too closes a
  theoretical gap: a hypothetical divergence in relative-offset
  computation specifically, decoupled from the absolute one.

- identity_migration.rs::needs_call_site_identity_baseline gains a doc
  comment explaining why it deliberately does NOT gain a v2-vs-v3 check
  the way it already has one for v1-vs-v2: a permanent, by-design mix of
  v2 (module-level calls, no real enclosing symbol to be relative to) and
  v3 (calls inside a real function/method) is the correct steady state,
  and the churn v3 fixes only matters for files that actually get
  reindexed -- reconcile_call_sites already upgrades a v2 row to v3
  organically on the next edit to its file, at the cost of exactly one
  identity transition, cheaper and lower-risk than a global forced
  rebuild that would churn every proof in the database at once for files
  that may never be touched again anyway. No code/behavior change.

This closes out PR#9 (docs/plans/2026-08-19-evidence-architecture-
execution-plan.md Part E): position-independent call-site identity (v3),
upsert-by-identity reconciliation fixing the actual proof-churn root
cause, and a regression test proving the plan's own DoD is met.

Verified: cargo build/clippy -p calm-core --all-targets clean, cargo test
-p calm-core 1249 passed/0 failed/12 ignored including both
golden_equivalence_{continued,incremental}_vs_fresh_across_mutation_rounds,
cargo fmt clean.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

Author: Your Name

crates/calm-core/src/indexer/pipeline/identity_migration.rs

@@ -42,6 +42,24 @@ use super::{GraphMode, ReindexSummary, now_secs};
 /// identity predates D4. Incremental indexing cannot repair these rows because
 /// their file hashes are unchanged, so it must take the full transactional
 /// baseline path instead of reporting a no-op.
+///
+/// PR#9 (docs/plans/2026-08-19-evidence-architecture-execution-plan.md Part
+/// E, position-independent v3 identity) deliberately does NOT extend this
+/// predicate to force a v2->v3 baseline the same way. Two reasons: (1) a
+/// permanent, by-design mix of v2 (module-level calls with no real
+/// enclosing symbol to be relative to) and v3 (calls inside a real
+/// function/method) rows is the correct steady state, not incomplete
+/// migration -- there is no "fully migrated" endpoint to detect the way
+/// v1->v2 has one; (2) the churn v3 fixes only matters for a call_sites
+/// row that actually gets RECONCILED (i.e. its file gets reindexed) --
+/// `extraction::reconcile_call_sites` already upgrades a v2 row to v3
+/// organically the next time its file changes, at the cost of exactly one
+/// identity transition (the old v2-keyed row won't match the new v3-keyed
+/// extraction, so it's replaced once) -- cheaper and lower-risk than a
+/// global forced rebuild that would churn every proof in the database in
+/// one pass on upgrade, for files that may never be touched again anyway.
+/// A file that's never reindexed was never going to churn regardless of
+/// which identity version its rows carry.
 pub(super) fn needs_call_site_identity_baseline(conn: &Connection) -> rusqlite::Result<bool> {
     conn.query_row(
         "SELECT EXISTS(

crates/calm-core/tests/golden_graph_equivalence.rs

@@ -28,6 +28,13 @@ struct CallSiteKey {
     identity_version: i64,
     callee_start_byte: Option<i64>,
     callee_end_byte: Option<i64>,
+    // PR#9 (docs/plans/2026-08-19-evidence-architecture-execution-plan.md
+    // Part E): v3's relative-to-enclosing-symbol offsets, alongside the
+    // pre-existing absolute ones above -- both compared, so equivalence
+    // catches a divergence in EITHER identity scheme, not just the
+    // absolute one v2 already covered.
+    callee_start_rel: Option<i64>,
+    callee_end_rel: Option<i64>,
     source_file_hash: Option<String>,
 }
 
@@ -78,7 +85,7 @@ fn graph_fingerprint(conn: &Connection) -> (BTreeSet<EdgeKey>, BTreeMap<String,
                     ep.definition_snapshot, ep.call_site_identity_version, \
                     CASE WHEN ep.id IS NULL THEN NULL \
                          WHEN ep.graph_generation = graph.generation THEN 1 ELSE 0 END, \
-                    ep.status \
+                    ep.status, cs.callee_start_rel, cs.callee_end_rel \
              FROM call_edges ce \
              LEFT JOIN call_sites cs ON cs.id = ce.call_site_id \
              LEFT JOIN file_index fi ON fi.path = cs.from_path \
@@ -100,6 +107,8 @@ fn graph_fingerprint(conn: &Connection) -> (BTreeSet<EdgeKey>, BTreeMap<String,
             let callee_start_byte: Option<i64> = r.get(15)?;
             let callee_end_byte: Option<i64> = r.get(16)?;
             let call_site_source_file_hash: Option<String> = r.get(17)?;
+            let call_site_start_rel: Option<i64> = r.get(28)?;
+            let call_site_end_rel: Option<i64> = r.get(29)?;
             let call_site = call_site_path.map(|path| CallSiteKey {
                 path,
                 enclosing_symbol: enclosing_symbol.unwrap_or_default(),
@@ -108,6 +117,8 @@ fn graph_fingerprint(conn: &Connection) -> (BTreeSet<EdgeKey>, BTreeMap<String,
                 identity_version: call_site_identity_version.unwrap_or_default(),
                 callee_start_byte,
                 callee_end_byte,
+                callee_start_rel: call_site_start_rel,
+                callee_end_rel: call_site_end_rel,
                 source_file_hash: call_site_source_file_hash,
             });
             let provider: Option<String> = r.get(18)?;