arkgate 4.8.8 → 4.8.10

package/bin/lib/rules-inventory.mjs

@@ -8,6 +8,7 @@
  * Pure CLI helper (bin/lib/rules-inventory.mjs). Zero Node I/O.
  */
 
+import { DOMAIN_EVENTS_PUSH_RE, DOMAIN_INVARIANT_WORD_RE, expectedDomainInvariantWordsPhrase, isIdiomaticEventsReset, } from './arkrules-sensors.mjs';
 function lineOf(content, index) {
     return content.slice(0, index).split('\n').length;
 }
@@ -226,7 +227,7 @@ export function buildRulesInventory(input) {
                 /(?:^|\/)[^/]*(?:-access)?\.error\./i.test(posix) ||
                 /(?:^|\/)errors?(?:\/|$)/i.test(posix);
             if (!isErrorBag) {
-                const mutRe = /this\.\w+\s*=/g;
+                const mutRe = /\bthis\.[A-Za-z_][A-Za-z0-9_]*\s*=(?!=)/g;
                 let mut;
                 while ((mut = mutRe.exec(content)) !== null) {
                     const classStart = content.lastIndexOf('class ', mut.index);
@@ -239,15 +240,18 @@ export function buildRulesInventory(input) {
                     if (/\bextends\s+(?:Error|[A-Za-z_$][A-Za-z0-9_$]*Error)\b/.test(classHeader)) {
                         continue;
                     }
+                    if (isIdiomaticEventsReset(content, mut.index))
+                        continue;
                     const window = content.slice(Math.max(0, mut.index - 200), mut.index + 200);
-                    if (!/\b(ensureInvariants|assertInvariants|validate|publish|emit)\b/.test(window)) {
+                    if (!DOMAIN_INVARIANT_WORD_RE.test(window) &&
+                        !DOMAIN_EVENTS_PUSH_RE.test(window)) {
                         seq += 1;
                         candidates.push({
                             id: `inv-mut-${seq}`,
                             kind: 'mutation-without-guard',
                             file,
                             line: lineOf(content, mut.index),
-                            message: 'Domain field mutation without nearby guard/publish call.',
+                            message: `Domain field mutation without nearby ${expectedDomainInvariantWordsPhrase()}.`,
                             confidence: 'heuristic',
                             governedLayer,
                             suggestedArkRule: {

package/bin/lib/upgrade-command.mjs

@@ -603,10 +603,23 @@ export function runUpgradeCommand(args, dependencies) {
     return 2;
   }
   if (applied.blocked) {
-    if (args.json) console.log(JSON.stringify(applied, null, 2));
-    else renderManagedUpgrade(applied, {
-      next: 'Preview again with --accept-conflicts, then use that preview\'s exact next command.',
-    });
+    const command = buildUpgradeNextCommand(
+      { ...args, acceptConflicts: true },
+      applied.planDigest
+    );
+    if (args.json) {
+      console.log(
+        managedUpgradeJson(applied, {
+          blocked: true,
+          reasonCode: applied.reasonCode ?? 'managed-consent-required',
+          nextCommand: command,
+        })
+      );
+    } else {
+      renderManagedUpgrade(applied, {
+        next: 'Preview again with --accept-conflicts, then use that preview\'s exact next command.',
+      });
+    }
     return 1;
   }
   if (applied.nothingToApply && !applied.applied) {

package/bin/lib/upstream-report.mjs

@@ -0,0 +1,330 @@
+/**
+ * Upstream GitHub issue draft for ArkGate itself (`arkgate report` / `ark report`).
+ * Target is this package's package.json bugs.url (pedroknigge/arkgate), never the consumer repo.
+ */
+import { spawnSync } from 'node:child_process';
+import fs from 'node:fs';
+import path from 'node:path';
+import readline from 'node:readline/promises';
+
+import { __packageRoot } from './gate-files.mjs';
+
+export const UPSTREAM_OWNER_REPO = 'pedroknigge/arkgate';
+export const SUBMIT_PROMPT = 'Type submit to send';
+
+export function ownerRepoFromGithubUrl(url) {
+  if (typeof url !== 'string' || url.trim() === '') return null;
+  const match = url.trim().match(/github\.com[:/]+([^/]+)\/([^/#?\s]+)/i);
+  if (!match) return null;
+  const owner = match[1];
+  const repo = match[2].replace(/\.git$/i, '');
+  if (!owner || !repo) return null;
+  return `${owner}/${repo}`;
+}
+
+export function resolveUpstreamRepo(pkg) {
+  const fromBugs = ownerRepoFromGithubUrl(pkg?.bugs?.url);
+  if (fromBugs) return fromBugs;
+  const repository = pkg?.repository;
+  const repoUrl = typeof repository === 'string' ? repository : repository?.url;
+  const fromRepo = ownerRepoFromGithubUrl(repoUrl);
+  if (fromRepo) return fromRepo;
+  return UPSTREAM_OWNER_REPO;
+}
+
+export function posixSingleQuote(value) {
+  return `'${String(value).replace(/'/g, `'\\''`)}'`;
+}
+
+export function formatGhIssueCreateCommand({ repo, title, body }) {
+  return `gh issue create --repo ${posixSingleQuote(repo)} --title ${posixSingleQuote(title)} --body ${posixSingleQuote(body)}`;
+}
+
+export function reportUsage() {
+  return `arkgate report (alias ark report) — draft an upstream GitHub issue for ArkGate.
+
+Target: pedroknigge/arkgate (this package's package.json bugs.url). Never the consumer repo.
+
+Usage:
+  arkgate report [--root <project>] [--json] [--title <text>] [--finding <ref>]
+  arkgate report --submit --i-confirm-submit
+  arkgate report --submit          # TTY: type submit to send
+
+Default prints a draft (arkgate version + last-check snippet). Nothing is created.
+Create only with --submit AND (--i-confirm-submit after the human said yes, or TTY
+"${SUBMIT_PROMPT}"). --yes does not submit.
+
+If gh is missing or not logged in: prints the draft and the exact
+gh issue create --repo pedroknigge/arkgate command, then exits 2.
+`;
+}
+
+export function lastCheckSnippet(latest) {
+  if (!latest || typeof latest !== 'object') return null;
+  const at =
+    typeof latest.generatedAt === 'string'
+      ? latest.generatedAt
+      : typeof latest.at === 'string'
+        ? latest.at
+        : null;
+  const active =
+    typeof latest.activeViolations === 'number'
+      ? latest.activeViolations
+      : typeof latest.violations?.active === 'number'
+        ? latest.violations.active
+        : null;
+  let verdict = null;
+  if (latest.ok === true && (active == null || active === 0)) verdict = 'pass';
+  else if (latest.ok === false || (typeof active === 'number' && active > 0)) verdict = 'fail';
+  else if (latest.completeness === 'partial' || latest.completeness === 'unavailable') {
+    verdict = 'incomplete';
+  } else if (latest.ok === true) verdict = 'pass';
+  if (at == null && verdict == null && active == null) return null;
+  return { at, verdict, activeViolations: active };
+}
+
+export function readLastCheckSnapshot(root) {
+  const latestPath = path.join(root, '.ark', 'reports', 'latest.json');
+  try {
+    return JSON.parse(fs.readFileSync(latestPath, 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+export function buildIssueDraft({ repo, arkgateVersion, lastCheck, finding, title }) {
+  const resolvedTitle =
+    typeof title === 'string' && title.trim()
+      ? title.trim()
+      : finding
+        ? `ArkGate finding ${finding}`
+        : 'ArkGate field report';
+  const lines = [`## ArkGate version`, String(arkgateVersion ?? 'unknown'), ''];
+  if (finding) {
+    lines.push('## Finding', String(finding), '');
+  }
+  if (lastCheck) {
+    lines.push('## Last check');
+    lines.push(`- at: ${lastCheck.at ?? 'none'}`);
+    lines.push(`- verdict: ${lastCheck.verdict ?? 'none'}`);
+    lines.push(`- activeViolations: ${lastCheck.activeViolations ?? 'unknown'}`);
+    lines.push('');
+  } else {
+    lines.push('## Last check', 'No last-check snapshot under .ark/reports/latest.json.', '');
+  }
+  lines.push(
+    '## Repro',
+    '```bash',
+    'npx arkgate-check --doctor',
+    'npx arkgate status --json',
+    '```',
+    '',
+    '## What happened',
+    '(ArkGate bug, false green, false red, missing doc, or improvable behavior in ArkGate itself — not leftover design in the consumer app.)',
+    '',
+    `Prepared with \`arkgate report\` against upstream ${repo}. Not the consumer repo.`
+  );
+  return { repo, title: resolvedTitle, body: lines.join('\n') };
+}
+
+export function defaultRunGh(argv, options = {}) {
+  const env = { ...(options.env ?? process.env) };
+  delete env.GH_REPO;
+  const result = spawnSync('gh', argv, {
+    encoding: 'utf8',
+    env,
+    stdio: ['ignore', 'pipe', 'pipe'],
+  });
+  if (result.error && (result.error.code === 'ENOENT' || result.error.code === 'EACCES')) {
+    return { missing: true, status: 127, stdout: '', stderr: result.error.message };
+  }
+  return {
+    missing: false,
+    status: result.status ?? 1,
+    stdout: result.stdout ?? '',
+    stderr: result.stderr ?? '',
+  };
+}
+
+function loadArkgatePackageJson(explicit) {
+  if (explicit && typeof explicit === 'object') return explicit;
+  try {
+    return JSON.parse(fs.readFileSync(path.join(__packageRoot, 'package.json'), 'utf8'));
+  } catch {
+    return { bugs: { url: `https://github.com/${UPSTREAM_OWNER_REPO}/issues` } };
+  }
+}
+
+function packageVersion(pkg, fallback) {
+  if (typeof fallback === 'string' && fallback.trim()) return fallback;
+  return typeof pkg?.version === 'string' ? pkg.version : 'unknown';
+}
+
+function renderHumanDraft(draft, arkgateVersion) {
+  return [
+    `Upstream: ${draft.repo}`,
+    '(never the consumer repo)',
+    '',
+    `ArkGate version: ${arkgateVersion}`,
+    '',
+    `Title: ${draft.title}`,
+    '',
+    draft.body,
+  ].join('\n');
+}
+
+async function defaultPromptSubmit(stdin, stdout) {
+  const rl = readline.createInterface({ input: stdin, output: stdout });
+  try {
+    return await rl.question(`${SUBMIT_PROMPT}\n`);
+  } finally {
+    rl.close();
+  }
+}
+
+export function parseReportArgv(argv = []) {
+  const out = {
+    submit: false,
+    iConfirmSubmit: false,
+    json: false,
+    yes: false,
+    help: false,
+    finding: undefined,
+    title: undefined,
+    root: undefined,
+  };
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i];
+    const next = () => {
+      const value = argv[i + 1];
+      if (value === undefined || String(value).startsWith('-')) {
+        throw new Error(`Missing value for ${arg}. Run arkgate report --help for usage.`);
+      }
+      i += 1;
+      return value;
+    };
+    if (arg === '--submit') out.submit = true;
+    else if (arg === '--i-confirm-submit') out.iConfirmSubmit = true;
+    else if (arg === '--json') out.json = true;
+    else if (arg === '--yes' || arg === '-y') out.yes = true;
+    else if (arg === '--help' || arg === '-h' || arg === 'help') out.help = true;
+    else if (arg === '--finding') out.finding = next();
+    else if (arg === '--title') out.title = next();
+    else if (arg === '--root') out.root = path.resolve(next());
+    else throw new Error(`Unknown argument: ${arg}. Run arkgate report --help for usage.`);
+  }
+  return out;
+}
+
+/**
+ * @param {object} options
+ * @returns {Promise<number>} process exit code
+ */
+export async function runUpstreamReportCommand(options = {}) {
+  const fromArgv = Array.isArray(options.argv) ? parseReportArgv(options.argv) : {};
+  if (fromArgv.help) {
+    const writeOut = options.writeOut ?? ((text) => console.log(text));
+    writeOut(reportUsage());
+    return 0;
+  }
+  const root = path.resolve(fromArgv.root ?? options.root ?? process.cwd());
+  const json = Boolean(fromArgv.json || options.json);
+  const submit = Boolean(fromArgv.submit || options.submit);
+  const iConfirmSubmit = Boolean(fromArgv.iConfirmSubmit || options.iConfirmSubmit);
+  const yes = Boolean(fromArgv.yes || options.yes);
+  const finding = fromArgv.finding ?? options.finding;
+  const title = fromArgv.title ?? options.title;
+  const stdin = options.stdin ?? process.stdin;
+  const stdout = options.stdout ?? process.stdout;
+  const stdinIsTTY = options.stdinIsTTY ?? Boolean(stdin.isTTY);
+  const env = options.env ?? process.env;
+  const runGh = options.runGh ?? ((argv) => defaultRunGh(argv, { env }));
+  const writeOut = options.writeOut ?? ((text) => console.log(text));
+  const writeErr = options.writeErr ?? ((text) => console.error(text));
+
+  const pkg = loadArkgatePackageJson(options.arkgatePackageJson);
+  const repo = resolveUpstreamRepo(pkg);
+  const arkgateVersion = packageVersion(pkg, options.arkgateVersion);
+  const lastCheck = lastCheckSnippet(options.latestSnapshot ?? readLastCheckSnapshot(root));
+  const draft = buildIssueDraft({
+    repo,
+    arkgateVersion,
+    lastCheck,
+    finding,
+    title,
+  });
+  const ghCommand = formatGhIssueCreateCommand(draft);
+  const human = renderHumanDraft(draft, arkgateVersion);
+
+  const payload = {
+    schemaVersion: '1.0',
+    command: 'report',
+    created: false,
+    submitted: false,
+    repo: draft.repo,
+    title: draft.title,
+    body: draft.body,
+    arkgateVersion,
+    lastCheck,
+    ghCommand,
+    yesDoesNotSubmit: true,
+  };
+
+  const emit = (extraHuman, extraPayload) => {
+    if (json) writeOut(JSON.stringify({ ...payload, ...extraPayload }, null, 2));
+    else writeOut(extraHuman ? `${human}\n\n${extraHuman}` : human);
+  };
+
+  if (!submit) {
+    emit('Draft only. Nothing was created.\nAfter a human confirms: arkgate report --submit --i-confirm-submit\n--yes does not submit.');
+    return 0;
+  }
+
+  // --yes never confirms. Confirm is --i-confirm-submit or TTY "submit".
+  let confirmed = iConfirmSubmit;
+  if (!confirmed && stdinIsTTY) {
+    const typed = options.promptSubmit
+      ? await options.promptSubmit()
+      : await defaultPromptSubmit(stdin, stdout);
+    confirmed = /^\s*submit\s*$/i.test(String(typed ?? ''));
+  }
+
+  if (!confirmed) {
+    const refused =
+      'Refused: --submit requires --i-confirm-submit or typing submit on a TTY. --yes does not submit.';
+    if (json) {
+      writeOut(JSON.stringify({ ...payload, error: 'submit-confirm-required', yesDoesNotSubmit: true }, null, 2));
+    } else {
+      writeOut(`${human}\n\nDraft only. ${refused}`);
+    }
+    writeErr(refused);
+    return 2;
+  }
+
+  const auth = runGh(['auth', 'status']);
+  const ghUnavailable = Boolean(auth?.missing) || auth?.status !== 0;
+  if (ghUnavailable) {
+    const missing =
+      'Not filed: gh is missing or not logged in.\nExact command:\n' + ghCommand;
+    emit(missing, { created: false, submitted: false, error: 'gh-unavailable', ghCommand });
+    if (!json) writeErr('Not filed: gh is missing or not logged in.');
+    return 2;
+  }
+
+  const created = runGh(['issue', 'create', '--repo', repo, '--title', draft.title, '--body', draft.body]);
+  if (created?.missing || created?.status !== 0) {
+    const missing =
+      'Not filed: gh is missing or not logged in.\nExact command:\n' + ghCommand;
+    emit(missing, { created: false, submitted: false, error: 'gh-unavailable', ghCommand });
+    if (!json) writeErr('Not filed: gh is missing or not logged in.');
+    return 2;
+  }
+
+  const url = String(created.stdout ?? '').trim();
+  emit(url ? `Created: ${url}` : 'Created.', {
+    created: true,
+    submitted: true,
+    url: url || null,
+  });
+  return 0;
+}

package/bin/lib/violations.mjs

@@ -16,8 +16,12 @@ import { baselineKeysFromDocument, baselineRecordsDocument } from './team-parlia
 import { toAdapterDiagnostic } from './adapter-contract.mjs';
 export { baselineKey, baselineOccurrenceKeys };
 
-const BASELINE_NOTE =
-  'Frozen ark-check violations (one record per edge). Only NEW keys vs the merge-base fail --against / --baseline. Regenerate with: ark-check --update-baseline';
+/** Real regenerate flags: freeze-refuse needs --force; law PR needs --contract-session; stewards[] needs --author. */
+export const REGENERATE_BASELINE_COMMAND =
+  'ark-check --update-baseline --force --contract-session --author <steward>';
+
+export const BASELINE_NOTE =
+  `Frozen ark-check violations (one record per edge). Only NEW keys vs the merge-base fail --against / --baseline. Regenerate with: ${REGENERATE_BASELINE_COMMAND} (--author when stewards[] is set)`;
 
 export function readBaseline(root, baselinePath) {
   const fullPath = path.isAbsolute(baselinePath) ? baselinePath : path.join(root, baselinePath);
@@ -76,13 +80,34 @@ export function printViolation(violation) {
 export const CONCENTRATION_MIN_VIOLATIONS = 10;
 export const CONCENTRATION_SHARE = 0.9;
 
+/** Sensor id for STRUCTURE findings. Orchestration-only is code debt, not a missing toLayer. */
+export function violationSensorId(violation) {
+  if (typeof violation?.sensor === 'string' && violation.sensor.trim()) return violation.sensor.trim();
+  if (typeof violation?.arkruleId === 'string' && violation.arkruleId.trim()) return violation.arkruleId.trim();
+  return undefined;
+}
+
 export function violationEdge(violation) {
   if (violation.ruleId === 'CIRCULAR_DEPENDENCY') return 'circular dependency';
   if (violation.ruleId === 'FORBIDDEN_GLOBAL') return `${violation.fromLayer ?? '?'} → ambient global`;
   if (violation.fromLayer && violation.toLayer) return `${violation.fromLayer} → ${violation.toLayer}`;
+  const sensor = violationSensorId(violation);
+  if (sensor) return sensor;
   return violation.ruleId;
 }
 
+/** Layer-import arrows can mean a contract bug. Structural-sensor blobs are code debt. */
+export function isContractConcentrationEdge(edge) {
+  return typeof edge === 'string' && edge.includes(' → ');
+}
+
+export function isContractStyleViolation(violation) {
+  if (violationSensorId(violation)) return false;
+  if (violation.ruleId === 'CIRCULAR_DEPENDENCY') return true;
+  if (violation.ruleId === 'FORBIDDEN_GLOBAL') return true;
+  return Boolean(violation.fromLayer && violation.toLayer);
+}
+
 // The directory the offending import lands in — the signal for "where does this edge go?".
 // For a LAYER_IMPORT_VIOLATION the target is a resolved file path; cluster by its dir prefix
 // so `kernel/internal/x` and `kernel/internal/y` collapse to one "into kernel/internal/".
@@ -100,27 +125,35 @@ export function summarizeViolations(violations) {
   for (const violation of violations) {
     if (violation.typeOnly) typeOnly += 1;
     const key = violationEdge(violation);
-    const entry = byEdge.get(key) ?? { edge: key, count: 0, typeOnly: 0, targets: new Map() };
+    const entry = byEdge.get(key) ?? {
+      edge: key,
+      count: 0,
+      typeOnly: 0,
+      targets: new Map(),
+      contractStyle: true,
+    };
     entry.count += 1;
     if (violation.typeOnly) entry.typeOnly += 1;
+    if (!isContractStyleViolation(violation)) entry.contractStyle = false;
     const subtree = violationTargetSubtree(violation);
     if (subtree) entry.targets.set(subtree, (entry.targets.get(subtree) ?? 0) + 1);
     byEdge.set(key, entry);
   }
-  const edges = [...byEdge.values()]
-    .map((entry) => ({
-      edge: entry.edge,
-      count: entry.count,
-      typeOnly: entry.typeOnly,
-      topTargets: [...entry.targets.entries()]
-        .sort((a, b) => b[1] - a[1])
-        .slice(0, 4)
-        .map(([dir, count]) => ({ dir, count })),
-    }))
-    .sort((a, b) => b.count - a.count);
+  const ranked = [...byEdge.values()].sort((a, b) => b.count - a.count);
+  const edges = ranked.map((entry) => ({
+    edge: entry.edge,
+    count: entry.count,
+    typeOnly: entry.typeOnly,
+    topTargets: [...entry.targets.entries()]
+      .sort((a, b) => b[1] - a[1])
+      .slice(0, 4)
+      .map(([dir, count]) => ({ dir, count })),
+  }));
   const total = violations.length;
   const dominant = edges[0];
   const dominantShare = total > 0 && dominant ? dominant.count / total : 0;
+  const contractConcentration =
+    Boolean(ranked[0]?.contractStyle) && isContractConcentrationEdge(ranked[0]?.edge);
   return {
     total,
     // Value edges are real runtime coupling; type-only edges (erased at compile time) are
@@ -130,7 +163,10 @@ export function summarizeViolations(violations) {
     edges,
     dominant: dominant ? dominant.edge : undefined,
     dominantShare,
-    concentrated: total >= CONCENTRATION_MIN_VIOLATIONS && dominantShare >= CONCENTRATION_SHARE,
+    concentrated:
+      total >= CONCENTRATION_MIN_VIOLATIONS &&
+      dominantShare >= CONCENTRATION_SHARE &&
+      contractConcentration,
   };
 }
 

package/dist/{configTypes-0eHpocR3.d.ts → configTypes-j7so8B4O.d.ts}

@@ -105,12 +105,24 @@ type ArkConfigArkOrder = {
     mode: ArkConfigArkOrderMode;
     planeRoots: string[];
     managedLayers: string[];
+    /**
+     * Haken cap on one `release()` / `assertXiKeyCap` (default 7).
+     * Not a cap on the `xiKeys` watchlist length.
+     */
     maxXiKeys: number;
     /**
      * Slow product keys the team can already name (plan, cost code, protocol).
      * Optional. Empty → `ARKORDER_XI_FIELD_WRITE` stays silent.
+     * Repo-wide watchlist — not compared to `maxXiKeys`.
      */
     xiKeys: string[];
+    /**
+     * Optional globs that narrow ξ field-write observation inside `managedLayers`.
+     * Same glob engine as `layers[].patterns`. Absence or empty → every file in
+     * those layers. Non-empty → emit only when the layer is managed AND the file
+     * matches at least one glob.
+     */
+    appliesTo?: string[];
 };
 type ArkConfig = {
     $schema: string;

package/dist/{diagnosticCatalog-DxKCTBbp.d.ts → diagnosticCatalog-biferT4R.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-BK47clMl.js';
-import { A as ArkConfig, c as ArkConfigLoadResult } from './configTypes-0eHpocR3.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-Djbs3KjE.js';
+import { A as ArkConfig, c as ArkConfigLoadResult } from './configTypes-j7so8B4O.js';
 
 /** Versioned public result contract shared by every ArkGate enforcement adapter. */
 /**
@@ -409,7 +409,7 @@ declare const ARK_ANALYSIS_RESULT_SCHEMA: {
 };
 
 /** ArkGate library version — single source of truth. */
-declare const version = "4.8.8";
+declare const version = "4.8.10";
 
 /**
  * AI Code Gate (basic).
@@ -1924,12 +1924,18 @@ declare function evaluateArkRuleSensors(input: EvaluateArkRuleSensorsInput): Ark
  * Rules without appliesTo (whole-layer) never emit this signal.
  */
 declare function collectEmptyAppliesToFindings(arkRules: EffectiveArkRules, files: readonly string[]): ArkRuleSensorViolation[];
+/** Optional resolved-import facts when the collector already classified the specifier. */
+type ResolvedPersistenceImportFact = {
+    specifier?: string;
+    resolvedFile?: string;
+    layer?: string | null;
+};
 /**
  * Pure Tooling/Domain heuristic for orchestration-only / thin-adapter fileHints.
  * Prefers false negatives over false positives (ADR 0013 discipline).
  * Returns null when neither flag is set (callers may omit the path).
  */
-declare function deriveArkRuleFileHints(_file: string, content: string): {
+declare function deriveArkRuleFileHints(_file: string, content: string, resolvedImports?: readonly ResolvedPersistenceImportFact[]): {
     orchestrationHeavy?: boolean;
     adapterThick?: boolean;
     persistenceWrite?: boolean;
@@ -1937,7 +1943,7 @@ declare function deriveArkRuleFileHints(_file: string, content: string): {
 /**
  * Build fileHints map from path→content. Omits paths with no flags (sparse map).
  */
-declare function buildArkRuleFileHints(fileContents: Readonly<Record<string, string>>): Record<string, {
+declare function buildArkRuleFileHints(fileContents: Readonly<Record<string, string>>, resolvedImportsByFile?: Readonly<Record<string, readonly ResolvedPersistenceImportFact[]>>): Record<string, {
     orchestrationHeavy?: boolean;
     adapterThick?: boolean;
     persistenceWrite?: boolean;