sourcecode 1.31.18__tar.gz → 1.31.21__tar.gz

sourcecode-1.31.21/.continue-here.md

@@ -0,0 +1,87 @@
+# Handoff — sesión 22
+**Date:** 2026-05-25T09:10:25Z  
+**Branch:** master  
+**Last commit:** `f1e80b6 feat(cache): introduce two-layer cache (L1 core + L2 view)`  
+**Suite:** 1510 passed, 3 skipped — all green
+
+---
+
+## What was done this session
+
+### Credibility audit (`AUDIT_REAL_REPOS.md`)
+Full adversarial audit of `sourcecode` against Keycloak (7885 Java files) and BroadleafCommerce (2985 Java files). Findings logged in `AUDIT_REAL_REPOS.md` at repo root. Key bugs fixed in prior sessions (P0-01 Spring DI bridging, P0-02 repo-ir boundedness).
+
+### Two-layer cache architecture (this session)
+
+**Problem:** cache key was `(commit, ALL_flags)` → N flag combos × M commits = N×M full snapshots. Same commit with `--compact` vs `--agent` ran the full analysis pipeline twice.
+
+**Solution implemented:**
+- **L1 core** `core-<sha>-<analysis_hash>.json.gz` → pre-computed view data, keyed by analysis-affecting flags only
+- **L2 view** `view-<core_hash16>-<view_hash>.json.gz` → rendered string, keyed by view-affecting flags  
+- Lookup: L2 hit → L1 hit + view rebuild → full analysis (skip analysis on L1 hit)
+
+**Files changed:**
+| File | What |
+|------|------|
+| `src/sourcecode/serializer.py` | Added `core_view(sm)` + `build_view_from_core()` + `CORE_VIEW_VERSION` |
+| `src/sourcecode/cache.py` | Added `read_core/write_core`, `read_view/write_view`, `_gc_views()`, updated `_gc()` |
+| `src/sourcecode/cli.py` | Replaced single-key cache block with 2-layer lookup + write; split flags into core vs view |
+| `tests/test_cache.py` | +12 new tests: TestCoreCache, TestViewCache, TestGCLayered (44 total cache tests) |
+
+**Flag split:**
+- Core (analysis): `dep/gm/docs/fm/sem/arch/gc/em/cn/mode/exclude/depth` + version
+- View (presentation): `compact/agent/format/full/no_tree/tree/rank_by/symbol/entrypoints_only/no_redact/graph_detail/docs_depth/max_nodes/graph_edges/max_importers/emit_graph`
+
+---
+
+## Current state
+
+Working tree is **clean** — everything committed.
+
+GSD state: milestone v1.0, 13 phases all complete (100%). No pending todos in `.planning/STATE.md`.
+
+Outstanding work from `AUDIT_REAL_REPOS.md` (NOT yet implemented — only audit findings logged):
+
+### P1 remaining (from audit):
+- **BUG-P1-01** Risk score inconsistency: `OrderServiceImpl` 0 callers → risk_level: low vs `OrderDaoImpl` 0 callers → risk_level: high. Same root cause, different heuristics fire.
+- **BUG-P1-02** `project_summary` copies README blurb instead of generating from code structure
+- **BUG-P1-03** `fix-bug` returns 426 relevant files for generic NPE symptom — no score field, no cap
+- **BUG-P1-04** `indirect_callers: 0` for KeycloakSession (1992 direct callers) — BFS exhausts at level 1
+
+### P2 remaining:
+- BUG-P2-01 `bounded_contexts` detection wrong (uses utility packages, not Maven modules)
+- BUG-P2-02 `role: unknown` for all modernize high_coupling_nodes
+- BUG-P2-03 `no_security_signal` always 100% for filter-based security (JAX-RS/XML)
+- BUG-P2-04 JAX-RS sub-resource paths not composed with parent `@Path`
+- BUG-P2-05 Broadleaf admin paths mixed into REST endpoints
+- BUG-P2-06 Architecture confidence inconsistent between `--compact` and `--agent`
+- BUG-P2-07 `entry_points.controllers.methods: 21` vs endpoints finding 130 (unexplained gap)
+- BUG-P2-08 `--format`/`--no-cache` inconsistently available across subcommands
+
+### Cosmetic:
+- Code notes URLs truncated (`s.webkit.org/...`)
+- `truncated: None` vs `truncated: false` inconsistency
+- `--deep` flag referenced in output but absent from `--help`
+- `--compact --help` claims 1000-3000 tokens; measured 2856-4031
+
+---
+
+## Next session: where to start
+
+**Option A** — tackle P1 bugs from audit (highest credibility impact):
+1. P1-01: risk score consistency when direct_callers=0 (Spring impl detection)
+2. P1-02: `project_summary` generation from code structure not README
+
+**Option B** — write integration tests for 2-layer cache (verify cli.py actually hits L1 on second run with different view flags)
+
+**Option C** — version bump + changelog (v1.32.0) with 2-layer cache as headline
+
+**Recommended: Option A → P1-01 first** (user-visible correctness, shortest fix).
+
+---
+
+## Resume
+
+```
+cat .continue-here.md
+```

{sourcecode-1.31.18 → sourcecode-1.31.21}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sourcecode
-Version: 1.31.18
+Version: 1.31.21
 Summary: Deterministic codebase context for AI coding agents
 License:                                  Apache License
                                    Version 2.0, January 2004
@@ -225,7 +225,7 @@ Description-Content-Type: text/markdown
 
 **AI-ready change intelligence for Java/Spring enterprise monoliths.**
 
-![Version](https://img.shields.io/badge/version-1.31.18-blue)
+![Version](https://img.shields.io/badge/version-1.31.21-blue)
 ![Python](https://img.shields.io/badge/python-3.10%2B-green)
 
 ---
@@ -263,7 +263,7 @@ pipx install sourcecode
 
 ```bash
 sourcecode version
-# sourcecode 1.31.18
+# sourcecode 1.31.21
 ```
 
 ---

{sourcecode-1.31.18 → sourcecode-1.31.21}/README.md

@@ -2,7 +2,7 @@
 
 **AI-ready change intelligence for Java/Spring enterprise monoliths.**
 
-![Version](https://img.shields.io/badge/version-1.31.18-blue)
+![Version](https://img.shields.io/badge/version-1.31.21-blue)
 ![Python](https://img.shields.io/badge/python-3.10%2B-green)
 
 ---
@@ -40,7 +40,7 @@ pipx install sourcecode
 
 ```bash
 sourcecode version
-# sourcecode 1.31.18
+# sourcecode 1.31.21
 ```
 
 ---

{sourcecode-1.31.18 → sourcecode-1.31.21}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "sourcecode"
-version = "1.31.18"
+version = "1.31.21"
 description = "Deterministic codebase context for AI coding agents"
 readme = "README.md"
 requires-python = ">=3.9"

{sourcecode-1.31.18 → sourcecode-1.31.21}/src/sourcecode/__init__.py

@@ -1,3 +1,3 @@
 """sourcecode — Deterministic codebase context maps for AI coding agents."""
 
-__version__ = "1.31.18"
+__version__ = "1.31.21"

{sourcecode-1.31.18 → sourcecode-1.31.21}/src/sourcecode/cache.py

@@ -69,6 +69,9 @@ from typing import Any, Optional
 #: Bump this string to invalidate *all* existing cached snapshots.
 SCHEMA_VERSION: str = "2"
 
+#: Bump to invalidate all L1 core caches (independent of snapshot version).
+CORE_SCHEMA_VERSION: str = "1"
+
 #: Fields eligible for CAS deduplication (applied to top-level JSON dict keys).
 _CAS_FIELDS: frozenset[str] = frozenset([
     "file_paths",
@@ -93,11 +96,18 @@ _DEFAULT_KEEP_COMMITS: int = 5
 # Matches "snapshot-<hex_commit>-<hex_flags>.json.gz"
 _SNAPSHOT_RE = re.compile(r"^snapshot-([0-9a-f]+)-[0-9a-f]+\.json\.gz$")
 
+# Matches "core-<hex_commit>-<hex_analysis>.json.gz"
+_CORE_RE = re.compile(r"^core-([0-9a-f]+)-[0-9a-f]+\.json\.gz$")
+
+# Matches "view-<hex_core_hash16>-<hex_view_flags>.json.gz"
+_VIEW_RE = re.compile(r"^view-([0-9a-f]{16})-[0-9a-f]+\.json\.gz$")
+
 
 # ---------------------------------------------------------------------------
 # Public API — location helpers
 # ---------------------------------------------------------------------------
 
+
 def repo_id(repo_root: Path) -> str:
     """Stable 16-char hex identifier derived from the canonical repo path."""
     return hashlib.sha256(str(repo_root.resolve()).encode()).hexdigest()[:16]
@@ -190,6 +200,138 @@ def write(
     _gc(cache_d)
 
 
+# ---------------------------------------------------------------------------
+# Layer 1 — Core Analysis cache
+# ---------------------------------------------------------------------------
+
+def read_core(repo_root: Path, core_key: str) -> Optional[tuple[dict[str, Any], str]]:
+    """Read core analysis artifacts from L1 cache.
+
+    Returns ``(core_dict, core_hash)`` on hit, or ``None`` on miss.
+    ``core_hash`` is the 16-char SHA-256 of the stored core JSON, used as
+    the L2 view-key prefix so that different views of the same core share
+    a common ancestry without a full re-analysis.
+    """
+    cache_d = cache_dir(repo_root)
+    gz_path = cache_d / f"core-{core_key}.json.gz"
+    if not gz_path.exists():
+        return None
+    try:
+        raw_bytes = gzip.decompress(gz_path.read_bytes())
+        envelope = json.loads(raw_bytes.decode("utf-8"))
+    except Exception:
+        _safe_unlink(gz_path)
+        return None
+
+    if not isinstance(envelope, dict):
+        _safe_unlink(gz_path)
+        return None
+    if envelope.get("csv") != CORE_SCHEMA_VERSION:
+        _safe_unlink(gz_path)  # schema mismatch — evict
+        return None
+
+    core_data = envelope.get("data")
+    core_hash = envelope.get("hash", "")
+    if not isinstance(core_data, dict) or not core_hash:
+        _safe_unlink(gz_path)
+        return None
+
+    return core_data, core_hash
+
+
+def write_core(repo_root: Path, core_key: str, core_data: dict[str, Any]) -> str:
+    """Persist core analysis dict to L1 cache.
+
+    Returns the 16-char SHA-256 hash of the core JSON (the L2 key prefix).
+    Writes are always best-effort; failures are silently swallowed.
+
+    File layout::
+
+        ~/.sourcecode/cache/<repo_id>/core-<core_key>.json.gz
+
+    Envelope schema::
+
+        { "csv": "1",       // CORE_SCHEMA_VERSION
+          "key": "...",     // core_key passed in
+          "hash": "<h16>",  // SHA-256[:16] of core JSON — used as L2 prefix
+          "ts":  "...",     // ISO-8601 UTC write time
+          "data": {...} }   // core_view(sm) dict
+    """
+    core_json = json.dumps(core_data, ensure_ascii=False)
+    core_hash = hashlib.sha256(core_json.encode()).hexdigest()[:16]
+
+    cache_d = cache_dir(repo_root)
+    dest = cache_d / f"core-{core_key}.json.gz"
+    try:
+        cache_d.mkdir(parents=True, exist_ok=True)
+        envelope: dict[str, Any] = {
+            "csv": CORE_SCHEMA_VERSION,
+            "key": core_key,
+            "hash": core_hash,
+            "ts": _now_iso(),
+            "data": core_data,
+        }
+        payload = gzip.compress(
+            json.dumps(envelope, ensure_ascii=False).encode("utf-8"),
+            compresslevel=6,
+        )
+        dest.write_bytes(payload)
+    except Exception:
+        pass
+
+    return core_hash
+
+
+# ---------------------------------------------------------------------------
+# Layer 2 — Derived View cache
+# ---------------------------------------------------------------------------
+
+def read_view(repo_root: Path, view_key: str) -> Optional[str]:
+    """Read a rendered view string from L2 cache.
+
+    Views are stored as ``view-{view_key}.json.gz`` using the same
+    envelope+CAS format as snapshot files.  Returns the content string
+    (JSON or YAML) or ``None`` on miss.
+    """
+    cache_d = cache_dir(repo_root)
+    gz_path = cache_d / f"view-{view_key}.json.gz"
+    if not gz_path.exists():
+        return None
+    try:
+        result = _parse_envelope(gz_path.read_bytes(), cache_d)
+        if result is not None:
+            return result
+    except Exception:
+        pass
+    _safe_unlink(gz_path)
+    return None
+
+
+def write_view(
+    repo_root: Path,
+    view_key: str,
+    content: str,
+    *,
+    fmt: str = "json",
+    layers: Optional[dict[str, str]] = None,
+) -> None:
+    """Persist a rendered view string to L2 cache as ``view-{view_key}.json.gz``.
+
+    Reuses the envelope+CAS infrastructure so large fields (file_paths,
+    graph, docs …) are automatically deduplicated with other snapshots/views.
+    Writes are always best-effort; GC is **not** triggered here — callers
+    that want eviction should invoke ``_gc(cache_dir(repo_root))`` explicitly.
+    """
+    cache_d = cache_dir(repo_root)
+    dest = cache_d / f"view-{view_key}.json.gz"
+    try:
+        cache_d.mkdir(parents=True, exist_ok=True)
+        payload = _build_envelope(view_key, content, fmt, layers or {}, cache_d)
+        dest.write_bytes(payload)
+    except Exception:
+        pass
+
+
 # ---------------------------------------------------------------------------
 # Envelope (de)serialisation
 # ---------------------------------------------------------------------------
@@ -384,31 +526,39 @@ def _cas_restore(
 # ---------------------------------------------------------------------------
 
 def _gc(cache_d: Path) -> None:
-    """
-    Evict old snapshots and sweep orphaned CAS blobs.
+    """Evict old snapshots/cores/views and sweep orphaned CAS blobs.
 
-    Keeps snapshots from the last ``SOURCECODE_CACHE_KEEP_COMMITS`` distinct
-    git commits (determined by mtime of files in each commit group).
+    Keeps snapshots and cores from the last ``SOURCECODE_CACHE_KEEP_COMMITS``
+    distinct git commits (determined by newest mtime within each commit group).
+    Views are then pruned: a view survives only when its core-hash prefix
+    matches a core file in the surviving set.
     """
     keep = int(os.environ.get("SOURCECODE_CACHE_KEEP_COMMITS", _DEFAULT_KEEP_COMMITS))
 
     try:
         all_snapshots = list(cache_d.glob("snapshot-*.json.gz"))
-        if not all_snapshots:
+        all_cores = list(cache_d.glob("core-*.json.gz"))
+        all_views = list(cache_d.glob("view-*.json.gz"))
+
+        if not all_snapshots and not all_cores and not all_views:
             return
 
-        # Group snapshot files by commit SHA
+        # Group snapshot + core files by commit SHA
         groups: dict[str, list[Path]] = {}
         for f in all_snapshots:
             m = _SNAPSHOT_RE.match(f.name)
             if m:
                 groups.setdefault(m.group(1), []).append(f)
+        for f in all_cores:
+            m = _CORE_RE.match(f.name)
+            if m:
+                groups.setdefault(m.group(1), []).append(f)
 
         surviving: list[Path]
 
         if keep <= 0 or len(groups) <= keep:
-            # No eviction needed — but still sweep CAS
-            surviving = all_snapshots
+            # No eviction needed — but still sweep views + CAS
+            surviving = all_snapshots + all_cores
         else:
             def _newest_mtime(commit: str) -> float:
                 return max(p.stat().st_mtime for p in groups[commit])
@@ -422,12 +572,46 @@ def _gc(cache_d: Path) -> None:
                     for f in groups[commit]:
                         _safe_unlink(f)
 
-        _gc_cas(cache_d, surviving)
+        # Prune view files whose core hash is no longer in the surviving set
+        _gc_views(cache_d, surviving, all_views)
+
+        # Sweep orphaned CAS blobs (surviving snapshots + view files may ref them)
+        surviving_with_views = surviving + [v for v in all_views if v.exists()]
+        _gc_cas(cache_d, surviving_with_views)
 
     except Exception:
         pass  # GC failure is non-fatal
 
 
+def _gc_views(cache_d: Path, surviving: list[Path], all_views: list[Path]) -> None:
+    """Delete view files not traceable to a surviving core.
+
+    Collects the ``hash`` field from every surviving core envelope, then
+    deletes view files whose filename core-hash prefix is absent from that
+    set.  View files with unrecognisable names are left untouched.
+    """
+    if not all_views:
+        return
+
+    # Collect live core hashes from surviving core-*.json.gz files
+    live_hashes: set[str] = set()
+    for path in surviving:
+        if not path.name.startswith("core-"):
+            continue
+        try:
+            env = json.loads(gzip.decompress(path.read_bytes()).decode("utf-8"))
+            h = env.get("hash", "")
+            if h:
+                live_hashes.add(h)
+        except Exception:
+            pass  # unreadable core — conservatively keep its views unknown
+
+    for vp in all_views:
+        m = _VIEW_RE.match(vp.name)
+        if m and m.group(1) not in live_hashes:
+            _safe_unlink(vp)
+
+
 def _gc_cas(cache_d: Path, surviving_snapshots: list[Path]) -> None:
     """
     Delete CAS blobs not referenced by any snapshot in *surviving_snapshots*.

{sourcecode-1.31.18 → sourcecode-1.31.21}/src/sourcecode/cli.py

@@ -876,16 +876,30 @@ def main(
         architecture = True  # agents need full architectural signal (M4)
         graph_modules = True  # IC-003: import graph needed for architecture confidence
 
-    # ── GAP-9: Cache check — serve from global cache when git SHA unchanged ──
-    # Cache is stored in ~/.sourcecode/cache/<repo_id>/ (outside the repo).
-    # Snapshots are gzip-compressed (.json.gz) — ~85 % smaller than plain JSON.
-    # Eviction keeps the last SOURCECODE_CACHE_KEEP_COMMITS commits (default 5).
+    # ── Two-layer cache ────────────────────────────────────────────────────────
+    # L1 (core): (repo, commit, analysis_flags) → pre-computed view data dict
+    #            key  = core-<git_sha>-<analysis_hash>.json.gz
+    # L2 (view): (core_hash, view_flags)        → final rendered string
+    #            key  = view-<core_hash16>-<view_hash>.json.gz
+    #
+    # Lookup order: L2 exact hit → L1 hit + view rebuild → full analysis
+    # Write order:  full analysis → write L1 core → write L2 view
+    #
+    # Flags split:
+    #   core (analysis) — affect WHAT is analysed; same core for any view
+    #   view            — affect HOW it's presented; same view for any format variant
     import hashlib as _hashlib
     import subprocess as _sub
     from sourcecode import cache as _cache_mod
+
     _cache_hit_content: Optional[str] = None
     _git_sha = ""
-    _cache_key = ""
+    _core_key = ""
+    _view_key = ""
+    _core_hash = ""
+    _core_flags_str = ""
+    _view_flags_str = ""
+
     if not no_cache:
         try:
             _sha_r = _sub.run(
@@ -896,37 +910,112 @@ def main(
             # Only cache when target IS the git repo root (not a subdir of one),
             # to avoid polluting sub-project directories used in tests.
             if _git_sha and (target / ".git").exists():
-                # Include every output-affecting flag so different flag combos never collide
-                # Include version so cache is invalidated on sourcecode upgrades
                 from sourcecode import __version__ as _sc_version
-                # FIX-P0-1: cache key must include ALL analysis-affecting flags.
-                # Previously missing: exclude, depth, rank_by, symbol, entrypoints_only,
-                # no_redact, graph_detail, docs_depth, max_nodes, graph_edges,
-                # max_importers, emit_graph.
-                # Use effective_depth (not raw depth) so Java auto-adjustment is captured.
                 _excl_key = (
                     ",".join(sorted(e.strip() for e in exclude.split(",") if e.strip()))
                     if exclude else ""
                 )
-                _flags_str = (
+
+                # ── Core (analysis) flags: affect which analyzers run + scan config ──
+                # Use effective_depth (not raw depth) so Java auto-adjustment is captured.
+                _core_flags_str = (
                     f"v={_sc_version},"
-                    f"c={compact},ag={agent},fmt={format},full={full},"
-                    f"co={changed_only},dep={dependencies},gm={graph_modules},"
+                    f"dep={dependencies},gm={graph_modules},"
                     f"docs={docs},fm={full_metrics},sem={semantics},"
                     f"arch={architecture},gc={git_context},em={env_map},"
-                    f"cn={code_notes},tree={tree},mode={mode},"
-                    f"ex={_excl_key},depth={effective_depth},"
+                    f"cn={code_notes},mode={mode},"
+                    f"ex={_excl_key},depth={effective_depth}"
+                )
+                _core_h = _hashlib.md5(_core_flags_str.encode()).hexdigest()[:8]
+                _core_key = f"{_git_sha}-{_core_h}"
+
+                # ── View flags: output presentation only (no re-analysis needed) ──
+                _view_flags_str = (
+                    f"c={compact},ag={agent},fmt={format},full={full},"
+                    f"co={changed_only},tree={tree},nt={no_tree},"
                     f"rb={rank_by},sym={symbol},ep={entrypoints_only},"
                     f"nr={no_redact},gd={graph_detail},dd={docs_depth},"
                     f"mn={max_nodes},ge={graph_edges},mi={max_importers},"
                     f"eg={emit_graph}"
                 )
-                _flags_h = _hashlib.md5(_flags_str.encode()).hexdigest()[:8]
-                _cache_key = f"{_git_sha}-{_flags_h}"
-                _cache_hit_content = _cache_mod.read(target, _cache_key)
+                _view_h = _hashlib.md5(_view_flags_str.encode()).hexdigest()[:8]
+
+                # ── Lookup ──────────────────────────────────────────────────────
+                # Step 1: try L1 to obtain the core_hash needed for L2 key
+                _l1_result = _cache_mod.read_core(target, _core_key)
+                if _l1_result is not None:
+                    _core_dict_l1, _core_hash = _l1_result
+                    _view_key = f"{_core_hash}-{_view_h}"
+
+                    # Step 2: try L2 (exact view match)
+                    _cache_hit_content = _cache_mod.read_view(target, _view_key)
+
+                    # Step 3: L1 hit but L2 miss → rebuild view from core dict
+                    if _cache_hit_content is None:
+                        try:
+                            from sourcecode.serializer import build_view_from_core as _bvfc
+                            _rebuilt = _bvfc(
+                                _core_dict_l1,
+                                compact=compact,
+                                agent=agent,
+                                full=full,
+                                no_tree=no_tree,
+                                tree=tree,
+                            )
+                            if _rebuilt is not None:
+                                # Apply redaction
+                                if not no_redact:
+                                    from sourcecode.redactor import redact_dict as _red_l1
+                                    _rebuilt = _red_l1(_rebuilt)
+                                # Apply output budget
+                                if agent:
+                                    from sourcecode.output_budget import (
+                                        trim_to_budget as _trim_l1,
+                                        BUDGET_AGENT,
+                                    )
+                                    _rebuilt = _trim_l1(_rebuilt, BUDGET_AGENT, label="agent")
+                                elif compact:
+                                    from sourcecode.output_budget import (
+                                        trim_to_budget as _trim_l1c,
+                                        BUDGET_COMPACT,
+                                    )
+                                    _rebuilt = _trim_l1c(_rebuilt, BUDGET_COMPACT, label="compact")
+                                # Serialize
+                                if format == "yaml":
+                                    from io import StringIO as _SIO_L1
+                                    from ruamel.yaml import YAML as _YAML_L1
+                                    _yl1 = _YAML_L1()
+                                    _yl1.default_flow_style = False
+                                    _yl1.representer.add_representer(
+                                        type(None),
+                                        lambda d, v: d.represent_scalar(
+                                            "tag:yaml.org,2002:null", "null"
+                                        ),
+                                    )
+                                    _sl1 = _SIO_L1()
+                                    _yl1.dump(_rebuilt, _sl1)
+                                    _cache_hit_content = _sl1.getvalue()
+                                else:
+                                    import json as _json_l1
+                                    _cache_hit_content = _json_l1.dumps(
+                                        _rebuilt, indent=2, ensure_ascii=False
+                                    )
+                                # Cache rebuilt view in L2
+                                if _cache_hit_content:
+                                    _cache_mod.write_view(
+                                        target,
+                                        _view_key,
+                                        _cache_hit_content,
+                                        fmt=format,
+                                    )
+                        except Exception:
+                            _cache_hit_content = None  # rebuild failed → full analysis
+
         except Exception:
             _git_sha = ""
-            _cache_key = ""
+            _core_key = ""
+            _view_key = ""
+            _core_hash = ""
 
     if _cache_hit_content is not None:
         from sourcecode.serializer import write_output
@@ -1687,8 +1776,21 @@ def main(
         if changed_only and _allowed_changed_files:
             # GAP-5: preserve full entry_points for architecture context even in
             # --changed-only mode. Only filter file_paths and code_notes.
+            # ALWAYS-INCLUDE: security-const files must stay in file_paths even when
+            # not in the git diff — they resolve Java constant references used in
+            # @M3FiltroSeguridad annotations (read-only anchors, not diff output).
+            def _is_always_include_ref(p: str) -> bool:
+                name = p.rsplit("/", 1)[-1].rsplit("\\", 1)[-1]
+                if name.endswith("Const.java") or name.endswith("Constants.java"):
+                    return True
+                parts = p.replace("\\", "/").lower().split("/")
+                return any(seg in ("security", "seguridad", "constantes") for seg in parts)
+
             sm = _replace(sm,
-                file_paths=[p for p in sm.file_paths if p in _allowed_changed_files],
+                file_paths=[
+                    p for p in sm.file_paths
+                    if p in _allowed_changed_files or _is_always_include_ref(p)
+                ],
                 code_notes=[n for n in sm.code_notes if n.path in _allowed_changed_files],
             )
         data = compact_view(sm, no_tree=no_tree, full=full)
@@ -1760,18 +1862,37 @@ def main(
     _progress.finish()
     write_output(content, output=output)
 
-    # GAP-9: Persist to cache for future identical runs (git SHA unchanged)
-    # Writes versioned envelope to ~/.sourcecode/cache/<repo_id>/<key>.json.gz.
-    # Large JSON fields are extracted into shared CAS blobs (deduplication).
-    # GC runs inline after each write (keep last N commits + CAS sweep).
-    if not no_cache and _cache_key and not _pipeline_error:
-        _cache_mod.write(
-            target,
-            _cache_key,
-            content,
-            fmt=format,
-            layers=_compute_analyzer_fingerprints(),
-        )
+    # Persist to two-layer cache (git SHA unchanged → re-use on next run).
+    #
+    # L1 (core): stores pre-computed compact+agent+standard views at max
+    #   fidelity so any subsequent view can be derived without re-analysis.
+    # L2 (view): stores the exact rendered string for this flag combination.
+    #
+    # GC runs after L2 write to evict old commits and orphaned blobs/views.
+    if not no_cache and _core_key and not _pipeline_error:
+        try:
+            from sourcecode.serializer import core_view as _core_view_fn
+            _core_dict_write = _core_view_fn(sm)
+            _written_core_hash = _cache_mod.write_core(target, _core_key, _core_dict_write)
+
+            # Compute view key using the just-written core hash
+            if _written_core_hash:
+                if not _view_key:
+                    # _view_key not set (L1 was also a miss); compute it now
+                    _wvh = _hashlib.md5(_view_flags_str.encode()).hexdigest()[:8]
+                    _view_key = f"{_written_core_hash}-{_wvh}"
+                _cache_mod.write_view(
+                    target,
+                    _view_key,
+                    content,
+                    fmt=format,
+                    layers=_compute_analyzer_fingerprints(),
+                )
+                # Trigger GC (evict old commits + orphaned views + CAS blobs)
+                from sourcecode.cache import cache_dir as _cdir, _gc as _run_gc
+                _run_gc(_cdir(target))
+        except Exception:
+            pass  # non-fatal: cache write failure
 
     if _pipeline_error:
         raise typer.Exit(code=2)