arkgate 3.0.4 → 3.1.0

package/docs/migrate-from-ark-runtime-kernel.md

@@ -1,174 +0,0 @@
-# Migrate from `ark-runtime-kernel` → **ArkGate** (`arkgate`)
-
-**Same product.** Only the npm name and primary CLI names changed.
-Config, baselines, and `/ark-*` skills stay.
-
-| | Before | After |
-|--|--------|--------|
-| Package | `ark-runtime-kernel` | **`arkgate`** |
-| Product name | Ark | **ArkGate** |
-| Check CLI | `ark-check` | **`arkgate-check`** (alias `ark-check` still works) |
-| MCP CLI | `ark-mcp` | **`arkgate-mcp`** (alias `ark-mcp` still works) |
-| Setup CLI | `ark` | **`arkgate`** (alias `ark` still works) |
-| Config | `ark.config.json` | **unchanged** |
-| Baseline | `.ark-baseline.json` | **unchanged** |
-| Skills | `/ark-autopilot`, … | **unchanged** |
-| GitHub | `pedroknigge/ark-runtime-kernel` | **`pedroknigge/arkgate`** (old URL redirects) |
-
----
-
-## Fast path (recommended)
-
-```bash
-# 1) Swap the dependency
-npm uninstall ark-runtime-kernel
-npm install -D arkgate
-# pnpm: pnpm remove ark-runtime-kernel && pnpm add -D arkgate
-# yarn: yarn remove ark-runtime-kernel && yarn add -D arkgate
-
-# 2) Refresh gates, skills, MCP templates
-npx arkgate-check --install-agent-gates --force
-
-# 3) Verify
-npx arkgate-check --doctor
-npx arkgate-check --root . --config ark.config.json --strict-config
-```
-
-One-liner if the old bin is still on the path after installing `arkgate`:
-
-```bash
-npx arkgate upgrade
-```
-
-(`ark upgrade` works too — both install `arkgate@latest` and refresh gates.)
-
-### TypeScript 7
-
-If the project uses **TypeScript 7** as `tsc`, the gate still works: ArkGate embeds a JS-API
-TypeScript host and falls back when `require('typescript')` is version-only. See
-[typescript-support.md](typescript-support.md). Optional dual-install (TS 6 for tools + TS 7
-CLI) is documented there.
-
-### MCP args (avoid double binary)
-
-`.mcp.json` / `.cursor/mcp.json` must look like:
-
-```json
-"args": ["arkgate-mcp", "--root", ".", "--config", "ark.config.json"]
-```
-
-**Not** `["ark-mcp", "arkgate-mcp", …]` — that breaks MCP stdio. Fixed by
-`npx arkgate-check --install-agent-gates --migrate-commands` (ArkGate ≥ 2.4.0).
-
----
-
-## What to change in your repo
-
-### `package.json`
-
-```diff
-- "ark-runtime-kernel": "^2.0.1"
-+ "arkgate": "^2.1.0"
-```
-
-Scripts:
-
-```diff
-- "check:architecture": "ark-check --root . --config ark.config.json --strict-config"
-+ "check:architecture": "arkgate-check --root . --config ark.config.json --strict-config"
-```
-
-(`ark-check` still works as a compat alias for one major.)
-
-### CI / GitHub Actions
-
-```diff
-- run: npx ark-check --root . --config ark.config.json --strict-config
-+ run: npx arkgate-check --root . --config ark.config.json --strict-config
-```
-
-Composite action:
-
-```diff
-- uses: pedroknigge/ark-runtime-kernel@main
-+ uses: pedroknigge/arkgate@main
-```
-
-### MCP (Claude / Cursor / `.mcp.json`)
-
-```json
-{
-  "mcpServers": {
-    "ark": {
-      "command": "npx",
-      "args": ["arkgate-mcp", "--root", ".", "--config", "ark.config.json"]
-    }
-  }
-}
-```
-
-Then restart the agent / reload MCP.
-
-### Codex
-
-Re-register so home MCP points at this project with the new bin:
-
-```bash
-npx arkgate-check --install-agent-gates --tools codex --force
-# optional home skills:
-npx arkgate-check --install-agent-gates --codex-home --force
-```
-
-### Grok
-
-```bash
-npx arkgate-check --install-agent-gates --tools grok --force
-```
-
-Or edit `.grok/config.toml` → `args` use `arkgate-mcp`.
-
-### TypeScript imports (runtime / Nest / ESLint only)
-
-The runtime and Nest surfaces are currently **experimental**; migrating the package name does not
-require adopting them. Static CLI/MCP enforcement remains the supported product path.
-
-```diff
-- import { createStrictArkKernelFromConfig } from 'ark-runtime-kernel';
-+ import { createStrictArkKernelFromConfig } from '@arkgate/runtime';
-
-- import { ArkModule } from 'ark-runtime-kernel/nestjs';
-+ import { ArkModule } from '@arkgate/runtime/nestjs';
-
-- import ark from 'ark-runtime-kernel/eslint';
-+ import ark from 'arkgate/eslint';
-```
-
-If you only used the CLI + MCP (most projects), **no import changes**.  
-Surface policy: [package-surface.md](package-surface.md).
-
----
-
-## What you can ignore
-
-- Renaming `ark.config.json` — not required  
-- Renaming `/ark-*` skills — not required  
-- Re-running full adopt/architect — not required unless you want a fresh plan  
-
----
-
-## Troubleshooting
-
-| Symptom | Fix |
-|---------|-----|
-| `npm warn deprecated ark-runtime-kernel` | Swap dep to `arkgate` (this guide) |
-| `ark-check: not found` after uninstall | Use `npx arkgate-check` or reinstall `arkgate` |
-| MCP still launches old package | Update `.mcp.json` / Codex / Grok config; restart agent |
-| pnpm blocks new package age | Wait for cooling-off or pin exact version `arkgate@2.1.0` |
-
----
-
-## Why the rename
-
-`ark-runtime-kernel` suggested a runtime framework. The product is the **architecture co-pilot / write+CI gate** for AI TypeScript. npm name is now **`arkgate`**.
-
-Questions: [github.com/pedroknigge/arkgate](https://github.com/pedroknigge/arkgate)

package/docs/production-hardening.md

@@ -1,100 +0,0 @@
-# Production Hardening
-
-The optional runtime kernel is currently **experimental**. This page is a requirements checklist
-for teams evaluating **`@arkgate/runtime`**, not a claim that the runtime is production-ready.
-Static ArkGate adoption does not require it. See [package-surface.md](package-surface.md).
-
-## 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 (reference only — not production durability)
-
-These defaults do not survive process restarts:
-
-- `InMemoryAuditStore`
-- `InMemoryEventBuffer` (`InMemoryOutboxStore` is a deprecated compatibility alias)
-- `InMemoryReadModelStore`
-- `InMemoryWorkflowStore`
-
-Use them only when losing state is acceptable. JSDoc on `EventBufferStore`, `AuditStore`,
-`ReadModelStore`, and `WorkflowStore` restates this stance at the type level.
-
-## Production Store Checklist
-
-When implementing Ark store interfaces in production, cover these guarantees explicitly:
-
-- Durability: records survive process restarts and deploys.
-- Idempotency: repeated writes or dispatch attempts do not corrupt state.
-- Ordering: event/outbox ordering is defined where consumers depend on it.
-- Concurrency: simultaneous publishers/workers cannot race checkpoints or workflow state.
-- Retention: audit and trace records have an explicit retention policy.
-- Observability: failed writes and dispatches are visible to operators.
-- Migration: schema changes for stored records are versioned.
-
-Workflow `timeoutMs` uses cooperative cancellation: ArkGate aborts the `AbortSignal`
-passed as the third `execute` argument, but JavaScript cannot stop an operation that
-ignores that signal. Production steps must pass it to network/database clients and keep
-external effects idempotent; otherwise work may finish after the workflow was marked failed.
-
-### Workflow retry boundary
-
-`RetryPolicy` applies only while `step.execute` is running, including a timeout from that
-execution. Once `execute` resolves, ArkGate marks the step completed before saving the
-snapshot and recording `workflow.step.completed`. If either post-effect operation fails, the
-workflow enters its failure/compensation path; it does not execute the completed step again.
-
-The same fail-closed rule applies when the final `workflow.completed` audit record fails:
-completed steps are compensated when handlers exist, and the workflow ends failed. Production
-effects and compensations must therefore be idempotent, and audit/snapshot stores must be
-operational dependencies rather than best-effort telemetry.
-
-### Required recovery semantics (not implemented by built-ins)
-
-| Contract | Required definition before a production claim |
-|----------|-----------------------------------------------|
-| Workflow recovery | Persist the last committed step and effect id; restart resumes only from that checkpoint and never assumes an in-flight effect failed or succeeded without reconciliation. |
-| Optimistic versioning | Every snapshot write carries the previously read version; conflicting writes fail without overwriting and the caller reloads before retrying. |
-| Dispatcher leases | A claim records owner and expiry atomically; only the owner may acknowledge it, and takeover is allowed only after expiry. |
-| Idempotent delivery | Every message/effect has a stable idempotency key retained for the full retry window; duplicate attempts return the prior outcome without repeating the effect. |
-| Atomic handoff | Application state and dispatch record commit in one transaction. Without this guarantee the API must be called an event buffer, not an outbox. |
-
-The experimental package supplies none of these persistence guarantees. Fault/restart matrices
-must cover crashes before and after every transaction, effect, checkpoint, lease, and acknowledgement.
-
-## Interface Targets
-
-| Concern | Interface |
-|---------|-----------|
-| Audit records | `AuditStore` |
-| Non-atomic dispatch buffer | `EventBufferStore` |
-| Projection state | `ReadModelStore` |
-| Workflow snapshots | `WorkflowStore` |
-
-## Example Shape
-
-```ts
-class DurableAuditStore implements AuditStore {
-  async append(record: AuditRecord): Promise<void> {
-    // Insert into your database with an idempotent key.
-  }
-
-  async query(query: AuditQuery = {}): Promise<AuditRecord[]> {
-    // Apply query filters and retention-aware ordering.
-    return [];
-  }
-
-  async clear(): Promise<void> {
-    // Usually only enabled in tests or isolated maintenance jobs.
-  }
-}
-```
-
-Ark does not ship a database adapter in core because storage choice is operationally
-specific. Keep those adapters in the application or a separate integration package.