arkgate 4.8.19 → 4.8.21

package/bin/lib/upgrade-outcome.mjs

@@ -0,0 +1,359 @@
+/**
+ * UpgradeOutcome — one value for `upgrade --apply`.
+ *
+ * Sketch (D2). Callers see one object and one exit mapping. Gitignore
+ * detection, rule aggregation, and version-note lookup stay in here.
+ *
+ *   classifyManagedAsset({ ..., gitignored }) →
+ *     { state: 'absent-local', requiresConsent: false } when recorded + gitignored + missing
+ *
+ *   runPostUpgradeVerification(root) →
+ *     { verdict: 'green'|'red'|'skipped', failing: [{ ruleId, count, sample }], behaviorChanges: string[] }
+ *
+ *   exitCodeFor(outcome) →
+ *     0 applied+green (also nothing-to-apply / verification skipped)
+ *     3 applied+red
+ *     2 blocked
+ *     1 error
+ *
+ * JSON fields on the existing upgrade payload are additive (`outcome`, `postUpgrade`,
+ * per-asset `reason` / `nextCommand`, state `absent-local`).
+ */
+import { spawnSync } from 'node:child_process';
+
+import { behaviorChangeLines } from './upgrade-behavior-changes.mjs';
+
+/**
+ * @typedef {'applied-green'|'applied-skipped'|'applied-red'|'blocked'|'error'|'nothing'|'preview'} UpgradeOutcomeKind
+ * @typedef {{ ruleId: string, count: number, sample: string }} FailingRule
+ * @typedef {{
+ *   verdict: 'green'|'red'|'skipped',
+ *   failing: FailingRule[],
+ *   behaviorChanges: string[],
+ *   mode: 'strict-merge'|'skipped',
+ *   exitCode: number,
+ *   stderr?: string,
+ * }} PostUpgradeVerification
+ * @typedef {{
+ *   kind: UpgradeOutcomeKind,
+ *   applied: boolean,
+ *   blocked: boolean,
+ *   postUpgrade: PostUpgradeVerification|null,
+ *   error?: string,
+ * }} UpgradeOutcome
+ */
+
+export const ABSENT_LOCAL_REASON =
+  'Recorded managed file is missing and gitignored (per-machine file). Recreated without consent.';
+
+/**
+ * @param {string} state
+ * @returns {string}
+ */
+export function blockedAssetReason(state) {
+  if (state === 'missing') {
+    return 'Recorded managed file is missing and is not gitignored. Apply will not recreate a deleted file without consent.';
+  }
+  if (state === 'conflicted') {
+    return 'Managed base and local edits both changed. Apply will not overwrite without consent.';
+  }
+  return 'Apply needs consent before changing this managed file.';
+}
+
+/**
+ * Paths git would ignore. Not a git repo, or git missing → empty set
+ * (fail closed toward consent). Global excludes are not consulted.
+ *
+ * @param {string} root
+ * @param {string[]} relativePaths
+ * @returns {Set<string>}
+ */
+export function gitignoredPathSet(root, relativePaths) {
+  const paths = [...new Set(relativePaths.filter((entry) => typeof entry === 'string' && entry.length > 0))];
+  if (paths.length === 0) return new Set();
+  let result;
+  try {
+    result = spawnSync(
+      'git',
+      ['-c', 'core.excludesFile=/dev/null', 'check-ignore', '-z', '--stdin'],
+      {
+        cwd: root,
+        input: `${paths.join('\0')}\0`,
+        encoding: 'utf8',
+        timeout: 5000,
+        env: {
+          ...process.env,
+          GIT_CONFIG_NOSYSTEM: '1',
+          GIT_CONFIG_GLOBAL: '/dev/null',
+        },
+      }
+    );
+  } catch {
+    return new Set();
+  }
+  if (!result || result.error || (result.status !== 0 && result.status !== 1)) return new Set();
+  const ignored = new Set();
+  for (const entry of String(result.stdout ?? '').split('\0')) {
+    if (entry) ignored.add(entry);
+  }
+  return ignored;
+}
+
+/**
+ * @param {unknown} check
+ * @returns {FailingRule[]}
+ */
+export function aggregateFailingRules(check) {
+  const violations = Array.isArray(check?.violations) ? check.violations : [];
+  /** @type {Map<string, FailingRule>} */
+  const groups = new Map();
+  for (const violation of violations) {
+    if (!violation || typeof violation !== 'object') continue;
+    if (violation.failsStrict === false) continue;
+    const ruleId = typeof violation.ruleId === 'string' && violation.ruleId.trim()
+      ? violation.ruleId.trim()
+      : 'UNKNOWN';
+    const existing = groups.get(ruleId) ?? { ruleId, count: 0, sample: '' };
+    existing.count += 1;
+    if (!existing.sample) existing.sample = sampleForViolation(violation, ruleId);
+    groups.set(ruleId, existing);
+  }
+  return [...groups.values()].sort(
+    (left, right) => right.count - left.count || left.ruleId.localeCompare(right.ruleId)
+  );
+}
+
+/**
+ * @param {Record<string, unknown>} violation
+ * @param {string} ruleId
+ */
+function sampleForViolation(violation, ruleId) {
+  const file = typeof violation.file === 'string'
+    ? violation.file
+    : typeof violation.path === 'string'
+      ? violation.path
+      : '';
+  const line = Number.isInteger(violation.line) ? `:${violation.line}` : '';
+  const where = file ? `${file}${line}` : '';
+  const message = typeof violation.message === 'string' ? violation.message.trim() : '';
+  const sample = [where, message].filter(Boolean).join(' — ') || ruleId;
+  return sample.length > 180 ? `${sample.slice(0, 177)}...` : sample;
+}
+
+/**
+ * @param {string} stdout
+ * @returns {Record<string, unknown>|null}
+ */
+export function parseCheckStdout(stdout) {
+  const text = typeof stdout === 'string' ? stdout.trim() : '';
+  if (!text) return null;
+  try {
+    const parsed = JSON.parse(text);
+    return parsed && typeof parsed === 'object' ? parsed : null;
+  } catch {
+    const start = text.indexOf('{');
+    const end = text.lastIndexOf('}');
+    if (start === -1 || end <= start) return null;
+    try {
+      const parsed = JSON.parse(text.slice(start, end + 1));
+      return parsed && typeof parsed === 'object' ? parsed : null;
+    } catch {
+      return null;
+    }
+  }
+}
+
+/**
+ * @param {string} root
+ * @param {string} arkCheck
+ * @returns {{ exitCode: number, stdout: string, stderr: string }}
+ */
+function spawnArchitectureCheck(root, arkCheck) {
+  if (typeof arkCheck !== 'string' || !arkCheck) {
+    return { exitCode: 1, stdout: '', stderr: 'architecture check binary is missing' };
+  }
+  const result = spawnSync(
+    process.execPath,
+    [arkCheck, '--root', root, '--config', 'ark.config.json', '--strict-merge', '--json'],
+    {
+      cwd: root,
+      stdio: ['ignore', 'pipe', 'pipe'],
+      encoding: 'utf8',
+    }
+  );
+  return {
+    exitCode: result.status ?? 1,
+    stdout: result.stdout ?? '',
+    stderr: result.stderr ?? '',
+  };
+}
+
+/**
+ * Structured post-upgrade verification. Reuses check JSON (rule ids), and
+ * attaches behavior-change lines from the shipped per-version table.
+ *
+ * @param {string} root
+ * @param {{
+ *   strict?: boolean,
+ *   arkCheck?: string,
+ *   packageVersion?: string,
+ *   checkResult?: { exitCode?: number, status?: number, stdout?: string, stderr?: string },
+ * }} [options]
+ * @returns {PostUpgradeVerification}
+ */
+export function runPostUpgradeVerification(root, options = {}) {
+  const behaviorChanges = behaviorChangeLines();
+  if (options.strict === false) {
+    return {
+      verdict: 'skipped',
+      failing: [],
+      behaviorChanges,
+      mode: 'skipped',
+      exitCode: 0,
+    };
+  }
+  const raw = options.checkResult ?? spawnArchitectureCheck(root, options.arkCheck);
+  const parsed = parseCheckStdout(raw.stdout ?? '');
+  const failing = aggregateFailingRules(parsed);
+  const exitCode = raw.exitCode ?? raw.status ?? 1;
+  const red = exitCode !== 0 || parsed?.ok === false || parsed?.valid === false;
+  if (red && failing.length === 0) {
+    const sampleSource = String(raw.stderr || 'architecture check failed').trim() || 'architecture check failed';
+    failing.push({
+      ruleId: 'ARCHITECTURE_CHECK',
+      count: 1,
+      sample: sampleSource.length > 180 ? `${sampleSource.slice(0, 177)}...` : sampleSource,
+    });
+  }
+  const stderr = typeof raw.stderr === 'string' && raw.stderr.trim() ? raw.stderr.trim() : undefined;
+  return {
+    verdict: red ? 'red' : 'green',
+    failing: red ? failing : [],
+    behaviorChanges,
+    mode: 'strict-merge',
+    exitCode: red ? (exitCode || 1) : 0,
+    ...(stderr ? { stderr } : {}),
+  };
+}
+
+/**
+ * @param {{
+ *   applied?: boolean,
+ *   blocked?: boolean,
+ *   nothingToApply?: boolean,
+ *   postUpgrade?: PostUpgradeVerification|null,
+ *   error?: unknown,
+ * }} input
+ * @returns {UpgradeOutcome}
+ */
+export function upgradeOutcome(input) {
+  if (input.error != null && input.error !== false) {
+    const message = input.error instanceof Error ? input.error.message : String(input.error);
+    return { kind: 'error', applied: false, blocked: false, postUpgrade: null, error: message };
+  }
+  if (input.blocked) {
+    return { kind: 'blocked', applied: false, blocked: true, postUpgrade: null };
+  }
+  if (input.nothingToApply && !input.applied) {
+    return { kind: 'nothing', applied: false, blocked: false, postUpgrade: null };
+  }
+  const postUpgrade = input.postUpgrade ?? null;
+  if (postUpgrade?.verdict === 'red') {
+    return { kind: 'applied-red', applied: true, blocked: false, postUpgrade };
+  }
+  if (postUpgrade?.verdict === 'skipped') {
+    return { kind: 'applied-skipped', applied: Boolean(input.applied), blocked: false, postUpgrade };
+  }
+  return { kind: 'applied-green', applied: Boolean(input.applied), blocked: false, postUpgrade };
+}
+
+/**
+ * @param {UpgradeOutcome|null|undefined} outcome
+ * @returns {0|1|2|3}
+ */
+export function exitCodeFor(outcome) {
+  switch (outcome?.kind) {
+    case 'applied-green':
+    case 'applied-skipped':
+    case 'nothing':
+    case 'preview':
+      return 0;
+    case 'applied-red':
+      return 3;
+    case 'blocked':
+      return 2;
+    case 'error':
+      return 1;
+    default:
+      return 1;
+  }
+}
+
+/**
+ * @param {{ mode?: string, exitCode?: number, verdict?: string }} [verification]
+ * @returns {boolean|null}
+ */
+export function architectureVerificationOk(verification) {
+  if (!verification || verification.mode === 'skipped' || verification.verdict === 'skipped') return null;
+  if (verification.verdict === 'green') return true;
+  if (verification.verdict === 'red') return false;
+  if (verification.exitCode === 0) return true;
+  if (typeof verification.exitCode === 'number') return false;
+  return null;
+}
+
+/**
+ * @param {{ mode?: string, exitCode?: number, verdict?: string, failing?: FailingRule[] }} [verification]
+ * @returns {string}
+ */
+export function architectureVerificationDetail(verification) {
+  if (!verification || verification.mode === 'skipped' || verification.verdict === 'skipped') {
+    return 'Strict architecture verification was skipped (--no-strict).';
+  }
+  const code = verification.exitCode;
+  if (architectureVerificationOk(verification) === true) {
+    return 'Strict-merge architecture verification passed.';
+  }
+  const failing = Array.isArray(verification.failing) ? verification.failing : [];
+  const rules = failing.map((row) => `${row.ruleId} ×${row.count}`).join(', ');
+  const head = `Architecture verification exit ${code ?? 'unknown'}.`;
+  if (!rules) return head;
+  return `${head} Failing rules: ${rules}. Read behaviorChanges before editing code.`;
+}
+
+/**
+ * @param {{ assets?: Array<{ blocked?: boolean, path?: string, state?: string, reason?: string, nextCommand?: string }>, blocked?: boolean, nextCommand?: string }} plan
+ * @param {{ refused?: boolean }} [options]
+ * @returns {string[]}
+ */
+export function formatBlockedAssets(plan, options = {}) {
+  const blocked = (plan?.assets ?? []).filter((asset) => asset?.blocked);
+  if (blocked.length === 0) return [];
+  const lines = [options.refused ? 'Apply refused.' : 'Blocked until you consent:'];
+  for (const asset of blocked) {
+    const reason = asset.reason || blockedAssetReason(asset.state ?? '');
+    lines.push(`  ${asset.path} — ${reason}`);
+  }
+  const next = blocked.find((asset) => asset.nextCommand)?.nextCommand ?? plan?.nextCommand;
+  if (next) lines.push(`Next: ${next}`);
+  return lines;
+}
+
+/**
+ * @param {PostUpgradeVerification|null|undefined} postUpgrade
+ * @returns {string[]}
+ */
+export function formatPostUpgradeHuman(postUpgrade) {
+  if (!postUpgrade) return [];
+  const lines = [`Post-upgrade verification: ${postUpgrade.verdict}.`];
+  if (postUpgrade.verdict !== 'red') return lines;
+  lines.push('Failing rules:');
+  const failing = postUpgrade.failing ?? [];
+  if (failing.length === 0) lines.push('  (check returned red without a rule id)');
+  for (const row of failing) {
+    lines.push(`  ${row.ruleId} ×${row.count} — ${row.sample}`);
+  }
+  lines.push('Read behaviorChanges before editing code.');
+  for (const note of postUpgrade.behaviorChanges ?? []) lines.push(`  ${note}`);
+  return lines;
+}

package/bin/lib/violations.mjs

@@ -97,6 +97,115 @@ export function printWarning(warning) {
   );
 }
 
+/** Advisory the engine emits once per shared-root → slice edge. Humans see a group. */
+export const SHARED_IMPORTS_SLICE_RULE_ID = 'SHARED_IMPORTS_SLICE';
+
+/**
+ * Where the full per-edge list lives. Human check output names this on every
+ * grouped line. `--json` is the machine list; `--doctor` prints every edge.
+ */
+export const SHARED_IMPORTS_SLICE_FULL_LIST =
+  'Full list: ark-check --json or ark-check --doctor';
+
+const SHARED_IMPORTS_SLICE_EXAMPLE_LIMIT = 3;
+
+function formatAdvisoryCount(count) {
+  return String(count).replace(/\B(?=(\d{3})+(?!\d))/g, ',');
+}
+
+function layerLabel(value) {
+  return typeof value === 'string' && value.trim() ? value.trim() : '?';
+}
+
+/** Group key: one fact per rule and layer edge. */
+export function sharedImportsSliceGroupKey(warning) {
+  return [
+    typeof warning?.ruleId === 'string' ? warning.ruleId : SHARED_IMPORTS_SLICE_RULE_ID,
+    layerLabel(warning?.fromLayer),
+    layerLabel(warning?.toLayer),
+  ].join('\0');
+}
+
+function formatSharedImportsSliceExample(warning) {
+  const file = typeof warning?.file === 'string' && warning.file.trim() ? warning.file.trim() : 'unknown';
+  const line = Number.isInteger(warning?.line) && warning.line > 0 ? warning.line : 1;
+  const slice =
+    typeof warning?.toSlice === 'string' && warning.toSlice.trim() ? warning.toSlice.trim() : 'slice';
+  const target =
+    typeof warning?.target === 'string' && warning.target.trim() ? ` (${warning.target.trim()})` : '';
+  return `${file}:${line} → ${slice}${target}`;
+}
+
+/** One human line for a (ruleId, fromLayer → toLayer) group. Count plus top 3 edges. */
+export function formatSharedImportsSliceSummary(group) {
+  const sample = group[0] ?? {};
+  const ruleId =
+    typeof sample.ruleId === 'string' ? sample.ruleId : SHARED_IMPORTS_SLICE_RULE_ID;
+  const count = group.length;
+  const noun = count === 1 ? 'bridge' : 'bridges';
+  const examples = group
+    .slice(0, SHARED_IMPORTS_SLICE_EXAMPLE_LIMIT)
+    .map(formatSharedImportsSliceExample)
+    .join('; ');
+  return (
+    `warning ${ruleId} ${layerLabel(sample.fromLayer)} → ${layerLabel(sample.toLayer)}: ` +
+    `${formatAdvisoryCount(count)} shared-root → slice ${noun} (e.g. ${examples}). ` +
+    `The wall is direct-only. ${SHARED_IMPORTS_SLICE_FULL_LIST}`
+  );
+}
+
+/**
+ * Human check lines. SHARED_IMPORTS_SLICE collapses to one line per group.
+ * Every other warning stays one line. Does not mutate `warnings` — `--json`
+ * and doctor still walk the per-edge array.
+ */
+export function humanWarningLines(warnings) {
+  const groups = new Map();
+  const slots = [];
+  for (const warning of warnings ?? []) {
+    if (warning?.ruleId !== SHARED_IMPORTS_SLICE_RULE_ID) {
+      slots.push({ kind: 'line', line: formatWarningLine(warning) });
+      continue;
+    }
+    const key = sharedImportsSliceGroupKey(warning);
+    let group = groups.get(key);
+    if (!group) {
+      group = [];
+      groups.set(key, group);
+      slots.push({ kind: 'group', key });
+    }
+    group.push(warning);
+  }
+  return slots.map((slot) =>
+    slot.kind === 'line' ? slot.line : formatSharedImportsSliceSummary(groups.get(slot.key))
+  );
+}
+
+function printColoredWarningLine(line) {
+  const painted = line.startsWith('warning ')
+    ? `${color.yellow('warning')}${line.slice('warning'.length)}`
+    : line;
+  console.error(painted);
+}
+
+/** ark-check human renderer. Grouping stops here; the warnings array is unchanged. */
+export function printHumanWarnings(warnings) {
+  for (const line of humanWarningLines(warnings)) {
+    printColoredWarningLine(line);
+  }
+}
+
+/** Doctor human list: every shared-root → slice edge, not the grouped summary. */
+export function printSharedImportsSliceBridgeList(warnings) {
+  const lines = (warnings ?? [])
+    .filter((warning) => warning?.ruleId === SHARED_IMPORTS_SLICE_RULE_ID)
+    .map((warning) => formatWarningLine(warning));
+  if (lines.length === 0) return;
+  console.log('');
+  console.log(`Shared-root → slice bridges (${formatAdvisoryCount(lines.length)}):`);
+  for (const line of lines) console.log(line);
+}
+
 /** Non-blocking type-only placement debt: exit stays 0; do not paint ✖. */
 export function isNonBlockingPlacementDebt(violation) {
   return violation?.failsStrict === false;

package/dist/{configTypes-VD0qcubY.d.ts → configTypes-CTELo87-.d.ts}

@@ -49,6 +49,8 @@ type ArkConfigLayer = {
     /** Alias of reserved — empty pattern matches are allowed. */
     allowEmpty?: boolean;
 };
+/** How a starred `sliceFolders` prefix is named. Absent equals `path`. */
+type ArkConfigSliceIdentity = 'path' | 'stars';
 type ArkConfigRule = {
     from: string;
     to: string;
@@ -56,10 +58,17 @@ type ArkConfigRule = {
     message?: string;
     peerIsolation?: boolean;
     sliceFolders?: string[];
+    /**
+     * How a starred `sliceFolders` prefix is named.
+     * Absent and `path` keep today's ids. `stars` is the last literal plus the star bindings.
+     */
+    sliceIdentity?: ArkConfigSliceIdentity;
     /** Roots the repo declares shared on purpose — evidence, not unclassifiable. */
     sharedRoots?: string[];
     /** Directed slice→slice edges the repo declares on purpose. */
     allowedCrossSlice?: ArkConfigCrossSliceEdge[];
+    /** When `"deny"`, a declared shared root may not import a slice. */
+    sharedImportsSlice?: 'deny';
 };
 type ArkConfigCrossSliceEdge = {
     from: string;

package/dist/{diagnosticCatalog-D2v0ASN2.d.ts → diagnosticCatalog-B7BXlet6.d.ts}

@@ -1,5 +1,5 @@
-import { e as CreateArchitectureProfileOptions, b as ArchitectureProfile, d as ArkCheckConfig, C as CreateArchitectureProfileFromArkConfigOptions, f as CreateElevenLayerArkConfigOptions, i as Policy, j as IntentCreator, I as IntentName } from './types-D5GT5ZT8.js';
-import { A as ArkConfig, c as ArkConfigLoadResult } from './configTypes-VD0qcubY.js';
+import { e as CreateArchitectureProfileOptions, b as ArchitectureProfile, d as ArkCheckConfig, C as CreateArchitectureProfileFromArkConfigOptions, f as CreateElevenLayerArkConfigOptions, i as Policy, j as IntentCreator, I as IntentName } from './types-fQ9-KrBj.js';
+import { A as ArkConfig, c as ArkConfigLoadResult } from './configTypes-CTELo87-.js';
 
 /** Versioned public result contract types + JSON Schema (adapter envelope). */
 /**
@@ -392,7 +392,7 @@ declare function createAdapterResult(input: {
 }): CurrentAdapterResult;
 
 /** ArkGate library version — single source of truth. */
-declare const version = "4.8.19";
+declare const version = "4.8.21";
 
 /**
  * AI Code Gate (basic).
@@ -1722,10 +1722,60 @@ type EffectiveArkRules = {
 /**
  * Pure invariant coverage evidence (ADR 0014 / AR09–AR10).
  *
- * Mines test titles and symbol presence against the Effective ArkRules catalog.
+ * Mines test titles and symbol declarations against the Effective ArkRules catalog.
+ * `classifyCoverage` returns one verdict; `countsAsCoverage` is the policy;
+ * `describeCoverage` is the sentence. A bare mention is never coverage.
  * No filesystem — Tooling supplies file contents and test globs.
  */
 
+/**
+ * How a `coverage.symbol` identifier is declared. `type`, `interface`, and
+ * `enum` are declarations — the same witness as function, class, const, and
+ * method.
+ */
+type DeclarationShape = 'function' | 'class' | 'const' | 'method' | 'type' | 'interface' | 'enum';
+/** Where a bare mention of an id or symbol sat. Never coverage. */
+type MentionContext = 'test-body' | 'comment' | 'string' | 'import';
+/**
+ * One coverage verdict. Best evidence wins: test-title, then declaration,
+ * then mention-only, then none. Regexes, the test-file vs source split, and
+ * `Aggregate.method` lookup stay behind this value.
+ */
+type CoverageEvidence = {
+    kind: 'test-title';
+    file: string;
+    title: string;
+} | {
+    kind: 'declaration';
+    file: string;
+    shape: DeclarationShape;
+} | {
+    kind: 'mention-only';
+    file: string;
+    context: MentionContext;
+} | {
+    kind: 'none';
+};
+/** Invariant fields the classifier reads. A full catalog entry is assignable. */
+type CoverageInvariant = {
+    id: string;
+    coverage?: {
+        test?: boolean;
+        symbol?: string;
+    } | null;
+};
+/** File set the classifier reads. Tooling has already loaded the contents. */
+type CoverageFiles = {
+    /** Project-relative path → file contents (tests and sources). */
+    fileContents: Readonly<Record<string, string>>;
+    /** Paths already classified as tests. */
+    testFiles?: readonly string[];
+    /**
+     * Declared runner roots. A test title inside a root beats one outside it.
+     * The outside-roots finding stays a separate verdict.
+     */
+    coverageRoots?: readonly string[];
+};
 type InvariantCoverageEvidence = {
     invariantId: string;
     layer: string;
@@ -1738,6 +1788,17 @@ type InvariantCoverageEvidence = {
     description: string;
     /** Test file that supplied the `test-title` evidence, when there was one. */
     testEvidenceFile?: string;
+    /**
+     * Non-test file that declares `coverage.symbol`. Absent when the name only
+     * appears in an import or a call. ArkGate never runs tests; this path is the
+     * declaration text, not a passing suite.
+     */
+    symbolEvidenceFile?: string;
+    /**
+     * Declaration shape when `evidence` includes `symbol`. Additive: readers that
+     * only know `test-title` | `symbol` ignore it.
+     */
+    shape?: DeclarationShape;
     /**
      * The only covering test found sits outside `coverage.coverageRoots` — the
      * places the project declares its runner executes. ArkGate never runs tests,
@@ -1835,6 +1896,19 @@ type InvariantCoverageStats = {
         outOfRoot: number;
     };
 };
+/**
+ * Best coverage evidence for `invariant` in `files`.
+ * test-title beats a declaration; a declaration beats a bare mention; a bare
+ * mention beats silence. Callers do not re-scan to explain the verdict.
+ */
+declare function classifyCoverage(invariant: CoverageInvariant, files: CoverageFiles): CoverageEvidence;
+/**
+ * Policy: a test title or any declaration counts, including type, interface,
+ * and enum. A mention-only verdict never counts. `none` does not count.
+ */
+declare function countsAsCoverage(ev: CoverageEvidence): boolean;
+/** Sentence for the verdict. `INVARIANT_UNCOVERED` prints this; it does not re-derive it. */
+declare function describeCoverage(invariant: CoverageInvariant, ev: CoverageEvidence): string;
 declare function evaluateInvariantCoverage(input: EvaluateInvariantCoverageInput): {
     coverage: InvariantCoverageEvidence[];
     violations: InvariantCoverageViolation[];
@@ -2484,4 +2558,4 @@ declare function catalogFixForRuleId(ruleId: string | null | undefined): string
  */
 declare function catalogWhyForRuleId(ruleId: string | null | undefined): string | undefined;
 
-export { type ArchitectureChangeMapFile as $, type AdapterViolationInput as A, type AdapterResult as B, type AdapterSeverity as C, type AnalysisCapabilityUse as D, type EffectiveArkRules as E, type AnalysisCompilerOptions as F, type AnalysisCompleteness as G, type AnalysisContract as H, type AnalysisEvidence as I, type AnalysisFile as J, type AnalysisFileChange as K, type AnalysisFileInput as L, type AnalysisImportEdge as M, type AnalysisIr as N, type AnalysisMode as O, type AnalysisResult as P, type AnalysisViolation as Q, type ResolvedArkRunKernelCallKind as R, type AnalyzeArchitectureConvergenceInput as S, type AnalyzeChangeInput as T, type AnalyzePolicyDeltaInput as U, type AnalyzeProjectInput as V, type AnalyzeResolvedProjectInput as W, type ArchitectureActualChange as X, type ArchitectureChangeMap as Y, type ArchitectureChangeMapContract as Z, type ArchitectureChangeMapDependency as _, type ArkRulesFile as a, type SemanticDependencyKind as a$, type ArchitectureChangeOperation as a0, type ArchitectureConvergenceClassification as a1, type ArchitectureConvergenceFinding as a2, type ArchitectureConvergenceResult as a3, type ArchitectureDependency as a4, type ArchitectureEngineEdge as a5, type ArchitectureEngineResult as a6, type ArchitectureEngineViolation as a7, type ArkDesignDeltaResult as a8, type ArkEnforcementHost as a9, type PolicyDeltaAcknowledgement as aA, type PolicyDeltaAnalysis as aB, type PolicyDeltaClassification as aC, type PolicyDeltaFinding as aD, type PreflightResolvedChangeInput as aE, type PreparedChangeFile as aF, RESOLVED_CANDIDATE_FACTS_SCHEMA as aG, RESOLVED_CANDIDATE_FACTS_SCHEMA_VERSION as aH, type ResolvedAmbientFact as aI, type ResolvedAnalysisFile as aJ, type ResolvedAnalysisIr as aK, type ResolvedAnalysisResult as aL, type ResolvedCandidateFacts as aM, type ResolvedCandidateFactsInput as aN, type ResolvedCapability as aO, type ResolvedCapabilityFact as aP, type ResolvedChangePreflightResult as aQ, type ResolvedDependencyKind as aR, type ResolvedDependencyState as aS, type ResolvedFactsCompleteness as aT, type ResolvedFileFact as aU, type ResolvedIntentReferenceFact as aV, type ResolvedPublishFact as aW, type ResolvedSafetyFact as aX, type ResolvedSafetyKind as aY, type ResolvedSafetyReport as aZ, type SemanticDependency as a_, type ArkEnforcementState as aa, type ArkRuleSensorViolation as ab, type ChangePreflightResult as ac, type ClassShapeFact as ad, type CollectAnalysisConfigWarningsInput as ae, DIAGNOSTIC_CATALOG as af, DIAGNOSTIC_CATALOG_SCHEMA_VERSION as ag, DIAGNOSTIC_DOCS_RELATIVE_PATH as ah, DIAGNOSTIC_RULE_IDS as ai, type DesignDeltaChange as aj, type DesignDeltaEnforcementScope as ak, type DesignDeltaIdentity as al, type DesignSmellEvidence as am, type DesignSmellFinding as an, type DesignSmellId as ao, type DiagnosticCatalogEntry as ap, type DiagnosticCategory as aq, type EnforcementBoundaryState as ar, type EnforcementEvidence as as, type EnforcementEvidenceField as at, type EnforcementVerification as au, type EvaluateArchitectureGraphInput as av, type ForbiddenCapabilityUse as aw, type InvariantCoverageEvidence as ax, POLICY_DELTA_SCHEMA_VERSION as ay, type PolicyDelta as az, type ResolvedArkRunDeclarationFact as b, analyzeArchitectureConvergence as b0, analyzeChange as b1, analyzePolicyDelta as b2, analyzeProject as b3, analyzeResolvedProject as b4, buildArkRuleFileHints as b5, canPromoteInvariant as b6, catalogFixForRuleId as b7, catalogWhyForRuleId as b8, classifyArkPolicyDelta as b9, policyDeltaAcknowledgementMatches as bA, preflightChange as bB, preflightResolvedChange as bC, resolvedFactsEvidenceRequirementsHash as bD, serializeDiagnosticCatalog as bE, stableSerialize as bF, toAdapterDiagnostic as bG, version as bH, collectAnalysisConfigWarnings as ba, collectEmptyAppliesToFindings as bb, collectForbiddenCapabilityUses as bc, createAICodeGate as bd, createAdapterResult as be, createArchitectureProfile as bf, createArchitectureProfileFromArkConfig as bg, createElevenLayerArkConfig as bh, createResolvedCandidateFacts as bi, deriveArkRuleFileHints as bj, detectArchitectureCycles as bk, deterministicHash as bl, diagnosticDocsFragment as bm, diagnosticDocsPath as bn, elevenLayerProfile as bo, evaluateArchitectureGraph as bp, evaluateArkRuleSensors as bq, evaluateInvariantCoverage as br, explainViolation as bs, extractClassShapesFromSource as bt, extractSemanticDependencies as bu, getDiagnosticCatalogEntry as bv, isCataloguedOrArkRuleFamily as bw, isKnownDiagnosticCode as bx, loadContract as by, loadResolvedCandidateFacts as bz, type ResolvedArkRunKernelCallFact as c, type ResolvedArkRunManagedNewFact as d, type ResolvedDependencyFact as e, type ResolvedArkRunCompositionRootHitFact as f, type ResolvedFactsReason as g, type ResolvedArkOrderPlaneCallFact as h, type ResolvedArkOrderGenericUpdateFact as i, type ResolvedArkOrderRootHitFact as j, type ResolvedArkOrderXiFieldWriteFact as k, type ResolvedArkOrderIngestWriteFact as l, ADAPTER_DIAGNOSTIC_DOCS_RELATIVE_PATH as m, type AICodeGate as n, type AICodeGateContext as o, type AICodeGateOptions as p, type AICodeGateResult as q, type AICodeGateViolation as r, type AIGateExtension as s, ANALYSIS_IR_SCHEMA_VERSION as t, ARK_ANALYSIS_RESULT_SCHEMA as u, ARK_ANALYSIS_RESULT_SCHEMA_VERSION as v, ARK_DESIGN_DELTA_SCHEMA_VERSION as w, ARK_ENFORCEMENT_STATE_SCHEMA_VERSION as x, type AdapterCompletenessReason as y, type AdapterDiagnostic as z };
+export { type ArchitectureChangeMapFile as $, type AdapterViolationInput as A, type AdapterResult as B, type AdapterSeverity as C, type AnalysisCapabilityUse as D, type EffectiveArkRules as E, type AnalysisCompilerOptions as F, type AnalysisCompleteness as G, type AnalysisContract as H, type AnalysisEvidence as I, type AnalysisFile as J, type AnalysisFileChange as K, type AnalysisFileInput as L, type AnalysisImportEdge as M, type AnalysisIr as N, type AnalysisMode as O, type AnalysisResult as P, type AnalysisViolation as Q, type ResolvedArkRunKernelCallKind as R, type AnalyzeArchitectureConvergenceInput as S, type AnalyzeChangeInput as T, type AnalyzePolicyDeltaInput as U, type AnalyzeProjectInput as V, type AnalyzeResolvedProjectInput as W, type ArchitectureActualChange as X, type ArchitectureChangeMap as Y, type ArchitectureChangeMapContract as Z, type ArchitectureChangeMapDependency as _, type ArkRulesFile as a, type ResolvedPublishFact as a$, type ArchitectureChangeOperation as a0, type ArchitectureConvergenceClassification as a1, type ArchitectureConvergenceFinding as a2, type ArchitectureConvergenceResult as a3, type ArchitectureDependency as a4, type ArchitectureEngineEdge as a5, type ArchitectureEngineResult as a6, type ArchitectureEngineViolation as a7, type ArkDesignDeltaResult as a8, type ArkEnforcementHost as a9, type ForbiddenCapabilityUse as aA, type InvariantCoverageEvidence as aB, type MentionContext as aC, POLICY_DELTA_SCHEMA_VERSION as aD, type PolicyDelta as aE, type PolicyDeltaAcknowledgement as aF, type PolicyDeltaAnalysis as aG, type PolicyDeltaClassification as aH, type PolicyDeltaFinding as aI, type PreflightResolvedChangeInput as aJ, type PreparedChangeFile as aK, RESOLVED_CANDIDATE_FACTS_SCHEMA as aL, RESOLVED_CANDIDATE_FACTS_SCHEMA_VERSION as aM, type ResolvedAmbientFact as aN, type ResolvedAnalysisFile as aO, type ResolvedAnalysisIr as aP, type ResolvedAnalysisResult as aQ, type ResolvedCandidateFacts as aR, type ResolvedCandidateFactsInput as aS, type ResolvedCapability as aT, type ResolvedCapabilityFact as aU, type ResolvedChangePreflightResult as aV, type ResolvedDependencyKind as aW, type ResolvedDependencyState as aX, type ResolvedFactsCompleteness as aY, type ResolvedFileFact as aZ, type ResolvedIntentReferenceFact as a_, type ArkEnforcementState as aa, type ArkRuleSensorViolation as ab, type ChangePreflightResult as ac, type ClassShapeFact as ad, type CollectAnalysisConfigWarningsInput as ae, type CoverageEvidence as af, type CoverageFiles as ag, type CoverageInvariant as ah, DIAGNOSTIC_CATALOG as ai, DIAGNOSTIC_CATALOG_SCHEMA_VERSION as aj, DIAGNOSTIC_DOCS_RELATIVE_PATH as ak, DIAGNOSTIC_RULE_IDS as al, type DeclarationShape as am, type DesignDeltaChange as an, type DesignDeltaEnforcementScope as ao, type DesignDeltaIdentity as ap, type DesignSmellEvidence as aq, type DesignSmellFinding as ar, type DesignSmellId as as, type DiagnosticCatalogEntry as at, type DiagnosticCategory as au, type EnforcementBoundaryState as av, type EnforcementEvidence as aw, type EnforcementEvidenceField as ax, type EnforcementVerification as ay, type EvaluateArchitectureGraphInput as az, type ResolvedArkRunDeclarationFact as b, type ResolvedSafetyFact as b0, type ResolvedSafetyKind as b1, type ResolvedSafetyReport as b2, type SemanticDependency as b3, type SemanticDependencyKind as b4, analyzeArchitectureConvergence as b5, analyzeChange as b6, analyzePolicyDelta as b7, analyzeProject as b8, analyzeResolvedProject as b9, explainViolation as bA, extractClassShapesFromSource as bB, extractSemanticDependencies as bC, getDiagnosticCatalogEntry as bD, isCataloguedOrArkRuleFamily as bE, isKnownDiagnosticCode as bF, loadContract as bG, loadResolvedCandidateFacts as bH, policyDeltaAcknowledgementMatches as bI, preflightChange as bJ, preflightResolvedChange as bK, resolvedFactsEvidenceRequirementsHash as bL, serializeDiagnosticCatalog as bM, stableSerialize as bN, toAdapterDiagnostic as bO, version as bP, buildArkRuleFileHints as ba, canPromoteInvariant as bb, catalogFixForRuleId as bc, catalogWhyForRuleId as bd, classifyArkPolicyDelta as be, classifyCoverage as bf, collectAnalysisConfigWarnings as bg, collectEmptyAppliesToFindings as bh, collectForbiddenCapabilityUses as bi, countsAsCoverage as bj, createAICodeGate as bk, createAdapterResult as bl, createArchitectureProfile as bm, createArchitectureProfileFromArkConfig as bn, createElevenLayerArkConfig as bo, createResolvedCandidateFacts as bp, deriveArkRuleFileHints as bq, describeCoverage as br, detectArchitectureCycles as bs, deterministicHash as bt, diagnosticDocsFragment as bu, diagnosticDocsPath as bv, elevenLayerProfile as bw, evaluateArchitectureGraph as bx, evaluateArkRuleSensors as by, evaluateInvariantCoverage as bz, type ResolvedArkRunKernelCallFact as c, type ResolvedArkRunManagedNewFact as d, type ResolvedDependencyFact as e, type ResolvedArkRunCompositionRootHitFact as f, type ResolvedFactsReason as g, type ResolvedArkOrderPlaneCallFact as h, type ResolvedArkOrderGenericUpdateFact as i, type ResolvedArkOrderRootHitFact as j, type ResolvedArkOrderXiFieldWriteFact as k, type ResolvedArkOrderIngestWriteFact as l, ADAPTER_DIAGNOSTIC_DOCS_RELATIVE_PATH as m, type AICodeGate as n, type AICodeGateContext as o, type AICodeGateOptions as p, type AICodeGateResult as q, type AICodeGateViolation as r, type AIGateExtension as s, ANALYSIS_IR_SCHEMA_VERSION as t, ARK_ANALYSIS_RESULT_SCHEMA as u, ARK_ANALYSIS_RESULT_SCHEMA_VERSION as v, ARK_DESIGN_DELTA_SCHEMA_VERSION as w, ARK_ENFORCEMENT_STATE_SCHEMA_VERSION as x, type AdapterCompletenessReason as y, type AdapterDiagnostic as z };