arkgate 2.6.1 → 2.7.0

package/docs/package-surface.md

@@ -0,0 +1,72 @@
+# ArkGate package surface policy
+
+**Product wedge:** write gate · CI gate · co-pilot (plan / loop / skills).  
+**Not the wedge:** the optional in-process runtime kernel.
+
+This document is the consumer contract for **what is stable** vs **what is opt-in**.
+
+---
+
+## Stable surfaces (semver-supported)
+
+| Surface | How you use it | Stability notes |
+|---------|----------------|-----------------|
+| **CLI** | `arkgate` / `arkgate-check` (aliases `ark` / `ark-check`) | Flags and human text may improve; **JSON output shapes** for `--json` (check, doctor, plan, coverage, recommend) are stable within a major. Additive fields OK; removals/renames are major. |
+| **MCP tools** | `arkgate-mcp` / `ark://…` resources | Tool names and primary argument shapes are stable within a major. |
+| **`ark.config.json`** | Layer globs, rules, include/exclude, forbiddenGlobals, intent prefixes | Schema fields documented in playbooks/examples are stable; new optional fields may appear. |
+| **Agent skills** | `/ark-*` templates installed by `--install-agent-gates` | Skill *names* and “default flow” are stable; internal skill prose may evolve. |
+| **ESLint subpath** | `arkgate/eslint` | Config-driven layer/import rules; loads consumer `ark.config.json`. |
+| **GitHub Action** | `pedroknigge/arkgate` (see `action.yml`) | Inputs for running the check stay stable within a major. |
+
+Gates need **no application code imports**. Most projects only use the CLI + MCP + config.
+
+---
+
+## Opt-in surfaces
+
+| 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. |
+| **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. |
+
+---
+
+## Recommended imports
+
+```ts
+// Preferred — opt-in runtime kernel
+import {
+  createStrictArkKernel,
+  createStrictArkKernelFromConfig,
+} from 'arkgate/runtime';
+
+// Still works this major (compat; not preferred for new code)
+import { createStrictArkKernel } from 'arkgate';
+
+// Nest adapter
+import { ArkModule, InjectArk } from 'arkgate/nestjs';
+```
+
+See [production-hardening.md](./production-hardening.md) for runtime operational guidance.
+
+---
+
+## Explicitly unstable / internal
+
+- `bin/lib/*` module layout and private helpers  
+- Generated `bin/ark-layer-match.mjs` (edit canonical `src/domain/layerMatch.ts` only)  
+- HTML report DOM structure (unless documented as a machine contract)  
+- Internal MCP diagnostic fields not listed in agent-guide  
+
+---
+
+## Versioning summary
+
+| Change | Version bump |
+|--------|----------------|
+| Break CLI JSON field, MCP tool rename, or required `ark.config` field | **major** |
+| New optional config field, new CLI flag, additive JSON | **minor** |
+| Bugfix with no contract change | **patch** |
+| Prefer `arkgate/runtime` over root (docs only; root still exports) | **patch/minor** |
+| Remove root kernel re-exports | **major** (with migration notes) |

package/docs/production-hardening.md

@@ -1,5 +1,8 @@
 # Production Hardening
 
+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
 stores that match their durability, ordering, retention, and operational requirements.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "arkgate",
-  "version": "2.6.1",
+  "version": "2.7.0",
   "description": "ArkGate — architecture co-pilot for AI TypeScript (write gate, CI gate, plan/loop)",
   "type": "module",
   "main": "./dist/index.cjs",
@@ -12,6 +12,11 @@
       "import": "./dist/index.js",
       "require": "./dist/index.cjs"
     },
+    "./runtime": {
+      "types": "./dist/runtime/index.d.ts",
+      "import": "./dist/runtime/index.js",
+      "require": "./dist/runtime/index.cjs"
+    },
     "./eslint": {
       "types": "./dist/eslint/index.d.ts",
       "import": "./dist/eslint/index.js",
@@ -46,6 +51,7 @@
     "docs/ark-check-example.json",
     "docs/assets",
     "docs/brownfield-adoption.md",
+    "docs/package-surface.md",
     "docs/production-hardening.md",
     "tests/fixtures/ts-consumer",
     "templates",
@@ -63,6 +69,10 @@
     "typecheck": "tsc --noEmit",
     "security:audit": "npm audit --omit=dev --audit-level=high",
     "check:architecture": "node bin/ark-check.mjs --root . --config ark.config.json --strict-config",
+    "generate:layer-match": "node scripts/generate-layer-match.mjs",
+    "check:layer-match": "node scripts/generate-layer-match.mjs --check",
+    "generate:cli-pure": "node scripts/generate-cli-pure.mjs",
+    "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:comparative": "node eval/comparative-run.mjs",

package/server.json

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