@saasontools/strauss-kb 0.1.1 → 0.1.2

package/ARCHITECTURE.md

@@ -0,0 +1,85 @@
+# Architecture
+
+The README says what the format is and how to use it. This says why it is
+shaped that way, and which alternatives were tried and dropped — the decisions
+a later reader would otherwise reopen.
+
+## One record per file
+
+The filename is the identity, so two writers never merge; they only choose
+distinct names. Publication uses `link`, which fails when the name is taken, and
+a collision surfaces as a 409 the caller has to answer rather than a silent
+last-write-wins.
+
+Read-modify-write (`setStatus`, `answer`) checks a content digest immediately
+before publishing. That narrows the lost-update window to two adjacent syscalls
+rather than closing it. A lock would close it and add a stale-hold failure worse
+than the residue: a crashed holder blocks every later writer, where a lost
+update costs one retry.
+
+## Read for a question, not for a session
+
+A base loaded at the start of a long conversation is summarised away by the end
+of it, and nothing keeps it alive. So no consumer loads it that way:
+
+| Consumer                        | How it reads                                                                 |
+| ------------------------------- | ---------------------------------------------------------------------------- |
+| Diff annotation                 | `matchToDiff` — deterministic, no context involved                           |
+| "Has this been decided?"        | a fresh short-lived reader, given the base and the question, discarded after |
+| An implementor writing a record | a point query at the moment of writing, not a load an hour earlier           |
+
+Each has clean context by construction. Where a base genuinely must stay
+resident it will drift, and there is no defence — the mitigation is that
+reloading costs about three thousand tokens, so read it again at the point of
+use rather than trying to keep it.
+
+## What happens when a base outgrows a context
+
+Loading stops working somewhere above a few hundred records. What replaces it is
+not a different answer to the same question — it is the same reader, given
+candidates instead of everything:
+
+```
+vector recall  →  top ~20 candidates, with their scores
+                  ↓
+reader judges  →  picks what answers, or says nothing does
+```
+
+The reader stays the judge in both regimes, which is what preserves the two
+structural wins the README reports: it can say no record answers the question,
+and it picks the record that answers rather than the one nearest the topic.
+Neither survives if a ranker's top hit is taken as the answer.
+
+**A score threshold is not the growth path.** The wrong `audit trail` hit scored
+0.318 against the correct `race condition` hit at 0.295; any cut that drops the
+first drops the second. A threshold excludes the absurd — an unrelated query
+scored 0.091 — and nothing else.
+
+**Tags are not the growth path either.** The field exists, is written, and is
+read by nothing but an index line, deliberately. Free-text tags drift the way
+`auth` / `authentication` / `authn` drift, which is the failure this format was
+rewritten to remove; enforcing a vocabulary would make them a closed enum, which
+`type` already is. The labels that matter here are already verifiable —
+`strauss_anchors` names a file and a symbol, which either match the repository
+or do not, where a tag can be wrong forever. If narrowing ever matters, measure
+tag narrowing against vector recall on a real base rather than adding both.
+
+## Rejected: a format that needs a parser
+
+This was broken twice. A hand-rolled frontmatter reader could not express nested
+maps, so it misread every OKF `generated`, `sources[]`, and `verified[]`. Its
+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.
+
+## Rejected for now: a base registry
+
+Cross-base questions are unaskable by construction — supersession, traces, and
+search stop at the directory boundary. That is the price of a base that can be
+copied, deleted, or handed over whole, and it is what keeps the search index
+disposable.
+
+If cross-base ever becomes the common case, the cheap escape is a registry: a
+list of paths a caller may name explicitly, queried one at a time and merged
+only for display. It is deliberately unbuilt. Adding it early would drag back
+the cross-scope machinery this model exists to avoid.

package/README.md

@@ -146,6 +146,10 @@ the name is taken — two writers choosing one concept id is a 409 the caller mu
 answer, by picking a more specific slug or by saying it meant to replace.
 `rename` is used only when the caller passes `overwrite`.
 
+Read-modify-write (`setStatus`, `answer`) checks a content digest immediately
+before publishing, which narrows the lost-update window rather than closing it.
+[ARCHITECTURE.md](./ARCHITECTURE.md) says why a lock was rejected.
+
 `supersede` writes both directions, so a backlink cannot drift in normal use and
 `validate` drops to catching hand-edits.
 
@@ -267,6 +271,10 @@ say no record answers the question, where vector search returns its nearest
 neighbour whatever the distance; and a reader picks the record that answers the
 question rather than the one nearest the topic.
 
+Read for a question, not for a session: a base loaded at the start of a long
+conversation is summarised away by the end of it, and reloading costs about
+three thousand tokens. Read it again at the point of use.
+
 `load` refuses rather than truncating when a base exceeds its budget (25,000
 tokens by default). 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
@@ -333,7 +341,8 @@ hold is the exception — no invariant, deterministic path.
 the directory boundary. "Was this settled somewhere else?" is answered by a
 person choosing which base to open. That is the price of a base that can be
 copied, deleted, or handed over whole, and it is what keeps the search index
-disposable.
+disposable. [ARCHITECTURE.md](./ARCHITECTURE.md) covers the registry that would
+lift it, and why it is unbuilt.
 
 ## License
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@saasontools/strauss-kb",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "description": "Knowledge base of markdown records with standing, supersession and trace: library, CLI, and MCP server over one command set",
   "license": "MIT",
   "author": "Assaf Kamil",
@@ -29,6 +29,7 @@
   "files": [
     "dist",
     "README.md",
+    "ARCHITECTURE.md",
     "LICENSE"
   ],
   "keywords": [