@saasontools/strauss-kb 0.1.6 → 0.1.8

package/dist/index.d.cts

@@ -225,12 +225,11 @@ declare function resolveHeads(from: KbRecord, byId: Map<string, KbRecord>): {
 };
 
 /**
- * Edges a trace may follow.
- *
- * Two more are conceivable and absent: `strauss_answered` carries no target id,
- * so a question's resolution lives in its own body rather than in another
- * record; and following OKF's body markdown links would need a markdown AST
- * pass this package does not yet do.
+ * Edges a trace may follow — the shared kb-edges.ts definitions, minus
+ * `body-link`: body links can reach most of a bundle from anywhere, which
+ * suits a bounded pack but floods a timeline. Also absent by design:
+ * `strauss_answered` carries no target id, so a question's resolution lives
+ * in its own body rather than in another record.
  */
 declare const TRACE_EDGES: readonly ["supersession", "anchor", "source"];
 type KbTraceEdge = (typeof TRACE_EDGES)[number];
@@ -260,6 +259,58 @@ type KbTraceOptions = {
  */
 declare function trace(seedId: string, bundle: KbRecord[], options?: KbTraceOptions): KbTraceStep[];
 
+declare const DEFAULT_PACK_HOPS = 2;
+declare const DEFAULT_PACK_MAX_NODES = 20;
+type KbPackOptions = {
+    /** How far from the root the walk may reach. */
+    hops?: number;
+    /** How many records the pack may hold, root included. */
+    maxNodes?: number;
+    /** Approximate token ceiling over what is actually emitted. */
+    budgetTokens?: number;
+};
+/** One record as the pack emits it — the same mapping `kb_load` hands back. */
+type KbPackedRecord = {
+    conceptId: string;
+    title: string | null;
+    standing: KbStanding;
+    supersededBy: string[];
+    warnings: KbWarning[];
+    anchors: KbAnchor[];
+    body: string;
+};
+/**
+ * Deliberately timestamp-free: the same bundle and root must produce the same
+ * bytes on every run, so a caller can diff two packs and trust that a changed
+ * byte means changed knowledge.
+ */
+type KbPackResult = {
+    root: string;
+    records: KbPackedRecord[];
+    /** Named only, exactly as `load` stubs them. Bodies reachable via trace. */
+    superseded: KbSupersededStub[];
+    /** Every reachable record the hop and node limits cut, never summarized. */
+    excluded: string[];
+    recordCount: number;
+    tokensLoaded: number;
+    budgetTokens: number;
+};
+/**
+ * A bounded, progressively disclosed neighbourhood around one record.
+ *
+ * Where `load` hands over a whole base and `trace` a timeline, a pack is the
+ * subgraph a reader needs to act near one record: everything within `hops`
+ * of the root, cut to `maxNodes` by ranking, with every cut id listed —
+ * a named gap is knowable, a silent one is not.
+ *
+ * Adjudication runs against the whole bundle, not the reached slice, so a
+ * record's standing cannot depend on whether its replacement happened to be
+ * within reach. Superseded records become the same stubs `load` emits, costed
+ * as stubs, and the budget is a refusal rather than a truncation: a partial
+ * pack looks complete to its reader.
+ */
+declare function pack(bundle: KbRecord[], rootId: string, options?: KbPackOptions): KbPackResult;
+
 declare const LOG_FILE = "log.jsonl";
 declare const kbLogEntrySchema: z.ZodObject<{
     at: z.ZodString;
@@ -310,6 +361,8 @@ type KbLogger = {
     info?(entry: Record<string, unknown>): void;
     warn?(entry: Record<string, unknown>): void;
 };
+/** Roughly an eighth of a large context window — generous, and overridable. */
+declare const DEFAULT_LOAD_BUDGET = 25000;
 /**
  * A superseded record, named but not spelled out.
  *
@@ -467,6 +520,8 @@ declare class KbStore {
     }): Promise<KbLoadResult>;
     /** How a position was arrived at, as a timeline. See `trace.ts`. */
     trace(bundlePath: string, seedId: string, options?: KbTraceOptions): Promise<KbTraceStep[]>;
+    /** A bounded neighbourhood around one record. See `pack.ts`. */
+    pack(bundlePath: string, rootId: string, options?: KbPackOptions): Promise<KbPackResult>;
     /**
      * The stored index, rebuilt if it disagrees with the records.
      *
@@ -545,6 +600,7 @@ declare enum Fault {
 declare enum ErrorTypes {
     KbRecordAlreadyExists = "KbRecordAlreadyExists",
     KbInvalidConceptId = "KbInvalidConceptId",
+    KbPackBudgetExceeded = "KbPackBudgetExceeded",
     KbRecordNotFound = "KbRecordNotFound",
     KbSelfVerification = "KbSelfVerification",
     KbWriteConflict = "KbWriteConflict"
@@ -596,6 +652,20 @@ declare class KbSelfVerificationError extends BaseError {
     readonly generatedBy: string;
     constructor(conceptId: string, actor: string, generatedBy: string);
 }
+/**
+ * A pack that will not fit its token budget. Refusal, not truncation: a
+ * partial pack is indistinguishable from a complete one, so the caller gets
+ * the full picture — how many records, how many tokens, and every id the
+ * walk's own limits already cut — and decides whether to raise the budget or
+ * tighten the walk.
+ */
+declare class KbPackBudgetExceededError extends BaseError {
+    readonly recordCount: number;
+    readonly approxTokens: number;
+    readonly budgetTokens: number;
+    readonly excluded: string[];
+    constructor(recordCount: number, approxTokens: number, budgetTokens: number, excluded: string[]);
+}
 declare class KbInvalidConceptIdError extends BaseError {
     constructor(message: string, details: Record<string, string>);
 }
@@ -1018,6 +1088,33 @@ type MatchOptions = {
 };
 declare function matchToDiff(files: DiffFile[], records: KbRecord[], options?: MatchOptions): DiffMatch[];
 
+/**
+ * The edges between records in one bundle, defined once.
+ *
+ * Both walks — `trace` and `pack` — consume this module, so they cannot drift
+ * into disagreeing about what makes two records neighbours, and a diagnostic
+ * pass over the graph can reuse the same definition.
+ *
+ * There is no separate `related` kind: compose.ts renders `relatedConceptIds`
+ * as body links (`Relates to [id](id.md).`), so in stored form a related edge
+ * IS a body link, and a distinct kind would count the same markdown twice.
+ */
+declare const KB_EDGE_KINDS: readonly ["body-link", "supersession", "anchor", "source"];
+type KbEdgeKind = (typeof KB_EDGE_KINDS)[number];
+type KbNeighbour = {
+    record: KbRecord;
+    /** Every edge kind that connects it to the record asked about. */
+    via: KbEdgeKind[];
+};
+/**
+ * Every record `from` touches, each carrying the full set of edge kinds that
+ * connect the pair. Order is deterministic: bundle order per kind, kinds in
+ * the order given.
+ */
+declare function neighbours(from: KbRecord, bundle: KbRecord[], kinds?: readonly KbEdgeKind[]): KbNeighbour[];
+/** The records one edge kind connects `from` to, in bundle order. */
+declare function edgeNeighbours(from: KbRecord, bundle: KbRecord[], kind: KbEdgeKind): KbRecord[];
+
 type KbValidationProblem = {
     check: string;
     conceptId: string;
@@ -1033,6 +1130,68 @@ type KbValidationProblem = {
  */
 declare function validateBundle(records: KbRecord[]): KbValidationProblem[];
 
+/**
+ * A health sweep over a whole base — read-only, and never a mutation.
+ *
+ * Every other read answers a question a caller already had. This one asks the
+ * questions nobody thinks to: which records the calendar has already retired,
+ * which nobody ever confirmed, which have been open long enough that "open" is
+ * now the answer, and which the graph has quietly dropped on the floor. Those
+ * 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.
+ *
+ * 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,
+ * and the difference is the whole value of a sweep.
+ */
+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"];
+type KbDoctorCheck = (typeof KB_DOCTOR_CHECKS)[number];
+type KbDoctorFinding = {
+    conceptId: string;
+    title: string | null;
+    status: KbRecordStatus;
+    /** Why this record is in this group, in one phrase a reader can act on. */
+    note: string;
+};
+type KbDoctorGroup = {
+    check: KbDoctorCheck;
+    /** What the check looks for, so a zero count still says something. */
+    headline: string;
+    count: number;
+    findings: KbDoctorFinding[];
+};
+type KbDoctorThresholds = {
+    expiringDays: number;
+    unverifiedDays: number;
+    agingDays: number;
+};
+type KbDoctorReport = {
+    recordCount: number;
+    thresholds: KbDoctorThresholds;
+    counts: Record<KbDoctorCheck, number>;
+    /** All seven, in `KB_DOCTOR_CHECKS` order, empty ones included. */
+    groups: KbDoctorGroup[];
+    findingCount: number;
+    healthy: boolean;
+};
+type KbDoctorOptions = {
+    /** How far ahead `expiring` looks. */
+    expiringDays?: number;
+    /** How old an unconfirmed record must be before `unverified` reports it. */
+    unverifiedDays?: number;
+    /** How long `open` or `proposed` may stand before `aging` reports it. */
+    agingDays?: number;
+    now?: Date;
+};
+declare function doctor(bundle: KbRecord[], options?: KbDoctorOptions): KbDoctorReport;
+
 /**
  * The record written while a change is being made: why it is shaped the way it
  * is, anchored to the symbols it touches.
@@ -1147,12 +1306,26 @@ type KbCommand<Shape extends z.ZodRawShape = z.ZodRawShape> = {
     /** Positional argv → the same object MCP receives. */
     fromArgv(argv: string[], bundlePath: string, stdin: () => Promise<string>): 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): boolean;
+    failsWhen?(result: unknown, input: z.infer<z.ZodObject<Shape>>): boolean;
 };
 
 /**
@@ -1297,4 +1470,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, 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, 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, composeDecisionRecord, composeInputSchema, composeNoDecisionRecord, composeRecord, contextProfileBudgets, createKbMcpServer, decisionInputSchema, indexIsStale, isKbRecordType, isNoDecisionRecord, kbActorStampSchema, kbAnchorSchema, kbConceptIdSchema, kbJsonSchemas, kbLogEntrySchema, kbRecordFrontmatterSchema, kbSourceSchema, kbVerifiedEventSchema, 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 };
+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 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, 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, 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, renderIndex, renderIndexLine, renderLogEntry, resolveHeads, resolveHits, resolvePinPath, runKbCli, runKbMcpServer, searchBase, selectDecisions, splitMarkdownFrontmatter, stringifyMarkdownWithFrontmatter, syncInstructions, toHookJson, trace, unpinBase, validateBundle };

package/dist/index.d.ts

@@ -225,12 +225,11 @@ declare function resolveHeads(from: KbRecord, byId: Map<string, KbRecord>): {
 };
 
 /**
- * Edges a trace may follow.
- *
- * Two more are conceivable and absent: `strauss_answered` carries no target id,
- * so a question's resolution lives in its own body rather than in another
- * record; and following OKF's body markdown links would need a markdown AST
- * pass this package does not yet do.
+ * Edges a trace may follow — the shared kb-edges.ts definitions, minus
+ * `body-link`: body links can reach most of a bundle from anywhere, which
+ * suits a bounded pack but floods a timeline. Also absent by design:
+ * `strauss_answered` carries no target id, so a question's resolution lives
+ * in its own body rather than in another record.
  */
 declare const TRACE_EDGES: readonly ["supersession", "anchor", "source"];
 type KbTraceEdge = (typeof TRACE_EDGES)[number];
@@ -260,6 +259,58 @@ type KbTraceOptions = {
  */
 declare function trace(seedId: string, bundle: KbRecord[], options?: KbTraceOptions): KbTraceStep[];
 
+declare const DEFAULT_PACK_HOPS = 2;
+declare const DEFAULT_PACK_MAX_NODES = 20;
+type KbPackOptions = {
+    /** How far from the root the walk may reach. */
+    hops?: number;
+    /** How many records the pack may hold, root included. */
+    maxNodes?: number;
+    /** Approximate token ceiling over what is actually emitted. */
+    budgetTokens?: number;
+};
+/** One record as the pack emits it — the same mapping `kb_load` hands back. */
+type KbPackedRecord = {
+    conceptId: string;
+    title: string | null;
+    standing: KbStanding;
+    supersededBy: string[];
+    warnings: KbWarning[];
+    anchors: KbAnchor[];
+    body: string;
+};
+/**
+ * Deliberately timestamp-free: the same bundle and root must produce the same
+ * bytes on every run, so a caller can diff two packs and trust that a changed
+ * byte means changed knowledge.
+ */
+type KbPackResult = {
+    root: string;
+    records: KbPackedRecord[];
+    /** Named only, exactly as `load` stubs them. Bodies reachable via trace. */
+    superseded: KbSupersededStub[];
+    /** Every reachable record the hop and node limits cut, never summarized. */
+    excluded: string[];
+    recordCount: number;
+    tokensLoaded: number;
+    budgetTokens: number;
+};
+/**
+ * A bounded, progressively disclosed neighbourhood around one record.
+ *
+ * Where `load` hands over a whole base and `trace` a timeline, a pack is the
+ * subgraph a reader needs to act near one record: everything within `hops`
+ * of the root, cut to `maxNodes` by ranking, with every cut id listed —
+ * a named gap is knowable, a silent one is not.
+ *
+ * Adjudication runs against the whole bundle, not the reached slice, so a
+ * record's standing cannot depend on whether its replacement happened to be
+ * within reach. Superseded records become the same stubs `load` emits, costed
+ * as stubs, and the budget is a refusal rather than a truncation: a partial
+ * pack looks complete to its reader.
+ */
+declare function pack(bundle: KbRecord[], rootId: string, options?: KbPackOptions): KbPackResult;
+
 declare const LOG_FILE = "log.jsonl";
 declare const kbLogEntrySchema: z.ZodObject<{
     at: z.ZodString;
@@ -310,6 +361,8 @@ type KbLogger = {
     info?(entry: Record<string, unknown>): void;
     warn?(entry: Record<string, unknown>): void;
 };
+/** Roughly an eighth of a large context window — generous, and overridable. */
+declare const DEFAULT_LOAD_BUDGET = 25000;
 /**
  * A superseded record, named but not spelled out.
  *
@@ -467,6 +520,8 @@ declare class KbStore {
     }): Promise<KbLoadResult>;
     /** How a position was arrived at, as a timeline. See `trace.ts`. */
     trace(bundlePath: string, seedId: string, options?: KbTraceOptions): Promise<KbTraceStep[]>;
+    /** A bounded neighbourhood around one record. See `pack.ts`. */
+    pack(bundlePath: string, rootId: string, options?: KbPackOptions): Promise<KbPackResult>;
     /**
      * The stored index, rebuilt if it disagrees with the records.
      *
@@ -545,6 +600,7 @@ declare enum Fault {
 declare enum ErrorTypes {
     KbRecordAlreadyExists = "KbRecordAlreadyExists",
     KbInvalidConceptId = "KbInvalidConceptId",
+    KbPackBudgetExceeded = "KbPackBudgetExceeded",
     KbRecordNotFound = "KbRecordNotFound",
     KbSelfVerification = "KbSelfVerification",
     KbWriteConflict = "KbWriteConflict"
@@ -596,6 +652,20 @@ declare class KbSelfVerificationError extends BaseError {
     readonly generatedBy: string;
     constructor(conceptId: string, actor: string, generatedBy: string);
 }
+/**
+ * A pack that will not fit its token budget. Refusal, not truncation: a
+ * partial pack is indistinguishable from a complete one, so the caller gets
+ * the full picture — how many records, how many tokens, and every id the
+ * walk's own limits already cut — and decides whether to raise the budget or
+ * tighten the walk.
+ */
+declare class KbPackBudgetExceededError extends BaseError {
+    readonly recordCount: number;
+    readonly approxTokens: number;
+    readonly budgetTokens: number;
+    readonly excluded: string[];
+    constructor(recordCount: number, approxTokens: number, budgetTokens: number, excluded: string[]);
+}
 declare class KbInvalidConceptIdError extends BaseError {
     constructor(message: string, details: Record<string, string>);
 }
@@ -1018,6 +1088,33 @@ type MatchOptions = {
 };
 declare function matchToDiff(files: DiffFile[], records: KbRecord[], options?: MatchOptions): DiffMatch[];
 
+/**
+ * The edges between records in one bundle, defined once.
+ *
+ * Both walks — `trace` and `pack` — consume this module, so they cannot drift
+ * into disagreeing about what makes two records neighbours, and a diagnostic
+ * pass over the graph can reuse the same definition.
+ *
+ * There is no separate `related` kind: compose.ts renders `relatedConceptIds`
+ * as body links (`Relates to [id](id.md).`), so in stored form a related edge
+ * IS a body link, and a distinct kind would count the same markdown twice.
+ */
+declare const KB_EDGE_KINDS: readonly ["body-link", "supersession", "anchor", "source"];
+type KbEdgeKind = (typeof KB_EDGE_KINDS)[number];
+type KbNeighbour = {
+    record: KbRecord;
+    /** Every edge kind that connects it to the record asked about. */
+    via: KbEdgeKind[];
+};
+/**
+ * Every record `from` touches, each carrying the full set of edge kinds that
+ * connect the pair. Order is deterministic: bundle order per kind, kinds in
+ * the order given.
+ */
+declare function neighbours(from: KbRecord, bundle: KbRecord[], kinds?: readonly KbEdgeKind[]): KbNeighbour[];
+/** The records one edge kind connects `from` to, in bundle order. */
+declare function edgeNeighbours(from: KbRecord, bundle: KbRecord[], kind: KbEdgeKind): KbRecord[];
+
 type KbValidationProblem = {
     check: string;
     conceptId: string;
@@ -1033,6 +1130,68 @@ type KbValidationProblem = {
  */
 declare function validateBundle(records: KbRecord[]): KbValidationProblem[];
 
+/**
+ * A health sweep over a whole base — read-only, and never a mutation.
+ *
+ * Every other read answers a question a caller already had. This one asks the
+ * questions nobody thinks to: which records the calendar has already retired,
+ * which nobody ever confirmed, which have been open long enough that "open" is
+ * now the answer, and which the graph has quietly dropped on the floor. Those
+ * 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.
+ *
+ * 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,
+ * and the difference is the whole value of a sweep.
+ */
+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"];
+type KbDoctorCheck = (typeof KB_DOCTOR_CHECKS)[number];
+type KbDoctorFinding = {
+    conceptId: string;
+    title: string | null;
+    status: KbRecordStatus;
+    /** Why this record is in this group, in one phrase a reader can act on. */
+    note: string;
+};
+type KbDoctorGroup = {
+    check: KbDoctorCheck;
+    /** What the check looks for, so a zero count still says something. */
+    headline: string;
+    count: number;
+    findings: KbDoctorFinding[];
+};
+type KbDoctorThresholds = {
+    expiringDays: number;
+    unverifiedDays: number;
+    agingDays: number;
+};
+type KbDoctorReport = {
+    recordCount: number;
+    thresholds: KbDoctorThresholds;
+    counts: Record<KbDoctorCheck, number>;
+    /** All seven, in `KB_DOCTOR_CHECKS` order, empty ones included. */
+    groups: KbDoctorGroup[];
+    findingCount: number;
+    healthy: boolean;
+};
+type KbDoctorOptions = {
+    /** How far ahead `expiring` looks. */
+    expiringDays?: number;
+    /** How old an unconfirmed record must be before `unverified` reports it. */
+    unverifiedDays?: number;
+    /** How long `open` or `proposed` may stand before `aging` reports it. */
+    agingDays?: number;
+    now?: Date;
+};
+declare function doctor(bundle: KbRecord[], options?: KbDoctorOptions): KbDoctorReport;
+
 /**
  * The record written while a change is being made: why it is shaped the way it
  * is, anchored to the symbols it touches.
@@ -1147,12 +1306,26 @@ type KbCommand<Shape extends z.ZodRawShape = z.ZodRawShape> = {
     /** Positional argv → the same object MCP receives. */
     fromArgv(argv: string[], bundlePath: string, stdin: () => Promise<string>): 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): boolean;
+    failsWhen?(result: unknown, input: z.infer<z.ZodObject<Shape>>): boolean;
 };
 
 /**
@@ -1297,4 +1470,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, 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, 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, composeDecisionRecord, composeInputSchema, composeNoDecisionRecord, composeRecord, contextProfileBudgets, createKbMcpServer, decisionInputSchema, indexIsStale, isKbRecordType, isNoDecisionRecord, kbActorStampSchema, kbAnchorSchema, kbConceptIdSchema, kbJsonSchemas, kbLogEntrySchema, kbRecordFrontmatterSchema, kbSourceSchema, kbVerifiedEventSchema, 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 };
+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 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, 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, 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, renderIndex, renderIndexLine, renderLogEntry, resolveHeads, resolveHits, resolvePinPath, runKbCli, runKbMcpServer, searchBase, selectDecisions, splitMarkdownFrontmatter, stringifyMarkdownWithFrontmatter, syncInstructions, toHookJson, trace, unpinBase, validateBundle };

package/dist/index.js

@@ -1,16 +1,22 @@
 import {
   runKbCli
-} from "./chunk-V7TRZ2ER.js";
+} from "./chunk-MGPYUZOM.js";
 import {
   createKbMcpServer,
   runKbMcpServer
-} from "./chunk-BVF7X5VO.js";
+} from "./chunk-YYX6CX6V.js";
 import {
   BaseError,
   CONTEXT_BEGIN,
   CONTEXT_END,
   CONTEXT_PROFILES,
   DECISION_TYPE,
+  DEFAULT_AGING_DAYS,
+  DEFAULT_EXPIRING_DAYS,
+  DEFAULT_LOAD_BUDGET,
+  DEFAULT_PACK_HOPS,
+  DEFAULT_PACK_MAX_NODES,
+  DEFAULT_UNVERIFIED_DAYS,
   ErrorTypes,
   Fault,
   INDEX_FILE,
@@ -19,12 +25,15 @@ import {
   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,
   KbBaseFrozenError,
   KbInvalidConceptIdError,
+  KbPackBudgetExceededError,
   KbPinsMalformedError,
   KbRecordAlreadyExistsError,
   KbRecordNotFoundError,
@@ -48,6 +57,8 @@ import {
   composeRecord,
   contextProfileBudgets,
   decisionInputSchema,
+  doctor,
+  edgeNeighbours,
   indexIsStale,
   isKbRecordType,
   isNoDecisionRecord,
@@ -62,6 +73,8 @@ import {
   listPins,
   loadQmd,
   mergedContextBudgets,
+  neighbours,
+  pack,
   parseLog,
   parseMarkdownWithFrontmatter,
   pinBase,
@@ -82,7 +95,7 @@ import {
   trace,
   unpinBase,
   validateBundle
-} from "./chunk-PNSRTKYN.js";
+} from "./chunk-YJK7KGHN.js";
 
 // src/match-diff.ts
 function matchToDiff(files, records, options = {}) {
@@ -169,6 +182,12 @@ export {
   CONTEXT_END,
   CONTEXT_PROFILES,
   DECISION_TYPE,
+  DEFAULT_AGING_DAYS,
+  DEFAULT_EXPIRING_DAYS,
+  DEFAULT_LOAD_BUDGET,
+  DEFAULT_PACK_HOPS,
+  DEFAULT_PACK_MAX_NODES,
+  DEFAULT_UNVERIFIED_DAYS,
   ErrorTypes,
   Fault,
   INDEX_FILE,
@@ -177,12 +196,15 @@ export {
   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,
   KbBaseFrozenError,
   KbInvalidConceptIdError,
+  KbPackBudgetExceededError,
   KbPinsMalformedError,
   KbRecordAlreadyExistsError,
   KbRecordNotFoundError,
@@ -207,6 +229,8 @@ export {
   contextProfileBudgets,
   createKbMcpServer,
   decisionInputSchema,
+  doctor,
+  edgeNeighbours,
   indexIsStale,
   isKbRecordType,
   isNoDecisionRecord,
@@ -222,6 +246,8 @@ export {
   loadQmd,
   matchToDiff,
   mergedContextBudgets,
+  neighbours,
+  pack,
   parseLog,
   parseMarkdownWithFrontmatter,
   pinBase,