@archrad/deterministic 0.1.4 → 0.1.5

package/CHANGELOG.md

@@ -7,6 +7,17 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.1.5] - 2026-04-07
+
+### Added
+
+- **`archrad-mcp`** — [Model Context Protocol](https://modelcontextprotocol.io/) server over **stdio** (same deterministic engine as the CLI). Tools: **`archrad_validate_ir`**, **`archrad_lint_summary`**, **`archrad_validate_drift`**, **`archrad_policy_packs_load`**, **`archrad_suggest_fix`** (static remediation per built-in code — **not** generated patches), **`archrad_list_rule_codes`**. IR input: inline **`ir`** or **`irPath`** (JSON file; max **25 MiB**). **`archrad_suggest_fix`** **`docsUrl`** → GitHub **`docs/RULE_CODES.md`**. Scope: **`docs/MCP.md`** (OSS: IR + local paths; no tracking params in tool responses).
+- **Docs:** **`docs/DRIFT.md`** (deterministic drift semantics), **`docs/RULE_CODES.md`** (built-in codes + anchors for MCP **`docsUrl`**), **`docs/MCP.md`** (local testing).
+
+### Fixed
+
+- **CodeQL** `js/polynomial-redos` — linear-time hyphen/underscore edge stripping for **`safeId`** / OpenAPI-derived ids (replaces ambiguous alternation regexes).
+
 ## [0.1.4] - 2026-04-06
 
 ### Added

package/README.md

@@ -2,28 +2,80 @@
 
 ![archrad validate — IR-LINT-DIRECT-DB-ACCESS-002 first, fix on the graph, clean gate](demo-validate.gif)
 
-<!-- GIFs: validate hero — `npm run build && vhs scripts/record-demo-validate.tape` → demo-validate.gif. Drift — `npm run record:demo:drift` → demo-drift.gif (terminal tape) or replay scripts + capture. For “edit → save → validate-drift” (IDE + terminal, skeptic-grade), see scripts/DEMO_GIF_STORYBOARD.md “Trust loop”. scripts/README_DEMO_RECORDING.md. package.json `files`. -->
+![Apache-2.0](https://img.shields.io/badge/license-Apache--2.0-blue) ![no LLM](https://img.shields.io/badge/no%20LLM-deterministic-green) ![no account](https://img.shields.io/badge/no%20account-offline-lightgrey)
 
-**A deterministic compiler and linter for system architecture.**
+Your architecture drifts before you write a single line of code. `archrad validate` catches it — deterministically, in CI, before the PR merges.
 
-**Validate your architecture before you write code.**
+Define your system as a graph. ArchRAD compiles it, lints it against architecture rules, and tells you exactly what's wrong — with rule codes, not opinions.
 
-**For AI agents / IDE assistants:** see **`llms.txt`** in this package (llms.txt-style project summary for tools like Claude Code, Devin, etc.).
+---
+
+## Quick start (60 seconds)
+
+```bash
+npm install -g @archrad/deterministic
+archrad validate --ir fixtures/demo-direct-db-violation.json
+```
+
+You should see something like (exact wording may vary slightly by version):
+
+```
+⚠️ IR-LINT-DIRECT-DB-ACCESS-002: API node "orders-api" connects directly to datastore node "orders-db"
+   Fix: Introduce a service or domain layer between HTTP handlers and persistence.
+```
+
+For a smaller graph (single endpoint, no DB edge), try **`fixtures/minimal-graph.json`** — you will get different warnings (e.g. health/auth heuristics), not **`IR-LINT-DIRECT-DB-ACCESS-002`**.
+
+No IR file yet? Cold-start from an existing OpenAPI spec:
+
+```bash
+archrad ingest openapi --spec ./openapi.yaml --out ./graph.json
+archrad validate --ir ./graph.json
+```
+
+---
+
+## What it does
+
+ArchRAD is a blueprint compiler and governance layer. You define your architecture as an IR — nodes, edges, allowed connections — and ArchRAD validates it against a deterministic rule engine. The same IR, the same rules, the same inputs always produce the same findings.
 
-**Apache-2.0** — blueprint **IR** (JSON graph) → **FastAPI** or **Express** + **OpenAPI**, **Docker**, **Makefile** — **no LLM**, **no account**, **offline**.
+| Command | What it checks | Codes |
+|---------|---------------|-------|
+| `archrad validate` | Graph structure + architecture lint | `IR-STRUCT-*` `IR-LINT-*` |
+| `archrad validate-drift` | IR vs generated code on disk | `DRIFT-*` |
+| `archrad ingest openapi` | Derive IR from existing OpenAPI spec | — |
+| `archrad export` | Compile IR → FastAPI or Express + Docker | — |
+
+## CI integration
+
+```bash
+# Fail on any structural error (default):
+archrad validate --ir ./graph.json
+
+# Also fail on lint warnings:
+archrad validate --ir ./graph.json --fail-on-warning
 
-**OSS positioning:** *Includes structural validation + basic architecture linting (rule-based, deterministic).*
+# Machine-readable output for GitHub Actions:
+archrad validate --ir ./graph.json --json
+```
 
-> This is not only a generator: **`archrad validate`** treats your graph like source code — **IR-STRUCT-*** (shape/refs/cycles) and **IR-LINT-*** (light architecture heuristics: health routes, fan-out, sync chains, HTTP→DB coupling). Then **`archrad export`** compiles to runnable projects. After you have a tree on disk, **`archrad validate-drift`** compares it to a **fresh** export from the same IR (missing/changed files — **not** semantic code review). Generated **OpenAPI** gets a **document-shape** pass (parse + required fields — **not** Spectral-style spec lint).
+## MCP server (Cursor / Claude Desktop)
 
-**Open core (OSS):** **IR structural validation**, **basic architecture lint** (rule-based, deterministic), **OpenAPI document-shape** checks. **ArchRad Cloud** adds **policy / compliance**, deeper **architecture intelligence**, and **AI remediation** — see **`docs/STRUCTURAL_VS_SEMANTIC_VALIDATION.md`**.
+After install, `archrad-mcp` is on your PATH. Add it to your IDE:
 
-### Concept, cold start, and strategy (honest scope)
+```json
+{
+  "mcpServers": {
+    "archrad": { "command": "archrad-mcp" }
+  }
+}
+```
 
-The **core idea** is sound: **IR = what to build**, **codegen = how** — with compiler-style validation and deterministic output. **Adoption friction** is real: this repo is a **compiler with no bundled authoring UI** (JSON/graph in; you bring **ArchRad Cloud**, another tool, or hand-written IR). **Where the IR comes from** is intentionally **plural**: **manual** graph JSON/YAML today, plus **`archrad ingest openapi`** (and more ingestion surfaces over time — e.g. **IaC**). Treat **OpenAPI → IR** as a **starting lane**, not the whole roadmap: regenerate IR in CI, then **`archrad validate`** / **`archrad export`** — structural HTTP surface only, not full system semantics. Draft language for “drift / where does IR come from?” threads: **`scripts/SOCIAL_POST_DRIFT_AND_INGESTION.md`**. **Export is one-way** (no built-in round-trip from edited code back to IR)—best thought of as **scaffold + contract validation**, not full lifecycle architecture sync unless you own that workflow. Many teams will still treat the OSS layer as a **trust and CI artifact** that makes the Cloud/AI path auditable. Read **`docs/CONCEPT_ADOPTION_AND_LIMITS.md`** for the full framing and future directions (e.g. lightweight YAML/IDE ergonomics).
+Your agent can call the same engine as the CLI via **six** MCP tools (e.g. `archrad_validate_ir`, `archrad_lint_summary`, `archrad_validate_drift`, `archrad_policy_packs_load`, `archrad_list_rule_codes`, `archrad_suggest_fix`). See [docs/MCP.md](docs/MCP.md) for parameters and local testing.
 
 ---
 
+
 ## How it works (architecture)
 
 ```
@@ -67,7 +119,7 @@ IR (nodes/edges)  →  validateIrStructural (IR-STRUCT-*)  →  errors block exp
 | **AI remediation** | Repair loops, suggested edits |
 
 1. **IR structural validation:** duplicate/missing node ids, bad HTTP `config.url` / `config.method`, unknown edge endpoints, directed cycles.
-2. **Architecture lint:** Implemented as a **registry of visitor functions** on a parsed graph (`buildParsedLintGraph` → **`LINT_RULE_REGISTRY`** in **`src/lint-rules.ts`**). If the IR cannot be parsed, **`buildParsedLintGraph`** returns **`{ findings }`** (IR-STRUCT-*) instead of **`null`**; use **`isParsedLintGraph()`** or call **`validateIrLint`**, which forwards those findings. Each rule returns **`IrStructuralFinding[]`**; **`runArchitectureLinting`** / **`validateIrLint`** flatten them. **Custom org rules:** compose **`runArchitectureLinting`** with your own **`(g) => findings`** in CI (worked example: **`docs/CUSTOM_RULES.md`**), or **fork** and append to **`LINT_RULE_REGISTRY`** if the stock **`archrad validate`** CLI must emit your codes. CLI **`archrad validate`** / **`archrad export`** print lint under **Architecture lint (IR-LINT-*)** (grouped separately from structural). Codes include **IR-LINT-DIRECT-DB-ACCESS-002**, **IR-LINT-SYNC-CHAIN-001**, **IR-LINT-NO-HEALTHCHECK-003**, **IR-LINT-HIGH-FANOUT-004**, **IR-LINT-ISOLATED-NODE-005**, **IR-LINT-DUPLICATE-EDGE-006**, **IR-LINT-HTTP-MISSING-NAME-007**, **IR-LINT-DATASTORE-NO-INCOMING-008**, **IR-LINT-MULTIPLE-HTTP-ENTRIES-009**. **Sync-chain** depth counts **synchronous** edges only; mark message/queue/async hops via **`edge.metadata.protocol`** / **`config.async`** (see **`edgeRepresentsAsyncBoundary`** in **`lint-graph.ts`** and **`docs/ENGINEERING_NOTES.md`**).
+2. **Architecture lint:** Implemented as a **registry of visitor functions** on a parsed graph (`buildParsedLintGraph` → **`LINT_RULE_REGISTRY`** in **`src/lint-rules.ts`**). If the IR cannot be parsed, **`buildParsedLintGraph`** returns **`{ findings }`** (IR-STRUCT-*) instead of **`null`**; use **`isParsedLintGraph()`** or call **`validateIrLint`**, which forwards those findings. Each rule returns **`IrStructuralFinding[]`**; **`runArchitectureLinting`** / **`validateIrLint`** flatten them. **Custom org rules:** compose **`runArchitectureLinting`** with your own **`(g) => findings`** in CI (worked example: **`docs/CUSTOM_RULES.md`**), or **fork** and append to **`LINT_RULE_REGISTRY`** if the stock **`archrad validate`** CLI must emit your codes. CLI **`archrad validate`** / **`archrad export`** print lint under **Architecture lint (IR-LINT-*)** (grouped separately from structural). Codes include **IR-LINT-DIRECT-DB-ACCESS-002**, **IR-LINT-SYNC-CHAIN-001**, **IR-LINT-NO-HEALTHCHECK-003**, **IR-LINT-HIGH-FANOUT-004**, **IR-LINT-ISOLATED-NODE-005**, **IR-LINT-DUPLICATE-EDGE-006**, **IR-LINT-HTTP-MISSING-NAME-007**, **IR-LINT-DATASTORE-NO-INCOMING-008**, **IR-LINT-MULTIPLE-HTTP-ENTRIES-009**, **IR-LINT-MISSING-AUTH-010**, **IR-LINT-DEAD-NODE-011**. **Sync-chain** depth counts **synchronous** edges only; mark message/queue/async hops via **`edge.metadata.protocol`** / **`config.async`** (see **`edgeRepresentsAsyncBoundary`** in **`lint-graph.ts`** and **`docs/ENGINEERING_NOTES.md`**).
 3. **Generators** → `openapi.yaml`, handlers, deps.
 4. **Golden path** → `make run` / `docker compose up --build`.
 5. **OpenAPI document shape** on the bundle — **not** [Spectral](https://github.com/stoplightio/spectral)-level lint. Issues → **`openApiStructuralWarnings`**.
@@ -76,6 +128,8 @@ IR (nodes/edges)  →  validateIrStructural (IR-STRUCT-*)  →  errors block exp
 
 **Trust builder:** **IR-STRUCT-*** errors block export; **IR-LINT-*** warnings are visible and can **gate CI** via **`--fail-on-warning`** / **`--max-warnings`**; OpenAPI shape issues surface as export warnings.
 
+**Reference (OSS):** **[`docs/DRIFT.md`](docs/DRIFT.md)** (deterministic **`validate-drift`**), **[`docs/RULE_CODES.md`](docs/RULE_CODES.md)** (finding codes; MCP **`docsUrl`** targets GitHub anchors), **[`docs/MCP.md`](docs/MCP.md)** (MCP tools + local testing).
+
 ### Codegen vs validation (retry, timeouts, policy)
 
 Generators **may emit** retry/timeout/circuit-breaker **code** when the IR carries matching edge or node config (e.g. `retryPolicy`). That is **code generation**, not a guarantee. OSS does **not** currently **require** or **lint** “every external call must have timeout/retry” — that class of rule is **semantic / policy** and fits **ArchRad Cloud** or custom linters on top of the IR.
@@ -92,10 +146,17 @@ Generators **may emit** retry/timeout/circuit-breaker **code** when the IR carri
 | **CLI validate** | CI / pre-commit: IR structural + architecture lint, no codegen | `archrad validate --ir graph.json` |
 | **CLI validate-drift** | After export or merges: on-disk tree vs fresh deterministic export from same IR | `archrad validate-drift -i graph.json -t python -o ./out` |
 | **Library** (`@archrad/deterministic`) | IDPs / pipelines | `runDeterministicExport` → files + findings; **`runValidateDrift`** / **`runDriftCheckAgainstFiles`** for drift |
+| **MCP** (`archrad-mcp`) | Cursor / Claude Desktop / other MCP hosts | stdio server: validate IR, lint summary, drift, policy packs, static **`archrad_suggest_fix`** — see **`docs/MCP.md`** |
+
+**MCP (Cursor example):** after `npm i -g @archrad/deterministic` (or `npx`), add a server with command **`archrad-mcp`** and no args (stdio). Pass **`ir`** inline or **`irPath`** to a JSON file for large graphs. **`archrad_suggest_fix`** returns curated text for a finding code (e.g. `IR-LINT-MISSING-AUTH-010`) — not machine-generated IR patches. **Step-by-step testing** (smoke script, MCP Inspector, Cursor chat prompts): **`docs/MCP.md`**, section **Local testing**.
 
 ### CLI
 
-**Input is structured IR (JSON), not natural language.** There is no `archrad export --prompt "..."`. You pass a **graph file** (nodes/edges) like **`fixtures/minimal-graph.json`**. The **npm README GIF** uses **`fixtures/demo-direct-db-violation.json`** → **`fixtures/demo-direct-db-layered.json`**: **failure-first** **`IR-LINT-DIRECT-DB-ACCESS-002`**, fix on the graph, then a **clean** validate (no codegen in the clip). For a graph that hits **many** lint rules at once (stress test), use **`fixtures/ecommerce-with-warnings.json`**. For a **golden payment + retry** graph (edge `config.retry.maxAttempts` + payment node `config.retryPolicy`, both `3`), use **`fixtures/payment-retry-demo.json`** — export shows **`retry_policy`** / retry helpers in **`app/main.py`**. Record that path with **`scripts/record-demo-payment-retry.tape`** (→ **`demo-payment-retry.gif`**). **Drift clip:** **`scripts/record-demo-drift.tape`** / **`npm run record:demo:drift`** (→ **`demo-drift.gif`**) — export, **`tail`** before/after a one-line tamper on **`out/app/main.py`**, then **`validate-drift`**; if **VHS** fails on your machine, run **`scripts/run-demo-drift-sequence.ps1`** or **`.sh`** while screen-capturing (see **`scripts/README_DEMO_RECORDING.md`**). See **`scripts/DEMO_GIF_STORYBOARD.md`** for all tapes. **CLI:** `--target python` is the FastAPI bundle; there is no separate `fastapi` target name. To go from **plain English → IR**, use **ArchRad Cloud** or your own LLM step; this package only does **IR → files**.
+**Input is structured IR (JSON), not natural language.** There is no `archrad export --prompt "..."`. Pass a **graph file** (nodes/edges).
+
+**Fixtures** (in this repo): **`fixtures/minimal-graph.json`** (small); **`fixtures/demo-direct-db-violation.json`** / **`fixtures/demo-direct-db-layered.json`** (before/after **`IR-LINT-DIRECT-DB-ACCESS-002`**); **`fixtures/ecommerce-with-warnings.json`** (many lint rules); **`fixtures/payment-retry-demo.json`** (retry-related codegen in export). **`--target python`** is the FastAPI bundle; there is no separate `fastapi` target. To go from **plain English → IR**, use **ArchRad Cloud** or your own LLM step; this package only does **IR → files**.
+
+**Recording demos and GIFs** (VHS, storyboards, drift replay): **`scripts/README_DEMO_RECORDING.md`** only — not required to use the CLI.
 
 **OpenAPI → JSON (spec as source of truth):** each operation under `paths` becomes an `http` node (`config.url` + `config.method`). Then validate and export like any other IR:
 
@@ -117,16 +178,13 @@ archrad validate --ir ./graph.json
 
 YAML must have either top-level **`graph:`** (object) or top-level **`nodes:`** (array); bare graphs are wrapped as `{ "graph": { ... } }` automatically.
 
-After `npm run build` (required after `npm ci`; there is no `prepare` hook — see **`docs/ENGINEERING_NOTES.md`**):
+**After `npm install -g` or `npx`** (typical):
 
 ```bash
-node dist/cli.js export --ir fixtures/minimal-graph.json --target python --out ./my-api
-node dist/cli.js yaml-to-ir --yaml fixtures/minimal-graph.yaml --out /tmp/ir.json
-# After global install / npx:
 archrad export --ir ./graph.json --target node --out ./my-express-api
 
 # Validate IR (structural + architecture lint). Pretty output; exit 1 on structural errors by default:
-node dist/cli.js validate --ir fixtures/minimal-graph.json
+archrad validate --ir ./graph.json
 # Machine-readable + CI gates:
 archrad validate --ir ./graph.json --json
 archrad validate --ir ./graph.json --fail-on-warning
@@ -137,6 +195,8 @@ archrad validate --ir ./graph.json --skip-lint
 archrad validate --ir ./graph.json --policies ./policy-packs
 ```
 
+**From a git clone** (contributors): run **`npm ci && npm run build`** in the package root (there is no `prepare` hook — see **`docs/ENGINEERING_NOTES.md`**), then use **`node dist/cli.js`** the same way you would use **`archrad`** (e.g. **`node dist/cli.js validate --ir fixtures/minimal-graph.json`**).
+
 **Deterministic drift (thin, OSS):** compare an existing export tree on disk to a **fresh** export from the same IR. Detects **missing** / **changed** generated files (line endings normalized). Optional **`--strict-extra`** flags files present on disk but not in the reference export. Not semantic “does code match intent” — **ArchRad Cloud** adds builder/UI drift checks and broader governance.
 
 ```bash
@@ -149,8 +209,6 @@ archrad validate-drift -i ./graph.json -t python -o ./out --skip-host-port-check
 archrad validate-drift -i ./graph.json -t python -o ./out --strict-extra
 ```
 
-Regenerate the matching clip: **`npm run record:demo:drift`** (VHS) → **`demo-drift.gif`**, or **`scripts/run-demo-drift-sequence.ps1`** / **`.sh`** + ShareX/OBS if VHS is unavailable (see **`scripts/DEMO_GIF_STORYBOARD.md`**).
-
 #### Example: validate architecture
 
 ```bash
@@ -183,13 +241,6 @@ By default, if **8080** (or your `--host-port`) looks **busy** on localhost, the
 
 **Export** runs **IR structural validation**, then **architecture lint**, then codegen. **Structural errors** abort with **no files written**. **`irLintFindings`** contains only **`IR-LINT-*`**; **`IR-STRUCT-*`** from a failed parse always appear under **`irStructuralFindings`** (including when structural validation was skipped). **Lint warnings** print by default; use **`--fail-on-warning`** / **`--max-warnings`** to block writes for CI.
 
-### Validate the package as a developer
-
-1. `cd packages/deterministic && npm ci && npm run build && npm test`
-2. `node dist/cli.js export --ir fixtures/minimal-graph.json --target python --out ./tmp-out`
-3. `cd tmp-out && make run` then `curl` the URL shown in the generated **README** (port matches `--host-port` if you set it).
-4. Optional: `node dist/cli.js export ... --host-port 18080` if **8080** is already taken.
-
 ### Library
 
 ```typescript
@@ -224,9 +275,9 @@ Optional: `isLocalHostPortFree` / `normalizeGoldenHostPort` from the same packag
 
 ---
 
-## Golden path (~60 seconds)
+## Golden path (contributors — local clone)
 
-From the package root (after build):
+This path assumes you **cloned the repo** and ran **`npm ci && npm run build`** in the package root. If you only installed with **`npm install -g @archrad/deterministic`**, use **`archrad`** instead of **`node dist/cli.js`** (same flags).
 
 ```bash
 node dist/cli.js export --ir fixtures/minimal-graph.json --target python --out ./out
@@ -238,13 +289,9 @@ curl -sS -X POST http://localhost:8080/signup -H "Content-Type: application/json
 
 You should see **422 Unprocessable Entity** (FastAPI/Pydantic) or **400** with a clear body — proof the stack is live and validation matches the spec, not a silent 500.
 
-**Helper script** (prints the same flow; use when recording a terminal GIF):
-
-```bash
-bash scripts/golden-path-demo.sh
-```
+Quick check from a clone: **`cd packages/deterministic && npm ci && npm run build && npm test`**, then export to **`./tmp-out`**, **`cd tmp-out && make run`**, **`curl`** as above. Use **`--host-port 18080`** (or **`node dist/cli.js export ... --host-port 18080`**) if **8080** is busy.
 
-See **`scripts/README_DEMO_RECORDING.md`** for **VHS / asciinema / ttyrec** tips, **When VHS fails**, **drift** replay scripts, and the **trust loop** (IDE edit + terminal **`validate-drift`**). The hero GIF at the top is **`demo-validate.gif`**; **`demo-drift.gif`** and the **trust-loop** storyboard live in **`scripts/DEMO_GIF_STORYBOARD.md`**.
+Optional: **`bash scripts/golden-path-demo.sh`** runs the same flow. **Demo recording** (GIFs, tapes, drift replays): **`scripts/README_DEMO_RECORDING.md`**.
 
 ---
 
@@ -261,20 +308,6 @@ See **`scripts/README_DEMO_RECORDING.md`** for **VHS / asciinema / ttyrec** tips
 
 You can depend on this CLI and library **without** ArchRad Cloud. The cloud product stacks collaboration and AI on top of the same deterministic contract.
 
-**InkByte vs this package:** Deeper workflow analysis, enterprise validation routes, and LLM-assisted flows may exist in the **private InkByte monorepo** (`server/`, etc.); they are **not** part of the **`@archrad/deterministic`** npm surface unless shipped here. This README describes **only** what the OSS package proves.
-
----
-
-## Monorepo vs public OSS repo
-
-The **canonical source** for this engine may live in a **private monorepo** next to the full product; `server` can depend on `file:../packages/deterministic`. The **public** GitHub repo should contain **only** this package — canonical clone: **`https://github.com/archradhq/arch-deterministic`**. Subtree publish: **`docs/OSS_VS_PRODUCT_REPOS.md`** and **`docs/PUBLISH_DETERMINISTIC_OSS.md`** (in the product monorepo).
-
----
-
-## Publishing the public OSS repo
-
-From the private monorepo root: **`docs/PUBLISH_DETERMINISTIC_OSS.md`**. This tree includes **`.github/workflows/ci.yml`** and **Dependabot**; they run when this folder is the **git root** of the public repo.
-
 ---
 
 ## Contributing

package/biome.json

@@ -1,25 +1,32 @@
-{
-  "$schema": "https://biomejs.dev/schemas/1.9.4/schema.json",
-  "vcs": { "enabled": true, "clientKind": "git", "useIgnoreFile": true },
-  "files": {
-    "ignore": ["dist", "node_modules", "*.json", "fixtures", "schemas"]
-  },
-  "formatter": {
-    "enabled": false
-  },
-  "organizeImports": { "enabled": false },
-  "linter": {
-    "enabled": true,
-    "rules": {
-      "recommended": false,
-      "suspicious": {
-        "noDebugger": "error"
-      }
-    }
-  },
-  "javascript": {
-    "formatter": {
-      "quoteStyle": "single"
-    }
-  }
-}
+{
+	"$schema": "https://biomejs.dev/schemas/2.4.10/schema.json",
+	"vcs": { "enabled": true, "clientKind": "git", "useIgnoreFile": true },
+	"files": {
+		"includes": [
+			"**",
+			"!**/dist",
+			"!**/node_modules",
+			"!**/*.json",
+			"!**/fixtures",
+			"!**/schemas"
+		]
+	},
+	"formatter": {
+		"enabled": false
+	},
+	"assist": { "actions": { "source": { "organizeImports": "off" } } },
+	"linter": {
+		"enabled": true,
+		"rules": {
+			"recommended": false,
+			"suspicious": {
+				"noDebugger": "error"
+			}
+		}
+	},
+	"javascript": {
+		"formatter": {
+			"quoteStyle": "single"
+		}
+	}
+}

package/dist/cli.js

@@ -76,7 +76,7 @@ const program = new Command();
 program
     .name('archrad')
     .description('Validate your architecture before you write code. Deterministic compiler + linter — FastAPI / Express (no LLM, no server).')
-    .version('0.1.4');
+    .version('0.1.5');
 program
     .command('validate')
     .description('Validate your architecture before you write code — IR structural (IR-STRUCT-*) + architecture lint (IR-LINT-*)')

package/dist/mcp-server.d.ts

@@ -0,0 +1,7 @@
+#!/usr/bin/env node
+/**
+ * archrad-mcp — Model Context Protocol server (stdio) for deterministic IR validation,
+ * architecture lint, policy packs, and drift checks. Uses the same engine as `archrad` CLI.
+ */
+export {};
+//# sourceMappingURL=mcp-server.d.ts.map

package/dist/mcp-server.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mcp-server.d.ts","sourceRoot":"","sources":["../src/mcp-server.ts"],"names":[],"mappings":";AACA;;;GAGG"}

package/dist/mcp-server.js

@@ -0,0 +1,236 @@
+#!/usr/bin/env node
+/**
+ * archrad-mcp — Model Context Protocol server (stdio) for deterministic IR validation,
+ * architecture lint, policy packs, and drift checks. Uses the same engine as `archrad` CLI.
+ */
+import { readFile, stat } from 'node:fs/promises';
+import { resolve } from 'node:path';
+import { z } from 'zod';
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { normalizeIrGraph, validateIrStructural, validateIrLint, runValidateDrift, sortFindings, loadPolicyPacksFromDirectory, loadPolicyPacksFromFiles, } from './index.js';
+import { getStaticRuleGuidance, listStaticRuleCodes } from './static-rule-guidance.js';
+const VERSION = '0.1.5';
+/** Hard cap for `irPath` reads (see docs/MCP.md). */
+const MAX_IR_FILE_BYTES = 25 * 1024 * 1024;
+const irSourceSchema = {
+    ir: z.unknown().optional(),
+    irPath: z.string().optional(),
+};
+function jsonResult(payload) {
+    return {
+        content: [{ type: 'text', text: JSON.stringify(payload, null, 2) }],
+    };
+}
+async function loadIrFromArgs(args) {
+    const hasInline = args.ir !== undefined;
+    const hasPath = args.irPath != null && String(args.irPath).trim() !== '';
+    if (hasInline && hasPath) {
+        return { ok: false, error: 'Provide only one of `ir` or `irPath`.' };
+    }
+    if (hasPath) {
+        const p = resolve(args.irPath);
+        let st;
+        try {
+            st = await stat(p);
+        }
+        catch (e) {
+            return { ok: false, error: `irPath not readable: ${e instanceof Error ? e.message : String(e)}` };
+        }
+        if (!st.isFile()) {
+            return { ok: false, error: `irPath is not a file: ${p}` };
+        }
+        if (st.size > MAX_IR_FILE_BYTES) {
+            return {
+                ok: false,
+                error: `IR file is ${st.size} bytes (max ${MAX_IR_FILE_BYTES}). Split the graph, trim fixtures, or validate smaller subgraphs.`,
+            };
+        }
+        const raw = await readFile(p, 'utf8');
+        try {
+            return { ok: true, ir: JSON.parse(raw) };
+        }
+        catch (e) {
+            return { ok: false, error: `Invalid JSON in irPath: ${e instanceof Error ? e.message : String(e)}` };
+        }
+    }
+    if (hasInline) {
+        return { ok: true, ir: args.ir };
+    }
+    return { ok: false, error: 'Provide `ir` (inline JSON) or `irPath` (path to IR JSON file).' };
+}
+async function main() {
+    const server = new McpServer({
+        name: 'archrad-deterministic',
+        version: VERSION,
+    });
+    server.registerTool('archrad_suggest_fix', {
+        title: 'Static remediation for a finding code',
+        description: 'Deterministic title, remediation text, and canonical docs URL for a built-in IR-STRUCT / IR-LINT / DRIFT code. Does not generate patches or IR edits.',
+        inputSchema: {
+            findingCode: z.string().min(1),
+        },
+    }, async (args) => {
+        const g = getStaticRuleGuidance(args.findingCode);
+        if (!g) {
+            return jsonResult({
+                ok: false,
+                findingCode: args.findingCode,
+                error: 'Unknown built-in code. PolicyPack and org rules use custom rule ids in YAML — see your pack. Use archrad_list_rule_codes for built-in codes.',
+            });
+        }
+        return jsonResult({ ok: true, ...g });
+    });
+    server.registerTool('archrad_list_rule_codes', {
+        title: 'List built-in rule codes',
+        description: 'Sorted list of IR-STRUCT-*, IR-LINT-*, and DRIFT-* codes that have static guidance via archrad_suggest_fix.',
+        inputSchema: {},
+    }, async () => jsonResult({ codes: listStaticRuleCodes() }));
+    server.registerTool('archrad_validate_ir', {
+        title: 'Validate IR (structural + IR-LINT)',
+        description: 'Run deterministic structural validation (IR-STRUCT-*) and architecture lint (IR-LINT-*). Pass `ir` inline or `irPath` to a JSON file (recommended for large graphs). Optional local PolicyPack directory.',
+        inputSchema: {
+            ...irSourceSchema,
+            policiesDirectory: z.string().optional(),
+        },
+    }, async (args) => {
+        const loaded = await loadIrFromArgs(args);
+        if (!loaded.ok)
+            return jsonResult({ ok: false, phase: 'input', error: loaded.error });
+        const irRaw = loaded.ir;
+        const norm = normalizeIrGraph(irRaw);
+        if ('findings' in norm) {
+            return jsonResult({ ok: false, phase: 'normalize', findings: norm.findings });
+        }
+        const structural = validateIrStructural(irRaw);
+        let policyRuleVisitors;
+        if (args.policiesDirectory) {
+            const dir = resolve(args.policiesDirectory);
+            const packLoaded = await loadPolicyPacksFromDirectory(dir);
+            if (!packLoaded.ok) {
+                return jsonResult({ ok: false, phase: 'policy_packs', errors: packLoaded.errors });
+            }
+            policyRuleVisitors = packLoaded.visitors;
+        }
+        const irLintFindings = validateIrLint(irRaw, { policyRuleVisitors });
+        const combined = sortFindings([...structural, ...irLintFindings]);
+        return jsonResult({
+            ok: combined.every((f) => f.severity !== 'error'),
+            irStructuralFindings: structural,
+            irLintFindings,
+            combined,
+        });
+    });
+    server.registerTool('archrad_lint_summary', {
+        title: 'Lint summary',
+        description: 'Short text summary of IR structural + lint findings. Use `ir` or `irPath` (see archrad_validate_ir).',
+        inputSchema: {
+            ...irSourceSchema,
+            policiesDirectory: z.string().optional(),
+        },
+    }, async (args) => {
+        const loaded = await loadIrFromArgs(args);
+        if (!loaded.ok)
+            return jsonResult({ summary: loaded.error });
+        const irRaw = loaded.ir;
+        const norm = normalizeIrGraph(irRaw);
+        if ('findings' in norm) {
+            return jsonResult({ summary: `Normalize failed: ${norm.findings.map((f) => f.message).join('; ')}` });
+        }
+        const structural = validateIrStructural(irRaw);
+        let policyRuleVisitors;
+        if (args.policiesDirectory) {
+            const packLoaded = await loadPolicyPacksFromDirectory(resolve(args.policiesDirectory));
+            if (!packLoaded.ok) {
+                return jsonResult({ summary: `Policy packs failed: ${packLoaded.errors.join('; ')}` });
+            }
+            policyRuleVisitors = packLoaded.visitors;
+        }
+        const irLintFindings = validateIrLint(irRaw, { policyRuleVisitors });
+        const combined = sortFindings([...structural, ...irLintFindings]);
+        const errors = combined.filter((f) => f.severity === 'error');
+        const warnings = combined.filter((f) => f.severity === 'warning');
+        const lines = [
+            `Findings: ${combined.length} (${errors.length} errors, ${warnings.length} warnings).`,
+            ...combined.slice(0, 20).map((f) => `- [${f.code}] ${f.message}`),
+        ];
+        if (combined.length > 20)
+            lines.push(`… and ${combined.length - 20} more.`);
+        return jsonResult({ summary: lines.join('\n'), counts: { total: combined.length, errors: errors.length, warnings: warnings.length } });
+    });
+    server.registerTool('archrad_validate_drift', {
+        title: 'Validate drift',
+        description: 'Compare on-disk export to a fresh deterministic export. Pass `ir` or `irPath` (JSON file).',
+        inputSchema: {
+            ...irSourceSchema,
+            target: z.enum(['python', 'node', 'nodejs']),
+            exportDir: z.string(),
+            policiesDirectory: z.string().optional(),
+            skipIrLint: z.boolean().optional(),
+        },
+    }, async (args) => {
+        const loaded = await loadIrFromArgs(args);
+        if (!loaded.ok)
+            return jsonResult({ ok: false, phase: 'input', error: loaded.error });
+        const irRaw = loaded.ir;
+        const norm = normalizeIrGraph(irRaw);
+        if ('findings' in norm) {
+            return jsonResult({ ok: false, phase: 'normalize', findings: norm.findings });
+        }
+        const actualIR = irRaw && typeof irRaw === 'object' && irRaw !== null && 'graph' in irRaw
+            ? irRaw
+            : { graph: norm.graph };
+        let policyRuleVisitors;
+        if (args.policiesDirectory) {
+            const packLoaded = await loadPolicyPacksFromDirectory(resolve(args.policiesDirectory));
+            if (!packLoaded.ok) {
+                return jsonResult({ ok: false, phase: 'policy_packs', errors: packLoaded.errors });
+            }
+            policyRuleVisitors = packLoaded.visitors;
+        }
+        const outDir = resolve(args.exportDir);
+        const result = await runValidateDrift(actualIR, args.target, outDir, {
+            skipIrLint: args.skipIrLint ?? false,
+            policyRuleVisitors,
+        });
+        return jsonResult({
+            ok: result.ok,
+            driftFindings: result.driftFindings,
+            extraBlocking: result.extraBlocking,
+            irStructuralFindings: result.exportResult.irStructuralFindings,
+            irLintFindings: result.exportResult.irLintFindings,
+        });
+    });
+    server.registerTool('archrad_policy_packs_load', {
+        title: 'Load policy packs',
+        description: 'Compile PolicyPack YAML/JSON from a directory or from in-memory file list.',
+        inputSchema: {
+            directory: z.string().optional(),
+            files: z
+                .array(z.object({ name: z.string(), content: z.string() }))
+                .optional(),
+        },
+    }, async (args) => {
+        if (args.files && args.files.length > 0) {
+            const loaded = loadPolicyPacksFromFiles(args.files.map((f) => ({ name: f.name, content: f.content })));
+            if (!loaded.ok) {
+                return jsonResult({ ok: false, errors: loaded.errors });
+            }
+            return jsonResult({ ok: true, ruleCount: loaded.ruleCount });
+        }
+        if (args.directory) {
+            const loaded = await loadPolicyPacksFromDirectory(resolve(args.directory));
+            if (!loaded.ok) {
+                return jsonResult({ ok: false, errors: loaded.errors });
+            }
+            return jsonResult({ ok: true, ruleCount: loaded.ruleCount });
+        }
+        return jsonResult({ ok: false, error: 'Provide `directory` or `files`.' });
+    });
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+}
+main().catch((err) => {
+    console.error('archrad-mcp:', err);
+    process.exitCode = 1;
+});

package/dist/nodeExpress.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"nodeExpress.d.ts","sourceRoot":"","sources":["../src/nodeExpress.ts"],"names":[],"mappings":"AAIA,wBAA8B,wBAAwB,CAAC,QAAQ,EAAE,GAAG,EAAE,IAAI,GAAE,GAAQ,GAAG,OAAO,CAAC,MAAM,CAAC,MAAM,EAAC,MAAM,CAAC,CAAC,CAuapH"}
+{"version":3,"file":"nodeExpress.d.ts","sourceRoot":"","sources":["../src/nodeExpress.ts"],"names":[],"mappings":"AAKA,wBAA8B,wBAAwB,CAAC,QAAQ,EAAE,GAAG,EAAE,IAAI,GAAE,GAAQ,GAAG,OAAO,CAAC,MAAM,CAAC,MAAM,EAAC,MAAM,CAAC,CAAC,CA0apH"}

package/dist/nodeExpress.js

@@ -1,6 +1,7 @@
 // Deterministic Node Express exporter (skeleton)
 // Exports a map of filename -> content for a generated Express app.
 import { getEdgeConfig, generateRetryCode, generateCircuitBreakerCode } from './edgeConfigCodeGenerator.js';
+import { MAX_UNTRUSTED_STRING_LEN, stripLeadingTrailingHyphens } from './stringEdgeStrip.js';
 export default async function generateNodeExpressFiles(actualIR, opts = {}) {
     const files = {};
     const graph = (actualIR && actualIR.graph) ? actualIR.graph : (actualIR || {});
@@ -12,7 +13,10 @@ export default async function generateNodeExpressFiles(actualIR, opts = {}) {
     const nonHttpNodes = [];
     // Track edge config utilities (retry, circuit breaker) to include once
     const edgeUtilityCode = new Set();
-    function safeId(id) { return String(id || '').replace(/[^A-Za-z0-9_\-]/g, '-').replace(/^-+|-+$/g, '').toLowerCase() || 'node'; }
+    function safeId(id) {
+        const raw = String(id || '').slice(0, MAX_UNTRUSTED_STRING_LEN);
+        return stripLeadingTrailingHyphens(raw.replace(/[^A-Za-z0-9_\-]/g, '-')).toLowerCase() || 'node';
+    }
     function handlerName(n) { return `handler_${safeId(n && (n.id || n.name))}`.replace(/-/g, '_'); }
     /**
      * Generate code for inner nodes (support nodes) that are embedded within a key node

package/dist/openapi-to-ir.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"openapi-to-ir.d.ts","sourceRoot":"","sources":["../src/openapi-to-ir.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAIH,qBAAa,kBAAmB,SAAQ,KAAK;gBAC/B,OAAO,EAAE,MAAM;CAI5B;AAuBD,MAAM,MAAM,eAAe,GAAG;IAC5B,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACjC,CAAC;AAEF;;GAEG;AACH,wBAAgB,0BAA0B,CAAC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,eAAe,EAAE,CAqD1F;AAyDD;;GAEG;AACH,wBAAgB,4BAA4B,CAAC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAgClG;AAED,wBAAgB,0BAA0B,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAMnF;AAED,wBAAgB,2BAA2B,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAQnF"}
+{"version":3,"file":"openapi-to-ir.d.ts","sourceRoot":"","sources":["../src/openapi-to-ir.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAKH,qBAAa,kBAAmB,SAAQ,KAAK;gBAC/B,OAAO,EAAE,MAAM;CAI5B;AA0BD,MAAM,MAAM,eAAe,GAAG;IAC5B,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACjC,CAAC;AAEF;;GAEG;AACH,wBAAgB,0BAA0B,CAAC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,eAAe,EAAE,CAqD1F;AAyDD;;GAEG;AACH,wBAAgB,4BAA4B,CAAC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAgClG;AAED,wBAAgB,0BAA0B,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAMnF;AAED,wBAAgB,2BAA2B,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAQnF"}

package/dist/openapi-to-ir.js

@@ -4,6 +4,7 @@
  * This is not semantic architecture truth — only operations under `paths` become `http` nodes.
  */
 import { parseOpenApiString, validateOpenApiStructural } from './openapi-structural.js';
+import { MAX_UNTRUSTED_STRING_LEN, stripLeadingTrailingHyphens, stripLeadingTrailingUnderscores } from './stringEdgeStrip.js';
 export class OpenApiIngestError extends Error {
     constructor(message) {
         super(message);
@@ -16,15 +17,16 @@ function normalizeOpenApiPath(pathKey) {
     return s.startsWith('/') ? s : `/${s}`;
 }
 function safeServiceName(title) {
-    const t = String(title || 'openapi-service')
+    const t = stripLeadingTrailingHyphens(String(title || 'openapi-service')
         .trim()
-        .replace(/[^a-zA-Z0-9_-]+/g, '-')
-        .replace(/^-+|-+$/g, '')
+        .slice(0, 256)
+        .replace(/[^a-zA-Z0-9_-]+/g, '-'))
         .toLowerCase();
     return t.slice(0, 63) || 'openapi-service';
 }
 function safeNodeId(path, method) {
-    const slug = `${method}_${path}`.replace(/[^a-zA-Z0-9]+/g, '_').replace(/^_|_$/g, '').toLowerCase();
+    const combined = `${method}_${path}`.slice(0, MAX_UNTRUSTED_STRING_LEN);
+    const slug = stripLeadingTrailingUnderscores(combined.replace(/[^a-zA-Z0-9]+/g, '_')).toLowerCase();
     return `openapi_${slug || 'route'}`.slice(0, 80);
 }
 /**

package/dist/pythonFastAPI.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"pythonFastAPI.d.ts","sourceRoot":"","sources":["../src/pythonFastAPI.ts"],"names":[],"mappings":"AA4OA,wBAA8B,0BAA0B,CAAC,QAAQ,EAAE,GAAG,EAAE,IAAI,GAAE,GAAQ,GAAG,OAAO,CAAC,MAAM,CAAC,MAAM,EAAC,MAAM,CAAC,CAAC,CA2ctH"}
+{"version":3,"file":"pythonFastAPI.d.ts","sourceRoot":"","sources":["../src/pythonFastAPI.ts"],"names":[],"mappings":"AA8OA,wBAA8B,0BAA0B,CAAC,QAAQ,EAAE,GAAG,EAAE,IAAI,GAAE,GAAQ,GAAG,OAAO,CAAC,MAAM,CAAC,MAAM,EAAC,MAAM,CAAC,CAAC,CA2ctH"}