docs(dataflow): record vendored scalpel as the default L4 oracle

Author: rahlk

.claude/SCHEMA_DECISIONS.md

@@ -152,6 +152,17 @@ supported 3.9–3.13+ range; `compute_SSA`'s return contract is discovered from
 source (not a documented public API) — wrap it behind `ScalpelAliasOracle` to
 contain upstream drift.
 
+**Follow-up (2026-07-22): Scalpel vendored, now the default.** The Stage-0
+"dependency hygiene" concern proved fatal for a hard dependency: `python-scalpel`
+drags `typed_ast`, which has no wheel for Python 3.12+ and does not build from
+source there, so `pip install python-scalpel` fails on 3.12/3.13/3.14. Since
+`typed_ast` is imported only by `scalpel/typeinfer` (unused here), the 9-module
+`SSA`/`cfg`/`core` slice the oracle loads was **vendored** into
+`codeanalyzer/dataflow/scalpel/` (Apache-2.0, verbatim but for a `graphviz`-lazy
+patch). `ScalpelAliasOracle` is now the shipping default on all supported Python;
+`TypeBasedAliasOracle` is the runtime safety net only. See
+`docs/superpowers/specs/2026-07-22-vendored-scalpel-default-oracle-design.md`.
+
 ## Stage 5 — keystone conformance sweep (issue #98, schema_version 2.0.0)
 
 The stage-5 pre-release conformance check against the canonical schema-v2

CHANGELOG.md

@@ -7,6 +7,16 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Changed
+- The Scalpel-backed L4 points-to oracle is now **vendored** (`typed_ast`-free)
+  and the default on all supported Python (3.9–3.14); `python-scalpel` is no
+  longer an optional dependency and the `[scalpel]` extra is removed. On Python
+  3.12+ (and anywhere the `[scalpel]` extra was not installed), L4
+  `prov:["points-to"]` data-dependence edges are now Scalpel-precise rather than
+  the coarser type-based over-approximation; the `prov:["ssa"]` set and the
+  `L3 ⊆ L4` monotonicity invariant are unchanged. Adds `astor` as a runtime
+  dependency.
+
 ## [1.0.3] - 2026-07-21
 
 ### Fixed

CLAUDE.md

@@ -122,10 +122,13 @@ declared callables by their `can://` tree id, imported/builtin targets by a
   (`codeanalyzer/dataflow/scalpel_oracle.py`) consumes `python-scalpel`'s **solved
   SSA + copy/const** state (it never forks the solver) as a copy-closure union-find
   over access paths, behind the frozen `may_alias(path_a, path_b) -> bool`
-  interface. `python-scalpel` is an **optional** dependency: if it is absent or a
-  build/query fails, the analyzer falls back to the total `TypeBasedAliasOracle`
-  (`alias.py`) and degrades, never raising. The type-based oracle is the sanctioned
-  fallback, not the shipping default.
+  interface. Scalpel is **vendored** (`codeanalyzer/dataflow/scalpel/`, a
+  `typed_ast`-free 9-module slice of `python-scalpel 1.0b0`, Apache-2.0) so it is
+  the **shipping default** L4 oracle on every supported Python — there is no
+  external `python-scalpel`/`typed_ast` dependency. `TypeBasedAliasOracle`
+  (`alias.py`) is retained only as the runtime safety net: on a per-callable
+  Scalpel build failure or a per-query unresolved access path, `may_alias`
+  degrades to it, never raising.
 - **CLI gating** (`codeanalyzer/__main__.py`): `-a` max is 4; `--graphs sdg`
   requires `-a 4` (a flag error below that); `cfg,dfg,pdg` require `-a 3`;
   `--graph-field-depth` (the `k_limit`) is valid at L3+.

test/test_vendored_scalpel.py

@@ -1,7 +1,10 @@
 """The vendored, typed_ast-free scalpel slice: it must import and compute SSA
 with no external scalpel / typed_ast / graphviz, and never pull in typeinfer."""
+import ast
 import sys
 
+import pytest
+
 
 def test_vendored_scalpel_imports_and_computes_ssa_typed_ast_free():
     # No external scalpel shadowing the vendored copy.
@@ -25,9 +28,6 @@ def test_vendored_scalpel_imports_and_computes_ssa_typed_ast_free():
     assert not any("typeinfer" in m for m in loaded), f"typeinfer leaked: {loaded}"
 
 
-import ast
-
-
 def test_make_alias_oracle_defaults_to_scalpel_without_typed_ast():
     import sys
     assert "typed_ast" not in sys.modules
@@ -51,3 +51,34 @@ def test_make_alias_oracle_is_deterministic():
     o2 = make_alias_oracle(None, _ast.parse(src).body[0], {})
     pairs = [("a", "b"), ("b", "c"), ("a", "c"), ("b", "b")]
     assert [o1.may_alias(x, y) for x, y in pairs] == [o2.may_alias(x, y) for x, y in pairs]
+
+
+def _pip_scalpel_available():
+    try:
+        import importlib.util
+        # the EXTERNAL package, not our vendored copy
+        return importlib.util.find_spec("scalpel") is not None and \
+            not importlib.util.find_spec("scalpel").origin.endswith(
+                "codeanalyzer/dataflow/scalpel/__init__.py")
+    except Exception:
+        return False
+
+
+@pytest.mark.skipif(not _pip_scalpel_available(),
+                    reason="upstream python-scalpel not installed (3.12+ can't build typed_ast)")
+def test_vendored_ssa_matches_upstream():
+    """On a Python where pip python-scalpel installs (<=3.11), the vendored copy
+    must produce identical SSA const_dict keys as upstream on the same source."""
+    import scalpel.SSA.const as up_ssa
+    import scalpel.cfg as up_cfg
+    from codeanalyzer.dataflow.scalpel.SSA.const import SSA as VSSA
+    from codeanalyzer.dataflow.scalpel.cfg import CFGBuilder as VCFG
+
+    src = "def f(a):\n    b = a\n    if a:\n        b = 2\n    return b\n"
+    up_c = up_cfg.CFGBuilder().build_from_src("m", src)
+    v_c = VCFG().build_from_src("m", src)
+    up_fn = list(up_c.functioncfgs.values())[0]
+    v_fn = list(v_c.functioncfgs.values())[0]
+    _, up_const = up_ssa.SSA().compute_SSA(up_fn)
+    _, v_const = VSSA().compute_SSA(v_fn)
+    assert sorted(map(str, up_const)) == sorted(map(str, v_const))