arkgate 4.6.6 → 4.7.0

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

@@ -0,0 +1,144 @@
+/**
+ * GENERATED FILE — do not edit by hand.
+ *
+ * Canonical algorithm: src/domain/arkRunDoctor.ts
+ * Regenerate: node scripts/generate-cli-pure.mjs
+ * Drift check: node scripts/generate-cli-pure.mjs --check
+ *
+ * Pure CLI helper (bin/lib/ark-run-doctor.mjs). Zero Node I/O.
+ */
+
+import { composeMergePlanesHonesty, extraMergeTeethAllowed, isArkRunRuleId, } from './extra-merge-teeth.mjs';
+export const ARK_RUN_DOCTOR_SCHEMA_VERSION = '1.0';
+const RESIDUAL_RULE_CAP = 12;
+function closedMode(value) {
+    return value === 'enforced' || value === 'advisory' ? value : null;
+}
+function uniqueArkRunRuleIds(findings) {
+    const seen = new Set();
+    if (!Array.isArray(findings))
+        return [];
+    for (const finding of findings) {
+        const id = finding?.ruleId;
+        if (typeof id !== 'string' || !isArkRunRuleId(id) || seen.has(id))
+            continue;
+        seen.add(id);
+    }
+    return [...seen].sort((left, right) => (left < right ? -1 : left > right ? 1 : 0));
+}
+function extraFromConfig(arkRun) {
+    if (!arkRun || typeof arkRun !== 'object') {
+        return { present: false, mode: null, roots: 0, layers: 0, requireDeclarations: null };
+    }
+    return {
+        present: true,
+        mode: closedMode(arkRun.mode),
+        roots: Array.isArray(arkRun.compositionRoots) ? arkRun.compositionRoots.length : 0,
+        layers: Array.isArray(arkRun.managedLayers) ? arkRun.managedLayers.length : 0,
+        requireDeclarations: arkRun.requireDeclarations === true,
+    };
+}
+/**
+ * Doctor / HTML ArkRun advisory. Always emitted; absence is an honest silent row.
+ */
+export function summarizeArkRunSection(input = {}) {
+    const extra = extraFromConfig(input.arkRun);
+    const uniqueIds = extra.present ? uniqueArkRunRuleIds(input.findings) : [];
+    const ruleIds = uniqueIds.slice(0, RESIDUAL_RULE_CAP);
+    const residualCount = uniqueIds.length;
+    const mergePlanes = composeMergePlanesHonesty({
+        classification: input.classification,
+        arkRules: {
+            active: input.arkRules?.active === true,
+            structureEnforced: input.arkRules?.structureEnforced,
+            structureTotal: input.arkRules?.structureTotal,
+            structureAdvisory: input.arkRules?.structureAdvisory,
+            invariantEnforced: input.arkRules?.invariantEnforced,
+            invariantTotal: input.arkRules?.invariantTotal,
+            invariantAdvisory: input.arkRules?.invariantAdvisory,
+            covered: input.arkRules?.covered,
+            uncovered: input.arkRules?.uncovered,
+        },
+        arkRun: {
+            present: extra.present,
+            mode: extra.mode,
+            residualCount,
+        },
+    });
+    const extraMergeTeeth = extra.present && extra.mode === 'enforced' && extraMergeTeethAllowed(input.classification);
+    let note;
+    if (!extra.present) {
+        note =
+            'Absence of arkRun is silent — Layers and ArkRules verdicts unchanged. Not a score.';
+    }
+    else if (extra.mode === 'advisory') {
+        note =
+            'Advisory ArkRun residual only — never flips valid or --strict-merge. Residual is a finding-id count, never a score.';
+    }
+    else if (extraMergeTeeth) {
+        note =
+            'Enforced ArkRun is on the extra merge plane. Residual is a finding-id count, never a score.';
+    }
+    else {
+        note =
+            'Enforced ArkRun extra teeth stay demoted until the layer plane is honestly classified. Residual is a finding-id count, never a score.';
+    }
+    return {
+        schemaVersion: ARK_RUN_DOCTOR_SCHEMA_VERSION,
+        notAScore: true,
+        active: extra.present,
+        mode: extra.mode,
+        compositionRoots: extra.roots,
+        managedLayers: extra.layers,
+        requireDeclarations: extra.requireDeclarations,
+        residual: { count: residualCount, ruleIds },
+        extraMergeTeeth,
+        failMergeWhen: mergePlanes.failMergeWhen,
+        note,
+        mergePlanes,
+    };
+}
+/** Thin status slice — counts only; residual null means unknown, not green. */
+export function projectStatusArkRun(input = {}) {
+    const present = input.present === true;
+    const mode = closedMode(input.mode);
+    const residualRaw = input.residual;
+    let residual = null;
+    if (typeof residualRaw === 'number' && Number.isFinite(residualRaw) && residualRaw >= 0) {
+        residual = Math.floor(residualRaw);
+    }
+    if (!present)
+        residual = residual == null ? 0 : residual;
+    return {
+        notAScore: true,
+        present,
+        mode: present ? mode : null,
+        extraMergeTeeth: present && mode === 'enforced' && input.extraMergeTeeth === true,
+        residual,
+    };
+}
+export function formatArkRunDoctorLines(section) {
+    if (!section || section.notAScore !== true)
+        return [];
+    if (section.active !== true) {
+        return ['ArkRun extra is off — silent on Layers/ArkRules (not a score).'];
+    }
+    const mode = section.mode ?? 'unknown';
+    const teeth = section.extraMergeTeeth === true ? 'armed' : 'not armed';
+    const lines = [
+        `mode: ${mode} · extra merge teeth ${teeth} · not a score`,
+    ];
+    if (section.residual.count > 0) {
+        const shown = section.residual.ruleIds.join(', ');
+        const more = section.residual.count > section.residual.ruleIds.length
+            ? ` (+${section.residual.count - section.residual.ruleIds.length} more)`
+            : '';
+        lines.push(`Residual: ${shown}${more}`);
+    }
+    else {
+        lines.push('Residual: none on this scan (not a score — green extras ≠ finished kernel wiring).');
+    }
+    if (section.failMergeWhen)
+        lines.push(section.failMergeWhen);
+    return lines;
+}

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

@@ -0,0 +1,472 @@
+/**
+ * GENERATED FILE — do not edit by hand.
+ *
+ * Canonical algorithm: src/domain/arkRunFacts.ts
+ * Regenerate: node scripts/generate-cli-pure.mjs
+ * Drift check: node scripts/generate-cli-pure.mjs --check
+ *
+ * Pure CLI helper (bin/lib/ark-run-facts.mjs). Zero Node I/O.
+ */
+
+export const ARKRUN_KERNEL_FACTORY_CALLEES = [
+    'createArkKernel',
+    'createStrictArkKernel',
+    'createArkKernelFromConfig',
+    'createStrictArkKernelFromConfig',
+];
+/** Closed interaction callees from ADR 0022 undeclared-emit/handle/depend. */
+export const ARKRUN_KERNEL_INTERACTION_CALLEES = [
+    'publisher',
+    'publish',
+    'raise',
+    'raiseAsync',
+    'send',
+    'sendTo',
+    'subscribe',
+    'registerHandler',
+    'resolve',
+    'resolveSingleton',
+];
+const FACTORY_CALLEES = new Set(ARKRUN_KERNEL_FACTORY_CALLEES);
+const BUILTIN_CTORS = new Set([
+    'AggregateError',
+    'Array',
+    'ArrayBuffer',
+    'BigInt64Array',
+    'BigUint64Array',
+    'Boolean',
+    'DataView',
+    'Date',
+    'Error',
+    'EvalError',
+    'FinalizationRegistry',
+    'Float32Array',
+    'Float64Array',
+    'Function',
+    'Int8Array',
+    'Int16Array',
+    'Int32Array',
+    'Map',
+    'Number',
+    'Object',
+    'Promise',
+    'Proxy',
+    'RangeError',
+    'ReferenceError',
+    'RegExp',
+    'Set',
+    'SharedArrayBuffer',
+    'String',
+    'Symbol',
+    'SyntaxError',
+    'TypeError',
+    'URIError',
+    'Uint8Array',
+    'Uint8ClampedArray',
+    'Uint16Array',
+    'Uint32Array',
+    'WeakMap',
+    'WeakRef',
+    'WeakSet',
+]);
+/** Receivers whose `.resolve`/`.publish` are ambient, not kernel APIs. */
+const SKIP_INTERACTION_RECEIVERS = new Set([
+    'Array',
+    'Atomics',
+    'Buffer',
+    'JSON',
+    'Math',
+    'Number',
+    'Object',
+    'Promise',
+    'Reflect',
+    'String',
+    'console',
+    'fs',
+    'path',
+    'url',
+    'util',
+]);
+export function isArkRunKernelModuleSpecifier(specifier) {
+    return (specifier === '@arkgate/runtime' ||
+        specifier.startsWith('@arkgate/runtime/') ||
+        specifier === 'arkgate/runtime' ||
+        specifier.startsWith('arkgate/runtime/'));
+}
+/**
+ * Closed broker / queue / emitter specifiers for `arkrun-transport-bypass`
+ * (ADR 0022 D4). Exact entry or package-root subpath only — never substring.
+ */
+export const ARKRUN_TRANSPORT_BYPASS_SPECIFIERS = [
+    'events',
+    'node:events',
+    'eventemitter2',
+    'eventemitter3',
+    'emittery',
+    'kafkajs',
+    'kafka-node',
+    'amqplib',
+    'amqp',
+    'bull',
+    'bullmq',
+    'mqtt',
+    'nats',
+    '@aws-sdk/client-sqs',
+    '@aws-sdk/client-sns',
+    '@aws-sdk/client-eventbridge',
+    '@google-cloud/pubsub',
+    '@azure/service-bus',
+];
+const TRANSPORT_BYPASS = new Set(ARKRUN_TRANSPORT_BYPASS_SPECIFIERS);
+export function isArkRunTransportBypassSpecifier(specifier) {
+    if (!specifier || specifier.startsWith('.') || specifier.startsWith('/'))
+        return false;
+    if (TRANSPORT_BYPASS.has(specifier))
+        return true;
+    const first = specifier.indexOf('/');
+    if (first < 0)
+        return false;
+    const root = specifier.slice(0, first);
+    if (TRANSPORT_BYPASS.has(root))
+        return true;
+    const second = specifier.indexOf('/', first + 1);
+    if (second < 0)
+        return false;
+    return TRANSPORT_BYPASS.has(specifier.slice(0, second));
+}
+export function arkRunKernelCallKind(callee) {
+    if (FACTORY_CALLEES.has(callee))
+        return 'factory';
+    switch (callee) {
+        case 'publisher':
+            return 'publisher';
+        case 'publish':
+            return 'publish';
+        case 'raise':
+        case 'raiseAsync':
+            return 'raise';
+        case 'send':
+        case 'sendTo':
+            return 'send';
+        case 'subscribe':
+            return 'subscribe';
+        case 'registerHandler':
+            return 'register-handler';
+        case 'resolve':
+            return 'resolve';
+        case 'resolveSingleton':
+            return 'resolve-singleton';
+        default:
+            return undefined;
+    }
+}
+function lineAt(content, index) {
+    let line = 1;
+    for (let i = 0; i < index; i += 1) {
+        if (content.charCodeAt(i) === 10)
+            line += 1;
+    }
+    return line;
+}
+/** Replace comments with spaces so line numbers stay aligned. */
+function stripCommentsPreservingLines(content) {
+    return content
+        .replace(/\/\*[\s\S]*?\*\//g, (block) => block.replace(/[^\n]/g, ' '))
+        .replace(/(^|[^:\\])\/\/.*$/gm, (line) => line.replace(/\/\/.*$/, (tail) => ' '.repeat(tail.length)));
+}
+function firstStringLiteralArg(content, openParenEnd) {
+    const slice = content.slice(openParenEnd);
+    const match = /^\s*(['"])((?:\\.|[^\\])*?)\1/.exec(slice);
+    if (!match)
+        return undefined;
+    const value = match[2] ?? '';
+    return value.length > 0 ? value : undefined;
+}
+function keywordBefore(content, index, keyword) {
+    const start = Math.max(0, index - keyword.length - 8);
+    const before = content.slice(start, index);
+    return new RegExp(`\\b${keyword}\\s+$`).test(before);
+}
+function parseValueImportClause(content, onClause) {
+    const importRe = /\b(?:import|export)(\s+type)?\s+([\s\S]*?)\s+from\s*['"]([^'"]+)['"]/g;
+    let match;
+    while ((match = importRe.exec(content)) !== null) {
+        if (match[1])
+            continue;
+        onClause(match[2] ?? '', match[3] ?? '');
+    }
+}
+/** Value `import`/`export … from` clauses. Strips comments so callers may pass raw source. */
+export function forEachArkRunValueImportClause(content, onClause) {
+    parseValueImportClause(stripCommentsPreservingLines(content), onClause);
+}
+/**
+ * Lexical import/export-from and require/import() specifier edges for the
+ * editor / snippet envelope. Resolution stays unresolved-external — sensors
+ * only need the specifier and from-file.
+ */
+export function extractArkRunValueImportDependenciesFromSource(file, content) {
+    const source = stripCommentsPreservingLines(content);
+    const out = [];
+    const fromRe = /\b(?:import|export)(\s+type)?\s+([\s\S]*?)\s+from\s*['"]([^'"]+)['"]/g;
+    let match;
+    while ((match = fromRe.exec(source)) !== null) {
+        const specifier = match[3] ?? '';
+        if (!specifier)
+            continue;
+        const statement = match[0] ?? '';
+        out.push({
+            from: file,
+            specifier,
+            kind: /^\s*export/.test(statement) ? 'export' : 'import',
+            typeOnly: Boolean(match[1]),
+            line: lineAt(content, match.index),
+            resolution: 'resolved-external',
+        });
+    }
+    const callRe = /\b(?:require|import)\s*\(\s*['"]([^'"]+)['"]\s*\)/g;
+    while ((match = callRe.exec(source)) !== null) {
+        const specifier = match[1] ?? '';
+        if (!specifier)
+            continue;
+        const kind = match[0]?.startsWith('import') ? 'dynamic-import' : 'require';
+        out.push({
+            from: file,
+            specifier,
+            kind,
+            typeOnly: false,
+            line: lineAt(content, match.index),
+            resolution: 'resolved-external',
+        });
+    }
+    return out;
+}
+/** PascalCase named bindings from value import clauses (snippet admitted constructors). */
+export function extractArkRunImportedConstructorNamesFromSource(content) {
+    const names = [];
+    forEachArkRunValueImportClause(content, (clause) => {
+        const braced = /\{([^}]*)\}/.exec(clause);
+        if (!braced?.[1])
+            return;
+        for (const part of braced[1].split(',')) {
+            const piece = part.trim();
+            if (!piece || piece.startsWith('type '))
+                continue;
+            const alias = /^([A-Za-z_][A-Za-z0-9_]*)\s+as\s+([A-Za-z_][A-Za-z0-9_]*)$/.exec(piece);
+            const local = alias?.[2] ?? /^([A-Za-z_][A-Za-z0-9_]*)$/.exec(piece)?.[1];
+            const original = alias?.[1] ?? local;
+            if (local && original && /^[A-Z]/.test(original))
+                names.push(local, original);
+        }
+    });
+    return uniqueSorted(names);
+}
+function collectKernelImportBindings(content) {
+    const named = new Map();
+    const namespaces = new Set();
+    parseValueImportClause(content, (clause, specifier) => {
+        if (!isArkRunKernelModuleSpecifier(specifier))
+            return;
+        const namespace = /\*\s+as\s+([A-Za-z_][A-Za-z0-9_]*)/.exec(clause);
+        if (namespace?.[1])
+            namespaces.add(namespace[1]);
+        const defaultIdent = /^([A-Za-z_][A-Za-z0-9_]*)\s*(?:,|$)/.exec(clause.trim());
+        if (defaultIdent?.[1])
+            named.set(defaultIdent[1], defaultIdent[1]);
+        const braced = /\{([^}]*)\}/.exec(clause);
+        if (!braced?.[1])
+            return;
+        for (const part of braced[1].split(',')) {
+            const piece = part.trim();
+            if (!piece || piece.startsWith('type '))
+                continue;
+            const alias = /^([A-Za-z_][A-Za-z0-9_]*)\s+as\s+([A-Za-z_][A-Za-z0-9_]*)$/.exec(piece);
+            if (alias) {
+                named.set(alias[2], alias[1]);
+                continue;
+            }
+            const ident = /^([A-Za-z_][A-Za-z0-9_]*)$/.exec(piece);
+            if (ident?.[1])
+                named.set(ident[1], ident[1]);
+        }
+    });
+    return { named, namespaces };
+}
+function collectImportedConstructors(content, admitted) {
+    const out = new Set(admitted);
+    parseValueImportClause(content, (clause, specifier) => {
+        const braced = /\{([^}]*)\}/.exec(clause);
+        if (!braced?.[1])
+            return;
+        for (const part of braced[1].split(',')) {
+            const piece = part.trim();
+            if (!piece || piece.startsWith('type '))
+                continue;
+            const alias = /^([A-Za-z_][A-Za-z0-9_]*)\s+as\s+([A-Za-z_][A-Za-z0-9_]*)$/.exec(piece);
+            const local = alias?.[2] ?? /^([A-Za-z_][A-Za-z0-9_]*)$/.exec(piece)?.[1];
+            const original = alias?.[1] ?? local;
+            if (!local || !original || !/^[A-Z]/.test(original))
+                continue;
+            if (isArkRunKernelModuleSpecifier(specifier) || admitted.has(original) || admitted.has(local)) {
+                out.add(local);
+                out.add(original);
+            }
+        }
+    });
+    return out;
+}
+function importedFromForName(content, localName) {
+    let found;
+    parseValueImportClause(content, (clause, specifier) => {
+        if (!found && new RegExp(`\\b${localName}\\b`).test(clause))
+            found = specifier;
+    });
+    return found;
+}
+export function extractArkRunKernelCallsFromSource(file, content) {
+    const source = stripCommentsPreservingLines(content);
+    const bindings = collectKernelImportBindings(source);
+    const facts = [];
+    const callRe = /\b([A-Za-z_][A-Za-z0-9_]*)\s*(?:<[^>]*>)?\s*\(/g;
+    let match;
+    while ((match = callRe.exec(source)) !== null) {
+        const callee = match[1];
+        const index = match.index;
+        if (keywordBefore(source, index, 'function') || keywordBefore(source, index, 'class'))
+            continue;
+        const dotted = source.slice(0, index).match(/([A-Za-z_][A-Za-z0-9_]*)\s*\.\s*$/);
+        const receiver = dotted?.[1];
+        const original = bindings.named.get(callee) ?? callee;
+        const kind = arkRunKernelCallKind(original) ?? arkRunKernelCallKind(callee);
+        if (!kind)
+            continue;
+        const viaImport = bindings.named.has(callee) || (receiver !== undefined && bindings.namespaces.has(receiver));
+        if (kind !== 'factory') {
+            if (!viaImport && receiver === undefined)
+                continue;
+            if (receiver && SKIP_INTERACTION_RECEIVERS.has(receiver) && !viaImport)
+                continue;
+        }
+        const nameLiteral = firstStringLiteralArg(source, index + match[0].length);
+        facts.push({
+            file,
+            line: lineAt(content, index),
+            kind,
+            callee,
+            viaImport,
+            ...(receiver ? { receiver } : {}),
+            ...(nameLiteral ? { nameLiteral } : {}),
+        });
+    }
+    return facts;
+}
+export function extractArkRunManagedNewsFromSource(file, content, admittedTypeNames) {
+    const source = stripCommentsPreservingLines(content);
+    const admitted = collectImportedConstructors(source, admittedTypeNames);
+    const facts = [];
+    const newRe = /\bnew\s+(?:[A-Za-z_][A-Za-z0-9_]*\s*\.\s*)*([A-Z][A-Za-z0-9_]*)\s*(?:<[^>]*>)?\s*\(/g;
+    let match;
+    while ((match = newRe.exec(source)) !== null) {
+        const typeName = match[1];
+        if (BUILTIN_CTORS.has(typeName) || !admitted.has(typeName))
+            continue;
+        const importedFrom = importedFromForName(source, typeName);
+        facts.push({
+            file,
+            line: lineAt(content, match.index),
+            typeName,
+            ...(importedFrom ? { importedFrom } : {}),
+        });
+    }
+    return facts;
+}
+function matchingBracketEnd(source, openIndex) {
+    let depth = 0;
+    let quote;
+    for (let i = openIndex; i < source.length; i += 1) {
+        const ch = source[i];
+        if (quote) {
+            if (ch === '\\') {
+                i += 1;
+                continue;
+            }
+            if (ch === quote)
+                quote = undefined;
+            continue;
+        }
+        if (ch === "'" || ch === '"' || ch === '`') {
+            quote = ch;
+            continue;
+        }
+        if (ch === '[')
+            depth += 1;
+        else if (ch === ']') {
+            depth -= 1;
+            if (depth === 0)
+                return i;
+        }
+    }
+    return -1;
+}
+function stringLiteralsInList(source, openIndex, closeIndex) {
+    const slice = source.slice(openIndex + 1, closeIndex);
+    const out = [];
+    const re = /(['"])((?:\\.|[^\\])*?)\1/g;
+    let match;
+    while ((match = re.exec(slice)) !== null) {
+        const value = match[2] ?? '';
+        if (value.length > 0)
+            out.push(value);
+    }
+    return out;
+}
+function uniqueSorted(values) {
+    return [...new Set(values)].sort((left, right) => (left < right ? -1 : left > right ? 1 : 0));
+}
+/** File-scoped `uses` / `reactsTo` / `raises` / `sends` string-literal lists (ADR 0023). */
+export function extractArkRunDeclarationsFromSource(file, content) {
+    const source = stripCommentsPreservingLines(content);
+    const fieldRe = /\b(uses|reactsTo|raises|sends)\s*:/g;
+    const uses = [];
+    const reactsTo = [];
+    const raises = [];
+    const sends = [];
+    let firstIndex;
+    let match;
+    while ((match = fieldRe.exec(source)) !== null) {
+        const after = source.slice(match.index + match[0].length);
+        const bracket = /^\s*\[/.exec(after);
+        if (!bracket)
+            continue;
+        const openIndex = match.index + match[0].length + (bracket[0].length - 1);
+        const closeIndex = matchingBracketEnd(source, openIndex);
+        if (closeIndex < 0)
+            continue;
+        const names = stringLiteralsInList(source, openIndex, closeIndex);
+        if (names.length === 0)
+            continue;
+        if (firstIndex === undefined)
+            firstIndex = match.index;
+        const field = match[1];
+        if (field === 'uses')
+            uses.push(...names);
+        else if (field === 'reactsTo')
+            reactsTo.push(...names);
+        else if (field === 'raises')
+            raises.push(...names);
+        else
+            sends.push(...names);
+    }
+    if (firstIndex === undefined)
+        return [];
+    return [
+        {
+            file,
+            line: lineAt(content, firstIndex),
+            uses: uniqueSorted(uses),
+            reactsTo: uniqueSorted(reactsTo),
+            raises: uniqueSorted(raises),
+            sends: uniqueSorted(sends),
+        },
+    ];
+}

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

@@ -0,0 +1,57 @@
+/**
+ * HTML for the doctor ArkRun advisory (report parity: data-advisory="arkRun").
+ */
+export function formatArkRunHtml(section, esc) {
+  if (!section || typeof section !== 'object' || section.notAScore !== true) return '';
+  const escape = typeof esc === 'function' ? esc : (v) => String(v);
+  const note = section.note ? `<p class="muted">${escape(section.note)}</p>` : '';
+  if (section.active !== true) {
+    return `
+  <section class="section card" data-advisory="arkRun">
+    <h2>ArkRun <span class="muted">(opt-in extra — not a score)</span></h2>
+    <p class="dim" style="margin:.15rem 0 .55rem;font-size:.88rem">
+      Kernel usage + complete declarations. Absence is silent — Layers and ArkRules verdicts stay the same.
+    </p>
+    ${note}
+  </section>`;
+  }
+  const residual = section.residual && typeof section.residual === 'object' ? section.residual : { count: 0, ruleIds: [] };
+  const ids = Array.isArray(residual.ruleIds) ? residual.ruleIds : [];
+  const residualHtml =
+    residual.count > 0
+      ? `<p><span class="tag warn">residual</span> ${ids
+          .map((id) => `<code>${escape(id)}</code>`)
+          .join(' · ')}${
+          residual.count > ids.length ? ` <span class="muted">(+${residual.count - ids.length} more)</span>` : ''
+        }</p>`
+      : '<p class="muted">Residual: none on this scan (not a score — green extras ≠ finished kernel wiring).</p>';
+  const teeth = section.extraMergeTeeth === true
+    ? '<span class="tag">extra merge teeth armed</span>'
+    : '<span class="tag warn">extra merge teeth not armed</span>';
+  const mergeSentence =
+    section.mergePlanes && typeof section.mergePlanes.failMergeWhen === 'string'
+      ? section.mergePlanes.failMergeWhen
+      : section.failMergeWhen;
+  const merge =
+    mergeSentence
+      ? `<p class="muted" style="margin:.35rem 0 .55rem;font-size:.86rem"><b>Merge planes:</b> ${escape(mergeSentence)}</p>`
+      : '';
+  return `
+  <section class="section card" data-advisory="arkRun">
+    <h2>ArkRun <span class="muted">(not a score)</span></h2>
+    <p class="dim" style="margin:.15rem 0 .55rem;font-size:.88rem">
+      <b>[ArkRun]</b> Kernel usage + declarations — separate from <b>[Layer]</b> imports and <b>[ArkRules]</b> shape.
+      Advisory never flips <code>valid</code>. Enforced extra teeth only when the layer plane is classified.
+    </p>
+    ${merge}
+    <div class="kpis" style="margin-bottom:.55rem">
+      <div class="kpi"><b>${escape(section.mode || '—')}</b><span>Mode</span></div>
+      <div class="kpi"><b>${Number(residual.count) || 0}</b><span>Residual ids</span></div>
+      <div class="kpi"><b>${Number(section.compositionRoots) || 0}</b><span>Composition roots</span></div>
+      <div class="kpi"><b>${Number(section.managedLayers) || 0}</b><span>Managed layers</span></div>
+    </div>
+    <p>${teeth} · <code>notAScore</code></p>
+    ${residualHtml}
+    ${note}
+  </section>`;
+}