@saasontools/strauss-kb 0.1.4 → 0.1.6

package/README.md

@@ -88,6 +88,24 @@ concepts. `type` is the only key OKF requires; `title`, `description`,
 OKF's. Unknown keys are preserved rather than stripped, as OKF requires of
 consumers.
 
+`verified` is the record's append-only trail of checks. Each entry is OKF's
+actor stamp — `{ by, at }` — and the entries this package's `verify` writes add
+a `note`: what the check actually found, not just that one happened. The `note`
+is a strauss extension key on the entries this tool writes, not an OKF
+requirement on the array, so noteless entries a foreign producer wrote remain
+readable, and prior entries are spread forward untouched rather than reshaped.
+
+Who may append is the point. A verifier whose actor equals the record's
+`generated.by` — compared case-insensitively over the whole actor, so case
+drift cannot mint a distinct verifier identity — is refused unless the actor
+is `human:`-prefixed: trust that can be self-granted is not trust, and a
+generator re-reading its own output is not an independent check. The refusal
+is recorded in the log as `verify:refused`, so an audit sees the attempt as
+well as the rule. The `human:` prefix itself is an honor-system label — actor
+identity is self-declared through `STRAUSS_KB_ACTOR`, not an authenticated
+identity claim — which is worth knowing when deciding how much weight a
+human-verified event carries.
+
 Anything prefixed `strauss_` is this package's extension, namespaced so a later
 OKF version defining the same name cannot collide:
 
@@ -196,7 +214,8 @@ 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.
+  verify <concept-id> --note <text>        Append a verified[] event — who checked, when, and what the check found.
+  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.
@@ -239,8 +258,8 @@ strauss-kb validate || echo "problems above"
 
 `strauss-kb-mcp` speaks stdio and takes no API key and no required environment.
 Every CLI verb is a tool: `kb_write`, `kb_write_decision`, `kb_no_decision`,
-`kb_status`, `kb_supersede`, `kb_answer`, `kb_load`, `kb_query`, `kb_trace`,
-`kb_list`, `kb_index`, `kb_log`, `kb_validate`, `kb_schema`, `kb_types`,
+`kb_status`, `kb_supersede`, `kb_answer`, `kb_verify`, `kb_load`, `kb_query`,
+`kb_trace`, `kb_list`, `kb_index`, `kb_log`, `kb_validate`, `kb_schema`, `kb_types`,
 `kb_pin`, `kb_unpin`, `kb_pins`, `kb_context`. Most tools take a `bundlePath`;
 `kb_schema` and `kb_types` describe the format rather than any one base, and
 `kb_pins` and `kb_context` read the workspace pin manifests instead. The one
@@ -299,6 +318,15 @@ problem:
 | Standing  | `strauss_status`, the supersession chain                | is this still what we hold?     |
 | Freshness | `stale_after`, `verified[]`                             | has anyone confirmed it lately? |
 
+Freshness is tiered by who did the confirming. OKF's spec (§5.3) defines the
+trust tiers from the verifying actor's prefix: an empty `verified[]` is
+unverified, an agent-prefixed verifier makes the record machine-confirmed, and
+a `human:`-prefixed verifier makes it human-reviewed. Of that ladder, today's
+adjudication reports only the first rung — the warning it attaches when
+`verified[]` is empty; reporting the full tier is upcoming tooling. When it
+lands, the tier will be derived from the events at read time, never stored, so
+it cannot drift from the trail that justifies it.
+
 **Load before you search.** These bases run to a few thousand tokens — twenty
 records measured at about 3,000 — so the first thing to try is taking all of it.
 On nine questions whose wording appears in no record, a reader holding the whole
@@ -323,6 +351,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-TS26G7TL.js → chunk-BVF7X5VO.js}

@@ -1,7 +1,7 @@
 import {
   KB_COMMANDS,
   KbStore
-} from "./chunk-EDH43Z7J.js";
+} from "./chunk-PNSRTKYN.js";
 
 // src/mcp.ts
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
@@ -45,4 +45,4 @@ export {
   createKbMcpServer,
   runKbMcpServer
 };
-//# sourceMappingURL=chunk-TS26G7TL.js.map
+//# sourceMappingURL=chunk-BVF7X5VO.js.map

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

@@ -11,6 +11,11 @@ var kbActorStampSchema = z.object({
   by: z.string().min(1),
   at: z.string().min(1)
 }).passthrough();
+var kbVerifiedEventSchema = kbActorStampSchema.extend({
+  note: z.string().refine((s) => s.trim().length > 0, {
+    message: "note must say what the check found"
+  })
+});
 var kbAnchorSchema = z.object({
   file: z.string().min(1),
   symbol: z.string().min(1).optional()
@@ -1198,25 +1203,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 {
@@ -1529,8 +1541,37 @@ var validateCommand = define({
   failsWhen: (result) => Array.isArray(result) && result.length > 0
 });
 
-// src/commands/write.ts
+// src/commands/verify.ts
 import { z as z26 } from "zod";
+var verifyCommand = define({
+  name: "verify",
+  tool: "kb_verify",
+  usage: "verify <concept-id> --note <text>",
+  description: "Append one verified[] event \u2014 who checked the record, when, and what the check found. Appends only; prior events are never rewritten. A record's own generator is refused unless the actor is human: re-reading your own output is not an independent check.",
+  input: z26.object({
+    bundlePath,
+    conceptId,
+    note: z26.string().refine((s) => s.trim().length > 0, {
+      message: "note must say what the check found"
+    })
+  }),
+  fromArgv: (argv, path) => ({
+    bundlePath: path,
+    conceptId: argv[1],
+    note: argvFlag(argv, "--note")
+  }),
+  run: async ({ store, actor, now }, { bundlePath: path, conceptId: id, note }) => {
+    await assertBaseNotFrozen(process.cwd(), path);
+    const record = await store.verify(path, id, note, actor, now());
+    return {
+      conceptId: record.conceptId,
+      verified: record.frontmatter.verified?.length ?? 0
+    };
+  }
+});
+
+// src/commands/write.ts
+import { z as z27 } from "zod";
 var writeCommand = define({
   name: "write",
   tool: "kb_write",
@@ -1544,9 +1585,9 @@ var writeCommand = define({
     "- Prefer a new record over overloading an existing one, and keep each short. A record nobody finishes reading is not durable memory.",
     "- Records are never deleted; supersede instead, so the earlier reasoning stays inspectable."
   ].join("\n"),
-  input: z26.object({
+  input: z27.object({
     bundlePath,
-    type: z26.enum(KB_RECORD_TYPES),
+    type: z27.enum(KB_RECORD_TYPES),
     input: composeInputSchema
   }),
   fromArgv: async (argv, path, stdin) => ({
@@ -1570,7 +1611,7 @@ var writeCommand = define({
 });
 
 // src/commands/write-decision.ts
-import { z as z27 } from "zod";
+import { z as z28 } from "zod";
 var writeDecisionCommand = define({
   name: "write-decision",
   tool: "kb_write_decision",
@@ -1583,7 +1624,7 @@ var writeDecisionCommand = define({
     "- `alternative` is what you turned down and why, not a list of everything considered.",
     "- A reference to material you read goes in `sources`; a reference to code goes in `anchors`; a reference to another record goes in `relatedConceptIds`."
   ].join("\n"),
-  input: z27.object({ bundlePath, input: decisionInputSchema }),
+  input: z28.object({ bundlePath, input: decisionInputSchema }),
   fromArgv: async (_argv, path, stdin) => ({
     bundlePath: path,
     input: JSON.parse(await stdin())
@@ -1611,6 +1652,7 @@ var KB_COMMANDS = [
   statusCommand,
   supersedeCommand,
   answerCommand,
+  verifyCommand,
   loadCommand,
   queryCommand,
   traceCommand,
@@ -1666,6 +1708,7 @@ var ErrorTypes = /* @__PURE__ */ ((ErrorTypes2) => {
   ErrorTypes2["KbRecordAlreadyExists"] = "KbRecordAlreadyExists";
   ErrorTypes2["KbInvalidConceptId"] = "KbInvalidConceptId";
   ErrorTypes2["KbRecordNotFound"] = "KbRecordNotFound";
+  ErrorTypes2["KbSelfVerification"] = "KbSelfVerification";
   ErrorTypes2["KbWriteConflict"] = "KbWriteConflict";
   return ErrorTypes2;
 })(ErrorTypes || {});
@@ -1734,6 +1777,25 @@ var KbWriteConflictError = class extends BaseError {
   }
   conceptId;
 };
+var KbSelfVerificationError = class extends BaseError {
+  constructor(conceptId2, actor, generatedBy) {
+    super({
+      message: `kb: ${conceptId2} was generated by ${generatedBy}, and a record's generator cannot verify it \u2014 only a human or a different actor can`,
+      errorType: "KbSelfVerification" /* KbSelfVerification */,
+      code: 400,
+      fault: "User" /* User */,
+      retriable: false,
+      reportToUser: true,
+      details: { conceptId: conceptId2, actor, generatedBy, action: "refused" }
+    });
+    this.conceptId = conceptId2;
+    this.actor = actor;
+    this.generatedBy = generatedBy;
+  }
+  conceptId;
+  actor;
+  generatedBy;
+};
 var KbInvalidConceptIdError = class extends BaseError {
   constructor(message, details) {
     super({
@@ -1964,6 +2026,40 @@ var KbStore = class {
       { operation: `status:${status}`, by: actor }
     );
   }
+  /**
+   * Appends one `verified[]` event: who checked the record, when, and what the
+   * check found. Append-only — prior events are history, and are spread into
+   * the new array untouched rather than reshaped through the write schema.
+   *
+   * A record's generator cannot verify its own record unless the actor is
+   * human: the generator re-reading its own output is not an independent
+   * check. The rule runs before the mutation so a refusal never publishes,
+   * and the refusal is logged under its own operation name — `mutate` only
+   * logs what it publishes.
+   */
+  async verify(bundlePath2, conceptId2, note, actor = "unknown", at = (/* @__PURE__ */ new Date()).toISOString()) {
+    const event = kbVerifiedEventSchema.parse({ by: actor, at, note });
+    const existing = await this.read(bundlePath2, conceptId2);
+    if (!existing) throw new KbRecordNotFoundError(conceptId2);
+    const generatedBy = existing.frontmatter.generated?.by;
+    if (generatedBy !== void 0 && actor.toLowerCase() === generatedBy.toLowerCase() && !normalizeActor(actor).startsWith("human:")) {
+      await this.record(this.root(bundlePath2), {
+        operation: "verify:refused",
+        conceptId: conceptId2,
+        by: actor
+      });
+      throw new KbSelfVerificationError(conceptId2, actor, generatedBy);
+    }
+    return this.mutate(
+      bundlePath2,
+      conceptId2,
+      (frontmatter) => ({
+        ...frontmatter,
+        verified: [...frontmatter.verified ?? [], event]
+      }),
+      { operation: "verify", by: actor }
+    );
+  }
   /**
    * Marks `conceptId` superseded by `replacementId`, and links both directions.
    *
@@ -2067,6 +2163,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;
@@ -2076,7 +2176,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,
@@ -2087,8 +2187,8 @@ ${answer}
     return {
       loaded: true,
       recordCount: wanted.length,
-      approxTokens: approxTokens2,
-      budgetTokens,
+      tokensLoaded: approxTokens2,
+      budgetTokens: options.all ? null : budgetTokens,
       records,
       superseded
     };
@@ -2294,6 +2394,11 @@ function matches(record, needle) {
     (field) => field?.toLowerCase().includes(needle)
   );
 }
+function normalizeActor(id) {
+  const colon = id.indexOf(":");
+  if (colon === -1) return id.toLowerCase();
+  return id.slice(0, colon + 1).toLowerCase() + id.slice(colon + 1);
+}
 function digest(contents) {
   return createHash("sha256").update(contents).digest("hex");
 }
@@ -2301,6 +2406,7 @@ function digest(contents) {
 export {
   kbSourceSchema,
   kbActorStampSchema,
+  kbVerifiedEventSchema,
   kbAnchorSchema,
   KB_RECORD_TYPES,
   KB_SLUG_PATTERN,
@@ -2366,6 +2472,7 @@ export {
   KbRecordAlreadyExistsError,
   KbRecordNotFoundError,
   KbWriteConflictError,
+  KbSelfVerificationError,
   KbInvalidConceptIdError,
   SEARCH_INDEX_FILE,
   searchBase,
@@ -2374,4 +2481,4 @@ export {
   KB_DIR,
   KbStore
 };
-//# sourceMappingURL=chunk-EDH43Z7J.js.map
+//# sourceMappingURL=chunk-PNSRTKYN.js.map