@saasontools/strauss-kb 0.1.3 → 0.1.4

package/README.md

@@ -151,7 +151,31 @@ before publishing, which narrows the lost-update window rather than closing it.
 [ARCHITECTURE.md](./ARCHITECTURE.md) says why a lock was rejected.
 
 `supersede` writes both directions, so a backlink cannot drift in normal use and
-`validate` drops to catching hand-edits.
+`validate` drops to catching hand-edits. A `write` (or `write-decision`) that
+carries `supersedes` does the same: the new record publishes first, then each
+prior record it names is marked superseded in turn — a crash between the two
+leaves an old record with no backlink, which `validate` already reports as
+"is not marked superseded", never a silent drift. A `supersedes` id naming a
+record that does not exist yet is legal and does not fail the write; `validate`
+is what reports a target that never resolves. A `supersedes` id naming the
+record's own concept id is a no-op rather than an error, duplicate ids mark
+once, and the array is capped at 32 entries.
+
+A concurrent writer marking the same target races the compare-and-swap check;
+that's retried a few times before giving up, and giving up is reported the
+same way as a target that doesn't exist yet — left out of `supersededIds` for
+`validate` to catch, not thrown, since the calling record is already
+published by that point. If two different records both name the same target
+in `supersedes`, the target's backlink points at whichever wrote last;
+`validate` doesn't see this as a problem because the target genuinely is
+superseded, but `kb_query`/`kb_load`'s adjudication surfaces the resulting
+fork as a warning at read time.
+
+`kb_write` and `kb_write_decision` return
+`{ conceptId, action: "created" | "superseded-prior", supersededIds }` —
+`supersededIds` is only the ids actually marked, not every id the input named.
+A 409 from a concept-id collision carries `action: "refused"` in its `details`,
+alongside the `conceptId`.
 
 Records are never deleted. Superseding keeps the earlier reasoning inspectable,
 which is what a later `trace` reads.

package/dist/{chunk-HYNAEAPM.js → chunk-EDH43Z7J.js}

@@ -180,7 +180,7 @@ var composeInputSchema = z2.object({
   /** 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).optional(),
+  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()
@@ -1561,7 +1561,11 @@ var writeCommand = define({
       composeRecord(type, input, actor, now()),
       actor
     );
-    return { conceptId: record.conceptId };
+    return {
+      conceptId: record.conceptId,
+      action: record.action,
+      supersededIds: record.supersededIds
+    };
   }
 });
 
@@ -1591,7 +1595,11 @@ var writeDecisionCommand = define({
       composeDecisionRecord(input, actor, now()),
       actor
     );
-    return { conceptId: record.conceptId };
+    return {
+      conceptId: record.conceptId,
+      action: record.action,
+      supersededIds: record.supersededIds
+    };
   }
 });
 
@@ -1690,7 +1698,7 @@ var KbRecordAlreadyExistsError = class extends BaseError {
       fault: "User" /* User */,
       retriable: false,
       reportToUser: true,
-      details: { conceptId: conceptId2 }
+      details: { conceptId: conceptId2, action: "refused" }
     });
     this.conceptId = conceptId2;
   }
@@ -1882,13 +1890,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) {
@@ -1952,15 +1974,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,
@@ -2124,6 +2142,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 readFile3(target, "utf8").catch(() => null);
@@ -2320,4 +2374,4 @@ export {
   KB_DIR,
   KbStore
 };
-//# sourceMappingURL=chunk-HYNAEAPM.js.map
+//# sourceMappingURL=chunk-EDH43Z7J.js.map