@archrad/deterministic 0.1.4 → 0.1.5

package/dist/pythonFastAPI.js

@@ -1,8 +1,10 @@
 // Deterministic Python FastAPI exporter
 // Produces a map of filename -> content given an IR (plan graph) and options.
 import { getEdgeConfig, generateRetryCode, generateCircuitBreakerCode } from './edgeConfigCodeGenerator.js';
+import { MAX_UNTRUSTED_STRING_LEN, stripLeadingTrailingHyphens } from './stringEdgeStrip.js';
 function safeId(id) {
-    return String(id || '').replace(/[^A-Za-z0-9_\-]/g, '-').replace(/^-+|-+$/g, '').toLowerCase() || 'node';
+    const raw = String(id || '').slice(0, MAX_UNTRUSTED_STRING_LEN);
+    return stripLeadingTrailingHyphens(raw.replace(/[^A-Za-z0-9_\-]/g, '-')).toLowerCase() || 'node';
 }
 function handlerNameFor(n) {
     if (n && n.config && n.config.name)

package/dist/static-rule-guidance.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Static, deterministic remediation text for built-in finding codes (IR-STRUCT-*, IR-LINT-*, DRIFT-*).
+ * Used by MCP `archrad_suggest_fix` — not generated architecture; same hints the engine documents in findings.
+ */
+export type StaticRuleGuidance = {
+    findingCode: string;
+    title: string;
+    remediation: string;
+    /** Canonical docs path (no analytics/query params). */
+    docsUrl: string;
+};
+/** Public OSS repo (subtree); `docs/` is at repo root in arch-deterministic. */
+export declare const RULE_CODES_DOC_BASE = "https://github.com/archradhq/arch-deterministic/blob/main/docs/RULE_CODES.md";
+/** GitHub heading anchor (must match markdown `## CODE` in docs/RULE_CODES.md). */
+export declare function githubRuleCodeAnchor(code: string): string;
+export declare function docsUrlForFindingCode(code: string): string;
+export declare function listStaticRuleCodes(): string[];
+export declare function getStaticRuleGuidance(findingCode: string): StaticRuleGuidance | null;
+//# sourceMappingURL=static-rule-guidance.d.ts.map

package/dist/static-rule-guidance.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"static-rule-guidance.d.ts","sourceRoot":"","sources":["../src/static-rule-guidance.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,MAAM,MAAM,kBAAkB,GAAG;IAC/B,WAAW,EAAE,MAAM,CAAC;IACpB,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,EAAE,MAAM,CAAC;IACpB,uDAAuD;IACvD,OAAO,EAAE,MAAM,CAAC;CACjB,CAAC;AAEF,gFAAgF;AAChF,eAAO,MAAM,mBAAmB,iFACgD,CAAC;AAEjF,mFAAmF;AACnF,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAKzD;AAED,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAE1D;AA2KD,wBAAgB,mBAAmB,IAAI,MAAM,EAAE,CAE9C;AAED,wBAAgB,qBAAqB,CAAC,WAAW,EAAE,MAAM,GAAG,kBAAkB,GAAG,IAAI,CASpF"}

package/dist/static-rule-guidance.js

@@ -0,0 +1,165 @@
+/**
+ * Static, deterministic remediation text for built-in finding codes (IR-STRUCT-*, IR-LINT-*, DRIFT-*).
+ * Used by MCP `archrad_suggest_fix` — not generated architecture; same hints the engine documents in findings.
+ */
+/** Public OSS repo (subtree); `docs/` is at repo root in arch-deterministic. */
+export const RULE_CODES_DOC_BASE = 'https://github.com/archradhq/arch-deterministic/blob/main/docs/RULE_CODES.md';
+/** GitHub heading anchor (must match markdown `## CODE` in docs/RULE_CODES.md). */
+export function githubRuleCodeAnchor(code) {
+    return code
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, '-')
+        .replace(/^-|-$/g, '');
+}
+export function docsUrlForFindingCode(code) {
+    return `${RULE_CODES_DOC_BASE}#${githubRuleCodeAnchor(code)}`;
+}
+/** Built-in codes with curated guidance. Org PolicyPack codes (e.g. ORG-*) are not listed here. */
+const GUIDANCE = {
+    'IR-LINT-DIRECT-DB-ACCESS-002': {
+        title: 'HTTP-like node connects directly to a datastore',
+        remediation: 'Introduce a service or domain layer between HTTP handlers and persistence: add intermediate nodes and edges so the API does not couple directly to a single DB node. This preserves testability, storage swaps, and invariant enforcement at a clear boundary.',
+    },
+    'IR-LINT-HIGH-FANOUT-004': {
+        title: 'High outgoing dependency count',
+        remediation: 'Reduce fan-out: split responsibilities, add a facade, batch calls, or use async handoff (queues) so one node does not synchronously depend on many downstreams. High fan-out increases blast radius and latency under load.',
+    },
+    'IR-LINT-SYNC-CHAIN-001': {
+        title: 'Long synchronous chain from HTTP entry',
+        remediation: 'Shorten the synchronous call graph or mark non-blocking hops as async: set `metadata.protocol` / edge metadata for async boundaries, or `config.async` where applicable, so depth reflects real execution. Deep sync chains amplify latency and failures.',
+    },
+    'IR-LINT-NO-HEALTHCHECK-003': {
+        title: 'No typical health/readiness route on HTTP nodes',
+        remediation: 'Add at least one GET route such as `/health` or `/ready` on an HTTP node (or document a dedicated health node). Orchestrators and load balancers rely on these for safe deploys and rollbacks.',
+    },
+    'IR-LINT-ISOLATED-NODE-005': {
+        title: 'Node has no incident edges',
+        remediation: 'Remove the orphan or connect it with edges so it participates in the architecture. Isolated nodes usually mean stale IR or a missing integration.',
+    },
+    'IR-LINT-DUPLICATE-EDGE-006': {
+        title: 'Duplicate from→to edge',
+        remediation: 'Collapse duplicate edges or distinguish them with metadata if your model allows. Parallel duplicates clutter views and can double-count in generators.',
+    },
+    'IR-LINT-HTTP-MISSING-NAME-007': {
+        title: 'HTTP-like node missing display name',
+        remediation: 'Set a short human-readable `name` on the node for docs, OpenAPI titles, and graph labels.',
+    },
+    'IR-LINT-DATASTORE-NO-INCOMING-008': {
+        title: 'Datastore has no incoming edges',
+        remediation: 'Connect a service or data path to this datastore, or remove it if unused. Orphan persistence nodes misrepresent how data is written.',
+    },
+    'IR-LINT-MULTIPLE-HTTP-ENTRIES-009': {
+        title: 'Multiple HTTP entry nodes without incoming edges',
+        remediation: 'Prefer a single API gateway or BFF unless multiple public surfaces are intentional and documented. Multiple entries duplicate auth, rate limits, and observability concerns.',
+    },
+    'IR-LINT-MISSING-AUTH-010': {
+        title: 'HTTP entry missing auth coverage',
+        remediation: 'Add an auth boundary: connect an auth, oauth, jwt, or middleware node with an edge to or from this entry, or set `config.authRequired: false` for intentionally public endpoints (health, assets). Regulated environments expect a documented auth path for every public HTTP entry.',
+    },
+    'IR-LINT-DEAD-NODE-011': {
+        title: 'Non-sink node with incoming edges but no outgoing edges',
+        remediation: 'Add an outgoing edge to a downstream consumer, or remove the node if it is obsolete. Dead-end non-sinks often indicate incomplete migrations or IR mistakes.',
+    },
+    'IR-STRUCT-INVALID_ROOT': {
+        title: 'IR root is not a JSON object',
+        remediation: 'Pass a single JSON object: either `{ "graph": { "nodes": [], "edges": [] } }` or a graph object with a top-level `nodes` array.',
+    },
+    'IR-STRUCT-NO_GRAPH': {
+        title: 'Missing graph shape',
+        remediation: 'Include `.graph` with `nodes` (and optional `edges`) or a top-level `nodes` array so the document describes a graph.',
+    },
+    'IR-STRUCT-NODES_NOT_ARRAY': {
+        title: '`nodes` is not an array',
+        remediation: 'Set `nodes` to an array of node objects, each with a string `id` and a type/kind.',
+    },
+    'IR-STRUCT-EDGES_NOT_ARRAY': {
+        title: '`edges` is present but not an array',
+        remediation: 'Set `edges` to an array of edge objects (or omit `edges` if there are no edges). Malformed `edges` is treated as empty with a warning.',
+    },
+    'IR-STRUCT-EMPTY_GRAPH': {
+        title: 'Graph has no nodes',
+        remediation: 'Add at least one node before validation or export. An empty graph cannot generate a service.',
+    },
+    'IR-STRUCT-NODE_INVALID': {
+        title: 'Node entry is not an object',
+        remediation: 'Each element of `nodes` must be a JSON object with at least `id` and type information.',
+    },
+    'IR-STRUCT-NODE_NO_ID': {
+        title: 'Node missing non-empty id',
+        remediation: 'Assign a stable string `id` to every node. Ids are used for edges and code generation.',
+    },
+    'IR-STRUCT-DUP_NODE_ID': {
+        title: 'Duplicate node id',
+        remediation: 'Ensure node ids are unique. Edges cannot reference duplicate ids unambiguously.',
+    },
+    'IR-STRUCT-NODE_INVALID_CONFIG': {
+        title: 'Node `config` is not a plain object',
+        remediation: 'Use a plain object for `config` (e.g. `{ "url": "/api", "method": "GET" }`). Arrays and null are not valid.',
+    },
+    'IR-STRUCT-HTTP_PATH': {
+        title: 'HTTP endpoint path invalid',
+        remediation: 'Set `config.url` or `config.route` to a non-empty path starting with `/`, e.g. `/users`.',
+    },
+    'IR-STRUCT-HTTP_METHOD': {
+        title: 'HTTP method not supported',
+        remediation: 'Use GET, POST, PUT, PATCH, DELETE, HEAD, or OPTIONS in `config.method` (default may be applied as POST).',
+    },
+    'IR-STRUCT-EDGE_INVALID': {
+        title: 'Edge is not an object',
+        remediation: 'Each edge must be an object with `from`/`to` (or `source`/`target`) referencing node ids.',
+    },
+    'IR-STRUCT-EDGE_NO_ENDPOINTS': {
+        title: 'Edge missing endpoints',
+        remediation: 'Set both ends of the edge to existing node ids using `from` and `to` (or legacy `source`/`target`).',
+    },
+    'IR-STRUCT-EDGE_AMBIGUOUS_FROM': {
+        title: 'Edge references duplicate source id',
+        remediation: 'Resolve duplicate node ids first; edges cannot point to an ambiguous source.',
+    },
+    'IR-STRUCT-EDGE_UNKNOWN_FROM': {
+        title: 'Edge references unknown source node',
+        remediation: 'Add a node with the referenced id or correct the `from` endpoint.',
+    },
+    'IR-STRUCT-EDGE_AMBIGUOUS_TO': {
+        title: 'Edge references duplicate target id',
+        remediation: 'Resolve duplicate node ids first; edges cannot point to an ambiguous target.',
+    },
+    'IR-STRUCT-EDGE_UNKNOWN_TO': {
+        title: 'Edge references unknown target node',
+        remediation: 'Add a node with the referenced id or correct the `to` endpoint.',
+    },
+    'IR-STRUCT-CYCLE': {
+        title: 'Directed cycle in the graph',
+        remediation: 'Remove or break cyclic edges unless your deployment explicitly allows synchronous loops. Cycles block layering and complicate codegen assumptions.',
+    },
+    'DRIFT-MISSING': {
+        title: 'Exported file missing on disk',
+        remediation: 'Regenerate the export (`archrad export`) or restore the missing file so the tree matches the deterministic output for this IR.',
+    },
+    'DRIFT-MODIFIED': {
+        title: 'File differs from deterministic export',
+        remediation: 'Revert manual edits to generated files or update the IR and re-export so the on-disk tree matches the compiler output.',
+    },
+    'DRIFT-EXTRA': {
+        title: 'Extra file not in deterministic export',
+        remediation: 'Remove stray files from the export directory or add them to the model if they should be generated. Use `--strict-extra` semantics as documented for your CI gate.',
+    },
+    'DRIFT-NO-EXPORT': {
+        title: 'No export produced for drift comparison',
+        remediation: 'Fix IR structural/lint errors blocking export, or verify `--target` and IR content so the exporter emits files.',
+    },
+};
+export function listStaticRuleCodes() {
+    return Object.keys(GUIDANCE).sort();
+}
+export function getStaticRuleGuidance(findingCode) {
+    const g = GUIDANCE[findingCode];
+    if (!g)
+        return null;
+    return {
+        findingCode,
+        title: g.title,
+        remediation: g.remediation,
+        docsUrl: docsUrlForFindingCode(findingCode),
+    };
+}

package/dist/stringEdgeStrip.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Linear-time trimming of repeated edge characters (avoids polynomial ReDoS on
+ * patterns like `/^-+|-+$/` when applied to uncontrolled strings).
+ */
+export declare const MAX_UNTRUSTED_STRING_LEN = 8192;
+export declare function stripLeadingTrailingHyphens(s: string, maxLen?: number): string;
+export declare function stripLeadingTrailingUnderscores(s: string, maxLen?: number): string;
+//# sourceMappingURL=stringEdgeStrip.d.ts.map

package/dist/stringEdgeStrip.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"stringEdgeStrip.d.ts","sourceRoot":"","sources":["../src/stringEdgeStrip.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,eAAO,MAAM,wBAAwB,OAAO,CAAC;AAE7C,wBAAgB,2BAA2B,CAAC,CAAC,EAAE,MAAM,EAAE,MAAM,SAA2B,GAAG,MAAM,CAOhG;AAED,wBAAgB,+BAA+B,CAAC,CAAC,EAAE,MAAM,EAAE,MAAM,SAA2B,GAAG,MAAM,CAOpG"}

package/dist/stringEdgeStrip.js

@@ -0,0 +1,25 @@
+/**
+ * Linear-time trimming of repeated edge characters (avoids polynomial ReDoS on
+ * patterns like `/^-+|-+$/` when applied to uncontrolled strings).
+ */
+export const MAX_UNTRUSTED_STRING_LEN = 8192;
+export function stripLeadingTrailingHyphens(s, maxLen = MAX_UNTRUSTED_STRING_LEN) {
+    const t = s.length <= maxLen ? s : s.slice(0, maxLen);
+    let i = 0;
+    let j = t.length;
+    while (i < j && t[i] === '-')
+        i++;
+    while (j > i && t[j - 1] === '-')
+        j--;
+    return t.slice(i, j);
+}
+export function stripLeadingTrailingUnderscores(s, maxLen = MAX_UNTRUSTED_STRING_LEN) {
+    const t = s.length <= maxLen ? s : s.slice(0, maxLen);
+    let i = 0;
+    let j = t.length;
+    while (i < j && t[i] === '_')
+        i++;
+    while (j > i && t[j - 1] === '_')
+        j--;
+    return t.slice(i, j);
+}

package/docs/DRIFT.md

@@ -0,0 +1,52 @@
+# Deterministic drift (`validate-drift`)
+
+**Canonical OSS description** — versioned with **`@archrad/deterministic`**.  
+**Not** semantic “does this code match business intent?” — that class of analysis is out of scope for this layer (see **`STRUCTURAL_VS_SEMANTIC_VALIDATION.md`**).
+
+## What it is
+
+**Drift** here means: you already have an **on-disk tree** (usually from `archrad export`), and you want to know whether it still matches what the **deterministic exporter would produce today** from the **same IR**.
+
+The engine:
+
+1. Runs a **fresh export** from your IR in memory (same pipeline as `archrad export`).
+2. Compares the **expected file set + contents** to what is on disk (paths normalized, line endings normalized to `\n`).
+3. Emits **DRIFT-*** findings when something is missing, changed, or (optionally) extra.
+
+So: **regen vs reality** — a thin gate for CI and pre-merge checks.
+
+## What it is not
+
+- **Not** diffing IR to arbitrary hand-written code semantics.
+- **Not** proving runtime behavior or security — use tests, review, and (where applicable) **ArchRad Cloud** governance.
+
+## CLI
+
+```bash
+archrad validate-drift -i ./graph.json -t python -o ./out
+```
+
+Use **`--json`** in CI. **`--strict-extra`** treats unexpected files in the output directory as findings. **`--skip-ir-lint`** / **`--policies`** follow the same semantics as **`export`** (see **`README.md`**).
+
+## Library
+
+**`runValidateDrift`**, **`diffExpectedExportAgainstFiles`**, **`readDirectoryAsExportMap`** — see **`src/validate-drift.ts`**.
+
+## MCP
+
+**`archrad_validate_drift`** — same semantics: IR (inline or **`irPath`**) + **`target`** + **`exportDir`**. See **`MCP.md`**.
+
+## DRIFT-* codes
+
+| Code | Meaning |
+|------|--------|
+| **DRIFT-MISSING** | A file the exporter would emit is missing on disk. |
+| **DRIFT-MODIFIED** | File exists but content differs from the deterministic export. |
+| **DRIFT-EXTRA** | File exists on disk but is not in the reference export (with **`--strict-extra`**). |
+| **DRIFT-NO-EXPORT** | Exporter produced no file map (often blocked by structural/lint errors or empty target output). |
+
+Remediation text for each code (aligned with MCP **`archrad_suggest_fix`**) lives in **`RULE_CODES.md`** and **`src/static-rule-guidance.ts`**.
+
+## Product site
+
+**archrad.com** may host narrative pages (e.g. `/docs/drift`) for onboarding; **definitions and CLI/MCP behavior** are maintained **here** in the OSS repo so they ship with the engine.

package/docs/MCP.md

@@ -0,0 +1,153 @@
+# ArchRad MCP server — specification
+
+**Status:** **0.1.x** — `archrad-mcp` ships in **`@archrad/deterministic`** (stdio MCP, same engine as CLI).  
+**Audience:** Engineering + launch narrative (Show HN / registry listing).
+
+## 1. Problem statement
+
+| Mode | Behavior |
+|------|------------|
+| **Reactive** | CI runs `archrad` after code exists → catches drift late. |
+| **Proactive** | An MCP server answers **before** edits land: “Is this edge allowed?”, “What does IR-LINT say about this sketch?” |
+
+Agents optimize for *working code*; ArchRad supplies **deterministic constraints** so the loop can ask the engine *before* violating architecture.
+
+## 2. OSS vs product boundary
+
+Aligned with **`STRUCTURAL_VS_SEMANTIC_VALIDATION.md`** (this folder) and your org’s OSS/product split docs.
+
+| Surface | Ships in **OSS** (`@archrad/deterministic`, binary **`archrad-mcp`**) | Stays in **product / Cloud** |
+|---------|------------------------------------------------------------------------|------------------------------|
+| IR structural validation (`IR-STRUCT-*`) | Yes | — |
+| Architecture lint (`IR-LINT-*`) + PolicyPack YAML from **local dir** | Yes | — |
+| `validate_drift` vs on-disk export (local paths) | Yes | — |
+| Static remediation text per **built-in** code (`archrad_suggest_fix`) | Yes | — |
+| Org **`settings.archPolicyPacks`**, Firestore, membership | — | Yes |
+| Semantic “is this business-correct?” reasoning | — | Yes (future assisted tools) |
+
+**Rule of thumb:** If the tool only needs **IR JSON + local files**, it can live in the public MCP server. If it needs **tenant identity, billing, or org policy from Cloud**, expose a **separate** “ArchRad Cloud” MCP connector (private or authenticated) — do not move Cloud policy enforcement into OSS without an explicit product decision.
+
+## 3. Transport and packaging
+
+- **Protocol:** [Model Context Protocol](https://modelcontextprotocol.io/) over **stdio** (default for Cursor, Claude Desktop, Copilot agent adapters).
+- **Package:** **`@archrad/deterministic`** publishes two binaries: **`archrad`** (CLI) and **`archrad-mcp`** (MCP). One implementation backs CLI + MCP.
+- **Registry:** Optional `server.json` / manifest for MCP Registry; document install for Cursor “Add MCP server”.
+
+## 4. IR payload size and `ir` vs `irPath`
+
+| Concern | Guidance |
+|---------|----------|
+| **Inline `ir`** | Fine for small/medium graphs. Large JSON in a single tool call still stresses **host message limits** and **model context** — prefer **`irPath`** when the IR is big. |
+| **`irPath`** | Absolute or relative path to a **single JSON file** (same shape as CLI `--ir`). Enforced **max file size 25 MiB** in the server (hard cap); if you exceed it, split validation or trim fixtures. |
+| **Soft ceiling** | Below ~**5k–10k nodes**, inline JSON is usually workable if the host allows; above that, **`irPath` is recommended**. This is not a graph semantics limit — only practical transport/memory. |
+| **Exactly one** | Provide **`ir`** **or** **`irPath`**, not both, not neither (for tools that need IR). |
+
+**Privacy:** The OSS server does **not** add analytics or tracking parameters to tool responses. Optional product docs URLs use a stable path only (see **`archrad_suggest_fix`**).
+
+## 5. Local testing
+
+### 5.1 Smoke script (npm)
+
+From the **`@archrad/deterministic`** package root (where **`package.json`** lives):
+
+```bash
+npm run build
+npm run smoke:mcp
+```
+
+Exit code **0** means the MCP server spawned **`dist/mcp-server.js`**, listed tools, and successfully called **`archrad_suggest_fix`**.
+
+### 5.2 MCP Inspector (browser UI)
+
+```bash
+npx @modelcontextprotocol/inspector node dist/mcp-server.js
+```
+
+Open the URL Inspector prints (often **http://localhost:6274**). Under **Tools**, run **`archrad_list_rule_codes`** (no args), then **`archrad_validate_ir`** with **`irPath`** set to **`fixtures/minimal-graph.json`** (relative paths work if the process was started with **cwd** set to the package root).
+
+### 5.3 Cursor (MCP config + chat)
+
+1. **Build** so **`dist/mcp-server.js`** exists (`npm run build`).
+2. In Cursor **Settings → MCP**, add a server (exact JSON shape depends on Cursor version):
+   - **Command:** `node` (or full path to `node.exe` on Windows).
+   - **Args:** full path to **`dist/mcp-server.js`**.
+   - **Cwd (recommended):** the deterministic package root (directory containing **`package.json`**). Relative **`irPath`** values like **`fixtures/minimal-graph.json`** resolve from this directory.
+3. **Chat:** Cursor does not always show a “run tool” button for every server. Use **Agent** mode (or another mode that supports **tool use**) and ask explicitly, for example:
+
+   **List codes:**
+
+   > Use the MCP tool **`archrad_list_rule_codes`** (no arguments) and show me the raw JSON result.
+
+   **Validate via file:**
+
+   > Use the MCP tool **`archrad_validate_ir`** with **`irPath`** set to **`fixtures/minimal-graph.json`** (relative to the deterministic package). Show the full tool result.
+
+   If the model says it cannot find the tool, the MCP server failed to start or the configured server name does not match — check Cursor’s MCP panel for errors.
+
+4. **If `irPath` fails** with “file not found”, use the **absolute path** to **`fixtures/minimal-graph.json`**.
+
+### 5.4 Success criteria
+
+- **`archrad_list_rule_codes`:** JSON with a **`codes`** array.
+- **`archrad_validate_ir`:** JSON with **`irStructuralFindings`**, **`irLintFindings`**, **`combined`**, **`ok`** — not a connection or file error.
+
+## 6. Tools (0.1.5)
+
+Tools are **idempotent** and **deterministic** where stated.
+
+### 6.1 Core
+
+| Tool | Input | Output | Notes |
+|------|--------|--------|-------|
+| **`archrad_validate_ir`** | `ir` **or** `irPath`; optional `policiesDirectory` | `{ ok, irStructuralFindings, irLintFindings, combined }` | Same as CLI validate. |
+| **`archrad_lint_summary`** | `ir` **or** `irPath`; optional `policiesDirectory` | Short summary + counts | Agent-friendly. |
+| **`archrad_validate_drift`** | `ir` **or** `irPath`; `target`; `exportDir`; optional policies, `skipIrLint` | Drift + export findings | Same as CLI `validate-drift`. |
+| **`archrad_policy_packs_load`** | `directory` or `files[]` | `{ ok, ruleCount }` or errors | Compiles packs; does not return visitor functions over MCP. |
+
+### 6.2 Static guidance (no generated architecture)
+
+| Tool | Input | Output | Notes |
+|------|--------|--------|-------|
+| **`archrad_suggest_fix`** | `findingCode` (e.g. `IR-LINT-MISSING-AUTH-010`) | `{ ok, findingCode, title, remediation, docsUrl }` or `{ ok: false, error }` | **Curated text only** — not JSON Patch, not IR edits, not LLM output. **`docsUrl`** points to the **[`RULE_CODES.md`](https://github.com/archradhq/arch-deterministic/blob/main/docs/RULE_CODES.md)** section for that code on **GitHub** (canonical OSS; no query strings). Unknown built-in codes and **PolicyPack/org** ids return `ok: false` with a short explanation. |
+| **`archrad_list_rule_codes`** | _(none)_ | `{ codes: string[] }` | Sorted list of built-in codes with static guidance. |
+
+**Explicit non-goal:** **`archrad_suggest_fix` must not** return machine-generated graph edits or “patches” that invent services — that would be **generative** and would break the deterministic OSS contract.
+
+### 6.3 Explicit non-goals (MVP)
+
+- No automatic **code** generation inside MCP (keep **`export`** as CLI/CI).
+- No remote calls to ArchRad Cloud unless a **separate authenticated** server is defined.
+- No **tracking** query parameters in MCP tool payloads.
+
+## 7. Resources (optional)
+
+| Resource URI | Content |
+|--------------|---------|
+| `archrad://docs/ir-contract` | Pointer to bundled `IR_CONTRACT.md` snippet or link. |
+| `archrad://schemas/ir-graph-v1` | JSON Schema for IR graph validation. |
+
+## 8. Security
+
+- **Local-only by default:** IR and paths stay on the user machine; **no telemetry** in the OSS server unless explicitly documented elsewhere.
+- **Path sandbox:** Validate `exportDir` / `irPath` against workspace roots if the host passes a `workspaceRoot` (host-dependent).
+- **Cloud MCP (future):** OAuth or API keys; never embed product secrets in OSS.
+
+## 9. Launch narrative (copy bank)
+
+- **One-liner:** *AI agents write code fast but drift from your architecture; ArchRad MCP gives them the same deterministic IR checks as CI, inside the agent loop.*
+- **Show HN angle:** *Architectural conscience for Copilot / Cursor — IR-LINT before you merge.*
+
+## 10. Related repo tasks
+
+- **Quality:** Keep graph/lint work responsive so MCP tools stay usable on mid-size IRs.
+
+## 11. Implementation checklist
+
+1. ~~Node MCP server (`@modelcontextprotocol/sdk`), stdio transport.~~
+2. ~~`archrad_validate_ir` + `archrad_validate_drift` + policy load + static `archrad_suggest_fix`.~~
+3. README + **`docs/MCP.md`**: Cursor config, `ir` / `irPath`, local testing (smoke, Inspector, chat prompts).
+4. Publish **`@archrad/deterministic`** to npm; subtree to public repo per release process.
+
+---
+
+*This document aligns OSS MCP scope with product strategy; update when adding Cloud-only tools.*

package/docs/RULE_CODES.md

@@ -0,0 +1,208 @@
+# Built-in finding codes (IR-STRUCT, IR-LINT, DRIFT)
+
+**Canonical OSS reference** — ships in **`@archrad/deterministic`**.  
+**MCP** **`archrad_suggest_fix`** returns **`title`**, **`remediation`**, and a **`docsUrl`** pointing at the matching section below. **PolicyPack / org** rules use custom ids (e.g. `ORG-*`) — not listed here.
+
+**Product / marketing** copy may live on **archrad.com**; **deterministic semantics** are defined in this repo.
+
+---
+
+## DRIFT-EXTRA
+
+Extra file not in deterministic export. **Remediation:** Remove stray files from the export directory or add them to the model if they should be generated. Use **`--strict-extra`** semantics as documented for your CI gate.
+
+---
+
+## DRIFT-MISSING
+
+Exported file missing on disk. **Remediation:** Regenerate the export (**`archrad export`**) or restore the missing file so the tree matches the deterministic output for this IR.
+
+---
+
+## DRIFT-MODIFIED
+
+File differs from deterministic export. **Remediation:** Revert manual edits to generated files or update the IR and re-export so the on-disk tree matches the compiler output.
+
+---
+
+## DRIFT-NO-EXPORT
+
+No export produced for drift comparison. **Remediation:** Fix IR structural/lint errors blocking export, or verify **`--target`** and IR content so the exporter emits files.
+
+---
+
+## IR-LINT-DATASTORE-NO-INCOMING-008
+
+Datastore has no incoming edges. **Remediation:** Connect a service or data path to this datastore, or remove it if unused.
+
+---
+
+## IR-LINT-DEAD-NODE-011
+
+Non-sink node with incoming edges but no outgoing edges. **Remediation:** Add an outgoing edge to a downstream consumer, or remove the node if it is obsolete.
+
+---
+
+## IR-LINT-DIRECT-DB-ACCESS-002
+
+HTTP-like node connects directly to a datastore. **Remediation:** Introduce a service or domain layer between HTTP handlers and persistence.
+
+---
+
+## IR-LINT-DUPLICATE-EDGE-006
+
+Duplicate from→to edge. **Remediation:** Collapse duplicate edges or distinguish them with metadata if your model allows.
+
+---
+
+## IR-LINT-HIGH-FANOUT-004
+
+High outgoing dependency count. **Remediation:** Reduce fan-out: split responsibilities, add a facade, batch calls, or use async handoff.
+
+---
+
+## IR-LINT-HTTP-MISSING-NAME-007
+
+HTTP-like node missing display name. **Remediation:** Set a short human-readable **`name`** on the node.
+
+---
+
+## IR-LINT-ISOLATED-NODE-005
+
+Node has no incident edges. **Remediation:** Remove the orphan or connect it with edges.
+
+---
+
+## IR-LINT-MISSING-AUTH-010
+
+HTTP entry missing auth coverage. **Remediation:** Add an auth boundary (auth/middleware/oauth/jwt node or **`config.authRequired: false`** for public endpoints).
+
+---
+
+## IR-LINT-MULTIPLE-HTTP-ENTRIES-009
+
+Multiple HTTP entry nodes without incoming edges. **Remediation:** Prefer a single API gateway or BFF unless multiple public surfaces are intentional.
+
+---
+
+## IR-LINT-NO-HEALTHCHECK-003
+
+No typical health/readiness route on HTTP nodes. **Remediation:** Add a GET route such as **`/health`** or **`/ready`**.
+
+---
+
+## IR-LINT-SYNC-CHAIN-001
+
+Long synchronous chain from HTTP entry. **Remediation:** Shorten the graph or mark non-blocking hops as async in edge metadata.
+
+---
+
+## IR-STRUCT-CYCLE
+
+Directed cycle in the graph. **Remediation:** Remove or break cyclic edges unless your tooling explicitly allows execution loops.
+
+---
+
+## IR-STRUCT-DUP_NODE_ID
+
+Duplicate node id. **Remediation:** Ensure node ids are unique.
+
+---
+
+## IR-STRUCT-EDGE_AMBIGUOUS_FROM
+
+Edge references duplicate source id. **Remediation:** Resolve duplicate node ids first.
+
+---
+
+## IR-STRUCT-EDGE_AMBIGUOUS_TO
+
+Edge references duplicate target id. **Remediation:** Resolve duplicate node ids first.
+
+---
+
+## IR-STRUCT-EDGE_INVALID
+
+Edge is not an object. **Remediation:** Each edge must be an object with **`from`**/**`to`** (or **`source`**/**`target`**).
+
+---
+
+## IR-STRUCT-EDGE_NO_ENDPOINTS
+
+Edge missing endpoints. **Remediation:** Set **`from`** and **`to`** to existing node ids.
+
+---
+
+## IR-STRUCT-EDGE_UNKNOWN_FROM
+
+Edge references unknown source node. **Remediation:** Add a node with the referenced id or correct **`from`**.
+
+---
+
+## IR-STRUCT-EDGE_UNKNOWN_TO
+
+Edge references unknown target node. **Remediation:** Add a node with the referenced id or correct **`to`**.
+
+---
+
+## IR-STRUCT-EDGES_NOT_ARRAY
+
+**`edges`** is present but not an array. **Remediation:** Set **`edges`** to an array of edge objects (or omit **`edges`**).
+
+---
+
+## IR-STRUCT-EMPTY_GRAPH
+
+Graph has no nodes. **Remediation:** Add at least one node before validation or export.
+
+---
+
+## IR-STRUCT-HTTP_METHOD
+
+HTTP method not supported. **Remediation:** Use GET, POST, PUT, PATCH, DELETE, HEAD, or OPTIONS.
+
+---
+
+## IR-STRUCT-HTTP_PATH
+
+HTTP endpoint path invalid. **Remediation:** Set **`config.url`** or **`config.route`** to a path starting with **`/`**.
+
+---
+
+## IR-STRUCT-INVALID_ROOT
+
+IR root is not a JSON object. **Remediation:** Pass a single JSON object with **`graph`** or top-level **`nodes`**.
+
+---
+
+## IR-STRUCT-NO_GRAPH
+
+Missing graph shape. **Remediation:** Include **`.graph`** with **`nodes`** or a top-level **`nodes`** array.
+
+---
+
+## IR-STRUCT-NODE_INVALID
+
+Node entry is not an object. **Remediation:** Each **`nodes`** entry must be a JSON object with **`id`** and type information.
+
+---
+
+## IR-STRUCT-NODE_INVALID_CONFIG
+
+Node **`config`** is not a plain object. **Remediation:** Use a plain object for **`config`**.
+
+---
+
+## IR-STRUCT-NODE_NO_ID
+
+Node missing non-empty id. **Remediation:** Assign a stable string **`id`** to every node.
+
+---
+
+## IR-STRUCT-NODES_NOT_ARRAY
+
+**`nodes`** is not an array. **Remediation:** Set **`nodes`** to an array of node objects.
+
+---
+
+*Full strings in MCP/CLI mirror **`src/static-rule-guidance.ts`** (single implementation).*