arkgate 2.12.0 → 2.13.0

package/dist/index.cjs

@@ -20,6 +20,7 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/index.ts
 var index_exports = {};
 __export(index_exports, {
+  ANALYSIS_IR_SCHEMA_VERSION: () => ANALYSIS_IR_SCHEMA_VERSION,
   DEFAULT_MAX_HISTORY_SIZE: () => DEFAULT_MAX_HISTORY_SIZE,
   EventContractRegistryImpl: () => EventContractRegistryImpl,
   EventContractViolationError: () => EventContractViolationError,
@@ -37,6 +38,8 @@ __export(index_exports, {
   SourceMetadataOverrideError: () => SourceMetadataOverrideError,
   UnknownEventSourceError: () => UnknownEventSourceError,
   UnregisteredIntentError: () => UnregisteredIntentError,
+  analyzeChange: () => analyzeChange,
+  analyzeProject: () => analyzeProject,
   architecturalPolicies: () => architecturalPolicies,
   buildPublishPolicyContext: () => buildPublishPolicyContext,
   checkAdapterGovernance: () => checkAdapterGovernance,
@@ -71,8 +74,12 @@ __export(index_exports, {
   definePolicy: () => definePolicy,
   definePort: () => definePort,
   definePublishPolicy: () => definePublishPolicy,
+  deterministicHash: () => deterministicHash,
   elevenLayerProfile: () => elevenLayerProfile,
+  explainViolation: () => explainViolation,
   isLayerPolicy: () => isLayerPolicy,
+  loadContract: () => loadContract,
+  stableSerialize: () => stableSerialize,
   syncRegistryToGraph: () => syncRegistryToGraph,
   validateIntentName: () => validateIntentName,
   version: () => version
@@ -80,7 +87,7 @@ __export(index_exports, {
 module.exports = __toCommonJS(index_exports);
 
 // src/version.ts
-var version = "2.12.0";
+var version = "2.13.0";
 
 // src/kernel/intent/IntentRegistry.ts
 var IntentRegistry = class {
@@ -744,6 +751,10 @@ async function recordInterceptorError(interceptor, event, error, deps) {
 }
 
 // src/domain/layerMatch.ts
+var regexpCache = /* @__PURE__ */ new Map();
+function escapeLiteral(ch) {
+  return /[.*+?^${}()|[\]\\]/.test(ch) ? `\\${ch}` : ch;
+}
 function normalizeGlobSeparators(pattern) {
   let out = "";
   for (let i = 0; i < pattern.length; i += 1) {
@@ -762,6 +773,91 @@ function normalizeGlobSeparators(pattern) {
   }
   return out;
 }
+function bracesBalanced(glob) {
+  let depth = 0;
+  for (let i = 0; i < glob.length; i += 1) {
+    const c = glob[i];
+    if (c === "\\") {
+      i += 1;
+      continue;
+    }
+    if (c === "{") depth += 1;
+    else if (c === "}") {
+      depth -= 1;
+      if (depth < 0) return false;
+    }
+  }
+  return depth === 0;
+}
+function globToRegExp(pattern) {
+  const cached = regexpCache.get(pattern);
+  if (cached) return cached;
+  const glob = normalizeGlobSeparators(pattern);
+  const useBraces = bracesBalanced(glob);
+  let out = "";
+  let braceDepth = 0;
+  for (let i = 0; i < glob.length; i += 1) {
+    const c = glob[i];
+    if (c === "\\" && i + 1 < glob.length) {
+      out += escapeLiteral(glob[i + 1]);
+      i += 1;
+    } else if (c === "*") {
+      if (glob[i + 1] === "*") {
+        if (glob[i + 2] === "/") {
+          out += "(?:.*/)?";
+          i += 2;
+        } else {
+          out += ".*";
+          i += 1;
+        }
+      } else {
+        out += "[^/]*";
+      }
+    } else if (c === "?") {
+      out += "[^/]";
+    } else if (c === "{" && useBraces) {
+      out += "(?:";
+      braceDepth += 1;
+    } else if (c === "}" && useBraces && braceDepth > 0) {
+      out += ")";
+      braceDepth -= 1;
+    } else if (c === "," && useBraces && braceDepth > 0) {
+      out += "|";
+    } else {
+      out += escapeLiteral(c);
+    }
+  }
+  const re = new RegExp(`^${out}$`);
+  regexpCache.set(pattern, re);
+  return re;
+}
+function patternSpecificity(pattern) {
+  const glob = normalizeGlobSeparators(String(pattern));
+  const beforeWildcard = glob.split("*")[0];
+  const literalSegments = beforeWildcard.split("/").filter(Boolean).length;
+  const literalLength = glob.replace(/\*/g, "").length;
+  return literalSegments * 1e4 + literalLength;
+}
+function layerForRelativePath(relPath, layers) {
+  const rel = String(relPath).split(/[/\\]/).join("/");
+  let bestName;
+  let bestScore = -1;
+  for (const layer of layers ?? []) {
+    if ((layer.exclude ?? []).some((pattern) => globToRegExp(pattern).test(rel))) {
+      continue;
+    }
+    for (const pattern of layer.patterns ?? []) {
+      if (globToRegExp(pattern).test(rel)) {
+        const score = patternSpecificity(pattern);
+        if (score > bestScore) {
+          bestScore = score;
+          bestName = layer.name;
+        }
+      }
+    }
+  }
+  return bestName;
+}
 function sliceIdForPath(relPath, sliceFolders) {
   if (!sliceFolders?.length) return void 0;
   const parts = String(relPath).split(/[/\\]/).filter(Boolean);
@@ -1356,13 +1452,13 @@ function formatPath(parent, field) {
   return parent ? `${parent}.${field}` : field;
 }
 function validateSchemaField(value, fieldSchema, path, contract, issues) {
-  const valueType = actualType(value);
-  if (fieldSchema.type !== "unknown" && valueType !== fieldSchema.type) {
+  const valueType2 = actualType(value);
+  if (fieldSchema.type !== "unknown" && valueType2 !== fieldSchema.type) {
     issues.push({
       intent: contract.intent,
       version: contract.version,
       field: path,
-      message: `Expected ${fieldSchema.type}, received ${valueType}.`
+      message: `Expected ${fieldSchema.type}, received ${valueType2}.`
     });
     return;
   }
@@ -1919,6 +2015,321 @@ function syncRegistryToGraph(registry, graph, options = {}) {
   }
 }
 
+// src/domain/configContract.ts
+var ARK_CONFIG_SCHEMA_VERSION = "1.0";
+var ARK_CONFIG_SCHEMA_URL = "https://unpkg.com/arkgate@2/schemas/ark.config.schema.json";
+var DEFAULT_LAYER_NAMES = [
+  "DomainModel",
+  "ApplicationOrchestration",
+  "PersistenceAdapters",
+  "IntegrationAdapters",
+  "WorkflowSagaEngine",
+  "BackgroundJobsScheduling",
+  "PresentationAdapters",
+  "ReportingReadModels",
+  "ExtensibilityMetadata",
+  "SecurityAuditObservability",
+  "Kernel"
+];
+var DEFAULT_ALLOWED_FLOWS = /* @__PURE__ */ new Set([
+  "PresentationAdapters->ApplicationOrchestration",
+  "ApplicationOrchestration->DomainModel",
+  "WorkflowSagaEngine->ApplicationOrchestration",
+  "WorkflowSagaEngine->DomainModel",
+  "BackgroundJobsScheduling->ApplicationOrchestration"
+]);
+function createDefaultRules() {
+  const rules = [];
+  for (const from of DEFAULT_LAYER_NAMES) {
+    for (const to of DEFAULT_LAYER_NAMES) {
+      if (from === to || DEFAULT_ALLOWED_FLOWS.has(`${from}->${to}`)) continue;
+      rules.push({ from, to, allowed: false });
+    }
+  }
+  return rules;
+}
+var DEFAULT_ARK_CONFIG_RULES = createDefaultRules();
+var stringArraySchema = {
+  type: "array",
+  items: { type: "string", minLength: 1 },
+  uniqueItems: true
+};
+var ARK_CONFIG_SCHEMA = {
+  $schema: "https://json-schema.org/draft/2020-12/schema",
+  $id: ARK_CONFIG_SCHEMA_URL,
+  title: "ArkGate architecture contract",
+  description: "Versioned contract consumed identically by ArkGate CLI, MCP, and ESLint surfaces.",
+  type: "object",
+  additionalProperties: false,
+  required: ["$schema", "schemaVersion", "include", "layers", "rules"],
+  properties: {
+    $schema: {
+      type: "string",
+      minLength: 1,
+      default: ARK_CONFIG_SCHEMA_URL,
+      description: "Editor-facing URL or local path for this JSON Schema."
+    },
+    schemaVersion: {
+      type: "string",
+      const: ARK_CONFIG_SCHEMA_VERSION,
+      default: ARK_CONFIG_SCHEMA_VERSION
+    },
+    name: { type: "string", minLength: 1 },
+    include: { ...stringArraySchema, minItems: 1, default: ["src"] },
+    exclude: { ...stringArraySchema, default: [] },
+    excludeGenerated: { type: "boolean", default: true },
+    frameworkOverlay: { type: "string", minLength: 1 },
+    layers: {
+      type: "array",
+      default: [],
+      items: { $ref: "#/$defs/layer" }
+    },
+    rules: {
+      type: "array",
+      default: DEFAULT_ARK_CONFIG_RULES,
+      items: { $ref: "#/$defs/rule" }
+    },
+    cyclePolicy: {
+      type: "string",
+      enum: ["strict", "soft", "framework-soft", "off"],
+      default: "strict"
+    },
+    dynamicImportAllowlist: { ...stringArraySchema, default: [] },
+    safety: {
+      $ref: "#/$defs/safety",
+      default: {
+        maxTsSuppressions: 0,
+        maxAnyCasts: 0,
+        allowInMemory: false,
+        allowDisabledPeerIsolation: false
+      }
+    }
+  },
+  $defs: {
+    layer: {
+      type: "object",
+      additionalProperties: false,
+      required: ["name", "patterns"],
+      properties: {
+        name: { type: "string", minLength: 1 },
+        patterns: { ...stringArraySchema, minItems: 1 },
+        exclude: stringArraySchema,
+        intentPrefixes: stringArraySchema,
+        description: { type: "string", minLength: 1 },
+        forbiddenGlobals: stringArraySchema,
+        mayImportInfrastructure: { type: "boolean" },
+        optional: { type: "boolean" }
+      }
+    },
+    rule: {
+      type: "object",
+      additionalProperties: false,
+      required: ["from", "to", "allowed"],
+      properties: {
+        from: { type: "string", minLength: 1 },
+        to: { type: "string", minLength: 1 },
+        allowed: { type: "boolean" },
+        message: { type: "string", minLength: 1 },
+        peerIsolation: { type: "boolean" },
+        sliceFolders: { ...stringArraySchema, minItems: 1 }
+      }
+    },
+    safety: {
+      type: "object",
+      additionalProperties: false,
+      properties: {
+        maxTsSuppressions: { type: "integer", minimum: 0, default: 0 },
+        maxAnyCasts: { type: "integer", minimum: 0, default: 0 },
+        allowInMemory: { type: "boolean", default: false },
+        allowDisabledPeerIsolation: { type: "boolean", default: false }
+      }
+    }
+  }
+};
+var ArkConfigValidationError = class extends Error {
+  issues;
+  source;
+  constructor(source, issues) {
+    super(
+      `Invalid ArkGate config (${source}):
+${issues.map((issue) => `- ${issue.path}: ${issue.message}`).join("\n")}`
+    );
+    this.name = "ArkConfigValidationError";
+    this.source = source;
+    this.issues = issues;
+  }
+};
+function isObject(value) {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function propertyPath(parent, key) {
+  return /^[A-Za-z_$][A-Za-z0-9_$]*$/.test(key) ? `${parent}.${key}` : `${parent}[${JSON.stringify(key)}]`;
+}
+function valueType(value) {
+  if (value === null) return "null";
+  if (Array.isArray(value)) return "array";
+  return typeof value;
+}
+function resolveSchemaRef(ref, root) {
+  const prefix = "#/$defs/";
+  if (!ref.startsWith(prefix)) return void 0;
+  return root.$defs[ref.slice(prefix.length)];
+}
+function validateNode(value, schema, path, root, issues) {
+  if (schema.$ref) {
+    const referenced = resolveSchemaRef(schema.$ref, root);
+    if (!referenced) {
+      issues.push({ path, message: `schema reference ${schema.$ref} cannot be resolved` });
+      return;
+    }
+    validateNode(value, referenced, path, root, issues);
+    return;
+  }
+  if (schema.const !== void 0 && !Object.is(value, schema.const)) {
+    issues.push({ path, message: `must equal ${JSON.stringify(schema.const)}` });
+    return;
+  }
+  if (schema.enum && !schema.enum.some((candidate) => Object.is(candidate, value))) {
+    issues.push({ path, message: `must be one of ${schema.enum.map(String).join(", ")}` });
+    return;
+  }
+  if (schema.type === "object") {
+    if (!isObject(value)) {
+      issues.push({ path, message: `must be an object; received ${valueType(value)}` });
+      return;
+    }
+    const properties = schema.properties ?? {};
+    for (const key of schema.required ?? []) {
+      if (value[key] === void 0) {
+        issues.push({ path: propertyPath(path, key), message: "is required" });
+      }
+    }
+    if (schema.additionalProperties === false) {
+      for (const key of Object.keys(value)) {
+        if (!(key in properties)) {
+          issues.push({ path: propertyPath(path, key), message: "unknown field" });
+        }
+      }
+    }
+    for (const [key, childSchema] of Object.entries(properties)) {
+      if (value[key] !== void 0) {
+        validateNode(value[key], childSchema, propertyPath(path, key), root, issues);
+      }
+    }
+    return;
+  }
+  if (schema.type === "array") {
+    if (!Array.isArray(value)) {
+      issues.push({ path, message: `must be an array; received ${valueType(value)}` });
+      return;
+    }
+    if (schema.minItems !== void 0 && value.length < schema.minItems) {
+      issues.push({ path, message: `must contain at least ${schema.minItems} item(s)` });
+    }
+    if (schema.uniqueItems) {
+      const serialized = value.map((entry) => JSON.stringify(entry));
+      if (new Set(serialized).size !== serialized.length) {
+        issues.push({ path, message: "must not contain duplicate items" });
+      }
+    }
+    if (schema.items) {
+      value.forEach(
+        (entry, index) => validateNode(entry, schema.items, `${path}[${index}]`, root, issues)
+      );
+    }
+    return;
+  }
+  if (schema.type === "string") {
+    if (typeof value !== "string") {
+      issues.push({ path, message: `must be a string; received ${valueType(value)}` });
+      return;
+    }
+    if (schema.minLength !== void 0 && value.length < schema.minLength) {
+      issues.push({ path, message: `must contain at least ${schema.minLength} character(s)` });
+    }
+    return;
+  }
+  if (schema.type === "boolean") {
+    if (typeof value !== "boolean") {
+      issues.push({ path, message: `must be a boolean; received ${valueType(value)}` });
+    }
+    return;
+  }
+  if (schema.type === "integer") {
+    if (!Number.isInteger(value)) {
+      issues.push({ path, message: `must be an integer; received ${valueType(value)}` });
+      return;
+    }
+    if (schema.minimum !== void 0 && value < schema.minimum) {
+      issues.push({ path, message: `must be at least ${schema.minimum}` });
+    }
+  }
+}
+function defaultedConfig(input) {
+  return {
+    ...input,
+    $schema: input.$schema === void 0 ? ARK_CONFIG_SCHEMA_URL : input.$schema,
+    schemaVersion: input.schemaVersion === void 0 ? ARK_CONFIG_SCHEMA_VERSION : input.schemaVersion,
+    include: input.include === void 0 ? ["src"] : input.include,
+    layers: input.layers === void 0 ? [] : input.layers,
+    rules: input.rules === void 0 ? DEFAULT_ARK_CONFIG_RULES.map((rule) => ({ ...rule })) : input.rules
+  };
+}
+function migrateArkConfig(input, source = "ark.config.json") {
+  if (!isObject(input)) {
+    throw new ArkConfigValidationError(source, [
+      { path: "$", message: `must be an object; received ${valueType(input)}` }
+    ]);
+  }
+  const migratedFrom = input.schemaVersion === void 0 ? "unversioned" : null;
+  if (input.schemaVersion !== void 0 && input.schemaVersion !== ARK_CONFIG_SCHEMA_VERSION) {
+    throw new ArkConfigValidationError(source, [
+      {
+        path: "$.schemaVersion",
+        message: `unsupported version ${JSON.stringify(input.schemaVersion)}; expected ${ARK_CONFIG_SCHEMA_VERSION}`
+      }
+    ]);
+  }
+  return { candidate: defaultedConfig(input), migratedFrom };
+}
+function loadArkConfigContract(input, source = "ark.config.json") {
+  const { candidate, migratedFrom } = migrateArkConfig(input, source);
+  const issues = [];
+  validateNode(
+    candidate,
+    ARK_CONFIG_SCHEMA,
+    "$",
+    ARK_CONFIG_SCHEMA,
+    issues
+  );
+  if (issues.length > 0) throw new ArkConfigValidationError(source, issues);
+  return { config: candidate, migratedFrom };
+}
+function parseArkConfigJson(json, source = "ark.config.json") {
+  let input;
+  try {
+    input = JSON.parse(json);
+  } catch (error) {
+    throw new ArkConfigValidationError(source, [
+      {
+        path: "$",
+        message: `invalid JSON: ${error instanceof Error ? error.message : String(error)}`
+      }
+    ]);
+  }
+  return loadArkConfigContract(input, source);
+}
+function withArkConfigMetadata(config) {
+  const result = {
+    $schema: typeof config.$schema === "string" && config.$schema.length > 0 ? config.$schema : ARK_CONFIG_SCHEMA_URL,
+    schemaVersion: ARK_CONFIG_SCHEMA_VERSION
+  };
+  for (const [key, value] of Object.entries(config)) {
+    if (key !== "$schema" && key !== "schemaVersion") result[key] = value;
+  }
+  return result;
+}
+
 // src/kernel/layers/ArchitectureProfile.ts
 function normalizePrefix(prefix) {
   return prefix.endsWith(".") ? prefix : `${prefix}.`;
@@ -1928,21 +2339,6 @@ function byLongestPrefix(a, b) {
   const maxB = b.prefixes.length ? Math.max(...b.prefixes.map((p) => p.length)) : 0;
   return maxB - maxA;
 }
-function flowKey2(from, to) {
-  return `${from}->${to}`;
-}
-function createStrictDenyRules(layers, allowedFlows) {
-  const allowed = new Set(allowedFlows.map((flow) => flowKey2(flow.from, flow.to)));
-  const rules = [];
-  for (const from of layers) {
-    for (const to of layers) {
-      if (from.name === to.name) continue;
-      if (allowed.has(flowKey2(from.name, to.name))) continue;
-      rules.push({ from: from.name, to: to.name, allowed: false });
-    }
-  }
-  return rules;
-}
 function createArchitectureProfile(options) {
   const layers = options.layers.map((layer) => ({
     ...layer,
@@ -2041,20 +2437,10 @@ var elevenLayerProfileLayers = [
     order: 11
   }
 ];
-var elevenLayerAllowedFlows = [
-  { from: "PresentationAdapters", to: "ApplicationOrchestration" },
-  { from: "ApplicationOrchestration", to: "DomainModel" },
-  { from: "WorkflowSagaEngine", to: "ApplicationOrchestration" },
-  { from: "WorkflowSagaEngine", to: "DomainModel" },
-  { from: "BackgroundJobsScheduling", to: "ApplicationOrchestration" }
-];
 var elevenLayerProfile = createArchitectureProfile({
   name: "Ark 11-layer Hexagonal Event-Driven Profile",
   layers: elevenLayerProfileLayers,
-  rules: createStrictDenyRules(
-    elevenLayerProfileLayers,
-    elevenLayerAllowedFlows
-  )
+  rules: DEFAULT_ARK_CONFIG_RULES.map((rule) => ({ ...rule }))
 });
 var defaultElevenLayerDirectories = {
   DomainModel: ["domain"],
@@ -2078,7 +2464,7 @@ function createElevenLayerArkConfig(options = {}) {
   const rootDir = options.rootDir ?? "src";
   const optional = options.optionalLayers ?? true;
   const prefix = rootDir === "." ? "" : `${rootDir}/`;
-  return {
+  return withArkConfigMetadata({
     include: options.include ?? [rootDir],
     layers: elevenLayerProfile.layers.map((layer) => ({
       name: layer.name,
@@ -2089,7 +2475,7 @@ function createElevenLayerArkConfig(options = {}) {
       optional
     })),
     rules: [...elevenLayerProfile.rules]
-  };
+  });
 }
 
 // src/kernel/metadata/MetadataRegistry.ts
@@ -2293,7 +2679,11 @@ function extractModuleSpecifiersAst(ts, source) {
         "export",
         Boolean(node.isTypeOnly || specifiersOnly)
       );
-    } else if (ts.isCallExpression(node) && node.arguments.length === 1) {
+    } else if (ts.isImportEqualsDeclaration(node) && ts.isExternalModuleReference(node.moduleReference)) {
+      const argument = node.moduleReference.expression;
+      const value = tsStringLiteralText(ts, argument);
+      if (value !== void 0) push(argument, value, "require");
+    } else if (ts.isCallExpression(node)) {
       const argument = node.arguments[0];
       const value = tsStringLiteralText(ts, argument);
       if (value !== void 0 && node.expression.kind === ts.SyntaxKind.ImportKeyword) {
@@ -2307,17 +2697,25 @@ function extractModuleSpecifiersAst(ts, source) {
   visit(sourceFile);
   return matches.sort((a, b) => a.index - b.index);
 }
-function nonLiteralDynamicImportLines(ts, source) {
+function nonLiteralDynamicDependencies(ts, source) {
   const sourceFile = ts.createSourceFile("generated.ts", source, ts.ScriptTarget.Latest, true);
-  const lines = [];
+  const uses = [];
   const visit = (node) => {
-    if (ts.isCallExpression(node) && node.expression.kind === ts.SyntaxKind.ImportKeyword && (!node.arguments[0] || !ts.isStringLiteralLike(node.arguments[0]))) {
-      lines.push(sourceFile.getLineAndCharacterOfPosition(node.getStart(sourceFile)).line + 1);
+    if (ts.isCallExpression(node)) {
+      const dynamicImport = node.expression.kind === ts.SyntaxKind.ImportKeyword;
+      const directRequire = ts.isIdentifier(node.expression) && node.expression.text === "require";
+      const argument = node.arguments[0];
+      if ((dynamicImport || directRequire) && (!argument || !ts.isStringLiteralLike(argument))) {
+        uses.push({
+          line: sourceFile.getLineAndCharacterOfPosition(node.getStart(sourceFile)).line + 1,
+          kind: directRequire ? "require" : "import"
+        });
+      }
     }
     ts.forEachChild(node, visit);
   };
   visit(sourceFile);
-  return lines;
+  return uses;
 }
 function extractQuotedStringsAst(ts, source) {
   const sourceFile = ts.createSourceFile("generated.ts", source, ts.ScriptTarget.Latest, true);
@@ -2428,10 +2826,45 @@ function tsPublishSourceLiteral(ts, node) {
   const rawMetadata = tsObjectPropertyValue(ts, firstArg, "metadata");
   return tsStringLiteralText(ts, tsObjectPropertyValue(ts, rawMetadata, "source")) ?? tsStringLiteralText(ts, tsObjectPropertyValue(ts, secondArg, "source")) ?? tsStringLiteralText(ts, tsObjectPropertyValue(ts, thirdArg, "source"));
 }
+function singleFileTypeChecker(ts, sourceFile) {
+  const options = {
+    noLib: true,
+    noResolve: true,
+    target: ts.ScriptTarget.Latest
+  };
+  const host = ts.createCompilerHost(options, true);
+  host.getSourceFile = (fileName) => fileName === sourceFile.fileName ? sourceFile : void 0;
+  host.fileExists = (fileName) => fileName === sourceFile.fileName;
+  host.readFile = (fileName) => fileName === sourceFile.fileName ? sourceFile.text : void 0;
+  return ts.createProgram([sourceFile.fileName], options, host).getTypeChecker();
+}
+function propertyAccessPath(ts, node) {
+  const segments = [];
+  let current = node;
+  while (ts.isPropertyAccessExpression(current)) {
+    segments.unshift(current.name.text);
+    current = current.expression;
+  }
+  if (!ts.isIdentifier(current)) return void 0;
+  segments.unshift(current.text);
+  return { root: current, segments };
+}
+function isRuntimeIdentifierReference(ts, node) {
+  if (ts.isPropertyAccessExpression(node.parent) && node.parent.name === node) return false;
+  return ts.isExpressionNode(node) && !ts.isInTypeQuery(node) || ts.isShorthandPropertyAssignment(node.parent) && node.parent.name === node;
+}
+function hasLocalDeclaration(ts, checker, sourceFile, node) {
+  const shorthand = ts.isShorthandPropertyAssignment(node.parent) && node.parent.name === node;
+  const symbol = shorthand ? checker.getShorthandAssignmentValueSymbol(node.parent) : checker.getSymbolAtLocation(node);
+  return Boolean(
+    symbol?.declarations?.some((declaration) => declaration.getSourceFile() === sourceFile)
+  );
+}
 function analyzeForbiddenGlobals(ts, source, filePath, layer, forbidden) {
   const entries = new Set(forbidden);
   if (entries.size === 0) return [];
   const sourceFile = ts.createSourceFile("generated.ts", source, ts.ScriptTarget.Latest, true);
+  const checker = singleFileTypeChecker(ts, sourceFile);
   const violations = [];
   const flag = (name, node) => violations.push(
     violation("FORBIDDEN_GLOBAL", `${layer} must not use the ambient global "${name}".`, {
@@ -2443,12 +2876,24 @@ function analyzeForbiddenGlobals(ts, source, filePath, layer, forbidden) {
     })
   );
   const visit = (node) => {
-    if (ts.isPropertyAccessExpression(node) && ts.isIdentifier(node.expression)) {
-      const dotted = `${node.expression.text}.${node.name.text}`;
-      if (entries.has(dotted)) flag(dotted, node);
-      else if (entries.has(node.expression.text)) flag(node.expression.text, node);
-    } else if ((ts.isCallExpression(node) || ts.isNewExpression(node)) && node.expression && ts.isIdentifier(node.expression) && entries.has(node.expression.text)) {
-      flag(node.expression.text, node);
+    const nestedPropertyAccess = ts.isPropertyAccessExpression(node) && ts.isPropertyAccessExpression(node.parent) && node.parent.expression === node;
+    if (ts.isPropertyAccessExpression(node) && !nestedPropertyAccess) {
+      const path = propertyAccessPath(ts, node);
+      if (path && !hasLocalDeclaration(ts, checker, sourceFile, path.root)) {
+        const explicitGlobalThis = path.segments[0] === "globalThis";
+        const normalized = explicitGlobalThis ? path.segments.slice(1) : path.segments;
+        let match;
+        for (let length = normalized.length; length >= (explicitGlobalThis ? 1 : 2); length -= 1) {
+          const candidate = normalized.slice(0, length).join(".");
+          if (entries.has(candidate)) {
+            match = candidate;
+            break;
+          }
+        }
+        if (match) flag(match, node);
+      }
+    } else if (ts.isIdentifier(node) && entries.has(node.text) && isRuntimeIdentifierReference(ts, node) && !hasLocalDeclaration(ts, checker, sourceFile, node)) {
+      flag(node.text, node);
     }
     ts.forEachChild(node, visit);
   };
@@ -2525,15 +2970,16 @@ function createAICodeGate(options = {}) {
       const gateContext = context;
       const filePath = gateContext?.filePath;
       const contextLayer = gateContext?.layer;
-      const moduleSpecifiers = options.typescript ? extractModuleSpecifiersAst(options.typescript, source) : extractModuleSpecifiers(source);
+      const moduleSpecifiers2 = options.typescript ? extractModuleSpecifiersAst(options.typescript, source) : extractModuleSpecifiers(source);
       const quotedStrings = options.typescript ? extractQuotedStringsAst(options.typescript, source) : extractQuotedStrings(source);
       if (options.typescript && !options.allowNonLiteralDynamicImport?.(filePath)) {
-        for (const line of nonLiteralDynamicImportLines(options.typescript, source)) {
+        for (const dependency of nonLiteralDynamicDependencies(options.typescript, source)) {
+          const isRequire = dependency.kind === "require";
           violations.push(
             violation(
-              "DYNAMIC_IMPORT_NOT_ALLOWLISTED",
-              "Non-literal dynamic import cannot be resolved statically; add the reviewed file to dynamicImportAllowlist.",
-              { line, filePath }
+              isRequire ? "DYNAMIC_REQUIRE_NOT_ALLOWLISTED" : "DYNAMIC_IMPORT_NOT_ALLOWLISTED",
+              `Non-literal ${isRequire ? "require call" : "dynamic import"} cannot be resolved statically; add the reviewed file to dynamicImportAllowlist.`,
+              { line: dependency.line, filePath }
             )
           );
         }
@@ -2563,7 +3009,7 @@ function createAICodeGate(options = {}) {
           );
         }
       }
-      for (const specifier of moduleSpecifiers) {
+      for (const specifier of moduleSpecifiers2) {
         const targetHit = options.resolveImportTarget?.(specifier.value, filePath) ?? (options.resolveImportLayer ? { layer: options.resolveImportLayer(specifier.value, filePath) } : void 0);
         const sourceHit = typeof filePath === "string" ? options.resolveImportTarget?.(filePath) ?? (options.resolveImportLayer ? { layer: contextLayer, relPath: void 0 } : void 0) : void 0;
         const targetLayer = targetHit?.layer;
@@ -2762,6 +3208,214 @@ function createAICodeGate(options = {}) {
   };
 }
 
+// src/domain/analysis.ts
+var ANALYSIS_IR_SCHEMA_VERSION = "1.0";
+function deterministicHash(value) {
+  let hash = 2166136261;
+  for (let index = 0; index < value.length; index += 1) {
+    hash ^= value.charCodeAt(index);
+    hash = Math.imul(hash, 16777619);
+  }
+  return `fnv1a-${(hash >>> 0).toString(16).padStart(8, "0")}`;
+}
+function stableSerialize(value) {
+  if (value === null || typeof value !== "object") return JSON.stringify(value);
+  if (Array.isArray(value)) return `[${value.map(stableSerialize).join(",")}]`;
+  const object = value;
+  return `{${Object.keys(object).sort().map((key) => `${JSON.stringify(key)}:${stableSerialize(object[key])}`).join(",")}}`;
+}
+
+// src/kernel/analysis.ts
+function loadContract(input, source) {
+  const loaded = typeof input === "string" ? parseArkConfigJson(input, source) : loadArkConfigContract(input, source);
+  return { ...loaded, policyHash: deterministicHash(stableSerialize(loaded.config)) };
+}
+function normalizePath(value) {
+  return value.replace(/\\/g, "/").replace(/^\.\//, "");
+}
+function isIdentifierCharacter(value) {
+  return value !== void 0 && /[A-Za-z0-9_$]/.test(value);
+}
+function skipWhitespace(source, index) {
+  while (index < source.length && /\s/.test(source[index])) index += 1;
+  return index;
+}
+function readString(source, index) {
+  const quote = source[index];
+  if (quote !== "'" && quote !== '"') return void 0;
+  const start = index;
+  let value = "";
+  for (index += 1; index < source.length; index += 1) {
+    const current = source[index];
+    if (current === quote) {
+      return { value, offset: start, excerpt: source.slice(start, index + 1) };
+    }
+    if (current === "\\" && index + 1 < source.length) {
+      value += source[index + 1];
+      index += 1;
+    } else {
+      value += current;
+    }
+  }
+  return void 0;
+}
+function isWordAt(source, word, index) {
+  return source.startsWith(word, index) && !isIdentifierCharacter(source[index - 1]) && !isIdentifierCharacter(source[index + word.length]);
+}
+function specifierAfterImport(source, index) {
+  index = skipWhitespace(source, index + "import".length);
+  if (source[index] === "(") return readString(source, skipWhitespace(source, index + 1));
+  return specifierInStaticStatement(source, index, true);
+}
+function specifierAfterExport(source, index) {
+  return specifierInStaticStatement(source, index + "export".length, false);
+}
+function specifierInStaticStatement(source, index, allowDirectSpecifier) {
+  for (; index < source.length; index += 1) {
+    if (source[index] === ";") return void 0;
+    if (isWordAt(source, "from", index)) {
+      return readString(source, skipWhitespace(source, index + "from".length));
+    }
+    if (allowDirectSpecifier && (source[index] === "'" || source[index] === '"')) {
+      return readString(source, index);
+    }
+    if (index > 0 && (isWordAt(source, "import", index) || isWordAt(source, "export", index))) {
+      return void 0;
+    }
+  }
+  return void 0;
+}
+function moduleSpecifiers(source) {
+  const result = [];
+  for (let index = 0; index < source.length; index += 1) {
+    const current = source[index];
+    if (current === "/" && source[index + 1] === "/") {
+      index = source.indexOf("\n", index + 2);
+      if (index < 0) break;
+      continue;
+    }
+    if (current === "/" && source[index + 1] === "*") {
+      const end = source.indexOf("*/", index + 2);
+      if (end < 0) break;
+      index = end + 1;
+      continue;
+    }
+    if (current === "'" || current === '"' || current === "`") {
+      const string = readString(source, index);
+      if (string) index = string.offset + string.excerpt.length - 1;
+      continue;
+    }
+    const specifier = isWordAt(source, "import", index) ? specifierAfterImport(source, index) : isWordAt(source, "export", index) ? specifierAfterExport(source, index) : void 0;
+    if (specifier) result.push(specifier);
+  }
+  return result;
+}
+function importEdges(file, files) {
+  const edges = [];
+  for (const moduleSpecifier of moduleSpecifiers(file.content)) {
+    const specifier = moduleSpecifier.value;
+    if (!specifier.startsWith(".")) continue;
+    const line = file.content.slice(0, moduleSpecifier.offset).split("\n").length;
+    const evidence = {
+      kind: "import",
+      file: file.path,
+      line,
+      excerpt: moduleSpecifier.excerpt
+    };
+    const target = resolveSpecifier(file.path, specifier, files);
+    edges.push({
+      from: file.path,
+      specifier,
+      to: target?.path ?? null,
+      resolution: target ? "resolved" : "unresolved",
+      fromLayer: file.layer,
+      toLayer: target?.layer ?? null,
+      evidence
+    });
+  }
+  return edges;
+}
+function resolveSpecifier(from, specifier, files) {
+  const segments = from.split("/");
+  segments.pop();
+  for (const segment of specifier.split("/")) {
+    if (segment === "." || segment === "") continue;
+    if (segment === "..") segments.pop();
+    else segments.push(segment);
+  }
+  const base = segments.join("/");
+  for (const candidate of [base, `${base}.ts`, `${base}.tsx`, `${base}.mts`, `${base}.cts`, `${base}/index.ts`, `${base}/index.tsx`]) {
+    const found = files.get(candidate);
+    if (found) return found;
+  }
+  return void 0;
+}
+function violationsFor(edges, config) {
+  const violations = [];
+  for (const edge of edges) {
+    if (!edge.to || !edge.fromLayer || !edge.toLayer) continue;
+    const rule = findDeniedEdgeRule(config.rules, edge.fromLayer, edge.toLayer, {
+      fromPath: edge.from,
+      toPath: edge.to,
+      layers: config.layers
+    });
+    if (!rule) continue;
+    violations.push({
+      ruleId: `layer-dependency:${rule.from}->${rule.to}`,
+      message: rule.message ?? `${rule.from} must not depend on ${rule.to}.`,
+      edge,
+      evidence: edge.evidence
+    });
+  }
+  return violations;
+}
+function analyzeProject(input) {
+  const files = input.files.map((inputFile) => {
+    const path = normalizePath(inputFile.path);
+    return {
+      path,
+      content: inputFile.content,
+      contentHash: deterministicHash(inputFile.content),
+      layer: layerForRelativePath(path, input.contract.config.layers) ?? null
+    };
+  }).sort((left, right) => left.path.localeCompare(right.path));
+  const fileByPath = new Map(files.map((file) => [file.path, file]));
+  const edges = files.flatMap((file) => importEdges(file, fileByPath));
+  const capabilityUses = [];
+  const violations = violationsFor(edges, input.contract.config);
+  return {
+    ir: {
+      schemaVersion: ANALYSIS_IR_SCHEMA_VERSION,
+      policyHash: input.contract.policyHash,
+      compilerOptionsHash: deterministicHash(stableSerialize(input.compilerOptions ?? {})),
+      files,
+      layers: input.contract.config.layers.map((layer) => layer.name),
+      edges,
+      capabilityUses,
+      violations
+    }
+  };
+}
+function analyzeChange(input) {
+  const files = new Map(input.files.map((file) => [normalizePath(file.path), file]));
+  for (const change of input.changes) {
+    const path = normalizePath(change.path);
+    if ("delete" in change && change.delete) files.delete(path);
+    else if ("content" in change) files.set(path, { path, content: change.content });
+  }
+  return analyzeProject({
+    contract: input.contract,
+    files: [...files.values()],
+    compilerOptions: input.compilerOptions
+  });
+}
+function explainViolation(violation2) {
+  const location = `${violation2.evidence.file}:${violation2.evidence.line}`;
+  if (!violation2.edge) return `${violation2.ruleId} at ${location}: ${violation2.message}`;
+  const target = violation2.edge.to ?? violation2.edge.specifier;
+  return `${violation2.ruleId} at ${location}: ${violation2.edge.from} imports ${target}. ${violation2.message}`;
+}
+
 // src/kernel/projections/ProjectionRegistry.ts
 var InMemoryReadModelStore = class {
   states = /* @__PURE__ */ new Map();
@@ -3070,22 +3724,13 @@ var WorkflowEngineImpl = class {
     for (let attempt = 1; attempt <= maxAttempts; attempt += 1) {
       snapshot.attempts[step.name] = attempt;
       await this.store.save(snapshot);
+      let result;
       try {
-        const result = await withTimeout(
+        result = await withTimeout(
           (signal) => Promise.resolve(step.execute(snapshot.context, this.bus, signal)),
           step.timeoutMs,
           step.name
         );
-        if (result) Object.assign(snapshot.context, result);
-        snapshot.completedSteps.push(step.name);
-        snapshot.currentStep = void 0;
-        snapshot.updatedAt = (/* @__PURE__ */ new Date()).toISOString();
-        await this.store.save(snapshot);
-        await this.audit("workflow.step.completed", snapshot, {
-          step: step.name,
-          attempt
-        });
-        return;
       } catch (err) {
         if (attempt < maxAttempts) {
           if (retry.delayMs) await sleep(retry.delayMs);
@@ -3101,6 +3746,16 @@ var WorkflowEngineImpl = class {
         });
         throw err;
       }
+      if (result) Object.assign(snapshot.context, result);
+      snapshot.completedSteps.push(step.name);
+      snapshot.currentStep = void 0;
+      snapshot.updatedAt = (/* @__PURE__ */ new Date()).toISOString();
+      await this.store.save(snapshot);
+      await this.audit("workflow.step.completed", snapshot, {
+        step: step.name,
+        attempt
+      });
+      return;
     }
     throw new Error(`Workflow step "${step.name}" did not complete.`);
   }
@@ -3292,6 +3947,7 @@ function createLenientArkKernel(options = {}) {
 }
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  ANALYSIS_IR_SCHEMA_VERSION,
   DEFAULT_MAX_HISTORY_SIZE,
   EventContractRegistryImpl,
   EventContractViolationError,
@@ -3309,6 +3965,8 @@ function createLenientArkKernel(options = {}) {
   SourceMetadataOverrideError,
   UnknownEventSourceError,
   UnregisteredIntentError,
+  analyzeChange,
+  analyzeProject,
   architecturalPolicies,
   buildPublishPolicyContext,
   checkAdapterGovernance,
@@ -3343,8 +4001,12 @@ function createLenientArkKernel(options = {}) {
   definePolicy,
   definePort,
   definePublishPolicy,
+  deterministicHash,
   elevenLayerProfile,
+  explainViolation,
   isLayerPolicy,
+  loadContract,
+  stableSerialize,
   syncRegistryToGraph,
   validateIntentName,
   version