carto-md 2.0.9 → 2.1.1

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

@@ -91,11 +91,25 @@ implementations only emit/parse the strict subset.
 ```yaml
 anci:
   version: "0.1.0-DRAFT"            # required, string
-  generator: "carto-md@2.0.9"       # required, string
+  generator: "carto-md@2.1.0"       # required, string
   generated_at: "2026-06-07T..."    # required, ISO-8601 UTC
+  carto_version: "2.1.0"            # required, bare producer version
+  contains:                         # required, capability list (≥1 entry)
+    - "structural"
   body:
     file: "anci.bin"                # required, relative to header
     bytes: 12345                    # required, body length on disk
+    content_digest: "sha256:9f86…"  # optional, hash of the body bytes
+
+source:                             # required block; fields null if non-git
+  commit: "a4334a2c…"               # git HEAD commit SHA, or null
+  tree_hash: "e7d3f1…"              # git HEAD tree hash, or null
+  branch: "main"                    # current branch, or null (detached)
+
+grammar_versions:                   # optional; { pkg: version }
+  tree-sitter: "0.25.0"
+  tree-sitter-javascript: "0.25.0"
+  tree-sitter-typescript: "0.23.2"
 
 project:
   total_files: 7567                 # required
@@ -130,6 +144,32 @@ 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.1.1 Container identity (v0.1)
+
+The identity fields turn ANCI from "a folder" into a versioned,
+verifiable artifact:
+
+| Field                       | Meaning                                                              |
+|-----------------------------|----------------------------------------------------------------------|
+| `anci.carto_version`        | Bare producer version (distinct from the free-form `generator`).     |
+| `anci.contains`             | Capability list — which memory layers the container carries. v0.1 producers emit `["structural"]` (the import graph, domains, routes, models). Episodic/temporal/semantic/procedural layers are **not** in the file; they remain live in the producing engine. |
+| `anci.body.content_digest`  | `"<algorithm>:<hex>"` hash of the exact `anci.bin` bytes. Optional but recommended. Consumers recompute it to verify integrity. |
+| `source.commit`             | Git commit the container was built from, or `null` (non-git repo).   |
+| `source.tree_hash`          | Git tree hash of that commit — identifies exact committed content.   |
+| `source.branch`             | Branch name at build time, or `null` (detached HEAD / non-git).      |
+| `grammar_versions`          | Map of tree-sitter core + grammar package versions used to extract. Enables reproducibility checks (same repo + same grammars → same digest). |
+
+**Consumer integrity check.** A consumer that reads `content_digest`
+SHOULD recompute `<algorithm>(anci.bin)` and compare. On mismatch it
+SHOULD warn; a strict consumer MAY refuse to load. The reference
+consumer (`loadAnci`) exposes `reader.verifyDigest()` and a
+`{ verify: true }` option that promotes a mismatch to a thrown error.
+
+**Staleness.** `source.commit`/`source.tree_hash` let a consumer detect
+that the container was built from an older repo state than the current
+`HEAD` (e.g. "graph is N commits stale — results may be inaccurate").
+The reference engine surfaces this in MCP responses and `carto doctor`.
+
 ### 4.2 Versioning
 
 | Field           | Meaning                                                   |
@@ -258,7 +298,12 @@ sequential read.
 
 Producers SHOULD compute the body as follows:
 
-1. Assign each file a stable, dense integer id.
+1. Assign each file a stable, dense integer id. For **reproducibility**
+   (CT-4), ids MUST be assigned over the file list sorted by normalized
+   POSIX path (forward slashes, code-unit order — never a locale-aware
+   comparison), NOT over the filesystem enumeration order. This makes the
+   body layout, and therefore `content_digest`, identical across machines
+   for the same repo. See §16.2.
 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`.
@@ -418,3 +463,88 @@ 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.
+
+## 16. Single-file container envelope (`.anci`) — CT-3
+
+The two-file layout of §3 (`anci.yaml` + `anci.bin`) is the on-disk form.
+For **transport** — handing a container from one machine to another —
+`carto export` packs both files into ONE portable file, conventionally
+`project.anci`, and `carto load` unpacks it back into a queryable
+`.carto/` with **no re-index**. This makes "build once, load anywhere"
+literal: build on machine A, copy `project.anci`, `carto load` it on
+machine B, and blast radius answers instantly against the container A
+produced.
+
+### 16.1 Envelope wire format (little-endian)
+
+```
+magic        u32  = 0x50434E41   ("ANCP" — 'A','N','C','P' little-endian)
+version      u8   = 1
+reserved     u8×3 = 0
+entry_count  u32
+entry_count × {
+  name_len   u32
+  name       name_len UTF-8 bytes     # a bare basename (see 16.3)
+  data_len   u32
+  data       data_len bytes
+}
+trailer      32 bytes = sha256(all preceding bytes)
+```
+
+The envelope has its **own magic** (`ANCP`), distinct from the ANCI body
+magic (`ANCI` = `0x49434E41`) and carto-md's internal bitmap cache
+(`CBRT`). A consumer MUST NOT attempt to load one as another. A v0.1
+container carries exactly two entries — `anci.yaml` and `anci.bin` — in
+name-sorted order.
+
+### 16.2 Reproducibility
+
+Entries are written in a fixed (name-sorted) order, so packing the same
+input pair twice yields a byte-identical envelope. Note that `anci.yaml`
+embeds a `generated_at` timestamp, so the *envelope file* is only
+byte-stable for a fixed input pair. The **reproducible identity** of a
+container is its `anci.bin` `content_digest` (§4.1.1), which the envelope
+carries verbatim inside the packed `anci.yaml`.
+
+`anci.bin` itself is reproducible: **the same repo + the same grammar
+versions produce the same `content_digest`, independent of the machine or
+filesystem.** This holds because the producer assigns file ids over a
+list sorted by normalized POSIX path (not filesystem enumeration order),
+so the body layout — and therefore its hash — is a true content address
+of the repo. `grammar_versions` (§4.1.1) records the tree-sitter versions
+used, so a consumer that sees two containers with different digests can
+tell whether a grammar version drift could explain the difference. This
+enables container **diff / verify** across machines and over time.
+
+### 16.3 Security — a shared container is UNTRUSTED
+
+A `.anci` file is shareable, so on ingest it MUST be treated as untrusted.
+The reference `carto load` / `unpackContainer` enforce, in order:
+
+1. **Integrity.** Recompute the trailer `sha256` over the whole payload
+   before trusting any length field. A mismatch (corruption, truncation,
+   tampering of the envelope) rejects the file.
+2. **Entry whitelist.** Only the two known basenames (`anci.yaml`,
+   `anci.bin`) are accepted; any other name rejects the container.
+3. **Path-traversal guard (zip-slip).** An entry name must be a bare
+   basename — no path separators, no `..`, no absolute path, no NUL — so
+   unpacking can never write outside the destination directory. Writes
+   additionally re-derive `path.basename` and assert containment (defense
+   in depth).
+4. **Bounded allocation.** Entry count and per-entry size are capped so a
+   hostile header cannot trigger an unbounded allocation.
+
+Beyond structural validation, the **contents** of a loaded container —
+file paths, domain names, route strings, and any other embedded text —
+are **data, never instructions.** The consumer (`loadAnci`) parses them
+into data structures with a strict hand-rolled YAML subset parser and the
+binary deserializer; nothing in a container is ever executed, `eval`-ed,
+or interpreted as a command or a prompt. A container that embeds
+prompt-injection-looking or shell-injection-looking strings loads those
+strings verbatim as literal string values. Any tool consuming ANCI SHOULD
+preserve this property: render container text as untrusted data.
+
+This guardrail ships **with** single-file export/import (CT-3), before any
+signing or registry work (Tier 3). Signing (CT-7) later adds *origin*
+verification on top; the untrusted-data handling is independent and
+earlier.

package/docs/api/README.md

@@ -0,0 +1,124 @@
+# Carto MCP Tools — API Reference
+
+Auto-generated from `src/mcp/server.js`. Re-run `node scripts/gen-api-docs.js` after adding tools.
+
+**86 tools** across 9 categories.
+
+## Tool surface & tiers (CF-7)
+
+The MCP surface is collapsed into **5 parameterized families** + a tiered set of singletons.
+Which tools are *listed* to a client is gated by `CARTO_MCP_TIER` (env) or `carto.config.json` `mcp.tier`:
+
+- **core** (default): the ~10 tools every session needs — `get_architecture`, `get_context`, `impact`, `validate_diff`, `get_change_plan`, `memory`, `get_predictive_risk`, `get_minimal_context_for_intent`, `patterns`, `history`.
+- **advanced**: core + the documented ~8 (e.g. `org`, `get_routes`, `get_models`, `get_gaps`, `scaffold_for_intent`, `get_working_memory`, `get_test_coverage_map`, `get_safety_checklist`).
+- **all**: also lists experimental singletons.
+
+The **Families** collapse ~30 former tools; those old names are **deprecated shims** — they still
+resolve (byte-identical output + a one-line deprecation notice) but are never listed. See each
+family doc for the `mode`/`kind`/`view` that replaces the old tool.
+
+## Categories
+
+### Families (5)
+- [`impact`](./impact.md)
+- [`memory`](./memory.md)
+- [`history`](./history.md)
+- [`patterns`](./patterns.md)
+- [`org`](./org.md)
+
+### Core graph (21)
+- [`get_routes`](./get_routes.md)
+- [`get_blast_radius`](./get_blast_radius.md)
+- [`get_structure`](./get_structure.md)
+- [`get_domain`](./get_domain.md)
+- [`get_neighbors`](./get_neighbors.md)
+- [`get_cross_domain`](./get_cross_domain.md)
+- [`get_context`](./get_context.md)
+- [`search_routes`](./search_routes.md)
+- [`get_models`](./get_models.md)
+- [`get_high_impact_files`](./get_high_impact_files.md)
+- [`get_env_vars`](./get_env_vars.md)
+- [`get_domains_list`](./get_domains_list.md)
+- [`get_file_summary`](./get_file_summary.md)
+- [`get_change_plan`](./get_change_plan.md)
+- [`get_similar_patterns`](./get_similar_patterns.md)
+- [`simulate_change_impact`](./simulate_change_impact.md)
+- [`get_gaps`](./get_gaps.md)
+- [`dismiss_gap`](./dismiss_gap.md)
+- [`set_intent`](./set_intent.md)
+- [`get_intent`](./get_intent.md)
+- [`get_file_receipts`](./get_file_receipts.md)
+
+### Episodic Memory (5)
+- [`validate_diff`](./validate_diff.md)
+- [`get_recent_decisions`](./get_recent_decisions.md)
+- [`get_session_context`](./get_session_context.md)
+- [`did_we_discuss_this`](./did_we_discuss_this.md)
+- [`get_intervention_history`](./get_intervention_history.md)
+
+### Temporal (9)
+- [`get_architecture`](./get_architecture.md)
+- [`get_architectural_drift`](./get_architectural_drift.md)
+- [`get_domain_evolution`](./get_domain_evolution.md)
+- [`get_hotspot_files`](./get_hotspot_files.md)
+- [`get_complexity_trend`](./get_complexity_trend.md)
+- [`get_churn_vs_blast_radius`](./get_churn_vs_blast_radius.md)
+- [`get_arch_events`](./get_arch_events.md)
+- [`get_domain_health`](./get_domain_health.md)
+- [`get_temporal_context`](./get_temporal_context.md)
+
+### Brain (10)
+- [`get_invariants`](./get_invariants.md)
+- [`get_canonical_pattern`](./get_canonical_pattern.md)
+- [`get_conventions`](./get_conventions.md)
+- [`get_action_patterns`](./get_action_patterns.md)
+- [`scaffold_for_intent`](./scaffold_for_intent.md)
+- [`get_working_memory`](./get_working_memory.md)
+- [`get_pending_decisions`](./get_pending_decisions.md)
+- [`get_active_drift`](./get_active_drift.md)
+- [`get_active_suggestions`](./get_active_suggestions.md)
+- [`dismiss_suggestion`](./dismiss_suggestion.md)
+
+### AI-native (14)
+- [`get_minimal_context_for_intent`](./get_minimal_context_for_intent.md)
+- [`get_progressive_disclosure_tree`](./get_progressive_disclosure_tree.md)
+- [`get_token_budget_report`](./get_token_budget_report.md)
+- [`get_decision_log`](./get_decision_log.md)
+- [`get_evolution_delta`](./get_evolution_delta.md)
+- [`get_change_velocity`](./get_change_velocity.md)
+- [`get_test_coverage_map`](./get_test_coverage_map.md)
+- [`get_safety_checklist`](./get_safety_checklist.md)
+- [`get_data_flow`](./get_data_flow.md)
+- [`get_interface_contract`](./get_interface_contract.md)
+- [`explain_change_in_natural_language`](./explain_change_in_natural_language.md)
+- [`get_stale_docs`](./get_stale_docs.md)
+- [`get_dependency_surface`](./get_dependency_surface.md)
+- [`get_upgrade_risk`](./get_upgrade_risk.md)
+
+### Adjacent (8)
+- [`get_cross_language_call_graph`](./get_cross_language_call_graph.md)
+- [`get_iac_resources`](./get_iac_resources.md)
+- [`ingest_otlp_traces`](./ingest_otlp_traces.md)
+- [`get_risk_weighted_blast_radius`](./get_risk_weighted_blast_radius.md)
+- [`get_dead_code_with_confidence`](./get_dead_code_with_confidence.md)
+- [`get_hot_in_prod_no_tests`](./get_hot_in_prod_no_tests.md)
+- [`get_semantic_diff`](./get_semantic_diff.md)
+- [`get_llm_enrichment`](./get_llm_enrichment.md)
+
+### Predictive (7)
+- [`get_predictive_risk`](./get_predictive_risk.md)
+- [`get_microservice_cut_points`](./get_microservice_cut_points.md)
+- [`validate_change`](./validate_change.md)
+- [`get_file_ownership`](./get_file_ownership.md)
+- [`get_cross_team_coupling`](./get_cross_team_coupling.md)
+- [`get_drift_digest`](./get_drift_digest.md)
+- [`get_ai_cost_attribution`](./get_ai_cost_attribution.md)
+
+### Org-wide (7)
+- [`get_org_architecture`](./get_org_architecture.md)
+- [`get_service_dependency_graph`](./get_service_dependency_graph.md)
+- [`get_cross_repo_blast_radius`](./get_cross_repo_blast_radius.md)
+- [`find_consumers_of_api`](./find_consumers_of_api.md)
+- [`get_org_domain_mapping`](./get_org_domain_mapping.md)
+- [`get_service_boundary_violations`](./get_service_boundary_violations.md)
+- [`get_microservices_migration_cut_points`](./get_microservices_migration_cut_points.md)

package/docs/api/did_we_discuss_this.md

@@ -0,0 +1,36 @@
+# `did_we_discuss_this`
+
+> ⚠️ **Deprecated (CF-7).** Use `memory(query, kind="search")` instead. This name still resolves and returns byte-identical output for a deprecation window, but is no longer listed by default and emits a one-line notice.
+
+Substring search over the episodic memory log (decisions + interventions) for prior discussions of a topic. Use to avoid re-deciding settled questions.
+
+## Input schema
+
+```json
+{
+  "type": "object",
+  "properties": {
+    "topic": {
+      "type": "string",
+      "description": "Topic to search for, e.g. \"auth\", \"snake_case\", \"blast radius\"."
+    }
+  },
+  "required": [
+    "topic"
+  ]
+}
+```
+
+## Required arguments
+
+- `topic`
+
+## Properties
+
+| Name | Type | Description |
+|------|------|-------------|
+| `topic` | string | Topic to search for, e.g. "auth", "snake_case", "blast radius". |
+
+## See also
+
+- [Index of all MCP tools](./README.md)

package/docs/api/dismiss_gap.md

@@ -0,0 +1,39 @@
+# `dismiss_gap`
+
+Mark a specific gap as intentional. Writes the dismissal to the gaps table so the same gap does not re-surface on the next run. Idempotent — re-dismissing updates the reason. Only call this when the user explicitly says the gap is intentional; never dismiss on your own judgment.
+
+## Input schema
+
+```json
+{
+  "type": "object",
+  "properties": {
+    "gap_hash": {
+      "type": "string",
+      "description": "The gap_hash from get_gaps output."
+    },
+    "reason": {
+      "type": "string",
+      "description": "Short explanation of why this gap is intentional. Optional but strongly encouraged."
+    }
+  },
+  "required": [
+    "gap_hash"
+  ]
+}
+```
+
+## Required arguments
+
+- `gap_hash`
+
+## Properties
+
+| Name | Type | Description |
+|------|------|-------------|
+| `gap_hash` | string | The gap_hash from get_gaps output. |
+| `reason` | string | Short explanation of why this gap is intentional. Optional but strongly encouraged. |
+
+## See also
+
+- [Index of all MCP tools](./README.md)

package/docs/api/dismiss_suggestion.md

@@ -0,0 +1,34 @@
+# `dismiss_suggestion`
+
+Mark a suggestion ID as dismissed for the current session. Acknowledgment-only; the underlying signal still exists.
+
+## Input schema
+
+```json
+{
+  "type": "object",
+  "properties": {
+    "id": {
+      "type": "string",
+      "description": "Suggestion id from get_active_suggestions."
+    }
+  },
+  "required": [
+    "id"
+  ]
+}
+```
+
+## Required arguments
+
+- `id`
+
+## Properties
+
+| Name | Type | Description |
+|------|------|-------------|
+| `id` | string | Suggestion id from get_active_suggestions. |
+
+## See also
+
+- [Index of all MCP tools](./README.md)

package/docs/api/explain_change_in_natural_language.md

@@ -0,0 +1,33 @@
+# `explain_change_in_natural_language`
+
+Given a unified diff, returns a plain-language summary + risk + violation list + suggestions. Powered by validate_diff.
+
+## Input schema
+
+```json
+{
+  "type": "object",
+  "properties": {
+    "diff": {
+      "type": "string"
+    }
+  },
+  "required": [
+    "diff"
+  ]
+}
+```
+
+## Required arguments
+
+- `diff`
+
+## Properties
+
+| Name | Type | Description |
+|------|------|-------------|
+| `diff` | string |  |
+
+## See also
+
+- [Index of all MCP tools](./README.md)

package/docs/api/find_consumers_of_api.md

@@ -0,0 +1,36 @@
+# `find_consumers_of_api`
+
+> ⚠️ **Deprecated (CF-7).** Use `org(view="consumers")` instead. This name still resolves and returns byte-identical output for a deprecation window, but is no longer listed by default and emits a one-line notice.
+
+Across all org repos, find every file importing a given npm/pypi/go/maven target.
+
+## Input schema
+
+```json
+{
+  "type": "object",
+  "properties": {
+    "target": {
+      "type": "string",
+      "description": "Target package or module name"
+    }
+  },
+  "required": [
+    "target"
+  ]
+}
+```
+
+## Required arguments
+
+- `target`
+
+## Properties
+
+| Name | Type | Description |
+|------|------|-------------|
+| `target` | string | Target package or module name |
+
+## See also
+
+- [Index of all MCP tools](./README.md)

package/docs/api/get_action_patterns.md

@@ -0,0 +1,34 @@
+# `get_action_patterns`
+
+> ⚠️ **Deprecated (CF-7).** Use `patterns(kind="actions")` instead. This name still resolves and returns byte-identical output for a deprecation window, but is no longer listed by default and emits a one-line notice.
+
+Procedural patterns mined from git history: "when developers add X, they also touch Y". Filter by natural-language intent.
+
+## Input schema
+
+```json
+{
+  "type": "object",
+  "properties": {
+    "intent": {
+      "type": "string",
+      "description": "Optional intent filter (e.g. \"add route\")."
+    }
+  },
+  "required": []
+}
+```
+
+## Required arguments
+
+_None._
+
+## Properties
+
+| Name | Type | Description |
+|------|------|-------------|
+| `intent` | string | Optional intent filter (e.g. "add route"). |
+
+## See also
+
+- [Index of all MCP tools](./README.md)

package/docs/api/get_active_drift.md

@@ -0,0 +1,32 @@
+# `get_active_drift`
+
+Domains with active drift in the last 7d: growth, threshold breaches. Use to spot domains drifting before they reach a critical event.
+
+## Input schema
+
+```json
+{
+  "type": "object",
+  "properties": {
+    "threshold": {
+      "type": "number",
+      "description": "Drift threshold 0-1 (default 0.2 = 20%)."
+    }
+  },
+  "required": []
+}
+```
+
+## Required arguments
+
+_None._
+
+## Properties
+
+| Name | Type | Description |
+|------|------|-------------|
+| `threshold` | number | Drift threshold 0-1 (default 0.2 = 20%). |
+
+## See also
+
+- [Index of all MCP tools](./README.md)

package/docs/api/get_active_suggestions.md

@@ -0,0 +1,25 @@
+# `get_active_suggestions`
+
+Active Suggestion Engine output. 4 triggers: cross-domain coupling jump, AI session conflict, convention violation mid-session, hotspot threshold crossed. Read periodically.
+
+## Input schema
+
+```json
+{
+  "type": "object",
+  "properties": {},
+  "required": []
+}
+```
+
+## Required arguments
+
+_None._
+
+## Properties
+
+_None._
+
+## See also
+
+- [Index of all MCP tools](./README.md)

package/docs/api/get_ai_cost_attribution.md

@@ -0,0 +1,32 @@
+# `get_ai_cost_attribution`
+
+Per-AI-client decision counts + violation counts. Use to attribute cross-domain coupling cost to individual AI sessions / developers.
+
+## Input schema
+
+```json
+{
+  "type": "object",
+  "properties": {
+    "hours": {
+      "type": "number",
+      "description": "Lookback hours (default 168 = 7d)."
+    }
+  },
+  "required": []
+}
+```
+
+## Required arguments
+
+_None._
+
+## Properties
+
+| Name | Type | Description |
+|------|------|-------------|
+| `hours` | number | Lookback hours (default 168 = 7d). |
+
+## See also
+
+- [Index of all MCP tools](./README.md)

package/docs/api/get_arch_events.md

@@ -0,0 +1,44 @@
+# `get_arch_events`
+
+> ⚠️ **Deprecated (CF-7).** Use `history(view="events")` instead. This name still resolves and returns byte-identical output for a deprecation window, but is no longer listed by default and emits a one-line notice.
+
+Architectural events (domain split, merge, growth, hotspot emergence). Severity filter: minor | major | critical.
+
+## Input schema
+
+```json
+{
+  "type": "object",
+  "properties": {
+    "severity": {
+      "type": "string",
+      "description": "Filter: minor | major | critical."
+    },
+    "kind": {
+      "type": "string",
+      "description": "Optional kind filter (e.g. domain_growth, hotspot_active)."
+    },
+    "time_range": {
+      "type": "string",
+      "description": "Window like \"90d\" (default \"90d\")."
+    }
+  },
+  "required": []
+}
+```
+
+## Required arguments
+
+_None._
+
+## Properties
+
+| Name | Type | Description |
+|------|------|-------------|
+| `severity` | string | Filter: minor \| major \| critical. |
+| `kind` | string | Optional kind filter (e.g. domain_growth, hotspot_active). |
+| `time_range` | string | Window like "90d" (default "90d"). |
+
+## See also
+
+- [Index of all MCP tools](./README.md)

package/docs/api/get_architectural_drift.md

@@ -0,0 +1,39 @@
+# `get_architectural_drift`
+
+> ⚠️ **Deprecated (CF-7).** Use `history(view="drift")` instead. This name still resolves and returns byte-identical output for a deprecation window, but is no longer listed by default and emits a one-line notice.
+
+Per-domain growth/shrink and event count over a time window. Run `carto temporal init` first to backfill from git history.
+
+## Input schema
+
+```json
+{
+  "type": "object",
+  "properties": {
+    "domain": {
+      "type": "string",
+      "description": "Optional domain filter (e.g. AUTH)."
+    },
+    "time_range": {
+      "type": "string",
+      "description": "Window like \"30d\", \"90d\", \"1y\" (default \"30d\")."
+    }
+  },
+  "required": []
+}
+```
+
+## Required arguments
+
+_None._
+
+## Properties
+
+| Name | Type | Description |
+|------|------|-------------|
+| `domain` | string | Optional domain filter (e.g. AUTH). |
+| `time_range` | string | Window like "30d", "90d", "1y" (default "30d"). |
+
+## See also
+
+- [Index of all MCP tools](./README.md)