pgc-inspector 2.0.0__py3-none-any.whl

inspector/__init__.py

@@ -0,0 +1,17 @@
+"""snapshot_inspector — read-only inspection over assembled PGC snapshots.
+
+A first-class toolchain component, symmetric with the compiler / assembler / runtime — each
+owns one phase of the snapshot lifecycle:
+
+    protocol_compiler    source      → compiled projections
+    snapshot_assembler   projections → assembled snapshot
+    protocol_runtime     snapshot    → execution
+    snapshot_inspector   snapshot    → inspection      (this repo)
+
+CONSUMER-NEUTRAL: the transport SNAPSHOT_READ/SNAPSHOT_QUERY handlers are one consumer; a `si`
+CLI, CI gates (validate/violations), and change-management dossiers are others. The API makes
+no web/transport assumptions.
+
+Inspection never mutates and never executes. Phase 2a projects PUBLISHED snapshot material;
+Phase 2b derives governed queries (refs/deps/impact/validation) over it.
+"""

inspector/__main__.py

@@ -0,0 +1,7 @@
+"""`python -m inspector` → the `si` CLI, so the tool runs without being installed."""
+import sys
+
+from inspector.cli import main
+
+if __name__ == "__main__":
+    sys.exit(main())

inspector/api.py

@@ -0,0 +1,94 @@
+"""inspector.api — the single programmatic entry point for snapshot inspection.
+
+    query(operation, params, snapshot_root)  -> (status, payload)
+    operations(snapshot_root)                -> the published catalog
+    operation_kind(operation, snapshot_root) -> the handler kind a boundary routes it by
+
+`status` ∈ {"SUCCESS", "NOT_FOUND"}; raises on internal error. This mirrors
+`runtime.api.run_workflow`'s `(status, surface)` so any boundary (e.g. the transport
+SNAPSHOT_READ handler) can treat execution and inspection uniformly.
+
+**The snapshot declares the operation set.** Every operation, its accepted parameters, its handler
+kind and the implementation that answers it are read from the snapshot's compiled `inspection::` TI
+artifacts (`inspector.catalog`); `inspector.registry` supplies implementations and declares no
+metadata. So an inspector pointed at a snapshot answers exactly what that snapshot declares — two
+snapshots may legitimately offer different operations, and neither is what the code privately
+believes.
+
+A missing REQUIRED parameter is NOT_FOUND, not a raise: the caller asked a well-formed question the
+snapshot cannot answer as posed. An operation the snapshot does not declare raises, because no
+amount of parameters would make it answerable here — that is a caller defect, not a result.
+"""
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+from inspector.catalog import load_catalog
+from inspector.kinds import CATEGORIES
+from inspector.snapshot import Snapshot
+
+
+def _resolve(operation: str, snapshot: Snapshot):
+    catalog = load_catalog(snapshot)
+    op = catalog.get(operation)
+    if op is None:
+        raise KeyError(
+            f"snapshot at {snapshot.root} declares no inspection operation {operation!r}"
+        )
+    return op
+
+
+def query(
+    operation: str,
+    params: dict[str, Any],
+    snapshot_root: str | Path,
+) -> tuple[str, dict[str, Any]]:
+    """Answer an inspection Operation Identity over the assembled snapshot at `snapshot_root`."""
+    snapshot = Snapshot(Path(snapshot_root))
+    op = _resolve(operation, snapshot)
+
+    params = params or {}
+    missing = [p for p in op.required if params.get(p) in (None, "")]
+    if missing:
+        return "NOT_FOUND", {
+            "operation": operation,
+            "reason": f"missing required parameter(s): {', '.join(missing)}",
+            "params": list(op.params),
+        }
+
+    return op.handler(snapshot, params)
+
+
+def operation_kind(operation: str, snapshot_root: str | Path) -> str:
+    """The handler kind (`SNAPSHOT_READ` / `SNAPSHOT_QUERY`) a boundary routes this operation by."""
+    return _resolve(operation, Snapshot(Path(snapshot_root))).kind
+
+
+def operations(snapshot_root: str | Path) -> list[dict[str, Any]]:
+    """The inspection catalog — every operation the snapshot declares, in category then identity order.
+
+    Published so a client's menu is what the SNAPSHOT offers. There is no second list: the CLI's
+    commands and the surface's launcher are both built from this, and this is built from the
+    compiled contracts.
+    """
+    snapshot = Snapshot(Path(snapshot_root))
+    return [
+        {
+            "operation": op.identity,
+            "kind": op.kind,
+            "category": op.category,
+            "label": op.label,
+            "params": list(op.params),
+            "required": list(op.required),
+            "flags": list(op.flags),
+            "summary": op.summary,
+            "implementation": op.implementation,
+        }
+        for op in load_catalog(snapshot).values()
+    ]
+
+
+def categories() -> tuple[str, ...]:
+    """The catalog groupings, in presentation order."""
+    return CATEGORIES

inspector/catalog.py

@@ -0,0 +1,135 @@
+"""The operation catalog, read from the snapshot's own `inspection::` TI artifacts.
+
+**The protocol declares which operations exist; the code only obeys.** An operation's identity,
+handler kind, accepted parameters and their types, which are required, how it is presented, and
+which implementation answers it are all declared by a compiled TI artifact. Nothing in Python
+enumerates the operation set — `inspector.registry` holds implementations and no metadata at all.
+
+Adding, removing, renaming or re-pointing an operation is therefore an authoring act on an
+artifact that is compiled, sealed into the snapshot and attested. It is visible in a snapshot
+diff, and it cannot happen silently in code.
+
+    TI frontmatter                          Operation field
+    ─────────────────────────────────────   ───────────────
+    operation                               identity
+    handler.kind                            kind
+    handler.implementation {module,callable} implementation → registry lookup
+    input_contract {name: {type, required}} params / required / flags
+    catalog {category, label, summary}      presentation
+
+`flags` is derived, not declared twice: a parameter is a flag exactly when its declared type is
+boolean. A client renders those as switches.
+
+Read once per `Snapshot` instance. If the snapshot carries no inspection contracts this raises —
+an inspector pointed at a snapshot that declares no operations has nothing to offer, and saying so
+is more useful than answering from a private list the snapshot does not know about.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any
+
+from inspector.kinds import CATEGORIES, INSPECTION_KINDS as _INSPECTION_KINDS
+from inspector.registry import Projection, resolve_implementation
+from inspector.snapshot import Snapshot, SnapshotError
+
+
+@dataclass(frozen=True)
+class Operation:
+    identity: str
+    kind: str                   # SNAPSHOT_READ | SNAPSHOT_QUERY
+    category: str               # catalog grouping
+    label: str                  # short human name for a menu entry
+    params: tuple[str, ...]     # accepted parameter names
+    required: tuple[str, ...]   # those without which the operation cannot answer
+    flags: tuple[str, ...]      # of `params`, the ones declared boolean
+    summary: str
+    implementation: str         # "<module>:<callable>", as the artifact declares it
+    handler: Projection         # what that reference resolves to
+
+
+def _operation_from_ti(frontmatter: dict[str, Any], source: str) -> Operation:
+    identity = frontmatter.get("operation")
+    handler = frontmatter.get("handler") or {}
+    kind = handler.get("kind")
+    if not identity:
+        raise SnapshotError(f"inspection TI declares no operation identity: {source}")
+    if kind not in _INSPECTION_KINDS:
+        raise SnapshotError(
+            f"inspection TI {identity!r} declares handler kind {kind!r}; expected one of "
+            f"{list(_INSPECTION_KINDS)} ({source})"
+        )
+
+    declared_impl = handler.get("implementation") or {}
+    module = declared_impl.get("module")
+    callable_name = declared_impl.get("callable")
+    if not module or not callable_name:
+        raise SnapshotError(
+            f"inspection TI {identity!r} declares no handler.implementation {{module, callable}} "
+            f"({source}) — an operation whose implementation is not declared is bound by code, "
+            "not by protocol"
+        )
+
+    contract = frontmatter.get("input_contract") or {}
+    params = tuple(contract)
+    required = tuple(p for p in params if (contract[p] or {}).get("required") is True)
+    flags = tuple(p for p in params if (contract[p] or {}).get("type") == "boolean")
+
+    presentation = frontmatter.get("catalog") or {}
+    category = presentation.get("category") or "SNAPSHOT"
+    if category not in CATEGORIES:
+        raise SnapshotError(
+            f"inspection TI {identity!r} declares category {category!r}, which is not a known "
+            f"catalog category {list(CATEGORIES)} ({source})"
+        )
+
+    return Operation(
+        identity=identity,
+        kind=kind,
+        category=category,
+        label=presentation.get("label") or identity,
+        params=params,
+        required=required,
+        flags=flags,
+        summary=presentation.get("summary") or "",
+        implementation=f"{module}:{callable_name}",
+        handler=resolve_implementation(module, callable_name),
+    )
+
+
+def load_catalog(snapshot: Snapshot) -> dict[str, Operation]:
+    """Every inspection operation the snapshot declares, keyed by Operation Identity."""
+    cached = snapshot.cached("__catalog__")
+    if cached is not None:
+        return cached
+
+    operations: dict[str, Operation] = {}
+    for fqdn, entry in snapshot.entries().items():
+        if entry.get("kind") != "TI":
+            continue
+        canonical = snapshot.canonical(fqdn) or {}
+        frontmatter = canonical.get("frontmatter") or {}
+        handler = frontmatter.get("handler") or {}
+        if handler.get("kind") not in _INSPECTION_KINDS:
+            continue  # an execution TI belongs to a workload, not to this catalog
+        operation = _operation_from_ti(frontmatter, fqdn)
+        if operation.identity in operations:
+            raise SnapshotError(
+                f"two inspection TIs declare operation {operation.identity!r} — an Operation "
+                "Identity must resolve to exactly one contract"
+            )
+        operations[operation.identity] = operation
+
+    if not operations:
+        raise SnapshotError(
+            f"snapshot at {snapshot.root} declares no inspection operations "
+            "(no TI artifact with a SNAPSHOT_READ/SNAPSHOT_QUERY handler kind) — "
+            "compile and assemble the inspection domain before inspecting"
+        )
+
+    ordered = dict(sorted(
+        operations.items(),
+        key=lambda kv: (CATEGORIES.index(kv[1].category), kv[0]),
+    ))
+    snapshot.cache("__catalog__", ordered)
+    return ordered

inspector/cli.py

@@ -0,0 +1,265 @@
+"""`si` — the command-line client of `inspector.api`.
+
+**Generated from the SNAPSHOT, not hand-written.** Every command, its arguments and its help text
+come from the inspection contracts the snapshot declares; there is no per-operation code here.
+That is deliberate twice over: a CLI with hand-written commands accretes capability the API does
+not have and becomes a second inspection engine, and a CLI built from a private list would offer
+commands the snapshot in front of it never declared. Authoring a TI artifact is the only way to
+add a command, and it is then automatically present.
+
+    si <group> <verb> [args]        one command per Operation Identity: si.artifact.show → si artifact show
+    si operations                   the catalog itself
+    si --snapshot PATH …            which snapshot to read
+
+Snapshot resolution, in order: `--snapshot`, `$PGC_SNAPSHOT_ROOT`, `./snapshot`. The only
+requirement is that the directory carry a `manifest.json` — an ASSEMBLED snapshot is the input
+contract, and nothing else is gated on.
+
+Exit codes: 0 on SUCCESS, 1 on NOT_FOUND, 2 on usage or snapshot error. `si snapshot validate
+--strict` additionally exits 1 when the snapshot is invalid, so it works as a CI gate.
+
+Stdlib only (argparse) — this repo installs nothing.
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import sys
+from pathlib import Path
+from typing import Any
+
+from inspector.api import query
+from inspector.catalog import Operation, load_catalog
+from inspector.kinds import CATEGORIES
+from inspector.snapshot import Snapshot, SnapshotError
+
+_DEFAULT_SNAPSHOT = "snapshot"
+
+
+def _snapshot_root(argv: list[str]) -> Path:
+    """Resolve the snapshot BEFORE the parser exists.
+
+    The commands are generated from the snapshot's declared operations, so the snapshot has to be
+    located first — `--snapshot` is read by a deliberately minimal pre-pass rather than by the
+    parser it is needed to build. This is the one place the ordering is inverted, and it is
+    inverted because the protocol, not the code, decides what commands exist.
+    """
+    pre = argparse.ArgumentParser(add_help=False)
+    pre.add_argument("--snapshot", default=None)
+    known, _ = pre.parse_known_args(argv)
+    return Path(known.snapshot or os.environ.get("PGC_SNAPSHOT_ROOT") or _DEFAULT_SNAPSHOT)
+
+
+def _group_and_verb(identity: str) -> tuple[str, str]:
+    """`si.artifact.show` → ('artifact', 'show'); `si.behavior_logic.show` → ('behavior_logic', 'show')."""
+    parts = identity.split(".")
+    return parts[1], ".".join(parts[2:])
+
+
+def _dest(param: str) -> str:
+    return f"param_{param}"
+
+
+def _build_parser(operations: dict[str, Operation]
+                  ) -> tuple[argparse.ArgumentParser, dict[tuple[str, str], Operation]]:
+    parser = argparse.ArgumentParser(
+        prog="si",
+        description="Read-only inspection of an assembled PGC snapshot.",
+    )
+    parser.add_argument("--snapshot", default=None, metavar="PATH",
+                        help="snapshot root (default: $PGC_SNAPSHOT_ROOT, else ./snapshot)")
+    parser.add_argument("--json", action="store_true", help="emit the raw payload as JSON")
+    groups = parser.add_subparsers(dest="group", metavar="<group>")
+
+    # The same two options after the verb, where a reader naturally reaches for them
+    # (`si artifact list --json`). SUPPRESS so an unused subcommand copy never overwrites the
+    # value already parsed at the top level.
+    common = argparse.ArgumentParser(add_help=False)
+    common.add_argument("--snapshot", metavar="PATH", default=argparse.SUPPRESS)
+    common.add_argument("--json", action="store_true", default=argparse.SUPPRESS)
+
+    by_group: dict[str, list[Operation]] = {}
+    for op in operations.values():
+        by_group.setdefault(_group_and_verb(op.identity)[0], []).append(op)
+
+    def bind(parser: argparse.ArgumentParser, op: Operation) -> None:
+        """Give a parser this operation's declared parameters and bind it to the identity."""
+        for param in op.params:
+            if param in op.flags:
+                parser.add_argument(f"--{param}", dest=_dest(param), action="store_true")
+            elif param in op.required:
+                parser.add_argument(_dest(param), nargs="?", default=None, metavar=param.upper())
+            else:
+                parser.add_argument(f"--{param}", dest=_dest(param), default=None)
+        parser.set_defaults(_operation=op.identity)
+
+    routes: dict[tuple[str, str], Operation] = {}
+    order = {c: i for i, c in enumerate(CATEGORIES)}
+    for group_name in sorted(by_group, key=lambda g: (order.get(by_group[g][0].category, 99), g)):
+        ops = sorted(by_group[group_name], key=lambda o: o.identity)
+
+        # A two-segment identity (`si.catalog`) is a command in its own right; a three-segment one
+        # (`si.artifact.show`) is a verb under a group. The shape of the identity decides, so an
+        # operation named either way gets the command a reader would expect.
+        flat = [op for op in ops if not _group_and_verb(op.identity)[1]]
+        if flat:
+            if len(ops) > 1:
+                raise ValueError(
+                    f"identity group {group_name!r} mixes a bare command with verbs: "
+                    f"{[o.identity for o in ops]}"
+                )
+            op = flat[0]
+            command = groups.add_parser(group_name, help=op.summary, parents=[common],
+                                        description=(f"{op.summary}\n\n"
+                                                     f"Operation Identity: {op.identity}  ({op.kind})"),
+                                        formatter_class=argparse.RawDescriptionHelpFormatter)
+            bind(command, op)
+            routes[(group_name, "")] = op
+            continue
+
+        group_parser = groups.add_parser(group_name, help=f"{ops[0].category.lower()} operations")
+        verbs = group_parser.add_subparsers(dest="verb", metavar="<verb>")
+        for op in ops:
+            _, verb = _group_and_verb(op.identity)
+            verb_parser = verbs.add_parser(verb, help=op.summary, parents=[common], description=(
+                f"{op.summary}\n\nOperation Identity: {op.identity}  ({op.kind})"
+            ), formatter_class=argparse.RawDescriptionHelpFormatter)
+            bind(verb_parser, op)
+            routes[(group_name, verb)] = op
+
+    operations_parser = groups.add_parser(
+        "operations", help="list every inspection operation this snapshot inspector answers")
+    operations_parser.set_defaults(_operation="__catalog__")
+
+    return parser, routes
+
+
+# ── rendering ────────────────────────────────────────────────────
+#
+# One generic renderer, for the same reason there is one generic command builder: a per-operation
+# formatter is per-operation code, and per-operation code drifts from the payload it formats.
+
+def _render(value: Any, indent: int = 0) -> list[str]:
+    pad = "  " * indent
+    lines: list[str] = []
+    if isinstance(value, dict):
+        scalars = {k: v for k, v in value.items() if not isinstance(v, (dict, list))}
+        nested = {k: v for k, v in value.items() if isinstance(v, (dict, list))}
+        width = max((len(k) for k in scalars), default=0)
+        for key, scalar in scalars.items():
+            lines.append(f"{pad}{key.ljust(width)}  {scalar}")
+        for key, child in nested.items():
+            if not child:
+                lines.append(f"{pad}{key}: —")
+                continue
+            lines.append(f"{pad}{key}:")
+            lines.extend(_render(child, indent + 1))
+    elif isinstance(value, list):
+        if all(isinstance(item, dict) for item in value) and value:
+            lines.extend(_render_table(value, pad))
+        else:
+            lines.extend(f"{pad}- {item}" for item in value)
+    else:
+        lines.append(f"{pad}{value}")
+    return lines
+
+
+def _render_table(rows: list[dict[str, Any]], pad: str) -> list[str]:
+    """List-of-dicts as a table when the rows are flat and share a shape; itemised otherwise."""
+    columns = list(dict.fromkeys(k for row in rows for k in row))
+    flat = all(not isinstance(row.get(c), (dict, list)) for row in rows for c in columns)
+    if not flat or len(columns) > 8:
+        lines = []
+        for position, row in enumerate(rows):
+            lines.append(f"{pad}—" if position else f"{pad}—")
+            lines.extend(_render(row, len(pad) // 2 + 1))
+        return lines
+    widths = {
+        c: max(len(c), max((len(str(row.get(c, ""))) for row in rows), default=0))
+        for c in columns
+    }
+    header = "  ".join(c.ljust(widths[c]) for c in columns)
+    lines = [f"{pad}{header}", f"{pad}{'  '.join('-' * widths[c] for c in columns)}"]
+    lines.extend(
+        f"{pad}{'  '.join(str(row.get(c, '')).ljust(widths[c]) for c in columns)}"
+        for row in rows
+    )
+    return lines
+
+
+def _render_catalog(operations: dict[str, Operation]) -> list[str]:
+    lines = ["Protocol Inspection — read-only inspection of the PGC snapshot", ""]
+    by_category: dict[str, list[Operation]] = {}
+    for op in operations.values():
+        by_category.setdefault(op.category, []).append(op)
+    for category in CATEGORIES:
+        ops = by_category.get(category)
+        if not ops:
+            continue
+        lines.append(f"  {category}")
+        for op in ops:
+            group, verb = _group_and_verb(op.identity)
+            params = " ".join(
+                f"<{p}>" if p in op.required else f"[--{p}]" for p in op.params
+            )
+            lines.append(f"    si {group} {verb} {params}".rstrip())
+            lines.append(f"        {op.summary}  [{op.kind}]")
+        lines.append("")
+    return lines
+
+
+# ── entry point ──────────────────────────────────────────────────
+
+def main(argv: list[str] | None = None) -> int:
+    argv = argv if argv is not None else sys.argv[1:]
+
+    # The snapshot declares the commands, so it is located first and read before the parser is
+    # built. A snapshot that declares no inspection contracts yields a usage error, not a partial
+    # CLI answering from a list the snapshot never agreed to.
+    root = _snapshot_root(argv)
+    try:
+        operations = load_catalog(Snapshot(root))
+    except SnapshotError as exc:
+        print(f"si: {exc}", file=sys.stderr)
+        return 2
+
+    parser, _ = _build_parser(operations)
+    args = parser.parse_args(argv)
+
+    operation = getattr(args, "_operation", None)
+    if operation is None:
+        parser.print_help()
+        return 2
+
+    if operation == "__catalog__":
+        print("\n".join(_render_catalog(operations)))
+        return 0
+
+    op = operations[operation]
+    params = {p: getattr(args, _dest(p)) for p in op.params}
+    params = {k: v for k, v in params.items() if v not in (None, False)}
+
+    try:
+        status, payload = query(operation, params, root)
+    except SnapshotError as exc:
+        print(f"si: {exc}", file=sys.stderr)
+        return 2
+
+    if args.json:
+        print(json.dumps(payload, indent=2, sort_keys=True))
+    else:
+        print(f"{operation}  [{status}]")
+        print("\n".join(_render(payload, 1)))
+
+    if status != "SUCCESS":
+        return 1
+    # `validate --strict` is a CI gate: an invalid snapshot must fail the command, not merely
+    # report inside a successful one.
+    if payload.get("valid") is False:
+        return 1
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

inspector/graph.py

@@ -0,0 +1,138 @@
+"""Semantic graph — the traversal substrate behind every SNAPSHOT_QUERY operation.
+
+The graph is the union of every domain's `evidence/<domain>/evidence.json` (artifact-level nodes
++ typed edges), deduplicated: an artifact visible to three domain builds contributes one node and
+its edges once. Operations here are STRUCTURAL only — neighbourhood, closure, grouping. No domain
+knowledge and no PGC semantics live here; that is what keeps inspection from becoming a second
+governance engine.
+
+Edge direction, as the compiler materializes it:
+
+    source --kind--> target    means "source depends on / contains / routes to target"
+
+So the CONSUMERS of X are the sources of edges INTO X (`refs`), and X's DEPENDENCIES are the
+targets of edges out of X (`deps`). Impact analysis is the transitive consumer closure.
+
+Ported from `protocol_compiler/compiler/inspection/traversal.py`, which this repo supersedes.
+"""
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass
+from typing import Any
+
+from inspector.snapshot import Snapshot
+
+
+@dataclass(frozen=True)
+class Edge:
+    source: str
+    target: str
+    kind: str
+    metadata_json: str  # canonical JSON — keeps Edge hashable, so dedup is by value
+
+    @property
+    def metadata(self) -> dict[str, Any]:
+        return json.loads(self.metadata_json)
+
+
+class SemanticGraph:
+    """Federated, immutable artifact graph over every composed domain."""
+
+    def __init__(self, snapshot: Snapshot) -> None:
+        nodes: dict[str, str] = {}
+        edges: set[Edge] = set()
+
+        for domain in snapshot.evidence_domains():
+            evidence = snapshot.evidence(domain)
+            for node in evidence.get("nodes", []):
+                nodes.setdefault(node["fqdn"], node["kind"])
+            for edge in evidence.get("edges", []):
+                edges.add(Edge(
+                    source=edge["source_fqdn"],
+                    target=edge["target_fqdn"],
+                    kind=edge["kind"],
+                    metadata_json=json.dumps(edge.get("metadata", {}), sort_keys=True),
+                ))
+
+        self.nodes = nodes
+        self.edges = sorted(edges, key=lambda e: (e.source, e.target, e.kind, e.metadata_json))
+
+        self._out: dict[str, list[Edge]] = {}
+        self._in: dict[str, list[Edge]] = {}
+        for edge in self.edges:
+            self._out.setdefault(edge.source, []).append(edge)
+            self._in.setdefault(edge.target, []).append(edge)
+
+    # ── direct neighbourhood ─────────────────────────────────────
+
+    def out_edges(self, fqdn: str) -> list[Edge]:
+        return self._out.get(fqdn, [])
+
+    def in_edges(self, fqdn: str) -> list[Edge]:
+        return self._in.get(fqdn, [])
+
+    def node_kind(self, fqdn: str) -> str:
+        return self.nodes.get(fqdn, "UNKNOWN")
+
+    def known(self, fqdn: str) -> bool:
+        """True iff the graph carries this artifact as a node.
+
+        An artifact can be indexed but carry no evidence node — it is then not traversable, which
+        a caller must be able to distinguish from "traversable but unreferenced".
+        """
+        return fqdn in self.nodes
+
+    # ── walks ────────────────────────────────────────────────────
+
+    def refs(self, fqdn: str, transitive: bool = False) -> list[dict[str, Any]]:
+        """Who references this artifact — incoming edges; its consumers."""
+        return self._walk(fqdn, self._in, "source", transitive)
+
+    def deps(self, fqdn: str, transitive: bool = False) -> list[dict[str, Any]]:
+        """What this artifact depends on — outgoing edges."""
+        return self._walk(fqdn, self._out, "target", transitive)
+
+    def _walk(
+        self,
+        start: str,
+        adjacency: dict[str, list[Edge]],
+        neighbor_attr: str,
+        transitive: bool,
+    ) -> list[dict[str, Any]]:
+        results: list[dict[str, Any]] = []
+        visited: set[str] = {start}
+        frontier = [start]
+        depth = 0
+        while frontier:
+            depth += 1
+            next_frontier: list[str] = []
+            for fqdn in frontier:
+                for edge in adjacency.get(fqdn, []):
+                    neighbor = getattr(edge, neighbor_attr)
+                    if neighbor in visited:
+                        continue
+                    visited.add(neighbor)
+                    results.append({
+                        "fqdn": neighbor,
+                        "kind": self.node_kind(neighbor),
+                        "edge_kind": edge.kind,
+                        "depth": depth,
+                    })
+                    next_frontier.append(neighbor)
+            if not transitive:
+                break
+            frontier = next_frontier
+        results.sort(key=lambda r: (r["depth"], r["fqdn"]))
+        return results
+
+    def impact(self, fqdn: str) -> dict[str, dict[str, list[str]]]:
+        """Transitive consumer closure, grouped by artifact kind then namespace."""
+        grouped: dict[str, dict[str, list[str]]] = {}
+        for record in self.refs(fqdn, transitive=True):
+            namespace = record["fqdn"].split("::", 1)[0]
+            grouped.setdefault(record["kind"], {}).setdefault(namespace, []).append(record["fqdn"])
+        return {
+            kind: {ns: sorted(set(fqdns)) for ns, fqdns in sorted(by_ns.items())}
+            for kind, by_ns in sorted(grouped.items())
+        }

inspector/kinds.py

@@ -0,0 +1,19 @@
+"""Inspection vocabulary — handler kinds and catalog categories.
+
+A leaf module that imports nothing, so the registry, the catalog reader, and the projections can
+all name these without importing each other. They are the fixed words of the inspection surface:
+
+    SNAPSHOT_READ   project PUBLISHED snapshot material — no traversal, no evaluation
+    SNAPSHOT_QUERY  DERIVE a result by traversing or evaluating snapshot state
+
+The handler kinds are also transport handler kinds: the boundary routes by them, and the pair is
+part of the Transport Standard rather than of this repo. `CATEGORIES` is presentation order for a
+catalog — the only thing here that is purely this surface's own.
+"""
+
+SNAPSHOT_READ = "SNAPSHOT_READ"
+SNAPSHOT_QUERY = "SNAPSHOT_QUERY"
+
+INSPECTION_KINDS = (SNAPSHOT_READ, SNAPSHOT_QUERY)
+
+CATEGORIES = ("SNAPSHOT", "ARTIFACTS", "STORES", "VOCABULARY", "BEHAVIOR")