imperal-sdk 6.5.2__tar.gz → 6.6.0__tar.gz

{imperal_sdk-6.5.2 → imperal_sdk-6.6.0}/.github/workflows/publish.yml

@@ -75,6 +75,28 @@ jobs:
           # on publish success.
           skip-existing: true
 
+  move-stable:
+    name: Move the stable branch to this release
+    needs: publish
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      # The `stable` branch is what every install from git names (webbee autoupdate, `pipx reinstall`, `uv tool
+      # upgrade`): moved here to the release just published -- only forward, a re-run of an older tag leaves it.
+      - name: Move
+        run: |
+          if git ls-remote --exit-code origin refs/heads/stable >/dev/null; then
+            git fetch -q origin stable
+            if git merge-base --is-ancestor HEAD FETCH_HEAD; then
+              echo "stable is already at or past this release"; exit 0
+            fi
+          fi
+          git push origin "HEAD:refs/heads/stable"
+
   # When a tag push triggered us (and there is no Release yet), also
   # create the GitHub Release so the version page is populated. No-op
   # when the trigger was already release:published.

{imperal_sdk-6.5.2 → imperal_sdk-6.6.0}/CHANGELOG.md

@@ -2,6 +2,35 @@
 
 All notable changes to `imperal-sdk` are documented here.
 
+## 6.6.0 - 2026-11-13
+
+From the imperal-mcp 0.9.14 field test.
+
+### Added
+- `Symbol.doc`: a symbol carries its docstring or the comment above it; Python, TypeScript and JavaScript symbols also
+  take scope_facts' definitions (module constants such as `PANEL_ORIGIN`), so the local index and the vault's are one
+  extractor's.
+- A project's own route decorator that names a URL path (`@door("/v1/x", methods=["GET"])`, `path=`, `method=`) declares
+  an endpoint; a decorator that names no path (`@lru_cache(128)`) does not.
+- IR runner: `{{args.x}}` names the function's parameters, like `{{event.x}}` (the spec and every agent wrote `args`;
+  it resolved to "" and a stored link came back empty).
+
+### Fixed
+- A function held by a `const` inside a function (an arrow handler inside a React component) is a definition; search
+  never found `completeSignIn`/`handleLogin` although outline saw them. `EXTRACTOR_VERSION` 5: the vault asks every
+  older blob again.
+- IR: one rule for the checker and the runner. `validate_step` requires a step `id` and names verb fields placed at the
+  step root ("must go under 'args'"); `run_steps` validates every step before it runs; `store.create` without
+  `args.data` says so instead of `KeyError: 'data'`.
+
+## 6.5.3 - 2026-11-06
+
+### Added
+- `code_links.contracts_reached(symbols, endpoints, callers_of)`: the endpoints a change reaches, meaning a handler
+  that is one of the symbols or calls one through up to 3 callers, each with its call chain. Field report 06.11 #3:
+  `contract_slice(session_for_sid)` returned nothing, because the endpoint's handler calls it and endpoints were matched
+  by their own text only. The kernel and the MCP use this one algorithm.
+
 ## 6.5.2 - 2026-11-06
 
 ### Fixed

{imperal_sdk-6.5.2 → imperal_sdk-6.6.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: imperal-sdk
-Version: 6.5.2
+Version: 6.6.0
 Summary: SDK for building Imperal Cloud extensions
 Author: Imperal, Inc.
 Author-email: Valentin Scerbacov <valentin@imperal.io>

{imperal_sdk-6.5.2 → imperal_sdk-6.6.0}/sdk-reference.json

@@ -1,5 +1,5 @@
 {
-  "sdk_version": "6.5.2",
+  "sdk_version": "6.6.0",
   "symbols": {
     "ActionResult": {
       "action_vocab_safe": false,

{imperal_sdk-6.5.2 → imperal_sdk-6.6.0}/sdk_claims.json

@@ -1,5 +1,5 @@
 {
-  "_sdk_version": "6.5.2",
+  "_sdk_version": "6.6.0",
   "constants": {
     "max_call_depth": {
       "counts_root": true,

{imperal_sdk-6.5.2 → imperal_sdk-6.6.0}/src/imperal_sdk/__init__.py

@@ -1,7 +1,7 @@
 """Imperal Cloud SDK — build extensions for the Imperal platform."""
 from typing import TYPE_CHECKING
 
-__version__ = "6.5.2"
+__version__ = "6.6.0"
 
 # 5.2.2 (2026-06-11): the package root resolves its public surface lazily
 # (PEP 562). The eager imports pulled the HTTP transport (Context / client

{imperal_sdk-6.5.2 → imperal_sdk-6.6.0}/src/imperal_sdk/code_index.py

@@ -12,6 +12,7 @@ import base64
 import hashlib
 import os
 import re
+import dataclasses
 from dataclasses import asdict, dataclass, field
 from typing import Iterable
 
@@ -26,6 +27,7 @@ class Symbol:
     start_line: int
     end_line: int
     signature: str = ""
+    doc: str = ""        # its docstring / the comment above it (from scope_facts) -- search answers carry it
 
 
 @dataclass
@@ -227,6 +229,33 @@ def _endpoint_refs(fn, call) -> tuple:
     return tuple(sorted(refs))
 
 
+def _known_route_decorator(dec: "ast.Call") -> bool:
+    """@x.get / @x.route / @x.api_route: the frameworks' own route decorators (read below by their verb)."""
+    return isinstance(dec.func, ast.Attribute) and (dec.func.attr.lower() in _HTTP_METHODS
+                                                     or dec.func.attr.lower() in ("route", "api_route"))
+
+
+def _decorator_path(dec: "ast.Call") -> str:
+    """The URL path a decorator call declares: its first argument or path= / route= / rule=, when it starts with
+    "/" ("" for any decorator that names no path -- @lru_cache(128), @retry("x"))."""
+    cand = [dec.args[0]] if dec.args else []
+    cand += [k.value for k in dec.keywords if k.arg in ("path", "route", "rule")]
+    for c in cand:
+        got = _literal_string(c)
+        if isinstance(got, str) and got.startswith("/") and len(got) > 1 and " " not in got:
+            return got
+    return ""
+
+
+def _method_kw(dec: "ast.Call") -> list:
+    """method="POST" as one keyword (the plural methods=[...] is _methods_kw's)."""
+    for k in dec.keywords:
+        if k.arg == "method":
+            got = _literal_string(k.value)
+            return [got.lower()] if got else []
+    return []
+
+
 def _python_contracts(path: str, text: str):
     try:
         tree = ast.parse(text)
@@ -247,6 +276,17 @@ def _python_contracts(path: str, text: str):
                                                       node.lineno, _endpoint_refs(funcs.get(handler), node)))
         if isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef)):
             for dec in node.decorator_list:
+                if isinstance(dec, ast.Call) and not _known_route_decorator(dec):
+                    # any other decorator that names a path is the project's own route declarer (live 2026-11-13:
+                    # the gateway's @door("/v1/panel/redirect", methods=["GET"]) had no endpoint)
+                    route = _decorator_path(dec)
+                    if route:
+                        for method in (_methods_kw(dec) or _method_kw(dec) or ["get"]):
+                            if method in _HTTP_METHODS:
+                                endpoints.append(EndpointEvidence(
+                                    method.upper(), _route_of(prefixes, "", route), node.name, path,
+                                    getattr(dec, "lineno", node.lineno), _endpoint_refs(node, dec)))
+                    continue
                 if not isinstance(dec, ast.Call) or not isinstance(dec.func, ast.Attribute):
                     continue
                 verb = dec.func.attr.lower()
@@ -683,9 +723,11 @@ def _lang_for(path: str) -> str:
 # 3 (2026-11-04): a blob is sent without its text -- facts with descriptions (``Def.doc``, ``BlobFacts.doc``), its
 # line hashes and size; a config as its parsed keys. The vault asks every version of an older extractor again, so the
 # text it held is replaced by the index (owner 2026-11-04: the vault holds the index, never the code)
-EXTRACTOR_VERSION = "4"
+EXTRACTOR_VERSION = "5"
 # 4 (2026-11-06): Go, Rust, Java, Kotlin, C#, PHP, Ruby carry imports and references (``code_langs``); TS/JS default
 # exports, CommonJS exports, dynamic import(); Vue / Svelte / Astro components -- every older blob is asked again
+# 5 (2026-11-13): a function held by a const inside a function (an arrow handler in a React component) is a
+# definition with its doc; a bare route decorator (@door("/x")) declares an endpoint
 MAX_FILE_BYTES = 10 * 1024 * 1024     # one file in the code index (Cloud OS: shared vault, many users)
 MAX_REPO_FILES = 20_000
 INDEXABLE_EXT = (".py", ".pyi", ".ts", ".tsx", ".mts", ".cts", ".js", ".jsx", ".mjs", ".cjs", ".vue", ".svelte",
@@ -1646,8 +1688,10 @@ def _ts_walk(sc: _Scope, node, scope: list, ctx: str, local: set, exported: bool
                 continue
             name, value = decl.child_by_field_name("name"), decl.child_by_field_name("value")
             typ = decl.child_by_field_name("type")
-            if name is not None and name.type == "identifier" and (not scope or scope[-1][1] == "class"):
-                fn_value = value is not None and value.type in _TS_FUNCTION_VALUES
+            fn_value = value is not None and value.type in _TS_FUNCTION_VALUES
+            # a function held by a const INSIDE a function is a definition too (live 2026-11-13: completeSignIn and
+            # handleLogin inside a React component were never found by search_code, outline saw them)
+            if name is not None and name.type == "identifier" and (not scope or scope[-1][1] == "class" or fn_value):
                 if not scope or fn_value:
                     nm = sc.text(name)
                     parent = scope[-1] if scope else None
@@ -2240,9 +2284,40 @@ def parse_file(path: str, text: str) -> FileIndex | None:
             stack.extend(node.children)
     except Exception:
         return fi  # parse error -> line-only, fail-soft
+    if lang in _SCOPE_FACT_LANGS:
+        _with_scope_defs(fi, path, text)
     return fi
 
 
+# the languages scope_facts reads: their symbols also take its definitions (nested arrow functions, module constants)
+# and descriptions, so the local index and the vault's index are one extractor's (2026-11-13)
+_SCOPE_FACT_LANGS = frozenset({"python", "typescript", "tsx", "javascript"})
+_SCOPE_DEF_KINDS = frozenset({"function", "method", "class", "type"})
+
+
+def _with_scope_defs(fi: "FileIndex", path: str, text: str) -> None:
+    try:
+        fx = scope_facts(path, text)
+    except Exception:
+        return
+    if fx is None:
+        return
+    lines = text.split("\n")
+    have = {(s.name, s.start_line): i for i, s in enumerate(fi.symbols)}
+    for d in fx.defs:
+        at = have.get((d.name, d.start_line))
+        if at is not None:
+            if d.doc and not fi.symbols[at].doc:
+                fi.symbols[at] = dataclasses.replace(fi.symbols[at], doc=d.doc)
+            continue
+        # a module-level constant is a definition worth finding (PANEL_ORIGIN); a local variable is not
+        if d.kind in _SCOPE_DEF_KINDS or (d.kind == "variable" and d.qualname == d.name):
+            sig = (lines[d.start_line - 1] if 0 < d.start_line <= len(lines) else "")[:200]
+            fi.symbols.append(Symbol(name=d.name, kind=d.kind, path=path, start_line=d.start_line,
+                                     end_line=d.end_line, signature=sig, doc=d.doc))
+            have[(d.name, d.start_line)] = len(fi.symbols) - 1
+
+
 def build_index(root: str, files: list[str]) -> ProjectIndex:
     idx = ProjectIndex()
     base = os.path.realpath(root)

{imperal_sdk-6.5.2 → imperal_sdk-6.6.0}/src/imperal_sdk/code_links.py

@@ -831,3 +831,55 @@ def impact_summary(symbols, resolved, users: int, by_name: int, same_file: int =
     elif not users:
         head += " and no other file mentions the name"
     return head
+
+
+# ── contracts reached through callers (field report 06.11 #3) ────────────────────────────────
+
+def _bare(name) -> str:
+    """A definition's own name: ``path::Class.method`` -> ``method``."""
+    return str(name or "").split("::")[-1].rsplit(".", 1)[-1]
+
+
+def contracts_reached(symbols, endpoints, callers_of, depth: int = 3, k: int = 50) -> list:
+    """The endpoints a change to ``symbols`` reaches: an endpoint whose handler IS one of them, or calls one of them
+    through up to ``depth`` callers. ``endpoints``: the catalog's records (``handler`` = the handler's qualname);
+    ``callers_of(names) -> {name: [qualnames of the definitions that call it]}`` asks the code graph (graph_slice).
+    Each endpoint returned carries ``via`` ("handler" | "caller") and ``chain`` (``mint_ticket -> session_for_sid``).
+    Field report 06.11 #3: contract_slice(session_for_sid) answered nothing -- the endpoint's handler CALLS it, and
+    endpoints were matched by their own text only. One algorithm for every client (kernel, MCP). PURE but for
+    ``callers_of``; never raises on a failing one (what was reached so far stands)."""
+    chain: dict = {}
+    for s in symbols or []:
+        b = _bare(s)
+        if b:
+            chain.setdefault(b, [b])
+    frontier = list(chain)
+    for _ in range(max(0, int(depth))):
+        if not frontier:
+            break
+        try:
+            got = callers_of(list(frontier)) or {}
+        except Exception:
+            break
+        nxt = []
+        for name in frontier:
+            for caller in got.get(name) or []:
+                c = _bare(caller)
+                if c and c not in chain:
+                    chain[c] = [c] + chain[name]
+                    nxt.append(c)
+        frontier = nxt
+    out, seen = [], set()
+    for e in endpoints or []:
+        if not isinstance(e, dict):
+            continue
+        h = _bare(e.get("handler"))
+        if h not in chain:
+            continue
+        key = (e.get("repo") or e.get("repo_key"), e.get("method"), e.get("route") or e.get("key"), h)
+        if key in seen:
+            continue
+        seen.add(key)
+        out.append({**e, "via": "handler" if len(chain[h]) == 1 else "caller", "chain": " -> ".join(chain[h])})
+    out.sort(key=lambda e: (len(str(e["chain"]).split(" -> ")), str(e.get("route") or e.get("key") or "")))
+    return out[:max(1, int(k))]

{imperal_sdk-6.5.2 → imperal_sdk-6.6.0}/src/imperal_sdk/ir/actions.py

@@ -146,11 +146,25 @@ def validate_step(step: dict) -> list[str]:
     op = step.get("op")
     if op not in ACTION_SCHEMAS:
         return [f"unknown op {op!r}; valid verbs: {sorted(ACTION_SCHEMAS)}"]
+    # the runner needs an id on every step (runtime/interpreter.run_steps); one validator for both, so a step that
+    # validates also runs (2026-11-13: validate passed a step smoke then refused with "step missing required 'id'")
+    errs: list[str] = []
+    sid = step.get("id")
+    if not isinstance(sid, str) or not sid.strip():
+        errs.append("step needs an 'id' (a non-empty string other steps and conditionals can name)")
 
     if op == "conditional":
         # conditional is pure control-flow — its fields (if/then/else) live at
         # the step ROOT, not under args. Validate the step dict itself.
-        return _validate_object(step, ACTION_SCHEMAS["conditional"])
+        return errs + _validate_object(step, ACTION_SCHEMAS["conditional"])
 
     args = step.get("args", {})
-    return _validate_object(args, ACTION_SCHEMAS[op])
+    if not isinstance(args, dict):
+        return errs + [f"'args' must be an object, got {type(args).__name__}"]
+    misplaced = sorted(k for k in step if k not in ("id", "op", "args", "if", "then", "else")
+                       and k in (ACTION_SCHEMAS[op].get("properties") or {}))
+    if misplaced:
+        # live 2026-11-13: {op, kind, data} at the step root read as "missing data" although data was right there
+        return errs + [f"{', '.join(misplaced)} must go under 'args': "
+                       f"{{\"id\": ..., \"op\": \"{op}\", \"args\": {{{', '.join(repr(k) + ': ...' for k in misplaced)}}}}}"]
+    return errs + _validate_object(args, ACTION_SCHEMAS[op])

{imperal_sdk-6.5.2 → imperal_sdk-6.6.0}/src/imperal_sdk/runtime/interpreter.py

@@ -15,12 +15,17 @@ from .verbs import eval_conditional, run_store, run_ai, run_call, make_directive
 
 async def run_steps(steps: list[dict], ctx: Any, *, event: dict | None = None) -> dict:
     """Execute a non-Turing declarative steps[] flow. Returns {steps, prev}."""
-    # Guard: all steps must have an "id"
-    for step in steps:
-        if "id" not in step:
-            raise ValueError(f"step missing required 'id': {step!r}")
+    # one validator for the checker and the runner: every problem of every step, named, before anything runs
+    from imperal_sdk.ir.actions import validate_step
+    problems = [f"step {s.get('id') or i + 1}: {e}" for i, s in enumerate(steps)
+                for e in (validate_step(s) if isinstance(s, dict) else ["a step must be an object"])]
+    if problems:
+        raise ValueError("invalid steps: " + "; ".join(problems))
     by_id = {s["id"]: s for s in steps}
-    tcx: dict[str, Any] = {"event": event or {}, "steps": {}, "prev": {}}
+    # `args` names the function's parameters too: the IR spec and every agent write {{args.x}}; it resolved to "" and
+    # a stored link came back with an empty url (2026-11-13). `event` stays the canonical name.
+    params = event or {}
+    tcx: dict[str, Any] = {"event": params, "args": params, "steps": {}, "prev": {}}
     # linear walk with conditional jumps
     order = [s["id"] for s in steps]
     budget = max(64, len(steps) * 8)

{imperal_sdk-6.5.2 → imperal_sdk-6.6.0}/src/imperal_sdk/runtime/verbs.py

@@ -48,6 +48,8 @@ async def run_store(op: str, args: dict, store) -> dict:
     """
     coll = args.get("kind", "")
     if op == "create":
+        if not isinstance(args.get("data"), dict):
+            raise ValueError("store.create needs args.data (an object of the fields to store)")
         doc = await store.create(coll, args["data"])
         doc_id = doc.get("id") if isinstance(doc, dict) else getattr(doc, "id", None)
         return {"id": doc_id}

{imperal_sdk-6.5.2 → imperal_sdk-6.6.0}/tests/runtime/test_interpreter.py

@@ -161,5 +161,5 @@ async def test_step_missing_id_raises():
     steps = [
         {"op": "send", "args": {"message": "no id here"}},
     ]
-    with pytest.raises(ValueError, match="missing required 'id'"):
+    with pytest.raises(ValueError, match="needs an 'id'"):
         await run_steps(steps, ctx=_ctx(caps))

imperal_sdk-6.6.0/tests/runtime/test_one_step_rule.py

@@ -0,0 +1,52 @@
+"""2026-11-13 (imperal-mcp tester): validate_ir and smoke_ir disagreed about one step, and {{args.x}} stored "".
+One rule now: a step that validates also runs, a step that does not run says why before anything runs."""
+import pytest
+
+from imperal_sdk.ir.actions import validate_step
+from imperal_sdk.runtime.interpreter import run_steps
+
+
+class _Store:
+    def __init__(self):
+        self.docs = []
+
+    async def create(self, coll, data):
+        self.docs.append((coll, data))
+        return {"id": f"d{len(self.docs)}"}
+
+
+class _Ctx:
+    def __init__(self):
+        self.store = _Store()
+
+
+SHAPES = [
+    ({"op": "store.create", "kind": "link", "data": {"url": "x"}}, False),                   # verb keys at the root, no id
+    ({"id": "s", "op": "store.create", "kind": "link", "data": {"url": "x"}}, False),       # verb keys at the root
+    ({"op": "store.create", "args": {"kind": "link", "data": {"url": "x"}}}, False),         # no id
+    ({"id": "s", "op": "store.create", "args": {"kind": "link", "data": {"url": "x"}}}, True),
+]
+
+
+@pytest.mark.parametrize("step,ok", SHAPES)
+@pytest.mark.asyncio
+async def test_validate_and_run_agree(step, ok):
+    assert (validate_step(step) == []) is ok
+    if ok:
+        await run_steps([step], _Ctx())
+    else:
+        with pytest.raises(ValueError):
+            await run_steps([step], _Ctx())
+
+
+def test_a_misplaced_key_is_named_with_where_it_goes():
+    errs = validate_step({"id": "s", "op": "store.create", "kind": "link", "data": {"url": "x"}})
+    assert any("must go under 'args'" in e and "data" in e for e in errs)
+
+
+@pytest.mark.asyncio
+async def test_args_names_the_functions_parameters():
+    ctx = _Ctx()
+    await run_steps([{"id": "s", "op": "store.create", "args": {"kind": "link", "data": {"url": "{{args.url}}"}}}],
+                    ctx, event={"url": "https://imperal.io"})
+    assert ctx.store.docs == [("link", {"url": "https://imperal.io"})]

imperal_sdk-6.6.0/tests/test_code_contracts_reached.py

@@ -0,0 +1,32 @@
+"""Field report 06.11 #3: the endpoints a change reaches -- its handler, or a handler that calls it."""
+from imperal_sdk.code_links import contracts_reached
+
+EPS = [{"repo": "gw", "method": "POST", "route": "/v1/terminal/tickets", "handler": "mint_terminal_ticket",
+        "path": "app/routers/terminal.py"},
+       {"repo": "gw", "method": "GET", "route": "/v1/health", "handler": "health", "path": "app/routers/health.py"},
+       {"repo": "gw", "method": "POST", "route": "/v1/login", "handler": "Auth.login", "path": "app/routers/auth.py"}]
+GRAPH = {"session_for_sid": ["app/routers/terminal.py::mint_terminal_ticket", "app/writers/auth.py::_write_auth_login"],
+         "_write_auth_login": ["Auth.login"]}
+
+
+def callers(names):
+    return {n: GRAPH.get(n, []) for n in names}
+
+
+def test_an_endpoint_whose_handler_calls_the_symbol_is_reached_with_its_chain():
+    got = contracts_reached(["session_for_sid"], EPS, callers)
+    assert [(e["route"], e["via"], e["chain"]) for e in got] == [
+        ("/v1/terminal/tickets", "caller", "mint_terminal_ticket -> session_for_sid"),
+        ("/v1/login", "caller", "login -> _write_auth_login -> session_for_sid")]
+
+
+def test_the_handler_itself_and_the_depth_bound():
+    assert contracts_reached(["app/routers/health.py::health"], EPS, callers)[0]["via"] == "handler"
+    assert [e["route"] for e in contracts_reached(["session_for_sid"], EPS, callers, depth=1)] == ["/v1/terminal/tickets"]
+
+
+def test_a_failing_graph_keeps_what_was_reached_and_nothing_is_invented():
+    def boom(names):
+        raise RuntimeError("vault down")
+    assert contracts_reached(["mint_terminal_ticket"], EPS, boom)[0]["via"] == "handler"
+    assert contracts_reached(["nothing_calls_me"], EPS, callers) == []

{imperal_sdk-6.5.2 → imperal_sdk-6.6.0}/tests/test_code_index_indexer.py

@@ -95,7 +95,7 @@ def test_one_table_and_the_old_private_names_stay_aliases():
     assert indexer.DEF_NODES["typescript"]["type_alias_declaration"] == "type"
     assert indexer.DEF_NODES["typescript"]["enum_declaration"] == "class"
     assert indexer._DEF_NODES is indexer.DEF_NODES and indexer._get_language is indexer.language
-    assert indexer.EXTRACTOR_VERSION == "4" and indexer.MAX_FILE_BYTES == 10 * 1024 * 1024
+    assert indexer.EXTRACTOR_VERSION == "5" and indexer.MAX_FILE_BYTES == 10 * 1024 * 1024
     assert indexer.MAX_REPO_FILES == 20_000
 
 

imperal_sdk-6.6.0/tests/test_field_test_1113.py

@@ -0,0 +1,49 @@
+"""imperal-mcp field test 2026-11-13: what search_code, impact_of_change and contract_slice missed."""
+import pytest
+
+pytest.importorskip("tree_sitter")
+
+from imperal_sdk.code_index import extract_contracts, parse_file, scope_facts  # noqa: E402
+from imperal_sdk.code_links import Linker  # noqa: E402
+
+TSX = '''/** Login page of the panel. */
+export default function LoginPage() {
+  /** Finish the sign-in after the code is approved. */
+  const completeSignIn = async () => { return 1 };
+  const handleLogin = () => { completeSignIn() };
+  const count = 3;
+  return null
+}
+'''
+
+
+def test_arrow_functions_inside_a_component_are_definitions_with_their_docs():
+    defs = {d.qualname: d for d in scope_facts("src/app/page.tsx", TSX).defs}
+    assert "LoginPage.completeSignIn" in defs and "LoginPage.handleLogin" in defs
+    assert "LoginPage.count" not in defs                      # a local value is no definition
+    syms = {s.name: s for s in parse_file("src/app/page.tsx", TSX).symbols}
+    assert {"LoginPage", "completeSignIn", "handleLogin"} <= set(syms) and "count" not in syms
+    assert syms["completeSignIn"].doc.startswith("Finish the sign-in") and syms["LoginPage"].doc
+
+
+def test_a_python_module_constant_is_a_symbol_and_functions_carry_their_docstring():
+    py = 'PANEL_ORIGIN = "https://x"\n\n\ndef build_url(p):\n    """Join the panel origin with a path."""\n    return PANEL_ORIGIN + p\n'
+    syms = {s.name: s for s in parse_file("app/config.py", py).symbols}
+    assert syms["PANEL_ORIGIN"].kind == "variable" and syms["build_url"].doc.startswith("Join the panel")
+
+
+def test_an_import_alone_is_named_by_name_never_hidden():
+    # an import with no use stays no resolved user (as in the vault: test_reexport_alias_...), but impact names it
+    from imperal_sdk.code_links import impact
+    files = {"config.py": 'PANEL_ORIGIN = "https://x"\n', "onlyimport.py": "from config import PANEL_ORIGIN\n"}
+    out = impact(Linker({p: scope_facts(p, t) for p, t in files.items()}), ["PANEL_ORIGIN"])
+    assert [b["path"] for b in out.get("by_name") or []] == ["onlyimport.py"]
+
+
+def test_a_projects_own_route_decorator_declares_an_endpoint():
+    src = ('@door("/v1/panel/redirect", methods=["GET"])\nasync def redirect(r):\n    return 1\n\n'
+           '@door(path="/v1/x", method="POST")\ndef make_x(r):\n    return 2\n\n'
+           '@lru_cache(128)\ndef cached():\n    return 3\n\n@retry("again")\ndef r2():\n    return 4\n')
+    eps, _ = extract_contracts("app/routes.py", src, "python")
+    assert sorted((e.method, e.route, e.handler) for e in eps) == [
+        ("GET", "/v1/panel/redirect", "redirect"), ("POST", "/v1/x", "make_x")]