Key a node on the code it reaches, not on the repository around it

`sync` follows each node function's imports through the project's own modules
— stopping at the standard library, at anything installed, and at Fluksio
itself, whose checkout would otherwise be most of every digest — and records
the file list with what it hashed to. The engine hashes those files again when
the run is claimed, so the fingerprint is live rather than a snapshot, and
falls back to what sync recorded when it cannot see them: a remote worker's
runs used to share one empty digest, and therefore one key.

Three things follow. Editing a helper a node calls into re-runs that node, as
before. Editing something the node never reaches no longer re-runs anything —
a notebook two directories away was invalidating every arm. And
`Run.code_digest` is now the hash of its nodes' digests, so it is neither
looser nor tighter than "the code behind these numbers", which is what makes
it worth joining an exported table on.

`sync` says so too: it compares the per-node digest against the stored one, so
a helper edit prints `train: updated (flow, fit)` instead of `unchanged`. The
digest is read when the document is built rather than when the flow is
declared, so a second `sync()` in one process sees an edit between them.

Also: `fluksio runs` shows only the inputs that differ from what the flow
declares, fitted to the terminal, so a flow taking a few kB of json no longer
wraps every line.

Every existing cache entry misses once — the fingerprint changed shape.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01A9Hdrmf2cwNABCnE5x9UJa

backend/fluksio/sdk/__init__.py

@@ -23,6 +23,8 @@ from collections.abc import Callable, Sequence
 from pathlib import Path
 from typing import Any, TypeVar
 
+from fluksio.sdk.imports import digest_of, reached
+
 __all__ = [
     "FLOWS",
     "Flow",
@@ -549,6 +551,18 @@ def _check(spec: NodeSpec, mode: str) -> dict[str, Any]:
     }
 
 
+def _code_of(spec: NodeSpec) -> dict[str, Any]:
+    """What this node's function calls into, which its shim does not say.
+
+    Read here rather than when the flow is declared, so a second `sync()` in
+    one process — a notebook — sees the edit that happened between them. This
+    side is the only one that can work it out at all: it has imported the
+    code, and the engine never does.
+    """
+    files = reached(spec.fn)
+    return {"code_files": files, "code_digest": digest_of(files)}
+
+
 def _serialisable(value: Any) -> bool:
     try:
         json.dumps(value)
@@ -676,7 +690,10 @@ class Flow:
             "name": self.name,
             "title": self.title,
             "mode": self.mode,
-            "nodes": self._nodes,
+            "nodes": [
+                node | _code_of(spec)
+                for spec, node in zip(self.nodes, self._nodes, strict=True)
+            ],
             "inputs": [
                 {"spec": port.spec(), "initial": port.initial} for port in self.inputs
             ],

backend/fluksio/sdk/cli.py

@@ -14,9 +14,10 @@ import importlib
 import itertools
 import json
 import pkgutil
+import shutil
 import sys
 import time
-from collections.abc import Callable, Iterator
+from collections.abc import Callable, Iterable, Iterator
 from contextlib import contextmanager, nullcontext
 from pathlib import Path
 from typing import Any
@@ -744,11 +745,36 @@ def cmd_status(args: argparse.Namespace) -> int:
         return _unreachable(exc)
 
 
-#: How much of a run's inputs the list shows. A flow taking a few kB of JSON
-#: would otherwise make the table unreadable; `client.runs()` is where the
-#: whole value is read.
+#: How much of a run's inputs the list shows when nothing says how wide the
+#: terminal is. `client.runs()` and `fluksio export runs` are where the whole
+#: value is read.
 PARAMS_WIDTH = 80
 
+#: What the columns before the inputs take: the id, status, flow, duration and
+#: stamp, with their spacing.
+LISTING_WIDTH = 84
+
+
+def _declared(client: Client, flows: Iterable[str]) -> dict[str, dict[str, Any]]:
+    """What each flow declares its inputs to be, by flow.
+
+    So the listing can leave out an input that is simply the declared value:
+    what a reader is looking for across a page of runs is where they differ,
+    and a flow taking a few kB of JSON crowds that off the line.
+    """
+    known: dict[str, dict[str, Any]] = {}
+    for name in flows:
+        try:
+            stored = client.get_flow(name) or {}
+        except (SyncError, ApiError, httpx.HTTPError):
+            # A flow deleted since its runs were recorded still lists them.
+            stored = {}
+        known[name] = {
+            str((entry.get("spec") or {}).get("name", "")): entry.get("initial")
+            for entry in (stored.get("definition") or {}).get("inputs") or []
+        }
+    return known
+
 
 def _stamp(row: dict[str, Any]) -> str:
     """What code a run ran: the commit, whether it was dirty, and the digest.
@@ -767,14 +793,29 @@ def cmd_runs(args: argparse.Namespace) -> int:
     try:
         with _client_for(args, retries=0) as client:
             rows = client.runs(flow=args.flow, limit=args.limit)
+            declared = _declared(client, {str(row["flow"]) for row in rows})
     except (SyncError, ApiError) as exc:
         return _fail(str(exc))
     except httpx.HTTPError as exc:
         return _unreachable(exc)
+    # Whatever is left of the line after the fixed columns; the fallback is
+    # what a pipe gets, since there is no width to ask for there.
+    room = max(
+        20,
+        shutil.get_terminal_size((LISTING_WIDTH + PARAMS_WIDTH, 24)).columns
+        - LISTING_WIDTH,
+    )
     for row in rows:
-        params = json.dumps(row["params"])
-        if len(params) > PARAMS_WIDTH:
-            params = params[: PARAMS_WIDTH - 3] + "..."
+        given = row["params"] or {}
+        defaults = declared.get(str(row["flow"])) or {}
+        shown = {
+            name: value
+            for name, value in given.items()
+            if name not in defaults or defaults[name] != value
+        }
+        params = json.dumps(shown)
+        if len(params) > room:
+            params = params[: room - 3] + "..."
         _say(
             f"{row['id']}  {_status(row['status'], 9)} {row['flow']:<16} "
             f"{row['duration_ms'] / 1000:7.1f}s  {_stamp(row):<22} {params}"

backend/fluksio/sdk/client.py

@@ -726,13 +726,19 @@ def _sync_one(
         if not force:
             known = _refuse_on_drift(client, target, definition)
 
-    saved = client.put_flow(target.document(origin) | {"version": version})
+    document = target.document(origin)
+    moved = _moved_code(stored, document)
+    saved = client.put_flow(document | {"version": version})
     stored_version = int((saved.get("definition") or {}).get("version") or version)
     if report.created or stored_version != version:
         # The store bumps the version only when the content actually changed,
         # so this is its own no-op detection rather than a second guess at it.
         report.changed.append("flow")
     version = stored_version
+    # Named before the shims are compared, because this is the case a shim
+    # comparison cannot see: the function is unchanged and something it calls
+    # into is not.
+    report.changed.extend(moved)
 
     for node_id, code in target.shims().items():
         if not report.created:
@@ -742,7 +748,8 @@ def _sync_one(
             if stored_code == code:
                 continue
         client.put_source(target.name, node_id, code)
-        report.changed.append(node_id)
+        if node_id not in report.changed:
+            report.changed.append(node_id)
 
     if publish and (client.get_flow(target.name) or {}).get("has_draft"):
         client.publish(target.name, version)
@@ -750,6 +757,28 @@ def _sync_one(
     return report
 
 
+def _moved_code(stored: dict[str, Any] | None, document: dict[str, Any]) -> list[str]:
+    """The nodes whose reachable code changed since the last sync.
+
+    A node is otherwise named only when its generated shim text changes, and
+    the shim reflects the declared ports rather than what the function calls
+    into — so editing a helper printed as nothing at all, which reads as
+    "there was nothing to do".
+    """
+    if stored is None:
+        return []
+    before = {
+        node.get("id"): node.get("code_digest") or ""
+        for node in (stored.get("definition") or {}).get("nodes") or []
+    }
+    return [
+        node_id
+        for node in document.get("nodes") or []
+        if (node_id := node.get("id")) in before
+        and before[node_id] != (node.get("code_digest") or "")
+    ]
+
+
 def _refuse_on_drift(
     client: Client, target: Flow, definition: dict[str, Any]
 ) -> dict[str, str]:

backend/fluksio/sdk/imports.py

@@ -0,0 +1,155 @@
+"""What code a node actually reaches, so a cache key can name it.
+
+A node's stored body is a shim that imports the real function, so it says
+nothing about what that function calls into. Hashing the whole repository
+instead says too much: it moves when a notebook two directories away does,
+which makes the digest neither necessary nor sufficient for "this run's
+numbers came from that code".
+
+This walks the imports out from the module a node's function lives in and
+stops at anything installed or standard, so what is left is the project's own
+code — including a package installed editable from its own checkout, whose
+files are its source rather than a copy under `site-packages`.
+
+The walk is static: it reads the imports out of each file rather than running
+it. A module imported by a name the code computes is therefore not followed,
+which is the same limit the yield check has, and for the same reason.
+"""
+
+from __future__ import annotations
+
+import ast
+import hashlib
+import importlib.util
+import sys
+import sysconfig
+from collections.abc import Iterator
+from pathlib import Path
+from typing import Any
+
+__all__ = ["digest_of", "reached"]
+
+
+#: Never the project's own code, however it happens to be installed. Every
+#: node's module imports the authoring API, and from a checkout or an editable
+#: install that is a source tree like any other — so without this, a node's
+#: digest is mostly this tool, and upgrading it invalidates every cache entry
+#: anybody has.
+_SELF = frozenset({"fluksio", "fluksio_worker"})
+
+
+def _foreign() -> tuple[str, ...]:
+    """Where code that is not the project's lives.
+
+    The standard library and whatever `pip install` copied. An editable
+    install is deliberately not here: its files are the checkout, and a
+    checkout is somebody's code.
+    """
+    roots = {
+        path
+        for key in ("stdlib", "platstdlib", "purelib", "platlib")
+        if (path := sysconfig.get_paths().get(key))
+    }
+    roots.update(
+        entry
+        for entry in sys.path
+        if entry.endswith(("site-packages", "dist-packages"))
+    )
+    return tuple(sorted(roots))
+
+
+def _project_file(name: str, foreign: tuple[str, ...]) -> Path | None:
+    """The file a dotted module is, if it is the project's own python."""
+    module = sys.modules.get(name)
+    origin = getattr(module, "__file__", None) if module is not None else None
+    if origin is None:
+        try:
+            spec = importlib.util.find_spec(name)
+        except (ImportError, ValueError, AttributeError):
+            return None
+        origin = spec.origin if spec is not None else None
+    if not origin or not origin.endswith(".py"):
+        return None
+    return None if origin.startswith(foreign) else Path(origin)
+
+
+def _package_of(name: str, path: Path) -> str:
+    """The package a relative import inside this module resolves against."""
+    return name if path.name == "__init__.py" else name.rpartition(".")[0]
+
+
+def _imported(tree: ast.AST, package: str) -> Iterator[str]:
+    """Every module name a file imports, relative ones resolved.
+
+    `from pkg import thing` yields both `pkg` and `pkg.thing`, since only
+    trying to resolve them says which of the two `thing` is.
+    """
+    for node in ast.walk(tree):
+        if isinstance(node, ast.Import):
+            for alias in node.names:
+                yield alias.name
+        elif isinstance(node, ast.ImportFrom):
+            base = node.module or ""
+            if node.level:
+                parts = package.split(".") if package else []
+                parts = parts[: len(parts) - (node.level - 1)]
+                base = ".".join([*parts, base]) if base else ".".join(parts)
+            if not base:
+                continue
+            yield base
+            for alias in node.names:
+                yield f"{base}.{alias.name}"
+
+
+def reached(fn: Any) -> dict[str, str]:
+    """The project modules ``fn``'s own module reaches, itself included.
+
+    Dotted name to the file it is on this machine — the name is what the
+    digest is keyed on, so an engine hashing the same code arrives at the same
+    answer; the path is how it finds the file.
+    """
+    start = getattr(fn, "__module__", "")
+    if not start:
+        return {}
+    foreign = _foreign()
+    found: dict[str, str] = {}
+    queue = [start]
+    while queue:
+        name = queue.pop()
+        if name in found or name.partition(".")[0] in _SELF:
+            continue
+        path = _project_file(name, foreign)
+        if path is None:
+            continue
+        try:
+            tree = ast.parse(path.read_bytes())
+        except (OSError, SyntaxError, ValueError):
+            continue
+        found[name] = str(path)
+        queue.extend(_imported(tree, _package_of(name, path)))
+        # The packages above it, whose `__init__` runs on the way to importing
+        # this module and is as much a part of what it does as an import is.
+        parts = name.split(".")[:-1]
+        queue.extend(".".join(parts[: index + 1]) for index in range(len(parts)))
+    return found
+
+
+def digest_of(files: dict[str, str]) -> str:
+    """What those modules hash to now, or empty if one is not readable here.
+
+    All or nothing: a digest over the half of the code an engine happens to
+    have would be a confident answer to a question it cannot see.
+    """
+    if not files:
+        return ""
+    digest = hashlib.sha256()
+    for name, path in sorted(files.items()):
+        try:
+            body = Path(path).read_bytes()
+        except OSError:
+            return ""
+        digest.update(name.encode())
+        digest.update(b"\0")
+        digest.update(body)
+        digest.update(b"\0")
+    return digest.hexdigest()