code-context-control 2.120.0__tar.gz → 2.121.0__tar.gz

{code_context_control-2.120.0/code_context_control.egg-info → code_context_control-2.121.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: code-context-control
-Version: 2.120.0
+Version: 2.121.0
 Summary: Local MCP code-intelligence for AI coding tools: surgical search/read/edit, agent-config version history, path-level access + masking guards, and a multi-project hub.
 Author-email: Dimitri Tselenchuk <dtselenc@gmail.com>
 License-Expression: Apache-2.0

{code_context_control-2.120.0 → code_context_control-2.121.0}/cli/c3.py

@@ -92,7 +92,7 @@ console = Console() if HAS_RICH else None
 # Config
 CONFIG_DIR = ".c3"
 CONFIG_FILE = ".c3/config.json"
-__version__ = "2.120.0"
+__version__ = "2.121.0"
 
 
 def _compress_file_cli(compressor, path, mode="smart", **kw):

{code_context_control-2.120.0 → code_context_control-2.121.0}/cli/mcp_server.py

@@ -85,7 +85,7 @@ def _build_instructions(ide_name: str) -> str:
     return (
         "C3 — local code intelligence. Route by goal:\n"
         "  FIND candidates → c3_search\n"
-        "  MAP file shape → c3_compress(mode='map') then READ content → c3_read(symbols=…)\n"
+        "  MAP a file → c3_read(file_path) with no symbols, then READ → c3_read(symbols=…); batch maps → c3_compress\n"
         "  EDIT code → c3_edit (always; it logs to the ledger automatically)\n"
         "  VALIDATE after every edit → c3_validate\n"
         "  BLAST RADIUS before shared-symbol edits → c3_impact\n"
@@ -583,8 +583,10 @@ async def c3_memory(action: str, query: str = "", fact: str = "",
 @mcp.tool()
 async def c3_read(file_path: str, symbols: Any = None, lines: Any = None,
             include_docstrings: bool = True, ctx: Context = None) -> str:
-    """READ exact content. Use after c3_compress when you need real source (read-only, plan-mode safe).
-    file_path: single or comma-separated. symbols: function/class names. lines: int, [start,end], or list of ranges."""
+    """READ source, or MAP a file when called with only file_path (read-only, plan-mode safe).
+    file_path: single or comma-separated. symbols: names as the map prints them (Class.method ok).
+    lines: int, [start,end], or list of ranges. No symbols/lines = one line per symbol with
+    signature and [La-Lb] range at ~10% of the file's tokens; then read the symbols you need."""
     path_err = validate_file_path(file_path)
     if path_err:
         return f"[c3_read:error] {path_err}"
@@ -597,10 +599,11 @@ async def c3_read(file_path: str, symbols: Any = None, lines: Any = None,
 
 
 @mcp.tool()
-async def c3_compress(file_path: str, mode: str = "smart", ctx: Context = None) -> str:
-    """MAP file shape — classes/functions/imports at 40-70% tokens (read-only, plan-mode safe).
-    Use before c3_read to know which symbols to fetch. Modes: map, dense_map, smart, diff, bug_scan, ast.
-    file_path: single or comma-separated."""
+async def c3_compress(file_path: str, mode: str = "map", ctx: Context = None) -> str:
+    """MAP a file — one line per symbol with full signature and [La-Lb] range, ~10% of the
+    file's tokens (read-only, plan-mode safe). Same map as c3_read(file_path) with no symbols;
+    use this form for a comma-separated batch (up to 10). mode: map (default); other modes
+    are legacy."""
     path_err = validate_file_path(file_path)
     if path_err:
         return f"[c3_compress:error] {path_err}"

{code_context_control-2.120.0 → code_context_control-2.121.0}/cli/tools/agent.py

@@ -877,11 +877,10 @@ def _parallel_compress(files: list, svc, steps_log: list,
     maps = {}
 
     def compress_one(fp):
-        full_path = str(Path(svc.project_path) / fp)
         try:
-            res = svc.compressor.compress_file(full_path, "map")
-            if isinstance(res, dict) and res.get("compressed"):
-                return fp, res["compressed"]
+            fmap = svc.file_memory.get_or_build_map(fp.replace("\\", "/"))
+            if fmap and not fmap.startswith("[file_map]"):
+                return fp, fmap
         except Exception:
             pass
         return fp, None
@@ -936,11 +935,10 @@ def _parallel_validate_and_compress(files: list, svc, steps_log: list):
             return "validate", fp, "ERROR", str(e)
 
     def compress_one(fp):
-        full_path = str(Path(svc.project_path) / fp)
         try:
-            res = svc.compressor.compress_file(full_path, "map")
-            if isinstance(res, dict) and res.get("compressed"):
-                return "compress", fp, res["compressed"]
+            fmap = svc.file_memory.get_or_build_map(fp.replace("\\", "/"))
+            if fmap and not fmap.startswith("[file_map]"):
+                return "compress", fp, fmap
         except Exception:
             pass
         return "compress", fp, None

{code_context_control-2.120.0 → code_context_control-2.121.0}/cli/tools/compress.py

@@ -1,5 +1,7 @@
-"""c3_compress — Token-efficient file summaries (6 modes: map, dense_map, smart, diff, bug_scan, ast).
-Supports comma-separated paths for batch compression with parallel execution."""
+"""c3_compress — the canonical file map (services/file_map.render_map), one file or a batch.
+
+mode='map' (default) is the same text c3_read(file_path) serves. The other
+modes (dense_map, smart, diff, bug_scan, ast) are legacy and retire in 2.122.0."""
 
 import json
 import shutil
@@ -218,8 +220,14 @@ def _compress_single(file_path: str, mode: str, svc, finalize, maybe_facts) -> s
         raw_tokens = None
         map_tokens = 0
         try:
-            raw_tokens = count_tokens(full.read_text(encoding="utf-8", errors="replace"))
+            raw_text = full.read_text(encoding="utf-8", errors="replace")
+            raw_tokens = count_tokens(raw_text)
             map_tokens = count_tokens(res)
+            if map_tokens >= raw_tokens and not res.startswith("[file_map]"):
+                # A map that costs more than the file is worth nothing
+                # (docs/file-map.md § Small files).
+                res = f"[compress:{file_path}] whole file — smaller than its map\n" + raw_text
+                map_tokens = count_tokens(res)
             summary = mode
         except Exception:
             summary = "mapped"

{code_context_control-2.120.0 → code_context_control-2.121.0}/cli/tools/read.py

@@ -316,6 +316,11 @@ def handle_read(file_path: str, symbols: Any = None, lines: Any = None,
     if not ranges:
         map_cached = not svc.file_memory.needs_update(rel_path)
         file_map = svc.file_memory.get_or_build_map(rel_path)
+        if count_tokens(file_map) >= full_file_tokens():
+            # A map that costs more than the file is worth nothing: serve the
+            # file (docs/file-map.md § Small files).
+            file_map = (f"[read:{file_path}] whole file — smaller than its map\n"
+                        + raw_text)
         resp = (file_map
                 + "\n[map only — pass lines=[start,end] or symbols=[...] for exact source]"
                 + maybe_related_facts(svc, rel_path, top_k=3, context="read"))

{code_context_control-2.120.0 → code_context_control-2.121.0}/cli/tools/search.py

@@ -13,6 +13,7 @@ from pathlib import Path
 from cli.tools._helpers import finalize_with_tokens, show_token_ratios
 from core import count_tokens
 from services import access_guard
+from services.file_map import render_map
 from services.indexer import DEFAULT_CODE_EXTS
 from services.lexical_index import Filters, doc_kind
 from services.scanner import SKIP_DIRS, iter_files
@@ -473,21 +474,15 @@ def _first_file_map(rel: str, svc) -> str:
         watcher_active = (hasattr(svc, "watcher") and svc.watcher._observer.is_alive())
         if not watcher_active and svc.file_memory.needs_update(rel):
             svc.file_memory.update(rel)
-        fmap = svc.file_memory.get_or_build_map(rel)
+        record = svc.file_memory.get(rel)
+        if not record:
+            return ""
+        # Same renderer as c3_read/c3_compress, shortened to the cap by
+        # dropping symbol lines from the end (docs/file-map.md).
+        fmap = render_map(record, max_tokens=_MAP_TOKEN_CAP)
         if not fmap:
             return ""
-        if count_tokens(fmap) <= _MAP_TOKEN_CAP:
-            return f"\n  {fmap.replace(chr(10), chr(10) + '  ')}"
-        # Truncate large maps: keep first N lines
-        truncated = []
-        tok = 0
-        for fl in fmap.split("\n"):
-            tok += count_tokens(fl)
-            if tok > _MAP_TOKEN_CAP:
-                break
-            truncated.append(fl)
-        truncated.append("  [map truncated]")
-        return f"\n  {chr(10).join(truncated).replace(chr(10), chr(10) + '  ')}"
+        return f"\n  {fmap.replace(chr(10), chr(10) + '  ')}"
     except Exception:
         return ""
 
@@ -720,11 +715,13 @@ def _append_prefetch(resp: str, query: str, top_k: int, svc) -> str:
         uncached.append(fp)
 
     def compress_one(fp):
+        # The canonical map from file_memory — the same text c3_read serves
+        # (compressor.compress_file never had a "map" mode; it rendered a
+        # structure-only summary under that name).
         try:
-            full = str(Path(svc.project_path) / fp)
-            result = svc.compressor.compress_file(full, "map")
-            if isinstance(result, dict) and result.get("compressed"):
-                return fp, result["compressed"]
+            fmap = svc.file_memory.get_or_build_map(fp.replace("\\", "/"))
+            if fmap and not fmap.startswith("[file_map]"):
+                return fp, fmap
         except Exception:
             pass
         return fp, None

{code_context_control-2.120.0 → code_context_control-2.121.0/code_context_control.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: code-context-control
-Version: 2.120.0
+Version: 2.121.0
 Summary: Local MCP code-intelligence for AI coding tools: surgical search/read/edit, agent-config version history, path-level access + masking guards, and a multi-project hub.
 Author-email: Dimitri Tselenchuk <dtselenc@gmail.com>
 License-Expression: Apache-2.0

{code_context_control-2.120.0 → code_context_control-2.121.0}/code_context_control.egg-info/SOURCES.txt

@@ -225,6 +225,7 @@ services/edit_ledger.py
 services/embedding_index.py
 services/enforcement_policy.py
 services/error_reporting.py
+services/file_map.py
 services/file_memory.py
 services/git_context.py
 services/hub_service.py
@@ -357,6 +358,7 @@ tests/test_enforcement_routes.py
 tests/test_env_parser.py
 tests/test_failed_calls_do_not_unlock.py
 tests/test_federated_graph.py
+tests/test_file_map_c1.py
 tests/test_filter_backoff.py
 tests/test_ghost_files.py
 tests/test_ghost_generation.py

{code_context_control-2.120.0 → code_context_control-2.121.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "code-context-control"
-version = "2.120.0"
+version = "2.121.0"
 description = "Local MCP code-intelligence for AI coding tools: surgical search/read/edit, agent-config version history, path-level access + masking guards, and a multi-project hub."
 readme = "README.md"
 requires-python = ">=3.10"

{code_context_control-2.120.0 → code_context_control-2.121.0}/services/agents.py

@@ -923,29 +923,10 @@ class FileMemoryAgent(BackgroundAgent):
         completed = []
         failed = []
         for rel_path in files_to_process:
-            ai_summary = None
-
-            # Generate AI summary if available
-            if self.ai_available:
-                record = self.file_memory.get(rel_path)
-                section_names = ""
-                if record:
-                    names = [s.get("name", "") for s in record.get("sections", [])
-                             if s.get("type") not in ("import", "decorator")]
-                    section_names = ", ".join(names[:10])
-
-                if section_names:
-                    ai_summary = self._ai_generate(
-                        f"File: {rel_path}\n"
-                        f"Symbols: {section_names}\n\n"
-                        f"Describe the purpose of this file and its main symbols in 1-2 concise sentences. "
-                        f"Focus on what they do, not how they are implemented.",
-                        system="You are a senior architect summarizing code for an AI assistant. "
-                               "Be technical, concise, and highlight the main responsibilities of the symbols.",
-                        max_tokens=100,
-                    )
-
-            result = self.file_memory.update(rel_path, ai_summary=ai_summary)
+            # No generated summary: it was produced from symbol names alone
+            # and half of the stored ones were cut mid-sentence (2026-09-06).
+            # The map carries symbols and ranges only (docs/file-map.md).
+            result = self.file_memory.update(rel_path)
             if result:
                 updated_count += 1
                 completed.append(rel_path)

code_context_control-2.121.0/services/file_map.py

@@ -0,0 +1,353 @@
+"""The canonical file map — ONE renderer for every map C3 serves.
+
+A map is what the model reads to choose a `c3_read` target: one line per
+symbol carrying kind, qualified name, the complete signature, the return
+type when the source has one, and the exact line range. Nothing else — no
+emoji, no column padding, no AI summary, no docstrings unless asked
+(docs/file-map.md, C1 of the c3_compress remediation).
+
+    # services/compressor.py (806L python)
+    I 12 imports
+    K LARGE_FILE_LINE_THRESHOLD [L77-L77]
+    C CodeCompressor [L130-L806]
+      M CodeCompressor.compress_file(self, filepath: str, mode: str = "structure") -> dict [L166-L188]
+    F handle_compress(file_path: str, mode: str, svc, finalize, maybe_facts) -> str [L94-L114]
+
+Every symbol line matches SYMBOL_LINE_RE, so a harness, a test, or the
+model can parse the map back without knowing the language. Renders from a
+FileMemoryStore record (the `sections` tree the parsers produce); parsers
+that emit a flat list (Rust, Go) are nested here by line containment so an
+impl's methods still read as `Type.method`.
+"""
+from __future__ import annotations
+
+import re
+from typing import Any, Optional
+
+from core import count_tokens
+
+# Section type (as the parsers emit it) -> kind letter in the map.
+KINDS = {
+    "class": "C", "function": "F", "method": "M", "property": "P",
+    "constant": "K", "variable": "V", "interface": "IF", "type": "T",
+    "enum": "E", "struct": "S", "trait": "TR", "impl": "IM",
+    "heading": "H", "section": "SEC", "import": "I",
+}
+# Section types that are never a symbol line of their own.
+SKIP_TYPES = {"decorator", "comment", "content"}
+# Kinds whose line carries a parameter list when the signature has one.
+CALLABLE_KINDS = {"F", "M"}
+# Container kinds: children (explicit or by containment) nest under them.
+CONTAINER_KINDS = {"C", "IM", "TR", "S", "E", "IF"}
+# More imports than this collapse to one count line.
+IMPORTS_INLINE_MAX = 6
+# Docstring excerpt cap when include_docs=True.
+DOC_MAX_CHARS = 120
+
+SYMBOL_LINE_RE = re.compile(
+    r"^(?P<indent> *)(?P<kind>I|K|V|C|M|P|F|IF|T|E|S|TR|IM|H|SEC) "
+    r"(?P<async>async )?(?P<name>.+?)(?:\((?P<params>.*)\))?"
+    r"(?: -> (?P<ret>.+?))? \[L(?P<a>\d+)-L(?P<b>\d+)\]$")
+
+_WS = re.compile(r"\s+")
+
+# Signature grammars, most specific first. Each yields (params, ret, receiver).
+_PY_DEF = re.compile(r"^(?:async\s+)?def\s+[\w.]+\s*\((?P<params>.*)\)\s*(?:->\s*(?P<ret>.+?))?\s*:?$")
+_PY_CLASS = re.compile(r"^class\s+\w+\s*(?:\((?P<bases>.*)\))?\s*:?$")
+_GO_FUNC = re.compile(r"^func\s+(?:\((?P<recv>[^)]*)\)\s*)?\w+\s*\((?P<params>.*?)\)\s*(?P<ret>[^{]*?)\s*\{?$")
+_RS_FN = re.compile(r"^(?:pub(?:\([^)]*\))?\s+)?(?:async\s+|const\s+|unsafe\s+)*fn\s+\w+(?:<[^>]*>)?\s*\((?P<params>.*)\)\s*(?:->\s*(?P<ret>[^{]+?))?\s*(?:where\b.*)?\{?$")
+_JS_FUNC = re.compile(r"^(?:export\s+)?(?:default\s+)?(?:async\s+)?function\s*\*?\s*\w*\s*(?:<[^>]*>)?\s*\((?P<params>.*)\)\s*(?::\s*(?P<ret>[^{]+?))?\s*\{?$")
+_JS_ARROW = re.compile(r"^(?:export\s+)?(?:const|let|var)\s+\w+\s*(?::[^=]+)?=\s*(?:async\s+)?\((?P<params>.*)\)\s*(?::\s*(?P<ret>[^=]+?))?\s*=>")
+_JS_ARROW1 = re.compile(r"^(?:export\s+)?(?:const|let|var)\s+\w+\s*=\s*(?:async\s+)?(?P<params>\w+)\s*=>")
+_JS_CLASS = re.compile(r"^(?:export\s+)?(?:default\s+)?(?:abstract\s+)?class\s+\w+(?:<[^>]*>)?\s*(?:extends\s+(?P<base>[\w.<>, ]+?))?\s*(?:implements\s+(?P<impl>[\w.<>, ]+?))?\s*\{?$")
+_JS_METHOD = re.compile(r"^(?:(?:public|private|protected|static|readonly|async|get|set|override)\s+)*[\w$#]+\s*(?:<[^>]*>)?\s*\((?P<params>.*)\)\s*(?::\s*(?P<ret>[^{]+?))?\s*\{?$")
+
+
+def _norm(text: str) -> str:
+    return _WS.sub(" ", str(text or "")).strip()
+
+
+def parse_signature(signature: str, language: str) -> dict:
+    """Split a raw signature into params / ret / receiver / bases.
+
+    Whitespace-normalized (a multi-line def becomes one line); nothing is
+    truncated. Returns {} when the text has no recognisable parameter list
+    so the caller renders the bare name.
+    """
+    sig = _norm(signature)
+    if not sig:
+        return {}
+    lang = (language or "").lower()
+    out: dict = {}
+    if lang == "python":
+        m = _PY_DEF.match(sig)
+        if m:
+            out["params"] = _norm(m.group("params"))
+            if m.group("ret"):
+                out["ret"] = _norm(m.group("ret"))
+            return out
+        m = _PY_CLASS.match(sig)
+        if m and m.group("bases"):
+            out["bases"] = _norm(m.group("bases"))
+        return out
+    if lang == "go":
+        m = _GO_FUNC.match(sig)
+        if m:
+            out["params"] = _norm(m.group("params"))
+            ret = _norm(m.group("ret") or "")
+            if ret:
+                out["ret"] = ret.strip("()") if ret.startswith("(") and "," not in ret else ret
+            recv = _norm(m.group("recv") or "")
+            if recv:
+                # `s *Server` / `Server` -> Server
+                out["receiver"] = recv.split()[-1].lstrip("*")
+        return out
+    if lang == "rust":
+        m = _RS_FN.match(sig)
+        if m:
+            out["params"] = _norm(m.group("params"))
+            if m.group("ret"):
+                out["ret"] = _norm(m.group("ret"))
+        return out
+    if lang in ("javascript", "typescript"):
+        m = _JS_CLASS.match(sig)
+        if m:
+            bases = [b.strip() for b in (m.group("base") or "").split(",") if b.strip()]
+            if bases:
+                out["bases"] = ", ".join(bases)
+            return out
+        for rx in (_JS_FUNC, _JS_ARROW, _JS_METHOD):
+            m = rx.match(sig)
+            if m:
+                out["params"] = _norm(m.group("params"))
+                if m.groupdict().get("ret"):
+                    out["ret"] = _norm(m.group("ret"))
+                return out
+        m = _JS_ARROW1.match(sig)
+        if m:
+            out["params"] = m.group("params")
+        return out
+    # Unknown language: a single balanced parenthesised group is a param list.
+    m = re.match(r"^[^()]*\((?P<params>.*)\)[^()]*$", sig)
+    if m and not sig.lstrip().startswith(("class ", "struct ", "enum ")):
+        out["params"] = _norm(m.group("params"))
+    return out
+
+
+#: Languages whose `property` sections are top-level keys, not members.
+DATA_LANGUAGES = {"json", "yaml", "toml", "ini"}
+
+
+def _kind_for(section: dict, language: str) -> Optional[str]:
+    stype = str(section.get("type") or "")
+    if stype in SKIP_TYPES:
+        return None
+    if stype == "property" and (language or "").lower() in DATA_LANGUAGES:
+        return "SEC"
+    kind = KINDS.get(stype)
+    if kind is None:
+        return None
+    if kind == "M" and _is_property(section):
+        return "P"
+    if kind == "F" and _is_property(section):
+        return "P"
+    return kind
+
+
+def _is_property(section: dict) -> bool:
+    decos = section.get("decorators") or []
+    if any(d == "property" or d.endswith(".setter") or d.endswith(".getter")
+           or d == "cached_property" or d.endswith(".cached_property") for d in decos):
+        return True
+    sig = str(section.get("signature") or "")
+    return bool(re.match(r"^\s*(?:get|set)\s+[\w$#]+\s*\(", sig))
+
+
+def _heading_level(section: dict) -> int:
+    name = str(section.get("name") or "")
+    m = re.match(r"^h([1-6]):", name)
+    if m:
+        return int(m.group(1))
+    sig = str(section.get("signature") or "").lstrip()
+    if sig.startswith("#"):
+        return len(sig) - len(sig.lstrip("#"))
+    return 1
+
+
+def _heading_text(section: dict) -> str:
+    name = str(section.get("name") or "")
+    name = re.sub(r"^h[1-6]:\s*", "", name)
+    return _norm(name)
+
+
+def _first_sentence(doc: str) -> str:
+    text = _norm(doc)
+    if not text:
+        return ""
+    m = re.match(r"(.+?[.!?])(?:\s|$)", text)
+    sent = m.group(1) if m else text
+    if len(sent) > DOC_MAX_CHARS:
+        sent = sent[:DOC_MAX_CHARS - 1].rstrip() + "…"
+    return sent
+
+
+def _nest_by_containment(sections: list) -> list:
+    """Turn a flat section list into a tree by line containment.
+
+    Parsers that never populate `children` (Rust, Go, the regex fallback)
+    emit an impl/trait/class followed by its methods as siblings. A
+    callable whose range lies inside the nearest preceding container becomes
+    that container's child, so it renders qualified. Sections that already
+    carry children are left as they are.
+    """
+    out: list = []
+    stack: list = []   # open containers (dicts with a synthetic "_kids" list)
+    for sec in sections:
+        ls, le = int(sec.get("line_start") or 0), int(sec.get("line_end") or 0)
+        while stack and not (stack[-1]["line_start"] <= ls and le <= stack[-1]["line_end"]):
+            stack.pop()
+        node = dict(sec)
+        node["_kids"] = list(sec.get("children") or [])
+        if stack and not sec.get("children") and node.get("type") in (
+                "function", "method", "property", "constant", "variable", "class", "struct",
+                "enum", "type", "interface"):
+            stack[-1]["_kids"].append(node)
+        else:
+            out.append(node)
+        if node.get("type") in ("class", "impl", "trait", "struct", "enum", "interface") \
+                and le > ls:
+            stack.append(node)
+    return out
+
+
+def _display_name(section: dict, kind: str, parent_name: str, language: str,
+                  parsed: dict) -> str:
+    name = _norm(section.get("name") or "")
+    if kind == "IM":
+        name = re.sub(r"^impl\s+", "", name)
+        # `impl Trait for Type` -> Type
+        m = re.match(r"^(?:<[^>]*>\s*)?(?:.+?\s+for\s+)?(?P<t>[\w:<>]+)", name)
+        if m:
+            name = m.group("t")
+    if kind == "H":
+        return _heading_text(section)
+    if parent_name and kind in ("M", "P", "F", "K", "V", "C", "S", "E", "T", "IF") \
+            and not name.startswith(parent_name + "."):
+        return f"{parent_name}.{name}"
+    if not parent_name and parsed.get("receiver") and kind in ("M", "F"):
+        return f"{parsed['receiver']}.{name}"
+    return name
+
+
+def _render_symbol(section: dict, language: str, indent: int, parent_name: str,
+                   include_docs: bool, lines: list) -> Optional[str]:
+    kind = _kind_for(section, language)
+    if kind is None:
+        return None
+    ls = int(section.get("line_start") or 0)
+    le = int(section.get("line_end") or ls)
+    if le < ls:
+        le = ls
+    sig = str(section.get("signature") or "")
+    parsed = parse_signature(sig, language) if kind in CALLABLE_KINDS | {"C", "P"} else {}
+    # Go: a receiver method is emitted flat; the receiver is the parent.
+    if kind == "M" and not parent_name and parsed.get("receiver"):
+        pass
+    name = _display_name(section, kind, parent_name, language, parsed)
+    is_async = bool(section.get("async")) or bool(re.match(r"^\s*(?:export\s+)?async\b", sig)) \
+        or bool(re.match(r"^\s*(?:pub\s+)?async\b", sig)) \
+        or (language == "python" and bool(re.match(r"^\s*(?:@.*\n)*\s*async\s+def", sig)))
+    pad = " " * indent
+    parts = [pad + kind + " " + ("async " if is_async else "") + name]
+    if kind in CALLABLE_KINDS and "params" in parsed:
+        parts[0] += f"({parsed['params']})"
+        if parsed.get("ret"):
+            parts[0] += f" -> {parsed['ret']}"
+    elif kind == "C" and parsed.get("bases"):
+        parts[0] += f"({parsed['bases']})"
+    parts[0] += f" [L{ls}-L{le}]"
+    lines.append(parts[0])
+    if include_docs and section.get("doc"):
+        sent = _first_sentence(str(section["doc"]))
+        if sent:
+            lines.append(f'{pad}  "{sent}"')
+    return name
+
+
+def render_map(record: dict, *, include_docs: bool = False,
+               max_tokens: Optional[int] = None) -> str:
+    """Render a FileMemoryStore record as the canonical map.
+
+    `max_tokens` (search prefetch's inline cap) drops symbol lines from the
+    END and appends `… <k> more symbols` — the renderer never changes shape
+    to fit, it only shortens.
+    """
+    path = str(record.get("path") or "").replace("\\", "/")
+    total_lines = int(record.get("lines") or 0)
+    language = str(record.get("language") or "")
+    sections = list(record.get("sections") or [])
+
+    header = f"# {path} ({total_lines}L {language})".rstrip()
+    body: list = []
+
+    imports = [s for s in sections if s.get("type") == "import"]
+    others = [s for s in sections if s.get("type") != "import"]
+    if imports:
+        if len(imports) > IMPORTS_INLINE_MAX:
+            body.append(f"I {len(imports)} imports")
+        else:
+            for imp in imports:
+                ls = int(imp.get("line_start") or 0)
+                le = int(imp.get("line_end") or ls)
+                body.append(f"I {_norm(imp.get('signature') or imp.get('name'))} [L{ls}-L{le}]")
+
+    tree = _nest_by_containment(others)
+
+    def _walk(nodes: list, indent: int, parent_name: str) -> None:
+        for node in nodes:
+            kind = _kind_for(node, language)
+            if kind is None:
+                continue
+            if kind == "H":
+                level = max(1, _heading_level(node))
+                name = _render_symbol(node, language, (level - 1) * 2, "", include_docs, body)
+                continue
+            name = _render_symbol(node, language, indent, parent_name, include_docs, body)
+            kids = node.get("_kids")
+            if kids is None:
+                kids = list(node.get("children") or [])
+            if kids and kind in CONTAINER_KINDS:
+                _walk(kids, indent + 2, name or "")
+            elif kids:
+                _walk(kids, indent + 2, parent_name)
+
+    _walk(tree, 0, "")
+
+    text = "\n".join([header] + body)
+    if max_tokens is not None and count_tokens(text) > max_tokens:
+        kept = list(body)
+        while kept and count_tokens("\n".join([header] + kept)) > max_tokens:
+            kept.pop()
+        dropped = len(body) - len(kept)
+        text = "\n".join([header] + kept + [f"… {dropped} more symbols"])
+    return text
+
+
+def parse_map(text: str) -> list[dict[str, Any]]:
+    """Parse a canonical map back into symbol dicts (name, kind, a, b, params, ret, async)."""
+    out = []
+    for line in text.splitlines():
+        m = SYMBOL_LINE_RE.match(line)
+        if not m:
+            continue
+        out.append({
+            "kind": m.group("kind"),
+            "name": m.group("name"),
+            "params": m.group("params"),
+            "ret": m.group("ret"),
+            "async": bool(m.group("async")),
+            "a": int(m.group("a")),
+            "b": int(m.group("b")),
+            "depth": len(m.group("indent")) // 2,
+        })
+    return out