ark-runtime-kernel 1.1.0 → 1.3.0

package/docs/agent-guide.md

@@ -0,0 +1,353 @@
+# Ark — Agent Integration Guide
+
+This guide describes how AI agents and codegen tools can safely interact with Ark.
+
+## Contract Discovery
+
+Prefer `createStrictArkKernel()` for strict projects. It wires the registry, graph,
+policies, event bus, audit trail, event contracts, outbox, observability,
+projections, metadata, workflow engine, and 11-layer architecture profile:
+
+```ts
+import {
+  createStrictArkKernel,
+} from 'ark-runtime-kernel';
+
+const ark = createStrictArkKernel();
+// ... define intents, event contracts, metadata, projections, and workflows through ark.*
+
+const contract = ark.manifest().toJSON();
+// contract.intents, policies, entities, graph, architecture, eventContracts,
+// contract.observability, projections
+```
+
+Agents should read `contract` and `ark.observability.report()` before generating or modifying code.
+
+## Naming Conventions
+
+| Prefix | Layer | Example |
+|--------|-------|---------|
+| `Domain.*` | Domain events & entities | `Domain.Order.OrderPlaced` |
+| `Application.*` | Use cases / orchestration | `Application.PlaceOrder` |
+| `Adapter.Persistence.*` | Persistence adapters | `Adapter.Persistence.OrderRepo` |
+| `Adapter.Integration.*` | External integrations | `Adapter.Integration.PaymentGateway.Charge` |
+| `Workflow.*` | Sagas / long-running processes | `Workflow.OrderFulfillment` |
+| `Job.*` | Background jobs / scheduling | `Job.InventoryRebuild` |
+| `Presentation.*` | UI/API adapters | `Presentation.Api.PlaceOrder` |
+| `Reporting.*` | Read models / projections | `Reporting.OrderSummary` |
+| `Metadata.*` | Metadata and extension contracts | `Metadata.OrderSchema` |
+| `Security.*`, `Audit.*`, `Observability.*` | Cross-cutting concerns | `Audit.OrderHistory` |
+| `Kernel.*` | Ark-owned governance signals | `Kernel.PolicyViolation` |
+
+Declare relationships at definition time:
+
+```ts
+registry.define('Application.PlaceOrder', {
+  dependsOn: ['Domain.Order.OrderPlaced'],
+  produces: ['Domain.Order.OrderPlaced'],
+});
+```
+
+Strict kernels also enforce the **observed** producer→event layer flow at publish time
+(`enforceObservedLayerFlow: 'hard'` by default). If a published event's real source and
+intent cross a forbidden layer boundary — e.g. a `Adapter.Persistence.*` source producing
+a `Domain.*` event — the publish throws `ObservedLayerFlowViolationError` before the event
+reaches history, outbox, or subscribers. Use `'soft'` to record `layer.observedViolation`
+trace/audit records without blocking, or `'off'` to disable. Agents should name the event's
+`source` honestly: it is checked against the layer matrix, not just the intent name.
+
+Strict kernels also require published events to have a registered source intent
+and a matching event contract:
+
+```ts
+const OrderPlaced = registry.define<
+  'Domain.Order.OrderPlaced',
+  { orderId: string; amount: number }
+>('Domain.Order.OrderPlaced');
+
+registry.define('Application.PlaceOrder', {
+  produces: ['Domain.Order.OrderPlaced'],
+});
+
+ark.eventContracts.register({
+  intent: 'Domain.Order.OrderPlaced',
+  version: '1',
+  allowAdditionalFields: false,
+  schema: {
+    orderId: { type: 'string', required: true },
+    amount: { type: 'number', required: true },
+  },
+});
+
+const publisher = ark.publisher('Application.PlaceOrder');
+
+await publisher.publish(OrderPlaced, { orderId: 'o1', amount: 99 }, {
+  eventVersion: '1',
+});
+```
+
+Agents should prefer `ark.publisher(sourceIntent).publish(...)` over direct
+`eventBus.publish(...)`. Source-bound publishers stamp `metadata.source` internally and
+reject attempts to override it with a different source.
+
+Interceptors may enrich event payloads, but they must remain add-only:
+
+```ts
+ark.eventBus.registerInterceptor(OrderPlaced, ({ intercept }) => {
+  intercept({ auditTag: 'checkout' });
+}, 'audit-tag');
+```
+
+If an interceptor overwrites an existing field or violates the registered event
+contract, Ark records `interceptor.error` and keeps delivering the original event.
+
+## Code Generation Validation
+
+Use `createAICodeGate()` before merging agent-generated source snippets:
+
+```ts
+import * as ts from 'typescript';
+
+const gate = createAICodeGate({
+  intents: registry.list(),
+  enforceIntentAllowlist: true,
+  architectureProfile: elevenLayerProfile,
+  typescript: ts,
+  extensions: [/* optional external AST analyzers implementing AIGateExtension */],
+});
+
+const result = gate.validate(generatedSource, {
+  filePath: 'src/domain/order.ts',
+  agentId: 'agent-1',
+  layer: 'DomainModel',
+});
+if (!result.valid) {
+  for (const v of result.violations) {
+    console.log(v.code, v.message, v.suggestion);
+  }
+}
+```
+
+Passing the `typescript` module enables built-in AST checks for raw publish calls, missing
+`metadata.source`, and source-layer mismatches. `ark-mcp` enables these checks
+automatically when TypeScript is available.
+
+Violation codes (from `createAICodeGate`): `RAW_EVENT_PUBLISH`, `PUBLISH_MISSING_SOURCE`, `PUBLISH_SOURCE_LAYER_MISMATCH`, `FORBIDDEN_PATTERN`, `FORBIDDEN_SUBSTRING`, `FORBIDDEN_IMPORT`, `POLICY_VIOLATION`, `UNKNOWN_INTENT`, `LAYER_REFERENCE_VIOLATION`, `EXTENSION_ERROR`, `AST_ANALYZER_ERROR`.
+
+Use `ark-check` in CI for repository-level checks that need real file paths:
+
+```bash
+npx ark-check --root . --config ark.config.json
+```
+
+Agents can generate a config from the project's actual directory layout instead of inventing layer mappings:
+
+```bash
+npx ark-check --init
+```
+
+Or print the full 11-layer template to adapt manually:
+
+```bash
+npx ark-check --print-config eleven-layer
+```
+
+Example config:
+
+```json
+{
+  "include": ["src"],
+  "layers": [
+    {
+      "name": "DomainModel",
+      "patterns": ["src/domain/**"],
+      "intentPrefixes": ["Domain."]
+    },
+    {
+      "name": "PersistenceAdapters",
+      "patterns": ["src/adapters/persistence/**"],
+      "intentPrefixes": ["Adapter.Persistence."]
+    },
+    {
+      "name": "ApplicationOrchestration",
+      "patterns": ["src/application/**"],
+      "intentPrefixes": ["Application."]
+    }
+  ],
+  "rules": [
+    {
+      "from": "DomainModel",
+      "to": "PersistenceAdapters",
+      "allowed": false
+    }
+  ]
+}
+```
+
+`ark-check` resolves imports through the TypeScript module resolver against your
+`tsconfig.json` — relative, path-alias (e.g. `@infra/db`), package imports, dynamic
+`import()`, and `require()` — plus string intent references. It also flags raw
+`publish()` calls, publish calls without `metadata.source`, and source intent literals
+whose resolved layer differs from the publishing file layer. Pass `--tsconfig <path>` to point at a specific config
+(otherwise the nearest `tsconfig.json` from `--root` is used). It resolves modules the way
+your build does, but is intentionally not yet a full type-graph analyzer (cross-layer
+type-only references beyond the import specifier are out of scope).
+
+`ark-check --json` also reports `warnings` for incomplete governance coverage: missing
+layers, unclassified included files, unmatched layer patterns, duplicate layers, and rules
+that reference unknown layers. These are advisory by default. Use `--strict-config` once a
+project is ready to fail CI on coverage gaps.
+
+Use the optional ESLint plugin for fast local feedback:
+
+```js
+import ark from 'ark-runtime-kernel/eslint';
+
+export default [
+  ark.configs.recommended,
+];
+```
+
+Rules: `ark/no-domain-infra-imports`, `ark/no-raw-event-publish`, and
+`ark/require-publish-source`.
+
+## Runtime Observability
+
+The event bus exposes a standard trace format:
+
+```ts
+const bus = createEventBus({
+  maxHistorySize: 1000,
+  auditTrail,
+  traceSinks: [(record) => otelBridge(record)],
+  onSoftViolation: (result, event) => { /* advisory policies */ },
+  onHandlerError: (err, event, intent) => { /* subscriber failures */ },
+});
+
+await bus.publish(intent, payload);
+const trace = bus.getTrace();
+// trace[].type includes 'event.published', 'event.rawPublish', 'event.intercepted',
+// 'interceptor.error', 'policy.hardViolation', 'policy.softViolation', 'handler.error'
+```
+
+Native audit records are available through `auditTrail.query()`. Projection
+state and checkpoints are available through `ProjectionRegistry`.
+
+`ark.observability.report()` compares declared productions with observed runtime
+flows. Use `observedButUndeclared` as a high-signal review queue for hidden coupling.
+
+For tests, use `createArkTestHarness(ark)` to inspect events, traces, audit,
+outbox, and observability snapshots without reaching into private internals.
+
+## Extension Points (External Layers)
+
+Implement these interfaces in **external** packages — not inside the Ark core:
+
+| Interface | Purpose |
+|-----------|---------|
+| `AIGateExtension` | Plug in AST/semantic analyzers for codegen validation |
+| `Policy` | Custom architectural rules via `definePolicy()` |
+| `LayerFlowRule` | Layer isolation via `defineLayerPolicy()` |
+| `WorkflowStore` | Persist workflow snapshots outside memory |
+| `ReadModelStore` | Persist projection/read-model state outside memory |
+| `AuditStore` | Persist audit records outside memory |
+| `OutboxStore` | Persist event outbox records outside memory |
+| `EventInterceptor` | Add-only event enrichment before delivery |
+
+## Ports and Adapters
+
+When generating adapter code, prefer ports with explicit ownership and allowlists:
+
+```ts
+const PaymentGateway = definePort<PaymentGatewayPort>('PaymentGateway', {
+  ownerLayer: 'ApplicationOrchestration',
+  intent: 'Application.Port.PaymentGateway',
+  allowedAdapters: ['Adapter.Integration.StripePaymentGateway'],
+});
+
+createAdapter(PaymentGateway, stripeAdapter, {
+  name: 'Adapter.Integration.StripePaymentGateway',
+  layer: 'IntegrationAdapters',
+  requiredKeys: ['charge'],
+});
+```
+
+`createAdapter` rejects adapter names/intents not listed in `allowedAdapters`; use
+`checkAdapterGovernance(adapter)` when a tool needs a non-throwing result.
+
+Preset: `elevenLayerProfile` plus `defineArchitectureProfilePolicy()` forbids invalid declared dependencies across the 11-layer profile. `architecturalPolicies.cleanArchitectureMatrix()` remains available for the older four-prefix model.
+
+Runtime support depth varies by design. Layers with dedicated kernel modules:
+DomainModel/ApplicationOrchestration (intents, policies), WorkflowSagaEngine
+(workflow engine), PersistenceAdapters (adapters, outbox), ReportingReadModels
+(projections), ExtensibilityMetadata (metadata registry), SecurityAuditObservability
+(audit trail, drift reporter), Kernel (event bus, graph, manifest).
+PresentationAdapters, IntegrationAdapters, and BackgroundJobsScheduling are
+**boundary-only on purpose**: Ark governs what they may import and publish, but does
+not replace your web framework, HTTP clients, or job scheduler.
+
+## Write-Path Gate (MCP)
+
+The strongest place to constrain an AI agent is the moment it writes a file, not after.
+`ark-mcp` exposes Ark over MCP (zero dependencies, JSON-RPC over stdio) so a host can gate
+the write path:
+
+```bash
+npx ark-mcp --root . --config ark.config.json [--manifest ark.manifest.json]
+```
+
+- **Resource `ark://manifest`** — contract discovery. Serve your exported
+  `ark.manifest().toJSON()` via `--manifest`, or omit it to get the 11-layer profile
+  (layers + rules) as the default contract.
+- **Tool `validate_code`** — args `{ source, layer?, filePath? }`. Runs `createAICodeGate`
+  against the profile and (when a manifest is provided) the registered intent allowlist.
+  Returns `{ valid, violations, layer }`; `isError` is `true` when invalid. If `layer` is
+  omitted it is inferred from `filePath` via the config's layer patterns.
+
+For hook-based enforcement, `ark-mcp --hook` runs one-shot: it reads a PreToolUse payload
+from stdin, validates the post-edit file content, and exits `2` with violations on stderr
+to block the write (`0` to allow). Working Claude Code configuration
+(`.claude/settings.json`):
+
+```json
+{
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Write|Edit|MultiEdit",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "npx ark-mcp --hook --root \"$CLAUDE_PROJECT_DIR\""
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+Register the server itself in `.mcp.json` so the agent can read `ark://manifest` and call
+`validate_code` on demand:
+
+```json
+{
+  "mcpServers": {
+    "ark": { "command": "npx", "args": ["ark-mcp", "--root", ".", "--config", "ark.config.json"] }
+  }
+}
+```
+
+This makes the manifest + AI gate an enforced checkpoint rather than a library the agent
+must remember to call.
+
+## Recommended Agent Workflow
+
+1. **Read** manifest via `ark.manifest().toJSON()`
+2. **Generate** code using registered intents, profiles, metadata, projections, and workflow definitions
+3. **Validate snippets** with `createAICodeGate().validate(source, { layer })`
+4. **Validate repository** with `ark-check --root . --config ark.config.json`
+5. **Lint** with `ark-runtime-kernel/eslint` recommended rules
+6. **Wire** relationships via `registry.define(..., { dependsOn, produces })`
+7. **Register** event contracts before publishing in strict mode
+8. **Observe** runtime via `bus.getTrace()`, `auditTrail.query()`, outbox records, projection checkpoints, and `ark.observability.report()`

package/docs/ai-gates.md

@@ -0,0 +1,177 @@
+# Gating AI Agents with Ark
+
+The write-path gate is what makes Ark different from every other architecture linter: generated code is validated against your architecture **before it lands on disk**, not after the PR is red.
+
+Everything below uses the same `ark.config.json` as `ark-check` (CI) — one contract, enforced everywhere. Generate it once:
+
+```bash
+npx ark-check --init
+```
+
+For guided setup with prompts, use:
+
+```bash
+npx ark init
+```
+
+For non-interactive defaults, use:
+
+```bash
+npx ark init --yes
+```
+
+You can also generate only the starter gate files for common agent runtimes and CI:
+
+```bash
+npx ark-check --install-agent-gates
+```
+
+The command writes templates for `.mcp.json`, Claude hooks, Cursor MCP/rules,
+GitHub Actions, `AGENTS.md`, and a Codex TOML snippet under `docs/`. It skips
+existing files unless you pass `--force`, so review and commit only the templates
+that match your project.
+
+If your project uses Codex, treat the MCP registration as part of the default setup,
+not an optional extra. Ark works best when Codex can read `ark://manifest` before it
+writes code; that is the fast path to avoiding architecture drift during generation.
+
+## Claude Code — hook (recommended, hard block)
+
+`ark-mcp --hook` is a one-shot PreToolUse gate: it reads the hook payload from stdin, computes the **post-edit** file content, validates it, and exits `2` (block, violations on stderr) or `0` (allow). The agent sees the violations and self-corrects.
+
+Add to your project's `.claude/settings.json`:
+
+```json
+{
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Write|Edit|MultiEdit",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "npx ark-mcp --hook --root \"$CLAUDE_PROJECT_DIR\" --config ark.config.json"
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+That's the whole setup. Try asking the agent to import a persistence adapter from your domain layer:
+
+```
+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/pg-order-repository". (line 1)
+Fix the violations and retry. The architecture contract is available as the ark://manifest MCP resource.
+```
+
+## Claude Code — MCP server (contract discovery + on-demand validation)
+
+The MCP server exposes two things agents can use proactively:
+
+- **`ark://manifest`** (resource) — the machine-readable architecture contract (layers + rules), so the agent can read the architecture before generating code.
+- **`validate_code`** (tool) — validates a snippet against the architecture on demand.
+
+```bash
+claude mcp add ark -- npx ark-mcp --root . --config ark.config.json
+```
+
+or in `.mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "ark": {
+      "type": "stdio",
+      "command": "npx",
+      "args": ["ark-mcp", "--root", ".", "--config", "ark.config.json"]
+    }
+  }
+}
+```
+
+Use both: the MCP server for discovery, the hook for enforcement.
+
+## Cursor
+
+Cursor supports MCP servers (`.cursor/mcp.json`):
+
+```json
+{
+  "mcpServers": {
+    "ark": {
+      "command": "npx",
+      "args": ["ark-mcp", "--root", ".", "--config", "ark.config.json"]
+    }
+  }
+}
+```
+
+Cursor has no pre-write hook, so the gate is advisory at write time — pair it with a rules file so the agent actually calls it. `.cursor/rules/ark.mdc`:
+
+```markdown
+---
+description: Ark architecture contract
+alwaysApply: true
+---
+
+Before writing or editing any TypeScript source file, call the `validate_code`
+tool from the `ark` MCP server with the full post-edit file content and its
+path. If it reports violations, fix them before writing. The architecture
+contract is available as the `ark://manifest` resource.
+```
+
+Your hard backstop in Cursor is CI: `ark-check` fails the PR on anything that slips through.
+
+## OpenAI Codex CLI
+
+Recommended for Ark projects.
+
+`~/.codex/config.toml`:
+
+```toml
+[mcp_servers.ark]
+command = "npx"
+args = ["ark-mcp", "--root", ".", "--config", "ark.config.json"]
+```
+
+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.
+
+## Any other agent runtime with shell hooks
+
+If your runtime can run a shell command before file writes and pass the tool payload on stdin (Claude Code's PreToolUse contract), `ark-mcp --hook` works as-is. The contract:
+
+- stdin: JSON `{ "tool_name": "Write|Edit|MultiEdit", "tool_input": { "file_path": ..., ... } }`
+- exit `0` → allow; exit `2` → block, human-readable violations on stderr
+- plumbing problems (no stdin, non-source files, files outside `--root`) never block
+
+## ESLint (editor feedback)
+
+For in-editor red squiggles on layer violations, add the ESLint plugin:
+
+```js
+// eslint.config.js
+import ark from 'ark-runtime-kernel/eslint';
+
+export default [ark.configs.recommended];
+```
+
+## CI backstop
+
+Whatever the agent side does, gate the merge:
+
+```yaml
+- run: npx ark-check --root . --config ark.config.json --strict-config
+```
+
+Adopting Ark on an existing codebase with violations? Freeze them once and ratchet down:
+
+```bash
+npx ark-check --update-baseline   # writes .ark-baseline.json — commit it
+npx ark-check --baseline          # only NEW violations fail
+```

package/docs/ark-check-example.json

@@ -0,0 +1,87 @@
+{
+  "include": ["src"],
+  "layers": [
+    {
+      "name": "DomainModel",
+      "patterns": ["src/domain/**"],
+      "intentPrefixes": ["Domain."]
+    },
+    {
+      "name": "ApplicationOrchestration",
+      "patterns": ["src/application/**"],
+      "intentPrefixes": ["Application."]
+    },
+    {
+      "name": "PersistenceAdapters",
+      "patterns": ["src/adapters/persistence/**"],
+      "intentPrefixes": ["Adapter.Persistence."]
+    },
+    {
+      "name": "IntegrationAdapters",
+      "patterns": ["src/adapters/integration/**"],
+      "intentPrefixes": ["Adapter.Integration."]
+    },
+    {
+      "name": "WorkflowSagaEngine",
+      "patterns": ["src/workflows/**"],
+      "intentPrefixes": ["Workflow."]
+    },
+    {
+      "name": "BackgroundJobsScheduling",
+      "patterns": ["src/jobs/**"],
+      "intentPrefixes": ["Job."]
+    },
+    {
+      "name": "PresentationAdapters",
+      "patterns": ["src/presentation/**"],
+      "intentPrefixes": ["Presentation."]
+    },
+    {
+      "name": "ReportingReadModels",
+      "patterns": ["src/reporting/**"],
+      "intentPrefixes": ["Reporting."]
+    },
+    {
+      "name": "ExtensibilityMetadata",
+      "patterns": ["src/metadata/**"],
+      "intentPrefixes": ["Metadata."]
+    },
+    {
+      "name": "SecurityAuditObservability",
+      "patterns": ["src/security/**", "src/audit/**", "src/observability/**"],
+      "intentPrefixes": ["Security.", "Audit.", "Observability."]
+    },
+    {
+      "name": "Kernel",
+      "patterns": ["src/kernel/**"],
+      "intentPrefixes": ["Kernel."]
+    }
+  ],
+  "rules": [
+    {
+      "from": "DomainModel",
+      "to": "PersistenceAdapters",
+      "allowed": false
+    },
+    {
+      "from": "DomainModel",
+      "to": "IntegrationAdapters",
+      "allowed": false
+    },
+    {
+      "from": "DomainModel",
+      "to": "PresentationAdapters",
+      "allowed": false
+    },
+    {
+      "from": "PresentationAdapters",
+      "to": "PersistenceAdapters",
+      "allowed": false
+    },
+    {
+      "from": "ReportingReadModels",
+      "to": "PersistenceAdapters",
+      "allowed": false
+    }
+  ]
+}

package/docs/assets/ark-write-gate.svg

@@ -0,0 +1,28 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="760" height="330" viewBox="0 0 760 330" font-family="ui-monospace, SFMono-Regular, Menlo, Consolas, monospace" font-size="13">
+  <defs>
+    <clipPath id="window"><rect x="0" y="0" width="760" height="330" rx="10"/></clipPath>
+  </defs>
+  <g clip-path="url(#window)">
+    <rect width="760" height="330" fill="#0d1117"/>
+    <rect width="760" height="34" fill="#161b22"/>
+    <circle cx="20" cy="17" r="6" fill="#ff5f57"/>
+    <circle cx="40" cy="17" r="6" fill="#febc2e"/>
+    <circle cx="60" cy="17" r="6" fill="#28c840"/>
+    <text x="380" y="21" fill="#8b949e" text-anchor="middle" font-size="12">claude — my-hexagonal-app</text>
+
+    <text x="24" y="64" fill="#c9d1d9">&gt; add a findById method to Order that reads straight from postgres</text>
+
+    <text x="24" y="96" fill="#8b949e">● Edit(src/domain/order.ts)</text>
+    <text x="40" y="118" fill="#6e7681">import { PgOrderRepository } from '../adapters/persistence/pg-order-repository';</text>
+
+    <text x="24" y="152" fill="#f85149" font-weight="bold">✗ Ark architecture gate blocked this write to src/domain/order.ts (layer: DomainModel):</text>
+    <text x="40" y="174" fill="#f85149">- [FORBIDDEN_IMPORT] Forbidden import target: "../adapters/persistence/pg-order-repository".</text>
+    <text x="24" y="196" fill="#8b949e">Fix the violations and retry. The architecture contract is available as the</text>
+    <text x="24" y="214" fill="#8b949e">ark://manifest MCP resource.</text>
+
+    <text x="24" y="248" fill="#c9d1d9">● The domain layer can't import persistence adapters. I'll define the port in the</text>
+    <text x="24" y="266" fill="#c9d1d9">domain instead and implement it in src/adapters/persistence/.</text>
+
+    <text x="24" y="300" fill="#28c840">● Edit(src/domain/ports/order-repository.ts)  ✔ allowed</text>
+  </g>
+</svg>