arkgate 4.6.7 → 4.7.0

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

@@ -0,0 +1,309 @@
+/**
+ * GENERATED FILE — do not edit by hand.
+ *
+ * Canonical algorithm: src/domain/arkRunSensors.ts
+ * Regenerate: node scripts/generate-cli-pure.mjs
+ * Drift check: node scripts/generate-cli-pure.mjs --check
+ *
+ * Pure CLI helper (bin/lib/ark-run-sensors.mjs). Zero Node I/O.
+ */
+
+import { extractArkRunImportedConstructorNamesFromSource, extractArkRunKernelCallsFromSource, extractArkRunManagedNewsFromSource, extractArkRunValueImportDependenciesFromSource, isArkRunKernelModuleSpecifier, isArkRunTransportBypassSpecifier, } from './ark-run-facts.mjs';
+import { extraMergeTeethAllowed, } from './extra-merge-teeth.mjs';
+import { deterministicNextAction } from './remediation.mjs';
+export const ARKRUN_TIER1_SENSOR_IDS = [
+    'arkrun-missing-root',
+    'arkrun-kernel-in-domain',
+    'arkrun-direct-new',
+    'arkrun-undeclared-emit',
+    'arkrun-undeclared-handle',
+    'arkrun-undeclared-depend',
+    'arkrun-transport-bypass',
+];
+/**
+ * Import / `new` envelope for `arkgate/eslint`.
+ * Missing-root and undeclared-* stay CLI/MCP/preflight (project-wide or declaration facts).
+ */
+export const ARKRUN_EDITOR_SENSOR_IDS = [
+    'arkrun-kernel-in-domain',
+    'arkrun-direct-new',
+    'arkrun-transport-bypass',
+];
+const EDITOR_SENSOR_SET = new Set(ARKRUN_EDITOR_SENSOR_IDS);
+export function isArkRunEditorSensor(sensor) {
+    return EDITOR_SENSOR_SET.has(sensor);
+}
+export const ARKRUN_RULE_IDS = {
+    'arkrun-missing-root': 'ARKRUN_MISSING_ROOT',
+    'arkrun-kernel-in-domain': 'ARKRUN_KERNEL_IN_DOMAIN',
+    'arkrun-direct-new': 'ARKRUN_DIRECT_NEW',
+    'arkrun-undeclared-emit': 'ARKRUN_UNDECLARED_EMIT',
+    'arkrun-undeclared-handle': 'ARKRUN_UNDECLARED_HANDLE',
+    'arkrun-undeclared-depend': 'ARKRUN_UNDECLARED_DEPEND',
+    'arkrun-transport-bypass': 'ARKRUN_TRANSPORT_BYPASS',
+};
+export const ARKRUN_INTERACTION_NAME_INCOMPLETE = 'ARKRUN_INTERACTION_NAME_INCOMPLETE';
+function isDomainRoleLayer(layer, intentPrefixes = []) {
+    const name = layer.trim();
+    // Start-anchored Domain/entity/aggregate — unanchored "model" matches ReportingReadModels.
+    if (/^domain(?:model)?$/i.test(name) || /^domain(?=[A-Z_\-\s])/i.test(name))
+        return true;
+    if (/^(?:entit(?:y|ies)|aggregates?)(?:$|(?=[A-Z_\-\s]))/i.test(name))
+        return true;
+    return intentPrefixes.some((prefix) => {
+        const normalized = prefix.trim().replace(/\.+$/, '');
+        return normalized === 'Domain' || normalized.startsWith('Domain.');
+    });
+}
+function compareFindings(left, right) {
+    return (left.file.localeCompare(right.file) ||
+        left.ruleId.localeCompare(right.ruleId) ||
+        left.line - right.line ||
+        left.message.localeCompare(right.message));
+}
+function finding(extra, sensor, file, line, message, extras, teethAllowed) {
+    const failsStrict = extra.mode === 'enforced' && teethAllowed;
+    return {
+        ruleId: ARKRUN_RULE_IDS[sensor],
+        sensor,
+        message,
+        file,
+        line,
+        ...(extras?.fromLayer ? { fromLayer: extras.fromLayer } : {}),
+        ...(extras?.target ? { target: extras.target } : {}),
+        severity: failsStrict ? 'error' : 'warning',
+        failsStrict,
+        nextAction: deterministicNextAction({
+            ruleId: ARKRUN_RULE_IDS[sensor],
+            fromLayer: extras?.fromLayer,
+            target: extras?.target,
+        }),
+    };
+}
+function bagForFile(declarations, file) {
+    const uses = [];
+    const reactsTo = [];
+    const raises = [];
+    const sends = [];
+    for (const entry of declarations) {
+        if (entry.file !== file)
+            continue;
+        uses.push(...entry.uses);
+        reactsTo.push(...entry.reactsTo);
+        raises.push(...entry.raises);
+        sends.push(...entry.sends);
+    }
+    return {
+        uses: new Set(uses),
+        reactsTo: new Set(reactsTo),
+        raises: new Set(raises),
+        sends: new Set(sends),
+    };
+}
+function emitKinds(kind) {
+    return kind === 'publisher' || kind === 'publish' || kind === 'raise' || kind === 'send';
+}
+function handleKinds(kind) {
+    return kind === 'subscribe' || kind === 'register-handler';
+}
+function dependKinds(kind) {
+    return kind === 'resolve' || kind === 'resolve-singleton';
+}
+function evaluateMissingRoot(extra, hits, teethAllowed) {
+    const out = [];
+    const roots = extra.compositionRoots;
+    if (roots.length === 0) {
+        out.push(finding(extra, 'arkrun-missing-root', 'ark.config.json', 1, 'ArkRun compositionRoots is empty; no createArkKernel factory site is declared.', undefined, teethAllowed));
+        return out;
+    }
+    const hitsByRoot = new Map();
+    for (const hit of hits) {
+        const list = hitsByRoot.get(hit.matchedRoot) ?? [];
+        list.push(hit);
+        hitsByRoot.set(hit.matchedRoot, list);
+    }
+    for (const pattern of roots) {
+        const matched = [...(hitsByRoot.get(pattern) ?? [])].sort((left, right) => left.file.localeCompare(right.file));
+        if (matched.length === 0) {
+            out.push(finding(extra, 'arkrun-missing-root', 'ark.config.json', 1, `ArkRun composition root ${JSON.stringify(pattern)} matched no governed files and has no createArkKernel factory.`, { target: pattern }, teethAllowed));
+            continue;
+        }
+        // Factory required in the root set, not in every glob hit.
+        if (matched.some((hit) => hit.hasKernelFactory))
+            continue;
+        const first = matched[0];
+        out.push(finding(extra, 'arkrun-missing-root', first.file, 1, `ArkRun composition root ${JSON.stringify(pattern)} has no createArkKernel / createStrictArkKernel factory.`, { target: pattern }, teethAllowed));
+    }
+    return out;
+}
+function evaluateKernelInDomain(extra, layers, dependencies, layerForFile, teethAllowed) {
+    const prefixes = new Map(layers.map((layer) => [layer.name, layer.intentPrefixes ?? []]));
+    const out = [];
+    for (const dependency of dependencies) {
+        const specifier = dependency.specifier;
+        if (!specifier || !isArkRunKernelModuleSpecifier(specifier))
+            continue;
+        const fromLayer = layerForFile(dependency.from);
+        if (!fromLayer)
+            continue;
+        if (!isDomainRoleLayer(fromLayer, prefixes.get(fromLayer) ?? []))
+            continue;
+        out.push(finding(extra, 'arkrun-kernel-in-domain', dependency.from, dependency.line, `${fromLayer} must not import kernel module ${JSON.stringify(specifier)}.`, { fromLayer, target: specifier }, teethAllowed));
+    }
+    return out;
+}
+function evaluateDirectNew(extra, layers, managedNews, hits, layerForFile, teethAllowed) {
+    const managed = new Set(extra.managedLayers);
+    if (managed.size === 0)
+        return [];
+    const prefixes = new Map(layers.map((layer) => [layer.name, layer.intentPrefixes ?? []]));
+    const admittedFactories = new Set(hits.filter((hit) => hit.hasKernelFactory).map((hit) => hit.file));
+    const out = [];
+    for (const constructed of managedNews) {
+        if (admittedFactories.has(constructed.file))
+            continue;
+        const fromLayer = layerForFile(constructed.file);
+        if (!fromLayer || !managed.has(fromLayer))
+            continue;
+        if (isDomainRoleLayer(fromLayer, prefixes.get(fromLayer) ?? []))
+            continue;
+        out.push(finding(extra, 'arkrun-direct-new', constructed.file, constructed.line, `${fromLayer} must not construct ${constructed.typeName} with new outside an ArkRun composition-root factory.`, { fromLayer, target: constructed.typeName }, teethAllowed));
+    }
+    return out;
+}
+function evaluateUndeclared(extra, kernelCalls, declarations, layerForFile, teethAllowed) {
+    const findings = [];
+    const completenessReasons = [];
+    if (extra.requireDeclarations !== true) {
+        return { findings, completenessReasons };
+    }
+    const managed = new Set(extra.managedLayers);
+    if (managed.size === 0)
+        return { findings, completenessReasons };
+    for (const call of kernelCalls) {
+        if (!emitKinds(call.kind) && !handleKinds(call.kind) && !dependKinds(call.kind))
+            continue;
+        const fromLayer = layerForFile(call.file);
+        if (!fromLayer || !managed.has(fromLayer))
+            continue;
+        if (!call.nameLiteral) {
+            if (extra.mode === 'enforced') {
+                completenessReasons.push({
+                    code: ARKRUN_INTERACTION_NAME_INCOMPLETE,
+                    file: call.file,
+                    message: `ArkRun ${call.kind} call in ${call.file} has no string-literal name; enforced extra cannot prove the declaration.`,
+                });
+            }
+            continue;
+        }
+        const bag = bagForFile(declarations, call.file);
+        if (emitKinds(call.kind)) {
+            if (bag.raises.has(call.nameLiteral) || bag.sends.has(call.nameLiteral))
+                continue;
+            findings.push(finding(extra, 'arkrun-undeclared-emit', call.file, call.line, `Emit ${JSON.stringify(call.nameLiteral)} is not declared in raises or sends.`, { fromLayer, target: call.nameLiteral }, teethAllowed));
+            continue;
+        }
+        if (handleKinds(call.kind)) {
+            if (bag.reactsTo.has(call.nameLiteral))
+                continue;
+            findings.push(finding(extra, 'arkrun-undeclared-handle', call.file, call.line, `Handle ${JSON.stringify(call.nameLiteral)} is not declared in reactsTo.`, { fromLayer, target: call.nameLiteral }, teethAllowed));
+            continue;
+        }
+        if (bag.uses.has(call.nameLiteral))
+            continue;
+        findings.push(finding(extra, 'arkrun-undeclared-depend', call.file, call.line, `Depend ${JSON.stringify(call.nameLiteral)} is not declared in uses.`, { fromLayer, target: call.nameLiteral }, teethAllowed));
+    }
+    return { findings, completenessReasons };
+}
+function evaluateTransportBypass(extra, dependencies, layerForFile, teethAllowed) {
+    const managed = new Set(extra.managedLayers);
+    if (managed.size === 0)
+        return [];
+    const out = [];
+    for (const dependency of dependencies) {
+        if (dependency.typeOnly)
+            continue;
+        const specifier = dependency.specifier;
+        if (!specifier || !isArkRunTransportBypassSpecifier(specifier))
+            continue;
+        const fromLayer = layerForFile(dependency.from);
+        if (!fromLayer || !managed.has(fromLayer))
+            continue;
+        out.push(finding(extra, 'arkrun-transport-bypass', dependency.from, dependency.line, `${fromLayer} must not import broker/queue/emitter ${JSON.stringify(specifier)}; use the ArkRun kernel transport.`, { fromLayer, target: specifier }, teethAllowed));
+    }
+    return out;
+}
+/**
+ * Evaluate closed tier-1 ArkRun sensors. Empty extra → no findings (silent).
+ */
+export function evaluateArkRunSensors(input) {
+    const extra = input.arkRun;
+    if (!extra)
+        return { findings: [], completenessReasons: [] };
+    const teethAllowed = extraMergeTeethAllowed(input.classification);
+    const undeclared = evaluateUndeclared(extra, input.kernelCalls, input.declarations, input.layerForFile, teethAllowed);
+    const findings = [
+        ...evaluateMissingRoot(extra, input.compositionRootHits, teethAllowed),
+        ...evaluateKernelInDomain(extra, input.layers, input.dependencies, input.layerForFile, teethAllowed),
+        ...evaluateDirectNew(extra, input.layers, input.managedNews, input.compositionRootHits, input.layerForFile, teethAllowed),
+        ...undeclared.findings,
+        ...evaluateTransportBypass(extra, input.dependencies, input.layerForFile, teethAllowed),
+    ].sort(compareFindings);
+    const completenessReasons = [...undeclared.completenessReasons].sort((left, right) => {
+        const leftKey = `${left.code}\0${left.file ?? ''}\0${left.message}`;
+        const rightKey = `${right.code}\0${right.file ?? ''}\0${right.message}`;
+        return leftKey < rightKey ? -1 : leftKey > rightKey ? 1 : 0;
+    });
+    return { findings, completenessReasons };
+}
+/**
+ * Same sensors as `evaluateArkRunSensors`, filtered to the ESLint import/`new` envelope.
+ * Does not emit missing-root or undeclared-* (those need project-wide / declaration facts).
+ */
+export function evaluateArkRunEditorSensors(input) {
+    const result = evaluateArkRunSensors(input);
+    return {
+        findings: result.findings.filter((item) => isArkRunEditorSensor(item.sensor)),
+        completenessReasons: [],
+    };
+}
+function fileMatchesCompositionRoot(pattern, file) {
+    if (pattern === file)
+        return true;
+    const star = pattern.indexOf('*');
+    if (star < 0)
+        return false;
+    const prefix = pattern.slice(0, star).replace(/\/$/, '');
+    return prefix.length > 0 && (file === prefix || file.startsWith(`${prefix}/`));
+}
+function compositionRootHitsForSource(extra, file, source) {
+    const hasFactory = extractArkRunKernelCallsFromSource(file, source).some((call) => call.kind === 'factory');
+    const hits = [];
+    for (const pattern of extra.compositionRoots) {
+        if (!fileMatchesCompositionRoot(pattern, file))
+            continue;
+        hits.push({ file, matchedRoot: pattern, hasKernelFactory: hasFactory });
+    }
+    return hits;
+}
+/**
+ * Import / `new` envelope from one proposed source (hook Write/Edit, snippet MCP).
+ * Missing-root and undeclared-* stay project-wide CLI/MCP/preflight.
+ */
+export function evaluateArkRunEditorSensorsFromSource(input) {
+    const extra = input.arkRun;
+    if (!extra)
+        return { findings: [], completenessReasons: [] };
+    const admitted = new Set(extractArkRunImportedConstructorNamesFromSource(input.source));
+    return evaluateArkRunEditorSensors({
+        arkRun: extra,
+        layers: input.layers,
+        kernelCalls: [],
+        managedNews: extractArkRunManagedNewsFromSource(input.file, input.source, admitted),
+        compositionRootHits: compositionRootHitsForSource(extra, input.file, input.source),
+        declarations: [],
+        dependencies: extractArkRunValueImportDependenciesFromSource(input.file, input.source),
+        layerForFile: input.layerForFile,
+        classification: input.classification,
+    });
+}

package/bin/lib/config-contract.mjs

@@ -8,8 +8,8 @@
  * Pure CLI helper (bin/lib/config-contract.mjs). Zero Node I/O.
  */
 
-/** Current published ark.config.json schema version (ADR 0012: 1.1 adds optional arkRules). */
-export const ARK_CONFIG_SCHEMA_VERSION = '1.1';
+/** Current published ark.config.json schema version (ADR 0020: 1.2 adds optional arkRun). */
+export const ARK_CONFIG_SCHEMA_VERSION = '1.2';
 export const ARK_CONFIG_SCHEMA_URL = 'https://unpkg.com/arkgate@2/schemas/ark.config.schema.json';
 const DEFAULT_LAYER_NAMES = [
     'DomainModel',
@@ -50,6 +50,7 @@ export const DEFAULT_ARK_CONFIG_RULES = createDefaultRules();
 export const ARK_CONFIG_MIGRATIONS = [
     { from: 'unversioned', to: '1.0' },
     { from: '1.0', to: '1.1' },
+    { from: '1.1', to: '1.2' },
 ];
 const stringArraySchema = {
     type: 'array',
@@ -112,6 +113,8 @@ export const ARK_CONFIG_SCHEMA = {
             additionalProperties: { type: 'string', minLength: 1 },
             default: {},
         },
+        /** ADR 0020 — optional ArkRun extra. Absence is silent; unknown keys fail closed. */
+        arkRun: { $ref: '#/$defs/arkRun' },
         /** Team parliament — GitHub handles or emails who may loosen the law (not part of policy hash). */
         stewards: { ...stringArraySchema, default: [] },
     },
@@ -181,6 +184,20 @@ export const ARK_CONFIG_SCHEMA = {
                 allowDisabledPeerIsolation: { type: 'boolean', default: false },
             },
         },
+        arkRun: {
+            type: 'object',
+            additionalProperties: false,
+            properties: {
+                mode: {
+                    type: 'string',
+                    enum: ['advisory', 'enforced'],
+                    default: 'advisory',
+                },
+                compositionRoots: { ...stringArraySchema, default: [] },
+                managedLayers: { ...stringArraySchema, default: [] },
+                requireDeclarations: { type: 'boolean', default: true },
+            },
+        },
     },
 };
 export class ArkConfigValidationError extends Error {
@@ -314,8 +331,19 @@ function validateNode(value, schema, path, root, issues) {
         }
     }
 }
-function defaultedConfig(input) {
+function defaultedArkRun(value) {
+    if (!isObject(value))
+        return value;
     return {
+        ...value,
+        mode: value.mode === undefined ? 'advisory' : value.mode,
+        compositionRoots: value.compositionRoots === undefined ? [] : value.compositionRoots,
+        managedLayers: value.managedLayers === undefined ? [] : value.managedLayers,
+        requireDeclarations: value.requireDeclarations === undefined ? true : value.requireDeclarations,
+    };
+}
+function defaultedConfig(input) {
+    const result = {
         ...input,
         $schema: input.$schema === undefined ? ARK_CONFIG_SCHEMA_URL : input.$schema,
         schemaVersion: input.schemaVersion === undefined ? ARK_CONFIG_SCHEMA_VERSION : input.schemaVersion,
@@ -325,6 +353,57 @@ function defaultedConfig(input) {
             ? DEFAULT_ARK_CONFIG_RULES.map((rule) => ({ ...rule }))
             : input.rules,
     };
+    if (input.arkRun !== undefined)
+        result.arkRun = defaultedArkRun(input.arkRun);
+    return result;
+}
+function validateArkRunExtra(config, issues) {
+    const extra = config.arkRun;
+    if (extra === undefined || !isObject(extra))
+        return;
+    const layerNames = new Set();
+    if (Array.isArray(config.layers)) {
+        for (const layer of config.layers) {
+            if (isObject(layer) && typeof layer.name === 'string' && layer.name.length > 0) {
+                layerNames.add(layer.name);
+            }
+        }
+    }
+    const managed = extra.managedLayers;
+    if (Array.isArray(managed)) {
+        managed.forEach((name, index) => {
+            if (typeof name === 'string' && name.length > 0 && !layerNames.has(name)) {
+                issues.push({
+                    path: `$.arkRun.managedLayers[${index}]`,
+                    message: `layer ${JSON.stringify(name)} is not declared in layers[]`,
+                });
+            }
+        });
+    }
+    if (extra.mode === 'enforced') {
+        const roots = extra.compositionRoots;
+        if (!Array.isArray(roots) || roots.length === 0) {
+            issues.push({
+                path: '$.arkRun.compositionRoots',
+                message: 'ARKRUN_MISSING_ROOT: enforced mode requires at least one composition root',
+            });
+        }
+        if (!Array.isArray(managed) || managed.length === 0) {
+            issues.push({
+                path: '$.arkRun.managedLayers',
+                message: 'enforced mode requires at least one managed layer',
+            });
+        }
+    }
+}
+function migratedFromOf(originalVersion) {
+    if (originalVersion === ARK_CONFIG_SCHEMA_VERSION)
+        return null;
+    if (originalVersion === 'unversioned')
+        return 'unversioned';
+    if (originalVersion === '1.0' || originalVersion === '1.1')
+        return originalVersion;
+    return null;
 }
 function knownInputVersions() {
     const versions = new Set([ARK_CONFIG_SCHEMA_VERSION]);
@@ -369,8 +448,8 @@ export function migrateArkConfig(input, source = 'ark.config.json') {
     }
     let version = originalVersion;
     const working = { ...input };
-    // Walk the migration table. Each step is a pure version stamp for 1.0→1.1
-    // (arkRules is optional; absence needs no field rewrite).
+    // Walk the migration table. Each step is a pure version stamp (optional extras
+    // like arkRules / arkRun need no field rewrite when absent).
     let guard = 0;
     while (version !== ARK_CONFIG_SCHEMA_VERSION && guard < ARK_CONFIG_MIGRATIONS.length + 1) {
         guard += 1;
@@ -394,17 +473,13 @@ export function migrateArkConfig(input, source = 'ark.config.json') {
             },
         ]);
     }
-    const migratedFrom = originalVersion === 'unversioned'
-        ? 'unversioned'
-        : originalVersion === '1.0'
-            ? '1.0'
-            : null;
-    return { candidate: defaultedConfig(working), migratedFrom };
+    return { candidate: defaultedConfig(working), migratedFrom: migratedFromOf(originalVersion) };
 }
 export function loadArkConfigContract(input, source = 'ark.config.json') {
     const { candidate, migratedFrom } = migrateArkConfig(input, source);
     const issues = [];
     validateNode(candidate, ARK_CONFIG_SCHEMA, '$', ARK_CONFIG_SCHEMA, issues);
+    validateArkRunExtra(candidate, issues);
     if (issues.length > 0)
         throw new ArkConfigValidationError(source, issues);
     return { config: candidate, migratedFrom };

package/bin/lib/diagnostic-catalog.mjs

@@ -56,6 +56,14 @@ export const DIAGNOSTIC_CATALOG = Object.freeze([
     entry('ARKRULE_INVARIANT', 'arkrules', 'ArkRule invariant failed', 'Reserved / remediation-recognized code for invariant-plane failures bound to an ArkRule id (coverage path also emits INVARIANT_UNCOVERED).', 'Fix the invariant for the ArkRule declared in arkrules/<Layer>.json, then preflight again. Do not demote without acknowledgement.'),
     entry('ARKRULE_SCOPE_EMPTY', 'arkrules', 'ArkRule appliesTo matched zero files', 'An ArkRule’s appliesTo globs matched no governed files — the rule cannot observe what it claims to protect.', 'Fix appliesTo globs so they match governed files, or remove the rule. Enforced empty scope fails; advisory empty scope warns.', { oftenAdvisory: true }),
     entry('INVARIANT_UNCOVERED', 'arkrules', 'Invariant without coverage evidence', 'An ArkRules invariant is under contract but no covering test title or declared symbol evidence was found (or coverage is partial). Kind is never-had-tests (adopt residual) vs tests-disappeared (suite exists).', 'Add a test title or declared symbol covering the arkruleId, then preflight again. Treat never-had-tests as adopt residual; treat tests-disappeared as a regression. Missing test globs report partial — never fake green.'),
+    // ── ArkRun (opt-in extra; RN05 dual-depth nextAction) ────────────────────
+    entry('ARKRUN_MISSING_ROOT', 'arkrun', 'No kernel factory in composition roots', 'The ArkRun extra is on but no createArkKernel / createStrictArkKernel / createArkKernelFromConfig / createStrictArkKernelFromConfig factory was found in arkRun.compositionRoots, so agents can skip the kernel while the write gate stays green.', '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.'),
+    entry('ARKRUN_KERNEL_IN_DOMAIN', 'arkrun', 'Domain-role layer imports the kernel', 'A Domain-role layer imports @arkgate/runtime or kernel types. Domain stays kernel-free; composition roots and adapters own the factory.', '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.'),
+    entry('ARKRUN_DIRECT_NEW', 'arkrun', 'Managed type constructed with new', 'A managed non-Domain file constructs an admitted type with new outside an ArkRun composition-root factory, skipping kernel resolve/registration.', 'Resolve the type from the kernel instead of constructing it with new, then preflight again. Never mechanical-safe — rewiring construction is a design decision.'),
+    entry('ARKRUN_UNDECLARED_EMIT', 'arkrun', 'Emit name not in raises/sends', 'A publisher / publish / raise / send call-site literal is not listed in the file’s raises or sends declaration.', '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.'),
+    entry('ARKRUN_UNDECLARED_HANDLE', 'arkrun', 'Handle name not in reactsTo', 'A subscribe / registerHandler call-site literal is not listed in the file’s reactsTo declaration.', '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.'),
+    entry('ARKRUN_UNDECLARED_DEPEND', 'arkrun', 'Depend name not in uses', 'A resolve / resolveSingleton call-site literal is not listed in the file’s uses declaration.', '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.'),
+    entry('ARKRUN_TRANSPORT_BYPASS', 'arkrun', 'Homemade broker or emitter import', 'A managed layer imports a closed broker/queue/emitter specifier (EventEmitter, queue clients, …) instead of the ArkRun kernel transport.', 'Send through the ArkRun kernel transport instead of importing that broker or emitter, then preflight again. Never mechanical-safe — homemade buses stay judgment.'),
     // ── atomic preflight / change set ────────────────────────────────────────
     entry('INVALID_CHANGE_PATH', 'preflight', 'Unsafe change path', 'A change set entry is not a safe, non-empty project-relative path (absolute, escape, empty, or NUL).', 'Use canonical project-relative paths only in the atomic change set, then preflight again.'),
     entry('DUPLICATE_CHANGE_PATH', 'preflight', 'Duplicate path in change set', 'The atomic change set lists more than one operation for the same path.', 'Collapse to one create/update/delete per path, then preflight again.'),

package/bin/lib/doctor-advisories.mjs

@@ -20,8 +20,20 @@ import { printParseHealthSection, summarizeParseHealth } from './parse-health.mj
 import { detectGraphBlindSpots, printGraphBlindSection } from './graph-blind.mjs';
 import { summarizeRulesUnderContract } from './rules-under-contract.mjs';
 import { collectStewardNudge } from './team-parliament-io.mjs';
+import { formatArkRunDoctorLines, summarizeArkRunSection } from './ark-run-doctor.mjs';
 
-export function computeDoctorAdvisories(root, config, cov, rules, files, ts, parseHealth, facts) {
+function classificationFromCoverage(cov) {
+  return {
+    governedPercent: cov?.governed?.percent ?? null,
+    populatedLayerCount: Array.isArray(cov?.layers)
+      ? cov.layers.filter((row) => (row?.files ?? 0) > 0).length
+      : null,
+    classifiedFiles: cov?.governed?.classifiedFiles ?? null,
+  };
+}
+
+/** `activeViolations` must already exclude frozen baseline keys (report residual parity). */
+export function computeDoctorAdvisories(root, config, cov, rules, files, ts, parseHealth, facts, activeViolations) {
   const physicalCohesion = computePhysicalCohesion(root, files);
   const decisionMemory = computeReshapeDecisionMemory(root, files);
   physicalCohesion.reshapeDecisions = decisionMemory.summary;
@@ -41,6 +53,27 @@ export function computeDoctorAdvisories(root, config, cov, rules, files, ts, par
           })).filter((f) => f.path),
         }
       : undefined);
+  const classification = classificationFromCoverage(cov);
+  const rulesUnderContract = summarizeRulesUnderContract(root, config, factPaths, 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;
+  }
   return {
     contractHealth: computeContractHealth(root, config, cov, rules),
     ambientState: computeAmbientState(ts, root, config, files),
@@ -51,13 +84,8 @@ export function computeDoctorAdvisories(root, config, cov, rules, files, ts, par
     // AR12 — Rules under contract (honest counts; real test I/O, never empty-fileContents stub).
     // P1M: pass classification so extraMergeTeeth cannot arm at 0% governed.
     stewardNudge: collectStewardNudge(root, config),
-    rulesUnderContract: summarizeRulesUnderContract(root, config, factPaths, {
-      governedPercent: cov?.governed?.percent ?? null,
-      populatedLayerCount: Array.isArray(cov?.layers)
-        ? cov.layers.filter((row) => (row?.files ?? 0) > 0).length
-        : null,
-      classifiedFiles: cov?.governed?.classifiedFiles ?? null,
-    }),
+    rulesUnderContract,
+    arkRun,
   };
 }
 
@@ -79,4 +107,13 @@ export function printDoctorAdvisories(advisories, io) {
     io.line(io.warn, nudge.ask);
     if (nudge.nextAction) io.line(' ', io.color.dim(`Next: ${nudge.nextAction}`));
   }
+  const arkRun = advisories.arkRun;
+  if (arkRun && arkRun.notAScore === true) {
+    console.log('');
+    console.log(io.color.bold('ArkRun (not a score)'));
+    const mark = arkRun.active && arkRun.residual?.count > 0 ? io.warn : ' ';
+    for (const text of formatArkRunDoctorLines(arkRun)) {
+      io.line(mark, text);
+    }
+  }
 }

package/bin/lib/doctor-human.mjs

@@ -140,6 +140,16 @@ export function printDoctorCompactHuman(view) {
     line(warn, nudge.ask);
   }
 
+  const arkRun = doctorAdvisories.arkRun;
+  if (arkRun?.active === true && arkRun.notAScore === true) {
+    console.log('');
+    const residual = Number(arkRun.residual?.count) || 0;
+    line(
+      residual > 0 ? warn : ' ',
+      `ArkRun: ${arkRun.mode || 'on'} · residual=${residual} · not a score`
+    );
+  }
+
   if (violations.length === 0) {
     if (!analysisComplete) {
       console.log('');

package/bin/lib/doctor-plan.mjs

@@ -599,21 +599,22 @@ export function runDoctor(root, config, files, rules, violations, asJson, option
     patternBets: patternBetsForLoop,
     designSmells,
   });
-  const doctorAdvisories = computeDoctorAdvisories(root, config, cov, rules, files, options.ts, options.parseHealth);
-  // AR12 — compute once for JSON + product honesty + human lines.
-  // P1M: classification gate on extraMergeTeeth (no teeth at empty graph).
-  const rulesUnderContract = summarizeRulesUnderContract(
+  const activeViolations = baseline.exists
+    ? violations.filter((_, index) => !baseline.keys.has(occurrenceKeys[index]))
+    : violations;
+  const doctorAdvisories = computeDoctorAdvisories(
     root,
     config,
+    cov,
+    rules,
+    files,
+    options.ts,
+    options.parseHealth,
     options.facts ?? options.architectureFacts,
-    {
-      governedPercent: cov.governed?.percent ?? null,
-      populatedLayerCount: Array.isArray(cov.layers)
-        ? cov.layers.filter((row) => (row?.files ?? 0) > 0).length
-        : null,
-      classifiedFiles: cov.governed?.classifiedFiles ?? null,
-    }
+    activeViolations
   );
+  const rulesUnderContract = doctorAdvisories.rulesUnderContract;
+  const arkRun = doctorAdvisories.arkRun;
   // Single residual expression (nextPilot || extractionCard) — HTML report uses the same.
   const residualPilot = pilotLoop?.nextPilot || pilotLoop?.extractionCard || null;
   // Evidence-backed hard only (never capabilities-from-hook-files alone).
@@ -653,9 +654,12 @@ export function runDoctor(root, config, files, rules, violations, asJson, option
       residualPilots: Boolean(residualPilot) && designFitness.designWeak === true,
       pilotTarget: residualPilot?.pilotTarget ?? residualPilot?.pilot ?? null,
       arkRulesMergeHonesty: rulesUnderContract?.mergePlanes
-        ? { active: rulesUnderContract.active === true, ...rulesUnderContract.mergePlanes }
-        : rulesUnderContract?.active === true
-          ? { active: true, extraMergeTeeth: false }
+        ? {
+            active: rulesUnderContract.active === true || arkRun?.active === true,
+            ...rulesUnderContract.mergePlanes,
+          }
+        : rulesUnderContract?.active === true || arkRun?.active === true
+          ? { active: true, extraMergeTeeth: arkRun?.extraMergeTeeth === true }
           : null,
       primaryNextAction:
         adopted === 'not-adopted' ? NOT_ADOPTED_NEXT_ACTION : postGreenPath?.action ?? dualTruthNext,
@@ -746,10 +750,10 @@ export function runDoctor(root, config, files, rules, violations, asJson, option
             // Dual-truth: managed CLI vs package.json pin (not a gate fail).
             packageVersionTruth,
             // Advisories, never a verdict: W01/U05/X04/Y03 + graph-blind spots.
-            // (rulesUnderContract is also in advisories; re-assert after spread so mergePlanes wins.)
+            // Re-assert after spread so mergePlanes from this scan wins.
             ...doctorAdvisories,
-            // AR12 + P1-M mergePlanes (authoritative; after advisories spread).
             rulesUnderContract,
+            arkRun,
             // P0-B — single anti-false-green honesty surface (never a score).
             productHonesty,
             governed: cov.governed,