@saasontools/strauss-kb 0.1.19 → 0.1.20

package/dist/index.d.cts

@@ -62,9 +62,58 @@ declare const kbVerifiedEventSchema: z.ZodObject<{
  * independent of each other, so every anchor written before they existed stays
  * valid.
  */
+/**
+ * An explicit line range, 1-based and inclusive. Author-owned: a resolver
+ * hashes it but never moves it.
+ */
+declare const kbAnchorSpanSchema: z.ZodObject<{
+    start: z.ZodNumber;
+    end: z.ZodNumber;
+}, z.core.$strict>;
 declare const kbAnchorSchema: z.ZodObject<{
     file: z.ZodString;
     symbol: z.ZodOptional<z.ZodString>;
+    span: z.ZodOptional<z.ZodObject<{
+        start: z.ZodNumber;
+        end: z.ZodNumber;
+    }, z.core.$strict>>;
+    side: z.ZodOptional<z.ZodEnum<{
+        old: "old";
+        new: "new";
+    }>>;
+    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<{
+        span: "span";
+        "tree-sitter": "tree-sitter";
+        regex: "regex";
+    }>>;
+}, z.core.$strict>;
+/**
+ * The anchor rules a resolver cannot settle for itself.
+ *
+ * Write-side only, like `kbVerifiedEventSchema`: the frontmatter keeps parsing
+ * with `kbAnchorSchema`, so a hand-edited defect is a `kb_validate` finding
+ * rather than a record that silently vanishes from `list()`.
+ */
+declare const kbAnchorWriteSchema: z.ZodObject<{
+    file: z.ZodString;
+    symbol: z.ZodOptional<z.ZodString>;
+    span: z.ZodOptional<z.ZodObject<{
+        start: z.ZodNumber;
+        end: z.ZodNumber;
+    }, z.core.$strict>>;
+    side: z.ZodOptional<z.ZodEnum<{
+        old: "old";
+        new: "new";
+    }>>;
     repo: z.ZodOptional<z.ZodString>;
     ref: z.ZodOptional<z.ZodString>;
     hash: z.ZodOptional<z.ZodString>;
@@ -75,6 +124,7 @@ declare const kbAnchorSchema: z.ZodObject<{
     resolved_at: z.ZodOptional<z.ZodString>;
     lines: z.ZodOptional<z.ZodNumber>;
     resolver: z.ZodOptional<z.ZodEnum<{
+        span: "span";
         "tree-sitter": "tree-sitter";
         regex: "regex";
     }>>;
@@ -143,6 +193,14 @@ declare const kbRecordFrontmatterSchema: z.ZodObject<{
     strauss_anchors: z.ZodOptional<z.ZodArray<z.ZodObject<{
         file: z.ZodString;
         symbol: z.ZodOptional<z.ZodString>;
+        span: z.ZodOptional<z.ZodObject<{
+            start: z.ZodNumber;
+            end: z.ZodNumber;
+        }, z.core.$strict>>;
+        side: z.ZodOptional<z.ZodEnum<{
+            old: "old";
+            new: "new";
+        }>>;
         repo: z.ZodOptional<z.ZodString>;
         ref: z.ZodOptional<z.ZodString>;
         hash: z.ZodOptional<z.ZodString>;
@@ -153,6 +211,7 @@ declare const kbRecordFrontmatterSchema: z.ZodObject<{
         resolved_at: z.ZodOptional<z.ZodString>;
         lines: z.ZodOptional<z.ZodNumber>;
         resolver: z.ZodOptional<z.ZodEnum<{
+            span: "span";
             "tree-sitter": "tree-sitter";
             regex: "regex";
         }>>;
@@ -193,6 +252,7 @@ declare const kbRecordFrontmatterSchema: z.ZodObject<{
 type KbSource = z.infer<typeof kbSourceSchema>;
 type KbActorStamp = z.infer<typeof kbActorStampSchema>;
 type KbVerifiedEvent = z.infer<typeof kbVerifiedEventSchema>;
+type KbAnchorSpan = z.infer<typeof kbAnchorSpanSchema>;
 type KbAnchor = z.infer<typeof kbAnchorSchema>;
 type KbLink = z.infer<typeof kbLinkSchema>;
 type KbRecordFrontmatter = z.infer<typeof kbRecordFrontmatterSchema>;
@@ -203,9 +263,6 @@ type KbRecord = {
     body: string;
 };
 
-/** Where bare mirrors live. Overridable so a test never writes to `$HOME`. */
-declare function repoCacheDir(override?: string): string;
-
 /**
  * The vocabulary anchor resolution is reported in.
  *
@@ -219,10 +276,10 @@ type ResolvedSymbol = {
     endLine: number;
 };
 /** Which resolver produced a span. Stamped on the anchor. */
-type AnchorResolverName = "tree-sitter" | "regex";
+type AnchorResolverName = "tree-sitter" | "regex" | "span";
 /**
  * A resolver's verdict. `abstain` ("not my language") and `symbol-not-found`
- * ("nothing I recognize declares this") both pass the symbol down the chain;
+ * ("nothing I recognize declares this") pass the symbol down the chain;
  * `symbol-ambiguous` and `resolver-unavailable` end it, because neither may be
  * answered by a looser resolver guessing.
  */
@@ -235,12 +292,17 @@ type ResolverAttempt = {
 } | {
     kind: "abstain";
 };
+/** What the chain already knows when it calls a resolver. */
+type ResolverAttemptOptions = {
+    /** A resolver that parsed this file already reported `symbol-not-found`. */
+    afterParsedMiss?: boolean;
+};
 interface AnchorResolver {
     name: string;
     /** 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;
+    attempt?(source: string, symbol: string, file?: string, options?: ResolverAttemptOptions): ResolverAttempt;
     resolve(source: string, symbol: string, file?: string): ResolvedSymbol | null;
     /**
      * The span's normalised token stream — comments dropped, runs of whitespace
@@ -267,6 +329,12 @@ type AnchorResolution = {
 type AnchorUnresolvedReason = "file-missing" | "symbol-not-found"
 /** More than one definition carries the name, and guessing is not allowed. */
  | "symbol-ambiguous"
+/** The anchor's `span` runs past the end of the file it names. */
+ | "span-out-of-range"
+/** `side: "old"` with no usable `ref`, or no such path at the rev. */
+ | "ref-unreadable"
+/** The `ref` is not in this clone — a shallow checkout, not deleted code. */
+ | "ref-unavailable"
 /** 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. */
@@ -313,6 +381,8 @@ type KbDriftMovedTo = {
 type KbAnchorDriftEntry = {
     file: string;
     symbol?: string;
+    /** Set only for `side: "old"`: read at `ref`, never from the working tree. */
+    side?: "old";
     state: "match" | "drifted" | "unresolved";
     storedHash: string;
     currentHash?: string;
@@ -345,6 +415,34 @@ type AnchorRead = {
 };
 type AnchorFileReader = (file: string) => Promise<AnchorRead>;
 
+/**
+ * The committed file an old-side anchor names, at its own `ref` and nowhere
+ * else. No history fallback: `side: "old"` asserts one exact tree, so guessing
+ * a nearby commit would answer a question the anchor did not ask.
+ *
+ * A rev this clone does not carry is `ref-unavailable` — unchecked, not
+ * `gone`: a shallow checkout is no evidence the code went away.
+ */
+declare function readFileAtRef(repoRoot: string, anchor: {
+    file: string;
+    ref?: string;
+}): Promise<AnchorRead>;
+/** Where a recovered file came from, so a packet can say how far back it looked. */
+type OldSourceOrigin = 
+/** `git cat-file blob <anchor.ref>:<file>` — the rev the record named. */
+{
+    kind: "ref";
+    ref: string;
+}
+/** The last commit touching the path before `resolved_at`. */
+ | {
+    kind: "history";
+    ref: string;
+};
+
+/** Where bare mirrors live. Overridable so a test never writes to `$HOME`. */
+declare function repoCacheDir(override?: string): string;
+
 /**
  * A foreign anchor's file at one rev. `ref` absent means the remote's default
  * branch — the "current" side of a ref-pinned comparison.
@@ -388,6 +486,8 @@ type AnchorDriftOptions = {
     concurrency?: number;
     /** Test seam: replaces the disk reader. */
     reader?: AnchorFileReader;
+    /** Test seam: replaces the committed-side git read. */
+    readAtRef?: typeof readFileAtRef;
     /** Remote resolution of foreign anchors; `offline` keeps a run off the wire. */
     remote?: RemoteOptions;
     /** Test seam: replaces the remote blob reader. */
@@ -518,9 +618,9 @@ declare function resolveAnchor(source: string, anchor: KbAnchor, resolver?: Anch
  * 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.
+ * not constants or fields), but a resolver that parsed the file and missed
+ * narrows what follows to definition-shaped candidates: never a call site or a
+ * bare mention. `symbol-ambiguous` and `resolver-unavailable` end the chain.
  */
 declare function resolveAnchorSpan(source: string, anchor: KbAnchor, resolvers?: readonly AnchorResolver[]): AnchorResolution;
 /** Loads every chained resolver's per-language assets, once. */
@@ -968,6 +1068,8 @@ type KbLogReadResult = {
         line: number;
         text: string;
     }[];
+    /** Whether the file still carried merge conflict markers. */
+    conflicted: boolean;
 };
 declare function parseLog(raw: string): KbLogReadResult;
 
@@ -1054,6 +1156,13 @@ type KbWriteInput = {
     /** Replace an existing record rather than failing on the collision. */
     overwrite?: boolean;
 };
+/** What a record had to still be for `deleteRecord` to remove it. */
+type KbDeleteExpectation = {
+    tag: string;
+    statuses: readonly KbRecordStatus[];
+};
+/** Whether the delete landed, or the record left that scope first. */
+type KbDeleteOutcome = "deleted" | "changed-since-listing";
 type KbWriteResult = KbRecord & {
     /** Whether this write also marked prior records superseded. */
     action: "created" | "superseded-prior";
@@ -1116,6 +1225,9 @@ declare class KbStore {
      * 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.
+     *
+     * Through the write schema: this is a write, and a defect a hand-edit put in
+     * the frontmatter must not be published back out under an actor stamp.
      */
     updateAnchors(bundlePath: string, conceptId: string, anchors: KbAnchor[], actor?: string): Promise<KbRecord>;
     /**
@@ -1140,6 +1252,15 @@ declare class KbStore {
     supersede(bundlePath: string, conceptId: string, replacementId: string, actor?: string): Promise<KbRecord>;
     /** Resolves an open question, stamping who answered and when. */
     answer(bundlePath: string, conceptId: string, answer: string, actor?: string, at?: string): Promise<KbRecord>;
+    /**
+     * Removes one record, logged as `sweep`. The only path in this store that
+     * deletes — see the specification for the scope that makes it safe.
+     *
+     * `expected` is re-read and re-checked immediately before the unlink, the
+     * compare-and-swap `mutate` makes: a record retagged or moved out of a
+     * terminal status since the caller listed it is reported, not removed.
+     */
+    deleteRecord(bundlePath: string, conceptId: string, expected: KbDeleteExpectation, actor?: string): Promise<KbDeleteOutcome>;
     /**
      * Records matching a text query, each carrying its standing.
      *
@@ -1254,14 +1375,29 @@ declare class KbStore {
      * and the next reader through here settles it.
      */
     readIndex(bundlePath: string): Promise<string>;
+    /**
+     * Drops the derived search index, so the next search rebuilds it.
+     *
+     * `searchBase` re-indexes when a record is newer than the index, which no
+     * deletion makes true — a swept record would stay findable until some other
+     * record was written.
+     */
+    dropSearchIndex(bundlePath: string): Promise<void>;
     /**
      * The log, with unparseable lines reported rather than repaired.
      *
      * The log is the bundle's only artifact that cannot be reconstructed — the
      * records rebuild the index, and the code outlives both, but nothing else
      * knows which agent touched what. So a bad line is surfaced and left alone.
+     * Conflict markers are read past rather than reported per line.
      */
     readLog(bundlePath: string): Promise<ReturnType<typeof parseLog>>;
+    /**
+     * Appends one log entry for a move the store cannot see from one base.
+     * Promotion writes into a target base and has to be legible from the source
+     * base too, where nothing was written.
+     */
+    note(bundlePath: string, entry: Omit<KbLogEntry, "at">): Promise<void>;
     /**
      * `markSuperseded`, tolerant of the two ways it legitimately doesn't land:
      * a missing target (a broken link, legal per compose.ts) or a CAS conflict
@@ -1296,7 +1432,8 @@ declare class KbStore {
     /**
      * Declares union merge for the log, so two worktrees writing the same
      * bundle interleave their `log.jsonl` lines on merge rather than one
-     * side's appends silently losing to git's ordinary line-level merge.
+     * side's appends silently losing to git's ordinary line-level merge — and
+     * marks every store-owned file generated, so GitHub collapses it in a diff.
      *
      * Called from `record` — every path that appends a log line, not just
      * `write` — so a bundle only ever mutated through `setStatus`/`verify`/
@@ -1309,10 +1446,9 @@ declare class KbStore {
      * race and created the file between the `readFile` below and this call,
      * `wx` fails instead of truncating what that writer just wrote, and the
      * failure is swallowed by the catch below same as any other best-effort
-     * miss. A file that exists but declares no merge strategy for the log
-     * gets the line appended, never a wholesale rewrite; one that already
-     * declares any merge strategy — this one or a user's own — is left alone
-     * entirely (see `hasMergeDeclaration`).
+     * miss. A file that exists gets only the lines it lacks appended, never a
+     * wholesale rewrite; an attribute it already sets — this one's value or a
+     * user's own — is left alone (see `missingGitattributesLines`).
      *
      * `readFile` failing is `existing === null` only for `ENOENT` — genuinely
      * missing. Any other error (a permission problem, a transient `EMFILE`,
@@ -1323,12 +1459,12 @@ declare class KbStore {
      * therefore left untouched and reported as a failure like any other.
      *
      * Two processes racing the append branch — both read a file without the
-     * line, both append it — is possible and left unguarded: `appendFile` is
-     * `O_APPEND`, so the result is two copies of the same line rather than a
-     * torn write, and `hasMergeDeclaration` sees a duplicate declaration as
-     * "already declared" on the next call. A cheap-to-detect, harmless-to-
-     * leave residue, not a reason to add a cross-process lock (see
-     * `ARCHITECTURE.md`'s rejection of one for the same trade on records).
+     * lines, both append them — is possible and left unguarded: `appendFile` is
+     * `O_APPEND`, so the result is two copies of the same lines rather than a
+     * torn write, and the next call sees a duplicate declaration as "already
+     * declared". A cheap-to-detect, harmless-to-leave residue, not a reason to
+     * add a cross-process lock (see `ARCHITECTURE.md`'s rejection of one for
+     * the same trade on records).
      *
      * Best-effort, like the log append it precedes: failing to write this
      * file must not fail the mutation it guards.
@@ -1364,9 +1500,15 @@ declare enum Fault {
 /** Machine-readable discriminant, stable across message rewording. */
 declare enum ErrorTypes {
     KbRecordAlreadyExists = "KbRecordAlreadyExists",
+    KbClassifyInput = "KbClassifyInput",
     KbInvalidConceptId = "KbInvalidConceptId",
+    KbMatchInput = "KbMatchInput",
     KbMissingFlagValue = "KbMissingFlagValue",
     KbPackBudgetExceeded = "KbPackBudgetExceeded",
+    KbPromoteCollision = "KbPromoteCollision",
+    KbPromoteSelf = "KbPromoteSelf",
+    KbPromoteStanding = "KbPromoteStanding",
+    KbPromoteStopped = "KbPromoteStopped",
     KbRecordNotFound = "KbRecordNotFound",
     KbSelfVerification = "KbSelfVerification",
     KbStampBaselineUnreadable = "KbStampBaselineUnreadable",
@@ -1460,6 +1602,35 @@ declare class KbMissingFlagValueError extends BaseError {
     readonly flag: string;
     constructor(flag: string);
 }
+/** `classify` invoked with no diff it could read, or one it could not parse. */
+declare class KbClassifyInputError extends BaseError {
+    readonly reason: string;
+    constructor(reason: string);
+}
+/** The target base already holds one of the records. Refused for the whole run. */
+declare class KbPromoteCollisionError extends BaseError {
+    readonly conceptId: string;
+    readonly to: string;
+    constructor(conceptId: string, to: string);
+}
+/** Promotion carries a record's standing, so a withdrawn one may not be copied. */
+declare class KbPromoteStandingError extends BaseError {
+    readonly conceptId: string;
+    readonly standing: string;
+    constructor(conceptId: string, standing: string);
+}
+/** Source and target are the same base: the run would rewrite its own records. */
+declare class KbPromoteSelfError extends BaseError {
+    readonly to: string;
+    constructor(to: string);
+}
+/** A write failed after earlier ones landed; `landed` is what the target now holds. */
+declare class KbPromoteStoppedError extends BaseError {
+    readonly conceptId: string;
+    readonly landed: string[];
+    readonly reason: string;
+    constructor(conceptId: string, landed: string[], reason: string);
+}
 declare class KbInvalidConceptIdError extends BaseError {
     constructor(message: string, details: Record<string, string>);
 }
@@ -1635,6 +1806,14 @@ declare const composeInputSchema: z.ZodObject<{
     anchors: z.ZodOptional<z.ZodArray<z.ZodObject<{
         file: z.ZodString;
         symbol: z.ZodOptional<z.ZodString>;
+        span: z.ZodOptional<z.ZodObject<{
+            start: z.ZodNumber;
+            end: z.ZodNumber;
+        }, z.core.$strict>>;
+        side: z.ZodOptional<z.ZodEnum<{
+            old: "old";
+            new: "new";
+        }>>;
         repo: z.ZodOptional<z.ZodString>;
         ref: z.ZodOptional<z.ZodString>;
         hash: z.ZodOptional<z.ZodString>;
@@ -1645,6 +1824,7 @@ declare const composeInputSchema: z.ZodObject<{
         resolved_at: z.ZodOptional<z.ZodString>;
         lines: z.ZodOptional<z.ZodNumber>;
         resolver: z.ZodOptional<z.ZodEnum<{
+            span: "span";
             "tree-sitter": "tree-sitter";
             regex: "regex";
         }>>;
@@ -2021,14 +2201,28 @@ declare function kbJsonSchemas(): Record<string, unknown>;
  * those, not the base.
  */
 type DiffHunk = {
-    /** 1-based, inclusive, in the file's post-change line numbering. */
+    /** 1-based, inclusive, in the numbering of this hunk's `side`. */
     startLine: number;
     endLine: number;
+    /**
+     * Which half of the change these lines number; absent means `new`. An
+     * old-side anchor lands here on the caller's word that its `ref` is this
+     * diff's base rev — nothing compares the two.
+     */
+    side?: "old" | "new";
+    /**
+     * This hunk's own changed lines, markers stripped, where a parser kept them.
+     * Nothing here reads them; a caller classifying content does.
+     */
+    lines?: string[];
 };
 type DiffFile = {
     /** Repo-relative, matching how anchors are written. */
     filePath: string;
     hunks: DiffHunk[];
+    /** Where `git diff -M` says this path came from, and how alike the two are. */
+    renamedFrom?: string;
+    similarity?: number;
 };
 /**
  * A symbol resolved to lines. Supplied by whatever the caller uses to index
@@ -2039,6 +2233,8 @@ type SymbolRange = {
     symbol: string;
     startLine: number;
     endLine: number;
+    /** Which side these lines number; absent means `new`, as on a hunk. */
+    side?: "old" | "new";
 };
 type DiffMatch = {
     filePath: string;
@@ -2059,6 +2255,157 @@ type MatchOptions = {
     now?: Date;
 };
 declare function matchToDiff(files: DiffFile[], records: KbRecord[], options?: MatchOptions): DiffMatch[];
+/** The anchor alone, for a caller that already knows the hunk matched. */
+declare function anchorOnHunk(record: KbRecord, filePath: string, hunk: DiffHunk, symbolRanges?: readonly SymbolRange[] | SymbolRangeIndex): KbAnchor | undefined;
+/** Built once by a caller placing many records on many hunks of one diff. */
+type SymbolRangeIndex = ReadonlyMap<string, SymbolRange[]>;
+declare function symbolRangeIndex(ranges: readonly SymbolRange[]): SymbolRangeIndex;
+
+/**
+ * Every operation a knowledge base exposes, defined once.
+ *
+ * The CLI and the MCP server are both projections of this table. Kept apart
+ * they drift within a day — fourteen commands against six tools — which is the
+ * same failure as a schema restated in prose beside the code that enforces it,
+ * one level up. A command added to the table appears in both surfaces or in
+ * neither, and a test asserts exactly that.
+ *
+ * The two differ only in how arguments arrive: MCP passes an object matching
+ * `input`, while the CLI has to turn positional argv into the same object.
+ * `fromArgv` is that adapter and is the only per-surface code a command needs.
+ *
+ * One file per command in this folder; `index.ts` assembles the table.
+ */
+type KbCommandContext = {
+    store: KbStore;
+    actor: string;
+    now: () => string;
+};
+type KbCommand<Shape extends z.ZodRawShape = z.ZodRawShape> = {
+    /** CLI verb. */
+    name: string;
+    /**
+     * MCP tool name. Absent only for CLI-only plumbing (`sync-instructions`),
+     * which exists to edit files for hooks and instruction blocks rather than to
+     * give an agent a capability — the capability, "get the pinned context
+     * block", is `kb_context`.
+     */
+    tool?: string;
+    /** Argument spelling for CLI usage output. */
+    usage: string;
+    /** Shown to an agent choosing a tool, so it carries the judgment too. */
+    description: string;
+    input: z.ZodObject<Shape>;
+    /**
+     * Positional argv → the same object MCP receives. `bundleExplicit` says
+     * whether `--bundle` was actually passed, for the one command whose meaning
+     * turns on it: `stamp` with no bundle stamps every pinned base.
+     */
+    fromArgv(argv: string[], bundlePath: string, stdin: () => Promise<string>, bundleExplicit?: boolean): Promise<unknown> | unknown;
+    run(ctx: KbCommandContext, input: z.infer<z.ZodObject<Shape>>): Promise<unknown>;
+    /**
+     * A human-readable form of the result, for the CLI. Where it exists the CLI
+     * prints it and `--json` asks for the machine shape instead; MCP always gets
+     * the machine shape, since a tool result is parsed rather than read.
+     *
+     * Separate from `run` rather than rendered inside it — as `pack` does, whose
+     * result *is* a document — because a command whose result is a report needs
+     * both forms: the table for a person, and the object for `failsWhen` and for
+     * anything downstream.
+     */
+    render?(result: unknown): string;
+    /**
+     * Turns a result into a non-zero exit for the CLI. A check that reports a
+     * problem has succeeded as a command and failed as a check, and a shell
+     * caller can only see the difference through the exit code.
+     *
+     * The input comes too, so a command can make the exit conditional on a flag
+     * the caller passed rather than on the result alone.
+     */
+    failsWhen?(result: unknown, input: z.infer<z.ZodObject<Shape>>): boolean;
+};
+
+/** One record on a hunk: enough to decide whether to read it, and no body. */
+type KbMatchRecord = {
+    conceptId: string;
+    type: string;
+    title: string | null;
+    /** Carried on every entry, so a hit is never handed over as a bare match. */
+    standing: KbStanding;
+    status: KbRecordStatus;
+    /** Where the supersession chain ends. Empty while the record still holds. */
+    supersededBy: string[];
+    materiality?: KbRecordFrontmatter["strauss_materiality"];
+    confidence?: KbRecordFrontmatter["strauss_confidence"];
+    tags?: string[];
+    /** The anchor that put this record on this hunk. */
+    anchor?: KbAnchor;
+};
+type KbMatch = {
+    filePath: string;
+    hunk: DiffHunk;
+    /** `symbol` when every record here was placed by a resolved symbol range. */
+    precision: "symbol" | "file";
+    records: KbMatchRecord[];
+};
+
+/**
+ * What a reviewer can skim and what they must read, derived from the diff.
+ *
+ * A closed set: a consumer branches on these nine, and a tenth would arrive
+ * unhandled. `source` is the residue — everything no rule claimed.
+ */
+declare const KB_CLASSES: readonly ["test", "config", "ci", "docs", "lockfile", "generated", "boilerplate", "rename", "source"];
+type KbClass = (typeof KB_CLASSES)[number];
+/** A diff file, plus the head lines a caller could read for it. */
+type KbClassifyFile = DiffFile & {
+    /** The file's first lines at head. Absent falls back to the diff's own. */
+    header?: string[];
+};
+type KbClassifyThresholds = {
+    /** Share of a file's changed lines that must match a boilerplate shape. */
+    boilerplate?: number;
+    /** The `git diff -M` similarity a rename needs before it is called one. */
+    rename?: number;
+};
+declare const DEFAULT_THRESHOLDS: Required<KbClassifyThresholds>;
+type KbClassifyOptions = {
+    /** The base, for the `review:*` overrides. Adjudicated: only current wins. */
+    records?: KbRecord[];
+    /** Without these a symbol anchor covers its whole file rather than a hunk. */
+    symbolRanges?: readonly SymbolRange[];
+    now?: Date;
+    thresholds?: KbClassifyThresholds;
+};
+/** The class and the name of the rule that produced it. */
+type KbVerdict = {
+    class: KbClass;
+    reason: string;
+};
+type KbClassifiedHunk = KbVerdict & {
+    startLine: number;
+    endLine: number;
+};
+type KbClassifiedFile = KbVerdict & {
+    filePath: string;
+    renamedFrom?: string;
+    /** Present only where some hunk's class differs from the file's. */
+    hunks?: KbClassifiedHunk[];
+};
+type KbClassifyResult = {
+    files: KbClassifiedFile[];
+};
+
+/**
+ * What kind of change each file carries.
+ *
+ * Every input is in the diff, so nothing here is written down: a class the KB
+ * stored would be a second copy of an answer the patch already gives, and the
+ * two would disagree the first time a rule changed. The one thing a script
+ * cannot derive — "this output is generated, read its input instead" — is a
+ * record, and it wins over the heuristic.
+ */
+declare function classifyDiff(files: readonly KbClassifyFile[], options?: KbClassifyOptions): KbClassifiedFile[];
 
 /**
  * The edges between records in one bundle, defined once.
@@ -2196,6 +2543,14 @@ type KbAnchorResolverCounts = {
     treeSitter: number;
     /** Includes anchors stamped before resolvers were named. */
     regex: number;
+    /** Author-given line ranges, hashed exactly as written. */
+    span: number;
+    /**
+     * Hashed anchors read at their `ref` rather than the working tree. Counted
+     * beside the resolver buckets and outside `total`: `side` is not a resolver,
+     * and one of these may name a whole file.
+     */
+    oldSide: number;
 };
 type KbDoctorOptions = {
     /** How far ahead `expiring` looks. */
@@ -2259,6 +2614,14 @@ declare const decisionInputSchema: z.ZodObject<{
     anchors: z.ZodOptional<z.ZodArray<z.ZodObject<{
         file: z.ZodString;
         symbol: z.ZodOptional<z.ZodString>;
+        span: z.ZodOptional<z.ZodObject<{
+            start: z.ZodNumber;
+            end: z.ZodNumber;
+        }, z.core.$strict>>;
+        side: z.ZodOptional<z.ZodEnum<{
+            old: "old";
+            new: "new";
+        }>>;
         repo: z.ZodOptional<z.ZodString>;
         ref: z.ZodOptional<z.ZodString>;
         hash: z.ZodOptional<z.ZodString>;
@@ -2269,6 +2632,7 @@ declare const decisionInputSchema: z.ZodObject<{
         resolved_at: z.ZodOptional<z.ZodString>;
         lines: z.ZodOptional<z.ZodNumber>;
         resolver: z.ZodOptional<z.ZodEnum<{
+            span: "span";
             "tree-sitter": "tree-sitter";
             regex: "regex";
         }>>;
@@ -2318,90 +2682,100 @@ declare function isNoDecisionRecord(record: KbRecord): boolean;
 declare function selectDecisions(records: KbRecord[]): KbRecord[];
 
 /**
- * Every operation a knowledge base exposes, defined once.
- *
- * The CLI and the MCP server are both projections of this table. Kept apart
- * they drift within a day — fourteen commands against six tools — which is the
- * same failure as a schema restated in prose beside the code that enforces it,
- * one level up. A command added to the table appears in both surfaces or in
- * neither, and a test asserts exactly that.
- *
- * The two differ only in how arguments arrive: MCP passes an object matching
- * `input`, while the CLI has to turn positional argv into the same object.
- * `fromArgv` is that adapter and is the only per-surface code a command needs.
+ * The command table, assembled from one file per command.
  *
- * One file per command in this folder; `index.ts` assembles the table.
+ * Order is the CLI usage listing's order: the write path, the read path,
+ * base housekeeping, the format, and the workspace pin verbs.
  */
-type KbCommandContext = {
-    store: KbStore;
-    actor: string;
-    now: () => string;
+
+declare const KB_COMMANDS: KbCommand[];
+declare const KB_COMMANDS_BY_NAME: Map<string, KbCommand>;
+
+/**
+ * Listing candidates and promoting share one input, and the two need different
+ * arguments. The rule lives here rather than in `run` so both surfaces refuse
+ * the same call: the CLI before it dispatches, MCP before the tool runs.
+ */
+declare const promoteInputSchema: z.ZodObject<{
+    bundlePath: z.ZodString;
+    conceptIds: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    to: z.ZodOptional<z.ZodString>;
+    source: z.ZodOptional<z.ZodString>;
+    force: z.ZodOptional<z.ZodBoolean>;
+    list: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strip>;
+/** A typed link the copy does not carry, because its target stayed behind. */
+type KbDroppedLink = {
+    target: string;
+    rel: string;
 };
-type KbCommand<Shape extends z.ZodRawShape = z.ZodRawShape> = {
-    /** CLI verb. */
-    name: string;
-    /**
-     * MCP tool name. Absent only for CLI-only plumbing (`sync-instructions`),
-     * which exists to edit files for hooks and instruction blocks rather than to
-     * give an agent a capability — the capability, "get the pinned context
-     * block", is `kb_context`.
-     */
-    tool?: string;
-    /** Argument spelling for CLI usage output. */
-    usage: string;
-    /** Shown to an agent choosing a tool, so it carries the judgment too. */
-    description: string;
-    input: z.ZodObject<Shape>;
-    /**
-     * Positional argv → the same object MCP receives. `bundleExplicit` says
-     * whether `--bundle` was actually passed, for the one command whose meaning
-     * turns on it: `stamp` with no bundle stamps every pinned base.
-     */
-    fromArgv(argv: string[], bundlePath: string, stdin: () => Promise<string>, bundleExplicit?: boolean): Promise<unknown> | unknown;
-    run(ctx: KbCommandContext, input: z.infer<z.ZodObject<Shape>>): Promise<unknown>;
-    /**
-     * A human-readable form of the result, for the CLI. Where it exists the CLI
-     * prints it and `--json` asks for the machine shape instead; MCP always gets
-     * the machine shape, since a tool result is parsed rather than read.
-     *
-     * Separate from `run` rather than rendered inside it — as `pack` does, whose
-     * result *is* a document — because a command whose result is a report needs
-     * both forms: the table for a person, and the object for `failsWhen` and for
-     * anything downstream.
-     */
-    render?(result: unknown): string;
-    /**
-     * Turns a result into a non-zero exit for the CLI. A check that reports a
-     * problem has succeeded as a command and failed as a check, and a shell
-     * caller can only see the difference through the exit code.
-     *
-     * The input comes too, so a command can make the exit conditional on a flag
-     * the caller passed rather than on the result alone.
-     */
-    failsWhen?(result: unknown, input: z.infer<z.ZodObject<Shape>>): boolean;
+type KbPromotedRecord = {
+    conceptId: string;
+    droppedLinks: KbDroppedLink[];
+};
+type KbPromoteCandidate = {
+    conceptId: string;
+    type: string;
+    title: string | null;
+    /** The rule that made it a candidate, in the reader's terms. */
+    why: string;
+};
+type KbPromoteResult = {
+    mode: "list";
+    candidates: KbPromoteCandidate[];
+} | {
+    mode: "promote";
+    to: string;
+    promoted: KbPromotedRecord[];
 };
 
+/** The source entry a promotion adds, replaced rather than repeated on re-promote. */
+declare const PROMOTION_SOURCE_ID = "promoted";
+type KbCarriedRecord = {
+    frontmatter: Omit<KbRecordFrontmatter, "type">;
+    body: string;
+    droppedLinks: KbDroppedLink[];
+};
 /**
- * The command table, assembled from one file per command.
+ * One record as the target base should hold it.
  *
- * Order is the CLI usage listing's order: the write path, the read path,
- * base housekeeping, the format, and the workspace pin verbs.
+ * Frontmatter is carried rather than recomposed: OKF requires a consumer to
+ * preserve keys it does not recognise when round-tripping, and a record written
+ * by another producer would lose them to a rebuild from known fields.
+ */
+declare function carry(record: KbRecord, promoted: ReadonlySet<string>, source?: string): KbCarriedRecord;
+/**
+ * `review` and the `review:<id>` family alike: the target base is not a review
+ * base, so a tag saying which review wrote the record no longer selects
+ * anything there.
  */
+declare function isReviewTag(tag: string): boolean;
 
-declare const KB_COMMANDS: KbCommand[];
-declare const KB_COMMANDS_BY_NAME: Map<string, KbCommand>;
+/**
+ * What in a review base is worth keeping once the change merges. Heuristics over
+ * what a reviewer usually wants; a record they cut is still nameable by hand.
+ * A withdrawn record is not among them — `promote` refuses those outright.
+ */
+declare function promoteCandidates(bundle: KbRecord[]): KbPromoteCandidate[];
 
-/** 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 KbExportedDecision = {
+    conceptId: string;
+    /** File name within the target directory, `NNNN-<slug>.md`. */
+    file: string;
+    /** The ADR's Status line, as adjudication settled it. */
+    status: string;
+};
+/** A file this exporter did not write, holding the name a decision needs. */
+type KbExportForeignFile = {
+    conceptId: string;
+    file: string;
+};
+type KbExportResult = {
+    to: string;
+    format: "madr";
+    exported: KbExportedDecision[];
+    /** Decisions left unwritten because a foreign file already holds their name. */
+    foreign: KbExportForeignFile[];
 };
 
 type MovedSearch = {
@@ -2706,4 +3080,4 @@ declare function parseMarkdownWithFrontmatter<S extends z.ZodType>(text: string,
     frontmatter: ReturnType<S["safeParse"]>;
 };
 
-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 KbTagFilter, 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, matchesTags, 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 };
+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_THRESHOLDS, 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_CLASSES, 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 KbAnchorSpan, type KbBacklink, type KbBacklinksResult, KbBaseFrozenError, type KbCatalogEntry, type KbCatalogResult, type KbClass, type KbClassifiedFile, type KbClassifiedHunk, type KbClassifyFile, KbClassifyInputError, type KbClassifyOptions, type KbClassifyResult, type KbClassifyThresholds, type KbCommand, type KbCommandContext, type KbContextBudgets, type KbContextOptions, type KbContextResult, type KbDoctorCheck, type KbDoctorFinding, type KbDoctorGroup, type KbDoctorOptions, type KbDoctorReport, type KbDoctorThresholds, type KbDroppedLink, type KbEdgeKind, type KbExportForeignFile, type KbExportResult, type KbExportedDecision, 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 KbMatch, type KbMatchRecord, 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 KbPromoteCandidate, KbPromoteCollisionError, type KbPromoteResult, KbPromoteSelfError, KbPromoteStandingError, KbPromoteStoppedError, type KbPromotedRecord, 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 KbTagFilter, type KbTraceEdge, type KbTraceOptions, type KbTraceStep, KbUnknownLinkRelError, type KbValidationProblem, type KbValidationSeverity, type KbVerdict, type KbVerifiedEvent, type KbWarning, KbWriteConflictError, type KbWriteInput, LINK_RELS, LOG_FILE, type MatchOptions, NO_DECISION_SLUG, PINS_FILE, PINS_LOCAL_FILE, PIN_LAYERS, PROMOTION_SOURCE_ID, type QmdModule, RECORD_TYPES, type RemoteAnchorState, type RemoteOptions, type RemoteRead, type ResolvedSymbol, type ResolverAttempt, type ResolverAttemptOptions, SEARCH_INDEX_FILE, type SearchHit, type SearchOptions, type SymbolRange, type SymbolRangeIndex, TRACE_EDGES, TreeSitterResolver, adjudicate, anchorFilePath, anchorOnHunk, assertBaseNotFrozen, backlinks, buildContext, carry, catalog, classifyDiff, 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, isReviewTag, kbActorStampSchema, kbAnchorSchema, kbAnchorSpanSchema, kbAnchorWriteSchema, kbConceptIdSchema, kbJsonSchemas, kbLinkSchema, kbLogEntrySchema, kbRecordFrontmatterSchema, kbSourceSchema, kbVerifiedEventSchema, languageForFile, listPins, loadQmd, matchToDiff, matchesTags, mergedContextBudgets, neighbours, pack, parseLog, parseMarkdownWithFrontmatter, pinBase, prepareResolvers, promoteCandidates, promoteInputSchema, readMergedPins, readPinsLayer, readRemoteAnchors, reassessPacket, regexResolver, renderCatalogLine, renderIndex, renderIndexLine, renderLogEntry, repoCacheDir, resolveAnchor, resolveAnchorSpan, resolveHeads, resolveHits, resolvePinPath, runKbCli, runKbMcpServer, searchBase, selectDecisions, splitMarkdownFrontmatter, stringifyMarkdownWithFrontmatter, symbolRangeIndex, syncInstructions, toHookJson, trace, treeSitterLanguages, unifiedDiff, unpinBase, validateBundle };