@saasontools/strauss-kb 0.1.10 → 0.1.11

package/dist/index.d.cts

@@ -47,13 +47,29 @@ 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. A later
- * pass resolves symbols to line ranges once the change has settled, and records
- * that resolution as a `verified[]` entry.
+ * `OrderService.cancel` survives every edit that does not rename it. Once the
+ * change settles, a resolution pass (`anchor-resolver.ts`) 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
+ * stored values. `lines` exists because the anchor keeps a hash, not the text:
+ * without the line count at hash time, a drift report could say "changed" but
+ * never how much.
+ *
+ * `repo` and `ref` say *which* code, for bases that describe more than one
+ * repository. They are author-owned identity: a resolver stamps `hash`,
+ * `lines`, and `resolved_at`, and never writes these two. Both are optional and
+ * independent of each other, so every anchor written before they existed stays
+ * valid.
  */
 declare const kbAnchorSchema: z.ZodObject<{
     file: z.ZodString;
     symbol: z.ZodOptional<z.ZodString>;
+    repo: z.ZodOptional<z.ZodString>;
+    ref: z.ZodOptional<z.ZodString>;
+    hash: z.ZodOptional<z.ZodString>;
+    resolved_at: z.ZodOptional<z.ZodString>;
+    lines: z.ZodOptional<z.ZodNumber>;
 }, z.core.$strict>;
 declare const KB_RECORD_TYPES: readonly ["fact", "requirement", "constraint", "decision", "assumption", "open-question", "risk", "contract", "flow", "affected-system", "test-obligation", "source-note"];
 type KbRecordType = (typeof KB_RECORD_TYPES)[number];
@@ -103,6 +119,11 @@ declare const kbRecordFrontmatterSchema: z.ZodObject<{
     strauss_anchors: z.ZodOptional<z.ZodArray<z.ZodObject<{
         file: z.ZodString;
         symbol: z.ZodOptional<z.ZodString>;
+        repo: z.ZodOptional<z.ZodString>;
+        ref: z.ZodOptional<z.ZodString>;
+        hash: z.ZodOptional<z.ZodString>;
+        resolved_at: z.ZodOptional<z.ZodString>;
+        lines: z.ZodOptional<z.ZodNumber>;
     }, z.core.$strict>>>;
     strauss_verify: z.ZodOptional<z.ZodArray<z.ZodString>>;
     strauss_status: z.ZodDefault<z.ZodEnum<{
@@ -145,6 +166,104 @@ type KbRecord = {
     body: string;
 };
 
+/**
+ * Resolves symbolic anchors to text and detects drift against stored hashes.
+ *
+ * Resolvers are pure — source string in, range out; only the file readers touch
+ * disk. Any shape the lexer cannot handle confidently returns `null` and is
+ * reported `unresolved` rather than guessed at.
+ */
+type ResolvedSymbol = {
+    text: string;
+    /** 1-based, inclusive. */
+    startLine: number;
+    endLine: number;
+};
+interface AnchorResolver {
+    name: string;
+    resolve(source: string, symbol: string): ResolvedSymbol | null;
+}
+/** 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"
+/**
+ * The anchor names a repository this root is not. Expected rather than
+ * wrong — a base describing several repositories resolves against one tree
+ * at a time — so it is never a drift finding and never reaches a reader as
+ * a warning. Multi-root resolution is SAA-709.
+ */
+ | "foreign-repo";
+/**
+ * v1 heuristic resolver. A dotted symbol like `OrderService.cancel` matches on
+ * its last segment, with the parent used to scope the search: a candidate
+ * counts only if the parent name appears in the fifty lines above it, when any
+ * candidate satisfies that at all.
+ *
+ * Deterministic, and ambiguity is not resolved by guessing — two lines of
+ * equally good shape mean the resolver cannot tell which one the record meant,
+ * and it says so by returning `null`.
+ */
+declare const regexResolver: AnchorResolver;
+/** CRLF normalized to LF before hashing, so checkout style cannot read as drift. */
+declare function hashAnchorText(text: string): string;
+/**
+ * An anchor without a symbol is about the whole file; with one, the resolver
+ * decides. Source newlines are normalized first so line counts and hashes
+ * agree with `hashAnchorText`.
+ *
+ * A file's last line is the last line with content: a trailing newline is a
+ * terminator, not an empty line, and counting it would have made every
+ * whole-file anchor's `lines` one larger than the file.
+ */
+declare function resolveAnchor(source: string, anchor: KbAnchor, resolver?: AnchorResolver): ResolvedSymbol | null;
+type KbAnchorDriftEntry = {
+    file: string;
+    symbol?: string;
+    state: "match" | "drifted" | "unresolved";
+    storedHash: string;
+    currentHash?: string;
+    /** `null` when the anchor recorded no `lines` — size unknown, not zero. */
+    diffSize: number | null;
+    reason?: AnchorUnresolvedReason;
+};
+/**
+ * An anchor's `file` must stay inside the repository root — a record points
+ * at code, not at arbitrary files on the machine reading it. Bundles are
+ * data, so a traversal or absolute path here is untrusted input, not a bug
+ * in the caller. Returns the resolved path, or `null` when it escapes.
+ *
+ * Lexical only, and therefore not the whole containment check: see
+ * `readAnchorFile`, which re-tests the real path after following symlinks.
+ */
+declare function anchorFilePath(repoRoot: string, file: string): string | null;
+type AnchorRead = {
+    ok: true;
+    source: string;
+} | {
+    ok: false;
+    reason: AnchorUnresolvedReason;
+};
+type AnchorFileReader = (file: string) => Promise<AnchorRead>;
+/**
+ * Re-resolves every hash-carrying anchor and compares against the stored hash.
+ *
+ * Anchors without a `hash` are skipped; one naming another repository is
+ * reported `foreign-repo` and never read, and `origin` is asked for once per
+ * run, only when some anchor declares a `repo`. A missing file or unresolvable
+ * symbol is a finding (`unresolved`), never a throw. Each distinct file is read
+ * once per run; all checked entries are returned per record, callers filter.
+ *
+ * Three phases: collect the checkable anchors, read their distinct files with
+ * a bounded pool, then resolve and hash in record order — so the output does
+ * not depend on which read finished first.
+ */
+declare function detectAnchorDrift(records: KbRecord[], options?: {
+    repoRoot?: string;
+    resolver?: AnchorResolver;
+    concurrency?: number;
+    /** Test seam: replaces the disk reader. */
+    reader?: AnchorFileReader;
+}): Promise<Map<string, KbAnchorDriftEntry[]>>;
+
 /**
  * Why a matched record must not be read as a plain answer.
  *
@@ -189,6 +308,18 @@ type KbWarning =
     staleAfter: string;
 } | {
     kind: "unverified";
+}
+/** The code this record anchors to has changed since its hash was recorded —
+ *  the record may describe code that no longer exists in that form. */
+ | {
+    kind: "drifted";
+    anchors: {
+        file: string;
+        symbol?: string;
+        /** `null` when the anchor recorded no line count — size unknown. */
+        diffSize: number | null;
+        reason?: string;
+    }[];
 };
 type KbStanding = "current" | "superseded" | "rejected" | "unsettled" | "open";
 type KbAdjudicated = {
@@ -205,7 +336,7 @@ type KbAdjudicated = {
  * invisible: the caller cannot tell it missed anything, so a dropped record is
  * worse than a flagged one — it turns a knowable gap into an unknowable one.
  */
-declare function adjudicate(hits: KbRecord[], bundle: KbRecord[], now?: Date): KbAdjudicated[];
+declare function adjudicate(hits: KbRecord[], bundle: KbRecord[], now?: Date, anchorDrift?: Map<string, KbAnchorDriftEntry[]>): KbAdjudicated[];
 /**
  * Walks a supersession chain to whatever currently stands in its place.
  *
@@ -526,6 +657,14 @@ declare class KbStore {
      * timeouts.
      */
     setStatus(bundlePath: string, conceptId: string, status: KbRecordStatus, actor?: string): Promise<KbRecord>;
+    /**
+     * Replaces a record's anchors wholesale, preserving everything else.
+     *
+     * Wholesale rather than merged: the caller just resolved the anchors it is
+     * writing, so it holds the complete current set, and a merge would keep
+     * stale entries the resolution pass deliberately dropped.
+     */
+    updateAnchors(bundlePath: string, conceptId: string, anchors: KbAnchor[], actor?: string): Promise<KbRecord>;
     /**
      * Appends one `verified[]` event: who checked the record, when, and what the
      * check found. Append-only — prior events are history, and are spread into
@@ -563,8 +702,31 @@ declare class KbStore {
     query(bundlePath: string, text: string, options?: {
         type?: string;
         includeNonCurrent?: boolean;
+        repoRoot?: string;
     }): Promise<KbAdjudicated[]>;
     private rank;
+    /**
+     * Anchor drift over the records about to be handed back. Like the search
+     * index, this is an enrichment: a filesystem failure degrades to "no drift
+     * reported" rather than failing the read. Anchors without a stored hash are
+     * skipped inside `detectAnchorDrift`, so a base nobody has stamped pays no
+     * fs cost here. `repoRoot` defaults to the working directory — the CLI runs
+     * at the repo root, and the MCP server's cwd is the workspace.
+     *
+     * Public because `doctor` needs the same map with the same degradation: a
+     * sweep that failed to read the tree should report no drift, not fail.
+     *
+     * When no root was given and not one anchored file was found, the finding is
+     * discarded. A base read from somewhere other than the tree it describes
+     * misses every file at once, and that shape is far likelier to be a wrong
+     * default root than a repository where every anchored file was deleted on
+     * the same day. Reporting it would put a drift warning on every record in
+     * the base, which teaches a reader to ignore the warning — the one outcome
+     * worse than not having it. One file found anywhere makes the root
+     * plausible, and the misses become findings again; an explicit `repoRoot` is
+     * taken at its word either way.
+     */
+    detectDrift(records: KbRecord[], repoRoot?: string): Promise<Map<string, KbAnchorDriftEntry[]> | undefined>;
     /**
      * The whole base, adjudicated, when it is small enough to hand over.
      *
@@ -599,6 +761,7 @@ declare class KbStore {
         budgetTokens?: number;
         type?: string;
         all?: boolean;
+        repoRoot?: string;
     }): Promise<KbLoadResult>;
     /** How a position was arrived at, as a timeline. See `trace.ts`. */
     trace(bundlePath: string, seedId: string, options?: KbTraceOptions): Promise<KbTraceStep[]>;
@@ -842,6 +1005,11 @@ declare const composeInputSchema: z.ZodObject<{
     anchors: z.ZodOptional<z.ZodArray<z.ZodObject<{
         file: z.ZodString;
         symbol: z.ZodOptional<z.ZodString>;
+        repo: z.ZodOptional<z.ZodString>;
+        ref: z.ZodOptional<z.ZodString>;
+        hash: z.ZodOptional<z.ZodString>;
+        resolved_at: z.ZodOptional<z.ZodString>;
+        lines: z.ZodOptional<z.ZodNumber>;
     }, z.core.$strict>>>;
     sources: z.ZodOptional<z.ZodArray<z.ZodObject<{
         id: z.ZodString;
@@ -1281,9 +1449,10 @@ declare function validateBundle(records: KbRecord[]): KbValidationProblem[];
  * decay silently, because a stale record reads exactly like a live one and a
  * question nobody answered reads exactly like one nobody asked.
  *
- * Grouped and counted rather than merged into one list: the seven checks are
- * seven different repairs — re-verify, re-date, answer, link, or supersede —
- * and a flat list of "problems" would leave the reader sorting them again.
+ * Grouped and counted rather than merged into one list: the eight checks are
+ * eight different repairs — re-verify, re-date, answer, link, supersede, or
+ * re-anchor — and a flat list of "problems" would leave the reader sorting
+ * them again.
  *
  * Every group is emitted even when empty. A check that found nothing and a
  * check that never ran look identical in a report that only lists findings,
@@ -1292,7 +1461,7 @@ declare function validateBundle(records: KbRecord[]): KbValidationProblem[];
 declare const DEFAULT_EXPIRING_DAYS = 30;
 declare const DEFAULT_UNVERIFIED_DAYS = 90;
 declare const DEFAULT_AGING_DAYS = 90;
-declare const KB_DOCTOR_CHECKS: readonly ["expired", "expiring", "unverified", "aging", "orphaned", "broken-supersession", "superseded-but-cited"];
+declare const KB_DOCTOR_CHECKS: readonly ["expired", "expiring", "unverified", "aging", "orphaned", "broken-supersession", "superseded-but-cited", "drifted"];
 type KbDoctorCheck = (typeof KB_DOCTOR_CHECKS)[number];
 type KbDoctorFinding = {
     conceptId: string;
@@ -1317,7 +1486,7 @@ type KbDoctorReport = {
     recordCount: number;
     thresholds: KbDoctorThresholds;
     counts: Record<KbDoctorCheck, number>;
-    /** All seven, in `KB_DOCTOR_CHECKS` order, empty ones included. */
+    /** All eight, in `KB_DOCTOR_CHECKS` order, empty ones included. */
     groups: KbDoctorGroup[];
     findingCount: number;
     healthy: boolean;
@@ -1330,6 +1499,13 @@ type KbDoctorOptions = {
     /** How long `open` or `proposed` may stand before `aging` reports it. */
     agingDays?: number;
     now?: Date;
+    /**
+     * Anchor drift, precomputed by the caller. `doctor` stays pure and sync for
+     * the same reason `adjudicate` does — the filesystem work of re-resolving
+     * anchors belongs to `detectAnchorDrift`, and a sweep with no map simply
+     * reports the `drifted` check as clean rather than half-running it.
+     */
+    anchorDrift?: Map<string, KbAnchorDriftEntry[]>;
 };
 declare function doctor(bundle: KbRecord[], options?: KbDoctorOptions): KbDoctorReport;
 
@@ -1377,6 +1553,11 @@ declare const decisionInputSchema: z.ZodObject<{
     anchors: z.ZodOptional<z.ZodArray<z.ZodObject<{
         file: z.ZodString;
         symbol: z.ZodOptional<z.ZodString>;
+        repo: z.ZodOptional<z.ZodString>;
+        ref: z.ZodOptional<z.ZodString>;
+        hash: z.ZodOptional<z.ZodString>;
+        resolved_at: z.ZodOptional<z.ZodString>;
+        lines: z.ZodOptional<z.ZodNumber>;
     }, z.core.$strict>>>;
     verify: z.ZodOptional<z.ZodArray<z.ZodString>>;
     relatedConceptIds: z.ZodOptional<z.ZodArray<z.ZodString>>;
@@ -1611,4 +1792,4 @@ declare function parseMarkdownWithFrontmatter<S extends z.ZodType>(text: string,
     frontmatter: ReturnType<S["safeParse"]>;
 };
 
-export { BaseError, CONTEXT_BEGIN, CONTEXT_END, CONTEXT_PROFILES, type ComposeInput, type ComposedRecord, DECISION_TYPE, DEFAULT_AGING_DAYS, DEFAULT_EXPIRING_DAYS, DEFAULT_LOAD_BUDGET, DEFAULT_PACK_HOPS, DEFAULT_PACK_MAX_NODES, DEFAULT_UNVERIFIED_DAYS, type DecisionInput, type DiffFile, type DiffHunk, type DiffMatch, type ErrorDetails, type ErrorProps, ErrorTypes, Fault, INDEX_FILE, KB_COMMANDS, KB_COMMANDS_BY_NAME, KB_CONCEPT_ID_PATTERN, KB_CONFIDENCES, KB_DIR, KB_DOCTOR_CHECKS, KB_EDGE_KINDS, KB_MATERIALITIES, KB_RECORD_STATUSES, KB_RECORD_TYPES, KB_SLUG_PATTERN, type KbActorStamp, type KbAdjudicated, type KbAnchor, 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, KbInvalidConceptIdError, 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, type KbValidationProblem, type KbVerifiedEvent, type KbWarning, KbWriteConflictError, type KbWriteInput, LOG_FILE, type MatchOptions, NO_DECISION_SLUG, PINS_FILE, PINS_LOCAL_FILE, PIN_LAYERS, type QmdModule, RECORD_TYPES, SEARCH_INDEX_FILE, type SearchHit, type SearchOptions, type SymbolRange, TRACE_EDGES, adjudicate, assertBaseNotFrozen, buildContext, catalog, composeDecisionRecord, composeInputSchema, composeNoDecisionRecord, composeRecord, contextProfileBudgets, createKbMcpServer, decisionInputSchema, doctor, edgeNeighbours, indexIsStale, isKbRecordType, isNoDecisionRecord, kbActorStampSchema, kbAnchorSchema, kbConceptIdSchema, kbJsonSchemas, kbLogEntrySchema, kbRecordFrontmatterSchema, kbSourceSchema, kbVerifiedEventSchema, listPins, loadQmd, matchToDiff, mergedContextBudgets, neighbours, pack, parseLog, parseMarkdownWithFrontmatter, pinBase, readMergedPins, readPinsLayer, renderCatalogLine, renderIndex, renderIndexLine, renderLogEntry, resolveHeads, resolveHits, resolvePinPath, runKbCli, runKbMcpServer, searchBase, selectDecisions, splitMarkdownFrontmatter, stringifyMarkdownWithFrontmatter, syncInstructions, toHookJson, trace, unpinBase, validateBundle };
+export { type AnchorResolver, BaseError, CONTEXT_BEGIN, CONTEXT_END, CONTEXT_PROFILES, type ComposeInput, type ComposedRecord, DECISION_TYPE, DEFAULT_AGING_DAYS, DEFAULT_EXPIRING_DAYS, DEFAULT_LOAD_BUDGET, DEFAULT_PACK_HOPS, DEFAULT_PACK_MAX_NODES, DEFAULT_UNVERIFIED_DAYS, type DecisionInput, type DiffFile, type DiffHunk, type DiffMatch, type ErrorDetails, type ErrorProps, ErrorTypes, Fault, INDEX_FILE, KB_COMMANDS, KB_COMMANDS_BY_NAME, KB_CONCEPT_ID_PATTERN, KB_CONFIDENCES, KB_DIR, KB_DOCTOR_CHECKS, KB_EDGE_KINDS, KB_MATERIALITIES, KB_RECORD_STATUSES, KB_RECORD_TYPES, KB_SLUG_PATTERN, type KbActorStamp, type KbAdjudicated, type KbAnchor, type KbAnchorDriftEntry, 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, KbInvalidConceptIdError, 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, type KbValidationProblem, type KbVerifiedEvent, type KbWarning, KbWriteConflictError, type KbWriteInput, LOG_FILE, type MatchOptions, NO_DECISION_SLUG, PINS_FILE, PINS_LOCAL_FILE, PIN_LAYERS, type QmdModule, RECORD_TYPES, type ResolvedSymbol, SEARCH_INDEX_FILE, type SearchHit, type SearchOptions, type SymbolRange, TRACE_EDGES, adjudicate, anchorFilePath, assertBaseNotFrozen, buildContext, catalog, composeDecisionRecord, composeInputSchema, composeNoDecisionRecord, composeRecord, contextProfileBudgets, createKbMcpServer, decisionInputSchema, detectAnchorDrift, doctor, edgeNeighbours, hashAnchorText, indexIsStale, isKbRecordType, isNoDecisionRecord, kbActorStampSchema, kbAnchorSchema, kbConceptIdSchema, kbJsonSchemas, kbLogEntrySchema, kbRecordFrontmatterSchema, kbSourceSchema, kbVerifiedEventSchema, listPins, loadQmd, matchToDiff, mergedContextBudgets, neighbours, pack, parseLog, parseMarkdownWithFrontmatter, pinBase, readMergedPins, readPinsLayer, regexResolver, renderCatalogLine, renderIndex, renderIndexLine, renderLogEntry, resolveAnchor, resolveHeads, resolveHits, resolvePinPath, runKbCli, runKbMcpServer, searchBase, selectDecisions, splitMarkdownFrontmatter, stringifyMarkdownWithFrontmatter, syncInstructions, toHookJson, trace, unpinBase, validateBundle };

package/dist/index.d.ts

@@ -47,13 +47,29 @@ 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. A later
- * pass resolves symbols to line ranges once the change has settled, and records
- * that resolution as a `verified[]` entry.
+ * `OrderService.cancel` survives every edit that does not rename it. Once the
+ * change settles, a resolution pass (`anchor-resolver.ts`) 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
+ * stored values. `lines` exists because the anchor keeps a hash, not the text:
+ * without the line count at hash time, a drift report could say "changed" but
+ * never how much.
+ *
+ * `repo` and `ref` say *which* code, for bases that describe more than one
+ * repository. They are author-owned identity: a resolver stamps `hash`,
+ * `lines`, and `resolved_at`, and never writes these two. Both are optional and
+ * independent of each other, so every anchor written before they existed stays
+ * valid.
  */
 declare const kbAnchorSchema: z.ZodObject<{
     file: z.ZodString;
     symbol: z.ZodOptional<z.ZodString>;
+    repo: z.ZodOptional<z.ZodString>;
+    ref: z.ZodOptional<z.ZodString>;
+    hash: z.ZodOptional<z.ZodString>;
+    resolved_at: z.ZodOptional<z.ZodString>;
+    lines: z.ZodOptional<z.ZodNumber>;
 }, z.core.$strict>;
 declare const KB_RECORD_TYPES: readonly ["fact", "requirement", "constraint", "decision", "assumption", "open-question", "risk", "contract", "flow", "affected-system", "test-obligation", "source-note"];
 type KbRecordType = (typeof KB_RECORD_TYPES)[number];
@@ -103,6 +119,11 @@ declare const kbRecordFrontmatterSchema: z.ZodObject<{
     strauss_anchors: z.ZodOptional<z.ZodArray<z.ZodObject<{
         file: z.ZodString;
         symbol: z.ZodOptional<z.ZodString>;
+        repo: z.ZodOptional<z.ZodString>;
+        ref: z.ZodOptional<z.ZodString>;
+        hash: z.ZodOptional<z.ZodString>;
+        resolved_at: z.ZodOptional<z.ZodString>;
+        lines: z.ZodOptional<z.ZodNumber>;
     }, z.core.$strict>>>;
     strauss_verify: z.ZodOptional<z.ZodArray<z.ZodString>>;
     strauss_status: z.ZodDefault<z.ZodEnum<{
@@ -145,6 +166,104 @@ type KbRecord = {
     body: string;
 };
 
+/**
+ * Resolves symbolic anchors to text and detects drift against stored hashes.
+ *
+ * Resolvers are pure — source string in, range out; only the file readers touch
+ * disk. Any shape the lexer cannot handle confidently returns `null` and is
+ * reported `unresolved` rather than guessed at.
+ */
+type ResolvedSymbol = {
+    text: string;
+    /** 1-based, inclusive. */
+    startLine: number;
+    endLine: number;
+};
+interface AnchorResolver {
+    name: string;
+    resolve(source: string, symbol: string): ResolvedSymbol | null;
+}
+/** 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"
+/**
+ * The anchor names a repository this root is not. Expected rather than
+ * wrong — a base describing several repositories resolves against one tree
+ * at a time — so it is never a drift finding and never reaches a reader as
+ * a warning. Multi-root resolution is SAA-709.
+ */
+ | "foreign-repo";
+/**
+ * v1 heuristic resolver. A dotted symbol like `OrderService.cancel` matches on
+ * its last segment, with the parent used to scope the search: a candidate
+ * counts only if the parent name appears in the fifty lines above it, when any
+ * candidate satisfies that at all.
+ *
+ * Deterministic, and ambiguity is not resolved by guessing — two lines of
+ * equally good shape mean the resolver cannot tell which one the record meant,
+ * and it says so by returning `null`.
+ */
+declare const regexResolver: AnchorResolver;
+/** CRLF normalized to LF before hashing, so checkout style cannot read as drift. */
+declare function hashAnchorText(text: string): string;
+/**
+ * An anchor without a symbol is about the whole file; with one, the resolver
+ * decides. Source newlines are normalized first so line counts and hashes
+ * agree with `hashAnchorText`.
+ *
+ * A file's last line is the last line with content: a trailing newline is a
+ * terminator, not an empty line, and counting it would have made every
+ * whole-file anchor's `lines` one larger than the file.
+ */
+declare function resolveAnchor(source: string, anchor: KbAnchor, resolver?: AnchorResolver): ResolvedSymbol | null;
+type KbAnchorDriftEntry = {
+    file: string;
+    symbol?: string;
+    state: "match" | "drifted" | "unresolved";
+    storedHash: string;
+    currentHash?: string;
+    /** `null` when the anchor recorded no `lines` — size unknown, not zero. */
+    diffSize: number | null;
+    reason?: AnchorUnresolvedReason;
+};
+/**
+ * An anchor's `file` must stay inside the repository root — a record points
+ * at code, not at arbitrary files on the machine reading it. Bundles are
+ * data, so a traversal or absolute path here is untrusted input, not a bug
+ * in the caller. Returns the resolved path, or `null` when it escapes.
+ *
+ * Lexical only, and therefore not the whole containment check: see
+ * `readAnchorFile`, which re-tests the real path after following symlinks.
+ */
+declare function anchorFilePath(repoRoot: string, file: string): string | null;
+type AnchorRead = {
+    ok: true;
+    source: string;
+} | {
+    ok: false;
+    reason: AnchorUnresolvedReason;
+};
+type AnchorFileReader = (file: string) => Promise<AnchorRead>;
+/**
+ * Re-resolves every hash-carrying anchor and compares against the stored hash.
+ *
+ * Anchors without a `hash` are skipped; one naming another repository is
+ * reported `foreign-repo` and never read, and `origin` is asked for once per
+ * run, only when some anchor declares a `repo`. A missing file or unresolvable
+ * symbol is a finding (`unresolved`), never a throw. Each distinct file is read
+ * once per run; all checked entries are returned per record, callers filter.
+ *
+ * Three phases: collect the checkable anchors, read their distinct files with
+ * a bounded pool, then resolve and hash in record order — so the output does
+ * not depend on which read finished first.
+ */
+declare function detectAnchorDrift(records: KbRecord[], options?: {
+    repoRoot?: string;
+    resolver?: AnchorResolver;
+    concurrency?: number;
+    /** Test seam: replaces the disk reader. */
+    reader?: AnchorFileReader;
+}): Promise<Map<string, KbAnchorDriftEntry[]>>;
+
 /**
  * Why a matched record must not be read as a plain answer.
  *
@@ -189,6 +308,18 @@ type KbWarning =
     staleAfter: string;
 } | {
     kind: "unverified";
+}
+/** The code this record anchors to has changed since its hash was recorded —
+ *  the record may describe code that no longer exists in that form. */
+ | {
+    kind: "drifted";
+    anchors: {
+        file: string;
+        symbol?: string;
+        /** `null` when the anchor recorded no line count — size unknown. */
+        diffSize: number | null;
+        reason?: string;
+    }[];
 };
 type KbStanding = "current" | "superseded" | "rejected" | "unsettled" | "open";
 type KbAdjudicated = {
@@ -205,7 +336,7 @@ type KbAdjudicated = {
  * invisible: the caller cannot tell it missed anything, so a dropped record is
  * worse than a flagged one — it turns a knowable gap into an unknowable one.
  */
-declare function adjudicate(hits: KbRecord[], bundle: KbRecord[], now?: Date): KbAdjudicated[];
+declare function adjudicate(hits: KbRecord[], bundle: KbRecord[], now?: Date, anchorDrift?: Map<string, KbAnchorDriftEntry[]>): KbAdjudicated[];
 /**
  * Walks a supersession chain to whatever currently stands in its place.
  *
@@ -526,6 +657,14 @@ declare class KbStore {
      * timeouts.
      */
     setStatus(bundlePath: string, conceptId: string, status: KbRecordStatus, actor?: string): Promise<KbRecord>;
+    /**
+     * Replaces a record's anchors wholesale, preserving everything else.
+     *
+     * Wholesale rather than merged: the caller just resolved the anchors it is
+     * writing, so it holds the complete current set, and a merge would keep
+     * stale entries the resolution pass deliberately dropped.
+     */
+    updateAnchors(bundlePath: string, conceptId: string, anchors: KbAnchor[], actor?: string): Promise<KbRecord>;
     /**
      * Appends one `verified[]` event: who checked the record, when, and what the
      * check found. Append-only — prior events are history, and are spread into
@@ -563,8 +702,31 @@ declare class KbStore {
     query(bundlePath: string, text: string, options?: {
         type?: string;
         includeNonCurrent?: boolean;
+        repoRoot?: string;
     }): Promise<KbAdjudicated[]>;
     private rank;
+    /**
+     * Anchor drift over the records about to be handed back. Like the search
+     * index, this is an enrichment: a filesystem failure degrades to "no drift
+     * reported" rather than failing the read. Anchors without a stored hash are
+     * skipped inside `detectAnchorDrift`, so a base nobody has stamped pays no
+     * fs cost here. `repoRoot` defaults to the working directory — the CLI runs
+     * at the repo root, and the MCP server's cwd is the workspace.
+     *
+     * Public because `doctor` needs the same map with the same degradation: a
+     * sweep that failed to read the tree should report no drift, not fail.
+     *
+     * When no root was given and not one anchored file was found, the finding is
+     * discarded. A base read from somewhere other than the tree it describes
+     * misses every file at once, and that shape is far likelier to be a wrong
+     * default root than a repository where every anchored file was deleted on
+     * the same day. Reporting it would put a drift warning on every record in
+     * the base, which teaches a reader to ignore the warning — the one outcome
+     * worse than not having it. One file found anywhere makes the root
+     * plausible, and the misses become findings again; an explicit `repoRoot` is
+     * taken at its word either way.
+     */
+    detectDrift(records: KbRecord[], repoRoot?: string): Promise<Map<string, KbAnchorDriftEntry[]> | undefined>;
     /**
      * The whole base, adjudicated, when it is small enough to hand over.
      *
@@ -599,6 +761,7 @@ declare class KbStore {
         budgetTokens?: number;
         type?: string;
         all?: boolean;
+        repoRoot?: string;
     }): Promise<KbLoadResult>;
     /** How a position was arrived at, as a timeline. See `trace.ts`. */
     trace(bundlePath: string, seedId: string, options?: KbTraceOptions): Promise<KbTraceStep[]>;
@@ -842,6 +1005,11 @@ declare const composeInputSchema: z.ZodObject<{
     anchors: z.ZodOptional<z.ZodArray<z.ZodObject<{
         file: z.ZodString;
         symbol: z.ZodOptional<z.ZodString>;
+        repo: z.ZodOptional<z.ZodString>;
+        ref: z.ZodOptional<z.ZodString>;
+        hash: z.ZodOptional<z.ZodString>;
+        resolved_at: z.ZodOptional<z.ZodString>;
+        lines: z.ZodOptional<z.ZodNumber>;
     }, z.core.$strict>>>;
     sources: z.ZodOptional<z.ZodArray<z.ZodObject<{
         id: z.ZodString;
@@ -1281,9 +1449,10 @@ declare function validateBundle(records: KbRecord[]): KbValidationProblem[];
  * decay silently, because a stale record reads exactly like a live one and a
  * question nobody answered reads exactly like one nobody asked.
  *
- * Grouped and counted rather than merged into one list: the seven checks are
- * seven different repairs — re-verify, re-date, answer, link, or supersede —
- * and a flat list of "problems" would leave the reader sorting them again.
+ * Grouped and counted rather than merged into one list: the eight checks are
+ * eight different repairs — re-verify, re-date, answer, link, supersede, or
+ * re-anchor — and a flat list of "problems" would leave the reader sorting
+ * them again.
  *
  * Every group is emitted even when empty. A check that found nothing and a
  * check that never ran look identical in a report that only lists findings,
@@ -1292,7 +1461,7 @@ declare function validateBundle(records: KbRecord[]): KbValidationProblem[];
 declare const DEFAULT_EXPIRING_DAYS = 30;
 declare const DEFAULT_UNVERIFIED_DAYS = 90;
 declare const DEFAULT_AGING_DAYS = 90;
-declare const KB_DOCTOR_CHECKS: readonly ["expired", "expiring", "unverified", "aging", "orphaned", "broken-supersession", "superseded-but-cited"];
+declare const KB_DOCTOR_CHECKS: readonly ["expired", "expiring", "unverified", "aging", "orphaned", "broken-supersession", "superseded-but-cited", "drifted"];
 type KbDoctorCheck = (typeof KB_DOCTOR_CHECKS)[number];
 type KbDoctorFinding = {
     conceptId: string;
@@ -1317,7 +1486,7 @@ type KbDoctorReport = {
     recordCount: number;
     thresholds: KbDoctorThresholds;
     counts: Record<KbDoctorCheck, number>;
-    /** All seven, in `KB_DOCTOR_CHECKS` order, empty ones included. */
+    /** All eight, in `KB_DOCTOR_CHECKS` order, empty ones included. */
     groups: KbDoctorGroup[];
     findingCount: number;
     healthy: boolean;
@@ -1330,6 +1499,13 @@ type KbDoctorOptions = {
     /** How long `open` or `proposed` may stand before `aging` reports it. */
     agingDays?: number;
     now?: Date;
+    /**
+     * Anchor drift, precomputed by the caller. `doctor` stays pure and sync for
+     * the same reason `adjudicate` does — the filesystem work of re-resolving
+     * anchors belongs to `detectAnchorDrift`, and a sweep with no map simply
+     * reports the `drifted` check as clean rather than half-running it.
+     */
+    anchorDrift?: Map<string, KbAnchorDriftEntry[]>;
 };
 declare function doctor(bundle: KbRecord[], options?: KbDoctorOptions): KbDoctorReport;
 
@@ -1377,6 +1553,11 @@ declare const decisionInputSchema: z.ZodObject<{
     anchors: z.ZodOptional<z.ZodArray<z.ZodObject<{
         file: z.ZodString;
         symbol: z.ZodOptional<z.ZodString>;
+        repo: z.ZodOptional<z.ZodString>;
+        ref: z.ZodOptional<z.ZodString>;
+        hash: z.ZodOptional<z.ZodString>;
+        resolved_at: z.ZodOptional<z.ZodString>;
+        lines: z.ZodOptional<z.ZodNumber>;
     }, z.core.$strict>>>;
     verify: z.ZodOptional<z.ZodArray<z.ZodString>>;
     relatedConceptIds: z.ZodOptional<z.ZodArray<z.ZodString>>;
@@ -1611,4 +1792,4 @@ declare function parseMarkdownWithFrontmatter<S extends z.ZodType>(text: string,
     frontmatter: ReturnType<S["safeParse"]>;
 };
 
-export { BaseError, CONTEXT_BEGIN, CONTEXT_END, CONTEXT_PROFILES, type ComposeInput, type ComposedRecord, DECISION_TYPE, DEFAULT_AGING_DAYS, DEFAULT_EXPIRING_DAYS, DEFAULT_LOAD_BUDGET, DEFAULT_PACK_HOPS, DEFAULT_PACK_MAX_NODES, DEFAULT_UNVERIFIED_DAYS, type DecisionInput, type DiffFile, type DiffHunk, type DiffMatch, type ErrorDetails, type ErrorProps, ErrorTypes, Fault, INDEX_FILE, KB_COMMANDS, KB_COMMANDS_BY_NAME, KB_CONCEPT_ID_PATTERN, KB_CONFIDENCES, KB_DIR, KB_DOCTOR_CHECKS, KB_EDGE_KINDS, KB_MATERIALITIES, KB_RECORD_STATUSES, KB_RECORD_TYPES, KB_SLUG_PATTERN, type KbActorStamp, type KbAdjudicated, type KbAnchor, 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, KbInvalidConceptIdError, 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, type KbValidationProblem, type KbVerifiedEvent, type KbWarning, KbWriteConflictError, type KbWriteInput, LOG_FILE, type MatchOptions, NO_DECISION_SLUG, PINS_FILE, PINS_LOCAL_FILE, PIN_LAYERS, type QmdModule, RECORD_TYPES, SEARCH_INDEX_FILE, type SearchHit, type SearchOptions, type SymbolRange, TRACE_EDGES, adjudicate, assertBaseNotFrozen, buildContext, catalog, composeDecisionRecord, composeInputSchema, composeNoDecisionRecord, composeRecord, contextProfileBudgets, createKbMcpServer, decisionInputSchema, doctor, edgeNeighbours, indexIsStale, isKbRecordType, isNoDecisionRecord, kbActorStampSchema, kbAnchorSchema, kbConceptIdSchema, kbJsonSchemas, kbLogEntrySchema, kbRecordFrontmatterSchema, kbSourceSchema, kbVerifiedEventSchema, listPins, loadQmd, matchToDiff, mergedContextBudgets, neighbours, pack, parseLog, parseMarkdownWithFrontmatter, pinBase, readMergedPins, readPinsLayer, renderCatalogLine, renderIndex, renderIndexLine, renderLogEntry, resolveHeads, resolveHits, resolvePinPath, runKbCli, runKbMcpServer, searchBase, selectDecisions, splitMarkdownFrontmatter, stringifyMarkdownWithFrontmatter, syncInstructions, toHookJson, trace, unpinBase, validateBundle };
+export { type AnchorResolver, BaseError, CONTEXT_BEGIN, CONTEXT_END, CONTEXT_PROFILES, type ComposeInput, type ComposedRecord, DECISION_TYPE, DEFAULT_AGING_DAYS, DEFAULT_EXPIRING_DAYS, DEFAULT_LOAD_BUDGET, DEFAULT_PACK_HOPS, DEFAULT_PACK_MAX_NODES, DEFAULT_UNVERIFIED_DAYS, type DecisionInput, type DiffFile, type DiffHunk, type DiffMatch, type ErrorDetails, type ErrorProps, ErrorTypes, Fault, INDEX_FILE, KB_COMMANDS, KB_COMMANDS_BY_NAME, KB_CONCEPT_ID_PATTERN, KB_CONFIDENCES, KB_DIR, KB_DOCTOR_CHECKS, KB_EDGE_KINDS, KB_MATERIALITIES, KB_RECORD_STATUSES, KB_RECORD_TYPES, KB_SLUG_PATTERN, type KbActorStamp, type KbAdjudicated, type KbAnchor, type KbAnchorDriftEntry, 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, KbInvalidConceptIdError, 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, type KbValidationProblem, type KbVerifiedEvent, type KbWarning, KbWriteConflictError, type KbWriteInput, LOG_FILE, type MatchOptions, NO_DECISION_SLUG, PINS_FILE, PINS_LOCAL_FILE, PIN_LAYERS, type QmdModule, RECORD_TYPES, type ResolvedSymbol, SEARCH_INDEX_FILE, type SearchHit, type SearchOptions, type SymbolRange, TRACE_EDGES, adjudicate, anchorFilePath, assertBaseNotFrozen, buildContext, catalog, composeDecisionRecord, composeInputSchema, composeNoDecisionRecord, composeRecord, contextProfileBudgets, createKbMcpServer, decisionInputSchema, detectAnchorDrift, doctor, edgeNeighbours, hashAnchorText, indexIsStale, isKbRecordType, isNoDecisionRecord, kbActorStampSchema, kbAnchorSchema, kbConceptIdSchema, kbJsonSchemas, kbLogEntrySchema, kbRecordFrontmatterSchema, kbSourceSchema, kbVerifiedEventSchema, listPins, loadQmd, matchToDiff, mergedContextBudgets, neighbours, pack, parseLog, parseMarkdownWithFrontmatter, pinBase, readMergedPins, readPinsLayer, regexResolver, renderCatalogLine, renderIndex, renderIndexLine, renderLogEntry, resolveAnchor, resolveHeads, resolveHits, resolvePinPath, runKbCli, runKbMcpServer, searchBase, selectDecisions, splitMarkdownFrontmatter, stringifyMarkdownWithFrontmatter, syncInstructions, toHookJson, trace, unpinBase, validateBundle };