throughline 2.0.0__tar.gz → 2.2.0__tar.gz

{throughline-2.0.0/src/throughline.egg-info → throughline-2.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: throughline
-Version: 2.0.0
+Version: 2.2.0
 Summary: A Git-native requirements management tool with a scope-avalanche grounding layer: permanent UIDs, one file per item, typed links, suspect detection, and a CI-gating check.
 Author-email: Henry J Grech-Cini <henry.grechcini@gmail.com>
 License-Expression: Apache-2.0
@@ -36,7 +36,7 @@ version control; a `check` command validates the whole graph and gates CI.
 
 **Dogfooded:** throughline's own spec is itself a throughline project —
 <!-- tl:count type == 'system_requirement' -->
-153
+156
 <!-- tl:end --> system requirements,
 <!-- tl:count type == 'user_requirement' -->
 25

{throughline-2.0.0 → throughline-2.2.0}/README.md

@@ -8,7 +8,7 @@ version control; a `check` command validates the whole graph and gates CI.
 
 **Dogfooded:** throughline's own spec is itself a throughline project —
 <!-- tl:count type == 'system_requirement' -->
-153
+156
 <!-- tl:end --> system requirements,
 <!-- tl:count type == 'user_requirement' -->
 25

{throughline-2.0.0 → throughline-2.2.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "throughline"
-version = "2.0.0"
+version = "2.2.0"
 description = "A Git-native requirements management tool with a scope-avalanche grounding layer: permanent UIDs, one file per item, typed links, suspect detection, and a CI-gating check."
 readme = "README.md"
 requires-python = ">=3.11"

{throughline-2.0.0 → throughline-2.2.0}/src/throughline/cli.py

@@ -165,7 +165,8 @@ def cmd_migrate(args) -> int:
         print(f"migrated project from format version {result.start} to {result.end}")
     elif result.repaired is None:
         print(f"already at format version {result.end}"
-              + ("" if result.bound or result.declared else " — nothing to migrate"))
+              + ("" if result.bound or result.declared or result.routed
+                 else " — nothing to migrate"))
     else:
         # Already at this major, but missing configuration the major requires —
         # repaired in place. Name every binding written so the change is never
@@ -186,6 +187,17 @@ def cmd_migrate(args) -> int:
               "in use; narrow them deliberately with `tl schema`:")
         for key, values in result.declared.items():
             print(f"  {key} = {', '.join(values)}")
+    # Routes to suspicion the repair restored (SR-0188). Named per status, and kept
+    # apart from the vocabularies above, because this is the one part of the repair
+    # that widens what the lifecycle permits — an operator who did not want a
+    # particular status able to move must be able to see which ones changed.
+    if result.routed:
+        print("restored this lifecycle's route to suspicion — an item in each "
+              "status below could never be marked suspect, so withdrawing what it "
+              "grounds in left it unflagged; narrow it back with `tl schema "
+              "transition deny`:")
+        for status, suspect in result.routed.items():
+            print(f"  {status} -> {suspect}")
     # Records the repair completed. Named for the same reason the config bindings
     # are, and more so: this wrote to an accountability record, so an operator who
     # disagrees with a stamp must be able to see which item carries it (SR-0152).
@@ -1324,6 +1336,7 @@ _CTX_COMMAND_USAGE = {
     "ratify": "tl ratify <UID> --by <who> [--by-id <scheme:value>]",
     "trace": "tl trace <UID> [--direction in|out]",
     "blast": "tl blast <UID>",
+    "subgraph": "tl subgraph <UID> [--depth N] [--link-type KIND] [--format json]",
     "shape": "tl shape [--format json]",
     "dump": "tl dump [-o FILE]",
     "diagram": "tl diagram [types|transitions|both]",
@@ -1337,7 +1350,7 @@ _CTX_COMMAND_USAGE = {
     "migrate": "tl migrate",
     "review": "tl review",
     "init": "tl init [--demo]",
-    "context": "tl context",
+    "context": "tl context [<UID>]",
 }
 
 # Commands whose importance is not evident from a one-line help string, and which
@@ -1476,12 +1489,42 @@ def _context_markdown(project) -> str:
     return "\n\n".join(sections) + "\n"
 
 
+def context_item_section(project, view, *, uid_display=None) -> str:
+    """The `<UID>` section of the brief, as markdown (SR-0190).
+
+    Both `tl context <UID>` and tl-compose's union-aware version render through
+    here, so the wording an agent is trained on cannot differ between the two
+    tools — only the graph the neighbourhood was computed over does.
+    """
+    show = uid_display or (lambda u: u)
+    lines: list[str] = []
+    render_subgraph(project, view, uid_display=uid_display, emit=lines.append)
+    body = "\n".join(lines)
+    return (
+        f"## The item you were given: {show(view.start)}\n\n"
+        "Its neighbourhood — what it rests on, what rests on it, and the links "
+        "joining them. Anything listed under *depended on by* may be affected by "
+        "your change.\n\n"
+        f"```\n{body}\n```\n")
+
+
 def cmd_context(args) -> int:
     try:
         project = load_project(args.path)
     except ProjectError as e:
         return _err(str(e))
-    sys.stdout.write(_context_markdown(project))
+    uid = getattr(args, "uid", None)
+    # With no UID the output stays byte-for-byte what it has always been (SR-0190),
+    # so every existing caller and script sees no change.
+    if uid is None:
+        sys.stdout.write(_context_markdown(project))
+        sys.stdout.flush()
+        return OK
+    if project.get(uid) is None:
+        return _err(f"{uid} does not exist")
+    view = Index.build(project).subgraph(uid)
+    sys.stdout.write(f"{_context_markdown(project)}\n"
+                     f"{context_item_section(project, view)}")
     sys.stdout.flush()
     return OK
 
@@ -1576,6 +1619,81 @@ def cmd_blast(args) -> int:
     return OK
 
 
+def render_subgraph(project, view, *, uid_display=None, emit=print) -> None:
+    """Render a Neighbourhood as text (SR-0189).
+
+    The one rendering both ``tl subgraph`` and ``tl context <UID>`` use, so the
+    two cannot drift (SR-0190). ``uid_display`` is the same seam ``render_trace``
+    offers: tl-compose passes the namespace-qualified form so a borrowed clause
+    reads ``asvs:SR-0272`` rather than its mangled union UID.
+    """
+    show = uid_display or (lambda u: u)
+
+    def label(uid: str) -> str:
+        item = project.get(uid)
+        if item is None:
+            return f"{show(uid)}  (unresolved)"
+        return f"{show(uid)}  [{item.type}/{item.status}] {item.title}".rstrip()
+
+    emit(label(view.start))
+    for heading, group in (("rests on", view.upstream),
+                           ("depended on by", view.downstream)):
+        emit("")
+        if group:
+            emit(f"{heading} ({len(group)}):")
+            for uid in group:
+                emit(f"  {label(uid)}")
+        else:
+            emit(f"{heading}: none")
+    emit("")
+    if view.edges:
+        emit(f"links within this set ({len(view.edges)}):")
+        width = max(len(show(s)) for s, _lt, _t in view.edges)
+        for src, ltype, tgt in view.edges:
+            emit(f"  {show(src).ljust(width)}  -{ltype}->  {show(tgt)}")
+    else:
+        emit("links within this set: none")
+
+
+def _subgraph_json(project, view, uid_display=None) -> dict:
+    show = uid_display or (lambda u: u)
+
+    def node(uid: str) -> dict:
+        item = project.get(uid)
+        if item is None:
+            return {"uid": show(uid), "resolved": False}
+        return {"uid": show(uid), "resolved": True, "type": item.type,
+                "status": item.status, "title": item.title}
+
+    return {
+        "start": show(view.start),
+        "upstream": [show(u) for u in view.upstream],
+        "downstream": [show(u) for u in view.downstream],
+        "nodes": [node(u) for u in view.nodes],
+        "edges": [{"source": show(s), "type": lt, "target": show(t)}
+                  for s, lt, t in view.edges],
+    }
+
+
+def cmd_subgraph(args) -> int:
+    try:
+        project = load_project(args.path)
+    except ProjectError as e:
+        return _err(str(e))
+    uid = _resolve_uid(project, args.uid, "show the neighbourhood of", "UID")
+    if uid is None:
+        return USAGE
+    if project.get(uid) is None:
+        return _err(f"{uid} does not exist")
+    types = set(args.link_type) if args.link_type else None
+    view = Index.build(project).subgraph(uid, types, args.depth or 0)
+    if args.format == "json":
+        print(json.dumps(_subgraph_json(project, view), indent=2))
+    else:
+        render_subgraph(project, view)
+    return OK
+
+
 def cmd_ratify(args) -> int:
     try:
         project = load_project(args.path)
@@ -1970,6 +2088,8 @@ def build_parser() -> argparse.ArgumentParser:
     s = sub.add_parser(
         "context",
         help="emit an agent-facing Markdown brief (IDD + this project's model)")
+    s.add_argument("uid", nargs="?", default=None,
+                   help="append this item's neighbourhood to the brief")
     s.set_defaults(func=cmd_context)
 
     s = sub.add_parser("trace", help="print the link tree from a UID")
@@ -1985,6 +2105,17 @@ def build_parser() -> argparse.ArgumentParser:
     s.add_argument("--format", choices=["text", "json"], default="text")
     s.set_defaults(func=cmd_blast)
 
+    s = sub.add_parser(
+        "subgraph",
+        help="show a UID's neighbourhood — both directions plus the links between")
+    s.add_argument("uid", nargs="?", default=None,
+                   help="UID to inspect (omit on a terminal to pick one)")
+    s.add_argument("--format", choices=["text", "json"], default="text")
+    s.add_argument("--depth", type=int, default=0, help="0 = unbounded")
+    s.add_argument("--link-type", action="append", default=None, metavar="KIND",
+                   help="restrict the walk to this link type (repeatable)")
+    s.set_defaults(func=cmd_subgraph)
+
     s = sub.add_parser("ratify", help="a human takes accountability for an item")
     s.add_argument("uid", nargs="?", default=None,
                    help="UID to ratify (omit on a terminal to pick one)")

{throughline-2.0.0 → throughline-2.2.0}/src/throughline/graph.py

@@ -10,6 +10,23 @@ from __future__ import annotations
 from dataclasses import dataclass, field
 
 
+@dataclass(frozen=True)
+class Neighbourhood:
+    """The induced subgraph around one item (SR-0189).
+
+    ``upstream`` and ``downstream`` are the transitive sets reachable by outgoing
+    and incoming links respectively; ``nodes`` is the start plus both, deduplicated
+    (a cycle can put one item in each). ``edges`` is every link whose *source and
+    target both fall inside* ``nodes`` — the part neither ``trace`` nor ``blast``
+    reports, and the reason this is a distinct view rather than a flag on either.
+    """
+    start: str
+    upstream: tuple[str, ...] = ()
+    downstream: tuple[str, ...] = ()
+    nodes: tuple[str, ...] = ()
+    edges: tuple[tuple[str, str, str], ...] = ()   # (source, link type, target)
+
+
 @dataclass
 class Index:
     items: dict = field(default_factory=dict)               # uid -> Item
@@ -70,20 +87,75 @@ class Index:
             stack.extend(t for t, _k in self.out_links(cur, link_types))
         return False
 
-    def impact(self, uid: str, link_types: set[str] | None = None) -> list[str]:
-        """Transitive set reachable via *incoming* links — what depends on this
-        (SR-0035 / blast radius)."""
+    def closure(self, uid: str, direction: str, link_types: set[str] | None = None,
+                max_depth: int = 0, expand=None) -> list[str]:
+        """Transitive set reachable from ``uid`` over one direction, in
+        breadth-first discovery order and excluding ``uid`` itself.
+
+        ``direction`` is ``"out"`` (what this rests on) or ``"in"`` (what rests on
+        this). ``max_depth`` of 0 means unlimited. The single walk behind both
+        ``impact`` and ``subgraph``, so a blast radius and a neighbourhood can
+        never disagree about what points at an item (SR-0189).
+
+        ``expand`` is the boundary seam ``render_trace`` also offers: a node it
+        rejects is still reported, but is not walked through. tl-compose passes
+        one so a neighbourhood touching a borrowed clause does not swallow the
+        whole standard behind it. ``uid`` itself is always walked — a caller who
+        named it is standing on it deliberately."""
+        step = self.out_links if direction == "out" else self.in_links
         hit: list[str] = []
         seen = {uid}
-        stack = [uid]
-        while stack:
-            for src, _k in self.in_links(stack.pop(), link_types):
-                if src not in seen:
-                    seen.add(src)
-                    hit.append(src)
-                    stack.append(src)
+        frontier = [uid]
+        depth = 0
+        while frontier and (not max_depth or depth < max_depth):
+            nxt: list[str] = []
+            for cur in frontier:
+                if expand is not None and cur != uid and not expand(cur):
+                    continue
+                for other, _k in step(cur, link_types):
+                    if other not in seen:
+                        seen.add(other)
+                        hit.append(other)
+                        nxt.append(other)
+            frontier = nxt
+            depth += 1
         return hit
 
+    def impact(self, uid: str, link_types: set[str] | None = None) -> list[str]:
+        """Transitive set reachable via *incoming* links — what depends on this
+        (SR-0035 / blast radius)."""
+        return self.closure(uid, "in", link_types)
+
+    def subgraph(self, uid: str, link_types: set[str] | None = None,
+                 max_depth: int = 0, expand=None) -> Neighbourhood:
+        """The induced subgraph around ``uid`` (SR-0189) — both directed closures
+        plus every link joining two members of the resulting node set.
+
+        A target that is not a local item (dangling, or namespace-qualified and
+        resolvable only under tl-compose) stays in the node set as a leaf; it has
+        no outgoing links here, so the walk stops at it rather than failing.
+
+        ``expand`` bounds only what is *walked through*; a link joining two nodes
+        already in the set is still reported, whichever of them it starts at, or
+        the drawing would contradict the set it claims to induce."""
+        upstream = self.closure(uid, "out", link_types, max_depth, expand)
+        downstream = self.closure(uid, "in", link_types, max_depth, expand)
+        nodes = [uid, *upstream]
+        within = set(nodes)
+        for d in downstream:                 # a cycle can put one item in both
+            if d not in within:
+                within.add(d)
+                nodes.append(d)
+        edges = sorted({
+            (src, ltype, tgt)
+            for src in nodes
+            for tgt, ltype in self.out_links(src, link_types)
+            if tgt in within
+        })
+        return Neighbourhood(start=uid, upstream=tuple(upstream),
+                             downstream=tuple(downstream), nodes=tuple(nodes),
+                             edges=tuple(edges))
+
     def refines_cycle(self, cycle_link_types: set[str]) -> list[str] | None:
         WHITE, GREY, BLACK = 0, 1, 2
         colour = {u: WHITE for u in self.items}

{throughline-2.0.0 → throughline-2.2.0}/src/throughline/model.py

@@ -244,6 +244,46 @@ class Project:
             used |= {frm} | set(to)
         return used
 
+    def suspect_unreachable_statuses(self) -> list[str]:
+        """The live statuses this project's lifecycle gives no route to the
+        suspect status, sorted (SR-0174, SR-0188).
+
+        Suspicion propagation is how the withdrawal of an item's footing becomes
+        visible, and it is carried entirely by the transition table: a status with
+        no declared move to suspect silently opts every item sitting in it out of
+        the mechanism. Empty when there is nothing to answer for — a project that
+        declares no transitions is unconstrained, and one that binds no suspect
+        role has no such mechanism to disable.
+
+        Judged over the statuses an item can actually hold (SR-0177): a composing
+        project declares the statuses its *borrowed* items carry so the union
+        validates, and nothing local ever enters them; reporting those buries the
+        real gaps under noise the project cannot act on. Occupancy is taken
+        alongside reachability so a status set by hand, or left behind by a
+        lifecycle that has since changed, is still judged rather than excused —
+        but counted over locally-authored items only (SR-0178), because a tool that
+        composes by merging borrowed items would otherwise reinstate through
+        occupancy exactly what reachability excluded, and a borrowed status answers
+        to its own graph's table, which this project cannot edit.
+
+        Defined here, once, because two callers act on it and they must never
+        disagree: the gate reports each of these as a finding, and the migration
+        repair adds the missing route (SR-0188). Were the two notions of "live" to
+        drift, migration would either churn a project's configuration over
+        statuses the gate ignores, or leave the ones it reports."""
+        schema = self.schema
+        if schema.transitions is None or not (schema.status_roles or {}).get("suspect"):
+            return []
+        suspect = schema.status_roles["suspect"]
+        dead = schema.dead_statuses()
+        occupied = {i.status for i in self.items() if i._authored_uid is None}
+        reachable = schema.reachable_statuses()
+        declared = schema.statuses or (set(schema.transitions) | occupied)
+        live = declared if reachable is None else (reachable | occupied) & declared
+        return sorted(s for s in live
+                      if s != suspect and s not in dead
+                      and not schema.allows_transition(s, suspect))
+
     def relied_on_link_types(self) -> set[str]:
         """The link types this project would strand by not declaring them — see
         :meth:`relied_on_statuses`. Its configuration names them in three further

{throughline-2.0.0 → throughline-2.2.0}/src/throughline/storage.py

@@ -27,7 +27,7 @@ from .graph import Index
 from .grounding import ratification_refusal
 from .model import Item, Link, Project, Register
 from .schema import SchemaError
-from .tomledit import TomlDocument
+from .tomledit import TomlDocument, TomlEditError
 from .version import distribution_version
 
 if sys.version_info >= (3, 11):
@@ -350,34 +350,107 @@ def _backfill_vocabularies(root: Path) -> dict[str, list[str]]:
     return written
 
 
+def _backfill_suspect_routes(root: Path) -> dict[str, str]:
+    """Add a move to the suspect status from every live status the lifecycle
+    leaves unable to reach it (SR-0188). Returns ``status -> suspect`` for each
+    row widened, and is empty when suspicion already reaches everywhere it must.
+
+    SR-0175 corrected the lifecycle the Tool *ships*, and left an existing project
+    with the table it already had — so every project scaffolded before it carries
+    a suspect role that is inert for exactly the statuses `tl new` births and parks
+    items in. The gate reports that (SR-0174) and, until this, offered no remedy but
+    editing each status by hand. This is what bounds it to the one command that
+    already repairs the rest of the major's configuration.
+
+    Which statuses are at issue is asked of
+    :meth:`~throughline.model.Project.suspect_unreachable_statuses` — the same
+    predicate the gate reports from — so the repair writes exactly what the gate
+    complains about, no more and no less. Reimplementing "live" here would let the
+    two drift into churning every project's configuration over statuses the gate
+    ignores, or leaving the ones it reports.
+
+    A route is *added* to the row rather than the row rewritten, so the moves
+    already declared keep their order and any comment grouping them (SR-0183). A
+    document this editor will not touch on a guess is refused whole, before
+    anything is written, and named with the command that makes the change by hand
+    — a corrupted `throughline.toml` invalidates the entire project, so a repair
+    that cannot be made safely must not be made at all.
+
+    Idempotent: a widened row permits the move and so is no longer reported.
+    """
+    project = load_project(root)
+    gaps = project.suspect_unreachable_statuses()
+    if not gaps:
+        return {}
+    suspect = project.schema.status_roles["suspect"]
+    declared = project.config.get("transitions") or {}
+    cfg_file = root / CONFIG_NAME
+    doc = TomlDocument(cfg_file.read_text(encoding="utf-8"))
+    if not doc.has_table("transitions"):
+        # The schema saw a `transitions` key, so the project declares one — but not
+        # as a [transitions] header, and writing one here would define the table
+        # twice and stop the file parsing at all. Refuse rather than corrupt it.
+        raise ProjectError(
+            f"{cfg_file} declares its transitions somewhere other than a "
+            "[transitions] table, which `tl migrate` will not edit on a guess; "
+            f"allow the moves to '{suspect}' by hand, or one at a time with "
+            f"`tl schema transition allow <status> {suspect} --because …`")
+    for status in gaps:
+        because = (
+            f"`tl migrate` added the move to '{suspect}' (SR-0188): this "
+            f"lifecycle gave '{status}' no route to it, so an item resting in "
+            f"'{status}' could never be marked suspect and invalidating anything "
+            "it grounds in would have left it unflagged. Narrow it back "
+            f"deliberately with `tl schema transition deny {status} {suspect}`.")
+        try:
+            if status in declared:
+                doc.add_to_array("transitions", status, [suspect], because=because)
+            else:
+                doc.set_key("transitions", status, [suspect], because=because)
+        except TomlEditError as e:
+            raise ProjectError(
+                f"cannot add the '{status}' -> '{suspect}' transition to "
+                f"{cfg_file} safely: {e}. Add it by hand, or with `tl schema "
+                f"transition allow {status} {suspect} --because …`") from e
+    cfg_file.write_text(doc.text(), encoding="utf-8")
+    return {status: suspect for status in gaps}
+
+
 class RepairResult(NamedTuple):
     """What a major's repair wrote: the configuration bindings it backfilled
-    (SR-0137), the vocabularies it declared (SR-0185), and the ratification
-    records it bound (SR-0152)."""
+    (SR-0137), the routes to suspicion it restored (SR-0188), the vocabularies it
+    declared (SR-0185), and the ratification records it bound (SR-0152)."""
     config: dict[str, str] | None
+    routes: dict[str, str]
     vocabularies: dict[str, list[str]]
     stamps: dict[str, str]
 
 
 def _repair_status_roles_major(root: Path, index: Index | None) -> RepairResult:
     """The repair for the major that requires [status.roles] (SR-0137, SR-0152,
-    SR-0185).
-
-    Ordered, not merely grouped, and the order is load-bearing twice over. The
-    role bindings come first because the status vocabulary is written from what
-    the configuration relies on, and a role bound to a status is exactly that —
-    written second, the vocabulary would omit the very statuses the roles name and
-    leave the schema refusing to build. The record backfill comes last because it
-    resolves the project's schema, so everything that schema requires has to be on
-    disk before it runs. Each part is idempotent, so the sequence is.
+    SR-0185, SR-0188).
+
+    Ordered, not merely grouped, and the order is load-bearing three times over.
+    The role bindings come first because everything after them reads a status
+    through a role — the suspect route has no target until the suspect role is
+    bound — and because the status vocabulary is written from what the
+    configuration relies on, so a role written second would be omitted from the
+    very vocabulary that has to contain it and leave the schema refusing to build.
+    The suspect routes come before that vocabulary for the same reason from the
+    other side: they widen the transitions table, and the vocabulary is derived
+    from the table's endpoints, so declaring it first could leave it short of a
+    status the table now names. The record backfill comes last because it resolves
+    the project's schema, so everything that schema requires has to be on disk
+    before it runs. Each part is idempotent, so the sequence is.
 
     ``index`` reaches only the record backfill (SR-0153): a grounding view has
-    nothing to say about which declared status plays which role, or about which
-    values a vocabulary should hold, so passing it to either configuration half
-    would imply an influence it does not have."""
+    nothing to say about which declared status plays which role, which moves a
+    lifecycle should permit, or which values a vocabulary should hold, so passing
+    it to any configuration half would imply an influence it does not have."""
     roles = _backfill_status_roles(root)
+    routes = _backfill_suspect_routes(root)
     vocabularies = _backfill_vocabularies(root)
-    return RepairResult(roles, vocabularies,
+    return RepairResult(roles, routes, vocabularies,
                         _backfill_ratification_stamps(root, index=index))
 
 
@@ -432,10 +505,17 @@ class MigrationResult(NamedTuple):
     (SR-0185), and is empty when the project already declared them. Separate again
     for the same reason: this one decides what the project's items will be
     validated against from now on, so it is the part an author is most likely to
-    want to narrow, and it cannot be left to be inferred from a count."""
+    want to narrow, and it cannot be left to be inferred from a count.
+
+    ``routed`` maps each status the repair gave a route to suspicion to the suspect
+    status it can now reach (SR-0188), and is empty when suspicion already reached
+    them all. Separate for the third time, and for the sharpest version of the same
+    reason: this one widens what the lifecycle permits, which is the only part of
+    the repair that lets an item make a move the project previously forbade."""
     start: int
     end: int
     repaired: dict[str, str] | None
+    routed: dict[str, str]
     declared: dict[str, list[str]]
     bound: dict[str, str]
 
@@ -483,9 +563,10 @@ def migrate_project(path: str | Path, *,
     if current != start:
         _rewrite_format_version(cfg_file, current)
     repair = _REPAIRS.get(current)
-    result = repair(root, index) if repair is not None else RepairResult(None, {}, {})
-    return MigrationResult(start, current, result.config, result.vocabularies,
-                           result.stamps)
+    result = (repair(root, index) if repair is not None
+              else RepairResult(None, {}, {}, {}))
+    return MigrationResult(start, current, result.config, result.routes,
+                           result.vocabularies, result.stamps)
 
 
 # ------------------------------------------------------------------- YAML dump

{throughline-2.0.0 → throughline-2.2.0}/src/throughline/validate.py

@@ -119,42 +119,24 @@ def validate(project, strict: bool = False,
             "`tl migrate` declares exactly that, or `tl schema "
             f"{cmd} declare …` declares the vocabulary you mean")
 
-    # A lifecycle with no route to suspicion (SR-0174). Suspicion propagation is
-    # how the withdrawal of an item's footing becomes visible, and it is carried
-    # entirely by the transition table: a status with no declared move to suspect
-    # silently opts every item sitting in it out of the mechanism, and `invalidate`
-    # can only report the gap once it is too late to matter. Reported per status
-    # because the partial case is the one that deceives — a project whose ratified
-    # items cascade while its proposed ones do not looks healthy from every angle
-    # except the one that counts. A project that declares no transitions is
-    # unconstrained and has nothing to answer for; one that binds no suspect role
-    # has no such mechanism to disable.
-    if schema.transitions is not None and (schema.status_roles or {}).get("suspect"):
+    # A lifecycle with no route to suspicion (SR-0174). Which statuses those are is
+    # decided by Project.suspect_unreachable_statuses, because `tl migrate` repairs
+    # exactly the ones reported here (SR-0188) and a second reading of "live" here
+    # would let the gate and the repair drift apart. Reported per status because the
+    # partial case is the one that deceives — a project whose ratified items cascade
+    # while its proposed ones do not looks healthy from every angle except the one
+    # that counts. `invalidate` can only report the gap once it is too late to matter.
+    # The finding names its remedy, as the undeclared-vocabulary one above does and
+    # for the same reason (SR-0188): `tl migrate` writes exactly what is reported
+    # here, so a reader is never left to close the gap status by status by hand.
+    for status in project.suspect_unreachable_statuses():
         suspect = schema.status_roles["suspect"]
-        dead = schema.dead_statuses()
-        # Only statuses an item can actually hold are judged (SR-0177). A composing
-        # project declares the statuses its borrowed items carry so the union
-        # validates, and nothing local ever enters them; reporting those as gaps
-        # buries the real ones under noise the project cannot act on. Occupancy is
-        # taken alongside reachability so a status set by hand, or left behind by a
-        # lifecycle that has since changed, is still judged rather than excused —
-        # but counted over locally-authored items only (SR-0178). A tool that composes
-        # by merging borrowed items, rather than only their vocabulary, otherwise
-        # reinstates through occupancy exactly what reachability excluded; and the
-        # borrowed status answers to its own graph's transition table, which this
-        # project cannot edit and that graph's own check already judges.
-        occupied = {i.status for i in project.items() if i._authored_uid is None}
-        reachable = schema.reachable_statuses()
-        declared = schema.statuses or (set(schema.transitions) | occupied)
-        live = declared if reachable is None else (reachable | occupied) & declared
-        for status in sorted(live):
-            if status == suspect or status in dead:
-                continue
-            if not schema.allows_transition(status, suspect):
-                add("suspect-unreachable", "", str(project.path / CONFIG_NAME),
-                    f"no declared transition moves '{status}' to '{suspect}', so an "
-                    f"item in '{status}' can never be marked suspect — invalidating "
-                    "anything it grounds in will leave it unflagged")
+        add("suspect-unreachable", "", str(project.path / CONFIG_NAME),
+            f"no declared transition moves '{status}' to '{suspect}', so an "
+            f"item in '{status}' can never be marked suspect — invalidating "
+            "anything it grounds in will leave it unflagged; `tl migrate` adds "
+            f"the route, or `tl schema transition allow {status} {suspect}` "
+            "adds this one")
 
     # A run that discovered nothing is not a sound graph (SR-0146). Items live only
     # beneath a register manifest, so a project whose manifests are missing, misnamed

{throughline-2.0.0 → throughline-2.2.0/src/throughline.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: throughline
-Version: 2.0.0
+Version: 2.2.0
 Summary: A Git-native requirements management tool with a scope-avalanche grounding layer: permanent UIDs, one file per item, typed links, suspect detection, and a CI-gating check.
 Author-email: Henry J Grech-Cini <henry.grechcini@gmail.com>
 License-Expression: Apache-2.0
@@ -36,7 +36,7 @@ version control; a `check` command validates the whole graph and gates CI.
 
 **Dogfooded:** throughline's own spec is itself a throughline project —
 <!-- tl:count type == 'system_requirement' -->
-153
+156
 <!-- tl:end --> system requirements,
 <!-- tl:count type == 'user_requirement' -->
 25

{throughline-2.0.0 → throughline-2.2.0}/tests/test_engine.py

@@ -42,7 +42,7 @@ from throughline.storage import (
     migrate_project,
     read_project,
 )
-from throughline.tomledit import TomlDocument
+from throughline.tomledit import TomlDocument, render_value
 from throughline.uid import UidError
 
 REPO = Path(__file__).resolve().parent.parent
@@ -3539,6 +3539,207 @@ def test_migrate_names_the_vocabularies_it_declared_on_the_cli(tmp_path, capsys)
     assert "nothing to migrate" not in out
 
 
+# --------------------- migration restores a route to suspicion (SR-0188) --- #
+
+def _pre_sr0175_lifecycle(root: Path) -> None:
+    """Put the transitions table back into the shape every project scaffolded before
+    SR-0175 carries: the statuses `tl new` births and parks items in have no move to
+    'suspect', so suspicion propagation is inert for exactly them."""
+    cfg = root / "throughline.toml"
+    doc = TomlDocument(cfg.read_text(encoding="utf-8"))
+    for status in ("proposed", "draft", "deferred"):
+        targets = tomllib.loads(cfg.read_text(encoding="utf-8"))["transitions"][status]
+        doc.set_key("transitions", status, [t for t in targets if t != "suspect"])
+        cfg.write_text(doc.text(), encoding="utf-8")
+
+
+def test_migrate_restores_a_route_to_suspicion_a_lifecycle_never_had(tmp_path):
+    """SR-0188. SR-0175 corrected only the table the Tool *ships*, so a project
+    scaffolded before it keeps an inert suspect role for the statuses items are born
+    and parked in. The gate reports that and, until this, offered no remedy but
+    editing each status by hand — so the same single command has to close it."""
+    root = tmp_path / "proj"
+    assert _cli(["-C", str(root), "init", "--bare"]) == 0
+    _pre_sr0175_lifecycle(root)
+    stranded = {"proposed", "draft", "deferred"}
+    assert set(load_project(root).suspect_unreachable_statuses()) == stranded
+
+    result = migrate_project(root)
+
+    assert set(result.routed) == stranded
+    assert set(result.routed.values()) == {"suspect"}
+    schema = load_project(root).schema
+    assert all(schema.allows_transition(s, "suspect") for s in stranded)
+    assert not [f for f in validate(load_project(root))
+                if f.rule == "suspect-unreachable"]
+
+
+def test_migrate_suspect_route_repair_is_idempotent(tmp_path):
+    """SR-0188 with SR-0137. The repair runs on every `tl migrate`, sound project or
+    not, so a lifecycle that already permits the move must be left byte-identical —
+    otherwise every run would re-comment and re-widen the same rows."""
+    root = tmp_path / "proj"
+    assert _cli(["-C", str(root), "init", "--bare"]) == 0
+    _pre_sr0175_lifecycle(root)
+    assert migrate_project(root).routed
+    cfg = root / "throughline.toml"
+    before = cfg.read_text(encoding="utf-8")
+
+    assert migrate_project(root).routed == {}
+
+    assert cfg.read_text(encoding="utf-8") == before
+
+
+def test_migrate_leaves_a_lifecycle_that_already_reaches_suspicion_alone(tmp_path):
+    """SR-0188. The table `tl init` ships has been correct since SR-0175, so the
+    repair must write nothing at all to a project scaffolded by it — a repair that
+    churned every current project's configuration would be its own defect."""
+    root = tmp_path / "proj"
+    assert _cli(["-C", str(root), "init", "--bare"]) == 0
+    cfg = root / "throughline.toml"
+    before = cfg.read_text(encoding="utf-8")
+
+    assert migrate_project(root).routed == {}
+
+    assert cfg.read_text(encoding="utf-8") == before
+
+
+def test_migrate_repairs_exactly_the_statuses_the_gate_reports(tmp_path):
+    """SR-0188. Both halves ask Project.suspect_unreachable_statuses, so what the
+    repair widens and what the gate complains about cannot drift apart: a second
+    reading of "live" here would churn a project's configuration over statuses the
+    gate ignores, or leave the ones it reports."""
+    root = tmp_path / "proj"
+    assert _cli(["-C", str(root), "init", "--bare"]) == 0
+    _pre_sr0175_lifecycle(root)
+    project = load_project(root)
+    reported = {f.message.split("'")[1]
+                for f in validate(project) if f.rule == "suspect-unreachable"}
+
+    assert reported == set(project.suspect_unreachable_statuses())
+    assert set(migrate_project(root).routed) == reported
+
+
+def test_migrate_adds_the_route_without_disturbing_the_moves_already_declared(tmp_path):
+    """SR-0188 through SR-0183/NFR-0009. The route is *added* to the row rather than
+    the row rewritten, so an author's own ordering, layout and comments survive being
+    brought up to what the major requires."""
+    root = tmp_path / "proj"
+    assert _cli(["-C", str(root), "init", "--bare"]) == 0
+    _pre_sr0175_lifecycle(root)
+    cfg = root / "throughline.toml"
+    cfg.write_text("# Why this project is shaped as it is.\n"
+                   + cfg.read_text(encoding="utf-8"), encoding="utf-8")
+    before = tomllib.loads(cfg.read_text(encoding="utf-8"))["transitions"]
+
+    migrate_project(root)
+    out = cfg.read_text(encoding="utf-8")
+
+    assert out.startswith("# Why this project is shaped as it is.\n")
+    after = tomllib.loads(out)["transitions"]
+    for status, targets in before.items():
+        extra = {"suspect"} if status in ("proposed", "draft", "deferred") else set()
+        assert after[status] == targets + sorted(extra)  # appended, nothing reordered
+    assert "SR-0188" in out, "the config records that migration made the change"
+
+
+def test_migrate_gives_a_status_with_no_row_at_all_a_route_to_suspicion(tmp_path):
+    """SR-0188. A status an item sits in but the table never mentions has no outgoing
+    move of any kind, which is the same disabled mechanism by another route — so it
+    gets a row rather than being passed over for lack of one to widen."""
+    root = tmp_path / "proj"
+    assert _cli(["-C", str(root), "init", "--bare"]) == 0
+    cfg = root / "throughline.toml"
+    doc = TomlDocument(cfg.read_text(encoding="utf-8"))
+    doc.remove_key("transitions", "deferred")
+    cfg.write_text(doc.text(), encoding="utf-8")
+
+    assert migrate_project(root).routed == {"deferred": "suspect"}
+
+    assert tomllib.loads(cfg.read_text(encoding="utf-8")
+                         )["transitions"]["deferred"] == ["suspect"]
+
+
+def test_migrate_writes_no_route_where_there_is_no_mechanism_to_disable(tmp_path):
+    """SR-0188. A project that declares no transitions is unconstrained, and one that
+    binds no suspect role has no suspicion to propagate. The repair reads a declared
+    lifecycle; it does not invent one, any more than the gate does."""
+    root = tmp_path / "proj"
+    assert _cli(["-C", str(root), "init", "--bare"]) == 0
+    cfg = root / "throughline.toml"
+    doc = TomlDocument(cfg.read_text(encoding="utf-8"))
+    doc.remove_table("transitions")
+    cfg.write_text(doc.text(), encoding="utf-8")
+    before = cfg.read_text(encoding="utf-8")
+
+    assert migrate_project(root).routed == {}
+
+    assert cfg.read_text(encoding="utf-8") == before
+
+
+def test_migrate_names_the_routes_it_restored_on_the_cli(tmp_path, capsys):
+    """SR-0188 with SR-0137. This is the one part of the repair that *widens* what
+    the lifecycle permits, so an operator who did not want a status able to move must
+    be able to see which rows changed rather than infer it from a count."""
+    root = tmp_path / "proj"
+    assert _cli(["-C", str(root), "init", "--bare"]) == 0
+    _pre_sr0175_lifecycle(root)
+    capsys.readouterr()
+
+    assert _cli(["-C", str(root), "migrate"]) == 0
+    out = capsys.readouterr().out
+
+    assert "draft -> suspect" in out
+    assert "nothing to migrate" not in out
+
+
+def test_migrate_refuses_to_guess_at_a_transitions_table_it_cannot_edit(tmp_path):
+    """SR-0188. A corrupted throughline.toml invalidates the whole project, so a
+    repair that cannot be made safely must not be made at all — it is refused whole,
+    before anything is written, and named with the command that does it by hand."""
+    root = tmp_path / "proj"
+    assert _cli(["-C", str(root), "init", "--bare"]) == 0
+    cfg = root / "throughline.toml"
+    doc = TomlDocument(cfg.read_text(encoding="utf-8"))
+    table = tomllib.loads(cfg.read_text(encoding="utf-8"))["transitions"]
+    doc.remove_table("transitions")
+    # The same lifecycle, declared as one inline table rather than a [transitions]
+    # header — a shape the editor cannot widen and must not append a second table to.
+    # Written above every header, so it is the top-level key the schema reads.
+    text = ("transitions = " + render_value({k: [t for t in v if t != "suspect"]
+                                             for k, v in table.items()})
+            + "\n" + doc.text())
+    cfg.write_text(text, encoding="utf-8")
+    assert load_project(root).suspect_unreachable_statuses()
+
+    with pytest.raises(ProjectError, match="tl schema transition allow"):
+        migrate_project(root)
+
+    assert cfg.read_text(encoding="utf-8") == text, "refused whole, nothing written"
+
+
+def test_migrate_keeps_a_comment_an_author_left_beside_one_move(tmp_path):
+    """SR-0188 through SR-0183. Adding to the row is what makes the author's note on
+    an individual move survivable — re-rendering the whole value would have nowhere
+    to put it back, and the editor would rightly refuse rather than drop it, leaving
+    the gap open on a project that had done nothing wrong."""
+    root = tmp_path / "proj"
+    assert _cli(["-C", str(root), "init", "--bare"]) == 0
+    cfg = root / "throughline.toml"
+    doc = TomlDocument(cfg.read_text(encoding="utf-8"))
+    doc.remove_key("transitions", "deferred")
+    cfg.write_text(doc.text().replace(
+        "[transitions]",
+        '[transitions]\ndeferred = [\n    "draft",  # back onto the active front\n]'),
+        encoding="utf-8")
+
+    assert migrate_project(root).routed == {"deferred": "suspect"}
+    out = cfg.read_text(encoding="utf-8")
+
+    assert "# back onto the active front" in out
+    assert tomllib.loads(out)["transitions"]["deferred"] == ["draft", "suspect"]
+
+
 def test_migrate_refuses_newer_project(tmp_path):
     """`tl migrate` refuses a project newer than this tl — there is nothing to
     migrate down to; the user must upgrade tl (NFR-0010)."""
@@ -4220,3 +4421,197 @@ def test_editability_is_read_from_recorded_metadata_not_guessed(monkeypatch):
     # Absent or unparseable metadata is not evidence of a working tree.
     assert not version_mod._editable_from_direct_url(_Dist(None))
     assert not version_mod._editable_from_direct_url(_Dist("{not json"))
+
+
+# ------------------------------------------------------------------- SR-0189/0190
+# `tl subgraph` — the induced neighbourhood around one UID, and `tl context <UID>`.
+
+def _neighbourhood_fixture(tmp_path) -> Path:
+    """FR-0001 with one thing above it, two below, and a link that crosses between
+    the two halves.
+
+        INT-0001 <-derives_from- FR-0001 <-derives_from- FR-0002 <-derives_from- FR-0003
+             ^------------------------relates-----------------'
+
+    The `relates` edge joins a *downstream* node to an *upstream* one, so it is the
+    edge no single-direction walk can report.
+    """
+    root = _scaffold(tmp_path)  # INT-0001 + FR register
+    for title, ground in [("a", "INT-0001"), ("b", "FR-0001"), ("c", "FR-0002")]:
+        assert _cli(["-C", str(root), "new", "FR", "--type", "requirement",
+                     "--title", title, "--ground", ground]) == 0
+    assert _cli(["-C", str(root), "link", "FR-0002", "INT-0001",
+                 "--type", "relates"]) == 0
+    return root
+
+
+def test_subgraph_reports_the_link_neither_trace_nor_blast_can_show(tmp_path, capsys):
+    """The whole justification for a third view (SR-0189). `trace` walks outward and
+    `blast` collects inward, so a link *between* two members of the neighbourhood —
+    here FR-0002 (below) pointing at INT-0001 (above) — appears in neither. The
+    induced subgraph is the only view that closes that gap."""
+    root = _neighbourhood_fixture(tmp_path)
+    crossing = "FR-0002  -relates->  INT-0001"
+
+    capsys.readouterr()
+    assert _cli(["-C", str(root), "trace", "FR-0001"]) == 0
+    assert "FR-0002" not in capsys.readouterr().out
+    assert _cli(["-C", str(root), "blast", "FR-0001"]) == 0
+    blast = capsys.readouterr().out
+    assert "FR-0002" in blast and "relates" not in blast
+
+    assert _cli(["-C", str(root), "subgraph", "FR-0001"]) == 0
+    out = capsys.readouterr().out
+    assert crossing in out
+    # Both directions are reported, from the one start item.
+    assert "rests on (1):" in out and "INT-0001" in out
+    assert "depended on by (2):" in out and "FR-0003" in out
+
+
+def test_subgraph_bounds_the_walk_by_depth_but_not_the_links(tmp_path, capsys):
+    """`--depth` limits how far the node set reaches, so FR-0003 (two hops below)
+    drops out. Edges stay *induced*: every link joining two surviving nodes is still
+    reported, because hiding one would misrepresent the set that is shown."""
+    root = _neighbourhood_fixture(tmp_path)
+    capsys.readouterr()
+    assert _cli(["-C", str(root), "subgraph", "FR-0001", "--depth", "1"]) == 0
+    out = capsys.readouterr().out
+    assert "FR-0003" not in out
+    assert "depended on by (1):" in out and "FR-0002" in out
+    assert "FR-0002  -relates->  INT-0001" in out
+
+
+def test_subgraph_restricts_the_walk_to_chosen_link_types(tmp_path, capsys):
+    """`--link-type` scopes both the closures and the edges, so asking only for
+    derives_from drops the relates edge while the derivation chain survives."""
+    root = _neighbourhood_fixture(tmp_path)
+    capsys.readouterr()
+    assert _cli(["-C", str(root), "subgraph", "FR-0001",
+                 "--link-type", "derives_from"]) == 0
+    out = capsys.readouterr().out
+    assert "relates" not in out
+    assert "FR-0003  -derives_from->  FR-0002" in out
+
+
+def test_subgraph_renders_an_unresolved_target_as_a_leaf(tmp_path, capsys):
+    """A namespace-qualified or dangling target has no local item to describe. It
+    stays in the node set as an `(unresolved)` leaf — the walk stops there rather
+    than aborting, matching how `tl trace` already behaves (SR-0051)."""
+    root = _scaffold(tmp_path)
+    assert _cli(["-C", str(root), "new", "FR", "--type", "requirement",
+                 "--title", "cites an external clause", "--ground", "INT-0001"]) == 0
+    item = root / "features" / "FR-0001.yml"
+    item.write_text(item.read_text(encoding="utf-8")
+                    + "- target: \"asvs:SR-0003\"\n  type: relates\n",
+                    encoding="utf-8")
+    capsys.readouterr()
+    assert _cli(["-C", str(root), "subgraph", "FR-0001"]) == 0
+    out = capsys.readouterr().out
+    assert "asvs:SR-0003  (unresolved)" in out
+    assert "FR-0001  -relates->  asvs:SR-0003" in out
+
+
+def test_subgraph_json_names_every_node_and_edge(tmp_path, capsys):
+    """The machine-readable form an agent consumes: both closures, a node record
+    carrying resolvability, and the edges as source/type/target triples."""
+    import json
+    root = _neighbourhood_fixture(tmp_path)
+    capsys.readouterr()
+    assert _cli(["-C", str(root), "subgraph", "FR-0001", "--format", "json"]) == 0
+    doc = json.loads(capsys.readouterr().out)
+    assert doc["start"] == "FR-0001"
+    assert doc["upstream"] == ["INT-0001"]
+    assert doc["downstream"] == ["FR-0002", "FR-0003"]
+    assert {n["uid"] for n in doc["nodes"]} == {
+        "FR-0001", "FR-0002", "FR-0003", "INT-0001"}
+    assert all(n["resolved"] for n in doc["nodes"])
+    assert {"source": "FR-0002", "type": "relates", "target": "INT-0001"} in doc["edges"]
+
+
+def test_subgraph_rejects_a_uid_that_does_not_exist(tmp_path, capsys):
+    """Naming an absent item is a usage error (exit 2), not an empty neighbourhood
+    that reads as "nothing depends on this"."""
+    root = _scaffold(tmp_path)
+    assert _cli(["-C", str(root), "subgraph", "NOPE-0001"]) == 2
+    assert "NOPE-0001 does not exist" in capsys.readouterr().err
+
+
+def test_render_subgraph_applies_the_uid_display_seam(tmp_path, capsys):
+    """The same seam `render_trace` exposes, so tl-compose can show a borrowed
+    clause under its namespace rather than its mangled union UID (SR-0189)."""
+    from throughline.cli import render_subgraph
+    from throughline.graph import Index
+    from throughline.storage import load_project
+    root = _neighbourhood_fixture(tmp_path)
+    project = load_project(str(root))
+    view = Index.build(project).subgraph("FR-0001")
+    capsys.readouterr()
+    render_subgraph(project, view, uid_display=lambda u: f"ns:{u}")
+    out = capsys.readouterr().out
+    assert "ns:FR-0001" in out and "ns:INT-0001" in out
+    assert "ns:FR-0002  -relates->  ns:INT-0001" in out
+
+
+def test_context_without_a_uid_is_unaffected(tmp_path, capsys):
+    """`tl context` with no argument keeps doing exactly what it did: the project
+    brief, and nothing item-specific bolted on (SR-0190)."""
+    root = _neighbourhood_fixture(tmp_path)
+    capsys.readouterr()
+    assert _cli(["-C", str(root), "context"]) == 0
+    out = capsys.readouterr().out
+    assert "## The item you were given" not in out
+    assert "rests on" not in out
+
+
+def test_context_with_a_uid_appends_the_neighbourhood(tmp_path, capsys):
+    """`tl context <UID>` is the brief *plus* that item's neighbourhood, so an agent
+    handed one UID gets the project rules and the item's surroundings in a single
+    call. The added section reuses the subgraph renderer, so the two cannot drift
+    (SR-0190)."""
+    root = _neighbourhood_fixture(tmp_path)
+    capsys.readouterr()
+    assert _cli(["-C", str(root), "context"]) == 0
+    bare = capsys.readouterr().out
+    assert _cli(["-C", str(root), "context", "FR-0001"]) == 0
+    out = capsys.readouterr().out
+    assert out.startswith(bare)                      # the brief is untouched
+    assert "## The item you were given: FR-0001" in out
+    assert "FR-0002  -relates->  INT-0001" in out
+
+
+def test_context_rejects_a_uid_that_does_not_exist(tmp_path, capsys):
+    """Same contract as `subgraph`: an unknown UID fails loudly rather than
+    printing the brief and silently omitting the section that was asked for."""
+    root = _scaffold(tmp_path)
+    assert _cli(["-C", str(root), "context", "NOPE-0001"]) == 2
+    assert "NOPE-0001 does not exist" in capsys.readouterr().err
+
+
+def test_subgraph_expand_bounds_the_walk_without_hiding_edges(tmp_path):
+    """The boundary seam tl-compose builds on. A node `expand` rejects is still
+    reported and its links to other members are still drawn — it is simply not
+    walked *through*, so one link into a borrowed standard cannot drag the whole
+    standard in. The named start item is always walked, whatever `expand` says,
+    because a caller who named it is standing on it deliberately."""
+    from throughline.graph import Index
+    from throughline.storage import load_project
+    root = _neighbourhood_fixture(tmp_path)  # INT-0001 <- FR-0001 <- FR-0002 <- FR-0003
+    index = Index.build(load_project(str(root)))
+
+    # Treat everything below FR-0001 as "foreign": FR-0002 is reported but not
+    # traversed, so FR-0003 behind it never enters the set.
+    view = index.subgraph("FR-0001", expand=lambda u: u in {"FR-0001", "INT-0001"})
+    assert view.downstream == ("FR-0002",)
+    assert "FR-0003" not in view.nodes
+    # FR-0002's own links to members of the set survive the boundary.
+    assert ("FR-0002", "relates", "INT-0001") in view.edges
+    assert ("FR-0002", "derives_from", "FR-0001") in view.edges
+    assert all("FR-0003" not in edge for edge in view.edges)
+
+    # The start is exempt: naming a node `expand` rejects still walks it, one step.
+    named = index.subgraph("FR-0002", expand=lambda u: False)
+    assert set(named.upstream) == {"FR-0001", "INT-0001"}   # both are one hop out
+    assert named.downstream == ("FR-0003",)
+    # ...and no further: FR-0001's own parent is already INT-0001, so the proof the
+    # walk stopped is that nothing two hops past the start appears via FR-0003.
+    assert set(named.nodes) == {"FR-0002", "FR-0001", "INT-0001", "FR-0003"}