arkgate 3.9.1 → 4.0.0

package/bin/lib/graph-blind.mjs

@@ -0,0 +1,254 @@
+/**
+ * Advisory graph-blind spots (Y09 direction — still parked as blocker work).
+ *
+ * Template-interpolation dynamic imports (`import(\`./x/${name}\`)`) never
+ * enter the static edge graph. Surface them as an advisory count + capped list
+ * so governed trees know where analysis is incomplete — never a hard verdict
+ * change, never false green from silence.
+ *
+ * Performance: lightweight AST walk only (no extractSemanticDependencies /
+ * full semantic binding). Doctor resident warm must stay under the 500 ms UX
+ * ceiling at the 10k fixture.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { normalize } from './scan-files.mjs';
+
+const MAX_LIST = 8;
+const MAX_FILE_BYTES = 256 * 1024;
+/** Full AST scan stays off huge trees so doctor resident warm keeps the 500 ms UX ceiling. */
+const MAX_FULL_SCAN_FILES = 2500;
+const LEXICAL_GATE = /\b(?:import|require)\s*\(|\bimport\s+\w+\s*=\s*require\s*\(/;
+
+/**
+ * Classify an unresolved dynamic dependency argument.
+ * @returns {'template-interpolation'|'non-literal'|null}
+ */
+export function classifyUnresolvedDependencyArg(ts, arg) {
+  if (!ts || !arg) return null;
+  if (ts.isTemplateExpression(arg)) return 'template-interpolation';
+  // NoSubstitutionTemplateLiteral is string-literal-like and already resolved.
+  if (ts.isStringLiteralLike(arg)) return null;
+  return 'non-literal';
+}
+
+/**
+ * Specifier expression for a dependency node (CallExpression or ImportEquals).
+ */
+export function unresolvedDependencyArg(ts, node) {
+  if (!node || typeof node !== 'object') return undefined;
+  if (Array.isArray(node.arguments)) return node.arguments[0];
+  // import x = require(expr) — ExternalModuleReference.expression
+  const modRef = node.moduleReference;
+  if (modRef && typeof modRef === 'object' && modRef.expression) return modRef.expression;
+  if (ts?.isExternalModuleReference?.(modRef) && modRef.expression) return modRef.expression;
+  return undefined;
+}
+
+/**
+ * Collect unresolvable dynamic import/require call sites with a shallow walk.
+ * Avoids extractSemanticDependencies (full binding / export walk) on every file.
+ */
+function collectDynamicBlindEdges(ts, sourceFile, rel, edges) {
+  const visit = (node) => {
+    // import('x') / require('x') / import(`./${x}`)
+    if (ts.isCallExpression(node) && node.expression) {
+      const expr = node.expression;
+      const isImport =
+        expr.kind === ts.SyntaxKind.ImportKeyword ||
+        (ts.isIdentifier(expr) && expr.text === 'import');
+      const isRequire = ts.isIdentifier(expr) && expr.text === 'require';
+      if (isImport || isRequire) {
+        const arg = node.arguments?.[0];
+        const reason = classifyUnresolvedDependencyArg(ts, arg);
+        if (reason) {
+          const { line } = sourceFile.getLineAndCharacterOfPosition(node.getStart(sourceFile));
+          edges.push({
+            file: rel,
+            line: line + 1,
+            kind: isRequire ? 'require' : 'import',
+            reason,
+          });
+        }
+      }
+    }
+
+    // import x = require(expr)
+    if (ts.isImportEqualsDeclaration?.(node) && node.moduleReference) {
+      const arg = unresolvedDependencyArg(ts, node);
+      const reason = classifyUnresolvedDependencyArg(ts, arg);
+      if (reason) {
+        const { line } = sourceFile.getLineAndCharacterOfPosition(node.getStart(sourceFile));
+        edges.push({
+          file: rel,
+          line: line + 1,
+          kind: 'require',
+          reason,
+        });
+      }
+    }
+
+    ts.forEachChild(node, visit);
+  };
+  visit(sourceFile);
+}
+
+/**
+ * Detect unresolvable import edges that leave the architecture graph incomplete.
+ *
+ * @returns {{
+ *   available: boolean,
+ *   advisory: true,
+ *   blockerGrade: false,
+ *   count: number,
+ *   templateInterpolationCount: number,
+ *   otherNonLiteralCount: number,
+ *   truncated: number,
+ *   edges: Array<{file:string,line:number,kind:string,reason:string}>,
+ *   note: string,
+ * }}
+ */
+export function detectGraphBlindSpots(ts, root, files = []) {
+  if (!ts) {
+    return {
+      available: false,
+      advisory: true,
+      blockerGrade: false,
+      count: 0,
+      templateInterpolationCount: 0,
+      otherNonLiteralCount: 0,
+      truncated: 0,
+      edges: [],
+      note: 'TypeScript was not available; graph-blind template-interpolation edges were not scanned.',
+    };
+  }
+
+  // Large-tree deferral: re-reading every path for an advisory sensor would blow the
+  // doctorResidentWarm 500 ms absolute UX ceiling at the 10k perf fixture.
+  if (files.length > MAX_FULL_SCAN_FILES) {
+    return {
+      available: true,
+      advisory: true,
+      blockerGrade: false,
+      deferred: true,
+      count: 0,
+      templateInterpolationCount: 0,
+      otherNonLiteralCount: 0,
+      truncated: 0,
+      edges: [],
+      note: `Graph-blind full scan deferred (${files.length} files > ${MAX_FULL_SCAN_FILES}). Non-literal dynamic import/require remain unresolvable in architecture analysis; advisory incomplete-graph honesty is not enumerated at this scale.`,
+    };
+  }
+
+  const resolvedRoot = path.resolve(root);
+  const edges = [];
+  for (const file of files) {
+    let source;
+    try {
+      const stats = fs.statSync(file);
+      if (!stats.isFile() || stats.size === 0 || stats.size > MAX_FILE_BYTES) continue;
+      source = fs.readFileSync(file, 'utf8');
+    } catch {
+      continue;
+    }
+    // Cheap lexical gate — dynamic import/require and import-equals require forms.
+    if (!LEXICAL_GATE.test(source)) continue;
+    // setParentNodes=false: we only need positions + node kinds.
+    const sourceFile = ts.createSourceFile(file, source, ts.ScriptTarget.ESNext, false);
+    const rel = normalize(path.relative(resolvedRoot, path.resolve(file)));
+    collectDynamicBlindEdges(ts, sourceFile, rel, edges);
+  }
+
+  edges.sort(
+    (a, b) =>
+      a.file.localeCompare(b.file) ||
+      a.line - b.line ||
+      a.reason.localeCompare(b.reason)
+  );
+
+  const templateInterpolationCount = edges.filter(
+    (e) => e.reason === 'template-interpolation'
+  ).length;
+  const otherNonLiteralCount = edges.length - templateInterpolationCount;
+  const truncated = Math.max(0, edges.length - MAX_LIST);
+  const listed = edges.slice(0, MAX_LIST);
+
+  return {
+    available: true,
+    advisory: true,
+    blockerGrade: false,
+    count: edges.length,
+    templateInterpolationCount,
+    otherNonLiteralCount,
+    truncated,
+    edges: listed,
+    note:
+      edges.length === 0
+        ? 'No unresolvable dynamic import/require edges detected in governed files (advisory scan).'
+        : `${edges.length} unresolvable dynamic edge(s) leave the architecture graph incomplete (${templateInterpolationCount} template-interpolation). Advisory only — never a hard architecture verdict; review or allowlist reviewed call sites.`,
+  };
+}
+
+/**
+ * Human doctor section. Unavailable prints a dim honesty line (not silence-as-done).
+ * Clean available scans stay silent.
+ */
+export function printGraphBlindSection(state, io) {
+  if (!state) return;
+  if (!state.available) {
+    console.log('');
+    console.log(io.color.bold('Graph blind spots (advisory)'));
+    io.line(
+      ' ',
+      io.color.dim(state.note || 'Graph-blind scan unavailable — incomplete-graph honesty not verified.')
+    );
+    return;
+  }
+  if (!state.count) return;
+  console.log('');
+  console.log(io.color.bold('Graph blind spots (advisory)'));
+  io.line(
+    io.warn,
+    `${state.count} unresolvable dynamic edge(s) (${state.templateInterpolationCount} template-interpolation) — graph incomplete`
+  );
+  for (const edge of state.edges.slice(0, 5)) {
+    io.line(
+      ' ',
+      io.color.dim(`[${edge.reason}] ${edge.file}:${edge.line} (${edge.kind})`)
+    );
+  }
+  if (state.count > 5) {
+    io.line(' ', io.color.dim(`…(+${state.count - 5} more in doctor JSON)`));
+  }
+  io.line(
+    ' ',
+    io.color.dim('advisory only — does not change the architecture verdict; edges are blind, not clean')
+  );
+}
+
+/**
+ * HTML report body for graphBlindSpots (X01 parity). `esc` is the report escaper.
+ * Kept here so html-report-advisories stays under budget.
+ */
+export function graphBlindSpotsHtml(state, esc = (v) => String(v)) {
+  if (!state) return '';
+  const edges = Array.isArray(state.edges) ? state.edges : [];
+  let body;
+  if (state.available === false) {
+    body = `<p class="muted">${esc(state.note ?? 'Graph-blind scan unavailable.')}</p>`;
+  } else if ((state.count ?? 0) === 0) {
+    body = '<p class="muted">No unresolvable dynamic import/require edges detected (advisory scan).</p>';
+  } else {
+    const list = edges
+      .slice(0, 8)
+      .map((e) => `<li><span class="tag warn">${esc(e.reason)}</span> <code>${esc(e.file)}:${e.line}</code> (${esc(e.kind)})</li>`)
+      .join('');
+    const more = state.truncated > 0 ? `<p class="muted">…(+${state.truncated} more in doctor JSON)</p>` : '';
+    body = `<p><span class="tag warn">${state.count} unresolvable</span> dynamic edge(s) — graph incomplete (${state.templateInterpolationCount ?? 0} template-interpolation).</p><ul>${list}</ul>${more}<p class="muted">Advisory only — does not change the architecture verdict; edges are blind, not clean.</p>`;
+  }
+  return `
+  <section data-advisory="graphBlindSpots">
+    <h2>Graph blind spots <span class="muted">(advisory — incomplete graph honesty; never a hard verdict)</span></h2>
+    ${body}
+  </section>`;
+}

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

@@ -8,6 +8,7 @@
  * this report from falling behind the product again.
  */
 import { effectiveCapabilityDeny } from './analysis-engine.mjs';
+import { graphBlindSpotsHtml } from './graph-blind.mjs';
 
 // htmlEscape is injected by the caller (html-report.mjs) — importing it back
 // would be a dependency cycle, and the repo's own gate blocks that. The
@@ -134,9 +135,9 @@ function ambientStateHtml(state) {
   }
   const findings = Array.isArray(state.findings) ? state.findings : [];
   const body = !state.active
-    ? '<p class="muted">Idle — no <code>pure: true</code> layer opted in. Declare a pure layer to scan module-scope mutable state.</p>'
+    ? '<p class="muted">Idle — no <code>pure: true</code> layer opted in. Advisory only; blocker-grade ambient diagnostics remain parked (Y07). Declare a pure layer to scan module-scope mutable state.</p>'
     : findings.length === 0
-      ? '<p class="muted">Active and clean — no module-scope <code>let</code>/<code>var</code> in pure layers.</p>'
+      ? '<p class="muted">Active and clean under the MVP envelope — still advisory; not a Y07 blocker-grade pass. No module-scope <code>let</code>/<code>var</code> in pure layers.</p>'
       : `<ul>${findings
           .slice(0, 10)
           .map(
@@ -147,7 +148,7 @@ function ambientStateHtml(state) {
         (state.acknowledged > 0 ? `<p class="muted">acknowledged module state: ${state.acknowledged}</p>` : '');
   return `
   <section data-advisory="ambientState">
-    <h2>Ambient state <span class="muted">(advisory — opt-in via pure layers; no strict mode exists)</span></h2>
+    <h2>Ambient state <span class="muted">(advisory — opt-in via pure layers; blocker-grade Y07 parked)</span></h2>
     ${body}
   </section>`;
 }
@@ -240,6 +241,29 @@ function parseHealthHtml(health) {
  * `computeDoctorAdvisories` returns — the parity guard enforces it.
  * @param escape injected HTML escaper (dependency points html-report → here only)
  */
+function rulesUnderContractHtml(section) {
+  if (!section || typeof section !== 'object') return '';
+  const note = section.note ? `<p class="muted">${esc(section.note)}</p>` : '';
+  if (section.active === false) {
+    return `
+  <section data-advisory="rulesUnderContract">
+    <h2>Rules under contract <span class="muted">(ArkRules opt-in)</span></h2>
+    ${note}
+  </section>`;
+  }
+  return `
+  <section data-advisory="rulesUnderContract">
+    <h2>Rules under contract <span class="muted">(counts — not a score)</span></h2>
+    <ul>
+      <li>Structure rules: <strong>${Number(section.structureRules) || 0}</strong></li>
+      <li>Invariants: <strong>${Number(section.invariants) || 0}</strong></li>
+      <li>Covered invariants: <strong>${Number(section.coveredInvariants) || 0}</strong></li>
+      <li>Uncovered invariants: <strong>${Number(section.uncoveredInvariants) || 0}</strong></li>
+    </ul>
+    ${note}
+  </section>`;
+}
+
 export function renderAdvisorySections(advisories, escape) {
   if (!advisories || typeof advisories !== 'object') return '';
   if (typeof escape === 'function') esc = escape;
@@ -248,6 +272,8 @@ export function renderAdvisorySections(advisories, escape) {
     ambientStateHtml(advisories.ambientState),
     physicalCohesionHtml(advisories.physicalCohesion),
     parseHealthHtml(advisories.parseHealth),
+    graphBlindSpotsHtml(advisories.graphBlindSpots, esc),
+    rulesUnderContractHtml(advisories.rulesUnderContract),
   ]
     .filter(Boolean)
     .join('\n');

package/bin/lib/install-migrate.mjs

@@ -138,14 +138,32 @@ export function warnLockfileConflict(root) {
 export function buildManagedAssetCatalog({ root, tools, compact = false, skillsOnly = false }) {
   const selectedTools = tools instanceof Set ? tools : new Set(tools ?? []);
   const assets = [];
+  // Path-keyed: codex + antigravity both target `.agents/skills/*/SKILL.md` (and
+  // antigravity + gemini share GEMINI.md). Duplicate plan entries caused apply to
+  // write once then fail the second pre-image assert (field: web-predial-ar).
+  const byPath = new Map();
   const add = (relativePath, content, kind = 'gate', scope = 'whole-file') => {
-    assets.push({
+    const existing = byPath.get(relativePath);
+    if (existing) {
+      // Shared destinations (codex+antigravity skills, antigravity+gemini GEMINI.md)
+      // must agree on bytes; silent first-wins would hide divergent host templates.
+      if (existing.content !== content || existing.kind !== kind || existing.scope !== scope) {
+        throw new Error(
+          `managed asset catalog conflict at ${JSON.stringify(relativePath)}: ` +
+            `hosts produced different content/kind/scope for the same path`
+        );
+      }
+      return;
+    }
+    const asset = {
       relativePath,
       content,
       kind,
       scope,
       templateId: `${kind}:${relativePath}`,
-    });
+    };
+    byPath.set(relativePath, asset);
+    assets.push(asset);
   };
 
   if (!skillsOnly) {

package/bin/lib/invariant-coverage-io.mjs

@@ -0,0 +1,157 @@
+/**
+ * Tooling I/O for ArkRules invariant coverage (AR10).
+ * Pure evaluation lives in Domain (`evaluateInvariantCoverage`); this module
+ * discovers test files and loads contents from disk (bounded).
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+
+const DEFAULT_TEST_NAME_RE =
+  /\.(test|spec)\.(ts|tsx|mts|cts|js|jsx|mjs|cjs)$|\/__tests__\/|\/tests?\//i;
+
+/** Max files to load for coverage evidence (budget). */
+const MAX_COVERAGE_FILES = 400;
+/** Max bytes per file when reading for title/symbol mining. */
+const MAX_FILE_BYTES = 256 * 1024;
+
+/**
+ * True when absolute is root or a file under root (separator-safe).
+ * @param {string} root
+ * @param {string} absolute
+ */
+function isPathInsideRoot(root, absolute) {
+  const rootResolved = path.resolve(root);
+  const absResolved = path.resolve(absolute);
+  if (absResolved === rootResolved) return true;
+  const relative = path.relative(rootResolved, absResolved);
+  return relative !== '' && !relative.startsWith('..') && !path.isAbsolute(relative);
+}
+
+/**
+ * Minimal glob match for testGlobs (double-star slash = zero path segments).
+ * @param {string} glob
+ * @param {string} file
+ */
+function matchSimpleGlob(glob, file) {
+  const pattern = String(glob || '').replace(/\\/g, '/');
+  const target = String(file || '').replace(/\\/g, '/');
+  if (!pattern) return false;
+  let out = '';
+  for (let i = 0; i < pattern.length; i += 1) {
+    const c = pattern[i];
+    if (c === '*') {
+      if (pattern[i + 1] === '*') {
+        if (pattern[i + 2] === '/') {
+          out += '(?:.*/)?';
+          i += 2;
+        } else {
+          out += '.*';
+          i += 1;
+        }
+      } else {
+        out += '[^/]*';
+      }
+    } else if (c === '?') {
+      out += '[^/]';
+    } else if (/[.+^${}()|[\]\\]/.test(c)) {
+      out += `\\${c}`;
+    } else {
+      out += c;
+    }
+  }
+  return new RegExp(`^${out}$`).test(target);
+}
+
+/**
+ * @param {string} root
+ * @param {{ files?: Array<{ path: string }> }} facts
+ * @param {{ testGlobs?: string[] }} [opts]
+ * @returns {{ fileContents: Record<string, string>, testFiles: string[], testGlobsMissing: boolean }}
+ */
+export function loadInvariantCoverageInputs(root, facts, opts = {}) {
+  const fileContents = {};
+  const testFiles = [];
+  const seen = new Set();
+  const testGlobs = Array.isArray(opts.testGlobs)
+    ? opts.testGlobs.filter((g) => typeof g === 'string' && g.length > 0)
+    : [];
+  const useCustomGlobs = testGlobs.length > 0;
+
+  const isTestPath = (rel) => {
+    if (useCustomGlobs) return testGlobs.some((g) => matchSimpleGlob(g, rel));
+    return DEFAULT_TEST_NAME_RE.test(rel);
+  };
+
+  const pushFile = (relPath, forceAsTest = false) => {
+    const rel = String(relPath || '')
+      .replace(/\\/g, '/')
+      .replace(/^\.\//, '');
+    if (!rel || seen.has(rel) || seen.size >= MAX_COVERAGE_FILES) return;
+    const absolute = path.resolve(root, rel);
+    if (!isPathInsideRoot(root, absolute)) return;
+    try {
+      const stat = fs.statSync(absolute);
+      if (!stat.isFile() || stat.size > MAX_FILE_BYTES) return;
+      const content = fs.readFileSync(absolute, 'utf8');
+      seen.add(rel);
+      fileContents[rel] = content;
+      if (forceAsTest || isTestPath(rel)) testFiles.push(rel);
+    } catch {
+      // skip unreadable
+    }
+  };
+
+  for (const file of facts?.files ?? []) {
+    if (file?.path) pushFile(file.path);
+  }
+
+  if (useCustomGlobs) {
+    // Walk project roots and keep files matching custom globs.
+    for (const dir of ['.', 'tests', 'test', 'src', '__tests__', 'spec']) {
+      const absDir = path.join(root, dir === '.' ? '' : dir);
+      if (!fs.existsSync(absDir)) continue;
+      walkTestFiles(absDir, root, (rel) => {
+        if (isTestPath(rel)) pushFile(rel, true);
+      });
+    }
+  } else {
+    // Walk common test roots when facts only cover production include globs.
+    for (const dir of ['tests', 'test', 'src', '__tests__']) {
+      const absDir = path.join(root, dir);
+      if (!fs.existsSync(absDir)) continue;
+      walkTestFiles(absDir, root, (rel) => {
+        if (isTestPath(rel)) pushFile(rel, true);
+      });
+    }
+  }
+
+  const testGlobsMissing = testFiles.length === 0;
+  return { fileContents, testFiles, testGlobsMissing };
+}
+
+/**
+ * @param {string} dir
+ * @param {string} root
+ * @param {(rel: string) => void} onFile
+ * @param {number} [depth]
+ */
+function walkTestFiles(dir, root, onFile, depth = 0) {
+  if (depth > 8) return;
+  let entries;
+  try {
+    entries = fs.readdirSync(dir, { withFileTypes: true });
+  } catch {
+    return;
+  }
+  for (const entry of entries) {
+    if (entry.name === 'node_modules' || entry.name === 'dist' || entry.name === '.git') continue;
+    const absolute = path.join(dir, entry.name);
+    if (entry.isDirectory()) {
+      walkTestFiles(absolute, root, onFile, depth + 1);
+      continue;
+    }
+    if (!entry.isFile()) continue;
+    const rel = path.relative(root, absolute).replace(/\\/g, '/');
+    onFile(rel);
+  }
+}

package/bin/lib/invariant-coverage.mjs

@@ -0,0 +1,127 @@
+/**
+ * GENERATED FILE — do not edit by hand.
+ *
+ * Canonical algorithm: src/domain/invariantCoverage.ts
+ * Regenerate: node scripts/generate-cli-pure.mjs
+ * Drift check: node scripts/generate-cli-pure.mjs --check
+ *
+ * Pure CLI helper (bin/lib/invariant-coverage.mjs). Zero Node I/O.
+ */
+
+function titleMatchesInvariant(content, id) {
+    // Match describe/it/test string titles containing the invariant id.
+    const escaped = id.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+    const re = new RegExp(`(?:describe|it|test|context)\\s*\\(\\s*['"\`][^'"\`]*${escaped}[^'"\`]*['"\`]`, 'i');
+    return re.test(content) || content.includes(id);
+}
+function symbolPresent(fileContents, symbol) {
+    if (!symbol)
+        return false;
+    // Support Aggregate.method or bare method name.
+    const parts = symbol.split('.');
+    const needle = parts[parts.length - 1];
+    const className = parts.length > 1 ? parts[0] : null;
+    for (const content of Object.values(fileContents)) {
+        if (className && !content.includes(className))
+            continue;
+        if (new RegExp(`(?:function\\s+|\\b)${needle.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}\\s*[(<]`).test(content) ||
+            content.includes(symbol)) {
+            return true;
+        }
+    }
+    return false;
+}
+export function evaluateInvariantCoverage(input) {
+    const invariants = input.arkRules.invariants ?? [];
+    if (invariants.length === 0) {
+        return { coverage: [], violations: [], partial: false };
+    }
+    const testFiles = input.testFiles ?? [];
+    const testGlobsMissing = input.testGlobsMissing === true || testFiles.length === 0;
+    const coverage = [];
+    const violations = [];
+    for (const inv of invariants) {
+        const evidence = [];
+        const wantsTest = inv.coverage?.test !== false; // default: prefer test evidence when catalogued
+        const symbol = inv.coverage?.symbol;
+        if (!testGlobsMissing && wantsTest) {
+            for (const file of testFiles) {
+                const content = input.fileContents[file];
+                if (content && titleMatchesInvariant(content, inv.id)) {
+                    evidence.push('test-title');
+                    break;
+                }
+            }
+        }
+        if (symbol && symbolPresent(input.fileContents, symbol)) {
+            evidence.push('symbol');
+        }
+        // Covered if any requested evidence is present.
+        // When coverage declares neither test nor symbol, require at least description-only advisory presence = not covered.
+        const requiresEvidence = inv.coverage?.test === true || Boolean(symbol) || inv.coverage === undefined;
+        const covered = requiresEvidence && evidence.length > 0
+            ? true
+            : inv.coverage?.test === false && !symbol
+                ? true // explicitly no coverage requirements
+                : evidence.length > 0;
+        // Partial only when tests are missing *and* no other evidence (e.g. symbol) completed coverage.
+        const partial = testGlobsMissing && wantsTest && evidence.length === 0;
+        coverage.push({
+            invariantId: inv.id,
+            layer: inv.provenance.layer,
+            sourceFile: inv.provenance.sourceFile,
+            mode: inv.mode,
+            covered: covered && !partial,
+            evidence,
+            partial,
+            description: inv.description,
+        });
+        if (!covered || partial) {
+            // Enforced + proven uncovered → failsStrict; partial always advisory (never fake green).
+            const failsStrict = inv.mode === 'enforced' && !partial;
+            violations.push({
+                ruleId: 'INVARIANT_UNCOVERED',
+                message: partial
+                    ? `Invariant ${inv.id} coverage cannot be proven (test globs missing or empty); reporting partial, not covered.`
+                    : `Invariant ${inv.id} is not covered by a test title or declared symbol.`,
+                file: inv.provenance.sourceFile,
+                line: 1,
+                arkruleId: inv.id,
+                arkruleSource: inv.provenance.sourceFile,
+                fromLayer: inv.provenance.layer,
+                severity: failsStrict ? 'error' : 'warning',
+                failsStrict,
+            });
+        }
+    }
+    // Top-level partial only from entry flags (symbol-only coverage must not stick partial).
+    return {
+        coverage,
+        violations,
+        partial: coverage.some((entry) => entry.partial),
+    };
+}
+/**
+ * Deterministic promotion gate: refuse advisory→enforced when invariant is uncovered.
+ */
+export function canPromoteInvariant(coverage) {
+    if (!coverage) {
+        return {
+            ok: false,
+            reason: 'No coverage evidence supplied for this invariant; evaluate coverage before promoting to enforced.',
+        };
+    }
+    if (coverage.partial) {
+        return {
+            ok: false,
+            reason: 'Coverage is partial (missing test globs); cannot promote until evidence is complete.',
+        };
+    }
+    if (!coverage.covered) {
+        return {
+            ok: false,
+            reason: `Invariant ${coverage.invariantId} is uncovered; add a test title or symbol before promoting to enforced.`,
+        };
+    }
+    return { ok: true, reason: `Invariant ${coverage.invariantId} has coverage evidence.` };
+}