@saasontools/strauss-kb 0.1.2 → 0.1.4

package/dist/chunk-EDH43Z7J.js

@@ -0,0 +1,2377 @@
+// src/kb-record.schema.ts
+import { z } from "zod";
+var kbSourceSchema = z.object({
+  id: z.string().min(1),
+  resource: z.string().min(1),
+  title: z.string().min(1).optional(),
+  author: z.string().min(1).optional(),
+  last_modified: z.string().min(1).optional()
+}).passthrough();
+var kbActorStampSchema = z.object({
+  by: z.string().min(1),
+  at: z.string().min(1)
+}).passthrough();
+var kbAnchorSchema = z.object({
+  file: z.string().min(1),
+  symbol: 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 = 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 = z.object({
+  // OKF: the only always-required key. A concept carrying just `type` is
+  // fully conformant, so everything below stays optional.
+  type: z.string().min(1),
+  // OKF recommended.
+  title: z.string().min(1).optional(),
+  description: z.string().min(1).optional(),
+  resource: z.string().min(1).optional(),
+  tags: z.array(z.string()).optional(),
+  // OKF optional: provenance and freshness.
+  sources: z.array(kbSourceSchema).optional(),
+  generated: kbActorStampSchema.optional(),
+  verified: z.array(kbActorStampSchema).optional(),
+  stale_after: z.string().min(1).optional(),
+  // strauss extensions — see the module comment.
+  strauss_anchors: z.array(kbAnchorSchema).optional(),
+  strauss_verify: z.array(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: z.enum(KB_RECORD_STATUSES).default("draft"),
+  strauss_supersedes: z.array(z.string().min(1)).optional(),
+  strauss_superseded_by: z.string().min(1).optional(),
+  strauss_answered: kbActorStampSchema.optional(),
+  strauss_materiality: z.enum(KB_MATERIALITIES).optional(),
+  strauss_confidence: z.enum(KB_CONFIDENCES).optional(),
+  strauss_owner: 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: 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
+import { z as z2 } from "zod";
+var composeInputSchema = z2.object({
+  slug: z2.string().min(1),
+  /** One line, in the reader's terms. Becomes OKF `title`. */
+  title: z2.string().min(1),
+  /** The consequence — what breaks if this is wrong. Becomes `description`. */
+  why: z2.string().min(1),
+  /** Keyed by section heading from the type's spec. Unknown keys rejected. */
+  sections: z2.record(z2.string(), z2.string().min(1)).optional(),
+  anchors: z2.array(kbAnchorSchema).optional(),
+  sources: z2.array(kbSourceSchema).optional(),
+  /** No source exists, as a claim rather than a sentinel in `sources`. */
+  assumption: z2.boolean().optional(),
+  /**
+   * OKF `stale_after`: the absolute date this record stops being trusted.
+   * Anything the outside world can change — pricing, quotas, versions,
+   * reception counts — should carry one.
+   */
+  stale_after: z2.string().regex(/^\d{4}-\d{2}-\d{2}$/, {
+    message: "stale_after must be YYYY-MM-DD"
+  }).refine((date) => !Number.isNaN(Date.parse(date)), {
+    message: "stale_after must be a real date"
+  }).optional(),
+  verify: z2.array(z2.string().min(1)).optional(),
+  tags: z2.array(z2.string().min(1)).optional(),
+  /** Concept ids this record relates to; rendered as body links. */
+  relatedConceptIds: z2.array(kbConceptIdSchema).optional(),
+  /** Concept ids this record replaces. The store settles the backlinks. */
+  supersedes: z2.array(kbConceptIdSchema).max(32).optional(),
+  materiality: z2.enum(KB_MATERIALITIES).optional(),
+  confidence: z2.enum(KB_CONFIDENCES).optional(),
+  owner: z2.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.stale_after) frontmatter.stale_after = parsed.stale_after;
+  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
+import { z as z3 } from "zod";
+var DECISION_TYPE = "decision";
+var NO_DECISION_SLUG = "none";
+var decisionInputSchema = composeInputSchema.omit({ sections: true }).extend({
+  alternative: z3.string().min(1).optional(),
+  impact: z3.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
+  );
+}
+function isNoDecisionRecord(record) {
+  return record.conceptId === `${DECISION_TYPE}.${NO_DECISION_SLUG}`;
+}
+function selectDecisions(records) {
+  return records.filter(
+    (record) => record.conceptId.startsWith(`${DECISION_TYPE}.`) && !isNoDecisionRecord(record)
+  );
+}
+
+// src/kb-pins/budgets.ts
+function asBudgets(value) {
+  if (value === null || typeof value !== "object") return {};
+  const table = value;
+  const pick = (key, min) => {
+    const raw = table[key];
+    return typeof raw === "number" && Number.isInteger(raw) && raw >= min ? raw : void 0;
+  };
+  const budgetTokens = pick("budgetTokens", 1);
+  const fullUnderTokens = pick("fullUnderTokens", 0);
+  return {
+    ...budgetTokens ? { budgetTokens } : {},
+    ...fullUnderTokens !== void 0 ? { fullUnderTokens } : {}
+  };
+}
+function contextProfileBudgets(manifest, profile) {
+  const table = manifest.context;
+  if (table === null || typeof table !== "object") return {};
+  const entries = table;
+  return {
+    ...asBudgets(entries["default"]),
+    ...profile ? asBudgets(entries[profile]) : {}
+  };
+}
+function mergedContextBudgets(merged, profile) {
+  const layered = ["user", "local", "project"].map((layer) => {
+    const manifest = merged.manifests[layer];
+    return manifest ? contextProfileBudgets(manifest, profile) : {};
+  });
+  return { ...layered[0], ...layered[1], ...layered[2] };
+}
+
+// src/kb-pins/errors.ts
+var KbPinsMalformedError = class extends Error {
+  constructor(file, cause) {
+    super(`pin manifest ${file} is not readable (${cause}) \u2014 fix or remove it`);
+    this.name = "KbPinsMalformedError";
+  }
+};
+var KbBaseFrozenError = class extends Error {
+  constructor(bundlePath2, layer) {
+    super(
+      `${bundlePath2} is frozen (read-only) by this workspace's ${layer} pin manifest \u2014 re-pin with --unfreeze, or unpin, to change it`
+    );
+    this.name = "KbBaseFrozenError";
+  }
+};
+
+// src/kb-pins/model.ts
+import { join } from "path";
+import { z as z4 } from "zod";
+var PINS_FILE = join(".strauss", "kb-pins.json");
+var PINS_LOCAL_FILE = join(".strauss", "kb-pins.local.json");
+var PIN_LAYERS = ["project", "local", "user"];
+var pinSchema = z4.object({
+  /** Relative to the manifest's root, so the file is committable. */
+  path: z4.string().min(1),
+  pinnedAt: z4.string().min(1).optional(),
+  /**
+   * How `context` renders this base. `full` preloads the whole base into
+   * the block regardless of the full-under threshold — for a base whose
+   * contents should simply be present, the way an ADR base should be —
+   * still answering to the block budget, with an index fallback that says
+   * so when it cannot fit. `index` never upgrades, whatever the threshold.
+   * Absent: the profile's full-under threshold decides. Invalid values
+   * degrade to absent rather than failing the manifest.
+   */
+  mode: z4.enum(["full", "index"]).optional().catch(void 0),
+  /**
+   * Context profiles this pin surfaces in (e.g. only at session-start,
+   * not per turn). Absent: every profile. A run without a profile sees
+   * every pin. A base that only matters to one skill is better loaded by
+   * that skill at point of use than pinned at all — pins are what every
+   * session should see.
+   */
+  profiles: z4.array(z4.string()).optional().catch(void 0),
+  /**
+   * The base is concluded — a finished piece of research, a frozen ADR
+   * set. Write commands against it refuse while this workspace holds the
+   * pin, and `context` labels it read-only. Workspace policy, not base
+   * state: the base itself stays copyable and writable elsewhere.
+   */
+  frozen: z4.boolean().optional().catch(void 0)
+}).passthrough();
+var pinsManifestSchema = z4.object({
+  pins: z4.array(pinSchema).default([]),
+  /**
+   * Per-repo budgets for the `context` command, keyed by profile —
+   * `"session-start"`, `"compact"`, `"turn"`, or `"default"` for all of
+   * them. Deliberately untyped here: a typo'd budget must degrade to the
+   * built-in default, not make the whole manifest unreadable and silence
+   * the index at every session start. `contextProfileBudgets` does the
+   * tolerant read.
+   */
+  context: z4.unknown().optional()
+}).passthrough();
+
+// src/kb-pins/layers.ts
+import { mkdir, readFile, writeFile } from "fs/promises";
+import { homedir } from "os";
+import { dirname, isAbsolute, join as join2, relative, resolve, sep } from "path";
+function userRoot() {
+  return process.env.STRAUSS_KB_USER_ROOT || homedir();
+}
+function layerRoot(workspaceDir, layer) {
+  return layer === "user" ? userRoot() : resolve(workspaceDir);
+}
+function layerFile(workspaceDir, layer) {
+  return join2(
+    layerRoot(workspaceDir, layer),
+    layer === "local" ? PINS_LOCAL_FILE : PINS_FILE
+  );
+}
+async function readPinsLayer(workspaceDir, layer) {
+  const file = layerFile(workspaceDir, layer);
+  let raw;
+  try {
+    raw = await readFile(file, "utf8");
+  } catch {
+    return { pins: [] };
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch (error) {
+    throw new KbPinsMalformedError(
+      file,
+      error instanceof Error ? error.message : "invalid JSON"
+    );
+  }
+  const manifest = pinsManifestSchema.safeParse(parsed);
+  if (!manifest.success) {
+    throw new KbPinsMalformedError(
+      file,
+      manifest.error.issues[0]?.message ?? "invalid shape"
+    );
+  }
+  return manifest.data;
+}
+async function writePinsLayer(workspaceDir, layer, manifest) {
+  const file = layerFile(workspaceDir, layer);
+  await mkdir(dirname(file), { recursive: true });
+  await writeFile(file, `${JSON.stringify(manifest, null, 2)}
+`, "utf8");
+}
+function resolvePinPath(rootDir, path) {
+  return isAbsolute(path) ? resolve(path) : resolve(rootDir, path.split("/").join(sep));
+}
+function storablePath(rootDir, bundlePath2) {
+  const rel = relative(resolve(rootDir), resolve(bundlePath2));
+  return (rel === "" ? "." : rel).split(sep).join("/");
+}
+async function readMergedPins(workspaceDir) {
+  const manifests = {};
+  const pins = [];
+  const seen = /* @__PURE__ */ new Set();
+  for (const layer of PIN_LAYERS) {
+    let manifest;
+    try {
+      manifest = await readPinsLayer(workspaceDir, layer);
+    } catch {
+      continue;
+    }
+    manifests[layer] = manifest;
+    const root = layerRoot(workspaceDir, layer);
+    for (const entry of manifest.pins) {
+      const absolutePath = resolvePinPath(root, entry.path);
+      if (seen.has(absolutePath)) continue;
+      seen.add(absolutePath);
+      pins.push({ ...entry, layer, absolutePath });
+    }
+  }
+  return { pins, manifests };
+}
+
+// src/kb-pins/frozen.ts
+import { resolve as resolve2 } from "path";
+async function assertBaseNotFrozen(workspaceDir, bundlePath2) {
+  const merged = await readMergedPins(workspaceDir);
+  const absolute = resolve2(bundlePath2);
+  const pin = merged.pins.find((entry) => entry.absolutePath === absolute);
+  if (pin?.frozen === true) {
+    throw new KbBaseFrozenError(pin.path, pin.layer);
+  }
+}
+
+// src/kb-pins/list.ts
+async function listPins(store, workspaceDir) {
+  const merged = await readMergedPins(workspaceDir);
+  return Promise.all(
+    merged.pins.map(async (entry) => {
+      const records = await store.list(entry.absolutePath);
+      return {
+        path: entry.path,
+        layer: entry.layer,
+        pinnedAt: entry.pinnedAt ?? null,
+        absolutePath: entry.absolutePath,
+        valid: records.length > 0,
+        recordCount: records.length,
+        mode: entry.mode ?? null,
+        profiles: entry.profiles ?? null,
+        frozen: entry.frozen === true
+      };
+    })
+  );
+}
+
+// src/kb-pins/pin.ts
+async function pinBase(store, workspaceDir, bundlePath2, at, options = {}) {
+  const layer = options.layer ?? "project";
+  const root = layerRoot(workspaceDir, layer);
+  const manifest = await readPinsLayer(workspaceDir, layer);
+  const absolute = resolvePinPath(root, storablePath(root, bundlePath2));
+  const existing = manifest.pins.find(
+    (entry2) => resolvePinPath(root, entry2.path) === absolute
+  );
+  const records = await store.list(absolute);
+  const warning = records.length === 0 ? `no records found at ${absolute} \u2014 pinned anyway; bases are routinely pinned before they are populated` : void 0;
+  const fields = {
+    ...options.mode ? { mode: options.mode } : {},
+    ...options.profiles?.length ? { profiles: options.profiles } : {},
+    ...options.frozen !== void 0 ? { frozen: options.frozen } : {}
+  };
+  if (existing) {
+    const updated = { ...existing, ...fields };
+    if (Object.keys(fields).length) {
+      await writePinsLayer(workspaceDir, layer, {
+        ...manifest,
+        pins: manifest.pins.map(
+          (entry2) => entry2 === existing ? updated : entry2
+        )
+      });
+    }
+    return {
+      path: existing.path,
+      layer,
+      pinnedAt: existing.pinnedAt ?? at,
+      alreadyPinned: true,
+      ...updated.mode ? { mode: updated.mode } : {},
+      ...updated.profiles ? { profiles: updated.profiles } : {},
+      ...updated.frozen !== void 0 ? { frozen: updated.frozen } : {},
+      ...warning ? { warning } : {}
+    };
+  }
+  const entry = {
+    path: storablePath(root, bundlePath2),
+    pinnedAt: at,
+    ...fields
+  };
+  await writePinsLayer(workspaceDir, layer, {
+    ...manifest,
+    pins: [...manifest.pins, entry]
+  });
+  return {
+    path: entry.path,
+    layer,
+    pinnedAt: at,
+    alreadyPinned: false,
+    ...fields,
+    ...warning ? { warning } : {}
+  };
+}
+
+// src/kb-pins/unpin.ts
+import { resolve as resolve3 } from "path";
+async function unpinBase(workspaceDir, bundlePath2) {
+  const layers = [];
+  for (const layer of PIN_LAYERS) {
+    const root = layerRoot(workspaceDir, layer);
+    let manifest;
+    try {
+      manifest = await readPinsLayer(workspaceDir, layer);
+    } catch {
+      continue;
+    }
+    const absolute = resolvePinPath(root, storablePath(root, bundlePath2));
+    const kept = manifest.pins.filter(
+      (entry) => resolvePinPath(root, entry.path) !== absolute
+    );
+    if (kept.length !== manifest.pins.length) {
+      await writePinsLayer(workspaceDir, layer, { ...manifest, pins: kept });
+      layers.push(layer);
+    }
+  }
+  return {
+    path: storablePath(resolve3(workspaceDir), bundlePath2),
+    removed: layers.length > 0,
+    layers
+  };
+}
+
+// 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/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(renderIndexLine);
+  return `${HEADING}
+
+${lines.join("\n")}
+`;
+}
+function renderIndexLine(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 ")}`;
+}
+function indexIsStale(stored, expected) {
+  return stored !== expected;
+}
+
+// src/kb-context.ts
+import { readFile as readFile2, writeFile as writeFile2 } from "fs/promises";
+var HEADING2 = "## Knowledge bases (pinned)";
+var DEFAULT_CONTEXT_BUDGET = 4e3;
+var CONTEXT_PROFILES = {
+  "session-start": { fullUnderTokens: 1500 },
+  compact: { budgetTokens: 2500 },
+  turn: { budgetTokens: 2500 }
+};
+function approxTokens(text) {
+  return Math.ceil(text.length / 4);
+}
+function preamble() {
+  return [
+    HEADING2,
+    "",
+    "What follows is an index of this workspace's pinned knowledge bases \u2014",
+    "concept ids, titles and standing only. The record bodies are NOT in this",
+    "context.",
+    "",
+    "Consult records only through the strauss-kb MCP tools: `kb_load` (the",
+    "preferred first call), `kb_query`, and `kb_trace`, passing the",
+    "`bundlePath` listed with each base. Do not read record files directly:",
+    "a raw file read bypasses supersession resolution, and a superseded or",
+    "rejected record file reads exactly like a current one \u2014 only the store",
+    "resolves chains and standing.",
+    "",
+    "KB content loaded earlier in a long session may have been compacted",
+    "away. Before answering a question one of these bases governs, load it",
+    "again at the point of use \u2014 reloading a small base costs a few thousand",
+    "tokens."
+  ].join("\n");
+}
+async function renderBase(store, path, absolutePath, fullUnderTokens, pinMode, budgetTokens) {
+  const bundle = await store.list(absolutePath);
+  if (bundle.length === 0) {
+    return {
+      path,
+      absolutePath,
+      mode: "empty",
+      body: "No readable records yet \u2014 pinned ahead of being populated."
+    };
+  }
+  const fullCap = pinMode === "full" ? budgetTokens : pinMode === "index" ? 0 : fullUnderTokens;
+  let degradedFrom;
+  if (fullCap > 0) {
+    const full = await store.load(absolutePath, {
+      budgetTokens: fullCap
+    });
+    if (!full.loaded && pinMode === "full") {
+      degradedFrom = { approxTokens: full.approxTokens };
+    }
+    if (full.loaded) {
+      const records = full.records.map(
+        (hit) => [
+          `#### ${hit.record.conceptId} \u2014 ${hit.record.frontmatter.title ?? "(untitled)"} (${hit.standing})`,
+          "",
+          hit.record.body.trim()
+        ].join("\n")
+      );
+      const superseded2 = full.superseded.map(
+        (entry) => `- \`${entry.conceptId}\` \u2192 superseded by ${entry.supersededBy.map((id) => `\`${id}\``).join(", ") || "(missing replacement)"}`
+      );
+      return {
+        path,
+        absolutePath,
+        mode: "full",
+        body: [
+          ...records,
+          ...superseded2.length ? [
+            "#### Superseded (bodies withheld \u2014 kb_trace reaches them)",
+            ...superseded2
+          ] : []
+        ].join("\n\n")
+      };
+    }
+  }
+  const adjudicated = adjudicate(bundle, bundle);
+  const lines = adjudicated.filter((hit) => hit.standing !== "superseded").map((hit) => renderIndexLine(hit.record));
+  const superseded = adjudicated.filter((hit) => hit.standing === "superseded").map(
+    (hit) => `- \`${hit.record.conceptId}\` \u2192 superseded by ${hit.heads.map((head) => `\`${head.conceptId}\``).join(", ") || "(missing replacement)"}`
+  );
+  return {
+    path,
+    absolutePath,
+    mode: "index",
+    body: [...lines, ...superseded].join("\n"),
+    ...degradedFrom ? { degradedFrom } : {}
+  };
+}
+async function buildContext(store, workspaceDir, options = {}) {
+  const builtin = options.profile ? CONTEXT_PROFILES[options.profile] ?? {} : {};
+  let budgetTokens = options.budgetTokens ?? builtin.budgetTokens ?? DEFAULT_CONTEXT_BUDGET;
+  let fullUnderTokens = options.fullUnderTokens ?? builtin.fullUnderTokens ?? 0;
+  const merged = await readMergedPins(workspaceDir);
+  const fromManifest = mergedContextBudgets(merged, options.profile);
+  budgetTokens = options.budgetTokens ?? fromManifest.budgetTokens ?? builtin.budgetTokens ?? DEFAULT_CONTEXT_BUDGET;
+  fullUnderTokens = options.fullUnderTokens ?? fromManifest.fullUnderTokens ?? builtin.fullUnderTokens ?? 0;
+  const pins = merged.pins.filter(
+    (pin) => !pin.profiles?.length || !options.profile || pin.profiles.includes(options.profile)
+  );
+  if (pins.length === 0) {
+    return {
+      block: "",
+      refused: false,
+      approxTokens: 0,
+      budgetTokens,
+      bases: []
+    };
+  }
+  const sections = await Promise.all(
+    pins.map(async (pin) => ({
+      section: await renderBase(
+        store,
+        pin.path,
+        pin.absolutePath,
+        fullUnderTokens,
+        pin.mode,
+        budgetTokens
+      ),
+      frozen: pin.frozen === true
+    }))
+  );
+  const modeLabel = {
+    index: "index only \u2014 record bodies are not here",
+    full: "full records \u2014 this base arrives whole",
+    empty: "empty"
+  };
+  for (const { section } of sections) {
+    if (section.degradedFrom) {
+      options.warn?.({
+        operation: "kb.context.full-pin-degraded",
+        path: section.path,
+        approxTokens: section.degradedFrom.approxTokens,
+        budgetTokens
+      });
+    }
+  }
+  const rendered = sections.map(({ section, frozen }) => {
+    const label = section.degradedFrom ? `index only \u2014 pinned \`mode: full\`, but its ~${section.degradedFrom.approxTokens} tokens exceed this block's ${budgetTokens}-token budget; kb_load it directly (load's budget is separate), or raise this profile's budget` : modeLabel[section.mode];
+    return [
+      `### ${section.path} (${label}${frozen ? " \xB7 frozen, read-only" : ""})`,
+      "",
+      `bundlePath: \`${section.absolutePath}\``,
+      "",
+      section.body
+    ].join("\n");
+  });
+  const block = [preamble(), "", rendered.join("\n\n"), ""].join("\n");
+  const bases = sections.map(({ section }) => ({
+    path: section.path,
+    absolutePath: section.absolutePath,
+    approxTokens: approxTokens(section.body)
+  }));
+  const total = approxTokens(block);
+  if (total > budgetTokens) {
+    options.warn?.({
+      operation: "kb.context.refused",
+      approxTokens: total,
+      budgetTokens,
+      bases: bases.map((base) => base.path)
+    });
+    const refusal = [
+      HEADING2,
+      "",
+      `The pinned index runs to ~${total} tokens, past the ${budgetTokens}-token`,
+      "budget, and was not emitted \u2014 a truncated index is indistinguishable",
+      "from a complete one. The pinned bases:",
+      "",
+      ...bases.map(
+        (base) => `- ${base.path} \u2014 ~${base.approxTokens} tokens (bundlePath: \`${base.absolutePath}\`)`
+      ),
+      "",
+      "For the question at hand, read what you need now \u2014 `kb_load` a base",
+      "(its own budget is separate), or `kb_index` for one base's shape.",
+      "",
+      "To bring this block back under budget, in order of preference:",
+      "- supersede or resolve stale records \u2014 the base shrinks, the knowledge keeps",
+      "- force a large base to index lines: `strauss-kb pin <path> --mode index`",
+      "- scope a pin to the profiles that need it: `strauss-kb pin <path> --profiles session-start`",
+      "- raise this profile's budget under `context` in .strauss/kb-pins.json",
+      "- unpin what no session actually needs",
+      ""
+    ].join("\n");
+    return {
+      block: refusal,
+      refused: true,
+      approxTokens: total,
+      budgetTokens,
+      bases
+    };
+  }
+  return { block, refused: false, approxTokens: total, budgetTokens, bases };
+}
+function toHookJson(block, event) {
+  return JSON.stringify({
+    hookSpecificOutput: {
+      hookEventName: event,
+      additionalContext: block
+    }
+  });
+}
+var CONTEXT_BEGIN = "<!-- strauss-kb:begin -->";
+var CONTEXT_END = "<!-- strauss-kb:end -->";
+async function syncInstructions(file, block) {
+  const existing = await readFile2(file, "utf8").catch(() => null);
+  const region = block ? `${CONTEXT_BEGIN}
+${block.trim()}
+${CONTEXT_END}` : null;
+  if (existing === null) {
+    if (!region) return { file, action: "unchanged" };
+    await writeFile2(file, `${region}
+`, "utf8");
+    return { file, action: "created" };
+  }
+  const begin = existing.indexOf(CONTEXT_BEGIN);
+  const end = existing.indexOf(CONTEXT_END);
+  if (begin !== -1 && end !== -1 && end >= begin) {
+    const before = existing.slice(0, begin);
+    const after = existing.slice(end + CONTEXT_END.length);
+    const next = region ? `${before}${region}${after}` : `${before.replace(/\n+$/, "\n")}${after.replace(/^\n+/, "\n")}`;
+    if (next === existing) return { file, action: "unchanged" };
+    await writeFile2(file, next, "utf8");
+    return { file, action: region ? "replaced" : "removed" };
+  }
+  if (!region) return { file, action: "unchanged" };
+  await writeFile2(
+    file,
+    `${existing.replace(/\n*$/, "\n\n")}${region}
+`,
+    "utf8"
+  );
+  return { file, action: "appended" };
+}
+
+// src/kb-log.ts
+import { z as z5 } from "zod";
+var LOG_FILE = "log.jsonl";
+var kbLogEntrySchema = z5.object({
+  at: z5.string().min(1),
+  by: z5.string().min(1),
+  operation: z5.string().min(1),
+  conceptId: z5.string().min(1),
+  /** Second concept id, where the operation relates two — supersession. */
+  target: z5.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
+import { z as z6 } from "zod";
+function kbJsonSchemas() {
+  return {
+    recordFrontmatter: z6.toJSONSchema(kbRecordFrontmatterSchema, {
+      io: "input"
+    }),
+    composeInput: z6.toJSONSchema(composeInputSchema, { io: "input" }),
+    logEntry: z6.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/answer.ts
+import { z as z8 } from "zod";
+
+// src/commands/model.ts
+import { z as z7 } from "zod";
+var bundlePath = z7.string().min(1).describe("Absolute path to the knowledge base directory.");
+var conceptId = z7.string().min(1).describe("e.g. decision.cursor-v2");
+function define(command) {
+  return command;
+}
+function argvFlag(argv, name) {
+  const at = argv.indexOf(name);
+  return at !== -1 ? argv[at + 1] : void 0;
+}
+
+// src/commands/answer.ts
+var answerCommand = 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: z8.object({ bundlePath, conceptId, answer: z8.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 }) => {
+    await assertBaseNotFrozen(process.cwd(), path);
+    const record = await store.answer(path, id, answer, actor);
+    return { conceptId: record.conceptId };
+  }
+});
+
+// src/commands/context.ts
+import { z as z9 } from "zod";
+var contextCommand = define({
+  name: "context",
+  tool: "kb_context",
+  usage: "context [--profile NAME] [--budget N] [--full-under N] [--format json] [--event NAME]",
+  description: "The pinned-base index block, for injection at every context birth \u2014 startup, clear, resume, and after compaction. An index, not the content: concept ids, titles and standing, with the bodies left behind kb_load at the point of use. Emits nothing when nothing is pinned. Refuses with the list of bases and their sizes rather than truncating past its budget. Budgets resolve most-specific-first: explicit flags, then the workspace manifests' `context` tables (per profile, over their `default`), then the built-in profile (session-start, compact, turn), then package defaults \u2014 so a repo tunes its own numbers in .strauss/kb-pins.json without touching hook commands. Like kb_schema and kb_types this takes no bundlePath \u2014 it reads the workspace pin manifests, because which bases a session should see is workspace state, not a property of one base.",
+  input: z9.object({
+    budgetTokens: z9.number().int().positive().optional().describe(
+      "Ceiling on the whole emitted block; past it the command refuses with a list of bases rather than truncating. Defaults to 4000."
+    ),
+    fullUnderTokens: z9.number().int().positive().optional().describe(
+      "Per-base rendering threshold, applied before the budget: a base whose complete load fits under this arrives as full records instead of index lines, and the whole block still answers to budgetTokens. Off by default \u2014 index-only is the safe default at a context birth, because injected bodies outlive the qualifiers on them; the session-start profile opts tiny bases in at 1500."
+    ),
+    profile: z9.string().optional().describe(
+      "Named budget set: built-ins are session-start (full-under 1500), compact and turn (budget 2500); the manifests' `context` tables override per repo. Unknown names fall through to defaults rather than failing."
+    ),
+    format: z9.enum(["markdown", "json"]).optional().describe(
+      "CLI envelope for hook protocols that require strict JSON on stdout. MCP callers omit this \u2014 the block itself is identical."
+    ),
+    event: z9.string().optional().describe(
+      "hookEventName stamped into the JSON envelope. Only meaningful with format=json."
+    )
+  }),
+  fromArgv: (argv) => {
+    const budget = argvFlag(argv, "--budget");
+    const fullUnder = argvFlag(argv, "--full-under");
+    const profile = argvFlag(argv, "--profile");
+    const format = argvFlag(argv, "--format");
+    const event = argvFlag(argv, "--event");
+    return {
+      ...budget ? { budgetTokens: Number(budget) } : {},
+      ...fullUnder ? { fullUnderTokens: Number(fullUnder) } : {},
+      ...profile ? { profile } : {},
+      ...format ? { format } : {},
+      ...event ? { event } : {}
+    };
+  },
+  run: async ({ store }, { budgetTokens, fullUnderTokens, profile, format, event }) => {
+    const result = await buildContext(store, process.cwd(), {
+      ...budgetTokens ? { budgetTokens } : {},
+      ...fullUnderTokens ? { fullUnderTokens } : {},
+      ...profile ? { profile } : {},
+      // Degradations — a full pin that could not fit, a refused block — go
+      // to stderr as well as into the block itself: stderr is diagnostics on
+      // both surfaces (hooks discard it, MCP logs it), so an operator can
+      // see budget pressure without reading injected context.
+      warn: (entry) => process.stderr.write(`${JSON.stringify(entry)}
+`)
+    });
+    if (!result.block) return "";
+    return format === "json" ? toHookJson(result.block, event ?? "SessionStart") : result.block;
+  }
+});
+
+// src/commands/list.ts
+import { z as z10 } from "zod";
+var listCommand = 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: z10.object({ bundlePath, type: z10.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 ?? []
+  }))
+});
+
+// src/commands/load.ts
+import { z as z11 } from "zod";
+var loadCommand = 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. Call at the point of use, not once per session: a base loaded early is summarised away by compaction, so if the visible context holds no records from this base and the question at hand is one it might govern, load before answering \u2014 never conclude nothing was decided from a context with no KB content in it. This tool (with kb_query and kb_trace) is the only supported way to read a base; a raw file read bypasses supersession resolution and returns replaced records as if current.",
+  input: z11.object({
+    bundlePath,
+    type: z11.enum(KB_RECORD_TYPES).optional(),
+    budgetTokens: z11.number().int().positive().optional().describe("Approximate token ceiling. Defaults to 25000.")
+  }),
+  fromArgv: (argv, path) => {
+    const budget = argvFlag(argv, "--budget");
+    return {
+      bundlePath: path,
+      ...argv[1] && argv[1] !== "--budget" ? { type: argv[1] } : {},
+      ...budget ? { budgetTokens: Number(budget) } : {}
+    };
+  },
+  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
+      }))
+    };
+  }
+});
+
+// src/commands/log.ts
+import { z as z12 } from "zod";
+var logCommand = 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: z12.object({ bundlePath }),
+  fromArgv: (_argv, path) => ({ bundlePath: path }),
+  run: ({ store }, { bundlePath: path }) => store.readLog(path)
+});
+
+// src/commands/no-decision.ts
+import { z as z13 } from "zod";
+var noDecisionCommand = 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: z13.object({ bundlePath, reason: z13.string().min(1) }),
+  fromArgv: (argv, path) => ({
+    bundlePath: path,
+    reason: argv.slice(1).join(" ").trim()
+  }),
+  run: async ({ store, actor, now }, { bundlePath: path, reason }) => {
+    await assertBaseNotFrozen(process.cwd(), path);
+    const record = await store.write(
+      path,
+      { ...composeNoDecisionRecord(reason, actor, now()), overwrite: true },
+      actor
+    );
+    return { conceptId: record.conceptId };
+  }
+});
+
+// src/commands/pin.ts
+import { z as z14 } from "zod";
+var pinCommand = define({
+  name: "pin",
+  tool: "kb_pin",
+  usage: "pin [bundle-path] [--mode full|index] [--profiles a,b] [--local|--user] [--frozen|--unfreeze]",
+  description: "Pin a base into a workspace pin manifest, so `context` surfaces it at every context birth. Three layers, nearest wins: the committed project manifest (.strauss/kb-pins.json, the default), `--local` (.strauss/kb-pins.local.json, personal and gitignored), and `--user` (~/.strauss/kb-pins.json, every workspace). Idempotent \u2014 re-pinning changes nothing unless --mode, --profiles, or --frozen/--unfreeze are given, which update just those fields. `--mode full` preloads the whole base into the block regardless of the full-under threshold; `--mode index` never upgrades. `--profiles` scopes the pin to named context profiles. `--frozen` marks the base concluded: write commands against it refuse and `context` labels it read-only. A path with no records yet succeeds with a warning; bases are routinely pinned before they are populated. Pins are workspace state: the pinned base itself is never touched.",
+  input: z14.object({
+    bundlePath,
+    mode: z14.enum(["full", "index"]).optional().describe(
+      "full: always emit this base's records whole (still under the block budget); index: never upgrade. Absent: the profile's full-under threshold decides."
+    ),
+    profiles: z14.array(z14.string()).optional().describe("Context profiles this pin surfaces in. Absent: all of them."),
+    layer: z14.enum(["project", "local", "user"]).optional().describe(
+      "Which manifest to write: project (committed, default), local (personal, gitignored), user (~/.strauss, every workspace)."
+    ),
+    frozen: z14.boolean().optional().describe(
+      "true: the base is concluded \u2014 writes against it refuse while pinned. false: lift a freeze."
+    )
+  }),
+  fromArgv: (argv, path) => {
+    const positional = argv[1] && !argv[1].startsWith("--") ? argv[1] : path;
+    const mode = argvFlag(argv, "--mode");
+    const profiles = argvFlag(argv, "--profiles");
+    const layer = argv.includes("--user") ? "user" : argv.includes("--local") ? "local" : void 0;
+    const frozen = argv.includes("--frozen") ? true : argv.includes("--unfreeze") ? false : void 0;
+    return {
+      bundlePath: positional,
+      ...mode ? { mode } : {},
+      ...profiles ? {
+        profiles: profiles.split(",").map((p) => p.trim()).filter(Boolean)
+      } : {},
+      ...layer ? { layer } : {},
+      ...frozen !== void 0 ? { frozen } : {}
+    };
+  },
+  run: ({ store, now }, { bundlePath: path, mode, profiles, layer, frozen }) => pinBase(store, process.cwd(), path, now(), {
+    ...mode ? { mode } : {},
+    ...profiles ? { profiles } : {},
+    ...layer ? { layer } : {},
+    ...frozen !== void 0 ? { frozen } : {}
+  })
+});
+
+// src/commands/pins.ts
+import { z as z15 } from "zod";
+var pinsCommand = define({
+  name: "pins",
+  tool: "kb_pins",
+  usage: "pins",
+  description: "Every pinned base across the manifest layers, each with its layer and whether it currently resolves to readable records. Reads the workspace manifests rather than any one base, like kb_context.",
+  input: z15.object({}),
+  fromArgv: () => ({}),
+  run: ({ store }) => listPins(store, process.cwd())
+});
+
+// src/commands/query.ts
+import { z as z16 } from "zod";
+var queryCommand = 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 kb_load when the base fits its budget: on this package's measurements, a reader holding the whole base answered eight of nine questions whose wording appears in no record, where embedding search answered four. Never read record files directly \u2014 this tool (with kb_load and kb_trace) is the only supported way to read a base; a file read bypasses supersession resolution and returns replaced records as if current.",
+  input: z16.object({
+    bundlePath,
+    text: z16.string().optional(),
+    type: z16.enum(KB_RECORD_TYPES).optional(),
+    includeNonCurrent: z16.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
+  }))
+});
+
+// src/commands/read-index.ts
+import { z as z17 } from "zod";
+var readIndexCommand = 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. The cheap re-orientation call after compaction or deep in a long session \u2014 a few hundred tokens; call it (or kb_context, when bases are pinned) first, then kb_load or fetch by concept id.",
+  input: z17.object({ bundlePath }),
+  fromArgv: (_argv, path) => ({ bundlePath: path }),
+  run: ({ store }, { bundlePath: path }) => store.readIndex(path)
+});
+
+// src/commands/schema.ts
+import { z as z18 } from "zod";
+var schemaCommand = 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: z18.object({}),
+  fromArgv: () => ({}),
+  run: () => Promise.resolve(kbJsonSchemas())
+});
+
+// src/commands/status.ts
+import { z as z19 } from "zod";
+var statusCommand = 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: z19.object({
+    bundlePath,
+    conceptId,
+    status: z19.enum(KB_RECORD_STATUSES)
+  }),
+  fromArgv: (argv, path) => ({
+    bundlePath: path,
+    conceptId: argv[1],
+    status: argv[2]
+  }),
+  run: async ({ store, actor }, { bundlePath: path, conceptId: id, status }) => {
+    await assertBaseNotFrozen(process.cwd(), path);
+    const record = await store.setStatus(path, id, status, actor);
+    return { conceptId: record.conceptId, status };
+  }
+});
+
+// src/commands/supersede.ts
+import { z as z20 } from "zod";
+var supersedeCommand = 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: z20.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 assertBaseNotFrozen(process.cwd(), path);
+    await store.supersede(path, id, replacementId, actor);
+    return { superseded: id, replacedBy: replacementId };
+  }
+});
+
+// src/commands/sync-instructions.ts
+import { z as z21 } from "zod";
+var syncInstructionsCommand = define({
+  name: "sync-instructions",
+  usage: "sync-instructions <file> [--profile NAME] [--budget N] [--full-under N]",
+  description: "Idempotently plant the `context` block between sentinel comments in an instruction file (AGENTS.md, CLAUDE.md), creating the block when absent and leaving everything outside the sentinels alone. CLI-only: this is file plumbing for runtimes whose instruction files are re-read where their conversations are not, not an agent capability \u2014 the capability is kb_context.",
+  input: z21.object({
+    file: z21.string().min(1).describe("The instruction file to edit in place."),
+    budgetTokens: z21.number().int().positive().optional(),
+    fullUnderTokens: z21.number().int().positive().optional(),
+    profile: z21.string().optional()
+  }),
+  fromArgv: (argv) => {
+    const budget = argvFlag(argv, "--budget");
+    const fullUnder = argvFlag(argv, "--full-under");
+    const profile = argvFlag(argv, "--profile");
+    return {
+      file: argv[1],
+      ...budget ? { budgetTokens: Number(budget) } : {},
+      ...fullUnder ? { fullUnderTokens: Number(fullUnder) } : {},
+      ...profile ? { profile } : {}
+    };
+  },
+  run: async ({ store }, { file, budgetTokens, fullUnderTokens, profile }) => {
+    const result = await buildContext(store, process.cwd(), {
+      ...budgetTokens ? { budgetTokens } : {},
+      ...fullUnderTokens ? { fullUnderTokens } : {},
+      ...profile ? { profile } : {},
+      warn: (entry) => process.stderr.write(`${JSON.stringify(entry)}
+`)
+    });
+    return syncInstructions(file, result.block);
+  }
+});
+
+// src/commands/trace.ts
+import { z as z22 } from "zod";
+var traceCommand = 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". This tool (with kb_load and kb_query) is the only supported way to read a base; a raw file read bypasses supersession resolution and returns replaced records as if current.',
+  input: z22.object({
+    bundlePath,
+    conceptId,
+    edges: z22.array(z22.enum(TRACE_EDGES)).optional(),
+    depth: z22.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
+  }))
+});
+
+// src/commands/types.ts
+import { z as z23 } from "zod";
+var typesCommand = 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: z23.object({}),
+  fromArgv: () => ({}),
+  run: () => Promise.resolve(RECORD_TYPES)
+});
+
+// src/commands/unpin.ts
+import { z as z24 } from "zod";
+var unpinCommand = define({
+  name: "unpin",
+  tool: "kb_unpin",
+  usage: "unpin [bundle-path]",
+  description: "Remove a base from every pin manifest layer that holds it \u2014 project, local, and user \u2014 because unpinned means gone, not still injected from another file. Reports which layers were touched.",
+  input: z24.object({ bundlePath }),
+  fromArgv: (argv, path) => ({ bundlePath: argv[1] ?? path }),
+  run: (_ctx, { bundlePath: path }) => unpinBase(process.cwd(), path)
+});
+
+// src/commands/validate.ts
+import { z as z25 } from "zod";
+var validateCommand = 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: z25.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
+});
+
+// src/commands/write.ts
+import { z as z26 } from "zod";
+var writeCommand = 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: z26.object({
+    bundlePath,
+    type: z26.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 }) => {
+    await assertBaseNotFrozen(process.cwd(), path);
+    const record = await store.write(
+      path,
+      composeRecord(type, input, actor, now()),
+      actor
+    );
+    return {
+      conceptId: record.conceptId,
+      action: record.action,
+      supersededIds: record.supersededIds
+    };
+  }
+});
+
+// src/commands/write-decision.ts
+import { z as z27 } from "zod";
+var writeDecisionCommand = 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: z27.object({ bundlePath, input: decisionInputSchema }),
+  fromArgv: async (_argv, path, stdin) => ({
+    bundlePath: path,
+    input: JSON.parse(await stdin())
+  }),
+  run: async ({ store, actor, now }, { bundlePath: path, input }) => {
+    await assertBaseNotFrozen(process.cwd(), path);
+    const record = await store.write(
+      path,
+      composeDecisionRecord(input, actor, now()),
+      actor
+    );
+    return {
+      conceptId: record.conceptId,
+      action: record.action,
+      supersededIds: record.supersededIds
+    };
+  }
+});
+
+// src/commands/index.ts
+var KB_COMMANDS = [
+  writeCommand,
+  writeDecisionCommand,
+  noDecisionCommand,
+  statusCommand,
+  supersedeCommand,
+  answerCommand,
+  loadCommand,
+  queryCommand,
+  traceCommand,
+  listCommand,
+  readIndexCommand,
+  logCommand,
+  validateCommand,
+  schemaCommand,
+  pinCommand,
+  unpinCommand,
+  pinsCommand,
+  contextCommand,
+  syncInstructionsCommand,
+  typesCommand
+];
+var KB_COMMANDS_BY_NAME = new Map(
+  KB_COMMANDS.map((command) => [command.name, command])
+);
+
+// src/markdown.ts
+import matter from "gray-matter";
+function stringifyMarkdownWithFrontmatter(content, frontmatter) {
+  return matter.stringify(content, frontmatter);
+}
+function splitMarkdownFrontmatter(text) {
+  const file = matter(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 Fault = /* @__PURE__ */ ((Fault2) => {
+  Fault2["Configuration"] = "Configuration";
+  Fault2["System"] = "System";
+  Fault2["User"] = "User";
+  return Fault2;
+})(Fault || {});
+var ErrorTypes = /* @__PURE__ */ ((ErrorTypes2) => {
+  ErrorTypes2["KbRecordAlreadyExists"] = "KbRecordAlreadyExists";
+  ErrorTypes2["KbInvalidConceptId"] = "KbInvalidConceptId";
+  ErrorTypes2["KbRecordNotFound"] = "KbRecordNotFound";
+  ErrorTypes2["KbWriteConflict"] = "KbWriteConflict";
+  return ErrorTypes2;
+})(ErrorTypes || {});
+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, action: "refused" }
+    });
+    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/search-index.ts
+import { stat } from "fs/promises";
+import { join as join3 } from "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: join3(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 stat(join3(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 stat(join3(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
+import { createHash } from "crypto";
+import {
+  appendFile,
+  link,
+  mkdir as mkdir2,
+  readdir,
+  readFile as readFile3,
+  rename,
+  unlink,
+  writeFile as writeFile3
+} from "fs/promises";
+import { join as join4, resolve as resolve4, sep as sep2 } from "path";
+var KB_DIR = join4(".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 mkdir2(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
+    });
+    const targets = new Set(frontmatter.strauss_supersedes ?? []);
+    targets.delete(conceptId2);
+    const supersededIds = [];
+    for (const old of targets) {
+      if (await this.markSupersededRetrying(bundlePath2, old, conceptId2, actor)) {
+        supersededIds.push(old);
+      }
+    }
+    this.logger.info?.({
+      operation: "kb.write",
+      bundlePath: root,
+      conceptId: conceptId2,
+      anchors: frontmatter.strauss_anchors?.length ?? 0
+    });
+    return {
+      conceptId: conceptId2,
+      frontmatter,
+      body: input.body,
+      action: supersededIds.length ? "superseded-prior" : "created",
+      supersededIds
+    };
+  }
+  /** 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 readFile3(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 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 readFile3(join4(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.markSuperseded(
+      bundlePath2,
+      conceptId2,
+      replacementId,
+      actor
+    );
+    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 approxTokens2 = records.reduce((total, hit) => total + estimateTokens(hit.record), 0) + superseded.reduce((total, entry) => total + estimateStubTokens(entry), 0);
+    if (approxTokens2 > budgetTokens) {
+      return {
+        loaded: false,
+        recordCount: wanted.length,
+        approxTokens: approxTokens2,
+        budgetTokens
+      };
+    }
+    return {
+      loaded: true,
+      recordCount: wanted.length,
+      approxTokens: approxTokens2,
+      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 readFile3(join4(root, INDEX_FILE), "utf8").catch(
+      () => null
+    );
+    if (indexIsStale(stored, expected)) {
+      await this.publish(join4(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 readFile3(
+      join4(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;
+  }
+  /**
+   * `markSuperseded`, tolerant of the two ways it legitimately doesn't land:
+   * a missing target (a broken link, legal per compose.ts) or a CAS conflict
+   * from a concurrent writer touching the same target. A conflict is retried
+   * a bounded number of times — each attempt re-reads the target fresh — and
+   * on the last, `false` reports "not marked" rather than throwing: the
+   * caller's own record is already published, so failing here would leave
+   * that publish unreported instead of undone. kb_validate's existing
+   * "not marked superseded" check is what surfaces the residue.
+   */
+  async markSupersededRetrying(bundlePath2, conceptId2, replacementId, actor, retries = 3) {
+    for (let attempt = 0; attempt <= retries; attempt++) {
+      try {
+        await this.markSuperseded(bundlePath2, conceptId2, replacementId, actor);
+        return true;
+      } catch (error) {
+        if (error instanceof KbRecordNotFoundError) return false;
+        if (!(error instanceof KbWriteConflictError)) throw error;
+        if (attempt === retries) return false;
+      }
+    }
+    return false;
+  }
+  /** The one-directional half of `supersede`: marks `conceptId` superseded. */
+  async markSuperseded(bundlePath2, conceptId2, replacementId, actor) {
+    return this.mutate(
+      bundlePath2,
+      conceptId2,
+      (frontmatter) => ({
+        ...frontmatter,
+        strauss_status: "superseded",
+        strauss_superseded_by: replacementId
+      }),
+      { operation: "supersede", by: actor, target: replacementId }
+    );
+  }
+  async mutate(bundlePath2, conceptId2, change, entry, changeBody = (body) => body) {
+    const target = this.recordPath(bundlePath2, conceptId2);
+    const before = await readFile3(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 readFile3(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 writeFile3(staging, contents, "utf8");
+    try {
+      if (overwrite) {
+        await rename(staging, target);
+        return;
+      }
+      await link(staging, target);
+    } catch (error) {
+      if (error.code === "EEXIST") {
+        throw new KbRecordAlreadyExistsError(conceptId2);
+      }
+      throw error;
+    } finally {
+      await 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 appendFile(join4(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 resolve4(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(sep2) || conceptId2.includes("/")) {
+      throw new KbInvalidConceptIdError(
+        "concept id must not contain a path separator",
+        { conceptId: conceptId2 }
+      );
+    }
+    return join4(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 createHash("sha256").update(contents).digest("hex");
+}
+
+export {
+  kbSourceSchema,
+  kbActorStampSchema,
+  kbAnchorSchema,
+  KB_RECORD_TYPES,
+  KB_SLUG_PATTERN,
+  KB_CONCEPT_ID_PATTERN,
+  kbConceptIdSchema,
+  KB_RECORD_STATUSES,
+  KB_MATERIALITIES,
+  KB_CONFIDENCES,
+  kbRecordFrontmatterSchema,
+  RECORD_TYPES,
+  isKbRecordType,
+  composeInputSchema,
+  composeRecord,
+  DECISION_TYPE,
+  NO_DECISION_SLUG,
+  decisionInputSchema,
+  composeDecisionRecord,
+  composeNoDecisionRecord,
+  isNoDecisionRecord,
+  selectDecisions,
+  contextProfileBudgets,
+  mergedContextBudgets,
+  KbPinsMalformedError,
+  KbBaseFrozenError,
+  PINS_FILE,
+  PINS_LOCAL_FILE,
+  PIN_LAYERS,
+  readPinsLayer,
+  resolvePinPath,
+  readMergedPins,
+  assertBaseNotFrozen,
+  listPins,
+  pinBase,
+  unpinBase,
+  adjudicate,
+  resolveHeads,
+  INDEX_FILE,
+  renderIndex,
+  renderIndexLine,
+  indexIsStale,
+  CONTEXT_PROFILES,
+  buildContext,
+  toHookJson,
+  CONTEXT_BEGIN,
+  CONTEXT_END,
+  syncInstructions,
+  LOG_FILE,
+  kbLogEntrySchema,
+  renderLogEntry,
+  parseLog,
+  kbJsonSchemas,
+  TRACE_EDGES,
+  trace,
+  validateBundle,
+  KB_COMMANDS,
+  KB_COMMANDS_BY_NAME,
+  stringifyMarkdownWithFrontmatter,
+  splitMarkdownFrontmatter,
+  parseMarkdownWithFrontmatter,
+  Fault,
+  ErrorTypes,
+  BaseError,
+  KbRecordAlreadyExistsError,
+  KbRecordNotFoundError,
+  KbWriteConflictError,
+  KbInvalidConceptIdError,
+  SEARCH_INDEX_FILE,
+  searchBase,
+  resolveHits,
+  loadQmd,
+  KB_DIR,
+  KbStore
+};
+//# sourceMappingURL=chunk-EDH43Z7J.js.map