arkgate 4.8.2 → 4.8.4

package/bin/lib/sensor-promote-io.mjs

@@ -0,0 +1,246 @@
+/**
+ * Tooling adapter for the sensor promotability map and the promotion write.
+ *
+ * Hand-written (NOT generated): the pure projection lives in
+ * `src/domain/sensorPromotion.ts` → `bin/lib/sensor-promotion.mjs`, and
+ * everything with a filesystem in it belongs here.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+
+import { buildSensorMap, promoteRuleInArkRulesText, ruleCountKey } from './sensor-promotion.mjs';
+import { loadEffectiveArkRulesFromDisk } from './effective-contract-load.mjs';
+import { evaluateInvariantCoverage } from './invariant-coverage.mjs';
+import {
+  coverageOptionsFromConfig,
+  invariantIdsFromCatalog,
+  loadInvariantCoverageInputs,
+} from './invariant-coverage-io.mjs';
+
+/**
+ * The root as the filesystem sees it. Comparing a realpath against a lexical
+ * root is a guaranteed mismatch wherever the root itself sits behind a link
+ * (`/var` on macOS, a symlinked checkout, a bind mount), and every containment
+ * test would then answer "outside". Same helper pair as literal-path-drift-io.
+ */
+function realRoot(root) {
+  const resolved = path.resolve(root);
+  try {
+    return fs.realpathSync.native(resolved);
+  } catch {
+    return resolved;
+  }
+}
+
+function isInsideRoot(real, rootReal) {
+  return real === rootReal || real.startsWith(rootReal + path.sep);
+}
+
+/**
+ * Build the promotability map for a project, WITHOUT the TypeScript resolver.
+ *
+ * Everything here is a declaration read off disk: the contract, the ArkRules
+ * documents it points at, and — for invariants — the coverage evidence scan,
+ * which is a filesystem walk plus a text match and never executes anything. A
+ * full `ark-check` on a real repository takes ~160s; this answers in the time
+ * it takes to read the files.
+ *
+ * @param {string} root
+ * @param {Record<string, unknown>} config
+ * @returns {{ ok: true, map: object, coverage: { partial: boolean, evaluated: boolean } }
+ *          | { ok: false, reason: string, issues?: object[] }}
+ */
+export function loadSensorMap(root, config, facts) {
+  const refs = config?.arkRules;
+  if (!refs || typeof refs !== 'object' || Object.keys(refs).length === 0) {
+    return {
+      ok: true,
+      map: buildSensorMap({ structure: [], invariants: [] }),
+      coverage: { partial: false, evaluated: false },
+      arkRulesActive: false,
+    };
+  }
+  const loaded = loadEffectiveArkRulesFromDisk(root, config);
+  if (loaded.errors?.length) {
+    return {
+      ok: false,
+      reason:
+        'ArkRules references failed to load, so no promotability can be reported (fail closed).',
+      issues: loaded.errors,
+    };
+  }
+  const structure = (loaded.arkRules.structure ?? []).map((entry) => ({
+    id: entry.id,
+    sensor: entry.sensor,
+    mode: entry.mode ?? 'advisory',
+    layer: entry.provenance?.layer ?? null,
+    sourceFile: entry.provenance?.sourceFile ?? null,
+    description: entry.description ?? null,
+  }));
+
+  const catalogued = loaded.arkRules.invariants ?? [];
+  let coverageRows = [];
+  let partial = false;
+  if (catalogued.length > 0) {
+    const inputs = loadInvariantCoverageInputs(root, facts ?? { files: [] }, {
+      invariantIds: invariantIdsFromCatalog(loaded.arkRules),
+      ...coverageOptionsFromConfig(config),
+    });
+    const coverage = evaluateInvariantCoverage({
+      arkRules: loaded.arkRules,
+      fileContents: inputs.fileContents,
+      testFiles: inputs.testFiles,
+      testGlobsMissing: inputs.testGlobsMissing,
+      coverageBudgetExhausted: inputs.coverageBudgetExhausted === true,
+      ...(inputs.stats ? { coverageStats: inputs.stats } : {}),
+      // The declared roots decide `outsideDeclaredRoots`, which is one of the
+      // four reasons canPromoteInvariant refuses. Dropping them here would make
+      // this surface promise a promotion the gate then denies.
+      ...(inputs.coverageRoots ? { coverageRoots: inputs.coverageRoots } : {}),
+    });
+    coverageRows = coverage.coverage ?? [];
+    partial = coverage.partial === true;
+  }
+  const evidenceById = new Map(coverageRows.map((row) => [row.invariantId, row]));
+
+  const invariants = catalogued.map((entry) => ({
+    id: entry.id,
+    mode: entry.mode ?? 'advisory',
+    layer: entry.provenance?.layer ?? null,
+    sourceFile: entry.provenance?.sourceFile ?? null,
+    description: entry.description ?? null,
+    ...(evidenceById.has(entry.id) ? { coverage: evidenceById.get(entry.id) } : {}),
+  }));
+
+  return {
+    ok: true,
+    map: buildSensorMap({ structure, invariants }),
+    coverage: { partial, evaluated: catalogued.length > 0 },
+    arkRulesActive: true,
+  };
+}
+
+/**
+ * Count the findings each declared rule produced in an analysis that already
+ * ran. One run answers for every rule: the loop this replaces was one full
+ * ~160s run per attempted promotion.
+ *
+ * Structure sensors stamp `arkruleId` AND `arkruleSource` on every violation
+ * they emit (`baseViolation` in arkRuleSensors.ts) and so do the
+ * invariant-coverage findings, so grouping by that pair is the per-rule count —
+ * there is no per-rule evaluator to call, and inventing one would be a second
+ * opinion that could disagree with the gate.
+ *
+ * The pair, not the bare id: ids are unique per DOCUMENT (`validateSemantics`
+ * keeps its `seen` set per file and `buildEffectiveArkRules` concatenates the
+ * layers without a second check), so two layer files declaring `shared-id`
+ * would pool their findings under it and each row would report the other's as
+ * its own.
+ *
+ * @param {Array<object>} findings violations and warnings from the same run
+ * @returns {Record<string, number>} `<sourceFile>#<ruleId>` → count
+ */
+export function countFindingsByRule(findings) {
+  /** @type {Record<string, number>} */
+  const counts = {};
+  for (const finding of findings ?? []) {
+    const id = finding?.arkruleId;
+    if (typeof id !== 'string' || id.length === 0) continue;
+    const source = typeof finding?.arkruleSource === 'string' ? finding.arkruleSource : null;
+    const key = ruleCountKey(source, id);
+    counts[key] = (counts[key] ?? 0) + 1;
+  }
+  return counts;
+}
+
+/**
+ * Set one rule to `mode: "enforced"` in the ArkRules document that declares it.
+ *
+ * The containment discipline is the one `--write` on `--path-drift` had to
+ * learn the hard way: the parent must still be inside the root as the
+ * filesystem sees it, the read-modify-write goes through a single
+ * `O_NOFOLLOW` descriptor so the LEAF is never resolved twice, and a hard link
+ * is refused because lstat reports one as an ordinary file while the write
+ * lands on a shared inode.
+ *
+ * What it does NOT close, stated rather than implied: `O_NOFOLLOW` guards the
+ * final component only. A local attacker who can swap an ANCESTOR directory for
+ * a symlink between the parent realpath check and the open still wins the race.
+ * Both writers in this package share that gap; closing it needs an
+ * openat-relative walk, which is a change to both, not to this one.
+ *
+ * @param {string} root
+ * @param {string} sourceFile project-relative path to the ArkRules document
+ * @param {string} ruleId
+ * @param {string} [expectedSensor] the sensor the rule had when it was priced
+ * @returns {{ ok: boolean, file: string, reason: string }}
+ */
+export function writeRulePromotion(root, sourceFile, ruleId, expectedSensor) {
+  const rootResolved = path.resolve(root);
+  const rootReal = realRoot(root);
+  const relative = String(sourceFile ?? '').replace(/\\/g, '/');
+  const fail = (reason) => ({ ok: false, file: relative, reason });
+  if (!relative) return fail('no source file recorded for this rule');
+  const absolute = path.resolve(rootResolved, relative);
+  if (!isInsideRoot(absolute, rootResolved)) return fail('outside-root');
+  let realParent;
+  try {
+    realParent = fs.realpathSync.native(path.dirname(absolute));
+  } catch {
+    return fail('unreadable');
+  }
+  if (!isInsideRoot(realParent, rootReal)) return fail('outside-root');
+
+  let fd;
+  try {
+    fd = fs.openSync(absolute, fs.constants.O_RDWR | fs.constants.O_NOFOLLOW);
+  } catch (error) {
+    const code = error?.code;
+    return fail(code === 'ELOOP' || code === 'EMLINK' ? 'symlink' : 'unwritable');
+  }
+  try {
+    const stat = fs.fstatSync(fd);
+    if (stat.nlink > 1) return fail('hard-link');
+    const buffer = Buffer.alloc(stat.size);
+    fs.readSync(fd, buffer, 0, stat.size, 0);
+    const text = buffer.toString('utf8');
+    // Reading as utf8 turns an invalid byte into U+FFFD and writing the whole
+    // string back would destroy it, anywhere in the file. Round-tripping the
+    // buffer is the exact test.
+    if (!Buffer.from(text, 'utf8').equals(buffer)) return fail('not-utf8');
+    const result = promoteRuleInArkRulesText(text, ruleId, expectedSensor);
+    if (!result.ok) return fail(result.reason);
+    const out = Buffer.from(result.text, 'utf8');
+    // Write BEFORE truncating, and only truncate once every byte is down. A
+    // truncate-then-write on the live descriptor turns an ENOSPC, an EIO or a
+    // signal into an empty or half-written contract; this order leaves a
+    // superset of the old document instead, which still parses back to a
+    // contract the loader can read.
+    let offset = 0;
+    while (offset < out.length) {
+      const wrote = fs.writeSync(fd, out, offset, out.length - offset, offset);
+      // A zero-byte write is not progress; looping on it would spin forever.
+      if (!(wrote > 0)) return fail('short-write');
+      offset += wrote;
+    }
+    fs.ftruncateSync(fd, out.length);
+    // The reported success has to mean the contract survives a crash: this file
+    // IS the contract, and a lost write leaves the project with no loadable one.
+    try {
+      fs.fsyncSync(fd);
+    } catch {
+      // Some filesystems refuse fsync on a regular file (rare, but real). The
+      // bytes are written either way; not durable is not a reason to report the
+      // write as failed.
+    }
+    return { ok: true, file: relative, reason: result.reason };
+  } catch (error) {
+    return fail(error instanceof Error ? error.message : 'unwritable');
+  } finally {
+    try {
+      fs.closeSync(fd);
+    } catch {
+      /* already closed */
+    }
+  }
+}

package/bin/lib/sensor-promotion.mjs

@@ -0,0 +1,363 @@
+/**
+ * GENERATED FILE — do not edit by hand.
+ *
+ * Canonical algorithm: src/domain/sensorPromotion.ts
+ * Regenerate: node scripts/generate-cli-pure.mjs
+ * Drift check: node scripts/generate-cli-pure.mjs --check
+ *
+ * Pure CLI helper (bin/lib/sensor-promotion.mjs). Zero Node I/O.
+ */
+
+import { ARK_RULE_SENSORS, ARK_RULE_TIER2_SENSORS } from './arkrules-contract.mjs';
+import { canPromoteInvariant } from './invariant-coverage.mjs';
+import { ARKRUN_TIER1_SENSOR_IDS } from './ark-run-sensors.mjs';
+import { ARKORDER_TIER1_SENSOR_IDS } from './ark-order-sensors.mjs';
+/**
+ * The Tier-2 heuristic on the ArkRun plane (ADR 0022 D2).
+ *
+ * It is not in `ARKRUN_TIER1_SENSOR_IDS` because it is not evaluated at all —
+ * `arkRunSensors.ts` says so in its header. Listing it here is the whole point
+ * of this surface: a sensor you cannot promote should appear in the map, not go
+ * missing from it, or the reader concludes it does not exist rather than that
+ * it can never bite.
+ */
+const ARKRUN_TIER2_SENSOR_IDS = ['arkrun-skip-resolve'];
+/**
+ * `invariant-coverage` is in the closed vocabulary and the schema will accept
+ * `mode: "enforced"` on a structure entry that names it, but
+ * `evaluateArkRuleSensors` has no case that emits for it: coverage is judged
+ * per invariant by the AR10 pass. Enforcing the structure entry buys no sensor
+ * findings, and reporting it as "promotable" would sell a tooth that does not
+ * exist.
+ *
+ * One sensor-independent effect survives promotion and the reason text says so:
+ * `collectEmptyAppliesToFindings` raises `ARKRULE_SCOPE_EMPTY` for ANY structure
+ * rule whose `appliesTo` matches zero governed files, and enforced makes that
+ * fail strict. That is a misconfiguration signal, not the coverage tooth the
+ * author was reaching for.
+ */
+const NO_TEETH_SENSORS = ['invariant-coverage'];
+function planeOf(sensor) {
+    if (ARK_RULE_SENSORS.includes(sensor))
+        return 'arkrules';
+    if (ARKRUN_TIER1_SENSOR_IDS.includes(sensor) ||
+        ARKRUN_TIER2_SENSOR_IDS.includes(sensor)) {
+        return 'arkrun';
+    }
+    if (ARKORDER_TIER1_SENSOR_IDS.includes(sensor))
+        return 'arkorder';
+    return null;
+}
+function isTier2(sensor) {
+    return (ARK_RULE_TIER2_SENSORS.includes(sensor) ||
+        ARKRUN_TIER2_SENSOR_IDS.includes(sensor));
+}
+const TIER2_ADR = {
+    arkrules: 'ADR 0013',
+    arkrun: 'ADR 0022',
+    arkorder: 'ADR 0029',
+};
+/** The promotability of one sensor id, known before any rule is written. */
+export function describeSensor(sensor) {
+    const plane = planeOf(sensor);
+    if (plane === null) {
+        return {
+            sensor,
+            // Not 'arkrules' with tier 1: a fabricated plane files an unknown id
+            // under a real one, and tier 1 reads as "direct evidence".
+            plane: 'unknown',
+            tier: 2,
+            promotable: false,
+            blocker: 'unknown-sensor',
+            reason: `Sensor ${JSON.stringify(sensor)} is in no closed sensor vocabulary; the loader rejects it.`,
+        };
+    }
+    if (isTier2(sensor)) {
+        return {
+            sensor,
+            plane,
+            tier: 2,
+            promotable: false,
+            blocker: 'tier-2-advisory-only',
+            reason: `Sensor ${JSON.stringify(sensor)} is Tier-2 (${TIER2_ADR[plane]}): a heuristic, advisory forever. No rule on this sensor can ever be promoted to enforced.`,
+        };
+    }
+    if (NO_TEETH_SENSORS.includes(sensor)) {
+        return {
+            sensor,
+            plane,
+            tier: 1,
+            promotable: false,
+            blocker: 'no-structure-teeth',
+            reason: `Sensor ${JSON.stringify(sensor)} emits no structure violations — invariant coverage is judged per entry in "invariants", not by a structure rule — so enforcing a structure rule on it buys no coverage tooth (only a zero-match "appliesTo" would still fail). Promote the invariant entry instead.`,
+        };
+    }
+    return {
+        sensor,
+        plane,
+        tier: 1,
+        promotable: true,
+        blocker: null,
+        // Naming the mechanism, not just the verdict. Only the ArkRules plane is
+        // promoted per rule; ArkRun and ArkOrder are switched by one plane-level
+        // `mode`, and `--promote --apply` writes ArkRules documents only. Saying
+        // "can be enforced" for all three would answer the question in a currency
+        // this surface cannot spend.
+        reason: plane === 'arkrules'
+            ? `Sensor ${JSON.stringify(sensor)} is Tier-1 (direct evidence) and can be enforced: set mode "enforced" on a rule that names it.`
+            : `Sensor ${JSON.stringify(sensor)} is Tier-1 (direct evidence) and can be enforced, but via the plane switch \`${plane}.mode\` in ark.config.json — not per rule, and not by --promote --apply.`,
+    };
+}
+/**
+ * Every sensor ArkGate ships, across all three planes, in declaration order.
+ *
+ * On the field repository almost every declared rule turned out to be
+ * promotable and nobody knew, because the only way to find out was to try one
+ * at a time. The whole vocabulary is a constant: printing it costs nothing and
+ * answers the question before the first attempt. The shipped counts are
+ * asserted in tests/unit/domain/sensorPromotion.test.ts, so this comment can
+ * never drift into a number the code does not produce.
+ */
+export function sensorVocabulary() {
+    const ids = [
+        ...ARK_RULE_SENSORS,
+        ...ARKRUN_TIER1_SENSOR_IDS,
+        ...ARKRUN_TIER2_SENSOR_IDS,
+        ...ARKORDER_TIER1_SENSOR_IDS,
+    ];
+    return ids.map((sensor) => describeSensor(sensor));
+}
+function nullable(value) {
+    return typeof value === 'string' && value.length > 0 ? value : null;
+}
+/**
+ * The identity of a rule, spelled the way the author wrote it.
+ *
+ * The Tier-2 rejection names the sensor and nothing else, so an author whose
+ * rule is called `types-only` reads an error about `no-anemic-model` and has to
+ * work out that the two are the same thing. Every reason string built here
+ * leads with the local id and names the file it came from.
+ */
+function locate(id, sourceFile) {
+    return sourceFile ? `Rule ${JSON.stringify(id)} (declared in ${sourceFile})` : `Rule ${JSON.stringify(id)}`;
+}
+export function buildSensorMap(input) {
+    const declaredStructure = input.structure ?? [];
+    const declaredInvariants = input.invariants ?? [];
+    // One pass to learn which ids are shared before any row is built: a row that
+    // does not know it is one of two cannot warn anybody.
+    const idCounts = new Map();
+    for (const rule of [...declaredStructure, ...declaredInvariants]) {
+        idCounts.set(rule.id, (idCounts.get(rule.id) ?? 0) + 1);
+    }
+    const ambiguity = (id) => {
+        const declarationsWithThisId = idCounts.get(id) ?? 1;
+        return { declarationsWithThisId, ambiguousId: declarationsWithThisId > 1 };
+    };
+    const structure = declaredStructure.map((rule) => {
+        const sourceFile = nullable(rule.sourceFile);
+        const sensor = describeSensor(rule.sensor);
+        const reason = sensor.promotable
+            ? `${locate(rule.id, sourceFile)} delegates to sensor ${JSON.stringify(rule.sensor)}, which is Tier-1 (direct evidence) and can be enforced.`
+            : `${locate(rule.id, sourceFile)} delegates to sensor ${JSON.stringify(rule.sensor)}. ${sensor.reason}`;
+        return {
+            kind: 'structure',
+            id: rule.id,
+            sensor: rule.sensor,
+            tier: sensor.tier,
+            mode: rule.mode,
+            layer: nullable(rule.layer),
+            sourceFile,
+            description: nullable(rule.description),
+            promotable: sensor.promotable,
+            blocker: sensor.blocker,
+            reason,
+            ...ambiguity(rule.id),
+        };
+    });
+    const invariants = declaredInvariants.map((rule) => {
+        const sourceFile = nullable(rule.sourceFile);
+        // One judge for promotion, shared with the policy-delta gate: a second
+        // opinion here would let this surface promise what the gate then refuses.
+        const verdict = canPromoteInvariant(rule.coverage);
+        return {
+            kind: 'invariant',
+            id: rule.id,
+            mode: rule.mode,
+            layer: nullable(rule.layer),
+            sourceFile,
+            description: nullable(rule.description),
+            promotable: verdict.ok,
+            blocker: verdict.ok ? null : 'no-coverage-evidence',
+            reason: `${locate(rule.id, sourceFile)}: ${verdict.reason}`,
+            coverageEvaluated: rule.coverage != null,
+            ...ambiguity(rule.id),
+        };
+    });
+    const all = [...structure, ...invariants];
+    return {
+        vocabulary: sensorVocabulary(),
+        structure,
+        invariants,
+        totals: {
+            declared: all.length,
+            enforced: all.filter((row) => row.mode === 'enforced').length,
+            advisoryPromotable: all.filter((row) => row.mode === 'advisory' && row.promotable).length,
+            advisoryBlocked: all.filter((row) => row.mode === 'advisory' && !row.promotable).length,
+            ambiguousIds: [...idCounts.values()].filter((count) => count > 1).length,
+        },
+        notAScore: true,
+    };
+}
+/**
+ * Ids close enough to be what the caller meant: a substring either way, so a
+ * typo'd `types-onl` and an over-qualified `domain/types-only` both land.
+ */
+function suggestionsFor(focus, ids) {
+    const needle = focus.toLowerCase();
+    const near = ids.filter((id) => {
+        const hay = id.toLowerCase();
+        return hay.includes(needle) || needle.includes(hay);
+    });
+    return (near.length > 0 ? near : [...ids]).slice(0, 10);
+}
+/**
+ * The key a finding is counted under: the document that declared the rule plus
+ * the rule id. Both are stamped on every ArkRules finding (`arkruleSource` /
+ * `arkruleId`), so this is the identity the gate itself uses.
+ */
+export function ruleCountKey(sourceFile, ruleId) {
+    return `${sourceFile ?? ''}#${ruleId}`;
+}
+export function buildPromotionPreview(input) {
+    const counts = input.countsByRuleKey ?? {};
+    const analysis = input.analysis ?? {};
+    const complete = analysis.completeness === undefined || analysis.completeness === 'complete';
+    const countsTrustworthy = complete && analysis.teethDemotedByFloor !== true && analysis.scopeNarrowed !== true;
+    const all = [...input.map.structure, ...input.map.invariants];
+    const focus = typeof input.focus === 'string' && input.focus.length > 0 ? input.focus : null;
+    const selected = focus ? all.filter((row) => row.id === focus) : all;
+    const unknownFocus = focus != null && selected.length === 0;
+    const rows = selected.map((row) => {
+        const key = ruleCountKey(row.sourceFile, row.id);
+        const currentFindings = Number.isFinite(counts[key]) ? Number(counts[key]) : 0;
+        // The floor demotes every enforced extra-plane finding to a warning, so a
+        // promotion made under it buys a label, not a tooth. Pricing it at N
+        // "would start failing the gate" would be a promise the gate does not keep.
+        const canBite = analysis.teethDemotedByFloor !== true;
+        const wouldBlock = row.mode === 'advisory' && row.promotable && canBite ? currentFindings : 0;
+        return {
+            ...row,
+            currentFindings,
+            wouldBlock,
+            // ambiguousId no longer poisons the COUNT (the key is per document), but
+            // it still makes a write ambiguous, which applyPromotion refuses.
+            countIsUnreliable: !complete || analysis.scopeNarrowed === true,
+        };
+    });
+    return {
+        focus,
+        unknownFocus,
+        ambiguousFocus: focus != null && selected.length > 1,
+        suggestions: unknownFocus ? suggestionsFor(focus, all.map((row) => row.id)) : [],
+        rows,
+        analysis,
+        countsTrustworthy,
+        totals: {
+            rules: rows.length,
+            wouldBlock: rows.reduce((sum, row) => sum + row.wouldBlock, 0),
+            cleanPromotions: rows.filter((row) => row.mode === 'advisory' &&
+                row.promotable &&
+                row.currentFindings === 0 &&
+                !row.countIsUnreliable).length,
+        },
+        notAScore: true,
+    };
+}
+/**
+ * Indentation the author used, so an indented document keeps its shape.
+ *
+ * A minified single-line document has none to detect and comes back
+ * pretty-printed at two spaces: the write is a JSON round-trip, not a targeted
+ * text edit, so "the file is untouched apart from one field" is only true of a
+ * document that was already indented.
+ */
+function detectIndent(text) {
+    const match = /\n([ \t]+)"/.exec(text);
+    if (!match)
+        return 2;
+    const found = match[1];
+    return found.includes('\t') ? '\t' : found.length;
+}
+/**
+ * Set `mode: "enforced"` on one rule inside an ArkRules document.
+ *
+ * Pure text in, pure text out: the caller owns the descriptor and the
+ * containment checks. The write refuses anything it cannot do exactly — an
+ * unparseable document, an id that is not there, an id that appears twice (the
+ * contract rejects duplicates, so this only fires on a file that was never
+ * loaded) — because a half-applied promotion is worse than none.
+ */
+export function promoteRuleInArkRulesText(text, ruleId, 
+/**
+ * The sensor this rule had when its promotion was priced. The file is read
+ * again here, so a concurrent edit between the preview and the write could
+ * have turned a Tier-1 rule into a Tier-2 one — and writing `enforced` onto
+ * that produces a contract the loader then refuses, while the command reports
+ * success. Passing it binds the write to the rule that was actually judged.
+ */
+expectedSensor) {
+    let parsed;
+    try {
+        parsed = JSON.parse(text);
+    }
+    catch (error) {
+        return {
+            ok: false,
+            reason: `ArkRules document is not valid JSON (${error instanceof Error ? error.message : String(error)}).`,
+        };
+    }
+    if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) {
+        return { ok: false, reason: 'ArkRules document is not a JSON object.' };
+    }
+    const doc = parsed;
+    const matches = [];
+    for (const key of ['structure', 'invariants']) {
+        const list = doc[key];
+        if (!Array.isArray(list))
+            continue;
+        for (const entry of list) {
+            if (entry !== null && typeof entry === 'object' && !Array.isArray(entry)) {
+                if (entry.id === ruleId) {
+                    matches.push(entry);
+                }
+            }
+        }
+    }
+    if (matches.length === 0) {
+        return { ok: false, reason: `Rule ${JSON.stringify(ruleId)} is not declared in this file.` };
+    }
+    if (matches.length > 1) {
+        return {
+            ok: false,
+            reason: `Rule ${JSON.stringify(ruleId)} appears ${matches.length} times in this file; refusing to guess which one to promote.`,
+        };
+    }
+    const entry = matches[0];
+    if (expectedSensor !== undefined && entry.sensor !== expectedSensor) {
+        return {
+            ok: false,
+            reason: `Rule ${JSON.stringify(ruleId)} now uses sensor ${JSON.stringify(entry.sensor)}, not the ${JSON.stringify(expectedSensor)} its promotion was judged against — the file changed since the preview. Re-run the preview.`,
+        };
+    }
+    if (entry.mode === 'enforced') {
+        return { ok: false, reason: `Rule ${JSON.stringify(ruleId)} is already enforced.` };
+    }
+    entry.mode = 'enforced';
+    const trailingNewline = text.endsWith('\n') ? '\n' : '';
+    return {
+        ok: true,
+        text: `${JSON.stringify(doc, null, detectIndent(text))}${trailingNewline}`,
+        reason: `Rule ${JSON.stringify(ruleId)} set to mode "enforced".`,
+    };
+}

package/dist/{configTypes-BdCe_gvv.d.ts → configTypes-dy5PfTqS.d.ts}

@@ -39,6 +39,14 @@ type ArkConfigRule = {
     message?: string;
     peerIsolation?: boolean;
     sliceFolders?: string[];
+    /** Roots the repo declares shared on purpose — evidence, not unclassifiable. */
+    sharedRoots?: string[];
+    /** Directed slice→slice edges the repo declares on purpose. */
+    allowedCrossSlice?: ArkConfigCrossSliceEdge[];
+};
+type ArkConfigCrossSliceEdge = {
+    from: string;
+    to: string;
 };
 type ArkConfigSafety = {
     maxTsSuppressions?: number;
@@ -46,6 +54,24 @@ type ArkConfigSafety = {
     allowInMemory?: boolean;
     allowDisabledPeerIsolation?: boolean;
 };
+/**
+ * Optional invariant-coverage scan controls. Absence keeps the built-in
+ * defaults (test-name heuristic, 400-file budget) and changes no verdict.
+ */
+type ArkConfigCoverage = {
+    /** Globs that decide which files count as tests (replaces the name heuristic). */
+    testGlobs?: string[];
+    /** Max files loaded as coverage evidence before the budget is exhausted. */
+    maxFiles?: number;
+    /**
+     * Path prefixes where this project declares its test runner actually executes
+     * tests. ArkGate never runs anything: this is a second declaration to compare
+     * the coverage scan against, so a covering test found outside them is reported
+     * (INVARIANT_COVERAGE_OUTSIDE_ROOTS) instead of silently certifying the
+     * invariant. Absence means no declaration and no such claim.
+     */
+    coverageRoots?: string[];
+};
 /**
  * ADR 0012 — optional map of layer name → project-relative ArkRules file path.
  * Absence changes no inter-layer verdict.
@@ -76,6 +102,11 @@ type ArkConfigArkOrder = {
     planeRoots: string[];
     managedLayers: string[];
     maxXiKeys: number;
+    /**
+     * Slow product keys the team can already name (plan, cost code, protocol).
+     * Optional. Empty → `ARKORDER_XI_FIELD_WRITE` stays silent.
+     */
+    xiKeys: string[];
 };
 type ArkConfig = {
     $schema: string;
@@ -90,6 +121,11 @@ type ArkConfig = {
     cyclePolicy?: ArkConfigCyclePolicy;
     dynamicImportAllowlist?: string[];
     safety?: ArkConfigSafety;
+    /**
+     * Invariant-coverage scan controls (test globs + file budget).
+     * Absence keeps the defaults; it never turns coverage on by itself.
+     */
+    coverage?: ArkConfigCoverage;
     /** ADR 0012 — modular ArkRules references (schema 1.1+). */
     arkRules?: ArkConfigArkRulesRefs;
     /** ADR 0020 — optional ArkRun extra (schema 1.2+). Absence changes no Layers/ArkRules verdict. */