arkgate 4.8.23 → 4.8.24

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,8 +4,12 @@
  * 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,
@@ -18,7 +22,7 @@ import {
   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,
@@ -96,9 +100,26 @@ function arkOrderMergeInput(config, residualCount = 0) {
   };
 }
 
-export function summarizeRulesUnderContract(root, config, facts, classification) {
+/** 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).
+ */
+export function summarizeRulesUnderContract(root, config, facts, classification, options = {}) {
   if (!config?.arkRules || Object.keys(config.arkRules).length === 0) {
+    let drift = {};
+    try {
+      drift = unreferencedArkRulesFiles(loadEffectiveArkRulesFromDisk(root, config));
+    } catch {
+      drift = {};
+    }
     return {
+      ...drift,
       active: false,
       structureRules: 0,
       invariants: 0,
@@ -191,7 +212,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 +221,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);
@@ -266,6 +287,14 @@ 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 } : {}),
       mergePlanes,
       notAScore: true,
@@ -314,9 +343,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 +401,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 +602,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 +620,129 @@ export function formatRulesUnderContractHtml(section, esc) {
     ${note}
   </section>`;
 }
+
+export 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.
+ */
+export 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);
+      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,
+        };
+      }
+    } 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

@@ -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 });
     }
@@ -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) =>

package/bin/lib/snippet-analysis.mjs

@@ -2,16 +2,31 @@
 import { layerForRelativePath } from '../ark-layer-match.mjs';
 import { ANALYSIS_COMPLETENESS } from './analysis-completeness.mjs';
 import { evaluateArkRunEditorSensorsFromSource } from './ark-run-sensors.mjs';
+import { evaluateArkOrderEditorSensors } from './ark-order-sensors.mjs';
+import {
+  buildArkRuleFileHints,
+  evaluateArkRuleSensors,
+  extractClassShapesFromSource,
+} from './arkrules-sensors.mjs';
 import { getDiagnosticCatalogEntry } from './diagnostic-catalog.mjs';
+import { demoteExtraPlaneTeethUnderClassificationFloor } from './extra-merge-teeth.mjs';
 
-function lexicalEvidenceIncompleteMessage(file) {
+/** Hook-only guidance: a hook deny is already the verdict for that write. */
+export const HOOK_DENY_PREPARE_CHANGE_NOTE = 'Do not call ark_prepare_change from a hook deny.';
+
+function surfaceNote(context) {
+  return context?.surface === 'hook' ? ` ${HOOK_DENY_PREPARE_CHANGE_NOTE}` : '';
+}
+
+function lexicalEvidenceIncompleteMessage(file, context) {
   const entry = getDiagnosticCatalogEntry('LEXICAL_EVIDENCE_INCOMPLETE');
   const text = [entry?.why, entry?.fix].filter(Boolean).join(' ');
   return {
     code: 'LEXICAL_EVIDENCE_INCOMPLETE',
     message:
-      text ||
-      'This check only saw one file, so it cannot fully prove how the import resolves. The result is provisional — `ark-check` on the project is the authority. Run `npx arkgate-check --root . --config ark.config.json` to confirm. Do not call ark_prepare_change from a hook deny.',
+      (text ||
+        'This check only saw one file, so it cannot fully prove how the import resolves. The result is provisional — `ark-check` on the project is the authority. For a complete verdict, run `npx arkgate-check --root . --config ark.config.json` (or ark_prepare_change over MCP with the full candidate batch).') +
+      surfaceNote(context),
     ...(file ? { file } : {}),
   };
 }
@@ -81,14 +96,132 @@ function arkRunSnippetViolations(source, context = {}) {
     }));
 }
 
+const TS_CLASS_SHAPE_FILE = /\.(tsx?|mts|cts)$/i;
+
+/**
+ * File-local ArkRules structure sensors on the proposed source — the same sensors,
+ * class-shape extraction, and per-file hints ark-check runs, pinned to this one file.
+ * Only enforced (failsStrict) findings block; advisory rules stay CI/doctor warnings.
+ */
+function arkRulesSnippetViolations(source, context = {}) {
+  const arkRules = context.arkRules;
+  const file = context.relFile;
+  if (!arkRules || !(arkRules.structure?.length > 0) || typeof file !== 'string' || !file) {
+    return [];
+  }
+  const layers = Array.isArray(context.layers) ? context.layers : [];
+  const layerForFile = (pathValue) =>
+    pathValue === file && typeof context.layer === 'string'
+      ? context.layer
+      : layerForRelativePath(pathValue, layers);
+  let classShapes = [];
+  if (TS_CLASS_SHAPE_FILE.test(file)) {
+    try {
+      classShapes = extractClassShapesFromSource(file, source);
+    } catch {
+      // Same as the CI resolver: shape extraction never fails the run.
+      classShapes = [];
+    }
+  }
+  const findings = evaluateArkRuleSensors({
+    arkRules,
+    classShapes,
+    files: [file],
+    layerForFile,
+    fileHints: buildArkRuleFileHints({ [file]: source }),
+  });
+  // Same classification floor ark-check applies before merge (teeth only on a classified tree).
+  return demoteExtraPlaneTeethUnderClassificationFloor(findings, context.classification ?? {})
+    .filter((finding) => finding.failsStrict)
+    .map((finding) => ({
+      ...finding,
+      nextAction:
+        getDiagnosticCatalogEntry('ARKRULE_STRUCTURE')?.fix ??
+        'Fix the ArkRules structure finding in this file, then retry the write.',
+      failsStrict: true,
+      severity: 'error',
+    }));
+}
+
+/** ArkOrder editor sensors (generic update, kernel-in-domain, ξ writes) on one source. */
+function arkOrderSnippetViolations(source, context = {}) {
+  const arkOrder = context.arkOrder;
+  const file = context.relFile;
+  if (!arkOrder || typeof file !== 'string' || !file) return [];
+  const layers = Array.isArray(context.layers) ? context.layers : [];
+  const fromLayer =
+    typeof context.layer === 'string' ? context.layer : layerForRelativePath(file, layers);
+  const layerMeta = layers.find((layer) => layer?.name === fromLayer);
+  return evaluateArkOrderEditorSensors({
+    arkOrder,
+    file,
+    source,
+    fromLayer,
+    intentPrefixes: layerMeta?.intentPrefixes ?? [],
+    ...(context.classification ? { classification: context.classification } : {}),
+  })
+    .filter((finding) => finding.failsStrict)
+    .map((finding) => ({
+      ruleId: finding.ruleId,
+      code: finding.ruleId,
+      message: finding.message,
+      file: finding.file,
+      line: finding.line,
+      ...(finding.fromLayer ? { fromLayer: finding.fromLayer } : {}),
+      ...(finding.target ? { target: finding.target } : {}),
+      nextAction: finding.nextAction,
+      failsStrict: true,
+      severity: 'error',
+    }));
+}
+
+/**
+ * The write gate could not load part of its own contract (e.g. a referenced ArkRules
+ * file is missing). CI fails closed on the same input, so the write path does too.
+ */
+function contractLoadViolations(context = {}) {
+  const errors = Array.isArray(context.contractErrors) ? context.contractErrors : [];
+  return errors.map((error) => ({
+    ruleId: 'WRITE_GATE_UNAVAILABLE',
+    code: 'WRITE_GATE_UNAVAILABLE',
+    message: `Invalid Effective Contract: ${
+      typeof error === 'string' ? error : `${error?.path ?? ''}: ${error?.message ?? ''}`.trim()
+    }`,
+    ...(context.relFile ? { file: context.relFile } : {}),
+    nextAction:
+      getDiagnosticCatalogEntry('WRITE_GATE_UNAVAILABLE')?.fix ??
+      'Fix the ArkRules reference in ark.config.json, then retry the write.',
+    failsStrict: true,
+    severity: 'error',
+  }));
+}
+
+/**
+ * Extras (ArkRules structure + ArkOrder) run only on files CI would scan. A file
+ * outside include / excluded is never judged by these planes in CI either.
+ */
+function extraPlaneSnippetViolations(source, context = {}) {
+  if (context.inScope === false) return [];
+  return [
+    ...contractLoadViolations(context),
+    ...arkRulesSnippetViolations(source, context),
+    ...arkOrderSnippetViolations(source, context),
+  ];
+}
+
 export function validateSnippetAnalysis({ gate, ts, source, context = {} }) {
   const observed = gate.validate(source, context);
   const arkRunViolations = arkRunSnippetViolations(source, context);
+  const extraViolations = extraPlaneSnippetViolations(source, context);
   const base = {
-    valid: Boolean(observed.lexicalValid ?? observed.valid) && arkRunViolations.length === 0,
+    valid:
+      Boolean(observed.lexicalValid ?? observed.valid) &&
+      arkRunViolations.length === 0 &&
+      extraViolations.length === 0,
     violations: [
       ...(Array.isArray(observed.violations) ? observed.violations : []),
       ...arkRunViolations,
+      ...extraViolations,
     ],
   };
   const file = context.filePath;
@@ -154,7 +287,8 @@ export function validateSnippetAnalysis({ gate, ts, source, context = {} }) {
               'ANALYSIS_PARSE_INCOMPLETE',
               `Analysis partial: ${detail}`,
               file,
-              'Incremental mid-edit parse errors are normal. Finish the source, then re-run `npx arkgate-check` (or the write hook). Do not call ark_prepare_change from a hook deny.'
+              'Incremental mid-edit parse errors are normal. Finish the source, then re-run `npx arkgate-check` (or the write hook).' +
+                surfaceNote(context)
             ),
             line: first?.line ?? 1,
             column: first?.column ?? 1,
@@ -169,7 +303,7 @@ export function validateSnippetAnalysis({ gate, ts, source, context = {} }) {
       valid: false,
       lexicalValid: base.valid,
       completeness: ANALYSIS_COMPLETENESS.partial,
-      completenessReasons: [lexicalEvidenceIncompleteMessage(file)],
+      completenessReasons: [lexicalEvidenceIncompleteMessage(file, context)],
     };
   } catch {
     return {

package/bin/lib/source-policy.mjs

@@ -25,6 +25,40 @@ export const DEFAULT_INTENT_PREFIXES = Object.freeze([
     { layer: 'SecurityAuditObservability', prefixes: ['Security.', 'Audit.', 'Observability.'] },
     { layer: 'Kernel', prefixes: ['Kernel.'] },
 ]);
+/**
+ * Runtime intent prefixes for one config layer: its declared `intentPrefixes`,
+ * else the built-in prefixes when the layer uses a canonical 11-layer name
+ * (`DomainModel` → `Domain.`, …; the same table the static gate falls back to),
+ * else none. Keeps `ark init` configs, which name canonical layers without
+ * declaring prefixes, resolvable by the ArkRun kernel.
+ */
+export function effectiveIntentPrefixes(layer) {
+    const declared = (layer.intentPrefixes ?? []).filter((prefix) => prefix.trim().length > 0);
+    if (declared.length > 0)
+        return declared;
+    return DEFAULT_INTENT_PREFIXES.find((entry) => entry.layer === layer.name)?.prefixes ?? [];
+}
+/**
+ * Layers named by an `allowed: false` (non-peerIsolation) rule that no intent can map to at runtime
+ * (no declared `intentPrefixes` and not a canonical layer name). Hard observed
+ * layer flow can never fire for such a rule. Sorted, unique.
+ */
+export function unresolvableLayerFlowLayers(config) {
+    const resolvable = new Set(config.layers
+        .filter((layer) => effectiveIntentPrefixes(layer).length > 0)
+        .map((layer) => layer.name));
+    const missing = new Set();
+    for (const rule of config.rules ?? []) {
+        // peerIsolation walls are file-path slice rules; runtime flow never evaluates them.
+        if (rule.allowed !== false || rule.peerIsolation === true)
+            continue;
+        for (const name of [rule.from, rule.to]) {
+            if (!resolvable.has(name))
+                missing.add(name);
+        }
+    }
+    return [...missing].sort();
+}
 /** Longest matching prefix wins; declaration order resolves an identical-prefix tie. */
 export function resolveIntentLayer(intent, layers) {
     const candidates = layers.flatMap((layer, layerIndex) => (layer.prefixes ?? layer.intentPrefixes ?? []).map((prefix) => ({

package/bin/lib/stable-hash.mjs

@@ -0,0 +1,90 @@
+/**
+ * GENERATED FILE — do not edit by hand.
+ *
+ * Canonical algorithm: src/domain/stableHash.ts
+ * Regenerate: node scripts/generate-cli-pure.mjs
+ * Drift check: node scripts/generate-cli-pure.mjs --check
+ *
+ * Pure CLI helper (bin/lib/stable-hash.mjs). Zero Node I/O.
+ */
+
+/** Stable FNV-1a hash. Identity/fingerprint only — not a security primitive. */
+export function deterministicHash(value) {
+    let hash = 0x811c9dc5;
+    for (let index = 0; index < value.length; index += 1) {
+        hash ^= value.charCodeAt(index);
+        hash = Math.imul(hash, 0x01000193);
+    }
+    return `fnv1a-${(hash >>> 0).toString(16).padStart(8, '0')}`;
+}
+/** Serialize JSON-like values with sorted object keys for reproducible hashes. */
+export function stableSerialize(value) {
+    if (value === null || typeof value !== 'object')
+        return JSON.stringify(value);
+    if (Array.isArray(value))
+        return `[${value.map(stableSerialize).join(',')}]`;
+    const object = value;
+    return `{${Object.keys(object)
+        .sort()
+        .map((key) => `${JSON.stringify(key)}:${stableSerialize(object[key])}`)
+        .join(',')}}`;
+}
+function feedText(text, state) {
+    let hash = state.hash;
+    for (let index = 0; index < text.length; index += 1) {
+        hash ^= text.charCodeAt(index);
+        hash = Math.imul(hash, 0x01000193);
+    }
+    state.hash = hash;
+}
+function feedStable(value, state) {
+    if (Array.isArray(value)) {
+        feedText('[', state);
+        for (let index = 0; index < value.length; index += 1) {
+            if (index > 0)
+                feedText(',', state);
+            // `map` skips holes and `join` renders an undefined element as ''.
+            if (!(index in value))
+                continue;
+            const item = value[index];
+            if (item !== null && typeof item === 'object')
+                feedStable(item, state);
+            else {
+                const text = JSON.stringify(item);
+                if (text !== undefined)
+                    feedText(text, state);
+            }
+        }
+        feedText(']', state);
+        return;
+    }
+    const object = value;
+    const keys = Object.keys(object).sort();
+    feedText('{', state);
+    for (let index = 0; index < keys.length; index += 1) {
+        if (index > 0)
+            feedText(',', state);
+        const key = keys[index];
+        feedText(`${JSON.stringify(key)}:`, state);
+        const item = object[key];
+        // A template literal renders an undefined serialization as 'undefined'.
+        if (item !== null && typeof item === 'object')
+            feedStable(item, state);
+        else
+            feedText(`${JSON.stringify(item)}`, state);
+    }
+    feedText('}', state);
+}
+/**
+ * `deterministicHash(stableSerialize(value))`, byte for byte, without building
+ * the serialized text. A large fact set hashes without first materializing a
+ * multi-megabyte string and every intermediate join.
+ */
+export function stableHash(value) {
+    if (value === null || typeof value !== 'object') {
+        return deterministicHash(stableSerialize(value));
+    }
+    const state = { hash: 0x811c9dc5 };
+    feedStable(value, state);
+    return `fnv1a-${(state.hash >>> 0).toString(16).padStart(8, '0')}`;
+}