sourcecode 2.7.0__py3-none-any.whl → 3.0.0__py3-none-any.whl

sourcecode/cli.py

@@ -268,6 +268,12 @@ _SUBCOMMANDS: frozenset[str] = frozenset(
         "archetype",
         # Experimental Semantic Retrieval Engine (Layer 3.5)
         "retrieve",
+        # Published output contracts (JSON Schema)
+        "schema",
+        # Repository-wide contract gate (baseline-relative)
+        "verify",
+        # Effective configuration under a profile set
+        "posture",
     }
 )
 
@@ -298,7 +304,7 @@ _OPTIONS_WITH_VALUE: frozenset[str] = frozenset({
     "--depth",
     "--git-depth",
     "--git-days",
-    "--since",
+    "--since", "--base",
     "--path", "-p",
     "--mode",
     "--max-symbols",
@@ -308,6 +314,11 @@ _OPTIONS_WITH_VALUE: frozenset[str] = frozenset({
     "--max-importers",
     "--exclude",
     "--files",
+    "--fail-on",
+    "--baseline",
+    "--profile",
+    "--diff",
+    "--min-severity",
 })
 
 
@@ -444,6 +455,29 @@ def _is_always_include_ref(p: str) -> bool:
     return any(seg in ("security", "seguridad", "constantes") for seg in parts)
 
 
+def _changed_files_in_scan(
+    scan_paths: "Optional[list[str]]",
+    changed_files: "Optional[set[str]]",
+) -> "Optional[list[str]]":
+    """The changed files the scan actually saw, in the scan's own namespace.
+
+    `changed_files` comes from git and `scan_paths` from the file walk; both are
+    already scope-relative (see `git_analyzer.to_scope_relative`).  Intersecting
+    them is what makes `--changed-only` say *what was analyzed* rather than what
+    git happened to report: a changed file that the walk excluded (vendored,
+    ignored, outside the scan) was never analyzed and must not be listed as if
+    it were.  Security-const files ride along as read-only reference anchors.
+
+    Returns None when the scan path list is unavailable — the caller must then
+    omit the field rather than emit an empty list, which would read as "this
+    scope has no files".
+    """
+    if scan_paths is None:
+        return None
+    allowed = changed_files or set()
+    return [p for p in scan_paths if p in allowed or _is_always_include_ref(p)]
+
+
 def filter_sensitive_files(tree: dict[str, Any], redactor: Any) -> dict[str, Any]:
     """Recursively filter .env and *.secret entries from the file tree (SEC-02)."""
     filtered: dict[str, Any] = {}
@@ -549,19 +583,99 @@ def _safe_write_file(path: "Path", content: str) -> None:
         raise typer.Exit(code=1) from None
 
 
+def _stamp_envelope(content: str) -> str:
+    """Add `_meta` identity to a JSON object payload; pass anything else through.
+
+    YAML output, plain text, JSON arrays and unparseable content are returned
+    untouched — the envelope is a claim about a JSON object, and stamping
+    anything else would corrupt it.
+    """
+    stripped = content.lstrip()
+    if not stripped.startswith("{"):
+        return content
+    try:
+        import json as _je
+
+        payload = _je.loads(content)
+        if not isinstance(payload, dict):
+            return content
+        from sourcecode.envelope import attach_meta, build_meta
+
+        command, target = _active_command_context()
+        if not command:
+            return content
+        meta = build_meta(
+            command,
+            target,
+            schema_version=payload.get("schema_version"),
+        )
+        return _je.dumps(attach_meta(payload, meta), indent=2, ensure_ascii=False)
+    except Exception:
+        return content
+
+
+def _active_command_context() -> "tuple[str, Optional[Path]]":
+    """(command name, scope path) of the running invocation, from Click.
+
+    The name is the full path through the group tree ("retrieve
+    endpoint-inventory"), because that is what a consumer has to quote when it
+    asks where a payload came from.
+    """
+    try:
+        import click
+
+        ctx = click.get_current_context(silent=True)
+    except Exception:
+        return "", None
+    if ctx is None:
+        return "", None
+
+    names: list[str] = []
+    node: Any = ctx
+    while node is not None:
+        name = getattr(node, "info_name", None)
+        if name:
+            names.append(str(name))
+        node = getattr(node, "parent", None)
+    names.reverse()
+    if names and names[0] in ("ask", "sourcecode"):
+        names = names[1:]
+
+    target: "Optional[Path]" = None
+    params = getattr(ctx, "params", None) or {}
+    for key in ("path", "target", "repo", "repo_path", "directory"):
+        value = params.get(key)
+        if isinstance(value, Path):
+            target = value
+            break
+        if isinstance(value, str) and value:
+            target = Path(value)
+            break
+    if target is None:
+        target = Path.cwd()
+    return " ".join(names), target
+
+
 def _emit_command_output(
     content: str,
     output_path: "Optional[Path]",
     copy: bool,
     *,
     success_msg: "Optional[str]" = None,
+    stamp_envelope: bool = True,
 ) -> None:
     """Unified output pipeline: stdout | file | clipboard.
 
-    Single call site for every command's final output step.
+    Single call site for every command's final output step — and therefore the
+    one seam where the response envelope is stamped, so no command can ship a
+    payload without saying which version, scope and analyzer produced it.
+    `stamp_envelope=False` is for output that is not a payload about a
+    repository — a schema document describes the envelope, it does not carry one.
     File write failures emit JSON to stderr via _safe_write_file.
     Clipboard fires only when no --output path is given.
     """
+    if stamp_envelope:
+        content = _stamp_envelope(content)
     if output_path is not None:
         _safe_write_file(output_path, content)
         if success_msg:
@@ -1507,6 +1621,7 @@ def main(
     from sourcecode import cache as _cache_mod
 
     _cache_hit_content: Optional[str] = None
+    _core_dict_l1: Optional[dict] = None
     _git_sha = ""
     # HEAD SHA is diagnostic metadata — compute unconditionally, not tied to cache.
     try:
@@ -1548,10 +1663,14 @@ def main(
 
             # ── Core (analysis) flags: affect which analyzers run + scan config ──
             # Use effective_depth (not raw depth) so Java auto-adjustment is captured.
-            # acv = ANALYZER_CACHE_VERSION — bumped only when analysis logic/schema
-            # changes, NOT on every package release.  Prevents patch-bump cache wipes.
+            # acv = ANALYZER_CACHE_VERSION — manual escape hatch, NOT bumped on
+            # package release, so patch bumps never wipe the cache.
+            # acode = content hash of the analyzer itself: a change to analysis
+            # logic must invalidate results the old logic produced, and nobody has
+            # to remember to say so.
             _core_flags_str = (
                 f"acv={_cache_mod.ANALYZER_CACHE_VERSION},"
+                f"acode={_cache_mod.analyzer_fingerprint()},"
                 f"dep={dependencies},gm={graph_modules},"
                 f"docs={docs},fm={full_metrics},sem={semantics},"
                 f"arch={architecture},gc={git_context},em={env_map},"
@@ -1742,7 +1861,11 @@ def main(
             _core_hash = ""
 
     if _cache_hit_content is not None:
-        _hit_source = "L2_view" if (_view_key and _core_hash) else "L1_core"
+        # --changed-only never reads L2 (the stored view is a previous diff
+        # snapshot), so its content always came from the L1 rebuild — report that.
+        _hit_source = (
+            "L2_view" if (_view_key and _core_hash and not changed_only) else "L1_core"
+        )
 
         # P0-A/B/C: --changed-only fast path via warm cache.
         if changed_only:
@@ -1781,11 +1904,21 @@ def main(
                 # Dirty repo — filter file_paths in cached compact, unified schema.
                 try:
                     _co_base = json.loads(_cache_hit_content)
-                    _fps_all = _co_base.get("file_paths", [])
-                    _co_base["file_paths"] = [
-                        p for p in _fps_all
-                        if p in _co_uc_files or _is_always_include_ref(p)
-                    ]
+                    # The rebuilt compact view carries no `file_paths`; take the
+                    # scan namespace from the L1 core (stored with the full tree)
+                    # so the warm path lists the same analyzed files as a cold run.
+                    _co_scan: Optional[list[str]] = None
+                    if isinstance(_core_dict_l1, dict):
+                        _co_std = _core_dict_l1.get("_standard")
+                        if isinstance(_co_std, dict):
+                            _co_fps = _co_std.get("file_paths")
+                            if isinstance(_co_fps, list):
+                                _co_scan = _co_fps
+                    _co_changed = _changed_files_in_scan(_co_scan, _co_uc_files)
+                    if _co_changed is not None:
+                        _co_base["file_paths"] = _co_changed
+                    else:
+                        _co_base.pop("file_paths", None)
                     _co_base.pop("_cache", None)
                     _co_dirty = json.dumps({
                         "schema_version": "1.0",
@@ -2626,13 +2759,15 @@ def main(
         # counts are correct; filter file_paths in the output dict, not in sm.
         data = compact_view(sm, no_tree=no_tree, full=full)
         if changed_only and _allowed_changed_files:
-            # GAP-5: preserve full entry_points; filter file_paths display only.
+            # GAP-5: preserve full entry_points; the changed-file list is the only
+            # file-level surface compact carries.  compact_view never emits
+            # `file_paths` (it is a summary view), so this list is built from the
+            # scan namespace instead of filtered out of a key that is not there —
+            # otherwise every --changed-only run reported `file_paths: []`.
             # ALWAYS-INCLUDE: security-const files stay for Java constant refs.
-            _fps_full = data.get("file_paths", [])
-            data["file_paths"] = [
-                p for p in _fps_full
-                if p in _allowed_changed_files or _is_always_include_ref(p)
-            ]
+            _fps_changed = _changed_files_in_scan(sm.file_paths, _allowed_changed_files)
+            if _fps_changed is not None:
+                data["file_paths"] = _fps_changed
         if not no_redact:
             data = redact_dict(data)
         # P0-1: Apply output budget — safety net for large repos.
@@ -2949,7 +3084,8 @@ def prepare_context_cmd(
     since: Optional[str] = typer.Option(
         None,
         "--since",
-        help="Git ref for delta task (e.g. HEAD~3, main)",
+        "--base",
+        help="Git ref for delta task (e.g. HEAD~3, main). `--base` is an alias.",
     ),
     llm_prompt: bool = typer.Option(
         False,
@@ -3649,7 +3785,8 @@ def repo_ir_cmd(
     since: Optional[str] = typer.Option(
         None,
         "--since",
-        help="Git ref for symbol-level diff (e.g. HEAD~1, main)",
+        "--base",
+        help="Git ref for symbol-level diff (e.g. HEAD~1, main). `--base` is an alias.",
     ),
     files: Optional[str] = typer.Option(
         None,
@@ -4059,10 +4196,15 @@ def _group_endpoints_by_controller(endpoints: "list[dict]") -> "dict":
     Returns ``{"by_controller": {fqn: [{method, path, return_type}, ...]},
     "controller_count": int, "total": int}``. Controllers and their routes are
     ordered deterministically (controllers by name, routes by path then method).
+
+    Keyed by FQN, as the docstring always said and the code did not: grouping on
+    the simple class name merged distinct controllers that share one — keycloak
+    reported 120 groups for 123 controller classes, and the three merged groups
+    listed another package's routes.
     """
     by_ctrl: "dict[str, list[dict]]" = {}
     for ep in endpoints:
-        ctrl = ep.get("controller", "") or "<unknown>"
+        ctrl = ep.get("controller_class") or ep.get("controller", "") or "<unknown>"
         by_ctrl.setdefault(ctrl, []).append({
             "method": ep.get("method", ""),
             "path": ep.get("path", ""),
@@ -5775,7 +5917,7 @@ def verify_edit_cmd(
     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."),
+    format: str = typer.Option("json", "--format", "-f", help="Output format: json."),
     ci: bool = typer.Option(
         True,
         "--ci/--no-ci",
@@ -5842,6 +5984,190 @@ def verify_edit_cmd(
         raise typer.Exit(code=v.exit_code)
 
 
+@app.command("verify")
+def verify_cmd(
+    path: Path = typer.Argument(
+        Path("."),
+        help="Repository path (default: current directory). Checks the tree as it stands.",
+    ),
+    output_path: Optional[Path] = typer.Option(
+        None, "--output", "-o", help="Write the report JSON to a file instead of stdout."
+    ),
+    format: str = typer.Option("json", "--format", "-f", help="Output format: json."),
+    fail_on: str = typer.Option(
+        "new",
+        "--fail-on",
+        help=(
+            "What blocks: new (violations absent from the baseline — default) | "
+            "any (every violation) | never (report only)."
+        ),
+        show_default=True,
+    ),
+    baseline: Optional[Path] = typer.Option(
+        None,
+        "--baseline",
+        help="Baseline file (default: .ask/contracts-baseline.json under the repo).",
+    ),
+    capture_baseline: bool = typer.Option(
+        False,
+        "--capture-baseline",
+        help="Record today's violations as accepted debt and exit. Does not gate.",
+    ),
+    ci: bool = typer.Option(
+        True,
+        "--ci/--no-ci",
+        help="Exit non-zero on a failing/unverified report (default on — for pipelines).",
+    ),
+) -> None:
+    """Check a repository against the contracts it declares.
+
+    \b
+    `verify-edit` asks "did this edit break something?" by diffing the working
+    tree against HEAD. This asks the other question a pipeline needs: does the
+    repository satisfy its contracts right now — on a branch, a merge commit, a
+    nightly run, where there is no edit to diff.
+
+    \b
+    Baseline-relative by default. A codebase adopting contracts already violates
+    them in places; capture that once and only NEW violations block, so the gate
+    survives contact with a real repository instead of being switched off.
+
+    \b
+    Contracts live in `.ask/contracts.yml` (see `ask verify-edit --help` for the
+    rule kinds). No contracts declared → nothing to verify, exit 0.
+
+    \b
+    Exit codes (with --ci, the default): 0 = pass, 1 = violations blocked,
+    2 = unverified (contracts unreadable or the repository could not be
+    analysed — never a silent pass). Same codes as `verify-edit`.
+
+    \b
+    Examples:
+      ask verify                            # gate on new violations
+      ask verify --capture-baseline         # accept today's debt
+      ask verify --fail-on any              # gate on every violation
+      ask verify --fail-on never            # report without gating
+    """
+    from sourcecode import verify_repo as _vr
+
+    if capture_baseline:
+        try:
+            captured = _vr.capture_baseline(path, baseline)
+        except _vr.VerifyError as exc:
+            _emit_error_json(
+                INVALID_INPUT_CODE,
+                str(exc),
+                hint="Fix the contracts file, then capture the baseline again.",
+            )
+            raise typer.Exit(code=2 if ci else 0)
+        _emit_command_output(
+            _serialize_dict(
+                {
+                    "schema_version": _vr.BASELINE_SCHEMA,
+                    "baseline_file": captured["baseline_file"],
+                    "captured": len(captured["violations"]),
+                    "head_sha": captured["head_sha"],
+                },
+                format,
+            ),
+            output_path,
+            False,
+            success_msg=f"baseline written to {captured['baseline_file']}",
+        )
+        return
+
+    try:
+        report = _vr.verify_repo(path, fail_on=fail_on, baseline_path=baseline)
+    except _vr.VerifyError as exc:
+        _emit_error_json(
+            INVALID_INPUT_CODE,
+            str(exc),
+            hint=f"--fail-on accepts: {' | '.join(_vr.FAIL_ON_CHOICES)}.",
+        )
+        raise typer.Exit(code=2 if ci else 0)
+
+    _emit_command_output(
+        _serialize_dict(report.to_dict(), format),
+        output_path,
+        False,
+        success_msg=f"verify report written to {output_path}",
+    )
+    if ci and report.exit_code != 0:
+        raise typer.Exit(code=report.exit_code)
+
+
+@app.command("posture")
+def posture_cmd(
+    path: Path = typer.Argument(
+        Path("."),
+        help="Repository path (default: current directory).",
+    ),
+    profile: Optional[str] = typer.Option(
+        None,
+        "--profile",
+        help="Active profile set, comma-separated (e.g. prod or prod,metrics).",
+    ),
+    diff: Optional[str] = typer.Option(
+        None,
+        "--diff",
+        help="Compare two profile sets: --diff dev:prod (each side comma-separated).",
+    ),
+    output_path: Optional[Path] = typer.Option(
+        None, "--output", "-o", help="Write the report to a file instead of stdout."
+    ),
+    format: str = typer.Option("json", "--format", "-f", help="Output format: json or yaml."),
+) -> None:
+    """[EXPERIMENTAL] Which beans are wired under a profile set — and which cannot be decided.
+
+    \b
+    Profile detection answers "we saw a profile". This answers the question a
+    reviewer actually has: under `prod`, which conditional beans are registered,
+    which are not, and which conditions this analyzer could not evaluate.
+
+    \b
+    EXPERIMENTAL: `@Profile` is resolved completely; every other condition
+    (`@ConditionalOnProperty` and the rest of the `@Conditional*` family) is
+    named and reported unresolved, never decided. On a repository that gates
+    beans on properties, most of the answer will be "unresolved".
+
+    \b
+    Unresolved is a first-class outcome. A bean whose registration depends on a
+    property value or a condition class is never assumed active and never
+    assumed absent — a posture answer that guesses is a confident falsehood.
+
+    \b
+    Examples:
+      ask posture . --profile prod
+      ask posture . --profile prod,metrics
+      ask posture . --diff dev:prod
+    """
+    from sourcecode.posture import build_posture, diff_posture
+
+    def _parse_set(raw: str) -> set:
+        return {p.strip() for p in raw.split(",") if p.strip()}
+
+    if diff:
+        if ":" not in diff:
+            _emit_error_json(
+                INVALID_INPUT_CODE,
+                f"--diff needs two profile sets separated by ':' (got {diff!r}).",
+                hint="Example: --diff dev:prod",
+                expected="left:right",
+            )
+            raise typer.Exit(code=1)
+        left_raw, right_raw = diff.split(":", 1)
+        data = diff_posture(path, _parse_set(left_raw), _parse_set(right_raw))
+    else:
+        data = build_posture(path, _parse_set(profile) if profile else set())
+
+    _emit_command_output(
+        _serialize_dict(data, format),
+        output_path,
+        False,
+        success_msg=f"posture written to {output_path}",
+    )
+
+
 # ── Spring Boot Migration Check ───────────────────────────────────────────────
 
 
@@ -6281,8 +6607,8 @@ def pr_impact_cmd(
         help="Write output to a file instead of stdout.",
     ),
     format: str = typer.Option(
-        "text", "--format", "-f",
-        help="Output format: text (default) or json.",
+        "json", "--format", "-f",
+        help="Output format: json (default) or text.",
         show_default=True,
     ),
     fail_on: Optional[str] = typer.Option(
@@ -6321,7 +6647,7 @@ def pr_impact_cmd(
     \b
     Examples:
       ask pr-impact --files changed_files.txt
-      ask pr-impact /path/to/repo --files diff.txt --format json
+      ask pr-impact /path/to/repo --files diff.txt --format text
       ask pr-impact --files A.java,B.java --fail-on high
       git diff --name-only origin/main | ask pr-impact --files -
     """
@@ -6667,15 +6993,18 @@ def review_pr_cmd(
         help="Repository root (default: current directory)",
     ),
     since: Optional[str] = typer.Option(
-        None, "--since",
-        help="Git ref baseline for diff (e.g. origin/main, HEAD~3).",
+        None, "--since", "--base",
+        help=(
+            "Git ref baseline for diff (e.g. origin/main, HEAD~3). "
+            "`--base` is an alias: reviewing a PR, the ref is its base branch."
+        ),
     ),
     output_path: Optional[Path] = typer.Option(
         None, "--output", "-o",
         help="Write output to a file instead of stdout.",
     ),
     format: Optional[str] = typer.Option(
-        None, "--format",
+        None, "--format", "-f",
         help="Output format: json (default) | github-comment",
     ),
     copy: bool = typer.Option(
@@ -7622,13 +7951,72 @@ def version_cmd() -> None:
         typer.echo(f"ask {__version__}")
     else:
         import json as _json_ver
+        from sourcecode.envelope import ENVELOPE_VERSION, available_schemas
         typer.echo(_json_ver.dumps({
             "cli_version": __version__,
             "mcp_schema_version": __version__,
             "compatibility_schema_version": "1.0",
+            # What a consumer should actually pin against: the release string
+            # changes every release, the envelope version only when the output
+            # contract does.
+            "envelope_version": ENVELOPE_VERSION,
+            "published_schemas": available_schemas(),
         }, ensure_ascii=False))
 
 
+@app.command("schema")
+def schema_cmd(
+    name: Optional[str] = typer.Argument(
+        None,
+        help="Schema to print (e.g. envelope-v1). Omit to list what is published.",
+    ),
+    output_path: Optional[Path] = typer.Option(
+        None, "--output", "-o", help="Write the schema to a file instead of stdout.",
+    ),
+) -> None:
+    """Print a published JSON Schema for this tool's output.
+
+    \b
+    The contract a consumer pins against, shipped with the version that emits
+    it — so "which shape does this release produce?" is answered by the release
+    itself, not by documentation that can drift from it.
+
+    \b
+    Examples:
+      ask schema                  # list published schemas
+      ask schema envelope-v1      # print the response-envelope schema
+    """
+    from sourcecode.envelope import available_schemas, load_schema
+
+    names = available_schemas()
+    if name is None:
+        _emit_command_output(
+            json.dumps({"schemas": names}, indent=2, ensure_ascii=False),
+            output_path,
+            False,
+        )
+        return
+    try:
+        schema = load_schema(name)
+    except FileNotFoundError:
+        _emit_error_json(
+            INVALID_INPUT_CODE,
+            f"No published schema named '{name}'.",
+            available=names,
+            hint="Run `ask schema` to list published schemas.",
+            expected="A published schema name.",
+        )
+        raise typer.Exit(code=1)
+    # A schema document describes the envelope; stamping one into it would put
+    # an unknown keyword inside the contract a consumer validates against.
+    _emit_command_output(
+        json.dumps(schema, indent=2, ensure_ascii=False),
+        output_path,
+        False,
+        stamp_envelope=False,
+    )
+
+
 # ── config ────────────────────────────────────────────────────────────────────
 
 @app.command("config")
@@ -7747,11 +8135,14 @@ def _run_retrieval_intent(
     if trace:
         payload = {"result": payload, "runtime": run.report.to_dict()}
     out = _json.dumps(payload, indent=2, ensure_ascii=False)
-    if output_path:
-        _safe_write_file(output_path, out)
-        typer.echo(f"Retrieval result written to {output_path}")
-    else:
-        typer.echo(out)
+    # Through the common pipeline so every retrieval intent carries the same
+    # envelope as the rest of the CLI.
+    _emit_command_output(
+        out,
+        output_path,
+        False,
+        success_msg=f"Retrieval result written to {output_path}" if output_path else None,
+    )
 
 
 @retrieve_app.command("architectural-core")
@@ -8668,12 +9059,23 @@ def cache_status_cmd(
 ) -> None:
     """Show cache statistics for a repository."""
     from sourcecode import cache as _cm
-    target = _resolve_repo_root(Path(path))
+    # Report on exactly the path given, like `cache warm` and every analysis
+    # command. Resolving up to the enclosing git root reported on a different
+    # cache than the one `ask ./service-a` reads and `cache warm ./service-a`
+    # writes — so a module's cache always looked empty right after warming it.
+    target = Path(path).resolve()
+    _git_root = _resolve_repo_root(Path(path))
     stats = _cm.status(target)
+    stats["scope"] = str(target)
+    if _git_root != target:
+        stats["git_root"] = str(_git_root)
     if json_output:
         import json as _j
         typer.echo(_j.dumps(stats, indent=2, ensure_ascii=False))
     else:
+        typer.echo(f"Scope:       {target}")
+        if _git_root != target:
+            typer.echo(f"Git root:    {_git_root}  (this cache covers the scope above, not the whole repository)")
         typer.echo(f"Cache dir:   {stats['cache_dir']}")
         typer.echo(f"Cores:       {stats['cores']}")
         typer.echo(f"Views:       {stats['views']}")
@@ -8702,7 +9104,11 @@ def cache_clear_cmd(
     index used for cold-start bootstrapping.  Use --all to also clear it.
     """
     from sourcecode import cache as _cm
-    target = _resolve_repo_root(Path(path))
+    # Clear exactly the path given, for the same reason `cache warm` warms it:
+    # resolving to the git root left a module's own cache untouched and
+    # unreachable — `cache clear ./service-a` reported "Removed 0 file(s)" while
+    # that module's cache stayed on disk with no way to evict it.
+    target = Path(path).resolve()
     _clear_ris = include_ris or all_
     if not yes:
         _ris_note = " (including RIS)" if _clear_ris else " (RIS preserved — use --all to also clear it)"

sourcecode/context_cache.py

@@ -84,6 +84,12 @@ ENVELOPE_VERSION: str = "1"
 #: Producer identity — the exact code that built the context. Package version
 #: bumps naturally participate in the key so a new release never reads context
 #: built by an older one.
+#:
+#: The package version alone is not the exact code: it does not move between
+#: releases, so during development — and in any install running unreleased code —
+#: context built by the old logic is served to the new logic. The analyzer content
+#: hash closes that window; the version stays in the key because it is readable in
+#: diagnostics and cheap.
 PRODUCER_VERSION: str = _PKG_VERSION
 
 _DEFAULT_TTL_DAYS: int = 30
@@ -288,10 +294,13 @@ class ContextCache:
         discriminator; for command-agnostic knowledge (the normal case) leave it
         unset and prefer :meth:`knowledge_key`.
         """
+        from sourcecode.cache import analyzer_fingerprint
+
         material = _UNIT_SEP.join([
             self._signature,
             KL_SCHEMA_VERSION,
             PRODUCER_VERSION,
+            analyzer_fingerprint(),
             ENVELOPE_VERSION,
             scope,
             target or "",