arkgate 2.7.0 → 2.8.1

package/dist/{types-CP3KkwZt.d.cts → types-CSJhEOk2.d.cts}

@@ -412,17 +412,29 @@ interface AuditQuery {
     until?: string;
     limit?: number;
 }
+/**
+ * Pluggable persistence for audit records.
+ *
+ * **Durability stance (R9):** Default is `InMemoryAuditStore` — reference only, not
+ * production durability (lost on restart). Implement this interface for durable audit.
+ * See `docs/production-hardening.md`.
+ */
 interface AuditStore {
     append(record: AuditRecord): MaybePromise<void>;
     query(query?: AuditQuery): MaybePromise<AuditRecord[]>;
     clear(): MaybePromise<void>;
 }
+/**
+ * High-level audit API used by the event bus / kernel.
+ * Durability is that of the injected `AuditStore` (default in-memory).
+ */
 interface AuditTrail {
     record(input: AuditRecordInput): Promise<AuditRecord>;
     query(query?: AuditQuery): Promise<AuditRecord[]>;
     clear(): Promise<void>;
 }
 interface CreateAuditTrailOptions {
+    /** Durable store when provided; otherwise `InMemoryAuditStore` (not production durability). */
     store?: AuditStore;
     maxRecords?: number;
 }
@@ -512,6 +524,14 @@ interface OutboxRecord {
     updatedAt: string;
     error?: string;
 }
+/**
+ * Pluggable outbox for publish handoff.
+ *
+ * **Durability stance (R9):** ArkGate ships only a reference in-process store
+ * (`InMemoryOutboxStore`) for tests, demos, and single-process development — it does
+ * not survive process restarts and is **not production durability**. Inject your own
+ * `OutboxStore` (DB, queue, etc.) for real systems. See `docs/production-hardening.md`.
+ */
 interface OutboxStore {
     enqueue(event: DomainEvent): Promise<OutboxRecord>;
     markDispatched(id: string): Promise<void>;
@@ -807,6 +827,13 @@ interface ProjectionCheckpoint {
     lastCorrelationId?: string;
     updatedAt?: string;
 }
+/**
+ * Pluggable projection/read-model state.
+ *
+ * **Durability stance (R9):** Default `InMemoryReadModelStore` is reference-only (not
+ * production durability). Inject a durable store for production. See
+ * `docs/production-hardening.md`.
+ */
 interface ReadModelStore {
     load<State = unknown>(name: string): MaybePromise<State | undefined>;
     save<State = unknown>(name: string, state: State): MaybePromise<void>;
@@ -933,6 +960,13 @@ interface WorkflowSnapshot<P extends SagaContext = SagaContext> {
     completedAt?: string;
     error?: string;
 }
+/**
+ * Pluggable saga/workflow snapshot store.
+ *
+ * **Durability stance (R9):** Default `InMemoryWorkflowStore` is reference-only (not
+ * production durability). Inject a durable store for production. See
+ * `docs/production-hardening.md`.
+ */
 interface WorkflowStore {
     save<P extends SagaContext>(snapshot: WorkflowSnapshot<P>): MaybePromise<void>;
     get<P extends SagaContext = SagaContext>(id: string): MaybePromise<WorkflowSnapshot<P> | undefined>;

package/dist/{types-CP3KkwZt.d.ts → types-CSJhEOk2.d.ts}

@@ -412,17 +412,29 @@ interface AuditQuery {
     until?: string;
     limit?: number;
 }
+/**
+ * Pluggable persistence for audit records.
+ *
+ * **Durability stance (R9):** Default is `InMemoryAuditStore` — reference only, not
+ * production durability (lost on restart). Implement this interface for durable audit.
+ * See `docs/production-hardening.md`.
+ */
 interface AuditStore {
     append(record: AuditRecord): MaybePromise<void>;
     query(query?: AuditQuery): MaybePromise<AuditRecord[]>;
     clear(): MaybePromise<void>;
 }
+/**
+ * High-level audit API used by the event bus / kernel.
+ * Durability is that of the injected `AuditStore` (default in-memory).
+ */
 interface AuditTrail {
     record(input: AuditRecordInput): Promise<AuditRecord>;
     query(query?: AuditQuery): Promise<AuditRecord[]>;
     clear(): Promise<void>;
 }
 interface CreateAuditTrailOptions {
+    /** Durable store when provided; otherwise `InMemoryAuditStore` (not production durability). */
     store?: AuditStore;
     maxRecords?: number;
 }
@@ -512,6 +524,14 @@ interface OutboxRecord {
     updatedAt: string;
     error?: string;
 }
+/**
+ * Pluggable outbox for publish handoff.
+ *
+ * **Durability stance (R9):** ArkGate ships only a reference in-process store
+ * (`InMemoryOutboxStore`) for tests, demos, and single-process development — it does
+ * not survive process restarts and is **not production durability**. Inject your own
+ * `OutboxStore` (DB, queue, etc.) for real systems. See `docs/production-hardening.md`.
+ */
 interface OutboxStore {
     enqueue(event: DomainEvent): Promise<OutboxRecord>;
     markDispatched(id: string): Promise<void>;
@@ -807,6 +827,13 @@ interface ProjectionCheckpoint {
     lastCorrelationId?: string;
     updatedAt?: string;
 }
+/**
+ * Pluggable projection/read-model state.
+ *
+ * **Durability stance (R9):** Default `InMemoryReadModelStore` is reference-only (not
+ * production durability). Inject a durable store for production. See
+ * `docs/production-hardening.md`.
+ */
 interface ReadModelStore {
     load<State = unknown>(name: string): MaybePromise<State | undefined>;
     save<State = unknown>(name: string, state: State): MaybePromise<void>;
@@ -933,6 +960,13 @@ interface WorkflowSnapshot<P extends SagaContext = SagaContext> {
     completedAt?: string;
     error?: string;
 }
+/**
+ * Pluggable saga/workflow snapshot store.
+ *
+ * **Durability stance (R9):** Default `InMemoryWorkflowStore` is reference-only (not
+ * production durability). Inject a durable store for production. See
+ * `docs/production-hardening.md`.
+ */
 interface WorkflowStore {
     save<P extends SagaContext>(snapshot: WorkflowSnapshot<P>): MaybePromise<void>;
     get<P extends SagaContext = SagaContext>(id: string): MaybePromise<WorkflowSnapshot<P> | undefined>;

package/docs/agent-guide.md

@@ -195,7 +195,7 @@ npx arkgate-check --install-agent-gates --tools claude,cursor,codex,grok
 |------|------------|-----|-------------|
 | Claude Code | PreToolUse hook | `.mcp.json` / `claude mcp add` | `.claude/skills/<name>/SKILL.md` |
 | Cursor | Advisory (rules + MCP) | `.cursor/mcp.json` | `.cursor/commands/` |
-| OpenAI Codex | MCP + CI | `~/.codex/config.toml` | `$CODEX_HOME/prompts` (`--codex-home`) |
+| OpenAI Codex | MCP + CI | `$CODEX_HOME/config.toml` (global; absolute `--root`; multi-project → secondary `ark_<slug>` unless `--force`) | `$CODEX_HOME/prompts` (`--codex-home`) |
 | **Grok Build** | PreToolUse hook (`.grok/hooks/`) | `.grok/config.toml` + `.mcp.json` | `.grok/skills/<name>/SKILL.md` |
 
 Full copy-paste setups: [ai-gates.md](ai-gates.md). Skill inventory: main [README](../README.md#agent-skills-ark-).

package/docs/ai-gates.md

@@ -189,20 +189,54 @@ Your hard backstop in Cursor is CI: `ark-check` fails the PR on anything that sl
 
 Recommended for Ark projects.
 
-`~/.codex/config.toml`:
+Unlike Claude/Cursor (project-local MCP files), **Codex loads MCP servers only from
+`$CODEX_HOME/config.toml`** (default `~/.codex/config.toml`) — a **global** home file.
+Hand-editing with relative `--root .` is wrong: Codex does not use the project as cwd, so
+`.` resolves against the launch directory. Prefer absolute paths, or let Ark write them:
+
+```bash
+npx ark-check --install-agent-gates --tools codex
+# optional: install /ark-* slash prompts into $CODEX_HOME/prompts
+npx ark-check --install-agent-gates --codex-home
+```
+
+Example shape (absolute paths — also what install writes):
 
 ```toml
 [mcp_servers.ark]
 command = "npx"
-args = ["ark-mcp", "--root", ".", "--config", "ark.config.json"]
+args = ["arkgate-mcp", "--root", "/absolute/path/to/project", "--config", "/absolute/path/to/project/ark.config.json"]
+```
+
+Then **restart Codex** — it does not hot-load MCP servers. Expect resource `ark://manifest`
+and tools `validate_code`, `ark_check`, `ark_coverage`, `ark_place`.
+
+Same model as Cursor for enforcement: MCP for discovery/validation, `ark-check` in CI as
+the hard gate. Register the MCP server as soon as the repo is adopted.
+
+### Multi-project Codex (home config last-wins)
+
+`[mcp_servers.ark]` is a **single primary** binding. If project A is already registered and
+you install gates for project B **without** `--force`, Ark does **not** silently steal
+primary A. It writes a **scoped secondary** table:
+
+```toml
+[mcp_servers.ark]            # primary — still project A
+# ...
+
+[mcp_servers.ark_proj-b_a1b2c3d4]  # secondary — basename + path hash (no slug collisions)
+# absolute --root for B
 ```
 
-Same model as Cursor: MCP for discovery/validation, `ark-check` in CI as the hard gate.
-For Ark projects, register the MCP server as soon as the repo is adopted so the agent
-has the contract available from the first edit.
+| Goal | Command |
+|------|---------|
+| Add B without moving primary | `ark-check --install-agent-gates --tools codex` (no `--force`) |
+| Make B the primary binding | `ark-check --install-agent-gates --tools codex --force` |
+| Doctor: primary points at another permanent project | gap id `codex-home-multi-project` (warn if no secondary yet; info if scoped table already present) |
 
-`ark-check --install-agent-gates --tools codex` auto-merges absolute paths into
-`~/.codex/config.toml` and can install `/ark-*` prompts with `--codex-home`.
+`ark-check --doctor` surfaces the multi-project state so you are not left thinking B owns
+`ark://manifest` when only a secondary table exists. Temp/upgrade primary roots are still
+rewritten fail-closed (not multi-project).
 
 ## Grok Build (xAI)
 

package/docs/brownfield-adoption.md

@@ -71,6 +71,13 @@ violations — the ratchet only moves toward zero.
 - **Value import of pure type module** (`targetTypeOnlyExports` — plan:
   `import-type-from-pure-type-module`): convert static import to `import type`. Not safe for
   `require()` / dynamic `import()`.
+- **Named type exports from mixed modules** (`namedBindingsTypeOnly` — plan:
+  `import-type-of-type-exports`): value-syntax `import { Row }` / `export { Row }` where every
+  binding is an `export type` / `interface` on the target — convert to `import type` /
+  `export type`. Still **judgment** when any binding is a value, dual-space name
+  (`export type Foo` + `export const Foo`), the target has top-level side effects (including
+  impure value-export initializers like `export const db = connect()`), or the edge is
+  `require` / dynamic `import()`.
 - **Raw infrastructure access** (value coupling — always **judgment**): relocate data-access
   **verbatim** into a repository/adapter. Same query bytes = same behavior; do NOT rewrite the
   query. If CODEOWNERS reserves the data layer, migrate one route as a pattern and hand bulk

package/docs/demos/03-copilot-autopilot.md

@@ -40,8 +40,9 @@ npx ark-check --plan --json     # { ok, plan: { goal, counts, steps } }
 ```
 
 Each step is tagged `mechanical-safe` / `judgment` / `deferred` with a `confidence`,
-`rationale`, and often `remediationKind`. Only three kinds are auto-safe: type-only type move,
-pure-type **file** relocate, and `import type` of pure-type modules. `goal.met` is true only when
+`rationale`, and often `remediationKind`. Auto-safe kinds: type-only type move, pure-type **file**
+relocate, `import type` of pure-type modules, and named type-export imports from mixed modules
+(`import-type-of-type-exports`). `goal.met` is true only when
 there are no active violations **and** governed coverage is meaningful — so a clean plan that
 checks almost nothing is not "done."
 

package/docs/enthusiast/reference-commands.md

@@ -51,7 +51,7 @@ arkgate-check --watch
 
 | `class` | Agent may auto-apply? | Examples (`remediationKind`) |
 |---------|----------------------|------------------------------|
-| `mechanical-safe` | Yes (validate + rollback) | `type-only-import-move`, `pure-type-file-relocate`, `import-type-from-pure-type-module` |
+| `mechanical-safe` | Yes (validate + rollback) | `type-only-import-move`, `pure-type-file-relocate`, `import-type-from-pure-type-module`, `import-type-of-type-exports` |
 | `judgment` | No — propose | value imports, ports, infra relocate, cycles |
 | `deferred` | No | unclear shape |
 
@@ -62,4 +62,4 @@ When present on violations:
 - `fixClass` — e.g. `port-inversion`, `file-move`
 - `effort` — `small` | `medium`
 - `enthusiastHint` — plain English fix guidance
-- plan enrichment: `class`, `remediationKind`, `typeOnly`, `sourcePureTypeModule`, `targetTypeOnlyExports`
+- plan enrichment: `class`, `remediationKind`, `typeOnly`, `sourcePureTypeModule`, `targetTypeOnlyExports`, `namedBindingsTypeOnly`

package/docs/package-surface.md

@@ -26,7 +26,7 @@ Gates need **no application code imports**. Most projects only use the CLI + MCP
 
 | Surface | Import path | Notes |
 |---------|-------------|--------|
-| **Runtime kernel** | **`arkgate/runtime`** (preferred) | Event bus, intents, policies, sagas, outbox, projections, `createArkKernel` / strict helpers. Optional. Not required for architecture enforcement. |
+| **Runtime kernel** | **`arkgate/runtime`** (preferred) | Event bus, intents, policies, sagas, outbox, projections, `createArkKernel` / strict helpers. Optional. Not required for architecture enforcement. Built-in stores are **InMemory reference only** (not production durability) — see [production-hardening.md](./production-hardening.md). |
 | **Root package barrel** | `arkgate` | Still re-exports the runtime kernel for **compatibility**. Prefer `arkgate/runtime` for new code. Root may be thinned in a future **major**. |
 | **NestJS adapter** | `arkgate/nestjs` | Optional peer `@nestjs/common`. Wires a kernel into Nest DI. |
 

package/docs/production-hardening.md

@@ -3,11 +3,17 @@
 The optional runtime kernel is imported from **`arkgate/runtime`** (preferred). See
 [package-surface.md](package-surface.md).
 
-Ark's built-in stores are intentionally in-memory defaults. They are appropriate for tests,
-local development, examples, and single-process demos. Production systems should provide
+## Durability stance (R9)
+
+**ArkGate does not ship production-durable adapters.** Built-in stores are **reference
+InMemory-only** — appropriate for tests, local development, examples, and single-process
+demos. They lose all state on process restart. Production systems **must** inject their
+own implementations of the store interfaces (or accept that data is ephemeral).
+
+Ark's built-in stores are intentionally in-memory defaults. Production systems should provide
 stores that match their durability, ordering, retention, and operational requirements.
 
-## In-Memory Defaults
+## In-Memory Defaults (reference only — not production durability)
 
 These defaults do not survive process restarts:
 
@@ -16,7 +22,8 @@ These defaults do not survive process restarts:
 - `InMemoryReadModelStore`
 - `InMemoryWorkflowStore`
 
-Use them only when losing state is acceptable.
+Use them only when losing state is acceptable. JSDoc on `OutboxStore`, `AuditStore`,
+`ReadModelStore`, and `WorkflowStore` restates this stance at the type level.
 
 ## Production Store Checklist
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "arkgate",
-  "version": "2.7.0",
+  "version": "2.8.1",
   "description": "ArkGate — architecture co-pilot for AI TypeScript (write gate, CI gate, plan/loop)",
   "type": "module",
   "main": "./dist/index.cjs",
@@ -75,6 +75,7 @@
     "check:cli-pure": "node scripts/generate-cli-pure.mjs --check",
     "test:ts-compat": "node scripts/ts-compat-matrix.mjs 5.9.3 && node scripts/ts-compat-matrix.mjs 6.0.3 && node scripts/ts-compat-matrix.mjs 7.0.2",
     "eval:agent": "node eval/run.mjs",
+    "eval:corpus": "node eval/validate-corpus.mjs",
     "eval:comparative": "node eval/comparative-run.mjs",
     "clean": "rm -rf dist",
     "release:npm": "node scripts/release-npm.mjs",

package/server.json

@@ -6,12 +6,12 @@
     "url": "https://github.com/pedroknigge/arkgate",
     "source": "github"
   },
-  "version": "2.7.0",
+  "version": "2.8.1",
   "packages": [
     {
       "registryType": "npm",
       "identifier": "arkgate",
-      "version": "2.7.0",
+      "version": "2.8.1",
       "runtimeHint": "npx",
       "transport": {
         "type": "stdio"

package/templates/skills/ark-explain.md

@@ -47,8 +47,9 @@ dependency direction, matrix, violations, enforcement points, Ark fitness score,
 **Senior diagnostics** block (coupling fan-in/out, deny density, purity surface, pattern
 forensics, baseline taxonomy) for tech leads.
 
-When explaining the **plan**, name the three `mechanical-safe` remediation kinds only
-(type-only move, pure-type file relocate, `import type` of pure-type modules) — everything
+When explaining the **plan**, name the four `mechanical-safe` remediation kinds only
+(type-only move, pure-type file relocate, `import type` of pure-type modules,
+`import-type-of-type-exports` for named type exports from mixed modules) — everything
 else is judgment/deferred and must not be auto-applied.
 
 ## Spoken / written explanation

package/templates/skills/ark-loop.md

@@ -32,8 +32,9 @@ validating every change with `ark-check` and rolling back regressions.
 | `type-only-import-move` | Move type to owning layer; re-export for back-compat |
 | `pure-type-file-relocate` | Relocate pure-type file to owning layer (or rename out of false Domain globs) |
 | `import-type-from-pure-type-module` | Convert value import of pure-type module to `import type` |
+| `import-type-of-type-exports` | Convert value-syntax named import/export of type-only exports from a mixed module to `import type` / `export type` |
 
-Never auto: value imports, dynamic import/require, mixed modules, forbidden globals, cycles, infra moves.
+Never auto: value imports (including mixed bindings with values), dynamic import/require, forbidden globals, cycles, infra moves.
 
 ## Steps