@saasontools/strauss-kb 0.1.8 → 0.1.9

package/ARCHITECTURE.md

@@ -72,6 +72,95 @@ replacement's first log format was `·`-delimited, with a splitter to read it
 back. Both are gone: the log is JSONL and the schema is emitted from Zod, so
 `strauss-kb schema` is the contract rather than a description of one.
 
+## Cross-worktree log safety
+
+`log.jsonl` is append-only and the one artifact nothing can rebuild, so how it
+merges across worktrees matters more than how any record file does. Records
+already don't need this: one concept id is one file, so two writers choosing
+distinct ids never merge at all, and `link`-based publish (above) turns the
+one case where they collide into a 409 rather than a merge. The log has no
+such escape — every writer appends into the same file by design — so it needs
+an actual merge strategy, not just atomicity per write.
+
+The append itself already had it: `record()` uses `appendFile`, which opens
+`O_APPEND` and is one `write(2)` for an entry this small, so two processes
+appending locally interleave whole lines, never a torn one. What was missing
+was git's merge of two worktrees' independently-appended logs — the default
+line-level merge can conflict, or silently keep one side, on lines that were
+never in conflict, since both sides only ever added, never edited, a line.
+
+The fix is `.gitattributes: log.jsonl text eol=lf merge=union`, written by
+`record()` — every path that appends a log line (`write`, `setStatus`,
+`verify`, `supersede`), not `write()` alone — on first use
+(`kb-store.ts#ensureGitattributes`). `union` is a merge driver git ships —
+nothing to configure beyond the attribute — that keeps both sides' added
+lines; `eol=lf` closes a second divergence path, below. The alternative
+considered and dropped was a lock file coordinating writes across worktrees
+the way `mutate`'s CAS coordinates a single record: it would need to span
+process boundaries and survive a crashed holder, which is the same
+stale-lock failure mode rejected above, for a smaller problem than the one it
+solves there.
+
+Decisions worth naming because a later reader could reopen them:
+
+- **A `.gitattributes` that exists but declares no merge strategy for the
+  log gets the line appended, not left alone.** The alternative — leave a
+  user's own file untouched — reads as more conservative, but a bundle that
+  already has a `.gitattributes` in front of it is exactly the bundle most
+  likely to be shared across worktrees or forks, so leaving it without union
+  merge is the worse of the two failure modes. A file that _does_ already
+  declare a merge strategy for `log.jsonl` — this one or a user's own, such
+  as `merge=ours` — is left alone entirely: gitattributes resolves repeated
+  lines for one pattern by "last one wins", so appending a second `merge=`
+  line would silently override rather than coexist. Recognizing "already
+  declared" needed a real tokenizer (`hasMergeDeclaration`) rather than
+  exact-string matching against the line this module writes — the first cut
+  missed a tab or doubled space between tokens (false negative, a harmless
+  duplicate line) and could never recognize a user's own `merge=ours` as a
+  decision already made (the one case where appending anything is wrong).
+- **A `.gitattributes` that fails to _read_ is never treated as "missing".**
+  The first cut folded every `readFile` failure — permissions, a transient
+  `EMFILE`, the path being a directory — into "doesn't exist yet" and took
+  the create branch, which is a truncating write: a real `.gitattributes`
+  hit by a transient read error would be silently replaced with just the
+  union-merge line. Only `ENOENT` means missing; anything else is reported
+  as a failure and the file is left exactly as it was. The create branch
+  also uses `wx` (exclusive create) rather than a plain write, so a
+  concurrent writer that created the file between the read and this write
+  fails loudly into the same best-effort catch instead of the second writer
+  truncating the first one's file.
+- **Union merge does not preserve line order, so `kb_log`'s reader sorts by
+  `at` rather than trusting file order.** Sorting there, once, is cheaper
+  than trying to make every future merge order-preserving. `at` is now
+  validated as an actual ISO-8601 timestamp (`z.iso.datetime()`, matching
+  exactly what `record()` writes) rather than any non-empty string — a value
+  that parses as JSON and matches the schema's shape but isn't really a
+  timestamp would otherwise sort unpredictably instead of failing, and
+  `parseLog` already has a place for "well-formed but wrong" to go: reported
+  as malformed, same as any other schema mismatch, never silently repaired.
+- **A union merge can keep the exact same line twice** — a cherry-pick or
+  rebase that carried one worktree's entry into the other's history before
+  the merge, not two independent writes agreeing by chance: `record()` mints
+  its own `at` per call, so two entries equal on every field including `at`
+  cannot be genuine. `parseLog` dedupes entries that are byte-for-byte equal
+  after parsing and keeps everything else, including two entries that agree
+  on every field except `at` — that pair is two real events. The
+  alternative — leave duplicates visible and call it "genuine repeat
+  ambiguity" — was rejected: there's no ambiguity to preserve, since the
+  only way to produce an exact duplicate is the merge itself.
+- **A read-then-append race across processes on the append branch — two
+  processes both reading a `.gitattributes` without the line, both
+  appending it — is left unguarded, not a reason to lock.** `appendFile` is
+  `O_APPEND`, so the outcome is two copies of the same line, never a torn
+  write, and `hasMergeDeclaration` sees a duplicate declaration as "already
+  declared" on the very next call. Cheap residue, not corruption — the same
+  trade the lock-file alternative above was rejected for, at a smaller
+  scale.
+
+GitHub does not run merge drivers for a PR it merges server-side — see the
+README's "Cross-worktree writes" section. The driver only helps a merge a
+local git client actually performs.
+
 ## Rejected for now: a base registry
 
 Cross-base questions are unaskable by construction — supersession, traces, and

package/README.md

@@ -54,6 +54,7 @@ bundling can `require()` it without depending on its Node version honouring
   <type>.<slug>.md    records
   INDEX.md            index      derived, store-owned
   log.jsonl           history    primary, append-only
+  .gitattributes      merge      store-owned, written on first write
   .index.sqlite       search     derived, gitignored
 ```
 
@@ -76,6 +77,46 @@ Repair-on-read, not coordination, is what lets both exist without a lock. The
 index is _eventually_ correct: a writer whose scan predated another's record
 publishes a briefly stale index, and the next read through the store settles it.
 
+### Cross-worktree writes
+
+A committed base is routinely written from more than one worktree at once —
+each records into the same `log.jsonl`, and a plain git merge of two branches
+that both appended lines resolves that file at the line level, same as any
+other text file. That is the wrong merge for an append-only log: git's default
+picks a side, or conflicts, on lines that both branches only ever meant to add
+to.
+
+So the first write to a base (through `write`, or whichever call happens to
+append the first log line) declares a merge driver for its log: it writes
+`log.jsonl text eol=lf merge=union` into the base's `.gitattributes` if that
+file does not exist yet, and appends the line if the file exists but declares
+no merge strategy for `log.jsonl` yet — a `.gitattributes` a user put there
+first is respected, never overwritten wholesale, and a line that already
+gives `log.jsonl` _any_ merge strategy — this one or the user's own choice
+such as `merge=ours` — is left alone rather than layered under a second,
+possibly conflicting one. `union` is one of git's built-in merge drivers; the
+attribute alone is enough; nothing else needs configuring. `eol=lf` pins line
+endings to `\n` regardless of a checkout's `core.autocrlf`, so a Windows
+checkout normalizing the file on checkout can't leave it with mixed endings
+against the raw `\n` every append writes. With it, a merge of two branches
+that both appended to `log.jsonl` keeps both sides' lines instead of picking
+one.
+
+A union merge does not preserve line order, and can occasionally keep the
+same line twice (a cherry-pick or rebase that carried one side's entry into
+the other's history before the merge). `kb_log`'s reader (`kb-log.ts`) sorts
+entries by `at` and drops exact duplicates before returning them, so neither
+is something a caller has to account for.
+
+**This applies to a local `git merge`, not to GitHub.** GitHub computes pull
+request merges (and the merge/squash/rebase buttons) through its own service,
+which does not read `.gitattributes` merge-driver declarations — a PR that
+merges two branches' `log.jsonl` appends on GitHub gets git's ordinary
+line-level merge (or a conflict) even with the attribute in place. The union
+driver only fires for a merge actually run by a local git client, which covers
+worktrees pulling from and pushing to each other directly, but not a merge
+GitHub itself performs.
+
 ## Records
 
 The filename is the identity. `fact.auth-retries.md` has concept id

package/dist/{chunk-MGPYUZOM.js → chunk-KVEEISYQ.js}

@@ -4,7 +4,7 @@ import {
   KB_DIR,
   KbStore,
   VERSION
-} from "./chunk-YJK7KGHN.js";
+} from "./chunk-OFDWRMY6.js";
 
 // src/cli.ts
 import { join } from "path";
@@ -112,4 +112,4 @@ function usage() {
 export {
   runKbCli
 };
-//# sourceMappingURL=chunk-MGPYUZOM.js.map
+//# sourceMappingURL=chunk-KVEEISYQ.js.map

package/dist/{chunk-YYX6CX6V.js → chunk-MWWDD23L.js}

@@ -2,7 +2,7 @@ import {
   KB_COMMANDS,
   KbStore,
   VERSION
-} from "./chunk-YJK7KGHN.js";
+} from "./chunk-OFDWRMY6.js";
 
 // src/mcp.ts
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
@@ -46,4 +46,4 @@ export {
   createKbMcpServer,
   runKbMcpServer
 };
-//# sourceMappingURL=chunk-YYX6CX6V.js.map
+//# sourceMappingURL=chunk-MWWDD23L.js.map

package/dist/{chunk-YJK7KGHN.js → chunk-OFDWRMY6.js}

@@ -1301,7 +1301,15 @@ function ageInDays(record, now) {
 import { z as z5 } from "zod";
 var LOG_FILE = "log.jsonl";
 var kbLogEntrySchema = z5.object({
-  at: z5.string().min(1),
+  // Validated, not just `min(1)`: `at` is a sort key (see `parseLog`
+  // below), and a value that isn't actually chronological — a Unix
+  // timestamp, a human-typed date, garbage — would sort wrong without
+  // ever failing to parse. `z.iso.datetime()` accepts exactly what
+  // `record()` writes (`Date#toISOString()`: full precision, `Z` offset)
+  // and rejects everything else, including a non-`Z` offset — so a
+  // malformed `at` is reported the same way a malformed line already is,
+  // rather than silently sorting into the wrong place.
+  at: z5.iso.datetime(),
   by: z5.string().min(1),
   operation: z5.string().min(1),
   conceptId: z5.string().min(1),
@@ -1315,6 +1323,7 @@ function renderLogEntry(entry) {
 function parseLog(raw) {
   const entries = [];
   const malformed = [];
+  const seen = /* @__PURE__ */ new Set();
   raw.split("\n").forEach((text, index) => {
     if (!text.trim()) return;
     let value;
@@ -1329,8 +1338,14 @@ function parseLog(raw) {
       malformed.push({ line: index + 1, text });
       return;
     }
+    const key = JSON.stringify(parsed.data);
+    if (seen.has(key)) return;
+    seen.add(key);
     entries.push(parsed.data);
   });
+  entries.sort(
+    (left, right) => left.at < right.at ? -1 : left.at > right.at ? 1 : 0
+  );
   return { entries, malformed };
 }
 
@@ -2416,6 +2431,32 @@ import {
   writeFile as writeFile3
 } from "fs/promises";
 import { join as join4, resolve as resolve4, sep as sep2 } from "path";
+
+// src/kb-gitattributes.ts
+var GITATTRIBUTES_FILE = ".gitattributes";
+var UNION_MERGE_LINE = `${LOG_FILE} text eol=lf merge=union`;
+function parseLine(line) {
+  const trimmed = line.trim();
+  if (!trimmed || trimmed.startsWith("#")) return null;
+  const [pattern, ...attrs] = trimmed.split(/\s+/);
+  return pattern === void 0 ? null : { pattern, attrs };
+}
+function hasMergeDeclaration(contents) {
+  return contents.split("\n").some((line) => {
+    const parsed = parseLine(line);
+    if (!parsed || parsed.pattern !== LOG_FILE) return false;
+    return parsed.attrs.some(
+      (attr) => attr === "merge" || attr === "-merge" || attr.startsWith("merge=")
+    );
+  });
+}
+function appendUnionMergeLine(contents) {
+  const separator = contents.length === 0 || contents.endsWith("\n") ? "" : "\n";
+  return `${separator}${UNION_MERGE_LINE}
+`;
+}
+
+// src/kb-store.ts
 var KB_DIR = join4(".strauss", "kb");
 var STORE_OWNED = /* @__PURE__ */ new Set([INDEX_FILE, LOG_FILE, SEARCH_INDEX_FILE]);
 var DEFAULT_LOAD_BUDGET = 25e3;
@@ -2840,8 +2881,87 @@ ${answer}
       await unlink(staging).catch(() => void 0);
     }
   }
+  /**
+   * Declares union merge for the log, so two worktrees writing the same
+   * bundle interleave their `log.jsonl` lines on merge rather than one
+   * side's appends silently losing to git's ordinary line-level merge.
+   *
+   * Called from `record` — every path that appends a log line, not just
+   * `write` — so a bundle only ever mutated through `setStatus`/`verify`/
+   * `supersede` still gets it. There is no cheaper reliable signal for
+   * "first write" than checking the file itself, and after the first call
+   * the check is a no-op `readFile`.
+   *
+   * A missing `.gitattributes` is created outright, with `wx` (exclusive
+   * create) rather than a plain write: if another process's `write()` won a
+   * race and created the file between the `readFile` below and this call,
+   * `wx` fails instead of truncating what that writer just wrote, and the
+   * failure is swallowed by the catch below same as any other best-effort
+   * miss. A file that exists but declares no merge strategy for the log
+   * gets the line appended, never a wholesale rewrite; one that already
+   * declares any merge strategy — this one or a user's own — is left alone
+   * entirely (see `hasMergeDeclaration`).
+   *
+   * `readFile` failing is `existing === null` only for `ENOENT` — genuinely
+   * missing. Any other error (a permission problem, a transient `EMFILE`,
+   * the path being a directory) is *not* "missing" and must not fall into
+   * the create branch, which would truncate whatever is actually there with
+   * just the union-merge line: that is the file-destroying bug this
+   * function exists to avoid, not commit. An unreadable existing file is
+   * therefore left untouched and reported as a failure like any other.
+   *
+   * Two processes racing the append branch — both read a file without the
+   * line, both append it — is possible and left unguarded: `appendFile` is
+   * `O_APPEND`, so the result is two copies of the same line rather than a
+   * torn write, and `hasMergeDeclaration` sees a duplicate declaration as
+   * "already declared" on the next call. A cheap-to-detect, harmless-to-
+   * leave residue, not a reason to add a cross-process lock (see
+   * `ARCHITECTURE.md`'s rejection of one for the same trade on records).
+   *
+   * Best-effort, like the log append it precedes: failing to write this
+   * file must not fail the mutation it guards.
+   */
+  async ensureGitattributes(root) {
+    const target = join4(root, GITATTRIBUTES_FILE);
+    try {
+      let existing;
+      try {
+        existing = await readFile3(target, "utf8");
+      } catch (error) {
+        if (error.code !== "ENOENT") throw error;
+        existing = null;
+      }
+      if (existing === null) {
+        await writeFile3(target, appendUnionMergeLine(""), {
+          encoding: "utf8",
+          flag: "wx"
+        });
+        this.logger.info?.({
+          operation: "kb.gitattributes.ensure",
+          bundlePath: root,
+          outcome: "created"
+        });
+        return;
+      }
+      if (!hasMergeDeclaration(existing)) {
+        await appendFile(target, appendUnionMergeLine(existing), "utf8");
+        this.logger.info?.({
+          operation: "kb.gitattributes.ensure",
+          bundlePath: root,
+          outcome: "appended"
+        });
+      }
+    } catch (error) {
+      this.logger.warn?.({
+        operation: "kb.gitattributes.ensure",
+        outcome: "failed",
+        error: error instanceof Error ? error.message : "unknown"
+      });
+    }
+  }
   /** Appends one log line. Failing to log must not fail the mutation. */
   async record(root, entry) {
+    await this.ensureGitattributes(root);
     const line = renderLogEntry({ at: (/* @__PURE__ */ new Date()).toISOString(), ...entry });
     await appendFile(join4(root, LOG_FILE), line, "utf8").catch((error) => {
       this.logger.warn?.({
@@ -2999,7 +3119,7 @@ function typeRank(record) {
 }
 
 // src/version.ts
-var VERSION = true ? "0.1.8" : "0.0.0-dev";
+var VERSION = true ? "0.1.9" : "0.0.0-dev";
 
 export {
   kbSourceSchema,
@@ -3093,4 +3213,4 @@ export {
   KbStore,
   VERSION
 };
-//# sourceMappingURL=chunk-YJK7KGHN.js.map
+//# sourceMappingURL=chunk-OFDWRMY6.js.map