carto-md 2.0.8 → 2.0.9

package/README.md

@@ -19,6 +19,8 @@ That's it. Carto auto-wires itself into every AI tool you have installed. Restar
 
 **Works with:** Cursor · Claude Code · Codex · Kiro · Claude Desktop · Windsurf · VS Code Copilot · JetBrains · Zed
 
+> Carto also publishes [**ANCI**](#anci--the-open-spec-for-codebases-describing-themselves-to-ai) — the open file format for any codebase to describe its architecture to AI tools. Carto is the reference implementation; the spec is open and any tool can consume it. [§ ANCI ↓](#anci--the-open-spec-for-codebases-describing-themselves-to-ai)
+
 ---
 
 ## Use it with your AI tool
@@ -159,6 +161,9 @@ Every `validate_diff` call is also written to a local SQLite log, so a session t
 | C / C++ | `.cpp` `.cc` `.cxx` `.h` `.hpp` |
 | C# | `.cs` |
 | Ruby | `.rb` |
+| R | `.r` `.R` |
+| Prisma schema | `.prisma` |
+| HTML | `.html` (for `fetch()` discovery) |
 
 ### Route extraction (framework-aware)
 
@@ -235,7 +240,131 @@ Carto supports any LLM provider — configure in your editor:
 
 ---
 
-## The 22 MCP tools
+## GitHub Action — PR impact reports
+
+Drop carto onto every PR your repo gets. Posts a sticky comment on each pull request with the diff's blast radius, cross-domain violations, affected routes, and a risk badge.
+
+`.github/workflows/carto.yml`:
+```yaml
+name: Carto Impact Report
+
+on:
+  pull_request:
+    branches: [main]
+
+permissions:
+  contents: read
+  pull-requests: write
+
+jobs:
+  carto:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with: { fetch-depth: 0 }
+      - uses: theanshsonkar/carto@v2.0.9
+```
+
+That's the whole config. The action handles `npm install`, builds (or restores from cache) the `.carto/` index, runs `carto pr-impact`, and posts the comment via `GITHUB_TOKEN`.
+
+### Inputs
+
+| Input | Default | What it does |
+|-------|---------|--------------|
+| `carto-version` | `latest` | The `carto-md` npm version to install. Pin in production for reproducibility. |
+| `base` | auto (`origin/$GITHUB_BASE_REF`) | Git ref the PR branched from. |
+| `head` | auto (`$GITHUB_SHA`) | Git ref of the PR head. |
+| `fail-on` | _(empty)_ | Fail the workflow when risk meets/exceeds this severity. One of `HIGH`, `MEDIUM`, `LOW`. Empty = comment-only. |
+| `comment-mode` | `sticky` | `sticky` updates the existing carto comment in place. `new` posts a new comment every push. `none` skips posting (renders to stdout). |
+| `node-version` | `20` | Node.js version on the runner. |
+
+### Outputs
+
+| Output | Description |
+|--------|-------------|
+| `risk` | Rolled-up risk: `SAFE` \| `LOW` \| `MEDIUM` \| `HIGH`. Lets downstream steps gate behavior on Carto's verdict. |
+| `comment-url` | URL of the posted/updated PR comment. |
+
+### What the comment looks like
+
+```markdown
+## 🗺️ Carto Impact Report
+
+This PR touches AUTH and DATABASE domains.
+
+| Metric | Value |
+|--------|-------|
+| Risk | 🔴 HIGH |
+| Blast radius (union) | 23 files |
+| Files changed | 6 |
+| Cross-domain violations introduced | 2 |
+| High-impact file changed | src/auth/session.ts (8 direct dependents) |
+
+<details>
+<summary>Affected routes (4)</summary>
+
+- POST /auth/login — risk: HIGH
+- GET /auth/me — risk: HIGH
+- POST /auth/register — risk: MEDIUM
+- POST /api/users — risk: LOW
+
+</details>
+
+<details>
+<summary>Cross-domain violations (2)</summary>
+
+- auth/login.ts now imports from payments/billing.ts (AUTH→PAYMENTS)
+- database/user-repo.ts now imports from auth/jwt.ts (DATABASE→AUTH)
+
+</details>
+```
+
+### Standalone CLI use
+
+The action is a thin wrapper around `carto pr-impact`. Use it locally, in custom CI, or in pre-commit hooks:
+
+```bash
+carto pr-impact --base origin/main --head HEAD              # markdown to stdout
+carto pr-impact --base origin/main --head HEAD --format json
+carto pr-impact --base origin/main --head HEAD --fail-on HIGH  # exit 2 on HIGH risk
+```
+
+---
+
+## ANCI — the open spec for codebases describing themselves to AI
+
+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. Same parsing, every tool, every session.
+
+**ANCI** (Architecturally Normalized Code Index) is the file format that fixes this. Two files at `.carto/anci.{yaml,bin}` that describe the codebase's architecture in a form any AI tool can read without indexing it itself. OpenAPI did this for REST APIs. ANCI does it for codebases.
+
+`carto sync` writes both files automatically. The header is grep-able YAML; the body is a compact binary import graph. Spec lives in [`docs/anci/v0.1-DRAFT.md`](docs/anci/v0.1-DRAFT.md). Carto is the reference implementation.
+
+```bash
+carto anci publish              # re-emit anci.{yaml,bin} from the index
+carto anci show                 # human-readable summary
+carto anci validate ./.carto    # validate a published pair
+```
+
+Any tool can consume an ANCI pair without depending on Carto:
+
+```js
+const { loadAnci } = require('carto-md/src/anci/consumer');
+
+const reader = loadAnci('./.carto');
+console.log(reader.domains);                          // [{ name: 'AUTH', file_count: 42 }, ...]
+console.log(reader.getHighImpactFiles(5));            // top 5 by transitive dependents
+console.log(reader.blastRadius('src/auth/session.ts'));// { count, hops, files: [...] }
+console.log(reader.simulateChangeImpact([             // multi-file change blast radius
+  'src/auth/session.ts',
+  'src/db/connection.ts',
+]));
+```
+
+> **Status:** v0.1.0-DRAFT — wire format may change up to v1.0. The reference implementation lives in this repo at `src/anci/`.
+
+---
+
+
 
 Once carto is wired in, your AI tool can call any of these mid-task. You don't need to memorize them — your AI will pick the right ones.
 
@@ -264,7 +393,7 @@ Once carto is wired in, your AI tool can call any of these mid-task. You don't n
 | `did_we_discuss_this(topic)` | Substring search over the episodic memory log — avoid re-deciding settled questions |
 | `get_intervention_history(file?)` | Past Carto-issued violations and suggestions, optionally filtered by file |
 
-**All MCP queries:** **<5ms** on every benchmarked repo.
+**Latency:** All bitmap-backed queries return in microseconds on real repos; cross-domain and `simulate_change_impact` settle under 2ms even on a 7.5K-file codebase like vscode. See [Benchmarks](#benchmarks) for the per-tool table.
 
 ## Episodic Memory
 
@@ -316,6 +445,7 @@ Full schema with anchor pinning (forces files into a domain regardless of cluste
 | `carto watch` | **Optional.** Live re-index on every file save. Not required — git hooks + lazy MCP re-parse keep the index fresh by default. Use only for AI-heavy workflows that write 50+ files between commits. |
 | `carto agent` | Start ACP agent mode (for Zed / JetBrains / VS Code) |
 | `carto impact <file>` | Blast radius: risk level, affected files, routes at risk |
+| `carto pr-impact` | Diff-shaped impact report between two git refs. Markdown (default) or JSON. Used by the [GitHub Action](#github-action--pr-impact-reports); works locally too. `--fail-on HIGH\|MEDIUM\|LOW` exits non-zero on threshold trip. |
 | `carto check` | Cross-domain violations, high-risk uncommitted changes, domain health |
 | `carto inspect` | Read-only diagnostic: index paths, sizes, freshness, bitmap sidecar shape, top-impact files, schema version, sync timestamps. `--json` for piping into `jq`. Never triggers a rebuild. |
 | `carto remove` | Remove AGENTS.md and .carto/ from project |
@@ -330,12 +460,12 @@ Measured on real open-source repos. Apple M-series, 8 CPUs, 8GB RAM. SHAs pinned
 
 | Repo | Language | Indexed Files | First Run | Second Run | DB Size | Import Edges |
 |------|----------|---------------|-----------|------------|---------|--------------|
-| [prisma/prisma](https://github.com/prisma/prisma) | TypeScript | 961 | **961ms** | **431ms** | 0.7 MB | 1,387 |
-| [supabase/supabase](https://github.com/supabase/supabase) | TypeScript | 6,330 | **5.4s** | **1.2s** | 4.0 MB | 5,321 |
-| [microsoft/vscode](https://github.com/microsoft/vscode) | TypeScript | 7,567 | **7.7s** | **1.0s** | 6.7 MB | 13,420 |
-| [zed-industries/zed](https://github.com/zed-industries/zed) | Rust | 1,752 | **3.0s** | **491ms** | 4.4 MB | 2,113 |
+| [prisma/prisma](https://github.com/prisma/prisma) | TypeScript | 961 | **1.0s** | **350ms** | 1.1 MB | 1,387 |
+| [supabase/supabase](https://github.com/supabase/supabase) | TypeScript | 6,330 | **5.4s** | **1.2s** | 4.8 MB | 5,189 |
+| [microsoft/vscode](https://github.com/microsoft/vscode) | TypeScript | 7,567 | **8.0s** | **935ms** | 14.3 MB | 13,335 |
+| [zed-industries/zed](https://github.com/zed-industries/zed) | Rust | 1,752 | **2.9s** | **468ms** | 4.8 MB | 2,110 |
 
-**Indexed Files** counts what Carto actually parses — `.ts/.js/.py/.go/.rs/...` after excluding `node_modules`, build output, and per-file `*.test.*` / `*.spec.*` / `*.stories.*` / `test_*.py` patterns. The on-disk file count of the repo is larger.
+**Indexed Files** counts what Carto actually parses — `.ts/.js/.py/.go/.rs/...` after excluding `node_modules`, build output, and per-file test patterns (`*.test.*` / `*.spec.*` / `*.stories.*` for JS/TS, `test_*.py` / `*_test.py` for Python, `test_*` / `*_test.r` for R). The on-disk file count of the repo is larger.
 
 **Second Run** = `carto sync` after no changes. mtime+size checked before reading content — if nothing changed, nothing is re-parsed.
 
@@ -351,7 +481,7 @@ Carto's MCP query path is bitmap-backed on five tools, plus a sixth (`simulate_c
 | `get_similar_patterns` | sub-ms | **73×** |
 | `simulate_change_impact` | sub-ms | **6.5×** (no SQLite equivalent at this latency) |
 
-Median speedup across all five tools on vscode: **10.7×**. Smaller repos hit higher peaks — laravel-framework `get_high_impact_files` clocks at 155× on the smaller graph. Reproducible via `npm run bench:bitmap -- --repo <path>`.
+Median speedup across all five tools on vscode: **10.7×**. Smaller repos with denser graphs hit higher peaks — supabase `get_high_impact_files` clocks well over 100× on its tighter import graph. Reproducible via `npm run bench:bitmap -- --repo <path>`.
 
 ### `validate_diff` latency
 
@@ -364,6 +494,15 @@ The new diff-shaped query that lets the AI ask "is this patch safe?" before show
 
 Budget was p50 ≤ 5ms, p99 ≤ 15ms. Both targets are cleared by 30-60×. The bitmap engine handles every blast-radius and cross-domain query in microseconds; what's left is diff parsing + result aggregation. Reproducible via `node bench/validation-perf/index.js --repo <path>`.
 
+### Scale
+
+Synthetic stress sweep + real-world corpus, dense-fan-out worst case all the way to 50K files. Headline numbers (full table in [`docs/scale.md`](docs/scale.md)):
+
+- Synth 50K files: init 1.1m, `blast_radius` p50 22µs, `simulate_change_impact` p50 50µs, `high_impact_files` p50 750ns. The dense Uint32Array bitset hits 415 MB on disk and 1.35 GB peak RSS at this size — the Tier-2 Roaring upgrade per PEAK §9.6 is the next move.
+- Real-world (vscode, 7,567 files): `blast_radius` p50 2.7µs, `cross_domain` p50 1.23ms, `similar_patterns` p50 834ns, `simulate_change_impact` p50 19µs.
+
+Reproducible via `npm run bench:scale -- --size <N>` (synth) and `node bench/scale-test/real-world.js --repo <path>` (any local clone, including Linux kernel or Chromium).
+
 ### Domains detected
 
 | Repo | Domains |
@@ -373,7 +512,7 @@ Budget was p50 ≤ 5ms, p99 ≤ 15ms. Both targets are cleared by 30-60×. The b
 | vscode | EXTENSIONS · AUTH · EVENTS · DATABASE · EXTENSION · CLI · CORE |
 | zed (Rust) | CORE · DATABASE · AUTH · EVENTS · PAYMENTS · TRPC · NOTIFICATIONS |
 
-vscode at 7,567 indexed files in under 8 seconds. Rust import graph working on zed (2,113 edges from `mod` declarations and `use crate::` paths).
+vscode at 7,567 indexed files in around 8 seconds. Rust import graph working on zed (2,110 edges from `mod` declarations and `use crate::` paths).
 
 ### Accuracy
 
@@ -420,6 +559,7 @@ File saved → debounce 50ms → re-parse 1 file → SQLite write → <50ms
 - **Sends your code anywhere.** Local only. SQLite on disk.
 - **Writes secrets into AGENTS.md.** `.cartoignore` blocks `.env` and credential files by default.
 - **Touches your manual notes.** Writes only between `<!-- CARTO:AUTO:START -->` and `<!-- CARTO:AUTO:END -->`.
+- **Forces you to install a C++ toolchain.** Prebuilt native binaries ship for macOS arm64, Linux x64 (glibc + musl/Alpine), and Windows x64. Intel Macs and other platforms transparently fall back to building from source, then to regex-only extraction if that fails.
 - **Costs money.** MIT license. Free forever.
 
 ---

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.