arkgate 4.7.6 → 4.8.0

package/dist/types-DCSlrRnV.d.ts

@@ -0,0 +1,181 @@
+import { a as ArkConfigRule, f as ArkConfigLayer, A as ArkConfig } from './configTypes-BdCe_gvv.js';
+
+/**
+ * Policy types for the Ark kernel.
+ *
+ * Policies allow declaring architectural rules that can be checked at runtime.
+ * Supports both hard policies (must never be violated) and soft policies (warnings).
+ */
+type PolicySeverity = 'hard' | 'soft';
+type PolicyEnforcementMode = 'runtime' | 'static' | 'runtime-and-static' | 'advisory';
+/**
+ * Represents a single violation of a policy.
+ */
+interface PolicyViolation {
+    /** Name of the policy that was violated */
+    policyName: string;
+    /** Severity level of the policy */
+    severity: PolicySeverity;
+    /** Human-readable explanation of the violation */
+    message: string;
+    /** Optional additional structured details */
+    details?: unknown;
+}
+/**
+ * A Policy defines a rule that can be evaluated against a context.
+ *
+ * @template Context - The shape of data the policy evaluates (e.g. { registry, events })
+ */
+interface Policy<Context = unknown> {
+    /** Unique name of the policy (used in violations and reporting) */
+    readonly name: string;
+    /** Whether this is a hard rule (enforced strictly) or soft (advisory) */
+    readonly severity: PolicySeverity;
+    /** Optional tags for policy classification (e.g. 'layer', 'naming') */
+    readonly tags?: readonly string[];
+    readonly owner?: string;
+    readonly version?: string;
+    readonly rationale?: string;
+    readonly enforcementMode?: PolicyEnforcementMode;
+    readonly deprecated?: boolean | string;
+    readonly replacedBy?: string;
+    /**
+     * Evaluates the policy against the given context.
+     * Return true / [] for pass, false / single violation / array for failure.
+     */
+    check(context: Context): boolean | PolicyViolation | PolicyViolation[];
+}
+
+/**
+ * Core domain primitives for Ark.
+ * These types are the foundation for all governance concepts.
+ */
+/**
+ * Semantic intent names follow a convention:
+ * - Domain.* for domain events and entities
+ * - Application.* for use-cases / orchestration
+ * - Adapter.* for integration points
+ * - Workflow.* for sagas and processes
+ * - Job.* for background jobs and scheduling
+ * - Presentation.* for UI/API adapters
+ * - Reporting.* for read models and projections
+ * - Metadata.* for extensibility contracts
+ * - Security.* / Audit.* / Observability.* for cross-cutting kernel concerns
+ * - Kernel.* for Ark-owned governance signals
+ */
+type IntentName = `Domain.${string}` | `Application.${string}` | `Adapter.${string}` | `Workflow.${string}` | `Job.${string}` | `Presentation.${string}` | `Reporting.${string}` | `Metadata.${string}` | `Security.${string}` | `Audit.${string}` | `Observability.${string}` | `Kernel.${string}`;
+type CorrelationId = string;
+interface EventMetadata {
+    occurredAt: string;
+    source: string;
+    kernelInstanceId?: string;
+    eventVersion?: string;
+    schemaVersion?: string;
+    allowInterception?: boolean;
+    interceptions?: Array<{
+        interceptorId: string;
+        timestamp: string;
+    }>;
+    correlationId?: CorrelationId;
+    causationId?: string;
+    traceId?: string;
+    spanId?: string;
+    parentSpanId?: string;
+    [key: string]: unknown;
+}
+interface DomainEvent<Name extends IntentName = IntentName, Payload = unknown> {
+    intent: Name;
+    payload: Payload;
+    metadata: EventMetadata;
+}
+
+/**
+ * Intent-specific types for the Ark kernel.
+ *
+ * Intents provide semantic naming for every important concept in the system
+ * (domain events, application operations, adapters, workflows).
+ */
+
+/**
+ * An IntentCreator is a callable that creates a strongly-typed DomainEvent
+ * when invoked with a payload.
+ *
+ * It also carries the semantic `name`.
+ *
+ * @example
+ * const OrderPlaced = defineIntent<'Domain.Order.OrderPlaced', { orderId: string }>('Domain.Order.OrderPlaced');
+ * const event = OrderPlaced({ orderId: 'o-1' });
+ */
+interface IntentCreator<Name extends IntentName, Payload = unknown> {
+    /**
+     * Creates a DomainEvent for this intent.
+     */
+    (payload: Payload): DomainEvent<Name, Payload>;
+    /**
+     * The fully-qualified semantic name of the intent (e.g. "Domain.Order.OrderPlaced").
+     */
+    readonly name: Name;
+}
+/** Kind of relationship between two intents. */
+type IntentRelationshipKind = 'dependsOn' | 'produces';
+/**
+ * Relationship declarations between intents.
+ * Used for dependency analysis and graph generation.
+ */
+interface IntentRelationship {
+    from: string;
+    to: string;
+    kind: IntentRelationshipKind;
+}
+
+/**
+ * Architecture layer profiles.
+ *
+ * A profile turns semantic names such as `Domain.Order.Placed` into governed
+ * layer names and dependency rules.
+ */
+
+interface ArchitectureLayer {
+    name: string;
+    prefixes: string[];
+    /**
+     * Custom matcher for teams whose intent names don't follow prefix conventions.
+     * Checked before any prefix matching, in layer declaration order. A layer may
+     * use `match` alone (with `prefixes: []`), prefixes alone, or both.
+     */
+    match?: (name: string) => boolean;
+    description?: string;
+    order?: number;
+}
+type ArchitectureRule = ArkConfigRule;
+interface ArchitectureProfile {
+    name: string;
+    layers: ArchitectureLayer[];
+    rules: ArchitectureRule[];
+    resolveLayer(name: string): string | undefined;
+}
+interface CreateArchitectureProfileOptions {
+    name: string;
+    layers: ArchitectureLayer[];
+    rules?: ArchitectureRule[];
+}
+interface CreateArchitectureProfileFromArkConfigOptions {
+    /** Runtime profile name. Default: config.name or "ark.config.json". */
+    name?: string;
+}
+type ArchitectureLayerConfig = ArkConfigLayer;
+type ArkCheckConfig = Omit<ArkConfig, '$schema' | 'schemaVersion' | 'rules'> & {
+    $schema?: string;
+    schemaVersion?: ArkConfig['schemaVersion'];
+    rules?: ArchitectureRule[];
+};
+interface CreateElevenLayerArkConfigOptions {
+    /** Source root used in generated file patterns. Default: "src". */
+    rootDir?: string;
+    /** Include entries for ark-check. Default: [rootDir]. */
+    include?: string[];
+    /** Mark generated layers optional. Default: true. */
+    optionalLayers?: boolean;
+}
+
+export type { ArchitectureLayer as A, CreateArchitectureProfileFromArkConfigOptions as C, DomainEvent as D, EventMetadata as E, IntentName as I, PolicyViolation as P, ArchitectureLayerConfig as a, ArchitectureProfile as b, ArchitectureRule as c, ArkCheckConfig as d, CreateArchitectureProfileOptions as e, CreateElevenLayerArkConfigOptions as f, PolicySeverity as g, PolicyEnforcementMode as h, Policy as i, IntentCreator as j, IntentRelationship as k, CorrelationId as l, IntentRelationshipKind as m };

package/docs/README.md

@@ -57,13 +57,13 @@ 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; `AL05` parked). [arkrun](plans/arkrun/README.md) (Phase RN; `RN01`–`RN17` done; shipped **4.7.0** + companion **4.7.4**; ADRs [0020](adr/0020-arkrun-gated-extra-plane.md)–[0024](adr/0024-arkrun-transport-ports.md) accepted). [one-catalog-one-root](plans/one-catalog-one-root/README.md) (Phase HS; `HS01`–`HS05` done; shipped **4.7.1**). |
+| 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`–`RN17` done; shipped **4.7.0** + companion **4.7.4**; ADRs [0020](adr/0020-arkrun-gated-extra-plane.md)–[0024](adr/0024-arkrun-transport-ports.md) accepted). [one-catalog-one-root](plans/one-catalog-one-root/README.md) (Phase HS; `HS01`–`HS05` done; shipped **4.7.1**). [arkorder](plans/arkorder/README.md) (Phase OR; `OR01`–`OR07` done; shipped **4.8.0**; extra **inside** package `arkgate` as `arkgate/order`; ADRs [0027](adr/0027-arkorder-gated-extra-plane.md)–[0031](adr/0031-one-package-extras-deprecate-companion.md)). |
 | 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 published: [releases/4.7.5.md](releases/4.7.5.md) (`arkgate@4.7.5` on npm `latest`).
-Prior: [releases/4.7.4.md](releases/4.7.4.md) · [4.7.3](releases/4.7.3.md) · [4.7.2](releases/4.7.2.md) · [4.7.1](releases/4.7.1.md) · [4.7.0](releases/4.7.0.md) · [4.6.7](releases/4.6.7.md) · [4.6.6](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).
+Current published: [releases/4.8.0.md](releases/4.8.0.md) (`arkgate@4.8.0` on npm `latest`; does not close `K01`).
+Prior: [releases/4.7.6.md](releases/4.7.6.md) · [4.7.5](releases/4.7.5.md) · [4.7.4](releases/4.7.4.md) · [4.7.3](releases/4.7.3.md) · [4.7.2](releases/4.7.2.md) · [4.7.1](releases/4.7.1.md) · [4.7.0](releases/4.7.0.md) · [4.6.7](releases/4.6.7.md) · [4.6.6](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).
 
 ---
@@ -74,4 +74,4 @@ Older notes: [releases/](releases/). Config: [configuration.md](configuration.md
 2. **One primary flow** — `start` → doctor → optional guided work.
 3. **Honest hardness** — host write guarantees differ; a **required GitHub status context** running the merge CLI is the shared hard boundary.
 4. **History is not the product** — version archaeology lives under `releases/` and `plans/`, not the front door.
-5. **Common language** — first-contact copy uses ordinary software words (import rules, the write doesn’t land, required CI). ArkGate is import rules; ArkRules is policies; ArkRun is an experimental runtime. Voice: [product-voice.md](product-voice.md).
+5. **Common language** — first-contact copy uses ordinary software words (import rules, the write doesn’t land, required CI). ArkGate is import rules; ArkRules is policies; ArkRun is an experimental runtime; ArkOrder is an optional pattern extra in the same npm package. Voice: [product-voice.md](product-voice.md).

package/docs/agent-guide.md

@@ -631,7 +631,7 @@ npx arkgate-check --install-agent-gates --tools claude,cursor,codex,grok,antigra
 | Cursor | `.cursor/mcp.json` + `.cursor/rules/ark.mdc` | **Repo:** `.agents/skills/<name>/SKILL.md` (same catalog as Codex). Do not also copy into `.cursor/commands/` or `$CODEX_HOME/skills` — Cursor lists every path it scans. |
 | OpenAI Codex | `.codex/config.toml` (project primary, relative `--root .`; configured on disk is not runtime-active until restart + `ark_identity` match); optional legacy `$CODEX_HOME/config.toml` fallback uses absolute roots and scoped secondaries — see [ai-gates.md](ai-gates.md) | **Repo:** `.agents/skills/<name>/SKILL.md`; **home:** `$CODEX_HOME/skills/<name>/SKILL.md` (`--codex-home`) |
 | **Grok Build** | `.grok/hooks/ark-write-gate.json` + `.grok/config.toml` / `.mcp.json` | **Repo:** `.grok/skills/<name>/SKILL.md`; **home:** `$GROK_HOME/skills` (default `~/.grok/skills`, `--grok-home`) |
-| Google Antigravity | `.agents/hooks.json` (+ `GEMINI.md` for shared Gemini consumers) | `.agents/skills/<name>/SKILL.md` |
+| Google Antigravity | `.agents/hooks.json` + `.agents/mcp_config.json` (+ `GEMINI.md` for shared Gemini consumers) | `.agents/skills/<name>/SKILL.md` |
 | OpenCode | `opencode.json` MCP (`type: local`; advisory) | `.opencode/skills/<name>/SKILL.md` |
 
 This is a path reference, not a guarantee table. Full copy-paste setups:

package/docs/ai-gates.md

@@ -63,7 +63,8 @@ npx arkgate-check --install-agent-gates
 
 The command writes templates for `.mcp.json`, Claude hooks, Cursor MCP/rules,
 GitHub Actions, `AGENTS.md`, Codex `.codex/hooks.json` plus a TOML snippet under `docs/`, and (when
-selected) Grok Build project files under `.grok/`, Antigravity `.agents/hooks.json`, and OpenCode
+selected) Grok Build project files under `.grok/`, Antigravity `.agents/hooks.json` plus
+`.agents/mcp_config.json`, and OpenCode
 `opencode.json` MCP registration. It skips existing files unless
 you pass `--force`, so review and commit only the templates that match your project.
 
@@ -577,6 +578,11 @@ Antigravity loads project hooks from **`.agents/hooks.json`** (also
 `~/.gemini/config/hooks.json` for user-global). Official PreToolUse **`decision: "deny"`** is a
 hard block for matched tools.
 
+Workspace MCP is **`.agents/mcp_config.json`** (also `~/.gemini/config/mcp_config.json` /
+`~/.gemini/antigravity/mcp_config.json` for user-global). Antigravity does **not** load
+repo-root `.mcp.json`. Opening a repo does not write these files — run the installer, trust
+project hooks, then refresh MCP (`/mcp`) or restart.
+
 Install:
 
 ```bash
@@ -588,9 +594,10 @@ npx ark-check --install-agent-gates --tools agy
 | File | Role |
 |------|------|
 | `.agents/hooks.json` | Named hook `ark-write-gate` with PreToolUse on write tools |
+| `.agents/mcp_config.json` | Official workspace MCP (`mcpServers.ark` stdio) |
 | `GEMINI.md` | Instruction rule for Gemini CLI / legacy consumers sharing the tree |
 | `.agents/skills/*/SKILL.md` | Agent Skills catalog (shared path with Codex) |
-| `AGENTS.md` + `.mcp.json` + CI | Shared with other hosts |
+| `AGENTS.md` + `.mcp.json` + CI | Shared with other hosts (`.mcp.json` is not the Antigravity MCP path) |
 
 **Write tools covered:** `write_to_file`, `replace_file_content`, `multi_replace_file_content`.
 `ark-mcp --hook` accepts the Antigravity stdin shape (`toolCall.name` / `toolCall.args` with

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.2",
+  "schemaVersion": "1.3",
   "include": ["src"],
   "layers": [],
   "rules": []
@@ -20,10 +20,12 @@ 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). 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).
+adds the optional top-level **`arkRun`** extra (ADR 0020). Schema **`1.3`** is additive over
+`1.2` and adds the optional top-level **`arkOrder`** extra (ADR 0027). Absence of `arkRules`,
+`arkRun`, or `arkOrder` changes no Layers / ArkRules verdict. Per-layer structure/invariant
+files use sibling schema `arkgate/schema/arkrules` (`schemas/ark.arkrules.schema.json`).
+ArkRun and ArkOrder v1 stay **inline** (no sibling file). The plane factory is
+`arkgate/order` in the same npm package — not a second install.
 
 For offline editor completion, point `$schema` at the installed file instead:
 
@@ -41,7 +43,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 → 1.2` in memory by adding
+The loader deterministically projects them through `unversioned → 1.0 → 1.1 → 1.2 → 1.3` 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
@@ -96,6 +98,11 @@ Top-level fields:
   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).
+- **`arkOrder`** (optional, schema `1.3+`) — inline ArkOrder extra (`mode`, `planeRoots`,
+  `managedLayers`, `maxXiKeys`). Absence is silent. Unknown keys fail closed.
+  Import `createOrderPlane` from `arkgate/order` (same package). Empty `planeRoots` in
+  `enforced` mode fails closed (`ARKORDER_MISSING_PLANE`). Demotion or deletion is a
+  policy-delta **weakening**. Haken: few slow keys (ξ); field ingest never mints a pattern.
 
 Layer fields:
 

package/docs/develop.md

@@ -176,10 +176,11 @@ Gates need **no** runtime kernel. Optional **`arkRun`** on `ark.config.json` (sc
 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,
+The **ArkRun** kernel (`arkgate/runtime`) is experimental, an opt-in extra of package `arkgate`,
 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.
+process-wide singleton). The kernel ships as `arkgate/runtime` in the same tarball.
+`@arkgate/runtime` is deprecated. 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

@@ -51,6 +51,11 @@ Link form for agents: `docs/diagnostics.md#RULE_ID` (exact-case HTML anchors bel
 | [`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 |
+| [`ARKORDER_MISSING_PLANE`](#ARKORDER_MISSING_PLANE) | arkorder | No createOrderPlane in plane roots |
+| [`ARKORDER_KERNEL_IN_DOMAIN`](#ARKORDER_KERNEL_IN_DOMAIN) | arkorder | Domain-role layer imports the order plane |
+| [`ARKORDER_GENERIC_UPDATE`](#ARKORDER_GENERIC_UPDATE) | arkorder | Generic update of ξ |
+| [`ARKORDER_TOO_MANY_PARAMS`](#ARKORDER_TOO_MANY_PARAMS) | arkorder | Too many slow keys |
+| [`ARKORDER_INGEST_WRITES_XI`](#ARKORDER_INGEST_WRITES_XI) | arkorder | ingest assigned into ξ |
 | [`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 |
@@ -290,7 +295,7 @@ Live adapters specialize `nextAction` with the call-site name or specifier when
 **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.
+- **Fix:** Import createStrictArkKernel from arkgate/runtime (same npm package; @arkgate/runtime is deprecated) 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>
 
@@ -298,8 +303,8 @@ Live adapters specialize `nextAction` with the call-site name or specifier when
 
 **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.
+- **Why:** A Domain-role layer imports arkgate/runtime, @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 (same npm package; @arkgate/runtime is deprecated), then preflight again. Never mechanical-safe.
 
 <a id="ARKRUN_DIRECT_NEW"></a>
 
@@ -346,6 +351,55 @@ Live adapters specialize `nextAction` with the call-site name or specifier when
 - **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.
 
+## ArkOrder (opt-in extra)
+
+Haken slaving: few slow keys (ξ) determine derived fast state. Field ingest never mints a pattern.
+
+<a id="ARKORDER_MISSING_PLANE"></a>
+
+### `ARKORDER_MISSING_PLANE`
+
+**No createOrderPlane in plane roots**
+
+- **Why:** The ArkOrder extra is on but no createOrderPlane factory was found in arkOrder.planeRoots, so agents can skip the pattern plane while the write gate stays green.
+- **Fix:** Import createOrderPlane from arkgate/order and call it in a plane root listed in arkOrder.planeRoots, then preflight again. Never mechanical-safe — factory placement is a design decision.
+
+<a id="ARKORDER_KERNEL_IN_DOMAIN"></a>
+
+### `ARKORDER_KERNEL_IN_DOMAIN`
+
+**Domain-role layer imports the order plane**
+
+- **Why:** A Domain-role layer imports arkgate/order. Domain stays plane-free; planeRoots own the factory.
+- **Fix:** Move the arkgate/order import out of the Domain-role layer into a plane root or adapter, then preflight again. Never mechanical-safe.
+
+<a id="ARKORDER_GENERIC_UPDATE"></a>
+
+### `ARKORDER_GENERIC_UPDATE`
+
+**Generic update of ξ**
+
+- **Why:** A call to update/patch/set on the order plane rewrites the slow pattern. Haken slaving forbids generic ξ mutation.
+- **Fix:** Use release() to freeze ξ or proposeRelease() for a pattern change with blast radius, then preflight again. Never mechanical-safe.
+
+<a id="ARKORDER_TOO_MANY_PARAMS"></a>
+
+### `ARKORDER_TOO_MANY_PARAMS`
+
+**Too many slow keys**
+
+- **Why:** ξ has more keys than arkOrder.maxXiKeys. Haken requires a few slow modes, not a dump of microstate.
+- **Fix:** Cut ξ to the slow keys that actually slave the rest, then preflight again. Never mechanical-safe.
+
+<a id="ARKORDER_INGEST_WRITES_XI"></a>
+
+### `ARKORDER_INGEST_WRITES_XI`
+
+**ingest assigned into ξ**
+
+- **Why:** An ingest() result is written into a Release or ξ store. ingest may absorb or escalate; it never mints a pattern.
+- **Fix:** Keep ingest results as absorb/escalate only. Change ξ with proposeRelease + release. Never mechanical-safe.
+
 ## Atomic preflight and change sets
 
 <a id="INVALID_CHANGE_PATH"></a>

package/docs/package-surface.md

@@ -3,7 +3,13 @@
 **Write. Check. Ship.**
 **When the agent writes a bad import, the write doesn’t land. The same check fails the pull request.**
 That is the product wedge (host hook + required CI). Skills name the next step after that.
-**Not the wedge:** the optional in-process **ArkRun** runtime (`@arkgate/runtime`).
+**Not the wedge:** the optional in-process **ArkRun** runtime (`arkgate/runtime`).
+
+The check that must agree everywhere is small ([ADR 0026](adr/0026-gate-waist-facts-in-verdict-out.md)):
+`ark.config.json` + resolved-candidate-facts → one analysis-result (`valid`).
+CLI, MCP, hook, ESLint, and CI are adapters around that waist. Doctor advisory
+sections project those facts; they are not a second check and never flip `valid`.
+Skills name the next step after the check.
 
 **Public product site:** [arkgate.online](https://www.arkgate.online/) (promise + only flow).
 In-repo `docs/` remains the package/agent reference. Source: GitHub; distribution: npm.
@@ -44,7 +50,7 @@ hardening guide remains repository-hosted rather than duplicated in the gate tar
 | **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+`); 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). |
+| **`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+`); optional **`arkOrder`** extra (schema `1.3+`) | Versioned by `schemaVersion`; unknown fields fail closed and migrations preserve the previous supported major. Absence of `arkRules`, `arkRun`, or `arkOrder` is byte-for-byte silent on Layers / ArkRules verdicts. Enforced 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. |
@@ -65,10 +71,10 @@ hardening guide remains repository-hosted rather than duplicated in the gate tar
 | **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.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. |
+| **`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) and ArkOrder `arkOrderPlaneCalls` / `arkOrderGenericUpdates` / `arkOrderRootHits` (OR05). `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/ArkOrder call-site evidence. Tier-1 sensors emit `ARKRUN_*` / `ARKORDER_*` diagnostics from those facts: advisory never flips `valid`; enforced blocks. Extra absence is silent. |
 | **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 — 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/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. |
+| **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, and ArkOrder envelope (`ark/no-arkorder-kernel-in-domain`, `ark/no-arkorder-generic-update`) when `arkOrder` is on; loads consumer `ark.config.json`. Absence of an extra is silent. Missing-root / missing-plane 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. |
 
@@ -166,25 +172,22 @@ product claims**. Static architecture enforcement does not depend on them.
 
 | Surface | Import path | Notes |
 |---------|-------------|--------|
-| **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). Published under the `experimental` dist-tag as `@arkgate/runtime@0.1.0-experimental.0`. Install `@arkgate/runtime@experimental`. Verify with `npm view @arkgate/runtime dist-tags --json`. Root `publish-npm.yml` publishes it when that companion version is unpublished; companion-only: `publish-runtime.yml`. The first npm copy also received a `latest` dist-tag pointing at the same 0.x (npm default); that is not a production-durability claim. 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. |
+| **ArkRun kernel** | **`arkgate/runtime`** | Public brand **ArkRun**. Same npm package `arkgate` (ADR 0031). Factory `createStrictArkKernel` (each call is an isolated instance; no process-wide `getKernel()` singleton). Root export does **not** include the factory. Optional extra `arkRun` on schema `1.2+`. 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. **`@arkgate/runtime` is deprecated** leftover 0.x (`experimental` dist-tag). |
+| **NestJS adapter** | **`arkgate/nestjs`** | Experimental optional peer `@nestjs/common` for the ArkRun kernel. Same npm package. `@arkgate/runtime/nestjs` is deprecated. |
+| **ArkOrder plane** | **`arkgate/order`** | Public brand **ArkOrder**. Same npm package `arkgate` (ADR 0030) — not `@arkgate/order`. Factory `createOrderPlane`. Four verbs: `release` / `project` / `ingest` / `proposeRelease`. No `update`. Haken: few slow keys; ingest never mints a pattern; empty blast fails closed. Root `arkgate` export does **not** include the factory. Optional extra `arkOrder` on schema `1.3`. In-memory; not durable. Does not replace ArkRun. |
 
 ---
 
 ## Recommended imports
 
 ```ts
-// Preferred ArkRun factory — each call is a new isolated instance (no getKernel() singleton)
-import { createStrictArkKernel, createStrictArkKernelFromConfig } from '@arkgate/runtime';
-
-// Nest adapter
-import { ArkModule, InjectArk } from '@arkgate/runtime/nestjs';
+import { createAICodeGate } from 'arkgate';
+import { createStrictArkKernel, createStrictArkKernelFromConfig } from 'arkgate/runtime';
+import { ArkModule, InjectArk } from 'arkgate/nestjs';
+import { createOrderPlane } from 'arkgate/order';
 ```
 
-These imports describe the intended package boundary. Install with
-`npm install @arkgate/runtime@experimental` and verify
-`npm view @arkgate/runtime dist-tags --json`. Root `arkgate/runtime` / `arkgate/nestjs`
-forwarders were **removed in 4.0.0** (AR04).
+One install: `npm install arkgate`. `@arkgate/runtime` is deprecated.
 
 See [production-hardening.md](https://github.com/pedroknigge/arkgate/blob/main/docs/production-hardening.md) for requirements an eventual
 production deployment would need to satisfy; it is not a readiness certification.
@@ -215,7 +218,8 @@ 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.7.6.md](https://github.com/pedroknigge/arkgate/blob/main/docs/releases/4.7.6.md);
+(current published: [4.8.0.md](https://github.com/pedroknigge/arkgate/blob/main/docs/releases/4.8.0.md);
+prior published: [4.7.6.md](https://github.com/pedroknigge/arkgate/blob/main/docs/releases/4.7.6.md);
 prior published: [4.7.5.md](https://github.com/pedroknigge/arkgate/blob/main/docs/releases/4.7.5.md);
 prior published: [4.7.3.md](https://github.com/pedroknigge/arkgate/blob/main/docs/releases/4.7.3.md);
 prior published: [4.7.2.md](https://github.com/pedroknigge/arkgate/blob/main/docs/releases/4.7.2.md);

package/docs/product-voice.md

@@ -18,7 +18,7 @@ The same check fails the pull request.
 
 **ArkRules** is optional policies inside a layer.
 
-**ArkRun** is an optional runtime (`@arkgate/runtime`). Experimental. In-memory.
+**ArkRun** is an optional runtime (`arkgate/runtime`). Experimental. In-memory.
 Not Postgres.
 
 ```text
@@ -96,6 +96,7 @@ These are product law, not vibe:
 
 - **Write. Check. Ship.** ArkGate is the wedge. ArkRules and ArkRun never determine the `arkgate` package shape.
 - The check is deterministic. No LLM pass/fail. Skills and `AGENTS.md` never replace the check.
+- Doctor and status advisory surfaces project existing facts. They are not a second check and never flip the deny.
 - No numeric architecture / trust / depth score. Lights and counts, never Excellent/Good.
 - Green imports ≠ elegant design. Leftover design work is **needs a refactor**, not “done”.
 - No silent auto-reshape. Invoke of a command is the approval.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "arkgate",
-  "version": "4.7.6",
+  "version": "4.8.0",
   "description": "When the agent writes a bad import, the write doesn’t land. The same check fails the pull request.",
   "type": "module",
   "main": "./dist/index.cjs",
@@ -17,6 +17,21 @@
       "import": "./dist/eslint/index.js",
       "require": "./dist/eslint/index.cjs"
     },
+    "./order": {
+      "types": "./dist/order/index.d.ts",
+      "import": "./dist/order/index.js",
+      "require": "./dist/order/index.cjs"
+    },
+    "./runtime": {
+      "types": "./dist/runtime/index.d.ts",
+      "import": "./dist/runtime/index.js",
+      "require": "./dist/runtime/index.cjs"
+    },
+    "./nestjs": {
+      "types": "./dist/nestjs/index.d.ts",
+      "import": "./dist/nestjs/index.js",
+      "require": "./dist/nestjs/index.cjs"
+    },
     "./schema": "./schemas/ark.config.schema.json",
     "./schema/ark.config.schema.json": "./schemas/ark.config.schema.json",
     "./schema/analysis-result": "./schemas/ark.analysis-result.schema.json",
@@ -155,11 +170,15 @@
     "typescript-ark-host": "npm:typescript@6.0.3"
   },
   "peerDependencies": {
-    "typescript": ">=5.0.0 <8"
+    "typescript": ">=5.0.0 <8",
+    "@nestjs/common": ">=9"
   },
   "peerDependenciesMeta": {
     "typescript": {
       "optional": true
+    },
+    "@nestjs/common": {
+      "optional": true
     }
   },
   "overrides": {