@saasontools/strauss-kb 0.1.16 → 0.1.17

package/dist/index.d.cts

@@ -48,7 +48,7 @@ declare const kbVerifiedEventSchema: z.ZodObject<{
  * Symbolic on purpose. These are written while the code is still moving: a
  * `line: 379` recorded at minute five is wrong by minute forty, but
  * `OrderService.cancel` survives every edit that does not rename it. Once the
- * change settles, a resolution pass (`anchor-resolver.ts`) stamps `hash`,
+ * change settles, a resolution pass (`anchor-resolver/`) stamps `hash`,
  * `resolved_at`, and `lines`; drift detection later re-resolves and compares.
  *
  * `hash` is prefixed with the algorithm so a future one can coexist with
@@ -70,6 +70,10 @@ declare const kbAnchorSchema: z.ZodObject<{
     hash: z.ZodOptional<z.ZodString>;
     resolved_at: z.ZodOptional<z.ZodString>;
     lines: z.ZodOptional<z.ZodNumber>;
+    resolver: z.ZodOptional<z.ZodEnum<{
+        "tree-sitter": "tree-sitter";
+        regex: "regex";
+    }>>;
 }, z.core.$strict>;
 /**
  * One typed causal edge, as the frontmatter stores it.
@@ -140,6 +144,10 @@ declare const kbRecordFrontmatterSchema: z.ZodObject<{
         hash: z.ZodOptional<z.ZodString>;
         resolved_at: z.ZodOptional<z.ZodString>;
         lines: z.ZodOptional<z.ZodNumber>;
+        resolver: z.ZodOptional<z.ZodEnum<{
+            "tree-sitter": "tree-sitter";
+            regex: "regex";
+        }>>;
     }, z.core.$strict>>>;
     strauss_verify: z.ZodOptional<z.ZodArray<z.ZodString>>;
     strauss_links: z.ZodOptional<z.ZodArray<z.ZodObject<{
@@ -202,12 +210,46 @@ type ResolvedSymbol = {
     startLine: number;
     endLine: number;
 };
+/** Which resolver produced a span. Stamped on the anchor. */
+type AnchorResolverName = "tree-sitter" | "regex";
+/**
+ * A resolver's verdict. `abstain` ("not my language") and `symbol-not-found`
+ * ("nothing I recognize declares this") both pass the symbol down the chain;
+ * `symbol-ambiguous` and `resolver-unavailable` end it, because neither may be
+ * answered by a looser resolver guessing.
+ */
+type ResolverAttempt = {
+    kind: "resolved";
+    span: ResolvedSymbol;
+} | {
+    kind: "unresolved";
+    reason: "symbol-not-found" | "symbol-ambiguous" | "resolver-unavailable";
+} | {
+    kind: "abstain";
+};
 interface AnchorResolver {
     name: string;
-    resolve(source: string, symbol: string): ResolvedSymbol | null;
+    /** Loads whatever these files need, before any `resolve` call. Optional. */
+    prepare?(files: readonly string[]): Promise<void>;
+    /** The richer verdict the chain uses; defaults to `resolve`. */
+    attempt?(source: string, symbol: string, file?: string): ResolverAttempt;
+    resolve(source: string, symbol: string, file?: string): ResolvedSymbol | null;
 }
+/** A resolved span, and which resolver produced it. */
+type AnchorResolution = {
+    ok: true;
+    span: ResolvedSymbol;
+    resolver?: AnchorResolverName;
+} | {
+    ok: false;
+    reason: AnchorUnresolvedReason;
+};
 /** Why an anchor could not be compared. Never an error — always a finding. */
-type AnchorUnresolvedReason = "file-missing" | "symbol-not-found" | "outside-repo" | "file-too-large" | "file-unreadable"
+type AnchorUnresolvedReason = "file-missing" | "symbol-not-found"
+/** More than one definition carries the name, and guessing is not allowed. */
+ | "symbol-ambiguous"
+/** The extension has a grammar, but it would not load. Never a throw. */
+ | "resolver-unavailable" | "outside-repo" | "file-too-large" | "file-unreadable"
 /** The remote could not be fetched, or `--offline` found nothing cached. */
  | "remote-unreachable"
 /** The anchor's `ref` is not on the remote any more. */
@@ -218,6 +260,12 @@ type AnchorUnresolvedReason = "file-missing" | "symbol-not-found" | "outside-rep
  | "ref-invalid"
 /** The anchor's `repo` is not a remote we will fetch from. */
  | "repo-invalid";
+/**
+ * A hash that changed because a more precise resolver took over, not because
+ * the code did. Reported as drift so nothing is restamped silently, and
+ * accepted by `--rebaseline` like any other.
+ */
+type AnchorDriftReason = "resolver-changed";
 /**
  * How a ref-pinned foreign anchor stands. `drifted-on-default` is the one a
  * working-tree anchor has no equivalent of: the evidence is still true at the
@@ -232,7 +280,9 @@ type KbAnchorDriftEntry = {
     currentHash?: string;
     /** `null` when the anchor recorded no `lines` — size unknown, not zero. */
     diffSize: number | null;
-    reason?: AnchorUnresolvedReason;
+    reason?: AnchorUnresolvedReason | AnchorDriftReason;
+    /** Which resolver produced `currentHash`. Absent for a whole-file anchor. */
+    resolver?: AnchorResolverName;
     /** Set only when the anchor was resolved against another repository. */
     repo?: string;
     remoteState?: RemoteAnchorState;
@@ -282,7 +332,10 @@ declare function readRemoteAnchors(wants: readonly RemoteWant[], options?: Remot
 
 type AnchorDriftOptions = {
     repoRoot?: string;
+    /** Single resolver, no chain. Convenience for tests. */
     resolver?: AnchorResolver;
+    /** The chain, tried in order. Defaults to tree-sitter then regex. */
+    resolvers?: readonly AnchorResolver[];
     concurrency?: number;
     /** Test seam: replaces the disk reader. */
     reader?: AnchorFileReader;
@@ -325,6 +378,69 @@ declare function anchorFilePath(repoRoot: string, file: string): string | null;
  */
 declare function isCanonicalRepoUrl(value: string): boolean;
 
+declare const grammarManifestSchema: z.ZodObject<{
+    webTreeSitter: z.ZodString;
+    linguist: z.ZodObject<{
+        tag: z.ZodString;
+        commit: z.ZodString;
+    }, z.core.$strip>;
+    packs: z.ZodRecord<z.ZodString, z.ZodObject<{
+        package: z.ZodString;
+        wasm: z.ZodObject<{
+            url: z.ZodString;
+            sha256: z.ZodString;
+            bytes: z.ZodNumber;
+        }, z.core.$strip>;
+        tags: z.ZodArray<z.ZodObject<{
+            url: z.ZodString;
+            sha256: z.ZodString;
+        }, z.core.$strip>>;
+        license: z.ZodString;
+        extensions: z.ZodArray<z.ZodString>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+type GrammarManifest = z.infer<typeof grammarManifestSchema>;
+/** A grammar and the query that runs over it, both verified, both on disk. */
+type Grammar = {
+    /** Path to the cached WASM. */
+    wasm: string;
+    /** The pack's tags parts as one query, or `undefined` where it declares none. */
+    query: string | undefined;
+};
+/** Where a grammar comes from and whether it may be fetched at all. */
+type GrammarOptions = {
+    /** Cache root; defaults to `STRAUSS_KB_GRAMMARS_DIR` then `~/.strauss/grammars`. */
+    cacheRoot?: string;
+    /** Replaces the scheme and host of every manifest URL. For tests and mirrors. */
+    baseUrl?: string;
+    /** Cache only, never the network — what `--offline` passes down. */
+    offline?: boolean;
+    fetchTimeoutMs?: number;
+    /** Where the download lines go. Defaults to stderr, never stdout. */
+    log?: (line: string) => void;
+};
+
+/**
+ * The shipped `grammars/manifest.json`: the URL, hash and extensions of every
+ * language pack. Read once per process.
+ */
+declare function grammarManifest(): GrammarManifest;
+
+/** Where downloaded grammars live. Overridable so a test never writes to `$HOME`. */
+declare function grammarsCacheRoot(override?: string): string;
+
+/**
+ * Both halves of a verified pack (cached WASM path, tags query text), each
+ * downloaded once. `null` on any refused, disabled or mismatched part is what
+ * the resolver reports as `resolver-unavailable`; a miss is not remembered.
+ */
+declare function ensureGrammar(language: string, options?: GrammarOptions): Promise<Grammar | null>;
+/**
+ * One line per grammar this process could not use, for the doctor and
+ * anchor-resolve reports. The only place a repair is spelled out.
+ */
+declare function grammarHints(): string[];
+
 /**
  * v1 heuristic resolver. A dotted symbol like `OrderService.cancel` matches on
  * its last segment, with the parent used to scope the search: a candidate
@@ -348,6 +464,25 @@ declare function hashAnchorText(text: string): string;
  * whole-file anchor's `lines` one larger than the file.
  */
 declare function resolveAnchor(source: string, anchor: KbAnchor, resolver?: AnchorResolver): ResolvedSymbol | null;
+/**
+ * Walks the resolver chain: tree-sitter, then regex, then a whole-file span
+ * when the anchor names no symbol.
+ *
+ * `symbol-not-found` falls through (a tags query defines functions and types,
+ * not constants or fields) and the anchor records the resolver that answered.
+ * `symbol-ambiguous` and `resolver-unavailable` end the chain: one would be
+ * settled by guessing, the other would trade a precise span for a guessed one.
+ */
+declare function resolveAnchorSpan(source: string, anchor: KbAnchor, resolvers?: readonly AnchorResolver[]): AnchorResolution;
+/** Loads every chained resolver's per-language assets, once. */
+declare function prepareResolvers(resolvers: readonly AnchorResolver[], files: readonly string[]): Promise<void>;
+/**
+ * The read-path chain. A fresh tree-sitter resolver per call, so its parse
+ * cache lives exactly as long as the run that owns it. `offline` rides down to
+ * grammar loading: a run that may not reach the network uses the cache or
+ * reports `resolver-unavailable`.
+ */
+declare function defaultAnchorResolvers(grammars?: GrammarOptions): AnchorResolver[];
 
 /**
  * Why a matched record must not be read as a plain answer.
@@ -1237,6 +1372,59 @@ declare class KbInvalidConceptIdError extends BaseError {
     constructor(message: string, details: Record<string, string>);
 }
 
+/**
+ * Grammar for a path, or `undefined` when the extension has none — or when the
+ * pinned grammar release ships no tags query for it, so the regex heuristic
+ * keeps those files, as before the resolver existed.
+ */
+declare function languageForFile(file: string): string | undefined;
+/** Every language the resolver can resolve in: a grammar and a tags query. */
+declare function treeSitterLanguages(): string[];
+
+type TreeSitterStats = {
+    parses: number;
+    cacheHits: number;
+};
+/** Where both halves of a pack come from, and whether they may be fetched. */
+type TreeSitterOptions = GrammarOptions;
+declare class TreeSitterResolver implements AnchorResolver {
+    readonly name = "tree-sitter";
+    private readonly grammars;
+    private readonly loaded;
+    private readonly trees;
+    private parser;
+    private initialized;
+    /** Cache effectiveness, for tests and for the latency numbers. */
+    readonly stats: TreeSitterStats;
+    constructor(options?: TreeSitterOptions);
+    /**
+     * Loads the grammars these files need, once per language per process,
+     * downloading each one on first use.
+     *
+     * A grammar that will not load is remembered as unavailable rather than
+     * retried per anchor, and never throws: an unobtainable WASM is a finding.
+     */
+    prepare(files: readonly string[]): Promise<void>;
+    /**
+     * An unobtainable grammar, one this runtime refuses, and a query that will
+     * not compile are three faults with three repairs; all are reported through
+     * the grammars module so every hint has one home.
+     */
+    private load;
+    /**
+     * Abstains on an extension with no grammar so the regex resolver gets a
+     * turn; reports `resolver-unavailable` when the grammar exists in principle
+     * but could not be loaded, because falling back there would silently trade a
+     * precise span for a guessed one.
+     */
+    attempt(source: string, symbol: string, file?: string): ResolverAttempt;
+    resolve(source: string, symbol: string, file?: string): ResolvedSymbol | null;
+    /** Parsed trees are keyed by content hash, so an unchanged file parses once. */
+    private parse;
+    /** Drops cached trees. Grammars stay loaded — they are immutable. */
+    reset(): void;
+}
+
 /**
  * What each record type is for, and the shape of its body.
  *
@@ -1334,6 +1522,10 @@ declare const composeInputSchema: z.ZodObject<{
         hash: z.ZodOptional<z.ZodString>;
         resolved_at: z.ZodOptional<z.ZodString>;
         lines: z.ZodOptional<z.ZodNumber>;
+        resolver: z.ZodOptional<z.ZodEnum<{
+            "tree-sitter": "tree-sitter";
+            regex: "regex";
+        }>>;
     }, z.core.$strict>>>;
     sources: z.ZodOptional<z.ZodArray<z.ZodObject<{
         id: z.ZodString;
@@ -1857,6 +2049,19 @@ type KbDoctorReport = {
     groups: KbDoctorGroup[];
     findingCount: number;
     healthy: boolean;
+    /**
+     * Anchors carrying a hash, by the resolver that produced it. A heuristic
+     * span is weaker evidence than a parsed one, so a base still leaning on the
+     * regex resolver is worth re-resolving. Not a finding: a regex-stamped
+     * anchor is not broken.
+     */
+    anchorResolvers: KbAnchorResolverCounts;
+};
+type KbAnchorResolverCounts = {
+    total: number;
+    treeSitter: number;
+    /** Includes anchors stamped before resolvers were named. */
+    regex: number;
 };
 type KbDoctorOptions = {
     /** How far ahead `expiring` looks. */
@@ -1925,6 +2130,10 @@ declare const decisionInputSchema: z.ZodObject<{
         hash: z.ZodOptional<z.ZodString>;
         resolved_at: z.ZodOptional<z.ZodString>;
         lines: z.ZodOptional<z.ZodNumber>;
+        resolver: z.ZodOptional<z.ZodEnum<{
+            "tree-sitter": "tree-sitter";
+            regex: "regex";
+        }>>;
     }, z.core.$strict>>>;
     verify: z.ZodOptional<z.ZodArray<z.ZodString>>;
     relatedConceptIds: z.ZodOptional<z.ZodArray<z.ZodString>>;
@@ -2176,4 +2385,4 @@ declare function parseMarkdownWithFrontmatter<S extends z.ZodType>(text: string,
     frontmatter: ReturnType<S["safeParse"]>;
 };
 
-export { type AnchorResolver, BaseError, CONTEXT_BEGIN, CONTEXT_END, CONTEXT_PROFILES, type ComposeInput, type ComposeLink, type ComposedRecord, DECISION_TYPE, DEFAULT_AGING_DAYS, DEFAULT_EXPIRING_DAYS, DEFAULT_LOAD_BUDGET, DEFAULT_PACK_HOPS, DEFAULT_PACK_MAX_NODES, DEFAULT_TYPED_LINK_RELS, DEFAULT_UNVERIFIED_DAYS, type DecisionInput, type DiffFile, type DiffHunk, type DiffMatch, type ErrorDetails, type ErrorProps, ErrorTypes, Fault, INDEX_FILE, KB_CAUSAL_LINK_RELS, KB_COMMANDS, KB_COMMANDS_BY_NAME, KB_CONCEPT_ID_PATTERN, KB_CONFIDENCES, KB_DIR, KB_DOCTOR_CHECKS, KB_EDGE_KINDS, KB_LINK_RELS, KB_MATERIALITIES, KB_RECORD_STATUSES, KB_RECORD_TYPES, KB_SLUG_PATTERN, type KbActorStamp, type KbAdjudicated, type KbAnchor, type KbAnchorDriftEntry, type KbBacklink, type KbBacklinksResult, KbBaseFrozenError, type KbCatalogEntry, type KbCatalogResult, type KbCommand, type KbCommandContext, type KbContextBudgets, type KbContextOptions, type KbContextResult, type KbDoctorCheck, type KbDoctorFinding, type KbDoctorGroup, type KbDoctorOptions, type KbDoctorReport, type KbDoctorThresholds, type KbEdgeKind, type KbImpactOptions, type KbImpactResult, type KbImpactedRecord, type KbInboundEdge, KbInvalidConceptIdError, type KbLink, type KbLinkEdge, type KbLinkRel, type KbLinkRelSpec, type KbLoadResult, type KbLogEntry, type KbLogReadResult, type KbLogger, type KbMergedPin, type KbMergedPins, KbMissingFlagValueError, type KbNeighbour, KbPackBudgetExceededError, type KbPackOptions, type KbPackResult, type KbPackedRecord, type KbPin, type KbPinLayer, type KbPinOptions, type KbPinResult, type KbPinStatus, KbPinsMalformedError, type KbPinsManifest, type KbRecord, KbRecordAlreadyExistsError, type KbRecordFrontmatter, KbRecordNotFoundError, type KbRecordStatus, type KbRecordType, type KbRecordTypeSpec, type KbSearchLogger, KbSelfVerificationError, type KbSource, type KbStanding, KbStore, type KbSupersededStub, type KbSyncResult, type KbTraceEdge, type KbTraceOptions, type KbTraceStep, KbUnknownLinkRelError, type KbValidationProblem, type KbValidationSeverity, type KbVerifiedEvent, type KbWarning, KbWriteConflictError, type KbWriteInput, LINK_RELS, LOG_FILE, type MatchOptions, NO_DECISION_SLUG, PINS_FILE, PINS_LOCAL_FILE, PIN_LAYERS, type QmdModule, RECORD_TYPES, type RemoteAnchorState, type RemoteOptions, type RemoteRead, type ResolvedSymbol, SEARCH_INDEX_FILE, type SearchHit, type SearchOptions, type SymbolRange, TRACE_EDGES, adjudicate, anchorFilePath, assertBaseNotFrozen, backlinks, buildContext, catalog, composeDecisionRecord, composeInputSchema, composeLinkSchema, composeNoDecisionRecord, composeRecord, contextProfileBudgets, createKbMcpServer, decisionInputSchema, detectAnchorDrift, doctor, edgeNeighbours, hashAnchorText, impact, inboundIndex, indexIsStale, isCanonicalRepoUrl, isKbLinkRel, isKbRecordType, isNoDecisionRecord, kbActorStampSchema, kbAnchorSchema, kbConceptIdSchema, kbJsonSchemas, kbLinkSchema, kbLogEntrySchema, kbRecordFrontmatterSchema, kbSourceSchema, kbVerifiedEventSchema, listPins, loadQmd, matchToDiff, mergedContextBudgets, neighbours, pack, parseLog, parseMarkdownWithFrontmatter, pinBase, readMergedPins, readPinsLayer, readRemoteAnchors, regexResolver, renderCatalogLine, renderIndex, renderIndexLine, renderLogEntry, repoCacheDir, resolveAnchor, resolveHeads, resolveHits, resolvePinPath, runKbCli, runKbMcpServer, searchBase, selectDecisions, splitMarkdownFrontmatter, stringifyMarkdownWithFrontmatter, syncInstructions, toHookJson, trace, unpinBase, validateBundle };
+export { type AnchorResolution, type AnchorResolver, type AnchorResolverName, BaseError, CONTEXT_BEGIN, CONTEXT_END, CONTEXT_PROFILES, type ComposeInput, type ComposeLink, type ComposedRecord, DECISION_TYPE, DEFAULT_AGING_DAYS, DEFAULT_EXPIRING_DAYS, DEFAULT_LOAD_BUDGET, DEFAULT_PACK_HOPS, DEFAULT_PACK_MAX_NODES, DEFAULT_TYPED_LINK_RELS, DEFAULT_UNVERIFIED_DAYS, type DecisionInput, type DiffFile, type DiffHunk, type DiffMatch, type ErrorDetails, type ErrorProps, ErrorTypes, Fault, type Grammar, type GrammarManifest, type GrammarOptions, INDEX_FILE, KB_CAUSAL_LINK_RELS, KB_COMMANDS, KB_COMMANDS_BY_NAME, KB_CONCEPT_ID_PATTERN, KB_CONFIDENCES, KB_DIR, KB_DOCTOR_CHECKS, KB_EDGE_KINDS, KB_LINK_RELS, KB_MATERIALITIES, KB_RECORD_STATUSES, KB_RECORD_TYPES, KB_SLUG_PATTERN, type KbActorStamp, type KbAdjudicated, type KbAnchor, type KbAnchorDriftEntry, type KbBacklink, type KbBacklinksResult, KbBaseFrozenError, type KbCatalogEntry, type KbCatalogResult, type KbCommand, type KbCommandContext, type KbContextBudgets, type KbContextOptions, type KbContextResult, type KbDoctorCheck, type KbDoctorFinding, type KbDoctorGroup, type KbDoctorOptions, type KbDoctorReport, type KbDoctorThresholds, type KbEdgeKind, type KbImpactOptions, type KbImpactResult, type KbImpactedRecord, type KbInboundEdge, KbInvalidConceptIdError, type KbLink, type KbLinkEdge, type KbLinkRel, type KbLinkRelSpec, type KbLoadResult, type KbLogEntry, type KbLogReadResult, type KbLogger, type KbMergedPin, type KbMergedPins, KbMissingFlagValueError, type KbNeighbour, KbPackBudgetExceededError, type KbPackOptions, type KbPackResult, type KbPackedRecord, type KbPin, type KbPinLayer, type KbPinOptions, type KbPinResult, type KbPinStatus, KbPinsMalformedError, type KbPinsManifest, type KbRecord, KbRecordAlreadyExistsError, type KbRecordFrontmatter, KbRecordNotFoundError, type KbRecordStatus, type KbRecordType, type KbRecordTypeSpec, type KbSearchLogger, KbSelfVerificationError, type KbSource, type KbStanding, KbStore, type KbSupersededStub, type KbSyncResult, type KbTraceEdge, type KbTraceOptions, type KbTraceStep, KbUnknownLinkRelError, type KbValidationProblem, type KbValidationSeverity, type KbVerifiedEvent, type KbWarning, KbWriteConflictError, type KbWriteInput, LINK_RELS, LOG_FILE, type MatchOptions, NO_DECISION_SLUG, PINS_FILE, PINS_LOCAL_FILE, PIN_LAYERS, type QmdModule, RECORD_TYPES, type RemoteAnchorState, type RemoteOptions, type RemoteRead, type ResolvedSymbol, type ResolverAttempt, SEARCH_INDEX_FILE, type SearchHit, type SearchOptions, type SymbolRange, TRACE_EDGES, TreeSitterResolver, adjudicate, anchorFilePath, assertBaseNotFrozen, backlinks, buildContext, catalog, composeDecisionRecord, composeInputSchema, composeLinkSchema, composeNoDecisionRecord, composeRecord, contextProfileBudgets, createKbMcpServer, decisionInputSchema, defaultAnchorResolvers, detectAnchorDrift, doctor, edgeNeighbours, ensureGrammar, grammarHints, grammarManifest, grammarsCacheRoot, hashAnchorText, impact, inboundIndex, indexIsStale, isCanonicalRepoUrl, isKbLinkRel, isKbRecordType, isNoDecisionRecord, kbActorStampSchema, kbAnchorSchema, kbConceptIdSchema, kbJsonSchemas, kbLinkSchema, kbLogEntrySchema, kbRecordFrontmatterSchema, kbSourceSchema, kbVerifiedEventSchema, languageForFile, listPins, loadQmd, matchToDiff, mergedContextBudgets, neighbours, pack, parseLog, parseMarkdownWithFrontmatter, pinBase, prepareResolvers, readMergedPins, readPinsLayer, readRemoteAnchors, regexResolver, renderCatalogLine, renderIndex, renderIndexLine, renderLogEntry, repoCacheDir, resolveAnchor, resolveAnchorSpan, resolveHeads, resolveHits, resolvePinPath, runKbCli, runKbMcpServer, searchBase, selectDecisions, splitMarkdownFrontmatter, stringifyMarkdownWithFrontmatter, syncInstructions, toHookJson, trace, treeSitterLanguages, unpinBase, validateBundle };

package/dist/index.d.ts

@@ -48,7 +48,7 @@ declare const kbVerifiedEventSchema: z.ZodObject<{
  * Symbolic on purpose. These are written while the code is still moving: a
  * `line: 379` recorded at minute five is wrong by minute forty, but
  * `OrderService.cancel` survives every edit that does not rename it. Once the
- * change settles, a resolution pass (`anchor-resolver.ts`) stamps `hash`,
+ * change settles, a resolution pass (`anchor-resolver/`) stamps `hash`,
  * `resolved_at`, and `lines`; drift detection later re-resolves and compares.
  *
  * `hash` is prefixed with the algorithm so a future one can coexist with
@@ -70,6 +70,10 @@ declare const kbAnchorSchema: z.ZodObject<{
     hash: z.ZodOptional<z.ZodString>;
     resolved_at: z.ZodOptional<z.ZodString>;
     lines: z.ZodOptional<z.ZodNumber>;
+    resolver: z.ZodOptional<z.ZodEnum<{
+        "tree-sitter": "tree-sitter";
+        regex: "regex";
+    }>>;
 }, z.core.$strict>;
 /**
  * One typed causal edge, as the frontmatter stores it.
@@ -140,6 +144,10 @@ declare const kbRecordFrontmatterSchema: z.ZodObject<{
         hash: z.ZodOptional<z.ZodString>;
         resolved_at: z.ZodOptional<z.ZodString>;
         lines: z.ZodOptional<z.ZodNumber>;
+        resolver: z.ZodOptional<z.ZodEnum<{
+            "tree-sitter": "tree-sitter";
+            regex: "regex";
+        }>>;
     }, z.core.$strict>>>;
     strauss_verify: z.ZodOptional<z.ZodArray<z.ZodString>>;
     strauss_links: z.ZodOptional<z.ZodArray<z.ZodObject<{
@@ -202,12 +210,46 @@ type ResolvedSymbol = {
     startLine: number;
     endLine: number;
 };
+/** Which resolver produced a span. Stamped on the anchor. */
+type AnchorResolverName = "tree-sitter" | "regex";
+/**
+ * A resolver's verdict. `abstain` ("not my language") and `symbol-not-found`
+ * ("nothing I recognize declares this") both pass the symbol down the chain;
+ * `symbol-ambiguous` and `resolver-unavailable` end it, because neither may be
+ * answered by a looser resolver guessing.
+ */
+type ResolverAttempt = {
+    kind: "resolved";
+    span: ResolvedSymbol;
+} | {
+    kind: "unresolved";
+    reason: "symbol-not-found" | "symbol-ambiguous" | "resolver-unavailable";
+} | {
+    kind: "abstain";
+};
 interface AnchorResolver {
     name: string;
-    resolve(source: string, symbol: string): ResolvedSymbol | null;
+    /** Loads whatever these files need, before any `resolve` call. Optional. */
+    prepare?(files: readonly string[]): Promise<void>;
+    /** The richer verdict the chain uses; defaults to `resolve`. */
+    attempt?(source: string, symbol: string, file?: string): ResolverAttempt;
+    resolve(source: string, symbol: string, file?: string): ResolvedSymbol | null;
 }
+/** A resolved span, and which resolver produced it. */
+type AnchorResolution = {
+    ok: true;
+    span: ResolvedSymbol;
+    resolver?: AnchorResolverName;
+} | {
+    ok: false;
+    reason: AnchorUnresolvedReason;
+};
 /** Why an anchor could not be compared. Never an error — always a finding. */
-type AnchorUnresolvedReason = "file-missing" | "symbol-not-found" | "outside-repo" | "file-too-large" | "file-unreadable"
+type AnchorUnresolvedReason = "file-missing" | "symbol-not-found"
+/** More than one definition carries the name, and guessing is not allowed. */
+ | "symbol-ambiguous"
+/** The extension has a grammar, but it would not load. Never a throw. */
+ | "resolver-unavailable" | "outside-repo" | "file-too-large" | "file-unreadable"
 /** The remote could not be fetched, or `--offline` found nothing cached. */
  | "remote-unreachable"
 /** The anchor's `ref` is not on the remote any more. */
@@ -218,6 +260,12 @@ type AnchorUnresolvedReason = "file-missing" | "symbol-not-found" | "outside-rep
  | "ref-invalid"
 /** The anchor's `repo` is not a remote we will fetch from. */
  | "repo-invalid";
+/**
+ * A hash that changed because a more precise resolver took over, not because
+ * the code did. Reported as drift so nothing is restamped silently, and
+ * accepted by `--rebaseline` like any other.
+ */
+type AnchorDriftReason = "resolver-changed";
 /**
  * How a ref-pinned foreign anchor stands. `drifted-on-default` is the one a
  * working-tree anchor has no equivalent of: the evidence is still true at the
@@ -232,7 +280,9 @@ type KbAnchorDriftEntry = {
     currentHash?: string;
     /** `null` when the anchor recorded no `lines` — size unknown, not zero. */
     diffSize: number | null;
-    reason?: AnchorUnresolvedReason;
+    reason?: AnchorUnresolvedReason | AnchorDriftReason;
+    /** Which resolver produced `currentHash`. Absent for a whole-file anchor. */
+    resolver?: AnchorResolverName;
     /** Set only when the anchor was resolved against another repository. */
     repo?: string;
     remoteState?: RemoteAnchorState;
@@ -282,7 +332,10 @@ declare function readRemoteAnchors(wants: readonly RemoteWant[], options?: Remot
 
 type AnchorDriftOptions = {
     repoRoot?: string;
+    /** Single resolver, no chain. Convenience for tests. */
     resolver?: AnchorResolver;
+    /** The chain, tried in order. Defaults to tree-sitter then regex. */
+    resolvers?: readonly AnchorResolver[];
     concurrency?: number;
     /** Test seam: replaces the disk reader. */
     reader?: AnchorFileReader;
@@ -325,6 +378,69 @@ declare function anchorFilePath(repoRoot: string, file: string): string | null;
  */
 declare function isCanonicalRepoUrl(value: string): boolean;
 
+declare const grammarManifestSchema: z.ZodObject<{
+    webTreeSitter: z.ZodString;
+    linguist: z.ZodObject<{
+        tag: z.ZodString;
+        commit: z.ZodString;
+    }, z.core.$strip>;
+    packs: z.ZodRecord<z.ZodString, z.ZodObject<{
+        package: z.ZodString;
+        wasm: z.ZodObject<{
+            url: z.ZodString;
+            sha256: z.ZodString;
+            bytes: z.ZodNumber;
+        }, z.core.$strip>;
+        tags: z.ZodArray<z.ZodObject<{
+            url: z.ZodString;
+            sha256: z.ZodString;
+        }, z.core.$strip>>;
+        license: z.ZodString;
+        extensions: z.ZodArray<z.ZodString>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+type GrammarManifest = z.infer<typeof grammarManifestSchema>;
+/** A grammar and the query that runs over it, both verified, both on disk. */
+type Grammar = {
+    /** Path to the cached WASM. */
+    wasm: string;
+    /** The pack's tags parts as one query, or `undefined` where it declares none. */
+    query: string | undefined;
+};
+/** Where a grammar comes from and whether it may be fetched at all. */
+type GrammarOptions = {
+    /** Cache root; defaults to `STRAUSS_KB_GRAMMARS_DIR` then `~/.strauss/grammars`. */
+    cacheRoot?: string;
+    /** Replaces the scheme and host of every manifest URL. For tests and mirrors. */
+    baseUrl?: string;
+    /** Cache only, never the network — what `--offline` passes down. */
+    offline?: boolean;
+    fetchTimeoutMs?: number;
+    /** Where the download lines go. Defaults to stderr, never stdout. */
+    log?: (line: string) => void;
+};
+
+/**
+ * The shipped `grammars/manifest.json`: the URL, hash and extensions of every
+ * language pack. Read once per process.
+ */
+declare function grammarManifest(): GrammarManifest;
+
+/** Where downloaded grammars live. Overridable so a test never writes to `$HOME`. */
+declare function grammarsCacheRoot(override?: string): string;
+
+/**
+ * Both halves of a verified pack (cached WASM path, tags query text), each
+ * downloaded once. `null` on any refused, disabled or mismatched part is what
+ * the resolver reports as `resolver-unavailable`; a miss is not remembered.
+ */
+declare function ensureGrammar(language: string, options?: GrammarOptions): Promise<Grammar | null>;
+/**
+ * One line per grammar this process could not use, for the doctor and
+ * anchor-resolve reports. The only place a repair is spelled out.
+ */
+declare function grammarHints(): string[];
+
 /**
  * v1 heuristic resolver. A dotted symbol like `OrderService.cancel` matches on
  * its last segment, with the parent used to scope the search: a candidate
@@ -348,6 +464,25 @@ declare function hashAnchorText(text: string): string;
  * whole-file anchor's `lines` one larger than the file.
  */
 declare function resolveAnchor(source: string, anchor: KbAnchor, resolver?: AnchorResolver): ResolvedSymbol | null;
+/**
+ * Walks the resolver chain: tree-sitter, then regex, then a whole-file span
+ * when the anchor names no symbol.
+ *
+ * `symbol-not-found` falls through (a tags query defines functions and types,
+ * not constants or fields) and the anchor records the resolver that answered.
+ * `symbol-ambiguous` and `resolver-unavailable` end the chain: one would be
+ * settled by guessing, the other would trade a precise span for a guessed one.
+ */
+declare function resolveAnchorSpan(source: string, anchor: KbAnchor, resolvers?: readonly AnchorResolver[]): AnchorResolution;
+/** Loads every chained resolver's per-language assets, once. */
+declare function prepareResolvers(resolvers: readonly AnchorResolver[], files: readonly string[]): Promise<void>;
+/**
+ * The read-path chain. A fresh tree-sitter resolver per call, so its parse
+ * cache lives exactly as long as the run that owns it. `offline` rides down to
+ * grammar loading: a run that may not reach the network uses the cache or
+ * reports `resolver-unavailable`.
+ */
+declare function defaultAnchorResolvers(grammars?: GrammarOptions): AnchorResolver[];
 
 /**
  * Why a matched record must not be read as a plain answer.
@@ -1237,6 +1372,59 @@ declare class KbInvalidConceptIdError extends BaseError {
     constructor(message: string, details: Record<string, string>);
 }
 
+/**
+ * Grammar for a path, or `undefined` when the extension has none — or when the
+ * pinned grammar release ships no tags query for it, so the regex heuristic
+ * keeps those files, as before the resolver existed.
+ */
+declare function languageForFile(file: string): string | undefined;
+/** Every language the resolver can resolve in: a grammar and a tags query. */
+declare function treeSitterLanguages(): string[];
+
+type TreeSitterStats = {
+    parses: number;
+    cacheHits: number;
+};
+/** Where both halves of a pack come from, and whether they may be fetched. */
+type TreeSitterOptions = GrammarOptions;
+declare class TreeSitterResolver implements AnchorResolver {
+    readonly name = "tree-sitter";
+    private readonly grammars;
+    private readonly loaded;
+    private readonly trees;
+    private parser;
+    private initialized;
+    /** Cache effectiveness, for tests and for the latency numbers. */
+    readonly stats: TreeSitterStats;
+    constructor(options?: TreeSitterOptions);
+    /**
+     * Loads the grammars these files need, once per language per process,
+     * downloading each one on first use.
+     *
+     * A grammar that will not load is remembered as unavailable rather than
+     * retried per anchor, and never throws: an unobtainable WASM is a finding.
+     */
+    prepare(files: readonly string[]): Promise<void>;
+    /**
+     * An unobtainable grammar, one this runtime refuses, and a query that will
+     * not compile are three faults with three repairs; all are reported through
+     * the grammars module so every hint has one home.
+     */
+    private load;
+    /**
+     * Abstains on an extension with no grammar so the regex resolver gets a
+     * turn; reports `resolver-unavailable` when the grammar exists in principle
+     * but could not be loaded, because falling back there would silently trade a
+     * precise span for a guessed one.
+     */
+    attempt(source: string, symbol: string, file?: string): ResolverAttempt;
+    resolve(source: string, symbol: string, file?: string): ResolvedSymbol | null;
+    /** Parsed trees are keyed by content hash, so an unchanged file parses once. */
+    private parse;
+    /** Drops cached trees. Grammars stay loaded — they are immutable. */
+    reset(): void;
+}
+
 /**
  * What each record type is for, and the shape of its body.
  *
@@ -1334,6 +1522,10 @@ declare const composeInputSchema: z.ZodObject<{
         hash: z.ZodOptional<z.ZodString>;
         resolved_at: z.ZodOptional<z.ZodString>;
         lines: z.ZodOptional<z.ZodNumber>;
+        resolver: z.ZodOptional<z.ZodEnum<{
+            "tree-sitter": "tree-sitter";
+            regex: "regex";
+        }>>;
     }, z.core.$strict>>>;
     sources: z.ZodOptional<z.ZodArray<z.ZodObject<{
         id: z.ZodString;
@@ -1857,6 +2049,19 @@ type KbDoctorReport = {
     groups: KbDoctorGroup[];
     findingCount: number;
     healthy: boolean;
+    /**
+     * Anchors carrying a hash, by the resolver that produced it. A heuristic
+     * span is weaker evidence than a parsed one, so a base still leaning on the
+     * regex resolver is worth re-resolving. Not a finding: a regex-stamped
+     * anchor is not broken.
+     */
+    anchorResolvers: KbAnchorResolverCounts;
+};
+type KbAnchorResolverCounts = {
+    total: number;
+    treeSitter: number;
+    /** Includes anchors stamped before resolvers were named. */
+    regex: number;
 };
 type KbDoctorOptions = {
     /** How far ahead `expiring` looks. */
@@ -1925,6 +2130,10 @@ declare const decisionInputSchema: z.ZodObject<{
         hash: z.ZodOptional<z.ZodString>;
         resolved_at: z.ZodOptional<z.ZodString>;
         lines: z.ZodOptional<z.ZodNumber>;
+        resolver: z.ZodOptional<z.ZodEnum<{
+            "tree-sitter": "tree-sitter";
+            regex: "regex";
+        }>>;
     }, z.core.$strict>>>;
     verify: z.ZodOptional<z.ZodArray<z.ZodString>>;
     relatedConceptIds: z.ZodOptional<z.ZodArray<z.ZodString>>;
@@ -2176,4 +2385,4 @@ declare function parseMarkdownWithFrontmatter<S extends z.ZodType>(text: string,
     frontmatter: ReturnType<S["safeParse"]>;
 };
 
-export { type AnchorResolver, BaseError, CONTEXT_BEGIN, CONTEXT_END, CONTEXT_PROFILES, type ComposeInput, type ComposeLink, type ComposedRecord, DECISION_TYPE, DEFAULT_AGING_DAYS, DEFAULT_EXPIRING_DAYS, DEFAULT_LOAD_BUDGET, DEFAULT_PACK_HOPS, DEFAULT_PACK_MAX_NODES, DEFAULT_TYPED_LINK_RELS, DEFAULT_UNVERIFIED_DAYS, type DecisionInput, type DiffFile, type DiffHunk, type DiffMatch, type ErrorDetails, type ErrorProps, ErrorTypes, Fault, INDEX_FILE, KB_CAUSAL_LINK_RELS, KB_COMMANDS, KB_COMMANDS_BY_NAME, KB_CONCEPT_ID_PATTERN, KB_CONFIDENCES, KB_DIR, KB_DOCTOR_CHECKS, KB_EDGE_KINDS, KB_LINK_RELS, KB_MATERIALITIES, KB_RECORD_STATUSES, KB_RECORD_TYPES, KB_SLUG_PATTERN, type KbActorStamp, type KbAdjudicated, type KbAnchor, type KbAnchorDriftEntry, type KbBacklink, type KbBacklinksResult, KbBaseFrozenError, type KbCatalogEntry, type KbCatalogResult, type KbCommand, type KbCommandContext, type KbContextBudgets, type KbContextOptions, type KbContextResult, type KbDoctorCheck, type KbDoctorFinding, type KbDoctorGroup, type KbDoctorOptions, type KbDoctorReport, type KbDoctorThresholds, type KbEdgeKind, type KbImpactOptions, type KbImpactResult, type KbImpactedRecord, type KbInboundEdge, KbInvalidConceptIdError, type KbLink, type KbLinkEdge, type KbLinkRel, type KbLinkRelSpec, type KbLoadResult, type KbLogEntry, type KbLogReadResult, type KbLogger, type KbMergedPin, type KbMergedPins, KbMissingFlagValueError, type KbNeighbour, KbPackBudgetExceededError, type KbPackOptions, type KbPackResult, type KbPackedRecord, type KbPin, type KbPinLayer, type KbPinOptions, type KbPinResult, type KbPinStatus, KbPinsMalformedError, type KbPinsManifest, type KbRecord, KbRecordAlreadyExistsError, type KbRecordFrontmatter, KbRecordNotFoundError, type KbRecordStatus, type KbRecordType, type KbRecordTypeSpec, type KbSearchLogger, KbSelfVerificationError, type KbSource, type KbStanding, KbStore, type KbSupersededStub, type KbSyncResult, type KbTraceEdge, type KbTraceOptions, type KbTraceStep, KbUnknownLinkRelError, type KbValidationProblem, type KbValidationSeverity, type KbVerifiedEvent, type KbWarning, KbWriteConflictError, type KbWriteInput, LINK_RELS, LOG_FILE, type MatchOptions, NO_DECISION_SLUG, PINS_FILE, PINS_LOCAL_FILE, PIN_LAYERS, type QmdModule, RECORD_TYPES, type RemoteAnchorState, type RemoteOptions, type RemoteRead, type ResolvedSymbol, SEARCH_INDEX_FILE, type SearchHit, type SearchOptions, type SymbolRange, TRACE_EDGES, adjudicate, anchorFilePath, assertBaseNotFrozen, backlinks, buildContext, catalog, composeDecisionRecord, composeInputSchema, composeLinkSchema, composeNoDecisionRecord, composeRecord, contextProfileBudgets, createKbMcpServer, decisionInputSchema, detectAnchorDrift, doctor, edgeNeighbours, hashAnchorText, impact, inboundIndex, indexIsStale, isCanonicalRepoUrl, isKbLinkRel, isKbRecordType, isNoDecisionRecord, kbActorStampSchema, kbAnchorSchema, kbConceptIdSchema, kbJsonSchemas, kbLinkSchema, kbLogEntrySchema, kbRecordFrontmatterSchema, kbSourceSchema, kbVerifiedEventSchema, listPins, loadQmd, matchToDiff, mergedContextBudgets, neighbours, pack, parseLog, parseMarkdownWithFrontmatter, pinBase, readMergedPins, readPinsLayer, readRemoteAnchors, regexResolver, renderCatalogLine, renderIndex, renderIndexLine, renderLogEntry, repoCacheDir, resolveAnchor, resolveHeads, resolveHits, resolvePinPath, runKbCli, runKbMcpServer, searchBase, selectDecisions, splitMarkdownFrontmatter, stringifyMarkdownWithFrontmatter, syncInstructions, toHookJson, trace, unpinBase, validateBundle };
+export { type AnchorResolution, type AnchorResolver, type AnchorResolverName, BaseError, CONTEXT_BEGIN, CONTEXT_END, CONTEXT_PROFILES, type ComposeInput, type ComposeLink, type ComposedRecord, DECISION_TYPE, DEFAULT_AGING_DAYS, DEFAULT_EXPIRING_DAYS, DEFAULT_LOAD_BUDGET, DEFAULT_PACK_HOPS, DEFAULT_PACK_MAX_NODES, DEFAULT_TYPED_LINK_RELS, DEFAULT_UNVERIFIED_DAYS, type DecisionInput, type DiffFile, type DiffHunk, type DiffMatch, type ErrorDetails, type ErrorProps, ErrorTypes, Fault, type Grammar, type GrammarManifest, type GrammarOptions, INDEX_FILE, KB_CAUSAL_LINK_RELS, KB_COMMANDS, KB_COMMANDS_BY_NAME, KB_CONCEPT_ID_PATTERN, KB_CONFIDENCES, KB_DIR, KB_DOCTOR_CHECKS, KB_EDGE_KINDS, KB_LINK_RELS, KB_MATERIALITIES, KB_RECORD_STATUSES, KB_RECORD_TYPES, KB_SLUG_PATTERN, type KbActorStamp, type KbAdjudicated, type KbAnchor, type KbAnchorDriftEntry, type KbBacklink, type KbBacklinksResult, KbBaseFrozenError, type KbCatalogEntry, type KbCatalogResult, type KbCommand, type KbCommandContext, type KbContextBudgets, type KbContextOptions, type KbContextResult, type KbDoctorCheck, type KbDoctorFinding, type KbDoctorGroup, type KbDoctorOptions, type KbDoctorReport, type KbDoctorThresholds, type KbEdgeKind, type KbImpactOptions, type KbImpactResult, type KbImpactedRecord, type KbInboundEdge, KbInvalidConceptIdError, type KbLink, type KbLinkEdge, type KbLinkRel, type KbLinkRelSpec, type KbLoadResult, type KbLogEntry, type KbLogReadResult, type KbLogger, type KbMergedPin, type KbMergedPins, KbMissingFlagValueError, type KbNeighbour, KbPackBudgetExceededError, type KbPackOptions, type KbPackResult, type KbPackedRecord, type KbPin, type KbPinLayer, type KbPinOptions, type KbPinResult, type KbPinStatus, KbPinsMalformedError, type KbPinsManifest, type KbRecord, KbRecordAlreadyExistsError, type KbRecordFrontmatter, KbRecordNotFoundError, type KbRecordStatus, type KbRecordType, type KbRecordTypeSpec, type KbSearchLogger, KbSelfVerificationError, type KbSource, type KbStanding, KbStore, type KbSupersededStub, type KbSyncResult, type KbTraceEdge, type KbTraceOptions, type KbTraceStep, KbUnknownLinkRelError, type KbValidationProblem, type KbValidationSeverity, type KbVerifiedEvent, type KbWarning, KbWriteConflictError, type KbWriteInput, LINK_RELS, LOG_FILE, type MatchOptions, NO_DECISION_SLUG, PINS_FILE, PINS_LOCAL_FILE, PIN_LAYERS, type QmdModule, RECORD_TYPES, type RemoteAnchorState, type RemoteOptions, type RemoteRead, type ResolvedSymbol, type ResolverAttempt, SEARCH_INDEX_FILE, type SearchHit, type SearchOptions, type SymbolRange, TRACE_EDGES, TreeSitterResolver, adjudicate, anchorFilePath, assertBaseNotFrozen, backlinks, buildContext, catalog, composeDecisionRecord, composeInputSchema, composeLinkSchema, composeNoDecisionRecord, composeRecord, contextProfileBudgets, createKbMcpServer, decisionInputSchema, defaultAnchorResolvers, detectAnchorDrift, doctor, edgeNeighbours, ensureGrammar, grammarHints, grammarManifest, grammarsCacheRoot, hashAnchorText, impact, inboundIndex, indexIsStale, isCanonicalRepoUrl, isKbLinkRel, isKbRecordType, isNoDecisionRecord, kbActorStampSchema, kbAnchorSchema, kbConceptIdSchema, kbJsonSchemas, kbLinkSchema, kbLogEntrySchema, kbRecordFrontmatterSchema, kbSourceSchema, kbVerifiedEventSchema, languageForFile, listPins, loadQmd, matchToDiff, mergedContextBudgets, neighbours, pack, parseLog, parseMarkdownWithFrontmatter, pinBase, prepareResolvers, readMergedPins, readPinsLayer, readRemoteAnchors, regexResolver, renderCatalogLine, renderIndex, renderIndexLine, renderLogEntry, repoCacheDir, resolveAnchor, resolveAnchorSpan, resolveHeads, resolveHits, resolvePinPath, runKbCli, runKbMcpServer, searchBase, selectDecisions, splitMarkdownFrontmatter, stringifyMarkdownWithFrontmatter, syncInstructions, toHookJson, trace, treeSitterLanguages, unpinBase, validateBundle };