arkgate 4.6.7 → 4.7.0

package/bin/lib/extra-merge-teeth.mjs

@@ -0,0 +1,187 @@
+/**
+ * GENERATED FILE — do not edit by hand.
+ *
+ * Canonical algorithm: src/domain/extraMergeTeeth.ts
+ * Regenerate: node scripts/generate-cli-pure.mjs
+ * Drift check: node scripts/generate-cli-pure.mjs --check
+ *
+ * Pure CLI helper (bin/lib/extra-merge-teeth.mjs). Zero Node I/O.
+ */
+
+export const EXTRA_MERGE_TEETH_GOVERNED_FLOOR = 50;
+export function normalizeExtraMergeTeethClassification(classification) {
+    if (!classification)
+        return {};
+    const governedPercent = typeof classification.governedPercent === 'number' ? classification.governedPercent : null;
+    let populatedLayerCount = typeof classification.populatedLayerCount === 'number'
+        ? classification.populatedLayerCount
+        : null;
+    if (populatedLayerCount == null &&
+        typeof classification.classifiedFiles === 'number') {
+        populatedLayerCount = classification.classifiedFiles > 0 ? 1 : 0;
+    }
+    return { governedPercent, populatedLayerCount };
+}
+export function extraMergeTeethAllowed(classification) {
+    const normalized = normalizeExtraMergeTeethClassification(classification);
+    const governed = typeof normalized.governedPercent === 'number' ? normalized.governedPercent : null;
+    const populated = typeof normalized.populatedLayerCount === 'number' ? normalized.populatedLayerCount : null;
+    if (governed == null && populated == null)
+        return true;
+    return ((governed ?? 0) >= EXTRA_MERGE_TEETH_GOVERNED_FLOOR && (populated ?? 0) >= 1);
+}
+export function classifyResolvedLayerCoverage(files) {
+    const total = files.length;
+    let classified = 0;
+    const populated = new Set();
+    for (const file of files) {
+        const layer = typeof file.layer === 'string' && file.layer.length > 0 ? file.layer : null;
+        if (!layer)
+            continue;
+        classified += 1;
+        populated.add(layer);
+    }
+    return {
+        governedPercent: total > 0 ? Math.round((classified / total) * 100) : 0,
+        populatedLayerCount: populated.size,
+    };
+}
+export function isArkRunRuleId(ruleId) {
+    return typeof ruleId === 'string' && ruleId.startsWith('ARKRUN_');
+}
+export function isExtraPlaneFinding(violation) {
+    if (violation?.arkruleId != null)
+        return true;
+    const id = typeof violation?.ruleId === 'string' ? violation.ruleId : '';
+    return id.startsWith('ARKRULE') || id.startsWith('arkrule') || id.startsWith('ARKRUN_');
+}
+/**
+ * Under the classification floor, demote enforced extra-plane findings in place
+ * so merge/write/CI match (layer graph only). Unknown classification is a no-op.
+ */
+export function demoteExtraPlaneTeethUnderClassificationFloor(violations, classification = {}) {
+    if (!Array.isArray(violations))
+        return violations;
+    if (extraMergeTeethAllowed(classification))
+        return violations;
+    for (const violation of violations) {
+        if (isExtraPlaneFinding(violation) && violation.failsStrict !== false) {
+            violation.failsStrict = false;
+            if (violation.severity === 'error')
+                violation.severity = 'warning';
+        }
+    }
+    return violations;
+}
+/** Stamp for extra-plane honesty: never one architecture score. */
+export const MERGE_PLANES_DUAL_STAMP = 'Structure = heuristics; invariants = catalog+coverage evidence (not business runtime); ArkRun = kernel usage + declarations (not a score). Extra planes never merge into one architecture score. Advisory ArkRules ≠ merge teeth. Advisory ArkRun ≠ merge teeth.';
+function countOrZero(value) {
+    return typeof value === 'number' && Number.isFinite(value) && value > 0 ? Math.floor(value) : 0;
+}
+/**
+ * Which extra planes can fail merge. Counts and stamps only — never a score.
+ */
+export function composeMergePlanesHonesty(input = {}) {
+    const normalized = normalizeExtraMergeTeethClassification(input.classification);
+    const governedPercent = typeof normalized.governedPercent === 'number' ? normalized.governedPercent : null;
+    const populatedLayerCount = typeof normalized.populatedLayerCount === 'number' ? normalized.populatedLayerCount : null;
+    const classificationKnown = governedPercent != null || populatedLayerCount != null;
+    const classificationAllowsTeeth = extraMergeTeethAllowed(normalized);
+    const arkRules = input.arkRules;
+    const structureEnforced = countOrZero(arkRules?.structureEnforced);
+    const structureTotal = countOrZero(arkRules?.structureTotal);
+    const structureAdvisory = typeof arkRules?.structureAdvisory === 'number'
+        ? countOrZero(arkRules.structureAdvisory)
+        : Math.max(0, structureTotal - structureEnforced);
+    const invariantEnforced = countOrZero(arkRules?.invariantEnforced);
+    const invariantTotal = countOrZero(arkRules?.invariantTotal);
+    const invariantAdvisory = typeof arkRules?.invariantAdvisory === 'number'
+        ? countOrZero(arkRules.invariantAdvisory)
+        : Math.max(0, invariantTotal - invariantEnforced);
+    const arkRulesHasEnforced = structureEnforced > 0 || invariantEnforced > 0;
+    const arkRunPresent = input.arkRun?.present === true;
+    const arkRunMode = input.arkRun?.mode === 'enforced' || input.arkRun?.mode === 'advisory'
+        ? input.arkRun.mode
+        : null;
+    const arkRunResidual = countOrZero(input.arkRun?.residualCount);
+    const arkRunHasEnforced = arkRunPresent && arkRunMode === 'enforced';
+    const arkRunTeeth = arkRunHasEnforced && classificationAllowsTeeth;
+    const hasEnforcedTeeth = arkRulesHasEnforced || arkRunHasEnforced;
+    const extraMergeTeeth = hasEnforcedTeeth && classificationAllowsTeeth;
+    const teethDeferredForClassification = hasEnforcedTeeth && classificationKnown && !classificationAllowsTeeth;
+    let failMergeWhen;
+    if (extraMergeTeeth) {
+        const extras = [];
+        if (arkRulesHasEnforced)
+            extras.push('enforced structure/invariant findings');
+        if (arkRunHasEnforced)
+            extras.push('enforced ArkRun skip findings');
+        failMergeWhen = `Layer graph failures plus ${extras.join(' and ')} (advisory extras never fail merge alone).`;
+    }
+    else if (teethDeferredForClassification) {
+        const which = [
+            arkRulesHasEnforced ? 'ArkRules structure/invariant' : null,
+            arkRunHasEnforced ? 'ArkRun' : null,
+        ]
+            .filter((part) => Boolean(part))
+            .join(' and ');
+        failMergeWhen = `Layer graph only — enforced ${which} findings are demoted under the teeth floor (need ≥${EXTRA_MERGE_TEETH_GOVERNED_FLOOR}% governed and ≥1 populated layer); they do not merge-block until classification is honest.`;
+    }
+    else {
+        const arkRunBit = !arkRunPresent
+            ? ' Absence of arkRun is silent.'
+            : arkRunMode === 'advisory'
+                ? ' Advisory ArkRun never merge-blocks.'
+                : ' ArkRun extra is present but does not arm merge teeth.';
+        failMergeWhen =
+            'Layer graph only — no enforced ArkRules structure/invariant teeth on this tree. Advisory packs do not arm merge teeth.' +
+                arkRunBit;
+    }
+    const out = {
+        layers: {
+            role: 'inter-layer-edges',
+            alwaysOnGate: true,
+            note: 'Import/export layer graph — the default merge plane. Absent arkRules or arkRun changes nothing here.',
+        },
+        structureSensors: {
+            role: 'intra-layer-heuristics',
+            total: structureTotal,
+            enforced: structureEnforced,
+            advisory: structureAdvisory,
+            note: 'Structure sensors are heuristics (prefer false negatives). Only mode:enforced fails merge; noisy sensors stay advisory by default. Advisory-only packs never add merge teeth (FG-ARKRULES-ADVISORY-ONLY).',
+        },
+        invariants: {
+            role: 'catalog-plus-coverage',
+            total: invariantTotal,
+            enforced: invariantEnforced,
+            advisory: invariantAdvisory,
+            covered: countOrZero(arkRules?.covered),
+            uncovered: countOrZero(arkRules?.uncovered),
+            note: 'Invariants are catalog + coverage evidence, not a business runtime. Enforced + proven-uncovered fails merge; absence of enforced rules adds no extra teeth.',
+        },
+        arkRun: {
+            role: 'kernel-usage-and-declarations',
+            present: arkRunPresent,
+            mode: arkRunMode,
+            residualCount: arkRunResidual,
+            extraMergeTeeth: arkRunTeeth,
+            note: arkRunPresent
+                ? arkRunMode === 'enforced'
+                    ? 'Enforced ArkRun arms extra merge teeth only when the layer plane is classified. Residual is a count, never a score.'
+                    : 'Advisory ArkRun never adds merge teeth and never flips valid. Residual is a count, never a score.'
+                : 'Absence of arkRun is silent — Layers and ArkRules verdicts unchanged. The extra never becomes a score.',
+        },
+        extraMergeTeeth,
+        dualPlaneStamp: MERGE_PLANES_DUAL_STAMP,
+        failMergeWhen,
+    };
+    if (classificationKnown) {
+        out.classificationGate = {
+            governedPercent,
+            populatedLayerCount,
+            floorPercent: EXTRA_MERGE_TEETH_GOVERNED_FLOOR,
+            allowsTeeth: classificationAllowsTeeth,
+        };
+    }
+    return out;
+}

package/bin/lib/html-report-advisories.mjs

@@ -10,6 +10,7 @@
 import { effectiveCapabilityDeny } from './analysis-engine.mjs';
 import { graphBlindSpotsHtml } from './graph-blind.mjs';
 import { formatRulesUnderContractHtml } from './rules-under-contract.mjs';
+import { formatArkRunHtml } from './ark-run-report.mjs';
 import { primaryImprovementCompassNextAction } from './improvement-compass.mjs';
 
 // htmlEscape is injected by the caller (html-report.mjs) — importing it back
@@ -351,6 +352,7 @@ export function renderAdvisorySections(advisories, escape) {
     parseHealthHtml(advisories.parseHealth),
     graphBlindSpotsHtml(advisories.graphBlindSpots, esc),
     rulesUnderContractHtml(advisories.rulesUnderContract),
+    formatArkRunHtml(advisories.arkRun, esc),
   ]
     .filter(Boolean)
     .join('\n');

package/bin/lib/html-report-depth.mjs

@@ -19,6 +19,7 @@ import {
   buildProductHonesty,
 } from './enforcement-honesty.mjs';
 import { summarizeRulesUnderContract } from './rules-under-contract.mjs';
+import { summarizeArkRunSection } from './ark-run-doctor.mjs';
 import { readBaseline, baselineOccurrenceKeys } from './violations.mjs';
 import { describePackageVersionDualTruth } from './field-install.mjs';
 import { buildDoctorImprovementCompass } from './improvement-compass-doctor.mjs';
@@ -127,13 +128,31 @@ export function buildReportDepthPayload(
       packageVersionTruth?.selfHost === true ||
       packageVersionTruth?.code === 'PACKAGE_PIN_SELF_HOST',
   });
-  const rulesUnderContract = summarizeRulesUnderContract(root, config, undefined, {
+  const classification = {
     governedPercent: coverage?.governed?.percent ?? null,
     populatedLayerCount: Array.isArray(coverage?.layers)
       ? coverage.layers.filter((row) => (row?.files ?? 0) > 0).length
       : null,
     classifiedFiles: coverage?.governed?.classifiedFiles ?? null,
+  };
+  const rulesUnderContract = summarizeRulesUnderContract(root, config, undefined, classification);
+  const arkRun = summarizeArkRunSection({
+    arkRun: config?.arkRun,
+    findings: activeViolations,
+    classification,
+    arkRules: {
+      active: rulesUnderContract?.active === true,
+      structureEnforced: rulesUnderContract?.mergePlanes?.structureSensors?.enforced,
+      structureTotal: rulesUnderContract?.mergePlanes?.structureSensors?.total,
+      structureAdvisory: rulesUnderContract?.mergePlanes?.structureSensors?.advisory,
+      invariantEnforced: rulesUnderContract?.mergePlanes?.invariants?.enforced,
+      invariantTotal: rulesUnderContract?.mergePlanes?.invariants?.total,
+      invariantAdvisory: rulesUnderContract?.mergePlanes?.invariants?.advisory,
+      covered: rulesUnderContract?.mergePlanes?.invariants?.covered,
+      uncovered: rulesUnderContract?.mergePlanes?.invariants?.uncovered,
+    },
   });
+  if (rulesUnderContract?.mergePlanes) rulesUnderContract.mergePlanes = arkRun.mergePlanes;
   // Single residual expression (parity with doctor): nextPilot || extractionCard.
   const residualPilot =
     pilotLoop?.nextPilot || pilotLoop?.extractionCard || null;
@@ -155,7 +174,7 @@ export function buildReportDepthPayload(
     residualPilots: Boolean(residualPilot) && designFitness.designWeak === true,
     pilotTarget: residualPilot?.pilotTarget ?? residualPilot?.pilot ?? null,
     arkRulesMergeHonesty: rulesUnderContract?.mergePlanes
-      ? { active: rulesUnderContract.active === true, ...rulesUnderContract.mergePlanes }
+      ? { active: rulesUnderContract.active === true || arkRun?.active === true, ...rulesUnderContract.mergePlanes }
       : null,
     primaryNextAction: postGreenPath?.action ?? dualTruthNext,
     activeBlockingViolations: activeBlockingCount,
@@ -198,6 +217,7 @@ export function buildReportDepthPayload(
       // P0-B / P1-M — folded into designDepth so --report stays a single payload.
       productHonesty,
       mergePlanes: rulesUnderContract?.mergePlanes ?? null,
+      arkRun,
       improvementCompass,
       deepModuleCoach,
     },

package/bin/lib/html-report.mjs

@@ -149,6 +149,8 @@ export function buildReportSnapshot({
   mode,
   /** DF02 — thin status compass slice (mode + residual ids, notAScore). */
   improvementCompass = null,
+  /** RN08 — thin status ArkRun slice (notAScore; residual count, never a score). */
+  arkRun = null,
 }) {
   const layers = Array.isArray(config?.layers) ? config.layers : [];
   const rules = Array.isArray(config?.rules) ? config.rules : [];
@@ -196,6 +198,20 @@ export function buildReportSnapshot({
   if (improvementCompass && typeof improvementCompass === 'object') {
     snapshot.improvementCompass = improvementCompass;
   }
+  if (arkRun && typeof arkRun === 'object' && arkRun.notAScore === true) {
+    snapshot.arkRun = {
+      notAScore: true,
+      present: arkRun.active === true || arkRun.present === true,
+      mode: arkRun.mode === 'enforced' || arkRun.mode === 'advisory' ? arkRun.mode : null,
+      extraMergeTeeth: arkRun.extraMergeTeeth === true,
+      residual:
+        typeof arkRun.residual === 'number'
+          ? arkRun.residual
+          : typeof arkRun.residual?.count === 'number'
+            ? arkRun.residual.count
+            : null,
+    };
+  }
   return snapshot;
 }
 

package/bin/lib/remediation.mjs

@@ -19,6 +19,7 @@ export const MECHANICAL_SAFE_KINDS = [
     'type-only-import-move',
     'import-type-from-pure-type-module',
     'import-type-of-type-exports',
+    'arkrun-declaration-list',
     // port-proof-inject-binding is intentionally NOT mechanical-safe (signature change).
 ];
 /**
@@ -40,6 +41,7 @@ export const KNOWN_FIX_CLASSES = [
     'intent-relocation',
     'break-cycle',
     'review-contract',
+    'arkrun-usage',
 ];
 const PURE_SHARED_RE = /(^|\/)(constants|types|enums|shared-types|shared\/(?:types|constants)|test-projects)(\/|\.|$)|(?:^|\/)[^/]*(?:constants|types)(?:\.[cm]?[jt]sx?)?$/i;
 const KERNEL_EMIT_RE = /(^|\/)(?:kernel(?:\/|$)|events?(?:\/|\.|$)|bootstrap(?:\.[cm]?[jt]sx?)?$|emitter(?:\.[cm]?[jt]sx?)?$)|(?:^|\/)(?:intents?|publish)(?:\/|\.|$)/i;
@@ -87,6 +89,101 @@ export function layerImportNextAction(violation) {
     }
     return 'Classify the import: if it is constants/types/pure, adopt into DomainModel or SharedKernel; define a port only if the target is a real use-case. Then preflight again.';
 }
+const ARKRUN_UNDECLARED_RULE_IDS = new Set([
+    'ARKRUN_UNDECLARED_EMIT',
+    'ARKRUN_UNDECLARED_HANDLE',
+    'ARKRUN_UNDECLARED_DEPEND',
+]);
+const ARKRUN_JUDGMENT_RULE_IDS = new Set([
+    'ARKRUN_MISSING_ROOT',
+    'ARKRUN_KERNEL_IN_DOMAIN',
+    'ARKRUN_DIRECT_NEW',
+    'ARKRUN_TRANSPORT_BYPASS',
+]);
+function arkRunCallSiteName(violation) {
+    return typeof violation.target === 'string' && violation.target.trim().length > 0
+        ? violation.target.trim()
+        : undefined;
+}
+function isArkRunDeclarationListSafe(violation) {
+    return (typeof violation.ruleId === 'string' &&
+        ARKRUN_UNDECLARED_RULE_IDS.has(violation.ruleId) &&
+        arkRunCallSiteName(violation) !== undefined);
+}
+/** Catalog `fix` is the no-target form; a present `target` specializes it. */
+function arkRunNextAction(violation) {
+    const target = arkRunCallSiteName(violation);
+    const fromLayer = typeof violation.fromLayer === 'string' && violation.fromLayer.length > 0
+        ? violation.fromLayer
+        : undefined;
+    switch (violation.ruleId) {
+        case 'ARKRUN_MISSING_ROOT':
+            return target
+                ? `Import createStrictArkKernel from @arkgate/runtime and call it in composition root ${target} listed in arkRun.compositionRoots, then preflight again.`
+                : 'Import createStrictArkKernel from @arkgate/runtime (never a removed arkgate/runtime shim) and call it in a composition root listed in arkRun.compositionRoots, then preflight again. Never mechanical-safe — factory placement is a design decision.';
+        case 'ARKRUN_KERNEL_IN_DOMAIN':
+            return target
+                ? `Move the kernel import of ${target} out of ${fromLayer ?? 'the Domain-role layer'} into a composition root or adapter. Import from @arkgate/runtime, never a removed arkgate/runtime shim, then preflight again.`
+                : 'Move the kernel import out of the Domain-role layer into a composition root or adapter. Import from @arkgate/runtime, never a removed arkgate/runtime shim, then preflight again. Never mechanical-safe.';
+        case 'ARKRUN_DIRECT_NEW':
+            return target
+                ? `Resolve ${target} from the kernel instead of constructing it with new, then preflight again.`
+                : 'Resolve the type from the kernel instead of constructing it with new, then preflight again. Never mechanical-safe — rewiring construction is a design decision.';
+        case 'ARKRUN_UNDECLARED_EMIT':
+            return target
+                ? `Add ${target} to raises or sends on the managed component, then preflight again.`
+                : 'Add the existing call-site name to raises or sends on the managed component, then preflight again. Mechanical-safe only when that literal already exists and the edit is the declaration list; inventing a new emit stays judgment.';
+        case 'ARKRUN_UNDECLARED_HANDLE':
+            return target
+                ? `Add ${target} to reactsTo on the managed component, then preflight again.`
+                : 'Add the existing call-site name to reactsTo on the managed component, then preflight again. Mechanical-safe only when that literal already exists and the edit is the declaration list; inventing a new handle stays judgment.';
+        case 'ARKRUN_UNDECLARED_DEPEND':
+            return target
+                ? `Add ${target} to uses on the managed component, then preflight again.`
+                : 'Add the existing call-site name to uses on the managed component, then preflight again. Mechanical-safe only when that literal already exists and the edit is the declaration list; inventing a new depend stays judgment.';
+        case 'ARKRUN_TRANSPORT_BYPASS':
+            return target
+                ? `Send through the ArkRun kernel transport instead of importing ${target}, then preflight again.`
+                : 'Send through the ArkRun kernel transport instead of importing that broker or emitter, then preflight again. Never mechanical-safe — homemade buses stay judgment.';
+        default:
+            return `Resolve ${typeof violation.ruleId === 'string' && violation.ruleId.length > 0 ? violation.ruleId : 'ARK_UNKNOWN'} without weakening ark.config.json, then run Ark again.`;
+    }
+}
+function arkRunEnthusiastHint(violation) {
+    const target = arkRunCallSiteName(violation);
+    switch (violation.ruleId) {
+        case 'ARKRUN_MISSING_ROOT':
+            return target
+                ? `Call createStrictArkKernel from @arkgate/runtime in ${target} so the app actually uses the kernel.`
+                : 'Call createStrictArkKernel from @arkgate/runtime in a listed composition root so the app actually uses the kernel.';
+        case 'ARKRUN_KERNEL_IN_DOMAIN':
+            return target
+                ? `Domain stays kernel-free. Move the ${target} import to a composition root or adapter — never a removed arkgate/runtime shim.`
+                : 'Domain stays kernel-free. Move that @arkgate/runtime import to a composition root or adapter — never a removed arkgate/runtime shim.';
+        case 'ARKRUN_DIRECT_NEW':
+            return target
+                ? `Do not construct ${target} with new. Resolve it from the kernel instead.`
+                : 'Do not construct that managed type with new. Resolve it from the kernel instead.';
+        case 'ARKRUN_UNDECLARED_EMIT':
+            return target
+                ? `Add "${target}" to raises or sends. Do not invent a new emit.`
+                : 'Add the name you already publish to raises or sends. Do not invent a new emit.';
+        case 'ARKRUN_UNDECLARED_HANDLE':
+            return target
+                ? `Add "${target}" to reactsTo. Do not invent a new handle.`
+                : 'Add the name you already subscribe to reactsTo.';
+        case 'ARKRUN_UNDECLARED_DEPEND':
+            return target
+                ? `Add "${target}" to uses. Do not invent a new depend.`
+                : 'Add the name you already resolve to uses.';
+        case 'ARKRUN_TRANSPORT_BYPASS':
+            return target
+                ? `Do not import ${target} here. Send through the ArkRun kernel transport.`
+                : 'Do not import that broker or EventEmitter here. Send through the ArkRun kernel transport.';
+        default:
+            return 'Read the ArkRun finding and use the kernel instead of skipping it.';
+    }
+}
 /** One deterministic re-entry action shared by human and machine denial surfaces. */
 export function deterministicNextAction(violation) {
     switch (violation.ruleId) {
@@ -110,6 +207,14 @@ export function deterministicNextAction(violation) {
                 : 'the ArkRule'} (declared in ${typeof violation.arkruleSource === 'string' && violation.arkruleSource.length > 0
                 ? violation.arkruleSource
                 : 'arkrules/<Layer>.json'}), then preflight again. Do not demote the rule without a hash-bound policy acknowledgement.`;
+        case 'ARKRUN_MISSING_ROOT':
+        case 'ARKRUN_KERNEL_IN_DOMAIN':
+        case 'ARKRUN_DIRECT_NEW':
+        case 'ARKRUN_UNDECLARED_EMIT':
+        case 'ARKRUN_UNDECLARED_HANDLE':
+        case 'ARKRUN_UNDECLARED_DEPEND':
+        case 'ARKRUN_TRANSPORT_BYPASS':
+            return arkRunNextAction(violation);
         default:
             if (typeof violation.ruleId === 'string' && violation.ruleId.startsWith('ARKRULE_')) {
                 return `Fix the ArkRule ${typeof violation.arkruleId === 'string' ? violation.arkruleId : violation.ruleId}, then preflight again.`;
@@ -226,6 +331,22 @@ export function classifyRemediation(violation) {
             rationale: 'ArkRule structure/invariant findings are never mechanical-safe — restore private state, factory shape, event publish, coverage, or redesign the aggregate with judgment.',
         };
     }
+    if (violation && isArkRunDeclarationListSafe(violation)) {
+        return {
+            class: 'mechanical-safe',
+            confidence: 0.9,
+            remediationKind: 'arkrun-declaration-list',
+            rationale: 'Call-site literal already exists; adding it to the declaration list is behavior-preserving. Inventing a new emit/handle/depend stays judgment.',
+        };
+    }
+    if (typeof ruleId === 'string' &&
+        (ARKRUN_JUDGMENT_RULE_IDS.has(ruleId) || ARKRUN_UNDECLARED_RULE_IDS.has(ruleId))) {
+        return {
+            class: 'judgment',
+            confidence: 0.85,
+            rationale: 'ArkRun usage, construction, and homemade-transport findings are never mechanical-safe. Declaration-list edits are mechanical-safe only when the call-site literal is already present as target.',
+        };
+    }
     if (typeof ruleId === 'string' && ruleId.length > 0) {
         return {
             class: 'judgment',
@@ -338,6 +459,17 @@ export function enrichViolationWithFixClass(violation) {
             enriched.enthusiastHint =
                 'Two modules import each other in a loop. Extract shared code, invert one dependency behind a port, or merge them if they are really one unit.';
             break;
+        case 'ARKRUN_MISSING_ROOT':
+        case 'ARKRUN_KERNEL_IN_DOMAIN':
+        case 'ARKRUN_DIRECT_NEW':
+        case 'ARKRUN_UNDECLARED_EMIT':
+        case 'ARKRUN_UNDECLARED_HANDLE':
+        case 'ARKRUN_UNDECLARED_DEPEND':
+        case 'ARKRUN_TRANSPORT_BYPASS':
+            enriched.fixClass = 'arkrun-usage';
+            enriched.effort = ARKRUN_UNDECLARED_RULE_IDS.has(violation.ruleId ?? '') ? 'small' : 'medium';
+            enriched.enthusiastHint = arkRunEnthusiastHint(violation);
+            break;
         default:
             enriched.fixClass = 'review-contract';
             enriched.effort = 'small';

package/bin/lib/resolved-candidate-facts.mjs

@@ -8,7 +8,7 @@
 import fs from 'node:fs';
 import path from 'node:path';
 
-import { isScanExcludedRelative } from '../ark-shared.mjs';
+import { globToRegExp, isScanExcludedRelative } from '../ark-shared.mjs';
 import {
   AMBIENT_CAPABILITY_ENTRIES,
   collectCapabilityUses,
@@ -35,6 +35,11 @@ import {
 } from './ast-scan.mjs';
 import { provePortProofInject } from './port-proof.mjs';
 import { extractClassShapesFromSource } from './arkrules-sensors.mjs';
+import {
+  extractArkRunDeclarationsFromSource,
+  extractArkRunKernelCallsFromSource,
+  extractArkRunManagedNewsFromSource,
+} from './ark-run-facts.mjs';
 import {
   collectGovernedFiles,
   isGovernableSourceFile,
@@ -998,6 +1003,12 @@ export function resolveCandidateFacts({
   const safetyUses = [];
   /** ADR 0013 class-shape facts for ArkRules structure sensors. */
   const classShapes = [];
+  /** ADR 0022 / RN03 — syntax evidence only; sensors emit in RN04. */
+  const arkRunKernelCalls = [];
+  const arkRunManagedNews = [];
+  const arkRunCompositionRootHits = [];
+  const arkRunDeclarations = [];
+  const compositionRootPatterns = [...(config.arkRun?.compositionRoots ?? [])];
 
   for (const candidate of candidateFiles) {
     const sourceFile = ts.createSourceFile(
@@ -1087,6 +1098,56 @@ export function resolveCandidateFacts({
       } catch {
         // Never fail the resolver for shape extraction; sensors stay silent on this file.
       }
+      try {
+        arkRunKernelCalls.push(
+          ...extractArkRunKernelCallsFromSource(candidate.path, candidate.content)
+        );
+      } catch {
+        // Never fail the resolver for ArkRun call extraction.
+      }
+      try {
+        arkRunDeclarations.push(
+          ...extractArkRunDeclarationsFromSource(candidate.path, candidate.content)
+        );
+      } catch {
+        // Never fail the resolver for ArkRun declaration extraction.
+      }
+    }
+  }
+
+  const admittedTypeNames = new Set(classShapes.map((shape) => shape.className));
+  for (const candidate of candidateFiles) {
+    if (!/\.(tsx?|mts|cts)$/i.test(candidate.path)) continue;
+    try {
+      arkRunManagedNews.push(
+        ...extractArkRunManagedNewsFromSource(
+          candidate.path,
+          candidate.content,
+          admittedTypeNames
+        )
+      );
+    } catch {
+      // Never fail the resolver for managed-new extraction.
+    }
+  }
+
+  if (compositionRootPatterns.length > 0) {
+    const factoryFiles = new Set(
+      arkRunKernelCalls.filter((call) => call.kind === 'factory').map((call) => call.file)
+    );
+    for (const candidate of candidateFiles) {
+      for (const pattern of compositionRootPatterns) {
+        try {
+          if (!globToRegExp(pattern).test(candidate.path)) continue;
+        } catch {
+          continue;
+        }
+        arkRunCompositionRootHits.push({
+          file: candidate.path,
+          matchedRoot: pattern,
+          hasKernelFactory: factoryFiles.has(candidate.path),
+        });
+      }
     }
   }
 
@@ -1152,7 +1213,7 @@ export function resolveCandidateFacts({
 
   const projectPackageName = readPackageName(canonicalRoot, observeInput);
   return createTrustedResolvedCandidateFacts({
-    schemaVersion: '1.1',
+    schemaVersion: '1.2',
     completeness: completenessReasons.length === 0 ? 'complete' : 'partial',
     completenessReasons,
     resolverIdentity: RESOLVED_FACTS_RESOLVER_IDENTITY,
@@ -1169,5 +1230,9 @@ export function resolveCandidateFacts({
     intentReferences,
     safetyUses,
     classShapes,
+    arkRunKernelCalls,
+    arkRunManagedNews,
+    arkRunCompositionRootHits,
+    arkRunDeclarations,
   });
 }