@retinue/agentkit 0.1.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;
@@ -116,4 +136,9 @@ export declare const createEmbeddingPipeline: (deps: EmbeddingPipelineDeps) => {
 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.
@@ -163,4 +194,9 @@ 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/navigate.d.ts

@@ -0,0 +1,89 @@
+/**
+ * Retrieval without vectors — REQ-050 (#209), task #219, AC-4.
+ *
+ * A **spike**, and the deliverable is a decision with numbers rather than a subsystem. See
+ * `docs/26-retrieval-quality.md` for what it scored.
+ *
+ * ## The idea being tested
+ *
+ * Embedding-based retrieval matches a query against fragments of text and hopes the fragments it surfaces are the
+ * ones that answer it. A person looking something up in a manual does something else entirely: they read the
+ * table of contents, decide which chapter is relevant, and then read it. That needs no index, no embedding cost
+ * and no re-indexing when a document changes — and its citations name a *document* somebody chose rather than a
+ * fragment a cosine distance surfaced.
+ *
+ * The cost is a model call per query, and latency measured in seconds rather than milliseconds.
+ *
+ * ## Two things this prototype found immediately
+ *
+ * **`KnowledgeStore` cannot enumerate its sources.** There is `listBySource`, `get`, `deleteSource` and
+ * `staleSources`, and no way to ask "what documents are in here". That is correct for a vector-based design —
+ * nothing needed it — and it is exactly what a navigating retriever needs first. So the outline arrives through
+ * a port the *host* supplies (`OutlineCatalogue`), which is honest but means this mode is not a drop-in for a
+ * deployment that already has hybrid retrieval working.
+ *
+ * **It does fit behind `RetrievalMode`**, which the issue asked to test. `createRetriever` gains one optional
+ * dependency and a fourth mode; every caller — `search_knowledge` included — is unchanged, and a deployment that
+ * has not wired a navigator gets a named refusal rather than a silent fall back to semantic search. If it had
+ * *not* fit, that would have been the finding; it fits.
+ */
+import type { ExecutionContext } from "../core/context.js";
+import type { KnowledgeChunk, KnowledgeStore } from "../persistence/index.js";
+import type { RetrievalOutcome } from "./retrieval.js";
+/** What a chooser sees of one document: enough to decide, and not the document itself. */
+export type SourceOutline = {
+    readonly sourceType: KnowledgeChunk["sourceType"];
+    readonly sourceId: string;
+    readonly title: string;
+    /** The heading trail, in document order. This is the table of contents a person would read. */
+    readonly headings: readonly string[];
+};
+/**
+ * Where the outline comes from.
+ *
+ * A port because the store cannot answer it (see the note above). A host that keeps documents in its own tables —
+ * which most do, since `KnowledgeStore` holds *chunks* — already has this list.
+ */
+export interface OutlineCatalogue {
+    list(context: {
+        readonly tenantId: ExecutionContext["tenantId"];
+        readonly authSubjects: readonly string[];
+    }): Promise<readonly SourceOutline[]>;
+}
+/**
+ * Whatever decides which documents to read. A model, in practice.
+ *
+ * A port rather than a model call, for the reason every model call in this package is a port: the platform must
+ * not acquire a provider, and a test must be able to pin the choice.
+ */
+export interface DocumentChooser {
+    readonly id: string;
+    choose(input: {
+        readonly query: string;
+        readonly catalogue: readonly SourceOutline[];
+        readonly limit: number;
+    }): Promise<readonly string[]>;
+}
+export type NavigatorDeps = {
+    readonly store: KnowledgeStore;
+    readonly catalogue: OutlineCatalogue;
+    readonly chooser: DocumentChooser;
+    /** Documents the chooser may pick. More than a handful and the model is guessing rather than choosing. */
+    readonly maxSources?: number;
+    /** Chunks read per chosen document. A whole 200-page document would not fit the caller's context. */
+    readonly maxChunksPerSource?: number;
+};
+export declare const DEFAULT_MAX_SOURCES = 3;
+export declare const DEFAULT_MAX_CHUNKS_PER_SOURCE = 40;
+export interface Navigator {
+    readonly id: string;
+    navigate(context: {
+        readonly tenantId: ExecutionContext["tenantId"];
+    }, input: {
+        readonly query: string;
+        readonly authSubjects: readonly string[];
+        readonly limit: number;
+    }): Promise<RetrievalOutcome>;
+}
+export declare const createNavigator: (deps: NavigatorDeps) => Navigator;
+//# sourceMappingURL=navigate.d.ts.map