@saasontools/strauss-kb 0.1.0

package/dist/mcp-main.cjs

@@ -0,0 +1,1522 @@
+#!/usr/bin/env node
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+
+// src/mcp.ts
+var import_mcp = require("@modelcontextprotocol/sdk/server/mcp.js");
+var import_stdio = require("@modelcontextprotocol/sdk/server/stdio.js");
+
+// src/commands.ts
+var import_zod6 = require("zod");
+
+// src/compose.ts
+var import_zod2 = require("zod");
+
+// src/kb-record.schema.ts
+var import_zod = require("zod");
+var kbSourceSchema = import_zod.z.object({
+  id: import_zod.z.string().min(1),
+  resource: import_zod.z.string().min(1),
+  title: import_zod.z.string().min(1).optional(),
+  author: import_zod.z.string().min(1).optional(),
+  last_modified: import_zod.z.string().min(1).optional()
+}).passthrough();
+var kbActorStampSchema = import_zod.z.object({
+  by: import_zod.z.string().min(1),
+  at: import_zod.z.string().min(1)
+}).passthrough();
+var kbAnchorSchema = import_zod.z.object({
+  file: import_zod.z.string().min(1),
+  symbol: import_zod.z.string().min(1).optional()
+}).strict();
+var KB_RECORD_TYPES = [
+  "fact",
+  "requirement",
+  "constraint",
+  "decision",
+  "assumption",
+  "open-question",
+  "risk",
+  "contract",
+  "flow",
+  "affected-system",
+  "test-obligation",
+  "source-note"
+];
+var KB_SLUG_PATTERN = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+var KB_CONCEPT_ID_PATTERN = /^[a-z0-9]+(?:-[a-z0-9]+)*\.[a-z0-9]+(?:-[a-z0-9]+)*$/;
+var kbConceptIdSchema = import_zod.z.string().regex(KB_CONCEPT_ID_PATTERN, {
+  message: "concept id must be <type>.<slug>, both kebab-case"
+});
+var KB_RECORD_STATUSES = [
+  "draft",
+  "proposed",
+  "accepted",
+  "open",
+  "resolved",
+  "rejected",
+  "superseded"
+];
+var KB_MATERIALITIES = [
+  "blocking",
+  "important",
+  "non-blocking"
+];
+var KB_CONFIDENCES = ["low", "medium", "high"];
+var kbRecordFrontmatterSchema = import_zod.z.object({
+  // OKF: the only always-required key. A concept carrying just `type` is
+  // fully conformant, so everything below stays optional.
+  type: import_zod.z.string().min(1),
+  // OKF recommended.
+  title: import_zod.z.string().min(1).optional(),
+  description: import_zod.z.string().min(1).optional(),
+  resource: import_zod.z.string().min(1).optional(),
+  tags: import_zod.z.array(import_zod.z.string()).optional(),
+  // OKF optional: provenance and freshness.
+  sources: import_zod.z.array(kbSourceSchema).optional(),
+  generated: kbActorStampSchema.optional(),
+  verified: import_zod.z.array(kbActorStampSchema).optional(),
+  stale_after: import_zod.z.string().min(1).optional(),
+  // strauss extensions — see the module comment.
+  strauss_anchors: import_zod.z.array(kbAnchorSchema).optional(),
+  strauss_verify: import_zod.z.array(import_zod.z.string().min(1)).optional(),
+  // Total after parsing, tolerant before it. Our producers must supply a
+  // status — an absent one would leave every reader inventing its own default
+  // — but OKF calls a concept carrying only `type` fully conformant, so
+  // rejecting a foreign record for the lack of one would put us outside the
+  // spec. The default resolves it in the single place that can: here.
+  strauss_status: import_zod.z.enum(KB_RECORD_STATUSES).default("draft"),
+  strauss_supersedes: import_zod.z.array(import_zod.z.string().min(1)).optional(),
+  strauss_superseded_by: import_zod.z.string().min(1).optional(),
+  strauss_answered: kbActorStampSchema.optional(),
+  strauss_materiality: import_zod.z.enum(KB_MATERIALITIES).optional(),
+  strauss_confidence: import_zod.z.enum(KB_CONFIDENCES).optional(),
+  strauss_owner: import_zod.z.string().min(1).optional(),
+  // "No source exists" as a field rather than a sentinel entry inside
+  // `sources`. A sentinel in a reference list is a value doing work a field
+  // should do; as a field, `sources` may be legitimately empty.
+  strauss_assumption: import_zod.z.boolean().optional()
+}).passthrough();
+
+// src/record-types.ts
+var RECORD_TYPES = {
+  fact: {
+    purpose: "Observed or sourced fact",
+    sections: ["Claim", "Evidence", "Implication"],
+    initialStatus: "accepted"
+  },
+  requirement: {
+    purpose: "Required behavior or outcome",
+    sections: ["Claim", "Evidence", "Implication"],
+    initialStatus: "proposed"
+  },
+  constraint: {
+    purpose: "Limitation, compatibility boundary, policy, or restriction",
+    sections: ["Claim", "Evidence", "Implication"],
+    initialStatus: "accepted"
+  },
+  decision: {
+    purpose: "Chosen or proposed direction",
+    sections: ["Decision", "Rationale", "Rejected", "Impact"],
+    initialStatus: "accepted"
+  },
+  assumption: {
+    purpose: "Unsourced or not-yet-confirmed working assumption",
+    sections: ["Claim", "Why we think so", "What would falsify it"],
+    initialStatus: "draft"
+  },
+  "open-question": {
+    purpose: "Question needing resolution",
+    sections: ["Question", "Why it matters", "Default assumption"],
+    initialStatus: "open"
+  },
+  risk: {
+    purpose: "Something that can go wrong",
+    sections: ["Risk", "Why it matters", "Mitigation", "Verification"],
+    initialStatus: "open"
+  },
+  contract: {
+    purpose: "API, data, event, schema, or permission contract",
+    sections: ["Contract", "Producer", "Consumer", "Compatibility"],
+    initialStatus: "proposed"
+  },
+  flow: {
+    purpose: "Sequence, lifecycle, or state behavior",
+    sections: ["Flow", "Trigger", "Steps", "Failure modes"],
+    initialStatus: "accepted"
+  },
+  "affected-system": {
+    purpose: "Component, service, package, integration, or external system",
+    sections: ["System", "How it is affected", "Blast radius"],
+    initialStatus: "accepted"
+  },
+  "test-obligation": {
+    purpose: "Behavior or contract that must be verified",
+    sections: ["Obligation", "Why it matters", "How to verify"],
+    initialStatus: "open"
+  },
+  "source-note": {
+    purpose: "Extracted note from source material",
+    sections: ["Note", "Where it came from"],
+    initialStatus: "accepted"
+  }
+};
+function isKbRecordType(value) {
+  return Object.prototype.hasOwnProperty.call(RECORD_TYPES, value);
+}
+
+// src/compose.ts
+var composeInputSchema = import_zod2.z.object({
+  slug: import_zod2.z.string().min(1),
+  /** One line, in the reader's terms. Becomes OKF `title`. */
+  title: import_zod2.z.string().min(1),
+  /** The consequence — what breaks if this is wrong. Becomes `description`. */
+  why: import_zod2.z.string().min(1),
+  /** Keyed by section heading from the type's spec. Unknown keys rejected. */
+  sections: import_zod2.z.record(import_zod2.z.string(), import_zod2.z.string().min(1)).optional(),
+  anchors: import_zod2.z.array(kbAnchorSchema).optional(),
+  sources: import_zod2.z.array(kbSourceSchema).optional(),
+  /** No source exists, as a claim rather than a sentinel in `sources`. */
+  assumption: import_zod2.z.boolean().optional(),
+  verify: import_zod2.z.array(import_zod2.z.string().min(1)).optional(),
+  tags: import_zod2.z.array(import_zod2.z.string().min(1)).optional(),
+  /** Concept ids this record relates to; rendered as body links. */
+  relatedConceptIds: import_zod2.z.array(kbConceptIdSchema).optional(),
+  /** Concept ids this record replaces. The store settles the backlinks. */
+  supersedes: import_zod2.z.array(kbConceptIdSchema).optional(),
+  materiality: import_zod2.z.enum(KB_MATERIALITIES).optional(),
+  confidence: import_zod2.z.enum(KB_CONFIDENCES).optional(),
+  owner: import_zod2.z.string().min(1).optional()
+}).strict();
+function composeRecord(type, input, writtenBy, writtenAt) {
+  const parsed = composeInputSchema.parse(input);
+  const spec = RECORD_TYPES[type];
+  const sections = parsed.sections ?? {};
+  const unknown = Object.keys(sections).filter(
+    (heading) => !spec.sections.includes(heading)
+  );
+  if (unknown.length) {
+    throw new Error(
+      `kb: ${type} has no section ${unknown.join(", ")} \u2014 expected one of ${spec.sections.join(", ")}`
+    );
+  }
+  const frontmatter = {
+    title: parsed.title,
+    description: parsed.why,
+    generated: { by: writtenBy, at: writtenAt },
+    // Empty rather than absent: a later verification pass appends here, and an
+    // empty list says "not yet verified" where a missing key would only say
+    // "this producer didn't think about it".
+    verified: [],
+    strauss_status: spec.initialStatus
+  };
+  if (parsed.anchors?.length) frontmatter.strauss_anchors = parsed.anchors;
+  if (parsed.verify?.length) frontmatter.strauss_verify = parsed.verify;
+  if (parsed.tags?.length) frontmatter.tags = parsed.tags;
+  if (parsed.sources?.length) frontmatter.sources = parsed.sources;
+  if (parsed.assumption) frontmatter.strauss_assumption = true;
+  if (parsed.materiality) frontmatter.strauss_materiality = parsed.materiality;
+  if (parsed.confidence) frontmatter.strauss_confidence = parsed.confidence;
+  if (parsed.owner) frontmatter.strauss_owner = parsed.owner;
+  if (parsed.supersedes?.length)
+    frontmatter.strauss_supersedes = parsed.supersedes;
+  const blocks = [];
+  for (const heading of spec.sections) {
+    const text = sections[heading];
+    if (text) blocks.push(`## ${heading}
+
+${text}`);
+  }
+  if (!blocks.length) blocks.push(parsed.why);
+  for (const related of parsed.relatedConceptIds ?? []) {
+    blocks.push(`Relates to [${related}](${related}.md).`);
+  }
+  if (parsed.sources?.length) {
+    blocks.push(
+      parsed.sources.map((source) => `[^${source.id}]: ${source.title ?? source.resource}`).join("\n")
+    );
+  }
+  return {
+    type,
+    slug: parsed.slug,
+    frontmatter,
+    body: `${blocks.join("\n\n")}
+`
+  };
+}
+
+// src/decision-record.ts
+var import_zod3 = require("zod");
+var DECISION_TYPE = "decision";
+var NO_DECISION_SLUG = "none";
+var decisionInputSchema = composeInputSchema.omit({ sections: true }).extend({
+  alternative: import_zod3.z.string().min(1).optional(),
+  impact: import_zod3.z.string().min(1).optional()
+}).strict();
+function composeDecisionRecord(input, writtenBy, writtenAt) {
+  const { alternative, impact, ...rest } = input;
+  return composeRecord(
+    DECISION_TYPE,
+    {
+      ...rest,
+      sections: {
+        Decision: input.title,
+        Rationale: input.why,
+        ...alternative ? { Rejected: alternative } : {},
+        ...impact ? { Impact: impact } : {}
+      }
+    },
+    writtenBy,
+    writtenAt
+  );
+}
+function composeNoDecisionRecord(reason, writtenBy, writtenAt) {
+  return composeRecord(
+    DECISION_TYPE,
+    {
+      slug: NO_DECISION_SLUG,
+      title: "No decision to record",
+      why: reason,
+      sections: { Decision: reason }
+    },
+    writtenBy,
+    writtenAt
+  );
+}
+
+// src/json-schema.ts
+var import_zod5 = require("zod");
+
+// src/kb-log.ts
+var import_zod4 = require("zod");
+var LOG_FILE = "log.jsonl";
+var kbLogEntrySchema = import_zod4.z.object({
+  at: import_zod4.z.string().min(1),
+  by: import_zod4.z.string().min(1),
+  operation: import_zod4.z.string().min(1),
+  conceptId: import_zod4.z.string().min(1),
+  /** Second concept id, where the operation relates two — supersession. */
+  target: import_zod4.z.string().min(1).optional()
+}).strict();
+function renderLogEntry(entry) {
+  return `${JSON.stringify(kbLogEntrySchema.parse(entry))}
+`;
+}
+function parseLog(raw) {
+  const entries = [];
+  const malformed = [];
+  raw.split("\n").forEach((text, index) => {
+    if (!text.trim()) return;
+    let value;
+    try {
+      value = JSON.parse(text);
+    } catch {
+      malformed.push({ line: index + 1, text });
+      return;
+    }
+    const parsed = kbLogEntrySchema.safeParse(value);
+    if (!parsed.success) {
+      malformed.push({ line: index + 1, text });
+      return;
+    }
+    entries.push(parsed.data);
+  });
+  return { entries, malformed };
+}
+
+// src/json-schema.ts
+function kbJsonSchemas() {
+  return {
+    recordFrontmatter: import_zod5.z.toJSONSchema(kbRecordFrontmatterSchema, {
+      io: "input"
+    }),
+    composeInput: import_zod5.z.toJSONSchema(composeInputSchema, { io: "input" }),
+    logEntry: import_zod5.z.toJSONSchema(kbLogEntrySchema, { io: "input" })
+  };
+}
+
+// src/trace.ts
+var TRACE_EDGES = ["supersession", "anchor", "source"];
+function trace(seedId, bundle, options = {}) {
+  const edges = options.edges?.length ? options.edges : TRACE_EDGES;
+  const maxDepth = options.depth ?? 3;
+  const byId = new Map(bundle.map((record) => [record.conceptId, record]));
+  const seed = byId.get(seedId);
+  if (!seed) return [];
+  const reached = /* @__PURE__ */ new Map([
+    [seedId, { record: seed, depth: 0, via: [] }]
+  ]);
+  let frontier = [seed];
+  for (let depth = 1; depth <= maxDepth && frontier.length; depth += 1) {
+    const next = [];
+    for (const from of frontier) {
+      for (const edge of edges) {
+        for (const record of neighbours(from, bundle, edge)) {
+          const existing = reached.get(record.conceptId);
+          if (existing) {
+            if (existing.depth > 0 && !existing.via.includes(edge)) {
+              existing.via.push(edge);
+            }
+            continue;
+          }
+          reached.set(record.conceptId, { record, depth, via: [edge] });
+          next.push(record);
+        }
+      }
+    }
+    frontier = next;
+  }
+  return [...reached.values()].sort(byGeneratedAt);
+}
+function neighbours(from, bundle, edge) {
+  switch (edge) {
+    case "supersession":
+      return bundle.filter(
+        (candidate) => candidate.conceptId !== from.conceptId && (candidate.conceptId === from.frontmatter.strauss_superseded_by || from.frontmatter.strauss_supersedes?.includes(
+          candidate.conceptId
+        ) || candidate.frontmatter.strauss_superseded_by === from.conceptId || candidate.frontmatter.strauss_supersedes?.includes(from.conceptId))
+      );
+    // The edge that answers "why is this code shaped this way": every record
+    // attached to the same file or symbol, whatever its standing.
+    case "anchor": {
+      const mine = from.frontmatter.strauss_anchors ?? [];
+      if (!mine.length) return [];
+      return bundle.filter(
+        (candidate) => candidate.conceptId !== from.conceptId && (candidate.frontmatter.strauss_anchors ?? []).some(
+          (theirs) => mine.some((ours) => anchorsTouch(ours, theirs))
+        )
+      );
+    }
+    case "source": {
+      const mine = new Set((from.frontmatter.sources ?? []).map((s) => s.id));
+      if (!mine.size) return [];
+      return bundle.filter(
+        (candidate) => candidate.conceptId !== from.conceptId && (candidate.frontmatter.sources ?? []).some(
+          (source) => mine.has(source.id)
+        )
+      );
+    }
+  }
+}
+function anchorsTouch(left, right) {
+  if (left.file !== right.file) return false;
+  if (!left.symbol || !right.symbol) return true;
+  return left.symbol === right.symbol;
+}
+function byGeneratedAt(left, right) {
+  const at = (step) => step.record.frontmatter.generated?.at ?? "";
+  return at(left).localeCompare(at(right)) || left.depth - right.depth;
+}
+
+// src/validate.ts
+function validateBundle(records) {
+  const byId = new Map(records.map((record) => [record.conceptId, record]));
+  const problems = [];
+  const report = (check, conceptId2, note) => problems.push({ check, conceptId: conceptId2, note });
+  for (const record of records) {
+    const { conceptId: conceptId2, frontmatter: fm } = record;
+    if (!isKbRecordType(fm.type)) {
+      report("type", conceptId2, `unrecognised type "${fm.type}"`);
+    }
+    if (fm.strauss_status === "superseded") {
+      const by = fm.strauss_superseded_by;
+      if (!by) {
+        report("superseded_by", conceptId2, "superseded with no replacement");
+      } else if (!byId.has(by)) {
+        report("superseded_by", conceptId2, `replacement ${by} is missing`);
+      } else if (!byId.get(by)?.frontmatter.strauss_supersedes?.includes(conceptId2)) {
+        report("backlink", by, `does not list ${conceptId2} in supersedes`);
+      }
+    }
+    for (const old of fm.strauss_supersedes ?? []) {
+      const previous = byId.get(old);
+      if (!previous) {
+        report("supersedes", conceptId2, `target ${old} is missing`);
+      } else if (previous.frontmatter.strauss_status !== "superseded") {
+        report("supersedes", conceptId2, `${old} is not marked superseded`);
+      }
+    }
+    if (fm.strauss_assumption && fm.sources?.length) {
+      report("assumption", conceptId2, "marked an assumption but cites sources");
+    }
+  }
+  return problems;
+}
+
+// src/commands.ts
+var bundlePath = import_zod6.z.string().min(1).describe("Absolute path to the knowledge base directory.");
+var conceptId = import_zod6.z.string().min(1).describe("e.g. decision.cursor-v2");
+function define(command) {
+  return command;
+}
+var KB_COMMANDS = [
+  define({
+    name: "write",
+    tool: "kb_write",
+    usage: "write <type> < record.json",
+    description: [
+      "Write one record. Search first \u2014 the same knowledge filed twice under different slugs is how a base rots, and a duplicate concept id is rejected rather than overwritten. Call kb_types for the sections each type accepts.",
+      "",
+      "Judgment the tool cannot enforce for you:",
+      "- An unsourced claim is an `assumption` record with assumption: true, never a `fact` with a vague source. The distinction is what lets a later reader separate what was established from what was guessed.",
+      "- When two records conflict, say so in a `risk`, an `open-question`, or a superseding `decision`. Quietly picking a winner destroys the disagreement, which is usually the useful part.",
+      "- Prefer a new record over overloading an existing one, and keep each short. A record nobody finishes reading is not durable memory.",
+      "- Records are never deleted; supersede instead, so the earlier reasoning stays inspectable."
+    ].join("\n"),
+    input: import_zod6.z.object({
+      bundlePath,
+      type: import_zod6.z.enum(KB_RECORD_TYPES),
+      input: composeInputSchema
+    }),
+    fromArgv: async (argv, path, stdin) => ({
+      bundlePath: path,
+      type: argv[1],
+      input: JSON.parse(await stdin())
+    }),
+    run: async ({ store, actor, now }, { bundlePath: path, type, input }) => {
+      const record = await store.write(
+        path,
+        composeRecord(type, input, actor, now()),
+        actor
+      );
+      return { conceptId: record.conceptId };
+    }
+  }),
+  define({
+    name: "write-decision",
+    tool: "kb_write_decision",
+    usage: "write-decision < decision.json",
+    description: [
+      "Write a decision. Takes `alternative` and `impact` as fields rather than free sections, because what was rejected is the part a later reader cannot reconstruct from the code \u2014 a heading is too easy to leave empty.",
+      "",
+      "What belongs in one:",
+      '- Record a decision when a later reader would otherwise "simplify" the constraint away. If the diff already answers the question, there is nothing here to write.',
+      "- `alternative` is what you turned down and why, not a list of everything considered.",
+      "- A reference to material you read goes in `sources`; a reference to code goes in `anchors`; a reference to another record goes in `relatedConceptIds`."
+    ].join("\n"),
+    input: import_zod6.z.object({ bundlePath, input: decisionInputSchema }),
+    fromArgv: async (_argv, path, stdin) => ({
+      bundlePath: path,
+      input: JSON.parse(await stdin())
+    }),
+    run: async ({ store, actor, now }, { bundlePath: path, input }) => {
+      const record = await store.write(
+        path,
+        composeDecisionRecord(input, actor, now()),
+        actor
+      );
+      return { conceptId: record.conceptId };
+    }
+  }),
+  define({
+    name: "no-decision",
+    tool: "kb_no_decision",
+    usage: "no-decision <reason...>",
+    description: 'Claim in one sentence that there was nothing to decide. Gating on "did you write a decision?" rewards writing a junk one; gating on "did you answer?" does not, so silence has to be expressible. Idempotent \u2014 restating it is not a collision.',
+    input: import_zod6.z.object({ bundlePath, reason: import_zod6.z.string().min(1) }),
+    fromArgv: (argv, path) => ({
+      bundlePath: path,
+      reason: argv.slice(1).join(" ").trim()
+    }),
+    run: async ({ store, actor, now }, { bundlePath: path, reason }) => {
+      const record = await store.write(
+        path,
+        { ...composeNoDecisionRecord(reason, actor, now()), overwrite: true },
+        actor
+      );
+      return { conceptId: record.conceptId };
+    }
+  }),
+  define({
+    name: "status",
+    tool: "kb_status",
+    usage: "status <concept-id> <status>",
+    description: "Move a record's status, leaving everything else alone. Uses a compare-and-swap, so a concurrent change fails loudly rather than being overwritten.",
+    input: import_zod6.z.object({
+      bundlePath,
+      conceptId,
+      status: import_zod6.z.enum(KB_RECORD_STATUSES)
+    }),
+    fromArgv: (argv, path) => ({
+      bundlePath: path,
+      conceptId: argv[1],
+      status: argv[2]
+    }),
+    run: async ({ store, actor }, { bundlePath: path, conceptId: id, status }) => {
+      const record = await store.setStatus(path, id, status, actor);
+      return { conceptId: record.conceptId, status };
+    }
+  }),
+  define({
+    name: "supersede",
+    tool: "kb_supersede",
+    usage: "supersede <concept-id> <replacement-id>",
+    description: "Mark a record superseded by another, linking both directions. Use this rather than editing a record whose meaning changed \u2014 a record that quietly becomes something else invalidates every reference to it, and the earlier understanding is what a later trace needs.",
+    input: import_zod6.z.object({ bundlePath, conceptId, replacementId: conceptId }),
+    fromArgv: (argv, path) => ({
+      bundlePath: path,
+      conceptId: argv[1],
+      replacementId: argv[2]
+    }),
+    run: async ({ store, actor }, { bundlePath: path, conceptId: id, replacementId }) => {
+      await store.supersede(path, id, replacementId, actor);
+      return { superseded: id, replacedBy: replacementId };
+    }
+  }),
+  define({
+    name: "answer",
+    tool: "kb_answer",
+    usage: "answer <concept-id> <answer...>",
+    description: "Resolve an open question: sets the status, stamps who answered and when, and appends an Answer section. If the answer overturns an assumption or a decision, that is a supersession \u2014 do it explicitly.",
+    input: import_zod6.z.object({ bundlePath, conceptId, answer: import_zod6.z.string().min(1) }),
+    fromArgv: (argv, path) => ({
+      bundlePath: path,
+      conceptId: argv[1],
+      answer: argv.slice(2).join(" ").trim()
+    }),
+    run: async ({ store, actor }, { bundlePath: path, conceptId: id, answer }) => {
+      const record = await store.answer(path, id, answer, actor);
+      return { conceptId: record.conceptId };
+    }
+  }),
+  define({
+    name: "load",
+    tool: "kb_load",
+    usage: "load [type] [--budget N]",
+    description: "Load the whole knowledge base at once, each record with its standing. Prefer this over searching: these bases run to a few thousand tokens, and a reader holding all of it has perfect recall and knows why it is asking, which no ranker does. Superseded records arrive under `superseded` as name, replacement and date only \u2014 their bodies no longer hold, and reading one later in a long session is the mistake this prevents; pass the id to kb_trace when you need the history. Rejected and unresolved records arrive whole: what was turned down, and what is still open, is the part a diff cannot show you. Refuses with a count rather than truncating when the base is too large \u2014 a truncated base is indistinguishable from a complete one, and would have you conclude something was never decided from a slice you did not know was a slice.",
+    input: import_zod6.z.object({
+      bundlePath,
+      type: import_zod6.z.enum(KB_RECORD_TYPES).optional(),
+      budgetTokens: import_zod6.z.number().int().positive().optional().describe("Approximate token ceiling. Defaults to 25000.")
+    }),
+    fromArgv: (argv, path) => {
+      const at = argv.indexOf("--budget");
+      return {
+        bundlePath: path,
+        ...argv[1] && argv[1] !== "--budget" ? { type: argv[1] } : {},
+        ...at !== -1 && argv[at + 1] ? { budgetTokens: Number(argv[at + 1]) } : {}
+      };
+    },
+    run: async ({ store }, { bundlePath: path, type, budgetTokens }) => {
+      const result = await store.load(path, {
+        ...type ? { type } : {},
+        ...budgetTokens ? { budgetTokens } : {}
+      });
+      if (!result.loaded) return result;
+      return {
+        ...result,
+        records: result.records.map((hit) => ({
+          conceptId: hit.record.conceptId,
+          title: hit.record.frontmatter.title ?? null,
+          standing: hit.standing,
+          supersededBy: hit.heads.map((head) => head.conceptId),
+          warnings: hit.warnings,
+          anchors: hit.record.frontmatter.strauss_anchors ?? [],
+          body: hit.record.body
+        }))
+      };
+    }
+  }),
+  define({
+    name: "query",
+    tool: "kb_query",
+    usage: "query <text...>",
+    description: "Search and return each match with its standing. Results are flagged, never filtered: a superseded record comes back alongside whatever replaced it, and a rejected one is marked as something explicitly not adopted. Prefer this over reading record files directly \u2014 relevance and standing are different questions, and a bare match answers only the first.",
+    input: import_zod6.z.object({
+      bundlePath,
+      text: import_zod6.z.string().optional(),
+      type: import_zod6.z.enum(KB_RECORD_TYPES).optional(),
+      includeNonCurrent: import_zod6.z.boolean().optional()
+    }),
+    fromArgv: (argv, path) => ({
+      bundlePath: path,
+      text: argv.slice(1).join(" ").trim(),
+      includeNonCurrent: true
+    }),
+    run: async ({ store }, { bundlePath: path, text, type, includeNonCurrent }) => (await store.query(path, text ?? "", {
+      ...type ? { type } : {},
+      includeNonCurrent: includeNonCurrent === true
+    })).map((hit) => ({
+      conceptId: hit.record.conceptId,
+      title: hit.record.frontmatter.title ?? null,
+      description: hit.record.frontmatter.description ?? null,
+      standing: hit.standing,
+      supersededBy: hit.heads.map((head) => head.conceptId),
+      warnings: hit.warnings,
+      body: hit.record.body
+    }))
+  }),
+  define({
+    name: "trace",
+    tool: "kb_trace",
+    usage: "trace <concept-id> [edges...]",
+    description: 'How a position was arrived at, as a timeline ordered by when each record was written. Deliberately includes rejected, draft, and superseded records \u2014 in a history those are the content, not noise. Follows supersession, shared code anchors, and shared sources. Use when the question is "why is this the way it is" rather than "what do we hold now".',
+    input: import_zod6.z.object({
+      bundlePath,
+      conceptId,
+      edges: import_zod6.z.array(import_zod6.z.enum(TRACE_EDGES)).optional(),
+      depth: import_zod6.z.number().int().positive().optional()
+    }),
+    fromArgv: (argv, path) => ({
+      bundlePath: path,
+      conceptId: argv[1],
+      edges: argv.slice(2).filter((edge) => TRACE_EDGES.includes(edge))
+    }),
+    run: async ({ store }, { bundlePath: path, conceptId: id, edges, depth }) => (await store.trace(path, id, {
+      ...edges?.length ? { edges } : {},
+      ...depth ? { depth } : {}
+    })).map((step) => ({
+      conceptId: step.record.conceptId,
+      at: step.record.frontmatter.generated?.at ?? null,
+      status: step.record.frontmatter.strauss_status,
+      title: step.record.frontmatter.title ?? null,
+      depth: step.depth,
+      via: step.via,
+      body: step.record.body
+    }))
+  }),
+  define({
+    name: "list",
+    tool: "kb_list",
+    usage: "list [type]",
+    description: "Every record, optionally narrowed to one type. Use kb_query when you have a question; this is for enumerating.",
+    input: import_zod6.z.object({ bundlePath, type: import_zod6.z.enum(KB_RECORD_TYPES).optional() }),
+    fromArgv: (argv, path) => ({ bundlePath: path, type: argv[1] }),
+    run: async ({ store }, { bundlePath: path, type }) => (await store.list(path, type)).map((record) => ({
+      conceptId: record.conceptId,
+      title: record.frontmatter.title ?? null,
+      description: record.frontmatter.description ?? null,
+      status: record.frontmatter.strauss_status,
+      anchors: record.frontmatter.strauss_anchors ?? []
+    }))
+  }),
+  define({
+    name: "index",
+    tool: "kb_index",
+    usage: "index",
+    description: "The index, rebuilt if it disagrees with the records. One call gives the whole shape of the base: title, type, status, and description per record.",
+    input: import_zod6.z.object({ bundlePath }),
+    fromArgv: (_argv, path) => ({ bundlePath: path }),
+    run: ({ store }, { bundlePath: path }) => store.readIndex(path)
+  }),
+  define({
+    name: "log",
+    tool: "kb_log",
+    usage: "log",
+    description: "What touched what, and when. The only artifact here that cannot be reconstructed from the records, so malformed lines are reported rather than repaired.",
+    input: import_zod6.z.object({ bundlePath }),
+    fromArgv: (_argv, path) => ({ bundlePath: path }),
+    run: ({ store }, { bundlePath: path }) => store.readLog(path)
+  }),
+  define({
+    name: "validate",
+    tool: "kb_validate",
+    usage: "validate",
+    description: "Check pointers no single record can see: supersession links that disagree between the two records, and assumptions that cite sources. Per-record shape is enforced on every read, so a problem here means someone edited a file by hand.",
+    input: import_zod6.z.object({ bundlePath }),
+    fromArgv: (_argv, path) => ({ bundlePath: path }),
+    run: async ({ store }, { bundlePath: path }) => validateBundle(await store.list(path)),
+    failsWhen: (result) => Array.isArray(result) && result.length > 0
+  }),
+  define({
+    name: "schema",
+    tool: "kb_schema",
+    usage: "schema",
+    description: "JSON Schema for the frontmatter, the write input, and log entries \u2014 generated from the code that enforces them, so it cannot drift from what a write will accept.",
+    input: import_zod6.z.object({}),
+    fromArgv: () => ({}),
+    run: () => Promise.resolve(kbJsonSchemas())
+  }),
+  define({
+    name: "types",
+    tool: "kb_types",
+    usage: "types",
+    description: "The twelve record types with their purpose, body sections, and starting status. Read this before writing rather than guessing headings \u2014 a section the type does not define is rejected.",
+    input: import_zod6.z.object({}),
+    fromArgv: () => ({}),
+    run: () => Promise.resolve(RECORD_TYPES)
+  })
+];
+var KB_COMMANDS_BY_NAME = new Map(
+  KB_COMMANDS.map((command) => [command.name, command])
+);
+
+// src/kb-store.ts
+var import_node_crypto = require("crypto");
+var import_promises2 = require("fs/promises");
+var import_node_path2 = require("path");
+
+// src/markdown.ts
+var import_gray_matter = __toESM(require("gray-matter"), 1);
+function stringifyMarkdownWithFrontmatter(content, frontmatter) {
+  return import_gray_matter.default.stringify(content, frontmatter);
+}
+function splitMarkdownFrontmatter(text) {
+  const file = (0, import_gray_matter.default)(text);
+  return {
+    content: file.content,
+    // Everything gray-matter consumed: the fences, the YAML, and the blank line
+    // after them. Kept so a caller can rewrite a body without touching the head.
+    prefix: text.slice(0, text.length - file.content.length),
+    raw: file.data
+  };
+}
+function parseMarkdownWithFrontmatter(text, schema) {
+  const { content, prefix, raw } = splitMarkdownFrontmatter(text);
+  return {
+    content,
+    prefix,
+    raw,
+    frontmatter: schema.safeParse(raw)
+  };
+}
+
+// src/errors.ts
+var BaseError = class extends Error {
+  code;
+  errorType;
+  fault;
+  retriable;
+  reportToUser;
+  details;
+  constructor(props) {
+    super(props.message);
+    this.name = props.name ?? this.constructor.name;
+    this.code = props.code ?? 500;
+    this.errorType = props.errorType;
+    this.fault = props.fault;
+    this.retriable = props.retriable ?? true;
+    this.reportToUser = props.reportToUser ?? false;
+    this.details = props.details;
+  }
+};
+
+// src/kb-errors.ts
+var KbRecordAlreadyExistsError = class extends BaseError {
+  constructor(conceptId2) {
+    super({
+      message: `kb: ${conceptId2} already exists \u2014 choose a more specific slug, or write with overwrite`,
+      errorType: "KbRecordAlreadyExists" /* KbRecordAlreadyExists */,
+      code: 409,
+      fault: "User" /* User */,
+      retriable: false,
+      reportToUser: true,
+      details: { conceptId: conceptId2 }
+    });
+    this.conceptId = conceptId2;
+  }
+  conceptId;
+};
+var KbRecordNotFoundError = class extends BaseError {
+  constructor(conceptId2) {
+    super({
+      message: `kb: ${conceptId2} does not exist`,
+      errorType: "KbRecordNotFound" /* KbRecordNotFound */,
+      code: 404,
+      fault: "User" /* User */,
+      retriable: false,
+      reportToUser: true,
+      details: { conceptId: conceptId2 }
+    });
+    this.conceptId = conceptId2;
+  }
+  conceptId;
+};
+var KbWriteConflictError = class extends BaseError {
+  constructor(conceptId2) {
+    super({
+      message: `kb: ${conceptId2} changed while it was being updated \u2014 re-read and retry`,
+      errorType: "KbWriteConflict" /* KbWriteConflict */,
+      code: 409,
+      fault: "System" /* System */,
+      retriable: true,
+      reportToUser: true,
+      details: { conceptId: conceptId2 }
+    });
+    this.conceptId = conceptId2;
+  }
+  conceptId;
+};
+var KbInvalidConceptIdError = class extends BaseError {
+  constructor(message, details) {
+    super({
+      message: `kb: ${message}`,
+      errorType: "KbInvalidConceptId" /* KbInvalidConceptId */,
+      code: 400,
+      fault: "User" /* User */,
+      retriable: false,
+      reportToUser: true,
+      details
+    });
+  }
+};
+
+// src/kb-index.ts
+var INDEX_FILE = "INDEX.md";
+var HEADING = "# KB Index";
+function renderIndex(records) {
+  const lines = [...records].sort((left, right) => left.conceptId.localeCompare(right.conceptId)).map((record) => {
+    const { frontmatter: fm } = record;
+    const parts = [fm.type, fm.strauss_status];
+    if (fm.tags?.length) parts.push(`tags: ${fm.tags.join(", ")}`);
+    if (fm.description) parts.push(fm.description);
+    return `- [${fm.title ?? record.conceptId}](${record.conceptId}.md) \u2014 ${parts.join(" \xB7 ")}`;
+  });
+  return `${HEADING}
+
+${lines.join("\n")}
+`;
+}
+function indexIsStale(stored, expected) {
+  return stored !== expected;
+}
+
+// src/adjudicate.ts
+var STANDING = {
+  accepted: "current",
+  resolved: "current",
+  draft: "unsettled",
+  proposed: "unsettled",
+  open: "open",
+  rejected: "rejected",
+  superseded: "superseded"
+};
+function adjudicate(hits, bundle, now = /* @__PURE__ */ new Date()) {
+  const byId = new Map(bundle.map((record) => [record.conceptId, record]));
+  return hits.map((record) => {
+    const status = record.frontmatter.strauss_status;
+    const warnings = [];
+    let heads = [];
+    if (status === "superseded") {
+      const resolved = resolveHeads(record, byId);
+      heads = resolved.heads;
+      warnings.push(...resolved.warnings);
+      if (heads.length) {
+        warnings.push({
+          kind: "superseded",
+          by: heads.map((head) => head.conceptId)
+        });
+      }
+    } else if (status === "rejected") {
+      warnings.push({ kind: "rejected" });
+    } else if (status === "draft" || status === "proposed") {
+      warnings.push({ kind: "unsettled", status });
+    } else if (status === "open") {
+      warnings.push({ kind: "unresolved-question" });
+    }
+    const staleAfter = record.frontmatter.stale_after;
+    if (staleAfter && Date.parse(staleAfter) < now.getTime()) {
+      warnings.push({ kind: "stale", staleAfter });
+    }
+    if (!record.frontmatter.verified?.length) {
+      warnings.push({ kind: "unverified" });
+    }
+    return { record, standing: STANDING[status], heads, warnings };
+  });
+}
+function resolveHeads(from, byId) {
+  const warnings = [];
+  const heads = /* @__PURE__ */ new Map();
+  const seen = /* @__PURE__ */ new Set([from.conceptId]);
+  const queue = [from];
+  while (queue.length) {
+    const current = queue.shift();
+    const next = successors(current, byId);
+    for (const missing of next.missing) {
+      warnings.push({ kind: "broken-chain", missing });
+    }
+    if (!next.records.length) {
+      if (current.conceptId !== from.conceptId)
+        heads.set(current.conceptId, current);
+      continue;
+    }
+    for (const record of next.records) {
+      if (seen.has(record.conceptId)) {
+        warnings.push({ kind: "chain-cycle", through: [...seen] });
+        continue;
+      }
+      seen.add(record.conceptId);
+      queue.push(record);
+    }
+  }
+  if (heads.size > 1) {
+    warnings.push({ kind: "forked-chain", heads: [...heads.keys()] });
+  }
+  return { heads: [...heads.values()], warnings };
+}
+function successors(record, byId) {
+  const ids = /* @__PURE__ */ new Set();
+  const forward = record.frontmatter.strauss_superseded_by;
+  if (forward) ids.add(forward);
+  for (const [id, candidate] of byId) {
+    if (candidate.frontmatter.strauss_supersedes?.includes(record.conceptId)) {
+      ids.add(id);
+    }
+  }
+  const records = [];
+  const missing = [];
+  for (const id of ids) {
+    const found = byId.get(id);
+    if (found) records.push(found);
+    else missing.push(id);
+  }
+  return { records, missing };
+}
+
+// src/search-index.ts
+var import_promises = require("fs/promises");
+var import_node_path = require("path");
+var SEARCH_INDEX_FILE = ".index.sqlite";
+var COLLECTION = "kb";
+async function searchBase(bundlePath2, query, options = {}) {
+  const qmd = options.qmd ?? await loadQmd(options.logger);
+  if (!qmd) return null;
+  let store = null;
+  try {
+    store = await qmd.createStore({
+      dbPath: (0, import_node_path.join)(bundlePath2, SEARCH_INDEX_FILE),
+      config: {
+        collections: {
+          [COLLECTION]: {
+            path: bundlePath2,
+            pattern: "**/*.md",
+            // Both store-owned files are markdown and neither is a record.
+            ignore: [INDEX_FILE, LOG_FILE]
+          }
+        }
+      }
+    });
+    if (await isStale(bundlePath2)) {
+      await store.update({ collections: [COLLECTION] });
+    }
+    const hits = await store.searchLex(query, {
+      collection: COLLECTION,
+      ...options.limit ? { limit: options.limit } : {}
+    });
+    return hits.map((hit) => ({
+      displayPath: hit.displayPath ?? hit.filepath ?? "",
+      score: hit.score ?? 0
+    })).filter((hit) => hit.displayPath.length > 0);
+  } catch (error) {
+    options.logger?.warn?.({
+      operation: "kb.search",
+      outcome: "unavailable",
+      error: error instanceof Error ? error.message : "unknown"
+    });
+    return null;
+  } finally {
+    await store?.close().catch(() => void 0);
+  }
+}
+async function isStale(bundlePath2) {
+  const indexAt = await (0, import_promises.stat)((0, import_node_path.join)(bundlePath2, SEARCH_INDEX_FILE)).then((s) => s.mtimeMs).catch(() => 0);
+  if (!indexAt) return true;
+  const { readdir: readdir2 } = await import("fs/promises");
+  const names = await readdir2(bundlePath2).catch(() => []);
+  for (const name of names) {
+    if (!name.endsWith(".md") || name === INDEX_FILE) continue;
+    const at = await (0, import_promises.stat)((0, import_node_path.join)(bundlePath2, name)).then((s) => s.mtimeMs).catch(() => 0);
+    if (at > indexAt) return true;
+  }
+  return false;
+}
+function resolveHits(hits, records) {
+  const byName = /* @__PURE__ */ new Map();
+  for (const record of records) {
+    const name = flatten(record.conceptId);
+    if (byName.has(name)) byName.delete(name);
+    else byName.set(name, record);
+  }
+  const resolved = [];
+  for (const hit of hits) {
+    const file = hit.displayPath.split("/").pop() ?? "";
+    const name = file.endsWith(".md") ? file.slice(0, -".md".length) : file;
+    const record = byName.get(flatten(name));
+    if (record) resolved.push(record);
+  }
+  return resolved;
+}
+function flatten(value) {
+  return value.replace(/[.]/g, "-").toLowerCase();
+}
+var QMD_MODULE = "@tobilu/qmd";
+async function loadQmd(logger) {
+  try {
+    return await import(QMD_MODULE);
+  } catch {
+    logger?.warn?.({ operation: "kb.search", outcome: "qmd-unavailable" });
+    return null;
+  }
+}
+
+// src/kb-store.ts
+var KB_DIR = (0, import_node_path2.join)(".strauss", "kb");
+var STORE_OWNED = /* @__PURE__ */ new Set([INDEX_FILE, LOG_FILE, SEARCH_INDEX_FILE]);
+var DEFAULT_LOAD_BUDGET = 25e3;
+var KbStore = class {
+  constructor(logger = {}) {
+    this.logger = logger;
+  }
+  logger;
+  /**
+   * 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.
+   */
+  async write(bundlePath2, input, actor = "unknown") {
+    if (!KB_SLUG_PATTERN.test(input.slug)) {
+      throw new KbInvalidConceptIdError("slug must be kebab-case", {
+        slug: input.slug
+      });
+    }
+    if (!KB_SLUG_PATTERN.test(input.type)) {
+      throw new KbInvalidConceptIdError("type must be kebab-case", {
+        type: input.type
+      });
+    }
+    const frontmatter = kbRecordFrontmatterSchema.parse({
+      ...input.frontmatter,
+      type: input.type
+    });
+    const conceptId2 = `${input.type}.${input.slug}`;
+    const root = this.root(bundlePath2);
+    const target = this.recordPath(bundlePath2, conceptId2);
+    await (0, import_promises2.mkdir)(root, { recursive: true });
+    await this.publish(
+      target,
+      stringifyMarkdownWithFrontmatter(input.body, frontmatter),
+      input.overwrite ?? false,
+      conceptId2
+    );
+    await this.record(root, {
+      operation: input.overwrite ? "overwrite" : "write",
+      conceptId: conceptId2,
+      by: actor
+    });
+    this.logger.info?.({
+      operation: "kb.write",
+      bundlePath: root,
+      conceptId: conceptId2,
+      anchors: frontmatter.strauss_anchors?.length ?? 0
+    });
+    return { conceptId: conceptId2, frontmatter, body: input.body };
+  }
+  /** One record by concept id, or null when it does not exist. */
+  async read(bundlePath2, conceptId2) {
+    const target = this.recordPath(bundlePath2, conceptId2);
+    let raw;
+    try {
+      raw = await (0, import_promises2.readFile)(target, "utf8");
+    } catch {
+      return null;
+    }
+    return this.parse(conceptId2, raw);
+  }
+  /**
+   * 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.
+   */
+  async list(bundlePath2, type) {
+    const root = this.root(bundlePath2);
+    let names;
+    try {
+      names = await (0, import_promises2.readdir)(root);
+    } catch {
+      return [];
+    }
+    const wanted = names.sort().filter((name) => name.endsWith(".md") && !STORE_OWNED.has(name)).map((name) => ({ name, conceptId: name.slice(0, -".md".length) })).filter(({ conceptId: conceptId2 }) => !type || conceptId2.startsWith(`${type}.`));
+    const records = await Promise.all(
+      wanted.map(
+        async ({ name, conceptId: conceptId2 }) => this.parse(conceptId2, await (0, import_promises2.readFile)((0, import_node_path2.join)(root, name), "utf8"))
+      )
+    );
+    return records.filter((record) => record !== null);
+  }
+  /**
+   * 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.
+   */
+  async setStatus(bundlePath2, conceptId2, status, actor = "unknown") {
+    return this.mutate(
+      bundlePath2,
+      conceptId2,
+      (frontmatter) => ({ ...frontmatter, strauss_status: status }),
+      { operation: `status:${status}`, by: actor }
+    );
+  }
+  /**
+   * 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.
+   */
+  async supersede(bundlePath2, conceptId2, replacementId, actor = "unknown") {
+    const replacement = await this.read(bundlePath2, replacementId);
+    if (!replacement) throw new KbRecordNotFoundError(replacementId);
+    const superseded = await this.mutate(
+      bundlePath2,
+      conceptId2,
+      (frontmatter) => ({
+        ...frontmatter,
+        strauss_status: "superseded",
+        strauss_superseded_by: replacementId
+      }),
+      { operation: "supersede", by: actor, target: replacementId }
+    );
+    await this.mutate(
+      bundlePath2,
+      replacementId,
+      (frontmatter) => ({
+        ...frontmatter,
+        strauss_supersedes: [
+          .../* @__PURE__ */ new Set([...frontmatter.strauss_supersedes ?? [], conceptId2])
+        ]
+      }),
+      { operation: "supersedes", by: actor, target: conceptId2 }
+    );
+    return superseded;
+  }
+  /** Resolves an open question, stamping who answered and when. */
+  async answer(bundlePath2, conceptId2, answer, actor = "unknown", at = (/* @__PURE__ */ new Date()).toISOString()) {
+    return this.mutate(
+      bundlePath2,
+      conceptId2,
+      (frontmatter) => ({
+        ...frontmatter,
+        strauss_status: "resolved",
+        strauss_answered: { by: actor, at }
+      }),
+      { operation: "answer", by: actor },
+      (body) => `${body.trimEnd()}
+
+## Answer
+
+${answer}
+`
+    );
+  }
+  /**
+   * 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.
+   */
+  async query(bundlePath2, text, options = {}) {
+    const bundle = await this.list(bundlePath2);
+    const needle = text.trim();
+    const hits = needle ? await this.rank(bundlePath2, needle, bundle) : bundle;
+    const adjudicated = adjudicate(
+      options.type ? hits.filter((r) => r.frontmatter.type === options.type) : hits,
+      bundle
+    );
+    if (options.includeNonCurrent) return adjudicated;
+    const present = new Set(adjudicated.map((hit) => hit.record.conceptId));
+    return adjudicated.filter(
+      (hit) => hit.standing !== "superseded" || !hit.heads.some((head) => present.has(head.conceptId))
+    );
+  }
+  async rank(bundlePath2, needle, bundle) {
+    const ranked = await searchBase(this.root(bundlePath2), needle, {
+      logger: this.logger
+    });
+    if (ranked) {
+      const found = resolveHits(ranked, bundle);
+      if (found.length) return found;
+    }
+    const lowered = needle.toLowerCase();
+    return bundle.filter((record) => matches(record, lowered));
+  }
+  /**
+   * 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.
+   */
+  async load(bundlePath2, options = {}) {
+    const budgetTokens = options.budgetTokens ?? DEFAULT_LOAD_BUDGET;
+    const bundle = await this.list(bundlePath2);
+    const wanted = options.type ? bundle.filter((record) => record.frontmatter.type === options.type) : bundle;
+    const adjudicated = adjudicate(wanted, bundle);
+    const records = adjudicated.filter((hit) => hit.standing !== "superseded");
+    const superseded = adjudicated.filter((hit) => hit.standing === "superseded").map(stub);
+    const approxTokens = records.reduce((total, hit) => total + estimateTokens(hit.record), 0) + superseded.reduce((total, entry) => total + estimateStubTokens(entry), 0);
+    if (approxTokens > budgetTokens) {
+      return {
+        loaded: false,
+        recordCount: wanted.length,
+        approxTokens,
+        budgetTokens
+      };
+    }
+    return {
+      loaded: true,
+      recordCount: wanted.length,
+      approxTokens,
+      budgetTokens,
+      records,
+      superseded
+    };
+  }
+  /** How a position was arrived at, as a timeline. See `trace.ts`. */
+  async trace(bundlePath2, seedId, options = {}) {
+    return trace(seedId, await this.list(bundlePath2), options);
+  }
+  /**
+   * 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.
+   */
+  async readIndex(bundlePath2) {
+    const root = this.root(bundlePath2);
+    const expected = renderIndex(await this.list(bundlePath2));
+    const stored = await (0, import_promises2.readFile)((0, import_node_path2.join)(root, INDEX_FILE), "utf8").catch(
+      () => null
+    );
+    if (indexIsStale(stored, expected)) {
+      await this.publish((0, import_node_path2.join)(root, INDEX_FILE), expected, true, INDEX_FILE);
+      this.logger.info?.({
+        operation: "kb.index.repair",
+        bundlePath: root,
+        reason: stored === null ? "missing" : "stale"
+      });
+    }
+    return expected;
+  }
+  /**
+   * 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.
+   */
+  async readLog(bundlePath2) {
+    const raw = await (0, import_promises2.readFile)(
+      (0, import_node_path2.join)(this.root(bundlePath2), LOG_FILE),
+      "utf8"
+    ).catch(() => "");
+    const result = parseLog(raw);
+    for (const bad of result.malformed) {
+      this.logger.warn?.({
+        operation: "kb.log.parse",
+        line: bad.line,
+        outcome: "skipped"
+      });
+    }
+    return result;
+  }
+  async mutate(bundlePath2, conceptId2, change, entry, changeBody = (body) => body) {
+    const target = this.recordPath(bundlePath2, conceptId2);
+    const before = await (0, import_promises2.readFile)(target, "utf8").catch(() => null);
+    if (before === null) throw new KbRecordNotFoundError(conceptId2);
+    const parsed = this.parse(conceptId2, before);
+    if (!parsed) throw new KbRecordNotFoundError(conceptId2);
+    const frontmatter = change(parsed.frontmatter);
+    const body = changeBody(parsed.body);
+    const contents = stringifyMarkdownWithFrontmatter(body, frontmatter);
+    const witness = await (0, import_promises2.readFile)(target, "utf8").catch(() => null);
+    if (witness === null || digest(witness) !== digest(before)) {
+      throw new KbWriteConflictError(conceptId2);
+    }
+    await this.publish(target, contents, true, conceptId2);
+    await this.record(this.root(bundlePath2), { ...entry, conceptId: conceptId2 });
+    return { conceptId: conceptId2, frontmatter, body };
+  }
+  /**
+   * 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.
+   */
+  async publish(target, contents, overwrite, conceptId2) {
+    const staging = `${target}.${process.pid}.tmp`;
+    await (0, import_promises2.writeFile)(staging, contents, "utf8");
+    try {
+      if (overwrite) {
+        await (0, import_promises2.rename)(staging, target);
+        return;
+      }
+      await (0, import_promises2.link)(staging, target);
+    } catch (error) {
+      if (error.code === "EEXIST") {
+        throw new KbRecordAlreadyExistsError(conceptId2);
+      }
+      throw error;
+    } finally {
+      await (0, import_promises2.unlink)(staging).catch(() => void 0);
+    }
+  }
+  /** Appends one log line. Failing to log must not fail the mutation. */
+  async record(root, entry) {
+    const line = renderLogEntry({ at: (/* @__PURE__ */ new Date()).toISOString(), ...entry });
+    await (0, import_promises2.appendFile)((0, import_node_path2.join)(root, LOG_FILE), line, "utf8").catch((error) => {
+      this.logger.warn?.({
+        operation: "kb.log.append",
+        outcome: "failed",
+        error: error instanceof Error ? error.message : "unknown"
+      });
+    });
+  }
+  parse(conceptId2, raw) {
+    const parsed = parseMarkdownWithFrontmatter(raw, kbRecordFrontmatterSchema);
+    if (!parsed.frontmatter.success) {
+      this.logger.warn?.({
+        operation: "kb.parse",
+        conceptId: conceptId2,
+        outcome: "skipped",
+        error: parsed.frontmatter.error.issues[0]?.message ?? "invalid"
+      });
+      return null;
+    }
+    return {
+      conceptId: conceptId2,
+      frontmatter: parsed.frontmatter.data,
+      body: parsed.content
+    };
+  }
+  root(bundlePath2) {
+    return (0, import_node_path2.resolve)(bundlePath2);
+  }
+  // Concept ids are `<type>.<slug>` and map to a single file directly under the
+  // bundle root; anything carrying a separator would escape it.
+  recordPath(bundlePath2, conceptId2) {
+    if (conceptId2.includes(import_node_path2.sep) || conceptId2.includes("/")) {
+      throw new KbInvalidConceptIdError(
+        "concept id must not contain a path separator",
+        { conceptId: conceptId2 }
+      );
+    }
+    return (0, import_node_path2.join)(this.root(bundlePath2), `${conceptId2}.md`);
+  }
+};
+function estimateTokens(record) {
+  return Math.ceil(
+    (record.body.length + JSON.stringify(record.frontmatter).length) / 4
+  );
+}
+function estimateStubTokens(entry) {
+  return Math.ceil(JSON.stringify(entry).length / 4);
+}
+function stub(hit) {
+  return {
+    conceptId: hit.record.conceptId,
+    title: hit.record.frontmatter.title ?? null,
+    supersededBy: hit.heads.map((head) => head.conceptId),
+    at: hit.record.frontmatter.generated?.at ?? null
+  };
+}
+function matches(record, needle) {
+  const { title, description } = record.frontmatter;
+  return [record.conceptId, title, description, record.body].some(
+    (field) => field?.toLowerCase().includes(needle)
+  );
+}
+function digest(contents) {
+  return (0, import_node_crypto.createHash)("sha256").update(contents).digest("hex");
+}
+
+// src/mcp.ts
+function createKbMcpServer() {
+  const server = new import_mcp.McpServer({ name: "strauss-kb", version: "0.1.0" });
+  const store = new KbStore({
+    warn: (entry) => process.stderr.write(`${JSON.stringify(entry)}
+`)
+  });
+  const ctx = {
+    store,
+    actor: process.env.STRAUSS_KB_ACTOR ?? "mcp",
+    now: () => (/* @__PURE__ */ new Date()).toISOString()
+  };
+  for (const command of KB_COMMANDS) {
+    server.registerTool(
+      command.tool,
+      { description: command.description, inputSchema: command.input.shape },
+      async (args) => {
+        const result = await command.run(ctx, command.input.parse(args));
+        return {
+          content: [
+            {
+              type: "text",
+              text: typeof result === "string" ? result : JSON.stringify(result, null, 2)
+            }
+          ]
+        };
+      }
+    );
+  }
+  return server;
+}
+async function runKbMcpServer() {
+  await createKbMcpServer().connect(new import_stdio.StdioServerTransport());
+}
+
+// src/mcp-main.ts
+runKbMcpServer().catch((error) => {
+  process.stderr.write(
+    `${error instanceof Error ? error.message : String(error)}
+`
+  );
+  process.exit(1);
+});
+//# sourceMappingURL=mcp-main.cjs.map