@saasontools/strauss-kb 0.1.3 → 0.1.5

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.
@@ -172,7 +196,7 @@ strauss-kb [--bundle PATH] <command> [args]
   status <concept-id> <status>             Move a record's status, compare-and-swap.
   supersede <concept-id> <replacement-id>  Mark a record superseded, linking both directions.
   answer <concept-id> <answer...>          Resolve an open question and append the answer.
-  load [type] [--budget N]                 Hand over the whole base, each record with its standing.
+  load [type] [--budget N | --all]         Hand over the whole base, each record with its standing.
   query <text...>                          Search; every match arrives flagged with its standing.
   trace <concept-id> [edges...]            How a position was arrived at, as a timeline.
   list [type]                              Every record, optionally narrowed to one type.
@@ -299,6 +323,17 @@ by default). Superseded records come back as name, replacement and date only —
 their bodies no longer hold, and a body read later in a long session outlives
 the qualifier that said so. `trace` still reaches them by id.
 
+`--all` (`all: true` over MCP) is the escape hatch: it bypasses the refusal
+outright and hands back the entire bundle whatever its size. A loaded result
+carries `tokensLoaded`, the same estimate the budget is held against, and
+`budgetTokens: null` marks that no ceiling was applied; `--all` is mutually
+exclusive with `--budget`. That refusal is the guardrail an agent needs so a
+wide base does not silently consume its whole context; `--all` is for a
+deliberate operator who has decided the size is worth the tokens, not a
+setting to reach for by default. A reader that does not actually need every
+record is better served by a narrower `type` filter or a `query` than by
+turning the guardrail off.
+
 **Flag, never filter.** `query` returns every hit with its standing, because a
 filtered result set is invisible — the caller cannot tell it missed anything.
 The single exception is narrow: a superseded record is dropped only when its

package/dist/{chunk-HYNAEAPM.js → chunk-FZIMFPGR.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()
@@ -1198,25 +1198,32 @@ 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.",
+  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: z11.object({
     bundlePath,
     type: z11.enum(KB_RECORD_TYPES).optional(),
-    budgetTokens: z11.number().int().positive().optional().describe("Approximate token ceiling. Defaults to 25000.")
+    budgetTokens: z11.number().int().positive().optional().describe("Approximate token ceiling. Defaults to 25000."),
+    all: z11.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 {
@@ -1561,7 +1568,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 +1602,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 +1705,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 +1897,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 +1981,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,
@@ -2049,6 +2074,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;
@@ -2058,7 +2087,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,
@@ -2069,8 +2098,8 @@ ${answer}
     return {
       loaded: true,
       recordCount: wanted.length,
-      approxTokens: approxTokens2,
-      budgetTokens,
+      tokensLoaded: approxTokens2,
+      budgetTokens: options.all ? null : budgetTokens,
       records,
       superseded
     };
@@ -2124,6 +2153,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 +2385,4 @@ export {
   KB_DIR,
   KbStore
 };
-//# sourceMappingURL=chunk-HYNAEAPM.js.map
+//# sourceMappingURL=chunk-FZIMFPGR.js.map