ark-runtime-kernel 1.3.0 → 1.5.0

package/README.md

@@ -3,7 +3,9 @@
 # 🏛️ Ark — Architectural Runtime Kernel
 
 **Stop AI agents (and humans) from quietly breaking your architecture.**<br/>
-One machine-readable contract — enforced at write time, merge time, and (optionally) runtime.
+One machine-readable contract — enforced at write time, merge time, and (optionally) runtime.<br/>
+Ships a complete 11-layer architecture you can adopt one layer at a time.
+Gates **Claude Code, Cursor, and Codex** natively — plus rule files for Windsurf, Cline, Copilot, Kiro, and Gemini CLI.
 
 [![CI](https://github.com/pedroknigge/ark-runtime-kernel/actions/workflows/ci.yml/badge.svg)](https://github.com/pedroknigge/ark-runtime-kernel/actions/workflows/ci.yml)
 [![npm](https://img.shields.io/npm/v/ark-runtime-kernel?color=cb3837&label=npm)](https://www.npmjs.com/package/ark-runtime-kernel)
@@ -12,7 +14,7 @@ One machine-readable contract — enforced at write time, merge time, and (optio
 ![TypeScript](https://img.shields.io/badge/TypeScript-first-3178c6?logo=typescript&logoColor=white)
 ![Zero deps](https://img.shields.io/badge/dependencies-0-success)
 
-[2-Minute Setup](#2-minute-setup) · [Why Ark](#why-ark-and-not-just-a-linter) · [AI Write Gate](#the-ai-write-gate) · [CI Gate](#ark-check--the-ci-gate) · [Runtime Kernel](#the-runtime-kernel-opt-in) · [Docs](#documentation)
+[2-Minute Setup](#2-minute-setup) · [Why Ark](#why-ark-and-not-just-a-linter) · [11 Layers](#batteries-included-the-11-layer-profile-all-optional) · [AI Write Gate](#the-ai-write-gate) · [CI Gate](#ark-check--the-ci-gate) · [Runtime Kernel](#the-runtime-kernel-opt-in) · [Docs](#documentation)
 
 </div>
 
@@ -124,6 +126,8 @@ If you only need import-boundary linting in CI, [dependency-cruiser](https://git
 | Cross-layer import checks in CI         | ✅ (TS resolver) | ✅ | ✅ | ✅ |
 | Blocks AI agents **before** code lands (MCP + hook) | ✅ | ❌ | ❌ | ❌ |
 | Machine-readable contract for agents (`ark://manifest`) | ✅ | ❌ | ❌ | ❌ |
+| Injects the contract into agent context at session start | ✅ | ❌ | ❌ | ❌ |
+| Forbidden ambient globals per layer (`Date.now` in domain, ...) | ✅ | ❌ | ➖ (generic ESLint) | ❌ |
 | Event/intent governance (who may publish what) | ✅ | ❌ | ❌ | ❌ |
 | Baseline ratchet for existing codebases | ✅ | ❌ | ➖ (via ESLint) | ❌ |
 | Optional runtime enforcement            | ✅ | ❌ | ❌ | ❌ |
@@ -133,19 +137,57 @@ If you only need import-boundary linting in CI, [dependency-cruiser](https://git
 
 | Gate         | Tool          | When it runs                  | What it enforces                              |
 |--------------|---------------|-------------------------------|-----------------------------------------------|
-| **Write**    | `ark-mcp`     | Agent PreToolUse (Write/Edit) | Layer rules, unknown intents, forbidden patterns |
-| **Merge**    | `ark-check`   | CI (GitHub Actions etc.)      | Cross-layer imports + intent references (real TS resolver) |
+| **Write**    | `ark-mcp`     | Agent PreToolUse (Write/Edit) | Layer rules, unknown intents, forbidden patterns + globals |
+| **Merge**    | `ark-check`   | CI (GitHub Actions etc.)      | Cross-layer imports + intent references (real TS resolver) + forbidden globals |
 | **Runtime**  | `createArkKernel()` | Running process (opt-in) | Intent registry, event contracts, observed layer flow, policies |
 
+## Batteries included: the 11-layer profile (all optional)
+
+You don't have to design a layer model before adopting Ark — it ships a complete,
+production-shaped division for Hexagonal + Event-Driven + DDD systems. Every layer is
+**optional by design**: on a fresh project the strict check passes immediately, and each
+layer starts being enforced the moment its directory gains source files. Adopt two
+layers or all eleven; `ark.config.json` is always authoritative and you can rename,
+remove, or re-map any of it.
+
+| Layer | Conventional directories | Intent prefixes |
+|-------|--------------------------|-----------------|
+| DomainModel | `domain/` | `Domain.` |
+| ApplicationOrchestration | `application/`, `app/` | `Application.` |
+| PersistenceAdapters | `adapters/persistence/`, `repositories/`, ... | `Adapter.Persistence.`, `Adapter.Repository.` |
+| IntegrationAdapters | `adapters/integration/`, `integrations/`, ... | `Adapter.Integration.`, `Adapter.External.` |
+| WorkflowSagaEngine | `workflows/`, `sagas/` | `Workflow.` |
+| BackgroundJobsScheduling | `jobs/`, `schedules/` | `Job.` |
+| PresentationAdapters | `presentation/`, `adapters/api/`, ... | `Presentation.`, `Adapter.Api.`, ... |
+| ReportingReadModels | `reporting/`, `read-models/`, `projections/` | `Reporting.` |
+| ExtensibilityMetadata | `metadata/`, `extensions/` | `Metadata.` |
+| SecurityAuditObservability | `security/`, `audit/`, `observability/` | `Security.`, `Audit.`, `Observability.` |
+| Kernel | `kernel/` | `Kernel.` |
+
+The default rule matrix is strict-deny: only the classic flows are open
+(Presentation→Application, Application→Domain, Workflow→Application/Domain,
+Jobs→Application) and everything else is a violation until you allow it explicitly.
+The profile isn't just for the linter — agents get it too: `ark://manifest` lists the
+layers your project hasn't adopted yet as `suggestedLayers`, so when an agent needs to
+create its first saga or background job, it puts it in the conventional place and adds
+the layer to the config instead of inventing an ungoverned location.
+
+```bash
+npx ark-check --print-config eleven-layer > ark.config.json   # the full profile, ready to edit
+```
+
 ## The AI Write Gate
 
 `ark-mcp` is a zero-dependency MCP server + one-shot hook:
 
 - **`ark-mcp --hook`** — PreToolUse gate: computes the **post-edit** file content, validates it against your layers, exits 2 with the violations when the write must be blocked. The agent self-corrects.
+- **`ark-mcp --session-context`** — SessionStart injection: prints a compact contract summary (layers, forbidden globals, baseline state) into the agent's context, so it knows the architecture from the first token instead of learning by rejection. Silent no-op outside Ark projects, so it can't leak into other repos.
 - **`validate_code` tool** — on-demand validation of a snippet, for runtimes without hooks.
-- **`ark://manifest` resource** — the architecture as JSON, so agents read the rules *before* generating code instead of learning by rejection.
+- **`ark://manifest` resource** — the architecture as JSON, so agents read the rules *before* generating code.
 
-Copy-paste setups for **Claude Code, Cursor, and OpenAI Codex**: [docs/ai-gates.md](docs/ai-gates.md).
+Copy-paste setups for **Claude Code, Cursor, and OpenAI Codex**, plus instruction-tier
+rule files for **Windsurf, Cline, GitHub Copilot, and Kiro** (Gemini CLI reads the
+generated `AGENTS.md` directly): [docs/ai-gates.md](docs/ai-gates.md).
 
 ## `ark-check` — The CI Gate
 
@@ -161,6 +203,17 @@ npx ark-check --baseline                                          # ratchet mode
 - String intent references across forbidden layers
 - Raw `publish()` calls that bypass registered intent creators
 - Missing / mismatched publish `source` metadata
+- Forbidden ambient globals per layer (`fetch`, `Date.now`, `Math.random`, ...) — see below
+
+**Fast on repeat runs, monorepo-ready:**
+
+- Per-file scan cache in `node_modules/.cache/ark-check.json` (keyed by mtime+size and
+  the config/manifest contents). Unchanged files skip the TypeScript parse; import edges
+  are always re-resolved against the live filesystem, so the cache can never hide a new
+  violation. Disable with `--no-cache`.
+- Path aliases resolve against the **nearest** `tsconfig.json` above each source file
+  (like `tsc`), so a monorepo with per-package alias maps runs under a single `--root`.
+  Pass `--tsconfig <path>` to force one config for every file.
 
 Violations come with the layer edge, the resolved target, and a fix hint:
 
@@ -171,6 +224,35 @@ Violations come with the layer edge, the resolved target, and a fix hint:
   fix: Depend on a port/interface owned by an inner layer instead, or move this code.
 ```
 
+### Domain purity: `forbiddenGlobals`
+
+Import rules can't catch code that reaches for an ambient global — an agent can call
+`fetch()` or `Date.now()` in your domain layer without importing anything. Declare the
+globals a layer must not touch and both the write gate and CI enforce it:
+
+```jsonc
+// ark.config.json
+{
+  "name": "DomainModel",
+  "patterns": ["src/domain/**"],
+  "intentPrefixes": ["Domain."],
+  "forbiddenGlobals": ["fetch", "process", "Date.now", "Math.random"]
+}
+```
+
+```
+✖ FORBIDDEN_GLOBAL  src/domain/order.ts:12
+  DomainModel must not use the ambient global "Date.now".
+  fix: Inject the capability through a port (e.g. a Clock, IdGenerator, or HttpPort).
+```
+
+Entries are either dotted (`"Date.now"` flags exactly that property access) or bare
+(`"console"` flags `console.*`, `fetch(...)`, `new WebSocket(...)`). Detection is
+positional, not scope-aware: mentions in types or import names are never flagged.
+`npx ark init` seeds the domain layer with `["fetch", "process", "Date.now", "Math.random"]`
+(a pure domain does no I/O and is deterministic); add `"console"` or any other global per
+project. Violations participate in the `--baseline` ratchet like every other rule.
+
 ### GitHub Action
 
 ```yaml
@@ -189,7 +271,15 @@ import ark from 'ark-runtime-kernel/eslint';
 export default [ark.configs.recommended];
 ```
 
-Rules: `ark/no-domain-infra-imports`, `ark/no-raw-event-publish`, `ark/require-publish-source`.
+Rules: `ark/no-domain-infra-imports`, `ark/no-raw-event-publish`, `ark/require-publish-source`,
+`ark/no-forbidden-globals` (not in `recommended` — scope it to your layer directories):
+
+```js
+{
+  files: ['src/domain/**'],
+  rules: { 'ark/no-forbidden-globals': ['error', { globals: ['fetch', 'process', 'Date.now', 'Math.random'] }] },
+}
+```
 
 ## The Runtime Kernel (opt-in)
 

package/bin/ark-check.mjs

@@ -1,10 +1,13 @@
 #!/usr/bin/env node
+import crypto from 'node:crypto';
 import fs from 'node:fs';
 import path from 'node:path';
 import {
+  DEFAULT_DOMAIN_FORBIDDEN_GLOBALS,
   DEFAULT_INTENT_PREFIXES,
   DEFAULT_LAYER_DIRECTORIES,
   DEFAULT_RULES,
+  collectForbiddenGlobalUses,
   createElevenLayerConfig,
   globToRegExp,
   layerForFile,
@@ -28,6 +31,7 @@ function parseArgs(argv) {
     force: false,
     baseline: undefined,
     updateBaseline: false,
+    noCache: false,
   };
   for (let i = 2; i < argv.length; i += 1) {
     const arg = argv[i];
@@ -51,6 +55,7 @@ function parseArgs(argv) {
       }
     }
     else if (arg === '--force') args.force = true;
+    else if (arg === '--no-cache') args.noCache = true;
     else if (arg === '--baseline' || arg === '--update-baseline') {
       if (arg === '--update-baseline') args.updateBaseline = true;
       // optional path value: consume the next arg only when it isn't another flag
@@ -69,7 +74,7 @@ function parseArgs(argv) {
 
 function usage() {
   return [
-    'Usage: ark-check --root <project> --config <ark.config.json> [--manifest <ark.manifest.json>] [--tsconfig <tsconfig.json>] [--strict-config] [--require-gates] [--json] [--baseline [file]]',
+    'Usage: ark-check --root <project> --config <ark.config.json> [--manifest <ark.manifest.json>] [--tsconfig <tsconfig.json>] [--strict-config] [--require-gates] [--json] [--baseline [file]] [--no-cache]',
     '       ark-check --init [--force]',
     '       ark-check --install-agent-gates [--tools claude,cursor,codex] [--force]',
     '       ark-check --update-baseline [file]     freeze current violations (default .ark-baseline.json)',
@@ -89,14 +94,21 @@ function usage() {
     '',
     'Resolves relative, tsconfig path-alias, and package imports via the TypeScript',
     'module resolver, then checks each resolved cross-layer import against the rules.',
-    'If no tsconfig is found, path aliases are unavailable but relative/package imports',
-    'still resolve.',
+    'Path aliases resolve against the NEAREST tsconfig.json above each source file, so',
+    'monorepo packages with per-package configs work under a single --root. Pass',
+    '--tsconfig to force one config for every file. If no tsconfig is found, path',
+    'aliases are unavailable but relative/package imports still resolve.',
+    '',
+    'Parsed files are cached in node_modules/.cache/ark-check.json (keyed by mtime+size',
+    'and the config/manifest contents); import edges are always re-resolved against the',
+    'live filesystem, so the cache can never hide a new violation. --no-cache disables it.',
     '',
     'Config shape:',
     '{',
     '  "include": ["src"],',
     '  "layers": [',
-    '    { "name": "DomainModel", "patterns": ["src/domain/**"], "intentPrefixes": ["Domain."] }',
+    '    { "name": "DomainModel", "patterns": ["src/domain/**"], "intentPrefixes": ["Domain."],',
+    '      "forbiddenGlobals": ["fetch", "process", "Date.now", "Math.random"] }',
     '  ],',
     '  "rules": [{ "from": "DomainModel", "to": "PersistenceAdapters", "allowed": false }]',
     '}',
@@ -109,9 +121,13 @@ function usage() {
     'with --strict-config to enforce gate presence and architecture in one run.',
     '',
     '--install-agent-gates writes AGENTS.md, .mcp.json, and the CI workflow for every',
-    'project, plus tool-specific templates. Pass --tools claude,cursor,codex to pick',
-    'which tool configs to write; otherwise they are auto-detected from .claude/, .cursor/,',
-    'and .codex/ (all are written when nothing is detected).',
+    'project, plus tool-specific templates. Known tools: claude, cursor, codex (full',
+    'MCP/hook gates) and windsurf, cline, copilot, kiro (instruction-tier rule files',
+    'derived from the same contract; Gemini CLI needs no template — it reads AGENTS.md).',
+    'Pass --tools to pick which tool configs to write; otherwise they are auto-detected',
+    'from their config directories (.claude/, .cursor/, .codex/, .windsurf/, .clinerules/,',
+    '.kiro/; copilot is explicit-only). claude+cursor+codex are written when nothing is',
+    'detected.',
     '',
     'Generate a starter 11-layer config:',
     '  ark-check --print-config eleven-layer > ark.config.json',
@@ -192,6 +208,9 @@ function detectConfig(root) {
       name: entry.layer,
       patterns: directories.map((directory) => `${normalize(path.join(srcDir, directory))}/**`),
       intentPrefixes: entry.prefixes,
+      ...(entry.layer === 'DomainModel'
+        ? { forbiddenGlobals: DEFAULT_DOMAIN_FORBIDDEN_GLOBALS }
+        : {}),
     });
   }
 
@@ -415,6 +434,25 @@ args = ["ark-mcp", "--root", ".", "--config", "ark.config.json"]
 `;
 }
 
+/**
+ * Compact always-on rule for instruction-tier hosts (Windsurf, Cline, GitHub Copilot,
+ * Kiro, ...): agents that read a project rule file but have no MCP tools or hooks.
+ * Derived from the same AGENT_CONTRACT as AGENTS.md and the Cursor rule so the steps
+ * can never drift; points at AGENTS.md for the full placement table.
+ */
+function instructionRule() {
+  const steps = AGENT_CONTRACT.steps.map((step, index) => `${index + 1}. ${step}`).join('\n');
+  return `# Ark architecture contract
+
+This project's architecture is governed by Ark (\`ark.config.json\` is authoritative).
+Before writing or editing TypeScript or JavaScript source files:
+
+${steps}
+
+See \`AGENTS.md\` for the full contract and the layer placement table.
+`;
+}
+
 function cursorRule() {
   return `---
 description: Ark architecture contract
@@ -460,6 +498,20 @@ ${setupSteps ? `${setupSteps}\n` : ''}      - run: ${pm.install}
 function claudeSettings() {
   return `${JSON.stringify({
     hooks: {
+      // Inject the contract at session start so the agent knows the architecture from
+      // the first token. Project-scoped by design; --session-context is also a silent
+      // no-op when no ark.config.json exists, so it can never leak into other projects.
+      SessionStart: [
+        {
+          hooks: [
+            {
+              type: 'command',
+              command:
+                'npx ark-mcp --session-context --root "$CLAUDE_PROJECT_DIR" --config ark.config.json',
+            },
+          ],
+        },
+      ],
       PreToolUse: [
         {
           matcher: 'Write|Edit|MultiEdit',
@@ -484,10 +536,17 @@ function resolveTools(args) {
   const detected = new Set();
   if (fs.existsSync(path.join(root, '.claude'))) detected.add('claude');
   if (fs.existsSync(path.join(root, '.cursor'))) detected.add('cursor');
-  if (fs.existsSync(path.join(root, '.codex'))) {
-    detected.add('codex');
+  if (fs.existsSync(path.join(root, '.codex'))) detected.add('codex');
+  if (fs.existsSync(path.join(root, '.windsurf'))) detected.add('windsurf');
+  // .clinerules can also be a single FILE (older Cline convention); only a directory
+  // can receive .clinerules/ark.md, so a file must not trigger detection.
+  if (fs.statSync(path.join(root, '.clinerules'), { throwIfNoEntry: false })?.isDirectory()) {
+    detected.add('cline');
   }
-  // No signal at all: fall back to writing every tool's templates so a fresh
+  if (fs.existsSync(path.join(root, '.kiro'))) detected.add('kiro');
+  // copilot has no reliable directory signal (.github exists in most repos),
+  // so it is explicit-only via --tools.
+  // No signal at all: fall back to writing the primary tools' templates so a fresh
   // project still gets a complete, reviewable starter set.
   if (detected.size === 0) {
     return new Set(['claude', 'cursor', 'codex']);
@@ -495,7 +554,7 @@ function resolveTools(args) {
   return detected;
 }
 
-const KNOWN_TOOLS = ['claude', 'cursor', 'codex'];
+const KNOWN_TOOLS = ['claude', 'cursor', 'codex', 'windsurf', 'cline', 'copilot', 'kiro'];
 
 function runInstallAgentGates(args) {
   const root = args.root;
@@ -529,6 +588,19 @@ function runInstallAgentGates(args) {
   if (tools.has('codex')) {
     templates.push(['docs/ark-codex-config.toml', codexTomlSnippet()]);
   }
+  // Instruction-tier hosts: one shared rule text, host-specific path.
+  if (tools.has('windsurf')) {
+    templates.push(['.windsurf/rules/ark.md', instructionRule()]);
+  }
+  if (tools.has('cline')) {
+    templates.push(['.clinerules/ark.md', instructionRule()]);
+  }
+  if (tools.has('copilot')) {
+    templates.push(['.github/copilot-instructions.md', instructionRule()]);
+  }
+  if (tools.has('kiro')) {
+    templates.push(['.kiro/steering/ark.md', instructionRule()]);
+  }
 
   const results = templates.map(([relativePath, content]) =>
     writeTemplate(root, relativePath, content, args.force)
@@ -652,6 +724,20 @@ function collectConfigWarnings(root, config, files, rules, manifest) {
     if (seenLayers.has(layer.name)) duplicateLayers.add(layer.name);
     seenLayers.add(layer.name);
 
+    if (
+      layer.forbiddenGlobals !== undefined &&
+      (!Array.isArray(layer.forbiddenGlobals) ||
+        layer.forbiddenGlobals.some((entry) => typeof entry !== 'string'))
+    ) {
+      warnings.push(
+        configWarning(
+          'CONFIG_INVALID_FORBIDDEN_GLOBALS',
+          `Layer "${layer.name}" has an invalid forbiddenGlobals value; expected an array of strings (e.g. ["fetch", "Date.now"]). The entry is ignored.`,
+          { layer: layer.name }
+        )
+      );
+    }
+
     const patterns = Array.isArray(layer.patterns) ? layer.patterns : [];
     if (patterns.length === 0) {
       warnings.push(
@@ -759,19 +845,91 @@ function createModuleResolutionHost(ts) {
   };
 }
 
-function loadCompilerOptions(ts, root, tsconfigArg) {
-  const configPath = tsconfigArg
-    ? path.isAbsolute(tsconfigArg)
-      ? tsconfigArg
-      : path.join(root, tsconfigArg)
-    : ts.findConfigFile(root, ts.sys.fileExists, 'tsconfig.json');
-  if (!configPath || !fs.existsSync(configPath)) return {};
+function parseTsconfig(ts, configPath) {
   const read = ts.readConfigFile(configPath, ts.sys.readFile);
   if (read.error) return {};
   const parsed = ts.parseJsonConfigFileContent(read.config, ts.sys, path.dirname(configPath));
   return parsed.options;
 }
 
+/**
+ * Compiler options for a given source file. With --tsconfig every file uses that one
+ * config; otherwise each file uses the NEAREST tsconfig.json above it (like tsc does),
+ * so monorepo packages with per-package path aliases resolve correctly under one --root.
+ */
+function createCompilerOptionsLookup(ts, root, tsconfigArg) {
+  if (tsconfigArg) {
+    const configPath = path.isAbsolute(tsconfigArg) ? tsconfigArg : path.join(root, tsconfigArg);
+    const options = fs.existsSync(configPath) ? parseTsconfig(ts, configPath) : {};
+    return () => options;
+  }
+  const byDir = new Map();
+  const byConfig = new Map();
+  return (file) => {
+    const dir = path.dirname(file);
+    if (byDir.has(dir)) return byDir.get(dir);
+    const configPath = ts.findConfigFile(dir, ts.sys.fileExists, 'tsconfig.json');
+    let options = {};
+    if (configPath) {
+      if (!byConfig.has(configPath)) byConfig.set(configPath, parseTsconfig(ts, configPath));
+      options = byConfig.get(configPath);
+    }
+    byDir.set(dir, options);
+    return options;
+  };
+}
+
+/**
+ * Per-file scan cache. A cache entry stores the parsed file's content-derived results:
+ * content violations (forbidden globals, publish checks, intent references) and the list
+ * of module-edge specifiers. Edges are NEVER cached as violations — they are re-resolved
+ * against the live filesystem every run, because resolution depends on files and tsconfigs
+ * outside the cached file. The whole cache is keyed by the config+manifest contents, so
+ * any rule change invalidates everything.
+ */
+function scanCachePath(root) {
+  return path.join(root, 'node_modules', '.cache', 'ark-check.json');
+}
+
+function scanCacheKey(root, args) {
+  const read = (p) => {
+    try {
+      return fs.readFileSync(p, 'utf8');
+    } catch {
+      return '';
+    }
+  };
+  const configPath = path.isAbsolute(args.config) ? args.config : path.join(root, args.config);
+  const manifestPath = args.manifest
+    ? path.isAbsolute(args.manifest)
+      ? args.manifest
+      : path.join(root, args.manifest)
+    : undefined;
+  return crypto
+    .createHash('sha1')
+    .update(`ark-check-cache-v1\0${read(configPath)}\0${manifestPath ? read(manifestPath) : ''}`)
+    .digest('hex');
+}
+
+function loadScanCache(root, key) {
+  try {
+    const data = JSON.parse(fs.readFileSync(scanCachePath(root), 'utf8'));
+    return data.key === key && data.files && typeof data.files === 'object' ? data.files : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+function saveScanCache(root, key, files) {
+  try {
+    const target = scanCachePath(root);
+    fs.mkdirSync(path.dirname(target), { recursive: true });
+    fs.writeFileSync(target, JSON.stringify({ key, files }));
+  } catch {
+    // cache is best-effort: read-only filesystems just re-parse every run
+  }
+}
+
 /**
  * Fallback resolver for extensionless relative imports whose on-disk target uses an
  * extension `ts.resolveModuleName` won't resolve without a matching tsconfig
@@ -816,8 +974,9 @@ function resolveRelativeFallback(fromFile, specifier) {
  * path RELATIVE TO ROOT either escapes the root (leading `..`) or contains a `node_modules`
  * segment. Using the root-relative path (not an absolute substring) means a project that
  * itself lives under a node_modules segment is still governed, while a broad catch-all
- * pattern (`**`) can't false-flag vendored deps or files outside the project. For monorepos,
- * run ark-check per package rather than reaching across package roots.
+ * pattern (`**`) can't false-flag vendored deps or files outside the project. Monorepos can
+ * run under a single --root (per-package tsconfigs are honored via the nearest-tsconfig
+ * lookup); edges that resolve outside the root are still skipped.
  */
 function resolveImport(ts, specifier, containingFile, options, host, root) {
   const res = ts.resolveModuleName(specifier, containingFile, options, host);
@@ -931,7 +1090,7 @@ function publishHasSource(ts, node) {
   );
 }
 
-// ponytail: baseline keys exclude the line number so unrelated edits that shift lines
+// Baseline keys exclude the line number so unrelated edits that shift lines
 // don't resurrect frozen violations; the trade-off is that N identical violations in one
 // file collapse to one key.
 function baselineKey(violation) {
@@ -981,6 +1140,8 @@ const FIX_HINTS = {
     'Add metadata.source (the publishing intent name) to the publish call.',
   PUBLISH_SOURCE_LAYER_MISMATCH:
     'Use a source intent that belongs to the same layer as the publishing file, or move the file.',
+  FORBIDDEN_GLOBAL:
+    'Inject the capability through a port (e.g. a Clock, IdGenerator, or HttpPort) instead of reaching for the ambient global.',
 };
 
 function printViolation(violation) {
@@ -1081,35 +1242,41 @@ async function main() {
   const manifest = readManifest(root, args.manifest);
   const rules = manifest?.architecture?.rules ?? config.rules;
   const manifestIntentLayers = intentLayersFromManifest(manifest);
-  const compilerOptions = loadCompilerOptions(ts, root, args.tsconfig);
+  const compilerOptionsFor = createCompilerOptionsLookup(ts, root, args.tsconfig);
   const moduleHost = createModuleResolutionHost(ts);
   const files = config.include.flatMap((entry) => walk(path.join(root, entry)));
   const violations = [];
   const warnings = collectConfigWarnings(root, config, files, rules, manifest);
-
-  for (const file of files) {
+  const cacheKey = args.noCache ? undefined : scanCacheKey(root, args);
+  const cachedFiles = cacheKey ? loadScanCache(root, cacheKey) : undefined;
+  const nextCacheFiles = {};
+
+  // Parses one file and returns its cacheable scan result: violations derived purely from
+  // the file's content (+config/manifest, hashed into the cache key) and the module-edge
+  // specifiers found, which the driver loop below resolves fresh on every run.
+  function scanSourceFile(file, sourceLayer) {
     const source = fs.readFileSync(file, 'utf8');
     const sourceFile = ts.createSourceFile(file, source, ts.ScriptTarget.Latest, true);
-    const sourceLayer = layerForFile(root, file, config.layers);
-    if (!sourceLayer) continue;
+    const violations = [];
+    const edges = [];
+
+    const layerConfig = config.layers.find((layer) => layer.name === sourceLayer);
+    const forbiddenGlobals = Array.isArray(layerConfig?.forbiddenGlobals)
+      ? layerConfig.forbiddenGlobals.filter((entry) => typeof entry === 'string')
+      : [];
+    for (const use of collectForbiddenGlobalUses(ts, sourceFile, forbiddenGlobals)) {
+      violations.push({
+        ruleId: 'FORBIDDEN_GLOBAL',
+        file: normalize(path.relative(root, file)),
+        line: lineOf(sourceFile, use.node.getStart(sourceFile)),
+        fromLayer: sourceLayer,
+        target: use.name,
+        message: `${sourceLayer} must not use the ambient global "${use.name}".`,
+      });
+    }
 
     const checkModuleEdge = (specifier, node, kind) => {
-      const target = resolveImport(ts, specifier, file, compilerOptions, moduleHost, root);
-      const targetLayer = target ? layerForFile(root, target, config.layers) : undefined;
-      const rule = targetLayer ? isBlocked(rules, sourceLayer, targetLayer) : undefined;
-      if (rule) {
-        violations.push({
-          ruleId: 'LAYER_IMPORT_VIOLATION',
-          file: normalize(path.relative(root, file)),
-          line: lineOf(sourceFile, node.getStart(sourceFile)),
-          fromLayer: sourceLayer,
-          toLayer: targetLayer,
-          target: normalize(path.relative(root, target)),
-          message:
-            rule.message ??
-            `${sourceLayer} must not ${kind} ${targetLayer}.`,
-        });
-      }
+      edges.push({ specifier, line: lineOf(sourceFile, node.getStart(sourceFile)), kind });
     };
 
     const visit = (node) => {
@@ -1196,8 +1363,43 @@ async function main() {
       ts.forEachChild(node, visit);
     };
     visit(sourceFile);
+    return { contentViolations: violations, edges };
+  }
+
+  for (const file of files) {
+    const sourceLayer = layerForFile(root, file, config.layers);
+    if (!sourceLayer) continue;
+    const relFile = normalize(path.relative(root, file));
+    const stat = fs.statSync(file);
+    const fileKey = `${stat.mtimeMs}:${stat.size}`;
+    const cached = cachedFiles?.[relFile];
+    const entry =
+      cached && cached.fileKey === fileKey
+        ? cached
+        : { fileKey, ...scanSourceFile(file, sourceLayer) };
+    nextCacheFiles[relFile] = entry;
+
+    violations.push(...entry.contentViolations);
+    for (const edge of entry.edges) {
+      const target = resolveImport(ts, edge.specifier, file, compilerOptionsFor(file), moduleHost, root);
+      const targetLayer = target ? layerForFile(root, target, config.layers) : undefined;
+      const rule = targetLayer ? isBlocked(rules, sourceLayer, targetLayer) : undefined;
+      if (rule) {
+        violations.push({
+          ruleId: 'LAYER_IMPORT_VIOLATION',
+          file: relFile,
+          line: edge.line,
+          fromLayer: sourceLayer,
+          toLayer: targetLayer,
+          target: normalize(path.relative(root, target)),
+          message: rule.message ?? `${sourceLayer} must not ${edge.kind} ${targetLayer}.`,
+        });
+      }
+    }
   }
 
+  if (cacheKey) saveScanCache(root, cacheKey, nextCacheFiles);
+
   if (args.updateBaseline) {
     const { fullPath, count } = writeBaseline(root, args.baseline, violations);
     console.log(`Wrote ${fullPath} with ${count} frozen violation key(s).`);