arkgate 4.8.8 → 4.8.10

package/bin/lib/architecture-scan.mjs

@@ -18,6 +18,85 @@ import {
 } from './invariant-coverage-io.mjs';
 import { loadArkRuleFileHints } from './arkrule-file-hints.mjs';
 
+const HINT_CACHE_CAP = 16;
+/** Process-local hint map keyed by scoped path + content hash. Not a second engine. */
+const hintCache = new Map();
+
+function normalizeScanRelPath(root, filePath) {
+  if (typeof filePath !== 'string' || filePath.length === 0) return null;
+  const resolvedRoot = path.resolve(root);
+  const absolute = path.isAbsolute(filePath)
+    ? path.resolve(filePath)
+    : path.resolve(resolvedRoot, filePath);
+  const relative = path.relative(resolvedRoot, absolute).replace(/\\/g, '/');
+  if (
+    !relative ||
+    relative === '..' ||
+    relative.startsWith('../') ||
+    path.isAbsolute(relative)
+  ) {
+    return null;
+  }
+  return relative;
+}
+
+/** Empty / missing `files` stays unbounded (full governed set). */
+function fileLocalScope(root, files) {
+  if (!Array.isArray(files) || files.length === 0) return null;
+  const scoped = new Set();
+  for (const file of files) {
+    const rel = normalizeScanRelPath(root, file);
+    if (rel) scoped.add(rel);
+  }
+  return scoped.size > 0 ? scoped : null;
+}
+
+function filterHintPreload(fileContents, scoped) {
+  if (!scoped || !fileContents) return fileContents;
+  const out = {};
+  for (const [rel, content] of Object.entries(fileContents)) {
+    const key = String(rel || '')
+      .replace(/\\/g, '/')
+      .replace(/^\.\//, '');
+    if (scoped.has(key)) out[rel] = content;
+  }
+  return out;
+}
+
+function hintCacheKey(root, scopedFiles, arkRules) {
+  const filesPart = (scopedFiles ?? [])
+    .map((file) => `${file.path}\0${file.contentHash ?? ''}`)
+    .sort()
+    .join('\n');
+  const rulesPart = (arkRules?.structure ?? [])
+    .map(
+      (rule) =>
+        `${rule.sensor ?? ''}\0${rule.mode ?? ''}\0${(rule.appliesTo ?? []).join(',')}`
+    )
+    .join('\n');
+  return `${path.resolve(root)}\0${filesPart}\0${rulesPart}`;
+}
+
+function rememberHintCache(key, value) {
+  if (hintCache.has(key)) hintCache.delete(key);
+  hintCache.set(key, value);
+  while (hintCache.size > HINT_CACHE_CAP) {
+    const oldest = hintCache.keys().next().value;
+    hintCache.delete(oldest);
+  }
+}
+
+function loadHintsForScope(root, facts, arkRules, preloadedContents, scoped) {
+  const hintFacts = scoped
+    ? { files: (facts.files ?? []).filter((file) => scoped.has(file.path)) }
+    : facts;
+  const key = hintCacheKey(root, hintFacts.files, arkRules);
+  if (hintCache.has(key)) return hintCache.get(key);
+  const hints = loadArkRuleFileHints(root, hintFacts, arkRules, preloadedContents);
+  rememberHintCache(key, hints);
+  return hints;
+}
+
 /** Resolve canonical facts and optionally retain filesystem probes for resident invalidation. */
 export function resolveArchitectureSnapshot({
   root,
@@ -66,9 +145,16 @@ export function resolveArchitectureSnapshot({
     err.issues = arkRulesLoad.errors;
     throw err;
   }
+  const scoped = fileLocalScope(root, files);
   const loadedContract = loadContract(effectiveConfig, configPath, {
     arkRules: arkRulesLoad.arkRules,
   });
+  const analysisContract = scoped
+    ? {
+        ...loadedContract,
+        classShapes: (facts.classShapes ?? []).filter((shape) => scoped.has(shape.file)),
+      }
+    : loadedContract;
   const hasInvariants = (arkRulesLoad.arkRules?.invariants?.length ?? 0) > 0;
   const coverageInputs = hasInvariants
     ? loadInvariantCoverageInputs(root, facts, {
@@ -76,15 +162,16 @@ export function resolveArchitectureSnapshot({
         ...coverageOptionsFromConfig(effectiveConfig),
       })
     : undefined;
-  // AR07: Tooling fileHints for orchestration-only / thin-adapter (reuse coverage contents when present).
-  const fileHints = loadArkRuleFileHints(
+  // File-local structure sensors + hint load honor `files`; graph still uses full facts.
+  const fileHints = loadHintsForScope(
     root,
     facts,
     arkRulesLoad.arkRules,
-    coverageInputs?.fileContents
+    filterHintPreload(coverageInputs?.fileContents, scoped),
+    scoped
   );
   const analyzed = analyzeTrustedResolvedProject({
-    contract: loadedContract,
+    contract: analysisContract,
     facts,
     ...(coverageInputs ? { coverageInputs } : {}),
     ...(fileHints ? { fileHints } : {}),

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

@@ -10,8 +10,13 @@
 
 export const ARKORDER_PLANE_FACTORY = 'createOrderPlane';
 export const ARKORDER_FORBIDDEN_METHODS = ['update', 'patch', 'set', 'mutate'];
-const IO_IMPORT_HINT_RE = /\bfrom\s+['"](?:@?prisma\/client|@supabase\/|drizzle-orm|typeorm|knex|mongodb|pg|mysql2|mongoose|better-sqlite3|ioredis|redis|kysely|sequelize)['"]|require\(\s*['"](?:@?prisma\/client|pg|knex|typeorm|mongoose)/;
-const PERSISTENCE_WRITE_HINT_RE = /\.(?:insert(?:One|Many)?|update(?:One|Many)?|upsert|delete(?:One|Many)?|createMany|create|replaceOne|findOneAnd(?:Update|Delete|Replace))\s*\(|\bINSERT\s+INTO\b|\bUPDATE\s+[A-Za-z_][\w.]*\s+SET\b|\bDELETE\s+FROM\b/i;
+/** Keep in lockstep with arkRuleSensors (WRITEAGG-001 / EOSF2-001). */
+const IO_IMPORT_HINT_RE = /\bfrom\s+['"](?:@?prisma\/client|@supabase\/|drizzle-orm(?:\/[^'"]+)?|postgres(?:\/[^'"]+)?|typeorm|knex|mongodb|pg|mysql2|mongoose|better-sqlite3|ioredis|redis|kysely|sequelize)['"]|require\(\s*['"](?:@?prisma\/client|pg|postgres(?:\/[^'"]+)?|drizzle-orm(?:\/[^'"]+)?|knex|typeorm|mongoose)/;
+const IO_ALIAS_IMPORT_RE = /\bfrom\s+['"](?:@\/|~\/)?(?:[\w.-]+\/)*(?:db|database|prisma|drizzle)(?:\.[cm]?[jt]sx?)?['"]|require\(\s*['"](?:@\/|~\/)?(?:[\w.-]+\/)*(?:db|database|prisma|drizzle)/;
+const PERSISTENCE_WRITE_HINT_RE = /\b(?:db|tx|client|prisma(?:Client)?|drizzle)\b(?:\s*\.\s*[A-Za-z_]\w*)*\s*\.\s*(?:insert(?:One|Many)?|update(?:One|Many)?|upsert|delete(?:One|Many)?|createMany|create|replaceOne|findOneAnd(?:Update|Delete|Replace))\s*\(|\bINSERT\s+INTO\b|\bUPDATE\s+[A-Za-z_][\w.]*\s+SET\b|\bDELETE\s+FROM\b/i;
+function sourceImportsPersistenceDriver(content) {
+    return IO_IMPORT_HINT_RE.test(content) || IO_ALIAS_IMPORT_RE.test(content);
+}
 function escapeRegExp(value) {
     return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
 }
@@ -49,7 +54,9 @@ export function extractArkOrderGenericUpdatesFromSource(file, content) {
     while ((match = re.exec(source)) !== null) {
         const method = match[1];
         const before = source.slice(Math.max(0, match.index - 80), match.index);
-        if (!/\b(?:plane|orderPlane|order)\s*$/.test(before) && !/\bcreateOrderPlane\b/.test(source)) {
+        // EOSF5-001: Map/URLSearchParams/React order.set is not ξ mutation.
+        const calleeIsOrderPlane = /\b(?:plane|orderPlane)\s*(?:\?|!)?$/.test(before);
+        if (!calleeIsOrderPlane && !/\bcreateOrderPlane\b/.test(source)) {
             continue;
         }
         facts.push({ file, line: lineAt(content, match.index), method });
@@ -64,7 +71,7 @@ export function extractArkOrderXiFieldWritesFromSource(file, content, xiKeys) {
     if (xiKeys.length === 0)
         return [];
     const source = stripCommentsPreservingLines(content);
-    if (!IO_IMPORT_HINT_RE.test(source) || !PERSISTENCE_WRITE_HINT_RE.test(source))
+    if (!sourceImportsPersistenceDriver(source) || !PERSISTENCE_WRITE_HINT_RE.test(source))
         return [];
     const facts = [];
     const seen = new Set();

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

@@ -11,6 +11,102 @@
 import { extractArkOrderGenericUpdatesFromSource, extractArkOrderIngestWritesXiFromSource, extractArkOrderPlaneCallsFromSource, extractArkOrderReleaseKeyCountsFromSource, extractArkOrderXiFieldWritesFromSource, isArkOrderModuleSpecifier, } from './ark-order-facts.mjs';
 import { extraMergeTeethAllowed, } from './extra-merge-teeth.mjs';
 import { deterministicNextAction } from './remediation.mjs';
+/**
+ * XIWRITE-001: same engine as `globToRegExp` in src/domain/layerMatch.ts.
+ * Inlined so generate:cli-pure emits a self-contained bin/lib/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;
+}
+function globToRegExp(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;
+}
 export const ARKORDER_TIER1_SENSOR_IDS = [
     'arkorder-missing-plane',
     'arkorder-kernel-in-domain',
@@ -31,6 +127,11 @@ export const ARKORDER_RULE_IDS = {
     'arkorder-information-budget': 'ARKORDER_INFORMATION_BUDGET',
     'arkorder-xi-ttl': 'ARKORDER_XI_TTL',
 };
+function matchesArkOrderAppliesTo(file, appliesTo) {
+    if (!appliesTo || appliesTo.length === 0)
+        return true;
+    return appliesTo.some((pattern) => globToRegExp(pattern).test(file));
+}
 function isDomainRoleLayer(layer, intentPrefixes = []) {
     const name = layer.trim();
     if (/^domain(?:model)?$/i.test(name) || /^domain(?=[A-Z_\-\s])/i.test(name))
@@ -103,9 +204,6 @@ export function evaluateArkOrderSensors(input) {
         findings.push(finding(extra, 'arkorder-generic-update', update.file, update.line, `Generic ${update.method}() on the order plane rewrites ξ; Haken forbids it.`, { target: update.method }, teethAllowed));
     }
     const xiKeys = extra.xiKeys ?? [];
-    if (xiKeys.length > extra.maxXiKeys) {
-        findings.push(finding(extra, 'arkorder-too-many-params', 'ark.config.json', 1, `arkOrder.xiKeys has ${xiKeys.length} keys; maxXiKeys is ${extra.maxXiKeys} (few slow modes).`, { target: String(xiKeys.length) }, teethAllowed));
-    }
     for (const release of input.releaseKeyCounts ?? []) {
         if (release.keyCount <= extra.maxXiKeys)
             continue;
@@ -119,6 +217,8 @@ export function evaluateArkOrderSensors(input) {
         const fromLayer = input.layerForFile(write.file);
         if (!fromLayer || !managed.has(fromLayer))
             continue;
+        if (!matchesArkOrderAppliesTo(write.file, extra.appliesTo))
+            continue;
         findings.push(finding(extra, 'arkorder-xi-field-write', write.file, write.line, `File writes slow key ${JSON.stringify(write.key)} through a persistence driver; route the field through ingest or a pattern change through proposeRelease.`, { fromLayer, target: write.key }, teethAllowed));
     }
     findings.sort((left, right) => left.file.localeCompare(right.file) ||

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

@@ -2,12 +2,20 @@
  * Tooling I/O for AR07 orchestration-only / thin-adapter fileHints.
  * Pure derivation lives in Domain (`deriveArkRuleFileHints` / `buildArkRuleFileHints`);
  * this module loads bounded source text when those sensors are active.
+ *
+ * The file budget is `coverage.maxFiles` (default 400). There is no
+ * `arkrules.hintBudget`. When eligible governed files exceed the budget, the
+ * loader records exact hinted/governed counts and a completeness reason so an
+ * enforced sensor that never saw its scope cannot look green.
  */
 import fs from 'node:fs';
 import path from 'node:path';
 import { buildArkRuleFileHints } from './arkrules-sensors.mjs';
 
-const MAX_HINT_FILES = 400;
+/** 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_FILE_BYTES = 256 * 1024;
 
 const HINT_SENSORS = new Set([
@@ -16,6 +24,12 @@ const HINT_SENSORS = new Set([
   'writes-via-aggregate',
 ]);
 
+const HINT_BUDGET_META = Symbol.for('arkgate.hintBudget');
+
+/** --doctor sentence: coverage.maxFiles also bounds structural-hint preload. */
+export const HINT_BUDGET_DOCTOR_LINE =
+  'coverage.maxFiles (default 400) also bounds structural-hint preload for orchestration-only, thin-adapter, and writes-via-aggregate; there is no separate arkrules.hintBudget.';
+
 /**
  * @param {{ structure?: Array<{ sensor?: string }> } | null | undefined} arkRules
  */
@@ -23,36 +37,222 @@ 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 | {
+ *   hinted: number,
+ *   governed: number,
+ *   budget: number,
+ *   truncated: boolean,
+ *   sensors: Array<{ sensor: string, reviewed: number, scope: number, mode: string }>,
+ *   finding: { ruleId: string, message: string, failsStrict: boolean } | null,
+ *   completenessReason: { code: string, message: string } | null,
+ * }}
+ */
+export function getArkRuleHintBudget(hints) {
+  if (!hints || typeof hints !== 'object') return null;
+  return hints[HINT_BUDGET_META] ?? null;
+}
+
+/**
+ * @param {ReturnType<typeof getArkRuleHintBudget>} [budget]
+ * @returns {string}
+ */
+export function formatHintBudgetDoctorLine(budget) {
+  if (!budget?.truncated) return HINT_BUDGET_DOCTOR_LINE;
+  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
+ */
+function matchesAppliesTo(file, appliesTo) {
+  if (!Array.isArray(appliesTo) || appliesTo.length === 0) return true;
+  return appliesTo.some(
+    (pattern) => typeof pattern === 'string' && matchSimpleGlob(pattern, file)
+  );
+}
+
+function normalizeRel(relPath) {
+  return String(relPath || '')
+    .replace(/\\/g, '/')
+    .replace(/^\.\//, '');
+}
+
+function isHintEligiblePath(rel) {
+  if (!rel) return false;
+  if (!/\.(tsx?|mts|cts|jsx?|mjs|cjs)$/i.test(rel)) return false;
+  if (rel.includes('node_modules/') || rel.endsWith('.d.ts')) return false;
+  return true;
+}
+
+/**
+ * One row per hint sensor (union of appliesTo; enforced if any rule is).
+ * @param {{ structure?: Array<{ sensor?: string, mode?: string, appliesTo?: string[] }> } | null | undefined} arkRules
+ */
+function hintSensorScopes(arkRules) {
+  /** @type {Map<string, { sensor: string, appliesTo: string[], unconstrained: boolean, enforced: boolean }>} */
+  const bySensor = new Map();
+  for (const rule of arkRules?.structure ?? []) {
+    const sensor = rule?.sensor;
+    if (!HINT_SENSORS.has(sensor)) continue;
+    const applies = Array.isArray(rule.appliesTo)
+      ? rule.appliesTo.filter((item) => typeof item === 'string' && item.length > 0)
+      : [];
+    const existing = bySensor.get(sensor);
+    if (!existing) {
+      bySensor.set(sensor, {
+        sensor,
+        appliesTo: [...applies],
+        unconstrained: applies.length === 0,
+        enforced: rule.mode === 'enforced',
+      });
+      continue;
+    }
+    if (applies.length === 0) existing.unconstrained = true;
+    else existing.appliesTo.push(...applies);
+    if (rule.mode === 'enforced') existing.enforced = true;
+  }
+  return [...bySensor.values()];
+}
+
+/**
+ * @param {ReturnType<typeof hintSensorScopes>} scopes
+ * @param {string[]} eligible
+ * @param {Set<string>} hintedSet
+ */
+function sensorCoverage(scopes, eligible, hintedSet) {
+  return scopes.map((scope) => {
+    const inScope = scope.unconstrained
+      ? eligible
+      : eligible.filter((file) => matchesAppliesTo(file, scope.appliesTo));
+    return {
+      sensor: scope.sensor,
+      reviewed: inScope.filter((file) => hintedSet.has(file)).length,
+      scope: inScope.length,
+      mode: scope.enforced ? 'enforced' : 'advisory',
+    };
+  });
+}
+
+function formatSensorSummaries(sensors) {
+  return sensors
+    .map((row) => `${row.sensor} reviewed ${row.reviewed}/${row.scope} files of its scope`)
+    .join('; ');
+}
+
+function attachHintBudget(hints, meta) {
+  Object.defineProperty(hints, HINT_BUDGET_META, {
+    value: meta,
+    enumerable: false,
+    configurable: true,
+  });
+  return hints;
+}
+
 /**
  * Load governed source contents (bounded) and derive fileHints.
  *
+ * Return value stays a path→flags map so architecture-scan can pass it through
+ * unchanged. Truncation stats hang on a non-enumerable symbol — read them with
+ * `getArkRuleHintBudget`.
+ *
  * @param {string} root
  * @param {{ files?: Array<{ path: string }> }} facts
- * @param {{ structure?: Array<{ sensor?: string }> } | null | undefined} arkRules
+ * @param {{ structure?: Array<{ sensor?: string, mode?: string, appliesTo?: string[] }> } | null | undefined} arkRules
  * @param {Readonly<Record<string, string>>} [preloadedContents] optional reuse from coverage I/O
+ * @param {{ maxFiles?: number }} [options] `coverage.maxFiles` when the caller knows it
  * @returns {Record<string, { orchestrationHeavy?: boolean, adapterThick?: boolean, persistenceWrite?: boolean }> | undefined}
  */
-export function loadArkRuleFileHints(root, facts, arkRules, preloadedContents) {
+export function loadArkRuleFileHints(root, facts, arkRules, preloadedContents, options) {
   if (!needsArkRuleFileHints(arkRules)) return undefined;
 
-  const fileContents = { ...(preloadedContents ?? {}) };
+  const explicitBudget =
+    Number.isInteger(options?.maxFiles) && options.maxFiles > 0
+      ? Math.min(options.maxFiles, MAX_HINT_FILES_CAP)
+      : null;
+
+  const eligible = [];
+  const seenEligible = new Set();
+  for (const file of facts?.files ?? []) {
+    const rel = normalizeRel(file?.path);
+    if (!isHintEligiblePath(rel) || seenEligible.has(rel)) continue;
+    seenEligible.add(rel);
+    eligible.push(rel);
+  }
+  eligible.sort();
+
+  let fileContents = { ...(preloadedContents ?? {}) };
+  if (explicitBudget != null) {
+    const keys = Object.keys(fileContents).sort();
+    if (keys.length > explicitBudget) {
+      fileContents = Object.fromEntries(
+        keys.slice(0, explicitBudget).map((key) => [key, fileContents[key]])
+      );
+    }
+  }
   const seen = new Set(Object.keys(fileContents));
+  // When coverage already preloaded more than the default 400, that preload *is*
+  // the coverage.maxFiles lever. Do not trim it unless the caller passed maxFiles.
+  const budget =
+    explicitBudget ??
+    Math.min(Math.max(DEFAULT_MAX_HINT_FILES, seen.size), MAX_HINT_FILES_CAP);
 
   const rootResolved = path.resolve(root);
   const pushFile = (relPath) => {
-    const rel = String(relPath || '')
-      .replace(/\\/g, '/')
-      .replace(/^\.\//, '');
-    if (!rel || seen.has(rel) || seen.size >= MAX_HINT_FILES) return;
-    if (!/\.(tsx?|mts|cts|jsx?|mjs|cjs)$/i.test(rel)) return;
-    if (rel.includes('node_modules/') || rel.endsWith('.d.ts')) return;
+    const rel = normalizeRel(relPath);
+    if (!rel || seen.has(rel) || seen.size >= budget) return;
+    if (!isHintEligiblePath(rel)) return;
     const absolute = path.resolve(root, rel);
     const relative = path.relative(rootResolved, absolute);
-    if (
-      relative === '' ||
-      relative.startsWith('..') ||
-      path.isAbsolute(relative)
-    ) {
+    if (relative === '' || relative.startsWith('..') || path.isAbsolute(relative)) {
       return;
     }
     try {
@@ -65,11 +265,46 @@ export function loadArkRuleFileHints(root, facts, arkRules, preloadedContents) {
     }
   };
 
-  for (const file of facts?.files ?? []) {
-    if (file?.path) pushFile(file.path);
+  for (const rel of eligible) {
+    pushFile(rel);
   }
 
-  if (Object.keys(fileContents).length === 0) return undefined;
-  const hints = buildArkRuleFileHints(fileContents);
-  return Object.keys(hints).length > 0 ? hints : {};
+  const hintedSet = new Set(Object.keys(fileContents));
+  const hinted = hintedSet.size;
+  const governed = eligible.length;
+  const truncated = governed > hinted;
+  const sensors = sensorCoverage(hintSensorScopes(arkRules), eligible, hintedSet);
+  const enforcedMiss = sensors.some(
+    (row) => row.mode === 'enforced' && row.reviewed < row.scope
+  );
+  const sensorSummary = formatSensorSummaries(sensors);
+  const message = truncated
+    ? `Structural-hint budget exhausted: hinted ${hinted} of ${governed} eligible governed files (budget ${budget}; raise coverage.maxFiles — this cap also bounds structural-hint preload)${sensorSummary ? `. ${sensorSummary}` : ''}.`
+    : null;
+  const finding = truncated
+    ? {
+        ruleId: 'ARKRULE_HINT_BUDGET_EXHAUSTED',
+        message,
+        failsStrict: enforcedMiss,
+      }
+    : null;
+  const completenessReason = truncated
+    ? { code: 'ARKRULE_HINT_BUDGET_EXHAUSTED', message }
+    : null;
+  const meta = {
+    hinted,
+    governed,
+    budget,
+    truncated,
+    sensors,
+    finding,
+    completenessReason,
+  };
+
+  if (Object.keys(fileContents).length === 0 && !truncated) return undefined;
+
+  const derived = buildArkRuleFileHints(fileContents);
+  const hints = derived && typeof derived === 'object' ? derived : {};
+  attachHintBudget(hints, meta);
+  return hints;
 }