feat(semantic-facts): split effects confidence into event/target (P3a)

Executes P3a of docs/plans/2026-08-08-derived-artifact-hardening-execution-plan.md.

symbol_effects.confidence is split into event_confidence (certainty an
effect happened -- always "exact" in v1, every extraction site fires only
on a real syntactic raise/throw/write node) and target_confidence ("exact"
| "none" -- certainty about what the target is). This recovers 3 Python
throw facts the pre-P3 code silently dropped instead of recording with
degraded confidence:

- `raise e` (bound exception variable, PEP-8 casing heuristic can't
  resolve it to a type)
- `raise factory()` (lowercase call, syntactically identical to
  `raise SomeException()`)
- bare `raise` (re-raise) -- previously had no target text at all
  structurally, so was skipped entirely rather than recorded

Java/TS/JS throw detection is untouched: those require a real
object_creation_expression/new_expression constructor node structurally,
so they're always target_confidence="exact" when they fire at all -- the
PEP-8 casing uncertainty is Python-specific (verified by reading
detect_java_throw/detect_tsjs_throw before assuming a blanket classifier
would be correct).

- schema.rs: symbol_effects gains event_confidence/target_confidence
  columns (fresh-install CREATE TABLE + migrate_add_column for existing
  installs; old confidence column left in place on upgraded DBs, matching
  every other migration in run_migrations).
- SOURCE_EXTRACTION_VERSION bumped 1->2 -- the first live exercise of the
  P1 drift-guard mechanism: it correctly failed first (hash mismatch) on
  this exact change, then passed once the expected hash was updated
  alongside the version bump.
- Confidence classification lives in walk_effects (language+kind aware),
  not inside each per-language detect_* function -- keeps all 7 existing
  detectors' signatures untouched.
- New symbol_info_surfaces_effect_confidence_split end-to-end test;
  understand_surfaces_architecture_digest_and_t1_facts and P1's
  derived_artifact_versions.rs updated for the schema/output change.

Deliberately deferred, not attempted: detect_go_write (P3b). Needs the
enclosing method's receiver PARAMETER NAME tracked through walk_effects's
recursive traversal (Go's receiver is a plain identifier, not a keyword
like Rust's self, so it can collide with an unrelated same-named local in
a different function) -- real design work the module's own doc comment
already flags as not wired. Left as its own future slice rather than
rushed alongside this phase.

Verified: full `cargo test --workspace --features embeddings` green (1054
calm-core + 367 calm-server + all other packages, 0 failures), clippy -D
warnings clean, rustfmt clean, locate/symbol_info/understand toolsnaps
regenerated.

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

Author: Your Name

crates/calm-core/src/db/schema.rs

@@ -322,13 +322,26 @@ CREATE INDEX IF NOT EXISTS idx_type_relations_path ON type_relations(source_path
 -- call_sites.enclosing_qn already is. Same rebuild lifecycle as
 -- type_relations above -- no source_hash needed.
 CREATE TABLE IF NOT EXISTS symbol_effects (
-    id              INTEGER PRIMARY KEY AUTOINCREMENT,
-    symbol_qn       TEXT NOT NULL,
-    effect_kind     TEXT NOT NULL CHECK (effect_kind IN ('explicit_throw', 'write_field')),
-    target_text     TEXT NOT NULL,
-    confidence      TEXT NOT NULL DEFAULT 'syntax_exact',
-    source_path     TEXT NOT NULL,
-    line            INTEGER NOT NULL,
+    id                 INTEGER PRIMARY KEY AUTOINCREMENT,
+    symbol_qn          TEXT NOT NULL,
+    effect_kind        TEXT NOT NULL CHECK (effect_kind IN ('explicit_throw', 'write_field')),
+    target_text        TEXT NOT NULL,
+    -- P3 (docs/plans/2026-08-08-derived-artifact-hardening-execution-plan.md):
+    -- split from the old single `confidence` column -- `event_confidence`
+    -- is certainty THAT the effect happened (currently always 'exact': every
+    -- extraction site fires only on a real syntactic raise/throw/write
+    -- node); `target_confidence` is certainty about WHAT the target is
+    -- ('exact' | 'none'). A Python `raise e`/`raise factory()`/bare `raise`
+    -- is a real, certain throw EVENT whose exact exception TYPE isn't
+    -- syntactically knowable without full resolution -- previously dropped
+    -- entirely (see semantic_facts.rs's module doc comment history);
+    -- target_confidence='none' now records the event honestly instead of
+    -- losing it. write_field's target (the field name) is always exact
+    -- once detected, so it's always 'exact' on both dimensions.
+    event_confidence   TEXT NOT NULL DEFAULT 'exact',
+    target_confidence  TEXT NOT NULL DEFAULT 'exact',
+    source_path        TEXT NOT NULL,
+    line               INTEGER NOT NULL,
     UNIQUE(symbol_qn, effect_kind, target_text, line)
 );
 CREATE INDEX IF NOT EXISTS idx_symbol_effects_symbol ON symbol_effects(symbol_qn);
@@ -883,6 +896,27 @@ fn run_migrations(conn: &Connection) -> rusqlite::Result<()> {
             OR definition_snapshot IS NULL",
         [],
     )?;
+    // P3 (docs/plans/2026-08-08-derived-artifact-hardening-execution-plan.md):
+    // splits the old `symbol_effects.confidence` into `event_confidence`/
+    // `target_confidence` (see the fresh-install CREATE TABLE comment for
+    // the semantics). The old `confidence` column is left in place on an
+    // upgraded DB rather than dropped -- every migration in this function
+    // is purely additive, and `symbol_effects` is fully DELETE-then-
+    // reinsert on every reindex of the owning file anyway, so it becomes
+    // dead weight the next time each row's file is touched, not a
+    // permanent liability.
+    migrate_add_column(
+        conn,
+        "symbol_effects",
+        "event_confidence",
+        "TEXT NOT NULL DEFAULT 'exact'",
+    )?;
+    migrate_add_column(
+        conn,
+        "symbol_effects",
+        "target_confidence",
+        "TEXT NOT NULL DEFAULT 'exact'",
+    )?;
     Ok(())
 }
 

crates/calm-core/src/indexer/edges.rs

@@ -117,6 +117,10 @@ pub struct SymbolEffectData {
     pub symbol_qn: String,
     pub effect_kind: &'static str,
     pub target_text: String,
+    /// P3 (docs/plans/2026-08-08-derived-artifact-hardening-execution-plan.md):
+    /// "exact" | "none" -- see `RawEffect::target_confidence`, which this
+    /// mirrors verbatim.
+    pub target_confidence: &'static str,
     pub source_path: String,
     pub line: i64,
 }
@@ -152,15 +156,21 @@ pub fn insert_symbol_effects_batch(
     tx: &Transaction,
     effects: &[SymbolEffectData],
 ) -> rusqlite::Result<()> {
+    // event_confidence is a literal 'exact' here, not threaded from
+    // SymbolEffectData -- see schema.rs's symbol_effects comment: every
+    // current extraction site fires only on a real syntactic raise/throw/
+    // write node, so the EVENT is always certain in v1. Only
+    // target_confidence varies per-row.
     let mut stmt = tx.prepare(
-        "INSERT OR IGNORE INTO symbol_effects (symbol_qn, effect_kind, target_text, source_path, line)
-         VALUES (?1, ?2, ?3, ?4, ?5)",
+        "INSERT OR IGNORE INTO symbol_effects (symbol_qn, effect_kind, target_text, event_confidence, target_confidence, source_path, line)
+         VALUES (?1, ?2, ?3, 'exact', ?4, ?5, ?6)",
     )?;
     for e in effects {
         stmt.execute(rusqlite::params![
             e.symbol_qn,
             e.effect_kind,
             e.target_text,
+            e.target_confidence,
             e.source_path,
             e.line,
         ])?;

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

@@ -844,6 +844,7 @@ fn extract_file_data(
             symbol_qn,
             effect_kind: re.effect_kind,
             target_text: re.target_text,
+            target_confidence: re.target_confidence,
             source_path: rel.to_string(),
             line: re.line as i64,
         });

crates/calm-core/src/indexer/semantic_facts.rs

@@ -65,6 +65,14 @@ pub struct RawEffect {
     pub enclosing_line: usize,
     pub effect_kind: &'static str, // "explicit_throw" | "write_field"
     pub target_text: String,
+    /// P3 (docs/plans/2026-08-08-derived-artifact-hardening-execution-plan.md):
+    /// `"exact"` | `"none"` -- certainty about WHAT `target_text` names.
+    /// Computed in `walk_effects` (language + `effect_kind`-aware), not
+    /// here: only Python's `explicit_throw` detection currently has a
+    /// textual-heuristic uncertain case (`raise e` / `raise factory()` /
+    /// bare `raise`); every other detector is fully structural and always
+    /// `"exact"` when it fires at all.
+    pub target_confidence: &'static str,
     pub line: usize,
 }
 
@@ -84,7 +92,7 @@ pub struct RawEffect {
 /// `derived_artifact_versions::source_extraction_fixture_is_pinned_to_its_version`
 /// (crates/calm-core/tests/derived_artifact_versions.rs) -- bump this AND
 /// that test's expected hash together, in the same commit, never one alone.
-pub const SOURCE_EXTRACTION_VERSION: i64 = 1;
+pub const SOURCE_EXTRACTION_VERSION: i64 = 2;
 
 pub fn extract_type_relations_from_tree(
     tree: &Tree,
@@ -356,11 +364,28 @@ fn walk_effects(
     if let Some((enclosing_name, enclosing_line)) = &current
         && let Some((kind, text)) = detect_effect(node, source, language)
     {
+        // P3 (docs/plans/2026-08-08-derived-artifact-hardening-execution-plan.md):
+        // classified here (language + kind aware), not inside each
+        // per-language `detect_*` function -- only Python's `explicit_throw`
+        // detection is textual-heuristic (`looks_like_exception_reference`);
+        // Java/TS/JS throw detection requires a real constructor node
+        // structurally, so it's always exact when it fires at all, and
+        // `write_field`'s target (the field name) is always exact once
+        // detected, in every language.
+        let target_confidence = if language == "python"
+            && kind == "explicit_throw"
+            && (text.is_empty() || !looks_like_exception_reference(&text))
+        {
+            "none"
+        } else {
+            "exact"
+        };
         out.push(RawEffect {
             enclosing_name: enclosing_name.clone(),
             enclosing_line: *enclosing_line,
             effect_kind: kind,
             target_text: text,
+            target_confidence,
             line: node.start_position().row + 1,
         });
     }
@@ -441,17 +466,29 @@ fn detect_python_throw(node: Node, source: &str) -> Option<(&'static str, String
         return None;
     }
     let mut cursor = node.walk();
-    let first = node.named_children(&mut cursor).next()?;
+    let Some(first) = node.named_children(&mut cursor).next() else {
+        // Bare `raise` (re-raise the currently-handled exception) -- a
+        // real throw EVENT with structurally no target text to capture.
+        // `walk_effects` classifies this `target_confidence: "none"`.
+        return Some(("explicit_throw", String::new()));
+    };
+    // Casing is no longer a FILTER here (P3) -- `raise e`/`raise factory()`
+    // are still real throw events, just ones whose target isn't a resolved
+    // exception TYPE. `walk_effects` runs `looks_like_exception_reference`
+    // on the returned text to classify `target_confidence`, so both the
+    // confident and uncertain cases are recorded, never dropped.
     match first.kind() {
         "call" => {
             let func = first.child_by_field_name("function")?;
-            let text = source[func.byte_range()].trim().to_string();
-            looks_like_exception_reference(&text).then_some(("explicit_throw", text))
-        }
-        "identifier" => {
-            let text = source[first.byte_range()].trim().to_string();
-            looks_like_exception_reference(&text).then_some(("explicit_throw", text))
+            Some((
+                "explicit_throw",
+                source[func.byte_range()].trim().to_string(),
+            ))
         }
+        "identifier" => Some((
+            "explicit_throw",
+            source[first.byte_range()].trim().to_string(),
+        )),
         _ => None,
     }
 }
@@ -569,6 +606,29 @@ mod tests {
             .collect()
     }
 
+    /// P3 (docs/plans/2026-08-08-derived-artifact-hardening-execution-plan.md):
+    /// same as `effects` but also returns `target_confidence`, for the
+    /// tests that specifically assert on the confidence split. A separate
+    /// helper (rather than widening `effects` itself) so the other tests
+    /// that don't care about confidence stay untouched.
+    fn effects_with_confidence(
+        lang: &str,
+        src: &str,
+    ) -> Vec<(String, &'static str, String, &'static str)> {
+        let tree = parse_tree(src, lang).expect("parse");
+        extract_effects_from_tree(&tree, src, lang)
+            .into_iter()
+            .map(|e| {
+                (
+                    e.enclosing_name,
+                    e.effect_kind,
+                    e.target_text,
+                    e.target_confidence,
+                )
+            })
+            .collect()
+    }
+
     #[test]
     fn java_extends_and_implements() {
         let rs = relations(
@@ -700,34 +760,40 @@ mod tests {
 
     #[test]
     fn python_reraise_of_bound_variable_is_not_captured() {
-        // `raise e` -- `e` is a caught-exception variable, not an
-        // exception TYPE reference. Capturing it would mislabel the
-        // variable's name as if it were a resolved exception class.
-        assert!(
-            effects(
+        // `raise e` -- P3: still a real throw EVENT, target uncertain.
+        assert_eq!(
+            effects_with_confidence(
                 "python",
                 "def f():\n    try:\n        pass\n    except Exception as e:\n        raise e\n"
-            )
-            .is_empty()
+            ),
+            vec![("f".into(), "explicit_throw", "e".into(), "none")]
         );
     }
 
     #[test]
     fn python_raise_of_lowercase_factory_call_is_not_captured() {
         // `raise factory()` -- syntactically identical to
         // `raise SomeException()`; only the PEP 8 casing convention lets
-        // us tell them apart without full symbol resolution.
-        assert!(effects("python", "def f():\n    raise factory()\n").is_empty());
+        // us tell them apart without full symbol resolution. P3: recorded
+        // now (target_confidence=none), not dropped -- function name kept
+        // for stability even though the assertion below changed.
+        assert_eq!(
+            effects_with_confidence("python", "def f():\n    raise factory()\n"),
+            vec![("f".into(), "explicit_throw", "factory".into(), "none")]
+        );
     }
 
     #[test]
     fn python_bare_reraise_is_skipped() {
-        assert!(
-            effects(
+        // P3: bare `raise` is now recorded too (empty target_text,
+        // target_confidence=none) instead of dropped -- function name kept
+        // for stability even though the assertion below changed.
+        assert_eq!(
+            effects_with_confidence(
                 "python",
                 "def f():\n    try:\n        pass\n    except Exception:\n        raise\n"
-            )
-            .is_empty()
+            ),
+            vec![("f".into(), "explicit_throw", "".into(), "none")]
         );
     }
 

crates/calm-core/tests/derived_artifact_versions.rs

@@ -71,17 +71,18 @@ fn source_extraction_snapshot(conn: &Connection) -> String {
         .unwrap();
     let mut effects: Vec<String> = conn
         .prepare(
-            "SELECT symbol_qn, effect_kind, target_text, confidence \
+            "SELECT symbol_qn, effect_kind, target_text, event_confidence, target_confidence \
              FROM symbol_effects ORDER BY symbol_qn, effect_kind, target_text",
         )
         .unwrap()
         .query_map([], |r| {
             Ok(format!(
-                "{}|{}|{}|{}",
+                "{}|{}|{}|{}|{}",
                 r.get::<_, String>(0)?,
                 r.get::<_, String>(1)?,
                 r.get::<_, String>(2)?,
                 r.get::<_, String>(3)?,
+                r.get::<_, String>(4)?,
             ))
         })
         .unwrap()
@@ -98,7 +99,7 @@ fn source_extraction_snapshot(conn: &Connection) -> String {
 
 /// Regenerate via: read the assertion failure's "actual hash" and paste it
 /// in below alongside a `SOURCE_EXTRACTION_VERSION` bump.
-const EXPECTED_SOURCE_EXTRACTION_HASH: &str = "1473f45c2586b01e";
+const EXPECTED_SOURCE_EXTRACTION_HASH: &str = "cd8a8816b5c84b00";
 
 #[test]
 fn source_extraction_fixture_is_pinned_to_its_version() {

crates/calm-server/src/__toolsnaps__/locate.snap

@@ -347,12 +347,22 @@
           "line": {
             "type": "integer",
             "format": "int64"
+          },
+          "event_confidence": {
+            "description": "P3 (docs/plans/2026-08-08-derived-artifact-hardening-execution-plan.md):\ncertainty THAT the effect happened -- currently always `\"exact\"`\n(every extraction site fires only on a real syntactic raise/throw/\nwrite node); kept as its own field for forward compatibility rather\nthan folded into `target_confidence`, which is a DIFFERENT question\n(certainty about WHAT the target is).",
+            "type": "string"
+          },
+          "target_confidence": {
+            "description": "`\"exact\"` | `\"none\"` -- certainty about what `target_text` names.\n`\"none\"` means the effect definitely happened but the exact target\ncouldn't be determined syntactically (e.g. Python `raise e` where\n`e` is a caught-exception variable, not a resolvable type) -- the\ntext is still the real syntax that was there, just not resolved.",
+            "type": "string"
           }
         },
         "required": [
           "effect_kind",
           "target_text",
-          "line"
+          "line",
+          "event_confidence",
+          "target_confidence"
         ]
       },
       "FileOverviewOutput": {

crates/calm-server/src/__toolsnaps__/symbol_info.snap

@@ -231,12 +231,22 @@
           "line": {
             "type": "integer",
             "format": "int64"
+          },
+          "event_confidence": {
+            "description": "P3 (docs/plans/2026-08-08-derived-artifact-hardening-execution-plan.md):\ncertainty THAT the effect happened -- currently always `\"exact\"`\n(every extraction site fires only on a real syntactic raise/throw/\nwrite node); kept as its own field for forward compatibility rather\nthan folded into `target_confidence`, which is a DIFFERENT question\n(certainty about WHAT the target is).",
+            "type": "string"
+          },
+          "target_confidence": {
+            "description": "`\"exact\"` | `\"none\"` -- certainty about what `target_text` names.\n`\"none\"` means the effect definitely happened but the exact target\ncouldn't be determined syntactically (e.g. Python `raise e` where\n`e` is a caught-exception variable, not a resolvable type) -- the\ntext is still the real syntax that was there, just not resolved.",
+            "type": "string"
           }
         },
         "required": [
           "effect_kind",
           "target_text",
-          "line"
+          "line",
+          "event_confidence",
+          "target_confidence"
         ]
       },
       "Caveat": {

crates/calm-server/src/__toolsnaps__/understand.snap

@@ -277,12 +277,22 @@
           "line": {
             "type": "integer",
             "format": "int64"
+          },
+          "event_confidence": {
+            "description": "P3 (docs/plans/2026-08-08-derived-artifact-hardening-execution-plan.md):\ncertainty THAT the effect happened -- currently always `\"exact\"`\n(every extraction site fires only on a real syntactic raise/throw/\nwrite node); kept as its own field for forward compatibility rather\nthan folded into `target_confidence`, which is a DIFFERENT question\n(certainty about WHAT the target is).",
+            "type": "string"
+          },
+          "target_confidence": {
+            "description": "`\"exact\"` | `\"none\"` -- certainty about what `target_text` names.\n`\"none\"` means the effect definitely happened but the exact target\ncouldn't be determined syntactically (e.g. Python `raise e` where\n`e` is a caught-exception variable, not a resolvable type) -- the\ntext is still the real syntax that was there, just not resolved.",
+            "type": "string"
           }
         },
         "required": [
           "effect_kind",
           "target_text",
-          "line"
+          "line",
+          "event_confidence",
+          "target_confidence"
         ]
       },
       "SourceOutput": {