@retinue/agentkit 0.2.0 → 0.3.0

package/dist/knowledge/graph.js

@@ -0,0 +1,369 @@
+/**
+ * The knowledge graph — REQ-064 (#270), task #271.
+ *
+ * Retrieval finds the chunks that *look like* the question. That cannot answer "which teams depend on the retry
+ * budget?", because no chunk says so: the fact is spread across a dozen documents, each naming one team and one
+ * dependency. This module builds the structure that does — entities, the relationships between them, and where
+ * each came from.
+ *
+ * Nothing here retrieves anything. #273 and #274 do that; this produces the graph and, just as importantly,
+ * proves it costs nothing when nobody asked for it.
+ *
+ * ## Three properties everything else rests on
+ *
+ * **Off costs nothing.** The extractor is optional in the dependencies and gated twice more at run time. A
+ * deployment that never enables GraphRAG supplies no extractor, makes no model calls, and writes no graph rows
+ * — measured by a test that counts calls rather than by reading this paragraph.
+ *
+ * **Determinism.** The same corpus produces byte-identical graphs twice. This is not tidiness: #275 measures
+ * GraphRAG against a fixed baseline, and a graph that shifts between runs cannot be measured, cannot be
+ * debugged, and cannot have its incremental rebuild (#272) verified. Every ordering here is explicit, and
+ * entity resolution is rule-based rather than similarity-based for exactly this reason — embedding similarity
+ * is not stable across model versions.
+ *
+ * **Provenance.** Every entity and edge records its chunks. The retriever will present graph-derived material
+ * as citable, so an untraceable claim is one the model states as though a document said it.
+ *
+ * ## What extraction is allowed to do to us
+ *
+ * Extraction is a model call, so it can return prose, malformed JSON, entities with no names, or an edge
+ * between two things it never mentioned. **None of that may corrupt the graph or fail the index.** A chunk
+ * whose extraction is unusable simply contributes nothing — it stays embedded and findable by every existing
+ * mode, and the graph is the only thing missing. `sanitiseExtraction` is where that judgement lives, and it is
+ * deliberately strict: an edge naming an entity that was not extracted is dropped rather than repaired,
+ * because repairing it would invent a provenance nobody asserted.
+ */
+/** Words dropped from the front of a name during normalisation. Articles only — see `normaliseName`. */
+const LEADING_ARTICLES = ["the", "a", "an"];
+/**
+ * A name reduced to what makes two spellings the same thing.
+ *
+ * Case, whitespace, separators and a leading article. That gets "the retry budget", "Retry Budget" and
+ * "retry-budget" to one entity, which is the merge AC-4 names.
+ *
+ * **What it deliberately does not do** is anything cleverer. Stemming would merge "billing" with "bill";
+ * embedding similarity would merge whatever the model of the week thinks is close and would stop being
+ * reproducible the moment that model changed. Both would make the graph unmeasurable, and the second would
+ * make it undebuggable too.
+ *
+ * Parenthetical qualifiers survive as words, so "Ana (engineering)" and "Ana (sales)" stay distinct — which
+ * AC-4 asks for, and which a punctuation-stripping rule gets right only by accident. It is worth being explicit
+ * that this is *why* punctuation becomes a space rather than nothing.
+ */
+export const normaliseName = (raw) => {
+    const collapsed = raw
+        .normalize("NFKD")
+        // Diacritics dropped so "Zurich" and "Zürich" meet. Same reasoning as case.
+        .replace(/[̀-ͯ]/g, "")
+        .toLowerCase()
+        // A separator becomes a space, never nothing: joining "retry" and "budget" into "retrybudget" would fail to
+        // match the spaced form, and dropping "(engineering)" entirely would merge two different people.
+        .replace(/[^\p{L}\p{N}]+/gu, " ")
+        .trim()
+        .replace(/\s+/g, " ");
+    const words = collapsed.split(" ").filter((word) => word !== "");
+    // Only when something follows it: "The" alone is a name, however unlikely, and stripping it leaves nothing.
+    if (words.length > 1 && LEADING_ARTICLES.includes(words[0])) {
+        return words.slice(1).join(" ");
+    }
+    return words.join(" ");
+};
+/** An entity type, normalised the same way but without the article rule — a type is one word in practice. */
+export const normaliseType = (raw) => raw
+    .toLowerCase()
+    .replace(/[^\p{L}\p{N}]+/gu, "-")
+    .replace(/^-+|-+$/g, "") || "unknown";
+/**
+ * The identity of an entity: its type and its normalised name.
+ *
+ * Readable rather than hashed, deliberately. `concept:retry budget` in a log, an error message or a database
+ * row tells whoever is reading it what went wrong; `sha256:9f2a…` tells them to go and write a script. The id
+ * is not a secret and its length is not a problem at this scale.
+ *
+ * Type participates because a person and a project can share a name and are not the same thing.
+ */
+export const entityId = (type, name) => `${normaliseType(type)}:${normaliseName(name)}`;
+/** The identity of an edge. Direction is part of it: "A depends on B" is not "B depends on A". */
+export const relationshipId = (fromId, type, toId) => `${fromId}|${normaliseType(type)}|${toId}`;
+const asText = (value) => (typeof value === "string" ? value.trim() : "");
+/**
+ * How long a description may be before it is a chunk rather than a description.
+ *
+ * A model asked for a short description sometimes returns the paragraph. Truncating rather than refusing keeps
+ * the entity — the name and the edges are the valuable part — and stops one verbose extraction from dominating
+ * the storage of a whole corpus.
+ */
+export const MAX_DESCRIPTION_CHARS = 480;
+const clamp = (text) => text.length <= MAX_DESCRIPTION_CHARS ? text : `${text.slice(0, MAX_DESCRIPTION_CHARS - 1).trimEnd()}…`;
+/**
+ * One chunk's raw extraction, turned into rows that can be trusted — or into nothing.
+ *
+ * Total: any input produces a valid contribution, possibly empty. That is what makes AC-7 hold everywhere at
+ * once rather than at each call site.
+ *
+ * The strict part is edges. An extractor routinely names an endpoint it did not extract — a pronoun it
+ * resolved, a thing it inferred — and the tempting fix is to create the missing entity. That invents an entity
+ * with a provenance nobody asserted, which is the exact failure provenance exists to prevent. So the edge is
+ * dropped, and the chunk keeps whatever else it gave us.
+ */
+export const sanitiseExtraction = (chunkId, raw) => {
+    const entities = new Map();
+    for (const candidate of Array.isArray(raw.entities) ? raw.entities : []) {
+        const name = asText(candidate?.name);
+        const type = asText(candidate?.type) || "concept";
+        if (name === "" || normaliseName(name) === "")
+            continue;
+        const id = entityId(type, name);
+        const description = clamp(asText(candidate?.description));
+        const existing = entities.get(id);
+        if (existing === undefined) {
+            entities.set(id, { name, type, ...(description === "" ? {} : { description }) });
+            continue;
+        }
+        // The same entity named twice in one chunk: keep the longer description, and the name that sorts first so
+        // the choice does not depend on extraction order.
+        const better = description.length > (existing.description ?? "").length ? description : existing.description;
+        entities.set(id, {
+            name: existing.name < name ? existing.name : name,
+            type: existing.type,
+            ...(better === undefined || better === "" ? {} : { description: better }),
+        });
+    }
+    const relationships = new Map();
+    for (const candidate of Array.isArray(raw.relationships) ? raw.relationships : []) {
+        const from = asText(candidate?.from);
+        const to = asText(candidate?.to);
+        const type = asText(candidate?.type) || "related-to";
+        if (from === "" || to === "")
+            continue;
+        // Endpoints are matched by *normalised name across any type*, because an extractor names an entity in a
+        // relationship without repeating its type and a type-qualified lookup would then miss every edge.
+        const fromId = [...entities.keys()].find((id) => id.slice(id.indexOf(":") + 1) === normaliseName(from));
+        const toId = [...entities.keys()].find((id) => id.slice(id.indexOf(":") + 1) === normaliseName(to));
+        if (fromId === undefined || toId === undefined)
+            continue; // See the note above: dropped, never invented.
+        if (fromId === toId)
+            continue; // A self-edge carries no information and clutters every traversal.
+        const description = clamp(asText(candidate?.description));
+        const id = relationshipId(fromId, type, toId);
+        const existing = relationships.get(id);
+        if (existing === undefined) {
+            relationships.set(id, { fromId, toId, type, ...(description === "" ? {} : { description }) });
+        }
+        else if (description.length > (existing.description ?? "").length) {
+            relationships.set(id, { ...existing, description });
+        }
+    }
+    return {
+        entities: [...entities.entries()]
+            .map(([id, entity]) => ({
+            id,
+            name: entity.name,
+            type: normaliseType(entity.type),
+            ...(entity.description === undefined ? {} : { description: entity.description }),
+            surfaceForms: [entity.name],
+            provenance: [chunkId],
+        }))
+            // Sorted here, not by the caller: determinism is a property of this function's output, so it cannot be
+            // forgotten at one of several call sites.
+            .sort((a, b) => (a.id < b.id ? -1 : a.id > b.id ? 1 : 0)),
+        relationships: [...relationships.entries()]
+            .map(([id, edge]) => ({
+            id,
+            fromId: edge.fromId,
+            toId: edge.toId,
+            type: normaliseType(edge.type),
+            ...(edge.description === undefined ? {} : { description: edge.description }),
+            weight: 1,
+            provenance: [chunkId],
+        }))
+            .sort((a, b) => (a.id < b.id ? -1 : a.id > b.id ? 1 : 0)),
+    };
+};
+const uniqueSorted = (values) => [...new Set(values)].sort();
+/**
+ * Many chunks' contributions, merged into one source's contribution.
+ *
+ * Where surface forms accumulate and edge weights are counted. The canonical `name` is the one that sorts
+ * first among everything merged — an arbitrary rule, chosen because it is *stable*: "first seen" would depend
+ * on chunk order, and chunk order is a thing that can change without the document changing.
+ */
+export const mergeContributions = (parts) => {
+    const entities = new Map();
+    for (const part of parts) {
+        for (const entity of part.entities) {
+            const existing = entities.get(entity.id);
+            if (existing === undefined) {
+                entities.set(entity.id, entity);
+                continue;
+            }
+            const description = (entity.description ?? "").length > (existing.description ?? "").length ? entity.description : existing.description;
+            entities.set(entity.id, {
+                id: entity.id,
+                name: existing.name < entity.name ? existing.name : entity.name,
+                type: existing.type,
+                ...(description === undefined ? {} : { description }),
+                surfaceForms: uniqueSorted([...existing.surfaceForms, ...entity.surfaceForms]),
+                provenance: uniqueSorted([...existing.provenance, ...entity.provenance]),
+            });
+        }
+    }
+    const relationships = new Map();
+    for (const part of parts) {
+        for (const edge of part.relationships) {
+            const existing = relationships.get(edge.id);
+            if (existing === undefined) {
+                relationships.set(edge.id, edge);
+                continue;
+            }
+            const description = (edge.description ?? "").length > (existing.description ?? "").length ? edge.description : existing.description;
+            const provenance = uniqueSorted([...existing.provenance, ...edge.provenance]);
+            relationships.set(edge.id, {
+                ...existing,
+                ...(description === undefined ? {} : { description }),
+                // Chunks that asserted it, not times it was seen — so re-reading one chunk cannot inflate a weight.
+                weight: provenance.length,
+                provenance,
+            });
+        }
+    }
+    // An edge whose endpoints did not survive the merge is dropped, for the same reason `sanitiseExtraction`
+    // drops one: the alternative is an edge pointing at nothing.
+    const kept = [...relationships.values()].filter((edge) => entities.has(edge.fromId) && entities.has(edge.toId));
+    return {
+        entities: [...entities.values()].sort((a, b) => (a.id < b.id ? -1 : a.id > b.id ? 1 : 0)),
+        relationships: kept.sort((a, b) => (a.id < b.id ? -1 : a.id > b.id ? 1 : 0)),
+    };
+};
+/**
+ * Extraction runs one chunk at a time by default.
+ *
+ * Sequential rather than parallel because the cost is the point: a corpus of 603 chunks is 603 model calls, and
+ * firing them concurrently is how a re-index becomes a rate-limit incident. A deployment that wants throughput
+ * raises this deliberately, having read the number.
+ */
+export const DEFAULT_EXTRACTION_CONCURRENCY = 1;
+export const createGraphIndexer = (deps) => {
+    const now = deps.now ?? (() => Date.now());
+    const log = deps.log ?? (() => { });
+    return {
+        extractorId: deps.extractor.id,
+        /**
+         * Whether this source would be graph-indexed — both switches, in the cheap order.
+         *
+         * The tenant switch first, so a deployment with GraphRAG off does one settings read and stops, rather than
+         * one read per source. AC-2's "flag is inert while the tenant switch is off" is this ordering: the source
+         * flag is never even consulted, and it stays stored for the day the tenant switch flips.
+         */
+        async shouldIndex(context, source) {
+            const settings = await deps.store.getSettings({ tenantId: context.tenantId });
+            if (!settings.enabled)
+                return false;
+            return deps.store.isSourceEnabled({ tenantId: context.tenantId, ...source });
+        },
+        /**
+         * Extract one source's chunks into the graph, replacing whatever that source contributed before.
+         *
+         * The caller has already decided this should run — `indexSource` calls `shouldIndex` first — so this does
+         * not re-check. Keeping the decision in one place is what makes "off costs nothing" a property of one
+         * function rather than a convention two functions share.
+         */
+        async indexSource(context, input) {
+            const started = now();
+            const concurrency = Math.max(1, input.concurrency ?? DEFAULT_EXTRACTION_CONCURRENCY);
+            const parts = [];
+            let extractionCalls = 0;
+            let inputTokens = 0;
+            let outputTokens = 0;
+            let unusableChunks = 0;
+            const runOne = async (chunk) => {
+                extractionCalls += 1;
+                try {
+                    const { extraction, usage } = await deps.extractor.extract(chunk);
+                    inputTokens += usage?.inputTokens ?? 0;
+                    outputTokens += usage?.outputTokens ?? 0;
+                    const contribution = sanitiseExtraction(chunk.id, extraction ?? {});
+                    if (contribution.entities.length === 0)
+                        unusableChunks += 1;
+                    return contribution;
+                }
+                catch (error) {
+                    /**
+                     * AC-7. A model call can fail or return prose, and neither may fail the index.
+                     *
+                     * Swallowed here rather than propagated because the chunk is *already embedded and findable* — every
+                     * existing retrieval mode works on it, and the graph is the only thing missing. Failing the index
+                     * would take the working part down with the optional one.
+                     */
+                    unusableChunks += 1;
+                    log("graph extraction failed for a chunk", {
+                        chunkId: chunk.id,
+                        reason: error instanceof Error ? error.message : String(error),
+                    });
+                    return { entities: [], relationships: [] };
+                }
+            };
+            for (let offset = 0; offset < input.chunks.length; offset += concurrency) {
+                const window = input.chunks.slice(offset, offset + concurrency);
+                // Order-independent by construction — `mergeContributions` sorts — but collected in order anyway, so a
+                // log read alongside the corpus makes sense.
+                parts.push(...(await Promise.all(window.map(runOne))));
+            }
+            const contribution = mergeContributions(parts);
+            const written = await deps.store.replaceSourceGraph({
+                tenantId: context.tenantId,
+                sourceType: input.sourceType,
+                sourceId: input.sourceId,
+                contribution,
+            });
+            const result = {
+                ran: true,
+                entities: written.entities,
+                relationships: written.relationships,
+                pruned: written.pruned,
+                extractionCalls,
+                inputTokens,
+                outputTokens,
+                unusableChunks,
+                elapsedMs: now() - started,
+            };
+            if (unusableChunks > 0)
+                log("some chunks contributed nothing to the graph", {
+                    sourceId: input.sourceId,
+                    unusableChunks,
+                    of: input.chunks.length,
+                });
+            return result;
+        },
+    };
+};
+/** What `indexSource` reports when the graph was not touched. Every counter zero, and `ran` says why. */
+export const GRAPH_NOT_RUN = {
+    ran: false,
+    entities: 0,
+    relationships: 0,
+    pruned: 0,
+    extractionCalls: 0,
+    inputTokens: 0,
+    outputTokens: 0,
+    unusableChunks: 0,
+    elapsedMs: 0,
+};
+/**
+ * The default `EntityExtractor`: one model call per chunk — AC-2.
+ *
+ * Thin on purpose. The provider call lives in `models/extraction.ts` behind boundary rule R3, so this is the
+ * adapter between that function and the port — which means a deployment can replace the extractor entirely
+ * (a smaller model, a local one, a rules-based one for a known corpus) without touching the pipeline.
+ *
+ * `model` is a factory rather than a value because a `LanguageModel` is resolved from a policy per tenant, and
+ * a single resolved model captured at construction would be the same one for every tenant in the deployment.
+ */
+export const createModelEntityExtractor = (deps) => ({
+    id: deps.id ?? "model",
+    async extract(chunk) {
+        const { extraction, usage } = await deps.extract(chunk.content);
+        return { extraction, usage };
+    },
+});
+//# sourceMappingURL=graph.js.map

package/dist/knowledge/index.d.ts

@@ -16,6 +16,7 @@ import type { TenantId } from "../core/ids.js";
 import type { DocumentBlock } from "../documents/index.js";
 import type { EmbeddingModelRef, KnowledgeSourceType, KnowledgeStore } from "../persistence/index.js";
 import { type ChunkingLimits } from "./chunking.js";
+import { type GraphIndexResult, type GraphIndexer } from "./graph.js";
 /**
  * How long newly added material may take to become findable — AC-4.
  *
@@ -59,6 +60,14 @@ export type IndexResult = {
     /** Wall-clock, so the freshness target can be measured rather than assumed. */
     readonly elapsedMs: number;
     readonly model: EmbeddingModelRef;
+    /**
+     * What the graph cost, when GraphRAG ran — REQ-064 (#270), task #271.
+     *
+     * Always present, never optional, and `ran: false` with every counter zero when it did not. An optional field
+     * would let a caller read "no graph work" and "GraphRAG is off" as the same thing, and they are not: the
+     * first is a source with nothing extractable, the second is a deployment that never asked.
+     */
+    readonly graph: GraphIndexResult;
 };
 export type EmbeddingPipelineDeps = {
     readonly knowledge: KnowledgeStore;
@@ -69,6 +78,17 @@ export type EmbeddingPipelineDeps = {
     /** Injectable so a test measures elapsed time without waiting for it. */
     readonly now?: () => number;
     readonly log?: (message: string, detail?: Readonly<Record<string, unknown>>) => void;
+    /**
+     * The graph indexer — REQ-064 (#270). **Absent means GraphRAG cannot run at all.**
+     *
+     * Optional at the type level rather than switched at run time, so a deployment that never enables it supplies
+     * no `EntityExtractor` and therefore configures no language model to index a document. That is the outermost
+     * of the three gates behind AC-4's "off costs nothing": absent here, off for the tenant, unflagged for the
+     * source. The first is free, and the second costs one settings read.
+     */
+    readonly graph?: GraphIndexer;
+    /** Chunks extracted concurrently. See `DEFAULT_EXTRACTION_CONCURRENCY` — the default is 1, deliberately. */
+    readonly graphConcurrency?: number;
 };
 /** Deterministic chunk id, so re-indexing the same source overwrites its own rows rather than duplicating. */
 export declare const chunkId: (sourceType: string, sourceId: string, index: number) => string;
@@ -117,4 +137,8 @@ export type EmbeddingPipeline = ReturnType<typeof createEmbeddingPipeline>;
 export * from "./chunking.js";
 export * from "./retrieval.js";
 export * from "./navigate.js";
+export * from "./graph.js";
+export * from "./graph-retrieval.js";
+export * from "./communities.js";
+export * from "./graph-global.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/knowledge/index.js

@@ -14,6 +14,7 @@
  */
 import { AgentPlatformError } from "../core/errors.js";
 import { DEFAULT_CHUNKING_LIMITS, chunkDocument } from "./chunking.js";
+import { GRAPH_NOT_RUN } from "./graph.js";
 /**
  * How long newly added material may take to become findable — AC-4.
  *
@@ -54,12 +55,24 @@ export const createEmbeddingPipeline = (deps) => {
                     sourceType: input.sourceType,
                     sourceId: input.sourceId,
                 });
+                // The graph goes with the content. A document extracted down to nothing must not leave entities
+                // asserting what it used to say — the same reasoning as removing its chunks.
+                let graph = GRAPH_NOT_RUN;
+                if (deps.graph !== undefined && (await deps.graph.shouldIndex(context, input))) {
+                    const pruned = await deps.graph.indexSource(context, {
+                        sourceType: input.sourceType,
+                        sourceId: input.sourceId,
+                        chunks: [],
+                    });
+                    graph = pruned;
+                }
                 return {
                     written: 0,
                     removed: cleared.removed,
                     batches: 0,
                     elapsedMs: now() - started,
                     model: deps.embeddings.model,
+                    graph,
                 };
             }
             const embedded = [];
@@ -98,6 +111,24 @@ export const createEmbeddingPipeline = (deps) => {
                 sourceId: input.sourceId,
                 chunks: embedded,
             });
+            /**
+             * The graph, after the chunks are written and only if asked — AC-1, AC-4.
+             *
+             * After, because the graph's provenance is chunk ids: writing edges that point at chunks which then fail
+             * to persist would leave the graph asserting sources that are not there.
+             *
+             * `shouldIndex` is one settings read when GraphRAG is off for the tenant, and zero model calls. When
+             * `deps.graph` is absent it is not even that.
+             */
+            let graph = GRAPH_NOT_RUN;
+            if (deps.graph !== undefined && (await deps.graph.shouldIndex(context, input))) {
+                graph = await deps.graph.indexSource(context, {
+                    sourceType: input.sourceType,
+                    sourceId: input.sourceId,
+                    chunks: embedded.map((chunk) => ({ id: chunk.id, content: chunk.content })),
+                    ...(deps.graphConcurrency === undefined ? {} : { concurrency: deps.graphConcurrency }),
+                });
+            }
             const elapsedMs = now() - started;
             if (elapsedMs > FRESHNESS_TARGET_MS)
                 // Reported rather than thrown: the material *is* indexed, and the useful action is to know the target
@@ -107,7 +138,7 @@ export const createEmbeddingPipeline = (deps) => {
                     elapsedMs,
                     targetMs: FRESHNESS_TARGET_MS,
                 });
-            return { ...written, batches, elapsedMs, model: deps.embeddings.model };
+            return { ...written, batches, elapsedMs, model: deps.embeddings.model, graph };
         },
         /**
          * One page of a re-index — AC-5.
@@ -164,4 +195,8 @@ export const createEmbeddingPipeline = (deps) => {
 export * from "./chunking.js";
 export * from "./retrieval.js";
 export * from "./navigate.js";
+export * from "./graph.js";
+export * from "./graph-retrieval.js";
+export * from "./communities.js";
+export * from "./graph-global.js";
 //# sourceMappingURL=index.js.map

package/dist/knowledge/retrieval.d.ts

@@ -41,6 +41,8 @@ import type { TenantId } from "../core/ids.js";
 import type { KeywordIndex, KnowledgeChunk, KnowledgeSourceType, VectorIndex } from "../persistence/index.js";
 import type { EmbeddingProvider } from "./index.js";
 import type { Navigator } from "./navigate.js";
+import type { GraphLocalSearch } from "./graph-retrieval.js";
+import type { GraphGlobalSearch } from "./graph-global.js";
 /** The rank-fusion constant. See the note above on why 60 and why rank rather than score. */
 export declare const RRF_K = 60;
 /** How many candidates each signal contributes before fusion. */
@@ -64,7 +66,14 @@ export declare const DEFAULT_RELEVANCE_FLOOR = 0.4;
  *
  * See `navigate.ts` for what it is and `docs/26-retrieval-quality.md` for what it scored.
  */
-export type RetrievalMode = "semantic" | "keyword" | "hybrid" | "navigate";
+/**
+ * `graph-local` joins the union in REQ-064 (#270), task #273.
+ *
+ * A closed union read in several places, so a new member is threaded rather than cast past — the same
+ * discipline #219 applied when it added `not-configured`. Like `navigate`, it is *delegated whole*: it shares
+ * no step with the fusion path, because it answers a different kind of question.
+ */
+export type RetrievalMode = "semantic" | "keyword" | "hybrid" | "navigate" | "graph-local" | "graph-global";
 /** What a citation needs, derived from a hit so there is one shape rather than each caller's own (AC-6). */
 export type SourceReference = {
     readonly sourceType: KnowledgeSourceType;
@@ -149,6 +158,22 @@ export type RetrieverDeps = {
      * mechanism, which is the only way this spike could have done harm.
      */
     readonly navigator?: Navigator;
+    /**
+     * Serves `mode: "graph-local"` — REQ-064 (#270), task #273.
+     *
+     * Optional for the same reason `navigator` is, and its absence is the same named refusal. GraphRAG is opt-in
+     * and expensive to index, so a deployment that never enabled it supplies nothing here and asking for the
+     * mode says so rather than quietly returning embeddings.
+     */
+    readonly graphLocal?: GraphLocalSearch;
+    /**
+     * Serves `mode: "graph-global"` — REQ-064 (#270), task #274.
+     *
+     * Separate from `graphLocal` rather than one graph dependency, because they are independently useful: a
+     * deployment can run entity-centric retrieval without paying for community summaries at all, and #273 landed
+     * before #272 for exactly that reason.
+     */
+    readonly graphGlobal?: GraphGlobalSearch;
 };
 export type RetrieveInput = {
     readonly query: string;

package/dist/knowledge/retrieval.js

@@ -63,11 +63,17 @@ export const NO_RESULT_REASONS = [
     "below-threshold",
     "no-access",
     /**
-     * The mode asked for is not wired — task #219.
+     * The mode asked for is not wired.
      *
      * Its own reason rather than `no-match`, because the two want opposite responses: one says rephrase, this says
      * a deployment has not configured what you asked for. Falling back to another mode silently would be worse
      * than either, since the caller would attribute the results to the mode it named.
+     *
+     * **Live, not a placeholder** — audited for #256 AC-8. Three code paths return it (`navigate` with no
+     * navigator, `graph-local` and `graph-global` with no GraphRAG), and three test files assert it. The optional
+     * modes are exactly why it has to exist: GraphRAG ships **off by default** on the measured evidence in
+     * `docs/29`, so "you asked for a mode this deployment did not switch on" is an ordinary answer rather than an
+     * edge case. The comment previously cited task #219 as if it were pending; it closed.
      */
     "not-configured",
 ];
@@ -119,6 +125,76 @@ export const createRetriever = (deps) => {
         rerankerId: deps.reranker?.id ?? null,
         async retrieve(context, input) {
             const mode = input.mode ?? "hybrid";
+            /**
+             * The graph mode, delegated whole — task #273.
+             *
+             * Before the `authSubjects` check below only because it does its own: an empty subject list means the
+             * same thing here, and the graph search returns an empty result for it rather than traversing first and
+             * filtering after. Placed with `navigate` because both are delegated modes rather than fusion inputs.
+             */
+            if (mode === "graph-local") {
+                if (deps.graphLocal === undefined)
+                    return { found: false, reason: "not-configured", message: NO_RESULT_MESSAGES["not-configured"], mode };
+                if (input.authSubjects.length === 0)
+                    return { found: false, reason: "no-access", message: NO_RESULT_MESSAGES["no-access"], mode };
+                const result = await deps.graphLocal.search(context, {
+                    query: input.query,
+                    authSubjects: input.authSubjects,
+                    limit: input.limit,
+                    ...(input.sourceTypes === undefined ? {} : { sourceTypes: input.sourceTypes }),
+                });
+                if (result.hits.length === 0)
+                    /**
+                     * An honest empty result, and the reason distinguishes the two ways it happens.
+                     *
+                     * Nothing in the question named an entity the graph knows is `no-match` — rephrasing might work.
+                     * Entities matched but reached no readable chunk is also `no-match` rather than `no-access`, because
+                     * the principal may genuinely have access to a corpus that simply says nothing more.
+                     */
+                    return { found: false, reason: "no-match", message: NO_RESULT_MESSAGES["no-match"], mode };
+                return {
+                    found: true,
+                    mode,
+                    hits: result.hits.map((hit) => ({
+                        chunk: hit.chunk,
+                        score: hit.score,
+                        signals: ["graph-local"],
+                        reference: referenceFor(hit.chunk),
+                    })),
+                };
+            }
+            /**
+             * The corpus-level mode — task #274.
+             *
+             * Its cost ceiling **throws** rather than returning an outcome, and that is deliberate: exceeding it is
+             * not "found nothing", it is "this question is too expensive to answer this way", and the two want
+             * different responses. `RetrievalOutcome`'s `found: false` reasons are all about the corpus; this is
+             * about the request.
+             */
+            if (mode === "graph-global") {
+                if (deps.graphGlobal === undefined)
+                    return { found: false, reason: "not-configured", message: NO_RESULT_MESSAGES["not-configured"], mode };
+                if (input.authSubjects.length === 0)
+                    return { found: false, reason: "no-access", message: NO_RESULT_MESSAGES["no-access"], mode };
+                const result = await deps.graphGlobal.search(context, {
+                    query: input.query,
+                    authSubjects: input.authSubjects,
+                    limit: input.limit,
+                    ...(input.sourceTypes === undefined ? {} : { sourceTypes: input.sourceTypes }),
+                });
+                if (result.hits.length === 0)
+                    return { found: false, reason: "no-match", message: NO_RESULT_MESSAGES["no-match"], mode };
+                return {
+                    found: true,
+                    mode,
+                    hits: result.hits.map((hit) => ({
+                        chunk: hit.chunk,
+                        score: hit.score,
+                        signals: ["graph-global"],
+                        reference: referenceFor(hit.chunk),
+                    })),
+                };
+            }
             // The spike's mode, delegated whole: it shares no step with the fusion path below.
             if (mode === "navigate") {
                 if (deps.navigator === undefined)