@saasontools/strauss-kb 0.1.11 → 0.1.12

package/README.md

@@ -534,6 +534,14 @@ fact; a missing replacement is `broken-chain` with no head — the case that nee
 the most care, because returning the stale record unmarked looks exactly like
 success.
 
+**Placement is cache economics.** `load`'s output belongs in the stable
+prefix — system prompt or first turn; `query` and `pack` results belong at
+the tail. `digest` is the base's content stamp: a change-notification hook
+and `kb_stamp` (SAA-719) compare it to detect change, not the model. A
+prompt cache matches a byte-for-byte prefix, so one volatile result ahead of
+a stable load prices the base at full rate thereafter. Mechanism and digest
+caveats: <https://saasontools.github.io/strauss-agent-tools/mcp-reference>.
+
 ## Health
 
 `doctor` sweeps a whole base and reports what has decayed. It is read-only —

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

@@ -2562,7 +2562,7 @@ 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 (name, replacement, date); rejected and open records arrive whole. Refuses past the token budget rather than truncating \u2014 call kb_catalog, then kb_pack on the record that matters, or narrow with `type`; kb_query for a lookup by wording. `all` bypasses the budget.",
+  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({
     bundlePath,
     type: z14.enum(KB_RECORD_TYPES).optional(),
@@ -2805,7 +2805,7 @@ var queryCommand = define({
   name: "query",
   tool: "kb_query",
   usage: "query <text...> [--repo-root PATH]",
-  description: "Search and return each match with its standing. Results are flagged, never filtered: a superseded record comes back alongside whatever replaced it, and a rejected one is marked as something explicitly not adopted. This is the lookup-by-wording rung, and the narrowest of the three: use it when you know roughly what the record says. The decision rule around it \u2014 while the base fits kb_load's token budget, kb_load it whole, because on this package's measurements a reader holding the whole base answered eight of nine questions whose wording appears in no record where embedding search answered four; once kb_load refuses, kb_catalog for one line per record and then kb_pack on the record the work centres on; and kb_query when the question is a point lookup rather than a neighbourhood. A query cannot tell you that nothing was decided \u2014 it returns its nearest hit whatever the distance \u2014 so reach for kb_catalog when the question is what exists. Never read record files directly: this tool (with kb_load, kb_catalog, kb_pack and kb_trace) is the only supported way to read a base; a file read bypasses supersession resolution and returns replaced records as if current.",
+  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({
     bundlePath,
     text: z20.string().optional(),
@@ -3642,6 +3642,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);
+    const bundleDigestValue = bundleDigest(records, superseded);
     if (!options.all && approxTokens2 > budgetTokens) {
       return {
         loaded: false,
@@ -3652,7 +3653,8 @@ ${answer}
           approxTokens: approxTokens2,
           budgetTokens,
           type: options.type
-        })
+        }),
+        digest: bundleDigestValue
       };
     }
     return {
@@ -3661,7 +3663,8 @@ ${answer}
       tokensLoaded: approxTokens2,
       budgetTokens: options.all ? null : budgetTokens,
       records,
-      superseded
+      superseded,
+      digest: bundleDigestValue
     };
   }
   /** How a position was arrived at, as a timeline. See `trace.ts`. */
@@ -3978,6 +3981,22 @@ function normalizeActor(id) {
 function digest(contents) {
   return createHash2("sha256").update(contents).digest("hex");
 }
+function bundleDigest(records, superseded) {
+  const entries = [
+    ...records.map(
+      (hit) => `${hit.record.conceptId}:current:${digest(
+        stringifyMarkdownWithFrontmatter(
+          hit.record.body,
+          hit.record.frontmatter
+        )
+      )}`
+    ),
+    ...superseded.map(
+      (entry) => `${entry.conceptId}:superseded:${digest(JSON.stringify(entry))}`
+    )
+  ].sort();
+  return digest(entries.join("\n"));
+}
 
 // src/pack.ts
 var DEFAULT_PACK_HOPS = 2;
@@ -4064,7 +4083,7 @@ function typeRank(record) {
 }
 
 // src/version.ts
-var VERSION = true ? "0.1.11" : "0.0.0-dev";
+var VERSION = true ? "0.1.12" : "0.0.0-dev";
 
 export {
   kbSourceSchema,
@@ -4166,4 +4185,4 @@ export {
   KbStore,
   VERSION
 };
-//# sourceMappingURL=chunk-OVRQCQ6P.js.map
+//# sourceMappingURL=chunk-33ZCBEUV.js.map