@saasontools/strauss-kb 0.1.3 → 0.1.4

package/dist/index.d.cts

@@ -334,6 +334,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 +363,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>;
     /**
@@ -447,6 +453,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

@@ -334,6 +334,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 +363,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>;
     /**
@@ -447,6 +453,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-Y5C7Z2HG.js";
 import {
   createKbMcpServer,
   runKbMcpServer
-} from "./chunk-FSI4Q2FD.js";
+} from "./chunk-TS26G7TL.js";
 import {
   BaseError,
   CONTEXT_BEGIN,
@@ -80,7 +80,7 @@ import {
   trace,
   unpinBase,
   validateBundle
-} from "./chunk-HYNAEAPM.js";
+} from "./chunk-EDH43Z7J.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()
@@ -1602,7 +1602,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 +1636,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 +1731,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 +1911,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 +1995,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,
@@ -2145,6 +2163,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);