@polycode-projects/the-mechanical-code-talker 0.2.0 → 0.4.0

package/src/providers/graph-service.mjs

@@ -0,0 +1,312 @@
+// The reference Repository-Interface service over a parsed code graph.
+// PLAN_REPOSITORY_INTERFACE.md — "the executable specification".
+//
+// createGraphService(graph) returns a typed service object implementing EVERY
+// service in src/repository-interface.mjs over the `{ individuals, byId,
+// relations, … }` shape parseEntities() yields. Every method returns a typed
+// Result (hit/miss) — a clean miss is a value, never a throw. The two providers
+// tmct ships (fixture, bootstrap) are this same builder over a small real graph
+// and over the empty bootstrap graph respectively.
+//
+// This is a GRAPH-ONLY provider: it advertises the source services (snippet,
+// context) but answers them with an honest miss(NO_SOURCE) — it exposes no
+// working tree. A host with a working tree (seonix, the chat shell) layers source
+// access on top. Pure graph queries, no fs, no LLM.
+
+import {
+  resolveSymbol,
+  siteOf,
+  edgesOfKind,
+  relationKind,
+  impactClosure,
+} from "../codegraph.mjs";
+import { ask } from "../ask.mjs";
+import {
+  hit,
+  miss,
+  toIndividual,
+  toEdge,
+  MISS_REASONS,
+  EDGE_KINDS,
+  SERVICES,
+  SOURCE_SERVICES,
+  INTERFACE_VERSION,
+} from "../repository-interface.mjs";
+
+const attrOf = (ind, key) => (ind?.attributes || []).find((a) => a.key === key)?.value ?? null;
+
+/** Group an individual id's incoming/outgoing edges across all relations, projected
+ *  to interface Edges. */
+function edgesAround(graph, id) {
+  const out = [];
+  const incoming = [];
+  for (const g of graph.relations) {
+    for (const e of g.edges) {
+      if (e.subject === id) out.push(toEdge(e, { predicate: g.predicate, prop: g.prop }));
+      if (e.object === id) incoming.push(toEdge(e, { predicate: g.predicate, prop: g.prop }));
+    }
+  }
+  return { out, incoming };
+}
+
+/** The kind-tagged relation group's predicate/prop for a given edge kind (for Edge
+ *  projection). Returns the first relation group classifying to `kind`. */
+function groupMetaForKind(graph, kind) {
+  for (const g of graph.relations) if (relationKind(g) === kind) return { predicate: g.predicate, prop: g.prop };
+  return { predicate: kind, prop: null };
+}
+
+/**
+ * @param {object} graph  a parseEntities() result
+ * @param {object} [opts]
+ * @param {boolean} [opts.sourceAccess=false]  whether source services can read bodies
+ * @returns the typed service object
+ */
+export function createGraphService(graph, { sourceAccess = false } = {}) {
+  const byId = graph.byId;
+
+  const resolveId = (id) => byId.get(id) || null;
+
+  const svc = {
+    version: INTERFACE_VERSION,
+    /** Advertised services. Source services are listed but honestly answer NO_SOURCE
+     *  unless a source-capable provider overrides them. */
+    capabilities: [...SERVICES],
+    sourceAccess: Boolean(sourceAccess),
+    /** The underlying graph — tmct-internal presentation (render*) reads it; not
+     *  part of the wire contract. */
+    graph,
+
+    resolve(term) {
+      const { match, candidates } = resolveSymbol(graph, String(term ?? ""));
+      if (!match) return miss(MISS_REASONS.UNRESOLVED_TERM, { term: String(term ?? "") });
+      return hit({ match: toIndividual(match), candidates: candidates.map(toIndividual) });
+    },
+
+    describe(id) {
+      const ind = resolveId(id);
+      if (!ind) return miss(MISS_REASONS.UNRESOLVED_TERM, { term: id });
+      const { out, incoming } = edgesAround(graph, id);
+      return hit({ individual: toIndividual(ind), out, incoming });
+    },
+
+    members(classId) {
+      const ind = resolveId(classId);
+      if (!ind) return miss(MISS_REASONS.UNRESOLVED_TERM, { term: classId });
+      const contains = edgesOfKind(graph, "contains").filter((e) => e.subject === classId);
+      const methods = [];
+      const attributes = [];
+      for (const e of contains) {
+        const m = byId.get(e.object);
+        const proj = m ? toIndividual(m) : { id: e.object, label: e.objectLabel || e.object, class: "Entity", attributes: [] };
+        if ((m?.class || "") === "Attribute") attributes.push(proj);
+        else methods.push(proj);
+      }
+      return hit({ methods, attributes });
+    },
+
+    subclasses(classId) {
+      const ind = resolveId(classId);
+      if (!ind) return miss(MISS_REASONS.UNRESOLVED_TERM, { term: classId });
+      const inherits = edgesOfKind(graph, "inherits");
+      const bases = inherits
+        .filter((e) => e.subject === classId)
+        .map((e) => byId.get(e.object) ? toIndividual(byId.get(e.object)) : { id: e.object, label: e.objectLabel || e.object, class: "Class", attributes: [] });
+      // transitive reverse inheritance closure (who extends this)
+      const childrenOf = new Map();
+      for (const e of inherits) {
+        if (!childrenOf.has(e.object)) childrenOf.set(e.object, []);
+        childrenOf.get(e.object).push(e.subject);
+      }
+      const seen = new Set([classId]);
+      const subs = [];
+      let frontier = [classId];
+      for (let d = 0; d < 8 && frontier.length; d += 1) {
+        const next = [];
+        for (const cur of frontier) {
+          for (const childId of childrenOf.get(cur) || []) {
+            if (seen.has(childId)) continue;
+            seen.add(childId);
+            const c = byId.get(childId);
+            subs.push(c ? toIndividual(c) : { id: childId, label: childId, class: "Class", attributes: [] });
+            next.push(childId);
+          }
+        }
+        frontier = next;
+      }
+      return hit({ bases, subclasses: subs });
+    },
+
+    exports(moduleId) {
+      const ind = resolveId(moduleId);
+      if (!ind) return miss(MISS_REASONS.UNRESOLVED_TERM, { term: moduleId });
+      const edges = edgesOfKind(graph, "reexports").filter((e) => e.subject === moduleId);
+      const exports = edges.map((e) =>
+        byId.get(e.object) ? toIndividual(byId.get(e.object)) : { id: e.object, label: e.objectLabel || e.object, class: "Entity", attributes: [] });
+      return hit({ exports });
+    },
+
+    signature(id) {
+      const ind = resolveId(id);
+      if (!ind) return miss(MISS_REASONS.UNRESOLVED_TERM, { term: id });
+      const flags = [];
+      for (const [attr, name] of [["isStatic", "static"], ["isAbstract", "abstract"], ["isConstant", "constant"]]) {
+        if (attrOf(ind, attr)) flags.push(name);
+      }
+      const vis = attrOf(ind, "visibility");
+      if (vis) flags.push(vis);
+      return hit({
+        id: ind.id,
+        label: ind.label,
+        class: ind.class || "Entity",
+        params: attrOf(ind, "params"),
+        returns: attrOf(ind, "returns"),
+        raises: attrOf(ind, "raises"),
+        decorators: attrOf(ind, "decorators"),
+        doc: attrOf(ind, "doc"),
+        selfFields: attrOf(ind, "self_fields"),
+        flags,
+      });
+    },
+
+    edges(id, kind) {
+      if (!EDGE_KINDS.includes(kind)) {
+        throw new TypeError(`edges(): unknown kind "${kind}" (not in EDGE_KINDS)`);
+      }
+      const ind = resolveId(id);
+      if (!ind) return miss(MISS_REASONS.UNRESOLVED_TERM, { term: id });
+      const meta = groupMetaForKind(graph, kind);
+      const edges = edgesOfKind(graph, kind)
+        .filter((e) => e.subject === id)
+        .map((e) => toEdge(e, meta));
+      return hit({ kind, edges });
+    },
+
+    impact(moduleId) {
+      const ind = resolveId(moduleId);
+      if (!ind) return miss(MISS_REASONS.UNRESOLVED_TERM, { term: moduleId });
+      const levels = impactClosure(graph, ind);
+      const total = levels.reduce((n, l) => n + l.length, 0);
+      return hit({ total, levels });
+    },
+
+    snippet(id) {
+      const ind = resolveId(id);
+      if (!ind) return miss(MISS_REASONS.UNRESOLVED_TERM, { term: id });
+      const site = siteOf(ind);
+      if (!svc.sourceAccess) {
+        return miss(MISS_REASONS.NO_SOURCE, {
+          term: id,
+          detail: site ? `span is ${site.path}:${site.start}-${site.end}; this provider exposes no working tree` : "no source span in the graph",
+        });
+      }
+      if (!site) return miss(MISS_REASONS.NO_SOURCE, { term: id, detail: "no source span in the graph (likely a module)" });
+      // A source-capable subclass overrides snippet to read the body; the graph-only
+      // base returns the span with a null body.
+      return hit({ path: site.path, span: { start: site.start, end: site.end }, body: null });
+    },
+
+    context(symbol) {
+      const { match } = resolveSymbol(graph, String(symbol ?? ""));
+      if (!match) return miss(MISS_REASONS.UNRESOLVED_TERM, { term: String(symbol ?? "") });
+      return miss(MISS_REASONS.NO_SOURCE, {
+        term: String(symbol ?? ""),
+        detail: "the edit bundle reaches into the working tree; this provider exposes no source",
+      });
+    },
+
+    architecture({ package: pkg = "" } = {}) {
+      const norm = String(pkg || "").trim().toLowerCase().replace(/^\.?\//, "");
+      const modules = graph.individuals.filter(
+        (i) => (i.class || "") === "Module" && (!norm || String(i.label || "").toLowerCase().startsWith(norm)),
+      );
+      const pkgCount = new Map();
+      for (const m of modules) {
+        const dir = m.label.includes("/") ? m.label.slice(0, m.label.lastIndexOf("/")) : "(root)";
+        pkgCount.set(dir, (pkgCount.get(dir) || 0) + 1);
+      }
+      const modSet = new Set(modules.map((m) => m.id));
+      const inDeg = new Map();
+      for (const e of edgesOfKind(graph, "imports")) {
+        if (modSet.has(e.object)) inDeg.set(e.object, (inDeg.get(e.object) || 0) + 1);
+      }
+      const hubs = [...inDeg.entries()]
+        .sort((a, b) => b[1] - a[1])
+        .map(([id, n]) => ({ id, label: byId.get(id)?.label || id, importers: n }));
+      const packages = [...pkgCount.entries()].sort((a, b) => b[1] - a[1]);
+      return hit({ modules: modules.length, packages, hubs });
+    },
+
+    untested() {
+      const covered = new Set(edgesOfKind(graph, "tests").map((e) => e.object));
+      const modules = graph.individuals
+        .filter((i) => (i.class || "") === "Module" && !covered.has(i.id) && !/\.test\./.test(i.label || ""))
+        .map(toIndividual);
+      return hit({ modules });
+    },
+
+    stats() {
+      const counts = new Map();
+      for (const i of graph.individuals) {
+        const c = i.class || "Entity";
+        counts.set(c, (counts.get(c) || 0) + 1);
+      }
+      const classes = [...counts.entries()]
+        .map(([cls, count]) => ({ class: cls, count }))
+        .sort((a, b) => b.count - a.count || a.class.localeCompare(b.class));
+      return hit({ total: graph.individuals.length, classes, truncated: (graph.truncated || []).length > 0 });
+    },
+
+    history(id) {
+      const ind = resolveId(id);
+      if (!ind) return miss(MISS_REASONS.UNRESOLVED_TERM, { term: id });
+      const touchEdges = [
+        ...edgesOfKind(graph, "touches"),
+        ...edgesOfKind(graph, "touchesSymbol"),
+      ].filter((e) => e.object === id);
+      const seen = new Set();
+      const commits = [];
+      for (const e of touchEdges) {
+        if (seen.has(e.subject)) continue;
+        seen.add(e.subject);
+        const c = byId.get(e.subject);
+        commits.push({
+          id: e.subject,
+          label: e.subjectLabel || c?.label || e.subject,
+          author: c ? attrOf(c, "author") ?? attrOf(c, "commitAuthor") : null,
+          date: c ? attrOf(c, "date") ?? attrOf(c, "commitDate") : null,
+          message: c ? attrOf(c, "message") ?? attrOf(c, "commitMessage") : null,
+        });
+      }
+      return hit({ commits });
+    },
+
+    search(query, { kind = "", name = "", decorator = "" } = {}) {
+      const q = String(query || "").trim().toLowerCase();
+      const k = String(kind || "").trim().toLowerCase();
+      const nm = String(name || "").trim().toLowerCase();
+      const dec = String(decorator || "").trim().toLowerCase();
+      const results = graph.individuals
+        .filter((i) => {
+          const label = String(i.label || "").toLowerCase();
+          if (k && (i.class || "").toLowerCase() !== k) return false;
+          if (nm && !label.includes(nm)) return false;
+          if (dec && !String(attrOf(i, "decorators") || "").toLowerCase().includes(dec)) return false;
+          if (q && !label.includes(q)) return false;
+          return true;
+        })
+        .map(toIndividual);
+      return hit({ results });
+    },
+
+    ask(query) {
+      const { content, tmct_ask } = ask(graph, String(query || ""));
+      return hit({ content, tmct_ask });
+    },
+  };
+
+  return svc;
+}
+
+/** The source-reaching services a graph-only provider satisfies with NO_SOURCE. */
+export { SOURCE_SERVICES };

package/src/repository-interface.mjs

@@ -0,0 +1,318 @@
+// The Repository Interface — tmct's OWNED, versioned contract between "interpret
+// the query" (tmct, the brittle side) and "ask the graph for truth" (a provider,
+// the stable side). PLAN_REPOSITORY_INTERFACE.md.
+//
+// tmct defines and versions this shape; a provider (seonix, a fixture, a browser
+// page) IMPLEMENTS it over its native graph. Both sides already agree on the
+// TYPES — every Individual.class is a `tmct:` class and every Edge.predicate a
+// `tmct:` object property (ontology/tmct-core.ttl is the type dictionary) — so
+// the interface only names the OPERATIONS over those shared types.
+//
+// The error contract is the load-bearing rule: a clean miss is a first-class
+// RETURN VALUE from a small CLOSED set of reasons (MISS_REASONS), never a throw.
+// Presentation (the render* layer, the chat surface) lives on tmct's side of the
+// seam and turns these typed results into prose; the interface returns data.
+//
+// This module is pure data + tiny constructors — no fs, no graph, no LLM.
+
+/** SemVer of the interface. Additive-by-default: new services / optional args are
+ *  minor bumps; the suite for version N stays green under N+1. A breaking change
+ *  is a new MAJOR with its own suite (see the versioning policy in the plan). */
+export const INTERFACE_VERSION = "1.0.0";
+
+/** The OWL vocabulary the types are grounded in. */
+export const ONTOLOGY_IRI = "urn:tmct:core";
+
+/**
+ * The CLOSED set of miss reasons. A service that cannot answer returns
+ * `miss(reason, detail)` with `reason` drawn from exactly these — the interpreter
+ * renders the reason, never free-text error prose.
+ *
+ * - UNRESOLVED_TERM   the term named no individual in the graph.
+ * - CAPABILITY_ABSENT the provider does not implement this service (negotiated away).
+ * - TRUNCATED_GRAPH   the answer exists but the provider shipped a truncated sample.
+ * - NO_SOURCE         a source-reaching service, but the provider exposes no working tree.
+ */
+export const MISS_REASONS = Object.freeze({
+  UNRESOLVED_TERM: "UNRESOLVED_TERM",
+  CAPABILITY_ABSENT: "CAPABILITY_ABSENT",
+  TRUNCATED_GRAPH: "TRUNCATED_GRAPH",
+  NO_SOURCE: "NO_SOURCE",
+});
+
+/** The closed vocabulary of edge kinds `edges(id, kind)` traverses, each aligned
+ *  to a `tmct:` object property (ontology/tmct-core.ttl). Symbol-granular kinds
+ *  (callsSymbol/touchesSymbol) stay separate from module-coarse calls/touches. */
+export const EDGE_KINDS = Object.freeze([
+  "imports", "calls", "callsSymbol", "defines", "tests",
+  "touches", "touchesSymbol", "contains", "inherits", "cochange", "reexports",
+]);
+
+/** edge-kind → the `tmct:` object property it realizes (the OWL grounding). */
+export const EDGE_KIND_TO_TMCT = Object.freeze({
+  imports: "tmct:imports",
+  calls: "tmct:calls",
+  callsSymbol: "tmct:calls",
+  defines: "tmct:defines",
+  tests: "tmct:covers",
+  touches: "tmct:touches",
+  touchesSymbol: "tmct:touches",
+  contains: "tmct:contains",
+  inherits: "tmct:extends",
+  cochange: "tmct:dependsOn",
+  reexports: "tmct:exports",
+});
+
+/** The named services, grouped as in the plan's six-group inventory. Names are
+ *  the interface's stable identifiers; a provider advertises which it implements
+ *  as its `capabilities`. `source: true` marks the working-tree-reaching services
+ *  a graph-only provider may satisfy with an honest NO_SOURCE miss. */
+export const SERVICE_GROUPS = Object.freeze({
+  resolution: ["resolve", "describe", "members", "subclasses", "exports", "signature"],
+  traversal: ["edges", "impact"],
+  source: ["snippet", "context"],
+  aggregate: ["architecture", "untested", "stats"],
+  temporal: ["history"],
+  search: ["search", "ask"],
+});
+
+/** Flat list of every service name. */
+export const SERVICES = Object.freeze(
+  Object.values(SERVICE_GROUPS).flat(),
+);
+
+/** The subset that reaches past the graph into a working tree. */
+export const SOURCE_SERVICES = Object.freeze(new Set(SERVICE_GROUPS.source));
+
+// ---- result constructors — the honest-miss ethos as tiny values --------------
+
+/** A successful result carrying typed `value`. */
+export function hit(value) {
+  return { ok: true, value };
+}
+
+/** A first-class miss: `reason` ∈ MISS_REASONS, optional `detail` (free text for
+ *  the human render) and `term` (what was looked up). Never thrown. */
+export function miss(reason, { detail = "", term = null } = {}) {
+  if (!MISS_REASONS[reason]) {
+    throw new TypeError(`miss(): unknown reason "${reason}" (not in MISS_REASONS)`);
+  }
+  return { ok: false, miss: { reason, detail, term } };
+}
+
+export const isHit = (r) => Boolean(r && r.ok === true);
+export const isMiss = (r) => Boolean(r && r.ok === false);
+
+// ---- type projections — raw graph rows → the interface's shared shapes --------
+
+/**
+ * Project a raw graph individual to the interface `Individual`:
+ *   { id, label, class, attributes: [{ key, value, prop }] }
+ * `class` is a `tmct:` class token; `attributes[].prop` is the SEON/mgx token the
+ * value was asserted under (OWL grounding preserved). Pure; tolerant of partials.
+ * @returns {Individual|null}
+ */
+export function toIndividual(ind) {
+  if (!ind || !ind.id) return null;
+  return {
+    id: String(ind.id),
+    label: ind.label != null ? String(ind.label) : String(ind.id),
+    class: ind.class || "Entity",
+    attributes: (Array.isArray(ind.attributes) ? ind.attributes : []).map((a) => ({
+      key: a.key,
+      value: a.value,
+      prop: a.prop || null,
+    })),
+  };
+}
+
+/**
+ * Project a raw relation edge to the interface `Edge`:
+ *   { subject, object, predicate, prop, subjectLabel?, objectLabel?, weight? }
+ * The required quartet is subject/object/predicate/prop; labels/weight are
+ * additive conveniences a provider MAY carry.
+ * @returns {Edge}
+ */
+export function toEdge(rawEdge, { predicate = "", prop = null } = {}) {
+  const e = {
+    subject: rawEdge.subject,
+    object: rawEdge.object,
+    predicate,
+    prop: prop || null,
+  };
+  if (rawEdge.subjectLabel != null) e.subjectLabel = rawEdge.subjectLabel;
+  if (rawEdge.objectLabel != null) e.objectLabel = rawEdge.objectLabel;
+  if (rawEdge.weight != null) e.weight = rawEdge.weight;
+  return e;
+}
+
+// ---- capability negotiation — CAPABILITY_ABSENT as a value, not a wall --------
+
+/**
+ * Invoke a service through capability negotiation. If the provider does not
+ * advertise `service` in `svc.capabilities`, return `miss(CAPABILITY_ABSENT)`
+ * rather than throwing — the interpreter degrades the query, never errors. When
+ * present, calls `svc[service](...args)` and returns its result verbatim.
+ *
+ * This is how a host calls an interface it cannot assume is complete; the
+ * reference providers implement every service, so they never trip it.
+ */
+export function invoke(svc, service, ...args) {
+  const caps = svc && svc.capabilities;
+  const has = Array.isArray(caps) ? caps.includes(service) : caps instanceof Set ? caps.has(service) : false;
+  if (!has || typeof svc[service] !== "function") {
+    return miss(MISS_REASONS.CAPABILITY_ABSENT, { detail: `service "${service}" is not implemented by this provider` });
+  }
+  return svc[service](...args);
+}
+
+// ---- the MACHINE-READABLE SHAPE ----------------------------------------------
+// A single JSON-serializable object enumerating every service, its args, result
+// type, and possible misses. tmct OWNS and versions this; docs/repository-
+// interface.md is the prose peer and docs/repository-interface.schema.json is the
+// committed serialization (the contract suite asserts they agree — no drift).
+
+const IND = "Individual";
+const EDGE = "Edge";
+
+/** Concurrency note shared by every read service: safe across handles — the graph
+ *  is read-only truth and the only mutable state is the caller-owned session
+ *  handle, never touched here. Proven by the suite's concurrent-session cases. */
+const CONCURRENT_SAFE = "concurrent-safe: reads immutable graph truth; no shared mutable state";
+
+export const REPOSITORY_INTERFACE = Object.freeze({
+  version: INTERFACE_VERSION,
+  ontology: ONTOLOGY_IRI,
+  missReasons: Object.values(MISS_REASONS),
+  edgeKinds: [...EDGE_KINDS],
+  types: {
+    Individual: {
+      fields: {
+        id: "string (opaque provider id)",
+        label: "string (human/display name)",
+        class: "string — a tmct: class token (module|class|function|method|attribute|variable|commit|test|…)",
+        attributes: "Array<{ key: string, value: string, prop: string|null }> — prop is the SEON/mgx token grounding the value",
+      },
+    },
+    Edge: {
+      fields: {
+        subject: "string (individual id)",
+        object: "string (individual id)",
+        predicate: "string — the relation predicate",
+        prop: "string|null — the SEON/mgx property token; see edgeKinds → tmct: mapping",
+        subjectLabel: "string? (additive)",
+        objectLabel: "string? (additive)",
+        weight: "number? (additive; e.g. cochange coupling)",
+      },
+    },
+    Result: { shape: "{ ok: true, value: T } | { ok: false, miss: Miss }" },
+    Miss: { shape: "{ reason: MISS_REASONS, detail: string, term: string|null }" },
+  },
+  capabilitiesModel:
+    "A provider advertises `capabilities: string[]` (service names it implements). " +
+    "A service outside the set is negotiated away to miss(CAPABILITY_ABSENT) — never an error. " +
+    "Source services (snippet, context) may be advertised yet answer miss(NO_SOURCE) when no working tree exists.",
+  services: {
+    resolve: {
+      group: "resolution", args: { term: "string" },
+      result: `{ match: ${IND}, candidates: ${IND}[] }`,
+      misses: ["UNRESOLVED_TERM"], concurrency: CONCURRENT_SAFE,
+      purpose: "The resolveSymbol seam: map a free term to an individual + runner-up candidates. Every id-taking service consumes a resolved id.",
+    },
+    describe: {
+      group: "resolution", args: { id: "string" },
+      result: `{ individual: ${IND}, out: ${EDGE}[], incoming: ${EDGE}[] }`,
+      misses: ["UNRESOLVED_TERM"], concurrency: CONCURRENT_SAFE,
+      purpose: "Full typed portrait of one individual: its attributes and its outgoing/incoming edges.",
+    },
+    members: {
+      group: "resolution", args: { classId: "string" },
+      result: `{ methods: ${IND}[], attributes: ${IND}[] }`,
+      misses: ["UNRESOLVED_TERM"], concurrency: CONCURRENT_SAFE,
+      purpose: "A class's methods + attributes (via the contains relation) — replaces reading the class body.",
+    },
+    subclasses: {
+      group: "resolution", args: { classId: "string" },
+      result: `{ bases: ${IND}[], subclasses: ${IND}[] }`,
+      misses: ["UNRESOLVED_TERM"], concurrency: CONCURRENT_SAFE,
+      purpose: "Forward bases + the transitive reverse inheritance closure (who extends this).",
+    },
+    exports: {
+      group: "resolution", args: { moduleId: "string" },
+      result: `{ exports: ${IND}[] }`,
+      misses: ["UNRESOLVED_TERM"], concurrency: CONCURRENT_SAFE,
+      purpose: "A module's curated public API (resolved __all__ / re-exports).",
+    },
+    signature: {
+      group: "resolution", args: { id: "string" },
+      result: "{ id, label, class, params, returns, raises, decorators, doc, selfFields, flags }",
+      misses: ["UNRESOLVED_TERM"], concurrency: CONCURRENT_SAFE,
+      purpose: "The compact API surface of a symbol without its body.",
+    },
+    edges: {
+      group: "traversal", args: { id: "string", kind: "EDGE_KINDS member" },
+      result: `{ kind: string, edges: ${EDGE}[] }`,
+      misses: ["UNRESOLVED_TERM"], concurrency: CONCURRENT_SAFE,
+      purpose: "Outgoing edges of one closed kind from an individual (an honest empty array is not a miss).",
+      note: "An unknown kind (outside EDGE_KINDS) is a programming error and throws TypeError, not a miss.",
+    },
+    impact: {
+      group: "traversal", args: { moduleId: "string" },
+      result: `{ total: number, levels: Array<Array<{ id, label, via, tests }>> }`,
+      misses: ["UNRESOLVED_TERM"], concurrency: CONCURRENT_SAFE,
+      purpose: "The transitive dependent closure the interpreter cannot compute without provider truth.",
+    },
+    snippet: {
+      group: "source", args: { id: "string" },
+      result: "{ path: string, span: { start, end }, body: string|null }",
+      misses: ["UNRESOLVED_TERM", "NO_SOURCE"], concurrency: CONCURRENT_SAFE,
+      purpose: "The exact source span of a symbol. A provider with no working tree returns miss(NO_SOURCE) honestly.",
+    },
+    context: {
+      group: "source", args: { symbol: "string", depth: "min|auto|full?" },
+      result: "{ text: string, tier: string } (a sized edit bundle)",
+      misses: ["UNRESOLVED_TERM", "NO_SOURCE"], concurrency: CONCURRENT_SAFE,
+      purpose: "The composed edit bundle (exemplar, siblings, registration, insertion region). Source-reaching.",
+    },
+    architecture: {
+      group: "aggregate", args: { package: "string?" },
+      result: "{ modules: number, packages: Array<[dir, count]>, hubs: Array<{ id, label, importers }> }",
+      misses: [], concurrency: CONCURRENT_SAFE,
+      purpose: "Package/module shape + the most-imported hub modules. Optional package prefix scopes it.",
+    },
+    untested: {
+      group: "aggregate", args: {},
+      result: `{ modules: ${IND}[] }`,
+      misses: [], concurrency: CONCURRENT_SAFE,
+      purpose: "Modules with no covering test module (via the tests relation).",
+    },
+    stats: {
+      group: "aggregate", args: {},
+      result: "{ total: number, classes: Array<{ class: string, count: number }>, truncated: boolean }",
+      misses: [], concurrency: CONCURRENT_SAFE,
+      purpose: "Per-tmct:class individual counts, read straight from the payload.",
+    },
+    history: {
+      group: "temporal", args: { id: "string" },
+      result: "{ commits: Array<{ id, label, author, date, message }> }",
+      misses: ["UNRESOLVED_TERM"], concurrency: CONCURRENT_SAFE,
+      purpose: "The commits that touched an individual (tmct:commit individuals via tmct:touches).",
+    },
+    search: {
+      group: "search", args: { query: "string", kind: "string?", name: "string?", decorator: "string?" },
+      result: `{ results: ${IND}[] }`,
+      misses: [], concurrency: CONCURRENT_SAFE,
+      purpose: "Lexical, provider-local locate. An empty result set is honest, not a miss.",
+    },
+    ask: {
+      group: "search", args: { query: "string" },
+      result: "{ content: string, tmct_ask: object } (the composed NL round-trip envelope)",
+      misses: [], concurrency: CONCURRENT_SAFE,
+      purpose: "The mechanical, zero-model NL query over the graph — tmct's whole reason to exist.",
+    },
+  },
+});
+
+/** Freeze-deep helper is unnecessary; REPOSITORY_INTERFACE is treated as read-only
+ *  data. Exported so the contract suite and docs generator share one source. */
+export default REPOSITORY_INTERFACE;