arkgate 4.8.24 → 4.8.25

package/bin/lib/architecture-scan.mjs

@@ -16,6 +16,7 @@ import { effectiveAnalysisConfig } from './analysis-policy.mjs';
 import { resolveCandidateFacts } from './resolved-candidate-facts.mjs';
 import {
   arkRulesDriftWarnings,
+  arkRulesLoadFailed,
   loadEffectiveArkRulesFromDisk,
 } from './effective-contract-load.mjs';
 import {
@@ -31,6 +32,7 @@ import {
 } from './invariant-tests-path.mjs';
 import { loadArkRuleFileHints } from './arkrule-file-hints.mjs';
 import { collectGovernedFiles } from './scan-files.mjs';
+import { projectImporterIndex } from './import-graph-projection.mjs';
 
 const HINT_CACHE_CAP = 16;
 /** Process-local hint map keyed by scoped path + content hash. Not a second engine. */
@@ -206,13 +208,7 @@ export function resolveArchitectureSnapshot({
     observeInput,
   });
   if (arkRulesLoad.errors.length > 0) {
-    const message = arkRulesLoad.errors
-      .map((issue) => `- ${issue.path}: ${issue.message}`)
-      .join('\n');
-    const err = new Error(`Invalid Effective Contract (${configPath}):\n${message}`);
-    err.code = 'ARKRULES_LOAD_FAILED';
-    err.issues = arkRulesLoad.errors;
-    throw err;
+    throw arkRulesLoadFailed(configPath, arkRulesLoad.errors);
   }
   const loadedContract = loadContract(effectiveConfig, configPath, {
     arkRules: arkRulesLoad.arkRules,
@@ -296,8 +292,14 @@ export function resolveArchitectureSnapshot({
 
 /**
  * Full architecture scan for governed files.
- * @returns {{ violations: object[], warnings: object[] }}
+ *
+ * `graphProjection: true` (doctor / report) also returns `importGraph`, a compact
+ * importer index projected from the resolved facts before they are released
+ * (ADR 0037 D1). The verdict fields are the same object either way.
+ * @returns {{ violations: object[], warnings: object[], importGraph?: object }}
  */
 export function runArchitectureScan(options) {
-  return resolveArchitectureSnapshot({ ...options, captureInputs: false }).result;
+  const snapshot = resolveArchitectureSnapshot({ ...options, captureInputs: false });
+  if (options?.graphProjection !== true) return snapshot.result;
+  return { ...snapshot.result, importGraph: projectImporterIndex(snapshot.facts) };
 }

package/bin/lib/ark-order-doctor.mjs

@@ -8,7 +8,7 @@
  * Pure CLI helper (bin/lib/ark-order-doctor.mjs). Zero Node I/O.
  */
 
-import { composeMergePlanesHonesty, extraMergeTeethAllowed, isArkOrderRuleId, } from './extra-merge-teeth.mjs';
+import { composeMergePlanesHonesty, extraMergeTeethAllowed, isArkOrderRuleId, mergePlanesArkRulesInput, projectExtraPlaneStatus, } from './extra-merge-teeth.mjs';
 export const ARK_ORDER_DOCTOR_SCHEMA_VERSION = '1.0';
 const RESIDUAL_RULE_CAP = 12;
 export const ARKORDER_ONE_BREATH = 'Layers stop a bad import. ArkOrder stops rewriting a big product choice — like the billing plan — as if it were a seat count. Change those choices through a valve, not a generic update.';
@@ -54,17 +54,7 @@ export function summarizeArkOrderSection(input = {}) {
     const residualCount = uniqueIds.length;
     const mergePlanes = composeMergePlanesHonesty({
         classification: input.classification,
-        arkRules: {
-            active: input.arkRules?.active === true,
-            structureEnforced: input.arkRules?.structureEnforced,
-            structureTotal: input.arkRules?.structureTotal,
-            structureAdvisory: input.arkRules?.structureAdvisory,
-            invariantEnforced: input.arkRules?.invariantEnforced,
-            invariantTotal: input.arkRules?.invariantTotal,
-            invariantAdvisory: input.arkRules?.invariantAdvisory,
-            covered: input.arkRules?.covered,
-            uncovered: input.arkRules?.uncovered,
-        },
+        arkRules: mergePlanesArkRulesInput(input.arkRules),
         arkRun: {
             present: input.arkRun?.present === true,
             mode: input.arkRun?.mode ?? null,
@@ -110,22 +100,7 @@ export function summarizeArkOrderSection(input = {}) {
 }
 /** Thin status slice — counts only; residual null means unknown, not green. */
 export function projectStatusArkOrder(input = {}) {
-    const present = input.present === true;
-    const mode = closedMode(input.mode);
-    const residualRaw = input.residual;
-    let residual = null;
-    if (typeof residualRaw === 'number' && Number.isFinite(residualRaw) && residualRaw >= 0) {
-        residual = Math.floor(residualRaw);
-    }
-    if (!present)
-        residual = residual == null ? 0 : residual;
-    return {
-        notAScore: true,
-        present,
-        mode: present ? mode : null,
-        extraMergeTeeth: present && mode === 'enforced' && input.extraMergeTeeth === true,
-        residual,
-    };
+    return projectExtraPlaneStatus(input);
 }
 export function formatArkOrderDoctorLines(section) {
     if (!section || section.notAScore !== true)

package/bin/lib/ark-order-facts.mjs

@@ -9,105 +9,12 @@
  */
 
 import { XI_TTL_KEY_RE } from './ark-order-types.mjs';
+import { globToRegExp } from '../ark-layer-match.mjs';
 import { sourceHasPersistenceWrite, sourceImportsPersistenceDriverText } from './persistence-write-hint.mjs';
-export const ARKORDER_PLANE_FACTORY = 'createOrderPlane';
-export const ARKORDER_FORBIDDEN_METHODS = ['update', 'patch', 'set', 'mutate'];
-/**
- * XIWRITE-001: same engine as `globToRegExp` in src/domain/layerMatch.ts.
- * Inlined so generate:cli-pure emits self-contained bin/lib/ark-order-facts.mjs /
- * ark-order-sensors.mjs
- * (layerMatch is derived to bin/ark-layer-match.mjs, not a bin/lib sibling).
- */
-const appliesToRegexpCache = new Map();
-function escapeAppliesToLiteral(ch) {
-    return /[.*+?^${}()|[\]\\]/.test(ch) ? `\\${ch}` : ch;
-}
-function normalizeAppliesToGlob(pattern) {
-    let out = '';
-    for (let i = 0; i < pattern.length; i += 1) {
-        const c = pattern[i];
-        if (c === '\\' && i + 1 < pattern.length) {
-            const next = pattern[i + 1];
-            if ('*?{}[],'.includes(next) || next === '\\') {
-                out += '\\' + next;
-                i += 1;
-                continue;
-            }
-            out += '/';
-            continue;
-        }
-        out += c;
-    }
-    return out;
-}
-function appliesToBracesBalanced(glob) {
-    let depth = 0;
-    for (let i = 0; i < glob.length; i += 1) {
-        const c = glob[i];
-        if (c === '\\') {
-            i += 1;
-            continue;
-        }
-        if (c === '{')
-            depth += 1;
-        else if (c === '}') {
-            depth -= 1;
-            if (depth < 0)
-                return false;
-        }
-    }
-    return depth === 0;
-}
+const ARKORDER_PLANE_FACTORY = 'createOrderPlane';
+/** XIWRITE-001 `appliesTo` globs use the layer-glob engine (`globToRegExp`). */
 export function arkOrderGlobToRegExp(pattern) {
-    const cached = appliesToRegexpCache.get(pattern);
-    if (cached)
-        return cached;
-    const glob = normalizeAppliesToGlob(pattern);
-    const useBraces = appliesToBracesBalanced(glob);
-    let out = '';
-    let braceDepth = 0;
-    for (let i = 0; i < glob.length; i += 1) {
-        const c = glob[i];
-        if (c === '\\' && i + 1 < glob.length) {
-            out += escapeAppliesToLiteral(glob[i + 1]);
-            i += 1;
-        }
-        else if (c === '*') {
-            if (glob[i + 1] === '*') {
-                if (glob[i + 2] === '/') {
-                    out += '(?:.*/)?';
-                    i += 2;
-                }
-                else {
-                    out += '.*';
-                    i += 1;
-                }
-            }
-            else {
-                out += '[^/]*';
-            }
-        }
-        else if (c === '?') {
-            out += '[^/]';
-        }
-        else if (c === '{' && useBraces) {
-            out += '(?:';
-            braceDepth += 1;
-        }
-        else if (c === '}' && useBraces && braceDepth > 0) {
-            out += ')';
-            braceDepth -= 1;
-        }
-        else if (c === ',' && useBraces && braceDepth > 0) {
-            out += '|';
-        }
-        else {
-            out += escapeAppliesToLiteral(c);
-        }
-    }
-    const re = new RegExp(`^${out}$`);
-    appliesToRegexpCache.set(pattern, re);
-    return re;
+    return globToRegExp(pattern);
 }
 function escapeRegExp(value) {
     return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
@@ -195,7 +102,7 @@ const TRAILING_IDENTIFIER_RE = /([A-Za-z_$][\w$]*)\s*!?\s*\??\s*$/;
 /** Leading identifier inside a parenthesized receiver: `x as T`, `<T>x`, `x!`, `x`. */
 const WRAPPED_IDENTIFIER_RE = /^\s*(?:<[^<>]*>\s*)?([A-Za-z_$][\w$]*)\s*!?\s*(?:\b(?:as|satisfies)\b[\s\S]*)?$/;
 /** Identifiers bound to `createOrderPlane(...)` in this file. */
-export function arkOrderPlaneBindings(content) {
+function arkOrderPlaneBindings(content) {
     const source = stripCommentsPreservingLines(content);
     const names = new Set();
     const re = new RegExp(PLANE_BINDING_RE.source, 'g');
@@ -260,7 +167,7 @@ function specifierResolvesToPlaneRoot(file, specifier, planeRoots) {
  * named import from a declared plane root. `isArkOrderFile` reports an `arkgate/order`
  * import, which admits the conventional names file-wide.
  */
-export function arkOrderPlaneReceivers(file, content, options = {}) {
+function arkOrderPlaneReceivers(file, content, options = {}) {
     const source = stripCommentsPreservingLines(content);
     const names = new Set(arkOrderPlaneBindings(content));
     const annotated = new RegExp(ORDER_PLANE_ANNOTATION_RE.source, 'g');

package/bin/lib/ark-order-types.mjs

@@ -11,6 +11,5 @@
 export const DEFAULT_MAX_XI_KEYS = 7;
 /** ξ keys that name freshness. Freshness is σ, never ξ (runtime and static sensor share this). */
 export const XI_TTL_KEY_RE = /^(ttl|freshUntil|fresh_until|maxAge|max_age)$/i;
-export const INGEST_RESIDUAL_KINDS = ['absorb', 'escalate_up', 'hold'];
-export const INGEST_REASON_CODES = ['not-in-pattern', 'stale-sigma', 'pack', 'capacity'];
+const INGEST_REASON_CODES = ['not-in-pattern', 'stale-sigma', 'pack', 'capacity'];
 export const CAPACITY_OPS = ['lte', 'lt', 'gte', 'gt'];

package/bin/lib/ark-run-doctor.mjs

@@ -8,7 +8,7 @@
  * Pure CLI helper (bin/lib/ark-run-doctor.mjs). Zero Node I/O.
  */
 
-import { composeMergePlanesHonesty, extraMergeTeethAllowed, isArkRunRuleId, } from './extra-merge-teeth.mjs';
+import { composeMergePlanesHonesty, extraMergeTeethAllowed, isArkRunRuleId, mergePlanesArkRulesInput, projectExtraPlaneStatus, } from './extra-merge-teeth.mjs';
 import { unresolvableLayerFlowLayers } from './source-policy.mjs';
 export const ARK_RUN_DOCTOR_SCHEMA_VERSION = '1.0';
 const RESIDUAL_RULE_CAP = 12;
@@ -59,17 +59,7 @@ export function summarizeArkRunSection(input = {}) {
     const residualCount = uniqueIds.length;
     const mergePlanes = composeMergePlanesHonesty({
         classification: input.classification,
-        arkRules: {
-            active: input.arkRules?.active === true,
-            structureEnforced: input.arkRules?.structureEnforced,
-            structureTotal: input.arkRules?.structureTotal,
-            structureAdvisory: input.arkRules?.structureAdvisory,
-            invariantEnforced: input.arkRules?.invariantEnforced,
-            invariantTotal: input.arkRules?.invariantTotal,
-            invariantAdvisory: input.arkRules?.invariantAdvisory,
-            covered: input.arkRules?.covered,
-            uncovered: input.arkRules?.uncovered,
-        },
+        arkRules: mergePlanesArkRulesInput(input.arkRules),
         arkRun: {
             present: extra.present,
             mode: extra.mode,
@@ -112,22 +102,7 @@ export function summarizeArkRunSection(input = {}) {
 }
 /** Thin status slice — counts only; residual null means unknown, not green. */
 export function projectStatusArkRun(input = {}) {
-    const present = input.present === true;
-    const mode = closedMode(input.mode);
-    const residualRaw = input.residual;
-    let residual = null;
-    if (typeof residualRaw === 'number' && Number.isFinite(residualRaw) && residualRaw >= 0) {
-        residual = Math.floor(residualRaw);
-    }
-    if (!present)
-        residual = residual == null ? 0 : residual;
-    return {
-        notAScore: true,
-        present,
-        mode: present ? mode : null,
-        extraMergeTeeth: present && mode === 'enforced' && input.extraMergeTeeth === true,
-        residual,
-    };
+    return projectExtraPlaneStatus(input);
 }
 export function formatArkRunDoctorLines(section) {
     if (!section || section.notAScore !== true)

package/bin/lib/ark-run-facts.mjs

@@ -23,14 +23,14 @@ export const ARKRUN_KERNEL_FACTORY_CALLEES = [
  * count as a kernel factory only when `ArkModule` is imported from a kernel module
  * (`arkgate/nestjs`). A bare `.forRoot(` on any other receiver never counts.
  */
-export const ARKRUN_NEST_KERNEL_MODULE = 'ArkModule';
-export const ARKRUN_NEST_FACTORY_METHODS = ['forRoot', 'forRootAsync'];
+const ARKRUN_NEST_KERNEL_MODULE = 'ArkModule';
+const ARKRUN_NEST_FACTORY_METHODS = ['forRoot', 'forRootAsync'];
 /**
  * Kernel types whose annotated bindings (`ark: ArkKernel`, constructor-injected
  * `private readonly ark: ArkKernel`) are traced as kernel receivers when the type
  * is imported from a kernel module.
  */
-export const ARKRUN_KERNEL_RECEIVER_TYPES = [
+const ARKRUN_KERNEL_RECEIVER_TYPES = [
     'ArkKernel',
     'EventBus',
     'EventPublisher',
@@ -310,21 +310,33 @@ export function extractArkRunValueImportDependenciesFromSource(file, content) {
     }
     return out;
 }
+/**
+ * Value bindings of a braced import list (`{ A, B as C }`): local name plus the
+ * imported (original) name. Inline `type` specifiers are skipped.
+ */
+function bracedValueImportBindings(clause) {
+    const braced = /\{([^}]*)\}/.exec(clause);
+    if (!braced?.[1])
+        return [];
+    const out = [];
+    for (const part of braced[1].split(',')) {
+        const piece = part.trim();
+        if (!piece || piece.startsWith('type '))
+            continue;
+        const alias = /^([A-Za-z_][A-Za-z0-9_]*)\s+as\s+([A-Za-z_][A-Za-z0-9_]*)$/.exec(piece);
+        const local = alias?.[2] ?? /^([A-Za-z_][A-Za-z0-9_]*)$/.exec(piece)?.[1];
+        const original = alias?.[1] ?? local;
+        if (local && original)
+            out.push({ local, original });
+    }
+    return out;
+}
 /** PascalCase named bindings from value import clauses (snippet admitted constructors). */
 export function extractArkRunImportedConstructorNamesFromSource(content) {
     const names = [];
     forEachArkRunValueImportClause(content, (clause) => {
-        const braced = /\{([^}]*)\}/.exec(clause);
-        if (!braced?.[1])
-            return;
-        for (const part of braced[1].split(',')) {
-            const piece = part.trim();
-            if (!piece || piece.startsWith('type '))
-                continue;
-            const alias = /^([A-Za-z_][A-Za-z0-9_]*)\s+as\s+([A-Za-z_][A-Za-z0-9_]*)$/.exec(piece);
-            const local = alias?.[2] ?? /^([A-Za-z_][A-Za-z0-9_]*)$/.exec(piece)?.[1];
-            const original = alias?.[1] ?? local;
-            if (local && original && /^[A-Z]/.test(original))
+        for (const { local, original } of bracedValueImportBindings(clause)) {
+            if (/^[A-Z]/.test(original))
                 names.push(local, original);
         }
     });
@@ -342,21 +354,8 @@ function collectKernelImportBindings(content) {
         const defaultIdent = /^([A-Za-z_][A-Za-z0-9_]*)\s*(?:,|$)/.exec(clause.trim());
         if (defaultIdent?.[1])
             named.set(defaultIdent[1], defaultIdent[1]);
-        const braced = /\{([^}]*)\}/.exec(clause);
-        if (!braced?.[1])
-            return;
-        for (const part of braced[1].split(',')) {
-            const piece = part.trim();
-            if (!piece || piece.startsWith('type '))
-                continue;
-            const alias = /^([A-Za-z_][A-Za-z0-9_]*)\s+as\s+([A-Za-z_][A-Za-z0-9_]*)$/.exec(piece);
-            if (alias) {
-                named.set(alias[2], alias[1]);
-                continue;
-            }
-            const ident = /^([A-Za-z_][A-Za-z0-9_]*)$/.exec(piece);
-            if (ident?.[1])
-                named.set(ident[1], ident[1]);
+        for (const { local, original } of bracedValueImportBindings(clause)) {
+            named.set(local, original);
         }
     });
     return { named, namespaces };
@@ -364,17 +363,8 @@ function collectKernelImportBindings(content) {
 function collectImportedConstructors(content, admitted) {
     const out = new Set(admitted);
     parseValueImportClause(content, (clause, specifier) => {
-        const braced = /\{([^}]*)\}/.exec(clause);
-        if (!braced?.[1])
-            return;
-        for (const part of braced[1].split(',')) {
-            const piece = part.trim();
-            if (!piece || piece.startsWith('type '))
-                continue;
-            const alias = /^([A-Za-z_][A-Za-z0-9_]*)\s+as\s+([A-Za-z_][A-Za-z0-9_]*)$/.exec(piece);
-            const local = alias?.[2] ?? /^([A-Za-z_][A-Za-z0-9_]*)$/.exec(piece)?.[1];
-            const original = alias?.[1] ?? local;
-            if (!local || !original || !/^[A-Z]/.test(original))
+        for (const { local, original } of bracedValueImportBindings(clause)) {
+            if (!/^[A-Z]/.test(original))
                 continue;
             if (isArkRunKernelModuleSpecifier(specifier) || admitted.has(original) || admitted.has(local)) {
                 out.add(local);

package/bin/lib/ark-run-sensors.mjs

@@ -30,7 +30,7 @@ export const ARKRUN_EDITOR_SENSOR_IDS = [
     'arkrun-transport-bypass',
 ];
 const EDITOR_SENSOR_SET = new Set(ARKRUN_EDITOR_SENSOR_IDS);
-export function isArkRunEditorSensor(sensor) {
+function isArkRunEditorSensor(sensor) {
     return EDITOR_SENSOR_SET.has(sensor);
 }
 export const ARKRUN_RULE_IDS = {

package/bin/lib/arkrule-file-hints.mjs

@@ -11,11 +11,12 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import { buildArkRuleFileHints } from './arkrules-sensors.mjs';
+import { matchSimpleGlob } from './invariant-coverage-io.mjs';
 
 /** Default hint-file budget. Same lever as `coverage.maxFiles`. */
 export const DEFAULT_MAX_HINT_FILES = 400;
 /** Hard ceiling — same clamp as coverage.maxFiles. */
-export const MAX_HINT_FILES_CAP = 20_000;
+const MAX_HINT_FILES_CAP = 20_000;
 const MAX_FILE_BYTES = 256 * 1024;
 
 const HINT_SENSORS = new Set([
@@ -37,17 +38,6 @@ export function needsArkRuleFileHints(arkRules) {
   return (arkRules?.structure ?? []).some((rule) => HINT_SENSORS.has(rule?.sensor));
 }
 
-/**
- * @param {unknown} maxFiles
- * @returns {number}
- */
-export function resolveHintBudget(maxFiles) {
-  if (Number.isInteger(maxFiles) && maxFiles > 0) {
-    return Math.min(maxFiles, MAX_HINT_FILES_CAP);
-  }
-  return DEFAULT_MAX_HINT_FILES;
-}
-
 /**
  * @param {unknown} hints
  * @returns {null | {
@@ -74,41 +64,6 @@ export function formatHintBudgetDoctorLine(budget) {
   return `${HINT_BUDGET_DOCTOR_LINE} Hinted ${budget.hinted} of ${budget.governed} eligible governed files (budget ${budget.budget}).`;
 }
 
-/**
- * Minimal glob match (double-star slash = zero path segments).
- * @param {string} glob
- * @param {string} file
- */
-function matchSimpleGlob(glob, file) {
-  const pattern = String(glob || '').replace(/\\/g, '/');
-  const target = String(file || '').replace(/\\/g, '/');
-  if (!pattern) return false;
-  let out = '';
-  for (let i = 0; i < pattern.length; i += 1) {
-    const c = pattern[i];
-    if (c === '*') {
-      if (pattern[i + 1] === '*') {
-        if (pattern[i + 2] === '/') {
-          out += '(?:.*/)?';
-          i += 2;
-        } else {
-          out += '.*';
-          i += 1;
-        }
-      } else {
-        out += '[^/]*';
-      }
-    } else if (c === '?') {
-      out += '[^/]';
-    } else if (/[.+^${}()|[\]\\]/.test(c)) {
-      out += `\\${c}`;
-    } else {
-      out += c;
-    }
-  }
-  return new RegExp(`^${out}$`).test(target);
-}
-
 /**
  * @param {string} file
  * @param {unknown} appliesTo