arkgate 4.6.7 → 4.7.0

package/docs/README.md

@@ -53,11 +53,12 @@ These are **not** the day-to-day product path. They stay in the repo for evidenc
 | Area | Path |
 |------|------|
 | Release notes (by version) | [releases/](releases/) · npm [CHANGELOG.md](../CHANGELOG.md) (Unreleased + 4.6.x) · [pre-4.6 archive](archive/CHANGELOG-pre-4.6.md) |
-| Epic plans | [plans/](plans/) — maintainer seeds, not required to use the package. Live: [alive-in-six-months](plans/alive-in-six-months/README.md) (`AL01`–`AL04` done on `main`; `AL05` parked). |
+| Epic plans | [plans/](plans/) — maintainer seeds, not required to use the package. Live: [alive-in-six-months](plans/alive-in-six-months/README.md) (`AL01`–`AL04` done; `AL05` parked). [arkrun](plans/arkrun/README.md) (Phase RN; `RN01`–`RN15` done; `RN16` preparing **4.7.0**; ADRs [0020](adr/0020-arkrun-gated-extra-plane.md)–[0024](adr/0024-arkrun-transport-ports.md) accepted). |
 | Claims audit | [audit/claims-matrix.md](audit/claims-matrix.md) |
 | Field adoption kit (scaffolding, not closed) | [field/](field/) |
 | Runtime hardening (experimental) | [production-hardening.md](production-hardening.md) |
 
+Current tree: [releases/4.7.0.md](releases/4.7.0.md) (`arkgate@4.7.0` prepared).
 Current published: [releases/4.6.7.md](releases/4.6.7.md) (`arkgate@4.6.7` on npm `latest`).
 Prior: [releases/4.6.6.md](releases/4.6.6.md) · [4.6.5](releases/4.6.5.md) · [4.6.4](releases/4.6.4.md) · [4.6.3](releases/4.6.3.md) · [4.6.2](releases/4.6.2.md) · [4.6.1](releases/4.6.1.md) · [4.6.0](releases/4.6.0.md).
 Older notes: [releases/](releases/). Config: [configuration.md](configuration.md).

package/docs/agent-guide.md

@@ -688,11 +688,12 @@ cp node_modules/arkgate/templates/tests/ark-adoption-gaps.test.ts tests/ark-adop
 
 It checks real on-disk contract, MCP, skill, and report artifacts; it does not mock the gate.
 
-## Experimental runtime: contract discovery
+## ArkRun kernel: contract discovery
 
-The runtime kernel is currently **experimental** and is not required for static gate adoption or
-presented as production-ready. If you are evaluating it, prefer `createStrictArkKernel()`. It
-wires the registry, graph,
+The **ArkRun** kernel (`@arkgate/runtime`) is currently **experimental** and is not required for
+static gate adoption or presented as production-ready. If you are evaluating it, prefer
+`createStrictArkKernel()`. Each call creates an isolated instance — there is no process-wide
+singleton. It wires the registry, graph,
 policies, event bus, audit trail, event contracts, outbox, observability,
 projections, metadata, workflow engine, and 11-layer architecture profile:
 
@@ -709,12 +710,13 @@ const contract = ark.manifest().toJSON();
 // contract.observability, projections
 ```
 
-Use `@arkgate/runtime` only when evaluating the experimental kernel. The stable `arkgate` gate
-package contains no runtime implementation. The companion is not currently present in the npm
-registry and is not published by the root release workflow. Verify availability with
-`npm view @arkgate/runtime dist-tags --json`; until a separate experimental publication exists,
-evaluate it only from a source checkout after `npm run build:runtime` and install the local
-`packages/runtime` folder. Package surface policy: [package-surface.md](package-surface.md).
+Use `@arkgate/runtime` only when evaluating the experimental ArkRun kernel. The stable `arkgate`
+gate package contains no runtime implementation (the kernel is not in the `arkgate` tarball). The
+companion is not currently present in the npm registry and is not published by the root release
+workflow. Verify availability with `npm view @arkgate/runtime dist-tags --json`; until a separate
+experimental publication exists, evaluate it only from a source checkout after
+`npm run build:runtime` and install the local `packages/runtime` folder. Package surface policy:
+[package-surface.md](package-surface.md).
 
 Agents should read `contract` and `ark.observability.report()` before generating or modifying code.
 
@@ -968,7 +970,10 @@ export default [
 Rules: `ark/no-domain-infra-imports` (exact parity for on-disk, in-scope static relative
 imports/exports; resolved CLI/preflight is authoritative outside that envelope),
 `ark/no-forbidden-globals` (per-layer `forbiddenGlobals`),
-`ark/no-denied-capabilities` (per-layer capability deny sets), `ark/no-raw-event-publish`, and
+`ark/no-denied-capabilities` (per-layer capability deny sets),
+`ark/no-arkrun-kernel-in-domain` / `ark/no-arkrun-direct-new` /
+`ark/no-arkrun-transport-bypass` (ArkRun extra; silent when absent; import / `new`
+envelope only), `ark/no-raw-event-publish`, and
 `ark/require-publish-source`. See [ai-gates.md](ai-gates.md).
 
 ## Runtime Observability
@@ -1208,11 +1213,12 @@ advisory on every host because the agent must call the tool.
 
 Decision rationale: [ADR 0017 — MCP verdicts require explicit project identity](adr/0017-mcp-project-identity-binding.md).
 
-## Experimental runtime kernel workflow (not the default path)
+## ArkRun kernel workflow (not the default path)
 
-This section is for adopters who **opt into** the experimental `@arkgate/runtime` / kernel surfaces.
-It is **not** the Beautiful Path day-zero curriculum. Default remains: `ark start` → doctor → compact
-router (and `/ark-autopilot` only after the skill pack).
+This section is for adopters who **opt into** the experimental **ArkRun** kernel
+(`@arkgate/runtime`). Construct it with `createStrictArkKernel` (per instance; no process-wide
+singleton). It is **not** the Beautiful Path day-zero curriculum. Default remains: `ark start` →
+doctor → compact router (and `/ark-autopilot` only after the skill pack).
 
 1. **Read** manifest via `ark.manifest().toJSON()`
 2. **Generate** code using registered intents, profiles, metadata, projections, and workflow definitions

package/docs/ai-gates.md

@@ -687,6 +687,8 @@ export default [
   // no-domain-infra-imports  → config-driven layer edges (type-only + value)
   // no-forbidden-globals     → layer.forbiddenGlobals from ark.config.json
   // ark/no-denied-capabilities → layer.capabilities.deny / layer.pure
+  // ark/no-arkrun-kernel-in-domain + no-arkrun-direct-new + no-arkrun-transport-bypass
+  //   → arkRun extra (silent when absent; import / `new` envelope only)
   // no-raw-event-publish + require-publish-source → runtime event hygiene
 ];
 ```
@@ -714,6 +716,17 @@ Additional rule notes:
 - Value forbidden edges error (same pass/fail as `arkgate-check`). Type-only forbidden edges are **placement debt** (reported with `typeOnly`); merge blocking prefers value edges — align with doctor `typeEdgePolicy`.
 - `no-forbidden-globals` applies from the file layer’s `forbiddenGlobals`; the `globals` option is only a standalone fallback when no project config applies, never an override that weakens the project contract. Layers without either surface are not inventively restricted. `process` also owns exact value imports of `process` / `node:process`; type-only forms, subpaths, and `child_process` stay excluded. If the same layer also denies the `process` capability, this rule is the single `FORBIDDEN_GLOBAL` voice.
 - Without `ark.config.json`, `no-domain-infra-imports` emits no contract verdict.
+- **ArkRun (RN06):** when `arkRun` is present, `no-arkrun-kernel-in-domain`,
+  `no-arkrun-direct-new`, and `no-arkrun-transport-bypass` reuse the same
+  `ARKRUN_*` sensors as ark-check. Envelope is the current file: package
+  specifiers (kernel / closed broker list), `require` / export / dynamic-literal
+  of those specifiers, and `new` of constructors admitted from this file's
+  exported classes, `@arkgate/runtime` PascalCase imports, or on-disk
+  relative/alias import targets. Absence of the extra is silent. Composition-root
+  factory files skip `direct-new`. Domain-role layers skip `direct-new` and flag
+  kernel imports (including type-only). Type-only broker imports do not flag
+  transport-bypass. Missing-root and undeclared emit/handle/depend are **not**
+  in this adapter — use CLI / preflight / CI.
 
 Rule ids are `ark/<kebab-name>`. Individual rules are also on `ark.rules` if you wire them by hand.
 Prefer keeping editor + CI on the same `ark.config.json`. Use the rule-local `globals` list only

package/docs/configuration.md

@@ -10,7 +10,7 @@ The CLI, MCP server, and ESLint plugin all use the same parser, migration, defau
 ```json
 {
   "$schema": "https://unpkg.com/arkgate@2/schemas/ark.config.schema.json",
-  "schemaVersion": "1.1",
+  "schemaVersion": "1.2",
   "include": ["src"],
   "layers": [],
   "rules": []
@@ -19,9 +19,11 @@ The CLI, MCP server, and ESLint plugin all use the same parser, migration, defau
 
 `$schema` is for editor completion. `schemaVersion` controls ArkGate's runtime contract and is
 independent from the npm package version. Schema **`1.1`** is additive over `1.0` and adds the
-optional top-level **`arkRules`** map (ADR 0012). Absence of `arkRules` changes no inter-layer
-verdict. Per-layer structure/invariant files use sibling schema
-`arkgate/schema/arkrules` (`schemas/ark.arkrules.schema.json`).
+optional top-level **`arkRules`** map (ADR 0012). Schema **`1.2`** is additive over `1.1` and
+adds the optional top-level **`arkRun`** extra (ADR 0020). Absence of `arkRules` or `arkRun`
+changes no Layers / ArkRules verdict. Per-layer structure/invariant files use sibling schema
+`arkgate/schema/arkrules` (`schemas/ark.arkrules.schema.json`). ArkRun v1 stays **inline**
+(no sibling file).
 
 For offline editor completion, point `$schema` at the installed file instead:
 
@@ -39,7 +41,7 @@ The same schema is exported through the stable package subpaths `arkgate/schema`
 ## Compatibility and migration
 
 Configs without `schemaVersion` are the legacy shape shipped through ArkGate 1.x and early 2.x.
-The loader deterministically projects them through `unversioned → 1.0 → 1.1` in memory by adding
+The loader deterministically projects them through `unversioned → 1.0 → 1.1 → 1.2` in memory by adding
 contract metadata and the established defaults. It never rewrites the user's file during a check.
 Newly generated
 configs always contain the metadata, and unsupported future versions fail at
@@ -85,6 +87,15 @@ Top-level fields:
 - **`arkRules`** (optional, schema `1.1+`) — map of layer name → project-relative path to an
   ArkRules file (e.g. `"DomainModel": "arkrules/DomainModel.json"`). Keys must match a declared
   layer. Missing/invalid referenced files **fail closed**.
+- **`arkRun`** (optional, schema `1.2+`) — inline ArkRun extra (`mode`, `compositionRoots`,
+  `managedLayers`, `requireDeclarations`). Absence is silent. Unknown keys fail closed.
+  `managedLayers` must name existing `layers[].name` values. Empty `compositionRoots` in
+  `enforced` mode fails closed (`ARKRUN_MISSING_ROOT`); empty `managedLayers` in `enforced`
+  mode also fails closed (direct-new / undeclared / transport-bypass would otherwise no-op).
+  Compact starters do not enable this extra. Demotion (`enforced` → `advisory`) or deletion
+  is a policy-delta **weakening**. Enforced extra teeth share the CLI / MCP / hook /
+  preflight / CI verdict and arm only when the layer plane is classified (same ≥50%
+  governed and ≥1 populated-layer floor as ArkRules).
 
 Layer fields:
 
@@ -142,14 +153,16 @@ See [brownfield adoption](brownfield-adoption.md#nextjs-honesty-default-overlays
 | **Layers** | Inter-layer import graph | Always on |
 | **Structure sensors** | Intra-layer heuristics | Only `mode: "enforced"` |
 | **Invariants** | Catalog + coverage evidence (not a business runtime) | Only enforced + proven-uncovered |
+| **ArkRun** (opt-in extra) | Kernel usage + complete declarations | Only `arkRun.mode: "enforced"` when classified |
 
-Absence of `arkRules` adds **no** extra merge teeth. **Advisory** structure sensors and advisory
-invariants also add **no** merge teeth (FG-ARKRULES-ADVISORY-ONLY) — packing every starter
-`arkrules/*` file does not make merge fail structure alone. Enforced structure/invariants arm
+Absence of `arkRules` or `arkRun` adds **no** extra merge teeth. **Advisory** structure sensors, advisory
+invariants, and advisory ArkRun also add **no** merge teeth (FG-ARKRULES-ADVISORY-ONLY / ADR 0020) — packing every starter
+`arkrules/*` file does not make merge fail structure alone. Enforced structure/invariants/ArkRun arm
 `mergePlanes.extraMergeTeeth` only when the layer plane is honestly classified
-(governed ≥ 50% and ≥ 1 populated layer); empty classification never gets structure teeth
-(P1M-EXTRATEETH-EMPTY-GRAPH). Structure and invariants **never** merge into one architecture
-score. Doctor exposes `rulesUnderContract.mergePlanes` for which plane can fail.
+(governed ≥ 50% and ≥ 1 populated layer); empty classification never gets extra-plane teeth
+(P1M-EXTRATEETH-EMPTY-GRAPH). Extra planes **never** merge into one architecture
+score. Doctor exposes `rulesUnderContract.mergePlanes` (including `mergePlanes.arkRun`) for which plane can fail,
+and a dedicated `doctor.arkRun` section that is always `notAScore`.
 
 Safety fields:
 

package/docs/develop.md

@@ -155,9 +155,18 @@ names. Details: [configuration.md](configuration.md#team-parliament-law-vs-featu
 
 ---
 
-## Optional experimental runtime
-
-Gates need **no** runtime kernel. `@arkgate/runtime` is experimental, separate package, not the day-zero product. See [package-surface.md](package-surface.md) and [production-hardening.md](production-hardening.md).
+## Optional ArkRun extra and kernel
+
+Gates need **no** runtime kernel. Optional **`arkRun`** on `ark.config.json` (schema `1.2`)
+is a *gate* extra: kernel usage + complete declarations on the same write/CI plane as
+Layers and ArkRules. Absence is silent. Compact starters leave it off.
+
+The companion **ArkRun** kernel (`@arkgate/runtime`) is experimental, a separate package,
+and not the day-zero product. `createStrictArkKernel` is the factory (per instance; no
+process-wide singleton). The kernel is not bundled in the `arkgate` tarball. Built-in
+stores are in-memory **reference only** — not production durability; `K01` stays parked.
+See [configuration.md](configuration.md), [package-surface.md](package-surface.md), and
+[production-hardening.md](production-hardening.md).
 
 ---
 

package/docs/diagnostics.md

@@ -44,6 +44,13 @@ Link form for agents: `docs/diagnostics.md#RULE_ID` (exact-case HTML anchors bel
 | [`ARKRULE_INVARIANT`](#ARKRULE_INVARIANT) | arkrules | ArkRule invariant failed |
 | [`ARKRULE_SCOPE_EMPTY`](#ARKRULE_SCOPE_EMPTY) | arkrules | ArkRule appliesTo matched zero files |
 | [`INVARIANT_UNCOVERED`](#INVARIANT_UNCOVERED) | arkrules | Invariant without coverage evidence |
+| [`ARKRUN_MISSING_ROOT`](#ARKRUN_MISSING_ROOT) | arkrun | No kernel factory in composition roots |
+| [`ARKRUN_KERNEL_IN_DOMAIN`](#ARKRUN_KERNEL_IN_DOMAIN) | arkrun | Domain-role layer imports the kernel |
+| [`ARKRUN_DIRECT_NEW`](#ARKRUN_DIRECT_NEW) | arkrun | Managed type constructed with new |
+| [`ARKRUN_UNDECLARED_EMIT`](#ARKRUN_UNDECLARED_EMIT) | arkrun | Emit name not in raises/sends |
+| [`ARKRUN_UNDECLARED_HANDLE`](#ARKRUN_UNDECLARED_HANDLE) | arkrun | Handle name not in reactsTo |
+| [`ARKRUN_UNDECLARED_DEPEND`](#ARKRUN_UNDECLARED_DEPEND) | arkrun | Depend name not in uses |
+| [`ARKRUN_TRANSPORT_BYPASS`](#ARKRUN_TRANSPORT_BYPASS) | arkrun | Homemade broker or emitter import |
 | [`INVALID_CHANGE_PATH`](#INVALID_CHANGE_PATH) | preflight | Unsafe change path |
 | [`DUPLICATE_CHANGE_PATH`](#DUPLICATE_CHANGE_PATH) | preflight | Duplicate path in change set |
 | [`DELETE_TARGET_MISSING`](#DELETE_TARGET_MISSING) | preflight | Delete target missing |
@@ -271,6 +278,74 @@ Link form for agents: `docs/diagnostics.md#RULE_ID` (exact-case HTML anchors bel
 - **Why:** An ArkRules invariant is under contract but no covering test title or declared symbol evidence was found (or coverage is partial). Kind is `never-had-tests` (adopt residual) vs `tests-disappeared` (suite exists).
 - **Fix:** Add a test title or declared symbol covering the arkruleId, then preflight again. Treat never-had-tests as adopt residual; treat tests-disappeared as a regression. Missing test globs report partial — never fake green.
 
+## ArkRun (opt-in extra)
+
+Live adapters specialize `nextAction` with the call-site name or specifier when present
+(casual `enthusiastHint` + engineer `nextAction`). Catalog **Fix** is the stable no-target form.
+
+<a id="ARKRUN_MISSING_ROOT"></a>
+
+### `ARKRUN_MISSING_ROOT`
+
+**No kernel factory in composition roots**
+
+- **Why:** The ArkRun extra is on but no createArkKernel / createStrictArkKernel / createArkKernelFromConfig / createStrictArkKernelFromConfig factory was found in arkRun.compositionRoots, so agents can skip the kernel while the write gate stays green.
+- **Fix:** Import createStrictArkKernel from @arkgate/runtime (never a removed arkgate/runtime shim) and call it in a composition root listed in arkRun.compositionRoots, then preflight again. Never mechanical-safe — factory placement is a design decision.
+
+<a id="ARKRUN_KERNEL_IN_DOMAIN"></a>
+
+### `ARKRUN_KERNEL_IN_DOMAIN`
+
+**Domain-role layer imports the kernel**
+
+- **Why:** A Domain-role layer imports @arkgate/runtime or kernel types. Domain stays kernel-free; composition roots and adapters own the factory.
+- **Fix:** Move the kernel import out of the Domain-role layer into a composition root or adapter. Import from @arkgate/runtime, never a removed arkgate/runtime shim, then preflight again. Never mechanical-safe.
+
+<a id="ARKRUN_DIRECT_NEW"></a>
+
+### `ARKRUN_DIRECT_NEW`
+
+**Managed type constructed with new**
+
+- **Why:** A managed non-Domain file constructs an admitted type with new outside an ArkRun composition-root factory, skipping kernel resolve/registration.
+- **Fix:** Resolve the type from the kernel instead of constructing it with new, then preflight again. Never mechanical-safe — rewiring construction is a design decision.
+
+<a id="ARKRUN_UNDECLARED_EMIT"></a>
+
+### `ARKRUN_UNDECLARED_EMIT`
+
+**Emit name not in raises/sends**
+
+- **Why:** A publisher / publish / raise / send call-site literal is not listed in the file’s raises or sends declaration.
+- **Fix:** Add the existing call-site name to raises or sends on the managed component, then preflight again. Mechanical-safe only when that literal already exists and the edit is the declaration list; inventing a new emit stays judgment.
+
+<a id="ARKRUN_UNDECLARED_HANDLE"></a>
+
+### `ARKRUN_UNDECLARED_HANDLE`
+
+**Handle name not in reactsTo**
+
+- **Why:** A subscribe / registerHandler call-site literal is not listed in the file’s reactsTo declaration.
+- **Fix:** Add the existing call-site name to reactsTo on the managed component, then preflight again. Mechanical-safe only when that literal already exists and the edit is the declaration list; inventing a new handle stays judgment.
+
+<a id="ARKRUN_UNDECLARED_DEPEND"></a>
+
+### `ARKRUN_UNDECLARED_DEPEND`
+
+**Depend name not in uses**
+
+- **Why:** A resolve / resolveSingleton call-site literal is not listed in the file’s uses declaration.
+- **Fix:** Add the existing call-site name to uses on the managed component, then preflight again. Mechanical-safe only when that literal already exists and the edit is the declaration list; inventing a new depend stays judgment.
+
+<a id="ARKRUN_TRANSPORT_BYPASS"></a>
+
+### `ARKRUN_TRANSPORT_BYPASS`
+
+**Homemade broker or emitter import**
+
+- **Why:** A managed layer imports a closed broker/queue/emitter specifier (EventEmitter, queue clients, …) instead of the ArkRun kernel transport.
+- **Fix:** Send through the ArkRun kernel transport instead of importing that broker or emitter, then preflight again. Never mechanical-safe — homemade buses stay judgment.
+
 ## Atomic preflight and change sets
 
 <a id="INVALID_CHANGE_PATH"></a>

package/docs/enthusiast/README.md

@@ -27,10 +27,11 @@ aliases `ark` / `ark-check` still work).
 |-------|---------------|
 | **Layers** | Who may import whom (always on after start) |
 | **ArkRules** (optional) | Habits *inside* a layer — structure and named invariants as data |
+| **ArkRun** (optional extra) | Kernel usage + complete declarations (`arkRun` on schema `1.2`) |
 
-You can stay on layers only. When you add ArkRules, start **advisory** and promote only with
-coverage. Residual labels: **`[Layer]`** vs **`[ArkRules]`**. Details:
-[use.md](../use.md) · [configuration](../configuration.md#arkrules-intra-layer-opt-in).
+You can stay on layers only. When you add ArkRules or ArkRun, start **advisory** and promote only with
+coverage. Compact starters leave ArkRun off. Residual labels: **`[Layer]`** vs **`[ArkRules]`**. Details:
+[use.md](../use.md) · [configuration](../configuration.md).
 
 ## Start here
 

package/docs/package-surface.md

@@ -1,7 +1,7 @@
 # ArkGate package surface policy
 
 **Product wedge:** write gate · CI gate · co-pilot (plan / loop / skills).  
-**Not the wedge:** the optional in-process runtime kernel.
+**Not the wedge:** the optional in-process **ArkRun** kernel (`@arkgate/runtime`).
 
 **Public product site:** [arkgate.online](https://www.arkgate.online/) (promise + only flow).
 In-repo `docs/` remains the package/agent reference. Source: GitHub; distribution: npm.
@@ -21,6 +21,7 @@ hardening guide remains repository-hosted rather than duplicated in the gate tar
 | **Programmatic gate API** | `import { analyzeProject, loadContract, createAICodeGate, ... } from 'arkgate'` | The root export is the static gate/config/analysis contract listed below. It intentionally contains no runtime-kernel implementation. |
 | **Improvement compass (4.4; status honesty 4.5)** | `ark-check --doctor --json` → `doctor.improvementCompass`; human doctor section **Improvement compass (not a score)**; HTML report `data-advisory="improvementCompass"`. **`ark status --json` / MCP `ark_status`** project a thin `improvementCompass` residual map with explicit honesty **`mode`**: `full` \| `subset` \| `unavailable` (always `notAScore: true`). When `mode` is `full`, status residual lens **ids** are a **subset of** doctor residual for the same facts (report snapshot stores the thin slice after `--report`). Incomplete or missing session facts → `subset` / `unavailable` + `reasonCode` / `reason` — **never invent green residual**. Residual never flips `valid` / strict-merge / `goal.met`. When status mode ≠ full, run doctor for full 15-lens detail. | Additive schema `1.0`. Closed **15** lens ids (`soc`, `cohesion`, `coupling`, `srp`, `dip`, `ocp`, `encapsulation`, `modularity`, `scalability`, `resilience`, `security`, `maintainability`, `testability`, `domain`, `stack`) with status `ok` \| `residual` \| `not-instrumented` \| `out-of-scope`, evidence refs, optional `nextAction`, capped `topResidual`, always **`notAScore: true`**. Projection from existing smells / walls / cohesion / ArkRules / design-weak only — **never** a gate input. Out-of-scope locked for scalability, resilience, and app security (no residual invent from missing SAST/APM). Root API: `buildImprovementCompass` / `IMPROVEMENT_LENS_IDS`; status: `projectStatusImprovementCompass` / `STATUS_COMPASS_MODES`. |
 | **Deep-module coach (post-4.5 advisory)** | `ark-check --doctor --json` → `doctor.deepModuleCoach`; human doctor section **Deep-module coach (advisory — not a score)** always when doctor runs (empty candidates / hot-path `unavailable` are honesty, not omission); HTML `data-advisory="deepModuleCoach"`. | Additive schema `1.0`. Always **`notAScore: true`**. **`hotPaths`**: recent-churn heuristic from bounded git log; `available` + `status` `ok` \| `unavailable`; empty `paths` when history missing/incomplete — **never invent**. **`deepeningCandidates`**: cards projected only from existing design smells / physical cohesion / reshape pilot / pilotLoop / residual compass lenses — **empty when no evidence** (no fake candidates). Never flips `valid`, strict-merge, completeness green, or `goal.met`. Prefer deep modules / named seams / test-at-public-interface process language in skills. Domain pure + CLI gen mirror (`deepeningCoach.ts` / `bin/lib/deepening-coach.mjs`); **not** a root package export — consume via `doctor.deepModuleCoach` (or the gen mirror in Tooling). |
+| **ArkRun doctor / status / report (RN08)** | `ark-check --doctor --json` → `doctor.arkRun`; HTML `data-advisory="arkRun"`; `ark status --json` / MCP `ark_status` → `arkRun`; `rulesUnderContract.mergePlanes.arkRun` | Additive. Always **`notAScore: true`**. Residual is a finding-id count (status residual `null` = unknown, not green). Advisory and absence never arm extra merge teeth; enforced teeth follow the classified-layer floor. Never a score or LLM verdict. |
 | **Upgrade what’s new (4.5.6+)** | `ark upgrade --json` → `whatsNew` (+ human **Suggested improvements** block; also on preview). | Always **`notAScore: true`**, **`neverGateInput: true`**. Closed try/inspect list: deep-module coach, improvement compass, session/status honesty, two-axis done, self-service honesty, registry-aware upgrade, skill drift/refresh, multi-project MCP, Codex hard-write refresh/trust/restart/verify, stale MCP/global CLI recovery. Never invents residual or flips gates. |
 | **Field upgrade truth (4.5.6)** | `ark upgrade` registry-aware install; JSON `reasonCode` / `suggestedInstallCmd`; `skillDrift`; `--refresh-skills`; `postUpgradeChecks`; `hostSelection`. | No false-skip when registry ahead; offline honesty; customized skills preserved unless opt-in refresh; checks are advisory only. |
 | **MCP process package honesty (4.5.6; fail-closed in 4.6.4)** | Every MCP tool context → `processPackage` (`processPackageMismatch` / `processStale`, versions, `nextAction`). | Multi-checkout users: restart MCP after pin bump. From 4.6.4, stale process context is non-authoritative; `ark_identity` remains diagnostic and project tools return `PROCESS_PACKAGE_STALE` until restart/retarget. Prefer project-local CLI until identity matched and versions align. |
@@ -38,10 +39,10 @@ hardening guide remains repository-hosted rather than duplicated in the gate tar
 | **Capability walls, every adapter** | CLI scan, pure IR engine, atomic preflight, `ark-mcp --hook` / MCP gate (`capabilityWalls`), ESLint `ark/no-denied-capabilities` | The same opt-in deny set enforces across every surface: hook/MCP and CLI cover ambient + import evidence (symbol-aware); the pure engine, preflight, and ESLint cover the import dimension (documented envelope). Dual depth everywhere: plain port hint (`FIX_HINTS`/`suggestion`) + stable JSON (`ruleId`, `capability`, `fixClass: inject-port`, deterministic `nextAction`). |
 | **Hook-path budgets (maintainer)** | Repository-only evidence: `npm run bench:hook-path`; `eval/performance/hook-budgets.v1.json`; CI job "Hook-path end-to-end budgets" | Measures the COMPLETE pre-tool paths as fresh child processes (hook cold/warm, doctor cold) at 1k/10k. D5 method locked: ceilings are Linux-baseline p95 + fixed headroom, set once per cycle, never ratcheted; scenarios without a recorded baseline stay in RECORDING mode and cannot fail CI. |
 | **Governance weight** | `ark-check --doctor --json` → `doctor.contractHealth.governanceWeight` | Additive, **advisory only** — raw facts (`declaredLayers`, `populatedLayers`, `governedFiles`, `rules`, `deniedEdges`, `allowedEdges`, `filesPerLayer`, `rulesPerLayer`) plus a fixed comparative band `weight: heavy | typical | light | unknown` and its fixed `note`. Fixed deterministic thresholds: **heavy** = fewer than 25 governed files per declared layer AND (6+ layers OR 4+ well-formed rules per layer); **light** = at most 2 layers over 150+ governed files; **unknown** = no layers or no governed files; everything else is **typical** (banding uses raw ratios; the reported ratios are rounded for display). `notAScore: true` is explicit: never a composite score, ranking, or gate input; the heavy note asks to justify NEW layers/rules and never suggests deleting working ones. Human doctor prints a line only for `heavy`/`light`. |
-| **Report parity and snapshot evidence (4.2)** | `ark-check --report` → advisory sections (`data-advisory="contractHealth\|ambientState\|parseHealth"`, nested `governanceWeight`) + layer wall badges; `.ark/reports/*.json` | The report is a rendering of doctor truth. **Standing rule:** every doctor advisory ships with its report section — enforced by the `reportParity` guard, which enumerates the doctor's advisory keys and fails on any missing section. Snapshots add best-effort Git `HEAD`/branch/dirty provenance without a shell; unavailable Git is explicit. Evolution renders the Ark score delta only when both snapshots name the same ArkGate version, while retaining raw facts across versions. |
+| **Report parity and snapshot evidence (4.2)** | `ark-check --report` → advisory sections (`data-advisory="contractHealth\|ambientState\|parseHealth\|arkRun"`, nested `governanceWeight`) + layer wall badges; `.ark/reports/*.json` | The report is a rendering of doctor truth. **Standing rule:** every doctor advisory ships with its report section — enforced by the `reportParity` guard, which enumerates the doctor's advisory keys and fails on any missing section. Snapshots add best-effort Git `HEAD`/branch/dirty provenance without a shell; unavailable Git is explicit. Evolution renders the Ark score delta only when both snapshots name the same ArkGate version, while retaining raw facts across versions. Thin `arkRun` on `latest.json` is `notAScore` residual honesty for `ark status`. |
 | **MCP project identity (4.2)** | `ark_identity`; `arkgate/schema/project-identity` or `arkgate/schema/ark.project-identity.schema.json`; root API constants/helpers/types | Schema `1.0`. `projectId` hashes canonical root + config path and stays stable across contract edits/restarts; runtime id/start time are separate. Every project-bound tool result and error carries `projectIdentity`, `binding` (`matched` / `unverified` / `mismatch`), and `authoritative`. Canonical out-of-root config/file evidence fails before project data. |
 | **MCP tools and compatibility resource** | `arkgate-mcp`; `ark_manifest`; `ark_status`; `ark://manifest` | Tool names and primary argument shapes are stable within a major. Every tool accepts additive `project.expectedRoot` / optional `expectedProjectId`. The initial handshake requires the exact project root; a contained descendant is authoritative only together with the matching project id. Legacy tool calls remain callable but `unverified` and non-authoritative. `ark_manifest` is the authoritative contract surface after binding. **`ark_status`** returns the status manifest envelope (parity with `ark status --json`). Standard `resources/read` cannot portably carry the expectation, so `ark://manifest` remains compatibility-only and always unverified/non-authoritative. The server never retargets from input. |
-| **`ark.config.json`** | Layer globs, rules, include/exclude, forbiddenGlobals, intent prefixes, `peerIsolation`, `dynamicImportAllowlist`, `safety` thresholds; optional **`arkRules`** map (schema `1.1+`) | Versioned by `schemaVersion`; unknown fields fail closed and migrations preserve the previous supported major. Absence of `arkRules` is byte-for-byte silent on inter-layer verdicts. |
+| **`ark.config.json`** | Layer globs, rules, include/exclude, forbiddenGlobals, intent prefixes, `peerIsolation`, `dynamicImportAllowlist`, `safety` thresholds; optional **`arkRules`** map (schema `1.1+`); optional **`arkRun`** extra (schema `1.2+`) | Versioned by `schemaVersion`; unknown fields fail closed and migrations preserve the previous supported major. Absence of `arkRules` or `arkRun` is byte-for-byte silent on Layers / ArkRules verdicts. Enforced `arkRun` extra teeth share the CLI / MCP / hook / preflight / CI verdict and arm only when the layer plane is classified (same ArkRules floor). |
 | **ArkRules inventory / under-contract (4.0; layer context 4.2)** | `ark-check --rules-inventory [--json]`; doctor `rulesUnderContract`; MCP `ark_rules_inventory` | Additive. Honest counts (inventoried / under-contract / frozen) — **never a score**. When configured layer evidence exists it overrides filename role guesses: a Domain file named `handler` is not a controller candidate. Test/fixture/seed/migration/exclusion surfaces plus narrow development-identity, PostgreSQL OID, and technical I/O constants are silent. Without layer evidence, backward-compatible path/content heuristics remain. Structure/invariant diagnostics use adapter `1.4` provenance. |
 | **`arkgate/schema/project-identity`** or **`arkgate/schema/ark.project-identity.schema.json`** | MCP canonical project, contract, runtime, expectation, and binding envelope | Schema `1.0`. Initial `expectedRoot` must be the exact project root. A contained descendant can match only when `expectedProjectId` is also present and correct; id-only matching stays non-authoritative. Mismatch codes are `PROJECT_ROOT_MISMATCH`, `PROJECT_ID_MISMATCH`, and `INVALID_PROJECT_EXPECTATION`. |
 | **Package pin dual-truth (4.0)** | doctor JSON `packageVersionTruth`; upgrade JSON/human note when pin behind CLI | Additive, advisory. Surfaces after `upgrade --no-install` when managed CLI is ahead of package.json. |
@@ -57,15 +58,15 @@ hardening guide remains repository-hosted rather than duplicated in the gate tar
 | **Design delta** | `--strict-merge` / `--strict` (created paths when a Git base exists); `--fail-on-new-smells --base-ref <ref>` (full ratchet); hook/MCP; schema/types | Schema `1.0`: identities, touched paths, optional `enforcementScope`. Default merge blocks **created** `domain-logic-in-ui` files vs merge-base; missing base skips (does not exit 2). Full new+worsened on touched paths remains opt-in `--fail-on-new-smells` (missing base fails closed). Historical residual and worsened-in-existing-file stay green on `--strict-merge`. Global doctor smells stay advisory. |
 | **`arkgate/schema/analysis-result`** or **`arkgate/schema/ark.analysis-result.schema.json`** | Public CLI/MCP/hook diagnostic envelope (`schemaVersion`, `mode`, `valid`, `completeness`, `completenessReasons`, `diagnostics`, resolved identities) | Schema **`1.5`** adds optional stable finding refs on diagnostics: `findingRef` (`fnv1a-` + hex), `targetKey` (baseline-compatible freeze identity), `docsCodePath` (`docs/diagnostics.md#RULE_ID`). Factory-emitted diagnostics always include them; consumer-owned 1.0–1.4 values remain valid without them. `1.4` added optional `evidence.arkruleId` / `evidence.arkruleSource` for ArkRules; `1.3` distinguished `resolved-candidate-facts` from `lexical-compatibility`; partial/unavailable analysis is always non-green, and resolved complete/partial results require policy/resolver/facts/tree identities. `1.2` added completeness and remains accepted alongside consumer-owned 1.0/1.1 values. |
 | **Stable finding refs (4.3)** | Root API `adapterFindingTargetKey` / `adapterFindingRefFromTargetKey` / `toAdapterDiagnostic` / `createAdapterResult`; CLI/MCP/repair envelopes via analysis-result diagnostics | Multi-turn re-address without fuzzy message match. `targetKey` **is** the baseline (occurrence) key so freeze identity is never orphaned; `findingRef` is a compact FNV-1a of that key. Line/message drift does not change the ref. Multi-turn fixture: `tests/fixtures/finding-refs/multi-turn-stability.json`. |
-| **Diagnostic code catalog** | Root API `DIAGNOSTIC_CATALOG` / `getDiagnosticCatalogEntry` / `diagnosticDocsPath`; docs [diagnostics.md](diagnostics.md) (`#RULE_ID` anchors) | Closed vocabulary of public `ruleId`s with why/fix anchors. Cataloguing only — no new rule semantics. Remediation parity is test-guarded. Docs ship in the npm tarball. |
-| **Status manifest** | CLI `ark status [--json] [--vs <ref>]`; MCP `ark_status`; `arkgate/schema/status-manifest`; root API `buildStatusManifest` / `ARK_STATUS_MANIFEST_SCHEMA` / `projectStatusImprovementCompass` | Schema `1.0`. One session/project snapshot: identity binding, honest write-path activation (`hard`\|`advisory`\|`unavailable`), last-check summary, rules residual counts, primary next action, **`improvementCompass`** with honesty **`mode`** `full`\|`subset`\|`unavailable` (residual ids only; always `notAScore: true`; optional `reasonCode`/`reason`/`factsSource`/`contractHash`), and optional **`vsBase`** (pin / contract / baseline grow vs a git ref; advisory only). **Not a score.** Residual never changes gate verdicts. Never prompts (`CI=1` forces JSON). Optional `--expected-root` / `--expected-project-id` (MCP `project`) for matched vs stale identity. |
+| **Diagnostic code catalog** | Root API `DIAGNOSTIC_CATALOG` / `getDiagnosticCatalogEntry` / `diagnosticDocsPath`; docs [diagnostics.md](diagnostics.md) (`#RULE_ID` anchors) | Closed vocabulary of public `ruleId`s with why/fix anchors. Cataloguing only — no new rule semantics. Remediation parity is test-guarded. ArkRun `ARKRUN_*` codes (RN05) share dual-depth `nextAction` / `enthusiastHint`; declaration-list adds are mechanical-safe only when the call-site literal already exists. Docs ship in the npm tarball. |
+| **Status manifest** | CLI `ark status [--json] [--vs <ref>]`; MCP `ark_status`; `arkgate/schema/status-manifest`; root API `buildStatusManifest` / `ARK_STATUS_MANIFEST_SCHEMA` / `projectStatusImprovementCompass` | Schema `1.0`. One session/project snapshot: identity binding, honest write-path activation (`hard`\|`advisory`\|`unavailable`), last-check summary, rules residual counts, primary next action, **`improvementCompass`** with honesty **`mode`** `full`\|`subset`\|`unavailable` (residual ids only; always `notAScore: true`; optional `reasonCode`/`reason`/`factsSource`/`contractHash`), optional **`vsBase`** (pin / contract / baseline grow vs a git ref; advisory only), and additive **`arkRun`** (`notAScore`; `present` / `mode` / `extraMergeTeeth` / residual count — null residual is unknown, not green). **Not a score.** Residual never changes gate verdicts. Never prompts (`CI=1` forces JSON). Optional `--expected-root` / `--expected-project-id` (MCP `project`) for matched vs stale identity. |
 | **Agent contract projection** | CLI `ark agents-md [--write] [--check] [--stdout] [--json]`; install/upgrade AGENTS templates; root API `buildAgentProjectionBlock` / `mergeAgentProjectionDocument` | Schema `1.0` (projection markers). Version-stamped managed block (`arkgateVersion` + contract summary + diagnostic short list). **Non-authoritative** — not a gate input; enforcement is ark-check / hooks / CI. Content-identity merge preserves customized regions outside markers. Drift: `--check` vs package version. |
 | **Agent Skills packaging** | `templates/agent-skills/<name>/SKILL.md` (+ package README); root API `ARK_SKILL_NAMES` / `validateAgentSkillsPackage`; `npm run check:agent-skills` | Schema `1.0` (package contract). Same **13** skill names as flat templates; Agent Skills–compatible layout for `npx skills add`. No new skill names. Layout is generated 1:1 from `templates/skills/*.md`. |
 | **`arkgate/schema/arkrules`** or **`arkgate/schema/ark.arkrules.schema.json`** | Per-layer structure sensors + invariant catalog (ADR 0012) | Schema `1.0`. Opt-in via root `arkRules` map (`ark.config` schema `1.1`). |
-| **`arkgate/schema/resolved-candidate-facts`** or **`arkgate/schema/ark.resolved-candidate-facts.schema.json`** | Versioned parity-capable input for `analyzeResolvedProject` / `preflightResolvedChange` | Schema `1.0` is serializable and deterministic. Tooling owns filesystem/compiler resolution; Domain/Kernel validate and evaluate supplied facts without importing those effects. Facts name resolver/compiler inputs, governed files, dependency evidence, completeness reasons, and candidate tree/facts hashes. |
+| **`arkgate/schema/resolved-candidate-facts`** or **`arkgate/schema/ark.resolved-candidate-facts.schema.json`** | Versioned parity-capable input for `analyzeResolvedProject` / `preflightResolvedChange` | Schema `1.2` is additive: optional `classShapes` (1.1) plus ArkRun `arkRunKernelCalls` / `arkRunManagedNews` / `arkRunCompositionRootHits` / `arkRunDeclarations` (RN03–RN04). `1.0`/`1.1` payloads remain loadable. Tooling owns filesystem/compiler resolution; Domain/Kernel validate and evaluate supplied facts without importing those effects. Facts name resolver/compiler inputs, governed files, dependency evidence, completeness reasons, candidate tree/facts hashes, and (when present) ArkRun call-site and declaration evidence. Tier-1 sensors emit `ARKRUN_*` diagnostics from those facts: advisory never flips `valid`; enforced blocks. |
 | **Config JSON Schema** | `arkgate/schema` or `arkgate/schema/ark.config.schema.json` | Stable package resource subpaths for editor completion and contract tooling. |
 | **Agent skills** | `/ark-*` templates; install via `--install-agent-gates` (often `--skills-only` on top of compact) **or** Agent Skills ecosystem path | **Day zero** is the compact router from `ark start` / `start --apply` + doctor control plane — not the full skill pack. Skill *names* (frozen **13**) and the guided expert path (`/ark-autopilot` after pack install) are stable; internal skill prose may evolve. **4.0:** all skills except experimental `/ark-runtime` integrate **layers + ArkRules** and must label residual `[Layer]` vs `[ArkRules]`. **4.2:** repo catalogs are content-idempotent; the optional shared Codex home catalog is monotonic across 4.2.0+ installers. Pre-4.2 writers are outside that protocol and must be upgraded first. A durable pending-catalog journal preserves the floor across an interrupted install and is cleared only by its owning same/newer recovery. **4.3:** Agent Skills–compatible layout at `templates/agent-skills/<name>/SKILL.md` (1:1 with flat `templates/skills/*.md`); install via `npx skills add ./node_modules/arkgate/templates/agent-skills` (or the GitHub tree). Domain `ARK_SKILL_NAMES` + `validateAgentSkillsPackage`; drift `npm run check:agent-skills`. Skills never enforce. |
-| **ESLint subpath** | `arkgate/eslint` | Config-driven layer/import rules; loads consumer `ark.config.json`. |
+| **ESLint subpath** | `arkgate/eslint` | Config-driven layer/import/purity rules plus ArkRun import/`new` envelope (`ark/no-arkrun-kernel-in-domain`, `ark/no-arkrun-direct-new`, `ark/no-arkrun-transport-bypass`) when `arkRun` is on; loads consumer `ark.config.json`. Absence of the extra is silent. Missing-root and undeclared-* stay CLI/MCP. |
 | **GitHub Action** | `pedroknigge/arkgate` (see `action.yml`) | The `uses:` tag/SHA selects the checker source; `version` remains an optional exact npm compatibility override. |
 | **Package metadata** | `arkgate/package.json` | Stable resource subpath for tooling that needs the installed manifest. |
 
@@ -152,7 +153,7 @@ The type-only root exports are also semver-supported:
 
 Runtime-kernel factories, `CAPABILITY_IDS`, `collectCapabilityUses`, and Domain capability mapping
 helpers are deliberately absent from this root. Use `@arkgate/runtime` for the experimental
-runtime, and `analyzeProject(...).ir.capabilityUses` for public capability evidence.
+**ArkRun** kernel, and `analyzeProject(...).ir.capabilityUses` for public capability evidence.
 
 ---
 
@@ -163,15 +164,15 @@ product claims**. Static architecture enforcement does not depend on them.
 
 | Surface | Import path | Notes |
 |---------|-------------|--------|
-| **Runtime kernel** | **`@arkgate/runtime`** | Separate 0.x source package configured for the `experimental` tag. It is not currently present in the npm registry, and the root `publish-npm.yml` workflow does not publish it automatically. Event bus, intents, policies, sagas, event buffer, projections, and strict helpers. Built-in stores are **InMemory reference only**. |
-| **NestJS adapter** | `@arkgate/runtime/nestjs` | Experimental optional peer `@nestjs/common`. Root `arkgate/nestjs` and `arkgate/runtime` forwarders were **removed in AR04 / ArkGate 4** — import the companion package directly. |
+| **ArkRun kernel** | **`@arkgate/runtime`** | Public brand **ArkRun**. Separate 0.x companion; `createStrictArkKernel` is the factory (each call is an isolated instance; no process-wide `getKernel()` singleton). Not bundled in the `arkgate` tarball (ADR 0004 / 0021). Not currently in the npm registry; root `publish-npm.yml` does not publish it automatically. Event bus, intents, policies, sagas, event buffer, projections, and strict helpers. Managed components declare `uses` / `reactsTo` / `raises` / `sends` on `register()`; `getDependencyInformationPackage()` is a JSON snapshot of ids, lifetime, and declarations and never includes factories, live instances, or input DTOs (ADR 0023). `requestGraph()` slices that snapshot into **process** or **technical** graphs with optional `nodeIds`, `degreesOfSeparation`, and include/exclude query; `formatArkRunGraphMermaid()` (also `graph.mermaid`) is a helper string, never a score. `send()` is the transport port (local / localBlocking / broker); missing broker falls back to in-process local delivery, `ephemeral` defaults true, and **no cloud SDKs ship** in the package (ADR 0024). Opt-in `startInspector()` / `startArkRunInspector()` binds **`127.0.0.1` only**, refuses `NODE_ENV=production`, lazy-loads HTTP, and serves JSON snapshots, SSE, and `/graph` slices of the information package (no public / authless bind). Built-in stores are **InMemory reference only**. Branding ArkRun is not a production-durability claim. |
+| **NestJS adapter** | `@arkgate/runtime/nestjs` | Experimental optional peer `@nestjs/common` for the ArkRun kernel. Root `arkgate/nestjs` and `arkgate/runtime` forwarders were **removed in AR04 / ArkGate 4** — import the companion package directly. |
 
 ---
 
 ## Recommended imports
 
 ```ts
-// Preferred path when evaluating the experimental runtime kernel
+// Preferred ArkRun factory — each call is a new isolated instance (no getKernel() singleton)
 import { createStrictArkKernel, createStrictArkKernelFromConfig } from '@arkgate/runtime';
 
 // Nest adapter
@@ -204,7 +205,7 @@ production deployment would need to satisfy; it is not a readiness certification
 | Break CLI JSON field, MCP tool rename, or required `ark.config` field | **major** |
 | New optional config field, new CLI flag, additive JSON | **minor** |
 | Bugfix with no contract change | **patch** |
-| Additive experimental runtime API | `@arkgate/runtime` prerelease/minor |
+| Additive experimental ArkRun kernel API | `@arkgate/runtime` prerelease/minor |
 | Remove deprecated `arkgate/runtime` / `arkgate/nestjs` forwarding shims | **Done (AR04)** — use `@arkgate/runtime` / `@arkgate/runtime/nestjs` |
 
 ---
@@ -212,9 +213,11 @@ production deployment would need to satisfy; it is not a readiness certification
 ## Release notes (maintainers)
 
 Ship notes for a version live under [releases/](https://github.com/pedroknigge/arkgate/tree/main/docs/releases)
-(current published: [4.6.7.md](https://github.com/pedroknigge/arkgate/blob/main/docs/releases/4.6.7.md);
+(current tree: [4.7.0.md](https://github.com/pedroknigge/arkgate/blob/main/docs/releases/4.7.0.md);
+current published: [4.6.7.md](https://github.com/pedroknigge/arkgate/blob/main/docs/releases/4.6.7.md);
 prior published: [4.6.6.md](https://github.com/pedroknigge/arkgate/blob/main/docs/releases/4.6.6.md);
 prior published: [4.6.5.md](https://github.com/pedroknigge/arkgate/blob/main/docs/releases/4.6.5.md);
+prior published: [4.6.4.md](https://github.com/pedroknigge/arkgate/blob/main/docs/releases/4.6.4.md);
 prior published: [4.6.3.md](https://github.com/pedroknigge/arkgate/blob/main/docs/releases/4.6.3.md);
 prior published: [4.6.2.md](https://github.com/pedroknigge/arkgate/blob/main/docs/releases/4.6.2.md), [4.6.1.md](https://github.com/pedroknigge/arkgate/blob/main/docs/releases/4.6.1.md), [4.6.0.md](https://github.com/pedroknigge/arkgate/blob/main/docs/releases/4.6.0.md), [4.5.7.md](https://github.com/pedroknigge/arkgate/blob/main/docs/releases/4.5.7.md), [4.5.6.md](https://github.com/pedroknigge/arkgate/blob/main/docs/releases/4.5.6.md), [4.5.0.md](https://github.com/pedroknigge/arkgate/blob/main/docs/releases/4.5.0.md), [4.4.0.md](https://github.com/pedroknigge/arkgate/blob/main/docs/releases/4.4.0.md), [4.3.0.md](https://github.com/pedroknigge/arkgate/blob/main/docs/releases/4.3.0.md),
 [4.2.1.md](https://github.com/pedroknigge/arkgate/blob/main/docs/releases/4.2.1.md);

package/docs/product-voice.md

@@ -19,7 +19,8 @@ because the design space is small and honest.
 - **Gate side:** architecture config (`ark.config.json`) + pre-write block where the host
   supports it + required CI. Deterministic. Don’t show green if we could not verify.
   Two planes: **import rules** (who may import whom) always; **ArkRules** (structure rules
-  inside a layer) opt-in.
+  inside a layer) opt-in. Third extra: **ArkRun** (kernel usage + declarations) via companion
+  `@arkgate/runtime` — not a durability claim.
 - **Coach side:** where code belongs, who talks to whom, how; fix imports first, then leftover
   design work; one small refactor at a time; never silent auto-reshape; never weaken the config.
 - **Five-door autonomy:** invoking `/ark-adopt`, `/ark-place`, `/ark-autopilot`, `/ark-explore`,
@@ -63,8 +64,9 @@ Examples:
 
 ## Lexicon (prefer) — 4.6 common words
 
-**Brands (keep):** **ArkGate** (product / npm `arkgate`) and **ArkRules** (opt-in structure rules
-inside a layer). Gloss on first mention; do not rebrand.
+**Brands (keep):** **ArkGate** (product / npm `arkgate`), **ArkRules** (opt-in structure rules
+inside a layer), and **ArkRun** (opt-in kernel-usage extra + companion `@arkgate/runtime`). Gloss
+on first mention; do not rebrand. Branding ArkRun is not a durability claim.
 
 Human copy prefers the **common** column. JSON field names (`designWeak`, `ruleId`, MCP tools)
 stay stable unless a change explicitly adds an alias.
@@ -74,6 +76,7 @@ stay stable unless a change explicitly adds an alias.
 | **architecture config** | contract | `ark.config.json` layers, rules, include |
 | **import rules** / **allowed dependencies** | Layers plane / edges | Who may import whom; placement, purity, isolation |
 | **ArkRules** (opt-in; gloss: structure rules inside a layer) | ArkRules | Intra-layer sensors + domain invariant catalogs (`arkrules/*`) |
+| **ArkRun** (opt-in; gloss: kernel usage + complete declarations) | arkRun | Extra plane on the gate; companion kernel is `@arkgate/runtime`; factory `createStrictArkKernel` (per instance, no singleton). Never a score. |
 | **advisory ArkRules** | advisory ArkRules | Default sensor mode — **not** merge teeth; does not fail CI/merge alone |
 | **extra merge checks** | extraMergeTeeth | Only when enforced structure/invariant rules exist **and** classification is honest |
 | **label `[Layer]` vs `[ArkRules]`** | dual-plane residual | Never blur import-rule findings with ArkRules findings |

package/docs/threat-model.md

@@ -1,6 +1,6 @@
 # Threat model — ArkGate
 
-**Scope:** architecture write/CI gates, agent hooks/MCP, and the experimental optional runtime.
+**Scope:** architecture write/CI gates, agent hooks/MCP, and the experimental optional **ArkRun** kernel (`@arkgate/runtime`).
 **Not in scope:** full org identity platforms, browser XSS in consumer apps, or npm registry
 infrastructure beyond how this package is published.
 

package/docs/use.md

@@ -59,16 +59,17 @@ unfinished architecture; **Not finished** is reserved for real project/config de
 
 ArkGate is **not** a web framework, ORM, or app runtime. It is architecture enforcement + a coach for AI TypeScript.
 
-### Two planes (you choose)
+### Planes (you choose)
 
 | Plane | Plain English | Config | Enforces |
 |-------|---------------|--------|----------|
 | **Layers** | Who may talk to whom | `layers[]` + `rules[]` | Import direction, purity, forbidden globals, capabilities, peer isolation |
-| **ArkRules** (optional) | Habits *inside* a layer + named policies | `arkRules` + `arkrules/<Layer>.json` | Structure **heuristics** (module shape); invariant **catalog + coverage evidence** (not full business proof) |
+| **ArkRules** (optional extra) | Habits *inside* a layer + named policies | `arkRules` + `arkrules/<Layer>.json` | Structure **heuristics** (module shape); invariant **catalog + coverage evidence** (not full business proof) |
+| **ArkRun** (optional extra) | Kernel usage + complete declarations | `arkRun` on schema `1.2` | Only `mode: "enforced"` when the tree is classified. Absence is silent. Doctor `arkRun` is **not a score**. |
 
-Start always gives you **layers**. ArkRules templates may ship with start/init; they begin **advisory** until you promote them. Doctor / HTML show `rulesUnderContract` (catalog, **not a score**). No `arkRules` map is fine — only Layers run.
+Start always gives you **layers**. ArkRules templates may ship with start/init; they begin **advisory** until you promote them. Compact starters do **not** turn on ArkRun — add it only if the project uses `@arkgate/runtime`. Doctor / HTML show `rulesUnderContract` (catalog, **not a score**). No `arkRules` / `arkRun` map is fine — only Layers run. In-memory kernel stores are **not** production durability.
 
-**Do not confuse:** green Layers ≠ perfect design (Shape residual can remain). Covered invariants ≠ “the business always does the right thing” — they mean the named policy is declared and has symbol/test evidence.
+**Do not confuse:** green Layers ≠ perfect design (Shape residual can remain). Covered invariants ≠ “the business always does the right thing” — they mean the named policy is declared and has symbol/test evidence. ArkRun branding ≠ durable stores.
 
 ### New modules vs config edits
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "arkgate",
-  "version": "4.6.7",
+  "version": "4.7.0",
   "description": "One architecture config. One check. One coach.",
   "type": "module",
   "main": "./dist/index.cjs",

package/schemas/ark.config.schema.json

@@ -21,8 +21,8 @@
     },
     "schemaVersion": {
       "type": "string",
-      "const": "1.1",
-      "default": "1.1"
+      "const": "1.2",
+      "default": "1.2"
     },
     "name": {
       "type": "string",
@@ -633,6 +633,9 @@
       },
       "default": {}
     },
+    "arkRun": {
+      "$ref": "#/$defs/arkRun"
+    },
     "stewards": {
       "type": "array",
       "items": {
@@ -793,6 +796,42 @@
           "default": false
         }
       }
+    },
+    "arkRun": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "mode": {
+          "type": "string",
+          "enum": [
+            "advisory",
+            "enforced"
+          ],
+          "default": "advisory"
+        },
+        "compositionRoots": {
+          "type": "array",
+          "items": {
+            "type": "string",
+            "minLength": 1
+          },
+          "uniqueItems": true,
+          "default": []
+        },
+        "managedLayers": {
+          "type": "array",
+          "items": {
+            "type": "string",
+            "minLength": 1
+          },
+          "uniqueItems": true,
+          "default": []
+        },
+        "requireDeclarations": {
+          "type": "boolean",
+          "default": true
+        }
+      }
     }
   }
 }