@saasontools/strauss-kb 0.1.0

package/dist/index.d.cts

@@ -0,0 +1,977 @@
+import { z } from 'zod';
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+
+/**
+ * Knowledge records, shaped as OKF v0.2 concepts.
+ *
+ * OKF (Google Cloud `knowledge-catalog`) requires exactly one key — `type` —
+ * and explicitly permits extension: "Producers MAY include any additional keys.
+ * Consumers SHOULD preserve unknown keys when round-tripping and MUST NOT
+ * reject documents with unrecognized fields."
+ *
+ * A record's identity is its `concept_id`: the file path within the bundle with
+ * `.md` removed. `<type>.<slug>.md` therefore yields `decision.some-slug`.
+ *
+ * Keys prefixed `strauss_` are this package's extensions rather than
+ * conformance, and are namespaced so a later OKF version defining the same
+ * names cannot collide: OKF names files through path-valued `resource` fields
+ * and has no notion of a span, so anchoring a concept to a range of code has no
+ * standard spelling, and standing has none either.
+ */
+/** A source the record draws on. Footnotes in the body key to `id`. */
+declare const kbSourceSchema: z.ZodObject<{
+    id: z.ZodString;
+    resource: z.ZodString;
+    title: z.ZodOptional<z.ZodString>;
+    author: z.ZodOptional<z.ZodString>;
+    last_modified: z.ZodOptional<z.ZodString>;
+}, z.core.$loose>;
+/** An actor/time pair — OKF's shape for both `generated` and `verified[]`. */
+declare const kbActorStampSchema: z.ZodObject<{
+    by: z.ZodString;
+    at: z.ZodString;
+}, z.core.$loose>;
+/**
+ * Where a record attaches in the code.
+ *
+ * Symbolic on purpose. These are written while the code is still moving: a
+ * `line: 379` recorded at minute five is wrong by minute forty, but
+ * `OrderService.cancel` survives every edit that does not rename it. A later
+ * pass resolves symbols to line ranges once the change has settled, and records
+ * that resolution as a `verified[]` entry.
+ */
+declare const kbAnchorSchema: z.ZodObject<{
+    file: z.ZodString;
+    symbol: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+declare const KB_RECORD_TYPES: readonly ["fact", "requirement", "constraint", "decision", "assumption", "open-question", "risk", "contract", "flow", "affected-system", "test-obligation", "source-note"];
+type KbRecordType = (typeof KB_RECORD_TYPES)[number];
+/** Both halves of `<type>.<slug>` are kebab-case, and neither may be empty. */
+declare const KB_SLUG_PATTERN: RegExp;
+declare const KB_CONCEPT_ID_PATTERN: RegExp;
+/**
+ * Concept ids are rendered into markdown links unescaped, so an id carrying a
+ * `]` or `)` would emit a broken edge rather than fail. Validating at the entry
+ * point keeps the renderer from having to care.
+ */
+declare const kbConceptIdSchema: z.ZodString;
+/**
+ * Standing, not freshness.
+ *
+ * OKF's `verified[]` and `stale_after` answer "is this still true?"; nothing in
+ * the spec answers "is this settled, and does it still apply?". A base
+ * supersedes its own conclusions as work proceeds, so that second question
+ * needs an answer, and it is this package's to define — hence `strauss_`.
+ */
+declare const KB_RECORD_STATUSES: readonly ["draft", "proposed", "accepted", "open", "resolved", "rejected", "superseded"];
+type KbRecordStatus = (typeof KB_RECORD_STATUSES)[number];
+declare const KB_MATERIALITIES: readonly ["blocking", "important", "non-blocking"];
+declare const KB_CONFIDENCES: readonly ["low", "medium", "high"];
+declare const kbRecordFrontmatterSchema: z.ZodObject<{
+    type: z.ZodString;
+    title: z.ZodOptional<z.ZodString>;
+    description: z.ZodOptional<z.ZodString>;
+    resource: z.ZodOptional<z.ZodString>;
+    tags: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    sources: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        resource: z.ZodString;
+        title: z.ZodOptional<z.ZodString>;
+        author: z.ZodOptional<z.ZodString>;
+        last_modified: z.ZodOptional<z.ZodString>;
+    }, z.core.$loose>>>;
+    generated: z.ZodOptional<z.ZodObject<{
+        by: z.ZodString;
+        at: z.ZodString;
+    }, z.core.$loose>>;
+    verified: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        by: z.ZodString;
+        at: z.ZodString;
+    }, z.core.$loose>>>;
+    stale_after: z.ZodOptional<z.ZodString>;
+    strauss_anchors: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        file: z.ZodString;
+        symbol: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>>>;
+    strauss_verify: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    strauss_status: z.ZodDefault<z.ZodEnum<{
+        draft: "draft";
+        proposed: "proposed";
+        accepted: "accepted";
+        open: "open";
+        resolved: "resolved";
+        rejected: "rejected";
+        superseded: "superseded";
+    }>>;
+    strauss_supersedes: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    strauss_superseded_by: z.ZodOptional<z.ZodString>;
+    strauss_answered: z.ZodOptional<z.ZodObject<{
+        by: z.ZodString;
+        at: z.ZodString;
+    }, z.core.$loose>>;
+    strauss_materiality: z.ZodOptional<z.ZodEnum<{
+        blocking: "blocking";
+        important: "important";
+        "non-blocking": "non-blocking";
+    }>>;
+    strauss_confidence: z.ZodOptional<z.ZodEnum<{
+        low: "low";
+        medium: "medium";
+        high: "high";
+    }>>;
+    strauss_owner: z.ZodOptional<z.ZodString>;
+    strauss_assumption: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$loose>;
+type KbSource = z.infer<typeof kbSourceSchema>;
+type KbActorStamp = z.infer<typeof kbActorStampSchema>;
+type KbAnchor = z.infer<typeof kbAnchorSchema>;
+type KbRecordFrontmatter = z.infer<typeof kbRecordFrontmatterSchema>;
+type KbRecord = {
+    /** Path minus `.md`, relative to the bundle root. OKF's concept identity. */
+    conceptId: string;
+    frontmatter: KbRecordFrontmatter;
+    body: string;
+};
+
+/**
+ * Why a matched record must not be read as a plain answer.
+ *
+ * Relevance and standing are different questions, and ranking answers only the
+ * first. A superseded record is usually the older, longer, more general one and
+ * its replacement is usually a narrowing, so any similarity measure favours the
+ * record that is no longer true. Every hit therefore carries its standing, and
+ * the caller is never handed a bare match.
+ */
+type KbWarning = 
+/** Explicitly not adopted. The most dangerous status to return unmarked: a
+ *  well-formed assertion of what someone decided *not* to do. */
+{
+    kind: "rejected";
+} | {
+    kind: "superseded";
+    by: string[];
+}
+/** Not settled. Acting on a proposal as though it were a decision is a defect. */
+ | {
+    kind: "unsettled";
+    status: KbRecordStatus;
+}
+/** Says a matter is unresolved. Valuable as a result, never as an answer. */
+ | {
+    kind: "unresolved-question";
+}
+/** `strauss_superseded_by` names a record that is not in the bundle. */
+ | {
+    kind: "broken-chain";
+    missing: string;
+} | {
+    kind: "chain-cycle";
+    through: string[];
+}
+/** Two records claim to replace this one; picking either would be a guess. */
+ | {
+    kind: "forked-chain";
+    heads: string[];
+} | {
+    kind: "stale";
+    staleAfter: string;
+} | {
+    kind: "unverified";
+};
+type KbStanding = "current" | "superseded" | "rejected" | "unsettled" | "open";
+type KbAdjudicated = {
+    record: KbRecord;
+    standing: KbStanding;
+    /** Where the supersession chain ends. Empty when it is broken or cyclic. */
+    heads: KbRecord[];
+    warnings: KbWarning[];
+};
+/**
+ * Attaches standing to records a search returned.
+ *
+ * Adjudicating rather than filtering, deliberately. A filtered result set is
+ * invisible: the caller cannot tell it missed anything, so a dropped record is
+ * worse than a flagged one — it turns a knowable gap into an unknowable one.
+ */
+declare function adjudicate(hits: KbRecord[], bundle: KbRecord[], now?: Date): KbAdjudicated[];
+/**
+ * Walks a supersession chain to whatever currently stands in its place.
+ *
+ * Both directions are followed, not just `strauss_superseded_by`. `supersede()`
+ * writes the pair, but a hand-edit can leave one side behind, and a walk that
+ * trusts only the forward pointer would silently return a record that something
+ * in the bundle openly claims to replace.
+ *
+ * Resolution happens here rather than being denormalised onto records at write
+ * time: a stored head would have to be rewritten on every ancestor whenever a
+ * chain grows, which is derived state that goes stale — the failure this design
+ * keeps avoiding elsewhere.
+ */
+declare function resolveHeads(from: KbRecord, byId: Map<string, KbRecord>): {
+    heads: KbRecord[];
+    warnings: KbWarning[];
+};
+
+/**
+ * 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.
+ */
+declare const TRACE_EDGES: readonly ["supersession", "anchor", "source"];
+type KbTraceEdge = (typeof TRACE_EDGES)[number];
+type KbTraceStep = {
+    record: KbRecord;
+    /** Hops from the seed. 0 is the seed itself. */
+    depth: number;
+    /** Why this record was reached. Empty for the seed. */
+    via: KbTraceEdge[];
+};
+type KbTraceOptions = {
+    edges?: readonly KbTraceEdge[];
+    /** Body links alone can reach the whole bundle, so a trace is always bounded. */
+    depth?: number;
+};
+/**
+ * How a position was arrived at, as a timeline.
+ *
+ * The inverse of a point query, and the reason the two cannot be one call with
+ * a flag: there, a `rejected` record is the most dangerous thing retrievable —
+ * here it is the content. A trace that drops the rejected alternatives and the
+ * superseded earlier understanding has removed the answer and kept the
+ * conclusion, which is what reading a diff already gives you.
+ *
+ * Ordered by `generated.at` rather than by relevance. Ranking a history is
+ * meaningless when the sequence is the point.
+ */
+declare function trace(seedId: string, bundle: KbRecord[], options?: KbTraceOptions): KbTraceStep[];
+
+declare const LOG_FILE = "log.jsonl";
+declare const kbLogEntrySchema: z.ZodObject<{
+    at: z.ZodString;
+    by: z.ZodString;
+    operation: z.ZodString;
+    conceptId: z.ZodString;
+    target: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+type KbLogEntry = z.infer<typeof kbLogEntrySchema>;
+/**
+ * The log is the bundle's only primary artifact, and the reason it is handled
+ * unlike `INDEX.md`.
+ *
+ * The index is derived: lose it and the records rebuild it. The log records
+ * events — which agent wrote what, and when — that leave no trace in the record
+ * set, so it cannot be regenerated from anything. Repair therefore means detect
+ * and report, never rewrite: rewriting an append-only log destroys the only
+ * copy of what it holds.
+ *
+ * JSONL rather than a markdown list. An earlier version rendered entries as
+ * `- <at> · <by> · <op> · <id>` and parsed them by splitting on the separator —
+ * a hand-written parser for a format invented here, which fails the first time
+ * a value contains the separator. JSON needs no parser and the schema below
+ * needs no separator to be unambiguous. Humans read the log through
+ * `strauss-kb log`, as they read everything else.
+ *
+ * One line per entry, appended with `O_APPEND`: POSIX makes the offset update
+ * atomic, and writes this size do not interleave on a local filesystem.
+ */
+declare function renderLogEntry(entry: KbLogEntry): string;
+type KbLogReadResult = {
+    entries: KbLogEntry[];
+    /** Lines that did not parse, with their 1-based position. Never rewritten. */
+    malformed: {
+        line: number;
+        text: string;
+    }[];
+};
+declare function parseLog(raw: string): KbLogReadResult;
+
+/**
+ * Default bundle, relative to the working directory. A scratch base lives here
+ * and is meant to be gitignored; a base worth keeping is written to a committed
+ * path instead, passed explicitly. Nothing promotes one to the other.
+ */
+declare const KB_DIR: string;
+type KbLogger = {
+    info?(entry: Record<string, unknown>): void;
+    warn?(entry: Record<string, unknown>): void;
+};
+/**
+ * A superseded record, named but not spelled out.
+ *
+ * Standing is a qualifier on a body, and over a long session the body outlives
+ * the qualifier — the reader keeps what the record said and loses that it no
+ * longer holds. A stub has nothing left to act on, so the failure cannot occur,
+ * and `trace` still reaches the content through the id.
+ */
+type KbSupersededStub = {
+    conceptId: string;
+    title: string | null;
+    supersededBy: string[];
+    at: string | null;
+};
+type KbLoadResult = {
+    loaded: true;
+    records: KbAdjudicated[];
+    /** Named only. Their bodies are reachable through `trace`. */
+    superseded: KbSupersededStub[];
+    recordCount: number;
+    approxTokens: number;
+    budgetTokens: number;
+} | {
+    loaded: false;
+    recordCount: number;
+    approxTokens: number;
+    budgetTokens: number;
+};
+type KbWriteInput = {
+    type: string;
+    slug: string;
+    frontmatter: Omit<KbRecordFrontmatter, "type">;
+    body: string;
+    /** Replace an existing record rather than failing on the collision. */
+    overwrite?: boolean;
+};
+/**
+ * Reads and writes a knowledge bundle.
+ *
+ * One record per file, deliberately. Several agents run in parallel against the
+ * same bundle, and a shared file would need merging — a file-per-record store
+ * has no write conflict to resolve, only distinct filenames to choose.
+ *
+ * The bundle is addressed by path rather than fixed to one directory. A base
+ * belongs to whatever prompted it — a worktree, an investigation, a document —
+ * and one hardcoded location cannot be all of those.
+ *
+ * Framework-free on purpose. The consumers are a library caller, a CLI an agent
+ * shells out to, and an MCP server; the store takes a logger rather than
+ * reaching for one, because only some of those have anything to reach into.
+ */
+declare class KbStore {
+    private readonly logger;
+    constructor(logger?: KbLogger);
+    /**
+     * Writes one record. `type` and `slug` compose both the filename and the
+     * concept id, so a caller cannot produce a file whose identity disagrees with
+     * its contents.
+     */
+    write(bundlePath: string, input: KbWriteInput, actor?: string): Promise<KbRecord>;
+    /** One record by concept id, or null when it does not exist. */
+    read(bundlePath: string, conceptId: string): Promise<KbRecord | null>;
+    /**
+     * Every record in the bundle, optionally narrowed to one type.
+     *
+     * A file that fails to parse is skipped and logged rather than thrown: one
+     * malformed record — hand-edited, or written by a producer we don't know —
+     * must not make the whole bundle unreadable.
+     */
+    list(bundlePath: string, type?: string): Promise<KbRecord[]>;
+    /**
+     * Moves a record's status, preserving everything else.
+     *
+     * Read-modify-write on one file is the one place two agents genuinely race,
+     * and the fix is a compare-and-swap rather than a lock: hash on read, verify
+     * the file is unchanged immediately before writing, fail if it moved. A lock
+     * would buy the same guarantee and add a stale-lock failure mode — a writer
+     * killed mid-hold blocks every later one until someone reasons about
+     * timeouts.
+     */
+    setStatus(bundlePath: string, conceptId: string, status: KbRecordStatus, actor?: string): Promise<KbRecord>;
+    /**
+     * Marks `conceptId` superseded by `replacementId`, and links both directions.
+     *
+     * Writing one side and letting a validator notice the other is missing was
+     * the previous arrangement; doing both here means the backlink cannot drift
+     * in normal use, and validation drops to catching hand-edits.
+     */
+    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>;
+    /**
+     * Records matching a text query, each carrying its standing.
+     *
+     * Relevance comes from qmd's BM25 where an index is available and from a
+     * substring scan where it is not. What never moves to the ranker is the
+     * adjudication below it: a ranker answers relevance, and relevance is not
+     * standing — a superseded record is the older, longer, more general one, so
+     * ranking alone prefers what is no longer true.
+     *
+     * The fallback is deliberate. A search index is an optimisation, so losing it
+     * degrades recall and must never change the answer's shape or fail the call.
+     */
+    query(bundlePath: string, text: string, options?: {
+        type?: string;
+        includeNonCurrent?: boolean;
+    }): Promise<KbAdjudicated[]>;
+    private rank;
+    /**
+     * The whole base, adjudicated, when it is small enough to hand over.
+     *
+     * At the sizes these reach — twenty records is about three thousand tokens —
+     * loading everything beats searching it, and measurably: on nine questions
+     * whose wording appears in no record, a reader holding the base answered
+     * eight against an embedding search's four. Two of those differences are
+     * structural. A reader can say no record answers the question; vector search
+     * returns its nearest neighbour whatever the distance. And a reader picks the
+     * record that answers the question rather than the one nearest the topic.
+     * See the README's retrieval section for the measurements.
+     *
+     * Load it for a question, not for a session — a base read into a long
+     * conversation is summarised away by the end of it.
+     *
+     * Refuses rather than truncates when the base is too large. A truncated base
+     * is indistinguishable from a complete one, so a caller would answer "that
+     * was never decided" from a slice it did not know was a slice.
+     */
+    load(bundlePath: string, options?: {
+        budgetTokens?: number;
+        type?: string;
+    }): Promise<KbLoadResult>;
+    /** How a position was arrived at, as a timeline. See `trace.ts`. */
+    trace(bundlePath: string, seedId: string, options?: KbTraceOptions): Promise<KbTraceStep[]>;
+    /**
+     * The stored index, rebuilt if it disagrees with the records.
+     *
+     * Repair on read is what makes the lock-free write path safe: a writer whose
+     * scan predated another writer's record publishes a momentarily stale index,
+     * and the next reader through here settles it.
+     */
+    readIndex(bundlePath: string): Promise<string>;
+    /**
+     * 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.
+     */
+    readLog(bundlePath: string): Promise<ReturnType<typeof parseLog>>;
+    private mutate;
+    /**
+     * Two guarantees, both about writers running in parallel.
+     *
+     * The record is written to a staging file and only then published, so a
+     * concurrent reader sees the whole record or no record — never half of one. A
+     * plain write is not atomic, and `list()` skips what it cannot parse, so a
+     * torn read would be silently reported as a malformed record.
+     *
+     * Publishing uses `link` rather than `rename` unless the caller asked to
+     * overwrite: `link` fails with EEXIST instead of replacing, which turns "two
+     * writers chose the same concept id" from silent data loss into a collision
+     * the caller has to answer. Both are atomic; only `rename` clobbers.
+     *
+     * The staging name deliberately does not end in `.md` — `list()` would
+     * otherwise try to read it mid-write.
+     */
+    private publish;
+    /** Appends one log line. Failing to log must not fail the mutation. */
+    private record;
+    private parse;
+    private root;
+    private recordPath;
+}
+
+/**
+ * The error shape the store throws.
+ *
+ * Every caller here is an agent, reached through a CLI or a stdio MCP server,
+ * so a bare `Error` arrives as an opaque string. What a caller has to act on is
+ * carried as fields instead: `code` separates "pick a different slug and retry"
+ * from "this input was never going to work", and `retriable` says whether
+ * re-running the same call could succeed.
+ *
+ * No dependency, deliberately. This is four fields and a constructor; an error
+ * library would be a runtime dependency in aid of that.
+ */
+declare enum Fault {
+    /** The environment is wrong — a path, a permission, a missing directory. */
+    Configuration = "Configuration",
+    /** Nothing the caller did; retrying may work. */
+    System = "System",
+    /** The call was malformed or asked for something impossible. */
+    User = "User"
+}
+/** Machine-readable discriminant, stable across message rewording. */
+declare enum ErrorTypes {
+    KbRecordAlreadyExists = "KbRecordAlreadyExists",
+    KbInvalidConceptId = "KbInvalidConceptId",
+    KbRecordNotFound = "KbRecordNotFound",
+    KbWriteConflict = "KbWriteConflict"
+}
+type ErrorDetails = Record<string, string | boolean | number | string[] | boolean[] | number[]>;
+interface ErrorProps {
+    message: string;
+    errorType?: ErrorTypes;
+    details?: ErrorDetails;
+    name?: string;
+    code?: number;
+    fault?: Fault;
+    retriable?: boolean;
+    reportToUser?: boolean;
+}
+declare class BaseError extends Error {
+    code: number;
+    errorType?: ErrorTypes;
+    fault?: Fault;
+    retriable: boolean;
+    reportToUser: boolean;
+    details?: ErrorDetails;
+    constructor(props: ErrorProps);
+}
+
+/**
+ * Every caller of this store is an agent, reached through a CLI or a stdio MCP
+ * server, so a bare `Error` reaches it as an opaque string. The `code` carries
+ * the distinction the caller has to act on: 409 means pick a different slug and
+ * retry, 400 means the input was never going to work.
+ */
+declare class KbRecordAlreadyExistsError extends BaseError {
+    readonly conceptId: string;
+    constructor(conceptId: string);
+}
+declare class KbRecordNotFoundError extends BaseError {
+    readonly conceptId: string;
+    constructor(conceptId: string);
+}
+/** Retriable, unlike the others: re-reading and re-applying usually succeeds. */
+declare class KbWriteConflictError extends BaseError {
+    readonly conceptId: string;
+    constructor(conceptId: string);
+}
+declare class KbInvalidConceptIdError extends BaseError {
+    constructor(message: string, details: Record<string, string>);
+}
+
+/**
+ * What each record type is for, and the shape of its body.
+ *
+ * A table rather than twelve composer modules. The types differ only in which
+ * questions their body answers and where they start in the lifecycle; encoding
+ * that as data keeps the one composer honest and makes adding a type an edit
+ * rather than a file.
+ *
+ * `sections` are ordered. A section the caller leaves empty is omitted rather
+ * than rendered with a placeholder — an empty "## Evidence" reads as evidence
+ * that was looked for and not found.
+ */
+type KbRecordTypeSpec = {
+    /** One line, for `INDEX.md` legends and CLI help. */
+    purpose: string;
+    /** Ordered body headings. The first is the record's central claim. */
+    sections: readonly string[];
+    /** Where a freshly written record of this type starts. */
+    initialStatus: KbRecordStatus;
+};
+declare const RECORD_TYPES: Readonly<Record<KbRecordType, KbRecordTypeSpec>>;
+declare function isKbRecordType(value: string): value is KbRecordType;
+
+declare const composeInputSchema: z.ZodObject<{
+    slug: z.ZodString;
+    title: z.ZodString;
+    why: z.ZodString;
+    sections: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+    anchors: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        file: z.ZodString;
+        symbol: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>>>;
+    sources: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        resource: z.ZodString;
+        title: z.ZodOptional<z.ZodString>;
+        author: z.ZodOptional<z.ZodString>;
+        last_modified: z.ZodOptional<z.ZodString>;
+    }, z.core.$loose>>>;
+    assumption: z.ZodOptional<z.ZodBoolean>;
+    verify: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    tags: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    relatedConceptIds: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    supersedes: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    materiality: z.ZodOptional<z.ZodEnum<{
+        blocking: "blocking";
+        important: "important";
+        "non-blocking": "non-blocking";
+    }>>;
+    confidence: z.ZodOptional<z.ZodEnum<{
+        low: "low";
+        medium: "medium";
+        high: "high";
+    }>>;
+    owner: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+type ComposeInput = z.infer<typeof composeInputSchema>;
+type ComposedRecord = {
+    type: string;
+    slug: string;
+    frontmatter: Omit<KbRecordFrontmatter, "type">;
+    body: string;
+};
+/**
+ * Builds one record's frontmatter and body from its type's spec.
+ *
+ * Edges go in the body rather than frontmatter because that is where OKF puts
+ * them: consumers read markdown links as directed but untyped relationships,
+ * with "the specific kind conveyed by the surrounding prose, not by the link
+ * itself". Broken links are explicitly legal, which matters here — records are
+ * routinely written before the ones they point at exist.
+ */
+declare function composeRecord(type: KbRecordType, input: ComposeInput, writtenBy: string, writtenAt: string): ComposedRecord;
+
+declare const INDEX_FILE = "INDEX.md";
+/**
+ * `INDEX.md` is a projection — every byte recomputable from record frontmatter.
+ *
+ * That is what lets parallel writers regenerate it without a lock: they compute
+ * the same function of the same records, so two concurrent regenerations differ
+ * only in how recent each writer's scan was, and the next read settles it. The
+ * file is therefore eventually correct rather than always correct, which is the
+ * right trade for something nothing reads transactionally.
+ *
+ * Lines carry `description`, not just a title. A reader consults the index to
+ * decide what is worth opening, and a list of titles does not answer that.
+ */
+declare function renderIndex(records: KbRecord[]): string;
+/** Whether the stored projection still matches the records it claims to index. */
+declare function indexIsStale(stored: string | null, expected: string): boolean;
+
+/**
+ * The frontmatter contract, emitted rather than restated.
+ *
+ * Prose describing a schema drifts from the code that enforces it; a generated
+ * artifact cannot. Documentation points at this, a YAML language server
+ * validates hand-edited records against it, and a consumer that is not
+ * TypeScript has something to check.
+ *
+ * `io: 'input'` on purpose. `strauss_status` carries a default, so the output
+ * type marks it required while the *document* may legitimately omit it — and
+ * the document is what this schema is used to validate.
+ */
+declare function kbJsonSchemas(): Record<string, unknown>;
+
+/**
+ * Which records apply to which part of a change.
+ *
+ * Takes a structural description of a diff rather than a patch, so this package
+ * carries no diff parser: callers already have one, and a knowledge base has no
+ * business preferring a particular flavour of unified diff.
+ *
+ * Deterministic on purpose. Every step here is mechanical — the one judgment,
+ * whether a matched record is worth showing a reviewer, is deliberately absent.
+ * A model placed here would sit between the reviewer and their diff on every
+ * review, to answer a question nobody has yet shown needs asking.
+ *
+ * Distinct from `load()`, which hands a reader the whole base. That answers
+ * "does anything address this question"; this answers "what is attached to this
+ * code", and an anchor is the author's own statement rather than an inference
+ * from one. A reader guessing which record relates to a hunk would be guessing
+ * at something already written down — and a diff has dozens of hunks, which is
+ * dozens of reader calls against microseconds of matching. Where they compose:
+ * this narrows a hunk to a few records, and a reader asked to explain them gets
+ * those, not the base.
+ */
+type DiffHunk = {
+    /** 1-based, inclusive, in the file's post-change line numbering. */
+    startLine: number;
+    endLine: number;
+};
+type DiffFile = {
+    /** Repo-relative, matching how anchors are written. */
+    filePath: string;
+    hunks: DiffHunk[];
+};
+/**
+ * A symbol resolved to lines. Supplied by whatever the caller uses to index
+ * symbols; absence is tolerated — see `place()`.
+ */
+type SymbolRange = {
+    file: string;
+    symbol: string;
+    startLine: number;
+    endLine: number;
+};
+type DiffMatch = {
+    filePath: string;
+    hunk: DiffHunk;
+    /** Current records first — what still holds should be read before what does not. */
+    records: KbAdjudicated[];
+    /**
+     * `symbol` when every record here was placed by a resolved symbol range,
+     * `file` when at least one fell back to the whole file. Reported rather than
+     * hidden: a caller showing a file-level match as though it were pinned to
+     * these lines is claiming a precision it does not have.
+     */
+    precision: "symbol" | "file";
+};
+type MatchOptions = {
+    /** Without these, symbol anchors degrade to file level rather than vanishing. */
+    symbolRanges?: SymbolRange[];
+    now?: Date;
+};
+declare function matchToDiff(files: DiffFile[], records: KbRecord[], options?: MatchOptions): DiffMatch[];
+
+type KbValidationProblem = {
+    check: string;
+    conceptId: string;
+    note: string;
+};
+/**
+ * Checks that only hold across the whole bundle.
+ *
+ * Per-record shape is the schema's job and is enforced on every read, so
+ * nothing here re-states it. What a schema cannot see is whether one record's
+ * pointers agree with another's — and since `supersede()` now writes both
+ * directions, a disagreement means someone edited a file by hand.
+ */
+declare function validateBundle(records: KbRecord[]): KbValidationProblem[];
+
+/**
+ * The record written while a change is being made: why it is shaped the way it
+ * is, anchored to the symbols it touches.
+ *
+ * A decision is the one thing a later pass cannot recover. The diff shows what
+ * changed; nothing in it says which alternative was rejected, or which
+ * constraint a future reader would otherwise "simplify" away. Everything else a
+ * review needs — categories, moves, formatting — is derivable from the finished
+ * diff and does not belong here.
+ */
+declare const DECISION_TYPE = "decision";
+/**
+ * Slug for the explicit "nothing to record here" answer.
+ *
+ * Gating on "did you write a decision?" rewards writing a junk decision. Gating
+ * on "did you answer?" does not, so silence has to be expressible as a claim:
+ * one record, one sentence, auditable after the fact. Work that genuinely
+ * needed no decision says so; work that says nothing at all is the case worth
+ * surfacing.
+ */
+declare const NO_DECISION_SLUG = "none";
+/**
+ * Decisions keep a typed input of their own where the generic composer takes a
+ * section map. `alternative` is not a nicety here — "what was rejected" is the
+ * part of a decision that a later reader cannot reconstruct, so it gets a field
+ * rather than a heading a writer may forget to fill.
+ */
+declare const decisionInputSchema: z.ZodObject<{
+    title: z.ZodString;
+    assumption: z.ZodOptional<z.ZodBoolean>;
+    tags: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    sources: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        resource: z.ZodString;
+        title: z.ZodOptional<z.ZodString>;
+        author: z.ZodOptional<z.ZodString>;
+        last_modified: z.ZodOptional<z.ZodString>;
+    }, z.core.$loose>>>;
+    slug: z.ZodString;
+    why: z.ZodString;
+    anchors: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        file: z.ZodString;
+        symbol: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>>>;
+    verify: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    relatedConceptIds: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    supersedes: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    materiality: z.ZodOptional<z.ZodEnum<{
+        blocking: "blocking";
+        important: "important";
+        "non-blocking": "non-blocking";
+    }>>;
+    confidence: z.ZodOptional<z.ZodEnum<{
+        low: "low";
+        medium: "medium";
+        high: "high";
+    }>>;
+    owner: z.ZodOptional<z.ZodString>;
+    alternative: z.ZodOptional<z.ZodString>;
+    impact: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+type DecisionInput = z.infer<typeof decisionInputSchema>;
+declare function composeDecisionRecord(input: DecisionInput, writtenBy: string, writtenAt: string): ComposedRecord;
+/** The explicit no-decision claim, so an absence and an answer stay distinct. */
+declare function composeNoDecisionRecord(reason: string, writtenBy: string, writtenAt: string): ComposedRecord;
+/** Whether a record is the explicit no-decision claim rather than a decision. */
+declare function isNoDecisionRecord(record: KbRecord): boolean;
+/**
+ * Decisions in the bundle, excluding the no-decision claim.
+ *
+ * Callers asking "what was decided" must not be handed the record that exists
+ * precisely to say nothing was.
+ */
+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 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.
+ */
+type KbCommandContext = {
+    store: KbStore;
+    actor: string;
+    now: () => string;
+};
+type KbCommand<Shape extends z.ZodRawShape = z.ZodRawShape> = {
+    /** CLI verb. */
+    name: string;
+    /** MCP tool name. */
+    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. */
+    fromArgv(argv: string[], bundlePath: string, stdin: () => Promise<string>): Promise<unknown> | unknown;
+    run(ctx: KbCommandContext, input: z.infer<z.ZodObject<Shape>>): Promise<unknown>;
+    /**
+     * 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.
+     */
+    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>>;
+}>>>;
+
+/**
+ * A knowledge base's own MCP server, over stdio.
+ *
+ * Standalone because a base is self-contained: a directory of markdown that
+ * needs no database, no HTTP surface, and no running service to read. Folding
+ * these tools into a larger server would make every consumer start that server
+ * to open files it could open itself.
+ *
+ * Every tool is a projection of `KB_COMMANDS`, which the CLI also projects, so
+ * the two cannot drift.
+ */
+declare function createKbMcpServer(): McpServer;
+declare function runKbMcpServer(): Promise<void>;
+
+declare function runKbCli(argv: string[]): Promise<void>;
+
+declare const SEARCH_INDEX_FILE = ".index.sqlite";
+/**
+ * BM25 over one knowledge base, via qmd's SDK.
+ *
+ * Reached only when a base is too large to hand over whole — see `load()`,
+ * which is the first thing a reader should try.
+ *
+ * Lexical only. `searchLex` is BM25 and needs no model. Measured against the
+ * substring scan it replaces it wins on word forms and little else: `pages`
+ * finds a record saying only `page`, and eight of nine probe queries returned
+ * exactly what substring returned.
+ *
+ * The vector tier does close the semantic gap — "why not just use a mutex"
+ * finds the record about compare-and-swap, which no lexical match can. It stays
+ * off because its scores do not separate right from wrong: a wrong hit scored
+ * 0.318 against a correct one at 0.295, and a query about a subject absent from
+ * the base still returns its nearest record rather than nothing.
+ *
+ * The index is derived and disposable — one file per base, gitignored, deleted
+ * and rebuilt at will. That is only true because a base is self-contained: an
+ * index covering exactly one directory can always be rebuilt from it.
+ *
+ * qmd is used as a **library**, and is an optional peer dependency: with it
+ * absent every path here still answers, `searchBase` returns null, and the
+ * store falls back to a substring scan. Its own MCP server would let an agent
+ * reach a base without passing the store, and its default markdown glob would
+ * return `INDEX.md` as a search hit — the case `list()` already excludes,
+ * reintroduced by a reader this package does not control. Hence the explicit
+ * `ignore` below.
+ */
+/**
+ * A hit as qmd reports it — by its own normalised path, not by our identity.
+ *
+ * qmd rewrites `decision.cursor-keyset.md` to `decision-cursor-keyset.md`,
+ * which destroys the separator between a record's type and its slug and cannot
+ * be undone from the string alone: `decision-cursor-keyset` could be the type
+ * `decision` or a type `decision-cursor`. The caller maps these back through
+ * the records it already holds rather than parsing them.
+ */
+type SearchHit = {
+    displayPath: string;
+    score: number;
+};
+type KbSearchLogger = {
+    warn?(entry: Record<string, unknown>): void;
+};
+/** What this module needs of qmd, which is all it is allowed to assume. */
+type QmdModule = {
+    createStore(options: unknown): Promise<unknown>;
+};
+type SearchOptions = {
+    limit?: number;
+    logger?: KbSearchLogger;
+    /**
+     * The backend, supplied rather than imported. Production passes nothing and
+     * gets the dynamic import below; a caller that already holds qmd — or a test
+     * covering the present-backend branch on a machine where the optional peer is
+     * not installed — passes it here.
+     */
+    qmd?: QmdModule;
+};
+/**
+ * Opens (or creates) the base's index and answers a query against it.
+ *
+ * Re-indexes when the index is older than the newest record rather than on a
+ * schedule or a write hook: the same repair-on-read rule `INDEX.md` follows,
+ * and for the same reason — a derived artifact that can rebuild itself does not
+ * need anyone to remember to rebuild it.
+ */
+declare function searchBase(bundlePath: string, query: string, options?: SearchOptions): Promise<SearchHit[] | null>;
+/**
+ * Maps qmd's normalised paths back onto real records.
+ *
+ * Comparing on the same normalisation rather than trying to invert it: a dot in
+ * a concept id and a dash in a slug are indistinguishable once qmd has rewritten
+ * the name, so the only reliable direction is forwards, from ids we hold.
+ */
+declare function resolveHits<T extends {
+    conceptId: string;
+}>(hits: SearchHit[], records: T[]): T[];
+/**
+ * Loaded on demand so a caller that never searches pays nothing for a
+ * dependency that pulls in native SQLite bindings and a llama runtime — and
+ * returns null rather than throwing when it is not installed at all, which is
+ * the normal case for an optional peer.
+ */
+declare function loadQmd(logger?: KbSearchLogger): Promise<QmdModule | null>;
+
+/**
+ * Frontmatter round-tripping, thin over gray-matter.
+ *
+ * Thin on purpose. A record is a YAML block and a markdown body, and every
+ * hand-rolled reader of that shape eventually meets a nested map — an OKF
+ * `generated`, a `sources[]`, a `verified[]` — and misreads it. The parser is
+ * therefore borrowed and the only thing added is the schema gate below.
+ */
+declare function stringifyMarkdownWithFrontmatter(content: string, frontmatter: Record<string, unknown>): string;
+declare function splitMarkdownFrontmatter(text: string): {
+    content: string;
+    prefix: string;
+    raw: Record<string, unknown>;
+};
+/**
+ * Splits, then validates the frontmatter against a schema.
+ *
+ * The result is a `safeParse` outcome rather than a throw: one malformed record
+ * must not make a whole directory unreadable, so the caller decides whether to
+ * skip it or fail.
+ */
+declare function parseMarkdownWithFrontmatter<S extends z.ZodType>(text: string, schema: S): {
+    content: string;
+    prefix: string;
+    raw: Record<string, unknown>;
+    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 };