ark-runtime-kernel 1.1.0 → 1.2.0

package/docs/blog/how-i-stopped-claude-from-breaking-my-architecture.md

@@ -0,0 +1,85 @@
+# How I stopped Claude from breaking my hexagonal architecture
+
+*Draft — publish on dev.to / HN / r/typescript alongside the repo going public.*
+
+---
+
+AI agents write most of my code now. They're fast, they're tireless, and they have absolutely no respect for my architecture.
+
+Ask an agent to "add a findById method to Order" and there's a decent chance it imports the Postgres repository straight into the domain layer. The code compiles. The tests pass. The PR looks fine at a glance. Three months of that and your hexagonal architecture is a decorative diagram.
+
+The usual answer is "review harder" — which doesn't scale when the agent produces 30 PRs a week — or "add a linter", which catches the violation *after* the agent already built three files on top of it.
+
+## The insight: block at write time, not review time
+
+Agent runtimes like Claude Code have pre-write hooks: a shell command that runs *before* a file edit lands, and can veto it. That's a fundamentally better enforcement point than CI:
+
+1. The violation never reaches disk.
+2. The agent sees the error **in its loop** and self-corrects immediately — it defines the port in the domain and implements it in the adapter, like you would have asked for in review.
+
+So I built [Ark](https://github.com/pedroknigge/ark-runtime-kernel). You describe your architecture once, as data:
+
+```json
+{
+  "layers": [
+    { "name": "DomainModel", "patterns": ["src/domain/**"] },
+    { "name": "PersistenceAdapters", "patterns": ["src/adapters/persistence/**"] }
+  ],
+  "rules": [
+    { "from": "DomainModel", "to": "PersistenceAdapters", "allowed": false }
+  ]
+}
+```
+
+Then wire it into Claude Code as a PreToolUse hook:
+
+```json
+{
+  "hooks": {
+    "PreToolUse": [{
+      "matcher": "Write|Edit|MultiEdit",
+      "hooks": [{ "type": "command",
+        "command": "npx ark-mcp --hook --root \"$CLAUDE_PROJECT_DIR\" --config ark.config.json" }]
+    }]
+  }
+}
+```
+
+Now the same request plays out like this:
+
+```
+● Write(src/domain/order.ts)
+✗ Ark architecture gate blocked this write to src/domain/order.ts (layer: DomainModel):
+- [FORBIDDEN_PATTERN] Forbidden pattern matched: /from ['"].*\/(infra|adapters|persistence|db)/i (line 1)
+- [FORBIDDEN_IMPORT] Forbidden import target: "../adapters/persistence/order-repository". (line 1)
+Fix the violations and retry. The architecture contract is available as the ark://manifest MCP resource.
+
+● The domain layer can't import persistence adapters. I'll define the port in
+  the domain instead and implement it in src/adapters/persistence/.
+```
+
+The agent fixed its own architecture violation. Nobody reviewed anything.
+
+## Details that turned out to matter
+
+**The gate validates the post-edit file, not the diff.** An edit snippet out of context tells you nothing about imports. `ark-mcp --hook` applies the proposed edit to the current file content and validates the result.
+
+**The same config gates CI.** Not every write goes through an agent, and not every agent runtime has hooks. `ark-check` runs the same rules in CI with TypeScript's real module resolver — path aliases and all — so nothing merges that violates the contract, whoever wrote it.
+
+**Agents can read the contract, not just bounce off it.** The MCP server also exposes `ark://manifest` — the architecture as JSON — so agents get the rules *before* generating code instead of learning by rejection.
+
+**Existing codebases need a ratchet.** Nobody adopts a checker that greets them with 400 errors. `ark-check --update-baseline` freezes today's violations; from then on only *new* ones fail. The count only goes down.
+
+## What about dependency-cruiser / eslint-plugin-boundaries?
+
+They're good tools and they cover the CI half. What they don't have is the write-time half: an MCP server and hook designed for agent runtimes, plus a machine-readable manifest for agents to consume. That's the part that changes agent behavior instead of just grading it.
+
+## Try it
+
+```bash
+npm i -D ark-runtime-kernel typescript
+npx ark-check --init      # infers layers from your folder structure
+npx ark-check             # CI gate
+```
+
+Repo: https://github.com/pedroknigge/ark-runtime-kernel — zero dependencies, MIT.

package/docs/production-hardening.md

@@ -0,0 +1,59 @@
+# Production Hardening
+
+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
+stores that match their durability, ordering, retention, and operational requirements.
+
+## In-Memory Defaults
+
+These defaults do not survive process restarts:
+
+- `InMemoryAuditStore`
+- `InMemoryOutboxStore`
+- `InMemoryReadModelStore`
+- `InMemoryWorkflowStore`
+
+Use them only when losing state is acceptable.
+
+## 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.
+
+## Interface Targets
+
+| Concern | Interface |
+|---------|-----------|
+| Audit records | `AuditStore` |
+| Outbox dispatch handoff | `OutboxStore` |
+| 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.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ark-runtime-kernel",
-  "version": "1.1.0",
+  "version": "1.2.0",
   "description": "Architectural Runtime Kernel — governance for Hexagonal + Event-Driven + DDD systems",
   "type": "module",
   "main": "./dist/index.cjs",
@@ -24,6 +24,7 @@
     }
   },
   "bin": {
+    "ark": "bin/ark.mjs",
     "ark-check": "bin/ark-check.mjs",
     "ark-mcp": "bin/ark-mcp.mjs"
   },
@@ -31,6 +32,7 @@
   "files": [
     "bin",
     "dist",
+    "docs",
     "server.json",
     "README.md",
     "LICENSE"
@@ -43,6 +45,7 @@
     "typecheck": "tsc --noEmit",
     "check:architecture": "node bin/ark-check.mjs --root . --config ark.config.json --strict-config",
     "clean": "rm -rf dist",
+    "postinstall": "node bin/ark-postinstall.mjs",
     "release:npm": "node scripts/release-npm.mjs",
     "prepack": "npm run build"
   },