@surea11y/core 1.1.2 → 1.3.0

package/src/core/dom-runner.js

@@ -12,652 +12,776 @@
  *   normalizeRuleMeta (src/core/rule-meta.js -- used for engineOptions.customRules).
  */
 
-function runCore(pageUrl, contextSelector, engineOptions, runOnly, CHECK_DEFS, RULE_IMPLS, ENGINE_TAG, SCHEMA_VERSION, COMPOSITE_RULES) {
-    // Normalize contrast options without mutating caller-provided engineOptions.
-    function __normalizeContrastOptions(engineOptions2) {
-        const eo = engineOptions2 && typeof engineOptions2 === 'object' ? engineOptions2 : {};
-        const c = (eo.contrast && typeof eo.contrast === 'object') ? eo.contrast : {};
-        const mode = (c.mode === 'auditorAssist') ? 'auditorAssist' : 'strictConformance';
-        const rootCanvasFallback =
-            (typeof c.rootCanvasFallback === 'string' && c.rootCanvasFallback.trim())
-                ? c.rootCanvasFallback.trim()
-                : '#ffffff';
-        return { mode, rootCanvasFallback };
-    }
-
-    const engineOptionsResolved =
-        (engineOptions && typeof engineOptions === 'object')
-            ? { ...engineOptions, contrast: __normalizeContrastOptions(engineOptions) }
-            : { contrast: __normalizeContrastOptions(null) };
-
-    const policy = resolvePolicy(POLICY_CONTRACTS, engineOptionsResolved);
-
-    // contextSelector accepts a single selector string (which may itself be a
-    // comma-separated selector list -- ordinary CSS union semantics) OR an
-    // array of selector strings for scanning multiple, possibly disjoint
-    // regions in one run (a widely-used reference engine's multi-.include()
-    // capability has no equivalent here otherwise). Both forms resolve via querySelectorAll,
-    // not querySelector -- previously a single string only ever scanned its
-    // FIRST match, silently ignoring the rest if it happened to match more
-    // than one element. That was a real gap, not a deliberate "one region
-    // only" design: switched to querySelectorAll for both forms so
-    // "matches this selector" actually means all matches, consistently.
-    // Shared with frame-scan.js (same resolution used to discover which
-    // child <iframe>/<frame> elements fall within the same scan scope).
-    const { ctxSelector, roots } = resolveContextRoots(document, contextSelector);
-
-    // Default on: opt OUT with `includeShadowDom: false`, not opt in.
-    const includeShadowDom = !(engineOptionsResolved && engineOptionsResolved.includeShadowDom === false);
-    // Default off: hidden/collapsed content is excluded from rule evaluation
-    // unless the caller explicitly opts in.
-    const includeHiddenElements = !!(engineOptionsResolved && engineOptionsResolved.includeHiddenElements === true);
-    const excludeSelectors = normalizeSelectorList(engineOptionsResolved && engineOptionsResolved.excludeSelectors);
-
-    const url = pageUrl || (document.location && document.location.href) || null;
-    const title = document.title || null;
-    // Deterministic timestamp: only use host-provided value (no time-based logic).
-    const timestamp =
-        (engineOptionsResolved && typeof engineOptionsResolved.timestamp === 'string' && engineOptionsResolved.timestamp.trim())
-            ? engineOptionsResolved.timestamp.trim()
-            : null;
-
-    // createDomHelpers()/createContrastHelpers() persist their element-keyed
-    // caches (outerHtmlCache, selectorCache, etc.) on window.__a11ycoreSharedCache
-    // so multiple helper instances created *within this run* can share them
-    // deterministically. But a window/document is frequently reused across
-    // SEPARATE runs -- e.g. Jest's jsdom environment creates one window per
-    // test file, and mutating document.body between it() blocks is standard.
-    // Those caches are keyed by element reference, not content, so a run that
-    // reuses an already-cached element (document.body never changes identity)
-    // would otherwise read stale data cached by an earlier, unrelated run on
-    // the same window. Clearing at the start of every run keeps sharing scoped
-    // to "this run" as intended, without leaking across runs.
+/* global resolvePolicy, POLICY_CONTRACTS, resolveRuleDefI18n, ruleMatchesRunOnly,
+   normalizeRuleResult, normalizeLocale, createDomHelpers, normalizeSelectorList,
+   resolveContextRoots, normalizeRuleMeta */
+
+function runCore(
+  pageUrl,
+  contextSelector,
+  engineOptions,
+  runOnly,
+  CHECK_DEFS,
+  RULE_IMPLS,
+  ENGINE_TAG,
+  SCHEMA_VERSION,
+  COMPOSITE_RULES
+) {
+  // Normalize contrast options without mutating caller-provided engineOptions.
+  function __normalizeContrastOptions(engineOptions2) {
+    const eo = engineOptions2 && typeof engineOptions2 === 'object' ? engineOptions2 : {};
+    const c = eo.contrast && typeof eo.contrast === 'object' ? eo.contrast : {};
+    const mode = c.mode === 'auditorAssist' ? 'auditorAssist' : 'strictConformance';
+    const rootCanvasFallback =
+      typeof c.rootCanvasFallback === 'string' && c.rootCanvasFallback.trim()
+        ? c.rootCanvasFallback.trim()
+        : '#ffffff';
+    return { mode, rootCanvasFallback };
+  }
+
+  const engineOptionsResolved =
+    engineOptions && typeof engineOptions === 'object'
+      ? { ...engineOptions, contrast: __normalizeContrastOptions(engineOptions) }
+      : { contrast: __normalizeContrastOptions(null) };
+
+  const policy = resolvePolicy(POLICY_CONTRACTS, engineOptionsResolved);
+
+  // contextSelector accepts a single selector string (which may itself be a
+  // comma-separated selector list -- ordinary CSS union semantics) OR an
+  // array of selector strings for scanning multiple, possibly disjoint
+  // regions in one run (a widely-used reference engine's multi-.include()
+  // capability has no equivalent here otherwise). Both forms resolve via querySelectorAll,
+  // not querySelector -- previously a single string only ever scanned its
+  // FIRST match, silently ignoring the rest if it happened to match more
+  // than one element. That was a real gap, not a deliberate "one region
+  // only" design: switched to querySelectorAll for both forms so
+  // "matches this selector" actually means all matches, consistently.
+  // Shared with frame-scan.js (same resolution used to discover which
+  // child <iframe>/<frame> elements fall within the same scan scope).
+  const { ctxSelector, roots } = resolveContextRoots(document, contextSelector);
+
+  // Default on: opt OUT with `includeShadowDom: false`, not opt in.
+  const includeShadowDom = !(
+    engineOptionsResolved && engineOptionsResolved.includeShadowDom === false
+  );
+  // Default off: hidden/collapsed content is excluded from rule evaluation
+  // unless the caller explicitly opts in.
+  const includeHiddenElements = !!(
+    engineOptionsResolved && engineOptionsResolved.includeHiddenElements === true
+  );
+  const excludeSelectors = normalizeSelectorList(
+    engineOptionsResolved && engineOptionsResolved.excludeSelectors
+  );
+  // Default off: explicit opt-in for "this scan target was never meant to
+  // represent a real page" -- see helpers.isWholeDocumentScope().
+  const fragment = !!(engineOptionsResolved && engineOptionsResolved.fragment === true);
+
+  const url = pageUrl || (document.location && document.location.href) || null;
+  const title = document.title || null;
+  // Deterministic timestamp: only use host-provided value (no time-based logic).
+  const timestamp =
+    engineOptionsResolved &&
+    typeof engineOptionsResolved.timestamp === 'string' &&
+    engineOptionsResolved.timestamp.trim()
+      ? engineOptionsResolved.timestamp.trim()
+      : null;
+
+  // createDomHelpers()/createContrastHelpers() persist their element-keyed
+  // caches (outerHtmlCache, selectorCache, etc.) on window.__a11ycoreSharedCache
+  // so multiple helper instances created *within this run* can share them
+  // deterministically. But a window/document is frequently reused across
+  // SEPARATE runs -- e.g. Jest's jsdom environment creates one window per
+  // test file, and mutating document.body between it() blocks is standard.
+  // Those caches are keyed by element reference, not content, so a run that
+  // reuses an already-cached element (document.body never changes identity)
+  // would otherwise read stale data cached by an earlier, unrelated run on
+  // the same window. Clearing at the start of every run keeps sharing scoped
+  // to "this run" as intended, without leaking across runs.
+  try {
+    if (window && window.__a11ycoreSharedCache) window.__a11ycoreSharedCache = {};
+  } catch {}
+
+  const sharedHelpers = createDomHelpers({
+    document,
+    window,
+    root: roots,
+    includeShadowDom,
+    includeHiddenElements,
+    excludeSelectors,
+    fragment,
+    // Optional perf counters (bench/debug only). Deterministic and per-run.
+    perfStats: !!(engineOptionsResolved && engineOptionsResolved.perfStats)
+  });
+
+  const profileRules = !!(engineOptionsResolved && engineOptionsResolved.profileRules);
+  const ruleTimings = profileRules ? Object.create(null) : null;
+
+  function nowMs() {
+    // performance.now() if available, else Date.now()
     try {
-        if (window && window.__a11ycoreSharedCache) window.__a11ycoreSharedCache = {};
-    } catch {}
-
-    const sharedHelpers = createDomHelpers({
-        document,
-        window,
-        root: roots,
-        includeShadowDom,
-        includeHiddenElements,
-        excludeSelectors,
-        // Optional perf counters (bench/debug only). Deterministic and per-run.
-        perfStats: !!(engineOptionsResolved && engineOptionsResolved.perfStats)
-    });
-
-    const profileRules = !!(engineOptionsResolved && engineOptionsResolved.profileRules);
-    const ruleTimings = profileRules ? Object.create(null) : null;
-
-    function nowMs() {
-        // performance.now() if available, else Date.now()
-        try {
-            if (typeof performance !== 'undefined' && performance && typeof performance.now === 'function') {
-                return performance.now();
-            }
-        } catch (e) {}
-        return Date.now();
+      if (
+        typeof performance !== 'undefined' &&
+        performance &&
+        typeof performance.now === 'function'
+      ) {
+        return performance.now();
+      }
+    } catch (e) {}
+    return Date.now();
+  }
+
+  // =========================
+  // Probes (optional evidence fed by the host app)
+  // Keep deterministic + serializable + no-throws.
+  // =========================
+  function sanitizeProbeValue(v, depth) {
+    // depth-bounded, JSON-safe sanitizer
+    if (depth <= 0) return null;
+    if (v == null) return null;
+
+    const t = typeof v;
+    if (t === 'string') return v.length > 2000 ? v.slice(0, 2000) : v;
+    if (t === 'number') return Number.isFinite(v) ? v : null;
+    if (t === 'boolean') return v;
+    if (t === 'function') return null;
+
+    if (Array.isArray(v)) {
+      // cap arrays to avoid huge payloads
+      const out = [];
+      const n = Math.min(v.length, 200);
+      for (let i = 0; i < n; i++) out.push(sanitizeProbeValue(v[i], depth - 1));
+      return out;
     }
 
-    // =========================
-    // Probes (optional evidence fed by the host app)
-    // Keep deterministic + serializable + no-throws.
-    // =========================
-    function sanitizeProbeValue(v, depth) {
-        // depth-bounded, JSON-safe sanitizer
-        if (depth <= 0) return null;
-        if (v == null) return null;
-
-        const t = typeof v;
-        if (t === 'string') return v.length > 2000 ? v.slice(0, 2000) : v;
-        if (t === 'number') return Number.isFinite(v) ? v : null;
-        if (t === 'boolean') return v;
-        if (t === 'function') return null;
-
-        if (Array.isArray(v)) {
-            // cap arrays to avoid huge payloads
-            const out = [];
-            const n = Math.min(v.length, 200);
-            for (let i = 0; i < n; i++) out.push(sanitizeProbeValue(v[i], depth - 1));
-            return out;
-        }
+    if (t === 'object') {
+      const out = {};
+      const keys = Object.keys(v).sort();
+      // cap object keys
+      const n = Math.min(keys.length, 50);
+      for (let i = 0; i < n; i++) {
+        const k = keys[i];
+        // only allow string keys
+        if (typeof k !== 'string') continue;
+        out[k] = sanitizeProbeValue(v[k], depth - 1);
+      }
+      return out;
+    }
 
-        if (t === 'object') {
-            const out = {};
-            const keys = Object.keys(v).sort();
-            // cap object keys
-            const n = Math.min(keys.length, 50);
-            for (let i = 0; i < n; i++) {
-                const k = keys[i];
-                // only allow string keys
-                if (typeof k !== 'string') continue;
-                out[k] = sanitizeProbeValue(v[k], depth - 1);
-            }
-            return out;
+    return null;
+  }
+
+  let probes;
+  try {
+    const rawProbes =
+      engineOptionsResolved && typeof engineOptionsResolved.probes === 'object'
+        ? engineOptionsResolved.probes
+        : null;
+    probes = rawProbes ? sanitizeProbeValue(rawProbes, 6) : null;
+    if (!probes || typeof probes !== 'object' || Array.isArray(probes)) probes = null;
+  } catch (e) {
+    probes = null;
+  }
+
+  // =========================
+  // Runtime custom rules (engineOptions.customRules)
+  // =========================
+  // Same module shape as an internal rule file: { id, meta, runInPage, applicability?, data? }.
+  // runInPage/applicability may be a real function (fine for same-realm/Node/jsdom callers)
+  // or a function-source string (required for cross-realm callers, e.g. a Playwright
+  // page.evaluate(runa11yCoreInPage, { engineOptions }) call -- engineOptions crosses a
+  // structured-clone/JSON boundary there, so a live Function reference can't survive it,
+  // but a string can). Reconstructed via `new Function`, matching exactly how build-core.js
+  // already embeds each built-in rule's own runInPage source into the in-page runner.
+  // Scan-scoped only (not added to the static CHECK_DEFS/getRulesCatalog() catalog) --
+  // matches surea11y's existing "fresh engineOptions per call, no mutable global config"
+  // design (see ROADMAP.md), rather than a widely-used reference engine's stateful global configure().
+  let effectiveCheckDefs = CHECK_DEFS;
+  let effectiveRuleImpls = RULE_IMPLS;
+  let overriddenBuiltinIds = [];
+  const rawCustomRules = Array.isArray(engineOptionsResolved.customRules)
+    ? engineOptionsResolved.customRules
+    : [];
+  if (rawCustomRules.length) {
+    function reviveRuleFn(value) {
+      if (typeof value === 'function') return value;
+      if (typeof value === 'string' && value.trim()) {
+        try {
+          const fn = new Function('return (' + value + ')')();
+          if (typeof fn === 'function') return fn;
+        } catch (e) {
+          return null;
         }
-
-        return null;
+      }
+      return null;
     }
 
-    let probes = null;
-    try {
-        const rawProbes = engineOptionsResolved && typeof engineOptionsResolved.probes === 'object' ? engineOptionsResolved.probes : null;
-        probes = rawProbes ? sanitizeProbeValue(rawProbes, 6) : null;
-        if (!probes || typeof probes !== 'object' || Array.isArray(probes)) probes = null;
-    } catch (e) {
-        probes = null;
+    const extraDefsById = new Map();
+    const extraImpls = {};
+    for (const c of rawCustomRules) {
+      if (!c || typeof c !== 'object') continue;
+      const ruleId = typeof c.id === 'string' ? c.id.trim() : '';
+      if (!ruleId) continue;
+      const runFn = reviveRuleFn(c.runInPage);
+      if (typeof runFn !== 'function') continue; // invalid custom rule: skipped, not a crash
+
+      const applicabilityFn = reviveRuleFn(c.applicability);
+      const normalizedMeta = normalizeRuleMeta(ruleId, ruleId, c.meta, ENGINE_TAG);
+
+      // Overriding a built-in rule id is supported (see docs/ENGINE_OPTIONS.md),
+      // but a same-named custom rule is just as likely to be an accidental
+      // collision (a generic name like "region" or "tabindex" picked without
+      // realizing it's already a built-in id) as a deliberate override -- so
+      // surface it either way rather than silently swapping the rule out.
+      if (CHECK_DEFS.some((d) => d && d.ruleId === ruleId)) {
+        overriddenBuiltinIds.push(ruleId);
+      }
+
+      extraDefsById.set(ruleId, {
+        ruleId,
+        title: normalizedMeta.title,
+        description: normalizedMeta.description,
+        i18n: normalizedMeta.i18n,
+        helpUrl: normalizedMeta.helpUrl,
+        tags: normalizedMeta.tags,
+        wcagSc: normalizedMeta.wcagSc,
+        normativeMappings: normalizedMeta.normativeMappings,
+        defaultSeverity: normalizedMeta.defaultSeverity,
+        defaultConfidence: normalizedMeta.defaultConfidence,
+        type: normalizedMeta.type,
+        coverage: normalizedMeta.coverage,
+        data: c.data === undefined ? null : c.data,
+        ruleInterfaceVersion: normalizedMeta.ruleInterfaceVersion,
+        ruleVersion: normalizedMeta.ruleVersion,
+        normative: normalizedMeta.normative,
+        atomic: normalizedMeta.atomic,
+        deprecated: normalizedMeta.deprecated,
+        deprecation: normalizedMeta.deprecation,
+        category: normalizedMeta.category,
+        standard: normalizedMeta.standard,
+        applicability: normalizedMeta.applicability,
+        expectation: normalizedMeta.expectation,
+        references: normalizedMeta.references,
+        requirements: normalizedMeta.requirements,
+        mappings: normalizedMeta.mappings
+      });
+      extraImpls[ruleId] = { run: runFn, applicability: applicabilityFn || null };
     }
 
-    // =========================
-    // Runtime custom rules (engineOptions.customRules)
-    // =========================
-    // Same module shape as an internal rule file: { id, meta, runInPage, applicability?, data? }.
-    // runInPage/applicability may be a real function (fine for same-realm/Node/jsdom callers)
-    // or a function-source string (required for cross-realm callers, e.g. a Playwright
-    // page.evaluate(runa11yCoreInPage, { engineOptions }) call -- engineOptions crosses a
-    // structured-clone/JSON boundary there, so a live Function reference can't survive it,
-    // but a string can). Reconstructed via `new Function`, matching exactly how build-core.js
-    // already embeds each built-in rule's own runInPage source into the in-page runner.
-    // Scan-scoped only (not added to the static CHECK_DEFS/getRulesCatalog() catalog) --
-    // matches surea11y's existing "fresh engineOptions per call, no mutable global config"
-    // design (see ROADMAP.md), rather than a widely-used reference engine's stateful global configure().
-    let effectiveCheckDefs = CHECK_DEFS;
-    let effectiveRuleImpls = RULE_IMPLS;
-    let overriddenBuiltinIds = [];
-    const rawCustomRules = Array.isArray(engineOptionsResolved.customRules) ? engineOptionsResolved.customRules : [];
-    if (rawCustomRules.length) {
-        function reviveRuleFn(value) {
-            if (typeof value === 'function') return value;
-            if (typeof value === 'string' && value.trim()) {
-                try {
-                    const fn = new Function('return (' + value + ')')();
-                    if (typeof fn === 'function') return fn;
-                } catch (e) {
-                    return null;
-                }
-            }
-            return null;
-        }
-
-        const extraDefsById = new Map();
-        const extraImpls = {};
-        for (const c of rawCustomRules) {
-            if (!c || typeof c !== 'object') continue;
-            const ruleId = typeof c.id === 'string' ? c.id.trim() : '';
-            if (!ruleId) continue;
-            const runFn = reviveRuleFn(c.runInPage);
-            if (typeof runFn !== 'function') continue; // invalid custom rule: skipped, not a crash
-
-            const applicabilityFn = reviveRuleFn(c.applicability);
-            const normalizedMeta = normalizeRuleMeta(ruleId, ruleId, c.meta, ENGINE_TAG);
-
-            // Overriding a built-in rule id is supported (see docs/ENGINE_OPTIONS.md),
-            // but a same-named custom rule is just as likely to be an accidental
-            // collision (a generic name like "region" or "tabindex" picked without
-            // realizing it's already a built-in id) as a deliberate override -- so
-            // surface it either way rather than silently swapping the rule out.
-            if (CHECK_DEFS.some((d) => d && d.ruleId === ruleId)) {
-                overriddenBuiltinIds.push(ruleId);
-            }
-
-            extraDefsById.set(ruleId, {
-                ruleId,
-                title: normalizedMeta.title,
-                description: normalizedMeta.description,
-                i18n: normalizedMeta.i18n,
-                helpUrl: normalizedMeta.helpUrl,
-                tags: normalizedMeta.tags,
-                wcagSc: normalizedMeta.wcagSc,
-                normativeMappings: normalizedMeta.normativeMappings,
-                defaultSeverity: normalizedMeta.defaultSeverity,
-                defaultConfidence: normalizedMeta.defaultConfidence,
-                type: normalizedMeta.type,
-                coverage: normalizedMeta.coverage,
-                data: (c.data === undefined ? null : c.data),
-                ruleInterfaceVersion: normalizedMeta.ruleInterfaceVersion,
-                ruleVersion: normalizedMeta.ruleVersion,
-                normative: normalizedMeta.normative,
-                atomic: normalizedMeta.atomic,
-                category: normalizedMeta.category,
-                standard: normalizedMeta.standard,
-                applicability: normalizedMeta.applicability,
-                expectation: normalizedMeta.expectation,
-                references: normalizedMeta.references,
-                requirements: normalizedMeta.requirements,
-                mappings: normalizedMeta.mappings
-            });
-            extraImpls[ruleId] = { run: runFn, applicability: applicabilityFn || null };
-        }
-
-        if (extraDefsById.size) {
-            effectiveCheckDefs = CHECK_DEFS
-                .filter((d) => !extraDefsById.has(d.ruleId))
-                .concat(Array.from(extraDefsById.values()));
-            effectiveRuleImpls = { ...RULE_IMPLS, ...extraImpls };
-        }
-
-        if (overriddenBuiltinIds.length) {
-            try {
-                console.warn('[surea11y] customRules overriding built-in rule id(s) for this scan: ' + overriddenBuiltinIds.join(', '));
-            } catch (e) {}
-        }
+    if (extraDefsById.size) {
+      effectiveCheckDefs = CHECK_DEFS.filter((d) => !extraDefsById.has(d.ruleId)).concat(
+        Array.from(extraDefsById.values())
+      );
+      effectiveRuleImpls = { ...RULE_IMPLS, ...extraImpls };
     }
 
-    const checksResults = [];
-
-    for (const def of effectiveCheckDefs) {
-        const t0 = ruleTimings ? nowMs() : 0;
-        const defResolved = resolveRuleDefI18n(def, engineOptionsResolved);
-        if (!ruleMatchesRunOnly(defResolved, runOnly, ENGINE_TAG)) continue;
-
-        const implEntry = effectiveRuleImpls[defResolved.ruleId];
-        const impl = implEntry && typeof implEntry.run === 'function' ? implEntry.run : null;
-        const applicabilityFn = implEntry && typeof implEntry.applicability === 'function' ? implEntry.applicability : null;
-        if (typeof impl !== 'function') continue;
-
-        const ruleConfig =
-            engineOptionsResolved && engineOptionsResolved.rules && engineOptionsResolved.rules[defResolved.ruleId]
-                ? engineOptionsResolved.rules[defResolved.ruleId]
-                : null;
-
-        // Rule-scoped excludeSelectors (engineOptions.rules[ruleId].excludeSelectors)
-        // apply on top of the global excludeSelectors for exactly this rule's
-        // applicability check + run, then are cleared once this rule is done.
-        // Safe because rule execution below is synchronous and one rule at a
-        // time -- sharedHelpers is reused across all rules in this loop.
-        if (typeof sharedHelpers.__setActiveRuleExcludeSelectors === 'function') {
-            sharedHelpers.__setActiveRuleExcludeSelectors(ruleConfig && ruleConfig.excludeSelectors);
-        }
-
-        const ctx = {
-            document,
-            window,
-            root: roots,
-            rule: defResolved,
-            config: ruleConfig,
-            helpers: sharedHelpers,
-            engineTag: ENGINE_TAG,
-            contextSelector: ctxSelector,
-            engineOptions: (engineOptionsResolved && typeof engineOptionsResolved === 'object') ? engineOptionsResolved : {},
-
-            // Optional evidence channel provided by host app
-            inputs: {
-                probes
-            }
-        };
-
-        if (typeof applicabilityFn === 'function') {
-            let applicable = true;
-            try {
-                const res = applicabilityFn(ctx);
-                if (typeof res === 'boolean') applicable = res;
-                else if (res && typeof res === 'object' && typeof res.applicable === 'boolean') applicable = res.applicable;
-            } catch (err) {
-                const raw = {
-                    outcome: 'cantTell',
-                    occurrences: [],
-                    error: String(err && err.message ? err.message : err),
-                    engineOptions: { ...(ctx.engineOptions || {}), locale: normalizeLocale(engineOptionsResolved && engineOptionsResolved.locale) }
-                };
-                checksResults.push(normalizeRuleResult(defResolved, raw, SCHEMA_VERSION, policy, sharedHelpers));
-                if (ruleTimings) ruleTimings[defResolved.ruleId] = (ruleTimings[defResolved.ruleId] || 0) + (nowMs() - t0);
-                continue;
-            }
-
-            if (!applicable) {
-                const raw = {
-                    outcome: 'notApplicable',
-                    occurrences: [],
-                    engineOptions: { ...(ctx.engineOptions || {}), locale: normalizeLocale(engineOptionsResolved && engineOptionsResolved.locale) }
-                };
-                checksResults.push(normalizeRuleResult(defResolved, raw, SCHEMA_VERSION, policy, sharedHelpers));
-                if (ruleTimings) ruleTimings[defResolved.ruleId] = (ruleTimings[defResolved.ruleId] || 0) + (nowMs() - t0);
-                continue;
-            }
-        }
-
-        let result;
-        try {
-            result = impl(ctx);
-        } catch (err) {
-            result = {
-                outcome: 'cantTell',
-                occurrences: [],
-                error: String(err && err.message ? err.message : err),
-                engineOptions: { ...(ctx.engineOptions || {}), locale: normalizeLocale(engineOptionsResolved && engineOptionsResolved.locale) }
-            };
-        }
-
-        if (!result || typeof result !== 'object') {
-            if (ruleTimings) ruleTimings[defResolved.ruleId] = (ruleTimings[defResolved.ruleId] || 0) + (nowMs() - t0);
-            continue;
-        }
-        if (!result.engineOptions) {
-            result.engineOptions = { ...(ctx.engineOptions || {}), locale: normalizeLocale(engineOptionsResolved && engineOptionsResolved.locale) };
-        }
-        checksResults.push(normalizeRuleResult(defResolved, result, SCHEMA_VERSION, policy, sharedHelpers));
-        if (ruleTimings) ruleTimings[defResolved.ruleId] = (ruleTimings[defResolved.ruleId] || 0) + (nowMs() - t0);
+    if (overriddenBuiltinIds.length) {
+      try {
+        console.warn(
+          '[surea11y] customRules overriding built-in rule id(s) for this scan: ' +
+            overriddenBuiltinIds.join(', ')
+        );
+      } catch (e) {}
     }
-
-    // Composite rollups below carry no occurrences/nodes of their own, so
-    // they never exercise rule-scoped excludes -- but clear the "active
-    // rule" state on sharedHelpers regardless, so nothing after this point
-    // (composite aggregation, perf stats) can observe a stale rule's excludes.
+  }
+
+  const checksResults = [];
+
+  for (const def of effectiveCheckDefs) {
+    const t0 = ruleTimings ? nowMs() : 0;
+    const defResolved = resolveRuleDefI18n(def, engineOptionsResolved);
+    if (!ruleMatchesRunOnly(defResolved, runOnly, ENGINE_TAG)) continue;
+
+    const implEntry = effectiveRuleImpls[defResolved.ruleId];
+    const impl = implEntry && typeof implEntry.run === 'function' ? implEntry.run : null;
+    const applicabilityFn =
+      implEntry && typeof implEntry.applicability === 'function' ? implEntry.applicability : null;
+    if (typeof impl !== 'function') continue;
+
+    const ruleConfig =
+      engineOptionsResolved &&
+      engineOptionsResolved.rules &&
+      engineOptionsResolved.rules[defResolved.ruleId]
+        ? engineOptionsResolved.rules[defResolved.ruleId]
+        : null;
+
+    // Rule-scoped excludeSelectors (engineOptions.rules[ruleId].excludeSelectors)
+    // apply on top of the global excludeSelectors for exactly this rule's
+    // applicability check + run, then are cleared once this rule is done.
+    // Safe because rule execution below is synchronous and one rule at a
+    // time -- sharedHelpers is reused across all rules in this loop.
     if (typeof sharedHelpers.__setActiveRuleExcludeSelectors === 'function') {
-        sharedHelpers.__setActiveRuleExcludeSelectors(null);
+      sharedHelpers.__setActiveRuleExcludeSelectors(ruleConfig && ruleConfig.excludeSelectors);
     }
 
-    // =========================
-    // Composite rule aggregation (data-only rollups)
-    // =========================
-    const rulesResults = [];
-    try {
-        const composites = Array.isArray(COMPOSITE_RULES) ? COMPOSITE_RULES : [];
-
-        // Determine target conformance level from runOnly.tags (already normalized by caller)
-        const LEVEL_RANK = { A: 1, AA: 2, AAA: 3 };
-
-        function inferTargetLevelFromRunOnly(runOnly2) {
-            const tags = runOnly2 && Array.isArray(runOnly2.tags) ? runOnly2.tags : [];
-            // tags are already lowercase
-            if (tags.includes('wcag2aaa') || tags.includes('wcag22aaa') || tags.includes('wcag21aaa')) return 'AAA';
-            if (tags.includes('wcag2aa') || tags.includes('wcag22aa') || tags.includes('wcag21aa')) return 'AA';
-            if (tags.includes('wcag2a') || tags.includes('wcag22a') || tags.includes('wcag21a')) return 'A';
-            return null; // if not specified, don't filter composites (back-compat)
-        }
+    const ctx = {
+      document,
+      window,
+      root: roots,
+      rule: defResolved,
+      config: ruleConfig,
+      helpers: sharedHelpers,
+      engineTag: ENGINE_TAG,
+      contextSelector: ctxSelector,
+      engineOptions:
+        engineOptionsResolved && typeof engineOptionsResolved === 'object'
+          ? engineOptionsResolved
+          : {},
+
+      // Optional evidence channel provided by host app
+      inputs: {
+        probes
+      }
+    };
 
-        function normalizeLevel(s) {
-            const v = typeof s === 'string' ? s.trim().toUpperCase() : '';
-            return (v === 'A' || v === 'AA' || v === 'AAA') ? v : null;
-        }
+    if (typeof applicabilityFn === 'function') {
+      let applicable = true;
+      try {
+        const res = applicabilityFn(ctx);
+        if (typeof res === 'boolean') applicable = res;
+        else if (res && typeof res === 'object' && typeof res.applicable === 'boolean')
+          applicable = res.applicable;
+      } catch (err) {
+        const raw = {
+          outcome: 'cantTell',
+          occurrences: [],
+          error: String(err && err.message ? err.message : err),
+          engineOptions: {
+            ...(ctx.engineOptions || {}),
+            locale: normalizeLocale(engineOptionsResolved && engineOptionsResolved.locale)
+          }
+        };
+        checksResults.push(
+          normalizeRuleResult(defResolved, raw, SCHEMA_VERSION, policy, sharedHelpers)
+        );
+        if (ruleTimings)
+          ruleTimings[defResolved.ruleId] = (ruleTimings[defResolved.ruleId] || 0) + (nowMs() - t0);
+        continue;
+      }
+
+      if (!applicable) {
+        const raw = {
+          outcome: 'notApplicable',
+          occurrences: [],
+          engineOptions: {
+            ...(ctx.engineOptions || {}),
+            locale: normalizeLocale(engineOptionsResolved && engineOptionsResolved.locale)
+          }
+        };
+        checksResults.push(
+          normalizeRuleResult(defResolved, raw, SCHEMA_VERSION, policy, sharedHelpers)
+        );
+        if (ruleTimings)
+          ruleTimings[defResolved.ruleId] = (ruleTimings[defResolved.ruleId] || 0) + (nowMs() - t0);
+        continue;
+      }
+    }
 
-        function isAllowedByTargetLevel(compositeLevel, targetLevel) {
-            if (!targetLevel) return true;
-            const c = LEVEL_RANK[compositeLevel];
-            const t = LEVEL_RANK[targetLevel];
-            if (!c || !t) return false; // unknown level => safest: exclude
-            return c <= t;
+    let result;
+    try {
+      result = impl(ctx);
+    } catch (err) {
+      result = {
+        outcome: 'cantTell',
+        occurrences: [],
+        error: String(err && err.message ? err.message : err),
+        engineOptions: {
+          ...(ctx.engineOptions || {}),
+          locale: normalizeLocale(engineOptionsResolved && engineOptionsResolved.locale)
         }
+      };
+    }
 
-        const targetLevel = inferTargetLevelFromRunOnly(runOnly);
+    if (!result || typeof result !== 'object') {
+      if (ruleTimings)
+        ruleTimings[defResolved.ruleId] = (ruleTimings[defResolved.ruleId] || 0) + (nowMs() - t0);
+      continue;
+    }
+    if (!result.engineOptions) {
+      result.engineOptions = {
+        ...(ctx.engineOptions || {}),
+        locale: normalizeLocale(engineOptionsResolved && engineOptionsResolved.locale)
+      };
+    }
+    checksResults.push(
+      normalizeRuleResult(defResolved, result, SCHEMA_VERSION, policy, sharedHelpers)
+    );
+    if (ruleTimings)
+      ruleTimings[defResolved.ruleId] = (ruleTimings[defResolved.ruleId] || 0) + (nowMs() - t0);
+  }
+
+  // Composite rollups below carry no occurrences/nodes of their own, so
+  // they never exercise rule-scoped excludes -- but clear the "active
+  // rule" state on sharedHelpers regardless, so nothing after this point
+  // (composite aggregation, perf stats) can observe a stale rule's excludes.
+  if (typeof sharedHelpers.__setActiveRuleExcludeSelectors === 'function') {
+    sharedHelpers.__setActiveRuleExcludeSelectors(null);
+  }
+
+  // =========================
+  // Composite rule aggregation (data-only rollups)
+  // =========================
+  const rulesResults = [];
+  try {
+    const composites = Array.isArray(COMPOSITE_RULES) ? COMPOSITE_RULES : [];
+
+    // Determine target conformance level from runOnly.tags (already normalized by caller)
+    const LEVEL_RANK = { A: 1, AA: 2, AAA: 3 };
+
+    function inferTargetLevelFromRunOnly(runOnly2) {
+      const tags = runOnly2 && Array.isArray(runOnly2.tags) ? runOnly2.tags : [];
+      // tags are already lowercase
+      if (tags.includes('wcag2aaa') || tags.includes('wcag22aaa') || tags.includes('wcag21aaa'))
+        return 'AAA';
+      if (tags.includes('wcag2aa') || tags.includes('wcag22aa') || tags.includes('wcag21aa'))
+        return 'AA';
+      if (tags.includes('wcag2a') || tags.includes('wcag22a') || tags.includes('wcag21a'))
+        return 'A';
+      return null; // if not specified, don't filter composites (back-compat)
+    }
 
-        // Severity rollup (deterministic)
-        const SEVERITY_RANK = { minor: 1, moderate: 2, serious: 3, critical: 4 };
+    function normalizeLevel(s) {
+      const v = typeof s === 'string' ? s.trim().toUpperCase() : '';
+      return v === 'A' || v === 'AA' || v === 'AAA' ? v : null;
+    }
 
-        function normalizeSeverity(s) {
-            const v = typeof s === 'string' ? s.trim().toLowerCase() : '';
-            return SEVERITY_RANK[v] ? v : null;
-        }
+    function isAllowedByTargetLevel(compositeLevel, targetLevel) {
+      if (!targetLevel) return true;
+      const c = LEVEL_RANK[compositeLevel];
+      const t = LEVEL_RANK[targetLevel];
+      if (!c || !t) return false; // unknown level => safest: exclude
+      return c <= t;
+    }
 
-        function maxSeverity(a, b) {
-            if (!a) return b || null;
-            if (!b) return a || null;
-            return (SEVERITY_RANK[b] > SEVERITY_RANK[a]) ? b : a;
-        }
+    const targetLevel = inferTargetLevelFromRunOnly(runOnly);
 
-        // Index atomic results by ruleId (deterministic)
-        const byRuleId = Object.create(null);
-        for (const rr of checksResults) {
-            if (rr && typeof rr === 'object' && typeof rr.ruleId === 'string' && rr.ruleId) {
-                byRuleId[rr.ruleId] = rr;
-            }
-        }
+    // Severity rollup (deterministic)
+    const SEVERITY_RANK = { minor: 1, moderate: 2, serious: 3, critical: 4 };
 
-        function isNonEmptyString(s) {
-            return typeof s === 'string' && !!s.trim();
-        }
+    function normalizeSeverity(s) {
+      const v = typeof s === 'string' ? s.trim().toLowerCase() : '';
+      return SEVERITY_RANK[v] ? v : null;
+    }
 
-        function buildCompositeDef(entry) {
-            if (!entry || typeof entry !== 'object') return null;
-
-            const ruleId = isNonEmptyString(entry.id) ? entry.id.trim() : String(entry.id || '').trim();
-            if (!ruleId) return null;
-
-            const metaIn = (entry.meta && typeof entry.meta === 'object' && !Array.isArray(entry.meta)) ? entry.meta : {};
-
-            const titleKey = (typeof metaIn.titleKey === 'string' && metaIn.titleKey.trim()) ? metaIn.titleKey.trim() : '';
-            const descriptionKey = (typeof metaIn.descriptionKey === 'string' && metaIn.descriptionKey.trim()) ? metaIn.descriptionKey.trim() : '';
-
-            const wcagSc = Array.isArray(metaIn.wcagSc) ? metaIn.wcagSc.map(String).map(s => s.trim()).filter(Boolean) : [];
-
-            const tags = [];
-            tags.push(String(ENGINE_TAG || 'a11ycore').toLowerCase());
-            tags.push('composite');
-
-            // Fixed WCAG-version-introduction lists (2.1 and 2.2 additions only -- every other
-            // SC, including all pre-2.1 ones, is WCAG 2.0 baseline). Keep in sync with
-            // src/coverage/wcag-version-map.js (the canonical copy the rule-authoring
-            // consistency test checks against) -- this one has to stay a self-contained
-            // literal since runCore is inlined via .toString() with no module access at runtime.
-            const WCAG21_NEW_SCS = ['1.3.4', '1.3.5', '1.3.6', '1.4.10', '1.4.11', '1.4.12', '1.4.13', '2.1.4', '2.2.6', '2.3.3', '2.5.1', '2.5.2', '2.5.3', '2.5.4', '2.5.5', '2.5.6', '4.1.3'];
-            const WCAG22_NEW_SCS = ['2.4.11', '2.4.12', '2.4.13', '2.5.7', '2.5.8', '3.2.6', '3.3.7', '3.3.8', '3.3.9'];
-            const isWcag22Sc = wcagSc.some((sc) => WCAG22_NEW_SCS.includes(sc));
-            const isWcag21Sc = !isWcag22Sc && wcagSc.some((sc) => WCAG21_NEW_SCS.includes(sc));
-            const versionTagPrefix = isWcag22Sc ? 'wcag22' : (isWcag21Sc ? 'wcag21' : 'wcag2');
-
-            const lvl = (typeof metaIn.level === 'string' ? metaIn.level.trim().toUpperCase() : '');
-            if (lvl === 'A') {
-                tags.push(versionTagPrefix + 'a');
-            } else if (lvl === 'AA') {
-                tags.push(versionTagPrefix + 'a', versionTagPrefix + 'aa');
-            } else if (lvl === 'AAA') {
-                tags.push(versionTagPrefix + 'a', versionTagPrefix + 'aa', versionTagPrefix + 'aaa');
-            }
+    function maxSeverity(a, b) {
+      if (!a) return b || null;
+      if (!b) return a || null;
+      return SEVERITY_RANK[b] > SEVERITY_RANK[a] ? b : a;
+    }
 
-            // Build normativeMappings so downstream consumers (like adapters) can derive WCAG SC/level
-            const normativeMappingsFromMeta = wcagSc.map((sc) => {
-                const m = { standard: 'WCAG', requirement: sc };
-                if (lvl === 'A' || lvl === 'AA' || lvl === 'AAA') m.level = lvl;
-                return m;
-            });
-
-            const checksIds =
-                Array.isArray(entry.checksIds)
-                    ? entry.checksIds.map(String).map(s => s.trim()).filter(Boolean)
-                    : [];
-
-            return {
-                ruleId,
-                title: metaIn.title || ruleId,
-                description: metaIn.description || '',
-
-                i18n: (titleKey || descriptionKey) ? { titleKey: titleKey || '', descriptionKey: descriptionKey || '' } : null,
-
-                helpUrl: '',
-                tags,
-
-                normativeMappings: normativeMappingsFromMeta,
-
-                defaultSeverity: 'serious',
-                defaultConfidence: 'medium',
-                type: 'automatic',
-                coverage: null,
-
-                ruleInterfaceVersion: '1.0.0',
-                ruleVersion: '0.0.0',
-                normative: true,
-                atomic: false,
-                category: null,
-                standard: null,
-                applicability: '',
-                expectation: '',
-                references: [],
-                requirements: null,
-                mappings: null,
-
-                // optional catalog meta passthrough
-                data: {
-                    details: {
-                        kind: 'compositeRule',
-                        wcagSc,
-                        level: (typeof metaIn.level === 'string' && metaIn.level.trim()) ? metaIn.level.trim() : null
-                    }
-                },
-
-                __checksIds: checksIds
-            };
-        }
+    // Index atomic results by ruleId (deterministic)
+    const byRuleId = Object.create(null);
+    for (const rr of checksResults) {
+      if (rr && typeof rr === 'object' && typeof rr.ruleId === 'string' && rr.ruleId) {
+        byRuleId[rr.ruleId] = rr;
+      }
+    }
 
-        for (let i = 0; i < composites.length; i++) {
-            const entry = composites[i];
-            const cDef0 = buildCompositeDef(entry);
-            if (!cDef0) continue;
+    function isNonEmptyString(s) {
+      return typeof s === 'string' && !!s.trim();
+    }
 
-            // Conformance-level gate: if scan is AA, suppress AAA composites even if tags match
-            const compositeLevel =
-                cDef0 &&
-                cDef0.data &&
-                cDef0.data.details &&
-                normalizeLevel(cDef0.data.details.level);
+    function buildCompositeDef(entry) {
+      if (!entry || typeof entry !== 'object') return null;
+
+      const ruleId = isNonEmptyString(entry.id) ? entry.id.trim() : String(entry.id || '').trim();
+      if (!ruleId) return null;
+
+      const metaIn =
+        entry.meta && typeof entry.meta === 'object' && !Array.isArray(entry.meta)
+          ? entry.meta
+          : {};
+
+      const titleKey =
+        typeof metaIn.titleKey === 'string' && metaIn.titleKey.trim() ? metaIn.titleKey.trim() : '';
+      const descriptionKey =
+        typeof metaIn.descriptionKey === 'string' && metaIn.descriptionKey.trim()
+          ? metaIn.descriptionKey.trim()
+          : '';
+
+      const wcagSc = Array.isArray(metaIn.wcagSc)
+        ? metaIn.wcagSc
+            .map(String)
+            .map((s) => s.trim())
+            .filter(Boolean)
+        : [];
+
+      const tags = [];
+      tags.push(String(ENGINE_TAG || 'a11ycore').toLowerCase());
+      tags.push('composite');
+
+      // Fixed WCAG-version-introduction lists (2.1 and 2.2 additions only -- every other
+      // SC, including all pre-2.1 ones, is WCAG 2.0 baseline). Keep in sync with
+      // src/coverage/wcag-version-map.js (the canonical copy the rule-authoring
+      // consistency test checks against) -- this one has to stay a self-contained
+      // literal since runCore is inlined via .toString() with no module access at runtime.
+      const WCAG21_NEW_SCS = [
+        '1.3.4',
+        '1.3.5',
+        '1.3.6',
+        '1.4.10',
+        '1.4.11',
+        '1.4.12',
+        '1.4.13',
+        '2.1.4',
+        '2.2.6',
+        '2.3.3',
+        '2.5.1',
+        '2.5.2',
+        '2.5.3',
+        '2.5.4',
+        '2.5.5',
+        '2.5.6',
+        '4.1.3'
+      ];
+      const WCAG22_NEW_SCS = [
+        '2.4.11',
+        '2.4.12',
+        '2.4.13',
+        '2.5.7',
+        '2.5.8',
+        '3.2.6',
+        '3.3.7',
+        '3.3.8',
+        '3.3.9'
+      ];
+      const isWcag22Sc = wcagSc.some((sc) => WCAG22_NEW_SCS.includes(sc));
+      const isWcag21Sc = !isWcag22Sc && wcagSc.some((sc) => WCAG21_NEW_SCS.includes(sc));
+      const versionTagPrefix = isWcag22Sc ? 'wcag22' : isWcag21Sc ? 'wcag21' : 'wcag2';
+
+      const lvl = typeof metaIn.level === 'string' ? metaIn.level.trim().toUpperCase() : '';
+      if (lvl === 'A') {
+        tags.push(versionTagPrefix + 'a');
+      } else if (lvl === 'AA') {
+        tags.push(versionTagPrefix + 'a', versionTagPrefix + 'aa');
+      } else if (lvl === 'AAA') {
+        tags.push(versionTagPrefix + 'a', versionTagPrefix + 'aa', versionTagPrefix + 'aaa');
+      }
+
+      // Build normativeMappings so downstream consumers (like adapters) can derive WCAG SC/level
+      const normativeMappingsFromMeta = wcagSc.map((sc) => {
+        const m = { standard: 'WCAG', requirement: sc };
+        if (lvl === 'A' || lvl === 'AA' || lvl === 'AAA') m.level = lvl;
+        return m;
+      });
+
+      const checksIds = Array.isArray(entry.checksIds)
+        ? entry.checksIds
+            .map(String)
+            .map((s) => s.trim())
+            .filter(Boolean)
+        : [];
+
+      return {
+        ruleId,
+        title: metaIn.title || ruleId,
+        description: metaIn.description || '',
+
+        i18n:
+          titleKey || descriptionKey
+            ? { titleKey: titleKey || '', descriptionKey: descriptionKey || '' }
+            : null,
+
+        helpUrl: '',
+        tags,
+
+        normativeMappings: normativeMappingsFromMeta,
+
+        defaultSeverity: 'serious',
+        defaultConfidence: 'medium',
+        type: 'automatic',
+        coverage: null,
+
+        ruleInterfaceVersion: '1.0.0',
+        ruleVersion: '0.0.0',
+        normative: true,
+        atomic: false,
+        deprecated: false,
+        deprecation: null,
+        category: null,
+        standard: null,
+        applicability: '',
+        expectation: '',
+        references: [],
+        requirements: null,
+        mappings: null,
+
+        // optional catalog meta passthrough
+        data: {
+          details: {
+            kind: 'compositeRule',
+            wcagSc,
+            level:
+              typeof metaIn.level === 'string' && metaIn.level.trim() ? metaIn.level.trim() : null
+          }
+        },
+
+        __checksIds: checksIds
+      };
+    }
 
-            if (!isAllowedByTargetLevel(compositeLevel, targetLevel)) continue;
+    for (let i = 0; i < composites.length; i++) {
+      const entry = composites[i];
+      const cDef0 = buildCompositeDef(entry);
+      if (!cDef0) continue;
 
-            // Localize title/description (uses def.i18n.* keys)
-            const cDefResolved = resolveRuleDefI18n(cDef0, engineOptionsResolved);
+      // Conformance-level gate: if scan is AA, suppress AAA composites even if tags match
+      const compositeLevel =
+        cDef0 && cDef0.data && cDef0.data.details && normalizeLevel(cDef0.data.details.level);
 
-            // Apply same selection logic to composites
-            if (!ruleMatchesRunOnly(cDefResolved, runOnly, ENGINE_TAG)) continue;
+      if (!isAllowedByTargetLevel(compositeLevel, targetLevel)) continue;
 
-            const checksIds = Array.isArray(cDef0.__checksIds) ? cDef0.__checksIds : [];
+      // Localize title/description (uses def.i18n.* keys)
+      const cDefResolved = resolveRuleDefI18n(cDef0, engineOptionsResolved);
 
-            // rollup metrics (stable order)
-            let failCount = 0;
-            let cantTellCount = 0;
-            let notApplicableCount = 0;
-            let passCount = 0;
-            let missingCount = 0;
+      // Apply same selection logic to composites
+      if (!ruleMatchesRunOnly(cDefResolved, runOnly, ENGINE_TAG)) continue;
 
-            const contributors = [];
+      const checksIds = Array.isArray(cDef0.__checksIds) ? cDef0.__checksIds : [];
 
-            let rolledFailSeverity = null;     // max severity among FAIL contributors
-            let rolledCantTellSeverity = null; // max severity among CANTTELL contributors (optional)
+      // rollup metrics (stable order)
+      let failCount = 0;
+      let cantTellCount = 0;
+      let notApplicableCount = 0;
+      let passCount = 0;
+      let missingCount = 0;
 
-            for (let j = 0; j < checksIds.length; j++) {
-                const tid = checksIds[j];
-                const child = tid ? byRuleId[tid] : null;
+      const contributors = [];
 
-                if (!child) {
-                    missingCount += 1;
-                    contributors.push({ testId: tid, outcome: 'missing' });
-                    continue;
-                }
+      let rolledFailSeverity = null; // max severity among FAIL contributors
+      let rolledCantTellSeverity = null; // max severity among CANTTELL contributors (optional)
 
-                const out = child.outcome;
-                const childSev = normalizeSeverity(child && child.severity);
+      for (let j = 0; j < checksIds.length; j++) {
+        const tid = checksIds[j];
+        const child = tid ? byRuleId[tid] : null;
 
-                contributors.push({ testId: tid, outcome: out, severity: childSev || null });
+        if (!child) {
+          missingCount += 1;
+          contributors.push({ testId: tid, outcome: 'missing' });
+          continue;
+        }
 
-                if (out === 'fail' && childSev) {
-                    rolledFailSeverity = maxSeverity(rolledFailSeverity, childSev);
-                } else if (out === 'cantTell' && childSev) {
-                    rolledCantTellSeverity = maxSeverity(rolledCantTellSeverity, childSev);
-                }
+        const out = child.outcome;
+        const childSev = normalizeSeverity(child && child.severity);
 
-                if (out === 'fail') failCount += 1;
-                else if (out === 'cantTell') cantTellCount += 1;
-                else if (out === 'notApplicable') notApplicableCount += 1;
-                else if (out === 'pass') passCount += 1;
-            }
+        contributors.push({ testId: tid, outcome: out, severity: childSev || null });
 
-            // outcome precedence:
-            // fail if any fail
-            // cantTell if any cantTell OR missing and none fail
-            // notApplicable if all notApplicable (and there is at least one test)
-            // pass otherwise
-            let outcome = 'pass';
-            let reasonCode = 'composite.rollup.pass.otherwise';
-
-            if (failCount > 0) {
-                outcome = 'fail';
-                reasonCode = 'composite.rollup.fail.anyFail';
-            } else if (cantTellCount > 0) {
-                outcome = 'cantTell';
-                reasonCode = 'composite.rollup.cantTell.anyCantTell';
-            } else if (missingCount > 0) {
-                outcome = 'cantTell';
-                reasonCode = 'composite.rollup.cantTell.missingChild';
-            } else if (checksIds.length > 0 && notApplicableCount === checksIds.length) {
-                outcome = 'notApplicable';
-                reasonCode = 'composite.rollup.notApplicable.allInapplicable';
-            } else if (checksIds.length === 0) {
-                outcome = 'cantTell';
-                reasonCode = 'composite.rollup.cantTell.emptyComposite';
-            }
+        if (out === 'fail' && childSev) {
+          rolledFailSeverity = maxSeverity(rolledFailSeverity, childSev);
+        } else if (out === 'cantTell' && childSev) {
+          rolledCantTellSeverity = maxSeverity(rolledCantTellSeverity, childSev);
+        }
 
-            const raw = {
-                outcome,
-                occurrences: [],
-
-                // REQUIRED by your reporting schema (top-level)
-                summaryKey: 'Composite rule rollup',
-                i18nKey: 'composite_rollup_summary',
-                i18nParams: { reasonCode, testCount: String(checksIds.length) },
-
-                // REQUIRED by your reporting schema (machine-readable payload)
-                data: {
-                    details: {
-                        reasonCode,
-                        checksIds: checksIds.slice(),
-                        contributors,
-                        metrics: {
-                            failCount,
-                            cantTellCount,
-                            notApplicableCount,
-                            passCount,
-                            missingCount
-                        }
-                    }
-                },
-
-                engineOptions: {
-                    ...(engineOptionsResolved || {}),
-                    locale: normalizeLocale(engineOptionsResolved && engineOptionsResolved.locale)
-                }
-            };
-
-            // Promote composite severity based on contributors (deterministic).
-            // - If composite fails: use max severity among failing children.
-            // - If composite cantTell: use max severity among cantTell children (fallback to failing if you prefer).
-            if (outcome === 'fail' && rolledFailSeverity) {
-                raw.severity = rolledFailSeverity;
-            } else if (outcome === 'cantTell' && rolledCantTellSeverity) {
-                raw.severity = rolledCantTellSeverity;
+        if (out === 'fail') failCount += 1;
+        else if (out === 'cantTell') cantTellCount += 1;
+        else if (out === 'notApplicable') notApplicableCount += 1;
+        else if (out === 'pass') passCount += 1;
+      }
+
+      // outcome precedence:
+      // fail if any fail
+      // cantTell if any cantTell OR missing and none fail
+      // notApplicable if all notApplicable (and there is at least one test)
+      // pass otherwise
+      let outcome = 'pass';
+      let reasonCode = 'composite.rollup.pass.otherwise';
+
+      if (failCount > 0) {
+        outcome = 'fail';
+        reasonCode = 'composite.rollup.fail.anyFail';
+      } else if (cantTellCount > 0) {
+        outcome = 'cantTell';
+        reasonCode = 'composite.rollup.cantTell.anyCantTell';
+      } else if (missingCount > 0) {
+        outcome = 'cantTell';
+        reasonCode = 'composite.rollup.cantTell.missingChild';
+      } else if (checksIds.length > 0 && notApplicableCount === checksIds.length) {
+        outcome = 'notApplicable';
+        reasonCode = 'composite.rollup.notApplicable.allInapplicable';
+      } else if (checksIds.length === 0) {
+        outcome = 'cantTell';
+        reasonCode = 'composite.rollup.cantTell.emptyComposite';
+      }
+
+      const raw = {
+        outcome,
+        occurrences: [],
+
+        // REQUIRED by your reporting schema (top-level)
+        summaryKey: 'Composite rule rollup',
+        i18nKey: 'composite_rollup_summary',
+        i18nParams: { reasonCode, testCount: String(checksIds.length) },
+
+        // REQUIRED by your reporting schema (machine-readable payload)
+        data: {
+          details: {
+            reasonCode,
+            checksIds: checksIds.slice(),
+            contributors,
+            metrics: {
+              failCount,
+              cantTellCount,
+              notApplicableCount,
+              passCount,
+              missingCount
             }
+          }
+        },
 
-            rulesResults.push(normalizeRuleResult(cDefResolved, raw, SCHEMA_VERSION, policy, sharedHelpers));
+        engineOptions: {
+          ...(engineOptionsResolved || {}),
+          locale: normalizeLocale(engineOptionsResolved && engineOptionsResolved.locale)
         }
-    } catch (e) {
-        // no-throws: omit rulesResults if anything goes wrong
+      };
+
+      // Promote composite severity based on contributors (deterministic).
+      // - If composite fails: use max severity among failing children.
+      // - If composite cantTell: use max severity among cantTell children (fallback to failing if you prefer).
+      if (outcome === 'fail' && rolledFailSeverity) {
+        raw.severity = rolledFailSeverity;
+      } else if (outcome === 'cantTell' && rolledCantTellSeverity) {
+        raw.severity = rolledCantTellSeverity;
+      }
+
+      rulesResults.push(
+        normalizeRuleResult(cDefResolved, raw, SCHEMA_VERSION, policy, sharedHelpers)
+      );
     }
-
-    // Optional perf counters passthrough (only when enabled). Deterministic.
-    let perfStats = null;
-    try {
-        if (engineOptionsResolved && engineOptionsResolved.perfStats && sharedHelpers && typeof sharedHelpers.getPerfStats === 'function') {
-            perfStats = sharedHelpers.getPerfStats();
-        }
-    } catch (e) {
-        perfStats = null;
+  } catch (e) {
+    // no-throws: omit rulesResults if anything goes wrong
+  }
+
+  // Optional perf counters passthrough (only when enabled). Deterministic.
+  let perfStats = null;
+  try {
+    if (
+      engineOptionsResolved &&
+      engineOptionsResolved.perfStats &&
+      sharedHelpers &&
+      typeof sharedHelpers.getPerfStats === 'function'
+    ) {
+      perfStats = sharedHelpers.getPerfStats();
     }
+  } catch (e) {
+    perfStats = null;
+  }
 
-    if (ruleTimings) {
-        if (perfStats && engineOptionsResolved && engineOptionsResolved.profileRules) {
-            perfStats.ruleTimings = ruleTimings; // (whatever your timing map is)
-        }
+  if (ruleTimings) {
+    if (perfStats && engineOptionsResolved && engineOptionsResolved.profileRules) {
+      perfStats.ruleTimings = ruleTimings; // (whatever your timing map is)
     }
-
-    return {
-        engine: { tag: ENGINE_TAG, schemaVersion: SCHEMA_VERSION },
-        url,
-        title,
-        timestamp,
-        perfStats,
-        contextSelector: ctxSelector,
-        checksResults,
-        rulesResults,
-        overriddenBuiltinIds
-    };
+  }
+
+  return {
+    engine: { tag: ENGINE_TAG, schemaVersion: SCHEMA_VERSION },
+    url,
+    title,
+    timestamp,
+    perfStats,
+    contextSelector: ctxSelector,
+    checksResults,
+    rulesResults,
+    overriddenBuiltinIds
+  };
 }
 
 module.exports = { runCore };