arkgate 4.8.23 → 4.8.25

package/bin/lib/rules-inventory.mjs

@@ -9,6 +9,11 @@
  */
 
 import { DOMAIN_EVENTS_PUSH_RE, DOMAIN_INVARIANT_WORD_RE, expectedDomainInvariantWordsPhrase, isIdiomaticEventsReset, } from './arkrules-sensors.mjs';
+/** Baseline key belongs to the ArkRules plane (structure sensors or invariants). */
+export function isArkRulesFrozenKey(key) {
+    const ruleId = key.split('|', 1)[0] ?? '';
+    return ruleId.startsWith('ARKRULE_') || ruleId.startsWith('INVARIANT_');
+}
 function lineOf(content, index) {
     return content.slice(0, index).split('\n').length;
 }
@@ -274,13 +279,27 @@ export function buildRulesInventory(input) {
         a.line - b.line ||
         a.kind.localeCompare(b.kind) ||
         a.id.localeCompare(b.id));
-    const underContract = candidates.filter((c) => (c.suggestedArkRule?.invariantId && contracted.has(c.suggestedArkRule.invariantId)) ||
-        (c.suggestedArkRule?.structureId && contracted.has(c.suggestedArkRule.structureId))).length;
+    const contractedSensors = new Set((input.contractedStructure ?? []).map((rule) => `${rule.layer}\u0000${rule.sensor}`));
+    const underContract = candidates.filter((c) => {
+        const suggestion = c.suggestedArkRule;
+        if (!suggestion)
+            return false;
+        if (suggestion.invariantId && contracted.has(suggestion.invariantId))
+            return true;
+        if (!suggestion.structureId)
+            return false;
+        // Structure suggestions: the sensor on that layer is what enforces, not the id string.
+        if (suggestion.sensor &&
+            contractedSensors.has(`${suggestion.layer}\u0000${suggestion.sensor}`)) {
+            return true;
+        }
+        return contracted.has(suggestion.structureId);
+    }).length;
     return {
         candidates,
         inventoried: candidates.length,
         underContract,
-        frozen: (input.frozenKeys ?? []).length,
+        frozen: (input.frozenKeys ?? []).filter(isArkRulesFrozenKey).length,
         notAScore: true,
     };
 }

package/bin/lib/rules-under-contract.mjs

@@ -4,21 +4,25 @@
  * Summary includes per-layer + structure/invariant detail so showcase HTML /ark-explain
  * can teach what is under contract, not only aggregate numbers.
  */
+import fs from 'node:fs';
 import path from 'node:path';
 import { loadEffectiveArkRulesFromDisk } from './effective-contract-load.mjs';
+import { buildRulesInventory, inventoryToExtractionCard } from './rules-inventory.mjs';
+import { collectGovernedFiles } from './scan-files.mjs';
+import { readBaseline } from './violations.mjs';
 import { evaluateInvariantCoverage, formatCoverageDiscards } from './invariant-coverage.mjs';
 import {
   coverageOptionsFromConfig,
   invariantIdsFromCatalog,
   loadInvariantCoverageInputs,
 } from './invariant-coverage-io.mjs';
+import { formatProbeStatusLines, probeStatusSection } from './invariant-probe-io.mjs';
 import {
-  EXTRA_MERGE_TEETH_GOVERNED_FLOOR,
   composeMergePlanesHonesty,
   demoteExtraPlaneTeethUnderClassificationFloor,
 } from './extra-merge-teeth.mjs';
 import { collectEmptyInvariantCatalogFindings } from './arkrules-sensors.mjs';
-import { layerForRelativePath } from '../ark-layer-match.mjs';
+import { layerForFile, layerForRelativePath } from '../ark-layer-match.mjs';
 import {
   ARKRULES_EMPTY_CATALOG_NEXT,
   ARKRULES_FIRST_CONTACT_NEXT,
@@ -35,8 +39,6 @@ const COVERED_SAMPLE_MAX = 24;
 const STRUCTURE_CATALOG_MAX = 40;
 const UNCOVERED_CATALOG_MAX = 30;
 
-export { EXTRA_MERGE_TEETH_GOVERNED_FLOOR };
-
 /** Doctor walk often hands absolute paths; layer globs are project-relative. */
 function projectRelativePath(root, filePath) {
   const posix = String(filePath).replace(/\\/g, '/');
@@ -96,9 +98,80 @@ function arkOrderMergeInput(config, residualCount = 0) {
   };
 }
 
-export function summarizeRulesUnderContract(root, config, facts, classification) {
+function rulesBySlice(arkRules) {
+  const groups = new Map();
+  const rows = [...(arkRules?.structure ?? []), ...(arkRules?.invariants ?? [])];
+  for (const entry of rows) {
+    const childId = entry?.provenance?.childId;
+    const sourceFile = entry?.provenance?.sourceFile;
+    if (typeof childId !== 'string' || typeof sourceFile !== 'string') continue;
+    const key = `${childId}\0${sourceFile}`;
+    let group = groups.get(key);
+    if (!group) {
+      group = {
+        slice: childId,
+        layer: entry.provenance?.layer ?? null,
+        sourceFile,
+        ids: [],
+        appliesTo: [],
+      };
+      groups.set(key, group);
+    }
+    if (typeof entry.id === 'string' && !group.ids.includes(entry.id)) group.ids.push(entry.id);
+    for (const pattern of entry.appliesTo ?? []) {
+      if (typeof pattern === 'string' && !group.appliesTo.includes(pattern)) group.appliesTo.push(pattern);
+    }
+  }
+  return [...groups.values()]
+    .map((group) => ({
+      ...group,
+      ids: [...group.ids].sort(),
+      appliesTo: [...group.appliesTo].sort(),
+    }))
+    .sort((left, right) => left.slice.localeCompare(right.slice) || left.sourceFile.localeCompare(right.sourceFile));
+}
+
+/** ADR 0012 D2 drift: arkrules/*.json no arkRules entry references (advisory). */
+function unreferencedArkRulesFiles(loaded) {
+  const files = (loaded?.warnings ?? []).map((w) => w.path).filter(Boolean);
+  return files.length > 0 ? { unreferencedFiles: files } : {};
+}
+
+/**
+ * @param {{ rulesMigration?: boolean }} [options] rulesMigration:false skips the
+ *   migration counts (the inventory payload computes them itself).
+ */
+function governedPathsFromFacts(root, facts) {
+  const rows = facts?.files;
+  if (!Array.isArray(rows) || rows.length === 0) return undefined;
+  const base = String(root).replace(/\\/g, '/').replace(/\/+$/, '');
+  const prefix = `${base}/`;
+  const out = [];
+  for (const entry of rows) {
+    const raw = typeof entry === 'string' ? entry : entry?.path;
+    if (typeof raw !== 'string' || raw.length === 0) continue;
+    const norm = raw.replace(/\\/g, '/');
+    const rel = norm.startsWith(prefix)
+      ? norm.slice(prefix.length)
+      : norm.replace(/^\.\//, '');
+    if (!rel || rel.startsWith('..') || rel.startsWith('/')) continue;
+    out.push(rel);
+  }
+  return out.length > 0 ? out : undefined;
+}
+
+export function summarizeRulesUnderContract(root, config, facts, classification, options = {}) {
+  const governedFiles = governedPathsFromFacts(root, facts);
+  const loadOpts = governedFiles ? { files: governedFiles } : {};
   if (!config?.arkRules || Object.keys(config.arkRules).length === 0) {
+    let drift = {};
+    try {
+      drift = unreferencedArkRulesFiles(loadEffectiveArkRulesFromDisk(root, config, loadOpts));
+    } catch {
+      drift = {};
+    }
     return {
+      ...drift,
       active: false,
       structureRules: 0,
       invariants: 0,
@@ -115,7 +188,7 @@ export function summarizeRulesUnderContract(root, config, facts, classification)
     };
   }
   try {
-    const loaded = loadEffectiveArkRulesFromDisk(root, config);
+    const loaded = loadEffectiveArkRulesFromDisk(root, config, loadOpts);
     if (loaded.errors?.length) {
       return {
         active: true,
@@ -146,6 +219,7 @@ export function summarizeRulesUnderContract(root, config, facts, classification)
     const covById = new Map(
       (coverage.coverage ?? []).map((row) => [row.invariantId, row])
     );
+    const probeSection = probeStatusSection(root, loaded.arkRules.invariants);
     const byLayer = loaded.arkRules.byLayer ?? {};
     const layers = Object.keys(byLayer)
       .sort((a, b) => a.localeCompare(b))
@@ -159,6 +233,7 @@ export function summarizeRulesUnderContract(root, config, facts, classification)
         return {
           name,
           sourceFile: part.sourceFile ?? null,
+          ...(Array.isArray(part.sourceFiles) ? { sourceFiles: [...part.sourceFiles] } : {}),
           structureRules: (part.structure ?? []).length,
           invariants: layerInvariants.length,
           coveredInvariants: covered,
@@ -191,7 +266,7 @@ export function summarizeRulesUnderContract(root, config, facts, classification)
 
     const symbolEvidence = (coverage.coverage ?? [])
       .filter((row) => typeof row.symbolEvidenceFile === 'string' && row.symbolEvidenceFile.length > 0)
-      .map((row) => ({ id: row.invariantId, file: row.symbolEvidenceFile }));
+      .map((row) => ({ id: row.invariantId, file: projectRelativePath(root, row.symbolEvidenceFile) }));
     const coveredAll = (coverage.coverage ?? [])
       .filter((row) => row.covered)
       .map((row) => ({
@@ -200,7 +275,7 @@ export function summarizeRulesUnderContract(root, config, facts, classification)
         mode: row.mode ?? null,
         description: row.description ?? null,
         ...(typeof row.symbolEvidenceFile === 'string' && row.symbolEvidenceFile.length > 0
-          ? { symbolEvidenceFile: row.symbolEvidenceFile }
+          ? { symbolEvidenceFile: projectRelativePath(root, row.symbolEvidenceFile) }
           : {}),
       }));
     const coveredTruncated = Math.max(0, coveredAll.length - COVERED_SAMPLE_MAX);
@@ -259,6 +334,7 @@ export function summarizeRulesUnderContract(root, config, facts, classification)
       partialCoverage: coverage.partial,
       testFilesScanned: coverageInputs.testFiles.length,
       layers,
+      ...(rulesBySlice(loaded.arkRules).length > 0 ? { bySlice: rulesBySlice(loaded.arkRules) } : {}),
       structure,
       structureTruncated,
       uncovered,
@@ -266,7 +342,17 @@ export function summarizeRulesUnderContract(root, config, facts, classification)
       coveredSample,
       coveredTruncated,
       symbolEvidence,
+      ...unreferencedArkRulesFiles(loaded),
+      // AR15: inventoried / under contract / frozen — same helper as --rules-inventory.
+      ...(options.rulesMigration === false
+        ? {}
+        : {
+            rulesMigration: buildRulesMigration({ root, config, arkRules: loaded.arkRules })
+              .rulesMigration,
+          }),
       ...(coverageInputs.stats ? { coverageStats: coverageInputs.stats } : {}),
+      // ADR 0039: only when a probe artifact exists — absence stays silent.
+      ...(probeSection ? { probe: probeSection } : {}),
       mergePlanes,
       notAScore: true,
       note: 'ArkRules plane (intra-layer) — counts and catalog, never a score. Green with uncovered residual must say so. Structure sensors are heuristics; invariants are catalog+coverage evidence, not a business runtime.',
@@ -306,6 +392,7 @@ export function formatArkRulesEvidenceLines(section) {
   }
   const discard = formatCoverageDiscards(section.coverageStats);
   if (discard) lines.push(`ArkRules:${discard}`);
+  lines.push(...formatProbeStatusLines(section.probe));
   return lines;
 }
 
@@ -314,9 +401,19 @@ export function formatArkRulesEvidenceLines(section) {
  * @param {ReturnType<typeof summarizeRulesUnderContract>|null|undefined} section
  * @returns {string[]}
  */
+function unreferencedFilesLine(section) {
+  const files = Array.isArray(section?.unreferencedFiles) ? section.unreferencedFiles : [];
+  if (files.length === 0) return [];
+  const shown = files.slice(0, 3).join(', ');
+  const more = files.length > 3 ? ` (+${files.length - 3} more)` : '';
+  return [
+    `ArkRules: ${shown}${more} not referenced by arkRules — nothing in it is enforced (ARKRULE_FILE_UNREFERENCED, advisory).`,
+  ];
+}
+
 export function formatArkRulesDoctorLines(section) {
   if (!section || typeof section !== 'object') return [];
-  if (section.active !== true) return [];
+  if (section.active !== true) return unreferencedFilesLine(section);
 
   if (Array.isArray(section.loadErrors) && section.loadErrors.length > 0) {
     const first = section.loadErrors[0];
@@ -362,6 +459,10 @@ export function formatArkRulesDoctorLines(section) {
     lines.push(`ArkRules: ${section.note}`);
   }
   lines.push(...formatArkRulesEvidenceLines(section));
+  if (section.rulesMigration) {
+    lines.push(`ArkRules migration: ${formatRulesMigrationCounts(section.rulesMigration)}.`);
+  }
+  lines.push(...unreferencedFilesLine(section));
   return lines;
 }
 
@@ -559,6 +660,11 @@ export function formatRulesUnderContractHtml(section, esc) {
     }
     ${uncoveredBlock}
     ${coveredBlock}
+    ${
+      section.rulesMigration
+        ? `<p class="muted" style="margin-top:.35rem;font-size:.84rem">Rules migration: ${escape(formatRulesMigrationCounts(section.rulesMigration))}</p>`
+        : ''
+    }
     ${
       formatArkRulesEvidenceLines(section)
         .map((line) => `<p class="muted" style="margin-top:.35rem;font-size:.84rem">${escape(line)}</p>`)
@@ -572,3 +678,135 @@ export function formatRulesUnderContractHtml(section, esc) {
     ${note}
   </section>`;
 }
+
+const RULES_INVENTORY_MAX_FILES = 400;
+
+/**
+ * Brownfield rules migration (AR13/AR15): one code path for `--rules-inventory`,
+ * MCP `ark_rules_inventory`, doctor, and the HTML report. Honest counts, never a score:
+ * - inventoried: candidates the heuristic inventory found (first 400 governed files);
+ * - underContract: candidates whose suggested ArkRule is declared — structure
+ *   suggestions by (layer, sensor), invariant suggestions by id;
+ * - frozen: ArkRules-plane keys (`ARKRULE_*` / `INVARIANT_*`) in .ark-baseline.json.
+ * @param {{ root: string, config: Record<string, any>, files?: string[], arkRules?: any }} input
+ *   `files` defaults to the governed walk; `arkRules` to the catalog on disk.
+ */
+function buildRulesMigration({ root, config, files, arkRules }) {
+  const governed = Array.isArray(files) ? files : collectGovernedFiles(root, config);
+  const fileContents = {};
+  const fileLayers = {};
+  for (const file of governed.slice(0, RULES_INVENTORY_MAX_FILES)) {
+    const absolute = path.isAbsolute(file) ? file : path.resolve(root, file);
+    const rel = path.relative(root, absolute).split(path.sep).join('/');
+    try {
+      fileContents[rel] = fs.readFileSync(absolute, 'utf8');
+      const layer = layerForFile(root, absolute, config.layers);
+      if (layer) fileLayers[rel] = layer;
+    } catch {
+      /* skip unreadable */
+    }
+  }
+  let catalog = arkRules;
+  if (catalog === undefined && config?.arkRules) {
+    try {
+      const loaded = loadEffectiveArkRulesFromDisk(root, config, {
+        files: governed.map((file) => {
+          const absolute = path.isAbsolute(file) ? file : path.resolve(root, file);
+          return path.relative(root, absolute).split(path.sep).join('/');
+        }),
+      });
+      catalog = loaded.errors.length > 0 ? null : loaded.arkRules;
+    } catch {
+      catalog = null; // the advisory inventory is still useful
+    }
+  }
+  const contractedRuleIds = [];
+  const contractedStructure = [];
+  for (const rule of catalog?.structure ?? []) {
+    contractedRuleIds.push(rule.id);
+    const layer = rule.provenance?.layer ?? rule.layer;
+    if (layer && rule.sensor) contractedStructure.push({ layer, sensor: rule.sensor });
+  }
+  for (const inv of catalog?.invariants ?? []) contractedRuleIds.push(inv.id);
+  let frozenKeys = [];
+  try {
+    frozenKeys = [...readBaseline(root, '.ark-baseline.json').keys];
+  } catch {
+    frozenKeys = []; // an unreadable baseline freezes nothing
+  }
+  const inventory = buildRulesInventory({
+    fileContents,
+    fileLayers,
+    layerContexts: (config.layers ?? []).map((layer) => ({
+      name: layer.name,
+      intentPrefixes: layer.intentPrefixes ?? [],
+    })),
+    contractedRuleIds,
+    contractedStructure,
+    frozenKeys,
+  });
+  return {
+    inventory,
+    rulesMigration: {
+      inventoried: inventory.inventoried,
+      underContract: inventory.underContract,
+      frozen: inventory.frozen,
+      notAScore: true,
+    },
+    nextPilot:
+      inventory.candidates[0] != null ? inventoryToExtractionCard(inventory.candidates[0]) : null,
+  };
+}
+
+/** `N inventoried, N under contract, N frozen (not a score)` — shared CLI/doctor wording. */
+export function formatRulesMigrationCounts(rulesMigration) {
+  if (!rulesMigration || typeof rulesMigration !== 'object') return '';
+  return `${rulesMigration.inventoried} inventoried, ${rulesMigration.underContract} under contract, ${rulesMigration.frozen} frozen (not a score)`;
+}
+
+/**
+ * Full `--rules-inventory` / `ark_rules_inventory` payload (same keys on both surfaces).
+ * @param {string} root
+ * @param {Record<string, any>} config
+ * @param {string[]} [files] governed files (absolute or root-relative)
+ */
+export function buildRulesInventoryPayload(root, config, files) {
+  const governed = Array.isArray(files) ? files : collectGovernedFiles(root, config);
+  const migration = buildRulesMigration({ root, config, files: governed });
+  let evidenceLines = [];
+  let coverageEvidence = null;
+  if (config?.arkRules && Object.keys(config.arkRules).length > 0) {
+    try {
+      const section = summarizeRulesUnderContract(
+        root,
+        config,
+        {
+          files: governed.map((file) => ({
+            path: path.relative(root, path.resolve(root, file)).split(path.sep).join('/'),
+          })),
+        },
+        undefined,
+        { rulesMigration: false }
+      );
+      evidenceLines = formatArkRulesEvidenceLines(section);
+      if (section.active === true) {
+        coverageEvidence = {
+          symbolEvidence: section.symbolEvidence ?? [],
+          discarded: section.coverageStats?.discarded ?? null,
+          ...(section.probe ? { probe: section.probe } : {}),
+        };
+      }
+    } catch {
+      /* inventory still useful when coverage cannot be read */
+    }
+  }
+  return {
+    payload: {
+      rulesInventory: migration.inventory,
+      rulesMigration: migration.rulesMigration,
+      nextPilot: migration.nextPilot,
+      ...(coverageEvidence ? { coverageEvidence } : {}),
+    },
+    evidenceLines,
+  };
+}

package/bin/lib/scan-files.mjs

@@ -8,12 +8,12 @@ import { isScanExcludedRelative, isSkippedSourceDir } from '../ark-shared.mjs';
 
 export { isSkippedSourceDir };
 
-export const SOURCE_FILE_NAME = /\.[cm]?[tj]sx?$/;
+const SOURCE_FILE_NAME = /\.[cm]?[tj]sx?$/;
 
 /** Unit/e2e test files are not architecture surface — agents and Nest put them next
  *  to production code (*.spec.ts). Counting them as ungoverned forces false
  *  CONFIG_UNCLASSIFIED_FILES under --strict-config on every starter. */
-export const TEST_FILE_NAME =
+const TEST_FILE_NAME =
   /(^test(?:[-_.]).*|\.(spec|test)(?:-d)?\.)(tsx?|jsx?|mjsx?|cjsx?|mts|cts)$/i;
 
 export function isGovernableSourceFile(name) {
@@ -32,6 +32,17 @@ function isInsideRoot(root, target) {
  * Internal symlink directories are followed once (TypeScript follows them too),
  * while escaping links fail closed instead of reading arbitrary filesystem paths.
  */
+/**
+ * Return `value` flattened. V8 keeps path.join / concatenation results as rope
+ * strings (a tree of segment objects); the per-file syscalls of the generic walk
+ * branch flattened them as a side effect. Without it, every retained path kept its
+ * rope alive and a 20k-file walk peaked ~70 MB higher. ToNumber flattens in place.
+ */
+function flatString(value) {
+  void Number(value);
+  return value;
+}
+
 export function walk(dir, files = [], options = {}) {
   let state = options.state;
   if (!state) {
@@ -67,6 +78,7 @@ export function walk(dir, files = [], options = {}) {
       !state.visitedFiles.has(resolved)
     ) {
       state.visitedFiles.add(resolved);
+      state.onFile?.(dir, resolved);
       files.push(dir);
     }
     return files;
@@ -84,6 +96,25 @@ export function walk(dir, files = [], options = {}) {
     } else if (entry.isSymbolicLink()) {
       if (isSkippedSourceDir(entry.name)) continue;
       walk(full, files, { state });
+    } else if (entry.isFile()) {
+      // A regular (non-link) file inside an already-resolved directory: its real
+      // path is that directory's real path plus its name. Same result as the
+      // per-file lstat + realpath of the generic branch, without two syscalls
+      // and two Stats objects for every source file.
+      if (!isGovernableSourceFile(entry.name)) continue;
+      state.observeInput?.(path.resolve(full), 'lstat');
+      state.observeInput?.(path.resolve(full), 'realpath');
+      // `resolved` is already a normalized real path and an entry name has no
+      // separator, so plain concatenation equals path.join(resolved, name).
+      const real = flatString(
+        resolved.endsWith(path.sep)
+          ? `${resolved}${entry.name}`
+          : `${resolved}${path.sep}${entry.name}`
+      );
+      if (state.visitedFiles.has(real)) continue;
+      state.visitedFiles.add(real);
+      state.onFile?.(full, real);
+      files.push(flatString(full));
     } else if (isGovernableSourceFile(entry.name)) {
       walk(full, files, { state });
     }
@@ -92,7 +123,7 @@ export function walk(dir, files = [], options = {}) {
 }
 
 /** Walk include roots then drop codegen / config.exclude (universal scan filter). */
-export function isIncludeMatch(relativePath, include) {
+function isIncludeMatch(relativePath, include) {
   return (include ?? []).some((entry) => {
     const includeRoot = String(entry)
       .replace(/\\/g, '/')
@@ -138,6 +169,7 @@ export function collectGovernedFiles(root, config, options = {}) {
     visitedDirectories: new Set(),
     visitedFiles: new Set(),
     onDirectory: options.onDirectory,
+    onFile: options.onFile,
     observeInput: options.observeInput,
   };
   const raw = (config.include ?? []).flatMap((entry) =>
@@ -160,7 +192,7 @@ export function normalize(value) {
 export const UNGOVERNED_PROBE_CAP = 200;
 
 /** Tooling configs (vite.config.ts, eslint.config.js …) are not the product source a contract governs. */
-export const TOOLING_CONFIG_FILE_NAME = /\.config\.[cm]?[jt]sx?$/i;
+const TOOLING_CONFIG_FILE_NAME = /\.config\.[cm]?[jt]sx?$/i;
 
 /**
  * Count governable source files under `root` that the contract's own scope cannot hide.

package/bin/lib/schema-validation.mjs

@@ -0,0 +1,130 @@
+/**
+ * GENERATED FILE — do not edit by hand.
+ *
+ * Canonical algorithm: src/domain/schemaValidation.ts
+ * Regenerate: node scripts/generate-cli-pure.mjs
+ * Drift check: node scripts/generate-cli-pure.mjs --check
+ *
+ * Pure CLI helper (bin/lib/schema-validation.mjs). Zero Node I/O.
+ */
+
+export function isObject(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+export function propertyPath(parent, key) {
+    return /^[A-Za-z_$][A-Za-z0-9_$]*$/.test(key)
+        ? `${parent}.${key}`
+        : `${parent}[${JSON.stringify(key)}]`;
+}
+export function valueType(value) {
+    if (value === null)
+        return 'null';
+    if (Array.isArray(value))
+        return 'array';
+    return typeof value;
+}
+function resolveSchemaRef(ref, root) {
+    const prefix = '#/$defs/';
+    if (!ref.startsWith(prefix))
+        return undefined;
+    return root.$defs[ref.slice(prefix.length)];
+}
+/** Walk `value` against `schema`, appending every finding to `issues`. */
+export function validateSchemaNode(value, schema, path, root, issues) {
+    if (schema.$ref) {
+        const referenced = resolveSchemaRef(schema.$ref, root);
+        if (!referenced) {
+            issues.push({ path, message: `schema reference ${schema.$ref} cannot be resolved` });
+            return;
+        }
+        validateSchemaNode(value, referenced, path, root, issues);
+        return;
+    }
+    if (schema.const !== undefined && !Object.is(value, schema.const)) {
+        issues.push({ path, message: `must equal ${JSON.stringify(schema.const)}` });
+        return;
+    }
+    if (schema.enum && !schema.enum.some((candidate) => Object.is(candidate, value))) {
+        issues.push({ path, message: `must be one of ${schema.enum.map(String).join(', ')}` });
+        return;
+    }
+    if (schema.type === 'object') {
+        if (!isObject(value)) {
+            issues.push({ path, message: `must be an object; received ${valueType(value)}` });
+            return;
+        }
+        const properties = schema.properties ?? {};
+        for (const key of schema.required ?? []) {
+            if (value[key] === undefined) {
+                issues.push({ path: propertyPath(path, key), message: 'is required' });
+            }
+        }
+        if (schema.additionalProperties === false) {
+            for (const key of Object.keys(value)) {
+                if (!(key in properties)) {
+                    issues.push({ path: propertyPath(path, key), message: 'unknown field' });
+                }
+            }
+        }
+        else if (schema.additionalProperties !== undefined &&
+            schema.additionalProperties !== true &&
+            typeof schema.additionalProperties === 'object') {
+            const additional = schema.additionalProperties;
+            for (const key of Object.keys(value)) {
+                if (!(key in properties)) {
+                    validateSchemaNode(value[key], additional, propertyPath(path, key), root, issues);
+                }
+            }
+        }
+        for (const [key, childSchema] of Object.entries(properties)) {
+            if (value[key] !== undefined) {
+                validateSchemaNode(value[key], childSchema, propertyPath(path, key), root, issues);
+            }
+        }
+        return;
+    }
+    if (schema.type === 'array') {
+        if (!Array.isArray(value)) {
+            issues.push({ path, message: `must be an array; received ${valueType(value)}` });
+            return;
+        }
+        if (schema.minItems !== undefined && value.length < schema.minItems) {
+            issues.push({ path, message: `must contain at least ${schema.minItems} item(s)` });
+        }
+        if (schema.uniqueItems) {
+            const serialized = value.map((entry) => JSON.stringify(entry));
+            if (new Set(serialized).size !== serialized.length) {
+                issues.push({ path, message: 'must not contain duplicate items' });
+            }
+        }
+        if (schema.items) {
+            value.forEach((entry, index) => validateSchemaNode(entry, schema.items, `${path}[${index}]`, root, issues));
+        }
+        return;
+    }
+    if (schema.type === 'string') {
+        if (typeof value !== 'string') {
+            issues.push({ path, message: `must be a string; received ${valueType(value)}` });
+            return;
+        }
+        if (schema.minLength !== undefined && value.length < schema.minLength) {
+            issues.push({ path, message: `must contain at least ${schema.minLength} character(s)` });
+        }
+        return;
+    }
+    if (schema.type === 'boolean') {
+        if (typeof value !== 'boolean') {
+            issues.push({ path, message: `must be a boolean; received ${valueType(value)}` });
+        }
+        return;
+    }
+    if (schema.type === 'integer') {
+        if (!Number.isInteger(value)) {
+            issues.push({ path, message: `must be an integer; received ${valueType(value)}` });
+            return;
+        }
+        if (schema.minimum !== undefined && value < schema.minimum) {
+            issues.push({ path, message: `must be at least ${schema.minimum}` });
+        }
+    }
+}

package/bin/lib/sensor-promote-cli.mjs

@@ -11,18 +11,9 @@ import path from 'node:path';
 
 import { arkCommand } from '../ark-shared.mjs';
 import { collectGovernedFiles, normalize } from './scan-files.mjs';
+// Same palette and TTY test as the entry's stderr output.
+import { color } from './violations.mjs';
 
-// Same shape and the same TTY test as the entry's own `color`: this module is
-// the only other writer to that terminal, and a second copy is cheaper than
-// exporting the entry's internals into a cycle.
-const useColor = process.stderr.isTTY && !process.env.NO_COLOR;
-const color = {
-  red: (s) => (useColor ? `\x1b[31m${s}\x1b[0m` : s),
-  yellow: (s) => (useColor ? `\x1b[33m${s}\x1b[0m` : s),
-  green: (s) => (useColor ? `\x1b[32m${s}\x1b[0m` : s),
-  dim: (s) => (useColor ? `\x1b[2m${s}\x1b[0m` : s),
-  bold: (s) => (useColor ? `\x1b[1m${s}\x1b[0m` : s),
-};
 
 /**
  * A rule id or a source path comes out of the project's own ArkRules JSON and