arkgate 4.6.7 → 4.7.0

package/CHANGELOG.md

@@ -5,6 +5,115 @@ in the immutable pre-2.0 archive linked below.
 
 ## Unreleased
 
+## 4.7.0 — 2026-08-25
+
+**Minor** over **4.6.7**. Ships **ArkRun**: an opt-in extra on schema `1.2` for kernel
+usage and complete declarations, plus companion `@arkgate/runtime` DX. Absence is
+silent (Layers / ArkRules verdicts unchanged). In-memory stores remain
+reference-only. **No required config migration.** Does not close Z09 / K01.
+
+**Status: prepared** (see `docs/releases/4.7.0.md`). npm `latest` remains **4.6.7**
+until publish.
+
+### Added
+
+- **`arkRun` extra on `ark.config.json` schema `1.2` (RN02):** optional inline
+  `{ mode, compositionRoots, managedLayers, requireDeclarations }`. `1.1` and
+  earlier configs migrate in memory; absence is silent (Layers / ArkRules
+  verdicts unchanged). Unknown keys, unknown `managedLayers` names, and empty
+  `compositionRoots` in `enforced` mode fail closed (`ARKRUN_MISSING_ROOT`).
+  Advisory → enforced is a strengthening policy delta; demotion or deletion is
+  weakening and needs the existing hash-bound ack. ESLint envelope is RN06
+  (landed below); CI extra teeth landed in RN07. Does not close Z09 / K01.
+
+- **ArkRun resolver facts on resolved-candidate-facts schema `1.2` (RN03):**
+  additive optional `arkRunKernelCalls`, `arkRunManagedNews`, and
+  `arkRunCompositionRootHits`. `1.0`/`1.1` payloads stay loadable (empty
+  arrays). Syntax evidence only — sensors consume these in RN04. Absence of
+  `arkRun` still leaves Layers / ArkRules verdicts unchanged. Does not close
+  Z09 / K01.
+
+- **ArkRun tier-1 sensors (RN04):** when `arkRun` is present, closed sensors
+  emit `ARKRUN_MISSING_ROOT`, `ARKRUN_KERNEL_IN_DOMAIN`, `ARKRUN_DIRECT_NEW`,
+  `ARKRUN_UNDECLARED_EMIT`, `ARKRUN_UNDECLARED_HANDLE`, `ARKRUN_UNDECLARED_DEPEND`,
+  and `ARKRUN_TRANSPORT_BYPASS`. Advisory findings never flip `valid`; enforced
+  blocks. Absence of the extra is still silent on Layers / ArkRules verdicts.
+  Optional `arkRunDeclarations` facts stay additive on schema `1.2`. Dual-depth
+  catalog nextAction is RN05 (landed below). Does not close Z09 / K01.
+
+- **ArkRun diagnostic catalog dual-depth (RN05):** closed `ARKRUN_*` catalog
+  entries have dual-depth remediation: casual `enthusiastHint` plus engineer
+  `nextAction` (target interpolates the call-site literal or specifier). Adding
+  an existing declaration-list string is `mechanical-safe` (`arkrun-declaration-list`)
+  only when that literal is already present; other ArkRun findings stay
+  `judgment`. Sensors, adapter fallback, and CLI remediation share
+  `deterministicNextAction`. Does not close Z09 / K01.
+
+- **ArkRun ESLint envelope (RN06):** `arkgate/eslint` recommended config adds
+  `ark/no-arkrun-kernel-in-domain`, `ark/no-arkrun-direct-new`, and
+  `ark/no-arkrun-transport-bypass`. Same `ARKRUN_*` sensors as ark-check for
+  the import / `new` envelope; silent when `arkRun` is absent. Missing-root and
+  undeclared-* stay CLI/MCP/preflight. Does not close Z09 / K01.
+
+- **ArkRun extra-teeth parity (RN07):** CLI `--strict-merge`, MCP `ark_check` /
+  snippet write, PreToolUse hook, atomic preflight, and CI share one ArkRun
+  verdict. Enforced extra teeth arm only when the layer plane is classified
+  (same ≥50% governed / ≥1 populated-layer floor as ArkRules); advisory and
+  absence stay silent on `valid`. Doctor/status `arkRun` section landed in
+  RN08 below. Does not close Z09 / K01.
+
+- **ArkRun doctor / status / report (RN08):** `ark-check --doctor`, HTML
+  `--report`, and `ark status` / MCP `ark_status` expose an `arkRun` section
+  that is always `notAScore`. Residual is a finding-id count, never a score or
+  LLM verdict. `mergePlanes.arkRun` states whether the extra can fail merge;
+  advisory and absence never arm extra teeth. Report parity requires
+  `data-advisory="arkRun"`. Does not close Z09 / K01.
+
+- **ArkRun companion branding (RN09):** `@arkgate/runtime` README and public
+  docs brand the kernel **ArkRun**. `createStrictArkKernel` stays the factory
+  (per-instance; no process-wide singleton). Kernel implementation stays out of
+  the `arkgate` tarball. Branding is not a production-durability claim. Does not
+  close Z09 / K01.
+
+- **ArkRun interaction declarations (RN10):** `@arkgate/runtime` `register()`
+  accepts `uses` / `reactsTo` / `raises` / `sends` plus optional tooling-only
+  `extendedInfo`. `getDependencyInformationPackage()` returns a JSON-serializable
+  snapshot of ids, lifetime, and declarations — never factories, live instances,
+  or input DTOs. Companion registrations may omit declarations for local
+  experiments; enforced `arkRun` on the gate still requires them. Does not close
+  Z09 / K01.
+
+- **ArkRun transport ports (RN11):** `@arkgate/runtime` `send()` is one call site
+  for `local` / `localBlocking` / `broker`. `ephemeral` defaults true (await local
+  recording or adapter accept — not a durability claim). Missing broker adapter
+  falls back to in-process local delivery, not cloud portability. No cloud SDKs
+  ship in the package. Does not close Z09 / K01.
+
+- **ArkRun dev inspector (RN12):** `@arkgate/runtime` `startInspector()` /
+  `startArkRunInspector()` is opt-in. Default bind is `127.0.0.1`; `NODE_ENV=production`
+  vetoes start; public hosts (`0.0.0.0`, `::`) are rejected. HTTP is lazy-loaded.
+  `GET /snapshot` and `GET /events` (SSE) serve the information package plus
+  transport facts (no factories, no shipped cloud SDKs). Does not close Z09 / K01.
+
+- **ArkRun graph slices (RN13):** `@arkgate/runtime` `requestGraph()` slices the
+  information package into `process` (raises / reactsTo / sends) or `technical`
+  (`uses`) graphs. Optional `nodeIds`, `degreesOfSeparation`, and include/exclude
+  query keep a neighborhood. `formatArkRunGraphMermaid()` / `graph.mermaid` is a
+  helper string, never a score. Inspector `GET /graph` serves the same slice.
+  Does not close Z09 / K01.
+
+- **ArkRun skip corpus (RN14):** `tests/fixtures/arkrun-skip-corpus/` is the
+  executable proof: Application `new`, same-layer peer import, and homemade
+  `EventEmitter` stay green when `arkRun` is absent (Layers / ArkRules match
+  schema `1.1`) and fail write path, CLI, MCP, and `--strict-merge` when the
+  extra is enforced. Does not close Z09 / K01.
+
+- **ArkRun skill-body deepen (RN15):** `/ark-runtime`, `/ark-place`, and
+  `/ark-adopt` teach the extra vs companion (advisory adopt, kernel-only
+  scaffold, composition-root wiring). Frozen **13** names — no `/ark-run`.
+  Skills never enforce; doctor `arkRun` stays `notAScore`. Agent Skills layout
+  stays 1:1 with `templates/skills`. Does not close Z09 / K01.
+
 ## 4.6.7 — 2026-08-24
 
 **Patch** over **4.6.6**. Production-hardening: CODEOWNERS, eval/pack honesty, CLI extracts,

package/README.md

@@ -16,11 +16,11 @@ and makes sure a “green” check means something real.
 
 </div>
 
-> **ArkGate 4.6.7** is current on npm `latest`.
+> **ArkGate 4.7.0** is prepared on this tree. **4.6.7** remains npm `latest` until publish.
 > A tree is **adopted** only with a required GitHub status running `arkgate-check --strict-merge`,
 > or `.ark/adoption-stance.json` `stance: "advisory-only"`. Doctor is compact (`--doctor --all`
-> for Details). [4.6.7 notes](docs/releases/4.6.7.md) · [4.6.6](docs/releases/4.6.6.md) ·
-> [Docs hub](docs/README.md) · [Product voice](docs/product-voice.md)
+> for Details). [4.7.0 notes](docs/releases/4.7.0.md) · [4.6.7](docs/releases/4.6.7.md) ·
+> [4.6.6](docs/releases/4.6.6.md) · [Docs hub](docs/README.md) · [Product voice](docs/product-voice.md)
 
 ---
 
@@ -78,11 +78,12 @@ A machine-readable architecture file (`ark.config.json`) plus enforcement:
 |-------|----------------|--------|
 | **Layers** (always) | Who may import whom — imports, placement, purity, isolation | `ark.config.json` layers + rules |
 | **ArkRules** (opt-in; structure rules inside a layer) | Habits *inside* a layer — structure sensors + domain invariants as data | `arkRules` → `arkrules/<Layer>.json` |
+| **ArkRun** (opt-in extra) | Kernel usage + complete declarations | `arkRun` on schema `1.2` |
 
-Absence of ArkRules changes no inter-layer verdict. Label residual **`[Layer]`** vs **`[ArkRules]`**.  
-Details: [configuration](docs/configuration.md#arkrules-intra-layer-opt-in) · [use path](docs/use.md).
+Absence of ArkRules or ArkRun changes no inter-layer verdict. Label residual **`[Layer]`** vs **`[ArkRules]`**.  
+Details: [configuration](docs/configuration.md) · [use path](docs/use.md).
 
-**Not** a web framework, ORM, or job runner. Optional experimental runtime is separate and not required for the gate.
+**Not** a web framework, ORM, or job runner. Optional **ArkRun** extra and companion kernel (`@arkgate/runtime`) are separate and not required for the gate. In-memory stores are not production durability.
 
 **Name note:** npm package `arkgate` — not affiliated with the separate Archgate CLI project.
 
@@ -192,9 +193,18 @@ More: [docs/develop.md](docs/develop.md) · skills install: [docs/agent-guide.md
 
 ---
 
-## Optional experimental runtime
+## Optional ArkRun kernel
 
-Gates need **no** app runtime. The experimental `@arkgate/runtime` companion is separate and is not a production-readiness claim.
+Gates need **no** app runtime. The experimental **ArkRun** companion (`@arkgate/runtime`) is separate
+and is not a production-readiness claim. `createStrictArkKernel` is the factory: each call creates
+an isolated instance (no process-wide singleton). Managed components declare `uses` / `reactsTo` /
+`raises` / `sends`; `getDependencyInformationPackage()` is a JSON snapshot and never leaks factories.
+`requestGraph()` slices that snapshot into process or technical graphs (`nodeIds`,
+`degreesOfSeparation`, include/exclude query) with a Mermaid helper. `send()` is local /
+localBlocking / broker (broker falls back to in-process local; `ephemeral`
+defaults true; no cloud SDKs in the package). Opt-in `startInspector()` binds `127.0.0.1`,
+refuses `NODE_ENV=production`, and lazy-loads HTTP for JSON snapshots, SSE, and `/graph`. The kernel is
+not bundled in the `arkgate` tarball.
 
 ### Durability stance
 
@@ -217,7 +227,8 @@ for real systems. Details: [docs/production-hardening.md](docs/production-harden
 | Config · package surface · TS | [configuration](docs/configuration.md) · [package-surface](docs/package-surface.md) · [typescript-support](docs/typescript-support.md) |
 | Brownfield | [docs/brownfield-adoption.md](docs/brownfield-adoption.md) |
 | Security | [SECURITY.md](SECURITY.md) |
-| Current published (4.6.7 on npm `latest`) | [docs/releases/4.6.7.md](docs/releases/4.6.7.md) · [CHANGELOG](CHANGELOG.md) |
+| Current tree (4.7.0 prepared) | [docs/releases/4.7.0.md](docs/releases/4.7.0.md) · [CHANGELOG](CHANGELOG.md) |
+| Current published (4.6.7 on npm `latest`) | [docs/releases/4.6.7.md](docs/releases/4.6.7.md) |
 | Prior published (4.6.6) | [docs/releases/4.6.6.md](docs/releases/4.6.6.md) |
 | Prior published (4.6.5) | [docs/releases/4.6.5.md](docs/releases/4.6.5.md) |
 | Prior published (4.6.3) | [docs/releases/4.6.3.md](docs/releases/4.6.3.md) |

package/SECURITY.md

@@ -18,7 +18,7 @@ Preferred path: use GitHub's private vulnerability reporting for this repository
 - reproduction steps
 - expected impact
 - whether the issue affects `arkgate-check` / `ark-check`, `arkgate-mcp` / `ark-mcp`,
-  generated agent gates, the GitHub Action, or the optional runtime kernel
+  generated agent gates, the GitHub Action, or the optional ArkRun kernel
 
 If private vulnerability reporting is unavailable, open a minimal public issue asking for
 a private security contact without including exploit details.

package/bin/ark-check-runtime.mjs

@@ -1471,6 +1471,7 @@ async function main() {
         score: fitness.score,
         mode: fitness.mode,
         improvementCompass: reportCompass,
+        arkRun: designDepth?.arkRun ?? null,
       }),
       leftoverDesignWork: designDepth?.designFitness?.designWeak === true,
     };
@@ -1493,7 +1494,17 @@ async function main() {
       adoption: adoptionForReport,
       designDepth,
       advisories: {
-        ...computeDoctorAdvisories(root, config, coverage, rules, files, ts, parseHealth),
+        ...computeDoctorAdvisories(
+          root,
+          config,
+          coverage,
+          rules,
+          files,
+          ts,
+          parseHealth,
+          undefined,
+          activeViolations
+        ),
         // Doctor parity: always emit improvement compass when doctor would (reportParity).
         ...(designDepth?.improvementCompass
           ? { improvementCompass: designDepth.improvementCompass }
@@ -1502,6 +1513,7 @@ async function main() {
         ...(designDepth?.deepModuleCoach
           ? { deepModuleCoach: designDepth.deepModuleCoach }
           : {}),
+        ...(designDepth?.arkRun ? { arkRun: designDepth.arkRun } : {}),
       },
     };
     const html = args.beginner

package/bin/ark-mcp-runtime.mjs

@@ -308,6 +308,42 @@ function hookEnforcement(root, host, operation, completePatch = false) {
   }).enforcementLadder;
 }
 
+function extraMergeTeethClassification(root, config) {
+  const files = collectGovernedFiles(root, config);
+  const layers = config.layers ?? [];
+  let classified = 0;
+  const populated = new Set();
+  for (const abs of files) {
+    const layer = layerForFile(root, abs, layers);
+    if (layer) {
+      classified += 1;
+      populated.add(layer);
+    }
+  }
+  return {
+    governedPercent: files.length > 0 ? Math.round((classified / files.length) * 100) : 0,
+    populatedLayerCount: populated.size,
+  };
+}
+
+function arkRunSnippetContext({ root, config, filePath, layer, relFile, classification }) {
+  const extra = config?.arkRun;
+  if (!extra) return { layer, filePath };
+  const relative =
+    relFile ||
+    (typeof filePath === 'string'
+      ? path.relative(root, path.resolve(root, filePath)).split(path.sep).join('/')
+      : undefined);
+  return {
+    layer,
+    filePath,
+    relFile: relative,
+    arkRun: extra,
+    layers: config.layers ?? [],
+    classification: classification ?? extraMergeTeethClassification(root, config),
+  };
+}
+
 function designDeltaViolations(delta) {
   return (delta?.changes ?? []).map((change) => ({
     ruleId: 'DESIGN_SMELL_REGRESSION',
@@ -565,7 +601,18 @@ function runHookPayload(payload, gate, config, args, ts, attemptContext, output
 
   const layer = inferLayer(filePath, config, args.root);
   const validateOnce = (src) =>
-    validateSnippetAnalysis({ gate, ts, source: src, context: { layer, filePath } });
+    validateSnippetAnalysis({
+      gate,
+      ts,
+      source: src,
+      context: arkRunSnippetContext({
+        root: args.root,
+        config,
+        filePath,
+        layer,
+        relFile: normalizedRel,
+      }),
+    });
   // W1: one validation pass (+ optional autoPatch). Original write still blocked when
   // invalid; hosts must apply autoPatch explicitly (never silent write).
   const result = ts
@@ -2136,7 +2183,17 @@ export async function runArkMcp({ hookInput } = {}) {
     const filePath = params.arguments.filePath;
     const layer = params.arguments.layer ?? inferLayer(filePath, config, args.root);
     const validateOnce = (src) =>
-      validateSnippetAnalysis({ gate, ts, source: src, context: { layer, filePath } });
+      validateSnippetAnalysis({
+        gate,
+        ts,
+        source: src,
+        context: arkRunSnippetContext({
+          root: args.root,
+          config,
+          filePath,
+          layer,
+        }),
+      });
     // W1: attempt mechanical-safe single-file autoPatch (import type), re-validate or discard.
     const result = validateWithAutoPatch({
       source,
@@ -2429,7 +2486,12 @@ export async function runArkMcp({ hookInput } = {}) {
         gate,
         ts,
         source: src,
-        context: { layer, filePath: placement.filePath },
+        context: arkRunSnippetContext({
+          root: args.root,
+          config,
+          filePath: placement.filePath,
+          layer,
+        }),
       });
     const result = composePrepareWrite({
       source,

package/bin/lib/adapter-contract.mjs

@@ -8,7 +8,7 @@
  * Pure CLI helper (bin/lib/adapter-contract.mjs). Zero Node I/O.
  */
 
-import { layerImportNextAction } from './remediation.mjs';
+import { deterministicNextAction } from './remediation.mjs';
 /** Versioned public result contract shared by every ArkGate enforcement adapter. */
 /**
  * 1.5 adds stable finding refs on every factory-emitted diagnostic (ACS06):
@@ -77,41 +77,22 @@ export function adapterDocsCodePath(ruleId) {
     return `${ADAPTER_DIAGNOSTIC_DOCS_RELATIVE_PATH}#${ruleId}`;
 }
 function nextActionForDiagnostic(ruleId, evidence, violation) {
-    if (ruleId === 'LAYER_IMPORT_VIOLATION') {
-        return layerImportNextAction({
-            ruleId,
-            typeOnly: evidence.typeOnly === true,
-            targetTypeOnlyExports: violation.targetTypeOnlyExports === true,
-            namedBindingsTypeOnly: violation.namedBindingsTypeOnly === true,
-            peerIsolation: violation.peerIsolation === true,
-            portProofEligible: violation.portProofEligible === true,
-            fromLayer: text(evidence.fromLayer) ?? undefined,
-            toLayer: text(evidence.toLayer) ?? undefined,
-            target: text(evidence.target) ?? text(violation.target) ?? undefined,
-        });
-    }
-    if (ruleId === 'FORBIDDEN_GLOBAL') {
-        return `Inject ${evidence.target ?? 'the capability'} through a port, test at the public interface, 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, test at the public interface, then preflight again.`;
-    }
-    if (ruleId === 'CIRCULAR_DEPENDENCY') {
-        return 'Extract the shared dependency into a third module, test at the public interface, then preflight again.';
-    }
-    if (ruleId === 'RAW_EVENT_PUBLISH')
-        return 'Publish through a registered intent creator, then run Ark again.';
-    if (ruleId === 'PUBLISH_MISSING_SOURCE')
-        return 'Add metadata.source to the publish call, then run Ark again.';
-    if (ruleId === 'ARKRULE_STRUCTURE' ||
-        ruleId === 'ARKRULE_INVARIANT' ||
-        ruleId === 'INVARIANT_UNCOVERED' ||
-        ruleId.startsWith('ARKRULE_')) {
-        const source = evidence.arkruleSource ?? 'arkrules/<Layer>.json';
-        const id = evidence.arkruleId ?? 'the ArkRule';
-        return `Fix the structure or invariant for ${id} (declared in ${source}), then preflight again. Do not demote the rule without a hash-bound policy acknowledgement.`;
-    }
-    return `Resolve ${ruleId} without weakening ark.config.json, then run Ark again.`;
+    return deterministicNextAction({
+        ruleId,
+        target: text(evidence.target) ?? text(violation.target) ?? undefined,
+        fromLayer: text(evidence.fromLayer) ?? undefined,
+        toLayer: text(evidence.toLayer) ?? undefined,
+        typeOnly: evidence.typeOnly === true,
+        targetTypeOnlyExports: evidence.targetTypeOnlyExports === true,
+        namedBindingsTypeOnly: evidence.namedBindingsTypeOnly === true,
+        portProofEligible: evidence.portProofEligible === true,
+        peerIsolation: evidence.peerIsolation === true,
+        sourcePureTypeModule: evidence.sourcePureTypeModule === true,
+        edgeKind: text(evidence.edgeKind) ?? undefined,
+        capability: text(evidence.capability) ?? text(violation.capability) ?? undefined,
+        arkruleId: text(evidence.arkruleId) ?? undefined,
+        arkruleSource: text(evidence.arkruleSource) ?? undefined,
+    });
 }
 export function toAdapterDiagnostic(violation, fallbackSeverity = 'error', 
 /**