ark-runtime

# /ark-runtime — Evaluate and wire ArkRun (experimental opt-in)

The ArkRun kernel (`arkgate/runtime`) is currently **experimental**. It is **not** required
for ArkGate enforcement and is **not** production durability. Use this skill when the user wants
to evaluate or wire the kernel. **This skill never enforces** — the write / CI / ESLint plane
does when the `arkRun` extra is on. Do **not** invent `/ark-run`. `@arkgate/runtime` is deprecated.

**When:** evaluate a hand-rolled bus / outbox / saga / projection / policy / Nest adapter against
the kernel, or wire an extra that is already on (kernel root, declarations, transport).
**Not when:** session 0 / extra not chosen (`/ark-adopt`); one new file (`/ark-place`); skip-violation
grind (`/ark-autopilot` / leftover `/ark-fix`).

## Extra vs kernel (mandatory)

| Piece | What it is | What it is not |
|-------|------------|----------------|
| **ArkRun extra** (`arkRun` on `ark.config.json`, schema `1.2+`) | Gate contract: kernel usage + complete declarations | A score; Layers / ArkRules replacement; merge teeth while `advisory` |
| **Kernel** `arkgate/runtime` | Kernel you construct with `createStrictArkKernel` (one instance per call) | A process-wide `getKernel()`; shipped cloud broker SDKs; production durability |

Absence of the extra is **silent** — Layers and ArkRules verdicts stay identical. Doctor / status
`arkRun` is always `notAScore`. Never invent 0–10 scores or pass/fail from this skill.

## Improvement compass note

This skill is **experimental runtime** only. Do **not** treat runtime adoption as residual on the
resilience lens unless the user explicitly opts into the experimental kernel. Prefer doctor compass
for static architecture residual; hand static residual to `/ark-explore` / `/ark-autopilot`.
Doctor `arkRun` residual is a finding-id count (`ARKRUN_*`), never a compass score.

## Dual engine (mandatory)

| Engine | Role |
|--------|------|
| **Deterministic** | CLI / MCP / contract sensors — exit codes, plan kinds, coverage numbers, install status |
| **Exploratory** | You open **this** repo's real files and product surface before concluding |

The CLI is a **sensor**, never the whole job. Claiming done without the exploratory bar for this skill is **incomplete**.

## MCP workspace binding (mandatory)

Before any `ark_*` MCP tool, call `ark_identity` with `project.expectedRoot` set to the exact
workspace root. Continue only when `binding.status === "matched"` and `authoritative === true`;
retain `projectIdentity.projectId`, then pass both `expectedRoot` and `expectedProjectId` under
`project` on every later MCP call. If identity is missing, mismatched, unverified, or the root is
uncertain, do not consume MCP analysis: use the workspace-local CLI and report that MCP
restart/retargeting is required. `ark://manifest` never satisfies this preflight.

## Out of scope for ArkRules and ArkOrder

This skill is **runtime-kernel only**. Do not mix ArkRules structure/invariants here; do **not** turn this skill into an ArkOrder skill. Hand off first extras to `/ark-adopt`, new files to `/ark-place`, skip clusters to `/ark-autopilot`. Label kernel-usage residual **`[ArkRun]`** so it never blurs with **`[Layer]`**, **`[ArkRules]`**, or **`[ArkOrder]`**.

## Subagent fan-out (optional, host-dependent)

If the host supports **parallel subagents** and the task splits cleanly (e.g. multiple
dirs to sample), fan out read-only scouts; otherwise **fall back to sequential**.
Parent merges and still emits the **### Completion** contract. Never parallel-write
the same files or weaken the gate.

## Steps

1. **Inventory** — grep the codebase for hand-rolled equivalents:
   - event bus / emitter used for domain events (`EventEmitter`, homemade
     pub/sub, ad-hoc handler registries)
   - outbox tables or "save event + publish later" code
   - audit/history logs written manually
   - saga/workflow orchestration (multi-step processes with compensation)
   - read-model/projection builders
   - policy/authorization checks scattered across use cases
   Also check whether `@nestjs/common` is present → the `arkgate/nestjs`
   adapters apply.
2. **Read the extra** — open `ark.config.json`. If `arkRun` is absent and the user wants the extra,
   **STOP — do not continue this skill as complete.** Handoff **`/ark-adopt`** to write **advisory**
   `arkRun` (schema `1.2+`; **`kernelRoots` preferred**, `compositionRoots` alias, `managedLayers`,
   `requireDeclarations`). Do not invent the extra here. If the extra is present, note `mode`,
   `kernelRoots` (or alias `compositionRoots`), managed layers, and `requireDeclarations`; doctor
   `arkRun` is `notAScore`.
3. **Pick ONE target** — the smallest, most self-contained candidate (fewest
   call sites). Migrating everything at once is how adoptions die. List the
   rest as follow-ups in the report. New files after the extra is on go through **`/ark-place`**.
4. **Resolve availability** — `npm install arkgate` already ships `arkgate/runtime`.
   Import from `arkgate/runtime` (or `arkgate/nestjs`). `@arkgate/runtime` is deprecated.
5. **Wire through the kernel** — read the
   [experimental opt-in surfaces](https://github.com/pedroknigge/arkgate/blob/main/docs/package-surface.md#experimental-opt-in-surfaces)
   (primary kernel guide; import `arkgate/runtime` from the same `arkgate` tarball). Optional
   durability non-claim: [production-hardening.md](https://github.com/pedroknigge/arkgate/blob/main/docs/production-hardening.md).
   Do **not** treat `packages/runtime/README.md` (deprecated companion leftover) as the kernel guide.
   - Call `createStrictArkKernel` (or an admission sibling: `createArkKernel`, `*FromConfig`) **only**
     inside `arkRun.kernelRoots` (`compositionRoots` is a legacy alias — still valid). Each call is a new instance — no process-wide singleton.
   - Keep Domain-role layers kernel-free (`ARKRUN_KERNEL_IN_DOMAIN`).
   - Resolve managed types from the kernel; do not construct admitted types