@archrad/deterministic 0.1.0

package/dist/cli.js

@@ -0,0 +1,341 @@
+#!/usr/bin/env node
+/**
+ * archrad — deterministic export without the hosted server.
+ * Usage: archrad export --ir graph.json --target python --out ./my-api
+ */
+import { readFile, mkdir, writeFile } from 'node:fs/promises';
+import { dirname, join, resolve } from 'node:path';
+import { Command, Option } from 'commander';
+import { runDeterministicExport } from './exportPipeline.js';
+import { isLocalHostPortFree, normalizeGoldenHostPort } from './hostPort.js';
+import { validateIrStructural, hasIrStructuralErrors } from './ir-structural.js';
+import { validateIrLint } from './ir-lint.js';
+import { printFindingsPretty, shouldFailFromFindings, sortFindings, } from './cli-findings.js';
+import { parseYamlToCanonicalIr, canonicalIrToJsonString, YamlGraphParseError, } from './yamlToIr.js';
+import { openApiStringToCanonicalIr, OpenApiIngestError } from './openapi-to-ir.js';
+import { runValidateDrift } from './validate-drift.js';
+async function writeTree(baseDir, files) {
+    for (const [rel, content] of Object.entries(files)) {
+        const dest = join(baseDir, rel);
+        await mkdir(dirname(dest), { recursive: true });
+        await writeFile(dest, content, 'utf8');
+    }
+}
+function parseMaxWarnings(v) {
+    if (v == null || v === '')
+        return undefined;
+    const n = parseInt(v, 10);
+    return Number.isFinite(n) ? n : undefined;
+}
+function exitPolicyFromOpts(opts) {
+    return {
+        failOnWarning: Boolean(opts.failOnWarning),
+        maxWarnings: parseMaxWarnings(opts.maxWarnings),
+    };
+}
+const program = new Command();
+program
+    .name('archrad')
+    .description('Validate your architecture before you write code. Deterministic compiler + linter — FastAPI / Express (no LLM, no server).')
+    .version('0.1.0');
+program
+    .command('validate')
+    .description('Validate your architecture before you write code — IR structural (IR-STRUCT-*) + architecture lint (IR-LINT-*)')
+    .requiredOption('-i, --ir <path>', 'Path to IR JSON (graph with nodes/edges or full wrapper)')
+    .option('--json', 'Print findings as JSON array to stdout')
+    .option('--skip-lint', 'Skip architecture lint (IR-LINT-*); structural only')
+    .option('--fail-on-warning', 'Exit with error if any warning (CI gate)')
+    .option('--max-warnings <n>', 'Exit with error if warning count is greater than n (e.g. 0 allows no warnings)')
+    .action(async (cmdOpts) => {
+    const irPath = resolve(cmdOpts.ir);
+    let ir;
+    try {
+        ir = JSON.parse(await readFile(irPath, 'utf8'));
+    }
+    catch {
+        console.error('archrad: invalid JSON in --ir file');
+        process.exitCode = 1;
+        return;
+    }
+    const noLint = Boolean(cmdOpts.skipLint);
+    const structural = validateIrStructural(ir);
+    const lint = noLint || hasIrStructuralErrors(structural) ? [] : validateIrLint(ir);
+    const combined = sortFindings([...structural, ...lint]);
+    if (cmdOpts.json) {
+        const forJson = combined.map((f) => ({
+            ...f,
+            layer: f.layer ?? (f.code.startsWith('IR-LINT-') ? 'lint' : 'structural'),
+        }));
+        console.log(JSON.stringify(forJson, null, 2));
+    }
+    else {
+        if (combined.length) {
+            printFindingsPretty(combined, 'archrad validate:');
+        }
+        else {
+            console.log('Validate your architecture before you write code.');
+            console.log('archrad: IR structural validation + architecture lint passed (no findings).');
+        }
+    }
+    const policy = exitPolicyFromOpts(cmdOpts);
+    if (shouldFailFromFindings(combined, policy)) {
+        process.exitCode = 1;
+    }
+});
+program
+    .command('yaml-to-ir')
+    .description('Convert YAML graph → canonical IR JSON (for validate / export without hand-editing JSON)')
+    .requiredOption('-y, --yaml <path>', 'Path to YAML blueprint (`graph:` wrapper or bare `nodes:`)')
+    .option('-o, --out <path>', 'Write JSON to file (default: print to stdout)')
+    .action(async (cmdOpts) => {
+    const yamlPath = resolve(cmdOpts.yaml);
+    let text;
+    try {
+        text = await readFile(yamlPath, 'utf8');
+    }
+    catch {
+        console.error('archrad yaml-to-ir: could not read --yaml file');
+        process.exitCode = 1;
+        return;
+    }
+    let ir;
+    try {
+        ir = parseYamlToCanonicalIr(text);
+    }
+    catch (e) {
+        if (e instanceof YamlGraphParseError) {
+            console.error(`archrad yaml-to-ir: ${e.message}`);
+        }
+        else {
+            console.error('archrad yaml-to-ir:', e);
+        }
+        process.exitCode = 1;
+        return;
+    }
+    const json = canonicalIrToJsonString(ir);
+    if (cmdOpts.out) {
+        const outPath = resolve(cmdOpts.out);
+        await mkdir(dirname(outPath), { recursive: true });
+        await writeFile(outPath, json, 'utf8');
+        console.log(`archrad: wrote IR JSON to ${outPath}`);
+    }
+    else {
+        process.stdout.write(json);
+    }
+});
+const ingest = program.command('ingest').description('Derive canonical IR from an external spec (structural surface — same JSON as yaml-to-ir for validate/export)');
+ingest
+    .command('openapi')
+    .description('OpenAPI 3.x JSON/YAML → IR graph (HTTP nodes per operation; commit + archrad validate in CI)')
+    .requiredOption('-s, --spec <path>', 'Path to OpenAPI 3.x document (.json, .yaml, or .yml)')
+    .option('-o, --out <path>', 'Write IR JSON to file (default: print to stdout)')
+    .action(async (cmdOpts) => {
+    const specPath = resolve(cmdOpts.spec);
+    let text;
+    try {
+        text = await readFile(specPath, 'utf8');
+    }
+    catch {
+        console.error('archrad ingest openapi: could not read --spec file');
+        process.exitCode = 1;
+        return;
+    }
+    let ir;
+    try {
+        ir = openApiStringToCanonicalIr(text);
+    }
+    catch (e) {
+        if (e instanceof OpenApiIngestError) {
+            console.error(`archrad ingest openapi: ${e.message}`);
+        }
+        else {
+            console.error('archrad ingest openapi:', e);
+        }
+        process.exitCode = 1;
+        return;
+    }
+    const json = canonicalIrToJsonString(ir);
+    if (cmdOpts.out) {
+        const outPath = resolve(cmdOpts.out);
+        await mkdir(dirname(outPath), { recursive: true });
+        await writeFile(outPath, json, 'utf8');
+        console.log(`archrad ingest openapi: wrote IR JSON to ${outPath}`);
+    }
+    else {
+        process.stdout.write(json);
+    }
+});
+program
+    .command('export')
+    .description('Generate project files from a blueprint IR JSON file')
+    .requiredOption('-i, --ir <path>', 'Path to IR JSON (graph with nodes/edges or full wrapper)')
+    .requiredOption('-t, --target <name>', 'python | node | nodejs')
+    .requiredOption('-o, --out <dir>', 'Output directory')
+    .option('-p, --host-port <port>', 'Host port for docker compose publish (container stays 8080). Env: ARCHRAD_HOST_PORT')
+    .option('--skip-host-port-check', 'Do not check if host port is free on 127.0.0.1')
+    .option('--strict-host-port', 'Exit with error if host port is in use (implies check)')
+    .addOption(new Option('--danger-skip-ir-structural-validation', 'UNSAFE: skip validateIrStructural (invalid IR may still export; never use in CI)'))
+    .addOption(new Option('--skip-ir-structural-validation', 'Deprecated alias').hideHelp())
+    .option('--skip-ir-lint', 'Skip architecture lint (IR-LINT-*) during export')
+    .option('--fail-on-warning', 'Do not write output if IR structural or lint warnings exceed policy (with --max-warnings or any warning)')
+    .option('--max-warnings <n>', 'With export: fail if total IR warning count > n (structural + lint warnings)')
+    .action(async (cmdOpts) => {
+    const irPath = resolve(cmdOpts.ir);
+    const outDir = resolve(cmdOpts.out);
+    const raw = await readFile(irPath, 'utf8');
+    let ir;
+    try {
+        ir = JSON.parse(raw);
+    }
+    catch {
+        console.error('archrad: invalid JSON in --ir file');
+        process.exitCode = 1;
+        return;
+    }
+    const actualIR = ir.graph ? ir : { graph: ir };
+    const hostPort = normalizeGoldenHostPort(cmdOpts.hostPort ?? process.env.ARCHRAD_HOST_PORT);
+    if (!cmdOpts.skipHostPortCheck) {
+        const free = await isLocalHostPortFree(hostPort);
+        if (!free) {
+            const msg = `archrad: host port ${hostPort} appears in use on 127.0.0.1 (docker publish may fail). Use --host-port <n>, free the port, or --skip-host-port-check.`;
+            if (cmdOpts.strictHostPort) {
+                console.error(msg);
+                process.exitCode = 1;
+                return;
+            }
+            console.warn(`archrad: warning: ${msg}`);
+        }
+    }
+    const exportOpts = cmdOpts;
+    const skipStruct = Boolean(exportOpts.dangerSkipIrStructuralValidation || exportOpts.skipIrStructuralValidation);
+    try {
+        const { files, openApiStructuralWarnings, irStructuralFindings, irLintFindings } = await runDeterministicExport(actualIR, cmdOpts.target, {
+            hostPort,
+            skipIrStructuralValidation: skipStruct,
+            skipIrLint: cmdOpts.skipIrLint,
+        });
+        const combined = sortFindings([...irStructuralFindings, ...irLintFindings]);
+        if (combined.length) {
+            printFindingsPretty(combined, 'archrad export:');
+        }
+        const policy = exitPolicyFromOpts(cmdOpts);
+        const blockByPolicy = Object.keys(files).length > 0 &&
+            shouldFailFromFindings(combined, policy);
+        if (blockByPolicy) {
+            console.error('archrad: export aborted by --fail-on-warning / --max-warnings (no files written).');
+            process.exitCode = 1;
+            return;
+        }
+        if (Object.keys(files).length === 0) {
+            if (hasIrStructuralErrors(irStructuralFindings) && !cmdOpts.skipIrStructuralValidation) {
+                console.error('archrad: export aborted due to IR structural errors (fix graph or use archrad validate).');
+            }
+            else {
+                console.error('archrad: no files generated (check IR nodes/target)');
+            }
+            process.exitCode = 1;
+            return;
+        }
+        await writeTree(outDir, files);
+        console.log(`archrad: wrote ${Object.keys(files).length} files to ${outDir}`);
+        if (openApiStructuralWarnings.length) {
+            console.warn('archrad: OpenAPI document-shape warnings (parse + required fields, not Spectral lint):');
+            for (const w of openApiStructuralWarnings)
+                console.warn(`  - ${w}`);
+        }
+        console.log('\nNext: cd to output, then `docker compose up --build` (see README in bundle).');
+    }
+    catch (e) {
+        console.error('archrad:', e?.message || String(e));
+        process.exitCode = 1;
+    }
+});
+program
+    .command('validate-drift')
+    .description('Compare on-disk export to a fresh deterministic export from IR (missing/modified files = drift; not semantic analysis)')
+    .requiredOption('-i, --ir <path>', 'Path to IR JSON (graph with nodes/edges or full wrapper)')
+    .requiredOption('-t, --target <name>', 'python | node | nodejs')
+    .requiredOption('-o, --out <dir>', 'Directory containing a previous archrad export to compare')
+    .option('-p, --host-port <port>', 'Host port for golden compose (must match export). Env: ARCHRAD_HOST_PORT')
+    .option('--skip-host-port-check', 'Do not check if host port is free on 127.0.0.1')
+    .addOption(new Option('--danger-skip-ir-structural-validation', 'UNSAFE: skip validateIrStructural during reference export'))
+    .addOption(new Option('--skip-ir-structural-validation', 'Deprecated alias').hideHelp())
+    .option('--skip-ir-lint', 'Skip architecture lint when building reference export')
+    .option('--strict-extra', 'Fail if output directory contains files not in the reference export')
+    .option('--json', 'Print drift findings and export metadata as JSON')
+    .action(async (cmdOpts) => {
+    const irPath = resolve(cmdOpts.ir);
+    const outDir = resolve(cmdOpts.out);
+    let ir;
+    try {
+        ir = JSON.parse(await readFile(irPath, 'utf8'));
+    }
+    catch {
+        console.error('archrad: invalid JSON in --ir file');
+        process.exitCode = 1;
+        return;
+    }
+    const actualIR = ir.graph ? ir : { graph: ir };
+    const hostPort = normalizeGoldenHostPort(cmdOpts.hostPort ?? process.env.ARCHRAD_HOST_PORT);
+    if (!cmdOpts.skipHostPortCheck) {
+        const free = await isLocalHostPortFree(hostPort);
+        if (!free) {
+            console.warn(`archrad: warning: host port ${hostPort} appears in use (use --skip-host-port-check to ignore)`);
+        }
+    }
+    const skipStruct = Boolean(cmdOpts.dangerSkipIrStructuralValidation || cmdOpts.skipIrStructuralValidation);
+    try {
+        const result = await runValidateDrift(actualIR, cmdOpts.target, outDir, {
+            hostPort,
+            skipIrStructuralValidation: skipStruct,
+            skipIrLint: cmdOpts.skipIrLint,
+            strictExtra: cmdOpts.strictExtra,
+        });
+        const combined = sortFindings([
+            ...result.exportResult.irStructuralFindings,
+            ...result.exportResult.irLintFindings,
+        ]);
+        if (combined.length && !cmdOpts.json) {
+            printFindingsPretty(combined, 'archrad validate-drift (reference export):');
+        }
+        if (cmdOpts.json) {
+            console.log(JSON.stringify({
+                ok: result.ok,
+                driftFindings: result.driftFindings,
+                extraBlocking: result.extraBlocking,
+                irStructuralFindings: result.exportResult.irStructuralFindings,
+                irLintFindings: result.exportResult.irLintFindings,
+                openApiStructuralWarnings: result.exportResult.openApiStructuralWarnings,
+                referenceFileCount: Object.keys(result.exportResult.files).length,
+            }, null, 2));
+        }
+        else {
+            if (result.driftFindings.length) {
+                console.error('archrad validate-drift:');
+                for (const f of result.driftFindings) {
+                    const icon = f.code === 'DRIFT-EXTRA' ? 'ℹ️' : '❌';
+                    console.error(`${icon} ${f.code}: ${f.path}`);
+                    console.error(`   ${f.message}`);
+                    console.error('');
+                }
+            }
+            if (result.ok) {
+                console.log('archrad: no deterministic drift (on-disk export matches fresh export from IR).');
+            }
+            else {
+                console.error('archrad: drift detected — regenerate with `archrad export` or align the IR.');
+            }
+        }
+        if (!result.ok) {
+            process.exitCode = 1;
+        }
+    }
+    catch (e) {
+        console.error('archrad:', e?.message || String(e));
+        process.exitCode = 1;
+    }
+});
+program.parseAsync(process.argv).catch((e) => {
+    console.error(e);
+    process.exit(1);
+});

package/dist/edgeConfigCodeGenerator.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Edge Configuration Code Generator Utilities
+ * Provides utilities for code generators to use edge/connectivity configurations
+ */
+export interface EdgeConfig {
+    edgeType?: string;
+    protocol?: string;
+    transport?: 'sync' | 'async' | 'streaming';
+    config?: {
+        timeout?: number;
+        retry?: {
+            maxAttempts?: number;
+            strategy?: 'exponential' | 'linear' | 'fixed';
+            backoffMs?: number;
+        };
+        circuitBreaker?: {
+            enabled?: boolean;
+            failureThreshold?: number;
+            resetTimeoutMs?: number;
+        };
+        authentication?: {
+            type?: string;
+            credentialRef?: {
+                vault?: string;
+                key?: string;
+            };
+        };
+        loadBalancing?: {
+            strategy?: string;
+            endpoints?: string[];
+        };
+        [key: string]: any;
+    };
+}
+/**
+ * Generate retry logic code from edge configuration
+ */
+export declare function generateRetryCode(edgeConfig: EdgeConfig, language: 'python' | 'nodejs' | 'java' | 'csharp' | 'go'): string;
+/**
+ * Generate circuit breaker code from edge configuration
+ */
+export declare function generateCircuitBreakerCode(edgeConfig: EdgeConfig, language: 'python' | 'nodejs' | 'java' | 'csharp' | 'go'): string;
+/**
+ * Generate HTTP client code with edge configuration
+ */
+export declare function generateHttpClientCode(edgeConfig: EdgeConfig, url: string, method: string, language: 'python' | 'nodejs' | 'java' | 'csharp' | 'go'): string;
+/**
+ * Get edge configuration for a specific edge
+ */
+export declare function getEdgeConfig(edges: any[], fromNodeId: string, toNodeId: string): EdgeConfig | null;
+/**
+ * Apply edge configuration to code generation context
+ */
+export declare function applyEdgeConfigToContext(edges: any[], fromNodeId: string, toNodeId: string, context: Record<string, any>): void;
+//# sourceMappingURL=edgeConfigCodeGenerator.d.ts.map

package/dist/edgeConfigCodeGenerator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"edgeConfigCodeGenerator.d.ts","sourceRoot":"","sources":["../src/edgeConfigCodeGenerator.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,SAAS,CAAC,EAAE,MAAM,GAAG,OAAO,GAAG,WAAW,CAAC;IAC3C,MAAM,CAAC,EAAE;QACP,OAAO,CAAC,EAAE,MAAM,CAAC;QACjB,KAAK,CAAC,EAAE;YACN,WAAW,CAAC,EAAE,MAAM,CAAC;YACrB,QAAQ,CAAC,EAAE,aAAa,GAAG,QAAQ,GAAG,OAAO,CAAC;YAC9C,SAAS,CAAC,EAAE,MAAM,CAAC;SACpB,CAAC;QACF,cAAc,CAAC,EAAE;YACf,OAAO,CAAC,EAAE,OAAO,CAAC;YAClB,gBAAgB,CAAC,EAAE,MAAM,CAAC;YAC1B,cAAc,CAAC,EAAE,MAAM,CAAC;SACzB,CAAC;QACF,cAAc,CAAC,EAAE;YACf,IAAI,CAAC,EAAE,MAAM,CAAC;YACd,aAAa,CAAC,EAAE;gBACd,KAAK,CAAC,EAAE,MAAM,CAAC;gBACf,GAAG,CAAC,EAAE,MAAM,CAAC;aACd,CAAC;SACH,CAAC;QACF,aAAa,CAAC,EAAE;YACd,QAAQ,CAAC,EAAE,MAAM,CAAC;YAClB,SAAS,CAAC,EAAE,MAAM,EAAE,CAAC;SACtB,CAAC;QACF,CAAC,GAAG,EAAE,MAAM,GAAG,GAAG,CAAC;KACpB,CAAC;CACH;AAED;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,UAAU,EAAE,UAAU,EAAE,QAAQ,EAAE,QAAQ,GAAG,QAAQ,GAAG,MAAM,GAAG,QAAQ,GAAG,IAAI,GAAG,MAAM,CA+E1H;AAED;;GAEG;AACH,wBAAgB,0BAA0B,CAAC,UAAU,EAAE,UAAU,EAAE,QAAQ,EAAE,QAAQ,GAAG,QAAQ,GAAG,MAAM,GAAG,QAAQ,GAAG,IAAI,GAAG,MAAM,CAmFnI;AAED;;GAEG;AACH,wBAAgB,sBAAsB,CACpC,UAAU,EAAE,UAAU,EACtB,GAAG,EAAE,MAAM,EACX,MAAM,EAAE,MAAM,EACd,QAAQ,EAAE,QAAQ,GAAG,QAAQ,GAAG,MAAM,GAAG,QAAQ,GAAG,IAAI,GACvD,MAAM,CAgDR;AAED;;GAEG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,GAAG,EAAE,EAAE,UAAU,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,UAAU,GAAG,IAAI,CAanG;AAED;;GAEG;AACH,wBAAgB,wBAAwB,CACtC,KAAK,EAAE,GAAG,EAAE,EACZ,UAAU,EAAE,MAAM,EAClB,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAC3B,IAAI,CAaN"}

package/dist/edgeConfigCodeGenerator.js

@@ -0,0 +1,249 @@
+/**
+ * Edge Configuration Code Generator Utilities
+ * Provides utilities for code generators to use edge/connectivity configurations
+ */
+/**
+ * Generate retry logic code from edge configuration
+ */
+export function generateRetryCode(edgeConfig, language) {
+    const retry = edgeConfig.config?.retry;
+    if (!retry || !retry.maxAttempts || retry.maxAttempts <= 0) {
+        return '';
+    }
+    const maxAttempts = retry.maxAttempts;
+    const strategy = retry.strategy || 'exponential';
+    const backoffMs = retry.backoffMs || 1000;
+    switch (language) {
+        case 'python':
+            if (strategy === 'exponential') {
+                return `
+import time
+import random
+
+def retry_with_exponential_backoff(func, max_attempts=${maxAttempts}, base_delay=${backoffMs / 1000}):
+    """Retry function with exponential backoff"""
+    for attempt in range(max_attempts):
+        try:
+            return func()
+        except Exception as e:
+            if attempt == max_attempts - 1:
+                raise
+            delay = base_delay * (2 ** attempt) + random.uniform(0, 0.1)
+            time.sleep(delay)
+    raise Exception("Max retry attempts exceeded")
+`;
+            }
+            else {
+                return `
+import time
+
+def retry_with_linear_backoff(func, max_attempts=${maxAttempts}, delay=${backoffMs / 1000}):
+    """Retry function with linear backoff"""
+    for attempt in range(max_attempts):
+        try:
+            return func()
+        except Exception as e:
+            if attempt == max_attempts - 1:
+                raise
+            time.sleep(delay)
+    raise Exception("Max retry attempts exceeded")
+`;
+            }
+        case 'nodejs':
+            if (strategy === 'exponential') {
+                return `
+const retryWithExponentialBackoff = async (fn, maxAttempts = ${maxAttempts}, baseDelay = ${backoffMs}) => {
+  for (let attempt = 0; attempt < maxAttempts; attempt++) {
+    try {
+      return await fn();
+    } catch (error) {
+      if (attempt === maxAttempts - 1) throw error;
+      const delay = baseDelay * Math.pow(2, attempt) + Math.random() * 100;
+      await new Promise(resolve => setTimeout(resolve, delay));
+    }
+  }
+};
+`;
+            }
+            else {
+                return `
+const retryWithLinearBackoff = async (fn, maxAttempts = ${maxAttempts}, delay = ${backoffMs}) => {
+  for (let attempt = 0; attempt < maxAttempts; attempt++) {
+    try {
+      return await fn();
+    } catch (error) {
+      if (attempt === maxAttempts - 1) throw error;
+      await new Promise(resolve => setTimeout(resolve, delay));
+    }
+  }
+};
+`;
+            }
+        default:
+            return `// Retry logic: ${maxAttempts} attempts, ${strategy} backoff, ${backoffMs}ms base delay`;
+    }
+}
+/**
+ * Generate circuit breaker code from edge configuration
+ */
+export function generateCircuitBreakerCode(edgeConfig, language) {
+    const circuitBreaker = edgeConfig.config?.circuitBreaker;
+    if (!circuitBreaker?.enabled) {
+        return '';
+    }
+    const failureThreshold = circuitBreaker.failureThreshold || 5;
+    const resetTimeoutMs = circuitBreaker.resetTimeoutMs || 60000;
+    switch (language) {
+        case 'python':
+            return `
+from datetime import datetime, timedelta
+
+class CircuitBreaker:
+    def __init__(self, failure_threshold=${failureThreshold}, reset_timeout=${resetTimeoutMs / 1000}):
+        self.failure_threshold = failure_threshold
+        self.reset_timeout = reset_timeout
+        self.failure_count = 0
+        self.last_failure_time = None
+        self.state = 'CLOSED'  # CLOSED, OPEN, HALF_OPEN
+    
+    def call(self, func):
+        if self.state == 'OPEN':
+            if datetime.now() - self.last_failure_time > timedelta(seconds=self.reset_timeout):
+                self.state = 'HALF_OPEN'
+            else:
+                raise Exception("Circuit breaker is OPEN")
+        
+        try:
+            result = func()
+            if self.state == 'HALF_OPEN':
+                self.state = 'CLOSED'
+                self.failure_count = 0
+            return result
+        except Exception as e:
+            self.failure_count += 1
+            self.last_failure_time = datetime.now()
+            if self.failure_count >= self.failure_threshold:
+                self.state = 'OPEN'
+            raise
+`;
+        case 'nodejs':
+            return `
+class CircuitBreaker {
+  constructor(failureThreshold = ${failureThreshold}, resetTimeout = ${resetTimeoutMs}) {
+    this.failureThreshold = failureThreshold;
+    this.resetTimeout = resetTimeout;
+    this.failureCount = 0;
+    this.lastFailureTime = null;
+    this.state = 'CLOSED'; // CLOSED, OPEN, HALF_OPEN
+  }
+  
+  async call(fn) {
+    if (this.state === 'OPEN') {
+      if (Date.now() - this.lastFailureTime > this.resetTimeout) {
+        this.state = 'HALF_OPEN';
+      } else {
+        throw new Error('Circuit breaker is OPEN');
+      }
+    }
+    
+    try {
+      const result = await fn();
+      if (this.state === 'HALF_OPEN') {
+        this.state = 'CLOSED';
+        this.failureCount = 0;
+      }
+      return result;
+    } catch (error) {
+      this.failureCount++;
+      this.lastFailureTime = Date.now();
+      if (this.failureCount >= this.failureThreshold) {
+        this.state = 'OPEN';
+      }
+      throw error;
+    }
+  }
+}
+`;
+        default:
+            return `// Circuit breaker: ${failureThreshold} failures, ${resetTimeoutMs}ms reset timeout`;
+    }
+}
+/**
+ * Generate HTTP client code with edge configuration
+ */
+export function generateHttpClientCode(edgeConfig, url, method, language) {
+    const protocol = edgeConfig.protocol || 'https';
+    const timeout = edgeConfig.config?.timeout || 30000;
+    const hasRetry = edgeConfig.config?.retry?.maxAttempts && edgeConfig.config.retry.maxAttempts > 0;
+    const hasCircuitBreaker = edgeConfig.config?.circuitBreaker?.enabled;
+    switch (language) {
+        case 'python':
+            const retryCode = hasRetry ? generateRetryCode(edgeConfig, 'python') : '';
+            const cbCode = hasCircuitBreaker ? generateCircuitBreakerCode(edgeConfig, 'python') : '';
+            return `
+import requests
+${retryCode}
+${cbCode}
+
+def make_request():
+    response = requests.${method.toLowerCase()}(
+        '${protocol}://${url}',
+        timeout=${timeout / 1000}
+    )
+    response.raise_for_status()
+    return response.json()
+
+${hasRetry ? 'result = retry_with_exponential_backoff(make_request)' : 'result = make_request()'}
+`;
+        case 'nodejs':
+            const retryCodeJs = hasRetry ? generateRetryCode(edgeConfig, 'nodejs') : '';
+            const cbCodeJs = hasCircuitBreaker ? generateCircuitBreakerCode(edgeConfig, 'nodejs') : '';
+            return `
+const axios = require('axios');
+${retryCodeJs}
+${cbCodeJs}
+
+const makeRequest = async () => {
+  const response = await axios.${method.toLowerCase()}({
+    url: '${protocol}://${url}',
+    timeout: ${timeout}
+  });
+  return response.data;
+};
+
+${hasRetry ? 'const result = await retryWithExponentialBackoff(makeRequest);' : 'const result = await makeRequest();'}
+`;
+        default:
+            return `// HTTP ${method} request to ${protocol}://${url} with ${timeout}ms timeout`;
+    }
+}
+/**
+ * Get edge configuration for a specific edge
+ */
+export function getEdgeConfig(edges, fromNodeId, toNodeId) {
+    const edge = edges.find((e) => (e.from === fromNodeId || e.source === fromNodeId) && (e.to === toNodeId || e.target === toNodeId));
+    if (!edge)
+        return null;
+    return {
+        edgeType: edge.edgeType || edge.type,
+        protocol: edge.protocol,
+        transport: edge.transport,
+        config: edge.config,
+    };
+}
+/**
+ * Apply edge configuration to code generation context
+ */
+export function applyEdgeConfigToContext(edges, fromNodeId, toNodeId, context) {
+    const edgeConfig = getEdgeConfig(edges, fromNodeId, toNodeId);
+    if (edgeConfig) {
+        context.edgeType = edgeConfig.edgeType;
+        context.protocol = edgeConfig.protocol;
+        context.transport = edgeConfig.transport;
+        context.timeout = edgeConfig.config?.timeout;
+        context.hasRetry = !!(edgeConfig.config?.retry?.maxAttempts && edgeConfig.config.retry.maxAttempts > 0);
+        context.hasCircuitBreaker = edgeConfig.config?.circuitBreaker?.enabled;
+        context.retryConfig = edgeConfig.config?.retry;
+        context.circuitBreakerConfig = edgeConfig.config?.circuitBreaker;
+    }
+}

package/dist/exportPipeline.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Full deterministic export for Python FastAPI and Node Express (no LLM).
+ * Used by the ArchRad server and the `archrad` CLI.
+ */
+import { type IrStructuralFinding } from './ir-structural.js';
+export type DeterministicExportResult = {
+    files: Record<string, string>;
+    /** Human-readable lines when generated OpenAPI fails **document-shape** checks (not full spec lint) */
+    openApiStructuralWarnings: string[];
+    /**
+     * IR-STRUCT-* from `validateIrStructural`, or — when **`skipIrStructuralValidation`** is set — the same
+     * codes surfaced by **`validateIrLint`** if the IR cannot be parsed (invalid root, empty graph, etc.).
+     * Errors block codegen; this field stays the single source for “graph does not compile.”
+     */
+    irStructuralFindings: IrStructuralFinding[];
+    /** IR-LINT-* heuristics only; does not include IR-STRUCT-* (those live in `irStructuralFindings`). */
+    irLintFindings: IrStructuralFinding[];
+};
+/**
+ * Generate FastAPI or Express project files + golden Docker/Makefile + OpenAPI **document-shape** check.
+ */
+export declare function runDeterministicExport(actualIR: any, target: string, opts?: Record<string, any>): Promise<DeterministicExportResult>;
+//# sourceMappingURL=exportPipeline.d.ts.map

package/dist/exportPipeline.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"exportPipeline.d.ts","sourceRoot":"","sources":["../src/exportPipeline.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAOH,OAAO,EAGL,KAAK,mBAAmB,EACzB,MAAM,oBAAoB,CAAC;AAG5B,MAAM,MAAM,yBAAyB,GAAG;IACtC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC9B,uGAAuG;IACvG,yBAAyB,EAAE,MAAM,EAAE,CAAC;IACpC;;;;OAIG;IACH,oBAAoB,EAAE,mBAAmB,EAAE,CAAC;IAC5C,sGAAsG;IACtG,cAAc,EAAE,mBAAmB,EAAE,CAAC;CACvC,CAAC;AAEF;;GAEG;AACH,wBAAsB,sBAAsB,CAC1C,QAAQ,EAAE,GAAG,EACb,MAAM,EAAE,MAAM,EACd,IAAI,GAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAM,GAC7B,OAAO,CAAC,yBAAyB,CAAC,CAwDpC"}