carto-md 2.0.7 → 2.0.9

package/docs/anci/v0.1-DRAFT.md

@@ -0,0 +1,420 @@
+# ANCI v0.1 DRAFT — Architecturally Normalized Code Index
+
+> **Status:** DRAFT (unstable). Do not depend on this format in production
+> consumers without pinning to a specific carto-md version. The wire
+> format may change in any direction up to v1.0.
+>
+> **Spec:** v0.1.0-DRAFT
+> **Reference implementation:** carto-md ≥ 2.0.9
+> **Editor:** [@theanshsonkar](https://github.com/theanshsonkar)
+> **License:** MIT (the spec itself)
+> **Repository:** https://github.com/theanshsonkar/carto
+
+---
+
+## 1. Motivation
+
+Every AI coding tool today re-discovers a codebase's architecture from
+scratch on every session. Cursor builds its own embedding index. Cline
+builds its own. Continue builds its own. The work duplicates across
+tools and is lost across sessions.
+
+ANCI fills the hole. It is a **static file format** — two files,
+`anci.yaml` and `anci.bin`, sitting at a known location in a repository
+— that describes that codebase's architecture in a form any AI tool can
+read without indexing it itself.
+
+ANCI is to codebases what OpenAPI is to REST APIs: a standardized way for
+something to describe itself to consumers it doesn't know about.
+
+## 2. Goals & non-goals
+
+### Goals
+
+* **Tool-neutral.** No assumption about which AI tool consumes ANCI.
+* **Local-first.** ANCI files live next to the code, in `.carto/` by
+  convention. Never sent over a network unless the user chooses to.
+* **Hybrid representation.** Human-readable header for grep / inspection;
+  binary body for fast queries on million-file repos.
+* **Bounded size.** Target ≤ 20 MB total for a 100K-file repo.
+* **Lossless round-trip.** Producer → file → consumer reproduces the
+  exact graph, domains, and metadata.
+* **Forward-compatible.** New optional sections may be added in v0.x
+  releases. Consumers ignore unknown sections.
+
+### Non-goals
+
+* **Not a query language.** Consumers traverse the data structures with
+  their own code. ANCI is just the data.
+* **Not a network protocol.** No RPC. No streaming. Static files only.
+* **Not a replacement for source code.** ANCI describes structure
+  (graph, domains, routes), not source.
+* **Not yet stable.** v0.1 DRAFT may break in v0.2, v0.3, etc. Stability
+  begins at v1.0.
+
+## 3. File layout
+
+A repository that ships ANCI places two files in `.carto/`:
+
+```
+.carto/
+├── anci.yaml    # Header. UTF-8 YAML. Required. Human-readable.
+├── anci.bin     # Body.   Binary.    Required. Machine-readable.
+```
+
+Producers write both. Consumers read either independently:
+
+* If a consumer only needs domain names and route counts, parse
+  `anci.yaml` and ignore the body.
+* If a consumer needs blast radius or graph traversal, parse the body.
+
+The header MUST point to the body's filename and byte length. If they
+disagree, the body is authoritative for graph data and the header is
+authoritative for human metadata.
+
+## 4. Header format (`anci.yaml`)
+
+UTF-8, YAML 1.2, **strict subset**:
+
+* 2-space indentation
+* `key: value` pairs only (no flow style `{}`/`[]`)
+* All string values double-quoted (no implicit typing)
+* Lists use `- ` prefix
+* No multi-line strings, no anchors, no aliases, no tags
+
+A v0.1.0-DRAFT producer MUST emit a header that conforms to this
+schema. A consumer MAY accept other YAML inputs but reference
+implementations only emit/parse the strict subset.
+
+### 4.1 Schema
+
+```yaml
+anci:
+  version: "0.1.0-DRAFT"            # required, string
+  generator: "carto-md@2.0.9"       # required, string
+  generated_at: "2026-06-07T..."    # required, ISO-8601 UTC
+  body:
+    file: "anci.bin"                # required, relative to header
+    bytes: 12345                    # required, body length on disk
+
+project:
+  total_files: 7567                 # required
+  total_routes: 86                  # required
+  total_models: 12                  # required
+  total_import_edges: 13420         # required
+
+domains:                            # required, possibly empty
+  - name: "AUTH"
+    file_count: 42
+    route_count: 7
+    model_count: 1
+
+high_impact:                        # optional, top N by transitive dep count
+  - file: "src/auth/session.ts"
+    transitive_dependents: 47
+
+routes:                             # optional
+  - method: "POST"
+    path: "/auth/login"
+    file: "src/auth/login.ts"
+    framework: "express"
+    handler: "login"
+
+models:                             # optional
+  - name: "User"
+    kind: "prisma"
+    file: "prisma/schema.prisma"
+```
+
+Field names are stable for the v0.x line. Adding new optional fields is
+not a breaking change. Removing or renaming a field IS breaking and
+requires a version bump.
+
+### 4.2 Versioning
+
+| Field           | Meaning                                                   |
+|-----------------|-----------------------------------------------------------|
+| `anci.version`  | Spec version. v0.x is unstable. v1.0+ follows semver.     |
+| `anci.generator`| Producer identity. Free-form string, conventionally `name@version`. |
+
+Consumers MUST refuse to parse a header whose `anci.version` is not in
+their compatibility set. Reference consumer behavior (carto-md):
+
+* Accepts: `0.1.x-DRAFT`
+* Rejects: anything else
+
+## 5. Body format (`anci.bin`)
+
+Binary, little-endian, length-prefixed sections. Designed so a single
+streaming pass can fully reconstruct all bitmaps, paths, and domain
+mappings.
+
+### 5.1 Header
+
+| Offset | Size  | Field        | Value                                         |
+|-------:|------:|--------------|-----------------------------------------------|
+|      0 |  4 B  | magic        | `0x49434E41` (`'A','N','C','I'` little-endian)|
+|      4 |  1 B  | version      | `0x01`                                        |
+|      5 |  3 B  | reserved     | zero                                          |
+|      8 |  4 B  | size_bits    | u32 — bit dimension of every bitmap (= max file id + 1) |
+
+Total fixed-header length: **12 bytes.**
+
+### 5.2 Sections
+
+After the fixed header, sections appear **in this order**. Each section
+begins with a u32 count.
+
+#### 5.2.1 `forward` — file → its imports
+
+```
+count_u32
+count × {
+  from_file_id_u32
+  words_len_u32
+  words_u32 × words_len      // raw Uint32Array bytes, LE
+}
+```
+
+Bit `j` of the bitmap of `from_file_id` is 1 iff the file with id
+`from_file_id` directly imports the file with id `j`.
+
+#### 5.2.2 `reverse` — file → its direct dependents
+
+Same record shape as `forward`. Bit `j` set iff file `to_file_id` is
+directly imported by file `j`.
+
+#### 5.2.3 `popcount` — pre-computed transitive dependent counts
+
+```
+count_u32
+count × {
+  file_id_u32
+  count_u32       // # of distinct dependents reachable in ≤ 5 hops
+}
+```
+
+Sorted DESC by count. Lets `getHighImpactFiles(n)` answer in O(1).
+Producers MUST clamp BFS to 5 hops to match the carto-md reference.
+
+#### 5.2.4 `paths` — file id → path string
+
+```
+count_u32
+count × {
+  file_id_u32
+  path_len_u32
+  path_bytes (UTF-8, no NUL terminator)
+}
+```
+
+Paths are project-relative POSIX paths (forward slashes, no leading `./`).
+
+#### 5.2.5 `file_domain` — file id → domain id
+
+```
+count_u32
+count × {
+  file_id_u32
+  domain_id_u32
+}
+```
+
+Files absent from this section have no domain assignment. A file MAY
+have at most one domain.
+
+#### 5.2.6 `domain_names` — domain id → human name
+
+```
+count_u32
+count × {
+  domain_id_u32
+  name_len_u32
+  name_bytes (UTF-8)
+}
+```
+
+Domain names are uppercase by convention (`AUTH`, `PAYMENTS`,
+`DATABASE`) but the spec does not constrain their contents.
+
+### 5.3 Total layout (concrete byte map)
+
+```
+[ 12 B fixed header ]
+[ forward section     ]
+[ reverse section     ]
+[ popcount section    ]
+[ paths section       ]
+[ file_domain section ]
+[ domain_names section]
+EOF
+```
+
+A consumer that knows the spec version can stream-parse top to bottom.
+There is no out-of-line index — the format is designed for one
+sequential read.
+
+## 6. Generation algorithm (reference)
+
+Producers SHOULD compute the body as follows:
+
+1. Assign each file a stable, dense integer id.
+2. For each file, build a bitmap of its forward imports (resolved
+   imports only; unresolved imports are excluded).
+3. Reverse the forward bitmaps into `reverse`.
+4. For each file with ≥ 1 dependent, run a 5-hop BFS over `reverse`
+   using the same self-loop guard as `bitmap/sidecar.js`:
+   a. Seed `visited` with direct dependents.
+   b. Expand frontier by one hop, mask `visited`, add result to
+      `visited`. Repeat to depth 5 or until frontier is empty.
+   c. Clear the seed bit (cycles must not count the file itself).
+   d. Record `popcount(visited)` if > 0.
+5. Sort `popcount` records DESC.
+6. Write sections in the order specified in §5.2.
+
+The carto-md reference implementation lives in `src/anci/serialize.js`.
+
+## 7. Consumer responsibilities
+
+A consumer MUST:
+
+* Validate magic bytes and version before reading any section.
+* Refuse to parse if `size_bits` differs from the bitmap dimension
+  derived from any section's `words_len`.
+* Treat unknown sections (in future v0.x releases) as opaque and skip
+  them. The reference implementation enforces strict order today, but
+  consumers SHOULD be permissive on order to ease forward compatibility.
+
+A consumer SHOULD:
+
+* Cache the parsed body in memory rather than re-parsing on every
+  query. The format is designed for fast load, not fast random seek.
+* Cross-validate the header's `body.bytes` against the actual file
+  size and warn (not fail) on mismatch.
+
+## 8. Versioning & deprecation policy
+
+### v0.1.0-DRAFT (this spec)
+
+* Format may change in any direction up to v1.0.
+* Consumers pin to specific producer versions.
+* Reference implementation is carto-md ≥ 2.0.9.
+* No backward compatibility guarantees.
+
+### Future v0.x (e.g. v0.2)
+
+* MAY add optional header fields.
+* MAY add optional body sections (appended after `domain_names`).
+* MUST NOT remove or rename existing fields.
+* MUST bump `anci.version` to a new minor.
+* Reference consumer accepts the latest v0.x and the version it shipped
+  against.
+
+### v1.0 stability
+
+When the format is judged ready (reference partner integrations exist,
+plus 6 months of v0.x stability), `anci.version` graduates to `1.0.0`
+and standard semver applies thereafter:
+
+* MAJOR: incompatible breaking change.
+* MINOR: backward-compatible addition.
+* PATCH: clarification only.
+
+A v1.x consumer MUST accept all v1.x bodies. v0.x compatibility at v1.0
+is not guaranteed — producers re-emit at the v1.0 schema.
+
+## 9. Security considerations
+
+ANCI is a passive description of code structure. It contains:
+
+* File paths (project-relative).
+* Domain names.
+* Route paths and HTTP methods.
+* Model names and kinds.
+* Import graph as integer bitmaps.
+
+ANCI does **not** contain source code, secrets, env values, or
+user-identifying information. Producers MUST NOT include source content
+in any field.
+
+A repository that publishes its `.carto/anci.{yaml,bin}` to a remote
+location is exposing its architecture. This is the same disclosure
+level as making the directory tree public. Producers SHOULD respect
+`.cartoignore` and SHOULD NOT include paths matching its patterns.
+
+## 10. Why YAML + binary (and not just YAML, or just binary)
+
+| Property               | YAML alone | Binary alone | Hybrid |
+|------------------------|:----------:|:------------:|:------:|
+| Human-readable         | ✅          | ❌            | ✅      |
+| Grep-able from CI      | ✅          | ❌            | ✅      |
+| Compact at 100K files  | ❌ (50–500 MB) | ✅       | ✅ (5–20 MB) |
+| Fast graph queries     | ❌          | ✅            | ✅      |
+| Easy partial parse     | ✅          | ⚠️           | ✅      |
+
+The split mirrors the structure of the data: metadata is small and
+varied (good for YAML); the graph is large and uniform (good for
+binary).
+
+## 11. Why these specific bitmap sections
+
+The body ships exactly the data needed to answer the four MCP tools
+that drive most AI-tool queries:
+
+* `getBlastRadius(file)` → walk `reverse` BFS-style.
+* `simulateChangeImpact(files)` → OR-aggregate `reverse` bitmaps.
+* `getHighImpactFiles(n)` → take first N from `popcount`.
+* `getDomainsList()` / domain membership → header + `file_domain` +
+  `domain_names`.
+
+Everything else (cross-domain detection, similarity, change-plan
+ranking) can be derived from these primitives. The format keeps the
+ship surface small.
+
+## 12. Compatibility with carto-md `bitmap.bin`
+
+ANCI v0.1 and carto-md's internal `bitmap.bin` (magic `0x54524243`
+"CBRT") share record-level encoding but are **distinct file formats
+with distinct magics**. Reasons:
+
+* `bitmap.bin` is private cache; `anci.bin` is public export.
+* `bitmap.bin` includes `crossForward` and `domainBitmaps` (internal
+  query optimizations); ANCI omits them. Consumers can re-derive both
+  in O(N) on load.
+* `bitmap.bin` may evolve at carto-md's pace; ANCI evolves only at
+  spec-revision pace.
+
+A consumer MUST NOT attempt to load `bitmap.bin` as ANCI or vice versa.
+
+## 13. Reference vs. interoperability tests
+
+The carto-md reference implementation includes a roundtrip test suite
+(`test/test.js` → `ANCI roundtrip`). Other implementations are
+encouraged to:
+
+* Run carto-md's reference suite against their own
+  serialize/deserialize code.
+* Publish their own conformance tests for the spec to consume.
+
+The DRAFT spec deliberately ships **without** an independent
+conformance harness. v1.0 will require one before formalization.
+
+## 14. Open questions (RFC-stage feedback welcome)
+
+* **Should the body be Roaring-compressed instead of dense
+  Uint32Array?** Roaring is smaller on sparse repos but adds a
+  dependency. v0.1 ships dense; v1.0 may add an opt-in compressed
+  encoding.
+* **Should env vars be in the header?** Currently no — they leak
+  configuration surface. Open question for partners.
+* **Should source language be part of `paths`?** Currently no — language
+  is derivable from extension. Open if consumers ask.
+* **Cross-repo references?** Out of scope for v0.1. Tier 3 work.
+
+## 15. Acknowledgements
+
+Inspired by OpenAPI's standardization play (2010-2015), Git's pack
+reachability bitmaps (2013), and Lucene's Roaring posting lists (2014).
+
+The spec is iterated alongside carto-md. File issues at
+https://github.com/theanshsonkar/carto for proposed changes.

package/docs/scale.md

@@ -0,0 +1,129 @@
+# Carto at scale
+
+> Empirical scale data for the bitmap engine — synthetic stress sweep + every real-world repo in the Carto corpus. Reproducer commands at the bottom.
+
+The bitmap-backed graph engine is designed to handle 100K-1M files cleanly. This page is the empirical receipt. It captures both the **dense-synth stress sweep** (deterministic worst-case fan-out distribution) and the **real-world corpus** (4 of the 7 larger repos, the largest open-source codebases under MIT/permissive licenses we routinely test against).
+
+## What's measured
+
+For each run we capture:
+
+- **Init time** — full `runSyncV2` from a wiped `.carto/` directory.
+- **Sync time** — second `runSyncV2` immediately after, no files changed (mtime+hash skip path).
+- **DB size** — `.carto/carto.db` bytes on disk.
+- **bitmap.bin size** — the sidecar bytes on disk.
+- **Sidecar (RAM)** — sum of all bitmap word-array byte lengths held in memory.
+- **Peak RSS** — process resident memory after init and during query workloads.
+- **MCP query p50 / p99** — 1000 calls each (50-call warmup) for the 5 production bitmap tools (`blastRadius`, `crossDomain`, `highImpactFiles`, `similarPatterns`) plus `simulate_change_impact`. Random query inputs are seeded so identical `--seed` produces identical workloads.
+
+The query stage opens SQLite **read-only** — invariant honored. The bitmap-as-derived-disposable invariant is also honored: the runner only reads from `bitmap.bin`, never writes.
+
+All numbers below were captured on the maintainer dev box: Apple silicon, Node 20.20, macOS, NVMe SSD. Recapture via the commands at the bottom.
+
+## Synthetic stress sweep (dense fan-out)
+
+Source: `bench/scale-test/`. Generates a deterministic-for-seed TypeScript repo with a worst-case-shaped import graph: 5 domain-like top-level dirs (`auth`/`payments`/`database`/`events`/`core`), Pareto(α=2) fan-out clipped to [1,8], 75% same-domain / 25% cross-domain, hotspot-biased targets so the first ~10% of file ids accumulate most in-edges. Imports always reference an earlier file id (acyclic).
+
+Edge density ≈ 1.5 per file. **This is denser than every real-world repo in the corpus** — real codebases have many leaf files with zero imports, so the synth deliberately exercises the worst case for the bitmap layer.
+
+| Files | Edges | Init | Sync | DB | bitmap.bin | Sidecar (RAM) | Peak RSS |
+|------:|------:|-----:|-----:|---:|-----------:|--------------:|---------:|
+| 1,000 | 1,392 | 533ms | 70ms | 756 KB | 222 KB | 186 KB | 149 MB |
+| 10,000 | 14,876 | 3.28s | 627ms | 6.5 MB | 17.0 MB | 18.1 MB | 350 MB |
+| 50,000 | 76,145 | 1.1m | 5.14s | 36.9 MB | 414.9 MB | 488.4 MB | 1.35 GB |
+
+| Files | blastRadius p50/p99 | crossDomain p50/p99 | highImpactFiles p50/p99 | similarPatterns p50/p99 | simulate_change_impact p50/p99 |
+|------:|---------------------|---------------------|------------------------|------------------------|--------------------------------|
+| 1,000 | 1.6µs / 24.4µs | 19.5µs / 25.0µs | 709ns / 4.3µs | 276µs / 484µs | 7.0µs / 78.8µs |
+| 10,000 | 6.6µs / 67.7µs | 705µs / 914µs | 750ns / 1.4µs | 17.0ms / 19.3ms | 11.6µs / 113µs |
+| 50,000 | 22.4µs / 472µs | 28.1ms / 28.9ms | 750ns / 1.3µs | 462ms / 798ms | 49.9µs / 455µs |
+
+### What 50K reveals
+
+Three distinct failure modes show up at the dense-synth 50K row, **all of them addressable by a Roaring-bitmap upgrade on the roadmap**:
+
+1. **Storage scales linearly with N** — every file gets its own forward + reverse bitmap of size ~`N/8` bytes. At N=50K bitmap.bin is 415 MB; at N=100K linear extrapolation puts it at ~1.7 GB. The current pure-Node `Uint32Array` bitset (`src/bitmap/bitset.js`) trades storage efficiency for raw query speed and zero native deps. Roaring would cut this 5-50× depending on density.
+2. **`crossDomain` p50 hits 28 ms** — linear sweep over the `crossForward` Map. Fixable with a precomputed cross-domain edge bitmap that's OR-aggregated once at build time, not iterated per query.
+3. **`similarPatterns` p50 hits 462 ms** — Jaccard over import sets at scale costs O(candidates × set-intersection). The MCP layer calls this with `top_k=5` so user-facing latency is well under the raw bench number, but the absolute cost is real.
+
+Three things stay healthy at 50K: `blastRadius` p50 22µs, `highImpactFiles` p50 750ns (popcount index is O(1) array slice), `simulate_change_impact` p50 50µs.
+
+### Pending (not yet captured on this box)
+
+| Files | Notes |
+|------:|-------|
+| 100,000 | Stress-test for the dense-bitset implementation. ~3-5 min walltime expected. Worth running before any Roaring work to lock in the regression baseline. |
+| 500,000 | Practical ceiling for the dense-bitset; expect bitmap.bin > 4 GB, possibly hitting OOM on 16 GB-RAM dev boxes. |
+| 1,000,000 | Roaring-bitmap upgrade target. Expect dense-bitset OOM. |
+
+Reproducible via `npm run bench:scale -- --size 100000 --keep --out /tmp/carto-100k`.
+
+## Real-world corpus
+
+These are the 4 largest repos in `~/carto-test-repos`, all already indexed by `~/carto-test-repos/run-bench.sh` (the bench harness baseline). The query latency below was measured against those existing indexes via `--queries-only` so this measurement does not perturb the indexes used by `node test/accuracy-corpus.js`.
+
+| Repo | Indexed files | Edges | DB | bitmap.bin | Sidecar (RAM) |
+|------|--------------:|------:|---:|-----------:|--------------:|
+| [cal.com](https://github.com/calcom/cal.com) | 4,351 | 3,478 | 3.1 MB | 1.9 MB | 2.0 MB |
+| [nextjs](https://github.com/vercel/next.js) | 6,193 | 7,930 | 15.0 MB | 4.4 MB | 4.3 MB |
+| [supabase](https://github.com/supabase/supabase) | 6,330 | 5,189 | 4.8 MB | 4.4 MB | 4.4 MB |
+| [vscode](https://github.com/microsoft/vscode) | 7,567 | 13,335 | 14.3 MB | 4.1 MB | 4.5 MB |
+
+| Repo | blastRadius p50/p99 | crossDomain p50/p99 | highImpactFiles p50/p99 | similarPatterns p50/p99 | simulate_change_impact p50/p99 |
+|------|---------------------|---------------------|------------------------|------------------------|--------------------------------|
+| cal.com | 4.3µs / 51µs | 148µs / 279µs | 667ns / 1.0µs | 1.0µs / 1.99ms | 10.3µs / 71.0µs |
+| nextjs | 5.0µs / 155µs | 196µs / 284µs | 750ns / 1.3µs | 1.2µs / 3.01ms | 28.9µs / 211µs |
+| supabase | 5.5µs / 47.9µs | 201µs / 260µs | 708ns / 1.0µs | 1.5µs / 3.19ms | 10.8µs / 65.9µs |
+| vscode | 2.7µs / 428µs | 1.23ms / 1.47ms | 750ns / 1.7µs | 834ns / 4.03ms | 19.3µs / 637µs |
+
+### Real-world vs dense-synth
+
+The 7,567-file vscode row vs the 10,000-file synth row tells the most important story:
+
+- vscode `similarPatterns` p50 is **834ns**; synth-10K is **17ms**. Real codebases have far sparser per-file import sets — most files import 0-3 things, a handful import many. Synth is a deliberate worst case (Pareto fan-out always ≥1, often 4-8). Real Jaccard-over-import-sets fits in cache; synth doesn't.
+- vscode `crossDomain` p50 is **1.23ms**; synth-10K is **704µs**. Cross-domain edges scale with edge density; synth is denser. Both are sub-2ms at any sensible scale.
+- vscode `bitmap.bin` is **4.1 MB** at 7,567 files; synth-10K is **17 MB** at 10,000 files. ~4× density difference, reflected directly in storage.
+
+The takeaway: **dense-synth identifies the failure modes; real-world data sets the actual user expectations.** Both are needed.
+
+## Linux kernel and Chromium
+
+Block 1.B in PEAK §10 explicitly calls out the Linux kernel and Chromium as scale targets. Neither is in `~/carto-test-repos` today (multi-GB clones, gated on the maintainer's disk budget). The `bench/scale-test/real-world.js` driver lands here so capturing those rows is one command once a clone exists:
+
+```bash
+git clone --depth=1 https://github.com/torvalds/linux ~/clones/linux
+node bench/scale-test/real-world.js --repo ~/clones/linux --name linux-kernel
+```
+
+```bash
+# Chromium follows the official `fetch` flow; expect a 30+ GB clone.
+node bench/scale-test/real-world.js --repo ~/clones/chromium/src --name chromium
+```
+
+These rows are intentionally not yet captured. The 50K dense-synth + 7,567-file vscode + 6,330-file supabase rows above already establish the scaling profile of the current implementation; whether kernel/Chromium clear or fail is *known* in the bitmap-storage sense (linear in N, hits the GB scale at 100K+ files in the worst case). Capturing them on the maintainer box is a confirm-the-known activity, not a discover-the-unknown one.
+
+## Reproducing this page
+
+Every number above is mechanically reproducible. The exact commands:
+
+```bash
+# Synth sweep (deterministic, dense-fan-out worst case)
+npm run bench:scale -- --size 1000
+npm run bench:scale -- --size 10000
+npm run bench:scale -- --size 50000
+
+# Real-world corpus (uses existing indexes; doesn't re-index)
+node bench/scale-test/real-world.js --repo ~/carto-test-repos/tier-b/vscode --name vscode --queries-only
+node bench/scale-test/real-world.js --repo ~/carto-test-repos/tier-b/supabase --name supabase --queries-only
+node bench/scale-test/real-world.js --repo ~/carto-test-repos/tier-b/nextjs --name nextjs --queries-only
+node bench/scale-test/real-world.js --repo ~/carto-test-repos/tier-b/cal.com --name cal.com --queries-only
+
+# Larger (maintainer-machine work)
+npm run bench:scale -- --size 100000 --keep --out /tmp/carto-100k
+```
+
+Each run writes `bench/scale-test/results/<tag>-<ISO-timestamp>.json` and refreshes `bench/scale-test/REPORT.md`. The aggregator keeps the latest run per (kind, label) so re-running a row replaces the old number.
+
+---
+
+_See `bench/scale-test/README.md` for full harness documentation._

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "carto-md",
-  "version": "2.0.7",
-  "description": "Structural intelligence layer for AI coding tools. Indexes your codebase into SQLite — routes, models, import graph, blast radius, domains — and exposes 16 MCP tools for Kiro, Cursor, and Claude.",
+  "version": "2.0.9",
+  "description": "Structural intelligence layer for AI coding tools. Indexes your codebase into SQLite — routes, models, import graph, blast radius, domains — and exposes 22 MCP tools for Kiro, Cursor, and Claude.",
   "bin": {
     "carto": "src/cli/index.js"
   },
@@ -10,7 +10,10 @@
     "test": "node test/test.js",
     "test:correctness": "node test/correctness.js",
     "test:benchmark": "node test/benchmark.js",
-    "test:bench-ci": "node test/bench-ci.js"
+    "test:bench-ci": "node test/bench-ci.js",
+    "postinstall": "node scripts/postinstall.js",
+    "bench:bitmap": "node bench/bitmap-validation/index.js",
+    "bench:scale": "node bench/scale-test/index.js"
   },
   "dependencies": {
     "@agentclientprotocol/sdk": "^0.22.1",
@@ -18,7 +21,9 @@
     "@modelcontextprotocol/sdk": "^1.0.0",
     "better-sqlite3": "11.7.0",
     "chokidar": "^3.6.0",
-    "tree-sitter": "0.25.0",
+    "tree-sitter": "0.25.0"
+  },
+  "optionalDependencies": {
     "tree-sitter-c-sharp": "0.21.3",
     "tree-sitter-cpp": "0.23.4",
     "tree-sitter-go": "0.25.0",
@@ -29,7 +34,7 @@
     "tree-sitter-typescript": "0.23.2"
   },
   "engines": {
-    "node": ">=18.0.0 <26.0.0"
+    "node": ">=18.0.0"
   },
   "author": {
     "name": "Ansh Sonkar",