@archrad/deterministic 0.1.0

package/dist/validate-drift.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Thin deterministic drift check: compare a fresh export from IR to an on-disk tree
+ * or to an in-memory file map (Cloud API). No semantic IR↔code analysis — regen vs reality.
+ */
+import { type DeterministicExportResult } from './exportPipeline.js';
+export type DriftCode = 'DRIFT-MISSING' | 'DRIFT-MODIFIED' | 'DRIFT-EXTRA' | 'DRIFT-NO-EXPORT';
+export type DriftFinding = {
+    code: DriftCode;
+    path: string;
+    message: string;
+};
+export declare function normalizeExportFileContent(content: string): string;
+/**
+ * Compare expected export map to an actual map (e.g. from client or built from disk reads).
+ */
+export declare function diffExpectedExportAgainstFiles(expected: Record<string, string>, actual: Record<string, string>, options?: {
+    strictExtra?: boolean;
+}): DriftFinding[];
+/**
+ * Read all files under rootDir into a flat map (relative POSIX paths).
+ */
+export declare function readDirectoryAsExportMap(rootDir: string): Promise<Record<string, string>>;
+export declare function diffExpectedExportAgainstDirectory(expected: Record<string, string>, rootDir: string, options?: {
+    strictExtra?: boolean;
+}): Promise<DriftFinding[]>;
+export type ValidateDriftResult = {
+    ok: boolean;
+    driftFindings: DriftFinding[];
+    /** True when --strict-extra and any DRIFT-EXTRA was found */
+    extraBlocking: boolean;
+    exportResult: DeterministicExportResult;
+};
+export declare function runValidateDrift(actualIR: any, target: string, outDir: string, opts?: {
+    hostPort?: string | number;
+    skipIrStructuralValidation?: boolean;
+    skipIrLint?: boolean;
+    strictExtra?: boolean;
+}): Promise<ValidateDriftResult>;
+export type DriftCheckFilesResult = {
+    ok: boolean;
+    driftFindings: DriftFinding[];
+    extraBlocking: boolean;
+    exportResult: DeterministicExportResult;
+};
+/**
+ * Cloud / API: compare a fresh deterministic export to a client-supplied file map (e.g. last export or repo snapshot).
+ */
+export declare function runDriftCheckAgainstFiles(actualIR: any, target: string, actualFiles: Record<string, string>, opts?: {
+    hostPort?: string | number;
+    skipIrStructuralValidation?: boolean;
+    skipIrLint?: boolean;
+    strictExtra?: boolean;
+}): Promise<DriftCheckFilesResult>;
+//# sourceMappingURL=validate-drift.d.ts.map

package/dist/validate-drift.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validate-drift.d.ts","sourceRoot":"","sources":["../src/validate-drift.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAIH,OAAO,EAA0B,KAAK,yBAAyB,EAAE,MAAM,qBAAqB,CAAC;AAG7F,MAAM,MAAM,SAAS,GAAG,eAAe,GAAG,gBAAgB,GAAG,aAAa,GAAG,iBAAiB,CAAC;AAE/F,MAAM,MAAM,YAAY,GAAG;IACzB,IAAI,EAAE,SAAS,CAAC;IAChB,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;CACjB,CAAC;AAEF,wBAAgB,0BAA0B,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAElE;AAED;;GAEG;AACH,wBAAgB,8BAA8B,CAC5C,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EAChC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EAC9B,OAAO,CAAC,EAAE;IAAE,WAAW,CAAC,EAAE,OAAO,CAAA;CAAE,GAClC,YAAY,EAAE,CAkChB;AAiBD;;GAEG;AACH,wBAAsB,wBAAwB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAQ/F;AAED,wBAAsB,kCAAkC,CACtD,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EAChC,OAAO,EAAE,MAAM,EACf,OAAO,CAAC,EAAE;IAAE,WAAW,CAAC,EAAE,OAAO,CAAA;CAAE,GAClC,OAAO,CAAC,YAAY,EAAE,CAAC,CAoCzB;AAED,MAAM,MAAM,mBAAmB,GAAG;IAChC,EAAE,EAAE,OAAO,CAAC;IACZ,aAAa,EAAE,YAAY,EAAE,CAAC;IAC9B,6DAA6D;IAC7D,aAAa,EAAE,OAAO,CAAC;IACvB,YAAY,EAAE,yBAAyB,CAAC;CACzC,CAAC;AAEF,wBAAsB,gBAAgB,CACpC,QAAQ,EAAE,GAAG,EACb,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,MAAM,EACd,IAAI,GAAE;IACJ,QAAQ,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IAC3B,0BAA0B,CAAC,EAAE,OAAO,CAAC;IACrC,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,WAAW,CAAC,EAAE,OAAO,CAAC;CAClB,GACL,OAAO,CAAC,mBAAmB,CAAC,CAyC9B;AAED,MAAM,MAAM,qBAAqB,GAAG;IAClC,EAAE,EAAE,OAAO,CAAC;IACZ,aAAa,EAAE,YAAY,EAAE,CAAC;IAC9B,aAAa,EAAE,OAAO,CAAC;IACvB,YAAY,EAAE,yBAAyB,CAAC;CACzC,CAAC;AAEF;;GAEG;AACH,wBAAsB,yBAAyB,CAC7C,QAAQ,EAAE,GAAG,EACb,MAAM,EAAE,MAAM,EACd,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EACnC,IAAI,GAAE;IACJ,QAAQ,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IAC3B,0BAA0B,CAAC,EAAE,OAAO,CAAC;IACrC,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,WAAW,CAAC,EAAE,OAAO,CAAC;CAClB,GACL,OAAO,CAAC,qBAAqB,CAAC,CAgChC"}

package/dist/validate-drift.js

@@ -0,0 +1,184 @@
+/**
+ * Thin deterministic drift check: compare a fresh export from IR to an on-disk tree
+ * or to an in-memory file map (Cloud API). No semantic IR↔code analysis — regen vs reality.
+ */
+import { readFile, readdir } from 'node:fs/promises';
+import { join } from 'node:path';
+import { runDeterministicExport } from './exportPipeline.js';
+import { normalizeGoldenHostPort } from './hostPort.js';
+export function normalizeExportFileContent(content) {
+    return content.replace(/\r\n/g, '\n');
+}
+/**
+ * Compare expected export map to an actual map (e.g. from client or built from disk reads).
+ */
+export function diffExpectedExportAgainstFiles(expected, actual, options) {
+    const findings = [];
+    const expectedKeys = Object.keys(expected).sort();
+    for (const rel of expectedKeys) {
+        if (!(rel in actual)) {
+            findings.push({
+                code: 'DRIFT-MISSING',
+                path: rel,
+                message: `Expected generated file is missing from the comparison set`,
+            });
+            continue;
+        }
+        const a = normalizeExportFileContent(actual[rel]);
+        const e = normalizeExportFileContent(expected[rel]);
+        if (a !== e) {
+            findings.push({
+                code: 'DRIFT-MODIFIED',
+                path: rel,
+                message: `File content differs from deterministic export for this IR`,
+            });
+        }
+    }
+    if (options?.strictExtra) {
+        for (const rel of Object.keys(actual).sort()) {
+            if (!(rel in expected)) {
+                findings.push({
+                    code: 'DRIFT-EXTRA',
+                    path: rel,
+                    message: `File exists in comparison set but is not part of the deterministic export`,
+                });
+            }
+        }
+    }
+    return findings;
+}
+async function listRelativeFilesRecursive(rootDir, sub = '') {
+    const dirPath = sub ? join(rootDir, sub) : rootDir;
+    const entries = await readdir(dirPath, { withFileTypes: true });
+    const out = [];
+    for (const ent of entries) {
+        const piece = sub ? `${sub}/${ent.name}` : ent.name;
+        if (ent.isDirectory()) {
+            out.push(...(await listRelativeFilesRecursive(rootDir, piece)));
+        }
+        else {
+            out.push(piece.replace(/\\/g, '/'));
+        }
+    }
+    return out;
+}
+/**
+ * Read all files under rootDir into a flat map (relative POSIX paths).
+ */
+export async function readDirectoryAsExportMap(rootDir) {
+    const rels = await listRelativeFilesRecursive(rootDir);
+    const map = {};
+    for (const rel of rels) {
+        const full = join(rootDir, ...rel.split('/'));
+        map[rel] = await readFile(full, 'utf8');
+    }
+    return map;
+}
+export async function diffExpectedExportAgainstDirectory(expected, rootDir, options) {
+    const findings = [];
+    for (const rel of Object.keys(expected).sort()) {
+        const fullPath = join(rootDir, ...rel.split('/'));
+        let disk;
+        try {
+            disk = await readFile(fullPath, 'utf8');
+        }
+        catch {
+            findings.push({
+                code: 'DRIFT-MISSING',
+                path: rel,
+                message: `File missing under output directory`,
+            });
+            continue;
+        }
+        if (normalizeExportFileContent(disk) !== normalizeExportFileContent(expected[rel])) {
+            findings.push({
+                code: 'DRIFT-MODIFIED',
+                path: rel,
+                message: `File differs from deterministic export for this IR`,
+            });
+        }
+    }
+    if (options?.strictExtra) {
+        const onDisk = await listRelativeFilesRecursive(rootDir);
+        for (const rel of onDisk.sort()) {
+            if (!(rel in expected)) {
+                findings.push({
+                    code: 'DRIFT-EXTRA',
+                    path: rel,
+                    message: `Unexpected file not produced by current deterministic export`,
+                });
+            }
+        }
+    }
+    return findings;
+}
+export async function runValidateDrift(actualIR, target, outDir, opts = {}) {
+    const hostPort = normalizeGoldenHostPort(opts.hostPort ?? process.env.ARCHRAD_HOST_PORT);
+    const exportResult = await runDeterministicExport(actualIR, target, {
+        hostPort,
+        skipIrStructuralValidation: Boolean(opts.skipIrStructuralValidation),
+        skipIrLint: Boolean(opts.skipIrLint),
+    });
+    const { files } = exportResult;
+    if (Object.keys(files).length === 0) {
+        return {
+            ok: false,
+            driftFindings: [
+                {
+                    code: 'DRIFT-NO-EXPORT',
+                    path: '.',
+                    message: 'No files generated from IR (structural errors or empty graph); cannot compare drift',
+                },
+            ],
+            extraBlocking: false,
+            exportResult,
+        };
+    }
+    const driftFindings = await diffExpectedExportAgainstDirectory(files, outDir, {
+        strictExtra: Boolean(opts.strictExtra),
+    });
+    const blocking = driftFindings.filter((f) => f.code === 'DRIFT-MISSING' || f.code === 'DRIFT-MODIFIED' || f.code === 'DRIFT-NO-EXPORT');
+    const extra = driftFindings.filter((f) => f.code === 'DRIFT-EXTRA');
+    const extraBlocking = Boolean(opts.strictExtra) && extra.length > 0;
+    const ok = blocking.length === 0 && !extraBlocking;
+    return {
+        ok,
+        driftFindings,
+        extraBlocking,
+        exportResult,
+    };
+}
+/**
+ * Cloud / API: compare a fresh deterministic export to a client-supplied file map (e.g. last export or repo snapshot).
+ */
+export async function runDriftCheckAgainstFiles(actualIR, target, actualFiles, opts = {}) {
+    const hostPort = normalizeGoldenHostPort(opts.hostPort ?? process.env.ARCHRAD_HOST_PORT);
+    const exportResult = await runDeterministicExport(actualIR, target, {
+        hostPort,
+        skipIrStructuralValidation: Boolean(opts.skipIrStructuralValidation),
+        skipIrLint: Boolean(opts.skipIrLint),
+    });
+    const { files } = exportResult;
+    if (Object.keys(files).length === 0) {
+        return {
+            ok: false,
+            driftFindings: [
+                {
+                    code: 'DRIFT-NO-EXPORT',
+                    path: '.',
+                    message: 'No files generated from IR (structural errors or empty graph); cannot compare drift',
+                },
+            ],
+            extraBlocking: false,
+            exportResult,
+        };
+    }
+    const driftFindings = diffExpectedExportAgainstFiles(files, actualFiles, {
+        strictExtra: Boolean(opts.strictExtra),
+    });
+    const blocking = driftFindings.filter((f) => f.code === 'DRIFT-MISSING' || f.code === 'DRIFT-MODIFIED' || f.code === 'DRIFT-NO-EXPORT');
+    const extra = driftFindings.filter((f) => f.code === 'DRIFT-EXTRA');
+    const extraBlocking = Boolean(opts.strictExtra) && extra.length > 0;
+    const ok = blocking.length === 0 && !extraBlocking;
+    return { ok, driftFindings, extraBlocking, exportResult };
+}

package/dist/yamlToIr.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Convert a YAML blueprint file into canonical IR JSON shape for validate/export.
+ * YAML mirrors JSON IR: either `{ graph: { metadata?, nodes, edges? } }` or a bare `{ nodes, edges?, metadata? }`.
+ */
+export declare class YamlGraphParseError extends Error {
+    constructor(message: string);
+}
+/**
+ * Parse YAML text and return `{ graph: { ... } }` suitable for `validateIrStructural` / `runDeterministicExport`.
+ */
+export declare function parseYamlToCanonicalIr(yamlText: string): Record<string, unknown>;
+/** Pretty-printed JSON for stable CLI output (2-space indent + trailing newline). */
+export declare function canonicalIrToJsonString(ir: Record<string, unknown>): string;
+//# sourceMappingURL=yamlToIr.d.ts.map

package/dist/yamlToIr.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"yamlToIr.d.ts","sourceRoot":"","sources":["../src/yamlToIr.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAIH,qBAAa,mBAAoB,SAAQ,KAAK;gBAChC,OAAO,EAAE,MAAM;CAI5B;AAED;;GAEG;AACH,wBAAgB,sBAAsB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CA4BhF;AAED,qFAAqF;AACrF,wBAAgB,uBAAuB,CAAC,EAAE,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAE3E"}

package/dist/yamlToIr.js

@@ -0,0 +1,39 @@
+/**
+ * Convert a YAML blueprint file into canonical IR JSON shape for validate/export.
+ * YAML mirrors JSON IR: either `{ graph: { metadata?, nodes, edges? } }` or a bare `{ nodes, edges?, metadata? }`.
+ */
+import yaml from 'js-yaml';
+export class YamlGraphParseError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'YamlGraphParseError';
+    }
+}
+/**
+ * Parse YAML text and return `{ graph: { ... } }` suitable for `validateIrStructural` / `runDeterministicExport`.
+ */
+export function parseYamlToCanonicalIr(yamlText) {
+    let doc;
+    try {
+        doc = yaml.load(yamlText, { schema: yaml.JSON_SCHEMA });
+    }
+    catch (e) {
+        const msg = e instanceof Error ? e.message : String(e);
+        throw new YamlGraphParseError(`Invalid YAML: ${msg}`);
+    }
+    if (doc == null || typeof doc !== 'object' || Array.isArray(doc)) {
+        throw new YamlGraphParseError('YAML root must be a mapping (object), not null, a scalar, or a sequence at the top level.');
+    }
+    const o = doc;
+    if (o.graph != null && typeof o.graph === 'object' && !Array.isArray(o.graph)) {
+        return { graph: o.graph };
+    }
+    if (Array.isArray(o.nodes)) {
+        return { graph: { ...o } };
+    }
+    throw new YamlGraphParseError('YAML must define either top-level `graph:` (object) or top-level `nodes:` (array). See fixtures/minimal-graph.yaml.');
+}
+/** Pretty-printed JSON for stable CLI output (2-space indent + trailing newline). */
+export function canonicalIrToJsonString(ir) {
+    return `${JSON.stringify(ir, null, 2)}\n`;
+}

package/docs/CONCEPT_ADOPTION_AND_LIMITS.md

@@ -0,0 +1,47 @@
+# Concept, adoption, and limits (honest framing)
+
+This doc captures how the **deterministic OSS package** fits in the market—not as marketing copy, but as a **product/engineering** read for contributors and partners.
+
+## What’s compelling
+
+- **IR as source of truth** — Separating *what should be built* (the graph) from *how it is generated* (templates/codegen) is a clean abstraction. Most tools skew either to opaque AI (hard to reproduce) or to dumb scaffolders (no architectural rigor).
+- **Compiler mental model** — **`archrad validate`** treats the graph like source code: structural checks, lint rules, and CI gates. That discipline is rare in “architecture” tooling.
+- **Tiered validation** — Structural → architecture lint → export-time OpenAPI **document-shape** is intentional: not “block on everything” or “warn on nothing.”
+- **Determinism** — Same IR → same output matters for teams that want **reproducible CI** and defensible pipelines.
+
+## Where the friction is (real adoption hurdles)
+
+### Who owns the IR?
+
+This package does **not** include a natural-language or visual **authoring** front-end. Input is **structured JSON** (or your own producer). The README states that **plain English → IR** is out of scope here: use **ArchRad Cloud**, an internal tool, or **your own LLM step**.
+
+**Cold start:** Developers must hand-write graph JSON, generate IR from another system, or adopt upstream tooling. **Fixtures** help demos; they don’t remove the onboarding gap.
+
+### One-way export (no round-trip)
+
+**`archrad export`** produces a **FastAPI** or **Express** project you can run and edit. There is **no** supported path today to **edit generated code and merge changes back into the IR**. That’s honest: the value proposition is **greenfield / contract-first scaffolding and validation**, not ongoing bidirectional architecture management—unless you rebuild that workflow yourself (e.g. regenerate into a fresh tree, or treat IR as the only editable source).
+
+## Strategic read (OSS vs Cloud)
+
+A coherent story is:
+
+1. **OSS** — Auditable, deterministic **compiler + linter** for a defined IR: trust, CI, and “read the same code that emitted your zip.”
+2. **Cloud / product** — **IR production** (UX, AI-assisted graph), deeper **semantic/policy** validation, and org workflows.
+
+If **IR** becomes a **shared format** beyond a single vendor (schemas, community examples, third-party generators), the OSS layer behaves like a **platform hook**. If IR stays **proprietary-in-practice**, the OSS repo is still valuable as a **spec and trust artifact**, but community leverage is smaller.
+
+## What would make OSS adoption stronger (directional ideas)
+
+None of these are commitments; they are **plausible** ways to narrow the cold-start gap **without** moving the whole product into OSS:
+
+- **Lightweight IR authoring in OSS** — **`archrad yaml-to-ir`** converts **`graph:`** or bare **`nodes:`** YAML to canonical IR JSON (see **`fixtures/minimal-graph.yaml`**). Further ideas: richer **starter templates**, **VS Code** snippets.
+- **Editor integration** — e.g. JSON Schema validation + snippets in **VS Code** / Cursor rules for graph files.
+- **Clear “IR from OpenAPI / Postman”** one-way adapters (if they match your graph model).
+
+For product strategy, treat this list as **roadmap candidates**, not shipped features.
+
+## See also
+
+- [IR_CONTRACT.md](./IR_CONTRACT.md) — parser boundary and normalized shapes  
+- [STRUCTURAL_VS_SEMANTIC_VALIDATION.md](./STRUCTURAL_VS_SEMANTIC_VALIDATION.md) — OSS vs Cloud validation split  
+- [README.md](../README.md) — usage and CLI  

package/docs/CUSTOM_RULES.md

@@ -0,0 +1,87 @@
+# Custom architecture rules (org / enterprise)
+
+OSS **`@archrad/deterministic`** ships a fixed set of **`IR-LINT-*`** visitors in **`src/lint-rules.ts`**. They are **deterministic** graph checks — not Spectral, not LLM, not org policy packs (those sit in **ArchRad Cloud** or your own stack).
+
+This doc shows a **minimal, real extension point**: the same **`ParsedLintGraph`** built-ins use, returning **`IrStructuralFinding[]`** with **`layer: 'lint'`**.
+
+## Two supported paths
+
+| Path | When to use | `archrad validate` CLI |
+|------|----------------|-------------------------|
+| **Compose in your pipeline** | CI / IDP runs Node; you call the library | Unchanged — your script runs custom rules after **`validateIrLint`** or replaces it with the composed function below. |
+| **Fork `arch-deterministic`** | You want **`archrad validate`** itself to emit **`ORG-*`** codes | Append your visitor to **`LINT_RULE_REGISTRY`** in **`lint-rules.ts`**, rebuild, publish / vendor the fork. |
+
+**Do not mutate** **`LINT_RULE_REGISTRY`** from application code at runtime: it is typed as **`ReadonlyArray`** and the project may freeze or replace that array in the future. Treat **`runArchitectureLinting`** as the built-in runner only.
+
+## Worked example: timeout on `service` nodes
+
+Assume IR nodes use **`type: "service"`** and you require **`config.timeout`** (milliseconds) on each.
+
+**`my-org/require-service-timeout.ts`**
+
+```typescript
+import type { IrStructuralFinding, ParsedLintGraph } from '@archrad/deterministic';
+
+function nodeType(n: Record<string, unknown>): string {
+  return String(n.type ?? n.kind ?? '').toLowerCase();
+}
+
+export function ruleRequireServiceTimeout(g: ParsedLintGraph): IrStructuralFinding[] {
+  const findings: IrStructuralFinding[] = [];
+  for (const [id, n] of g.nodeById) {
+    if (nodeType(n) !== 'service') continue;
+    const cfg = (n.config as Record<string, unknown> | undefined) ?? {};
+    if (cfg.timeout == null || cfg.timeout === '') {
+      findings.push({
+        code: 'ORG-001',
+        severity: 'warning',
+        layer: 'lint',
+        message: `Service node "${id}" has no config.timeout`,
+        nodeId: id,
+        fixHint: 'Set config.timeout (e.g. milliseconds) on this node.',
+      });
+    }
+  }
+  return findings;
+}
+```
+
+**`my-org/validate-with-org-lint.ts`** — same entry shape as **`validateIrLint`**:
+
+```typescript
+import {
+  buildParsedLintGraph,
+  isParsedLintGraph,
+  runArchitectureLinting,
+} from '@archrad/deterministic';
+import { ruleRequireServiceTimeout } from './require-service-timeout.js';
+
+/** Built-in IR-LINT-* plus org rules (drop-in mental model for validateIrLint). */
+export function validateIrLintWithOrg(ir: unknown) {
+  const built = buildParsedLintGraph(ir);
+  if (!isParsedLintGraph(built)) return built.findings;
+  return [...runArchitectureLinting(built), ...ruleRequireServiceTimeout(built)];
+}
+```
+
+Wire **`validateIrLintWithOrg`** (or your own name) into CI instead of plain **`validateIrLint`** when you need **`ORG-*`** findings. Combine with **`validateIrStructural`**, **`sortFindings`**, and **`shouldFailFromFindings`** the same way as the README library example.
+
+## CLI without a fork
+
+There is **no** `archrad validate --rules ./extra.js` flag today. Options:
+
+- **Wrapper script** that loads IR JSON, runs **`validateIrStructural`** + **`validateIrLintWithOrg`**, prints findings, exits **`1`** on your policy (mirror **`cli-findings`** formatting if you want).
+- **Fork** and register **`ruleRequireServiceTimeout`** inside **`LINT_RULE_REGISTRY`** so the stock **`archrad validate`** binary includes it.
+
+## Conventions (match built-in rules)
+
+- Return **`layer: 'lint'`** for architecture heuristics; use your own **`code`** prefix (**`ORG-*`**, **`ACME-*`**) to avoid colliding with **`IR-LINT-*`** / **`IR-STRUCT-*`**.
+- Use **`ParsedLintGraph`**: **`g.nodeById`**, **`g.edges`**, **`g.adj`**, **`g.inDegree`** / **`g.outDegree`** — see **`src/lint-graph.ts`**.
+- Reuse predicates when it helps: **`isHttpLikeType`**, **`isDbLikeType`**, **`isQueueLikeNodeType`** (exported from the package).
+- Heavy or semantic policy (SOC2 mapping, “is this PII?”) belongs in **product** or a separate engine; keep OSS visitors **fast and deterministic**.
+
+## See also
+
+- **[STRUCTURAL_VS_SEMANTIC_VALIDATION.md](./STRUCTURAL_VS_SEMANTIC_VALIDATION.md)** — OSS vs Cloud boundary.
+- **[IR_CONTRACT.md](./IR_CONTRACT.md)** — normalized node/edge shapes before lint runs.
+- **`src/lint-rules.ts`** — reference implementations for **`IR-LINT-*`**.

package/docs/ENGINEERING_NOTES.md

@@ -0,0 +1,42 @@
+# Engineering notes (audit responses & tradeoffs)
+
+Internal reference for **quality posture** and known limits of `@archrad/deterministic`.
+
+## TypeScript
+
+- **`strict`: true** — enabled in `tsconfig.json` (with `noUnusedLocals` / `noUnusedParameters`). `tsconfig.build.json` extends it; **`npm test`** runs **`tsc -p tsconfig.build.json --noEmit`** before Vitest.
+- **`skipLibCheck`: true** — keeps builds fast; dependency `.d.ts` issues are not typechecked. Acceptable while `strict` is on for first-party code.
+
+## Linting (Biome)
+
+- **Biome** is installed with a **minimal** ruleset (`biome.json`: `noDebugger` only) so `npm run lint` is green without a large style refactor. Expanding to `recommended` rules (and/or formatter) is a follow-up chore.
+
+## IR-LINT-SYNC-CHAIN-001
+
+- Depth uses **synchronous edges only**. Edges are excluded when `edgeRepresentsAsyncBoundary` is true — e.g. `metadata.protocol: async|message|queue|event`, `metadata.async: true`, `config.async: true`, top-level `edge.kind` merged into metadata, channel-like `kind`, edges **to** queue/topic/stream-like node types, or target nodes classified as queue-like (see `lint-graph.ts` / `graphPredicates.ts`). Document async boundaries in IR to avoid false positives.
+- **HTTP entry selection:** The rule prefers HTTP-like nodes with **no incoming synchronous** edges as chain **starts**. If that set is empty (every HTTP-like node has an incoming sync edge — e.g. unusual modeling or an internal-only slice), the implementation **falls back** to using **all** HTTP-like nodes as possible starts so deep synchronous chains are still detectable. Interpret warnings in that case with your graph’s northbound entry model.
+
+## CLI safety
+
+- **`--danger-skip-ir-structural-validation`** is the **documented** escape hatch; **`--skip-ir-structural-validation`** remains as a **hidden** backward-compatible alias. Do not use either in CI for real bundles.
+
+## `npm install` / `prepare`
+
+- **`prepare`** was removed so installing the package does not always compile TS. **`prepublishOnly`** runs **`npm run build`** before **npm publish** (tarball includes `dist/`).
+- **Monorepo / `file:..` consumers** (e.g. InkByte `server`) must **build** `packages/deterministic` **before** `npm ci` in the consumer — already covered in **`docs/DETERMINISTIC_OSS_SYNC.md`** and CI.
+
+## OpenAPI pass
+
+- Export only validates **document shape** (parse + required top-level fields), not Spectral-level spec lint. See README and `openapi-structural.ts`.
+
+## Host port probe
+
+- Preflight checks **127.0.0.1** only; bindings on `0.0.0.0` / IPv6 or other hosts may not be detected.
+
+## Dependencies
+
+- **Major bumps** (e.g. Commander) should be reviewed manually; do not auto-merge without checking CLI behavior.
+
+## Versioning
+
+- **0.1.0** / pre-1.0: public API and CLI flags may still evolve; follow **CHANGELOG.md**.

package/docs/IR_CONTRACT.md

@@ -0,0 +1,54 @@
+# IR contract: parser boundary and validation levels
+
+## External input (parser boundary)
+
+The toolchain accepts **either**:
+
+- `{ "graph": { ... } }` — product / wrapped shape, or  
+- A **bare graph** object with top-level `nodes` (and optional `edges`, `metadata`).
+
+`normalizeIrGraph(ir)` returns a single internal **`graph`** object in both cases.
+
+## Internal normalized graph (after unwrap)
+
+Always:
+
+- `graph.metadata` — object (default `{}` if missing or invalid)
+- `graph.nodes` — array (required for export; validated separately)
+- `graph.edges` — array or absent; non-array `edges` is treated as `[]` with a structural **warning**
+
+`materializeNormalizedGraph(graph)` builds the **coerced** view used by structural validation and architecture lint (generators still receive the **original** IR).
+
+## Internal normalized node
+
+| Field    | Meaning |
+|----------|---------|
+| `id`     | string (trimmed from `id`) |
+| `type`   | string, lowercased from `type` **or** `kind` |
+| `name`   | string |
+| `config` | object (empty if missing / non-object) |
+| `schema` | object (empty if missing / non-object) |
+
+## Internal normalized edge
+
+| Field    | Meaning |
+|----------|---------|
+| `id`     | string |
+| `from`   | string, from `from` **or** `source` |
+| `to`     | string, from `to` **or** `target` |
+| `config` | object (empty if missing / non-object) |
+| `metadata` | object (preserved for lint, e.g. `protocol: async`, `kind` from top-level **`edge.kind`** when `metadata.kind` is unset; empty if missing) |
+
+**Index contract:** `materializeNormalizedGraph` maps **`graph.edges[i]` → `normalized.edges[i]`** 1:1 when `edges` is an array; structural findings reference `edgeIndex` in that array.
+
+API: `materializeNormalizedGraph`, `normalizeNodeSlot`, `normalizeEdgeSlot` in `src/ir-normalize.ts` (re-exported from the package entry).
+
+## Validation levels (contract for developers)
+
+1. **JSON Schema validation** — Document contract: `schemas/archrad-ir-graph-v1.schema.json`. Use in editors, CI, or with a schema validator; this package does not require Ajv at runtime for export.
+2. **IR structural validation** — Runtime checks in `validateIrStructural`: nodes array, unique ids (edges referencing **duplicate** ids get **`IR-STRUCT-EDGE_AMBIGUOUS_*`**), **HTTP-like** node types (shared predicate with lint: `http`, `rest`, `gateway`, …), `config` path/method, edge endpoints, directed cycles (cycle message includes an example node id). Codes: **`IR-STRUCT-*`**.
+3. **Export-time OpenAPI structural validation** — After codegen, **`validateOpenApiInBundleStructural`** (parse + required OpenAPI document fields). Not Spectral-level API lint.
+
+Between (2) and (3), **architecture lint** (`IR-LINT-*`) runs on a parsed graph from the normalized shape; it is heuristic, not JSON Schema. **`validateIrLint`** returns **`IR-STRUCT-*`** when the IR cannot be normalized (same as `normalizeIrGraph`); **`runDeterministicExport`** folds those into **`irStructuralFindings`** if structural validation was skipped so exports still fail closed on invalid roots / empty graphs.
+
+See also [STRUCTURAL_VS_SEMANTIC_VALIDATION.md](./STRUCTURAL_VS_SEMANTIC_VALIDATION.md).

package/docs/STRUCTURAL_VS_SEMANTIC_VALIDATION.md

@@ -0,0 +1,86 @@
+# Structural vs semantic validation (open core)
+
+This document defines how **@archrad/deterministic** (OSS) and **ArchRad Cloud** (product) split validation.
+
+**OSS positioning:** *Includes structural validation + basic architecture linting (rule-based, deterministic).*
+
+## OSS layers (names)
+
+| Name in docs | Role |
+|--------------|------|
+| **IR structural validation** | Graph shape, references, cycles, HTTP path/method |
+| **Architecture lint (basic)** | Deterministic heuristics (`IR-LINT-*`), no AI |
+| **OpenAPI structural validation** | Document **shape** on generated spec (parse + required fields) |
+
+## Structural (OSS)
+
+**Question:** Is the blueprint IR **well-formed** and **safe for the deterministic compiler**?
+
+**Where:** `validateIrStructural()`, first step of `archrad validate` / `archrad export`.
+
+**Examples:**
+
+| Code | Meaning |
+|------|---------|
+| `IR-STRUCT-EDGE_UNKNOWN_FROM` | Edge references a node id that does not exist |
+| `IR-STRUCT-EDGE_AMBIGUOUS_FROM` / `…_TO` | Edge uses an id that appears on **more than one** node |
+| `IR-STRUCT-CYCLE` | Directed cycle (message names an example node on the cycle) |
+| `IR-STRUCT-HTTP_PATH` | HTTP-**like** node (`http`, `rest`, `gateway`, …) `config.url` must start with `/` |
+| `IR-STRUCT-DUP_NODE_ID` | Two nodes share the same `id` |
+
+Findings use **`severity`**: `error` (blocks export) or `warning` / `info` when applicable.
+
+**Contract:** See **`schemas/archrad-ir-graph-v1.schema.json`** for JSON shape; code rules may be stricter. **Parser boundary and normalized node/edge shapes:** [IR_CONTRACT.md](./IR_CONTRACT.md).
+
+## Architecture lint (OSS)
+
+**Question:** Does the graph trip **light, rule-based** architecture smells (still deterministic)?
+
+**Where:** `validateIrLint()` (returns **`IR-LINT-*`** when the graph parses; **`IR-STRUCT-*`** only if normalize fails — e.g. invalid root, empty nodes), `archrad validate` (after structural pass; structural errors skip the lint pass), `archrad export` (unless `--skip-ir-lint`). **`buildParsedLintGraph`** returns **`{ findings }`** with structural codes on failure instead of `null`; use **`isParsedLintGraph()`** to narrow.
+
+| Code | Meaning |
+|------|---------|
+| `IR-LINT-DIRECT-DB-ACCESS-002` | HTTP node has a direct edge to a datastore-like node |
+| `IR-LINT-SYNC-CHAIN-001` | Long **synchronous** dependency chain from an HTTP entry (async-marked edges excluded; see `edgeRepresentsAsyncBoundary` in `lint-graph.ts`) |
+| `IR-LINT-NO-HEALTHCHECK-003` | HTTP routes exist but no typical health-like path (heuristic incl. `/health`, `/ping`, `/healthcheck`, …; one route per HTTP node) |
+| `IR-LINT-HIGH-FANOUT-004` | Node with ≥5 outgoing edges |
+| `IR-LINT-ISOLATED-NODE-005` | Node with no edges while the graph has other edges (disconnected subgraph) |
+| `IR-LINT-DUPLICATE-EDGE-006` | Same `from`→`to` edge appears more than once |
+| `IR-LINT-HTTP-MISSING-NAME-007` | HTTP-like node has empty `name` |
+| `IR-LINT-DATASTORE-NO-INCOMING-008` | Datastore-like node has no incoming edges |
+| `IR-LINT-MULTIPLE-HTTP-ENTRIES-009` | More than one HTTP node with no incoming edges |
+
+**CI:** `archrad validate --fail-on-warning` or `--max-warnings N`. Not org-specific policy — that stays in Cloud. **Custom deterministic visitors** on the same graph (e.g. **`ORG-*`** codes): see **[CUSTOM_RULES.md](./CUSTOM_RULES.md)**.
+
+## Semantic (ArchRad Cloud)
+
+**Question:** Is this architecture **appropriate** for security, compliance, scale, and org policy?
+
+**Marketing / product names:** **Policy engine**, **architecture intelligence**, **AI remediation** (not shipped in `@archrad/deterministic`).
+
+**Examples:** missing auth on sensitive routes, PII handling, SOC2 mapping, deeper bottleneck analysis, idempotency guidance, **AI-assisted repair loops**.
+
+This layer is **not** required to use the OSS CLI or library offline.
+
+## OpenAPI “document shape” (OSS, post-generation)
+
+After codegen, **`validateOpenApiInBundleStructural`** checks that the generated spec is **parseable OpenAPI 3.x** with **`paths`**, **`info.title`**, and **`info.version`**.
+
+That is **document shape**, not full API linting: it does **not** enforce Spectral-style rules (e.g. mandatory `security`, `operationId` conventions, or style). Use Spectral or Cloud semantic checks if you need that depth.
+
+## Codegen vs validation (retry / timeouts)
+
+The FastAPI/Express generators **can emit** retry, backoff, or circuit-breaker **code** when the IR includes the right edge/node config. That is **generation**, not proof that every external call is resilient.
+
+Requiring “timeouts and retries on all third-party calls” is a **policy / semantic** concern — a good fit for **ArchRad Cloud** or org-specific tooling, not the baseline OSS structural layer.
+
+## OSS package vs InkByte product
+
+**`@archrad/deterministic`** (and the public **`arch-deterministic`** repo) ship only what is in this package: IR structural rules, deterministic export, OpenAPI document-shape check, golden Docker/Makefile.
+
+The **InkByte** monorepo may contain additional validation, analyzers, and LLM workflows under **`server/`** and elsewhere. Those are **not** implied by the OSS README unless the same code is published in this package.
+
+## One-line summary
+
+- **Structural:** “Your graph **compiles**.”
+- **Semantic:** “Your graph **should** run in production, per policy and best practice.”

package/fixtures/demo-direct-db-layered.json

@@ -0,0 +1,37 @@
+{
+  "graph": {
+    "metadata": {
+      "name": "demo-direct-db-layered",
+      "description": "GIF/demo: same intent as violation fixture — API → service → Postgres; health route chained from API entry. Passes architecture lint (no IR-LINT-*)."
+    },
+    "nodes": [
+      {
+        "id": "orders-api",
+        "type": "http",
+        "name": "Orders API",
+        "config": { "url": "/orders", "method": "GET" }
+      },
+      {
+        "id": "health",
+        "type": "http",
+        "name": "Health",
+        "config": { "url": "/health", "method": "GET" }
+      },
+      {
+        "id": "orders-svc",
+        "type": "service",
+        "name": "Orders service"
+      },
+      {
+        "id": "orders-db",
+        "type": "postgres",
+        "name": "Orders DB"
+      }
+    ],
+    "edges": [
+      { "from": "orders-api", "to": "health", "id": "e-api-health" },
+      { "from": "orders-api", "to": "orders-svc", "id": "e-api-svc" },
+      { "from": "orders-svc", "to": "orders-db", "id": "e-svc-db" }
+    ]
+  }
+}