arkgate 2.12.0 → 3.0.0

package/docs/production-hardening.md

@@ -1,7 +1,8 @@
 # Production Hardening
 
-The optional runtime kernel is imported from **`arkgate/runtime`** (preferred). See
-[package-surface.md](package-surface.md).
+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)
 
@@ -18,11 +19,11 @@ stores that match their durability, ordering, retention, and operational require
 These defaults do not survive process restarts:
 
 - `InMemoryAuditStore`
-- `InMemoryOutboxStore`
+- `InMemoryEventBuffer` (`InMemoryOutboxStore` is a deprecated compatibility alias)
 - `InMemoryReadModelStore`
 - `InMemoryWorkflowStore`
 
-Use them only when losing state is acceptable. JSDoc on `OutboxStore`, `AuditStore`,
+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
@@ -42,12 +43,37 @@ passed as the third `execute` argument, but JavaScript cannot stop an operation
 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` |
-| Outbox dispatch handoff | `OutboxStore` |
+| Non-atomic dispatch buffer | `EventBufferStore` |
 | Projection state | `ReadModelStore` |
 | Workflow snapshots | `WorkflowStore` |
 

package/docs/threat-model.md

@@ -0,0 +1,65 @@
+# Threat model — ArkGate (Q9)
+
+**Scope:** architecture write/CI gates, agent hooks/MCP, and the experimental optional runtime.
+**Not in scope:** full org identity platforms, browser XSS in consumer apps, or npm registry
+infrastructure beyond how this package is published.
+
+## Assets
+
+| Asset | Why it matters |
+|-------|----------------|
+| `ark.config.json` contract | Defines what agents may import; weaken it → silent architectural debt |
+| Write hook (`arkgate-mcp --hook`) | Hard local boundary only for installed/trusted Claude/Grok hook operations |
+| CI `ark-check --strict-merge` | Repository check for every host; merge blocking requires a required status |
+| Baselines (`.ark-baseline.json`) | Freezes debt; abuse silences real violations |
+| Published npm tarball + Action SHA | Supply-chain integrity of the gate itself |
+| Experimental runtime kernel | Event/saga state; InMemory is not durable |
+
+## Actors
+
+- **AI agent** (Claude / Cursor / Codex / Grok) with tool write access; see the
+  [canonical host support matrix](../README.md#host-enforcement-support)
+- **Human developer** editing files outside hooks (IDE, git apply)  
+- **CI runner** on PRs / main  
+- **Maintainer / attacker** with publish or PR privileges  
+
+## Threats (STRIDE-light)
+
+| ID | Threat | Impact | Mitigations (shipped) |
+|----|--------|--------|------------------------|
+| T1 | Agent bypasses hook (direct `fs` / alternate tool) | Ungoverned code lands | CI gate; optional pre-commit (Q3); doctor writePath honesty |
+| T2 | Human commits without agent path | Same as T1 | `templates/hooks/pre-commit-ark`; branch protection + required check (Q3 external) |
+| T3 | CI job missing / not required | Merge green without architecture | doctor `enforcement-ci-*` gaps; `--strict-merge` profile |
+| T4 | Config weakened (`peerIsolation: false`, empty rules) | False green | safety diagnostics; false-green adoption detector |
+| T5 | Baseline ratcheted open | Debt reintroduced | baseline unused/stale signals; occurrence keys |
+| T6 | Dual MCP bin / wrong root | Gate points at wrong tree | migrate-commands; Codex fail-closed temp roots |
+| T7 | Malicious dependency in publish | Compromised gate | signed tags, npm provenance, dependency-review, CodeQL, Semgrep, `verify-package-files` |
+| T8 | Path traversal in hooks/check | Read/write outside project | root resolution + under-root import resolve |
+| T9 | Runtime InMemory mistaken for durable | Data loss | durability stance docs + safety InMemory production detector |
+| T10 | Repair payload silently applied | Unexpected rewrites | repair never writes; host must re-inject; exit 2 on deny |
+
+## Trust boundaries
+
+```
+Claude/Grok host --PreToolUse--> arkgate-mcp (hard matched-write boundary)
+Any MCP host     --tool call----> arkgate-mcp (advisory validation)
+Human IDE        --disk/git-----> working tree
+working tree     --PR-----------> CI ark-check --strict-merge
+npm publish <-- signed tag ---  GitHub Release + provenance
+```
+
+## Residual risk (accepted)
+
+- Branch protection is **external GitHub state** — doctor reports honestly when unavailable.  
+- Full external adoption matrix (Q4) and independent ≥95 audit (Q10) are separate exit gates.
+- Live multi-agent loop-cost remains optional (`ARK_EVAL_LOOP_LIVE`).
+
+## Verification hooks
+
+| Check | Command |
+|-------|---------|
+| Package allowlist | `node scripts/verify-package-files.mjs` |
+| Module budgets | `node scripts/check-module-budgets.mjs` |
+| Security CI | `.github/workflows/security.yml` |
+| Audit (prod deps) | `npm run security:audit` |
+| Architecture | `npm run check:architecture` |

package/docs/typescript-support.md

@@ -32,7 +32,7 @@ itself; the CLI resolves it from the **project** first, then from the environmen
 ## How loading works
 
 1. Prefer `require('typescript')` from the **project** root (when it has `sys` + AST + resolve).  
-2. If missing or **not API-compatible** (TS 7.0 version-only export, or incomplete host), fall back to **ArkGate’s own** `typescript` dependency (JS-API 5.x nested under the package), then bare `import('typescript')`.  
+2. If missing or **not API-compatible** (TS 7.0 version-only export, or incomplete host), fall back to **ArkGate’s own** `typescript` dependency (JS-API 5.x nested under the package), then bare `import('typescript')`.
 3. If nothing usable is found:  
    - `--plan` still prints **coverage honesty** (no import graph)  
    - full check exits non-zero with an install hint  
@@ -49,9 +49,9 @@ ARK_DEBUG_TS=1 npx arkgate-check --plan
 TypeScript 7 is the **native (Go) compiler** generation. Important for tools like ArkGate:
 
 - **`require('typescript')` on 7.0.x** exports only `{ version, versionMajorMinor }` — not `sys`, `createSourceFile`, or `resolveModuleName`.  
-- Unstable programmatic surfaces live under `typescript/unstable/*` (sync/async API, AST). They are **not** the classic TS 5/6 host ArkGate uses today.  
+- Unstable programmatic surfaces live under `typescript/unstable/*` (sync/async API, AST). They are **not** the classic TS 5/6 host ArkGate uses today.
 - Stable **programmatic JS API** maturity continues over the 7.x line (Microsoft: full story into **7.1+**).  
-- When the project’s TypeScript is not API-compatible, ArkGate loads its **bundled JS-API dependency** (`typescript@^5.9`, nested under the package) so the write/CI gate keeps working while you try TS 7 as the project compiler.  
+- When the project’s TypeScript is not API-compatible, ArkGate loads its **bundled JS-API dependency** (`typescript@^5.9`, nested under the package) so the host write path and CI check keep working while you try TS 7 as the project compiler.
 - Your **tsconfig** must follow TS 6/7 defaults (see below) or `tsc` / resolve can fail independently of ArkGate.
 
 ### tsconfig defaults that surprise teams (TS 6 → 7)
@@ -131,6 +131,33 @@ node scripts/ts-compat-matrix.mjs 7.0.2
 | Gate uses native Go typechecker API exclusively | Not required; future if 7.1+ exposes a stable Node API we adopt |
 | User tsconfigs with removed options still “just work” | User must migrate tsconfig (TS6/7); Ark reports resolve/parse failures clearly |
 
+## Static-analysis soundness envelope
+
+ArkGate uses the TypeScript compiler API to extract dependency and ambient-capability facts. The
+same Kernel implementation feeds the library, CLI, MCP write gate, and AICodeGate bundle.
+
+Dependency forms enforced when their module specifier is a string literal:
+
+- ESM `import`, `import type`, side-effect imports, and `export ... from` / `export type ... from`;
+- TypeScript `import x = require("...")`;
+- unshadowed CommonJS `require("...")`;
+- dynamic `import("...")`.
+
+Non-literal `import(expr)` and unshadowed `require(expr)` are reported as unresolved. They are
+advisory by default, fail with `--strict-config`, and may be reviewed at file granularity through
+`dynamicImportAllowlist`. A locally declared `require` function is not treated as CommonJS.
+
+Forbidden capabilities are resolved with single-file TypeScript symbols. Local variables,
+parameters, and imports shadow ambient names; aliases such as `const Clock = Date`, explicit
+`globalThis`, static bracket access, and object destructuring remain detectable. Resolution of
+module paths then uses the nearest tsconfig/jsconfig compiler options, including path aliases,
+project-local packages, workspaces, and symlinked workspace entries.
+
+ArkGate intentionally does not claim soundness for runtime-generated module names, `eval`, custom
+loader functions, proxy-based globals, dynamically computed property keys, or aliases mutated
+after declaration. Those constructs must remain absent from governed pure layers or be handled by
+an explicit project policy. Every newly discovered bypass is minimized into the adversarial corpus.
+
 ## Future (7.1+ programmatic API)
 
 When Microsoft ships a stable Node API for native TypeScript 7.1+:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "arkgate",
-  "version": "2.12.0",
+  "version": "3.0.0",
   "description": "ArkGate — architecture co-pilot for AI TypeScript (write gate, CI gate, plan/loop)",
   "type": "module",
   "main": "./dist/index.cjs",
@@ -13,19 +13,23 @@
       "require": "./dist/index.cjs"
     },
     "./runtime": {
-      "types": "./dist/runtime/index.d.ts",
-      "import": "./dist/runtime/index.js",
-      "require": "./dist/runtime/index.cjs"
+      "types": "./compat/runtime.d.ts",
+      "import": "./compat/runtime.js",
+      "require": "./compat/runtime.cjs"
     },
     "./eslint": {
       "types": "./dist/eslint/index.d.ts",
       "import": "./dist/eslint/index.js",
       "require": "./dist/eslint/index.cjs"
     },
+    "./schema": "./schemas/ark.config.schema.json",
+    "./schema/ark.config.schema.json": "./schemas/ark.config.schema.json",
+    "./schema/analysis-result": "./schemas/ark.analysis-result.schema.json",
+    "./schema/ark.analysis-result.schema.json": "./schemas/ark.analysis-result.schema.json",
     "./nestjs": {
-      "types": "./dist/nestjs/index.d.ts",
-      "import": "./dist/nestjs/index.js",
-      "require": "./dist/nestjs/index.cjs"
+      "types": "./compat/nestjs.d.ts",
+      "import": "./compat/nestjs.js",
+      "require": "./compat/nestjs.cjs"
     },
     "./package.json": "./package.json"
   },
@@ -41,7 +45,9 @@
   "files": [
     "bin",
     "bin/lib",
+    "compat",
     "dist",
+    "schemas",
     "docs/agent-guide.md",
     "docs/enthusiast",
     "docs/demos",
@@ -51,8 +57,10 @@
     "docs/ark-check-example.json",
     "docs/assets",
     "docs/brownfield-adoption.md",
+    "docs/configuration.md",
     "docs/package-surface.md",
     "docs/production-hardening.md",
+    "docs/threat-model.md",
     "tests/fixtures/ts-consumer",
     "templates",
     "server.json",
@@ -62,11 +70,23 @@
     "LICENSE"
   ],
   "scripts": {
-    "build": "tsup",
+    "build": "node scripts/clean-gate-dist.mjs && tsup",
+    "build:runtime": "tsup --config packages/runtime/tsup.config.ts",
     "dev": "tsup --watch",
     "test": "vitest",
     "test:run": "vitest run",
-    "test:coverage": "vitest run --coverage --coverage.reporter=text-summary --coverage.reporter=json-summary",
+    "test:coverage": "npm run build && vitest run --coverage --coverage.reporter=text-summary --coverage.reporter=json-summary",
+    "test:mutation": "npm run build && stryker run && npm run check:mutation-groups",
+    "check:mutation-groups": "node scripts/check-mutation-groups.mjs",
+    "test:property": "vitest run tests/property",
+    "test:fuzz": "npm run build && ARK_FUZZ_CAMPAIGN=pr vitest run tests/fuzz",
+    "test:fuzz:extended": "npm run build && ARK_FUZZ_CAMPAIGN=extended vitest run tests/fuzz",
+    "test:confidence": "npm run test:coverage && npm run test:mutation",
+    "test:adapter-parity": "vitest run tests/unit/adapters/adapterParity.test.ts tests/unit/eslint/parity.test.ts",
+    "test:onboarding-matrix": "for shard in library/small library/medium library/large api/small api/medium api/large frontend/small frontend/medium frontend/large monorepo/small monorepo/medium monorepo/large; do O04_SHARD=$shard npm run test:onboarding-matrix:shard; done",
+    "test:onboarding-matrix:shard": "vitest run tests/unit/static-check/o04OnboardingMatrix.test.ts",
+    "test:gate-only": "vitest run tests/unit/static-check/arkCheck.test.ts tests/unit/mcp/arkMcp.test.ts tests/unit/eslint",
+    "test:package-isolation": "node scripts/smoke-package-isolation.mjs",
     "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",
@@ -75,6 +95,8 @@
     "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",
+    "generate:analysis-engine": "node scripts/generate-analysis-engine.mjs",
+    "check:analysis-engine": "node scripts/generate-analysis-engine.mjs --check",
     "check:gallery-starters": "node scripts/check-gallery-starters.mjs",
     "generate:gallery-starters": "node scripts/check-gallery-starters.mjs --write",
     "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",
@@ -82,6 +104,15 @@
     "eval:corpus": "node eval/validate-corpus.mjs",
     "eval:comparative": "node eval/comparative-run.mjs",
     "eval:loop-cost": "node eval/loop-cost-run.mjs",
+    "eval:adoption": "node eval/adoption-run.mjs",
+    "test:adoption-harness": "vitest run tests/unit/eval/adoptionHarness.test.ts",
+    "bench:scale": "node scripts/ark-scale-bench.mjs",
+    "test:scale-bench": "npm run build && vitest run tests/unit/scripts/arkScaleBench.test.ts",
+    "check:module-budgets": "node scripts/check-module-budgets.mjs",
+    "check:package-files": "node scripts/verify-package-files.mjs",
+    "check:release-artifacts": "node scripts/verify-release-artifacts.mjs",
+    "test:release-artifacts": "vitest run tests/unit/scripts/verifyReleaseArtifacts.test.ts",
+    "audit:beta-exit": "node scripts/beta-exit-audit.mjs",
     "clean": "rm -rf dist",
     "release:npm": "node scripts/release-npm.mjs",
     "prepack": "npm run build"
@@ -90,11 +121,11 @@
     "typescript": "^5.9.3"
   },
   "peerDependencies": {
-    "@nestjs/common": ">=9",
+    "@arkgate/runtime": ">=0.1.0-experimental.0 <1",
     "typescript": ">=5.0.0 <8"
   },
   "peerDependenciesMeta": {
-    "@nestjs/common": {
+    "@arkgate/runtime": {
       "optional": true
     },
     "typescript": {
@@ -102,6 +133,7 @@
     }
   },
   "overrides": {
+    "qs": "6.15.3",
     "vite": "6.4.3",
     "tsup": {
       "esbuild": "0.28.1"
@@ -112,8 +144,11 @@
   },
   "devDependencies": {
     "@nestjs/common": "^11.1.27",
+    "@stryker-mutator/core": "^9.6.1",
+    "@stryker-mutator/vitest-runner": "^9.6.1",
     "@types/node": "^20.14.0",
     "@vitest/coverage-v8": "^3.2.6",
+    "fast-check": "^4.9.0",
     "reflect-metadata": "^0.2.2",
     "rxjs": "^7.8.2",
     "tsup": "^8.1.0",

package/schemas/ark.analysis-result.schema.json

@@ -0,0 +1,91 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://unpkg.com/arkgate@2/schemas/ark.analysis-result.schema.json",
+  "title": "ArkGate analysis result",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "schemaVersion",
+    "valid",
+    "diagnostics"
+  ],
+  "properties": {
+    "schemaVersion": {
+      "const": "1.0"
+    },
+    "valid": {
+      "type": "boolean"
+    },
+    "diagnostics": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": [
+          "ruleId",
+          "severity",
+          "message",
+          "location",
+          "evidence"
+        ],
+        "properties": {
+          "ruleId": {
+            "type": "string",
+            "minLength": 1
+          },
+          "severity": {
+            "enum": [
+              "error",
+              "warning"
+            ]
+          },
+          "message": {
+            "type": "string",
+            "minLength": 1
+          },
+          "location": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": [
+              "file",
+              "line",
+              "column"
+            ],
+            "properties": {
+              "file": {
+                "type": "string",
+                "minLength": 1
+              },
+              "line": {
+                "type": "integer",
+                "minimum": 1
+              },
+              "column": {
+                "type": "integer",
+                "minimum": 1
+              }
+            }
+          },
+          "evidence": {
+            "type": "object",
+            "additionalProperties": false,
+            "properties": {
+              "target": {
+                "type": "string"
+              },
+              "fromLayer": {
+                "type": "string"
+              },
+              "toLayer": {
+                "type": "string"
+              },
+              "typeOnly": {
+                "type": "boolean"
+              }
+            }
+          }
+        }
+      }
+    }
+  }
+}