git-span 1.0.134 → 1.0.137

package/README.md

@@ -1,14 +1,18 @@
 # git span
 
-`git span` tracks implicit semantic dependencies in a git repository — line-range or whole-file anchors that participate in a coupling no schema, type, or test enforces. Each span names its anchors, optionally carries a `why` sentence defining the subsystem they collectively form (recommended on every span), and surfaces drift via `git span stale` when those anchors diverge from their anchored state.
+`git span` tracks implicit semantic dependencies in a git repository — line-range or whole-file anchors that participate in a coupling no schema, type, or test enforces. Each span names its anchors, optionally carries a `why` — one present-tense sentence defining the subsystem they form together (recommended on every span), and surfaces drift via `git span stale` when those anchors diverge from their anchored state.
 
 The primary CLI surface lives in `src/cli/mod.rs`. Run `git span --help` or `git span stale --help` for flag reference.
 
-### Upgrading from the sqlite cache
+### The stale cache
 
-The trail cache now lives at `<common_dir>/span/cache/v1/` as a BLAKE3-keyed content-addressed filesystem store. The previous sqlite-backed cache at `<common_dir>/span/cache/span_cache.sqlite` (or `<git_dir>/span/cache/span_cache.sqlite` on older per-worktree installations), along with its `-shm` and `-wal` companions, is unused and can be removed with a single `rm -f <common_dir>/span/cache/span_cache.sqlite*` (and the `<git_dir>` variant if present). Nothing reads those files anymore.
+`git span stale` (and related resolution paths) are backed by a single persistent cache: a SQLite database at `<common_dir>/span/store.db` (plus its `-wal` and `-shm` companions), implemented in `src/resolver/store/`. This is the whole on-disk cache footprint — remove `store.db*` to reset it. Setting `GIT_SPAN_CACHE=0` disables it for a run.
 
-Separately, and unrelated to the sqlite cache above, `git span stale` (and related resolution paths) are backed by a second, currently-active cache: a SQLite database at `<common_dir>/span/stale-cache.db` (see `src/resolver/cache_v2/schema.rs`). Cleanup of the on-disk footprint needs to account for both stores — the `cache/v1/` filesystem store and `stale-cache.db` (plus its `-shm`/`-wal` companions) — not just one.
+The store is bounded by a byte high-water mark (256 MiB by default; override with `GIT_SPAN_STORE_MAX_BYTES` or `git config git-span.storeMaxBytes`), with transactional GC that runs only when a publish crosses the cap. It lives in the Git *common* directory, so it is shared across linked worktrees of one clone on one host; it is not shared cross-host or cross-clone. Earlier releases kept two separate caches (a `cache/v1/` filesystem trail store and a `stale-cache.db`); both were replaced by this one store and leave no files behind on a fresh clone.
+
+### The shared executable-digest store
+
+A configured filter driver's resolved executable (e.g. a `git-lfs` install) is content-hashed to prove its identity as part of every state-token capture. That hash is a fact about a file on the local machine, not about any one repository, so it is memoized in a *second*, small, per-user SQLite database — separate from the per-repo stale cache above — at `$GIT_SPAN_CACHE_HOME/exe-digest.db`, defaulting to `$HOME/.cache/git-span/exe-digest.db` (mirrors the workspace's `$HOME/.cache/git-span/cargo-target/` per-user build-artifact directory). Every repository on a machine that shares the same filter executable reuses the same memoized digest instead of re-hashing it per clone. `GIT_SPAN_EXE_DIGEST_DB` overrides the database file path directly (useful for CI isolation). `GIT_SPAN_CACHE=0` disables this store too, exactly like the stale cache. Implemented in `src/resolver/core/exe_digest_store.rs`; safe to delete at any time (it is rebuilt lazily, fail-closed on any error — a missing or broken database just means every executable is re-hashed).
 
 ## Profiling
 

package/man/git-span.1

@@ -1,6 +1,6 @@
 .ie \n(.g .ds Aq \(aq
 .el .ds Aq '
-.TH git-span 1  "git-span 1.0.134" 
+.TH git-span 1  "git-span 1.0.137" 
 .ie \n(.g .ds Aq \(aq
 .el .ds Aq '
 .SH NAME
@@ -18,32 +18,38 @@ Each
 .B span
 anchors the participating anchors and carries a durable
 .I why
-\[em] one prose sentence that names the relationship the anchored set holds
-and survives a rewrite of either side.
+\[em] one present-tense sentence that defines the subsystem the anchored set
+forms together and stays true across a rewrite of either side.
 .PP
 The standing question at commit time: did this change create or rely on a
 coupling that is not visible from the lines themselves?
 .PP
 .B Writing the why.
-Name the relationship the anchors hold in one prose sentence, written so it
-survives a rewrite of either side.
-Describe the relationship in role\-words (\(lqthe doc,\(rq \(lqthe parser,\(rq
+Write one complete sentence, in the present tense, that defines the subsystem
+the anchors form together: name the thing, then say what it does across the
+anchors.
+Give it a subject and a verb \[em] never a label followed by a colon \[em] and
+name the thing in role\-words (\(lqthe doc,\(rq \(lqthe parser,\(rq
 \(lqthe runbook,\(rq \(lqthe migration\(rq) rather than repeating filenames.
-For asymmetric relationships, name which side is normative:
-\(lqthe doc is the source of truth when they disagree.\(rq
-Do not restate the span name, embed incidental implementation details, or
-bundle ownership and review triggers in the why.
+A why is read when a hook surfaces it mid\-task, so make it specific enough
+that a reader who just edited one anchor can tell from the sentence alone
+whether their change lands inside the thing it names.
+Do not restate the span name or embed incidental implementation details, and
+keep invariants, caveats, ownership, and review triggers out of the why \[em]
+those belong in comments at the anchor sites, in commit messages, CODEOWNERS,
+and PR descriptions.
 .PP
 .B Re\-anchoring on drift.
 When
 .B git span stale
 reports drift, review the change at each anchor.
-If the relationship still holds, re-anchor with
+Because a why only defines, it is inherited across routine re-anchors: if the
+subsystem still holds, re-anchor with
 .B git span add
-and commit.
-If the relationship has changed, update the why with
+and commit, leaving the why alone.
+Rewrite it with
 .B git span why
-before re-anchoring.
+only when the subsystem itself has changed.
 .PP
 Each span is an ordinary tracked file under the span root (default
 .IR .span ,
@@ -101,7 +107,7 @@ git\-span\-remove(1)
 Remove anchors from a span, editing the span file under the span root. Stage and commit the change with `git add .span && git commit`
 .TP
 git\-span\-why(1)
-Read or stage the span\*(Aqs why — a one\-sentence definition of the subsystem, flow, or concern the anchors collectively form
+Read or stage the span\*(Aqs why — one complete present\-tense sentence defining the subsystem the anchors form together
 .TP
 git\-span\-delete(1)
 Delete a span
@@ -123,7 +129,7 @@ Print this message or the help of the given subcommand(s)
 .ie \n(.g .ds Aq \(aq
 .el .ds Aq '
 .SH VERSION
-v1.0.134
+v1.0.137
 .SH EXAMPLES
 Anchor a new span alongside a code change:
 .PP
@@ -132,8 +138,8 @@ Anchor a new span alongside a code change:
 git span add billing/charge-request-contract \e
     docs/api/charge.md#L40-L88 api/charge.ts#L30-L76
 git span why billing/charge-request-contract \e
-    -m "The doc states the request body shape the parser honors; \e
-the doc is the source of truth when they disagree."
+    -m "The charge request body shape is stated by the doc \e
+and honored by the parser that reads it."
 git add .span
 git commit -m "Wire checkout to charge API"
 .fi
@@ -147,7 +153,8 @@ git span add auth/token-contract --at HEAD \e
     packages/auth/token.ts#L88-L104 \e
     packages/auth/crypto.ts#L12-L40
 git span why auth/token-contract \e
-    -m "Token verification depends on signature verification."
+    -m "Session token verification checks signatures with the \e
+algorithm and key encoding the crypto helper defines."
 git add .span && git commit -m "Document token/crypto coupling"
 .fi
 .RE

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "git-span",
-  "version": "1.0.134",
+  "version": "1.0.137",
   "bin": "bin/git-span.exe",
   "man": [
     "man/git-span.1"
@@ -15,7 +15,7 @@
     "lint": "bash scripts/with-target-lock.sh shared env CARGO_BUILD_JOBS=1 RUSTFLAGS=\"-W unused -W dead-code\" CARGO_TARGET_DIR=\"${GIT_SPAN_CARGO_TARGET_ROOT:-$HOME/.cache/git-span/cargo-target}/git-span/check\" cargo clippy --quiet --locked -- -D warnings",
     "typecheck": "bash scripts/with-target-lock.sh shared env CARGO_BUILD_JOBS=1 RUSTFLAGS=\"-W unused -W dead-code\" CARGO_TARGET_DIR=\"${GIT_SPAN_CARGO_TARGET_ROOT:-$HOME/.cache/git-span/cargo-target}/git-span/check\" cargo check --quiet --locked",
     "bench:check": "bash scripts/with-target-lock.sh shared env CARGO_BUILD_JOBS=1 CARGO_TARGET_DIR=\"${GIT_SPAN_CARGO_TARGET_ROOT:-$HOME/.cache/git-span/cargo-target}/git-span/build\" cargo bench --no-run --locked --features bench-corpus",
-    "bench": "bash scripts/with-target-lock.sh shared env CARGO_TARGET_DIR=\"${GIT_SPAN_CARGO_TARGET_ROOT:-$HOME/.cache/git-span/cargo-target}/git-span/build\" cargo bench --locked",
+    "bench": "bash scripts/with-target-lock.sh shared env CARGO_BUILD_JOBS=1 CARGO_TARGET_DIR=\"${GIT_SPAN_CARGO_TARGET_ROOT:-$HOME/.cache/git-span/cargo-target}/git-span/build\" cargo bench --locked",
     "udeps": "bash scripts/with-target-lock.sh shared env CARGO_BUILD_JOBS=1 CARGO_TARGET_DIR=\"${GIT_SPAN_CARGO_TARGET_ROOT:-$HOME/.cache/git-span/cargo-target}/git-span/udeps\" cargo +nightly udeps"
   },
   "files": [
@@ -24,11 +24,11 @@
     "scripts/postinstall.js"
   ],
   "optionalDependencies": {
-    "git-span-darwin-arm64": "1.0.134",
-    "git-span-darwin-x64": "1.0.134",
-    "git-span-linux-arm64": "1.0.134",
-    "git-span-linux-x64": "1.0.134",
-    "git-span-win32-x64": "1.0.134"
+    "git-span-darwin-arm64": "1.0.137",
+    "git-span-darwin-x64": "1.0.137",
+    "git-span-linux-arm64": "1.0.137",
+    "git-span-linux-x64": "1.0.137",
+    "git-span-win32-x64": "1.0.137"
   },
   "repository": {
     "type": "git",