@saasontools/strauss-kb 0.1.2 → 0.1.3

package/dist/index.d.ts

@@ -583,6 +583,7 @@ declare const composeInputSchema: z.ZodObject<{
         last_modified: z.ZodOptional<z.ZodString>;
     }, z.core.$loose>>>;
     assumption: z.ZodOptional<z.ZodBoolean>;
+    stale_after: z.ZodOptional<z.ZodString>;
     verify: z.ZodOptional<z.ZodArray<z.ZodString>>;
     tags: z.ZodOptional<z.ZodArray<z.ZodString>>;
     relatedConceptIds: z.ZodOptional<z.ZodArray<z.ZodString>>;
@@ -631,9 +632,260 @@ declare const INDEX_FILE = "INDEX.md";
  * decide what is worth opening, and a list of titles does not answer that.
  */
 declare function renderIndex(records: KbRecord[]): string;
+/**
+ * One record's index line. The single writer of this shape — `context` emits
+ * the same line rather than growing a second index renderer that would drift
+ * from this one.
+ */
+declare function renderIndexLine(record: KbRecord): string;
 /** Whether the stored projection still matches the records it claims to index. */
 declare function indexIsStale(stored: string | null, expected: string): boolean;
 
+/**
+ * Pin manifests, in three layers.
+ *
+ * Pins are workspace state, not base state: they record which bases a session
+ * should be shown at every context birth. The pinned base is never touched —
+ * not even its log — because a base must remain copyable without knowing who
+ * pins it.
+ *
+ * The layers, nearest wins when the same base appears in more than one:
+ *
+ * | layer   | file                                    | for                        |
+ * | ------- | --------------------------------------- | -------------------------- |
+ * | project | <workspace>/.strauss/kb-pins.json       | committed, the team's pins |
+ * | local   | <workspace>/.strauss/kb-pins.local.json | personal, gitignored       |
+ * | user    | ~/.strauss/kb-pins.json                 | personal, every workspace  |
+ *
+ * Every manifest's paths resolve against its own root — the workspace for
+ * project and local, the home directory for user — so each file is portable
+ * with the tree it belongs to. `STRAUSS_KB_USER_ROOT` overrides the user root
+ * (tests, unusual homes).
+ */
+declare const PINS_FILE: string;
+declare const PINS_LOCAL_FILE: string;
+declare const PIN_LAYERS: readonly ["project", "local", "user"];
+type KbPinLayer = (typeof PIN_LAYERS)[number];
+/**
+ * Primary state — it records an intent nothing else holds — but trivially
+ * rewritable, so a full rewrite on change is fine and no append log is needed.
+ * Unknown keys are preserved on rewrite, the same tolerance the record reader
+ * extends to frontmatter it did not write.
+ */
+declare const pinSchema: z.ZodObject<{
+    path: z.ZodString;
+    pinnedAt: z.ZodOptional<z.ZodString>;
+    mode: z.ZodCatch<z.ZodOptional<z.ZodEnum<{
+        full: "full";
+        index: "index";
+    }>>>;
+    profiles: z.ZodCatch<z.ZodOptional<z.ZodArray<z.ZodString>>>;
+    frozen: z.ZodCatch<z.ZodOptional<z.ZodBoolean>>;
+}, z.core.$loose>;
+declare const pinsManifestSchema: z.ZodObject<{
+    pins: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        path: z.ZodString;
+        pinnedAt: z.ZodOptional<z.ZodString>;
+        mode: z.ZodCatch<z.ZodOptional<z.ZodEnum<{
+            full: "full";
+            index: "index";
+        }>>>;
+        profiles: z.ZodCatch<z.ZodOptional<z.ZodArray<z.ZodString>>>;
+        frozen: z.ZodCatch<z.ZodOptional<z.ZodBoolean>>;
+    }, z.core.$loose>>>;
+    context: z.ZodOptional<z.ZodUnknown>;
+}, z.core.$loose>;
+type KbPin = z.infer<typeof pinSchema>;
+type KbPinsManifest = z.infer<typeof pinsManifestSchema>;
+type KbContextBudgets = {
+    budgetTokens?: number;
+    fullUnderTokens?: number;
+};
+/** A pin as the merged view hands it back: entry + where it came from. */
+type KbMergedPin = KbPin & {
+    layer: KbPinLayer;
+    absolutePath: string;
+};
+type KbMergedPins = {
+    /** Effective pins after dedup — nearest layer wins per resolved path. */
+    pins: KbMergedPin[];
+    /** Per-layer manifests that parsed, for budget merging. */
+    manifests: Partial<Record<KbPinLayer, KbPinsManifest>>;
+};
+/** One pinned base, with whether it currently resolves to anything readable. */
+type KbPinStatus = {
+    /** As stored — relative to its layer's root. */
+    path: string;
+    layer: KbPinLayer;
+    pinnedAt: string | null;
+    absolutePath: string;
+    /** The directory exists and yielded at least one parseable record. */
+    valid: boolean;
+    recordCount: number;
+    mode: "full" | "index" | null;
+    profiles: string[] | null;
+    frozen: boolean;
+};
+type KbPinResult = {
+    path: string;
+    layer: KbPinLayer;
+    pinnedAt: string;
+    alreadyPinned: boolean;
+    mode?: "full" | "index";
+    profiles?: string[];
+    frozen?: boolean;
+    /** Set when the path holds no readable records — pinned anyway. */
+    warning?: string;
+};
+type KbPinOptions = {
+    mode?: "full" | "index";
+    profiles?: string[];
+    frozen?: boolean;
+    /** Which manifest to write. Defaults to the committed project layer. */
+    layer?: KbPinLayer;
+};
+
+/**
+ * One manifest's budgets for one profile: the named profile's values over the
+ * manifest's `"default"` entry. What is absent here falls through to the
+ * caller's built-ins — a manifest narrows, it never has to be complete.
+ */
+declare function contextProfileBudgets(manifest: KbPinsManifest, profile?: string): KbContextBudgets;
+/**
+ * Budgets across the layers: user underneath, local over it, project on top —
+ * the committed file is the workspace's word — and explicit flags above all
+ * of this, applied by the caller.
+ */
+declare function mergedContextBudgets(merged: KbMergedPins, profile?: string): KbContextBudgets;
+
+declare class KbPinsMalformedError extends Error {
+    constructor(file: string, cause: string);
+}
+declare class KbBaseFrozenError extends Error {
+    constructor(bundlePath: string, layer: KbPinLayer);
+}
+
+/**
+ * Refuses when a write would land in a base this workspace froze. Called by
+ * every mutating command; a workspace that pinned a base `--frozen` said the
+ * base is concluded, and a quiet write past that would be exactly the silent
+ * drift the pin was meant to stop.
+ */
+declare function assertBaseNotFrozen(workspaceDir: string, bundlePath: string): Promise<void>;
+
+/**
+ * One layer's manifest, or an empty one when the file is missing.
+ *
+ * A malformed file throws rather than being treated as empty: every write path
+ * does a full rewrite, and rewriting over content we could not read would
+ * destroy the one copy of it. Read-only consumers that must stay silent
+ * (`context` from a session hook, the merged reader) skip malformed layers
+ * themselves.
+ */
+declare function readPinsLayer(workspaceDir: string, layer: KbPinLayer): Promise<KbPinsManifest>;
+/** Where a stored pin points, resolved against its layer's root. */
+declare function resolvePinPath(rootDir: string, path: string): string;
+/**
+ * All three layers, merged. A malformed layer is skipped rather than thrown:
+ * this feeds hooks at every session start, and one broken personal file must
+ * not silence the team's pins — `pin`/`unpin` against the broken layer still
+ * refuse loudly.
+ */
+declare function readMergedPins(workspaceDir: string): Promise<KbMergedPins>;
+
+/** Every effective pin across the layers, with whether it points at records. */
+declare function listPins(store: KbStore, workspaceDir: string): Promise<KbPinStatus[]>;
+
+/**
+ * Adds a base to one layer's manifest. Idempotent — re-pinning a pinned path
+ * with no options returns the existing entry untouched, and re-pinning with
+ * `mode`, `profiles`, or `frozen` updates just those fields, which is how a
+ * pin's rendering or writability is changed. A path that is not (yet) a valid
+ * base succeeds with a warning: bases are routinely pinned before they are
+ * populated, the same way records link to records that do not exist yet.
+ */
+declare function pinBase(store: KbStore, workspaceDir: string, bundlePath: string, at: string, options?: KbPinOptions): Promise<KbPinResult>;
+
+/**
+ * Removes a base from every layer that holds it — unpinned means gone, not
+ * "gone from one file and still injected from another". A malformed layer is
+ * skipped (it cannot be rewritten safely); the layers actually touched are
+ * reported.
+ */
+declare function unpinBase(workspaceDir: string, bundlePath: string): Promise<{
+    path: string;
+    removed: boolean;
+    layers: KbPinLayer[];
+}>;
+
+/**
+ * What the hooks ask for by name, so the numbers live in one place and a repo
+ * can override them in its pin manifest rather than editing hook commands.
+ * `session-start` is a fresh window — room for tiny bases to arrive whole.
+ * `compact` competes with a summary for a smaller window — index only.
+ * `turn` is per-turn injection (Antigravity) — same tight stance as compact.
+ */
+declare const CONTEXT_PROFILES: Record<string, KbContextBudgets>;
+type KbContextOptions = {
+    /** Refuse past this. Defaults to 4000 tokens. */
+    budgetTokens?: number;
+    /** Emit bases whose full `load` fits under this as records, not index. 0 = off. */
+    fullUnderTokens?: number;
+    /**
+     * A named budget set. Resolution, most specific wins: explicit options,
+     * then the manifest's `context[profile]` over its `context.default`, then
+     * the built-in profile, then the package defaults. An unknown profile is
+     * not an error — it simply falls through; hooks must never break over a
+     * name.
+     */
+    profile?: string;
+    /**
+     * Where budget pressure is reported outside the block itself: a full pin
+     * that had to degrade to an index, a block that refused. The block already
+     * says both to the agent; this says them to the operator's log.
+     */
+    warn?: (entry: Record<string, unknown>) => void;
+};
+type KbContextResult = {
+    /** The markdown block. Empty when there are no pins — silence, not a stub. */
+    block: string;
+    /** Refused: over budget. The block then lists the bases instead of the index. */
+    refused: boolean;
+    approxTokens: number;
+    budgetTokens: number;
+    bases: {
+        path: string;
+        absolutePath: string;
+        approxTokens: number;
+    }[];
+};
+/**
+ * Builds the block, or a refusal that lists the bases — never a truncation. A
+ * truncated index is indistinguishable from a complete one, so a reader would
+ * take a slice for the whole, which is `load`'s argument one layer up.
+ */
+declare function buildContext(store: KbStore, workspaceDir: string, options?: KbContextOptions): Promise<KbContextResult>;
+/**
+ * The same block in the envelope hook protocols that demand strict JSON on
+ * stdout require:
+ * those protocols treat non-JSON stdout as a violation, where Claude Code and
+ * Codex take plain text. One canonical writer for the block; this is wrapping.
+ */
+declare function toHookJson(block: string, event: string): string;
+declare const CONTEXT_BEGIN = "<!-- strauss-kb:begin -->";
+declare const CONTEXT_END = "<!-- strauss-kb:end -->";
+type KbSyncResult = {
+    file: string;
+    action: "created" | "replaced" | "appended" | "removed" | "unchanged";
+};
+/**
+ * Idempotently plants the block between sentinels in an instruction file
+ * (AGENTS.md, CLAUDE.md). This is how a runtime without a reliable
+ * post-compact hook keeps a refreshable index: the file is re-read where the
+ * conversation is not. Everything outside the sentinels is left alone.
+ */
+declare function syncInstructions(file: string, block: string): Promise<KbSyncResult>;
+
 /**
  * The frontmatter contract, emitted rather than restated.
  *
@@ -762,6 +1014,7 @@ declare const decisionInputSchema: z.ZodObject<{
         author: z.ZodOptional<z.ZodString>;
         last_modified: z.ZodOptional<z.ZodString>;
     }, z.core.$loose>>>;
+    stale_after: z.ZodOptional<z.ZodString>;
     slug: z.ZodString;
     why: z.ZodString;
     anchors: z.ZodOptional<z.ZodArray<z.ZodObject<{
@@ -802,15 +1055,17 @@ 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 list. 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 here appears in both surfaces or in neither, and a
- * test asserts exactly that.
+ * 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;
@@ -820,8 +1075,13 @@ type KbCommandContext = {
 type KbCommand<Shape extends z.ZodRawShape = z.ZodRawShape> = {
     /** CLI verb. */
     name: string;
-    /** MCP tool name. */
-    tool: 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. */
@@ -837,10 +1097,16 @@ type KbCommand<Shape extends z.ZodRawShape = z.ZodRawShape> = {
      */
     failsWhen?(result: unknown): boolean;
 };
-declare const KB_COMMANDS: KbCommand<z.ZodRawShape>[];
-declare const KB_COMMANDS_BY_NAME: Map<string, KbCommand<Readonly<{
-    [k: string]: z.core.$ZodType<unknown, unknown, z.core.$ZodTypeInternals<unknown, unknown>>;
-}>>>;
+
+/**
+ * The command table, assembled from one file per command.
+ *
+ * Order is the CLI usage listing's order: the write path, the read path,
+ * base housekeeping, the format, and the workspace pin verbs.
+ */
+
+declare const KB_COMMANDS: KbCommand[];
+declare const KB_COMMANDS_BY_NAME: Map<string, KbCommand>;
 
 /**
  * A knowledge base's own MCP server, over stdio.
@@ -974,4 +1240,4 @@ declare function parseMarkdownWithFrontmatter<S extends z.ZodType>(text: string,
     frontmatter: ReturnType<S["safeParse"]>;
 };
 
-export { BaseError, type ComposeInput, type ComposedRecord, DECISION_TYPE, 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_MATERIALITIES, KB_RECORD_STATUSES, KB_RECORD_TYPES, KB_SLUG_PATTERN, type KbActorStamp, type KbAdjudicated, type KbAnchor, type KbCommand, type KbCommandContext, KbInvalidConceptIdError, type KbLoadResult, type KbLogEntry, type KbLogReadResult, type KbLogger, type KbRecord, KbRecordAlreadyExistsError, type KbRecordFrontmatter, KbRecordNotFoundError, type KbRecordStatus, type KbRecordType, type KbRecordTypeSpec, type KbSearchLogger, type KbSource, type KbStanding, KbStore, type KbSupersededStub, type KbTraceEdge, type KbTraceOptions, type KbTraceStep, type KbValidationProblem, type KbWarning, KbWriteConflictError, type KbWriteInput, LOG_FILE, type MatchOptions, NO_DECISION_SLUG, type QmdModule, RECORD_TYPES, SEARCH_INDEX_FILE, type SearchHit, type SearchOptions, type SymbolRange, TRACE_EDGES, adjudicate, composeDecisionRecord, composeInputSchema, composeNoDecisionRecord, composeRecord, createKbMcpServer, decisionInputSchema, indexIsStale, isKbRecordType, isNoDecisionRecord, kbActorStampSchema, kbAnchorSchema, kbConceptIdSchema, kbJsonSchemas, kbLogEntrySchema, kbRecordFrontmatterSchema, kbSourceSchema, loadQmd, matchToDiff, parseLog, parseMarkdownWithFrontmatter, renderIndex, renderLogEntry, resolveHeads, resolveHits, runKbCli, runKbMcpServer, searchBase, selectDecisions, splitMarkdownFrontmatter, stringifyMarkdownWithFrontmatter, trace, validateBundle };
+export { BaseError, CONTEXT_BEGIN, CONTEXT_END, CONTEXT_PROFILES, type ComposeInput, type ComposedRecord, DECISION_TYPE, 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_MATERIALITIES, KB_RECORD_STATUSES, KB_RECORD_TYPES, KB_SLUG_PATTERN, type KbActorStamp, type KbAdjudicated, type KbAnchor, KbBaseFrozenError, type KbCommand, type KbCommandContext, type KbContextBudgets, type KbContextOptions, type KbContextResult, KbInvalidConceptIdError, type KbLoadResult, type KbLogEntry, type KbLogReadResult, type KbLogger, type KbMergedPin, type KbMergedPins, 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, type KbSource, type KbStanding, KbStore, type KbSupersededStub, type KbSyncResult, type KbTraceEdge, type KbTraceOptions, type KbTraceStep, type KbValidationProblem, 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, composeDecisionRecord, composeInputSchema, composeNoDecisionRecord, composeRecord, contextProfileBudgets, createKbMcpServer, decisionInputSchema, indexIsStale, isKbRecordType, isNoDecisionRecord, kbActorStampSchema, kbAnchorSchema, kbConceptIdSchema, kbJsonSchemas, kbLogEntrySchema, kbRecordFrontmatterSchema, kbSourceSchema, listPins, loadQmd, matchToDiff, mergedContextBudgets, parseLog, parseMarkdownWithFrontmatter, pinBase, readMergedPins, readPinsLayer, renderIndex, renderIndexLine, renderLogEntry, resolveHeads, resolveHits, resolvePinPath, runKbCli, runKbMcpServer, searchBase, selectDecisions, splitMarkdownFrontmatter, stringifyMarkdownWithFrontmatter, syncInstructions, toHookJson, trace, unpinBase, validateBundle };

package/dist/index.js

@@ -1,12 +1,15 @@
 import {
   runKbCli
-} from "./chunk-KGM34MYU.js";
+} from "./chunk-QLTB77W4.js";
 import {
   createKbMcpServer,
   runKbMcpServer
-} from "./chunk-WFHYWZX5.js";
+} from "./chunk-FSI4Q2FD.js";
 import {
   BaseError,
+  CONTEXT_BEGIN,
+  CONTEXT_END,
+  CONTEXT_PROFILES,
   DECISION_TYPE,
   ErrorTypes,
   Fault,
@@ -20,21 +23,29 @@ import {
   KB_RECORD_STATUSES,
   KB_RECORD_TYPES,
   KB_SLUG_PATTERN,
+  KbBaseFrozenError,
   KbInvalidConceptIdError,
+  KbPinsMalformedError,
   KbRecordAlreadyExistsError,
   KbRecordNotFoundError,
   KbStore,
   KbWriteConflictError,
   LOG_FILE,
   NO_DECISION_SLUG,
+  PINS_FILE,
+  PINS_LOCAL_FILE,
+  PIN_LAYERS,
   RECORD_TYPES,
   SEARCH_INDEX_FILE,
   TRACE_EDGES,
   adjudicate,
+  assertBaseNotFrozen,
+  buildContext,
   composeDecisionRecord,
   composeInputSchema,
   composeNoDecisionRecord,
   composeRecord,
+  contextProfileBudgets,
   decisionInputSchema,
   indexIsStale,
   isKbRecordType,
@@ -46,20 +57,30 @@ import {
   kbLogEntrySchema,
   kbRecordFrontmatterSchema,
   kbSourceSchema,
+  listPins,
   loadQmd,
+  mergedContextBudgets,
   parseLog,
   parseMarkdownWithFrontmatter,
+  pinBase,
+  readMergedPins,
+  readPinsLayer,
   renderIndex,
+  renderIndexLine,
   renderLogEntry,
   resolveHeads,
   resolveHits,
+  resolvePinPath,
   searchBase,
   selectDecisions,
   splitMarkdownFrontmatter,
   stringifyMarkdownWithFrontmatter,
+  syncInstructions,
+  toHookJson,
   trace,
+  unpinBase,
   validateBundle
-} from "./chunk-ZSYSHJVZ.js";
+} from "./chunk-HYNAEAPM.js";
 
 // src/match-diff.ts
 function matchToDiff(files, records, options = {}) {
@@ -142,6 +163,9 @@ function normalize(path) {
 }
 export {
   BaseError,
+  CONTEXT_BEGIN,
+  CONTEXT_END,
+  CONTEXT_PROFILES,
   DECISION_TYPE,
   ErrorTypes,
   Fault,
@@ -155,21 +179,29 @@ export {
   KB_RECORD_STATUSES,
   KB_RECORD_TYPES,
   KB_SLUG_PATTERN,
+  KbBaseFrozenError,
   KbInvalidConceptIdError,
+  KbPinsMalformedError,
   KbRecordAlreadyExistsError,
   KbRecordNotFoundError,
   KbStore,
   KbWriteConflictError,
   LOG_FILE,
   NO_DECISION_SLUG,
+  PINS_FILE,
+  PINS_LOCAL_FILE,
+  PIN_LAYERS,
   RECORD_TYPES,
   SEARCH_INDEX_FILE,
   TRACE_EDGES,
   adjudicate,
+  assertBaseNotFrozen,
+  buildContext,
   composeDecisionRecord,
   composeInputSchema,
   composeNoDecisionRecord,
   composeRecord,
+  contextProfileBudgets,
   createKbMcpServer,
   decisionInputSchema,
   indexIsStale,
@@ -182,21 +214,31 @@ export {
   kbLogEntrySchema,
   kbRecordFrontmatterSchema,
   kbSourceSchema,
+  listPins,
   loadQmd,
   matchToDiff,
+  mergedContextBudgets,
   parseLog,
   parseMarkdownWithFrontmatter,
+  pinBase,
+  readMergedPins,
+  readPinsLayer,
   renderIndex,
+  renderIndexLine,
   renderLogEntry,
   resolveHeads,
   resolveHits,
+  resolvePinPath,
   runKbCli,
   runKbMcpServer,
   searchBase,
   selectDecisions,
   splitMarkdownFrontmatter,
   stringifyMarkdownWithFrontmatter,
+  syncInstructions,
+  toHookJson,
   trace,
+  unpinBase,
   validateBundle
 };
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/match-diff.ts"],"sourcesContent":["import { adjudicate, type KbAdjudicated } from \"./adjudicate.js\";\nimport type { KbAnchor, KbRecord } from \"./kb-record.schema.js\";\n\n/**\n * Which records apply to which part of a change.\n *\n * Takes a structural description of a diff rather than a patch, so this package\n * carries no diff parser: callers already have one, and a knowledge base has no\n * business preferring a particular flavour of unified diff.\n *\n * Deterministic on purpose. Every step here is mechanical — the one judgment,\n * whether a matched record is worth showing a reviewer, is deliberately absent.\n * A model placed here would sit between the reviewer and their diff on every\n * review, to answer a question nobody has yet shown needs asking.\n *\n * Distinct from `load()`, which hands a reader the whole base. That answers\n * \"does anything address this question\"; this answers \"what is attached to this\n * code\", and an anchor is the author's own statement rather than an inference\n * from one. A reader guessing which record relates to a hunk would be guessing\n * at something already written down — and a diff has dozens of hunks, which is\n * dozens of reader calls against microseconds of matching. Where they compose:\n * this narrows a hunk to a few records, and a reader asked to explain them gets\n * those, not the base.\n */\nexport type DiffHunk = {\n  /** 1-based, inclusive, in the file's post-change line numbering. */\n  startLine: number;\n  endLine: number;\n};\n\nexport type DiffFile = {\n  /** Repo-relative, matching how anchors are written. */\n  filePath: string;\n  hunks: DiffHunk[];\n};\n\n/**\n * A symbol resolved to lines. Supplied by whatever the caller uses to index\n * symbols; absence is tolerated — see `place()`.\n */\nexport type SymbolRange = {\n  file: string;\n  symbol: string;\n  startLine: number;\n  endLine: number;\n};\n\nexport type DiffMatch = {\n  filePath: string;\n  hunk: DiffHunk;\n  /** Current records first — what still holds should be read before what does not. */\n  records: KbAdjudicated[];\n  /**\n   * `symbol` when every record here was placed by a resolved symbol range,\n   * `file` when at least one fell back to the whole file. Reported rather than\n   * hidden: a caller showing a file-level match as though it were pinned to\n   * these lines is claiming a precision it does not have.\n   */\n  precision: \"symbol\" | \"file\";\n};\n\nexport type MatchOptions = {\n  /** Without these, symbol anchors degrade to file level rather than vanishing. */\n  symbolRanges?: SymbolRange[];\n  now?: Date;\n};\n\nexport function matchToDiff(\n  files: DiffFile[],\n  records: KbRecord[],\n  options: MatchOptions = {},\n): DiffMatch[] {\n  const ranges = indexRanges(options.symbolRanges ?? []);\n  const anchored = records.filter(\n    (record) => (record.frontmatter.strauss_anchors ?? []).length > 0,\n  );\n  const matches: DiffMatch[] = [];\n\n  for (const file of files) {\n    const candidates = anchored\n      .map((record) => ({\n        record,\n        anchors: (record.frontmatter.strauss_anchors ?? []).filter(\n          (anchor) => normalize(anchor.file) === normalize(file.filePath),\n        ),\n      }))\n      .filter(({ anchors }) => anchors.length > 0);\n    if (!candidates.length) continue;\n\n    for (const hunk of file.hunks) {\n      const hits: KbRecord[] = [];\n      let precision: DiffMatch[\"precision\"] = \"symbol\";\n\n      for (const { record, anchors } of candidates) {\n        const placement = place(anchors, file.filePath, hunk, ranges);\n        if (placement === \"miss\") continue;\n        if (placement === \"file\") precision = \"file\";\n        hits.push(record);\n      }\n\n      if (!hits.length) continue;\n      matches.push({\n        filePath: file.filePath,\n        hunk,\n        records: order(adjudicate(hits, records, options.now)),\n        precision,\n      });\n    }\n  }\n\n  return matches;\n}\n\n/**\n * Whether any of a record's anchors puts it on this hunk.\n *\n * An anchor naming only a file is about the whole file, so it lands on every\n * hunk in it. One naming a symbol lands only where that symbol's lines overlap\n * — unless nothing resolved the symbol, in which case it falls back to the file\n * rather than disappearing. A record silently absent because a resolver was\n * unavailable is worse than one shown imprecisely and labelled as such.\n */\nfunction place(\n  anchors: KbAnchor[],\n  filePath: string,\n  hunk: DiffHunk,\n  ranges: Map<string, SymbolRange[]>,\n): \"symbol\" | \"file\" | \"miss\" {\n  let fallback: \"file\" | \"miss\" = \"miss\";\n\n  for (const anchor of anchors) {\n    if (!anchor.symbol) return \"file\";\n\n    const resolved = ranges.get(key(filePath, anchor.symbol));\n    if (!resolved?.length) {\n      fallback = \"file\";\n      continue;\n    }\n    if (resolved.some((range) => overlaps(range, hunk))) return \"symbol\";\n  }\n\n  return fallback;\n}\n\nfunction overlaps(range: SymbolRange, hunk: DiffHunk): boolean {\n  return range.startLine <= hunk.endLine && hunk.startLine <= range.endLine;\n}\n\n/** Current before superseded, then oldest first, so an arc reads in order. */\nfunction order(records: KbAdjudicated[]): KbAdjudicated[] {\n  const rank: Record<string, number> = {\n    current: 0,\n    unsettled: 1,\n    open: 2,\n    superseded: 3,\n    rejected: 4,\n  };\n  return [...records].sort(\n    (left, right) =>\n      (rank[left.standing] ?? 9) - (rank[right.standing] ?? 9) ||\n      (left.record.frontmatter.generated?.at ?? \"\").localeCompare(\n        right.record.frontmatter.generated?.at ?? \"\",\n      ),\n  );\n}\n\nfunction indexRanges(ranges: SymbolRange[]): Map<string, SymbolRange[]> {\n  const byKey = new Map<string, SymbolRange[]>();\n  for (const range of ranges) {\n    const id = key(range.file, range.symbol);\n    byKey.set(id, [...(byKey.get(id) ?? []), range]);\n  }\n  return byKey;\n}\n\nfunction key(file: string, symbol: string): string {\n  return `${normalize(file)}#${symbol}`;\n}\n\n/** Anchors are written by hand often enough that `./` shows up. */\nfunction normalize(path: string): string {\n  return path.replace(/^\\.\\//, \"\");\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAmEO,SAAS,YACd,OACA,SACA,UAAwB,CAAC,GACZ;AACb,QAAM,SAAS,YAAY,QAAQ,gBAAgB,CAAC,CAAC;AACrD,QAAM,WAAW,QAAQ;AAAA,IACvB,CAAC,YAAY,OAAO,YAAY,mBAAmB,CAAC,GAAG,SAAS;AAAA,EAClE;AACA,QAAM,UAAuB,CAAC;AAE9B,aAAW,QAAQ,OAAO;AACxB,UAAM,aAAa,SAChB,IAAI,CAAC,YAAY;AAAA,MAChB;AAAA,MACA,UAAU,OAAO,YAAY,mBAAmB,CAAC,GAAG;AAAA,QAClD,CAAC,WAAW,UAAU,OAAO,IAAI,MAAM,UAAU,KAAK,QAAQ;AAAA,MAChE;AAAA,IACF,EAAE,EACD,OAAO,CAAC,EAAE,QAAQ,MAAM,QAAQ,SAAS,CAAC;AAC7C,QAAI,CAAC,WAAW,OAAQ;AAExB,eAAW,QAAQ,KAAK,OAAO;AAC7B,YAAM,OAAmB,CAAC;AAC1B,UAAI,YAAoC;AAExC,iBAAW,EAAE,QAAQ,QAAQ,KAAK,YAAY;AAC5C,cAAM,YAAY,MAAM,SAAS,KAAK,UAAU,MAAM,MAAM;AAC5D,YAAI,cAAc,OAAQ;AAC1B,YAAI,cAAc,OAAQ,aAAY;AACtC,aAAK,KAAK,MAAM;AAAA,MAClB;AAEA,UAAI,CAAC,KAAK,OAAQ;AAClB,cAAQ,KAAK;AAAA,QACX,UAAU,KAAK;AAAA,QACf;AAAA,QACA,SAAS,MAAM,WAAW,MAAM,SAAS,QAAQ,GAAG,CAAC;AAAA,QACrD;AAAA,MACF,CAAC;AAAA,IACH;AAAA,EACF;AAEA,SAAO;AACT;AAWA,SAAS,MACP,SACA,UACA,MACA,QAC4B;AAC5B,MAAI,WAA4B;AAEhC,aAAW,UAAU,SAAS;AAC5B,QAAI,CAAC,OAAO,OAAQ,QAAO;AAE3B,UAAM,WAAW,OAAO,IAAI,IAAI,UAAU,OAAO,MAAM,CAAC;AACxD,QAAI,CAAC,UAAU,QAAQ;AACrB,iBAAW;AACX;AAAA,IACF;AACA,QAAI,SAAS,KAAK,CAAC,UAAU,SAAS,OAAO,IAAI,CAAC,EAAG,QAAO;AAAA,EAC9D;AAEA,SAAO;AACT;AAEA,SAAS,SAAS,OAAoB,MAAyB;AAC7D,SAAO,MAAM,aAAa,KAAK,WAAW,KAAK,aAAa,MAAM;AACpE;AAGA,SAAS,MAAM,SAA2C;AACxD,QAAM,OAA+B;AAAA,IACnC,SAAS;AAAA,IACT,WAAW;AAAA,IACX,MAAM;AAAA,IACN,YAAY;AAAA,IACZ,UAAU;AAAA,EACZ;AACA,SAAO,CAAC,GAAG,OAAO,EAAE;AAAA,IAClB,CAAC,MAAM,WACJ,KAAK,KAAK,QAAQ,KAAK,MAAM,KAAK,MAAM,QAAQ,KAAK,OACrD,KAAK,OAAO,YAAY,WAAW,MAAM,IAAI;AAAA,MAC5C,MAAM,OAAO,YAAY,WAAW,MAAM;AAAA,IAC5C;AAAA,EACJ;AACF;AAEA,SAAS,YAAY,QAAmD;AACtE,QAAM,QAAQ,oBAAI,IAA2B;AAC7C,aAAW,SAAS,QAAQ;AAC1B,UAAM,KAAK,IAAI,MAAM,MAAM,MAAM,MAAM;AACvC,UAAM,IAAI,IAAI,CAAC,GAAI,MAAM,IAAI,EAAE,KAAK,CAAC,GAAI,KAAK,CAAC;AAAA,EACjD;AACA,SAAO;AACT;AAEA,SAAS,IAAI,MAAc,QAAwB;AACjD,SAAO,GAAG,UAAU,IAAI,CAAC,IAAI,MAAM;AACrC;AAGA,SAAS,UAAU,MAAsB;AACvC,SAAO,KAAK,QAAQ,SAAS,EAAE;AACjC;","names":[]}
+{"version":3,"sources":["../src/match-diff.ts"],"sourcesContent":["import { adjudicate, type KbAdjudicated } from \"./adjudicate.js\";\nimport type { KbAnchor, KbRecord } from \"./kb-record.schema.js\";\n\n/**\n * Which records apply to which part of a change.\n *\n * Takes a structural description of a diff rather than a patch, so this package\n * carries no diff parser: callers already have one, and a knowledge base has no\n * business preferring a particular flavour of unified diff.\n *\n * Deterministic on purpose. Every step here is mechanical — the one judgment,\n * whether a matched record is worth showing a reviewer, is deliberately absent.\n * A model placed here would sit between the reviewer and their diff on every\n * review, to answer a question nobody has yet shown needs asking.\n *\n * Distinct from `load()`, which hands a reader the whole base. That answers\n * \"does anything address this question\"; this answers \"what is attached to this\n * code\", and an anchor is the author's own statement rather than an inference\n * from one. A reader guessing which record relates to a hunk would be guessing\n * at something already written down — and a diff has dozens of hunks, which is\n * dozens of reader calls against microseconds of matching. Where they compose:\n * this narrows a hunk to a few records, and a reader asked to explain them gets\n * those, not the base.\n */\nexport type DiffHunk = {\n  /** 1-based, inclusive, in the file's post-change line numbering. */\n  startLine: number;\n  endLine: number;\n};\n\nexport type DiffFile = {\n  /** Repo-relative, matching how anchors are written. */\n  filePath: string;\n  hunks: DiffHunk[];\n};\n\n/**\n * A symbol resolved to lines. Supplied by whatever the caller uses to index\n * symbols; absence is tolerated — see `place()`.\n */\nexport type SymbolRange = {\n  file: string;\n  symbol: string;\n  startLine: number;\n  endLine: number;\n};\n\nexport type DiffMatch = {\n  filePath: string;\n  hunk: DiffHunk;\n  /** Current records first — what still holds should be read before what does not. */\n  records: KbAdjudicated[];\n  /**\n   * `symbol` when every record here was placed by a resolved symbol range,\n   * `file` when at least one fell back to the whole file. Reported rather than\n   * hidden: a caller showing a file-level match as though it were pinned to\n   * these lines is claiming a precision it does not have.\n   */\n  precision: \"symbol\" | \"file\";\n};\n\nexport type MatchOptions = {\n  /** Without these, symbol anchors degrade to file level rather than vanishing. */\n  symbolRanges?: SymbolRange[];\n  now?: Date;\n};\n\nexport function matchToDiff(\n  files: DiffFile[],\n  records: KbRecord[],\n  options: MatchOptions = {},\n): DiffMatch[] {\n  const ranges = indexRanges(options.symbolRanges ?? []);\n  const anchored = records.filter(\n    (record) => (record.frontmatter.strauss_anchors ?? []).length > 0,\n  );\n  const matches: DiffMatch[] = [];\n\n  for (const file of files) {\n    const candidates = anchored\n      .map((record) => ({\n        record,\n        anchors: (record.frontmatter.strauss_anchors ?? []).filter(\n          (anchor) => normalize(anchor.file) === normalize(file.filePath),\n        ),\n      }))\n      .filter(({ anchors }) => anchors.length > 0);\n    if (!candidates.length) continue;\n\n    for (const hunk of file.hunks) {\n      const hits: KbRecord[] = [];\n      let precision: DiffMatch[\"precision\"] = \"symbol\";\n\n      for (const { record, anchors } of candidates) {\n        const placement = place(anchors, file.filePath, hunk, ranges);\n        if (placement === \"miss\") continue;\n        if (placement === \"file\") precision = \"file\";\n        hits.push(record);\n      }\n\n      if (!hits.length) continue;\n      matches.push({\n        filePath: file.filePath,\n        hunk,\n        records: order(adjudicate(hits, records, options.now)),\n        precision,\n      });\n    }\n  }\n\n  return matches;\n}\n\n/**\n * Whether any of a record's anchors puts it on this hunk.\n *\n * An anchor naming only a file is about the whole file, so it lands on every\n * hunk in it. One naming a symbol lands only where that symbol's lines overlap\n * — unless nothing resolved the symbol, in which case it falls back to the file\n * rather than disappearing. A record silently absent because a resolver was\n * unavailable is worse than one shown imprecisely and labelled as such.\n */\nfunction place(\n  anchors: KbAnchor[],\n  filePath: string,\n  hunk: DiffHunk,\n  ranges: Map<string, SymbolRange[]>,\n): \"symbol\" | \"file\" | \"miss\" {\n  let fallback: \"file\" | \"miss\" = \"miss\";\n\n  for (const anchor of anchors) {\n    if (!anchor.symbol) return \"file\";\n\n    const resolved = ranges.get(key(filePath, anchor.symbol));\n    if (!resolved?.length) {\n      fallback = \"file\";\n      continue;\n    }\n    if (resolved.some((range) => overlaps(range, hunk))) return \"symbol\";\n  }\n\n  return fallback;\n}\n\nfunction overlaps(range: SymbolRange, hunk: DiffHunk): boolean {\n  return range.startLine <= hunk.endLine && hunk.startLine <= range.endLine;\n}\n\n/** Current before superseded, then oldest first, so an arc reads in order. */\nfunction order(records: KbAdjudicated[]): KbAdjudicated[] {\n  const rank: Record<string, number> = {\n    current: 0,\n    unsettled: 1,\n    open: 2,\n    superseded: 3,\n    rejected: 4,\n  };\n  return [...records].sort(\n    (left, right) =>\n      (rank[left.standing] ?? 9) - (rank[right.standing] ?? 9) ||\n      (left.record.frontmatter.generated?.at ?? \"\").localeCompare(\n        right.record.frontmatter.generated?.at ?? \"\",\n      ),\n  );\n}\n\nfunction indexRanges(ranges: SymbolRange[]): Map<string, SymbolRange[]> {\n  const byKey = new Map<string, SymbolRange[]>();\n  for (const range of ranges) {\n    const id = key(range.file, range.symbol);\n    byKey.set(id, [...(byKey.get(id) ?? []), range]);\n  }\n  return byKey;\n}\n\nfunction key(file: string, symbol: string): string {\n  return `${normalize(file)}#${symbol}`;\n}\n\n/** Anchors are written by hand often enough that `./` shows up. */\nfunction normalize(path: string): string {\n  return path.replace(/^\\.\\//, \"\");\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAmEO,SAAS,YACd,OACA,SACA,UAAwB,CAAC,GACZ;AACb,QAAM,SAAS,YAAY,QAAQ,gBAAgB,CAAC,CAAC;AACrD,QAAM,WAAW,QAAQ;AAAA,IACvB,CAAC,YAAY,OAAO,YAAY,mBAAmB,CAAC,GAAG,SAAS;AAAA,EAClE;AACA,QAAM,UAAuB,CAAC;AAE9B,aAAW,QAAQ,OAAO;AACxB,UAAM,aAAa,SAChB,IAAI,CAAC,YAAY;AAAA,MAChB;AAAA,MACA,UAAU,OAAO,YAAY,mBAAmB,CAAC,GAAG;AAAA,QAClD,CAAC,WAAW,UAAU,OAAO,IAAI,MAAM,UAAU,KAAK,QAAQ;AAAA,MAChE;AAAA,IACF,EAAE,EACD,OAAO,CAAC,EAAE,QAAQ,MAAM,QAAQ,SAAS,CAAC;AAC7C,QAAI,CAAC,WAAW,OAAQ;AAExB,eAAW,QAAQ,KAAK,OAAO;AAC7B,YAAM,OAAmB,CAAC;AAC1B,UAAI,YAAoC;AAExC,iBAAW,EAAE,QAAQ,QAAQ,KAAK,YAAY;AAC5C,cAAM,YAAY,MAAM,SAAS,KAAK,UAAU,MAAM,MAAM;AAC5D,YAAI,cAAc,OAAQ;AAC1B,YAAI,cAAc,OAAQ,aAAY;AACtC,aAAK,KAAK,MAAM;AAAA,MAClB;AAEA,UAAI,CAAC,KAAK,OAAQ;AAClB,cAAQ,KAAK;AAAA,QACX,UAAU,KAAK;AAAA,QACf;AAAA,QACA,SAAS,MAAM,WAAW,MAAM,SAAS,QAAQ,GAAG,CAAC;AAAA,QACrD;AAAA,MACF,CAAC;AAAA,IACH;AAAA,EACF;AAEA,SAAO;AACT;AAWA,SAAS,MACP,SACA,UACA,MACA,QAC4B;AAC5B,MAAI,WAA4B;AAEhC,aAAW,UAAU,SAAS;AAC5B,QAAI,CAAC,OAAO,OAAQ,QAAO;AAE3B,UAAM,WAAW,OAAO,IAAI,IAAI,UAAU,OAAO,MAAM,CAAC;AACxD,QAAI,CAAC,UAAU,QAAQ;AACrB,iBAAW;AACX;AAAA,IACF;AACA,QAAI,SAAS,KAAK,CAAC,UAAU,SAAS,OAAO,IAAI,CAAC,EAAG,QAAO;AAAA,EAC9D;AAEA,SAAO;AACT;AAEA,SAAS,SAAS,OAAoB,MAAyB;AAC7D,SAAO,MAAM,aAAa,KAAK,WAAW,KAAK,aAAa,MAAM;AACpE;AAGA,SAAS,MAAM,SAA2C;AACxD,QAAM,OAA+B;AAAA,IACnC,SAAS;AAAA,IACT,WAAW;AAAA,IACX,MAAM;AAAA,IACN,YAAY;AAAA,IACZ,UAAU;AAAA,EACZ;AACA,SAAO,CAAC,GAAG,OAAO,EAAE;AAAA,IAClB,CAAC,MAAM,WACJ,KAAK,KAAK,QAAQ,KAAK,MAAM,KAAK,MAAM,QAAQ,KAAK,OACrD,KAAK,OAAO,YAAY,WAAW,MAAM,IAAI;AAAA,MAC5C,MAAM,OAAO,YAAY,WAAW,MAAM;AAAA,IAC5C;AAAA,EACJ;AACF;AAEA,SAAS,YAAY,QAAmD;AACtE,QAAM,QAAQ,oBAAI,IAA2B;AAC7C,aAAW,SAAS,QAAQ;AAC1B,UAAM,KAAK,IAAI,MAAM,MAAM,MAAM,MAAM;AACvC,UAAM,IAAI,IAAI,CAAC,GAAI,MAAM,IAAI,EAAE,KAAK,CAAC,GAAI,KAAK,CAAC;AAAA,EACjD;AACA,SAAO;AACT;AAEA,SAAS,IAAI,MAAc,QAAwB;AACjD,SAAO,GAAG,UAAU,IAAI,CAAC,IAAI,MAAM;AACrC;AAGA,SAAS,UAAU,MAAsB;AACvC,SAAO,KAAK,QAAQ,SAAS,EAAE;AACjC;","names":[]}