@canonical/pragma-cli 0.36.0 → 0.38.0

package/src/capabilities/graph/connect.test.ts

@@ -0,0 +1,361 @@
+/**
+ * `graph connect` over a fixture graph authored for it.
+ *
+ * The five negative answers and the traversal policy are tested HERE, against
+ * data this repo owns, because that is the only place exact numbers mean
+ * anything: the shipped pack's hop counts and path sets will move the moment new
+ * symbols and binding records land, so pinning them there would fail on a
+ * correct change. What the shipped pack is tested for is invariants — see
+ * `connect.shipped.exec.test.ts`.
+ *
+ * Each of the five causes is reached, and each is asserted to be
+ * DISTINGUISHABLE from the other four: two refusals with different codes, and
+ * three answers with different discriminators. That is the whole point of
+ * `connect`'s output contract — a caller who cannot tell "I have never heard of
+ * this name" from "these two are unrelated" has been told nothing.
+ */
+
+import { afterAll, beforeAll, describe, expect, it } from "vitest";
+import { verbKey } from "../../kernel/packs/uniqueness.js";
+import { ROSTER_THRESHOLD } from "../../kernel/runtime/readEntity.js";
+import type { PragmaRuntime } from "../../kernel/runtime/types.js";
+import type { VerbSpec } from "../../kernel/spec/types.js";
+import {
+  CHAIN_LENGTH,
+  CONNECT_PREFIXES,
+  CONNECT_TTL,
+  HUB_ROSTER_SIZE,
+  ROSTER_SIZE,
+} from "../../testing/fixtures/connectGraph.js";
+import { buildFixtureRuntime } from "../../testing/helpers/packRuntime.js";
+import type { ConnectResult } from "./connect.types.js";
+import { graphModule } from "./index.js";
+
+const DS = "https://ds.canonical.com/";
+const RDF_TYPE = "http://www.w3.org/1999/02/22-rdf-syntax-ns#type";
+
+const connect = graphModule.verbs.find(
+  (v) => verbKey(v.path) === "graph connect",
+) as VerbSpec;
+
+let rt: PragmaRuntime;
+beforeAll(async () => {
+  ({ rt } = await buildFixtureRuntime({
+    ttl: CONNECT_TTL,
+    prefixes: CONNECT_PREFIXES,
+  }));
+});
+afterAll(async () => {
+  (await rt.store.get()).store.dispose();
+});
+
+/** Ask one connect question through the verb, as a projector would. */
+async function ask(
+  a: string,
+  b: string,
+  options: { hops?: number; paths?: number } = {},
+): Promise<ConnectResult> {
+  return (await connect.run({ a, b, ...options }, rt)) as ConnectResult;
+}
+
+/** The error a question raises, or `undefined` when it answered. */
+async function refusal(
+  a: string,
+  b: string,
+  options: { hops?: number; paths?: number } = {},
+): Promise<{ code?: string; message: string; suggestions?: string[] }> {
+  try {
+    await ask(a, b, options);
+  } catch (error) {
+    return error as { code?: string; message: string; suggestions?: string[] };
+  }
+  throw new Error(`connect ${a} ${b} answered where it should have refused`);
+}
+
+describe("graph connect — the traversal policy", () => {
+  it("walks a chain and reports the hop count and the limit it used", async () => {
+    const result = await ask("ds:a1", "ds:a5");
+    expect(result.connected).toBe(true);
+    expect(result.hops).toBe(4);
+    expect(result.pathCount).toBe(1);
+    expect(result.paths[0]?.steps).toHaveLength(4);
+    expect(result.hopLimit).toBe(4);
+    expect(result.rosterThreshold).toBe(ROSTER_THRESHOLD);
+  });
+
+  it("walks each step in the direction the triple is asserted", async () => {
+    // ds:r2 points at BOTH ends, so the only route runs against the first
+    // edge's direction. A path that dropped `direction` would claim
+    // `ds:r1 ds:pointsAt ds:r2`, which the graph does not assert.
+    const result = await ask("ds:r1", "ds:r3");
+    expect(result.connected).toBe(true);
+    expect(result.paths[0]?.steps.map((step) => step.direction)).toEqual([
+      "reverse",
+      "forward",
+    ]);
+    expect(result.paths[0]?.steps.map((step) => step.to.value)).toEqual([
+      `${DS}r2`,
+      `${DS}r3`,
+    ]);
+  });
+
+  it("walks THROUGH a blank-node record", async () => {
+    // The traversal a per-layer SPARQL query cannot do: a blank node's label is
+    // not a legal IRI, so a frontier query either fails or drops it silently.
+    const result = await ask("ds:bridgeStart", "ds:bridgeEnd");
+    expect(result.connected).toBe(true);
+    expect(result.hops).toBe(2);
+    const middle = result.paths[0]?.steps[0]?.to;
+    expect(middle?.addressable).toBe(false);
+    expect(result.paths[0]?.steps[1]?.from.value).toBe(middle?.value);
+  });
+
+  it("returns ONLY shortest paths, all of one length, ranked and distinct", async () => {
+    const result = await ask("ds:m1", "ds:m2");
+    expect(result.hops).toBe(2);
+    expect(result.pathCount).toBe(3);
+    for (const path of result.paths) expect(path.steps).toHaveLength(2);
+    // Ranked by fewest distinct predicates, then lexicographically: the two
+    // single-family routes come first, alpha before gamma, and the route that
+    // mixes two predicates comes last.
+    expect(result.paths.map((path) => path.steps[0]?.to.value)).toEqual([
+      `${DS}via1`,
+      `${DS}via3`,
+      `${DS}via2`,
+    ]);
+    expect(result.truncated).toBeUndefined();
+  });
+
+  it("caps the paths shown but never the count, and says it truncated", async () => {
+    const capped = await ask("ds:m1", "ds:m2", { paths: 1 });
+    expect(capped.paths).toHaveLength(1);
+    expect(capped.pathCount).toBe(3);
+    expect(capped.truncated).toBe(true);
+    // A cap above the true count is not a truncation.
+    const generous = await ask("ds:m1", "ds:m2", { paths: 99 });
+    expect(generous.paths).toHaveLength(3);
+    expect(generous.truncated).toBeUndefined();
+  });
+
+  it("honours --hops, up to its ceiling, and refuses above it", async () => {
+    // The chain is longer than the ceiling, so it can be walked to the ceiling
+    // and still have a pair the ceiling cannot reach.
+    expect((await ask("ds:a1", "ds:a6")).connected).toBe(false);
+    const raised = await ask("ds:a1", "ds:a6", { hops: 5 });
+    expect(raised.connected).toBe(true);
+    expect(raised.hops).toBe(5);
+    expect(raised.hopLimit).toBe(5);
+    const ceiling = await ask("ds:a1", "ds:a7", { hops: 6 });
+    expect(ceiling.connected).toBe(true);
+    expect(ceiling.hops).toBe(6);
+
+    // Above the ceiling it REFUSES rather than clamping: a clamped limit is a
+    // limit the answer would report without the caller having set it.
+    const tooFar = await refusal("ds:a1", "ds:a7", { hops: 7 });
+    expect(tooFar.code).toBe("INVALID_INPUT");
+    expect(tooFar.message).toContain("7");
+    const notWhole = await refusal("ds:a1", "ds:a7", { hops: 2.5 });
+    expect(notWhole.code).toBe("INVALID_INPUT");
+  });
+
+  it("classifies each edge, not each predicate name", async () => {
+    // ONE predicate, two group sizes. `ds:shares` fans in past the threshold on
+    // ds:hub and stays under it on ds:small, so the same predicate is a roster
+    // at one node and a real relation at another. No rule keyed on a predicate
+    // NAME can produce both of these answers.
+    const relation = await ask("ds:relA", "ds:relB");
+    expect(relation.connected).toBe(true);
+    expect(relation.hops).toBe(2);
+    expect(relation.paths[0]?.steps[0]?.predicate.value).toBe(`${DS}shares`);
+
+    const roster = await ask("ds:member0", "ds:member1");
+    expect(roster.connected).toBe(false);
+    expect(
+      roster.sharedRosters.map((group) => group.predicate.value),
+    ).toContain(`${DS}shares`);
+  });
+
+  it("applies the rule in BOTH directions of a group", async () => {
+    // ds:fanHub fans OUT past the threshold, so its edges are refused for the
+    // (subject, predicate) half of the rule — the half a rule that only counted
+    // inbound fan-in would miss entirely.
+    const result = await ask("ds:leaf0", "ds:leaf1");
+    expect(result.connected).toBe(false);
+    expect(result.sharedRosters).toEqual([
+      {
+        side: "objects",
+        predicate: expect.objectContaining({ value: `${DS}fansTo` }),
+        node: expect.objectContaining({ value: `${DS}fanHub` }),
+        members: ROSTER_SIZE,
+      },
+    ]);
+  });
+
+  it("answers the same path set whichever way round it is asked", async () => {
+    const forwards = await ask("ds:m1", "ds:m2");
+    const backwards = await ask("ds:m2", "ds:m1");
+    expect(backwards.hops).toBe(forwards.hops);
+    expect(backwards.pathCount).toBe(forwards.pathCount);
+    // The same paths, walked the other way: reverse the step order, swap each
+    // step's ends, and flip its direction.
+    const mirrored = backwards.paths.map((path) =>
+      [...path.steps].reverse().map((step) => ({
+        from: step.to.value,
+        to: step.from.value,
+        predicate: step.predicate.value,
+        direction: step.direction === "forward" ? "reverse" : "forward",
+      })),
+    );
+    const original = forwards.paths.map((path) =>
+      path.steps.map((step) => ({
+        from: step.from.value,
+        to: step.to.value,
+        predicate: step.predicate.value,
+        direction: step.direction,
+      })),
+    );
+    expect(mirrored.map((p) => JSON.stringify(p)).sort()).toEqual(
+      original.map((p) => JSON.stringify(p)).sort(),
+    );
+  });
+});
+
+describe("graph connect — the five negative answers, each distinguishable", () => {
+  it("(a) refuses an absent name, naming WHICH argument, with suggestions", async () => {
+    const first = await refusal("ds:membre0", "ds:a1");
+    expect(first.code).toBe("ENTITY_NOT_FOUND");
+    expect(first.message).toContain("<a>");
+    expect(first.message).toContain("ds:membre0");
+    // A name-similarity suggestion, from the same index the argument's own
+    // shell completion draws on.
+    expect(first.suggestions).toContain("ds:member0");
+    // And never a connectivity VERDICT: a typo must not be reported as a fact
+    // about how two things relate. (Saying that nothing can be said is the
+    // opposite of a claim, so the check is for the verdicts themselves.)
+    expect(first.message).not.toMatch(
+      /not connected|unrelated|no path|no relation/i,
+    );
+
+    // The SECOND argument is named as the second argument.
+    const second = await refusal("ds:a1", "ds:nosuchthing");
+    expect(second.code).toBe("ENTITY_NOT_FOUND");
+    expect(second.message).toContain("<b>");
+  });
+
+  it("(b) answers that an endpoint carries no relation, and says what it is", async () => {
+    const result = await ask("ds:isolated", "ds:a1");
+    expect(result.connected).toBe(false);
+    expect(result.unconnectedBecause).toBe("endpoint-carries-no-relation");
+    expect(result.a.relatable).toBe(false);
+    expect(result.b.relatable).toBe(true);
+    // "Then what IS it?" — the groups that classify it, which is all there is
+    // to say about a node with no relations.
+    const classifiers = (result.a.classifiedBy ?? []).map(
+      (group) => group.predicate.value,
+    );
+    expect(classifiers).toContain(RDF_TYPE);
+    expect(classifiers).toContain(`${DS}shares`);
+  });
+
+  it("(c) answers that there is no path within the limit", async () => {
+    const result = await ask("ds:a1", `ds:a${CHAIN_LENGTH}`);
+    expect(result.connected).toBe(false);
+    expect(result.unconnectedBecause).toBe("no-path-within-hop-limit");
+    expect(result.hops).toBeNull();
+    expect(result.paths).toEqual([]);
+    // Nothing in common at all — which is what separates this from (d).
+    expect(result.sharedRosters).toEqual([]);
+    // Both endpoints ARE relatable, which is what separates it from (b).
+    expect(result.a.relatable).toBe(true);
+    expect(result.b.relatable).toBe(true);
+  });
+
+  it("(d) answers that the two share only membership, and names it", async () => {
+    const result = await ask("ds:member0", "ds:member1");
+    expect(result.connected).toBe(false);
+    expect(result.unconnectedBecause).toBe("shares-only-rosters");
+    expect(result.a.relatable).toBe(true);
+    expect(result.b.relatable).toBe(true);
+    const hub = result.sharedRosters.find(
+      (group) => group.node.value === `${DS}hub`,
+    );
+    expect(hub).toMatchObject({
+      side: "subjects",
+      members: HUB_ROSTER_SIZE,
+    });
+  });
+
+  it("(e) REFUSES when no loaded pack binds an endpoint's namespace", async () => {
+    // Staleness, not a fact about the model — and the dangerous one, because a
+    // missing pack makes the honest "no path" and the dishonest one identical.
+    // So it refuses with the store's own recovery instead of answering.
+    const result = await refusal("https://unloaded.example/thing", "ds:a1");
+    expect(result.code).toBe("STORE_UNAVAILABLE");
+    expect(result.message).toContain("https://unloaded.example/thing");
+    expect(result.message).not.toMatch(
+      /not connected|unrelated|no path|no relation/i,
+    );
+    // The recovery the kernel already mints for a store that cannot answer.
+    expect(
+      (result as { recovery?: { cli?: string; mcp?: { tool: string } } })
+        .recovery?.cli,
+    ).toContain("sources update");
+    expect(
+      (result as { recovery?: { mcp?: { tool: string } } }).recovery?.mcp?.tool,
+    ).toBe("sources_update");
+  });
+
+  it("keeps all five apart — five causes, five distinct discriminators", async () => {
+    const absent = await refusal("ds:nosuchthing", "ds:a1");
+    const unbound = await refusal("https://unloaded.example/thing", "ds:a1");
+    const answers = await Promise.all([
+      ask("ds:isolated", "ds:a1"),
+      ask("ds:a1", `ds:a${CHAIN_LENGTH}`),
+      ask("ds:member0", "ds:member1"),
+    ]);
+    // The two refusals carry different codes...
+    expect(new Set([absent.code, unbound.code]).size).toBe(2);
+    // ...and the three answers carry different reasons, none of them empty.
+    const reasons = answers.map((answer) => answer.unconnectedBecause);
+    expect(new Set(reasons).size).toBe(3);
+    for (const answer of answers) {
+      expect(answer.connected).toBe(false);
+      expect(answer.unconnectedBecause).toBeDefined();
+    }
+  });
+});
+
+describe("graph connect — what every answer states about itself", () => {
+  it("reports the packs the answering store was actually built from", async () => {
+    const session = await rt.store.get();
+    const result = await ask("ds:a1", "ds:a2");
+    expect(result.packs).toEqual(
+      session.manifest.sourceRef
+        .split(",")
+        .map((ref) => ref.trim())
+        .filter((ref) => ref.length > 0),
+    );
+  });
+
+  it("states its policy on a NEGATIVE answer too", async () => {
+    // The cheapest answer is the one most in need of context: without the
+    // limit, the threshold and the packs, "not connected" is unfalsifiable.
+    const result = await ask("ds:a1", `ds:a${CHAIN_LENGTH}`, { hops: 3 });
+    expect(result.hopLimit).toBe(3);
+    expect(result.rosterThreshold).toBe(ROSTER_THRESHOLD);
+    expect(result.packs.length).toBeGreaterThan(0);
+  });
+
+  it("refuses two spellings of the same entity rather than answering 0 hops", async () => {
+    const result = await refusal("ds:a1", `${DS}a1`);
+    expect(result.code).toBe("INVALID_INPUT");
+  });
+
+  it("refuses an unknown prefix as invalid input, naming the loaded ones", async () => {
+    const result = await refusal("nope:a1", "ds:a1");
+    expect(result.code).toBe("INVALID_INPUT");
+    expect((result as { validOptions?: string[] }).validOptions).toContain(
+      "ds",
+    );
+  });
+});

package/src/capabilities/graph/connect.types.ts

@@ -0,0 +1,136 @@
+/**
+ * The shape of a `graph connect` answer — the ONE contract its run body writes
+ * and its three formatters read.
+ *
+ * Type-only, and deliberately its own module: the formatters hang off the verb
+ * spec, so they are on the static import graph the lazy-dispatch probe walks
+ * (`capabilities/lazy.test.ts`), while the walk itself must stay behind a
+ * dynamic import. A shared type module lets both sides name the same answer
+ * without dragging the traversal onto the storeless fast path.
+ *
+ * Every answer carries the POLICY it was produced under — the hop limit, the
+ * roster threshold, and the packs searched. That is Constitution VI applied to
+ * the answer rather than only to the source: the commonest answer this verb
+ * gives is "these two are not connected", and that sentence means nothing
+ * without knowing how far it looked, what it was willing to walk, and what it
+ * was looking in. A missing pack is what makes an honest "no path" and a
+ * dishonest one byte-identical, so `packs` is present whether the answer is
+ * positive or negative.
+ */
+
+/** A node or predicate as the answer names it: full IRI, short form, human name. */
+export interface ConnectTerm {
+  /** The full IRI, or a blank node's session-local label. */
+  readonly value: string;
+  /** Prefixed form, when a loaded namespace matches. */
+  readonly prefixed?: string;
+  /** Human name from the pack index, when it says more than the local name. */
+  readonly title?: string;
+  /**
+   * Marks a term no `pragma:{+uri}` read can resolve. Only blank nodes carry
+   * it: their labels re-mint on every load, so the record is real but its
+   * handle is not addressable. Blank nodes ARE walked — 6,942 of them carry the
+   * token graph's declarations and resolved values — so a path may name one.
+   */
+  readonly addressable?: false;
+}
+
+/**
+ * One step of a path: the triple that was traversed, and which way.
+ *
+ * `direction` is not decoration. `forward` says the triple `(from, predicate,
+ * to)` is asserted; `reverse` says `(to, predicate, from)` is. Concatenating a
+ * path's steps walks from one endpoint to the other only if each step's
+ * direction is respected, and an answer that dropped it would claim edges the
+ * graph does not assert.
+ */
+export interface ConnectStep {
+  readonly from: ConnectTerm;
+  readonly predicate: ConnectTerm;
+  readonly direction: "forward" | "reverse";
+  readonly to: ConnectTerm;
+}
+
+/** One path: an ordered walk of steps from `a` to `b`. */
+export interface ConnectPath {
+  readonly steps: readonly ConnectStep[];
+}
+
+/**
+ * A group both endpoints belong to that is a ROSTER rather than a relation —
+ * membership, which is what the noun's own list verb answers properly.
+ *
+ * Two shapes, because a group has two directions: `subjects` means both
+ * endpoints are subjects of `predicate` pointing at `node` (both are
+ * `ds:Component`s, both in the `ds:global` tier); `objects` means both are
+ * objects of `node` asserting `predicate` (both covered by one modifier
+ * family's 359 `dt:covers` edges). Reporting these is what separates "unrelated
+ * in the model, though they do share membership" from "unrelated, full stop".
+ */
+export interface SharedRoster {
+  /** Which side of the group the two endpoints sit on. */
+  readonly side: "subjects" | "objects";
+  readonly predicate: ConnectTerm;
+  /** The group's other end: the shared object, or the shared subject. */
+  readonly node: ConnectTerm;
+  /** The TRUE size of the group — why it is a roster and not a relation. */
+  readonly members: number;
+}
+
+/** One endpoint of the question, as the store resolved it. */
+export interface ConnectEndpoint {
+  /** The value the caller supplied, verbatim. */
+  readonly input: string;
+  readonly term: ConnectTerm;
+  /**
+   * False when this endpoint carries no walkable relation edge in either
+   * direction — it is in the graph, but only classified. Nothing can be
+   * connected to it, which is a different answer from "nothing is".
+   */
+  readonly relatable: boolean;
+  /**
+   * The roster groups that classify an endpoint, present only when
+   * {@link relatable} is false — the answer to "then what IS it?", which is
+   * the only useful thing to say about a node with no relations.
+   */
+  readonly classifiedBy?: readonly SharedRoster[];
+}
+
+/**
+ * Why an unconnected pair is unconnected. Three of `CN.07`'s five cases; the
+ * other two are refusals rather than answers (an absent name throws
+ * `ENTITY_NOT_FOUND` naming which argument, an unbound namespace throws
+ * `STORE_UNAVAILABLE`), because neither may make a connectivity claim at all.
+ */
+export type ConnectRefusal =
+  /** An endpoint carries no relation edge — see {@link ConnectEndpoint.relatable}. */
+  | "endpoint-carries-no-relation"
+  /** The walk exhausted, but the two share membership — {@link ConnectResult.sharedRosters}. */
+  | "shares-only-rosters"
+  /** The walk exhausted with nothing in common at all. */
+  | "no-path-within-hop-limit";
+
+/** The answer to one `graph connect` question. */
+export interface ConnectResult {
+  readonly a: ConnectEndpoint;
+  readonly b: ConnectEndpoint;
+  readonly connected: boolean;
+  /** Which negative answer this is; absent when {@link connected}. */
+  readonly unconnectedBecause?: ConnectRefusal;
+  /** The shortest-path length, or null when there is no path. */
+  readonly hops: number | null;
+  /** How many distinct shortest paths there are — the truth behind `paths`. */
+  readonly pathCount: number;
+  /** The shortest paths, ranked and capped by `--paths`. */
+  readonly paths: readonly ConnectPath[];
+  /** Set when `paths` is shorter than {@link pathCount}. */
+  readonly truncated?: true;
+  /** Roster groups both endpoints belong to (see {@link SharedRoster}). */
+  readonly sharedRosters: readonly SharedRoster[];
+  /** The hop limit actually applied to this walk. */
+  readonly hopLimit: number;
+  /** The fan-in above which an edge was refused as a roster. */
+  readonly rosterThreshold: number;
+  /** The packs the answering store was built from, as it records them. */
+  readonly packs: readonly string[];
+}

package/src/capabilities/graph/connect.verb.ts

@@ -0,0 +1,165 @@
+/**
+ * `graph connect <a> <b>` — what connects two entities, and what "unlinked"
+ * means when nothing does.
+ *
+ * The third verb on the `graph` noun, beside `inspect` (one entity's
+ * neighbourhood) and `query` (the raw SPARQL escape hatch). It belongs here for
+ * the same reason those two do: it reads ACROSS the whole store rather than
+ * within one population, so it hangs off the noun for a store-wide read and
+ * adds no noun of its own.
+ *
+ * It is hand-written rather than a declared pack story because the pack grammar
+ * cannot express it. A list story's parameters are exactly its declared filters
+ * plus its declared search, every filter is projected as an OPTIONAL NAMED
+ * flag, and the only positional-and-required parameter the compiler ever mints
+ * is a lookup's single name — so there is nowhere in the grammar to put two
+ * required entity arguments. And a filter is a row predicate over an author's
+ * query, so a declared form would have to enumerate the walk space and let a
+ * filter pick one pair out of it: at four hops that space is 71 million walks,
+ * against the largest declared story's 1,698 rows.
+ *
+ * Both arguments accept exactly what `graph inspect` accepts — a prefixed name
+ * or an absolute IRI — and complete from the pack index through the same
+ * `names`/`index` source a compiled lookup's `<name>` uses, so the two
+ * positionals behave like every other entity argument in the CLI.
+ *
+ * Store-backed and read-only, like both its siblings. The traversal lives in a
+ * dynamically-imported run body: the relation index it needs is built by one
+ * scan of the store, and a process that never asks a connect question must
+ * never pay for it — which is the same guarantee `needsStore` and the lazy
+ * store already give every other read.
+ */
+
+import { BIN_NAME } from "../../constants.js";
+import { PragmaError } from "../../kernel/error/index.js";
+import { asVerb } from "../../kernel/spec/asVerb.js";
+import type { VerbSpec } from "../../kernel/spec/index.js";
+import { connectFormatters } from "./connect.render.js";
+import type { ConnectResult } from "./connect.types.js";
+
+/**
+ * The hop limit in force unless `--hops` says otherwise.
+ *
+ * Four, from the measured connectivity ladder on the shipped pack: it is the
+ * smallest limit that spans the longest genuine bridge in this store — the walk
+ * from a platform variable through its declaration and its references to the
+ * symbol behind it — and the largest that keeps the answer set honest. At three
+ * that walk is refused; at six the connected fraction jumps and the paths stop
+ * being something a person can hold in mind.
+ */
+export const DEFAULT_HOPS = 4;
+
+/** The ceiling `--hops` may be raised to; above it the verb refuses. */
+export const MAX_HOPS = 6;
+
+/** How many shortest paths are shown unless `--paths` says otherwise. */
+export const DEFAULT_PATHS = 10;
+
+/**
+ * Hold a numeric param to a whole number within its stated range.
+ *
+ * REFUSES rather than clamps. A clamped `--hops 40` would answer a question
+ * nobody asked and report a limit the caller did not set, which is precisely
+ * the hidden policy every answer's policy block exists to rule out.
+ *
+ * The kernel already coerces a `number` param and rejects what is not a number
+ * at all (`project/cli/dispatch.ts#coerceParam`, and `z.number()` over MCP), so
+ * what is left to check is RANGE and wholeness — `--hops 2.5` is a number, and
+ * it is not a hop count.
+ *
+ * @param value - The coerced param value.
+ * @param name - The flag's name, for the diagnostic.
+ * @param fallback - The value when the flag was not given.
+ * @param min - The smallest accepted value.
+ * @param max - The largest accepted value, if there is one.
+ * @returns The validated integer.
+ * @throws PragmaError INVALID_INPUT when the value is not an integer in range.
+ */
+function bounded(
+  value: unknown,
+  name: string,
+  fallback: number,
+  min: number,
+  max?: number,
+): number {
+  if (value === undefined || value === null) return fallback;
+  const parsed = typeof value === "number" ? value : Number(value);
+  const ceiling = max === undefined ? "" : ` and at most ${max}`;
+  if (
+    !Number.isInteger(parsed) ||
+    parsed < min ||
+    (max !== undefined && parsed > max)
+  ) {
+    throw PragmaError.invalidInput(name, String(value), {
+      recovery: {
+        message: `--${name} must be a whole number of at least ${min}${ceiling}.`,
+      },
+    });
+  }
+  return parsed;
+}
+
+const connectVerb: VerbSpec<Record<string, unknown>, ConnectResult> = {
+  path: ["graph", "connect"],
+  summary: "Show the shortest relation paths between two entities.",
+  doc: "Finds every shortest path of RELATION edges between two entities, and says which kind of nothing it found when there is no path. An edge counts as a relation only where it does not fan out into a roster — membership of a class, a tier or a family is answered by that noun's list verb, not by a path — so most pairs are correctly reported as unconnected. Address each endpoint by prefixed name (ds:global.component.button) or absolute IRI. Every answer states the hop limit, the fan-in threshold, and the packs searched.",
+  params: [
+    {
+      kind: "string",
+      name: "a",
+      doc: "The first endpoint — a prefixed name or absolute IRI.",
+      positional: true,
+      required: true,
+      complete: { kind: "names", source: { from: "index", type: "" } },
+    },
+    {
+      kind: "string",
+      name: "b",
+      doc: "The second endpoint — a prefixed name or absolute IRI.",
+      positional: true,
+      required: true,
+      complete: { kind: "names", source: { from: "index", type: "" } },
+    },
+    {
+      kind: "number",
+      name: "hops",
+      doc: `Largest path length to return (default ${DEFAULT_HOPS}, ceiling ${MAX_HOPS}).`,
+      default: DEFAULT_HOPS,
+    },
+    {
+      kind: "number",
+      name: "paths",
+      doc: `Most shortest paths to show (default ${DEFAULT_PATHS}); the answer always reports the true total.`,
+      default: DEFAULT_PATHS,
+    },
+  ],
+  output: { formatters: connectFormatters },
+  examples: [
+    {
+      cmd: `${BIN_NAME} graph connect ds:global.component.button dt:color.text`,
+      note: "a block and a token symbol",
+    },
+    {
+      cmd: `${BIN_NAME} graph connect ds:global.component.button ds:apps.pattern.datatable --format json`,
+      note: "an honest unlinked answer, with the policy it was found under",
+    },
+  ],
+  capability: {
+    needsStore: true,
+    mutates: false,
+    mcp: {
+      expose: true,
+      annotations: { readOnlyHint: true, openWorldHint: false },
+    },
+  },
+  run: (params: Record<string, unknown>, rt) =>
+    import("./runConnect.js").then((m) =>
+      m.runConnect(rt, String(params.a), String(params.b), {
+        hops: bounded(params.hops, "hops", DEFAULT_HOPS, 1, MAX_HOPS),
+        paths: bounded(params.paths, "paths", DEFAULT_PATHS, 1),
+      }),
+    ),
+};
+
+/** The `graph connect` verb. */
+export const graphConnectVerb = asVerb(connectVerb);

package/src/capabilities/graph/index.ts

@@ -1,10 +1,12 @@
 /**
- * The `graph` capability module — `inspect` (single-entity read) plus `query`
- * (the raw SPARQL escape hatch, PR6). The covenant blesses both.
+ * The `graph` capability module — `inspect` (single-entity read), `query` (the
+ * raw SPARQL escape hatch, PR6) and `connect` (relation paths between two
+ * entities). The covenant blesses all three.
  */
 
 import type { CapabilityModule } from "../../kernel/spec/index.js";
 import { resourceProvider } from "../resources/index.js";
+import { graphConnectVerb } from "./connect.verb.js";
 import { graphInspectVerb } from "./inspect.verb.js";
 import { graphQueryVerb } from "./query.verb.js";
 
@@ -16,6 +18,6 @@ import { graphQueryVerb } from "./query.verb.js";
  */
 export const graphModule: CapabilityModule = {
   name: "graph",
-  verbs: [graphInspectVerb, graphQueryVerb],
+  verbs: [graphConnectVerb, graphInspectVerb, graphQueryVerb],
   mcpResources: resourceProvider,
 };