arkgate 4.8.25 → 4.8.27

package/CHANGELOG.md

@@ -5,6 +5,33 @@ in the immutable pre-2.0 archive linked below.
 
 ## Unreleased
 
+## 4.8.27 — 2026-10-14
+
+**Patch** over **4.8.26**. First-principles enforcement, public layer entrypoints, and remediation blueprints (P0–P5). **Write. Check. Ship.** **No required config migration.** No `schemaVersion` bump. Does not close `K01` / `Z09`. This mother `ark.config.json` still does **not** turn `arkOrder` on.
+
+**Status: released** (tag `v4.8.27`). Run `npm view arkgate@4.8.27 version` to confirm (#314).
+
+### Added
+- `layers[].entrypoints` public surface contract enforced across `ark-check`, `arkgate/eslint`, `AICodeGate`, and `ark-mcp` at the `findDeniedEdgeDecision` waist, with policy-delta classification and config warnings.
+- `ark_place` and `ark_prepare_write` project `entrypoints` and `targetEntrypoints` so agents know which public barrel/entrypoint to import before writing.
+- Deterministic TypeScript remediation `blueprint` (`judgmentBrief.blueprint`) on rejections for `LAYER_IMPORT_VIOLATION` (including `entrypoints`), `FORBIDDEN_GLOBAL`, `CAPABILITY_VIOLATION`, `ARKORDER_*`, and `ARKRUN_*`.
+- `ark init --baseline [path]` freezes existing violations into `.ark-baseline.json` via `--write-baseline` and wires `--baseline` into `--strict-merge` during brownfield onboarding.
+- Immediate 2-hop value cycle detection (`A -> B -> A`) in single-file `Write`/`Edit` hooks and `ark_prepare_write` when `cyclePolicy` is `"strict"`, plus warm resident `ApplyPatch` / `apply_patch` evaluation (`1500ms` window) and incremental `ResolverIngestCache`.
+
+### Fixed
+- `arkRuleSensors` masks comments and strings before evaluating `aggregate-guards-invariants` and `immutable-value-object` method bodies, and recognizes structural `if (...) throw` guard clauses.
+- Enabled `treeshake: true` in `tsup.config.ts` and `packages/runtime/tsup.config.ts`, shrinking compiled runtime bundles.
+
+## 4.8.26 — 2026-10-13
+
+**Patch** over **4.8.25**. #353 and #354. **Write. Check. Ship.** **No required config migration.** No `schemaVersion` bump. Does not close `K01` / `Z09`. This mother `ark.config.json` still does **not** turn `arkOrder` on.
+
+**Status: released** (tag `v4.8.26`). Run `npm view arkgate@4.8.26 version` to confirm (#314).
+
+### Fixed
+- `--root` is always the analyzed tree. `--config` is only a file: an explicit path never replaces `--root` with the config's folder (#353, #352).
+- `--strict` refuses a config outside the Git repository before base-ref discovery, including on the trunk (#354).
+
 ## 4.8.25 — 2026-10-05
 
 **Patch** over **4.8.24**. Weekly accumulate (#342, #344, #345, #346, #347, #348, #349, #350). **Write. Check. Ship.** **No required config migration.** `childSlices.arkRulesFile` and pinned `sliceAliases` need 4.8.25. No `schemaVersion` bump. Does not close `K01` / `Z09`. This mother `ark.config.json` still does **not** turn `arkOrder` on.

package/README.md

@@ -25,11 +25,11 @@ Design the boundary before you implement. Put a small interface in front of the
 
 ## Try it
 
-One command. Preview only — no files change. Current release is **4.8.25**
+One command. Preview only — no files change. Current release is **4.8.27**
 (check npm `latest` with `npm view arkgate version`):
 
 ```bash
-npx arkgate@4.8.25 start
+npx arkgate@4.8.27 start
 ```
 
 ## What a red result looks like

package/bin/ark-layer-match.mjs

@@ -1858,6 +1858,29 @@ export function findDeniedEdgeDecision(rules, from, to, options) {
             continue;
         return { rule };
     }
+    if (from !== to &&
+        typeof options?.toPath === 'string' &&
+        options.toPath.length > 0 &&
+        Array.isArray(options?.layers)) {
+        const targetLayer = options.layers.find((layer) => layer.name === to);
+        const entrypoints = Array.isArray(targetLayer?.entrypoints)
+            ? targetLayer.entrypoints.filter((entry) => typeof entry === 'string' && entry.length > 0)
+            : [];
+        if (entrypoints.length > 0) {
+            const normTo = String(options.toPath).split(/[/\\]/).join('/');
+            const matchesEntrypoint = entrypoints.some((pattern) => globToRegExp(pattern).test(normTo));
+            if (!matchesEntrypoint) {
+                return {
+                    rule: {
+                        from,
+                        to,
+                        allowed: false,
+                        message: `${from} may only import ${to} via its declared entrypoints (${entrypoints.join(', ')}); deep import "${normTo}" bypasses the public surface.`,
+                    },
+                };
+            }
+        }
+    }
     return undefined;
 }
 /**

package/bin/ark-mcp-runtime.mjs

@@ -100,6 +100,7 @@ import {
 } from './lib/mcp-hook-payload.mjs';
 import {
   canonicalizeCandidateChanges,
+  createResolverIngestCache,
   resolvedCompilerInputPaths,
   resolvedInputIdentities,
 } from './lib/resolved-candidate-facts.mjs';
@@ -415,8 +416,16 @@ function snippetContext({
   classification,
   arkRulesSnapshot,
   surface,
+  resolveImportTarget,
 }) {
-  const base = { layer, filePath, ...(surface ? { surface } : {}) };
+  const base = {
+    root,
+    layer,
+    filePath,
+    cyclePolicy: config?.cyclePolicy ?? 'strict',
+    ...(typeof resolveImportTarget === 'function' ? { resolveImportTarget } : {}),
+    ...(surface ? { surface } : {}),
+  };
   const arkRulesOn = (arkRulesSnapshot?.arkRules?.structure?.length ?? 0) > 0;
   const contractErrors = arkRulesSnapshot?.errors ?? [];
   if (!config?.arkRun && !config?.arkOrder && !arkRulesOn && contractErrors.length === 0) {
@@ -597,9 +606,13 @@ function runHookPayload(payload, gate, config, args, ts, attemptContext, output
       return;
     }
     const patchChangeSet = classifyChangeSet(patchWrites.map((change) => String(change.path)));
+    const effectiveContractSession =
+      typeof attemptContext?.contractSession === 'boolean'
+        ? attemptContext.contractSession
+        : contractSessionFrom({});
     const patchLawGate = evaluateTeamGate({
       changeSet: patchChangeSet,
-      contractSession: contractSessionFrom({}),
+      contractSession: effectiveContractSession,
     });
     if (patchLawGate.deny && patchChangeSet.mixed) {
       const message = patchLawGate.message;
@@ -737,6 +750,8 @@ function runHookPayload(payload, gate, config, args, ts, attemptContext, output
         ts,
         tsconfig: args.tsconfig,
         manifest: args.projectManifest,
+        ingestCache: args.residentIngestCache,
+        contractSession: effectiveContractSession,
       });
     } catch (error) {
       const message = error instanceof Error ? error.message : String(error);
@@ -920,6 +935,7 @@ function runHookPayload(payload, gate, config, args, ts, attemptContext, output
     relFile: normalizedRel,
     arkRulesSnapshot: args.arkRulesSnapshot,
     surface: 'hook',
+    resolveImportTarget: args.resolveImportTarget,
   });
   const validateOnce = (src) =>
     validateSnippetAnalysis({ gate, ts, source: src, context });
@@ -1224,7 +1240,10 @@ function captureResidentHook(payload, gate, config, args, ts, request) {
       failOnNewSmells: request.failOnNewSmells === true,
     },
     ts,
-    { grokHookEvent: request.grokHookEvent === true },
+    {
+      grokHookEvent: request.grokHookEvent === true,
+      contractSession: request.contractSession === true,
+    },
     {
       stdout: (value) => {
         stdout += value;
@@ -1632,6 +1651,10 @@ export async function runArkMcp({ hookInput, hookRoot } = {}) {
     .filter((layer) => layer.name && layer.mayImportInfrastructure === true)
     .map((layer) => layer.name);
 
+  const importTargetResolver = createImportTargetResolver(ts, args.root, config);
+  args.resolveImportTarget = importTargetResolver;
+  args.residentIngestCache = createResolverIngestCache(config);
+
   const gate = ark.createAICodeGate({
     architectureProfile: profile,
     intents,
@@ -1641,10 +1664,11 @@ export async function runArkMcp({ hookInput, hookRoot } = {}) {
     capabilityWalls,
     infrastructureLayers,
     // Contract-first: one resolve step yields layer + relPath for rules + peerIsolation.
-    resolveImportTarget: createImportTargetResolver(ts, args.root, config),
+    resolveImportTarget: importTargetResolver,
     architectureLayers: configLayers.map((layer) => ({
       name: layer.name,
       patterns: layer.patterns,
+      ...(Array.isArray(layer.entrypoints) ? { entrypoints: layer.entrypoints } : {}),
     })),
     allowNonLiteralDynamicImport: (filePath) => {
       if (!filePath || !Array.isArray(config.dynamicImportAllowlist)) return false;
@@ -2624,6 +2648,7 @@ export async function runArkMcp({ hookInput, hookRoot } = {}) {
       layer,
       arkRulesSnapshot: effectiveArkRulesSnapshot,
       surface: 'mcp',
+      resolveImportTarget: args.resolveImportTarget,
     });
     const validateOnce = (src) => validateSnippetAnalysis({ gate, ts, source: src, context });
     // W1: attempt mechanical-safe single-file autoPatch (import type), re-validate or discard.
@@ -2874,6 +2899,16 @@ export async function runArkMcp({ hookInput, hookRoot } = {}) {
       rules.some((rule) => !rule.allowed && rule.from === layerName && rule.to === to)
     );
     const mayImport = otherNames.filter((name) => !mustNotImport.includes(name));
+    const targetEntrypoints = Object.fromEntries(
+      configLayers
+        .filter(
+          (layer) =>
+            mayImport.includes(layer.name) &&
+            Array.isArray(layer.entrypoints) &&
+            layer.entrypoints.length > 0
+        )
+        .map((layer) => [layer.name, layer.entrypoints])
+    );
     const sliceCatalog = [
       ...(args.arkRulesSnapshot?.arkRules?.structure ?? []),
       ...(args.arkRulesSnapshot?.arkRules?.invariants ?? []),
@@ -2886,6 +2921,10 @@ export async function runArkMcp({ hookInput, hookRoot } = {}) {
       ...placementDescriptionFields(layerMeta),
       forbiddenGlobals: layerMeta?.forbiddenGlobals ?? [],
       ...(layerMeta?.mayImportInfrastructure ? { mayImportInfrastructure: true } : {}),
+      ...(Array.isArray(layerMeta?.entrypoints) && layerMeta.entrypoints.length > 0
+        ? { entrypoints: layerMeta.entrypoints }
+        : {}),
+      ...(Object.keys(targetEntrypoints).length > 0 ? { targetEntrypoints } : {}),
       ...(sliceRules.length > 0 ? { sliceRules } : {}),
       mayImport,
       mustNotImport,
@@ -2946,6 +2985,7 @@ export async function runArkMcp({ hookInput, hookRoot } = {}) {
       layer,
       arkRulesSnapshot: effectiveArkRulesSnapshot,
       surface: 'mcp',
+      resolveImportTarget: args.resolveImportTarget,
     });
     const validateOnce = (src) => validateSnippetAnalysis({ gate, ts, source: src, context });
     const result = composePrepareWrite({
@@ -2998,6 +3038,7 @@ export async function runArkMcp({ hookInput, hookRoot } = {}) {
         ts,
         tsconfig: args.tsconfig,
         manifest: projectManifest,
+        ingestCache: args.residentIngestCache,
       });
       return validityToolResult(result);
     } catch (error) {

package/bin/ark-mcp.mjs

@@ -44,8 +44,7 @@ function launcherArgs(argv) {
 }
 
 function residentEligiblePayload(payload) {
-  const toolName = payload?.tool_name ?? payload?.toolName;
-  return !['ApplyPatch', 'apply_patch'].includes(toolName);
+  return Boolean(payload && typeof payload === 'object');
 }
 
 async function tryResidentHook(args, hookInput) {
@@ -58,6 +57,8 @@ async function tryResidentHook(args, hookInput) {
     return { status: 0, stdout: '', stderr: '' };
   }
   if (!residentEligiblePayload(payload)) return null;
+  const toolName = payload?.tool_name ?? payload?.toolName;
+  const isPatch = toolName === 'ApplyPatch' || toolName === 'apply_patch';
   const endpoint = residentHookEndpoint({
     root: args.root,
     config: args.config,
@@ -70,7 +71,9 @@ async function tryResidentHook(args, hookInput) {
     socket: endpoint.socket,
     timeoutMs: Number.isFinite(configuredTimeout) && configuredTimeout > 0
       ? configuredTimeout
-      : 75,
+      : isPatch
+        ? 1500
+        : 75,
     request: {
       protocolVersion: RESIDENT_HOOK_PROTOCOL_VERSION,
       kind: 'hook',
@@ -81,6 +84,9 @@ async function tryResidentHook(args, hookInput) {
       hookRepair: args.hookRepair,
       failOnNewSmells: args.failOnNewSmells,
       grokHookEvent: Boolean(process.env.GROK_HOOK_EVENT),
+      contractSession: /^(?:1|true|yes|on)$/i.test(
+        String(process.env.ARK_CONTRACT_SESSION ?? '').trim()
+      ),
       payload,
     },
   });

package/bin/ark.mjs

@@ -98,7 +98,7 @@ function freezeDayZeroOrigin(root) {
 /** Commands that read a non-default contract file via --config. */
 const CONFIG_FLAG_COMMANDS = new Set(['preflight', 'status', 'agents-md', 'agent-projection']);
 
-function parseArgs(argv) {
+export function parseArgs(argv) {
   const args = {
     command: undefined,
     root: process.cwd(),
@@ -119,6 +119,7 @@ function parseArgs(argv) {
     requireWriteHook: undefined,
     expectedRoot: undefined,
     expectedProjectId: undefined,
+    baseline: undefined,
     write: false,
     check: false,
     stdout: false,
@@ -144,6 +145,15 @@ function parseArgs(argv) {
     else if (arg === '--yes' || arg === '-y') args.yes = true;
     else if (arg === '--force') args.force = true;
     else if (arg === '--no-strict') args.strict = false;
+    else if (arg === '--baseline') {
+      const next = argv[i + 1];
+      if (next !== undefined && !next.startsWith('-')) {
+        args.baseline = next;
+        i += 1;
+      } else {
+        args.baseline = '.ark-baseline.json';
+      }
+    }
     else if (arg === '--install') {
       args.install = true;
       args.installExplicit = true;
@@ -369,11 +379,27 @@ async function init(args) {
       if (status !== 0) return status;
     }
 
+    if (args.baseline) {
+      const baselineAbs = path.isAbsolute(args.baseline)
+        ? args.baseline
+        : path.join(root, args.baseline);
+      if (!fs.existsSync(baselineAbs) || args.force) {
+        const baselineStatus = runArkCheck(
+          ['--root', root, '--config', 'ark.config.json', '--write-baseline', args.baseline],
+          { cwd: root }
+        );
+        if (baselineStatus !== 0) return baselineStatus;
+      }
+    }
+
     const runStrict =
       args.strict &&
       (nonInteractive || (await askYesNo(rl, 'Run strict architecture check now?', true)));
     if (runStrict) {
       const strictArgs = ['--root', root, '--config', 'ark.config.json', '--strict-merge'];
+      if (args.baseline) {
+        strictArgs.push('--baseline', args.baseline);
+      }
       if (args.requireWriteHook) {
         strictArgs.push('--require-write-hook', args.requireWriteHook);
       }