@archrad/deterministic 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,66 @@
+# Changelog
+
+All notable changes to **`@archrad/deterministic`** are documented here.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+### Added
+- **[docs/CUSTOM_RULES.md](docs/CUSTOM_RULES.md)** — custom **`IR-LINT`-style** visitors (`ParsedLintGraph` → **`IrStructuralFinding[]`**): worked **service / `config.timeout`** example, **compose** (`runArchitectureLinting` + org rules) vs **fork** (`LINT_RULE_REGISTRY`); no runtime registry mutation.
+- **`archrad validate-drift`** — compare an on-disk export directory to a **fresh** deterministic export from the same IR (`DRIFT-MISSING` / `DRIFT-MODIFIED` / optional `DRIFT-EXTRA` with **`--strict-extra`**); **`--json`** for CI. Library: **`runValidateDrift`**, **`diffExpectedExportAgainstFiles`**, **`runDriftCheckAgainstFiles`**, etc. (`src/validate-drift.ts`).
+- **VHS tape** **`scripts/record-demo-drift.tape`** → **`demo-drift.gif`**; **`npm run record:demo:drift`**. Storyboard and recording docs updated (**`scripts/DEMO_GIF_STORYBOARD.md`**). **Replay without VHS:** **`scripts/run-demo-drift-sequence.sh`** / **`.ps1`** for ShareX/OBS/asciinema capture; **`README_DEMO_RECORDING.md`** (**When VHS fails**).
+- **`graphPredicates.ts`**: shared **`isHttpLikeType`** / **`isDbLikeType`** / **`isQueueLikeNodeType`** (exported from the package root) so structural HTTP checks and IR-LINT stay aligned.
+- **`IR-STRUCT-EDGE_AMBIGUOUS_FROM` / `IR-STRUCT-EDGE_AMBIGUOUS_TO`** when an edge references a **duplicate** node id.
+- **`ParsedLintGraph.inDegree`**, **`BuildParsedLintGraphResult`**, **`isParsedLintGraph()`** — `buildParsedLintGraph` returns **`{ findings }`** on parse failure instead of **`null`**.
+- Richer **`IR-STRUCT-CYCLE`** message (example node on the cycle) and **`nodeId`** when detectable.
+- **`archrad yaml-to-ir`** — YAML blueprint → canonical `{ "graph": … }` JSON (`-y/--yaml`, `-o/--out` or stdout). Library: **`parseYamlToCanonicalIr`**, **`canonicalIrToJsonString`**, **`YamlGraphParseError`**. Fixture **`fixtures/minimal-graph.yaml`**.
+- **Five architecture lint rules** (`IR-LINT-ISOLATED-NODE-005` … **009**): isolated nodes when the graph has edges elsewhere, duplicate edges, HTTP missing `name`, datastore with no incoming edges, multiple HTTP entry nodes. CLI prints **Architecture lint (IR-LINT-*)** in a separate block from structural findings.
+- Launch line: **Validate your architecture before you write code.** (README, `llms.txt`, npm `description`, `archrad --help` / `validate` description, clean `archrad validate` stdout).
+- **`ir-normalize`** (`materializeNormalizedGraph`, `NormalizedGraph` / node / edge types) — parser boundary docs in **`docs/IR_CONTRACT.md`**; README **Validation levels** (JSON Schema → IR structural → export-time OpenAPI structural).
+- **`llms.txt`** at package root — markdown summary for LLM/agent discovery (included in npm tarball).
+- **IR structural validation** (`validateIrStructural`, `normalizeIrGraph`, `hasIrStructuralErrors`): node ids, HTTP path/method, edge endpoints, directed **cycles**; codes like `IR-STRUCT-*`.
+- **Architecture lint** (`validateIrLint`, **`IR-LINT-*`**): deterministic rules only — direct **HTTP→DB** edge, **sync chain** depth from HTTP entry, **missing health** path, **high fan-out** (≥5 outbound edges). No AI, no org policy.
+- **`archrad validate --ir <path>`** — structural + lint; **`--json`**; pretty output; **`--skip-lint`**, **`--fail-on-warning`**, **`--max-warnings <n>`** for CI.
+- **`schemas/archrad-ir-graph-v1.schema.json`** — documented JSON shape for the graph IR (companion to code rules).
+- **`runDeterministicExport`** returns **`irStructuralFindings`** and **`irLintFindings`**; **structural errors** block codegen unless **`skipIrStructuralValidation`**.
+- CLI **`export`**: **`--skip-ir-structural-validation`**, **`--skip-ir-lint`**, **`--fail-on-warning`**, **`--max-warnings <n>`** (blocks writes when IR policy fails).
+- Library: **`validateIrLint`**, **`sortFindings`**, **`shouldFailFromFindings`**, **`IrFindingLayer`**.
+- Fixtures **`invalid-edge-unknown-node.json`**, **`invalid-cycle.json`** for negative tests; **`ecommerce-with-warnings.json`** triggers all four **`IR-LINT-*`** rules for demos and tests.
+
+### Changed
+- **`validateIrLint`** returns **structural findings** when the IR cannot be built (same codes as **`normalizeIrGraph`** / empty graph), instead of **`[]`**.
+- **`runDeterministicExport`**: when **`skipIrStructuralValidation`** is set, **`IR-STRUCT-*`** from **`validateIrLint`** are merged into **`irStructuralFindings`** (and block codegen on errors); **`irLintFindings`** stays **`IR-LINT-*`** only — aligns server logging and product “fail closed” on invalid/empty IR.
+- **`normalizeEdgeSlot`**: top-level **`edge.kind`** is copied into **`metadata.kind`** when metadata does not already set **`kind`** (preserves async lint signal).
+- **`edgeRepresentsAsyncBoundary`**: considers top-level **`kind`**, optional **`ParsedLintGraph`** (queue-like **target** nodes), and normalized metadata.
+- **`IR-LINT-DIRECT-DB-ACCESS-002`**: one finding per **`(from,to)`** pair (deduped parallel edges).
+- **`looksLikeHealthUrl`**: **`/healthcheck`**, **`/ping`**, **`/status`**, **`/alive`** (and **`ruleNoHealthcheck`** message notes gateway/BFF heuristic).
+- **`isHttpLikeType`**: **`gateway`**, **`bff`**, **`graphql`**, **`grpc`**, and word-boundary matches for common API surface types.
+
+### Changed (engineering / safety)
+- **TypeScript `strict: true`** + **`noUnusedLocals` / `noUnusedParameters`**; **`npm test`** runs **`tsc --noEmit`** before Vitest.
+- **`prepare`** removed; **`prepublishOnly`** runs **`npm run build`** for npm publishes. Monorepo consumers must build this package explicitly (unchanged for InkByte CI).
+- **Biome** added with a **minimal** lint ruleset (`npm run lint`); expand rules incrementally — see **`docs/ENGINEERING_NOTES.md`**.
+- **IR-LINT-SYNC-CHAIN-001** uses **sync-only** adjacency; edges marked async (`metadata.protocol`, `config.async`, etc.) are excluded — see **`edgeRepresentsAsyncBoundary`** in `lint-graph.ts`.
+- **CLI:** **`--danger-skip-ir-structural-validation`** documented; **`--skip-ir-structural-validation`** hidden (deprecated alias).
+
+### Changed (documentation / messaging)
+- **`docs/CONCEPT_ADOPTION_AND_LIMITS.md`** — honest framing: strengths (IR as SoT, compiler model, tiered validation), adoption friction (IR authoring, one-way export), OSS-as-trust vs platform adoption; README + `llms.txt` summaries and links.
+- Canonical **OSS positioning** line in README, `llms.txt`, monorepo/OSS docs: *Includes structural validation + basic architecture linting (rule-based, deterministic).*
+- Clarified OpenAPI pass as **document shape** (parse + required top-level fields), explicitly **not** Spectral-style lint; README + `docs/STRUCTURAL_VS_SEMANTIC_VALIDATION.md` + code comments.
+- Documented **codegen vs validation** for retry/timeout IR fields and **InkByte vs OSS** scope in README and structural/semantic doc.
+- README positioning: **deterministic compiler and linter for system architecture**; validation layers table (OSS vs Cloud).
+
+## [0.1.0] - 2026-02-26
+
+### Added
+- Deterministic **FastAPI** and **Express** generators from blueprint **IR** (JSON graph).
+- **`archrad export`** CLI (`--ir`, `--target`, `--out`).
+- **Structural OpenAPI** validation pass on generated bundles (warnings, no LLM repair).
+- **Golden path**: `docker-compose.yml`, `Dockerfile`, `Makefile`, README section; container port **8080**; configurable **host** publish port (`--host-port` / `ARCHRAD_HOST_PORT`).
+- Optional **localhost preflight** for host port (warn or `--strict-host-port`).
+- Library API: `runDeterministicExport`, OpenAPI helpers, golden-layer helpers.
+
+[Unreleased]: https://github.com/archradhq/arch-deterministic/compare/v0.1.0...HEAD
+[0.1.0]: https://github.com/archradhq/arch-deterministic/releases/tag/v0.1.0

package/CONTRIBUTING.md

@@ -0,0 +1,15 @@
+# Contributing
+
+Development usually happens in the **private InkByte monorepo** under `packages/deterministic`, so the server and package stay in sync.
+
+When you change this package, follow the product monorepo checklist: **`docs/MONOREPO_OSS_DETERMINISTIC_ALIGNMENT.md`** (and run **`npm run test:deterministic`** from the **InkByte repo root**).
+
+If you clone **only** this repository (`archradhq/arch-deterministic`):
+
+```bash
+npm ci
+npm run build   # required: there is no prepare script (see docs/ENGINEERING_NOTES.md)
+npm test        # runs tsc --noEmit then vitest
+```
+
+PRs: keep changes **free of product-specific** imports (no Firestore, no `server/` paths). Apache-2.0 — see `LICENSE`.

package/LICENSE

@@ -0,0 +1,17 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   Copyright 2026 ArchRad / InkByte contributors
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -0,0 +1,284 @@
+# @archrad/deterministic
+
+![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`. -->
+
+**A deterministic compiler and linter for system architecture.**
+
+**Validate your architecture before you write code.**
+
+**For AI agents / IDE assistants:** see **`llms.txt`** in this package (llms.txt-style project summary for tools like Claude Code, Devin, etc.).
+
+**Apache-2.0** — blueprint **IR** (JSON graph) → **FastAPI** or **Express** + **OpenAPI**, **Docker**, **Makefile** — **no LLM**, **no account**, **offline**.
+
+**OSS positioning:** *Includes structural validation + basic architecture linting (rule-based, deterministic).*
+
+> 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).
+
+**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`**.
+
+### Concept, cold start, and strategy (honest scope)
+
+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).
+
+---
+
+## How it works (architecture)
+
+```
+IR (nodes/edges)  →  validateIrStructural (IR-STRUCT-*)  →  errors block export
+                           ↓
+                    validateIrLint (IR-LINT-*)  →  warnings (CI: --fail-on-warning / --max-warnings)
+                           ↓
+              pythonFastAPI | nodeExpress generators
+                           ↓
+              openapi.yaml + app code + package metadata
+                           ↓
+              golden layer (Dockerfile, docker-compose.yml, Makefile, README; host→container e.g. 8080:8080)
+                           ↓
+              validateOpenApiInBundleStructural(openapi.yaml)  →  document-shape warnings (not full API lint)
+                           ↓
+              { files, openApiStructuralWarnings, irStructuralFindings, irLintFindings }
+
+  Optional CI: archrad validate-drift  →  re-export IR in-memory, diff vs existing ./out  →  DRIFT-MISSING / DRIFT-MODIFIED (thin deterministic gate)
+```
+
+### Validation levels (quick contract)
+
+1. **JSON Schema validation** — IR document shape vs `schemas/archrad-ir-graph-v1.schema.json` (editor/CI; optional at runtime).
+2. **IR structural validation** — `validateIrStructural`: arrays, ids, HTTP `config`, edge refs, cycles (`IR-STRUCT-*`). Uses an internal **normalized** graph (see **`docs/IR_CONTRACT.md`**).
+3. **Export-time generated OpenAPI structural validation** — Parse + required fields on the **generated** `openapi.yaml` (document shape, not Spectral).
+
+**Architecture lint** (`IR-LINT-*`) sits after structural checks: rule visitors on the parsed graph (heuristics, not schema).
+
+### Validation layers (naming)
+
+| Layer (OSS) | What it is | Codes |
+|-------------|------------|--------|
+| **IR structural validation** | Graph well-formedness: ids, edges, cycles, HTTP path/method | `IR-STRUCT-*` |
+| **Architecture lint (basic)** | Deterministic heuristics only (no AI, no org policy) | `IR-LINT-*` |
+| **OpenAPI structural validation** (document shape) | Parse + required top-level OpenAPI fields on **generated** spec | *(string warnings, not IR codes)* |
+
+| Layer (Cloud — not this package) | Examples |
+|----------------------------------|----------|
+| **Policy engine** | SOC2, org rules, entitlement |
+| **Architecture intelligence** | Deeper NFR / cost / security reasoning |
+| **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`**).
+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`**.
+
+**IR contract:** **`schemas/archrad-ir-graph-v1.schema.json`**. **Parser boundary + normalized shapes:** **`docs/IR_CONTRACT.md`** (`normalizeIrGraph` → `materializeNormalizedGraph`).
+
+**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.
+
+### 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.
+
+---
+
+## Ways to use it
+
+| Mode | Best for | Example |
+|------|-----------|---------|
+| **CLI** | Quick local scaffolding, CI, “no Node project” usage | `archrad export --ir graph.json --target python --out ./out` |
+| **YAML → IR** | Author graphs in YAML, emit JSON for validate/export | `archrad yaml-to-ir -y graph.yaml -o graph.json` |
+| **OpenAPI → IR** | Derive HTTP nodes from OpenAPI 3.x (same IR shape as YAML path); **ArchRad Cloud** merge uses the same library | `archrad ingest openapi --spec openapi.yaml -o graph.json` |
+| **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 |
+
+### 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**.
+
+**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:
+
+```bash
+archrad ingest openapi --spec ./openapi.yaml --out ./graph.json
+archrad validate --ir ./graph.json
+archrad export --ir ./graph.json --target python --out ./out
+```
+
+**YAML → JSON (lighter authoring):** edit **`fixtures/minimal-graph.yaml`** (or your own file) and compile to IR JSON, then validate or export:
+
+```bash
+archrad yaml-to-ir --yaml fixtures/minimal-graph.yaml --out ./graph.json
+archrad validate --ir ./graph.json
+# or pipe: archrad yaml-to-ir -y fixtures/minimal-graph.yaml | archrad validate --ir /dev/stdin   # on Unix; on Windows use --out then validate
+```
+
+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`**):
+
+```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
+# Machine-readable + CI gates:
+archrad validate --ir ./graph.json --json
+archrad validate --ir ./graph.json --fail-on-warning
+archrad validate --ir ./graph.json --max-warnings 0
+# Structural only (skip IR-LINT-*):
+archrad validate --ir ./graph.json --skip-lint
+```
+
+**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
+archrad export -i ./graph.json -t python -o ./out
+# …edit files under ./out…
+archrad validate-drift -i ./graph.json -t python -o ./out --skip-host-port-check
+# CI-friendly:
+archrad validate-drift -i ./graph.json -t python -o ./out --skip-host-port-check --json
+# Fail if the tree has extra files not in the reference export:
+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
+archrad validate --ir fixtures/minimal-graph.json
+```
+
+Example output (stderr):
+
+```text
+archrad validate:
+⚠️ IR-LINT-NO-HEALTHCHECK-003: No HTTP node exposes a typical health/readiness path (...)
+   Fix: Add a GET route such as /health for orchestrators and load balancers.
+   Suggestion: Expose liveness vs readiness separately if your platform distinguishes them.
+   Impact: Weaker deploy/rollback safety and harder operations automation.
+```
+
+Structural errors look like **`❌ IR-STRUCT-...`** with **`Fix:`** lines. Use **`--json`** to consume findings in GitHub Actions or other CI.
+
+- **`--ir`** — JSON: `{ "graph": { "nodes", "edges", "metadata" } }` or a raw graph (CLI wraps it).
+- **`--target`** — `python` \| `node` \| `nodejs`
+- **`--out`** — output directory (created if needed)
+- **`--host-port <n>`** — host port Docker publishes (default **8080**; container still listens on **8080** inside). Same as env **`ARCHRAD_HOST_PORT`**.
+- **`--skip-host-port-check`** — don’t probe `127.0.0.1` before export.
+- **`--strict-host-port`** — **exit with error** if the host port appears **in use** (CI-friendly).
+- **`--danger-skip-ir-structural-validation`** — **UNSAFE:** skip **`validateIrStructural`** before export (never in CI). **Parse/normalize failures** (invalid root, empty graph) are still detected via **`validateIrLint`** and **block** export with **`IR-STRUCT-*`** in **`irStructuralFindings`**. A hidden **`--skip-ir-structural-validation`** remains as a deprecated alias.
+- **`--skip-ir-lint`** — skip **`validateIrLint`** during export.
+- **`--fail-on-warning`** / **`--max-warnings <n>`** — if set, **no files are written** when IR structural + lint findings violate the policy (same semantics as **`validate`**).
+
+By default, if **8080** (or your `--host-port`) looks **busy** on localhost, the CLI **warns** so you can change the port before `docker compose` fails with a bind error.
+
+**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
+import {
+  runDeterministicExport,
+  runValidateDrift,
+  validateIrStructural,
+  validateIrLint,
+  sortFindings,
+  shouldFailFromFindings,
+} from '@archrad/deterministic';
+
+const { files, openApiStructuralWarnings, irStructuralFindings, irLintFindings } =
+  await runDeterministicExport(ir, 'python', {
+    hostPort: 8080,
+    skipIrLint: false, // default
+  });
+// Structural errors → empty files (unless skipIrStructuralValidation). Lint is non-blocking for export unless you check policy in your pipeline.
+
+const drift = await runValidateDrift(ir, 'python', '/path/to/existing-export', {
+  skipIrLint: false, // set true to match CLI --skip-ir-lint on reference export
+});
+// drift.ok, drift.driftFindings, drift.exportResult — same core semantics as CLI validate-drift (CLI also probes host port before calling the library)
+
+const all = sortFindings([...validateIrStructural(ir), ...validateIrLint(ir)]);
+if (shouldFailFromFindings(all, { failOnWarning: true })) {
+  /* gate your CI */
+}
+```
+
+Optional: `isLocalHostPortFree` / `normalizeGoldenHostPort` from the same package if you want your own preflight.
+
+---
+
+## Golden path (~60 seconds)
+
+From the package root (after build):
+
+```bash
+node dist/cli.js export --ir fixtures/minimal-graph.json --target python --out ./out
+cd ./out
+make run
+# In another terminal, once the API is up:
+curl -sS -X POST http://localhost:8080/signup -H "Content-Type: application/json" -d '{}'
+```
+
+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
+```
+
+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`**.
+
+---
+
+## Open source vs ArchRad Cloud
+
+**This repository is only the deterministic engine** — local, offline, no phone-home.
+
+| Here (OSS) | ArchRad Cloud (commercial product) |
+|------------|-------------------------------------|
+| IR **structural** + **architecture lint** (`validate`, `IR-STRUCT-*`, `IR-LINT-*`), compiler (`export`), **`validate-drift`** (on-disk vs fresh export), OpenAPI **document-shape** warnings, golden Docker/Makefile | **Policy engine**, deeper **architecture intelligence**, **AI remediation**, richer **drift / sync** UX in the builder |
+| `archrad` CLI forever, no account required for this package | Auth, orgs, **quotas**, billing |
+| No proprietary **LLM** orchestration or “repair” loops | LLM generation, repair, multi-model routing |
+| No Git sync, no enterprise policy injection in this repo | Git push, governance, compliance dashboards |
+
+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
+
+See **`CONTRIBUTING.md`**.
+
+---
+
+## License
+
+Apache-2.0 — see **`LICENSE`**.

package/SECURITY.md

@@ -0,0 +1,26 @@
+# Security policy
+
+## Supported versions
+
+We publish **`@archrad/deterministic`** on npm from the [`archradhq/arch-deterministic`](https://github.com/archradhq/arch-deterministic) repository. Security fixes are applied on the **latest** minor release line when practical; use the newest version when possible.
+
+## Reporting a vulnerability
+
+**Please do not** open a public GitHub issue for undisclosed security problems.
+
+Instead:
+
+1. Prefer **GitHub private vulnerability reporting** on [`archradhq/arch-deterministic`](https://github.com/archradhq/arch-deterministic/security) if enabled; otherwise email the **repository maintainers** with:
+   - A short description and impact
+   - Steps to reproduce (if safe to share)
+   - Affected versions / environments (Node, OS) if known
+
+2. We aim to acknowledge within **a few business days** and coordinate disclosure and a fix release.
+
+## Scope
+
+This package is a **local** CLI and library: **IR JSON → project files**. It does not ship a network service by default. Reports about **generated application code** (e.g. a user’s Docker image) are usually out of scope unless the issue is in **this package’s** templates or logic.
+
+## Dependency advisories
+
+Run `npm audit` in your project after installing. We use **Dependabot** on the GitHub repo for dependency update PRs.

package/biome.json

@@ -0,0 +1,25 @@
+{
+  "$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"
+    }
+  }
+}

package/dist/cli-findings.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Human-oriented CLI formatting for IR findings (structural + architecture lint).
+ */
+import type { IrStructuralFinding } from './ir-structural.js';
+/** Pretty multi-line output for terminal / CI logs */
+export declare function formatFindingLines(f: IrStructuralFinding): string[];
+/**
+ * Pretty-print findings. By default groups **IR structural (IR-STRUCT-*)** and **architecture lint (IR-LINT-*)** so both are obvious in CI logs.
+ */
+export declare function printFindingsPretty(findings: IrStructuralFinding[], header?: string, options?: {
+    groupByLayer?: boolean;
+}): void;
+export type ValidationExitPolicy = {
+    /** When true, any warning fails the run (CI gate). */
+    failOnWarning?: boolean;
+    /** Fail when warning count is strictly greater than this (undefined = no limit) */
+    maxWarnings?: number;
+};
+export declare function countBySeverity(findings: IrStructuralFinding[], sev: IrStructuralFinding['severity']): number;
+/** true = exit with failure */
+export declare function shouldFailFromFindings(findings: IrStructuralFinding[], policy: ValidationExitPolicy): boolean;
+export declare function sortFindings(findings: IrStructuralFinding[]): IrStructuralFinding[];
+//# sourceMappingURL=cli-findings.d.ts.map

package/dist/cli-findings.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli-findings.d.ts","sourceRoot":"","sources":["../src/cli-findings.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAC;AAc9D,sDAAsD;AACtD,wBAAgB,kBAAkB,CAAC,CAAC,EAAE,mBAAmB,GAAG,MAAM,EAAE,CAYnE;AAWD;;GAEG;AACH,wBAAgB,mBAAmB,CACjC,QAAQ,EAAE,mBAAmB,EAAE,EAC/B,MAAM,CAAC,EAAE,MAAM,EACf,OAAO,CAAC,EAAE;IAAE,YAAY,CAAC,EAAE,OAAO,CAAA;CAAE,GACnC,IAAI,CAuBN;AAED,MAAM,MAAM,oBAAoB,GAAG;IACjC,sDAAsD;IACtD,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,mFAAmF;IACnF,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB,CAAC;AAEF,wBAAgB,eAAe,CAAC,QAAQ,EAAE,mBAAmB,EAAE,EAAE,GAAG,EAAE,mBAAmB,CAAC,UAAU,CAAC,GAAG,MAAM,CAE7G;AAED,+BAA+B;AAC/B,wBAAgB,sBAAsB,CAAC,QAAQ,EAAE,mBAAmB,EAAE,EAAE,MAAM,EAAE,oBAAoB,GAAG,OAAO,CAM7G;AAID,wBAAgB,YAAY,CAAC,QAAQ,EAAE,mBAAmB,EAAE,GAAG,mBAAmB,EAAE,CAKnF"}

package/dist/cli-findings.js

@@ -0,0 +1,88 @@
+/**
+ * Human-oriented CLI formatting for IR findings (structural + architecture lint).
+ */
+const ICON = {
+    error: '❌',
+    warning: '⚠️',
+    info: 'ℹ️',
+};
+function ttyColor() {
+    const noColor = process.env.NO_COLOR != null && process.env.NO_COLOR !== '';
+    if (noColor || !process.stderr.isTTY)
+        return { red: '', reset: '' };
+    return { red: '\u001b[31m', reset: '\u001b[0m' };
+}
+/** Pretty multi-line output for terminal / CI logs */
+export function formatFindingLines(f) {
+    const icon = ICON[f.severity] ?? '•';
+    const { red, reset } = ttyColor();
+    const head = f.code.startsWith('IR-LINT-') && red
+        ? `${red}${icon} ${f.code}: ${f.message}${reset}`
+        : `${icon} ${f.code}: ${f.message}`;
+    const lines = [head];
+    if (f.fixHint)
+        lines.push(`   Fix: ${f.fixHint}`);
+    if (f.suggestion)
+        lines.push(`   Suggestion: ${f.suggestion}`);
+    if (f.impact)
+        lines.push(`   Impact: ${f.impact}`);
+    return lines;
+}
+function printFindingBlock(findings) {
+    for (const f of findings) {
+        for (const line of formatFindingLines(f)) {
+            console.error(line);
+        }
+        console.error('');
+    }
+}
+/**
+ * Pretty-print findings. By default groups **IR structural (IR-STRUCT-*)** and **architecture lint (IR-LINT-*)** so both are obvious in CI logs.
+ */
+export function printFindingsPretty(findings, header, options) {
+    if (!findings.length)
+        return;
+    if (header)
+        console.error(header);
+    const group = options?.groupByLayer !== false;
+    if (!group) {
+        printFindingBlock(findings);
+        return;
+    }
+    const structural = findings.filter((f) => f.code.startsWith('IR-STRUCT-'));
+    const lint = findings.filter((f) => f.code.startsWith('IR-LINT-'));
+    const other = findings.filter((f) => !f.code.startsWith('IR-STRUCT-') && !f.code.startsWith('IR-LINT-'));
+    if (structural.length) {
+        console.error('IR structural (IR-STRUCT-*):');
+        printFindingBlock(structural);
+    }
+    if (lint.length) {
+        console.error('Architecture lint (IR-LINT-*):');
+        printFindingBlock(lint);
+    }
+    if (other.length) {
+        console.error('Other findings:');
+        printFindingBlock(other);
+    }
+}
+export function countBySeverity(findings, sev) {
+    return findings.filter((f) => f.severity === sev).length;
+}
+/** true = exit with failure */
+export function shouldFailFromFindings(findings, policy) {
+    if (findings.some((f) => f.severity === 'error'))
+        return true;
+    const w = countBySeverity(findings, 'warning');
+    if (Boolean(policy.failOnWarning) && w > 0)
+        return true;
+    if (policy.maxWarnings != null && w > policy.maxWarnings)
+        return true;
+    return false;
+}
+const SEV_ORDER = { error: 0, warning: 1, info: 2 };
+export function sortFindings(findings) {
+    return [...findings].sort((a, b) => {
+        const d = (SEV_ORDER[a.severity] ?? 9) - (SEV_ORDER[b.severity] ?? 9);
+        return d !== 0 ? d : a.code.localeCompare(b.code);
+    });
+}

package/dist/cli.d.ts

@@ -0,0 +1,7 @@
+#!/usr/bin/env node
+/**
+ * archrad — deterministic export without the hosted server.
+ * Usage: archrad export --ir graph.json --target python --out ./my-api
+ */
+export {};
+//# sourceMappingURL=cli.d.ts.map

package/dist/cli.d.ts.map

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