arkgate 4.6.6 → 4.7.0

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/deep-module-coach.mjs

@@ -22,6 +22,8 @@ export const HOT_PATH_COMMIT_LIMIT = 200;
 export const HOT_PATH_LIST_CAP = 8;
 /** Minimum change hits before a path is “elevated”. */
 export const HOT_PATH_MIN_HITS = 3;
+/** Kill hung git instead of stalling CI. */
+export const SPAWN_TIMEOUT_MS = 8000;
 
 /**
  * Best-effort recent-churn paths from git history.
@@ -40,6 +42,7 @@ export function computeHotPathAdvisory(root, opts = {}) {
             encoding: 'utf8',
             maxBuffer: 8 * 1024 * 1024,
             stdio: ['ignore', 'pipe', 'pipe'],
+            timeout: SPAWN_TIMEOUT_MS,
           });
 
   const emptyUnavailable = (reason) => ({

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);
+    }
+  }
 }