@hawkeyexl/manni 4.0.3 → 4.2.0

package/dist/graph/runtime.d.ts

@@ -0,0 +1,751 @@
+/**
+ * Graph derivation: DocModel[] → deduplicated Quad[]. This file is the
+ * vocabulary mapping — the deterministic rules for what documentation
+ * structure becomes which triples.
+ */
+
+type Term = {
+    kind: "iri";
+    value: string;
+} | {
+    kind: "literal";
+    value: string;
+    datatype?: string;
+};
+interface Quad {
+    s: string;
+    p: string;
+    o: Term;
+}
+
+/**
+ * `GraphIndex` — the browser-native in-memory graph (ADR 01018).
+ *
+ * Built from `graph.jsonld` (the Phase 6 export) with **no RDF parser**: that
+ * artifact is plain `JSON.parse`-able, deterministically sorted, and free of
+ * blank nodes, so a `Map`-based adjacency index is all the runtime needs. Node
+ * callers can also build from quads (`fromQuads`) so the CLI can read Turtle.
+ *
+ * Platform-neutral: no `node:` imports, no npm dependencies, no I/O — the
+ * caller supplies the bytes. Type-only imports are erased at build time.
+ *
+ * Every accessor returns deterministically sorted results, so traversal order
+ * (and therefore the trace) is byte-stable for a given graph.
+ */
+
+/** An object value: an IRI reference or a literal. */
+type Value = {
+    kind: "iri";
+    value: string;
+} | {
+    kind: "literal";
+    value: string;
+    datatype?: string;
+};
+interface GraphNode {
+    id: string;
+    /** Full class IRIs, sorted. */
+    types: string[];
+    /** Full predicate IRI → values, in insertion-normalized sorted order. */
+    props: Map<string, Value[]>;
+}
+declare class GraphIndex {
+    private readonly nodes;
+    /** subject → predicate → object IRIs (sorted). */
+    private readonly outbound;
+    /** object → predicate → subject IRIs (sorted). */
+    private readonly inbound;
+    /** class IRI → instance IRIs (sorted). */
+    private readonly byType;
+    /** prefix → namespace, from the artifact's own `@context`. */
+    readonly context: Record<string, string>;
+    private constructor();
+    /**
+     * Build from a `graph.jsonld` document — a JSON string or the parsed object.
+     * CURIE keys and `@type` values are expanded using the document's own
+     * `@context`, so the index is self-describing.
+     */
+    static fromJsonLd(input: string | object): GraphIndex;
+    /** Build from dockg's internal quad shape (the Node/CLI path). */
+    static fromQuads(quads: Quad[], context?: Record<string, string>): GraphIndex;
+    /** Expand a CURIE (`dcterms:title`) to a full IRI using `@context`. */
+    expand(term: string): string;
+    /** Compact a full IRI to a CURIE when a context namespace matches. */
+    compact(iri: string): string;
+    private addJsonLdNode;
+    private toValue;
+    private ensureNode;
+    private addTriple;
+    /** Sort every collection so traversal order is deterministic. */
+    private finalize;
+    /** Every node IRI, sorted. */
+    ids(): string[];
+    size(): number;
+    node(iri: string): GraphNode | undefined;
+    has(iri: string): boolean;
+    /** Class IRIs of a node, sorted. */
+    types(iri: string): string[];
+    /** Instances of a class, sorted. */
+    instancesOf(classIri: string): string[];
+    /** All values for a predicate, sorted. */
+    values(iri: string, predicate: string): Value[];
+    /** Literal lexical forms for a predicate, sorted. */
+    literals(iri: string, predicate: string): string[];
+    /** The first literal for a predicate, if any. */
+    literal(iri: string, predicate: string): string | undefined;
+    /** Outbound IRI targets: all predicates, or one. Sorted. */
+    out(iri: string, predicate?: string): Array<{
+        predicate: string;
+        target: string;
+    }>;
+    /** Inbound IRI sources (who points at this node). Sorted. */
+    in(iri: string, predicate?: string): Array<{
+        predicate: string;
+        target: string;
+    }>;
+}
+
+/**
+ * Query trace — the explainability contract (ADR 01018). Every runtime stage
+ * appends to a trace, and no API returns results without one: retrieval
+ * provenance is part of the contract exactly as PROV provenance is part of the
+ * build. The trace answers "how and why did this result come back": which nodes
+ * were seeded, every hop walked, every node scope excluded (and by which rule),
+ * and every content resolution attempted.
+ *
+ * Events are appended in traversal order, which is itself deterministic, so the
+ * trace is byte-stable for a given graph + query.
+ */
+/** How a seed was found. `hybrid` means several legs agreed on it. */
+type EntryVia = "explicit" | "lexical" | "vector" | "hybrid";
+/** A starting node, with the score/reason that made it a seed. */
+interface EntryCandidate {
+    iri: string;
+    /**
+     * Relevance score: 1 for an explicitly requested seed, otherwise the fused
+     * `rrfMerge` score. Note that fusion is **rank**-based, so a searched seed's
+     * score reflects its position (1/(60 + rank)), not the engine's relevance —
+     * it orders candidates but is not a magnitude to threshold on.
+     */
+    score: number;
+    via: EntryVia;
+}
+/** One edge walked, in either direction. */
+interface Hop {
+    from: string;
+    predicate: string;
+    to: string;
+    /** Hops from the nearest seed (seeds are depth 0; their neighbors are 1). */
+    depth: number;
+    direction: "out" | "in";
+}
+/** A node the scope filter removed, and why. */
+interface ScopeExclusion {
+    node: string;
+    /**
+     * The predicate that disqualified the node: a `graph:not*` IRI when an
+     * explicit negative named the target, or the positive predicate (e.g.
+     * `iirds:relates-to-product-variant`) when the node declared a scope set that
+     * omits the target.
+     */
+    rule: string;
+    /**
+     * The filter target being applied — the variant or subject IRI the query
+     * asked for. Under a `graph:not*` rule the node named this explicitly; under
+     * a positive rule this is what the node's declared set was missing.
+     */
+    value: string;
+}
+/** One content-resolution attempt. */
+interface Resolution {
+    iri: string;
+    sourceUrl: string;
+    ok: boolean;
+    /** Present when `ok` is false. */
+    error?: string;
+}
+interface QueryTrace {
+    entry: EntryCandidate[];
+    hops: Hop[];
+    exclusions: ScopeExclusion[];
+    resolutions: Resolution[];
+}
+declare function createTrace(): QueryTrace;
+/**
+ * Every node named anywhere in the trace as reached — seeds plus hop targets.
+ * The trace-completeness contract: a traversal's results must be a subset of
+ * this, so every returned node is explainable by recorded events.
+ */
+declare function reachedNodes(trace: QueryTrace): Set<string>;
+
+type Direction = "out" | "in" | "both";
+interface ScopeFilter {
+    /** Product variant: an IRI, a `dcterms:title` (e.g. "SP-X100"), or a slug. */
+    variant?: string;
+    /** Software subject: an IRI or a `graph.about-product-aspect` value (e.g. "architecture"). */
+    subject?: string;
+    /**
+     * BCP-47 tag (ADR 01037). Matched against `dcterms:language` after both are
+     * canonicalized, since tags are case-insensitive. There is no fallback:
+     * `de-AT` is not `de`, because relatedness between locales is an inference
+     * and this runtime does not infer.
+     */
+    language?: string;
+}
+interface TraverseOptions extends ScopeFilter {
+    /** Starting nodes (IRIs). */
+    seeds: string[];
+    /** Maximum hops from a seed. Default 1. */
+    depth?: number;
+    /** Restrict to these predicates (full IRIs). Default: every predicate. */
+    predicates?: string[];
+    /** Which edge directions to follow. Default "out". */
+    direction?: Direction;
+    /** Stop after this many nodes (seeds included). */
+    limit?: number;
+    /**
+     * Follow `rdf:type` edges into class nodes. Default false, deliberately:
+     * class nodes are schema, not content, and every document shares them — so
+     * traversing them makes every document reachable from every other in two
+     * hops (`a → graph:Document → b`). That is exactly the edge contamination
+     * graph-governed retrieval exists to avoid. A `predicates` list that names
+     * `rdf:type` follows them too, because it asked for them by name.
+     */
+    includeTypeEdges?: boolean;
+    /** Append to an existing trace instead of starting a new one. */
+    trace?: QueryTrace;
+}
+interface TraversedNode {
+    iri: string;
+    /** Hops from the nearest seed; seeds are 0. */
+    depth: number;
+}
+interface TraverseResult {
+    nodes: TraversedNode[];
+    trace: QueryTrace;
+}
+/**
+ * Resolve a variant input to its IRI: an exact node IRI, a `dcterms:title`
+ * match on an `iirds:ProductVariant`, or a trailing-segment slug match.
+ */
+declare function resolveVariant(graph: GraphIndex, input: string): string | undefined;
+/** Resolve a software-subject input to its iiRDS IRI. */
+declare function resolveSubject(graph: GraphIndex, input: string): string | undefined;
+/**
+ * Decide whether a node survives the scope filter, and if not, why.
+ *
+ * Rules, in the spirit of ADR 01014 (absence of a positive claim is not a
+ * negative claim, so both polarities are explicit):
+ * - An explicit negative (`graph:notApplicableToVariant` /
+ *   `graph:notSoftwareSubject`) naming the target **excludes** the node.
+ * - A node that declares a positive set which omits the target is **excluded**
+ *   — it scoped itself elsewhere — recorded under the positive predicate so
+ *   the trace distinguishes this from an explicit negative.
+ * - A node that makes no claim is **kept**: unscoped content applies broadly.
+ */
+declare function scopeExclusion(graph: GraphIndex, iri: string, scope: {
+    variantIri?: string;
+    subjectIri?: string;
+    language?: string;
+}): ScopeExclusion | undefined;
+/** Breadth-first traversal with scope filtering and full trace recording. */
+declare function traverse(graph: GraphIndex, options: TraverseOptions): TraverseResult;
+/** Who links to this node (one hop inbound over `dcterms:references`). */
+declare function reverseReferences(graph: GraphIndex, iri: string, options?: Omit<TraverseOptions, "seeds" | "direction" | "predicates">): TraverseResult;
+/**
+ * Transitive inbound reach — "what is affected if this node changes".
+ * Excludes the node itself from the returned set. Defaults to depth 3 rather
+ * than the walker's 1, because impact analysis is only useful transitively.
+ */
+declare function impact(graph: GraphIndex, iri: string, options?: Omit<TraverseOptions, "seeds" | "direction">): TraverseResult;
+
+interface ResolvedContent {
+    iri: string;
+    text: string;
+    sourceUrl: string;
+    title?: string;
+}
+interface ContentResolver {
+    /** Text for a node, or undefined when the node has no content. */
+    resolve(iri: string): Promise<ResolvedContent | undefined>;
+}
+type FetchLike = (url: string) => Promise<{
+    ok: boolean;
+    status: number;
+    text(): Promise<string>;
+}>;
+interface FetchResolverOptions {
+    /** Prefix joined to each `graph:path`, e.g. "https://site/raw/". */
+    baseUrl?: string;
+    /** Full control over path → URL. Overrides `baseUrl`. */
+    pathToUrl?: (path: string) => string;
+    /** Injectable fetch (defaults to the global). */
+    fetch?: FetchLike;
+    /** Record resolutions here. */
+    trace?: QueryTrace;
+}
+/** Split a section IRI into its document IRI and fragment. */
+declare function splitFragment(iri: string): {
+    doc: string;
+    fragment?: string;
+};
+/**
+ * Sections of a document in true document order, reconstructed from the
+ * `dcterms:hasPart` tree ordered by `graph:order` within each parent.
+ *
+ * Needed because heading text is not unique: a document with two `## Install`
+ * headings produces two section nodes, and matching by title alone would give
+ * both the *first* heading's text — wrong content under a confident citation.
+ */
+declare function documentSectionOrder(graph: GraphIndex, docIri: string): string[];
+/**
+ * Occurrence number of every section of a document, in one walk: section IRI →
+ * how many earlier sections share its heading text and level.
+ *
+ * Batched because the per-section form is quadratic — a document with N
+ * sections would otherwise rebuild the whole `hasPart` order N times, once per
+ * section indexed or resolved.
+ */
+declare function sectionOccurrences(graph: GraphIndex, docIri: string): Map<string, number>;
+/**
+ * Which occurrence of its heading text a section is (0-based) — the number of
+ * earlier same-title, same-level sections in the same document. A section the
+ * `hasPart` tree does not reach counts as the first (0).
+ */
+declare function sectionOccurrence(graph: GraphIndex, sectionIri: string): number;
+/**
+ * The prose before a document's first heading — the text that belongs to no
+ * section, and so would otherwise be indexed nowhere in a document that has
+ * sections.
+ *
+ * Fence-aware for the same reason `sliceSection` is: a `#` comment inside a
+ * leading code block is not a heading, and treating it as one would cut the
+ * preamble short. Frontmatter is *not* stripped here — the caller decides,
+ * since only the search index cares about that.
+ */
+declare function documentPreamble(markdown: string): string | undefined;
+/**
+ * Slice a markdown document at the heading whose text matches `title`,
+ * returning that heading through to the next heading of the same or higher
+ * rank. Returns undefined when no such heading exists. Handles CRLF, and
+ * ignores `#` lines inside fenced code blocks.
+ *
+ * `occurrence` selects among repeated headings (0 = the first). Heading text is
+ * not unique, so callers with a specific section node in hand should pass
+ * `sectionOccurrence(graph, iri)` rather than defaulting to the first match.
+ */
+declare function sliceSection(markdown: string, title: string, level?: number, occurrence?: number): string | undefined;
+/**
+ * The text a section *owns*: its heading down to the next heading of **any**
+ * rank, so nested subsections are excluded.
+ *
+ * `sliceSection` keeps the subtree because that is what retrieval wants — ask
+ * for "Configuration" and you should get its subsections too. Indexing wants
+ * the opposite: with the subtree, a parent section matches everything its
+ * children match and outranks them, so an H1 section shadows every heading
+ * beneath it. Same granularity rule as Document vs Section, one level down.
+ */
+declare function sectionOwnText(markdown: string, title: string, level?: number, occurrence?: number): string | undefined;
+/**
+ * A resolver that fetches document sources over HTTP. Documents map through
+ * `graph:path`; sections slice their parent document by heading.
+ */
+declare function createFetchResolver(graph: GraphIndex, options?: FetchResolverOptions): ContentResolver;
+
+/**
+ * Context assembly (ADR 01018) — the runtime's terminal stage.
+ *
+ * Turns traversed nodes into the bundle an inference engine consumes:
+ * `{ context, citations, trace, refusal? }`. **dockg stops here**: it never
+ * calls a model. A different tool (an agent over MCP, a site backend) takes the
+ * bundle onward, which keeps this runtime fully deterministic and keeps API
+ * keys and inference cost outside dockg entirely.
+ *
+ * When nothing survives retrieval the result is a *structured refusal*, never
+ * empty context — a caller must be able to tell "no route exists" apart from
+ * "here is nothing, proceed anyway" (the disciplined-silence contract).
+ *
+ * Platform-neutral: no `node:` imports, no npm dependencies.
+ */
+
+interface ContextBlock {
+    iri: string;
+    title?: string;
+    text: string;
+    sourceUrl: string;
+    /** Hops from the nearest seed — the relevance signal, carried through. */
+    depth: number;
+}
+interface Citation {
+    iri: string;
+    title?: string;
+    sourceUrl: string;
+}
+type RefusalReason = "no-route" | "no-content";
+interface Refusal {
+    reason: RefusalReason;
+    detail: string;
+}
+/**
+ * The rankings that produced the seeds, carried through to the caller.
+ *
+ * Retrieval answers two different questions — "what matched the query?" and
+ * "what is the graph connected to it?" — and a consumer needs both. Returning
+ * only the graph result would make the match rankings inferrable solely from the
+ * trace, which is diagnostic rather than a result surface (ADR 01020).
+ */
+interface EntryRankings {
+    /** The lexical leg's own ranking. */
+    lexical: EntryCandidate[];
+    /** The vector leg's own ranking; empty when no embedder was in play. */
+    vector: EntryCandidate[];
+    /** The fused ranking that actually seeded traversal. */
+    merged: EntryCandidate[];
+}
+interface RetrievalBundle {
+    /** What matched the query, per leg. Absent when seeds were given explicitly. */
+    entry?: EntryRankings;
+    context: ContextBlock[];
+    citations: Citation[];
+    trace: QueryTrace;
+    /** Present when retrieval found nothing usable. `context` is then empty. */
+    refusal?: Refusal;
+    /** True when the character budget dropped otherwise-eligible blocks. */
+    truncated: boolean;
+}
+interface AssembleOptions {
+    /** Character budget across all blocks. Default: unbounded. */
+    maxChars?: number;
+    /** Append to an existing trace (normally the traversal's). */
+    trace?: QueryTrace;
+    /**
+     * The entry rankings that produced these nodes, passed through to the bundle
+     * so callers see matches and graph results side by side.
+     */
+    entry?: EntryRankings;
+}
+/**
+ * Resolve traversed nodes to text and assemble the retrieval bundle. Nodes are
+ * kept in traversal order (nearest-first), which is deterministic, and every
+ * block carries the IRI it came from so citations are structural, not inferred.
+ */
+declare function assemble(resolver: ContentResolver, nodes: TraversedNode[], options?: AssembleOptions): Promise<RetrievalBundle>;
+
+interface RdfTerm {
+    termType: "NamedNode" | "Literal" | "DefaultGraph";
+    value: string;
+    language?: string;
+    datatype?: RdfTerm;
+    equals(other?: RdfTerm | null): boolean;
+}
+interface RdfQuad {
+    termType: "Quad";
+    subject: RdfTerm;
+    predicate: RdfTerm;
+    object: RdfTerm;
+    graph: RdfTerm;
+    equals(other?: RdfQuad | null): boolean;
+}
+declare function namedNode(value: string): RdfTerm;
+declare function defaultGraph(): RdfTerm;
+declare function literal(value: string, datatype?: string): RdfTerm;
+/**
+ * The whole index as RDF/JS quads, in the index's deterministic order. Feed to
+ * any RDF/JS store (`new Store(rdfjsQuads(graph))`) to run SPARQL.
+ */
+declare function rdfjsQuads(graph: GraphIndex): RdfQuad[];
+/**
+ * Triple-pattern match returning RDF/JS quads. A null/undefined position is a
+ * wildcard. Convenience for callers who want RDF/JS terms without pulling in a
+ * store; the walker API is the richer (and traced) way to query.
+ */
+declare function matchQuads(graph: GraphIndex, subject?: string | null, predicate?: string | null, object?: string | null): RdfQuad[];
+
+/** One indexable node. Empty fields are omitted so the artifact stays tight. */
+interface SearchEntry {
+    /** Node IRI. */
+    id: string;
+    /** Compacted class IRI, e.g. `graph:Section`. */
+    type: string;
+    title?: string;
+    /** Space-joined alternative labels, deduped case-insensitively. */
+    labels?: string;
+    description?: string;
+    /** Body text, per the granularity rule. */
+    text?: string;
+}
+interface SearchIndexDoc {
+    version: 1;
+    entries: SearchEntry[];
+}
+
+interface LexicalSearchOptions {
+    /** Maximum candidates to return. Default 10. */
+    limit?: number;
+}
+interface LexicalIndex {
+    /** Ranked candidates, best first, ties broken by IRI. */
+    search(query: string, options?: LexicalSearchOptions): EntryCandidate[];
+    /** Indexed entry count. */
+    size(): number;
+    /** The entry behind an IRI, for callers that want its title/type. */
+    entry(iri: string): SearchEntry | undefined;
+}
+/**
+ * Build a lexical index from the search artifact — a JSON string or the parsed
+ * document.
+ */
+declare function createLexicalIndex(input: string | SearchIndexDoc): LexicalIndex;
+
+interface VectorIndexHeader {
+    /** Embedding model id, e.g. an HF repo path. */
+    model: string;
+    /** Model-weight quantization the vectors were produced under. */
+    dtype: string;
+    /** Vector dimensions. Never assumed — always read from here. */
+    dims: number;
+    /** Number of vectors; equals `ids.length`. */
+    count: number;
+    /** Node IRIs, sorted, in payload order. */
+    ids: string[];
+    /** Digest of the `search.<lang>.json` these were built from (staleness detection). */
+    source: string;
+    /**
+     * BCP-47 tag of the index these cover, or `und` (ADR 01038). Recorded so a
+     * host that fetched the wrong pair is refused rather than ranked against a
+     * model that never saw the language.
+     */
+    language: string;
+}
+interface VectorIndexDoc {
+    header: VectorIndexHeader;
+    /** `count * dims` floats, L2-normalized, row-major in `ids` order. */
+    vectors: Float32Array;
+}
+/** Thrown for malformed input so callers can map it to an exit code / refusal. */
+declare class VectorIndexError extends Error {
+    constructor(message: string);
+}
+/**
+ * L2-normalize a vector in place and return it. A zero vector is left alone —
+ * dividing by its norm would produce NaNs that silently poison every later dot
+ * product.
+ */
+declare function normalize(vector: Float32Array): Float32Array;
+/**
+ * Encode entries into the sidecar. Entries are sorted by IRI first, so the bytes
+ * depend on the set of entries and not on the order they were produced in.
+ */
+declare function encodeVectorIndex(entries: Array<{
+    id: string;
+    vector: Float32Array;
+}>, meta: {
+    model: string;
+    dtype: string;
+    source: string;
+    language: string;
+}): Uint8Array;
+/** Decode a sidecar, rejecting anything malformed rather than mis-reading it. */
+declare function decodeVectorIndex(bytes: Uint8Array): VectorIndexDoc;
+
+interface VectorSearchOptions {
+    /** Maximum candidates to return. Default 10. */
+    limit?: number;
+    /**
+     * Drop candidates scoring below this. Default 0 — every model has its own
+     * useful range, so dockg does not impose a threshold the user did not choose.
+     */
+    minScore?: number;
+}
+/** Why a vector index cannot be used with the embedder or corpus at hand. */
+interface VectorMismatch {
+    reason: "model" | "dtype" | "dims" | "stale-source";
+    detail: string;
+}
+/**
+ * Thrown when a query would be ranked against vectors it cannot be compared to.
+ *
+ * A distinct type so hosts can catch exactly this — and so it cannot be mistaken
+ * for "no results". Ranking on regardless is the silent-wrong-answer failure
+ * ADR 01020 exists to prevent, so this is loud by design.
+ */
+declare class VectorMismatchError extends Error {
+    readonly reason: VectorMismatch["reason"];
+    constructor(mismatch: VectorMismatch);
+}
+/**
+ * The digest `manni graph embed` records as a sidecar's `source`, computed the same
+ * way in a browser — SHA-256 over the **raw bytes of `search.json` exactly as
+ * fetched**, hex, prefixed `sha256:`.
+ *
+ * Exists so a host can pass `source` to `findEntry` and get the staleness half
+ * of the refusal (ADR 01020) without reconstructing the recipe. Re-serializing
+ * the parsed JSON would change the bytes and so the digest — pass the response
+ * text, not `JSON.stringify(doc)`.
+ *
+ * Uses Web Crypto, which is platform-neutral: browsers and Node 18+ both have
+ * it on `globalThis`.
+ */
+declare function searchIndexDigest(raw: string): Promise<string>;
+interface VectorIndex {
+    /**
+     * Rank nodes against a query vector. The vector is normalized here, so
+     * callers need not — an unnormalized query would otherwise scale every score.
+     */
+    search(query: Float32Array, options?: VectorSearchOptions): EntryCandidate[];
+    /**
+     * Check this index against the embedder and corpus in play. Returns the
+     * mismatch, or undefined when they agree. Ranking against vectors from a
+     * different model compares outputs of two different functions (ADR 01020), so
+     * callers should refuse rather than proceed.
+     */
+    check(expected: {
+        model?: string;
+        dtype?: string;
+        dims?: number;
+        source?: string;
+    }): VectorMismatch | undefined;
+    readonly model: string;
+    /**
+     * Weight quantization the corpus vectors were produced under. The query side
+     * must embed at the *same* dtype — q8 and fp32 weights are different
+     * functions, so mixing them compares incomparable vectors (ADR 01020).
+     */
+    readonly dtype: string;
+    readonly dims: number;
+    readonly source: string;
+    size(): number;
+    /** The IRI at a payload row, for callers walking the index directly. */
+    idAt(row: number): string | undefined;
+}
+/** Build a vector index from encoded sidecar bytes. */
+declare function createVectorIndex(bytes: Uint8Array): VectorIndex;
+
+/**
+ * Enough of an embedder to verify it against a vector index. Structural rather
+ * than the `Embedder` interface itself, so the runtime stays independent of
+ * `@hawkeyexl/manni/graph/embed` — any object with these three fields works.
+ */
+interface QueryEmbedder {
+    readonly model: string;
+    readonly dtype: string;
+    embed(text: string): Promise<Float32Array> | Float32Array;
+}
+interface FindEntryOptions {
+    /** The lexical index to query. */
+    lexical: LexicalIndex;
+    /** The vector index. Without it (and an embedder), entry is lexical-only. */
+    vectors?: VectorIndex;
+    /**
+     * The embedder for the query side. **Prefer this over `embedQuery`**: it
+     * carries the model and dtype, so `findEntry` can verify they match the
+     * vector index and refuse rather than rank against incomparable vectors.
+     */
+    embedder?: QueryEmbedder;
+    /**
+     * Embed the query with a bare function. An escape hatch for hosts wiring
+     * their own model — but it carries no identity, so **the model/dtype match
+     * cannot be verified**; only the dimension check inside `search` applies.
+     * Prefer `embedder`.
+     */
+    embedQuery?: (query: string) => Promise<Float32Array> | Float32Array;
+    /**
+     * Digest of the `search.json` this caller loaded, from `searchIndexDigest`.
+     * Supplied, a sidecar built from a *different* corpus is refused rather than
+     * ranked — its IRIs may no longer exist, and it misses everything added
+     * since. Omitted, that half of the check simply does not run: the runtime
+     * cannot derive the digest, since it never sees the raw bytes.
+     */
+    source?: string;
+    /** Maximum seeds to return. Default 10. */
+    limit?: number;
+    /** Append candidates here instead of starting a new trace. */
+    trace?: QueryTrace;
+}
+interface EntryResult {
+    /** The fused ranking — what seeds traversal. */
+    candidates: EntryCandidate[];
+    /** The lexical leg's own ranking. */
+    lexical: EntryCandidate[];
+    /** The vector leg's own ranking; empty when no embedder was supplied. */
+    vector: EntryCandidate[];
+    trace: QueryTrace;
+}
+/**
+ * Reciprocal rank fusion over N ranked lists: score = Σ 1/(k + rank).
+ *
+ * Rank-based rather than score-based on purpose — lexical BM25 scores and
+ * cosine similarities are not on a comparable scale, so fusing raw scores would
+ * let whichever leg happens to produce bigger numbers dominate. `k = 60` is the
+ * standard damping constant.
+ *
+ * Deterministic: input list order does not affect the result, and ties break by
+ * IRI.
+ */
+declare function rrfMerge(rankings: EntryCandidate[][], k?: number): EntryCandidate[];
+/**
+ * Find seed nodes for a question, returning each ranking leg and their fusion.
+ *
+ * Async because embedding a query is: local models are a WASM forward pass.
+ * Uniformly async rather than sync-when-lexical-only, so callers have one
+ * contract to hold rather than a return type that changes with the options.
+ *
+ * The vector leg runs only when both a `vectors` index and an `embedQuery` are
+ * supplied. Absent either, this is lexical entry exactly as Phase 8 shipped it —
+ * additive, never a new failure mode (ADR 01009's degrade-don't-fail rule).
+ */
+declare function findEntry(query: string, options: FindEntryOptions): Promise<EntryResult>;
+
+/** Conventional filename, written beside the graph. */
+declare const LOCALIZATIONS_FILENAME = "localizations.json";
+/**
+ * BCP-47's tag for undetermined, used as the bucket for documents that declare
+ * no language. A real tag rather than a dockg invention, so a consumer that
+ * knows BCP-47 already knows what it means — and so the bucket sorts, filters,
+ * and names a file like any other language.
+ */
+declare const UNDETERMINED = "und";
+/** Where one language's lexical index lives, and what it holds. */
+interface SearchArtifact {
+    /** Filename, relative to the manifest. */
+    path: string;
+    /** Indexed nodes. */
+    entries: number;
+    /** `sha256:…` of the file, so a consumer can detect a stale pair. */
+    digest: string;
+}
+/** Where one language's vector sidecar lives, and what produced it. */
+interface VectorArtifact {
+    path: string;
+    /** The embedding model this language was embedded with. */
+    model: string;
+    dtype: string;
+    dims: number;
+    count: number;
+}
+interface LocalizationEntry {
+    /** BCP-47 tag, or `und` for the undeclared bucket. */
+    language: string;
+    /** Documents in this language (sections excluded). */
+    documents: number;
+    search: SearchArtifact;
+    /** Absent until `manni graph embed` has run for this language. */
+    vectors?: VectorArtifact;
+}
+interface LocalizationsDoc {
+    version: 1;
+    /** One entry per language present, sorted by tag. */
+    languages: LocalizationEntry[];
+}
+/** `search.de.json` — the lexical index for one language. */
+declare function searchIndexFilename(language: string): string;
+/** `vectors.de.bin` — the vector sidecar for one language. */
+declare function vectorIndexFilename(language: string): string;
+/**
+ * Serialize the manifest: sorted by language, two-space indent, trailing
+ * newline — byte-stable like every other dockg artifact.
+ */
+declare function emitLocalizations(doc: LocalizationsDoc): string;
+declare function parseLocalizations(text: string): LocalizationsDoc | undefined;
+
+export { type AssembleOptions, type Citation, type ContentResolver, type ContextBlock, type Direction, type EntryCandidate, type EntryRankings, type EntryResult, type EntryVia, type FetchResolverOptions, type FindEntryOptions, GraphIndex, type GraphNode, type Hop, LOCALIZATIONS_FILENAME, type LexicalIndex, type LexicalSearchOptions, type LocalizationEntry, type LocalizationsDoc, type QueryEmbedder, type QueryTrace, type RdfQuad, type RdfTerm, type Refusal, type RefusalReason, type Resolution, type ResolvedContent, type RetrievalBundle, type ScopeExclusion, type ScopeFilter, type SearchArtifact, type SearchEntry, type SearchIndexDoc, type TraverseOptions, type TraverseResult, type TraversedNode, UNDETERMINED, type Value, type VectorArtifact, type VectorIndex, type VectorIndexDoc, VectorIndexError, type VectorIndexHeader, type VectorMismatch, VectorMismatchError, type VectorSearchOptions, assemble, createFetchResolver, createLexicalIndex, createTrace, createVectorIndex, decodeVectorIndex, defaultGraph, documentPreamble, documentSectionOrder, emitLocalizations, encodeVectorIndex, findEntry, impact, literal, matchQuads, namedNode, normalize, parseLocalizations, rdfjsQuads, reachedNodes, resolveSubject, resolveVariant, reverseReferences, rrfMerge, scopeExclusion, searchIndexDigest, searchIndexFilename, sectionOccurrence, sectionOccurrences, sectionOwnText, sliceSection, splitFragment, traverse, vectorIndexFilename };