@saasontools/strauss-kb 0.1.12 → 0.1.13

package/dist/{chunk-33ZCBEUV.js → chunk-XALWG3EZ.js}

@@ -44,6 +44,10 @@ var kbAnchorSchema = z.object({
   /** Line count of the text the hash was taken over. */
   lines: z.number().int().positive().optional()
 }).strict();
+var kbLinkSchema = z.object({
+  target: z.string().min(1),
+  rel: z.string().min(1)
+}).passthrough();
 var KB_RECORD_TYPES = [
   "fact",
   "requirement",
@@ -95,6 +99,10 @@ var kbRecordFrontmatterSchema = z.object({
   // strauss extensions — see the module comment.
   strauss_anchors: z.array(kbAnchorSchema).optional(),
   strauss_verify: z.array(z.string().min(1)).optional(),
+  // Typed causal edges, source → target, living on the source. `A depends_on
+  // B` means A needs B, so `kb_impact` walks these inbound: what breaks if B
+  // changes is whatever declared a dependence on it.
+  strauss_links: z.array(kbLinkSchema).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
@@ -179,9 +187,71 @@ var RECORD_TYPES = {
 function isKbRecordType(value) {
   return Object.prototype.hasOwnProperty.call(RECORD_TYPES, value);
 }
+var KB_LINK_RELS = [
+  "depends_on",
+  "constrains",
+  "informs",
+  "blocks",
+  "invalidates",
+  "verified_by",
+  "satisfies",
+  "related_to"
+];
+var LINK_RELS = {
+  depends_on: {
+    purpose: "The source needs the target to hold; the source breaks if the target changes",
+    phrase: "Depends on",
+    dependant: "source"
+  },
+  constrains: {
+    purpose: "The source bounds what the target may do; the target breaks if the constraint changes",
+    phrase: "Constrains",
+    dependant: "target"
+  },
+  informs: {
+    purpose: "The source shaped the target without binding it; the target is what needs revisiting",
+    phrase: "Informs",
+    dependant: "target"
+  },
+  blocks: {
+    purpose: "The target cannot proceed until the source is settled; the target is what waits",
+    phrase: "Blocks",
+    dependant: "target"
+  },
+  invalidates: {
+    purpose: "The source makes the target no longer hold; the target is what stops holding",
+    phrase: "Invalidates",
+    dependant: "target"
+  },
+  verified_by: {
+    purpose: "The target is the check that confirms the source; the source's confirmation moves with it",
+    phrase: "Verified by",
+    dependant: "source"
+  },
+  satisfies: {
+    purpose: "The source discharges the target's requirement; the source must change if the requirement does",
+    phrase: "Satisfies",
+    dependant: "source"
+  },
+  related_to: {
+    purpose: "A pointer worth following, with no claim of dependence",
+    phrase: "Relates to",
+    dependant: null
+  }
+};
+var KB_CAUSAL_LINK_RELS = KB_LINK_RELS.filter(
+  (rel) => LINK_RELS[rel].dependant !== null
+);
+function isKbLinkRel(value) {
+  return Object.prototype.hasOwnProperty.call(LINK_RELS, value);
+}
 
 // src/compose.ts
 import { z as z2 } from "zod";
+var composeLinkSchema = z2.object({
+  target: kbConceptIdSchema,
+  rel: z2.enum(KB_LINK_RELS)
+}).strict();
 var composeInputSchema = z2.object({
   slug: z2.string().min(1),
   /** One line, in the reader's terms. Becomes OKF `title`. */
@@ -208,6 +278,18 @@ var composeInputSchema = z2.object({
   tags: z2.array(z2.string().min(1)).optional(),
   /** Concept ids this record relates to; rendered as body links. */
   relatedConceptIds: z2.array(kbConceptIdSchema).optional(),
+  /**
+   * Typed causal edges, source → target: `{ target: "fact.b", rel:
+   * "depends_on" }` on record A says A needs B. Stored in frontmatter and
+   * also rendered as one prose sentence each, so the meaning survives a
+   * reader that knows only OKF. The vocabulary goes into the description from
+   * the same table the walk uses, so `kb_schema` emits it.
+   */
+  links: z2.array(composeLinkSchema).max(64).optional().describe(
+    `Typed causal edges, source \u2192 target \u2014 a link on this record says this record <rel> the target. ${KB_LINK_RELS.map(
+      (rel) => `${rel}: ${LINK_RELS[rel].purpose}`
+    ).join("; ")}.`
+  ),
   /** Concept ids this record replaces. The store settles the backlinks. */
   supersedes: z2.array(kbConceptIdSchema).max(32).optional(),
   materiality: z2.enum(KB_MATERIALITIES).optional(),
@@ -247,6 +329,15 @@ function composeRecord(type, input, writtenBy, writtenAt) {
   if (parsed.owner) frontmatter.strauss_owner = parsed.owner;
   if (parsed.supersedes?.length)
     frontmatter.strauss_supersedes = parsed.supersedes;
+  const selfLink = parsed.links?.find(
+    (link2) => link2.target === `${type}.${parsed.slug}`
+  );
+  if (selfLink) {
+    throw new Error(
+      `kb: ${type}.${parsed.slug} cannot ${selfLink.rel} itself \u2014 a link must name another record`
+    );
+  }
+  if (parsed.links?.length) frontmatter.strauss_links = parsed.links;
   const blocks = [];
   for (const heading of spec.sections) {
     const text = sections[heading];
@@ -258,6 +349,11 @@ ${text}`);
   for (const related of parsed.relatedConceptIds ?? []) {
     blocks.push(`Relates to [${related}](${related}.md).`);
   }
+  for (const link2 of parsed.links ?? []) {
+    blocks.push(
+      `${LINK_RELS[link2.rel].phrase} [${link2.target}](${link2.target}.md).`
+    );
+  }
   if (parsed.sources?.length) {
     blocks.push(
       parsed.sources.map((source) => `[^${source.id}]: ${source.title ?? source.resource}`).join("\n")
@@ -281,7 +377,7 @@ var decisionInputSchema = composeInputSchema.omit({ sections: true }).extend({
   impact: z3.string().min(1).optional()
 }).strict();
 function composeDecisionRecord(input, writtenBy, writtenAt) {
-  const { alternative, impact, ...rest } = input;
+  const { alternative, impact: impact2, ...rest } = input;
   return composeRecord(
     DECISION_TYPE,
     {
@@ -290,7 +386,7 @@ function composeDecisionRecord(input, writtenBy, writtenAt) {
         Decision: input.title,
         Rationale: input.why,
         ...alternative ? { Rejected: alternative } : {},
-        ...impact ? { Impact: impact } : {}
+        ...impact2 ? { Impact: impact2 } : {}
       }
     },
     writtenBy,
@@ -785,6 +881,7 @@ var ErrorTypes = /* @__PURE__ */ ((ErrorTypes2) => {
   ErrorTypes2["KbPackBudgetExceeded"] = "KbPackBudgetExceeded";
   ErrorTypes2["KbRecordNotFound"] = "KbRecordNotFound";
   ErrorTypes2["KbSelfVerification"] = "KbSelfVerification";
+  ErrorTypes2["KbUnknownLinkRel"] = "KbUnknownLinkRel";
   ErrorTypes2["KbWriteConflict"] = "KbWriteConflict";
   return ErrorTypes2;
 })(ErrorTypes || {});
@@ -893,6 +990,23 @@ var KbPackBudgetExceededError = class extends BaseError {
   budgetTokens;
   excluded;
 };
+var KbUnknownLinkRelError = class extends BaseError {
+  constructor(rel, expected) {
+    super({
+      message: `kb: ${rel} is not a rel a walk can follow \u2014 expected one of ${expected.join(", ")}`,
+      errorType: "KbUnknownLinkRel" /* KbUnknownLinkRel */,
+      code: 400,
+      fault: "User" /* User */,
+      retriable: false,
+      reportToUser: true,
+      details: { rel, expected: expected.join(", ") }
+    });
+    this.rel = rel;
+    this.expected = expected;
+  }
+  rel;
+  expected;
+};
 var KbMissingFlagValueError = class extends BaseError {
   constructor(flag) {
     super({
@@ -1624,6 +1738,7 @@ ${CONTEXT_END}` : null;
 // src/kb-edges.ts
 var KB_EDGE_KINDS = [
   "body-link",
+  "typed-link",
   "supersession",
   "anchor",
   "source"
@@ -1632,10 +1747,11 @@ var BODY_LINK_TARGET = new RegExp(
   `\\]\\((${KB_CONCEPT_ID_PATTERN.source.replace(/^\^|\$$/g, "")})\\.md\\)`,
   "g"
 );
-function neighbours(from, bundle, kinds = KB_EDGE_KINDS) {
+var DEFAULT_TYPED_LINK_RELS = KB_LINK_RELS;
+function neighbours(from, bundle, kinds = KB_EDGE_KINDS, linkRels = DEFAULT_TYPED_LINK_RELS) {
   const found = /* @__PURE__ */ new Map();
   for (const kind of kinds) {
-    for (const record of edgeNeighbours(from, bundle, kind)) {
+    for (const record of edgeNeighbours(from, bundle, kind, linkRels)) {
       const existing = found.get(record.conceptId);
       if (existing) {
         if (!existing.via.includes(kind)) existing.via.push(kind);
@@ -1646,7 +1762,7 @@ function neighbours(from, bundle, kinds = KB_EDGE_KINDS) {
   }
   return [...found.values()];
 }
-function edgeNeighbours(from, bundle, kind) {
+function edgeNeighbours(from, bundle, kind, linkRels = DEFAULT_TYPED_LINK_RELS) {
   switch (kind) {
     // A link whose target is not in the bundle is legal per compose.ts —
     // records are routinely written before the ones they point at exist — so
@@ -1660,6 +1776,21 @@ function edgeNeighbours(from, bundle, kind) {
         (candidate) => candidate.conceptId !== from.conceptId && targets.has(candidate.conceptId)
       );
     }
+    // Outbound only, like `body-link`, and for the same reason: this is what
+    // the record declares about itself. A missing target is legal — the walk
+    // skips it, and `kb_validate` is what reports it as a warning. A rel
+    // outside `linkRels` is skipped too, which is how an unknown rel stays
+    // untraversable everywhere rather than one walk at a time.
+    case "typed-link": {
+      const allowed = new Set(linkRels);
+      const targets = new Set(
+        (from.frontmatter.strauss_links ?? []).filter((link2) => allowed.has(link2.rel)).map((link2) => link2.target)
+      );
+      if (!targets.size) return [];
+      return bundle.filter(
+        (candidate) => candidate.conceptId !== from.conceptId && targets.has(candidate.conceptId)
+      );
+    }
     // Both directions and both pointers: `supersede()` writes the pair, but a
     // hand-edit can leave one side behind, and a walk trusting one pointer
     // would miss a replacement the bundle openly declares.
@@ -1701,7 +1832,7 @@ function anchorsTouch(left, right) {
 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 });
+  const report = (check, conceptId2, note, severity = "error") => problems.push({ check, conceptId: conceptId2, note, severity });
   for (const record of records) {
     const { conceptId: conceptId2, frontmatter: fm } = record;
     if (!isKbRecordType(fm.type)) {
@@ -1725,6 +1856,36 @@ function validateBundle(records) {
         report("supersedes", conceptId2, `${old} is not marked superseded`);
       }
     }
+    for (const link2 of fm.strauss_links ?? []) {
+      if (!isKbLinkRel(link2.rel)) {
+        report(
+          "link_rel",
+          conceptId2,
+          `unknown rel "${link2.rel}" on link to ${link2.target} \u2014 expected one of ${KB_LINK_RELS.join(", ")}`
+        );
+      }
+      if (!KB_CONCEPT_ID_PATTERN.test(link2.target)) {
+        report(
+          "link_target",
+          conceptId2,
+          `target "${link2.target}" is not a valid concept id \u2014 expected <type>.<slug>, both kebab-case`
+        );
+      } else if (link2.target === conceptId2) {
+        report(
+          "link_target",
+          conceptId2,
+          `links to itself (${link2.rel})`,
+          "warning"
+        );
+      } else if (!byId.has(link2.target)) {
+        report(
+          "link_target",
+          conceptId2,
+          `target ${link2.target} is not in the bundle`,
+          "warning"
+        );
+      }
+    }
     if (fm.strauss_assumption && fm.sources?.length) {
       report("assumption", conceptId2, "marked an assumption but cites sources");
     }
@@ -2075,7 +2236,12 @@ function kbJsonSchemas() {
 }
 
 // src/trace.ts
-var TRACE_EDGES = ["supersession", "anchor", "source"];
+var TRACE_EDGES = [
+  "typed-link",
+  "supersession",
+  "anchor",
+  "source"
+];
 function trace(seedId, bundle, options = {}) {
   const edges = options.edges?.length ? options.edges : TRACE_EDGES;
   const maxDepth = options.depth ?? 3;
@@ -2090,7 +2256,12 @@ function trace(seedId, bundle, options = {}) {
     const next = [];
     for (const from of frontier) {
       for (const edge of edges) {
-        for (const record of edgeNeighbours(from, bundle, edge)) {
+        for (const record of edgeNeighbours(
+          from,
+          bundle,
+          edge,
+          KB_CAUSAL_LINK_RELS
+        )) {
           const existing = reached.get(record.conceptId);
           if (existing) {
             if (existing.depth > 0 && !existing.via.includes(edge)) {
@@ -2322,16 +2493,28 @@ var answerCommand = define({
   }
 });
 
-// src/commands/catalog.ts
+// src/commands/backlinks.ts
 import { z as z10 } from "zod";
+var backlinksCommand = define({
+  name: "backlinks",
+  tool: "kb_backlinks",
+  usage: "backlinks <concept-id>",
+  description: "Who points at this record: every inbound typed causal link (`strauss_links`), one hop, every rel including `related_to`, each with its rel and the standing of the record that made it. Use it when you need the exact edges \u2014 reviewing or renaming a record.",
+  input: z10.object({ bundlePath, conceptId }),
+  fromArgv: (argv, path) => ({ bundlePath: path, conceptId: argv[1] }),
+  run: async ({ store }, { bundlePath: path, conceptId: id }) => store.backlinks(path, id)
+});
+
+// src/commands/catalog.ts
+import { z as z11 } from "zod";
 var catalogCommand = define({
   name: "catalog",
   tool: "kb_catalog",
   usage: "catalog [type]",
   description: "Lists every record as one line \u2014 concept id, type, title, standing, and a stale flag \u2014 at roughly thirty tokens each. Pick this over kb_load once kb_load refuses: kb_catalog never refuses. Superseded records show only their replacement; fetch bodies with kb_load, kb_pack, kb_query, or kb_trace.",
-  input: z10.object({
+  input: z11.object({
     bundlePath,
-    type: z10.enum(KB_RECORD_TYPES).optional()
+    type: z11.enum(KB_RECORD_TYPES).optional()
   }),
   fromArgv: (argv, path) => ({
     bundlePath: path,
@@ -2386,26 +2569,26 @@ function count(value, noun) {
 }
 
 // src/commands/context.ts
-import { z as z11 } from "zod";
+import { z as z12 } 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: z11.object({
-    budgetTokens: z11.number().int().positive().optional().describe(
+  input: z12.object({
+    budgetTokens: z12.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: z11.number().int().positive().optional().describe(
+    fullUnderTokens: z12.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: z11.string().optional().describe(
+    profile: z12.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: z11.enum(["markdown", "json"]).optional().describe(
+    format: z12.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: z11.string().optional().describe(
+    event: z12.string().optional().describe(
       "hookEventName stamped into the JSON envelope. Only meaningful with format=json."
     )
   }),
@@ -2441,14 +2624,14 @@ var contextCommand = define({
 });
 
 // src/commands/doctor.ts
-import { z as z12 } from "zod";
-var days = (what, fallback) => z12.number().int().positive().optional().describe(`${what} Defaults to ${fallback}.`);
+import { z as z13 } from "zod";
+var days = (what, fallback) => z13.number().int().positive().optional().describe(`${what} Defaults to ${fallback}.`);
 var doctorCommand = define({
   name: "doctor",
   tool: "kb_doctor",
   usage: "doctor [--expiring-days N] [--unverified-days N] [--aging-days N] [--repo-root PATH] [--strict]",
   description: "Read-only health sweep: expired, expiring, unverified, aging, orphaned, broken-supersession, superseded-but-cited, drifted anchors. Every group is reported even when empty; nothing is written or re-stamped. Use it when picking up a base you have not touched in a while; kb_validate only checks that pointers between records agree.",
-  input: z12.object({
+  input: z13.object({
     bundlePath,
     repoRoot: REPO_ROOT,
     expiringDays: days(
@@ -2463,7 +2646,7 @@ var doctorCommand = define({
       "How long a record may stay `open` or `proposed` before `aging` reports it, in days.",
       DEFAULT_AGING_DAYS
     ),
-    strict: z12.boolean().optional().describe(
+    strict: z13.boolean().optional().describe(
       "Turn an expired record into a non-zero exit for the CLI. No effect on the report itself."
     )
   }),
@@ -2538,14 +2721,47 @@ function render2(result) {
   return lines.join("\n");
 }
 
+// src/commands/impact.ts
+import { z as z14 } from "zod";
+var impactCommand = define({
+  name: "impact",
+  tool: "kb_impact",
+  usage: "impact <concept-id> [--depth N] [--rels a,b]",
+  description: "What breaks if this record changes: its transitive set of dependants, each with its standing. Each rel declares which of its ends depends on the other, and the walk follows each rel in its own direction. Naming `related_to` or an unknown rel in `rels` is an error. kb_backlinks gives one flat hop.",
+  input: z14.object({
+    bundlePath,
+    conceptId,
+    depth: z14.number().int().positive().optional().describe(
+      "Hops out from the record. Unbounded when omitted; a walk this cuts reports truncated: true."
+    ),
+    rels: z14.array(z14.enum(KB_CAUSAL_LINK_RELS)).optional().describe(
+      "Narrow which rels the walk follows. Defaults to every rel that carries a dependence \u2014 all but related_to."
+    )
+  }),
+  fromArgv: (argv, path) => {
+    const depth = argvFlag(argv, "--depth");
+    const rels = argvFlag(argv, "--rels");
+    return {
+      bundlePath: path,
+      conceptId: argv[1],
+      ...depth ? { depth: Number(depth) } : {},
+      ...rels ? { rels: rels.split(",").filter(Boolean) } : {}
+    };
+  },
+  run: async ({ store }, { bundlePath: path, conceptId: id, depth, rels }) => store.impact(path, id, {
+    ...depth !== void 0 ? { depth } : {},
+    ...rels?.length ? { rels } : {}
+  })
+});
+
 // src/commands/list.ts
-import { z as z13 } from "zod";
+import { z as z15 } 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: z13.object({ bundlePath, type: z13.enum(KB_RECORD_TYPES).optional() }),
+  input: z15.object({ bundlePath, type: z15.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,
@@ -2557,17 +2773,17 @@ var listCommand = define({
 });
 
 // src/commands/load.ts
-import { z as z14 } from "zod";
+import { z as z16 } from "zod";
 var loadCommand = define({
   name: "load",
   tool: "kb_load",
   usage: "load [type] [--budget N | --all] [--repo-root PATH]",
   description: "Loads the whole knowledge base at once, each record with its standing. Superseded records arrive as stubs; rejected and open records arrive whole. Refuses past the token budget \u2014 call kb_catalog, kb_pack on it; `all` bypasses the budget. Never read record files directly. Cache-stable; `digest` is the base's content stamp \u2014 hooks use it to tell you when to reload.",
-  input: z14.object({
+  input: z16.object({
     bundlePath,
-    type: z14.enum(KB_RECORD_TYPES).optional(),
-    budgetTokens: z14.number().int().positive().optional().describe("Approximate token ceiling. Defaults to 25000."),
-    all: z14.boolean().optional().describe(
+    type: z16.enum(KB_RECORD_TYPES).optional(),
+    budgetTokens: z16.number().int().positive().optional().describe("Approximate token ceiling. Defaults to 25000."),
+    all: z16.boolean().optional().describe(
       "Loads the entire base regardless of size, bypassing the token budget; mutually exclusive with budgetTokens."
     ),
     repoRoot: REPO_ROOT
@@ -2609,25 +2825,25 @@ var loadCommand = define({
 });
 
 // src/commands/log.ts
-import { z as z15 } from "zod";
+import { z as z17 } 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: z15.object({ bundlePath }),
+  input: z17.object({ bundlePath }),
   fromArgv: (_argv, path) => ({ bundlePath: path }),
   run: ({ store }, { bundlePath: path }) => store.readLog(path)
 });
 
 // src/commands/no-decision.ts
-import { z as z16 } from "zod";
+import { z as z18 } 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: z16.object({ bundlePath, reason: z16.string().min(1) }),
+  input: z18.object({ bundlePath, reason: z18.string().min(1) }),
   fromArgv: (argv, path) => ({
     bundlePath: path,
     reason: argv.slice(1).join(" ").trim()
@@ -2644,20 +2860,20 @@ var noDecisionCommand = define({
 });
 
 // src/commands/pack.ts
-import { z as z17 } from "zod";
+import { z as z19 } from "zod";
 var packCommand = define({
   name: "pack",
   tool: "kb_pack",
   usage: "pack <conceptId> [--hops N] [--max-nodes N] [--budget N]",
   description: "The bounded neighbourhood around one record: everything within `hops` of the root, ranked and cut to `maxNodes`, with every cut record named under Excluded \u2014 a named gap is knowable, a silent one is not. Prefer this over kb_load when the base is too large to hold whole and the work centres on one record; prefer it over kb_query when the question needs the governed neighbourhood \u2014 what was settled and what binds near this record \u2014 rather than a lookup by wording. Superseded records arrive as name, replacement and date stubs exactly as kb_load emits them: their bodies no longer hold, and kb_trace has the history. Refuses outright rather than truncating when the pack would exceed its token budget \u2014 a partial pack is indistinguishable from a complete one \u2014 reporting the record count and every already-cut id so the caller can lower hops or maxNodes, or raise the budget. The header carries the bundle, root, budget and a timestamp; everything below the header is byte-identical across runs over an unchanged base, so two packs can be diffed and a changed byte means changed knowledge. This tool (with kb_load, 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: z17.object({
+  input: z19.object({
     bundlePath,
     conceptId,
-    hops: z17.number().int().positive().optional().describe("How far from the root the walk may reach. Defaults to 2."),
-    maxNodes: z17.number().int().positive().optional().describe(
+    hops: z19.number().int().positive().optional().describe("How far from the root the walk may reach. Defaults to 2."),
+    maxNodes: z19.number().int().positive().optional().describe(
       "How many records the pack may hold, root included. Defaults to 20."
     ),
-    budgetTokens: z17.number().int().positive().optional().describe(
+    budgetTokens: z19.number().int().positive().optional().describe(
       "Approximate token ceiling over what is actually emitted. Defaults to 25000."
     )
   }),
@@ -2744,22 +2960,22 @@ function warningLabel(warning) {
 }
 
 // src/commands/pin.ts
-import { z as z18 } from "zod";
+import { z as z20 } 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: z18.object({
+  input: z20.object({
     bundlePath,
-    mode: z18.enum(["full", "index"]).optional().describe(
+    mode: z20.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: z18.array(z18.string()).optional().describe("Context profiles this pin surfaces in. Absent: all of them."),
-    layer: z18.enum(["project", "local", "user"]).optional().describe(
+    profiles: z20.array(z20.string()).optional().describe("Context profiles this pin surfaces in. Absent: all of them."),
+    layer: z20.enum(["project", "local", "user"]).optional().describe(
       "Which manifest to write: project (committed, default), local (personal, gitignored), user (~/.strauss, every workspace)."
     ),
-    frozen: z18.boolean().optional().describe(
+    frozen: z20.boolean().optional().describe(
       "true: the base is concluded \u2014 writes against it refuse while pinned. false: lift a freeze."
     )
   }),
@@ -2788,29 +3004,29 @@ var pinCommand = define({
 });
 
 // src/commands/pins.ts
-import { z as z19 } from "zod";
+import { z as z21 } 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: z19.object({}),
+  input: z21.object({}),
   fromArgv: () => ({}),
   run: ({ store }) => listPins(store, process.cwd())
 });
 
 // src/commands/query.ts
-import { z as z20 } from "zod";
+import { z as z22 } from "zod";
 var queryCommand = define({
   name: "query",
   tool: "kb_query",
   usage: "query <text...> [--repo-root PATH]",
   description: "Search; every hit carries its standing. Flagged, never filtered: a superseded hit returns with its replacement, a rejected one is marked. Prefer kb_load when the base fits its budget \u2014 a full read beats search. Results are volatile: place them at the tail, not the cached prefix. Never read record files directly.",
-  input: z20.object({
+  input: z22.object({
     bundlePath,
-    text: z20.string().optional(),
-    type: z20.enum(KB_RECORD_TYPES).optional(),
-    includeNonCurrent: z20.boolean().optional(),
+    text: z22.string().optional(),
+    type: z22.enum(KB_RECORD_TYPES).optional(),
+    includeNonCurrent: z22.boolean().optional(),
     repoRoot: REPO_ROOT
   }),
   // `--repo-root` is a flag, so its value must not fall into the search text.
@@ -2842,40 +3058,40 @@ var queryCommand = define({
 });
 
 // src/commands/read-index.ts
-import { z as z21 } from "zod";
+import { z as z23 } 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: z21.object({ bundlePath }),
+  input: z23.object({ bundlePath }),
   fromArgv: (_argv, path) => ({ bundlePath: path }),
   run: ({ store }, { bundlePath: path }) => store.readIndex(path)
 });
 
 // src/commands/schema.ts
-import { z as z22 } from "zod";
+import { z as z24 } 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: z22.object({}),
+  input: z24.object({}),
   fromArgv: () => ({}),
   run: () => Promise.resolve(kbJsonSchemas())
 });
 
 // src/commands/status.ts
-import { z as z23 } from "zod";
+import { z as z25 } 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: z23.object({
+  input: z25.object({
     bundlePath,
     conceptId,
-    status: z23.enum(KB_RECORD_STATUSES)
+    status: z25.enum(KB_RECORD_STATUSES)
   }),
   fromArgv: (argv, path) => ({
     bundlePath: path,
@@ -2890,13 +3106,13 @@ var statusCommand = define({
 });
 
 // src/commands/supersede.ts
-import { z as z24 } from "zod";
+import { z as z26 } 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: z24.object({ bundlePath, conceptId, replacementId: conceptId }),
+  input: z26.object({ bundlePath, conceptId, replacementId: conceptId }),
   fromArgv: (argv, path) => ({
     bundlePath: path,
     conceptId: argv[1],
@@ -2910,16 +3126,16 @@ var supersedeCommand = define({
 });
 
 // src/commands/sync-instructions.ts
-import { z as z25 } from "zod";
+import { z as z27 } 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: z25.object({
-    file: z25.string().min(1).describe("The instruction file to edit in place."),
-    budgetTokens: z25.number().int().positive().optional(),
-    fullUnderTokens: z25.number().int().positive().optional(),
-    profile: z25.string().optional()
+  input: z27.object({
+    file: z27.string().min(1).describe("The instruction file to edit in place."),
+    budgetTokens: z27.number().int().positive().optional(),
+    fullUnderTokens: z27.number().int().positive().optional(),
+    profile: z27.string().optional()
   }),
   fromArgv: (argv) => {
     const budget = argvFlag(argv, "--budget");
@@ -2945,17 +3161,17 @@ var syncInstructionsCommand = define({
 });
 
 // src/commands/trace.ts
-import { z as z26 } from "zod";
+import { z as z28 } 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: z26.object({
+  input: z28.object({
     bundlePath,
     conceptId,
-    edges: z26.array(z26.enum(TRACE_EDGES)).optional(),
-    depth: z26.number().int().positive().optional()
+    edges: z28.array(z28.enum(TRACE_EDGES)).optional(),
+    depth: z28.number().int().positive().optional()
   }),
   fromArgv: (argv, path) => ({
     bundlePath: path,
@@ -2977,53 +3193,56 @@ var traceCommand = define({
 });
 
 // src/commands/types.ts
-import { z as z27 } from "zod";
+import { z as z29 } 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: z27.object({}),
+  input: z29.object({}),
   fromArgv: () => ({}),
   run: () => Promise.resolve(RECORD_TYPES)
 });
 
 // src/commands/unpin.ts
-import { z as z28 } from "zod";
+import { z as z30 } 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: z28.object({ bundlePath }),
+  input: z30.object({ bundlePath }),
   fromArgv: (argv, path) => ({ bundlePath: argv[1] ?? path }),
   run: (_ctx, { bundlePath: path }) => unpinBase(process.cwd(), path)
 });
 
 // src/commands/validate.ts
-import { z as z29 } from "zod";
+import { z as z31 } 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: z29.object({ bundlePath }),
+  description: "Check pointers no single record can see: supersession links that disagree between the two records, typed causal links, and assumptions that cite sources. Each finding carries a severity: errors fail the exit code, warnings do not.",
+  input: z31.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
+  // Warnings never fail the exit code; every other severity does.
+  failsWhen: (result) => Array.isArray(result) && result.some(
+    (problem) => problem.severity !== "warning"
+  )
 });
 
 // src/commands/verify.ts
-import { z as z30 } from "zod";
+import { z as z32 } from "zod";
 var verifyCommand = define({
   name: "verify",
   tool: "kb_verify",
   usage: "verify <concept-id> --note <text>",
   description: "Append one verified[] event \u2014 who checked the record, when, and what the check found. Appends only; prior events are never rewritten. A record's own generator is refused unless the actor is human: re-reading your own output is not an independent check.",
-  input: z30.object({
+  input: z32.object({
     bundlePath,
     conceptId,
-    note: z30.string().refine((s) => s.trim().length > 0, {
+    note: z32.string().refine((s) => s.trim().length > 0, {
       message: "note must say what the check found"
     })
   }),
@@ -3043,7 +3262,7 @@ var verifyCommand = define({
 });
 
 // src/commands/write.ts
-import { z as z31 } from "zod";
+import { z as z33 } from "zod";
 var writeCommand = define({
   name: "write",
   tool: "kb_write",
@@ -3057,9 +3276,9 @@ var writeCommand = define({
     "- 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: z31.object({
+  input: z33.object({
     bundlePath,
-    type: z31.enum(KB_RECORD_TYPES),
+    type: z33.enum(KB_RECORD_TYPES),
     input: composeInputSchema
   }),
   fromArgv: async (argv, path, stdin) => ({
@@ -3083,7 +3302,7 @@ var writeCommand = define({
 });
 
 // src/commands/write-decision.ts
-import { z as z32 } from "zod";
+import { z as z34 } from "zod";
 var writeDecisionCommand = define({
   name: "write-decision",
   tool: "kb_write_decision",
@@ -3096,7 +3315,7 @@ var writeDecisionCommand = define({
     "- `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: z32.object({ bundlePath, input: decisionInputSchema }),
+  input: z34.object({ bundlePath, input: decisionInputSchema }),
   fromArgv: async (_argv, path, stdin) => ({
     bundlePath: path,
     input: JSON.parse(await stdin())
@@ -3131,6 +3350,8 @@ var KB_COMMANDS = [
   packCommand,
   queryCommand,
   traceCommand,
+  impactCommand,
+  backlinksCommand,
   listCommand,
   readIndexCommand,
   logCommand,
@@ -3276,6 +3497,141 @@ import {
 } from "fs/promises";
 import { join as join4, resolve as resolve5, sep as sep3 } from "path";
 
+// src/kb-links/inbound.ts
+function inboundIndex(bundle) {
+  const byTarget = /* @__PURE__ */ new Map();
+  for (const record of bundle) {
+    for (const link2 of record.frontmatter.strauss_links ?? []) {
+      if (link2.target === record.conceptId) continue;
+      const edges = byTarget.get(link2.target) ?? [];
+      if (edges.some(
+        (edge) => edge.from === record.conceptId && edge.rel === link2.rel
+      )) {
+        continue;
+      }
+      edges.push({ from: record.conceptId, rel: link2.rel });
+      byTarget.set(link2.target, edges);
+    }
+  }
+  return byTarget;
+}
+
+// src/kb-links/backlinks.ts
+function backlinks(targetId, bundle) {
+  const byId = new Map(bundle.map((record) => [record.conceptId, record]));
+  if (!byId.has(targetId)) throw new KbRecordNotFoundError(targetId);
+  const standingOf = new Map(
+    adjudicate(bundle, bundle).map((hit) => [hit.record.conceptId, hit])
+  );
+  const rows = [];
+  for (const edge of inboundIndex(bundle).get(targetId) ?? []) {
+    const record = byId.get(edge.from);
+    if (!record) continue;
+    const hit = standingOf.get(edge.from);
+    rows.push({
+      ...edge,
+      title: record.frontmatter.title ?? null,
+      standing: hit?.standing ?? "unsettled",
+      warnings: hit?.warnings ?? []
+    });
+  }
+  return {
+    target: targetId,
+    backlinks: rows.sort(
+      (left, right) => left.from.localeCompare(right.from) || left.rel.localeCompare(right.rel)
+    )
+  };
+}
+
+// src/kb-links/impact.ts
+function impact(targetId, bundle, options = {}) {
+  const byId = new Map(bundle.map((record) => [record.conceptId, record]));
+  if (!byId.has(targetId)) throw new KbRecordNotFoundError(targetId);
+  const rels = resolveRels(options.rels);
+  const maxDepth = options.depth ?? Number.POSITIVE_INFINITY;
+  const inbound = inboundIndex(bundle);
+  const standingOf = new Map(
+    adjudicate(bundle, bundle).map((hit) => [hit.record.conceptId, hit])
+  );
+  const reached = /* @__PURE__ */ new Map();
+  const stopped = [];
+  let frontier = [targetId];
+  let depth = 0;
+  while (frontier.length && depth < maxDepth) {
+    depth += 1;
+    const next = [];
+    const consider = (dependantId, edge) => {
+      if (dependantId === targetId) return;
+      const existing = reached.get(dependantId);
+      if (existing) {
+        if (!hasEdge(existing.via, edge)) existing.via.push(edge);
+        return;
+      }
+      const record = byId.get(dependantId);
+      if (!record) return;
+      const hit = standingOf.get(dependantId);
+      const entry = {
+        conceptId: dependantId,
+        title: record.frontmatter.title ?? null,
+        standing: hit?.standing ?? "unsettled",
+        warnings: hit?.warnings ?? [],
+        depth,
+        via: [edge]
+      };
+      reached.set(dependantId, entry);
+      if (entry.standing === "superseded" || entry.standing === "rejected") {
+        stopped.push(dependantId);
+        return;
+      }
+      next.push(dependantId);
+    };
+    for (const id of frontier) {
+      for (const edge of inbound.get(id) ?? []) {
+        if (!rels.has(edge.rel)) continue;
+        if (dependantEnd(edge.rel) !== "source") continue;
+        consider(edge.from, { source: edge.from, target: id, rel: edge.rel });
+      }
+      for (const link2 of byId.get(id)?.frontmatter.strauss_links ?? []) {
+        if (!rels.has(link2.rel)) continue;
+        if (dependantEnd(link2.rel) !== "target") continue;
+        if (link2.target === id) continue;
+        consider(link2.target, {
+          source: id,
+          target: link2.target,
+          rel: link2.rel
+        });
+      }
+    }
+    frontier = next;
+  }
+  return {
+    root: targetId,
+    impacted: [...reached.values()].sort(
+      (left, right) => left.depth - right.depth || left.conceptId.localeCompare(right.conceptId)
+    ),
+    stopped: stopped.sort(),
+    truncated: frontier.length > 0,
+    unexpanded: [...frontier].sort()
+  };
+}
+function resolveRels(rels) {
+  if (!rels?.length) return new Set(KB_CAUSAL_LINK_RELS);
+  for (const rel of rels) {
+    if (!isKbLinkRel(rel) || LINK_RELS[rel].dependant === null) {
+      throw new KbUnknownLinkRelError(rel, KB_CAUSAL_LINK_RELS);
+    }
+  }
+  return new Set(rels);
+}
+function dependantEnd(rel) {
+  return isKbLinkRel(rel) ? LINK_RELS[rel].dependant : null;
+}
+function hasEdge(edges, edge) {
+  return edges.some(
+    (existing) => existing.source === edge.source && existing.target === edge.target && existing.rel === edge.rel
+  );
+}
+
 // src/kb-gitattributes.ts
 var GITATTRIBUTES_FILE = ".gitattributes";
 var UNION_MERGE_LINE = `${LOG_FILE} text eol=lf merge=union`;
@@ -3679,6 +4035,14 @@ ${answer}
   async pack(bundlePath2, rootId, options = {}) {
     return pack(await this.list(bundlePath2), rootId, options);
   }
+  /** What breaks if this record changes. See `kb-links/impact.ts`. */
+  async impact(bundlePath2, targetId, options = {}) {
+    return impact(targetId, await this.list(bundlePath2), options);
+  }
+  /** Who points at this record, one hop. See `kb-links/backlinks.ts`. */
+  async backlinks(bundlePath2, targetId) {
+    return backlinks(targetId, await this.list(bundlePath2));
+  }
   /**
    * The stored index, rebuilt if it disagrees with the records.
    *
@@ -4083,13 +4447,14 @@ function typeRank(record) {
 }
 
 // src/version.ts
-var VERSION = true ? "0.1.12" : "0.0.0-dev";
+var VERSION = true ? "0.1.13" : "0.0.0-dev";
 
 export {
   kbSourceSchema,
   kbActorStampSchema,
   kbVerifiedEventSchema,
   kbAnchorSchema,
+  kbLinkSchema,
   KB_RECORD_TYPES,
   KB_SLUG_PATTERN,
   KB_CONCEPT_ID_PATTERN,
@@ -4100,6 +4465,11 @@ export {
   kbRecordFrontmatterSchema,
   RECORD_TYPES,
   isKbRecordType,
+  KB_LINK_RELS,
+  LINK_RELS,
+  KB_CAUSAL_LINK_RELS,
+  isKbLinkRel,
+  composeLinkSchema,
   composeInputSchema,
   composeRecord,
   DECISION_TYPE,
@@ -4122,6 +4492,7 @@ export {
   KbWriteConflictError,
   KbSelfVerificationError,
   KbPackBudgetExceededError,
+  KbUnknownLinkRelError,
   KbMissingFlagValueError,
   KbInvalidConceptIdError,
   contextProfileBudgets,
@@ -4153,6 +4524,7 @@ export {
   CONTEXT_END,
   syncInstructions,
   KB_EDGE_KINDS,
+  DEFAULT_TYPED_LINK_RELS,
   neighbours,
   edgeNeighbours,
   validateBundle,
@@ -4180,9 +4552,12 @@ export {
   DEFAULT_PACK_HOPS,
   DEFAULT_PACK_MAX_NODES,
   pack,
+  inboundIndex,
+  backlinks,
+  impact,
   KB_DIR,
   DEFAULT_LOAD_BUDGET,
   KbStore,
   VERSION
 };
-//# sourceMappingURL=chunk-33ZCBEUV.js.map
+//# sourceMappingURL=chunk-XALWG3EZ.js.map