arkgate 3.3.0 → 3.5.0

package/CHANGELOG.md

@@ -4,6 +4,81 @@ All notable changes to ArkGate (`arkgate`; formerly `ark-runtime-kernel`) are do
 
 ## Unreleased
 
+## 3.5.0 — 2026-07-16
+
+Field-feedback release (Phase X, from the amarilla adoption session): the HTML report reaches
+parity with the doctor and stays there by an executable rule, contract-smell acknowledgments gain
+a lifecycle so migration acks cannot fossilize, and the lateral-adapter smell stops firing on a
+family's own infrastructure base. Everything remains **advisory** — no verdict, `designFitness`,
+or gate behavior changes. **No breaking** CLI or `ark.config.json` changes. **No gate weaken.**
+
+### Added
+
+- **Report parity (X01):** `ark-check --report` now renders every doctor advisory — contract
+  health (smells with evidence/fix, acknowledgment honesty, invalid-sidecar warning), governance
+  weight, ambient state (idle/clean/findings with honest overflow), and capability-wall badges
+  (`pure` / `walls: …`) in the layers table. The rule is **executable**: `reportParity.test.ts`
+  enumerates the advisory keys `computeDoctorAdvisories` returns and fails CI when any key lacks
+  a `data-advisory` section — the report can never silently fall behind the product again.
+- **Acknowledgment lifecycle (X02):** a contract-smell ack may carry an optional `reviewBy`
+  (`YYYY-MM-DD`, strict round-trip validation). Past that date the ack **stops applying** and the
+  smell returns with `(ack expired …)` annotated evidence; a re-ack with a fresh date wins over a
+  dead entry, and once any dated ack exists for an edge the dated entries govern — a leftover
+  undated duplicate cannot resurrect an expired exception.
+  Undated acks keep applying (backward compatible) but are counted and surfaced —
+  doctor line, report note — even when every smell is suppressed. Malformed dates never apply
+  (fail-loud, like a sloppy edge); non-string `reviewBy` invalidates the file. Doctor JSON gains
+  `contractHealth.ackLifecycle` (`{ undated, malformed, expiredCount, expired[] }`).
+
+### Changed
+
+- **Lateral-adapter smell (X03):** `contract-lateral-adapter-allow` no longer fires when an
+  adapter layer reaches its **own family's infra base** (same leading name token and every
+  remaining target token an infra word — `Infra`/`Base`/`Core`/`Shared`/`Common`/`Kernel`/
+  `Platform`/`Foundation` — e.g. `PaymentsAdapters -> PaymentsInfra`; `PaymentsCoreAdapters` is
+  still a sibling). Cross-family edges, same-family non-infra siblings, and the reverse
+  direction (base → member) still fire.
+
+## 3.4.0 — 2026-07-16
+
+Understandable execution, second slice (Phase U: U04–U07): the capability evidence shipped in
+3.3 becomes **opt-in enforcement** across every adapter, plus the advisory ambient-state sensor
+and the measured pre-tool path. Everything remains opt-in — a config without `capabilities` /
+`pure` keys behaves exactly as before. **No breaking** CLI or `ark.config.json` changes.
+**No gate weaken.**
+
+### Added
+
+- **Capability walls (U04):** a layer may declare `capabilities: { deny: [...] }` (seven-id enum
+  in the versioned schema) or the casual shorthand `pure: true` (denies all seven). Enforcement
+  is judgment-class `CAPABILITY_VIOLATION` — never mechanical-safe, never auto-patched — with a
+  port-injection `nextAction`, across the CLI scan (ambient + import evidence), the pure IR
+  engine and atomic preflight (a multi-file batch cannot hide a denied capability), the real
+  PreToolUse hook and MCP gate (`capabilityWalls`), and ESLint
+  (`ark/no-denied-capabilities`, import dimension, in the recommended config). One violation,
+  one voice: an ambient use covered by the layer's `forbiddenGlobals` reports only
+  `FORBIDDEN_GLOBAL`.
+- **Coverage-atom policy delta (U04/D6):** T01 classifies the ambient/wall surface on coverage
+  atoms (`ambient:<entry>` prefix-expanded + `import:<capability>`): any lost atom is weakening
+  (`fetch`→`XMLHttpRequest`, `Date`→`Date.now`, wall→`forbiddenGlobals` all require the
+  hash-bound acknowledgment); migrating `forbiddenGlobals` to an equivalent-or-stronger wall
+  never needs one.
+- **Ambient-state sensor (U05, advisory + opt-in):** `doctor.ambientState` flags module-scope
+  `let`/`var` in `pure: true` layers only, with bounded sidecar acknowledgments at
+  `.ark/ambient-state-acks.json`. `declare` ambients and `using` bindings never count; skipped
+  oversized files are reported. No strict mode exists.
+- **Measured pre-tool path (U06):** `npm run bench:hook-path` measures the complete
+  hook/doctor child-process paths; `eval/performance/hook-budgets.v1.json` locks the D5 method
+  (Linux baseline first, ceilings = baseline + fixed headroom, recording mode until then); CI
+  runs the bench. Dual-depth remediation everywhere: plain port hints for casual users, stable
+  `ruleId`/`capability`/`fixClass`/`nextAction` JSON for tooling.
+
+### Fixed
+
+- The scan cache is version-bumped (v8) so a warm cache from an older ArkGate cannot miss wall
+  verdicts; template-literal text and `require()` handling in the pure scanner are
+  capability-correct (templates skipped; require counts as evidence, never as a graph edge).
+
 ## 3.3.0 — 2026-07-16
 
 Understandable execution, first slice (Phase U: U01–U03): typed effect capabilities as

package/README.md

@@ -16,9 +16,10 @@ and makes sure a “green” check means something real.
 
 </div>
 
-> **ArkGate 3.3.0** is current stable: typed effect-capability evidence (seven closed ids,
-> evidence-only until walls opt in), on top of 3.2's contract health and 3.1's change-integrity
-> loop. [Release notes](docs/releases/3.3.0.md).
+> **ArkGate 3.4.0** is current stable: opt-in capability walls (`pure: true` or
+> `capabilities.deny` per layer, enforced on every adapter), the advisory ambient-state sensor,
+> and the measured pre-tool path — completing 3.3's evidence slice.
+> [Release notes](docs/releases/3.4.0.md).
 
 ---
 

package/bin/ark-check.mjs

@@ -59,6 +59,7 @@ import {
   reportsDir,
   readJsonSafe,
 } from './lib/html-report.mjs';
+import { computeDoctorAdvisories } from './lib/doctor-advisories.mjs';
 import { buildReportDepthPayload } from './lib/html-report-depth.mjs';
 import { shouldOpenHtmlReport, openHtmlInBrowser } from './lib/open-html.mjs';
 import {
@@ -101,7 +102,6 @@ import { runArchitectureScan } from './lib/architecture-scan.mjs';
 import { validateHardWriteRequest } from './lib/enforcement-profiles.mjs';
 import { analyzePolicyTransition } from './lib/policy-delta-io.mjs';
 
-
 function parseArgs(argv) {
   const args = {
     root: process.cwd(),
@@ -1148,6 +1148,7 @@ async function main() {
       configPath: path.isAbsolute(args.config) ? args.config : path.join(root, args.config),
       configMissing: !fs.existsSync(path.isAbsolute(args.config) ? args.config : path.join(root, args.config)),
       safety,
+      ts,
     });
     return;
   }
@@ -1319,6 +1320,7 @@ async function main() {
       originJustCreated: !existingOrigin,
       adoption: adoptionForReport,
       designDepth,
+      advisories: computeDoctorAdvisories(root, config, coverage, rules, files, ts),
     };
     const html = args.beginner
       ? renderBeginnerHtmlReport(reportPayload)

package/bin/ark-mcp.mjs

@@ -58,6 +58,7 @@ import {
   detectTsPackageRoots,
   resolveIncludeRoots,
 } from './ark-shared.mjs';
+import { effectiveCapabilityDeny } from './lib/analysis-engine.mjs';
 import { createImportTargetResolver } from './lib/import-resolve.mjs';
 import { validateWithAutoPatch, resolveImportFileAbs } from './lib/auto-patch.mjs';
 import { composePrepareWrite } from './lib/prepare-write.mjs';
@@ -765,6 +766,14 @@ async function main() {
       ])
   );
 
+  // Layer → effective capability deny set (U04 walls). Same opt-in surface the
+  // CLI enforces; the gate applies it whenever the target file's layer is known.
+  const capabilityWalls = Object.fromEntries(
+    configLayers
+      .map((layer) => [layer.name, effectiveCapabilityDeny(layer)])
+      .filter(([name, deny]) => name && deny.length > 0)
+  );
+
   // Layers explicitly flagged as infrastructure in ark.config.json may import
   // infrastructure — the built-in infra-import heuristics skip them (in addition
   // to layers whose name conventionally signals an infra role). Lets a project
@@ -779,6 +788,7 @@ async function main() {
     enforceIntentAllowlist: intents.length > 0,
     typescript: ts,
     forbiddenGlobals,
+    capabilityWalls,
     infrastructureLayers,
     // Contract-first: one resolve step yields layer + relPath for rules + peerIsolation.
     resolveImportTarget: createImportTargetResolver(ts, args.root, config),

package/bin/lib/adapter-contract.mjs

@@ -30,6 +30,9 @@ function nextActionForDiagnostic(ruleId, evidence, violation) {
     if (ruleId === 'FORBIDDEN_GLOBAL') {
         return `Inject ${evidence.target ?? 'the capability'} through a port, then preflight again.`;
     }
+    if (ruleId === 'CAPABILITY_VIOLATION') {
+        return `Define a ${text(violation.capability) ?? 'capability'} port in ${evidence.fromLayer ?? 'the walled layer'}, bind the implementation outside it, then preflight again.`;
+    }
     if (ruleId === 'CIRCULAR_DEPENDENCY') {
         return 'Extract the shared dependency into a third module, then preflight again.';
     }

package/bin/lib/ambient-state.mjs

@@ -0,0 +1,221 @@
+/**
+ * U05 — ambient mutable-state sensor (ADR 0009 D4 / A5).
+ *
+ * Advisory and OPT-IN: only layers declared `pure: true` are scanned; the MVP
+ * shape is module-scope `let`/`var`. Legitimate registries/caches are
+ * acknowledged in a bounded `.ark/` sidecar (W01 precedent) — a malformed file
+ * suppresses nothing. Doctor-only: no strict default may be introduced from
+ * this sensor until the fixed corpus proves blocker-grade precision (A5).
+ *
+ * Documented envelope: only top-level statements are walked — `let` inside a
+ * `namespace` body (real runtime state on the namespace object) is out of the
+ * MVP shape; `declare` ambients and `using` bindings never count (no state /
+ * not reassignable).
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { layerForFile } from '../ark-shared.mjs';
+
+export const AMBIENT_STATE_ACKS_PATH = '.ark/ambient-state-acks.json';
+
+const MAX_ACK_BYTES = 64 * 1024;
+const MAX_ACK_ENTRIES = 200;
+const MAX_FILE_BYTES = 256 * 1024;
+const MAX_FINDINGS = 50;
+
+/** Bounded, fail-loud sidecar loader (same discipline as contract-smell acks). */
+export function loadAmbientStateAcks(root) {
+  const relPath = AMBIENT_STATE_ACKS_PATH;
+  const abs = path.join(root, relPath);
+  let stats;
+  try {
+    stats = fs.statSync(abs);
+  } catch {
+    return { path: relPath, exists: false, acks: [] };
+  }
+  const invalid = (error) => ({ path: relPath, exists: true, invalid: true, error, acks: [] });
+  if (!stats.isFile()) return invalid('not a regular file');
+  if (stats.size > MAX_ACK_BYTES) return invalid(`larger than ${MAX_ACK_BYTES} bytes`);
+  let parsed;
+  try {
+    parsed = JSON.parse(fs.readFileSync(abs, 'utf8'));
+  } catch (error) {
+    return invalid(error instanceof Error ? error.message : 'unreadable JSON');
+  }
+  const acks = Array.isArray(parsed?.acks) ? parsed.acks : null;
+  if (!acks) return invalid('expected { acks: [{ file, name, reason? }] }');
+  if (acks.length > MAX_ACK_ENTRIES) return invalid(`more than ${MAX_ACK_ENTRIES} entries`);
+  const wellFormed = acks.every(
+    (a) =>
+      a !== null &&
+      typeof a === 'object' &&
+      typeof a.file === 'string' &&
+      a.file.length > 0 &&
+      typeof a.name === 'string' &&
+      a.name.length > 0
+  );
+  if (!wellFormed) return invalid('every ack needs string file and name');
+  // Normalize separators so a Windows-authored ack file still matches.
+  const normalized = acks.map((a) => ({ ...a, file: a.file.replace(/\\/g, '/') }));
+  return { path: relPath, exists: true, acks: normalized };
+}
+
+function isAcknowledged(ackState, file, name) {
+  if (!ackState || ackState.invalid || !Array.isArray(ackState.acks)) return false;
+  return ackState.acks.some((a) => a.file === file && a.name === name);
+}
+
+function bindingIdentifiers(ts, name, out) {
+  if (ts.isIdentifier(name)) {
+    out.push(name.text);
+    return;
+  }
+  if (ts.isObjectBindingPattern(name) || ts.isArrayBindingPattern(name)) {
+    for (const element of name.elements) {
+      if (element && !ts.isOmittedExpression(element) && element.name) {
+        bindingIdentifiers(ts, element.name, out);
+      }
+    }
+  }
+}
+
+/**
+ * Detect module-scope mutable state in `pure: true` layers.
+ *
+ * @returns {{ active: boolean, findings: Array<{file: string, line: number, name: string, kind: 'module-let'|'module-var'}>, acknowledgedCount: number, truncated: number }}
+ */
+export function detectAmbientState(ts, root, config, files, ackState = { exists: false, acks: [] }) {
+  const layers = Array.isArray(config?.layers) ? config.layers : [];
+  const pureLayers = new Set(
+    layers.filter((layer) => layer?.pure === true).map((layer) => layer.name)
+  );
+  if (pureLayers.size === 0) return { active: false, findings: [], acknowledgedCount: 0, truncated: 0 };
+
+  const resolvedRoot = path.resolve(root);
+  const findings = [];
+  const acknowledgedPairs = new Set();
+  let skippedFiles = 0;
+  for (const file of files) {
+    const layer = layerForFile(root, file, layers);
+    if (!layer || !pureLayers.has(layer)) continue;
+    const rel = path.relative(resolvedRoot, path.resolve(file)).split(path.sep).join('/');
+    let source;
+    try {
+      const stats = fs.statSync(file);
+      if (!stats.isFile() || stats.size === 0) continue;
+      if (stats.size > MAX_FILE_BYTES) {
+        skippedFiles += 1;
+        continue;
+      }
+      source = fs.readFileSync(file, 'utf8');
+    } catch {
+      continue;
+    }
+    const sourceFile = ts.createSourceFile(file, source, ts.ScriptTarget.Latest, true);
+    for (const statement of sourceFile.statements) {
+      if (!ts.isVariableStatement(statement)) continue;
+      // `declare` ambients allocate no runtime state.
+      if (
+        statement.modifiers?.some(
+          (modifier) => modifier.kind === ts.SyntaxKind.DeclareKeyword
+        )
+      ) {
+        continue;
+      }
+      const flags = statement.declarationList.flags;
+      // const never reassigns; `using`/`await using` bindings are not reassignable.
+      const immutableFlags =
+        ts.NodeFlags.Const | (ts.NodeFlags.Using ?? 0) | (ts.NodeFlags.AwaitUsing ?? 0);
+      if ((flags & immutableFlags) !== 0) continue;
+      const kind = (flags & ts.NodeFlags.Let) !== 0 ? 'module-let' : 'module-var';
+      for (const declaration of statement.declarationList.declarations) {
+        const names = [];
+        bindingIdentifiers(ts, declaration.name, names);
+        for (const name of names) {
+          if (isAcknowledged(ackState, rel, name)) {
+            acknowledgedPairs.add(`${rel}\u0000${name}`);
+            continue;
+          }
+          const line =
+            sourceFile.getLineAndCharacterOfPosition(declaration.getStart(sourceFile)).line + 1;
+          findings.push({ file: rel, line, name, kind });
+        }
+      }
+    }
+  }
+  const acknowledgedCount = acknowledgedPairs.size;
+  findings.sort(
+    (left, right) =>
+      left.file.localeCompare(right.file) ||
+      left.line - right.line ||
+      left.name.localeCompare(right.name)
+  );
+  const truncated = Math.max(0, findings.length - MAX_FINDINGS);
+  return {
+    active: true,
+    findings: findings.slice(0, MAX_FINDINGS),
+    acknowledgedCount,
+    truncated,
+    skippedFiles,
+  };
+}
+
+/** JSON summary for doctor. Advisory only — never a verdict input. */
+export function summarizeAmbientState(result, ackState = { exists: false, acks: [] }) {
+  return {
+    available: true,
+    active: result.active,
+    advisory: true,
+    findingCount: result.findings.length,
+    acknowledged: ackState?.invalid ? 0 : result.acknowledgedCount,
+    ...(result.truncated > 0 ? { truncated: result.truncated } : {}),
+    ...(result.skippedFiles > 0 ? { skippedFiles: result.skippedFiles } : {}),
+    note: result.active
+      ? 'Module-scope mutable state in pure layers — advisory only; acknowledge deliberate registries in the sidecar or move the state behind a port.'
+      : 'No pure: true layer opted in; the sensor is idle.',
+    ackFile: {
+      path: ackState?.path ?? AMBIENT_STATE_ACKS_PATH,
+      present: ackState?.exists === true,
+      invalid: ackState?.invalid === true,
+      ...(ackState?.invalid ? { error: ackState.error ?? 'invalid' } : {}),
+    },
+  };
+}
+
+/** One-call compute for doctor; `ts` may be absent (report unavailable honestly). */
+export function computeAmbientState(ts, root, config, files) {
+  if (!ts) {
+    return {
+      available: false,
+      active: false,
+      advisory: true,
+      findings: [],
+      findingCount: 0,
+      acknowledged: 0,
+      note: 'TypeScript was not available to the doctor run; the ambient-state sensor did not execute.',
+    };
+  }
+  const ackState = loadAmbientStateAcks(root);
+  const result = detectAmbientState(ts, root, config, files, ackState);
+  return { ...summarizeAmbientState(result, ackState), findings: result.findings };
+}
+
+/** Human doctor section (advisory); silent when idle and healthy. */
+export function printAmbientStateSection(state, io) {
+  if (!state.available || (!state.findingCount && !state.ackFile?.invalid)) return;
+  console.log('');
+  console.log(io.color.bold('Ambient state (advisory)'));
+  if (state.ackFile?.invalid) {
+    io.line(io.warn, `${state.ackFile.path} is present but invalid — acknowledgments are ignored.`);
+  }
+  for (const finding of state.findings.slice(0, 5)) {
+    io.line(io.warn, `[${finding.kind}] ${finding.file}:${finding.line} — \`${finding.name}\``);
+  }
+  if (state.findingCount > 5) {
+    io.line(' ', io.color.dim(`…(+${state.findingCount - 5} more in doctor JSON)`));
+  }
+  if (state.acknowledged > 0) {
+    io.line(' ', io.color.dim(`acknowledged module state: ${state.acknowledged}`));
+  }
+  io.line(' ', io.color.dim('advisory only — never blocks; move state behind a port or acknowledge it'));
+}