@saasontools/strauss-kb 0.1.3 → 0.1.5

package/dist/index.d.cts

@@ -318,8 +318,9 @@ type KbLoadResult = {
     /** Named only. Their bodies are reachable through `trace`. */
     superseded: KbSupersededStub[];
     recordCount: number;
-    approxTokens: number;
-    budgetTokens: number;
+    tokensLoaded: number;
+    /** `null` when loaded via `all`: no ceiling was applied. */
+    budgetTokens: number | null;
 } | {
     loaded: false;
     recordCount: number;
@@ -334,6 +335,12 @@ type KbWriteInput = {
     /** Replace an existing record rather than failing on the collision. */
     overwrite?: boolean;
 };
+type KbWriteResult = KbRecord & {
+    /** Whether this write also marked prior records superseded. */
+    action: "created" | "superseded-prior";
+    /** `frontmatter.strauss_supersedes` ids that were actually marked. */
+    supersededIds: string[];
+};
 /**
  * Reads and writes a knowledge bundle.
  *
@@ -357,7 +364,7 @@ declare class KbStore {
      * concept id, so a caller cannot produce a file whose identity disagrees with
      * its contents.
      */
-    write(bundlePath: string, input: KbWriteInput, actor?: string): Promise<KbRecord>;
+    write(bundlePath: string, input: KbWriteInput, actor?: string): Promise<KbWriteResult>;
     /** One record by concept id, or null when it does not exist. */
     read(bundlePath: string, conceptId: string): Promise<KbRecord | null>;
     /**
@@ -424,10 +431,15 @@ declare class KbStore {
      * 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.
+     *
+     * That refusal is the default guardrail. `all` bypasses it outright and
+     * always hands back the whole bundle: an explicit, never-accidental escape
+     * hatch for an operator who has the budget to spend, not a wider default.
      */
     load(bundlePath: string, options?: {
         budgetTokens?: number;
         type?: string;
+        all?: boolean;
     }): Promise<KbLoadResult>;
     /** How a position was arrived at, as a timeline. See `trace.ts`. */
     trace(bundlePath: string, seedId: string, options?: KbTraceOptions): Promise<KbTraceStep[]>;
@@ -447,6 +459,19 @@ declare class KbStore {
      * knows which agent touched what. So a bad line is surfaced and left alone.
      */
     readLog(bundlePath: string): Promise<ReturnType<typeof parseLog>>;
+    /**
+     * `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.
+     */
+    private markSupersededRetrying;
+    /** The one-directional half of `supersede`: marks `conceptId` superseded. */
+    private markSuperseded;
     private mutate;
     /**
      * Two guarantees, both about writers running in parallel.

package/dist/index.d.ts

@@ -318,8 +318,9 @@ type KbLoadResult = {
     /** Named only. Their bodies are reachable through `trace`. */
     superseded: KbSupersededStub[];
     recordCount: number;
-    approxTokens: number;
-    budgetTokens: number;
+    tokensLoaded: number;
+    /** `null` when loaded via `all`: no ceiling was applied. */
+    budgetTokens: number | null;
 } | {
     loaded: false;
     recordCount: number;
@@ -334,6 +335,12 @@ type KbWriteInput = {
     /** Replace an existing record rather than failing on the collision. */
     overwrite?: boolean;
 };
+type KbWriteResult = KbRecord & {
+    /** Whether this write also marked prior records superseded. */
+    action: "created" | "superseded-prior";
+    /** `frontmatter.strauss_supersedes` ids that were actually marked. */
+    supersededIds: string[];
+};
 /**
  * Reads and writes a knowledge bundle.
  *
@@ -357,7 +364,7 @@ declare class KbStore {
      * concept id, so a caller cannot produce a file whose identity disagrees with
      * its contents.
      */
-    write(bundlePath: string, input: KbWriteInput, actor?: string): Promise<KbRecord>;
+    write(bundlePath: string, input: KbWriteInput, actor?: string): Promise<KbWriteResult>;
     /** One record by concept id, or null when it does not exist. */
     read(bundlePath: string, conceptId: string): Promise<KbRecord | null>;
     /**
@@ -424,10 +431,15 @@ declare class KbStore {
      * 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.
+     *
+     * That refusal is the default guardrail. `all` bypasses it outright and
+     * always hands back the whole bundle: an explicit, never-accidental escape
+     * hatch for an operator who has the budget to spend, not a wider default.
      */
     load(bundlePath: string, options?: {
         budgetTokens?: number;
         type?: string;
+        all?: boolean;
     }): Promise<KbLoadResult>;
     /** How a position was arrived at, as a timeline. See `trace.ts`. */
     trace(bundlePath: string, seedId: string, options?: KbTraceOptions): Promise<KbTraceStep[]>;
@@ -447,6 +459,19 @@ declare class KbStore {
      * knows which agent touched what. So a bad line is surfaced and left alone.
      */
     readLog(bundlePath: string): Promise<ReturnType<typeof parseLog>>;
+    /**
+     * `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.
+     */
+    private markSupersededRetrying;
+    /** The one-directional half of `supersede`: marks `conceptId` superseded. */
+    private markSuperseded;
     private mutate;
     /**
      * Two guarantees, both about writers running in parallel.

package/dist/index.js

@@ -1,10 +1,10 @@
 import {
   runKbCli
-} from "./chunk-QLTB77W4.js";
+} from "./chunk-KQMGKSPZ.js";
 import {
   createKbMcpServer,
   runKbMcpServer
-} from "./chunk-FSI4Q2FD.js";
+} from "./chunk-VOJ6D6OX.js";
 import {
   BaseError,
   CONTEXT_BEGIN,
@@ -80,7 +80,7 @@ import {
   trace,
   unpinBase,
   validateBundle
-} from "./chunk-HYNAEAPM.js";
+} from "./chunk-FZIMFPGR.js";
 
 // src/match-diff.ts
 function matchToDiff(files, records, options = {}) {

package/dist/mcp-main.cjs

@@ -214,7 +214,7 @@ var composeInputSchema = import_zod2.z.object({
   /** Concept ids this record relates to; rendered as body links. */
   relatedConceptIds: import_zod2.z.array(kbConceptIdSchema).optional(),
   /** Concept ids this record replaces. The store settles the backlinks. */
-  supersedes: import_zod2.z.array(kbConceptIdSchema).optional(),
+  supersedes: import_zod2.z.array(kbConceptIdSchema).max(32).optional(),
   materiality: import_zod2.z.enum(KB_MATERIALITIES).optional(),
   confidence: import_zod2.z.enum(KB_CONFIDENCES).optional(),
   owner: import_zod2.z.string().min(1).optional()
@@ -1074,25 +1074,32 @@ var import_zod9 = require("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.",
+  usage: "load [type] [--budget N | --all]",
+  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.\n\nThat refusal is the default guardrail, meant for an agent that would otherwise burn its whole context on one call. `all` bypasses it and loads everything regardless of size: a deliberate operator with the budget to spend, not something to reach for automatically. It is mutually exclusive with `budgetTokens`. When the reader does not need everything, kb_query or a narrower `type` filter is the better fit than either.",
   input: import_zod9.z.object({
     bundlePath,
     type: import_zod9.z.enum(KB_RECORD_TYPES).optional(),
-    budgetTokens: import_zod9.z.number().int().positive().optional().describe("Approximate token ceiling. Defaults to 25000.")
+    budgetTokens: import_zod9.z.number().int().positive().optional().describe("Approximate token ceiling. Defaults to 25000."),
+    all: import_zod9.z.boolean().optional().describe(
+      "Load the entire base regardless of size. The deliberate-operator escape hatch; mutually exclusive with budgetTokens."
+    )
+  }).refine((value) => !(value.all && value.budgetTokens !== void 0), {
+    message: "all and budgetTokens are mutually exclusive: pass a ceiling or none, not both."
   }),
   fromArgv: (argv, path) => {
     const budget = argvFlag(argv, "--budget");
     return {
       bundlePath: path,
-      ...argv[1] && argv[1] !== "--budget" ? { type: argv[1] } : {},
-      ...budget ? { budgetTokens: Number(budget) } : {}
+      ...argv[1] && !argv[1].startsWith("--") ? { type: argv[1] } : {},
+      ...budget ? { budgetTokens: Number(budget) } : {},
+      ...argv.includes("--all") ? { all: true } : {}
     };
   },
-  run: async ({ store }, { bundlePath: path, type, budgetTokens }) => {
+  run: async ({ store }, { bundlePath: path, type, budgetTokens, all }) => {
     const result = await store.load(path, {
       ...type ? { type } : {},
-      ...budgetTokens ? { budgetTokens } : {}
+      ...budgetTokens ? { budgetTokens } : {},
+      ...all ? { all } : {}
     });
     if (!result.loaded) return result;
     return {
@@ -1602,7 +1609,11 @@ var writeCommand = define({
       composeRecord(type, input, actor, now()),
       actor
     );
-    return { conceptId: record.conceptId };
+    return {
+      conceptId: record.conceptId,
+      action: record.action,
+      supersededIds: record.supersededIds
+    };
   }
 });
 
@@ -1632,7 +1643,11 @@ var writeDecisionCommand = define({
       composeDecisionRecord(input, actor, now()),
       actor
     );
-    return { conceptId: record.conceptId };
+    return {
+      conceptId: record.conceptId,
+      action: record.action,
+      supersededIds: record.supersededIds
+    };
   }
 });
 
@@ -1723,7 +1738,7 @@ var KbRecordAlreadyExistsError = class extends BaseError {
       fault: "User" /* User */,
       retriable: false,
       reportToUser: true,
-      details: { conceptId: conceptId2 }
+      details: { conceptId: conceptId2, action: "refused" }
     });
     this.conceptId = conceptId2;
   }
@@ -1903,13 +1918,27 @@ var KbStore = class {
       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 };
+    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) {
@@ -1973,15 +2002,11 @@ var KbStore = class {
   async supersede(bundlePath2, conceptId2, replacementId, actor = "unknown") {
     const replacement = await this.read(bundlePath2, replacementId);
     if (!replacement) throw new KbRecordNotFoundError(replacementId);
-    const superseded = await this.mutate(
+    const superseded = await this.markSuperseded(
       bundlePath2,
       conceptId2,
-      (frontmatter) => ({
-        ...frontmatter,
-        strauss_status: "superseded",
-        strauss_superseded_by: replacementId
-      }),
-      { operation: "supersede", by: actor, target: replacementId }
+      replacementId,
+      actor
     );
     await this.mutate(
       bundlePath2,
@@ -2070,6 +2095,10 @@ ${answer}
    * 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.
+   *
+   * That refusal is the default guardrail. `all` bypasses it outright and
+   * always hands back the whole bundle: an explicit, never-accidental escape
+   * hatch for an operator who has the budget to spend, not a wider default.
    */
   async load(bundlePath2, options = {}) {
     const budgetTokens = options.budgetTokens ?? DEFAULT_LOAD_BUDGET;
@@ -2079,7 +2108,7 @@ ${answer}
     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) {
+    if (!options.all && approxTokens2 > budgetTokens) {
       return {
         loaded: false,
         recordCount: wanted.length,
@@ -2090,8 +2119,8 @@ ${answer}
     return {
       loaded: true,
       recordCount: wanted.length,
-      approxTokens: approxTokens2,
-      budgetTokens,
+      tokensLoaded: approxTokens2,
+      budgetTokens: options.all ? null : budgetTokens,
       records,
       superseded
     };
@@ -2145,6 +2174,42 @@ ${answer}
     }
     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 (0, import_promises4.readFile)(target, "utf8").catch(() => null);