@saasontools/strauss-kb 0.1.5 → 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,6 +214,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.
+  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.
@@ -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

package/dist/{chunk-VOJ6D6OX.js → chunk-BVF7X5VO.js}

@@ -1,7 +1,7 @@
 import {
   KB_COMMANDS,
   KbStore
-} from "./chunk-FZIMFPGR.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-VOJ6D6OX.js.map
+//# sourceMappingURL=chunk-BVF7X5VO.js.map

package/dist/{chunk-FZIMFPGR.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()
@@ -1536,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",
@@ -1551,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) => ({
@@ -1577,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",
@@ -1590,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())
@@ -1618,6 +1652,7 @@ var KB_COMMANDS = [
   statusCommand,
   supersedeCommand,
   answerCommand,
+  verifyCommand,
   loadCommand,
   queryCommand,
   traceCommand,
@@ -1673,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 || {});
@@ -1741,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({
@@ -1971,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.
    *
@@ -2305,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");
 }
@@ -2312,6 +2406,7 @@ function digest(contents) {
 export {
   kbSourceSchema,
   kbActorStampSchema,
+  kbVerifiedEventSchema,
   kbAnchorSchema,
   KB_RECORD_TYPES,
   KB_SLUG_PATTERN,
@@ -2377,6 +2472,7 @@ export {
   KbRecordAlreadyExistsError,
   KbRecordNotFoundError,
   KbWriteConflictError,
+  KbSelfVerificationError,
   KbInvalidConceptIdError,
   SEARCH_INDEX_FILE,
   searchBase,
@@ -2385,4 +2481,4 @@ export {
   KB_DIR,
   KbStore
 };
-//# sourceMappingURL=chunk-FZIMFPGR.js.map
+//# sourceMappingURL=chunk-PNSRTKYN.js.map