sourcecode 2.6.2__tar.gz → 2.6.5__tar.gz

{sourcecode-2.6.2 → sourcecode-2.6.5}/CHANGELOG.md

@@ -1,5 +1,123 @@
 # Changelog
 
+## [2.6.5] — 2026-07-24
+
+**Mistyped-subcommand ergonomics: `ask` no longer swallows a typo'd command as a path
+and then blames the wrong token.** CLI-only; no analysis behaviour changes.
+
+### Fixed
+
+- **A mistyped command now names the token the user got wrong, and suggests the real
+  command.** `ask` accepts a bare repository path (`ask ./repo`) as an implicit scan, so
+  a misspelled subcommand used to be swallowed as a path and surface a misleading error
+  about the *next* token — `ask notacommand /tmp` complained `No such command '/tmp'` (the
+  path), and `ask spring-audi` complained the directory did not exist. Now:
+  - a first positional followed by another non-subcommand positional
+    (`ask notacommand /tmp`) is rejected as an unknown command (exit `2`), naming the
+    first token and — when it is close to a real command — suggesting it;
+  - a lone token that does not resolve to a directory but closely matches a command
+    (`ask spring-audi`) adds a *did you mean `ask spring-audit`* hint to the path error.
+
+  The implicit-scan contract is unchanged: a single positional is still treated as a
+  repository path with existence validated downstream, and the documented
+  `ask <subcommand> <path>` order (and the `ask <path> <subcommand>` rejection) are
+  untouched.
+
+## [2.6.4] — 2026-07-24
+
+**TX-006: self-invocation proxy-bypass detection — a new Spring transaction rule that
+also participates automatically in the `verify-edit` write-loop gate.** Plus a root-cause
+false-positive fix in body-fact extraction and one internal-id output leak removed. No
+change to any existing command's contract. Suite: **3742 passed, 5 skipped, 1 deselected**
+(the deselected chunker test is a pre-existing external-fixture flake).
+
+### Added
+
+- **TX-006 — self-invocation of a `@Transactional` sibling (Spring proxy bypass).** A
+  same-instance call — an unqualified `foo()` or an explicit `this.foo()` to a method of
+  the same class — does not pass through the Spring proxy, so the target's method-level
+  `@Transactional` is silently ignored at runtime (the Sonar S2229 class of bug). Detection
+  is structural and vendor-agnostic, reading the Semantic-IR `invocation` atoms already
+  produced by the pipeline: the receiver is `None`/`this` and the call resolves to an
+  unambiguous same-class sibling that carries a method-level `@Transactional`. False-positive
+  guards are built in — overloaded/ambiguous targets are skipped, class-level-only
+  `@Transactional` is not flagged (the proxy already covers the outer entry method), and the
+  legitimate self-injection escape hatch (`self.foo()` through an injected same-type field)
+  uses a field receiver and never resolves as a sibling. Severity is tiered: `high` only when
+  the callee propagation mandates a distinct boundary (`REQUIRES_NEW`/`NESTED`/`NOT_SUPPORTED`/
+  `NEVER`/`MANDATORY`); a plain `REQUIRED`/`SUPPORTS` callee or a `readOnly` getter is `medium`.
+  Surfaced by `ask spring-audit` and, with no additional wiring, by the `verify-edit`
+  `tx_boundary_changed` axis — an edit that *introduces* a self-invocation now breaks the
+  write-loop verdict before commit, while a pre-existing one never fails an unrelated change.
+
+### Fixed
+
+- **Chained-call receivers no longer read as self-calls (body-fact extraction).** A
+  method-chained invocation such as `Context.getBean().method()` left the receiver empty
+  because the receiver is an expression, not a bare identifier — causing it to be mistaken
+  for an unqualified self-call. A callee immediately preceded by `.` is now marked as a
+  non-self expression receiver. This is a general sibling-resolution correctness fix
+  (it also prevents a chained sibling-named call from being mis-resolved to a call edge);
+  `body_facts` is not a `cir_hash` input, so the fix is hash-neutral. It removed roughly
+  half of the raw TX-006 candidates on a real Spring codebase — all of them true bypass
+  false-positives, including a service that correctly routes `REQUIRES_NEW` through a
+  service-locator proxy.
+- **Internal bug id removed from user-facing output.** The self-referential-exclusion
+  warning in `impact` no longer prints the internal `(BUG #2)` tag; the explanation stays.
+
+## [2.6.3] — 2026-07-24
+
+**`ask verify-edit` — the in-loop semantic diff gate lands (the read-context → write-loop
+verification pivot), plus a content-addressed parse cache and one field-test correctness
+fix.** New user-facing capability; no change to any existing command's contract. Suite:
+**3731 passed, 5 skipped, 1 deselected** (the deselected chunker test is a pre-existing
+external-fixture flake).
+
+### Added
+
+- **`ask verify-edit` — a deterministic, in-loop semantic diff gate.** Verdict over the
+  diff of the working tree against HEAD, built for the agent write-loop and CI. Each axis
+  is a diff over two Canonical IRs (working vs a throwaway `git worktree` checkout of
+  HEAD), reporting only regressions the edit **introduced** — pre-existing debt never
+  fails an unrelated commit:
+  - `contract_broken` — a public symbol removed, its visibility downgraded, or (when
+    unambiguous) its signature changed.
+  - `tx_boundary_changed` — a `@Transactional` proxy boundary broken (e.g. a
+    `@Transactional` method flipped `public` → `private` → a silently inert CGLIB proxy).
+  - `security_delta` — a security-posture finding the edit introduced.
+  - `new_orphan_bean` — a bean that lost all its injection wiring.
+  - `custom_rule_violated` — the client's own invariants, declared in
+    `.ask/verify-rules.json` (below).
+  - plus an informational `blast_radius` (entry points reachable from the changed files).
+
+  Exit codes under `--ci` (default): `0` pass, `1` break, `2` unverified (a blocking axis
+  could not be computed — never a silent pass). JSON verdict to stdout, prose to stderr.
+- **Custom domain rules (`.ask/verify-rules.json`).** Declare invariants of *your*
+  codebase and have `verify-edit` enforce them — `forbidden_edge` ("no `@RestController`
+  injects a `*DaoJpa`") and `require_endpoint_security` ("every `/payroll` endpoint
+  requires role X"). Selectors reason by structure (annotation / fqn-regex / kind /
+  modifier / source-file); the concrete names are config data, never branched on in the
+  engine. Zero-config: no rules file ⇒ nothing to enforce; a malformed ruleset degrades
+  to *unverified*, never a silent pass.
+- **MCP tool `verify_edit`** (report-only) so an agent can call the gate after each edit,
+  and **`ask verify-edit --install-hook pre-commit|pre-push`** to install a git hook that
+  runs the same binary and blocks on a break (bypass with `git --no-verify`).
+- **Content-addressed per-file parse cache.** Symbol extraction and the body-fact bundle
+  of an unchanged file are pure functions of its bytes, so they are memoised by a content
+  hash — a 1-file edit re-parses 1 file, not the whole repo. It **never changes the
+  result** (a miss just re-parses; the CIR is byte-identical whether the cache is cold,
+  warm, or disabled) and it accelerates every CIR consumer, not only `verify-edit`.
+  Measured on a 1076-file repo: the working-CIR build drops ~59% warm.
+
+### Fixed
+
+- **`verify-edit` contract axis no longer false-breaks on overloaded methods** (found in
+  a field-test of a real repo with a clean tree). An fqn carries no signature, so
+  overloaded methods/constructors share one id across several graph nodes; the axis now
+  aggregates visibility per fqn as *any overload public* instead of picking an
+  order-dependent representative, so a public name that also has a non-public overload no
+  longer reads as a downgrade on an unchanged tree.
+
 ## [2.6.2] — 2026-07-23
 
 **Field-eval Fase 3 — cache reuse (C) + cold-scan honesty (E). No

{sourcecode-2.6.2 → sourcecode-2.6.5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sourcecode
-Version: 2.6.2
+Version: 2.6.5
 Summary: Persistent structural context and ultra-fast repeated analysis for AI coding agents
 License-File: LICENSE
 Keywords: agents,ai,codebase,context,developer-tools,llm

{sourcecode-2.6.2 → sourcecode-2.6.5}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "sourcecode"
-version = "2.6.2"
+version = "2.6.5"
 description = "Persistent structural context and ultra-fast repeated analysis for AI coding agents"
 readme = "README.md"
 requires-python = ">=3.9"

{sourcecode-2.6.2 → sourcecode-2.6.5}/src/sourcecode/__init__.py

@@ -4,4 +4,4 @@ ASK Engine is the product. ``ask`` is the canonical CLI command; ``sourcecode``
 the legacy compatibility alias and the Python/PyPI package name. See
 docs/PRODUCT_IDENTITY.md (normative)."""
 
-__version__ = "2.6.2"
+__version__ = "2.6.5"

{sourcecode-2.6.2 → sourcecode-2.6.5}/src/sourcecode/cli.py

@@ -2,6 +2,7 @@ from __future__ import annotations
 
 import hashlib
 import json
+import difflib
 import os
 import sys
 import threading
@@ -254,6 +255,8 @@ _SUBCOMMANDS: frozenset[str] = frozenset(
         "explain",
         # Spring Boot 2→3 migration readiness
         "migrate-check",
+        # In-loop semantic diff gate (working tree vs HEAD)
+        "verify-edit",
         # Native file rename (BLOCKER-A)
         "rename-class",
         # Large file semantic chunking (BLOCKER-B)
@@ -329,6 +332,54 @@ def _reject_path_before_subcommand(path_token: str, subcommand: str) -> "NoRetur
     raise SystemExit(2)
 
 
+def _reject_unknown_command(token: str) -> "NoReturn":
+    """Refuse a first positional that is neither a known subcommand nor a real path.
+
+    `ask` accepts a bare repository path (`ask ./repo`) as an implicit scan, so a
+    mistyped subcommand used to be swallowed as a path and then surfaced a
+    misleading error naming the *wrong* token — `ask spring-audi` complained the
+    directory 'spring-audi' did not exist, and `ask notacommand /tmp` complained
+    'No such command /tmp' (the path, not the typo). Name the token the user
+    actually got wrong, and suggest the closest real commands.
+    """
+    matches = difflib.get_close_matches(token, sorted(_SUBCOMMANDS), n=3, cutoff=0.6)
+    first = f"error: '{token}' is not a known command"
+    if matches:
+        first += f". Did you mean: {', '.join(matches)}?"
+    else:
+        first += " and is not an existing directory to scan."
+    print(
+        first + "\n       run 'ask --help' to list commands, or pass an existing "
+        "repository path.",
+        file=sys.stderr,
+    )
+    raise SystemExit(2)
+
+
+def _has_trailing_nonsubcommand_positional(args: list[str], after: int) -> bool:
+    """True when a bare positional that is NOT a subcommand appears after index
+    ``after`` (options and the values they consume are skipped).
+
+    The implicit scan (`ask <path>`) owns exactly one positional, and a valid
+    invocation with two positionals always starts with a subcommand. So a first
+    non-subcommand positional followed by another non-subcommand positional —
+    `ask notacommand /tmp` — is malformed: the user meant a command. A trailing
+    token that IS a subcommand is left for ``_reject_path_before_subcommand``."""
+    skip_next = False
+    for arg in args[after + 1:]:
+        if skip_next:
+            skip_next = False
+            continue
+        if arg.startswith("-"):
+            if arg.split("=")[0] in _OPTIONS_WITH_VALUE and "=" not in arg:
+                skip_next = True
+            continue
+        if arg in _SUBCOMMANDS:
+            return False  # wrong-order path/subcommand — handled elsewhere
+        return True
+    return False
+
+
 def _preprocess_args(args: list[str]) -> list[str]:
     """Extract a repository path token from an args list and store it in _detected_path.
 
@@ -361,7 +412,13 @@ def _preprocess_args(args: list[str]) -> list[str]:
             return result  # known subcommand — leave for Click to dispatch
         if _path_index >= 0:
             continue  # a later positional is the subcommand's own business
-        # First genuine positional: treat as repository path
+        # First genuine positional. `ask` treats it as the repository path to scan
+        # (existence is validated downstream, not here). But if it is followed by
+        # another non-subcommand positional, the one-path scan cannot own both —
+        # `ask notacommand /tmp` — so the user meant a command: name the token they
+        # got wrong instead of swallowing it and erroring on the next one.
+        if _has_trailing_nonsubcommand_positional(result, i):
+            _reject_unknown_command(arg)
         _set_detected_path(arg)
         _path_index = i
     if _path_index >= 0:
@@ -1276,11 +1333,23 @@ def main(
     _raw_path_input = _get_detected_path()
     target = Path(_raw_path_input).resolve()
     if not target.exists():
+        # A non-existent path that closely matches a command name is almost always a
+        # mistyped subcommand (`ask spring-audi`) swallowed as an implicit-scan path,
+        # not a real directory. Point at the likely command instead of only the path.
+        _cmd_matches = difflib.get_close_matches(
+            _raw_path_input, sorted(_SUBCOMMANDS), n=3, cutoff=0.6
+        )
+        _hint = "Pass an existing repository directory."
+        if _cmd_matches:
+            _hint = (
+                f"If you meant a command, try: {', '.join('ask ' + m for m in _cmd_matches)}. "
+                "Otherwise pass an existing repository directory."
+            )
         _emit_error_json(
             INVALID_INPUT_CODE,
             f"Directory '{_raw_path_input}' does not exist.",
             path=_raw_path_input,
-            hint="Pass an existing repository directory.",
+            hint=_hint,
             expected="An existing directory path.",
         )
         raise typer.Exit(code=1)
@@ -5526,7 +5595,7 @@ def spring_audit_cmd(
         help="Accepted for compatibility; this command always reads fresh source (no snapshot cache). No-op.",
     ),
 ) -> None:
-    """Spring semantic audit: TX anomalies (TX-001..005) + security surface (SEC-001..003).
+    """Spring semantic audit: TX anomalies (TX-001..006) + security surface (SEC-001..003).
 
     \b
     Detects:
@@ -5535,6 +5604,7 @@ def spring_audit_cmd(
       TX-003  readOnly=true boundary propagating to write operation
       TX-004  NOT_SUPPORTED/NEVER within active TX chain
       TX-005  Exception swallowing inside @Transactional
+      TX-006  Self-invocation of @Transactional sibling (proxy bypass)
       SEC-001 Unsecured endpoint in annotation_based security model
       SEC-002 CVE-2025-41248: @PreAuthorize on inherited method from generic supertype
       SEC-003 @Transactional on @Controller/@RestController (TX in wrong layer)
@@ -5678,6 +5748,85 @@ def spring_audit_cmd(
         raise typer.Exit(code=1)
 
 
+# ── verify-edit: in-loop semantic diff gate ───────────────────────────────────
+
+
+@app.command("verify-edit")
+def verify_edit_cmd(
+    path: Path = typer.Argument(
+        Path("."),
+        help="Repository path (default: current directory). Diffs the working tree vs HEAD.",
+    ),
+    output_path: Optional[Path] = typer.Option(
+        None, "--output", "-o", help="Write the verdict JSON to a file instead of stdout."
+    ),
+    format: str = typer.Option("json", "--format", help="Output format: json."),
+    ci: bool = typer.Option(
+        True,
+        "--ci/--no-ci",
+        help="Exit non-zero on a broken/unverified verdict (default on — for gates and hooks).",
+    ),
+    install_hook: Optional[str] = typer.Option(
+        None,
+        "--install-hook",
+        help="Install a git hook (pre-commit|pre-push) that runs this gate, then exit. Does not verify.",
+    ),
+) -> None:
+    """Semantic diff gate: did the working-tree edits change runtime behavior?
+
+    Deterministic, in-loop verdict over the diff of the working tree against HEAD:
+    public contract, @Transactional proxy boundary, security surface, bean wiring,
+    custom domain rules, and blast radius. Built for the agent write-loop (MCP) and
+    git hooks. Only regressions the edit INTRODUCED (vs HEAD) block — pre-existing
+    debt never fails an unrelated commit.
+
+    Custom rules: drop a `.ask/verify-rules.json` at the repo root to enforce your own
+    invariants (e.g. "no @RestController injects a *DaoJpa", "every /payroll endpoint
+    requires role X"). They gate the same way as the built-in axes.
+
+    Exit codes (with --ci, the default): 0 = pass, 1 = break (a blocking axis proved
+    a regression), 2 = unverified (a blocking axis could not be computed — never a
+    silent pass) or the path is not a git repository.
+
+    Examples:
+      ask verify-edit                       # verify the current working tree
+      ask verify-edit /path/to/repo
+      ask verify-edit --no-ci               # always exit 0 (report only)
+      ask verify-edit --install-hook pre-commit
+    """
+    from sourcecode import verify_edit as _ve
+
+    if install_hook is not None:
+        try:
+            _hook_path = _ve.install_git_hook(path, install_hook)
+        except _ve.VerifyEditError as exc:
+            _emit_error_json(
+                INVALID_INPUT_CODE,
+                str(exc),
+                hint=f"Choose a hook type: {' | '.join(_ve.HOOK_TYPES)}. The repo must be a git repository.",
+            )
+            raise typer.Exit(code=2)
+        typer.echo(f"Installed verify-edit {install_hook} hook: {_hook_path}", err=True)
+        typer.echo(f"It runs `ask verify-edit --ci` and blocks on a break; bypass with git --no-verify.", err=True)
+        return
+
+    try:
+        v = _ve.verify_edit(path)
+    except _ve.VerifyEditError as exc:
+        _emit_error_json(
+            INVALID_INPUT_CODE,
+            str(exc),
+            hint="verify-edit needs a git repository with a HEAD commit (it diffs the working tree vs HEAD).",
+        )
+        raise typer.Exit(code=2 if ci else 0)
+
+    output = _serialize_dict(v.to_dict(), format)
+    _emit_command_output(output, output_path, False,
+                         success_msg=f"verify-edit verdict written to {output_path}")
+    if ci and v.exit_code != 0:
+        raise typer.Exit(code=v.exit_code)
+
+
 # ── Spring Boot Migration Check ───────────────────────────────────────────────
 
 

{sourcecode-2.6.2 → sourcecode-2.6.5}/src/sourcecode/mcp/registry.py

@@ -1269,6 +1269,7 @@ _MCP_HIDDEN_CANONICAL_TOOLS: frozenset[str] = frozenset({
     "spring_audit",       # curated: repo_path + scope + min_severity only (strips output_path/format/copy)
     "impact_chain",       # curated: repo_path + symbol + depth + query_type with choices
     "migrate_check",      # curated: repo_path + min_severity only (strips output_path/format/copy/ci)
+    "verify_edit",        # curated: repo_path only (report-only --no-ci; strips output_path/format/ci)
     # MCP self-management (an agent is not the MCP client admin)
     "mcp_init",
     "mcp_serve",
@@ -1450,7 +1451,54 @@ min_severity: "low" (default) | "medium" | "high" | "critical" — filter thresh
         docstring_override=_MIGRATE_CHECK_DOC,
     )
 
-    return [spring_audit, impact_chain, migrate_check]
+    _VERIFY_EDIT_DOC = """\
+Semantic diff gate: did the working-tree edits change runtime behavior? JAVA/SPRING.
+
+When to call: right AFTER editing Java source, BEFORE proposing a commit — the
+in-loop guardrail. Deterministic verdict over the diff of the working tree vs HEAD.
+
+Report-only over MCP: it ALWAYS returns the verdict payload (never errors on a
+break) so you can read the result and auto-correct. Read `verdict`:
+  "pass"       — no runtime-behavior regression proven; safe to proceed.
+  "break"      — a blocking axis proved a regression; fix before committing. See
+                 `axes` + `reasons`.
+  "unverified" — an axis could not be computed (e.g. parse failure); do not treat
+                 as safe.
+
+Axes (each a diff HEAD→working):
+  contract_broken     — public API removed / visibility-downgraded / signature changed
+  tx_boundary_changed — @Transactional now on a private/final method = silent CGLIB
+                        proxy bypass (TX ignored at runtime)
+  security_delta      — a new security finding the edit introduced
+  new_orphan_bean     — a bean that lost all its injection wiring
+  blast_radius        — informational: entry points reached by the changed files
+
+Needs a git repository with a HEAD commit (it diffs the working tree vs HEAD).
+"""
+
+    verify_edit = _alias_spec(
+        "verify_edit",
+        "Semantic diff gate over working-tree vs HEAD: contract / TX / security / bean-wiring. JAVA/SPRING.",
+        ("verify-edit",),
+        (
+            ToolParamSpec("repo_path", "argument", str, required=False, default=".", is_path=True,
+                          help="Absolute path to the git repository (default: current directory)."),
+        ),
+        # Report-only: --no-ci so the tool always returns the verdict JSON (a break is
+        # data for the agent, not a command failure that would surface as an error).
+        lambda inputs: [
+            "verify-edit",
+            str(inputs.get("repo_path", ".")),
+            "--no-ci",
+            "--format", "json",
+        ],
+        supported_targets=("repo_path",),
+        unsupported_targets=("file_path",),
+        validator=validate_repo_path,
+        docstring_override=_VERIFY_EDIT_DOC,
+    )
+
+    return [spring_audit, impact_chain, migrate_check, verify_edit]
 
 
 @lru_cache(maxsize=1)

sourcecode-2.6.5/src/sourcecode/parse_cache.py

@@ -0,0 +1,138 @@
+"""Content-addressed per-file parse cache (verify-edit Fase V4 — sub-second loop).
+
+The bottleneck, measured: on a 1-file edit in a large repo, ``build_repo_ir`` re-parses
+*every* file, and per-file symbol extraction dominates the working-tree CIR build (~85%
+of warm time; ~1.0s of 1.16s at 4.8k symbols). Yet the parse of an unchanged file is a
+**pure function of its bytes** — so it can be memoised across builds.
+
+This cache stores the output of ``_extract_symbols`` — ``(package, imports, symbols)`` —
+keyed by a content hash of ``(rel_path, capture_signature, source)``. Properties that
+make it safe:
+
+  * **Content-addressed ⇒ never stale.** The key *is* the content; a changed file yields
+    a different key and misses (re-parses), it never serves an old parse. There is no
+    invalidation to get wrong — unlike a signature-keyed cache.
+  * **Correctness never depends on it.** A miss, a corrupt entry, or an unwritable dir all
+    degrade to "parse it" — the CIR is byte-identical whether the cache hit or missed
+    (proven by the cir_hash-equivalence test, not assumed).
+  * **Isolated from the whole-CIR cache.** Its own directory tree; it can never poison the
+    ``java-cir`` knowledge entry that ``explain``/``impact``/``review-pr`` share.
+
+Deserialisation was measured at ~5× cheaper than re-parsing (38ms vs 197ms for 4.8k
+symbols), so the round-trip is a real win, not a wash.
+"""
+from __future__ import annotations
+
+import dataclasses
+import hashlib
+import json
+import os
+from pathlib import Path
+from typing import TYPE_CHECKING, Optional
+
+from sourcecode.context_cache import _atomic_write, _base_dir
+
+if TYPE_CHECKING:
+    from sourcecode.repository_ir import SymbolRecord
+
+_CACHE_SUBDIR = "parse-cache-v1"  # bump when the SymbolRecord shape or extractor changes
+
+
+def is_enabled() -> bool:
+    """On unless explicitly disabled (shares the context-cache kill switch). Correctness
+    is identical either way; this only trades disk for CPU."""
+    return os.environ.get("SOURCECODE_CONTEXT_CACHE_DISABLE", "") not in ("1", "true", "yes")
+
+
+def _cache_root() -> Path:
+    return _base_dir() / _CACHE_SUBDIR
+
+
+def file_key(rel_path: str, source: str, capture_sig: str) -> str:
+    """Content hash of everything ``_extract_symbols`` depends on. Two identical inputs
+    ⇒ same key (reuse); any change ⇒ different key (miss, re-parse)."""
+    h = hashlib.sha256()
+    h.update(rel_path.encode("utf-8", "replace"))
+    h.update(b"\x00")
+    h.update(capture_sig.encode("utf-8", "replace"))
+    h.update(b"\x00")
+    h.update(source.encode("utf-8", "replace"))
+    return h.hexdigest()[:32]
+
+
+def _path_for(key: str) -> Path:
+    # Shard by the first 2 hex chars so no single directory grows unbounded.
+    return _cache_root() / key[:2] / f"{key}.json"
+
+
+def get(key: str) -> "Optional[tuple[str, list[str], list[SymbolRecord]]]":
+    """Return the cached ``(package, imports, symbols)`` for *key*, or None on any miss.
+    Best-effort: a missing file, unreadable bytes, or a decode/shape error all read as a
+    miss (the caller then parses) — never an exception."""
+    if not is_enabled():
+        return None
+    from sourcecode.repository_ir import SymbolRecord
+
+    p = _path_for(key)
+    try:
+        raw = p.read_bytes()
+    except OSError:
+        return None
+    try:
+        d = json.loads(raw)
+        pkg = d["p"]
+        imports = list(d["i"])
+        symbols = [SymbolRecord(**sd) for sd in d["s"]]
+    except (ValueError, KeyError, TypeError):
+        return None  # corrupt or shape-drifted entry — treat as absent, will rebuild
+    return pkg, imports, symbols
+
+
+def put(key: str, package: str, imports: list[str], symbols: "list[SymbolRecord]") -> None:
+    """Store a parse result. Best-effort and side-effect-free on failure: caching is a
+    performance aid, never a correctness dependency."""
+    if not is_enabled():
+        return
+    try:
+        payload = {
+            "p": package,
+            "i": list(imports),
+            "s": [dataclasses.asdict(s) for s in symbols],
+        }
+        data = json.dumps(payload, ensure_ascii=False).encode("utf-8")
+        p = _path_for(key)
+        p.parent.mkdir(parents=True, exist_ok=True)
+        _atomic_write(p, data)
+    except Exception:
+        pass  # unwritable / serialisation fault — silently skip; correctness unaffected
+
+
+# ── generic JSON blob (V4b: the per-file *body-fact* bundle) ─────────────────────
+# The Pass-2 fact extractors (body/literal/guard/field-type/…) are, like symbol
+# extraction, pure functions of the file's bytes, so their combined output is memoised
+# under the SAME content key with a distinct suffix. Values are already plain JSON dicts
+# (atomic-fact IR), so no dataclass reconstruction is needed. Same best-effort contract:
+# a miss/corrupt entry recomputes; the CIR is byte-identical either way.
+def _blob_path(key: str) -> Path:
+    return _cache_root() / key[:2] / f"{key}.blob.json"
+
+
+def get_blob(key: str) -> Optional[dict]:
+    if not is_enabled():
+        return None
+    try:
+        return json.loads(_blob_path(key).read_bytes())
+    except (OSError, ValueError):
+        return None
+
+
+def put_blob(key: str, data: dict) -> None:
+    if not is_enabled():
+        return
+    try:
+        raw = json.dumps(data, ensure_ascii=False).encode("utf-8")
+        p = _blob_path(key)
+        p.parent.mkdir(parents=True, exist_ok=True)
+        _atomic_write(p, raw)
+    except Exception:
+        pass