@archrad/deterministic 0.1.3 → 0.1.4

package/CHANGELOG.md

@@ -7,6 +7,21 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.1.4] - 2026-04-06
+
+### Added
+
+- **`loadPolicyPacksFromFiles(sources)`** — compile PolicyPack YAML/JSON from in-memory **`{ name, content }[]`** (same semantics as **`loadPolicyPacksFromDirectory`**; no filesystem).
+- **Declarative policy packs** — YAML/JSON documents (`apiVersion: archrad/v1`, `kind: PolicyPack`) with `rules` that match **nodes** or **edges** on the parsed lint graph. Loader: **`loadPolicyPacksFromDirectory(dir)`** (supports `*.yaml`, `*.yml`, `*.json`; duplicate `rule.id` across the directory is rejected).
+- **CLI** — **`archrad validate`**, **`archrad export`**, and **`archrad validate-drift`** accept **`--policies <dir>`** to merge compiled rules after built-in **`IR-LINT-*`** (skipped when **`--skip-lint`** / **`--skip-ir-lint`** is set).
+- **ArchRad Cloud (InkByte server)** — org **`settings.archPolicyPacks`** (array of **`{ name, content }`**) is merged into deterministic export when **`organizationId`** is on the export request; **`POST /api/drift-check`** accepts **`organizationId`**, **`policyPackFiles`**, and **`skipArchPolicyPacks`** (membership required when **`organizationId`** is set).
+- **Library** — **`validateIrLint(ir, { policyRuleVisitors })`**; **`runDeterministicExport`** / drift helpers accept **`policyRuleVisitors`** the same way.
+- **Normalization** — **`NormalizedNode`** now includes **`metadata`** (from each node’s `metadata` object) so **`buildParsedLintGraph`** / policy **`match.node.tags`** see **`metadata.tags`** on the graph.
+- **`--policies`** applies to all three lint commands consistently — 
+  `validate-drift` uses the same policy layer when building the 
+  reference export, so org rules are enforced end-to-end across 
+  validate → export → drift.
+
 ## [0.1.3] - 2026-04-04
 
 ### Fixed

package/README.md

@@ -133,6 +133,8 @@ 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
+# Declarative PolicyPack YAML/JSON in a directory (after IR-LINT-*; skipped with --skip-lint):
+archrad validate --ir ./graph.json --policies ./policy-packs
 ```
 
 **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.

package/dist/cli.js

@@ -10,6 +10,7 @@ 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 { loadPolicyPacksFromDirectory } from './policy-pack.js';
 import { printFindingsPretty, shouldFailFromFindings, sortFindings, } from './cli-findings.js';
 import { parseYamlToCanonicalIr, canonicalIrToJsonString, YamlGraphParseError, } from './yamlToIr.js';
 import { openApiStringToCanonicalIr, OpenApiIngestError } from './openapi-to-ir.js';
@@ -51,6 +52,20 @@ function parseMaxWarnings(v) {
     const n = parseInt(v, 10);
     return Number.isFinite(n) ? n : undefined;
 }
+/** Load `--policies` directory; on failure prints to stderr and returns null (caller should exit 1). */
+async function loadPoliciesOption(policiesDir) {
+    if (policiesDir == null || policiesDir === '')
+        return {};
+    const dir = resolve(policiesDir);
+    const loaded = await loadPolicyPacksFromDirectory(dir);
+    if (!loaded.ok) {
+        for (const e of loaded.errors) {
+            console.error(`archrad: ${e}`);
+        }
+        return null;
+    }
+    return { policyRuleVisitors: loaded.visitors };
+}
 function exitPolicyFromOpts(opts) {
     return {
         failOnWarning: Boolean(opts.failOnWarning),
@@ -61,13 +76,14 @@ 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');
+    .version('0.1.4');
 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('--policies <dir>', 'Directory of PolicyPack YAML/JSON (*.yaml, *.yml, *.json); merged after IR-LINT-*')
     .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) => {
@@ -78,8 +94,19 @@ program
         return;
     }
     const noLint = Boolean(cmdOpts.skipLint);
+    let lintOpts = {};
+    if (!noLint && cmdOpts.policies) {
+        const loaded = await loadPoliciesOption(cmdOpts.policies);
+        if (loaded == null) {
+            process.exitCode = 1;
+            return;
+        }
+        lintOpts = loaded;
+    }
     const structural = validateIrStructural(ir);
-    const lint = noLint || hasIrStructuralErrors(structural) ? [] : validateIrLint(ir);
+    const lint = noLint || hasIrStructuralErrors(structural)
+        ? []
+        : validateIrLint(ir, lintOpts);
     const combined = sortFindings([...structural, ...lint]);
     if (cmdOpts.json) {
         const forJson = combined.map((f) => ({
@@ -224,11 +251,21 @@ program
     }
     const exportOpts = cmdOpts;
     const skipStruct = Boolean(exportOpts.dangerSkipIrStructuralValidation || exportOpts.skipIrStructuralValidation);
+    let exportLintOpts = {};
+    if (!cmdOpts.skipIrLint && cmdOpts.policies) {
+        const loaded = await loadPoliciesOption(cmdOpts.policies);
+        if (loaded == null) {
+            process.exitCode = 1;
+            return;
+        }
+        exportLintOpts = loaded;
+    }
     try {
         const { files, openApiStructuralWarnings, irStructuralFindings, irLintFindings } = await runDeterministicExport(actualIR, cmdOpts.target, {
             hostPort,
             skipIrStructuralValidation: skipStruct,
             skipIrLint: cmdOpts.skipIrLint,
+            ...exportLintOpts,
         });
         const combined = sortFindings([...irStructuralFindings, ...irLintFindings]);
         if (combined.length) {
@@ -277,6 +314,7 @@ program
     .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('--policies <dir>', 'Directory of PolicyPack YAML/JSON; merged after IR-LINT-* for the 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) => {
@@ -297,12 +335,22 @@ program
         }
     }
     const skipStruct = Boolean(cmdOpts.dangerSkipIrStructuralValidation || cmdOpts.skipIrStructuralValidation);
+    let driftLintOpts = {};
+    if (!cmdOpts.skipIrLint && cmdOpts.policies) {
+        const loaded = await loadPoliciesOption(cmdOpts.policies);
+        if (loaded == null) {
+            process.exitCode = 1;
+            return;
+        }
+        driftLintOpts = loaded;
+    }
     try {
         const result = await runValidateDrift(actualIR, cmdOpts.target, outDir, {
             hostPort,
             skipIrStructuralValidation: skipStruct,
             skipIrLint: cmdOpts.skipIrLint,
             strictExtra: cmdOpts.strictExtra,
+            ...driftLintOpts,
         });
         const combined = sortFindings([
             ...result.exportResult.irStructuralFindings,

package/dist/exportPipeline.d.ts

@@ -3,6 +3,7 @@
  * Used by the ArchRad server and the `archrad` CLI.
  */
 import { type IrStructuralFinding } from './ir-structural.js';
+import { type ValidateIrLintOptions } from './ir-lint.js';
 export type DeterministicExportResult = {
     files: Record<string, string>;
     /** Human-readable lines when generated OpenAPI fails **document-shape** checks (not full spec lint) */
@@ -13,11 +14,11 @@ export type DeterministicExportResult = {
      * 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`). */
+    /** IR-LINT-* plus optional declarative policy-pack findings; 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>;
+export declare function runDeterministicExport(actualIR: any, target: string, opts?: Record<string, any> & ValidateIrLintOptions): Promise<DeterministicExportResult>;
 //# sourceMappingURL=exportPipeline.d.ts.map

package/dist/exportPipeline.d.ts.map

@@ -1 +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"}
+{"version":3,"file":"exportPipeline.d.ts","sourceRoot":"","sources":["../src/exportPipeline.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAOH,OAAO,EAGL,KAAK,mBAAmB,EACzB,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAAkB,KAAK,qBAAqB,EAAE,MAAM,cAAc,CAAC;AAE1E,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,qIAAqI;IACrI,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,CAAC,GAAG,qBAA0B,GACrD,OAAO,CAAC,yBAAyB,CAAC,CAwDpC"}

package/dist/exportPipeline.js

@@ -21,7 +21,7 @@ export async function runDeterministicExport(actualIR, target, opts = {}) {
     }
     let irLintFindings = [];
     if (!skipLint) {
-        const lintPass = validateIrLint(actualIR);
+        const lintPass = validateIrLint(actualIR, { policyRuleVisitors: opts.policyRuleVisitors });
         if (skipIr) {
             // Dangerous mode: full structural pass is off, but parse/normalize failures still return IR-STRUCT-* from
             // validateIrLint — fold those into irStructuralFindings so InkByte / CLI consumers block and log like normal.

package/dist/index.d.ts

@@ -12,7 +12,8 @@ export { runDeterministicExport, type DeterministicExportResult } from './export
 export { diffExpectedExportAgainstFiles, diffExpectedExportAgainstDirectory, readDirectoryAsExportMap, runValidateDrift, runDriftCheckAgainstFiles, normalizeExportFileContent, type DriftFinding, type DriftCode, type ValidateDriftResult, type DriftCheckFilesResult, } from './validate-drift.js';
 export { normalizeIrGraph, validateIrStructural, hasIrStructuralErrors, detectCycles, type IrStructuralFinding, type IrStructuralSeverity, type IrFindingLayer, } from './ir-structural.js';
 export { materializeNormalizedGraph, normalizeNodeSlot, normalizeEdgeSlot, type NormalizedGraph, type NormalizedNode, type NormalizedEdge, type MaterializeResult, } from './ir-normalize.js';
-export { validateIrLint } from './ir-lint.js';
+export { validateIrLint, type ValidateIrLintOptions } from './ir-lint.js';
+export { loadPolicyPacksFromDirectory, loadPolicyPacksFromFiles, type LoadPolicyPacksResult, type PolicyPackFileSource, type PolicyPackDocumentV1, type PolicyRuleV1, type PolicyPackMetadataV1, type PolicyNodeSelectorV1, type PolicyEdgeMatchV1, type PolicySeverity, } from './policy-pack.js';
 export { runArchitectureLinting, LINT_RULE_REGISTRY } from './lint-rules.js';
 export { buildParsedLintGraph, isParsedLintGraph, type ParsedLintGraph, type BuildParsedLintGraphResult, } from './lint-graph.js';
 export { isHttpLikeType, isHttpEndpointType, isDbLikeType, isQueueLikeNodeType, isAuthLikeNodeType } from './graphPredicates.js';

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EACL,mBAAmB,EACnB,kBAAkB,EAClB,yBAAyB,EACzB,mBAAmB,EACnB,iCAAiC,GAClC,MAAM,yBAAyB,CAAC;AAEjC,OAAO,EACL,uBAAuB,EACvB,2BAA2B,EAC3B,mBAAmB,EACnB,yBAAyB,EACzB,uBAAuB,EACvB,KAAK,WAAW,EAChB,KAAK,kBAAkB,GACxB,MAAM,oBAAoB,CAAC;AAE5B,OAAO,EACL,wBAAwB,EACxB,uBAAuB,EACvB,mBAAmB,GACpB,MAAM,eAAe,CAAC;AAEvB,cAAc,8BAA8B,CAAC;AAE7C,OAAO,EAAE,OAAO,IAAI,0BAA0B,EAAE,MAAM,oBAAoB,CAAC;AAC3E,OAAO,EAAE,OAAO,IAAI,wBAAwB,EAAE,MAAM,kBAAkB,CAAC;AAEvE,OAAO,EAAE,sBAAsB,EAAE,KAAK,yBAAyB,EAAE,MAAM,qBAAqB,CAAC;AAE7F,OAAO,EACL,8BAA8B,EAC9B,kCAAkC,EAClC,wBAAwB,EACxB,gBAAgB,EAChB,yBAAyB,EACzB,0BAA0B,EAC1B,KAAK,YAAY,EACjB,KAAK,SAAS,EACd,KAAK,mBAAmB,EACxB,KAAK,qBAAqB,GAC3B,MAAM,qBAAqB,CAAC;AAE7B,OAAO,EACL,gBAAgB,EAChB,oBAAoB,EACpB,qBAAqB,EACrB,YAAY,EACZ,KAAK,mBAAmB,EACxB,KAAK,oBAAoB,EACzB,KAAK,cAAc,GACpB,MAAM,oBAAoB,CAAC;AAE5B,OAAO,EACL,0BAA0B,EAC1B,iBAAiB,EACjB,iBAAiB,EACjB,KAAK,eAAe,EACpB,KAAK,cAAc,EACnB,KAAK,cAAc,EACnB,KAAK,iBAAiB,GACvB,MAAM,mBAAmB,CAAC;AAE3B,OAAO,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAC9C,OAAO,EAAE,sBAAsB,EAAE,kBAAkB,EAAE,MAAM,iBAAiB,CAAC;AAC7E,OAAO,EACL,oBAAoB,EACpB,iBAAiB,EACjB,KAAK,eAAe,EACpB,KAAK,0BAA0B,GAChC,MAAM,iBAAiB,CAAC;AAEzB,OAAO,EAAE,cAAc,EAAE,kBAAkB,EAAE,YAAY,EAAE,mBAAmB,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAC;AAEjI,OAAO,EAAE,YAAY,EAAE,sBAAsB,EAAE,KAAK,oBAAoB,EAAE,MAAM,mBAAmB,CAAC;AAEpG,OAAO,EACL,sBAAsB,EACtB,uBAAuB,EACvB,mBAAmB,GACpB,MAAM,eAAe,CAAC;AAEvB,OAAO,EACL,0BAA0B,EAC1B,4BAA4B,EAC5B,0BAA0B,EAC1B,2BAA2B,EAC3B,kBAAkB,EAClB,KAAK,eAAe,GACrB,MAAM,oBAAoB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EACL,mBAAmB,EACnB,kBAAkB,EAClB,yBAAyB,EACzB,mBAAmB,EACnB,iCAAiC,GAClC,MAAM,yBAAyB,CAAC;AAEjC,OAAO,EACL,uBAAuB,EACvB,2BAA2B,EAC3B,mBAAmB,EACnB,yBAAyB,EACzB,uBAAuB,EACvB,KAAK,WAAW,EAChB,KAAK,kBAAkB,GACxB,MAAM,oBAAoB,CAAC;AAE5B,OAAO,EACL,wBAAwB,EACxB,uBAAuB,EACvB,mBAAmB,GACpB,MAAM,eAAe,CAAC;AAEvB,cAAc,8BAA8B,CAAC;AAE7C,OAAO,EAAE,OAAO,IAAI,0BAA0B,EAAE,MAAM,oBAAoB,CAAC;AAC3E,OAAO,EAAE,OAAO,IAAI,wBAAwB,EAAE,MAAM,kBAAkB,CAAC;AAEvE,OAAO,EAAE,sBAAsB,EAAE,KAAK,yBAAyB,EAAE,MAAM,qBAAqB,CAAC;AAE7F,OAAO,EACL,8BAA8B,EAC9B,kCAAkC,EAClC,wBAAwB,EACxB,gBAAgB,EAChB,yBAAyB,EACzB,0BAA0B,EAC1B,KAAK,YAAY,EACjB,KAAK,SAAS,EACd,KAAK,mBAAmB,EACxB,KAAK,qBAAqB,GAC3B,MAAM,qBAAqB,CAAC;AAE7B,OAAO,EACL,gBAAgB,EAChB,oBAAoB,EACpB,qBAAqB,EACrB,YAAY,EACZ,KAAK,mBAAmB,EACxB,KAAK,oBAAoB,EACzB,KAAK,cAAc,GACpB,MAAM,oBAAoB,CAAC;AAE5B,OAAO,EACL,0BAA0B,EAC1B,iBAAiB,EACjB,iBAAiB,EACjB,KAAK,eAAe,EACpB,KAAK,cAAc,EACnB,KAAK,cAAc,EACnB,KAAK,iBAAiB,GACvB,MAAM,mBAAmB,CAAC;AAE3B,OAAO,EAAE,cAAc,EAAE,KAAK,qBAAqB,EAAE,MAAM,cAAc,CAAC;AAE1E,OAAO,EACL,4BAA4B,EAC5B,wBAAwB,EACxB,KAAK,qBAAqB,EAC1B,KAAK,oBAAoB,EACzB,KAAK,oBAAoB,EACzB,KAAK,YAAY,EACjB,KAAK,oBAAoB,EACzB,KAAK,oBAAoB,EACzB,KAAK,iBAAiB,EACtB,KAAK,cAAc,GACpB,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EAAE,sBAAsB,EAAE,kBAAkB,EAAE,MAAM,iBAAiB,CAAC;AAC7E,OAAO,EACL,oBAAoB,EACpB,iBAAiB,EACjB,KAAK,eAAe,EACpB,KAAK,0BAA0B,GAChC,MAAM,iBAAiB,CAAC;AAEzB,OAAO,EAAE,cAAc,EAAE,kBAAkB,EAAE,YAAY,EAAE,mBAAmB,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAC;AAEjI,OAAO,EAAE,YAAY,EAAE,sBAAsB,EAAE,KAAK,oBAAoB,EAAE,MAAM,mBAAmB,CAAC;AAEpG,OAAO,EACL,sBAAsB,EACtB,uBAAuB,EACvB,mBAAmB,GACpB,MAAM,eAAe,CAAC;AAEvB,OAAO,EACL,0BAA0B,EAC1B,4BAA4B,EAC5B,0BAA0B,EAC1B,2BAA2B,EAC3B,kBAAkB,EAClB,KAAK,eAAe,GACrB,MAAM,oBAAoB,CAAC"}

package/dist/index.js

@@ -13,6 +13,7 @@ export { diffExpectedExportAgainstFiles, diffExpectedExportAgainstDirectory, rea
 export { normalizeIrGraph, validateIrStructural, hasIrStructuralErrors, detectCycles, } from './ir-structural.js';
 export { materializeNormalizedGraph, normalizeNodeSlot, normalizeEdgeSlot, } from './ir-normalize.js';
 export { validateIrLint } from './ir-lint.js';
+export { loadPolicyPacksFromDirectory, loadPolicyPacksFromFiles, } from './policy-pack.js';
 export { runArchitectureLinting, LINT_RULE_REGISTRY } from './lint-rules.js';
 export { buildParsedLintGraph, isParsedLintGraph, } from './lint-graph.js';
 export { isHttpLikeType, isHttpEndpointType, isDbLikeType, isQueueLikeNodeType, isAuthLikeNodeType } from './graphPredicates.js';

package/dist/ir-lint.d.ts

@@ -1,11 +1,16 @@
 /**
  * Architecture lint (IR-LINT-*): thin entry — parses graph then runs visitor registry in `lint-rules.ts`.
  */
+import type { ParsedLintGraph } from './lint-graph.js';
 import type { IrStructuralFinding } from './ir-structural.js';
+export type ValidateIrLintOptions = {
+    /** Extra visitors after built-in IR-LINT-* (declarative policy packs, org rules). */
+    policyRuleVisitors?: ReadonlyArray<(g: ParsedLintGraph) => IrStructuralFinding[]>;
+};
 /**
- * Run architecture lint (IR-LINT-*). If the IR cannot be parsed (invalid root, empty graph, etc.),
+ * Run architecture lint (IR-LINT-*) plus optional policy visitors. If the IR cannot be parsed (invalid root, empty graph, etc.),
  * returns the same **structural** findings as `normalizeIrGraph` / `validateIrStructural` would surface
  * for that shape — callers that only invoke `validateIrLint` still see blockers instead of a silent `[]`.
  */
-export declare function validateIrLint(ir: unknown): IrStructuralFinding[];
+export declare function validateIrLint(ir: unknown, options?: ValidateIrLintOptions): IrStructuralFinding[];
 //# sourceMappingURL=ir-lint.d.ts.map

package/dist/ir-lint.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ir-lint.d.ts","sourceRoot":"","sources":["../src/ir-lint.ts"],"names":[],"mappings":"AAAA;;GAEG;AAIH,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAC;AAE9D;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,EAAE,EAAE,OAAO,GAAG,mBAAmB,EAAE,CAIjE"}
+{"version":3,"file":"ir-lint.d.ts","sourceRoot":"","sources":["../src/ir-lint.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AAGvD,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAC;AAE9D,MAAM,MAAM,qBAAqB,GAAG;IAClC,qFAAqF;IACrF,kBAAkB,CAAC,EAAE,aAAa,CAAC,CAAC,CAAC,EAAE,eAAe,KAAK,mBAAmB,EAAE,CAAC,CAAC;CACnF,CAAC;AAEF;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,EAAE,EAAE,OAAO,EAAE,OAAO,CAAC,EAAE,qBAAqB,GAAG,mBAAmB,EAAE,CAMlG"}

package/dist/ir-lint.js

@@ -4,13 +4,15 @@
 import { buildParsedLintGraph, isParsedLintGraph } from './lint-graph.js';
 import { runArchitectureLinting } from './lint-rules.js';
 /**
- * Run architecture lint (IR-LINT-*). If the IR cannot be parsed (invalid root, empty graph, etc.),
+ * Run architecture lint (IR-LINT-*) plus optional policy visitors. If the IR cannot be parsed (invalid root, empty graph, etc.),
  * returns the same **structural** findings as `normalizeIrGraph` / `validateIrStructural` would surface
  * for that shape — callers that only invoke `validateIrLint` still see blockers instead of a silent `[]`.
  */
-export function validateIrLint(ir) {
+export function validateIrLint(ir, options) {
     const built = buildParsedLintGraph(ir);
     if (!isParsedLintGraph(built))
         return built.findings;
-    return runArchitectureLinting(built);
+    const base = runArchitectureLinting(built);
+    const extra = options?.policyRuleVisitors?.flatMap((v) => v(built)) ?? [];
+    return [...base, ...extra];
 }

package/dist/ir-normalize.d.ts

@@ -9,6 +9,8 @@ export type NormalizedNode = {
     name: string;
     config: Record<string, unknown>;
     schema: Record<string, unknown>;
+    /** Node-level metadata (e.g. `tags` for policy packs / lint). */
+    metadata: Record<string, unknown>;
 };
 export type NormalizedEdge = {
     id: string;

package/dist/ir-normalize.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ir-normalize.d.ts","sourceRoot":"","sources":["../src/ir-normalize.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,MAAM,MAAM,cAAc,GAAG;IAC3B,EAAE,EAAE,MAAM,CAAC;IACX,uCAAuC;IACvC,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAChC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACjC,CAAC;AAEF,MAAM,MAAM,cAAc,GAAG;IAC3B,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,EAAE,EAAE,MAAM,CAAC;IACX,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAChC,+EAA+E;IAC/E,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACnC,CAAC;AAEF,MAAM,MAAM,eAAe,GAAG;IAC5B,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAClC,KAAK,EAAE,cAAc,EAAE,CAAC;IACxB,KAAK,EAAE,cAAc,EAAE,CAAC;CACzB,CAAC;AAOF;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,OAAO,GAAG,cAAc,CAiB9D;AAED;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,OAAO,GAAG,cAAc,CAuB9D;AAED,MAAM,MAAM,iBAAiB,GAAG;IAC9B,UAAU,EAAE,eAAe,CAAC;IAC5B,sEAAsE;IACtE,sBAAsB,EAAE,OAAO,CAAC;CACjC,CAAC;AAEF;;;;;;;GAOG;AACH,wBAAgB,0BAA0B,CAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,iBAAiB,CAkB5F"}
+{"version":3,"file":"ir-normalize.d.ts","sourceRoot":"","sources":["../src/ir-normalize.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,MAAM,MAAM,cAAc,GAAG;IAC3B,EAAE,EAAE,MAAM,CAAC;IACX,uCAAuC;IACvC,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAChC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAChC,iEAAiE;IACjE,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACnC,CAAC;AAEF,MAAM,MAAM,cAAc,GAAG;IAC3B,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,EAAE,EAAE,MAAM,CAAC;IACX,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAChC,+EAA+E;IAC/E,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACnC,CAAC;AAEF,MAAM,MAAM,eAAe,GAAG;IAC5B,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAClC,KAAK,EAAE,cAAc,EAAE,CAAC;IACxB,KAAK,EAAE,cAAc,EAAE,CAAC;CACzB,CAAC;AAOF;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,OAAO,GAAG,cAAc,CAkB9D;AAED;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,OAAO,GAAG,cAAc,CAuB9D;AAED,MAAM,MAAM,iBAAiB,GAAG;IAC9B,UAAU,EAAE,eAAe,CAAC;IAC5B,sEAAsE;IACtE,sBAAsB,EAAE,OAAO,CAAC;CACjC,CAAC;AAEF;;;;;;;GAOG;AACH,wBAAgB,0BAA0B,CAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,iBAAiB,CAkB5F"}

package/dist/ir-normalize.js

@@ -12,7 +12,7 @@ function emptyRecord(obj) {
  */
 export function normalizeNodeSlot(raw) {
     if (raw == null || typeof raw !== 'object') {
-        return { id: '', type: '', name: '', config: {}, schema: {} };
+        return { id: '', type: '', name: '', config: {}, schema: {}, metadata: {} };
     }
     const r = raw;
     const id = String(r.id ?? '').trim();
@@ -26,6 +26,7 @@ export function normalizeNodeSlot(raw) {
         name,
         config: emptyRecord(r.config),
         schema: emptyRecord(r.schema),
+        metadata: emptyRecord(r.metadata),
     };
 }
 /**

package/dist/lint-graph.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"lint-graph.d.ts","sourceRoot":"","sources":["../src/lint-graph.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAC;AAK9D,6FAA6F;AAC7F,OAAO,EAAE,cAAc,EAAE,YAAY,EAAE,mBAAmB,EAAE,MAAM,sBAAsB,CAAC;AAEzF,MAAM,MAAM,eAAe,GAAG;IAC5B,QAAQ,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;IAC/C,KAAK,EAAE,OAAO,EAAE,CAAC;IACjB,GAAG,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,CAAC;IAC3B,SAAS,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC/B,+EAA+E;IAC/E,QAAQ,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAC/B,CAAC;AAEF,MAAM,MAAM,0BAA0B,GAAG,eAAe,GAAG;IAAE,QAAQ,EAAE,mBAAmB,EAAE,CAAA;CAAE,CAAC;AAE/F,wBAAgB,aAAa,CAAC,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,EAAE,EAAE,MAAM,CAAA;CAAE,CAItF;AAED,wBAAgB,QAAQ,CAAC,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAE3D;AAED,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAWvD;AAED;;;;;GAKG;AACH,wBAAgB,2BAA2B,CAAC,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,KAAK,CAAC,EAAE,eAAe,GAAG,OAAO,CAqBxG;AAED,2EAA2E;AAC3E,wBAAgB,yBAAyB,CAAC,CAAC,EAAE,eAAe,GAAG,GAAG,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,CAYnF;AAED;;;GAGG;AACH,wBAAgB,oBAAoB,CAAC,EAAE,EAAE,OAAO,GAAG,0BAA0B,CAqD5E;AAED,2DAA2D;AAC3D,wBAAgB,iBAAiB,CAAC,CAAC,EAAE,0BAA0B,GAAG,CAAC,IAAI,eAAe,CAErF"}
+{"version":3,"file":"lint-graph.d.ts","sourceRoot":"","sources":["../src/lint-graph.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAC;AAK9D,6FAA6F;AAC7F,OAAO,EAAE,cAAc,EAAE,YAAY,EAAE,mBAAmB,EAAE,MAAM,sBAAsB,CAAC;AAEzF,MAAM,MAAM,eAAe,GAAG;IAC5B,QAAQ,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;IAC/C,KAAK,EAAE,OAAO,EAAE,CAAC;IACjB,GAAG,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,CAAC;IAC3B,SAAS,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC/B,+EAA+E;IAC/E,QAAQ,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAC/B,CAAC;AAEF,MAAM,MAAM,0BAA0B,GAAG,eAAe,GAAG;IAAE,QAAQ,EAAE,mBAAmB,EAAE,CAAA;CAAE,CAAC;AAE/F,wBAAgB,aAAa,CAAC,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,EAAE,EAAE,MAAM,CAAA;CAAE,CAItF;AAED,wBAAgB,QAAQ,CAAC,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAE3D;AAED,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAWvD;AAED;;;;;GAKG;AACH,wBAAgB,2BAA2B,CAAC,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,KAAK,CAAC,EAAE,eAAe,GAAG,OAAO,CAqBxG;AAED,2EAA2E;AAC3E,wBAAgB,yBAAyB,CAAC,CAAC,EAAE,eAAe,GAAG,GAAG,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,CAYnF;AAED;;;GAGG;AACH,wBAAgB,oBAAoB,CAAC,EAAE,EAAE,OAAO,GAAG,0BAA0B,CAsD5E;AAED,2DAA2D;AAC3D,wBAAgB,iBAAiB,CAAC,CAAC,EAAE,0BAA0B,GAAG,CAAC,IAAI,eAAe,CAErF"}

package/dist/lint-graph.js

@@ -106,6 +106,7 @@ export function buildParsedLintGraph(ir) {
             name: n.name,
             config: n.config,
             schema: n.schema,
+            metadata: n.metadata,
         });
     }
     const edges = normalized.edges;

package/dist/policy-pack.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Declarative org policy packs (YAML/JSON) — deterministic graph matchers on ParsedLintGraph.
+ * Codes should use a stable prefix (e.g. ORG-*, ACME-*) to avoid colliding with IR-LINT-* / IR-STRUCT-*.
+ */
+import type { ParsedLintGraph } from './lint-graph.js';
+import type { IrStructuralFinding } from './ir-structural.js';
+export type PolicySeverity = 'error' | 'warning' | 'info';
+/** Single-node selector: all provided predicates must match (AND). */
+export type PolicyNodeSelectorV1 = {
+    id?: string;
+    type?: string | string[];
+    /** All listed tags must appear on `node.metadata.tags` (array of strings). */
+    tags?: string[];
+};
+export type PolicyEdgeMatchV1 = {
+    from: PolicyNodeSelectorV1;
+    to: PolicyNodeSelectorV1;
+};
+export type PolicyRuleV1 = {
+    id: string;
+    severity: PolicySeverity;
+    message: string;
+    fixHint?: string;
+    match: {
+        node?: PolicyNodeSelectorV1;
+        edge?: PolicyEdgeMatchV1;
+    };
+};
+export type PolicyPackMetadataV1 = {
+    name?: string;
+    org?: string;
+};
+export type PolicyPackDocumentV1 = {
+    apiVersion: 'archrad/v1';
+    kind: 'PolicyPack';
+    metadata?: PolicyPackMetadataV1;
+    rules: PolicyRuleV1[];
+};
+export type LoadPolicyPacksResult = {
+    ok: true;
+    visitors: ReadonlyArray<(g: ParsedLintGraph) => IrStructuralFinding[]>;
+    ruleCount: number;
+} | {
+    ok: false;
+    errors: string[];
+};
+export type PolicyPackFileSource = {
+    /** Virtual filename (must end with .yaml, .yml, or .json for parse rules). */
+    name: string;
+    content: string;
+};
+/**
+ * Load policy packs from in-memory file sources (same semantics as {@link loadPolicyPacksFromDirectory}).
+ * Use for ArchRad Cloud, tests, and API bodies — no filesystem required.
+ */
+export declare function loadPolicyPacksFromFiles(sources: ReadonlyArray<PolicyPackFileSource>): LoadPolicyPacksResult;
+/**
+ * Load and compile all policy YAML/JSON files in a directory into lint visitors.
+ * Filenames: `*.yaml`, `*.yml`, `*.json` (other files ignored).
+ */
+export declare function loadPolicyPacksFromDirectory(dir: string): Promise<LoadPolicyPacksResult>;
+//# sourceMappingURL=policy-pack.d.ts.map

package/dist/policy-pack.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"policy-pack.d.ts","sourceRoot":"","sources":["../src/policy-pack.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAKH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AAEvD,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAC;AAE9D,MAAM,MAAM,cAAc,GAAG,OAAO,GAAG,SAAS,GAAG,MAAM,CAAC;AAE1D,sEAAsE;AACtE,MAAM,MAAM,oBAAoB,GAAG;IACjC,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,IAAI,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC;IACzB,8EAA8E;IAC9E,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;CACjB,CAAC;AAEF,MAAM,MAAM,iBAAiB,GAAG;IAC9B,IAAI,EAAE,oBAAoB,CAAC;IAC3B,EAAE,EAAE,oBAAoB,CAAC;CAC1B,CAAC;AAEF,MAAM,MAAM,YAAY,GAAG;IACzB,EAAE,EAAE,MAAM,CAAC;IACX,QAAQ,EAAE,cAAc,CAAC;IACzB,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE;QACL,IAAI,CAAC,EAAE,oBAAoB,CAAC;QAC5B,IAAI,CAAC,EAAE,iBAAiB,CAAC;KAC1B,CAAC;CACH,CAAC;AAEF,MAAM,MAAM,oBAAoB,GAAG;IACjC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,GAAG,CAAC,EAAE,MAAM,CAAC;CACd,CAAC;AAEF,MAAM,MAAM,oBAAoB,GAAG;IACjC,UAAU,EAAE,YAAY,CAAC;IACzB,IAAI,EAAE,YAAY,CAAC;IACnB,QAAQ,CAAC,EAAE,oBAAoB,CAAC;IAChC,KAAK,EAAE,YAAY,EAAE,CAAC;CACvB,CAAC;AAEF,MAAM,MAAM,qBAAqB,GAC7B;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,QAAQ,EAAE,aAAa,CAAC,CAAC,CAAC,EAAE,eAAe,KAAK,mBAAmB,EAAE,CAAC,CAAC;IAAC,SAAS,EAAE,MAAM,CAAA;CAAE,GACvG;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,MAAM,EAAE,CAAA;CAAE,CAAC;AAgHpC,MAAM,MAAM,oBAAoB,GAAG;IACjC,8EAA8E;IAC9E,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;CACjB,CAAC;AAEF;;;GAGG;AACH,wBAAgB,wBAAwB,CAAC,OAAO,EAAE,aAAa,CAAC,oBAAoB,CAAC,GAAG,qBAAqB,CAkC5G;AA4BD;;;GAGG;AACH,wBAAsB,4BAA4B,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,qBAAqB,CAAC,CAmC9F"}

package/dist/policy-pack.js

@@ -0,0 +1,220 @@
+/**
+ * Declarative org policy packs (YAML/JSON) — deterministic graph matchers on ParsedLintGraph.
+ * Codes should use a stable prefix (e.g. ORG-*, ACME-*) to avoid colliding with IR-LINT-* / IR-STRUCT-*.
+ */
+import { readFile, readdir } from 'node:fs/promises';
+import { join, resolve } from 'node:path';
+import yaml from 'js-yaml';
+import { edgeEndpoints, nodeType } from './lint-graph.js';
+function isNonEmptyRecord(x) {
+    return x != null && typeof x === 'object' && !Array.isArray(x);
+}
+function normalizeTypes(t) {
+    if (t == null)
+        return null;
+    const arr = Array.isArray(t) ? t : [t];
+    return arr.map((s) => String(s).trim().toLowerCase()).filter(Boolean);
+}
+/** True if selector has at least one predicate (empty match-all forbidden for v1). */
+function selectorHasPredicate(sel) {
+    if (sel.id != null && String(sel.id).trim() !== '')
+        return true;
+    if (sel.type != null) {
+        const n = normalizeTypes(sel.type);
+        if (n && n.length > 0)
+            return true;
+    }
+    if (sel.tags != null && Array.isArray(sel.tags) && sel.tags.length > 0)
+        return true;
+    return false;
+}
+function nodeMatchesSelector(n, sel) {
+    if (sel.id != null && String(n.id ?? '') !== String(sel.id))
+        return false;
+    const types = normalizeTypes(sel.type);
+    if (types && types.length > 0) {
+        const nt = nodeType(n);
+        if (!types.includes(nt))
+            return false;
+    }
+    if (sel.tags != null && sel.tags.length > 0) {
+        const meta = n.metadata ?? {};
+        const raw = meta.tags;
+        if (!Array.isArray(raw))
+            return false;
+        const have = new Set(raw.map((x) => String(x).toLowerCase()));
+        for (const t of sel.tags) {
+            if (!have.has(String(t).toLowerCase()))
+                return false;
+        }
+    }
+    return true;
+}
+function compileRule(rule, source) {
+    if (!rule.id || typeof rule.id !== 'string' || !/^[A-Za-z0-9_.-]+$/.test(rule.id)) {
+        throw new Error(`[${source}] invalid rule.id`);
+    }
+    if (!['error', 'warning', 'info'].includes(rule.severity)) {
+        throw new Error(`[${source}] rule "${rule.id}": severity must be error | warning | info`);
+    }
+    if (!rule.message || typeof rule.message !== 'string') {
+        throw new Error(`[${source}] rule "${rule.id}": message is required`);
+    }
+    const hasNode = rule.match?.node != null;
+    const hasEdge = rule.match?.edge != null;
+    if (hasNode === hasEdge) {
+        throw new Error(`[${source}] rule "${rule.id}": specify exactly one of match.node or match.edge`);
+    }
+    if (hasNode) {
+        const sel = rule.match.node;
+        if (!selectorHasPredicate(sel)) {
+            throw new Error(`[${source}] rule "${rule.id}": match.node must include id, type, and/or tags`);
+        }
+        return (g) => {
+            const findings = [];
+            for (const [id, n] of g.nodeById) {
+                if (nodeMatchesSelector(n, sel)) {
+                    findings.push({
+                        code: rule.id,
+                        severity: rule.severity,
+                        message: rule.message,
+                        nodeId: id,
+                        layer: 'lint',
+                        fixHint: rule.fixHint,
+                    });
+                }
+            }
+            return findings;
+        };
+    }
+    const edge = rule.match.edge;
+    if (!selectorHasPredicate(edge.from) || !selectorHasPredicate(edge.to)) {
+        throw new Error(`[${source}] rule "${rule.id}": match.edge.from and match.edge.to must each include id, type, and/or tags`);
+    }
+    return (g) => {
+        const findings = [];
+        for (let edgeIndex = 0; edgeIndex < g.edges.length; edgeIndex++) {
+            const e = g.edges[edgeIndex];
+            if (!e || typeof e !== 'object')
+                continue;
+            const { from, to } = edgeEndpoints(e);
+            if (!from || !to)
+                continue;
+            const a = g.nodeById.get(from);
+            const b = g.nodeById.get(to);
+            if (!a || !b)
+                continue;
+            if (nodeMatchesSelector(a, edge.from) && nodeMatchesSelector(b, edge.to)) {
+                findings.push({
+                    code: rule.id,
+                    severity: rule.severity,
+                    message: rule.message,
+                    nodeId: to,
+                    edgeIndex,
+                    layer: 'lint',
+                    fixHint: rule.fixHint,
+                });
+            }
+        }
+        return findings;
+    };
+}
+/**
+ * Load policy packs from in-memory file sources (same semantics as {@link loadPolicyPacksFromDirectory}).
+ * Use for ArchRad Cloud, tests, and API bodies — no filesystem required.
+ */
+export function loadPolicyPacksFromFiles(sources) {
+    const errors = [];
+    const visitors = [];
+    const seenIds = new Set();
+    let ruleCount = 0;
+    const sorted = [...sources].sort((a, b) => a.name.localeCompare(b.name));
+    if (sorted.length === 0) {
+        return { ok: false, errors: ['no policy sources provided'] };
+    }
+    for (const src of sorted) {
+        const name = src.name?.trim() || 'unnamed';
+        try {
+            const doc = parseDocument(src.content, name);
+            for (const rule of doc.rules) {
+                if (seenIds.has(rule.id)) {
+                    errors.push(`duplicate rule id "${rule.id}" (file ${name})`);
+                    continue;
+                }
+                seenIds.add(rule.id);
+                visitors.push(compileRule(rule, name));
+                ruleCount += 1;
+            }
+        }
+        catch (e) {
+            errors.push(`${name}: ${e instanceof Error ? e.message : String(e)}`);
+        }
+    }
+    if (errors.length > 0) {
+        return { ok: false, errors };
+    }
+    return { ok: true, visitors, ruleCount };
+}
+function parseDocument(text, filename) {
+    const ext = filename.toLowerCase();
+    let data;
+    if (ext.endsWith('.json')) {
+        data = JSON.parse(text);
+    }
+    else if (ext.endsWith('.yaml') || ext.endsWith('.yml')) {
+        data = yaml.load(text);
+    }
+    else {
+        throw new Error(`unsupported policy file extension: ${filename}`);
+    }
+    if (!isNonEmptyRecord(data)) {
+        throw new Error('policy document must be a JSON object');
+    }
+    const doc = data;
+    if (doc.apiVersion !== 'archrad/v1') {
+        throw new Error(`apiVersion must be "archrad/v1" (got ${String(doc.apiVersion)})`);
+    }
+    if (doc.kind !== 'PolicyPack') {
+        throw new Error(`kind must be PolicyPack (got ${String(doc.kind)})`);
+    }
+    if (!Array.isArray(doc.rules) || doc.rules.length === 0) {
+        throw new Error('rules must be a non-empty array');
+    }
+    return doc;
+}
+/**
+ * Load and compile all policy YAML/JSON files in a directory into lint visitors.
+ * Filenames: `*.yaml`, `*.yml`, `*.json` (other files ignored).
+ */
+export async function loadPolicyPacksFromDirectory(dir) {
+    const root = resolve(dir);
+    const errors = [];
+    let names;
+    try {
+        names = await readdir(root);
+    }
+    catch (e) {
+        const err = e;
+        return { ok: false, errors: [`cannot read policies directory ${root}: ${err.message}`] };
+    }
+    const policyFiles = names.filter((n) => /\.(yaml|yml|json)$/i.test(n)).sort();
+    if (policyFiles.length === 0) {
+        return { ok: false, errors: [`no policy files (*.yaml, *.yml, *.json) in ${root}`] };
+    }
+    const sources = [];
+    for (const name of policyFiles) {
+        const full = join(root, name);
+        try {
+            const text = await readFile(full, 'utf8');
+            sources.push({ name, content: text });
+        }
+        catch (e) {
+            const err = e;
+            errors.push(`${full}: ${err.message}`);
+        }
+    }
+    if (errors.length > 0) {
+        return { ok: false, errors };
+    }
+    return loadPolicyPacksFromFiles(sources);
+}

package/dist/validate-drift.d.ts

@@ -3,6 +3,7 @@
  * or to an in-memory file map (Cloud API). No semantic IR↔code analysis — regen vs reality.
  */
 import { type DeterministicExportResult } from './exportPipeline.js';
+import type { ValidateIrLintOptions } from './ir-lint.js';
 export type DriftCode = 'DRIFT-MISSING' | 'DRIFT-MODIFIED' | 'DRIFT-EXTRA' | 'DRIFT-NO-EXPORT';
 export type DriftFinding = {
     code: DriftCode;
@@ -35,6 +36,7 @@ export declare function runValidateDrift(actualIR: any, target: string, outDir:
     skipIrStructuralValidation?: boolean;
     skipIrLint?: boolean;
     strictExtra?: boolean;
+    policyRuleVisitors?: ValidateIrLintOptions['policyRuleVisitors'];
 }): Promise<ValidateDriftResult>;
 export type DriftCheckFilesResult = {
     ok: boolean;
@@ -50,5 +52,6 @@ export declare function runDriftCheckAgainstFiles(actualIR: any, target: string,
     skipIrStructuralValidation?: boolean;
     skipIrLint?: boolean;
     strictExtra?: boolean;
+    policyRuleVisitors?: ValidateIrLintOptions['policyRuleVisitors'];
 }): Promise<DriftCheckFilesResult>;
 //# sourceMappingURL=validate-drift.d.ts.map

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

@@ -1 +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"}
+{"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;AAC7F,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,cAAc,CAAC;AAG1D,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;IACtB,kBAAkB,CAAC,EAAE,qBAAqB,CAAC,oBAAoB,CAAC,CAAC;CAC7D,GACL,OAAO,CAAC,mBAAmB,CAAC,CA0C9B;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;IACtB,kBAAkB,CAAC,EAAE,qBAAqB,CAAC,oBAAoB,CAAC,CAAC;CAC7D,GACL,OAAO,CAAC,qBAAqB,CAAC,CAiChC"}

package/dist/validate-drift.js

@@ -118,6 +118,7 @@ export async function runValidateDrift(actualIR, target, outDir, opts = {}) {
         hostPort,
         skipIrStructuralValidation: Boolean(opts.skipIrStructuralValidation),
         skipIrLint: Boolean(opts.skipIrLint),
+        policyRuleVisitors: opts.policyRuleVisitors,
     });
     const { files } = exportResult;
     if (Object.keys(files).length === 0) {
@@ -157,6 +158,7 @@ export async function runDriftCheckAgainstFiles(actualIR, target, actualFiles, o
         hostPort,
         skipIrStructuralValidation: Boolean(opts.skipIrStructuralValidation),
         skipIrLint: Boolean(opts.skipIrLint),
+        policyRuleVisitors: opts.policyRuleVisitors,
     });
     const { files } = exportResult;
     if (Object.keys(files).length === 0) {

package/fixtures/policies/ecommerce-demo.yaml

@@ -0,0 +1,15 @@
+# Demo pack for validate + --policies: matches checkout-api → orders-db in ecommerce-with-warnings.json
+apiVersion: archrad/v1
+kind: PolicyPack
+metadata:
+  name: ecommerce-demo
+rules:
+  - id: ORG-DIRECT-HTTP-DATASTORE-001
+    severity: warning
+    message: Policy pack demo — direct HTTP to datastore edge (for Show HN / CI smoke)
+    match:
+      edge:
+        from:
+          type: http
+        to:
+          type: postgres

package/fixtures/policy-packs/duplicate-pack/first.yaml

@@ -0,0 +1,10 @@
+apiVersion: archrad/v1
+kind: PolicyPack
+rules:
+  - id: DUP-RULE-001
+    severity: warning
+    message: first
+    match:
+      node:
+        type: http
+        tags: [a]

package/fixtures/policy-packs/duplicate-pack/second.yaml

@@ -0,0 +1,10 @@
+apiVersion: archrad/v1
+kind: PolicyPack
+rules:
+  - id: DUP-RULE-001
+    severity: warning
+    message: second duplicate
+    match:
+      node:
+        type: database
+        tags: [b]

package/fixtures/policy-packs/sample-only/sample-node-tags.yaml

@@ -0,0 +1,14 @@
+# Flags HTTP nodes tagged deprecated (forbidden pattern — selector matches the violation)
+apiVersion: archrad/v1
+kind: PolicyPack
+metadata:
+  name: sample-node-tags
+rules:
+  - id: ORG-HTTP-DEPRECATED-001
+    severity: warning
+    message: Deprecated HTTP routes must not remain in the graph
+    fixHint: Remove the deprecated tag or replace the node
+    match:
+      node:
+        type: http
+        tags: [deprecated]

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@archrad/deterministic",
-  "version": "0.1.3",
+  "version": "0.1.4",
   "description": "A deterministic compiler and linter for system architecture. Validate your architecture before you write code. OSS: structural validation + basic architecture lint (rule-based); FastAPI/Express export; OpenAPI document-shape; golden Docker/Makefile — no LLM.",
   "keywords": [
     "archrad",