@saasontools/strauss-kb 0.1.16 → 0.1.17

package/ARCHITECTURE.md

@@ -84,11 +84,28 @@ from Zod, and `strauss-kb schema` is the contract.
 A fresh stamp is a baseline nobody has checked, so only a run where every
 checkable anchor already matched appends `verified[]`.
 
-The v1 resolver is regex-based, biased so a wrong answer loses to no answer: a
-span short of the code it claims hashes as stable while that code moves. It
-ranks by shape, scopes a dotted symbol to its parent, captures by brace depth or
-Python indentation, and returns `null` otherwise. A pure `AnchorResolver`
-interface admits a tree-sitter replacement.
+Symbols resolve through tree-sitter first: a WASM parser per language, each
+grammar's own upstream `queries/tags.scm` over definition sites, and the
+definition node's range as the span. A dotted symbol matches the definition whose enclosing chain
+matches; a bare name matching two is `symbol-ambiguous`. Only declarations are
+captured: a symbol appearing solely in a call is no match.
+
+The chain is tree-sitter, then regex, then a whole-file hash. A resolver that
+parsed the file answers for it unless it defines no such symbol at all — tags
+queries capture functions and types, not constants, aliases or fields — so
+`symbol-not-found` continues down the chain and the anchor records whichever
+resolver answered. `symbol-ambiguous` and `resolver-unavailable` stop it:
+picking one of two definitions by text search, or swapping a precise span for a
+heuristic one when a grammar will not load, is how a wrong span comes to hash
+as `match`. A grammar that will not load is a finding, never a throw.
+
+Grammars download on first use, sha256-pinned by `grammars/manifest.json` and
+cached under `~/.strauss/grammars`; the reasoning is in the
+[specification](https://saasontools.github.io/strauss-agent-tools/specification#symbol-resolution).
+
+Each anchor records the resolver that stamped it. A hash only the previous
+resolver reproduces is `drifted`, reason `resolver-changed`. Trees are cached
+per content hash, grammars load once per process.
 
 Repository identity is normalised and compared, not parsed: an invented format
 would reject correct values from unseen hosts.

package/README.md

@@ -206,17 +206,18 @@ Why a lock was rejected: [ARCHITECTURE.md](./ARCHITECTURE.md).
 
 An anchor names where a record attaches in the code: a `file`, optionally a
 `symbol` — symbolic, because a line number written mid-change is wrong by the
-end of it. Five optional fields extend it:
+end of it. Six optional fields extend it:
 
 | Field         | Meaning                                                                               |
 | ------------- | ------------------------------------------------------------------------------------- |
 | `hash`        | `sha256:<hex>` over the anchored text, algorithm-prefixed.                            |
 | `lines`       | Line count the hash covered.                                                          |
 | `resolved_at` | When the anchor last resolved.                                                        |
+| `resolver`    | Which resolver produced the hash: `tree-sitter` or `regex`.                           |
 | `repo`        | Which repository — remote URL or short name. Absent means this base's own repository. |
 | `ref`         | Git rev the evidence was taken at.                                                    |
 
-`hash`, `lines`, and `resolved_at` are **measured** — a resolution pass stamps
+`hash`, `lines`, `resolved_at`, and `resolver` are **measured** — a resolution pass stamps
 them; `repo` and `ref` are **author-owned identity** and a resolution pass
 never writes them.
 
@@ -246,8 +247,17 @@ carries a hash; unstamped anchors and unreachable remotes never fail.
 A fully clean run — every anchor checked and `match`, none stamped this run —
 appends a `verified[]` event.
 
-Symbol resolution is a v1 heuristic; ties and unclosed blocks return
-`unresolved`.
+Symbols resolve tree-sitter first — the 20 language packs that have both a
+grammar and a definitions query, pinned together by `pnpm grammars pin` from
+`grammars/packs.json` and proved at pin time — then the regex heuristic for
+other extensions and for symbols the tags query does not define (constants,
+type aliases, class fields), then a
+whole-file hash when the anchor names no symbol; an ambiguous match or an
+unloadable grammar returns `unresolved` rather than falling through to a guess. Neither half of a pack is published with the
+package: grammar and query both download on first use, sha256-pinned against
+`grammars/manifest.json`, and are cached under `~/.strauss/grammars`. A hash the old resolver still reproduces and
+the new one does not is `drifted` with reason `resolver-changed` — accept it
+with `--rebaseline`.
 
 Drift also surfaces on read: `kb_load` and `kb_query` attach a
 `{ kind: "drifted" }` warning — or `{ kind: "unchecked" }` for a foreign anchor

package/dist/{chunk-RINBOAQZ.js → chunk-RMJUGTAQ.js}

@@ -4,7 +4,7 @@ import {
   KB_DIR,
   KbStore,
   VERSION
-} from "./chunk-H5W53NVU.js";
+} from "./chunk-ZKIQOBHT.js";
 
 // src/cli.ts
 import { join } from "path";
@@ -121,4 +121,4 @@ function usage() {
 export {
   runKbCli
 };
-//# sourceMappingURL=chunk-RINBOAQZ.js.map
+//# sourceMappingURL=chunk-RMJUGTAQ.js.map

package/dist/{chunk-MEZCF646.js → chunk-SA3A2SPY.js}

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