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

{imperal_sdk-6.5.2 → imperal_sdk-6.5.3}/.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.5.3}/CHANGELOG.md

@@ -2,6 +2,14 @@
 
 All notable changes to `imperal-sdk` are documented here.
 
+## 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.5.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: imperal-sdk
-Version: 6.5.2
+Version: 6.5.3
 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.5.3}/sdk-reference.json

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

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

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

{imperal_sdk-6.5.2 → imperal_sdk-6.5.3}/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.5.3"
 
 # 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.5.3}/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.3/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) == []