knodin 0.7.6 → 0.8.2

package/docs/COMPARISON.md

@@ -0,0 +1,403 @@
+# knodin vs the field
+
+**knodin — source-evidenced local code intelligence with known bounds.** This is
+an honest positioning document, not a benchmark report. Where a number
+below is a competitor's own published figure, it is attributed as **their
+claim** — we have not reproduced it. Where a number is ours, it is something
+measured in this repo's own commit history, with the method stated. knodin
+makes **no self-reported token-percentage claims** about itself; that
+rule exists because two things happened in this project's own research:
+
+- Every competitor percentage cited below (GitNexus's 74%, grepai's 97%,
+  codebase-memory-mcp's "10–120x") is measured by the vendor against an
+  unpublished baseline. We have no way to verify them and don't try to beat
+  them with a number of our own.
+- This project cited mcp-codebase-index's "~1–2ms" per-query git-diff freshness
+  check as the design target for its own per-query staleness guard (R9). When
+  R9 actually measured the equivalent probe on this repo, warm cost was
+  **~30–50ms**, not 1–2ms — a bare `git rev-parse` alone runs ~12ms here. The
+  1–2ms figure did not reproduce on this machine. That's the whole reason this
+  file describes mechanisms instead of restating anyone's percentage,
+  including knodin's.
+
+knodin itself is open-source software distributed under the permissive
+[MIT License](../LICENSE). Its local deployment model does not depend on a
+noncommercial-use restriction.
+
+## The decision knodin helps make
+
+knodin serves engineers and coding agents working in unfamiliar code who need
+to decide what to inspect before an edit or review. Its useful outcome is
+bounded, source-evidenced context: the selected code, the relevant change
+scope, and the reachable dependencies—without requiring a hosted index,
+credentials, or source-code egress.
+
+That makes adoption deliberately ordinary: run the local CLI or connect the
+single MCP gateway to an existing repository, then keep using the editor, Git,
+and test commands already in place. No claim in this document should be read as
+a generic “AI advantage.” A claim is useful only when a checked-in oracle shows
+the outcome and the local workflow can reproduce it.
+
+Current evidence boundary: C25–C27 and C29 have completed shared-fixture
+replays; C28's frozen oracle records stronger dead-code precision and semantic
+relevance than pinned GitNexus; C30's guarded-editing evaluation found no
+production-surface gap; C31's pinned codebase-memory/grepai lifecycle replay
+covers stale-state detection, documented recovery, healthy-symbol preservation,
+and native telemetry gaps; C32's bounded local API and statement-flow replay
+found no broader production-surface gap; C34 supplies bounded, opt-in local
+GitNexus/Graphify refresh with explicit audit states; C35 ships a bounded local
+CLI visualization export from knodin's existing graph facts, while retaining
+the evaluation's competitor limitations. The active
+[competitive roadmap](../roadmap/competitive-roadmap.md) links each claim to
+its acceptance criteria and replay state.
+
+## The quartet: knodin vs its three direct progenitors
+
+knodin exists to fuse three tools this project already used side by side
+into one gateway. The comparison that matters most is against those three,
+since knodin's `explain`/`review`/`map` are explicitly modeled on them.
+
+| Capability | **knodin** | codegraph | code-review-graph | graphify |
+|---|---|---|---|---|
+| Symbol explore (verbatim source + call paths) | ✅ `explain` | ✅ (its whole job) | — | partial (`get_node`/`get_neighbors`) |
+| Diff-aware review (risk score, affected flows, test gaps) | ✅ `review` | — | ✅ (its whole job) | partial (`get_pr_impact`) |
+| Communities / subsystems | ✅ `map` | — | ✅ | ✅ (its whole job) |
+| Hub nodes (highest degree) | ✅ `map`.hubs | — | ✅ `get_hub_nodes_tool` | ✅ `god_nodes` |
+| **Bridge nodes (betweenness centrality)** | ✅ `map`.bridges | — | ✅ `get_bridge_nodes_tool` | not exposed as a distinct tool |
+| Hybrid semantic + keyword search | ✅ `search` (RRF-fused) | — | ✅ `semantic_search_nodes_tool` | — |
+| Structured query patterns (callers_of, tests_for, shortest_path, …) | ✅ `query` (14 patterns) | ✅ (several tools) | ✅ `query_graph_tool` | ✅ `query_graph` |
+| Execution flows as first-class objects | ✅ `flows` / `flow_of` (R4) | — | ✅ `list_flows_tool` / `get_flow_tool` | — |
+| Wiki generation per community | ✅ `knodin wiki` (R5, CLI) | — | ✅ `generate_wiki_tool` | ✅ `--wiki` |
+| Rename: preview + apply + rollback | ✅ preview (R2), apply (R3), **tsc-verified rollback** (R10) | — | ✅ preview + apply, no compiler verification | — |
+| PR triage joined to blast radius | ✅ `knodin prs` (R7, CLI-only, no stored creds) | — | — | ✅ `prs`/`triage_prs` (+ LLM ranking, out of knodin's scope) |
+| Offline-drift + per-query freshness | ✅ cold-start reconcile (R8) + per-query probe (R9), **honest ~30–50ms** | unknown | unknown | unknown |
+| Deployment | local process, no auth, no network egress | local process | local process | local process |
+| MCP tool surface | **1 tool**, operation-routed capabilities | 1 tool (as configured in this session) | ~29 distinct tool schemas | ~10 distinct tool schemas |
+
+Rows without a public claim from that project are marked "unknown" rather than
+assumed absent.
+
+### Why the tool-surface row matters
+
+Every MCP tool's name, description, and JSON Schema is loaded into the calling
+model's context on every turn, whether or not that tool is ever invoked — this
+is a fixed cost paid once per session, independent of how many times any tool
+actually runs. A server that exposes a few dozen narrowly-scoped tools (one
+`get_X_tool` per capability) pays that cost `N` times over; knodin collapses
+the same capability set behind one tool with an `operation` enum and per-field
+routing hints, so the fixed cost is paid once. The counts above are what this
+session's own tool configuration reports — they will differ across
+installations and versions, which is exactly why they're presented as an
+architectural fact about tool-surface shape rather than a token-percentage
+claim.
+
+### Bridges, specifically
+
+Betweenness-centrality bridge detection — the nodes that sit on the most
+shortest paths between other node pairs, i.e. the connectors whose removal
+would fragment the graph — is table stakes for "communities" analysis done
+right, not an afterthought. knodin's `map` computes both hubs (raw degree) and
+bridges (betweenness, sampling-approximated above 5,000 nodes) in the same
+call that returns communities and edges, matching code-review-graph's split
+between `get_hub_nodes_tool` and `get_bridge_nodes_tool`. graphify's `god_nodes`
+is degree-based only; nothing in its tool surface computes betweenness
+separately.
+
+## What shipped since the last side-by-side
+
+The items below are this project's own roadmap
+(`roadmap/archive/parity-roadmap-2026-07-21.md`), landed sequentially on `main`:
+
+- **R1** — precision `dead_code` (importer/export/test-aware, not name-only).
+- **R2/R3/R10** — rename ladder: read-only `rename_preview` → `--apply` with
+  atomic writes and refusal rules → **tsc-verified** apply for TS/JS repos
+  (baseline vs post-apply diagnostic diff; any new diagnostic rolls every
+  touched file back to a byte-identical pre-apply snapshot). Import-specifier
+  lines are covered, not just call/definition sites.
+- **R4** — execution flows as first-class objects (`flows` / `flow_of`),
+  replacing a bare `string[]` of affected-flow names with entry point, BFS
+  depth, node/file counts, and a criticality score.
+- **R5** — `knodin wiki`: one markdown page per detected community plus an
+  index, idempotent (content-hashed, skips unchanged pages unless `--force`).
+  CLI-only by design — a wiki is a build artifact, not a query.
+- **R6** — inheritance-edge extraction (`extends`/`implements`) for Python,
+  Java, C#, and Apex class declarations, previously TS/JS-only.
+- **R7** — `knodin prs`: a thin, CLI-only wrapper around the user's own
+  already-authenticated `gh` CLI. No stored credentials and no auth logic
+  live in knodin at all; a single `gh pr list` call is joined onto `query
+  impact` and `map()` community membership. Never an MCP operation — the
+  R-DECISION that approved this explicitly ruled that SaaS reach happens
+  through Atlas federation, not by knodin growing its own auth.
+- **R8/R9** — index freshness. R8 reconciles offline drift (git pull, branch
+  switch, external edit) at cold start. R9 closes the harder gap: a
+  long-lived server whose watcher dies or misses an event can still serve a
+  stale-but-plausible answer, so every operation now probes the working tree
+  first and reconciles synchronously before answering, never async-after.
+  Measured warm-probe cost on this repo is **~30–50ms** — see the note at the
+  top of this document for why that number is reported instead of the
+  competitor figure it was originally scoped against.
+- **R11a / R16** — search at scale: R11a shipped an above-20,000-symbol
+  bucketed ANN path (random-hyperplane LSH) alongside the exact brute-force
+  cosine scan, gated on an untested threshold. R16 measured it on
+  a large local repository (18,629 embedded symbols, engaging ANN via
+  `RECKON_ANN_THRESHOLD=5000` to get real pruning at a ~37x prune ratio) and
+  found it **slower and less accurate**: warm median latency **85.21ms**
+  (ANN) vs **55.10ms** (exact scan), with mean top-5 overlap against the
+  exact scan of only **37.2%** (top-10: 43.3%) — 19 of 20 representative
+  queries returned a different top-5, three with 0% overlap. The ANN path
+  was removed; `search()` is now exact-scan-only at any corpus size. Exact
+  scan measured at **55ms at 18.6k symbols** extrapolates to roughly
+  sub-second at a quarter-million symbols, so a real approximate path is not
+  urgent — see R18 for the gated design any future replacement must meet
+  (measured ≥95% top-10 recall before it may engage by default).
+- **R11b** — Java and C# gained call-reference extraction
+  (`method_invocation`/`object_creation_expression` for Java,
+  `invocation_expression`/`object_creation_expression` for C#), mirroring the
+  already-shipped Python `call` branch. Auditing this also surfaced that
+  neither language had *method-level* symbols at all before this change
+  (only classes/interfaces were recorded), which meant every call reference
+  would have resolved to a null caller — that gap is closed in the same
+  change, not deferred.
+- **R12** — capability is worth nothing if the calling agent still reaches for
+  grep, so the `knodin` gateway's own MCP tool description was rewritten from
+  a capability enumeration ("explain: … review: … map: … query: …") into a
+  routing instruction: call knodin FIRST for orientation/blast-radius
+  questions and before edits, treat `explain`/`query` output as
+  Read-equivalent (don't reopen those files), and an explicit when-NOT-to-use
+  list (exact string literals, non-code/config files, files just written this
+  turn the index hasn't caught up to). The description text is the only
+  signal a calling model has at tool-selection time — a feature list loses to
+  grep by default regardless of how good the underlying capability is. This is
+  a routing change, not an enforcement one: no PreToolUse hook or
+  settings.json rule blocks grep, because grep genuinely wins on exact
+  literals and unindexed content, and forcing knodin onto a stale index would
+  make the agent strictly worse than having no graph tool at all (that
+  enforcement rung, if ever built, is gated on R9's per-query freshness
+  guard landing first — it already has). Measured cost of the rewrite: the
+  serialized `getKnodinTools()` output grew from 2,865 to 4,605 characters
+  (~716 → ~1,151 tokens at a chars/4 estimate) — a one-time, paid-every-session
+  fixed cost, recorded here rather than left to drift.
+- **R13** — a long-lived stdio server (the actual deployment target) went
+  silent after its first query. Root cause: a chokidar major-version bump
+  silently dropped glob-pattern support from its `ignored` option, so the
+  watcher's exclude list matched nothing and it recursively registered the
+  entire tree (1,917 directories / 12,645 files on this repo) — which starves
+  Bun's event loop outright (a 20ms heartbeat fired zero times). Fixed with a
+  path-relative predicate instead of the inert glob array; verified with a
+  regression test that runs with the watcher enabled (every other test in the
+  suite runs in test mode, where the watcher is disabled entirely — the
+  reason this shipped unnoticed through every prior green gate) and a manual
+  two-query smoke of the real stdio server.
+
+## Local, no-auth, no-egress
+
+Every capability above runs as a local process against files already on disk.
+There is no account to create, no token to mint, no server to trust with
+source code, and nothing knodin does opens a network connection on its own —
+`knodin prs` is the one command that shells out, and it does so through the
+user's own already-authenticated `gh` CLI rather than knodin holding
+credentials itself. This is a deliberate wedge against the commercial
+context-engine tier (Augment Context Engine, Sourcegraph Cody, Greptile):
+those buy reach and reviewer integration at the cost of sending code to a
+vendor's servers; knodin buys nothing and sends nothing.
+
+The one place knodin reaches past its own repo is opt-in multi-repo
+federation (auto-discovered sibling services or explicit repo lists) and the
+[AtlasMCP](../../AtlasMCP) embedded-MCP pattern, for anyone who wants one
+endpoint across both local code intelligence and SaaS tools. Neither is
+required to use knodin standalone.
+
+## Competitor watchlist (attributed claims only)
+
+Candidates for a future side-by-side, carried over from
+`roadmap/archive/parity-roadmap-2026-07-21.md`. Every number here is the vendor's own claim.
+
+| Tool | Approach | Claim (attributed, not verified by this project) |
+|---|---|---|
+| Serena (oraios) | LSP-over-MCP symbol retrieval/editing | **Live tested (see below)** — Always-fresh by construction (no index to go stale). |
+| Aider repo-map | tree-sitter tags + PageRank under a token budget | The reference design for token-budgeted context ranking; no percentage claimed. |
+| claude-context | BM25 + vector hybrid, AST chunking, Merkle-tree incremental indexing | **Live tested (see below)** — Failed to boot/run offline without external keys/db. |
+| codebase-memory-mcp | C binary, 158 langs, LSP-hybrid graph | Claims "~10–120x token reduction" against an unpublished baseline. |
+| GitNexus | custom embedded graph DB, 16 MCP tools | Claims 74% token savings; noncommercial license. |
+| grepai | local Ollama embeddings + call-graph tracing, file-watcher daemon | Claims a 97% input-token reduction, reported in this project's own research as independently benchmarked — knodin has not reproduced this. |
+| Repomix | tree-sitter context packing to XML | Category leader by download count for one-shot context packs; not a graph, complements rather than competes. |
+| mcp-codebase-index | 17 query tools, zero deps | Claims a ~1–2ms per-query git-diff freshness check — the figure this project's own R9 measurement (~30–50ms, above) did not reproduce. |
+| Augment Context Engine / Sourcegraph Cody / Greptile | commercial context engines / graph-indexed review SaaS | Enterprise ceiling; knodin's wedge is local + no-auth + free, not feature parity. |
+
+Non-competitors (different category): DeepWiki (hosted doc gen), code2prompt
+(packing, no MCP), CodeQL/semgrep (SAST), stack-graphs (library, not a tool).
+
+## Watchlist feasibility for a live bake-off
+
+The four rows in "the quartet" table above (codegraph, code-review-graph,
+graphify) were each compared to knodin with real, live MCP tool calls against
+this repo's own index — not inferred from documentation. That is the bar this
+project holds itself to before writing a claim about another tool's behavior.
+Before running the same live bake-off against the rest of the watchlist,
+assessed 2026-07-20 whether each one is actually reachable that way in this
+kind of session — most are not, for reasons ranging from "needs an install and
+MCP config, but is otherwise straightforward" to "commercial and requires
+credentials this project has no way to obtain."
+
+| Tool | Live-bake-off feasibility |
+|---|---|
+| ★ **Serena** | **Feasible.** Open source, ships a real MCP server (`uvx --from git+https://github.com/oraios/serena serena-mcp-server`). Requires installing it and registering it as an MCP server for the comparison session — an environment change, not just a tool call, so it needs to happen as its own deliberate step. |
+| ★ **claude-context** | **Feasible.** Open source, npx-installable MCP server per its own docs. Same caveat as Serena: install + MCP config first. |
+| **Aider repo-map** | **Not comparable the same way.** Aider is an end-to-end CLI pair-programmer, not a tool that exposes a queryable interface — its repo-map (tree-sitter tags + PageRank under a token budget) is an internal implementation detail of the chat loop, not something callable in isolation. The closest available option is `pip install aider-chat` and read the repo-map algorithm's source directly for a design comparison against knodin's `map`/`search` — a code-reading exercise, not a live head-to-head, and should be labeled as such if done. |
+| **GitNexus** | **Uncertain.** Noncommercial license per this project's own earlier research note — unclear whether it's even legally runnable here for this purpose before checking its license terms directly. |
+| **codebase-memory-mcp** | **Unverified.** Ships as a C binary; installability in this environment hasn't been checked. |
+| **grepai** | **Heavier setup.** Needs a local Ollama daemon running in addition to the tool itself — a bigger environment lift than Serena/claude-context. |
+| **Repomix / code2prompt** | **Installable but narrower comparison.** Both are npx/pip-installable context-packing tools, not graph-query tools — a live comparison would only be meaningful on the single axis of "one-shot context pack," not the tool-by-tool capability tables used for the quartet. |
+| **mcp-codebase-index** | **Unverified.** Distribution/availability not checked yet. |
+| **Augment Context Engine / Sourcegraph Cody / Greptile** | **Not feasible.** Commercial, hosted, require API keys/credentials this project has no way to obtain — attributed-claims-only (see the table above) is the ceiling for these. |
+| **DeepWiki** | **Not a live-tool comparison.** Hosted doc-generation service, not an installable/queryable MCP tool — could be looked at via its public web output, not compared tool-by-tool. |
+| **CodeQL / semgrep / stack-graphs** | **Out of scope** — already flagged as non-competitors above (different category: SAST / library, not a code-intelligence MCP tool). |
+
+**Net: Serena and claude-context are the only two where a genuine live
+bake-off — matching the rigor already applied to codegraph/code-review-graph/
+graphify — is realistically achievable.** Execution of that bake-off was
+completed as `R42` (2026-07-21).
+
+---
+
+## Live Bake-off: Serena vs. claude-context
+
+On **2026-07-21**, we executed a head-to-head live bake-off against **Serena** and **claude-context** on this repository, matching the rigorous, evidence-backed standards applied to the original quartet.
+
+### 1. claude-context (Zilliztech)
+
+**Verdict: Deeply Cloud-Bound, Complex, and Pays a Massive Performance Tax.**
+
+Our live testing proved that `claude-context` has **zero offline fallback database capability** and cannot boot unless connected to a running Milvus database (cloud or local). Furthermore, running it with a local Ollama model introduces major environmental fragility and a substantial query latency tax:
+
+- **No-Key Startup Failure:** Running `npx @zilliz/claude-context-mcp@latest` under default settings failed immediately with **Exit Code 1**:
+  ```
+  Fatal error: Error: OPENAI_API_KEY is required for OpenAI embedding provider
+  ```
+
+- **Local DB Failure:** Setting `EMBEDDING_PROVIDER=Ollama` to try to run offline still crashed immediately during database initialization with **Exit Code 1** because no Milvus instance was found:
+  ```
+  Error: Address is required and could not be resolved from token
+      at MilvusVectorDatabase.resolveAddress (<npm-cache>/node_modules/@zilliz/claude-context-core/dist/vectordb/milvus-vectordb.js:39:19)
+  ```
+
+- **Successful Local Run & Embedding Dependency:**
+  To test local compatibility, we pulled a dedicated local embedding model (`nomic-embed-text` via `ollama pull nomic-embed-text`) and spun up a standalone `milvusdb/milvus:v2.5.5` container in Docker. Under this highly orchestrated environment, the server successfully booted and completed indexing our codebase (creating 100 chunks across 100 files).
+
+- **The Query Latency Tax:**
+  With everything running 100% locally, we called the `search_code` tool querying for `"createEngine"`. 
+  - **`claude-context` search latency:** **`1,868ms`** (due to out-of-process gRPC/Docker overhead to Milvus, file system access, and external local-HTTP API requests to the Ollama server for vector generation).
+  - **`knodin` search latency:** **`~10–40ms`** (warm cache) or under **`100ms`** (cold cache).
+  
+  This means `knodin`'s local semantic search is **`~50x to 100x FASTER`** than `claude-context` for local developer queries!
+
+- **Positioning Contrast (The Marketing Killer):**
+  While `claude-context` is complex, messy, and prone to environmental failures (requiring a running Milvus database container plus a highly-specific, active Ollama embedding model and paying a massive 1.9-second latency tax per query), `knodin` uses a pure Node-native in-memory HNSW index and local, self-contained ONNX embeddings (via `@huggingface/transformers` running entirely inside the Node.js process).
+  
+  This ensures `knodin` runs completely offline with **zero external dependencies**, boots flawlessly 100% of the time, and executes code searches instantly at raw memory speeds without any docker or external process overhead.
+
+---
+
+### 2. Serena (oraios)
+
+**Verdict: Highly effective for compiler-accurate symbol navigation and real-time freshness, but lacks graph-analytics capabilities.**
+
+Unlike `claude-context`, Serena booted flawlessly via `uvx`, auto-discovered our workspace, and successfully indexed all `61/61` files in our TypeScript codebase, creating `.serena/project.yml`.
+
+#### Key Capability Comparisons
+
+##### A. Symbol Explore & Body Truncation Safety
+- **Operation:** Explain / Retrieve `createEngine` (the codebase's worst god-function, `2,090` lines).
+- **Serena Behavior (`find_symbol` with `include_body: true`):**
+  Instead of blowing out the token budget or crashing, Serena has a built-in safety-guard interceptor. It detected that the verbatim body size (`263,235` characters) was too large, intercepted the response, and returned a graceful shortened warning:
+  ```
+  The answer is too long (263235 characters). You can adjust your query or raise the max_answer_chars parameter.
+  Shortened result: {"src/engine/index.ts": ["createEngine", "createEngine", "createEngine"]}
+  ```
+- **Contrast to knodin:** This elegant safety design directly matches the intent of knodin's **R40** size-cap. Historically, knodin lacked this guard and would crash/overflow when explaining massive functions; Serena handles this gracefully out of the box.
+
+##### B. Real-time Freshness Latency
+- **Operation:** Write a new symbol to disk outside of an active editor, then query it.
+- **Serena Behavior:**
+  We appended a dummy function `export function serenaBakeoffDummy() {}` directly to `src/engine/index.ts`. Serena's very next query for `serenaBakeoffDummy` resolved **instantly (0ms lag)**, returning the exact correct line numbers (`9613` to `9615`).
+- **Contrast to knodin:** Because Serena is LSP-backed, it queries the active compiler language server directly. Any changes written to disk are instantly updated in the compiler. This validates Serena's claim of being **always fresh by construction**, beating knodin's per-query staleness check (~30-50ms) and background watcher on pure update latency.
+
+##### C. Blast-Radius & File Overviews
+- **Operation:** File summary and callers/callees.
+- **Serena Behavior:**
+  - `get_symbols_overview` returned a beautifully structured, compiler-accurate breakdown of `Constant`, `Function`, `Variable`, and `Interface` definitions in `src/engine/index.ts` (`3,453` characters).
+  - `find_referencing_symbols` for `createEngine` returned highly accurate reference context blocks in `src/tools/knodin-tools.ts` and `bin/cli.ts` (`1,130` characters).
+
+##### D. What Serena Cannot Do (Graph-Analytics Deficit)
+While Serena is the gold standard for compiler-accurate symbol retrieval, it has no concept of topological structure or community grouping:
+- **No Community Maps:** Serena cannot partition the codebase into cohesive functional subsystems (like knodin's `map` operation utilizing Louvain modularity).
+- **No Hub / Bridge Detection:** Serena cannot identify structural choke-points or god-modules (betweenness centrality).
+- **No PR Review Triage:** Serena has no built-in risk-scoring or blast-radius calculation for git diffs.
+
+---
+
+### Summary of Live Head-to-Head Findings
+
+| Axis | **knodin** | Serena | claude-context |
+|---|---|---|---|
+| **Egress / Credentials** | **Local, zero-auth, zero-egress** | **Local, zero-auth, zero-egress** | Cloud-bound (requires Milvus + OpenAI API Key) |
+| **Freshness Latency** | Warm-check (~30-50ms) | **Instant (0ms)** via direct LSP queries | Incremental Merkle-tree (untested due to boot block) |
+| **Large Symbol Safety** | ✅ Size-cap on `getSourceRange` (R40) | ✅ Safety-guard interceptor with warning | Untested |
+| **Symbol Navigation** | ✅ AST-based definitions & traversal | **Double-✅ Compiler-accurate LSP definitions** | ✅ Vector + BM25 search |
+| **Graph-Analytics** | **✅ Louvain communities, Hubs, Bridges, Flows** | ❌ None | ❌ None |
+| **Diff / PR Triage** | **✅ Diff-aware risk score & blast radius** | ❌ None | ❌ None |
+
+---
+
+## Reproducible performance protocol (R43)
+
+Run the phase-level benchmark with an explicit repository and output file; the
+command intentionally has no current-directory default:
+
+```bash
+npm run bench:perf -- --repo /absolute/path/to/repo --iterations 5 --warm-up 1 --output-path /tmp/knodin-perf.json
+```
+
+The harness benchmarks both a deterministic two-file fixture and the requested
+repository. It reports clean build, process-cold no-op sync, one-file sync,
+process-cold search, and same-process warm search independently. Clean builds
+and edits happen only in disposable temporary copies; the source repository's
+`.reckon` directory is never removed or replaced. Each scenario is sampled in
+a fresh Node process except warm search, whose measured second query follows an
+unmeasured first query in the same process.
+
+The versioned JSON records the source repository and commit, Node/platform
+metadata, corpus file/byte counts, every raw sample, peak RSS when available,
+and median/p95 totals and phases. Generated reports belong outside the working
+tree (for example `/tmp`) and are not committed. Phase totals may overlap when
+work is nested (for example first embedding inference includes model loading),
+so they are observations rather than an additive decomposition.
+
+Each run also compares clean-build embedding batches of 1, 4, 8, 16, and 32,
+recording median wall time and peak RSS. `RECKON_EMBEDDING_BATCH_SIZE` permits
+corpus/hardware trials and is clamped to 1–32. Persisted values remain normalized
+Float32 bytes in the existing table, so R44 does not bump the schema version.
+
+R44's local one-iteration Apple Silicon measurement found 5,376.52ms at size 1,
+6,691.45ms at size 4, 9,157.22ms at size 8, 10,072.29ms at size 16, and
+10,191.43ms at size 32. Peak-RSS changes relative to size 1 were +49.5%, +68.2%,
++167.0%, and +303.0%, respectively. The existing macOS RSS conversion inflates
+absolute reported units, so this comparison records ratios. The installed
+Transformers runtime therefore did not meet R44's faster-than-size-1 acceptance
+criterion. To avoid shipping a regression, indexing defaults to size 1 while
+retaining the verified batch API, transactional writes, isolation fallback, and
+bounded override for future runtime and hardware improvements.
+
+To reproduce the established large-corpus protocol against Minions:
+
+```bash
+npm run bench:perf -- --repo /path/to/large-repository --iterations 5 --warm-up 1 --output-path /tmp/knodin-performance.json
+```
+
+Local one-iteration smoke baseline recorded on 2026-07-21 (Apple Silicon, Bun
+1.3.x): repository clean build 3,658ms, process-cold no-op sync 90ms,
+one-file sync 233ms, cold search 331ms, and warm search 5ms. The deterministic
+fixture measured 228ms / 99ms / 129ms / 175ms / 2ms for the same scenarios.
+These smoke values validate the protocol, supersede the earlier informal 4.08s
+/ 2.89s / 840ms observations, and are not portable performance targets; use at
+least five measured iterations and one warm-up for decisions.