@saasontools/strauss-kb 0.1.16 → 0.1.18

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
@@ -68,8 +68,16 @@ declare const kbAnchorSchema: z.ZodObject<{
     repo: z.ZodOptional<z.ZodString>;
     ref: z.ZodOptional<z.ZodString>;
     hash: z.ZodOptional<z.ZodString>;
+    hash_kind: z.ZodOptional<z.ZodEnum<{
+        raw: "raw";
+        ast: "ast";
+    }>>;
     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.
@@ -138,8 +146,16 @@ declare const kbRecordFrontmatterSchema: z.ZodObject<{
         repo: z.ZodOptional<z.ZodString>;
         ref: z.ZodOptional<z.ZodString>;
         hash: z.ZodOptional<z.ZodString>;
+        hash_kind: z.ZodOptional<z.ZodEnum<{
+            raw: "raw";
+            ast: "ast";
+        }>>;
         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 +218,57 @@ 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;
+    /**
+     * The span's normalised token stream — comments dropped, runs of whitespace
+     * collapsed — or `null` when this resolver cannot parse the text.
+     *
+     * Only a resolver that understands the language can offer one, which is why
+     * it is optional: a text heuristic normalising by guess would call two
+     * different programs equal.
+     */
+    normalize?(text: string, file?: string): string | null;
 }
+/** A resolved span, and which resolver produced it. */
+type AnchorResolution = {
+    ok: true;
+    span: ResolvedSymbol;
+    resolver?: AnchorResolverName;
+    /** The span's token stream, when the resolver that spanned it can parse. */
+    normalized?: string;
+} | {
+    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,12 +279,37 @@ 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
  * commit it was taken from, and the code has moved since.
  */
 type RemoteAnchorState = "matches-ref" | "drifted-from-ref" | "drifted-on-default";
+/** What `hash` was taken over. Absent on an anchor means `raw`. */
+type AnchorHashKind = "raw" | "ast";
+/**
+ * How an anchor's code changed, once the bytes are known to differ.
+ *
+ * The classes a machine can settle, so a reader only sees the ones it cannot:
+ * `moved` and `cosmetic` are answered and closed, `gone` and `changed` are
+ * handed on. Deliberately shallow — whether the record's *claim* still holds
+ * is a reading, and no hash can stand in for one.
+ */
+declare const KB_DRIFT_CLASSES: readonly ["moved", "cosmetic", "gone", "changed"];
+type KbDriftClass = (typeof KB_DRIFT_CLASSES)[number];
+/** Where a `moved` anchor's stored hash turned up. */
+type KbDriftMovedTo = {
+    file: string;
+    symbol?: string;
+    startLine: number;
+    endLine: number;
+};
 type KbAnchorDriftEntry = {
     file: string;
     symbol?: string;
@@ -232,10 +318,23 @@ 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;
+    /** What the compared hashes were taken over. */
+    hashKind?: AnchorHashKind;
+    /**
+     * Provisional: `gone` or `changed`, the two a hash comparison alone can
+     * settle. `moved` and `cosmetic` cost a repository search and a git read, so
+     * `classifyDrift` refines this on the reassessment path rather than on every
+     * `load`.
+     */
+    class?: KbDriftClass;
+    /** Set by `classifyDrift` when the class is `moved`. */
+    movedTo?: KbDriftMovedTo;
 };
 type AnchorRead = {
     ok: true;
@@ -282,7 +381,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 +427,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 +513,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.
@@ -415,6 +599,12 @@ type KbWarningAnchor = {
     /** Set only for an anchor resolved against another repository. */
     repo?: string;
     remoteState?: string;
+    /**
+     * `gone` or `changed` — what a hash comparison alone can settle. `moved` and
+     * `cosmetic` cost a repository search and a git read, so they are
+     * `kb_reassess`'s answer, not a read path's.
+     */
+    class?: KbDriftClass;
 };
 type KbStanding = "current" | "superseded" | "rejected" | "unsettled" | "open";
 type KbAdjudicated = {
@@ -830,6 +1020,15 @@ type KbStampResult = {
     /** Newest `generated.at` across the base, or null when none carries one. */
     newestAt: string | null;
     records: KbRecordStamp[];
+    /**
+     * Records with at least one anchor whose code no longer matches its hash.
+     *
+     * Outside the digest, and deliberately: drift is a fact about the working
+     * tree, not about the base's content, and folding it in would make a stamp
+     * change every time someone checked out a branch. `null` when the drift pass
+     * could not run — an unknown count, which is not zero.
+     */
+    drifted: number | null;
 };
 type KbWriteInput = {
     type: string;
@@ -1001,11 +1200,16 @@ declare class KbStore {
     }): Promise<KbLoadResult>;
     /**
      * `load`'s digest without `load`'s bodies — the same records, adjudicated
-     * the same way, handed back as a stamp. Skips the anchor drift pass, which
-     * reads source files and only ever adds warnings: no warning reaches the
-     * digest, so the value is identical to the one `load` returns.
+     * the same way, handed back as a stamp.
+     *
+     * Drift is counted but kept out of the digest, which is what lets the reload
+     * hook ask one question and get two answers: whether the base moved, and
+     * whether the code under it did. A `load` and a `stamp` of the same base
+     * still agree on the digest, because no warning has ever reached it.
      */
-    stamp(bundlePath: string): Promise<KbStampResult>;
+    stamp(bundlePath: string, options?: {
+        repoRoot?: string;
+    }): Promise<KbStampResult>;
     /** How a position was arrived at, as a timeline. See `trace.ts`. */
     trace(bundlePath: string, seedId: string, options?: KbTraceOptions): Promise<KbTraceStep[]>;
     /** Every record named in one line each. See `catalog.ts`. */
@@ -1237,6 +1441,85 @@ 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;
+    /**
+     * Every definition this file declares, as dotted symbol and span.
+     *
+     * The inverse of `attempt`: that asks "where is this name", this asks "what
+     * names are here". `moved` needs the second — the stored hash has to be
+     * looked for at every definition in the repository, and there is no name to
+     * ask about, since the whole question is which name now carries that code.
+     */
+    spans(source: string, file: string): {
+        symbol: string;
+        span: ResolvedSymbol;
+    }[];
+    /**
+     * The token stream of a span: every leaf the parser sees, comments dropped,
+     * joined by single spaces.
+     *
+     * This is what makes a reformat not be drift. Hashing it rather than the raw
+     * text means indentation, line breaks, trailing commas the formatter moved,
+     * and every comment above or inside the definition are outside the hash —
+     * and a renamed identifier or a changed literal is still inside it, because
+     * those are leaves.
+     *
+     * `null` when the file has no grammar, the grammar would not load, or the
+     * text will not parse: no normalisation is better than a guessed one.
+     */
+    normalize(text: string, file?: string): string | null;
+    /** Drops cached trees. Grammars stay loaded — they are immutable. */
+    reset(): void;
+}
+
 /**
  * What each record type is for, and the shape of its body.
  *
@@ -1332,8 +1615,16 @@ declare const composeInputSchema: z.ZodObject<{
         repo: z.ZodOptional<z.ZodString>;
         ref: z.ZodOptional<z.ZodString>;
         hash: z.ZodOptional<z.ZodString>;
+        hash_kind: z.ZodOptional<z.ZodEnum<{
+            raw: "raw";
+            ast: "ast";
+        }>>;
         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 +2148,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. */
@@ -1923,8 +2227,16 @@ declare const decisionInputSchema: z.ZodObject<{
         repo: z.ZodOptional<z.ZodString>;
         ref: z.ZodOptional<z.ZodString>;
         hash: z.ZodOptional<z.ZodString>;
+        hash_kind: z.ZodOptional<z.ZodEnum<{
+            raw: "raw";
+            ast: "ast";
+        }>>;
         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>>;
@@ -2044,6 +2356,189 @@ type KbCommand<Shape extends z.ZodRawShape = z.ZodRawShape> = {
 declare const KB_COMMANDS: KbCommand[];
 declare const KB_COMMANDS_BY_NAME: Map<string, KbCommand>;
 
+/** Where a recovered file came from, so a packet can say how far back it looked. */
+type OldSourceOrigin = 
+/** `git show <anchor.ref>:<file>` — the rev the record itself named. */
+{
+    kind: "ref";
+    ref: string;
+}
+/** The last commit touching the path before `resolved_at`. */
+ | {
+    kind: "history";
+    ref: string;
+};
+
+type MovedSearch = {
+    /**
+     * Where this anchor's stored hash turned up, or `undefined`.
+     *
+     * Shared across every anchor of a run: one `git ls-files`, one parse cache,
+     * one set of loaded grammars. A `doctor --drifted` sweep over a base whose
+     * records anchor into the same few languages parses each candidate once, not
+     * once per drifted anchor.
+     */
+    find(anchor: KbAnchor): Promise<KbDriftMovedTo | undefined>;
+};
+
+/**
+ * Turning "the bytes changed" into one of four answers, two of which end the
+ * matter.
+ *
+ * The order is not arbitrary: `moved` is asked first because it is the only
+ * class that needs no history at all, and `cosmetic` second because it is the
+ * only one that needs the old text. What survives both is what a reader has to
+ * read — and the whole point of asking the cheap questions first is that most
+ * drift never reaches them.
+ *
+ * Everything here is read-only. Rebaselining a `moved` anchor is a write, and
+ * writes belong to the verb the caller named.
+ */
+type ClassifiedAnchor = {
+    anchor: KbAnchor;
+    entry: KbAnchorDriftEntry;
+    /** Resolved class. Never `undefined` — every reported anchor gets one. */
+    class: KbDriftClass;
+    /** The anchored text as it stands now. Absent when the class is `gone`. */
+    newText?: string;
+    /** The anchored text as it was, when history could produce it. */
+    oldText?: string;
+    oldOrigin?: OldSourceOrigin;
+};
+type ClassifyOptions = {
+    /** Test seam: replaces the disk reader. */
+    reader?: AnchorFileReader;
+    /** Skip the history read. `cosmetic` cannot be reached without it. */
+    withHistory?: boolean;
+    /**
+     * The run's shared `moved` search. A sweep classifying many records passes
+     * one, so the repository is listed once and each candidate file is parsed
+     * once for the whole sweep rather than once per record.
+     */
+    search?: MovedSearch;
+};
+/**
+ * Refines one record's drift entries. Anchors that matched, or that name
+ * another repository, are not drift and never appear.
+ */
+declare function classifyDrift(repoRoot: string, record: KbRecord, entries: readonly KbAnchorDriftEntry[], options?: ClassifyOptions): Promise<ClassifiedAnchor[]>;
+
+type UnifiedDiff = {
+    /** `-`/`+`/` ` prefixed lines, with a `@@` header. */
+    text: string;
+    added: number;
+    removed: number;
+    /** Whether the cap cut it short. */
+    truncated: boolean;
+};
+/**
+ * One hunk, no context trimming: the two sides are already a symbol's span,
+ * so the whole of both is the context a reader wants.
+ *
+ * The common subsequence is computed over line *hashes* through a simple
+ * O(n·m) table. Spans are bounded by the anchor file cap, and a smarter
+ * algorithm would be a second thing to be wrong about for a saving nobody can
+ * measure at this size.
+ */
+declare function unifiedDiff(before: string, after: string, options?: {
+    maxLines?: number;
+    oldLabel?: string;
+    newLabel?: string;
+}): UnifiedDiff;
+
+/**
+ * What a reader needs in order to decide whether a record still holds, without
+ * opening the repository.
+ *
+ * A drift finding today says two hashes disagree, which is not a thing anyone
+ * can judge. The packet is the same finding with the three pieces judgment
+ * actually takes: what the record claims, what the code did, and what depends
+ * on the answer. It stops there — the reading itself is the reader's, and
+ * every default below is a starting point the protocol expects to be argued
+ * with.
+ */
+type KbReassessDiff = {
+    status: "ok";
+    /** `ref` when the anchor pinned one, `history` when it was inferred. */
+    source: "ref" | "history";
+    /** The rev the old side was read at. */
+    ref: string;
+    unified: string;
+    added: number;
+    removed: number;
+    truncated: boolean;
+}
+/** No committed text to diff against; see `readOldSource`. */
+ | {
+    status: "unrecoverable";
+};
+type KbReassessAnchor = {
+    file: string;
+    symbol?: string;
+    class: KbDriftClass;
+    reason?: string;
+    storedHash: string;
+    currentHash?: string;
+    diffSize: number | null;
+    movedTo?: KbDriftMovedTo;
+    diff?: KbReassessDiff;
+};
+/**
+ * What the type says about a record whose code changed under it.
+ *
+ * A `fact` is a claim about the world that the code was the evidence for, so
+ * changed evidence presumptively unmakes it. A `decision` is a claim about a
+ * choice, and the reasoning for a choice routinely outlives the code that
+ * implemented it. Neither is a verdict — they are which way to lean while
+ * reading, and naming the lean is what keeps it arguable.
+ */
+type KbReassessDefault = "presumed-invalidated" | "rationale-may-survive" | "review";
+type KbReassessPacket = {
+    conceptId: string;
+    title: string | null;
+    type: string;
+    standing: KbStanding;
+    /** What breaks if this record is wrong — the record's `why`, stored as `description`. */
+    why: string | null;
+    /** The type's claim section — the sentence being reassessed. */
+    claim: {
+        section: string;
+        text: string;
+    } | null;
+    anchors: KbReassessAnchor[];
+    /**
+     * The record's dependants. A fact that stopped holding did not stop holding
+     * alone, and a reader deciding about it is deciding about these too.
+     */
+    impact: {
+        conceptId: string;
+        title: string | null;
+        standing: KbStanding;
+        depth: number;
+    }[];
+    impactTruncated: boolean;
+    default: KbReassessDefault;
+    defaultNote: string;
+};
+type PacketOptions = ClassifyOptions & {
+    /** Recover and render the old-vs-new span diff. Off by default: it reads git. */
+    withDiff?: boolean;
+    impact?: KbImpactResult;
+    standing?: KbStanding;
+};
+/**
+ * One record's packet, or `null` when nothing survived classification.
+ *
+ * A record whose every drifted anchor turned out to be `moved` or `cosmetic`
+ * is a record with no reassessment work, and emitting an empty packet for it
+ * would put it back in front of the reader the classification just cleared it
+ * from.
+ */
+declare function reassessPacket(repoRoot: string, record: KbRecord, entries: readonly KbAnchorDriftEntry[], options?: PacketOptions): Promise<{
+    packet: KbReassessPacket | null;
+    classified: ClassifiedAnchor[];
+}>;
+
 /**
  * A knowledge base's own MCP server, over stdio.
  *
@@ -2176,4 +2671,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 ClassifiedAnchor, 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 KbReassessAnchor, type KbReassessDefault, type KbReassessDiff, type KbReassessPacket, 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, classifyDrift, 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, reassessPacket, regexResolver, renderCatalogLine, renderIndex, renderIndexLine, renderLogEntry, repoCacheDir, resolveAnchor, resolveAnchorSpan, resolveHeads, resolveHits, resolvePinPath, runKbCli, runKbMcpServer, searchBase, selectDecisions, splitMarkdownFrontmatter, stringifyMarkdownWithFrontmatter, syncInstructions, toHookJson, trace, treeSitterLanguages, unifiedDiff, unpinBase, validateBundle };