arkgate 2.9.2 → 2.11.0

package/bin/lib/core-ratchet.mjs

@@ -6,18 +6,14 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { arkCommand } from '../ark-shared.mjs';
 import { computeCoverage } from './doctor-plan.mjs';
+import { CORE_LAYER_NAMES } from './core-layers.mjs';
+
+export { CORE_LAYER_NAMES } from './core-layers.mjs';
 
 /**
  * Core layers whose optionality matters once they match files (presets share these names).
  * Used by doctor adoption gaps and `--ratchet-cores`.
  */
-export const CORE_LAYER_NAMES = new Set([
-  'DomainModel',
-  'ApplicationOrchestration',
-  'PresentationAdapters',
-  'PersistenceAdapters',
-]);
-
 /**
  * Plan a ratchet of optional→required for core layers that already match files.
  * Empty cores stay optional (avoids false ENFORCE theatre). Pure — does not write disk.

package/bin/lib/doctor-plan.mjs

@@ -14,11 +14,12 @@ import {
 import {
   collectAdoptionGaps,
   detectSkillGaps,
+  detectWritePathCapabilities,
   missingGates,
   staleRunnerGateFiles,
 } from './agent-gates.mjs';
 import {
-  baselineKey,
+  baselineOccurrenceKeys,
   readBaseline,
   summarizeViolations,
   violationEdge,
@@ -268,10 +269,13 @@ export function runDoctor(root, config, files, rules, violations, asJson, option
   const skillGaps = detectSkillGaps(root);
   const staleRunners = staleRunnerGateFiles(root);
   const adoption = collectAdoptionGaps(root, config, cov);
+  // Prefer writePath from adoption (same detector); recompute only if missing (tests/stubs).
+  const writePath = adoption.writePath ?? detectWritePathCapabilities(root);
   const baseline = readBaseline(root, '.ark-baseline.json');
-  const currentKeys = new Set(violations.map(baselineKey));
+  const occurrenceKeys = baselineOccurrenceKeys(violations);
+  const currentKeys = new Set(occurrenceKeys);
   const suppressed = baseline.exists
-    ? violations.filter((v) => baseline.keys.has(baselineKey(v))).length
+    ? occurrenceKeys.filter((key) => baseline.keys.has(key)).length
     : 0;
   const staleBaseline = baseline.exists
     ? [...baseline.keys].filter((key) => !currentKeys.has(key)).length
@@ -323,7 +327,28 @@ export function runDoctor(root, config, files, rules, violations, asJson, option
             gatesMissing,
             skillGaps,
             staleRunnerFiles: staleRunners,
+            // W5 — prepare-write / autoPatch / reject-only awareness (stable additive)
+            writePath: {
+              mode: writePath.mode,
+              prepareWrite: writePath.prepareWrite,
+              autoPatch: writePath.autoPatch,
+              hookPresent: writePath.hookPresent,
+              hookRepair: writePath.hookRepair,
+              mcpPresent: writePath.mcpPresent,
+              evidence: writePath.evidence,
+              ...(writePath.gap
+                ? {
+                    gap: {
+                      id: writePath.gap.id,
+                      severity: writePath.gap.severity,
+                      message: writePath.gap.message,
+                      fix: writePath.gap.fix,
+                    },
+                  }
+                : { gap: null }),
+            },
             adoption,
+            safety: options.safety,
             newHere: showNewHere
               ? {
                   show: true,
@@ -469,6 +494,37 @@ export function runDoctor(root, config, files, rules, violations, asJson, option
     }
   }
 
+  console.log('');
+  console.log(color.bold('Write path (agent)'));
+  const writePathLabels = {
+    repair: 'repair-capable — hard block + machine-readable autoPatch / ARK_REPAIR_JSON',
+    'reject-only': 'reject-only — hard block with prose; no repair payload',
+    'mcp-only': 'MCP tools only — prepare-write/autoPatch available; no PreToolUse hook',
+    none: 'none — no write gate hook and no Ark MCP',
+  };
+  const wpMark =
+    writePath.mode === 'repair'
+      ? ok
+      : writePath.mode === 'none'
+        ? bad
+        : warn;
+  line(wpMark, `Mode: ${writePath.mode} — ${writePathLabels[writePath.mode] || writePath.mode}`);
+  line(
+    writePath.prepareWrite ? ok : warn,
+    `prepare-write (MCP): ${writePath.prepareWrite ? 'yes' : 'no'}`
+  );
+  line(
+    writePath.autoPatch ? ok : warn,
+    `autoPatch surface: ${writePath.autoPatch ? 'yes' : 'no'}`
+  );
+  if (writePath.gap) {
+    line(writePath.gap.severity === 'warn' ? warn : warn, writePath.gap.message);
+    if (writePath.gap.fix) {
+      line(' ', color.dim(`Fix: ${writePath.gap.fix}`));
+      actions.push(writePath.gap.fix);
+    }
+  }
+
   console.log('');
   console.log(color.bold('Gates & skills'));
   if (gatesMissing.length === 0) line(ok, 'Gate files present (AGENTS.md, .mcp.json, CI, write gate)');
@@ -538,11 +594,33 @@ export function runDoctor(root, config, files, rules, violations, asJson, option
     line(ok, 'Origin architecture snapshot present (.ark/reports/origin.json)');
   }
 
+  console.log('');
+  console.log(color.bold('Safety / bypass resistance'));
+  const safety = options.safety;
+  if (!safety) {
+    line(warn, 'Safety diagnostics unavailable');
+  } else {
+    const rows = [
+      ['Non-literal dynamic imports', safety.nonLiteralDynamicImports],
+      ['@ts-ignore / @ts-nocheck', safety.tsSuppressions],
+      ['Explicit any casts', safety.anyCasts],
+      ['InMemory stores in production source', safety.inMemoryProductionStores],
+      ['Rules with peerIsolation: false', safety.disabledPeerIsolationRules],
+    ];
+    for (const [label, entries] of rows) {
+      line(entries.length === 0 ? ok : warn, `${label}: ${entries.length}`);
+    }
+    if (rows.some(([, entries]) => entries.length > 0)) {
+      actions.push('resolve strict safety diagnostics before treating CI as enforcement');
+    }
+  }
+
   console.log('');
   if (actions.length === 0) {
     console.log(color.green('✔ Healthy — nothing to do.'));
   } else {
-    console.log(color.bold(`Top actions (${actions.length}):`));
-    actions.forEach((action, index) => console.log(`  ${index + 1}. ${action}`));
+    const uniqueActions = [...new Set(actions.filter(Boolean))];
+    console.log(color.bold(`Top actions (${uniqueActions.length}):`));
+    uniqueActions.forEach((action, index) => console.log(`  ${index + 1}. ${action}`));
   }
 }

package/bin/lib/port-proof.mjs

@@ -0,0 +1,309 @@
+/**
+ * W6 — Verified structural transform: port-proof inject binding (single narrow kind).
+ *
+ * Scope (intentionally tiny — false mechanical-safe is worse than extra judgment):
+ *   - Exactly one static named value import (no default / namespace / side-effect / export-from)
+ *   - Binding used ONLY as property-access call receiver: `binding.method(...)`
+ *   - All uses inside `function` declarations (not module-level, not classes, not arrows)
+ *   - No require / dynamic import
+ *
+ * Transform (single file):
+ *   1. Remove the import
+ *   2. Emit `export type <Port> = { method: (...args: unknown[]) => unknown; ... }`
+ *   3. Add `binding: Port` as last parameter of each function that uses it
+ *   4. Leave call expressions verbatim (`binding.method(...)`)
+ *
+ * Static proof of behavior preservation (module-local):
+ *   If the injected parameter equals the value previously bound by the import, every
+ *   statement in each rewritten function evaluates identically — call expressions are
+ *   preserved character-for-character after rebinding. No adapter file is invented;
+ *   the outer layer must pass the implementation (classic port inject).
+ *
+ * Fail closed: any unmatched use pattern → not eligible (judgment).
+ */
+import path from 'node:path';
+
+/**
+ * @param {object} ts typescript module
+ * @param {string} source
+ * @param {{ filePath?: string, importLocalName?: string, importSpecifier?: string }} [opts]
+ * @returns {{ eligible: boolean, reason?: string, bindingName?: string, methods?: string[], functionNames?: string[], specifier?: string }}
+ */
+export function provePortProofInject(ts, source, opts = {}) {
+  if (!ts || typeof source !== 'string') {
+    return { eligible: false, reason: 'missing-ts-or-source' };
+  }
+  const sf = ts.createSourceFile(
+    opts.filePath || 'file.ts',
+    source,
+    ts.ScriptTarget.Latest,
+    true,
+    ts.ScriptKind.TS
+  );
+
+  /** @type {import('typescript').ImportDeclaration | null} */
+  let targetImport = null;
+  let bindingName = null;
+  let specifier = null;
+  let namedImportCount = 0;
+
+  for (const stmt of sf.statements) {
+    if (!ts.isImportDeclaration(stmt)) continue;
+    if (stmt.importClause?.isTypeOnly) continue;
+    const clause = stmt.importClause;
+    if (!clause) continue; // side-effect
+    if (clause.name) {
+      // default import — never port-proof
+      return { eligible: false, reason: 'default-import' };
+    }
+    const named = clause.namedBindings;
+    if (!named || !ts.isNamedImports(named)) {
+      return { eligible: false, reason: 'namespace-or-missing-named' };
+    }
+    if (named.elements.some((el) => el.isTypeOnly)) {
+      // partial type-only mixed — not this transform
+      continue;
+    }
+    if (named.elements.length !== 1) {
+      return { eligible: false, reason: 'multi-named-import' };
+    }
+    namedImportCount += 1;
+    if (namedImportCount > 1) {
+      return { eligible: false, reason: 'multiple-value-imports' };
+    }
+    const el = named.elements[0];
+    bindingName = el.name.text;
+    specifier = stmt.moduleSpecifier && ts.isStringLiteralLike(stmt.moduleSpecifier)
+      ? stmt.moduleSpecifier.text
+      : null;
+    if (!specifier || (!specifier.startsWith('./') && !specifier.startsWith('../'))) {
+      return { eligible: false, reason: 'non-relative-specifier' };
+    }
+    if (opts.importLocalName && opts.importLocalName !== bindingName) {
+      return { eligible: false, reason: 'binding-mismatch' };
+    }
+    if (opts.importSpecifier && opts.importSpecifier !== specifier) {
+      // soft: still allow if only one import
+    }
+    targetImport = stmt;
+  }
+
+  if (!targetImport || !bindingName) {
+    return { eligible: false, reason: 'no-single-named-value-import' };
+  }
+
+  const methods = new Set();
+  const functionNames = new Set();
+  let freeBindingUse = false;
+
+  // Walk top-level: only function declarations may use the binding (as method calls).
+  function walkTop(node) {
+    if (ts.isFunctionDeclaration(node)) {
+      if (node.body) {
+        visitBody(node.body, node.name?.text);
+      }
+      return;
+    }
+    // Any binding use outside function decls is invalid
+    if (ts.isIdentifier(node) && node.text === bindingName) {
+      if (node.parent && ts.isImportSpecifier(node.parent)) return;
+      freeBindingUse = true;
+      return;
+    }
+    ts.forEachChild(node, walkTop);
+  }
+
+  function visitBody(body, fnName) {
+    function walk(node) {
+      if (ts.isIdentifier(node) && node.text === bindingName) {
+        const parent = node.parent;
+        if (
+          parent &&
+          ts.isPropertyAccessExpression(parent) &&
+          parent.expression === node &&
+          parent.parent &&
+          ts.isCallExpression(parent.parent) &&
+          parent.parent.expression === parent
+        ) {
+          methods.add(parent.name.text);
+          if (fnName) functionNames.add(fnName);
+          return;
+        }
+        freeBindingUse = true;
+        return;
+      }
+      // Nested functions: still require property-call form
+      if (ts.isFunctionDeclaration(node) || ts.isFunctionExpression(node) || ts.isArrowFunction(node)) {
+        // Nested non-declarations: fail closed (narrow transform)
+        if (!ts.isFunctionDeclaration(node)) {
+          // Check if binding used inside — if yes, ineligible
+          let nestedUse = false;
+          const check = (n) => {
+            if (ts.isIdentifier(n) && n.text === bindingName) nestedUse = true;
+            else ts.forEachChild(n, check);
+          };
+          if (node.body) check(node.body);
+          if (nestedUse) freeBindingUse = true;
+          return;
+        }
+      }
+      ts.forEachChild(node, walk);
+    }
+    walk(body);
+  }
+
+  for (const stmt of sf.statements) {
+    walkTop(stmt);
+  }
+
+  if (freeBindingUse) {
+    return { eligible: false, reason: 'free-or-non-call-use' };
+  }
+  if (methods.size === 0 || functionNames.size === 0) {
+    return { eligible: false, reason: 'no-method-calls-in-functions' };
+  }
+
+  return {
+    eligible: true,
+    bindingName,
+    methods: [...methods].sort(),
+    functionNames: [...functionNames].sort(),
+    specifier,
+  };
+}
+
+/**
+ * Apply port-proof inject when prove succeeds.
+ * @returns {{ source: string, remediationKind: string, confidence: number, proof: object } | null}
+ */
+export function applyPortProofInject(ts, source, opts = {}) {
+  const proof = provePortProofInject(ts, source, opts);
+  if (!proof.eligible) return null;
+
+  const sf = ts.createSourceFile(
+    opts.filePath || 'file.ts',
+    source,
+    ts.ScriptTarget.Latest,
+    true,
+    ts.ScriptKind.TS
+  );
+
+  const bindingName = proof.bindingName;
+  const methods = proof.methods;
+  const portTypeName = `${capitalize(bindingName)}Port`;
+
+  // Find import to remove
+  /** @type {{ start: number, end: number } | null} */
+  let importSpan = null;
+  for (const stmt of sf.statements) {
+    if (!ts.isImportDeclaration(stmt)) continue;
+    const clause = stmt.importClause;
+    if (!clause?.namedBindings || !ts.isNamedImports(clause.namedBindings)) continue;
+    if (clause.namedBindings.elements.length !== 1) continue;
+    if (clause.namedBindings.elements[0].name.text !== bindingName) continue;
+    // getStart skips leading trivia so we don't leave a stray indent before the port type.
+    importSpan = { start: stmt.getStart(sf), end: stmt.getEnd() };
+    if (source[importSpan.end] === '\r') importSpan.end += 1;
+    if (source[importSpan.end] === '\n') importSpan.end += 1;
+    break;
+  }
+  if (!importSpan) return null;
+
+  // Functions that need the port param
+  const fnEdits = [];
+  for (const stmt of sf.statements) {
+    if (!ts.isFunctionDeclaration(stmt) || !stmt.name || !stmt.body) continue;
+    if (!proof.functionNames.includes(stmt.name.text)) continue;
+    // Already has a param named bindingName?
+    const params = stmt.parameters || [];
+    if (params.some((p) => ts.isIdentifier(p.name) && p.name.text === bindingName)) {
+      continue;
+    }
+    // Fail closed: rest params / non-identifier patterns would yield illegal TS
+    // (e.g. function f(...args, db: Port)).
+    if (
+      params.some(
+        (p) =>
+          p.dotDotDotToken ||
+          !ts.isIdentifier(p.name)
+      )
+    ) {
+      return null;
+    }
+    if (params.length > 0) {
+      const at = params[params.length - 1].getEnd();
+      fnEdits.push({
+        start: at,
+        end: at,
+        text: `, ${bindingName}: ${portTypeName}`,
+      });
+    } else {
+      const open = source.indexOf('(', stmt.name.getEnd());
+      if (open < 0) continue;
+      const at = open + 1;
+      fnEdits.push({
+        start: at,
+        end: at,
+        text: `${bindingName}: ${portTypeName}`,
+      });
+    }
+  }
+  if (fnEdits.length === 0) return null;
+
+  const portDecl =
+    `export type ${portTypeName} = {\n` +
+    methods.map((m) => `  ${m}: (...args: unknown[]) => unknown;`).join('\n') +
+    `\n};\n\n`;
+
+  // Apply edits from end to start
+  const edits = [
+    { start: importSpan.start, end: importSpan.end, text: portDecl },
+    ...fnEdits,
+  ].sort((a, b) => b.start - a.start);
+
+  let out = source;
+  for (const e of edits) {
+    out = out.slice(0, e.start) + e.text + out.slice(e.end);
+  }
+  if (out === source) return null;
+
+  // Re-prove on result: binding should no longer need the import; methods still present
+  // (as params). Eligibility after transform is "no value import" — proof may fail for
+  // different reasons. Validate shape: no import of binding's original specifier as value.
+  if (new RegExp(`import\\s*\\{[^}]*\\b${escapeRe(bindingName)}\\b`).test(out)) {
+    return null;
+  }
+  if (!out.includes(`export type ${portTypeName}`)) return null;
+
+  return {
+    source: out,
+    remediationKind: 'port-proof-inject-binding',
+    confidence: 0.8,
+    proof: {
+      bindingName,
+      methods,
+      functionNames: proof.functionNames,
+      specifier: proof.specifier,
+      portTypeName,
+    },
+  };
+}
+
+function capitalize(s) {
+  if (!s) return 'Port';
+  return s.charAt(0).toUpperCase() + s.slice(1);
+}
+
+function escapeRe(s) {
+  return String(s).replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+/**
+ * True when relative path basename matches a common path segment of the import target.
+ * Used only as a soft filter when wiring from ark-check violations.
+ */
+export function specifierLooksLikeTarget(specifier, violationTargetRel) {
+  if (!specifier || !violationTargetRel) return true;
+  const base = path.basename(violationTargetRel, path.extname(violationTargetRel));
+  return specifier.includes(base) || violationTargetRel.includes(specifier.replace(/^\.\//, ''));
+}

package/bin/lib/prepare-write.mjs

@@ -0,0 +1,130 @@
+/**
+ * W2 — ark_prepare_write composition helpers.
+ *
+ * Place + constrain + validate + autoPatch + judgmentBrief + content identity.
+ * Pure-ish: no second architecture contract — callers pass placement + validate.
+ */
+import crypto from 'node:crypto';
+import { validateWithAutoPatch } from './auto-patch.mjs';
+import { classifyRemediation, enrichViolationWithFixClass } from './remediation.mjs';
+
+/**
+ * Stable content identity for host commit / cache keys.
+ * @param {string} source
+ * @returns {{ contentHash: string, byteLength: number }}
+ */
+export function contentIdentity(source) {
+  const text = typeof source === 'string' ? source : '';
+  const contentHash = `sha256:${crypto.createHash('sha256').update(text, 'utf8').digest('hex')}`;
+  return { contentHash, byteLength: Buffer.byteLength(text, 'utf8') };
+}
+
+/**
+ * One judgment decision for the agent when autoPatch is absent or insufficient.
+ * @param {Array<object>} violations
+ * @returns {null | { fixClass: string, decision: string, remediationClass: string, remediationKind?: string }}
+ */
+export function buildJudgmentBrief(violations) {
+  if (!Array.isArray(violations) || violations.length === 0) return null;
+  for (const v of violations) {
+    const ruleId = v.ruleId || v.code;
+    const shaped = {
+      ruleId,
+      typeOnly: v.typeOnly ?? v.details?.typeOnly,
+      sourcePureTypeModule: v.sourcePureTypeModule,
+      targetTypeOnlyExports: v.targetTypeOnlyExports,
+      namedBindingsTypeOnly: v.namedBindingsTypeOnly,
+      peerIsolation: v.peerIsolation ?? v.details?.peerIsolation,
+      edgeKind: v.edgeKind ?? v.details?.importKind,
+      fromLayer: v.fromLayer,
+      toLayer: v.toLayer,
+      target: v.target,
+      message: v.message,
+    };
+    const verdict = classifyRemediation(shaped);
+    if (verdict.class === 'mechanical-safe') continue;
+    const enriched = enrichViolationWithFixClass(shaped);
+    return {
+      fixClass: enriched.fixClass,
+      decision: enriched.enthusiastHint,
+      remediationClass: verdict.class,
+      ...(verdict.remediationKind ? { remediationKind: verdict.remediationKind } : {}),
+    };
+  }
+  // All mechanical-safe or unclassifiable — still offer first enriched hint
+  const first = violations[0];
+  const ruleId = first.ruleId || first.code;
+  const shaped = { ...first, ruleId };
+  const enriched = enrichViolationWithFixClass(shaped);
+  const verdict = classifyRemediation(shaped);
+  return {
+    fixClass: enriched.fixClass,
+    decision: enriched.enthusiastHint,
+    remediationClass: verdict.class,
+    ...(verdict.remediationKind ? { remediationKind: verdict.remediationKind } : {}),
+  };
+}
+
+/**
+ * Compose placement + write-boundary validation into one prepare_write result.
+ *
+ * @param {{
+ *   source: string,
+ *   placement: object,
+ *   root: string,
+ *   ts: object,
+ *   validate: (source: string) => { valid: boolean, violations?: any[] },
+ *   resolveTargetAbs?: Function,
+ * }} opts
+ */
+export function composePrepareWrite(opts) {
+  const { source, placement, root, ts, validate, resolveTargetAbs } = opts;
+  if (typeof source !== 'string') {
+    return {
+      ok: false,
+      error: 'source is required (string)',
+    };
+  }
+  const identity = contentIdentity(source);
+  const filePath = placement?.filePath;
+  const gate = validateWithAutoPatch({
+    source,
+    filePath,
+    root,
+    ts,
+    validate,
+    resolveTargetAbs,
+  });
+
+  // judgmentBrief when invalid and no mechanical autoPatch (agent must decide).
+  // When autoPatch is present, omit brief — host should apply the patch first.
+  const judgment =
+    !gate.valid && !gate.autoPatch ? buildJudgmentBrief(gate.violations) : null;
+
+  return {
+    ok: true,
+    filePath: placement?.filePath ?? null,
+    layer: placement?.layer ?? null,
+    governed: placement?.governed,
+    proposed: placement?.proposed,
+    mayImport: placement?.mayImport,
+    mustNotImport: placement?.mustNotImport,
+    forbiddenGlobals: placement?.forbiddenGlobals ?? [],
+    ...(placement?.mayImportInfrastructure ? { mayImportInfrastructure: true } : {}),
+    ...(placement?.suggestedLayers ? { suggestedLayers: placement.suggestedLayers } : {}),
+    ...(placement?.message ? { placementMessage: placement.message } : {}),
+    ...(placement?.note ? { placementNote: placement.note } : {}),
+    ...(placement?.description ? { description: placement.description } : {}),
+    valid: gate.valid,
+    violations: gate.violations,
+    ...(gate.autoPatch ? { autoPatch: gate.autoPatch } : {}),
+    ...(judgment ? { judgmentBrief: judgment } : {}),
+    contentHash: identity.contentHash,
+    byteLength: identity.byteLength,
+    ...(gate.autoPatch
+      ? {
+          autoPatchContentHash: contentIdentity(gate.autoPatch.source).contentHash,
+        }
+      : {}),
+  };
+}

package/bin/lib/remediation.mjs

@@ -19,6 +19,14 @@ export const MECHANICAL_SAFE_KINDS = [
     'type-only-import-move',
     'import-type-from-pure-type-module',
     'import-type-of-type-exports',
+    // port-proof-inject-binding is intentionally NOT mechanical-safe (signature change).
+];
+/**
+ * Judgment-class kinds that still have a named transform / plan label (eval corpus vocabulary).
+ * Never auto-apply without multi-file / caller proof.
+ */
+export const JUDGMENT_SUGGESTED_KINDS = [
+    'port-proof-inject-binding',
 ];
 /** fixClass values from enrichViolationWithFixClass (eval corpus / reports). */
 export const KNOWN_FIX_CLASSES = [
@@ -91,6 +99,19 @@ export function classifyRemediation(violation) {
                 rationale: 'Named bindings are type-only exports of the target module (even if the file also exports values): convert to `import type` / `export type` (erased at runtime). Gate verifies.',
             };
         }
+        // W6: port-proof inject is a *suggested* shape when proof holds, but always judgment
+        // for auto-apply — adding a required parameter breaks external call sites.
+        if (violation?.portProofEligible &&
+            edgeKind !== 'require' &&
+            edgeKind !== 'dynamic-import' &&
+            !violation?.typeOnly) {
+            return {
+                class: 'judgment',
+                confidence: 0.82,
+                remediationKind: 'port-proof-inject-binding',
+                rationale: 'Port-proof shape: single named value import used only as binding.method(...) in function declarations. Inject as a port parameter (body-local calls preserved) — outer layer must pass the impl. Not mechanical-safe auto-apply: call arity changes. Apply via agent judgment / multi-file plan.',
+            };
+        }
         return {
             class: 'judgment',
             confidence: 0.7,