@saasontools/strauss-kb 0.1.15 → 0.1.16

package/README.md

@@ -408,8 +408,8 @@ Worked flows:
 
 **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
+the tail. `digest` is the base's content stamp: `kb_stamp` and the opt-in
+reload hook 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>.
@@ -451,6 +451,11 @@ carry no numbers:
 }
 ```
 
+A pinned base can also change mid-session — a `git pull`, a sub-agent's write.
+`strauss-kb stamp` reports each pinned base's content digest. Comparing it for
+you is opt-in, see the
+[plugin README](../../plugins/strauss-kb/README.md#opt-in-workspace-hooks).
+
 `sync-instructions <file>` keeps that block between
 `<!-- strauss-kb:begin/end -->` sentinels in AGENTS.md or CLAUDE.md; it is
 idempotent, and covers runtimes without a reliable post-compaction hook.
@@ -458,15 +463,16 @@ idempotent, and covers runtimes without a reliable post-compaction hook.
 What each runtime gets (configs in the
 [plugin's adapters](../../plugins/strauss-kb/adapters/)):
 
-| Layer                     | Claude Code        | Codex CLI                                   | Antigravity CLI            |
-| ------------------------- | ------------------ | ------------------------------------------- | -------------------------- |
-| MCP tool descriptions     | ✓                  | ✓                                           | ✓                          |
-| Session-start injection   | SessionStart hook  | SessionStart hook                           | PreInvocation, per turn    |
-| Post-compact re-injection | ✓ `compact` source | ✓ client-side; instruction-only when hosted | moot — injected every turn |
-| File-read blocking        | opt-in PreToolUse  | ✗ (shell is the side door)                  | opt-in PreToolUse, JSON    |
-| Manual-edit validation    | opt-in PostToolUse | ✗                                           | ✗                          |
-| Generated-file edit guard | opt-in PreToolUse  | ✗                                           | ✗                          |
-| Instruction file          | CLAUDE.md          | AGENTS.md                                   | AGENTS.md + rules/         |
+| Layer                     | Claude Code                      | Codex CLI                                   | Antigravity CLI            |
+| ------------------------- | -------------------------------- | ------------------------------------------- | -------------------------- |
+| MCP tool descriptions     | ✓                                | ✓                                           | ✓                          |
+| Session-start injection   | SessionStart hook                | SessionStart hook                           | PreInvocation, per turn    |
+| Post-compact re-injection | ✓ `compact` source               | ✓ client-side; instruction-only when hosted | moot — injected every turn |
+| Reload after a pull       | opt-in PostToolUse, SubagentStop | opt-in PostToolUse on `shell`               | moot — injected every turn |
+| File-read blocking        | opt-in PreToolUse                | ✗ (shell is the side door)                  | opt-in PreToolUse, JSON    |
+| Manual-edit validation    | opt-in PostToolUse               | ✗                                           | ✗                          |
+| Generated-file edit guard | opt-in PreToolUse                | ✗                                           | ✗                          |
+| Instruction file          | CLAUDE.md                        | AGENTS.md                                   | AGENTS.md + rules/         |
 
 Never read record files directly — read through the tools; a raw read bypasses
 standing, and a superseded record reads exactly like a current one. Enforce it

package/dist/{chunk-KNIUBCZY.js → chunk-H5W53NVU.js}

@@ -1273,6 +1273,8 @@ var ErrorTypes = /* @__PURE__ */ ((ErrorTypes2) => {
   ErrorTypes2["KbPackBudgetExceeded"] = "KbPackBudgetExceeded";
   ErrorTypes2["KbRecordNotFound"] = "KbRecordNotFound";
   ErrorTypes2["KbSelfVerification"] = "KbSelfVerification";
+  ErrorTypes2["KbStampBaselineUnreadable"] = "KbStampBaselineUnreadable";
+  ErrorTypes2["KbStampDigestBaselineAmbiguous"] = "KbStampDigestBaselineAmbiguous";
   ErrorTypes2["KbUnknownLinkRel"] = "KbUnknownLinkRel";
   ErrorTypes2["KbWriteConflict"] = "KbWriteConflict";
   return ErrorTypes2;
@@ -1427,6 +1429,36 @@ var KbInvalidConceptIdError = class extends BaseError {
     });
   }
 };
+var KbStampBaselineError = class extends BaseError {
+  constructor(since) {
+    super({
+      message: `kb: --since ${since} is neither a 64-character digest nor a readable stamp file`,
+      errorType: "KbStampBaselineUnreadable" /* KbStampBaselineUnreadable */,
+      code: 400,
+      fault: "User" /* User */,
+      retriable: false,
+      reportToUser: true,
+      details: { since }
+    });
+    this.since = since;
+  }
+  since;
+};
+var KbStampDigestBaselineError = class extends BaseError {
+  constructor(since) {
+    super({
+      message: `kb: --since ${since} is a digest, which needs --bundle (one base) \u2014 a file baseline works for many`,
+      errorType: "KbStampDigestBaselineAmbiguous" /* KbStampDigestBaselineAmbiguous */,
+      code: 400,
+      fault: "User" /* User */,
+      retriable: false,
+      reportToUser: true,
+      details: { since }
+    });
+    this.since = since;
+  }
+  since;
+};
 
 // src/kb-pins/budgets.ts
 function asBudgets(value) {
@@ -3611,17 +3643,115 @@ var schemaCommand = define({
   run: () => Promise.resolve(kbJsonSchemas())
 });
 
-// src/commands/status.ts
+// src/commands/stamp.ts
+import { readFile as readFile4 } from "fs/promises";
 import { z as z25 } from "zod";
+var DIGEST = /^[0-9a-f]{64}$/;
+var stampCommand = define({
+  name: "stamp",
+  tool: "kb_stamp",
+  usage: "stamp [--bundle PATH] [--since DIGEST|FILE]",
+  description: "Content stamp of a base \u2014 `load`'s digest, record counts, per-record digests \u2014 without any bodies. Takes no bundlePath to stamp every pinned base. With `since`, reports only the bases that moved, naming the changed ids when the baseline is a prior stamp; silent when nothing changed. Reads, never writes.",
+  input: z25.object({
+    bundlePath: z25.string().min(1).optional().describe(
+      "Absolute path to one knowledge base. Omit to stamp every pinned base."
+    ),
+    since: z25.string().min(1).optional().describe(
+      "Prior digest, or path to a prior `stamp --json`; only moved bases return, with changed ids when the baseline is a file."
+    )
+  }),
+  fromArgv: (argv, path, _stdin, bundleExplicit) => {
+    const since = argvFlag(argv, "--since");
+    return {
+      ...bundleExplicit ? { bundlePath: path } : {},
+      ...since !== void 0 ? { since } : {}
+    };
+  },
+  run: async ({ store }, { bundlePath: bundlePath2, since }) => {
+    const targets = bundlePath2 ? [bundlePath2] : (await readMergedPins(process.cwd())).pins.map(
+      (pin) => pin.absolutePath
+    );
+    if (since !== void 0 && DIGEST.test(since) && targets.length > 1) {
+      throw new KbStampDigestBaselineError(since);
+    }
+    const stamps = await Promise.all(
+      targets.map((target) => store.stamp(target))
+    );
+    if (since === void 0) {
+      return stamps.map((stamp) => ({ ...stamp, changed: null }));
+    }
+    const baseline = await readBaseline(since);
+    const reports = [];
+    for (const stamp of stamps) {
+      const before = baseline.byPath.get(stamp.path);
+      if (baseline.digest !== null) {
+        if (baseline.digest === stamp.digest) continue;
+        reports.push({ ...stamp, changed: null });
+        continue;
+      }
+      if (before && before.digest === stamp.digest) continue;
+      reports.push({ ...stamp, changed: changedIds(before?.records, stamp) });
+    }
+    return reports;
+  },
+  render: (result) => result.map((report) => {
+    const counts = `${report.recordCount} record(s), ${report.superseded} superseded`;
+    const head = `${report.path}  ${report.digest}  ${counts}${report.newestAt ? `  newest ${report.newestAt}` : ""}`;
+    return report.changed?.length ? `${head}
+  changed: ${report.changed.join(", ")}` : head;
+  }).join("\n")
+});
+function changedIds(before, stamp) {
+  const now = new Map(
+    stamp.records.map((record) => [record.conceptId, record.digest])
+  );
+  const ids = /* @__PURE__ */ new Set();
+  for (const [conceptId2, digest] of now) {
+    if (before?.get(conceptId2) !== digest) ids.add(conceptId2);
+  }
+  for (const conceptId2 of before?.keys() ?? []) {
+    if (!now.has(conceptId2)) ids.add(conceptId2);
+  }
+  return [...ids].sort();
+}
+async function readBaseline(since) {
+  if (DIGEST.test(since)) return { digest: since, byPath: /* @__PURE__ */ new Map() };
+  let parsed;
+  try {
+    parsed = JSON.parse(await readFile4(since, "utf8"));
+  } catch {
+    throw new KbStampBaselineError(since);
+  }
+  const entries = Array.isArray(parsed) ? parsed : parsed?.stamps ?? [];
+  const byPath = /* @__PURE__ */ new Map();
+  for (const entry of entries) {
+    if (typeof entry?.path !== "string" || typeof entry?.digest !== "string") {
+      continue;
+    }
+    byPath.set(entry.path, {
+      digest: entry.digest,
+      records: new Map(
+        (entry.records ?? []).map((record) => [
+          record.conceptId,
+          record.digest
+        ])
+      )
+    });
+  }
+  return { digest: null, byPath };
+}
+
+// src/commands/status.ts
+import { z as z26 } from "zod";
 var statusCommand = define({
   name: "status",
   tool: "kb_status",
   usage: "status <concept-id> <status>",
   description: "Move a record's status. Compare-and-swap: a concurrent change fails instead of being overwritten.",
-  input: z25.object({
+  input: z26.object({
     bundlePath,
     conceptId,
-    status: z25.enum(KB_RECORD_STATUSES)
+    status: z26.enum(KB_RECORD_STATUSES)
   }),
   fromArgv: (argv, path) => ({
     bundlePath: path,
@@ -3636,13 +3766,13 @@ var statusCommand = define({
 });
 
 // src/commands/supersede.ts
-import { z as z26 } from "zod";
+import { z as z27 } from "zod";
 var supersedeCommand = define({
   name: "supersede",
   tool: "kb_supersede",
   usage: "supersede <concept-id> <replacement-id>",
   description: "Mark a record superseded by another, linked in both directions. Use instead of editing a record whose meaning changed.",
-  input: z26.object({ bundlePath, conceptId, replacementId: conceptId }),
+  input: z27.object({ bundlePath, conceptId, replacementId: conceptId }),
   fromArgv: (argv, path) => ({
     bundlePath: path,
     conceptId: argv[1],
@@ -3656,16 +3786,16 @@ var supersedeCommand = define({
 });
 
 // src/commands/sync-instructions.ts
-import { z as z27 } from "zod";
+import { z as z28 } from "zod";
 var syncInstructionsCommand = define({
   name: "sync-instructions",
   usage: "sync-instructions <file> [--profile NAME] [--budget N] [--full-under N]",
   description: "CLI-only: plant the kb_context block between sentinel comments in AGENTS.md or CLAUDE.md, idempotently.",
-  input: z27.object({
-    file: z27.string().min(1).describe("The instruction file to edit in place."),
-    budgetTokens: z27.number().int().positive().optional(),
-    fullUnderTokens: z27.number().int().positive().optional(),
-    profile: z27.string().optional()
+  input: z28.object({
+    file: z28.string().min(1).describe("The instruction file to edit in place."),
+    budgetTokens: z28.number().int().positive().optional(),
+    fullUnderTokens: z28.number().int().positive().optional(),
+    profile: z28.string().optional()
   }),
   fromArgv: (argv) => {
     const budget = argvFlag(argv, "--budget");
@@ -3691,17 +3821,17 @@ var syncInstructionsCommand = define({
 });
 
 // src/commands/trace.ts
-import { z as z28 } from "zod";
+import { z as z29 } from "zod";
 var traceCommand = define({
   name: "trace",
   tool: "kb_trace",
   usage: "trace <concept-id> [edges...]",
   description: 'Timeline of how a position was reached, ordered by write time, following supersession, shared anchors and shared sources. Includes rejected, draft and superseded records \u2014 in a history they are the content. For "why is it like this"; kb_load answers "what holds now".',
-  input: z28.object({
+  input: z29.object({
     bundlePath,
     conceptId,
-    edges: z28.array(z28.enum(TRACE_EDGES)).optional(),
-    depth: z28.number().int().positive().optional()
+    edges: z29.array(z29.enum(TRACE_EDGES)).optional(),
+    depth: z29.number().int().positive().optional()
   }),
   fromArgv: (argv, path) => ({
     bundlePath: path,
@@ -3723,37 +3853,37 @@ var traceCommand = define({
 });
 
 // src/commands/types.ts
-import { z as z29 } from "zod";
+import { z as z30 } from "zod";
 var typesCommand = define({
   name: "types",
   tool: "kb_types",
   usage: "types",
   description: "The twelve record types with their purpose, body sections, and starting status. Read this before writing rather than guessing headings \u2014 a section the type does not define is rejected.",
-  input: z29.object({}),
+  input: z30.object({}),
   fromArgv: () => ({}),
   run: () => Promise.resolve(RECORD_TYPES)
 });
 
 // src/commands/unpin.ts
-import { z as z30 } from "zod";
+import { z as z31 } from "zod";
 var unpinCommand = define({
   name: "unpin",
   tool: "kb_unpin",
   usage: "unpin [bundle-path]",
   description: "Remove a base from every manifest layer that holds it. Reports the layers touched.",
-  input: z30.object({ bundlePath }),
+  input: z31.object({ bundlePath }),
   fromArgv: (argv, path) => ({ bundlePath: argv[1] ?? path }),
   run: (_ctx, { bundlePath: path }) => unpinBase(process.cwd(), path)
 });
 
 // src/commands/validate.ts
-import { z as z31 } from "zod";
+import { z as z32 } from "zod";
 var validateCommand = define({
   name: "validate",
   tool: "kb_validate",
   usage: "validate",
   description: "Check pointers no single record can see: supersession links that disagree between the two records, typed causal links, and assumptions that cite sources. Each finding carries a severity: errors fail the exit code, warnings do not.",
-  input: z31.object({ bundlePath }),
+  input: z32.object({ bundlePath }),
   fromArgv: (_argv, path) => ({ bundlePath: path }),
   run: async ({ store }, { bundlePath: path }) => validateBundle(await store.list(path)),
   // Warnings never fail the exit code; every other severity does.
@@ -3763,16 +3893,16 @@ var validateCommand = define({
 });
 
 // src/commands/verify.ts
-import { z as z32 } from "zod";
+import { z as z33 } from "zod";
 var verifyCommand = define({
   name: "verify",
   tool: "kb_verify",
   usage: "verify <concept-id> --note <text>",
   description: "Append a verified[] event: who checked, when, and what was found. Append-only. A record's own generator is refused unless the actor is `human:`-prefixed.",
-  input: z32.object({
+  input: z33.object({
     bundlePath,
     conceptId,
-    note: z32.string().refine((s) => s.trim().length > 0, {
+    note: z33.string().refine((s) => s.trim().length > 0, {
       message: "note must say what the check found"
     })
   }),
@@ -3792,15 +3922,15 @@ var verifyCommand = define({
 });
 
 // src/commands/write.ts
-import { z as z33 } from "zod";
+import { z as z34 } from "zod";
 var writeCommand = define({
   name: "write",
   tool: "kb_write",
   usage: "write <type> < record.json",
   description: "Write one record. Search first \u2014 a duplicate concept id is rejected, not overwritten; kb_types lists each type's sections. An unsourced claim is an `assumption` with assumption: true, never a vague `fact`. Conflicting records get a `risk`, `open-question`, or superseding `decision`. Prefer a new short record over overloading one. Never delete; supersede.",
-  input: z33.object({
+  input: z34.object({
     bundlePath,
-    type: z33.enum(KB_RECORD_TYPES),
+    type: z34.enum(KB_RECORD_TYPES),
     input: composeInputSchema
   }),
   fromArgv: async (argv, path, stdin) => ({
@@ -3824,13 +3954,13 @@ var writeCommand = define({
 });
 
 // src/commands/write-decision.ts
-import { z as z34 } from "zod";
+import { z as z35 } from "zod";
 var writeDecisionCommand = define({
   name: "write-decision",
   tool: "kb_write_decision",
   usage: "write-decision < decision.json",
   description: "Write a decision, with `alternative` (what was rejected and why) and `impact` as fields. Record one when a later reader would otherwise simplify the constraint away; skip when the diff already answers it. `sources` for material read, `anchors` for code, `relatedConceptIds` for records.",
-  input: z34.object({ bundlePath, input: decisionInputSchema }),
+  input: z35.object({ bundlePath, input: decisionInputSchema }),
   fromArgv: async (_argv, path, stdin) => ({
     bundlePath: path,
     input: JSON.parse(await stdin())
@@ -3870,6 +4000,7 @@ var KB_COMMANDS = [
   listCommand,
   readIndexCommand,
   logCommand,
+  stampCommand,
   validateCommand,
   doctorCommand,
   schemaCommand,
@@ -3999,19 +4130,50 @@ async function loadQmd(logger) {
 }
 
 // src/kb-store.ts
-import { createHash as createHash2 } from "crypto";
 import {
   appendFile,
   link,
   mkdir as mkdir3,
   readdir,
-  readFile as readFile4,
+  readFile as readFile5,
   rename,
   unlink,
   writeFile as writeFile3
 } from "fs/promises";
 import { join as join5, resolve as resolve5, sep as sep3 } from "path";
 
+// src/kb-stamp.ts
+import { createHash as createHash2 } from "crypto";
+function sha256(contents) {
+  return createHash2("sha256").update(contents).digest("hex");
+}
+function bundleStamp(records, superseded) {
+  const entries = [
+    ...records.map((hit) => ({
+      conceptId: hit.record.conceptId,
+      digest: `current:${sha256(
+        stringifyMarkdownWithFrontmatter(
+          hit.record.body,
+          hit.record.frontmatter
+        )
+      )}`
+    })),
+    ...superseded.map((entry) => ({
+      conceptId: entry.conceptId,
+      digest: `superseded:${sha256(JSON.stringify(entry))}`
+    }))
+  ].sort((a, b) => a.conceptId < b.conceptId ? -1 : 1);
+  return {
+    digest: sha256(
+      entries.map((entry) => `${entry.conceptId}:${entry.digest}`).join("\n")
+    ),
+    records: entries
+  };
+}
+function bundleDigest(records, superseded) {
+  return bundleStamp(records, superseded).digest;
+}
+
 // src/kb-links/inbound.ts
 function inboundIndex(bundle) {
   const byTarget = /* @__PURE__ */ new Map();
@@ -4242,7 +4404,7 @@ var KbStore = class {
     const target = this.recordPath(bundlePath2, conceptId2);
     let raw;
     try {
-      raw = await readFile4(target, "utf8");
+      raw = await readFile5(target, "utf8");
     } catch {
       return null;
     }
@@ -4267,7 +4429,7 @@ var KbStore = class {
     const records = await mapLimit(
       wanted,
       DEFAULT_IO_CONCURRENCY,
-      async ({ name, conceptId: conceptId2 }) => this.parse(conceptId2, await readFile4(join5(root, name), "utf8"))
+      async ({ name, conceptId: conceptId2 }) => this.parse(conceptId2, await readFile5(join5(root, name), "utf8"))
     );
     return records.filter((record) => record !== null);
   }
@@ -4542,6 +4704,28 @@ ${answer}
       digest: bundleDigestValue
     };
   }
+  /**
+   * `load`'s digest without `load`'s bodies — the same records, adjudicated
+   * the same way, handed back as a stamp. Skips the anchor drift pass, which
+   * reads source files and only ever adds warnings: no warning reaches the
+   * digest, so the value is identical to the one `load` returns.
+   */
+  async stamp(bundlePath2) {
+    const bundle = await this.list(bundlePath2);
+    const adjudicated = adjudicate(bundle, bundle, /* @__PURE__ */ new Date());
+    const current = adjudicated.filter((hit) => hit.standing !== "superseded");
+    const superseded = adjudicated.filter((hit) => hit.standing === "superseded").map(stub);
+    const stamped = bundleStamp(current, superseded);
+    const dates = bundle.map((record) => record.frontmatter.generated?.at ?? null).filter((at) => typeof at === "string").sort();
+    return {
+      path: bundlePath2,
+      digest: stamped.digest,
+      recordCount: bundle.length,
+      superseded: superseded.length,
+      newestAt: dates.at(-1) ?? null,
+      records: stamped.records
+    };
+  }
   /** How a position was arrived at, as a timeline. See `trace.ts`. */
   async trace(bundlePath2, seedId, options = {}) {
     return trace(seedId, await this.list(bundlePath2), options);
@@ -4572,7 +4756,7 @@ ${answer}
   async readIndex(bundlePath2) {
     const root = this.root(bundlePath2);
     const expected = renderIndex(await this.list(bundlePath2));
-    const stored = await readFile4(join5(root, INDEX_FILE), "utf8").catch(
+    const stored = await readFile5(join5(root, INDEX_FILE), "utf8").catch(
       () => null
     );
     if (indexIsStale(stored, expected)) {
@@ -4593,7 +4777,7 @@ ${answer}
    * knows which agent touched what. So a bad line is surfaced and left alone.
    */
   async readLog(bundlePath2) {
-    const raw = await readFile4(
+    const raw = await readFile5(
       join5(this.root(bundlePath2), LOG_FILE),
       "utf8"
     ).catch(() => "");
@@ -4645,15 +4829,15 @@ ${answer}
   }
   async mutate(bundlePath2, conceptId2, change, entry, changeBody = (body) => body) {
     const target = this.recordPath(bundlePath2, conceptId2);
-    const before = await readFile4(target, "utf8").catch(() => null);
+    const before = await readFile5(target, "utf8").catch(() => null);
     if (before === null) throw new KbRecordNotFoundError(conceptId2);
     const parsed = this.parse(conceptId2, before);
     if (!parsed) throw new KbRecordNotFoundError(conceptId2);
     const frontmatter = change(parsed.frontmatter);
     const body = changeBody(parsed.body);
     const contents = stringifyMarkdownWithFrontmatter(body, frontmatter);
-    const witness = await readFile4(target, "utf8").catch(() => null);
-    if (witness === null || digest(witness) !== digest(before)) {
+    const witness = await readFile5(target, "utf8").catch(() => null);
+    if (witness === null || sha256(witness) !== sha256(before)) {
       throw new KbWriteConflictError(conceptId2);
     }
     await this.publish(target, contents, true, conceptId2);
@@ -4739,7 +4923,7 @@ ${answer}
     try {
       let existing;
       try {
-        existing = await readFile4(target, "utf8");
+        existing = await readFile5(target, "utf8");
       } catch (error) {
         if (error.code !== "ENOENT") throw error;
         existing = null;
@@ -4861,25 +5045,6 @@ function normalizeActor(id) {
   if (colon === -1) return id.toLowerCase();
   return id.slice(0, colon + 1).toLowerCase() + id.slice(colon + 1);
 }
-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;
@@ -4966,7 +5131,7 @@ function typeRank(record) {
 }
 
 // src/version.ts
-var VERSION = true ? "0.1.15" : "0.0.0-dev";
+var VERSION = true ? "0.1.16" : "0.0.0-dev";
 
 export {
   kbSourceSchema,
@@ -5082,4 +5247,4 @@ export {
   KbStore,
   VERSION
 };
-//# sourceMappingURL=chunk-KNIUBCZY.js.map
+//# sourceMappingURL=chunk-H5W53NVU.js.map