knodin 0.7.6 → 0.8.2

package/docs/COMPETITIVE-LANDSCAPE-2026-08.md

@@ -0,0 +1,267 @@
+# Reckon Graph — Competitive Landscape & Strategic Threat Assessment
+**Date:** 2026-08-01 · **Rev 2** (post-verification) · **Subject:** `reckon-graph` v0.4.3 (Docusign / DTS-Productivity-Engineering)
+**Status:** research assessment with corrections applied. Not a benchmark report. See §0 for what is verified and by whom.
+
+---
+
+## 0. Provenance and evidence discipline
+
+This document follows the attribution rule already established in `docs/COMPARISON.md`: a claim is either **verified in this repo**, **attributed to a vendor**, **independently measured**, or **unverified**. Rev 2 applies corrections from a verification pass run in a networked environment.
+
+### Four classes of claim, marked throughout
+
+| Mark | Meaning |
+|---|---|
+| **[repo]** | Read directly from the `reckon-graph` checkout. Highest confidence. |
+| **[independent]** | Measured by a third party with published methodology (JetBrains, arXiv preprints). |
+| **[vendor]** | The vendor's own claim. Not reproduced. |
+| **[survey]** | Observed in this research pass. **Absence of a finding is not proof of absence in the market.** |
+
+### Network limitation — scoped correctly
+
+The GitHub REST API was **unreachable from this research environment**, returning HTTP 403 with an explicit sandbox-policy body (`"GitHub access to this repository is not enabled for this session"`) — a network policy on my side, **not a GitHub outage and not a universal condition**. Rev 1 stated the caveat as though it were a fact about the world. It was a fact about my environment. A subsequent verification pass from a networked environment did reach the API.
+
+**Star snapshot — two sources, neither independently confirmed by me:**
+
+| Repository | Rev 1 (page reads / aggregators) | Verification pass, 2026-08-01 (live API) |
+|---|---|---|
+| `colbymchenry/codegraph` | 21,913 / 59.7k (disputed) | **63,942** |
+| `Graphify-Labs/graphify` | 30.6k / 76k (disputed) | **100,041** |
+| `Cranot/roam-code` | ~460 | **502** |
+| `GlitterKill/sdl-mcp` | ~301 | **457** |
+| `aovestdipaperino/tokensave` | ~249 | **523** |
+| `sverklo/sverklo` | ~76 | **76** |
+| `sdsrss/code-graph-mcp` | 44 | **60** |
+
+> ⚠️ **Two of these warrant a human sanity check before external use.** A 100,041-star count would place a niche code-graph MCP tool in roughly the top tier of all GitHub repositories, and 63,942 for a repo created in January 2026 is an extraordinary four-month trajectory. Both may well be correct — the AI-tooling hype cycle produces real outliers — but I could not confirm either, and Rev 1's assertion that the *lower* codegraph figure was "more credible" was an unsupported guess and is withdrawn. **Star counts move daily; timestamp any figure you reuse.**
+
+The separate warning about **AI-generated comparison spam in this category remains valid and unretracted** — aggregator blogs published figures differing from each other by 10–1000× (one checked case: `sdsrss/code-graph-mcp` cited at 16,000, actual double digits). That warning was about source quality, not API reachability.
+
+### Corrections applied in Rev 2
+Codebase-Memory paper figures (transposition + a fabricated detail) · MCP operation count (13 → 19) · cross-substrate impact demoted from capability to opportunity · all market-wide superiority claims rescoped to the surveyed set · TACO characterization softened and "peer-reviewed" removed · Amazon Q retirement narrowed · Claude Code "absorbed nothing" narrowed · Graphify version/license refreshed · vendor-percentage generalization narrowed.
+
+---
+
+## 1. What Reckon Graph is **[repo]**
+
+**A local, MIT-licensed code-intelligence MCP server that fuses four normally-separate jobs over one fresh SQLite graph, behind a single operation-routed MCP tool.**
+
+| Layer | Detail |
+|---|---|
+| **Deployment** | One local Node.js 24+ process. No account, hosted index, credential flow, source egress, or mandatory database/vector daemon. `.reckon/db.sqlite` per checkout; shared MiniLM ONNX model in the user cache. |
+| **MCP surface** | **Exactly one tool** (`reckon`) with **19 operation values** — verified in `src/context.ts:17-36` and `src/tools/reckon-tools.ts:216`: `explain`, `review`, `map`, `search`, `query`, `prs`, `context`, `wiki`, `docs`, `doctor`, `pack`, `compress`, `status`, `wait`, `worktrees`, `repair`, `repositories`, `system`, `telemetry`. *(Rev 1 listed 13, taken from the README rather than source.)* |
+| **Core jobs** | `explain` (edit-ready verbatim source + call paths + blast radius) · `review` (risk-scored diff context, four explicit scopes) · `map` (Louvain communities + hubs + betweenness bridges) · `context`/`search`/`pack`/`compress` (bounded retrieval and export). |
+| **Distinctive contracts** | Serialized **`responseBudget`** on every operation — byte/token/item limits, serialized size, truncation state, totals, continuation instruction; deterministic 4-bytes-per-token estimate, tested in `src/__tests__/unit/response-budget.spec.ts:35`. Explicit availability states (`no-match`, `not-initialized`, `empty-index`, `repair-needed`, `indexing`, `lifecycle-degraded`) that fail closed. Per-query freshness probe measured at **~30–50ms**, honestly qualified in `docs/COMPARISON.md:17`. |
+| **`compress` / `compress diagnose`** | Bounded, recoverable compression of build/test output under hard line + content-byte budgets, preserving exit metadata and detected signals with exact omission reporting — then mapping a retained failure back through the graph to owning symbols, tests, callers, and bounded source. |
+| **Parsers** | TS/JS, Python, Java, C#, **Apex**, SQL/PLSQL, Prisma, XML; structural indexers for **Salesforce metadata, Terraform/HCL, Dockerfile, dbt manifests, Workday Studio XML, LSIF**. Gaps: Go, Rust, PHP, Ruby, Kotlin, Swift, Bash, PowerShell — per `docs/LANGUAGE-SUPPORT.md`. |
+| **Scale-out** | `reckon repos discover/init/status/doctor`, `reckon system`, `reckon.yaml`. Live 61-repository bounded certification recorded in `roadmap/competitive-roadmap.md:100`. |
+| **Release posture** | npm + Homebrew tap + digest-pinned GHES assets. Signed-update machinery implemented; ceremony/drills open as C62–C67. |
+
+---
+
+## 2. The four-way squeeze
+
+| Category | Reckon surface | 2026 pressure |
+|---|---|---|
+| Symbol navigation | `explain`, `query`, `search` | 🔴 **Commoditized.** Many free local OSS servers. Serena still strongest via LSP. |
+| Change impact & review | `review`, `impact`, `tests_for`, `prs` | 🔴 **Squeezed both ends.** Free OSS ships risk-scored diff review; Greptile and CodeRabbit give away SaaS review at the free tier. |
+| Architecture mapping | `map`, `community`, `flows`, `wiki`, `visualize` | 🟠 **Being absorbed into products teams already buy.** SonarQube shipped Architecture (beta) inside its **$34/mo Team plan** [vendor]. DeepWiki is free for public repos. |
+| Retrieval & context | `context`, `pack`, `compress` | 🟢 **Bifurcated.** Packers are symbol-blind; graph servers never see a build log. **No tool in the surveyed set crosses that line.** |
+| **Platform substrates** *(not in the README taxonomy)* | Apex, SF metadata, Terraform, Workday XML | 🟢 **Least contested surface found**, and the one the docs undersell — `LANGUAGE-SUPPORT.md` frames it as a *limitations* matrix. |
+
+---
+
+## 3. Known competitors — what moved
+
+| Tool | Status change (2026) | Implication |
+|---|---|---|
+| **codegraph** (colbymchenry) | 🔴 **Converged on the one-tool thesis.** Lists `codegraph_explore` as its single default MCP tool with seven others functional-but-unlisted behind `CODEGRAPH_MCP_TOOLS`. Hosted-platform waitlist opened. Stars: see §0 snapshot. | **"Single operation-routed MCP tool" is no longer differentiating.** It is a shared design pattern. |
+| **codebase-memory-mcp** | 🔴 Now ships **Louvain community detection** and `detect_changes` (git diff → affected symbols with risk classification). **Published preprint** — arXiv:2603.27277, verbatim from the abstract: *"parsing **66 languages**… Evaluated across **31 real-world repositories**, Codebase-Memory achieves **83% answer quality versus 92%** for a file-exploration agent, at **ten times fewer tokens** and **2.1 times fewer tool calls**."* [independent, preprint — not peer-reviewed] | Two Reckon headline features replicated in a tracked competitor — **with a published methodology Reckon has not matched.** *(Rev 1 said "31 languages, 12 question categories." Both wrong: figures transposed, and "12 question categories" does not appear in the paper.)* |
+| **Graphify** | YC S26. **v0.9.31 (published 2026-07-30), Apache-2.0** per repository API. Leiden communities; `EXTRACTED`/`INFERRED`/`AMBIGUOUS` confidence tags; multi-modal ingest. Star figure disputed — see §0. | Its confidence-tier model is the closest analogue found to Reckon's evidence labeling. |
+| **GitNexus** | PolyForm Noncommercial; migrated to LadybugDB; 17 MCP tools; enterprise SaaS tier. | License remains the cleanest wedge here. Unchanged. |
+| **grepai** | Last release v0.35.0 (Mar 2026) — ~5 months quiet. | Deprioritize. |
+| **Serena** | Reference LSP-over-MCP implementation; no token budgets. | Unchanged: better freshness and compiler accuracy, no graph analytics. |
+| **Repomix** | v1.17.0 (Jul 2026). Tree-sitter "Code Compression" (**[vendor]** ~70% reduction), `--include-diffs`/`--include-logs`, `--token-count-tree`, `--split-output`, Agent Skills generation, two CVE fixes. ~26k★ / ~255k npm downloads/mo. | **`pack` alone is a commodity.** Repomix converged on nearly Reckon's `pack` feature set at far greater distribution. |
+| **Aider repo-map** | Algorithm essentially unchanged since 2023. | Still the reference design; still not an MCP surface. |
+
+---
+
+## 4. New entrants not tracked in-repo
+
+### Tier 1 — direct architectural twins
+
+| Tool | Threat | Why |
+|---|---|---|
+| **Sverklo** (76★, MIT, TS) | 🔴 Critical | **Closest competitor found.** Independently arrived at Reckon's *exact* stack — SQLite + `sqlite-vec` + local `all-MiniLM-L6-v2` ONNX — and its analytics set: `review_diff` risk-scores by symbol importance × coverage × churn; `audit` finds god nodes and hub files; `ctx_peek`/`ctx_slice` slice context. Adds bi-temporal memory Reckon lacks. **Its only clear weakness vs Reckon is 37 flat MCP tools.** [vendor] 180-task benchmark, F1 0.58 vs grep 0.34. |
+| **sdl-mcp** (457★, source-available) | 🔴 Critical | Ships an explicit **gateway mode (6 tools)** alongside 38 flat ones — attacks the one-tool differentiator directly. Its **"Iris Gate Ladder"** (four-rung context escalation with proof-of-need gating before raw source is released) is a more legible, productized articulation of Reckon's response-budget idea. |
+| **roam-code** (502★, Apache + open-core) | 🟠 High | `preflight` = blast radius + tests; `critique` consumes `git diff`; PageRank reranking (explicitly rejects embeddings); signed exportable index bundles. **145 MCP tools** — the best foil for the one-tool argument. Uniquely detects algorithmic anti-patterns (O(n²), N+1). |
+| **sdsrss/code-graph-mcp** (60★, Rust) | 🟠 High | SQLite + `sqlite-vec`, BM25+vector RRF, optional local Candle embeddings, **BLAKE3 Merkle incremental reindex**, dead code, impact analysis with risk classification, explicit "context compression for LLM token budgets." **A double-digit-star project matches the capability list.** |
+| **Code-Graph-RAG** (~2.3k★, MIT, Python) | 🟠 High | Restored and active at v0.0.535 after its GitHub-account outage. Its opt-in `READS_FROM`, `WRITES_TO`, and `FLOWS_TO` graph models environment variables, files, databases, sockets, network endpoints, and standard streams across nine language registries. This is a real gap versus Knodin's bounded TS/JS statement flow, but its Memgraph + Docker + optional Qdrant/model stack conflicts with Knodin's compact local architecture. The analysis is conservatively intra-procedural plus one argument/return handoff, not path-sensitive, and source-order limited across files. C78's local disposable prototype retained 100% precision but reached only 62.5% recall on its labeled TS/JS oracle, so Knodin retained C8 unchanged rather than persisting a partial static reachability graph. |
+
+### Tier 2 — adjacent, high momentum
+
+**CocoIndex** (~10.2k★) — incremental pipeline framework now shipping a code MCP with AST-aware incremental index, call graph, blast radius; per-row provenance, hash-of-code invalidation. **The most credible competitor found to Reckon's freshness/reconciliation story.** · **Semble** (~5.7k★, MIT) — 2 MCP tools, **static Model2Vec embeddings, no transformer**; [vendor] 250ms full index, 1.5ms query, NDCG@10 0.854. · **tokensave** (523★, Rust) — composite code-health score (acyclicity, Gini, modularity, DSM); **per-branch graph DBs with cross-branch diff**, no equivalent in Reckon. · **Axon** (~709★, stalled Mar 2026) — Leiden communities, symbol-level branch diffing, **change-coupling from 6 months of git history**; on archived KuzuDB. · **RTK** — PreToolUse-hook binary compressing Bash output across 15 agents; **closest competitor to `compress`**, and independently benchmarked — see §5. · **build-output-tools-mcp** — the only other tool found with **artifact-ID drill-back** from compressed build output, but LLM-summarized (non-deterministic), no hard budget, no omission accounting, and drill-back returns raw log text rather than owning symbols.
+
+**CodeFlow** (~3.7k★, MIT) — client-side interactive architecture map with
+dependency/blast-radius views and raw JSON export. Its README explicitly calls
+dependency resolution heuristic and warns that dynamic imports and runtime
+renames may be missed. A LinkedIn summary further claims that individual edges
+identify whether they came from Tree-sitter, a language parser, or regex, but
+that finer per-edge extractor identity was not found in the current repository
+or README and remains unverified. Knodin already returns edge provenance,
+confidence, exact-versus-heuristic labels, source evidence, and source lines;
+C77 adds a like-for-like replay to test communication and export fidelity rather
+than assuming a product gap.
+
+### Tier 3 — ecosystem facts
+🔴 **Kuzu is dead** — archived without notice Oct 2025; an EC filing revealed an Apple acqui-hire. Successors: LadybugDB, FalkorDB Lite, Lance Graph. **Reckon's plain-SQLite choice is now a concrete talking point.** · 🟠 **SCIP moved to independent open governance (Mar 2026)** with a Meta/Uber/Sourcegraph steering committee. It is the durable interchange format and the precision upgrade path competitors are taking. **Reckon supports LSIF, which SCIP supersedes — a closable gap.**
+
+### Dead / stalled
+er77/code-graph-rag-mcp (archived) · mcp-language-server (last release May 2025) · VectorCode · code2prompt · files-to-prompt · **CodeSee** (→GitKraken 2024, sunset) · **Structure101** (→Sonar Oct 2024, explicitly no longer sold).
+
+---
+
+## 5. The commercial tier restructured
+
+| Player | 2026 state | Egress | Floor |
+|---|---|---|---|
+| **Sourcegraph** | Split from **Amp** into separate companies (Dec 2025). **Cody Free/Pro deleted.** MCP server GA (Feb 2026) with SCIP-precise navigation; **Code Finder** [vendor] 2.19× faster, up to 40% fewer tokens than agents searching locally. | Self-hosted = none | **$16K/yr** |
+| **Augment** | Pivoted to **Cosmos** orchestration; killed completions Mar 2026; individual plans eliminated. Context Engine survives ([vendor] 33% fewer tokens). | SaaS, indexed on their infra | $100/mo flat |
+| **Greptile** | $25–30M raised, Benchmark-led. Explicit graph-based context → impact analysis. MCP server. Reads `CLAUDE.md`. | Self-host incl. air-gapped (Ent.) | Free tier / $30 seat |
+| **Qodo** | **DeepCodeBench** [vendor] (1,144 PR-derived questions): Qodo 80% fact recall vs Claude Code 64%, Gemini CLI 45%. | **On-prem supported** | ~$0.012/credit |
+| **CodeRabbit** | [vendor] $40M ARR, ~700% YoY, 8,000+ paying customers. Weakest graph story — no published architecture. | SaaS; self-host Ent. only | Free / $24 user |
+| **Cursor** | Trained its **own embedding model** on agent session traces: [vendor] +12.5% accuracy, +2.6% code retention on 1,000+ file repos. **Explicitly says it does not replace grep.** | SaaS, server-side chunking | $20/mo |
+| **Windsurf** | Cognition acquired the remnant; **became Devin Desktop (Jun 2026)**. Cascade retired; Devin Local rewritten in Rust. | SaaS + VPC Ent. | Free / $20 |
+| **Amazon Q Developer** | **IDE plugins and paid subscriptions** are being retired — new signups blocked May 2026, support ends Apr 30 2027, replaced by **Kiro**. **AWS explicitly states Q Developer in the AWS console and other first-party experiences is unaffected.** *(Rev 1 said "being retired" flatly — overbroad.)* | — | — |
+| **DeepWiki** | Free, no auth, every public GitHub repo. MCP server. | Hosted only | **$0** |
+
+> **The wedge, precisely.** In the surveyed set, nobody paid competes below $30/seat except the agent vendors themselves. **Reckon's "free + local + no-egress" wedge holds against the commercial tier** — and is gone against OSS, where it is the baseline every entrant leads with.
+
+### Adjacent tiers
+Every DSM/architecture vendor MCP-enabled within ~6 months: Lattix 2026.0, NDepend (Feb 2026, open-sourced), CAST Imaging ($10.5K–$810.8K/yr), vFunction 4.5, and **Moderne** (local stdio MCP, Apr 2026 — auto-configures Claude Code/Cursor/Windsurf; [vendor] a Java 8→25 migration going 61M→30k tokens). **"Local graph + MCP server" became a checkbox in H1 2026.**
+
+**SonarQube is the most dangerous long-tail threat:** Architecture (beta) + MCP GA + AI Code Assurance inside a **$34/month** product a large share of enterprise teams — including Docusign, per this repo's own `sonar-project.properties` — already license.
+
+### Platform substrates — leg by leg
+
+| Substrate | Served? | Assessment |
+|---|---|---|
+| **Apex source graph** | 🟢 Open | Salesforce Code Analyzer v5 + Graph Engine is *violation-shaped*, not navigable — **no caller/reference API found in the surveyed set**. SFGE remains Developer Preview and its per-entry-point timeout was cut 15 min → 30 s, with Salesforce conceding "some complex code violations may be missed." |
+| **SF metadata graph** | 🟡 Contested | Elements.cloud, Salto, Panaya, Copado Agentia, Gearset Org Intelligence all claim it. **Every vendor examined in this pass requires live-org credentials**; none was found operating from a local checkout with no org connection. Window: ~12–18 months. |
+| **Terraform / HCL** | 🟢 Largely open | **No local-checkout Terraform dependency analyzer for agents found in the surveyed set.** HashiCorp's official Terraform MCP server is registry/HCP-oriented per its own reference docs. `terraform graph` emits DOT with no agent surface. |
+| **dbt** | 🔴 Solved | **Do not lead with dbt.** Official `dbt-mcp` ships local *and* remote **column-level lineage**. Reading `manifest.json` gets node-level lineage dbt already exposes better. |
+| **Workday Studio XML** | 🟡 Open | **No Studio-XML static analyzer found in this pass.** Workday's June 2026 agent launch is about *building* agents, not *understanding* existing assemblies. Tiny, shrinking market. |
+
+> **Cross-substrate impact is an opportunity, not a shipped capability. [corrected]**
+> Reckon demonstrably indexes Terraform, dbt manifests, Salesforce metadata/Apex, and Workday inputs **independently**. Rev 1 listed *"Terraform → dbt → Salesforce field → Apex trigger"* cross-substrate resolution in the implemented-differentiator matrix. **A verification pass found no implementation, test, or documentation establishing that chain.** Correct framing: *Reckon has the ingredients for cross-substrate analysis; a demonstrated end-to-end cross-substrate path remains an opportunity* — and would need a checked-in replay before it appears in any external claim. This matters because `CLAUDE.md` explicitly forbids describing the engine as planned or almost-done.
+
+---
+
+## 6. The research that should change the pitch
+
+**Three primary studies, supported by two additional preprints.** *(Rev 1 said "three studies" and then listed five.)*
+
+**① "Token Reduction Is Not Cost Reduction" — arXiv:2607.12161 (Jul 2026) [independent].** 2,908 Claude Code runs, 103 tasks, 7 repos, 3 models. Evaluated RTK, RTK-ML, Headroom, plus lexical/embedding/structural retrieval.
+- Removing **38.4% of tool-output tokens produced a +6.8% cost *increase*** (95% CI [+2.8, +11.3]).
+- Token reduction correlated with cost change at **r = 0.15** — essentially zero.
+- **Prompt cache ≈ 87% of reconstructed cost.** Compressing uncached output attacks a small slice *while invalidating the cache.*
+- **Compression destroyed verbatim edit anchors: patch application fell 27/40 → 15/40.**
+
+**② JetBrains independent RTK trial (Jul 2026) [independent].** Pre-registered, paired A/B, 86 tasks, 425 billed trials. Low effort: **+7.6% cost** (p=0.004). High effort: ~0%. Output quality statistically equivalent. **RTK's own analytics reported "96.2M tokens saved" while the bill went up.**
+
+**③ ContextBench — arXiv:2602.05892 (Feb 2026) [independent].** 1,136 tasks, 66 repos, 8 languages, human-annotated gold contexts. Headline: *"sophisticated agent scaffolding yields only marginal gains in context retrieval."* **Adverse to the entire category, Reckon included.**
+
+*Supporting:* **TACO** (arXiv:2604.19572) — *"A Self-Evolving Framework for Efficient Terminal Agents via Observational Context Compression."* Learns compression rules from execution trajectories and preserves error/failure-signal outputs unchanged — the same invariant as Reckon's "preserve detected diagnostics." **Reports task-dependent token reductions with maintained or improved success rates; the abstract was not machine-readable at verification time, so no specific percentage is quoted here, and it is a preprint, not peer-reviewed.** *(Rev 1 characterized it as "peer-reviewed" with a clean "~10% per step" figure — both overstated.)* · **"Notation Matters"** (arXiv:2605.29676) — TOON/TRON encodings buy 18–27% at 9–14pp accuracy cost; Markdown/JSON/XML is the right call.
+
+> **What to do with this.** The 27/40→15/40 patch-application collapse is a **correctness** failure caused by lossy, unrecoverable compression — the exact failure mode that bounded, recoverable, exact-omission-accounted compression is designed to prevent. That is a falsifiable, benchmark-backed pitch. A percentage is not. **Many surveyed vendor token-reduction claims are self-measured against undisclosed baselines** — that is a characterization of the sampled set, not a universal law *(Rev 1 said "every," which the report's own independent citations contradict)*.
+>
+> Two facts make `responseBudget` load-bearing: **Claude Code's ~25K-token tool-result ceiling** is documented in `anthropics/claude-code#45770` — *an issue report, not a formal product contract* — and the **MCP spec has no standardized response size limit** (open discussion `modelcontextprotocol#2211`). Every native truncation mechanism surveyed is destructive with no recovery handle.
+
+---
+
+## 7. Differentiator erosion matrix
+
+Rescoped: **✓ holds** now means *"no equivalent found in the surveyed set"*, not market-wide uniqueness.
+
+| Claimed differentiator | Status | Detail |
+|---|---|---|
+| Single operation-routed MCP tool | ✗ **Gone** | codegraph (1 default tool), sdl-mcp (gateway mode), pathfinder (7), Semble (2), probe (4). **Retire as the headline.** |
+| Local, no-auth, no-egress | ✗ **Baseline** | Nearly every OSS entrant leads with it. Still a hard moat vs. every commercial player except self-hosted Sourcegraph, self-hosted Greptile, on-prem Qodo. |
+| Diff-aware review with risk scoring | ✗ **Gone** | Sverklo `review_diff`, codebase-memory-mcp `detect_changes`, roam `preflight`/`critique`, jCodeMunch, sdsrss, Greptile. |
+| Louvain communities / subsystem mapping | ✗ **Gone** | codebase-memory-mcp, Axon & Graphify (Leiden), SonarQube Architecture, DeepWiki. |
+| Local ONNX embeddings · SQLite graph store | ✗ **Gone** | Sverklo uses the *identical* model on the identical stack. Semble's Model2Vec is faster still. |
+| Context packing (`pack`) | ✗ **Gone** | Repomix, at far greater distribution, with Tree-sitter compression, diff scopes, split output, token trees. |
+| Hub / bridge betweenness centrality | ~ **Partial** | roam (PageRank), Sverklo `audit`, tokensave (Gini/DSM), Axon. **True betweenness specifically remains uncommon in the surveyed set.** |
+| Truthful serialized response budgets | ~ **Partial — best remaining graph claim** | sdl-mcp's Iris Gate Ladder is the only close analogue found, and it is more legible. Others offer `limit`/`offset` — pagination, not a budget. **No surveyed MCP server emits truncation state + continuation instruction.** |
+| Explicit availability / freshness states | ✓ **No equivalent found** | `repair-needed`, `lifecycle-degraded`. Surveyed graph servers index and go quiet; CocoIndex has provenance but no fail-closed availability contract. |
+| Recoverable bounded command-output compression | ✓ **No equivalent found** | RTK: bounded, partial recovery, no symbol drill-back. build-output-tools-mcp: recoverable but LLM-summarized. Headroom: returns the original chunk, not symbols. |
+| `compress diagnose` — failure → owning symbols / tests / callers / source | ✓ **No equivalent found in the surveyed set** | The surveyed landscape is bifurcated: log compressors are symbol-blind; code-graph servers never see a build log. *(Rev 1 said "UNIQUE" — withdrawn as unprovable.)* |
+| Apex + SF metadata from a local checkout, no org credentials | ✓ **No equivalent found** | Every Salesforce metadata vendor examined requires a live org connection. |
+| ~~Cross-substrate impact~~ | ⚠️ **REMOVED — opportunity, not capability** | **No implementation, test, or documentation found establishing the Terraform → dbt → SF field → Apex chain.** Must not appear as a current capability until a checked-in replay demonstrates it. |
+
+> **Honest summary.** Every *individual* graph feature is replicated in free OSS. What remains uncommon in the surveyed set is **(a)** the combination in one process — no single competitor found has all six of gateway + budgets + diff-review + communities + centrality + local embeddings; **(b)** the contracts — budget truthfulness, fail-closed availability, exact omission accounting, all verifiable in-repo; and **(c)** substrate coverage. **(a) is a race. (b) and (c) are the defensible ground** — and (b) is the only one backed by checked-in tests today.
+
+---
+
+## 8. Ranked threat assessment
+
+| # | Threat | Severity | Horizon | Why |
+|---|---|---|---|---|
+| 1 | **Generic code-graph floor collapsed to $0** | 🔴 Critical | Now | codegraph, Sverklo, sdsrss, CodeGraphContext, roam all ship free, local, MCP-native graphs with impact analysis. |
+| 2 | **Competitors published methodology; Reckon hasn't** | 🔴 Critical | Now | codebase-memory-mcp has a preprint with a reproducible protocol; Qodo has DeepCodeBench. Methodology is the scarcest asset in this market — and Reckon's replay harness already exists to produce it. Self-inflicted. |
+| 3 | **SonarQube absorbs architecture mapping into $34/mo** | 🟠 High | 6–12 mo | In a product Docusign already runs. The internal adoption argument gets harder. |
+| 4 | **Sverklo-class convergence** | 🟠 High | 3–9 mo | An independent project reached the same stack and analytics set. Feature-level differentiation has a short half-life. |
+| 5 | **LSIF-only while SCIP takes over** | 🟠 High | 6–12 mo | Concrete and closable. |
+| 6 | **Salesforce metadata window closing** | 🟡 Medium | 12–18 mo | Salesforce ships DX MCP toolsets monthly; Copado shipped a Context Hub Apr 2026. |
+| 7 | **Free SaaS review from Greptile / CodeRabbit** | 🟡 Medium | Now | `review` is the most contested capability Reckon has. |
+| 8 | **ContextBench's "bitter lesson"** | 🟡 Medium | Structural | Category ceiling may be lower than assumed. Argues for narrow, provable claims. |
+| 9 | **Agent-native absorption** | 🟢 Low-Med | 12–24 mo | Asymmetric — see below. |
+| 10 | **Indexing-cost undercut (Model2Vec)** | 🟢 Low | 12 mo | Onboarding-friction perception, not correctness. |
+
+### On absorption — narrowed
+
+**Semantic retrieval over a single repo is being absorbed. Precise, persistent, cross-repo symbol graphs are not.**
+
+*For:* Cursor built and shipped its own embedding model default-on. GitHub bundles Copilot Spaces + repo overview + code review inside the seat price. Gemini Code Assist Enterprise indexes private repos. DeepWiki is free for public repos.
+
+*Against:* **Neither Claude Code nor Codex documents a persistent repository index** — Claude Code's changelog through Jul 2026 shows no codebase-indexing entries, and reporting indicates Anthropic removed an early local vector DB in favor of agentic search. *(Rev 1 said they had "absorbed nothing" — "no persistent repository index documented" is the defensible version; absence of documentation is not proof of absence.)* Sourcegraph's CodeScaleBench [vendor]: Sonnet 4.6 + Sourcegraph MCP at 0.698 / $1.02 per quality point vs a frontier model with no retrieval at 0.568 / $1.83. Every vendor standardized on **MCP as the seam**.
+
+> **Conclusion: target Claude Code and Codex users, not Cursor users.** `reckon init` already configures Claude Code, Codex, Gemini CLI, and Antigravity — that targeting is correct and should be explicit in the positioning.
+
+---
+
+## 9. Recommendations
+
+### Reposition
+1. **Retire "single operation-routed MCP tool" as the headline.** Keep it as a design fact; keep roam-code's 145 tools as the foil.
+2. **Lead with the compression↔graph join.** `compress diagnose` has no equivalent in the surveyed set and is currently buried in README paragraph 2.
+3. **Reframe "no token-percentage claims" from caveat to pitch.** Cite arXiv:2607.12161 and the JetBrains RTK trial. Lead on determinism, exact omission accounting, preserved edit anchors, recoverability.
+4. **Promote the substrate story out of the appendix** — but describe it as *coverage*, not as a demonstrated cross-substrate chain. Drop dbt from the lead.
+5. **Name the target agent explicitly:** Claude Code and Codex.
+
+### Build
+6. **Publish the benchmark.** Highest ROI available. `bench:competitive`, the replay harness, and `benchmarks/evaluations/` already exist; codebase-memory-mcp's protocol (31 repos, 66 languages, quality-vs-tokens curve) is an adaptable template.
+7. **Add SCIP import alongside LSIF.** Mechanically small, strategically disproportionate.
+8. **Run a live bake-off against Sverklo** — same bar already applied to Serena and claude-context.
+9. **Build the cross-substrate replay** — if the Terraform → dbt → SF → Apex chain is the strategic bet, it needs a checked-in oracle before it can be claimed at all. Currently it is the largest gap between the story and the evidence.
+10. **Add git-history signals to `review`** (change-coupling, churn-weighted risk).
+11. **Evaluate Model2Vec vs MiniLM ONNX**, given R44 already found batching made indexing worse.
+
+### Watch
+**Moderne** (closest strategic overlap in the commercial tier) · **SonarQube Architecture** (commoditization vector for `map`) · **sdl-mcp's Iris Gate Ladder** (better articulation of the budget idea) · **`modelcontextprotocol#2211`** (if the spec standardizes budgets, Reckon should be cited as prior art rather than made redundant).
+
+---
+
+## Appendix — verification register
+
+| Claim class | Confidence | Note |
+|---|---|---|
+| Reckon capability set, 19 operations, `responseBudget` contract, ~30–50ms probe, 61-repo certification | **High [repo]** | Read from source; operation enum confirmed at `src/context.ts:17-36` |
+| Cross-substrate impact chain | **NOT SUPPORTED** | No implementation, test, or doc found. Removed from the matrix. |
+| arXiv figures (2607.12161, 2602.05892, 2603.27277) | **High [independent]** | Transcribed from abstracts; preprints, not peer-reviewed |
+| TACO (2604.19572) | **Low** | Abstract not machine-readable at verification time; no figure quoted |
+| Star counts | **Unconfirmed by me** | Two sources in §0; GitHub API blocked from this environment. Two figures flagged as extraordinary. **Timestamp anything you reuse.** |
+| Vendor claims and percentages | **Attributed only** | Many self-measured against undisclosed baselines |
+| Commercial pricing | **Med-High** | Public pricing pages; enterprise floors directional |
+| Acquisitions / EOL | **High** | Press releases and vendor statements; Amazon Q narrowed to IDE plugins + paid subscriptions |
+| "No equivalent found" statements | **Survey-scoped** | Bounded by what this pass examined. **Not market-wide nonexistence.** |

package/docs/CONTAINED-EXECUTION.md

@@ -0,0 +1,77 @@
+# Profile-based contained execution
+
+`knodin` can execute one immutable repository-defined profile through the
+single MCP gateway. It never accepts a command string, executable, argv, cwd,
+environment, or limit from an MCP caller.
+
+Execution is disabled by two independent defaults. Enable it globally in
+`$XDG_CONFIG_HOME/knodin/execution.json` (or
+`~/.config/knodin/execution.json`):
+
+```json
+{"execution":{"enabled":true}}
+```
+
+Then define and enable exact profiles in `.knodin/execution.json`:
+
+```json
+{
+  "execution": {
+    "enabled": true,
+    "profiles": {
+      "test": {
+        "executable": "/opt/homebrew/bin/bun",
+        "args": ["run", "test"],
+        "network": "deny",
+        "timeoutMs": 120000,
+        "maxOutputBytes": 2097152,
+        "maxProcesses": 1,
+        "containment": "fully-contained"
+      }
+    }
+  }
+}
+```
+
+An agent may call `{ "operation": "execute", "profile": "test" }`. Profile
+names are bounded identifiers. Shell strings and caller-supplied argument
+suffixes are not part of the schema.
+
+## Containment contract
+
+The initial certified adapter is macOS `sandbox-exec`. It runs with a minimal
+environment (`PATH`, `LANG`, `LC_ALL`, and repository-local `TMPDIR`), closed
+stdin, no shell, repository cwd, a detached process group, hard timeout and
+combined-output caps, and Seatbelt rules that:
+
+- deny all network operations;
+- deny process forks, making `maxProcesses: 1` a hard contract;
+- deny all writes outside the repository;
+- deny reads under user homes, mounted volumes, network mounts, and shared
+  temporary roots outside the repository; and
+- allow repository reads/writes and read-only system runtime paths required to
+  load the approved executable.
+
+Profiles needing child processes are rejected by this first contract. Define
+the profile around a single-process test/lint/typecheck/build executable. The
+macOS adapter reports `fully-contained` only when every configured boundary is
+active. It also reports that `sandbox-exec` is deprecated; this certification
+is tied to the checked-in adversarial tests, not a claim that Seatbelt is a
+supported public Apple API.
+
+Linux and Windows currently report `containment-unavailable` and do not spawn
+the profile. A future Bubblewrap or Windows Job Object/restricted-token adapter
+requires its own native evidence before it can change that result.
+
+## Output, diagnosis, and audit
+
+Captured stdout/stderr goes directly through recoverable compression. Failed,
+timed-out, and output-limited MCP executions then request source-evidenced
+failure diagnosis from the existing graph. Raw command text, argv, environment,
+and output are never written to execution telemetry. The private repository
+audit `.knodin/execution-audit.jsonl` records only timestamp, profile identity,
+status, exit/signal, reported containment, and retained output-artifact identity.
+
+Repository code can still be destructive inside the authorized repository.
+This is a constrained trusted-repository workflow, not a guarantee that an
+approved test/build profile cannot modify its own checkout.

package/docs/DIAGNOSTICS.md

@@ -0,0 +1,80 @@
+# Local troubleshooting diagnostics
+
+knodin can retain a small, local diagnostic journal and build a redacted bundle
+for a user to inspect and share with support. Diagnostics are disabled until the
+user enables them, never upload automatically, and require no account or hosted
+service.
+
+```bash
+knodin diagnostics enable --retention-days 14
+knodin diagnostics status
+knodin diagnostics preview --since 24h
+knodin diagnostics archive --since 24h
+knodin diagnostics inspect .knodin/diagnostics/knodin-diagnostics-….json.gz
+knodin diagnostics clear
+knodin diagnostics disable
+```
+
+`enable` records bounded failure envelopes from the CLI and MCP gateway. Each
+record contains a timestamp, random correlation ID, surface, operation, phase,
+safe error name/code, a message fingerprint, and sanitized stack shape. It does
+not retain the command arguments, query, error message, source, raw output,
+environment, username, repository path, or source paths. Records are stored in
+`.knodin/diagnostics/events.jsonl`, mode `0600`, capped at 500 events, and
+pruned to the configured 1–365 day retention window.
+
+`preview` runs local installation and deep graph diagnostics and returns the
+exact allowlisted payload that `archive` writes. (`collect` remains a compatible
+alias for `archive`.) The default window is 24 hours; `--since` accepts hours or
+days. Bundle output must remain inside the current checkout and cannot traverse
+a symlink. Linked worktrees therefore retain separate trace journals and
+archives even when they share Git objects.
+
+Preview persists a private, content-addressed snapshot and returns its
+`previewId`. Pass `--preview-id <id>` to `archive` to write those exact inspected
+contents without recollecting timestamps or health state. The checkout retains
+at most eight previews, seven days, and 2 MiB in aggregate; older or excess
+entries are pruned inside two alternating private store slots after each
+preview. Each slot is capped at 1 MiB, preserving one prior valid generation
+while keeping the aggregate at 2 MiB. Retrieval treats both generations as one
+eight-preview window. Symlinks are never followed.
+
+Private diagnostic writes use a short-lived local helper bound to the validated
+destination parent. The helper proves the parent device and inode with a random
+nonce before knodin sends any payload bytes, then bounded-writes with
+no-follow/exclusive descriptors, fsyncs, and returns an identity-bound receipt.
+Malformed, crashed, displaced, or overdue helpers fail closed; there is no
+pathname-write fallback and no network activity.
+
+The schema-v2 bundle is gzip-compressed JSON, written mode `0600`, and includes
+a human report plus logical runtime, health, repository-scale, MCP-trace, and
+failure files. Its manifest names every logical file and field, exact UTF-8 byte
+size, retention rule, explicit-allowlist policy, omissions, and unavailable
+sections. `inspect` validates the manifest and compressed/uncompressed bounds
+before returning its contents.
+Users should inspect the bundle before attaching it to Jira, GitHub, email, or
+another support channel. knodin does not transmit it.
+
+`clear` removes only the event journal. It does not delete previously created
+bundles or ROI telemetry. `disable` stops future failure recording but preserves
+existing events so disabling never silently destroys troubleshooting evidence.
+Run `clear` when deletion is intended.
+
+Diagnostics are evidence, not runtime-causality proof. Message fingerprints can
+group identical sanitized failures but cannot reconstruct the original message.
+The default bundle does not pass arbitrary doctor, graph, telemetry, lifecycle,
+or future diagnostic fields through a sanitizer. A fixed allowlist admits only
+aggregate repository scale, classified health/freshness, safe runtime versions,
+bounded failure envelopes, and C89 request/trace lifecycle fields. Source,
+diffs, raw or external paths, credentials, environment values, usernames,
+command output, Git remotes/messages, and arguments have no output slot. New
+fields fail closed until the allowlist, schema, privacy fixture, and tests are
+updated together. Automated redaction cannot certify arbitrary future fields,
+so users must still inspect the preview before sharing.
+
+The same preview/archive builder is exposed through MCP with
+`operation: "diagnostics"`, `telemetryAction: "report"` for preview or
+`telemetryAction: "export"` for archive, and an
+optional `sinceHours` that is interpreted as the evidence window in hours. Pass the
+preview's ID as `artifactId` when archiving the exact snapshot. Both surfaces are bounded, local, credential-free, and
+perform no upload or other network action.

package/docs/GIT-HISTORY-REVIEW.md

@@ -0,0 +1,39 @@
+# Bounded Git-history review signals
+
+`knodin review` and the MCP gateway's `review` operation return `signals` beside
+the compatibility `riskScore`. The signal groups stay separate:
+
+- `graphImpact`: changed files and affected flows from indexed relationships;
+- `testGaps`: missing test-path/reference facts;
+- `structuralCentrality`: inbound, outbound, and total indexed references for
+  each changed symbol;
+- `history`: rename-aware churn, co-change commit facts, and coupling ratios.
+
+History output includes the exact contributing commit IDs, availability,
+confidence, configured bounds, commands executed, analyzed counts, truncation,
+and explicit omissions. Results are sorted deterministically. CLI and MCP output
+also retain the review's graph `staleness` field.
+
+## Bounds and unavailable states
+
+The defaults are 250 commits, 25 changed files, 100 related-file facts, a
+2-second timeout per Git command, and an 8 MiB output ceiling. Review uses one
+bounded `git log` pass after HEAD and shallow-state probes, and caches facts by
+repository, HEAD, requested files, and bounds. User-provided file paths must be
+repository-relative; revisions never enter the history command.
+
+`shallow`, `unborn`, `git-unavailable`, `not-a-repository`, `timeout`, and
+`unavailable` are explicit. Missing history never produces synthetic commits or
+coupling. Shallow results contain only locally present commits and disclose that
+omission. Commit, file, and related-file truncation likewise names what was
+omitted and why.
+
+## Interpretation limit
+
+Co-change and coupling show correlation in the inspected history only. They do
+not assert causation, defect likelihood, ownership, or mandatory remediation.
+Treat them as review context alongside graph impact, test gaps, and structural
+centrality—not as an opaque score or automated decision.
+
+The reproducible synthetic-DAG evidence, raw replay, resource measurement, and
+verifier are under `benchmarks/evaluations/c85-git-history/`.