@contractspec/module.workspace 1.57.0 → 1.58.0

package/dist/index.js

@@ -1,38 +1,4302 @@
-import { extractTestCoverage, extractTestTarget } from "./analysis/spec-parsing-utils.js";
-import { inferSpecTypeFromCodeBlock, inferSpecTypeFromFilePath, scanAllSpecsFromSource, scanSpecSource } from "./analysis/spec-scan.js";
-import { isFeatureFile, scanFeatureSource } from "./analysis/feature-scan.js";
-import { isExampleFile, scanExampleSource } from "./analysis/example-scan.js";
-import { SpecGroupingStrategies, filterFeatures, filterSpecs, getUniqueSpecDomains, getUniqueSpecOwners, getUniqueSpecTags, groupSpecs, groupSpecsToArray } from "./analysis/grouping.js";
-import { computeSemanticDiff } from "./analysis/diff/semantic.js";
-import { computeFieldDiff, computeFieldsDiff, computeIoDiff, isBreakingChange } from "./analysis/diff/deep-diff.js";
-import { addContractNode, buildReverseEdges, createContractGraph, detectCycles, findMissingDependencies, toDot } from "./analysis/deps/graph.js";
-import { parseImportedSpecNames } from "./analysis/deps/parse-imports.js";
-import { validateSpecStructure } from "./analysis/validate/spec-structure.js";
-import { computeHash, normalizeValue, sortFields, sortSpecs, toCanonicalJson } from "./analysis/snapshot/normalizer.js";
-import { generateSnapshot } from "./analysis/snapshot/snapshot.js";
-import { BREAKING_RULES, DEFAULT_RULES, INFO_RULES, NON_BREAKING_RULES, findMatchingRule, getRulesBySeverity } from "./analysis/impact/rules.js";
-import { classifyImpact } from "./analysis/impact/classifier.js";
-import { loadSpecFromSource } from "./analysis/spec-parser.js";
-import "./analysis/index.js";
-import { capitalize, escapeString, toCamelCase, toKebabCase, toPascalCase } from "./templates/utils.js";
-import { generateOperationSpec } from "./templates/operation.js";
-import { generateEventSpec } from "./templates/event.js";
-import { generatePresentationSpec } from "./templates/presentation.js";
-import { generateWorkflowSpec } from "./templates/workflow.js";
-import { generateWorkflowRunnerTemplate } from "./templates/workflow-runner.js";
-import { generateDataViewSpec } from "./templates/data-view.js";
-import { generateTelemetrySpec } from "./templates/telemetry.js";
-import { generateExperimentSpec } from "./templates/experiment.js";
-import { generateAppBlueprintSpec } from "./templates/app-config.js";
-import { generateMigrationSpec } from "./templates/migration.js";
-import { generateIntegrationSpec } from "./templates/integration.js";
-import { generateKnowledgeSpaceSpec } from "./templates/knowledge.js";
-import { generateComponentTemplate, generateHandlerTemplate, generateTestTemplate } from "./templates/handler.js";
-import { addExampleContext, buildEventSpecPrompt, buildOperationSpecPrompt, buildPresentationSpecPrompt, getSystemPrompt } from "./ai/prompts/spec-creation.js";
-import { buildComponentPrompt, buildFormPrompt, buildHandlerPrompt, buildTestPrompt, getCodeGenSystemPrompt } from "./ai/prompts/code-generation.js";
-import { detectFormatter, formatFiles, formatFilesBatch } from "./formatter.js";
-import { combineSpecMarkdowns, generateSpecsSummaryHeader, specToMarkdown, specToMarkdownWithOptions } from "./formatters/spec-markdown.js";
-import { convertSpecToDocBlock } from "./formatters/spec-to-docblock.js";
-import "./formatters/index.js";
-
-export { BREAKING_RULES, DEFAULT_RULES, INFO_RULES, NON_BREAKING_RULES, SpecGroupingStrategies, addContractNode, addExampleContext, buildComponentPrompt, buildEventSpecPrompt, buildFormPrompt, buildHandlerPrompt, buildOperationSpecPrompt, buildPresentationSpecPrompt, buildReverseEdges, buildTestPrompt, capitalize, classifyImpact, combineSpecMarkdowns, computeFieldDiff, computeFieldsDiff, computeHash, computeIoDiff, computeSemanticDiff, convertSpecToDocBlock, createContractGraph, detectCycles, detectFormatter, escapeString, extractTestCoverage, extractTestTarget, filterFeatures, filterSpecs, findMatchingRule, findMissingDependencies, formatFiles, formatFilesBatch, generateAppBlueprintSpec, generateComponentTemplate, generateDataViewSpec, generateEventSpec, generateExperimentSpec, generateHandlerTemplate, generateIntegrationSpec, generateKnowledgeSpaceSpec, generateMigrationSpec, generateOperationSpec, generatePresentationSpec, generateSnapshot, generateSpecsSummaryHeader, generateTelemetrySpec, generateTestTemplate, generateWorkflowRunnerTemplate, generateWorkflowSpec, getCodeGenSystemPrompt, getRulesBySeverity, getSystemPrompt, getUniqueSpecDomains, getUniqueSpecOwners, getUniqueSpecTags, groupSpecs, groupSpecsToArray, inferSpecTypeFromCodeBlock, inferSpecTypeFromFilePath, isBreakingChange, isExampleFile, isFeatureFile, loadSpecFromSource, normalizeValue, parseImportedSpecNames, scanAllSpecsFromSource, scanExampleSource, scanFeatureSource, scanSpecSource, sortFields, sortSpecs, specToMarkdown, specToMarkdownWithOptions, toCamelCase, toCanonicalJson, toDot, toKebabCase, toPascalCase, validateSpecStructure };
+// @bun
+// src/analysis/utils/matchers.ts
+function escapeRegex(value) {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+function matchStringField(code, field) {
+  const regex = new RegExp(`${escapeRegex(field)}\\s*:\\s*['"]([^'"]+)['"]`);
+  const match = code.match(regex);
+  return match?.[1] ?? null;
+}
+function matchStringFieldIn(code, field) {
+  return matchStringField(code, field);
+}
+function matchVersionField(code, field) {
+  const regex = new RegExp(`${escapeRegex(field)}\\s*:\\s*(?:['"]([^'"]+)['"]|(\\d+(?:\\.\\d+)*))`);
+  const match = code.match(regex);
+  if (match?.[1])
+    return match[1];
+  if (match?.[2])
+    return match[2];
+  return;
+}
+function matchStringArrayField(code, field) {
+  const regex = new RegExp(`${escapeRegex(field)}\\s*:\\s*\\[([\\s\\S]*?)\\]`);
+  const match = code.match(regex);
+  if (!match?.[1])
+    return;
+  const inner = match[1];
+  const items = Array.from(inner.matchAll(/['"]([^'"]+)['"]/g)).map((m) => m[1]).filter((value) => typeof value === "string" && value.length > 0);
+  return items.length > 0 ? items : undefined;
+}
+function isStability(value) {
+  return value === "experimental" || value === "beta" || value === "stable" || value === "deprecated";
+}
+function findMatchingDelimiter(code, startIndex, openChar, closeChar) {
+  let depth = 0;
+  let inString = false;
+  let stringChar = "";
+  for (let i = startIndex;i < code.length; i++) {
+    const char = code[i];
+    const prevChar = i > 0 ? code[i - 1] : "";
+    if ((char === '"' || char === "'" || char === "`") && prevChar !== "\\") {
+      if (!inString) {
+        inString = true;
+        stringChar = char;
+      } else if (char === stringChar) {
+        inString = false;
+      }
+      continue;
+    }
+    if (inString)
+      continue;
+    if (char === openChar) {
+      depth++;
+    } else if (char === closeChar) {
+      depth--;
+      if (depth === 0) {
+        return i;
+      }
+    }
+  }
+  return -1;
+}
+
+// src/analysis/utils/variables.ts
+function extractArrayConstants(code) {
+  const variables = new Map;
+  const regex = /const\s+(\w+)\s*=\s*\[/g;
+  let match;
+  while ((match = regex.exec(code)) !== null) {
+    const name = match[1];
+    const startIndex = match.index + match[0].length - 1;
+    const endIndex = findMatchingDelimiter(code, startIndex, "[", "]");
+    if (endIndex !== -1) {
+      const value = code.substring(startIndex, endIndex + 1);
+      if (name) {
+        variables.set(name, value);
+      }
+    }
+  }
+  return variables;
+}
+function resolveVariablesInBlock(block, variables) {
+  if (variables.size === 0)
+    return block;
+  return block.replace(/\.\.\.(\w+)/g, (match, name) => {
+    const value = variables.get(name);
+    if (value) {
+      if (value.startsWith("[") && value.endsWith("]")) {
+        return value.substring(1, value.length - 1);
+      }
+      return value;
+    }
+    return match;
+  });
+}
+
+// src/analysis/spec-parsing-utils.ts
+function parsePolicy(code) {
+  const policyBlock = code.match(/policy\s*:\s*\{([\s\S]*?)\}/);
+  if (!policyBlock?.[1])
+    return [];
+  return extractRefList(policyBlock[1], "policies") ?? [];
+}
+function extractRefList(code, field) {
+  const regex = new RegExp(`${escapeRegex(field)}\\s*:\\s*\\[([\\s\\S]*?)\\]`);
+  const match = code.match(regex);
+  if (!match?.[1])
+    return;
+  const inner = match[1];
+  const items = [];
+  const parts = inner.match(/\{[\s\S]*?\}/g);
+  if (parts) {
+    for (const part of parts) {
+      const k = matchStringField(part, "key");
+      const v = matchVersionField(part, "version");
+      if (k) {
+        items.push({ key: k, version: v ?? "1.0.0" });
+      }
+    }
+  }
+  return items.length > 0 ? items : undefined;
+}
+function extractTestRefs(code) {
+  const regex = new RegExp(`testRefs\\s*:\\s*\\[([\\s\\S]*?)\\]`);
+  const match = code.match(regex);
+  if (!match?.[1])
+    return;
+  const inner = match[1];
+  const items = [];
+  const parts = inner.match(/\{[\s\S]*?\}/g);
+  if (parts) {
+    for (const part of parts) {
+      const k = matchStringField(part, "key");
+      const v = matchVersionField(part, "version");
+      const t = matchStringField(part, "type");
+      if (k) {
+        items.push({
+          key: k,
+          version: v ?? "1.0.0",
+          type: t === "error" ? "error" : "success"
+        });
+      }
+    }
+  }
+  return items.length > 0 ? items : undefined;
+}
+function extractTestTarget(code) {
+  const targetStartMatch = code.match(/target\s*:\s*\{/);
+  if (!targetStartMatch || targetStartMatch.index === undefined)
+    return;
+  const openBraceIndex = targetStartMatch.index + targetStartMatch[0].length - 1;
+  const closeBraceIndex = findMatchingDelimiter(code, openBraceIndex, "{", "}");
+  if (closeBraceIndex === -1)
+    return;
+  const targetBlock = code.substring(openBraceIndex + 1, closeBraceIndex);
+  const typeMatch = targetBlock.match(/type\s*:\s*['"](\w+)['"]/);
+  if (!typeMatch?.[1])
+    return;
+  const type = typeMatch[1];
+  if (type !== "operation" && type !== "workflow")
+    return;
+  const flatKey = matchStringField(targetBlock, "key");
+  if (flatKey) {
+    const flatVersion = matchVersionField(targetBlock, "version");
+    return {
+      type,
+      key: flatKey,
+      version: flatVersion
+    };
+  }
+  const refBlockMatch = targetBlock.match(new RegExp(`${type}\\s*:\\s*\\{([\\s\\S]*?)\\}`));
+  if (!refBlockMatch?.[1])
+    return;
+  const refBlock = refBlockMatch[1];
+  const key = matchStringField(refBlock, "key");
+  if (!key)
+    return;
+  const version = matchVersionField(refBlock, "version");
+  return {
+    type,
+    key,
+    version
+  };
+}
+function extractTestCoverage(code) {
+  const hasSuccessNew = /expectOutput\s*:/.test(code);
+  const hasErrorNew = /expectError\s*:/.test(code);
+  const hasSuccessOld = /(['"]?)type\1\s*:\s*['"]expectOutput['"]/.test(code);
+  const hasErrorOld = /(['"]?)type\1\s*:\s*['"]expectError['"]/.test(code);
+  return {
+    hasSuccess: hasSuccessNew || hasSuccessOld,
+    hasError: hasErrorNew || hasErrorOld
+  };
+}
+
+// src/analysis/spec-scan.ts
+function scanAllSpecsFromSource(code, filePath) {
+  const results = [];
+  const variables = extractArrayConstants(code);
+  const definitionRegex = /export\s+const\s+(\w+)\s*=\s*define(Command|Query|Event|Presentation|Capability|Policy|Type|Example|AppConfig|Integration|Workflow|TestSpec|Feature)\s*\(/g;
+  let match;
+  while ((match = definitionRegex.exec(code)) !== null) {
+    const start = match.index;
+    const openParenIndex = start + match[0].length - 1;
+    const end = findMatchingDelimiter(code, openParenIndex, "(", ")");
+    if (end === -1)
+      continue;
+    let finalEnd = end;
+    if (code[finalEnd + 1] === ";") {
+      finalEnd++;
+    }
+    const block = code.substring(start, finalEnd + 1);
+    const resolvedBlock = resolveVariablesInBlock(block, variables);
+    const result = scanSpecSource(resolvedBlock, filePath);
+    if (result) {
+      results.push({
+        ...result,
+        sourceBlock: resolvedBlock
+      });
+    }
+  }
+  if (results.length === 0 && filePath.includes(".spec.")) {
+    const result = scanSpecSource(code, filePath);
+    if (result.key !== "unknown") {
+      const resolvedBlock = resolveVariablesInBlock(code, variables);
+      const result2 = scanSpecSource(resolvedBlock, filePath);
+      results.push(result2);
+    }
+  }
+  return results;
+}
+function inferSpecTypeFromCodeBlock(fileSourceCode) {
+  if (fileSourceCode.includes("defineCommand")) {
+    return {
+      specType: "operation",
+      kind: "command"
+    };
+  }
+  if (fileSourceCode.includes("defineQuery")) {
+    return {
+      specType: "operation",
+      kind: "query"
+    };
+  }
+  if (fileSourceCode.includes("defineEvent")) {
+    return {
+      specType: "event",
+      kind: "event"
+    };
+  }
+  if (fileSourceCode.includes("definePresentation")) {
+    return {
+      specType: "presentation",
+      kind: "presentation"
+    };
+  }
+  if (fileSourceCode.includes("definePolicy")) {
+    return {
+      specType: "policy",
+      kind: "policy"
+    };
+  }
+  if (fileSourceCode.includes("defineCapability")) {
+    return {
+      specType: "capability",
+      kind: "capability"
+    };
+  }
+  if (fileSourceCode.includes("defineExample")) {
+    return {
+      specType: "example",
+      kind: "example"
+    };
+  }
+  if (fileSourceCode.includes("defineAppConfig") && !fileSourceCode.includes("export const defineAppConfig")) {
+    return {
+      specType: "app-config",
+      kind: "app-config"
+    };
+  }
+  if (fileSourceCode.includes("defineIntegration")) {
+    return {
+      specType: "integration",
+      kind: "integration"
+    };
+  }
+  if (fileSourceCode.includes("defineWorkflow")) {
+    return {
+      specType: "workflow",
+      kind: "workflow"
+    };
+  }
+  if (fileSourceCode.includes("defineTestSpec")) {
+    return {
+      specType: "test-spec",
+      kind: "test-spec"
+    };
+  }
+  if (fileSourceCode.includes("defineFeature")) {
+    return {
+      specType: "feature",
+      kind: "feature"
+    };
+  }
+  return {
+    specType: "unknown",
+    kind: "unknown"
+  };
+}
+function scanSpecSource(code, filePath) {
+  const keyMatch = code.match(/key\s*:\s*['"]([^'"]+)['"]/) ?? code.match(/export\s+const\s+(\w+)\s*=/);
+  const key = keyMatch?.[1] ?? "unknown";
+  const version = matchVersionField(code, "version");
+  const description = matchStringField(code, "description") ?? undefined;
+  const goal = matchStringField(code, "goal") ?? undefined;
+  const context = matchStringField(code, "context") ?? undefined;
+  const stabilityRaw = matchStringField(code, "stability");
+  const stability = isStability(stabilityRaw) ? stabilityRaw : undefined;
+  const owners = matchStringArrayField(code, "owners");
+  const tags = matchStringArrayField(code, "tags");
+  const inferredSpecType = inferSpecTypeFromCodeBlock(code);
+  const hasMeta = /meta\s*:\s*\{/.test(code);
+  const hasIo = /io\s*:\s*\{/.test(code);
+  const hasPolicy = /policy\s*:\s*\{/.test(code);
+  const hasPayload = /payload\s*:\s*\{/.test(code);
+  const hasContent = /content\s*:\s*\{/.test(code);
+  const hasDefinition = /definition\s*:\s*\{/.test(code);
+  const emittedEvents = extractRefList(code, "emits") ?? extractRefList(code, "emittedEvents");
+  const testRefs = extractTestRefs(code);
+  const policyRefs = hasPolicy ? parsePolicy(code) : undefined;
+  return {
+    filePath,
+    key,
+    version,
+    specType: inferredSpecType.specType,
+    kind: inferredSpecType.kind,
+    description,
+    goal,
+    context,
+    stability,
+    owners,
+    tags,
+    hasMeta,
+    hasIo,
+    hasPolicy,
+    hasPayload,
+    hasContent,
+    hasDefinition,
+    emittedEvents,
+    policyRefs,
+    testRefs,
+    testTarget: extractTestTarget(code),
+    testCoverage: extractTestCoverage(code),
+    sourceBlock: code
+  };
+}
+function inferSpecTypeFromFilePath(filePath) {
+  if (filePath.includes(".contracts.") || /\/operations?\//.test(filePath)) {
+    return "operation";
+  }
+  if (filePath.includes(".event.") || /\/events?\//.test(filePath)) {
+    return "event";
+  }
+  if (filePath.includes(".presentation.") || /\/presentations?\//.test(filePath)) {
+    return "presentation";
+  }
+  if (filePath.includes(".policy.") || /\/policies?\//.test(filePath)) {
+    return "policy";
+  }
+  if (filePath.includes(".feature.") || /\/features?\//.test(filePath)) {
+    return "feature";
+  }
+  if (filePath.includes(".type.") || /\/types?\//.test(filePath)) {
+    return "type";
+  }
+  if (filePath.includes(".example.") || /\/examples?\//.test(filePath)) {
+    return "example";
+  }
+  if (filePath.includes(".app-config.")) {
+    return "app-config";
+  }
+  if (filePath.includes(".workflow.") || /\/workflows?\//.test(filePath)) {
+    return "workflow";
+  }
+  if (filePath.includes(".integration.") || /\/integrations?\//.test(filePath)) {
+    return "integration";
+  }
+  return "unknown";
+}
+// src/analysis/feature-extractor.ts
+import {
+  Project,
+  Node,
+  SyntaxKind
+} from "ts-morph";
+function extractFeatureRefs(code) {
+  const result = {
+    operations: [],
+    events: [],
+    presentations: [],
+    experiments: [],
+    capabilities: {
+      provides: [],
+      requires: []
+    },
+    opToPresentationLinks: [],
+    presentationsTargets: []
+  };
+  const project = new Project({ useInMemoryFileSystem: true });
+  const sourceFile = project.createSourceFile("feature.ts", code);
+  const extractRefs = (obj, propName, allowKeyOnly = false) => {
+    const refs = [];
+    const prop = obj.getProperty(propName);
+    if (prop && Node.isPropertyAssignment(prop)) {
+      const init = prop.getInitializer();
+      if (init && Node.isArrayLiteralExpression(init)) {
+        for (const elem of init.getElements()) {
+          if (Node.isObjectLiteralExpression(elem)) {
+            const keyText = getTextFromProp(elem, "key");
+            const verText = getTextFromProp(elem, "version");
+            if (keyText && verText) {
+              refs.push({ key: keyText, version: verText });
+            } else if (keyText && allowKeyOnly) {
+              refs.push({ key: keyText, version: "1.0.0" });
+            }
+          }
+        }
+      }
+    }
+    return refs;
+  };
+  const callExpressions = sourceFile.getDescendantsOfKind(SyntaxKind.CallExpression);
+  for (const call of callExpressions) {
+    if (["defineFeature", "defineAppConfig", "defineAppBlueprint"].includes(call.getExpression().getText())) {
+      const args = call.getArguments();
+      if (args.length > 0 && Node.isObjectLiteralExpression(args[0])) {
+        const obj = args[0];
+        result.operations.push(...extractRefs(obj, "operations"));
+        result.events.push(...extractRefs(obj, "events"));
+        result.presentations.push(...extractRefs(obj, "presentations"));
+        result.experiments.push(...extractRefs(obj, "experiments"));
+        const capsProp = obj.getProperty("capabilities");
+        if (capsProp && Node.isPropertyAssignment(capsProp)) {
+          const capsObj = capsProp.getInitializer();
+          if (capsObj && Node.isObjectLiteralExpression(capsObj)) {
+            result.capabilities.provides.push(...extractRefs(capsObj, "provides"));
+            result.capabilities.requires.push(...extractRefs(capsObj, "requires", true));
+          }
+        }
+        const linksProp = obj.getProperty("opToPresentation");
+        if (linksProp && Node.isPropertyAssignment(linksProp)) {
+          const linksArr = linksProp.getInitializer();
+          if (linksArr && Node.isArrayLiteralExpression(linksArr)) {
+            linksArr.getElements().forEach((link) => {
+              if (Node.isObjectLiteralExpression(link)) {
+                const opProp = link.getProperty("op");
+                const presProp = link.getProperty("pres");
+                let opRef;
+                let presRef;
+                if (opProp && Node.isPropertyAssignment(opProp)) {
+                  const val = opProp.getInitializer();
+                  if (val && Node.isObjectLiteralExpression(val)) {
+                    const key = getTextFromProp(val, "key");
+                    const version = getTextFromProp(val, "version");
+                    if (key && version)
+                      opRef = { key, version };
+                  }
+                }
+                if (presProp && Node.isPropertyAssignment(presProp)) {
+                  const val = presProp.getInitializer();
+                  if (val && Node.isObjectLiteralExpression(val)) {
+                    const key = getTextFromProp(val, "key");
+                    const version = getTextFromProp(val, "version");
+                    if (key && version)
+                      presRef = { key, version };
+                  }
+                }
+                if (opRef && presRef) {
+                  result.opToPresentationLinks.push({
+                    op: opRef,
+                    pres: presRef
+                  });
+                }
+              }
+            });
+          }
+        }
+        extractLinks(obj, result.opToPresentationLinks);
+        const targetsProp = obj.getProperty("presentationsTargets");
+        if (targetsProp && Node.isPropertyAssignment(targetsProp)) {
+          const targetsArr = targetsProp.getInitializer();
+          if (targetsArr && Node.isArrayLiteralExpression(targetsArr)) {
+            targetsArr.getElements().forEach((targetBlock) => {
+              if (Node.isObjectLiteralExpression(targetBlock)) {
+                const key = getTextFromProp(targetBlock, "key");
+                const version = getTextFromProp(targetBlock, "version");
+                const targetsList = getTargetsList(targetBlock, "targets");
+                if (key && version && targetsList) {
+                  result.presentationsTargets.push({
+                    key,
+                    version,
+                    targets: targetsList
+                  });
+                }
+              }
+            });
+          }
+        }
+        extractPresentationTargets(obj, result.presentationsTargets);
+      }
+    }
+  }
+  return result;
+}
+function extractLinks(obj, opToPresentationLinks) {
+  const interactionsProp = obj.getProperty("interactions");
+  if (interactionsProp && Node.isPropertyAssignment(interactionsProp)) {
+    const interactionsArr = interactionsProp.getInitializer();
+    if (interactionsArr && Node.isArrayLiteralExpression(interactionsArr)) {
+      interactionsArr.getElements().forEach((interaction) => {
+        if (Node.isObjectLiteralExpression(interaction)) {
+          const triggerProp = interaction.getProperty("trigger");
+          const triggerObj = triggerProp && Node.isPropertyAssignment(triggerProp) && triggerProp.getInitializer();
+          const actionProp = interaction.getProperty("action");
+          const actionObj = actionProp && Node.isPropertyAssignment(actionProp) && actionProp.getInitializer();
+          if (triggerObj && Node.isObjectLiteralExpression(triggerObj) && actionObj && Node.isObjectLiteralExpression(actionObj)) {
+            const triggerType = getTextFromProp(triggerObj, "type");
+            const actionType = getTextFromProp(actionObj, "type");
+            if (triggerType === "presentation" && actionType === "operation") {
+              const presRef = extractNestedRef(triggerObj, "presentation");
+              const opRef = extractNestedRef(actionObj, "operation");
+              if (presRef && opRef) {
+                opToPresentationLinks.push({ op: opRef, pres: presRef });
+              }
+            }
+          }
+        }
+      });
+    }
+  }
+}
+function extractNestedRef(obj, propName) {
+  const prop = obj.getProperty(propName);
+  if (prop && Node.isPropertyAssignment(prop)) {
+    const val = prop.getInitializer();
+    if (val && Node.isObjectLiteralExpression(val)) {
+      const key = getTextFromProp(val, "key");
+      const version = getTextFromProp(val, "version");
+      if (key && version)
+        return { key, version };
+    }
+  }
+  return;
+}
+function extractPresentationTargets(obj, presentationsTargets) {
+  const presentationsProp = obj.getProperty("presentations");
+  if (presentationsProp && Node.isPropertyAssignment(presentationsProp)) {
+    const presentationsArr = presentationsProp.getInitializer();
+    if (presentationsArr && Node.isArrayLiteralExpression(presentationsArr)) {
+      for (const elem of presentationsArr.getElements()) {
+        if (Node.isObjectLiteralExpression(elem)) {
+          const keyText = getTextFromProp(elem, "key");
+          const verText = getTextFromProp(elem, "version");
+          const targetsList = getTargetsList(elem, "targets");
+          if (keyText && verText && targetsList) {
+            presentationsTargets.push({
+              key: keyText,
+              version: verText,
+              targets: targetsList
+            });
+          }
+        }
+      }
+    }
+  }
+}
+function getTextFromProp(obj, propName) {
+  const prop = obj.getProperty(propName);
+  if (prop && Node.isPropertyAssignment(prop)) {
+    const init = prop.getInitializer();
+    if (init && Node.isStringLiteral(init)) {
+      return init.getLiteralText();
+    }
+  }
+  return;
+}
+function getTargetsList(obj, propName) {
+  const prop = obj.getProperty(propName);
+  if (prop && Node.isPropertyAssignment(prop)) {
+    const init = prop.getInitializer();
+    if (init && Node.isArrayLiteralExpression(init)) {
+      return init.getElements().map((e) => {
+        if (Node.isStringLiteral(e))
+          return e.getLiteralText();
+        return { target: e.getText() };
+      });
+    }
+  }
+  return;
+}
+
+// src/analysis/feature-scan.ts
+function isFeatureFile(filePath) {
+  return filePath.includes(".feature.") && filePath.endsWith(".ts");
+}
+function scanFeatureSource(code, filePath) {
+  const key = matchStringField(code, "key") ?? extractKeyFromFilePath(filePath);
+  const versionRaw = matchStringField(code, "version");
+  const version = versionRaw ?? "1.0.0";
+  const title = matchStringField(code, "title") ?? undefined;
+  const description = matchStringField(code, "description") ?? undefined;
+  const goal = matchStringField(code, "goal") ?? undefined;
+  const context = matchStringField(code, "context") ?? undefined;
+  const stabilityRaw = matchStringField(code, "stability");
+  const stability = isStability(stabilityRaw) ? stabilityRaw : undefined;
+  const owners = matchStringArrayField(code, "owners");
+  const tags = matchStringArrayField(code, "tags");
+  const refs = extractFeatureRefs(code);
+  return {
+    filePath,
+    key,
+    version,
+    title,
+    description,
+    goal,
+    context,
+    stability,
+    owners,
+    tags,
+    operations: refs.operations,
+    events: refs.events,
+    presentations: refs.presentations,
+    experiments: refs.experiments,
+    capabilities: refs.capabilities,
+    opToPresentationLinks: refs.opToPresentationLinks,
+    presentationsTargets: refs.presentationsTargets,
+    sourceBlock: code
+  };
+}
+function extractKeyFromFilePath(filePath) {
+  const fileName = filePath.split("/").pop() ?? filePath;
+  return fileName.replace(/\.feature\.[jt]s$/, "").replace(/[^a-zA-Z0-9-]/g, "-");
+}
+// src/analysis/example-scan.ts
+function isExampleFile(filePath) {
+  return filePath.includes("/example.") || filePath.endsWith(".example.ts");
+}
+function scanExampleSource(code, filePath) {
+  const key = matchStringField(code, "key") ?? extractKeyFromFilePath2(filePath);
+  const versionRaw = matchStringField(code, "version");
+  const version = versionRaw ?? undefined;
+  const title = matchStringField(code, "title") ?? undefined;
+  const description = matchStringField(code, "description") ?? undefined;
+  const summary = matchStringField(code, "summary") ?? undefined;
+  const kind = matchStringField(code, "kind") ?? undefined;
+  const visibility = matchStringField(code, "visibility") ?? undefined;
+  const domain = matchStringField(code, "domain") ?? undefined;
+  const stabilityRaw = matchStringField(code, "stability");
+  const stability = isStability(stabilityRaw) ? stabilityRaw : undefined;
+  const owners = matchStringArrayField(code, "owners");
+  const tags = matchStringArrayField(code, "tags");
+  const docs = extractDocs(code);
+  const surfaces = extractSurfaces(code);
+  const entrypoints = extractEntrypoints(code);
+  return {
+    filePath,
+    key,
+    version,
+    title,
+    description,
+    summary,
+    kind,
+    visibility,
+    domain,
+    stability,
+    owners,
+    tags,
+    docs,
+    surfaces,
+    entrypoints
+  };
+}
+function extractDocs(code) {
+  const docsMatch = code.match(/docs\s*:\s*\{([\s\S]*?)\}/);
+  if (!docsMatch?.[1])
+    return;
+  const docsContent = docsMatch[1];
+  return {
+    rootDocId: matchStringFieldIn(docsContent, "rootDocId") ?? undefined,
+    goalDocId: matchStringFieldIn(docsContent, "goalDocId") ?? undefined,
+    usageDocId: matchStringFieldIn(docsContent, "usageDocId") ?? undefined
+  };
+}
+function extractSurfaces(code) {
+  const surfaces = {
+    templates: false,
+    sandbox: { enabled: false, modes: [] },
+    studio: { enabled: false, installable: false },
+    mcp: { enabled: false }
+  };
+  surfaces.templates = /surfaces\s*:\s*\{[\s\S]*?templates\s*:\s*true/.test(code);
+  const sandboxMatch = code.match(/sandbox\s*:\s*\{\s*enabled\s*:\s*(true|false)\s*,\s*modes\s*:\s*\[([^\]]*)\]/);
+  if (sandboxMatch) {
+    surfaces.sandbox.enabled = sandboxMatch[1] === "true";
+    if (sandboxMatch[2]) {
+      surfaces.sandbox.modes = Array.from(sandboxMatch[2].matchAll(/['"]([^'"]+)['"]/g)).map((m) => m[1]).filter((v) => typeof v === "string");
+    }
+  }
+  const studioMatch = code.match(/studio\s*:\s*\{\s*enabled\s*:\s*(true|false)\s*,\s*installable\s*:\s*(true|false)/);
+  if (studioMatch) {
+    surfaces.studio.enabled = studioMatch[1] === "true";
+    surfaces.studio.installable = studioMatch[2] === "true";
+  }
+  const mcpMatch = code.match(/mcp\s*:\s*\{\s*enabled\s*:\s*(true|false)/);
+  if (mcpMatch) {
+    surfaces.mcp.enabled = mcpMatch[1] === "true";
+  }
+  return surfaces;
+}
+function extractEntrypoints(code) {
+  const entrypoints = {
+    packageName: ""
+  };
+  const entrypointsMatch = code.match(/entrypoints\s*:\s*\{([\s\S]*?)\}(?=\s*[,}])/);
+  if (!entrypointsMatch?.[1])
+    return entrypoints;
+  const content = entrypointsMatch[1];
+  entrypoints.packageName = matchStringFieldIn(content, "packageName") ?? "unknown";
+  entrypoints.feature = matchStringFieldIn(content, "feature") ?? undefined;
+  entrypoints.blueprint = matchStringFieldIn(content, "blueprint") ?? undefined;
+  entrypoints.contracts = matchStringFieldIn(content, "contracts") ?? undefined;
+  entrypoints.presentations = matchStringFieldIn(content, "presentations") ?? undefined;
+  entrypoints.handlers = matchStringFieldIn(content, "handlers") ?? undefined;
+  entrypoints.ui = matchStringFieldIn(content, "ui") ?? undefined;
+  entrypoints.docs = matchStringFieldIn(content, "docs") ?? undefined;
+  return entrypoints;
+}
+function extractKeyFromFilePath2(filePath) {
+  const parts = filePath.split("/");
+  const examplesIndex = parts.findIndex((p) => p === "examples");
+  const exampleName = parts[examplesIndex + 1];
+  if (examplesIndex !== -1 && exampleName !== undefined) {
+    return exampleName;
+  }
+  const fileName = parts.pop() ?? filePath;
+  return fileName.replace(/\.example\.[jt]s$/, "").replace(/[^a-zA-Z0-9-]/g, "-");
+}
+// src/analysis/grouping.ts
+var SpecGroupingStrategies = {
+  byTag: (item) => item.tags?.[0] ?? "untagged",
+  byOwner: (item) => item.owners?.[0] ?? "unowned",
+  byDomain: (item) => {
+    const key = item.key ?? "";
+    if (key.includes(".")) {
+      return key.split(".")[0] ?? "default";
+    }
+    return "default";
+  },
+  byStability: (item) => item.stability ?? "stable",
+  bySpecType: (item) => item.specType,
+  byDirectory: (item) => {
+    const parts = item.filePath.split("/");
+    return parts.slice(0, -1).join("/") || ".";
+  }
+};
+function filterSpecs(specs, filter) {
+  return specs.filter((spec) => {
+    if (filter.tags?.length) {
+      const hasMatchingTag = filter.tags.some((tag) => spec.tags?.includes(tag));
+      if (!hasMatchingTag)
+        return false;
+    }
+    if (filter.owners?.length) {
+      const hasMatchingOwner = filter.owners.some((owner) => spec.owners?.includes(owner));
+      if (!hasMatchingOwner)
+        return false;
+    }
+    if (filter.stability?.length) {
+      if (!filter.stability.includes(spec.stability ?? "stable")) {
+        return false;
+      }
+    }
+    if (filter.specType?.length) {
+      if (!filter.specType.includes(spec.specType)) {
+        return false;
+      }
+    }
+    if (filter.namePattern) {
+      const key = spec.key ?? "";
+      const pattern = filter.namePattern.replace(/\*/g, ".*").replace(/\?/g, ".");
+      const regex = new RegExp(`^${pattern}$`, "i");
+      if (!regex.test(key))
+        return false;
+    }
+    return true;
+  });
+}
+function groupSpecs(items, keyFn) {
+  const groups = new Map;
+  for (const item of items) {
+    const key = keyFn(item);
+    const existing = groups.get(key);
+    if (existing) {
+      existing.push(item);
+    } else {
+      groups.set(key, [item]);
+    }
+  }
+  return groups;
+}
+function groupSpecsToArray(items, keyFn) {
+  const map = groupSpecs(items, keyFn);
+  return Array.from(map.entries()).map(([key, items2]) => ({ key, items: items2 })).sort((a, b) => a.key.localeCompare(b.key));
+}
+function getUniqueSpecTags(specs) {
+  const tags = new Set;
+  for (const spec of specs) {
+    for (const tag of spec.tags ?? []) {
+      tags.add(tag);
+    }
+  }
+  return Array.from(tags).sort();
+}
+function getUniqueSpecOwners(specs) {
+  const owners = new Set;
+  for (const spec of specs) {
+    for (const owner of spec.owners ?? []) {
+      owners.add(owner);
+    }
+  }
+  return Array.from(owners).sort();
+}
+function getUniqueSpecDomains(specs) {
+  const domains = new Set;
+  for (const spec of specs) {
+    domains.add(SpecGroupingStrategies.byDomain(spec));
+  }
+  return Array.from(domains).sort();
+}
+function filterFeatures(features, filter) {
+  return features.filter((feature) => {
+    if (filter.tags?.length) {
+      const hasMatchingTag = filter.tags.some((tag) => feature.tags?.includes(tag));
+      if (!hasMatchingTag)
+        return false;
+    }
+    if (filter.owners?.length) {
+      const hasMatchingOwner = filter.owners.some((owner) => feature.owners?.includes(owner));
+      if (!hasMatchingOwner)
+        return false;
+    }
+    if (filter.stability?.length) {
+      if (!filter.stability.includes(feature.stability ?? "stable")) {
+        return false;
+      }
+    }
+    if (filter.namePattern) {
+      const pattern = filter.namePattern.replace(/\*/g, ".*").replace(/\?/g, ".");
+      const regex = new RegExp(`^${pattern}$`, "i");
+      if (!regex.test(feature.key))
+        return false;
+    }
+    return true;
+  });
+}
+// src/analysis/diff/semantic.ts
+function computeSemanticDiff(aCode, aPath, bCode, bPath, options = {}) {
+  const a = scanSpecSource(aCode, aPath);
+  const b = scanSpecSource(bCode, bPath);
+  const diffs = [];
+  compareScalar(diffs, "specType", a.specType, b.specType, {
+    breaking: true,
+    label: "Spec type"
+  });
+  compareScalar(diffs, "key", a.key, b.key, {
+    breaking: true,
+    label: "Key"
+  });
+  compareScalar(diffs, "version", a.version, b.version, {
+    breaking: true,
+    label: "Version"
+  });
+  compareScalar(diffs, "kind", a.kind, b.kind, {
+    breaking: true,
+    label: "Kind"
+  });
+  compareScalar(diffs, "stability", a.stability, b.stability, {
+    breaking: isStabilityDowngrade(a, b),
+    label: "Stability"
+  });
+  compareArray(diffs, "owners", a.owners ?? [], b.owners ?? [], {
+    label: "Owners"
+  });
+  compareArray(diffs, "tags", a.tags ?? [], b.tags ?? [], { label: "Tags" });
+  compareStructuralHints(diffs, a, b);
+  const filtered = options.breakingOnly ? diffs.filter((d) => d.type === "breaking") : diffs;
+  return filtered;
+}
+function compareScalar(diffs, path, a, b, config) {
+  if (a === b)
+    return;
+  diffs.push({
+    type: config.breaking ? "breaking" : "changed",
+    path,
+    oldValue: a,
+    newValue: b,
+    description: `${config.label} changed`
+  });
+}
+function compareArray(diffs, path, a, b, config) {
+  const aSorted = [...a].sort();
+  const bSorted = [...b].sort();
+  if (JSON.stringify(aSorted) === JSON.stringify(bSorted))
+    return;
+  diffs.push({
+    type: "changed",
+    path,
+    oldValue: aSorted,
+    newValue: bSorted,
+    description: `${config.label} changed`
+  });
+}
+function isStabilityDowngrade(a, b) {
+  const order = {
+    experimental: 0,
+    beta: 1,
+    stable: 2,
+    deprecated: 3
+  };
+  const aValue = a.stability ? order[a.stability] ?? 0 : 0;
+  const bValue = b.stability ? order[b.stability] ?? 0 : 0;
+  return bValue > aValue;
+}
+function compareStructuralHints(diffs, a, b) {
+  compareScalar(diffs, "hasMeta", a.hasMeta, b.hasMeta, {
+    breaking: a.specType === "operation" || b.specType === "operation",
+    label: "meta section presence"
+  });
+  compareScalar(diffs, "hasIo", a.hasIo, b.hasIo, {
+    breaking: a.specType === "operation" || b.specType === "operation",
+    label: "io section presence"
+  });
+  compareScalar(diffs, "hasPolicy", a.hasPolicy, b.hasPolicy, {
+    breaking: a.specType === "operation" || b.specType === "operation",
+    label: "policy section presence"
+  });
+  compareScalar(diffs, "hasPayload", a.hasPayload, b.hasPayload, {
+    breaking: a.specType === "event" || b.specType === "event",
+    label: "payload section presence"
+  });
+  compareScalar(diffs, "hasContent", a.hasContent, b.hasContent, {
+    breaking: a.specType === "presentation" || b.specType === "presentation",
+    label: "content section presence"
+  });
+  compareScalar(diffs, "hasDefinition", a.hasDefinition, b.hasDefinition, {
+    breaking: a.specType === "workflow" || b.specType === "workflow",
+    label: "definition section presence"
+  });
+}
+// src/analysis/diff/deep-diff.ts
+function computeIoDiff(base, head, options = {}) {
+  const diffs = [];
+  diffs.push(...computeFieldsDiff(base.input, head.input, "io.input", options));
+  diffs.push(...computeFieldsDiff(base.output, head.output, "io.output", options));
+  return options.breakingOnly ? diffs.filter((d) => d.type === "breaking") : diffs;
+}
+function computeFieldsDiff(baseFields, headFields, pathPrefix, options = {}) {
+  const diffs = [];
+  const baseNames = new Set(Object.keys(baseFields));
+  const headNames = new Set(Object.keys(headFields));
+  for (const name of baseNames) {
+    if (!headNames.has(name)) {
+      const baseField = baseFields[name];
+      diffs.push({
+        type: "breaking",
+        path: `${pathPrefix}.${name}`,
+        oldValue: baseField,
+        newValue: undefined,
+        description: `Field '${name}' was removed`
+      });
+    }
+  }
+  for (const name of headNames) {
+    if (!baseNames.has(name)) {
+      const headField = headFields[name];
+      const isBreaking = headField?.required === true;
+      diffs.push({
+        type: isBreaking ? "breaking" : "added",
+        path: `${pathPrefix}.${name}`,
+        oldValue: undefined,
+        newValue: headField,
+        description: isBreaking ? `Required field '${name}' was added` : `Optional field '${name}' was added`
+      });
+    }
+  }
+  for (const name of baseNames) {
+    if (headNames.has(name)) {
+      const baseField = baseFields[name];
+      const headField = headFields[name];
+      if (baseField && headField) {
+        diffs.push(...computeFieldDiff(baseField, headField, `${pathPrefix}.${name}`, options));
+      }
+    }
+  }
+  return diffs;
+}
+function computeFieldDiff(base, head, path, _options = {}) {
+  const diffs = [];
+  if (base.type !== head.type) {
+    diffs.push({
+      type: "breaking",
+      path: `${path}.type`,
+      oldValue: base.type,
+      newValue: head.type,
+      description: `Field type changed from '${base.type}' to '${head.type}'`
+    });
+  }
+  if (base.required !== head.required) {
+    const isBreaking = !base.required && head.required;
+    diffs.push({
+      type: isBreaking ? "breaking" : "changed",
+      path: `${path}.required`,
+      oldValue: base.required,
+      newValue: head.required,
+      description: isBreaking ? `Field '${base.name}' changed from optional to required` : `Field '${base.name}' changed from required to optional`
+    });
+  }
+  if (base.nullable !== head.nullable) {
+    const isBreaking = base.nullable && !head.nullable;
+    diffs.push({
+      type: isBreaking ? "breaking" : "changed",
+      path: `${path}.nullable`,
+      oldValue: base.nullable,
+      newValue: head.nullable,
+      description: isBreaking ? `Field '${base.name}' is no longer nullable` : `Field '${base.name}' is now nullable`
+    });
+  }
+  if (base.type === "enum" && head.type === "enum") {
+    const baseValues = new Set(base.enumValues ?? []);
+    const headValues = new Set(head.enumValues ?? []);
+    for (const value of baseValues) {
+      if (!headValues.has(value)) {
+        diffs.push({
+          type: "breaking",
+          path: `${path}.enumValues`,
+          oldValue: base.enumValues,
+          newValue: head.enumValues,
+          description: `Enum value '${value}' was removed`
+        });
+      }
+    }
+    for (const value of headValues) {
+      if (!baseValues.has(value)) {
+        diffs.push({
+          type: "added",
+          path: `${path}.enumValues`,
+          oldValue: base.enumValues,
+          newValue: head.enumValues,
+          description: `Enum value '${value}' was added`
+        });
+      }
+    }
+  }
+  if (base.type === "object" && head.type === "object" && base.properties && head.properties) {
+    diffs.push(...computeFieldsDiff(base.properties, head.properties, path, _options));
+  }
+  if (base.type === "array" && head.type === "array" && base.items && head.items) {
+    diffs.push(...computeFieldDiff(base.items, head.items, `${path}.items`, _options));
+  }
+  return diffs;
+}
+function isBreakingChange(diff, context) {
+  if (context === "output") {
+    return diff.type === "breaking" || diff.type === "removed";
+  }
+  if (context === "input") {
+    if (diff.type === "added" && diff.description?.includes("Required field")) {
+      return true;
+    }
+    return diff.type === "breaking";
+  }
+  return diff.type === "breaking";
+}
+// src/analysis/deps/graph.ts
+function buildReverseEdges(graph) {
+  for (const node of graph.values()) {
+    node.dependents = [];
+  }
+  for (const [key, node] of graph) {
+    for (const dep of node.dependencies) {
+      const depNode = graph.get(dep);
+      if (depNode) {
+        depNode.dependents.push(key);
+      }
+    }
+  }
+  for (const node of graph.values()) {
+    node.dependents.sort((a, b) => a.localeCompare(b));
+  }
+}
+function detectCycles(graph) {
+  const visited = new Set;
+  const stack = new Set;
+  const cycles = [];
+  function dfs(key, path) {
+    if (stack.has(key)) {
+      const start = path.indexOf(key);
+      if (start >= 0)
+        cycles.push([...path.slice(start), key]);
+      return;
+    }
+    if (visited.has(key))
+      return;
+    visited.add(key);
+    stack.add(key);
+    const node = graph.get(key);
+    if (node) {
+      for (const dep of node.dependencies) {
+        dfs(dep, [...path, key]);
+      }
+    }
+    stack.delete(key);
+  }
+  for (const key of graph.keys()) {
+    if (!visited.has(key))
+      dfs(key, []);
+  }
+  return cycles;
+}
+function findMissingDependencies(graph) {
+  const missing = [];
+  for (const [key, node] of graph) {
+    const absent = node.dependencies.filter((dep) => !graph.has(dep));
+    if (absent.length > 0) {
+      missing.push({ contract: key, missing: absent });
+    }
+  }
+  return missing;
+}
+function toDot(graph) {
+  const lines = [];
+  lines.push("digraph ContractDependencies {");
+  lines.push("  rankdir=LR;");
+  lines.push("  node [shape=box];");
+  for (const [key, node] of graph) {
+    for (const dep of node.dependencies) {
+      lines.push(`  "${key}" -> "${dep}";`);
+    }
+    if (node.dependencies.length === 0) {
+      lines.push(`  "${key}";`);
+    }
+  }
+  lines.push("}");
+  return lines.join(`
+`);
+}
+function createContractGraph() {
+  return new Map;
+}
+function addContractNode(graph, key, file, dependencies) {
+  graph.set(key, {
+    key,
+    file,
+    dependencies,
+    dependents: []
+  });
+}
+// src/analysis/deps/parse-imports.ts
+function parseImportedSpecNames(sourceCode, _fromFilePath) {
+  const imports = [];
+  const importRegex = /import\s+.*?\s+from\s+['"]([^'"]+\.(?:contracts|contract|operation|operations|event|presentation|workflow|data-view|migration|telemetry|experiment|app-config|integration|knowledge)(?:\.[jt]s)?)['"]/g;
+  let match;
+  while ((match = importRegex.exec(sourceCode)) !== null) {
+    const importPath = match[1];
+    if (!importPath)
+      continue;
+    if (!importPath.startsWith(".") && !importPath.startsWith("/"))
+      continue;
+    const pathParts = importPath.split("/");
+    const base = pathParts[pathParts.length - 1] ?? "";
+    const name = base.replace(/\.(ts|js)$/, "").replace(/\.(contracts|contract|operation|operations|event|presentation|workflow|data-view|migration|telemetry|experiment|app-config|integration|knowledge)$/, "");
+    if (name.length > 0) {
+      imports.push(name);
+    }
+  }
+  return Array.from(new Set(imports)).sort((a, b) => a.localeCompare(b));
+}
+// src/analysis/validate/spec-structure.ts
+import {
+  Node as Node2,
+  Project as Project2,
+  SyntaxKind as SyntaxKind2
+} from "ts-morph";
+var DEFAULT_RULES_CONFIG = {
+  getRule: () => "warn"
+};
+function validateSpecStructure(specFile, rulesConfig = DEFAULT_RULES_CONFIG) {
+  const errors = [];
+  const warnings = [];
+  const project = new Project2({ useInMemoryFileSystem: true });
+  const sourceFile = project.createSourceFile(specFile.filePath, specFile.sourceBlock);
+  const hasExport = sourceFile.getExportAssignments().length > 0 || sourceFile.getVariableStatements().some((s) => s.isExported()) || sourceFile.getFunctions().some((f) => f.isExported()) || sourceFile.getClasses().some((c) => c.isExported()) || sourceFile.getExportDeclarations().length > 0;
+  if (!hasExport) {
+    errors.push("No exported spec found");
+  }
+  switch (specFile.specType) {
+    case "operation":
+      validateOperationSpec(sourceFile, errors, warnings, rulesConfig);
+      break;
+    case "event":
+      validateEventSpec(sourceFile, errors, warnings, rulesConfig);
+      break;
+    case "presentation":
+      validatePresentationSpec(sourceFile, errors, warnings);
+      break;
+    case "workflow":
+      validateWorkflowSpec(sourceFile, errors, warnings, rulesConfig);
+      break;
+    case "data-view":
+      validateDataViewSpec(sourceFile, errors, warnings, rulesConfig);
+      break;
+    case "migration":
+      validateMigrationSpec(sourceFile, errors, warnings, rulesConfig);
+      break;
+    case "telemetry":
+      validateTelemetrySpec(sourceFile, errors, warnings, rulesConfig);
+      break;
+    case "app-config":
+      validateAppConfigSpec(sourceFile, errors, warnings, rulesConfig);
+      break;
+    case "experiment":
+      validateExperimentSpec(sourceFile, errors, warnings, rulesConfig);
+      break;
+  }
+  validateCommonFields(sourceFile, specFile.filePath, errors, warnings, rulesConfig);
+  return {
+    valid: errors.length === 0,
+    errors,
+    warnings
+  };
+}
+function emitRule(ruleName, specKind, message, errors, warnings, rulesConfig) {
+  const severity = rulesConfig.getRule(ruleName, specKind);
+  if (severity === "off")
+    return;
+  if (severity === "error") {
+    errors.push(message);
+  } else {
+    warnings.push(message);
+  }
+}
+function validateOperationSpec(sourceFile, errors, warnings, rulesConfig) {
+  const callExpressions = sourceFile.getDescendantsOfKind(SyntaxKind2.CallExpression);
+  const hasDefine = callExpressions.some((call) => {
+    const text = call.getExpression().getText();
+    return text === "defineCommand" || text === "defineQuery";
+  });
+  if (!hasDefine) {
+    errors.push("Missing defineCommand or defineQuery call");
+  }
+  let specObject;
+  for (const call of callExpressions) {
+    const text = call.getExpression().getText();
+    if (text === "defineCommand" || text === "defineQuery") {
+      const args = call.getArguments();
+      if (args.length > 0 && Node2.isObjectLiteralExpression(args[0])) {
+        specObject = args[0];
+        break;
+      }
+    }
+  }
+  if (specObject && Node2.isObjectLiteralExpression(specObject)) {
+    if (!specObject.getProperty("meta")) {
+      errors.push("Missing meta section");
+    }
+    if (!specObject.getProperty("io")) {
+      errors.push("Missing io section");
+    }
+    if (!specObject.getProperty("policy")) {
+      errors.push("Missing policy section");
+    }
+    const metaProp = specObject.getProperty("meta");
+    let hasKey = false;
+    let hasVersion = false;
+    if (metaProp && Node2.isPropertyAssignment(metaProp)) {
+      const metaObj = metaProp.getInitializer();
+      if (metaObj && Node2.isObjectLiteralExpression(metaObj)) {
+        if (metaObj.getProperty("key"))
+          hasKey = true;
+        if (metaObj.getProperty("version"))
+          hasVersion = true;
+      }
+    }
+    if (!hasKey) {
+      if (specObject.getProperty("key"))
+        hasKey = true;
+    }
+    if (!hasKey) {
+      errors.push("Missing or invalid key field");
+    }
+    if (!hasVersion) {
+      if (specObject.getProperty("version"))
+        hasVersion = true;
+    }
+    if (!hasVersion) {
+      errors.push("Missing or invalid version field");
+    }
+    const hasExplicitKind = specObject.getProperty("kind");
+    const callText = callExpressions.find((c) => {
+      const t = c.getExpression().getText();
+      return t === "defineCommand" || t === "defineQuery";
+    })?.getExpression().getText();
+    if (!callText && !hasExplicitKind) {
+      errors.push("Missing kind: use defineCommand(), defineQuery(), or explicit kind field");
+    }
+    if (!specObject.getProperty("acceptance")) {
+      emitRule("require-acceptance", "operation", "No acceptance scenarios defined", errors, warnings, rulesConfig);
+    }
+    if (!specObject.getProperty("examples")) {
+      emitRule("require-examples", "operation", "No examples provided", errors, warnings, rulesConfig);
+    }
+  }
+  const fullText = sourceFile.getFullText();
+  if (fullText.includes("TODO")) {
+    emitRule("no-todo", "operation", "Contains TODO items that need completion", errors, warnings, rulesConfig);
+  }
+}
+function validateTelemetrySpec(sourceFile, errors, warnings, rulesConfig) {
+  const specObject = getSpecObject(sourceFile, "TelemetrySpec");
+  if (!specObject) {
+    errors.push("Missing TelemetrySpec type annotation");
+    return;
+  }
+  if (specObject) {
+    const metaProp = specObject.getProperty("meta");
+    let hasName = false;
+    if (metaProp && Node2.isPropertyAssignment(metaProp)) {
+      const metaObj = metaProp.getInitializer();
+      if (Node2.isObjectLiteralExpression(metaObj)) {
+        if (metaObj.getProperty("name"))
+          hasName = true;
+      }
+    }
+    if (!hasName) {
+      errors.push("TelemetrySpec.meta is required");
+    }
+    if (!specObject.getProperty("events")) {
+      errors.push("TelemetrySpec must declare events");
+    }
+    const privacyProp = specObject.getProperty("privacy");
+    if (!privacyProp) {
+      emitRule("telemetry-privacy", "telemetry", "No explicit privacy classification found", errors, warnings, rulesConfig);
+    }
+  }
+}
+function validateExperimentSpec(sourceFile, errors, warnings, rulesConfig) {
+  const specObject = getSpecObject(sourceFile, "ExperimentSpec");
+  if (!specObject) {
+    errors.push("Missing ExperimentSpec type annotation");
+    return;
+  }
+  if (!specObject.getProperty("controlVariant")) {
+    errors.push("ExperimentSpec must declare controlVariant");
+  }
+  if (!specObject.getProperty("variants")) {
+    errors.push("ExperimentSpec must declare variants");
+  }
+  if (!specObject.getProperty("allocation")) {
+    emitRule("experiment-allocation", "experiment", "ExperimentSpec missing allocation configuration", errors, warnings, rulesConfig);
+  }
+}
+function validateAppConfigSpec(sourceFile, errors, warnings, rulesConfig) {
+  const callExpressions = sourceFile.getDescendantsOfKind(SyntaxKind2.CallExpression);
+  const defineCall = callExpressions.find((c) => c.getExpression().getText() === "defineAppConfig");
+  let specObject;
+  if (defineCall) {
+    const args = defineCall.getArguments();
+    if (args.length > 0 && Node2.isObjectLiteralExpression(args[0])) {
+      specObject = args[0];
+    }
+  } else {
+    specObject = getSpecObject(sourceFile, "AppBlueprintSpec");
+  }
+  if (!specObject) {
+    errors.push("Missing defineAppConfig call or AppBlueprintSpec type annotation");
+    return;
+  }
+  const metaProp = specObject.getProperty("meta");
+  if (!metaProp) {
+    errors.push("AppBlueprintSpec must define meta");
+  } else if (Node2.isPropertyAssignment(metaProp)) {
+    const metaObj = metaProp.getInitializer();
+    if (Node2.isObjectLiteralExpression(metaObj)) {
+      if (!metaObj.getProperty("appId")) {
+        emitRule("app-config-appid", "app-config", "AppBlueprint meta missing appId assignment", errors, warnings, rulesConfig);
+      }
+    }
+  }
+  if (!specObject.getProperty("capabilities")) {
+    emitRule("app-config-capabilities", "app-config", "App blueprint spec does not declare capabilities", errors, warnings, rulesConfig);
+  }
+}
+function validateEventSpec(sourceFile, errors, warnings, rulesConfig) {
+  const callExpressions = sourceFile.getDescendantsOfKind(SyntaxKind2.CallExpression);
+  const defineEventCall = callExpressions.find((c) => c.getExpression().getText() === "defineEvent");
+  if (!defineEventCall) {
+    errors.push("Missing defineEvent call");
+    return;
+  }
+  let specObject;
+  const args = defineEventCall.getArguments();
+  if (args.length > 0 && Node2.isObjectLiteralExpression(args[0])) {
+    specObject = args[0];
+  }
+  if (specObject && Node2.isObjectLiteralExpression(specObject)) {
+    const metaProp = specObject.getProperty("meta");
+    let hasKey = false;
+    let hasVersion = false;
+    if (metaProp && Node2.isPropertyAssignment(metaProp)) {
+      const metaObj = metaProp.getInitializer();
+      if (Node2.isObjectLiteralExpression(metaObj)) {
+        const keyP = metaObj.getProperty("key");
+        if (keyP && Node2.isPropertyAssignment(keyP)) {
+          const init = keyP.getInitializer();
+          if (init && Node2.isStringLiteral(init)) {
+            hasKey = true;
+          }
+        }
+        if (metaObj.getProperty("version"))
+          hasVersion = true;
+      }
+    }
+    if (!hasKey) {
+      const kp = specObject.getProperty("key");
+      if (kp && Node2.isPropertyAssignment(kp)) {
+        const init = kp.getInitializer();
+        if (init && Node2.isStringLiteral(init)) {
+          hasKey = true;
+        }
+      }
+    }
+    if (!hasVersion && specObject.getProperty("version"))
+      hasVersion = true;
+    if (!hasKey) {
+      errors.push("Missing or invalid key field");
+    }
+    if (!hasVersion) {
+      errors.push("Missing or invalid version field");
+    }
+    if (!specObject.getProperty("payload")) {
+      errors.push("Missing payload field");
+    }
+    let name = "";
+    const getName = (obj) => {
+      const init = obj.getInitializer();
+      if (init && Node2.isStringLiteral(init)) {
+        return init.getLiteralText();
+      }
+      return "";
+    };
+    if (metaProp && Node2.isPropertyAssignment(metaProp)) {
+      const metaObj = metaProp.getInitializer();
+      if (Node2.isObjectLiteralExpression(metaObj)) {
+        const nameP = metaObj.getProperty("name");
+        if (nameP && Node2.isPropertyAssignment(nameP)) {
+          name = getName(nameP);
+        }
+      }
+    }
+    if (!name) {
+      const nameP = specObject.getProperty("name");
+      if (nameP && Node2.isPropertyAssignment(nameP)) {
+        name = getName(nameP);
+      }
+    }
+    if (name) {
+      const eventName = name.split(".").pop() ?? "";
+      if (!eventName.match(/(ed|created|updated|deleted|completed)$/i)) {
+        emitRule("event-past-tense", "event", 'Event name should use past tense (e.g., "created", "updated")', errors, warnings, rulesConfig);
+      }
+    }
+  }
+}
+function validatePresentationSpec(sourceFile, errors, _warnings) {
+  const callExpressions = sourceFile.getDescendantsOfKind(SyntaxKind2.CallExpression);
+  const defineCall = callExpressions.find((c) => c.getExpression().getText() === "definePresentation");
+  let specObject;
+  if (defineCall) {
+    const args = defineCall.getArguments();
+    if (args.length > 0 && Node2.isObjectLiteralExpression(args[0])) {
+      specObject = args[0];
+    }
+  } else {
+    specObject = getSpecObject(sourceFile, "PresentationSpec");
+  }
+  if (!specObject) {
+    errors.push("Missing definePresentation call or PresentationSpec type annotation");
+    return;
+  }
+  if (!specObject.getProperty("meta")) {
+    errors.push("Missing meta section");
+  }
+  const sourceProp = specObject.getProperty("source");
+  if (!sourceProp) {
+    errors.push("Missing source section");
+  } else if (Node2.isPropertyAssignment(sourceProp)) {
+    const sourceObj = sourceProp.getInitializer();
+    if (Node2.isObjectLiteralExpression(sourceObj)) {
+      const typeProp = sourceObj.getProperty("type");
+      if (!typeProp) {
+        errors.push("Missing or invalid source.type field");
+      } else if (Node2.isPropertyAssignment(typeProp)) {
+        const init = typeProp.getInitializer();
+        if (init && Node2.isStringLiteral(init)) {
+          const val = init.getLiteralText();
+          if (val !== "component" && val !== "blocknotejs") {
+            errors.push("Missing or invalid source.type field");
+          }
+        }
+      }
+    }
+  }
+  if (!specObject.getProperty("targets")) {
+    errors.push("Missing targets section");
+  }
+}
+function validateWorkflowSpec(sourceFile, errors, warnings, rulesConfig) {
+  const callExpressions = sourceFile.getDescendantsOfKind(SyntaxKind2.CallExpression);
+  const defineCall = callExpressions.find((c) => c.getExpression().getText() === "defineWorkflow");
+  let specObject;
+  if (defineCall) {
+    const args = defineCall.getArguments();
+    if (args.length > 0 && Node2.isObjectLiteralExpression(args[0])) {
+      specObject = args[0];
+    }
+  } else {
+    specObject = getSpecObject(sourceFile, "WorkflowSpec");
+  }
+  if (!specObject) {
+    errors.push("Missing defineWorkflow call or WorkflowSpec type annotation");
+    return;
+  }
+  if (!specObject.getProperty("definition")) {
+    errors.push("Missing definition section");
+  } else {
+    const defProp = specObject.getProperty("definition");
+    if (defProp && Node2.isPropertyAssignment(defProp)) {
+      const defObj = defProp.getInitializer();
+      if (Node2.isObjectLiteralExpression(defObj)) {
+        if (!defObj.getProperty("steps")) {
+          errors.push("Workflow must declare steps");
+        }
+        if (!defObj.getProperty("transitions")) {
+          emitRule("workflow-transitions", "workflow", "No transitions declared; workflow will complete after first step.", errors, warnings, rulesConfig);
+        }
+      }
+    }
+  }
+  let titleFound = false;
+  let domainFound = false;
+  const metaProp = specObject.getProperty("meta");
+  if (metaProp && Node2.isPropertyAssignment(metaProp)) {
+    const metaObj = metaProp.getInitializer();
+    if (Node2.isObjectLiteralExpression(metaObj)) {
+      if (metaObj.getProperty("title"))
+        titleFound = true;
+      if (metaObj.getProperty("domain"))
+        domainFound = true;
+    }
+  }
+  if (!titleFound && specObject.getProperty("title"))
+    titleFound = true;
+  if (!domainFound && specObject.getProperty("domain"))
+    domainFound = true;
+  if (!titleFound) {
+    warnings.push("Missing workflow title");
+  }
+  if (!domainFound) {
+    warnings.push("Missing domain field");
+  }
+  if (sourceFile.getFullText().includes("TODO")) {
+    emitRule("no-todo", "workflow", "Contains TODO items that need completion", errors, warnings, rulesConfig);
+  }
+}
+function validateMigrationSpec(sourceFile, errors, warnings, rulesConfig) {
+  const specObject = getSpecObject(sourceFile, "MigrationSpec");
+  if (!specObject) {
+    errors.push("Missing MigrationSpec type annotation");
+    return;
+  }
+  const planProp = specObject.getProperty("plan");
+  if (!planProp) {
+    errors.push("Missing plan section");
+  } else if (Node2.isPropertyAssignment(planProp)) {
+    const planObj = planProp.getInitializer();
+    if (Node2.isObjectLiteralExpression(planObj)) {
+      if (!planObj.getProperty("up")) {
+        errors.push("Migration must define at least one up step");
+      }
+    }
+  }
+  let nameFound = false;
+  let versionFound = false;
+  const metaProp = specObject.getProperty("meta");
+  if (metaProp && Node2.isPropertyAssignment(metaProp)) {
+    const metaObj = metaProp.getInitializer();
+    if (Node2.isObjectLiteralExpression(metaObj)) {
+      if (metaObj.getProperty("name"))
+        nameFound = true;
+      if (metaObj.getProperty("version"))
+        versionFound = true;
+    }
+  }
+  if (!nameFound && specObject.getProperty("name"))
+    nameFound = true;
+  if (!versionFound && specObject.getProperty("version"))
+    versionFound = true;
+  if (!nameFound) {
+    errors.push("Missing or invalid migration name");
+  }
+  if (!versionFound) {
+    errors.push("Missing or invalid migration version");
+  }
+  if (sourceFile.getFullText().includes("TODO")) {
+    emitRule("no-todo", "migration", "Contains TODO items that need completion", errors, warnings, rulesConfig);
+  }
+}
+function validateCommonFields(sourceFile, fileName, errors, warnings, rulesConfig) {
+  const code = sourceFile.getFullText();
+  const isInternalLib = fileName.includes("/libs/contracts/") || fileName.includes("/libs/contracts-transformers/") || fileName.includes("/libs/schema/");
+  if (code.includes("SchemaModel") && !isInternalLib) {
+    const imports = sourceFile.getImportDeclarations();
+    const hasSchemaImport = imports.some((i) => i.getModuleSpecifierValue().includes("@contractspec/lib.schema"));
+    if (!hasSchemaImport) {
+      errors.push("Missing import for SchemaModel from @contractspec/lib.schema");
+    }
+  }
+  const usesSpecTypes = code.includes("OperationSpec") || code.includes("PresentationSpec") || code.includes("EventSpec") || code.includes("FeatureSpec") || code.includes("WorkflowSpec") || code.includes("DataViewSpec") || code.includes("MigrationSpec") || code.includes("TelemetrySpec") || code.includes("ExperimentSpec") || code.includes("AppBlueprintSpec") || code.includes("defineCommand") || code.includes("defineQuery") || code.includes("defineEvent") || code.includes("definePresentation") || code.includes("defineWorkflow") || code.includes("defineDataView") || code.includes("defineAppConfig") || code.includes("defineFeature") || code.includes("defineExperiment") || code.includes("defineTelemetry") || code.includes("defineMigration");
+  if (usesSpecTypes && !isInternalLib) {
+    const imports = sourceFile.getImportDeclarations();
+    const hasContractsImport = imports.some((i) => i.getModuleSpecifierValue().includes("@contractspec/lib.contracts"));
+    if (!hasContractsImport) {
+      errors.push("Missing import from @contractspec/lib.contracts");
+    }
+  }
+  const specObject = findMainExportedObject(sourceFile);
+  if (specObject && Node2.isObjectLiteralExpression(specObject)) {
+    const ownersProp = specObject.getProperty("owners");
+    let ownersArr = undefined;
+    const checkOwners = (prop) => {
+      if (Node2.isPropertyAssignment(prop)) {
+        const init = prop.getInitializer();
+        if (init && Node2.isArrayLiteralExpression(init)) {
+          return init;
+        }
+      }
+      return;
+    };
+    if (ownersProp)
+      ownersArr = checkOwners(ownersProp);
+    if (!ownersArr) {
+      const metaProp = specObject.getProperty("meta");
+      if (metaProp && Node2.isPropertyAssignment(metaProp)) {
+        const metaObj = metaProp.getInitializer();
+        if (metaObj && Node2.isObjectLiteralExpression(metaObj)) {
+          const o = metaObj.getProperty("owners");
+          if (o)
+            ownersArr = checkOwners(o);
+        }
+      }
+    }
+    if (ownersArr) {
+      for (const elem of ownersArr.getElements()) {
+        if (Node2.isStringLiteral(elem)) {
+          const val = elem.getLiteralText();
+          if (!val.includes("@") && !val.includes("Enum") && !val.match(/[A-Z][a-zA-Z0-9_]+/)) {
+            emitRule("require-owners-format", "operation", "Owners should start with @ or use an Enum/Constant", errors, warnings, rulesConfig);
+          }
+        }
+      }
+    }
+    let stabilityFound = false;
+    const stabilityProp = specObject.getProperty("stability");
+    if (stabilityProp)
+      stabilityFound = true;
+    if (!stabilityFound) {
+      const metaProp = specObject.getProperty("meta");
+      if (metaProp && Node2.isPropertyAssignment(metaProp)) {
+        const metaObj = metaProp.getInitializer();
+        if (Node2.isObjectLiteralExpression(metaObj)) {
+          if (metaObj.getProperty("stability"))
+            stabilityFound = true;
+        }
+      }
+    }
+    if (!stabilityFound) {
+      emitRule("require-stability", "operation", "Missing or invalid stability field", errors, warnings, rulesConfig);
+    }
+  }
+}
+function validateDataViewSpec(sourceFile, errors, warnings, rulesConfig) {
+  const callExpressions = sourceFile.getDescendantsOfKind(SyntaxKind2.CallExpression);
+  const defineCall = callExpressions.find((c) => c.getExpression().getText() === "defineDataView");
+  let specObject;
+  if (defineCall) {
+    const args = defineCall.getArguments();
+    if (args.length > 0 && Node2.isObjectLiteralExpression(args[0])) {
+      specObject = args[0];
+    }
+  } else {
+    specObject = getSpecObject(sourceFile, "DataViewSpec");
+  }
+  if (!specObject) {
+    errors.push("Missing defineDataView call or DataViewSpec type annotation");
+    return;
+  }
+  if (!specObject.getProperty("meta")) {
+    errors.push("Missing meta section");
+  }
+  if (!specObject.getProperty("source")) {
+    errors.push("Missing source section");
+  }
+  const viewProp = specObject.getProperty("view");
+  if (!viewProp) {
+    errors.push("Missing view section");
+    errors.push("Missing or invalid view.kind (list/table/detail/grid)");
+  } else if (Node2.isPropertyAssignment(viewProp)) {
+    const viewObj = viewProp.getInitializer();
+    if (Node2.isObjectLiteralExpression(viewObj)) {
+      const kindProp = viewObj.getProperty("kind");
+      if (!kindProp) {
+        errors.push("Missing or invalid view.kind (list/table/detail/grid)");
+      } else if (Node2.isPropertyAssignment(kindProp)) {
+        const init = kindProp.getInitializer();
+        if (init && Node2.isStringLiteral(init)) {
+          const val = init.getLiteralText();
+          if (!["list", "table", "detail", "grid"].includes(val)) {
+            errors.push("Missing or invalid view.kind (list/table/detail/grid)");
+          }
+        }
+      }
+    }
+  }
+  let fieldsFound = false;
+  if (viewProp && Node2.isPropertyAssignment(viewProp)) {
+    const viewObj = viewProp.getInitializer();
+    if (Node2.isObjectLiteralExpression(viewObj)) {
+      if (viewObj.getProperty("fields"))
+        fieldsFound = true;
+    }
+  }
+  if (!fieldsFound && specObject.getProperty("fields"))
+    fieldsFound = true;
+  if (!fieldsFound) {
+    emitRule("data-view-fields", "data-view", "No fields defined for data view", errors, warnings, rulesConfig);
+  }
+}
+function getSpecObject(sourceFile, typeName) {
+  const varStmts = sourceFile.getVariableStatements();
+  for (const stmt of varStmts) {
+    if (stmt.isExported()) {
+      for (const decl of stmt.getDeclarations()) {
+        const typeNode = decl.getTypeNode();
+        if (typeNode && typeNode.getText().includes(typeName)) {
+          const init = decl.getInitializer();
+          if (init && Node2.isObjectLiteralExpression(init)) {
+            return init;
+          }
+        }
+      }
+    }
+  }
+  const exportAssign = sourceFile.getExportAssignment((d) => !d.isExportEquals());
+  if (exportAssign) {
+    const expr = exportAssign.getExpression();
+    if (Node2.isAsExpression(expr)) {
+      if (expr.getTypeNode()?.getText().includes(typeName)) {
+        const inner = expr.getExpression();
+        if (Node2.isObjectLiteralExpression(inner))
+          return inner;
+      }
+    }
+    if (Node2.isObjectLiteralExpression(expr)) {
+      return expr;
+    }
+  }
+  return;
+}
+function findMainExportedObject(sourceFile) {
+  const varStmts = sourceFile.getVariableStatements();
+  for (const stmt of varStmts) {
+    if (stmt.isExported()) {
+      for (const decl of stmt.getDeclarations()) {
+        const init = decl.getInitializer();
+        if (init) {
+          if (Node2.isObjectLiteralExpression(init))
+            return init;
+          if (Node2.isCallExpression(init)) {
+            const args = init.getArguments();
+            if (args.length > 0 && Node2.isObjectLiteralExpression(args[0]))
+              return args[0];
+          }
+        }
+      }
+    }
+  }
+  const exportAssign = sourceFile.getExportAssignment((d) => !d.isExportEquals());
+  if (exportAssign) {
+    const expr = exportAssign.getExpression();
+    if (Node2.isObjectLiteralExpression(expr))
+      return expr;
+    if (Node2.isAsExpression(expr) && Node2.isObjectLiteralExpression(expr.getExpression()))
+      return expr.getExpression();
+    if (Node2.isCallExpression(expr)) {
+      const args = expr.getArguments();
+      if (args.length > 0 && Node2.isObjectLiteralExpression(args[0]))
+        return args[0];
+    }
+  }
+  return;
+}
+// src/analysis/snapshot/normalizer.ts
+import { createHash } from "crypto";
+import { compareVersions } from "compare-versions";
+function normalizeValue(value) {
+  if (value === null || value === undefined) {
+    return value === null ? null : undefined;
+  }
+  if (Array.isArray(value)) {
+    return value.map(normalizeValue);
+  }
+  if (typeof value === "object") {
+    const obj = value;
+    const sortedKeys = Object.keys(obj).sort();
+    const normalized = {};
+    for (const key of sortedKeys) {
+      const normalizedValue = normalizeValue(obj[key]);
+      if (normalizedValue !== undefined) {
+        normalized[key] = normalizedValue;
+      }
+    }
+    return normalized;
+  }
+  return value;
+}
+function toCanonicalJson(value) {
+  return JSON.stringify(normalizeValue(value), null, 0);
+}
+function computeHash(value) {
+  const canonical = toCanonicalJson(value);
+  return createHash("sha256").update(canonical).digest("hex").slice(0, 16);
+}
+function sortSpecs(specs) {
+  return [...specs].sort((a, b) => {
+    const keyCompare = a.key.localeCompare(b.key);
+    if (keyCompare !== 0)
+      return keyCompare;
+    return compareVersions(a.version, b.version);
+  });
+}
+function sortFields(fields) {
+  const sorted = {};
+  const keys = Object.keys(fields).sort();
+  for (const key of keys) {
+    sorted[key] = fields[key];
+  }
+  return sorted;
+}
+// src/analysis/snapshot/snapshot.ts
+function generateSnapshot(specs, options = {}) {
+  const snapshots = [];
+  for (const { path, content } of specs) {
+    const scanned = scanSpecSource(content, path);
+    if (options.types && !options.types.includes(scanned.specType)) {
+      continue;
+    }
+    if (scanned.specType === "operation" && scanned.key && scanned.version !== undefined) {
+      const opSnapshot = createOperationSnapshot(scanned, content);
+      if (opSnapshot) {
+        snapshots.push(opSnapshot);
+      }
+    } else if (scanned.specType === "event" && scanned.key && scanned.version !== undefined) {
+      const eventSnapshot = createEventSnapshot(scanned, content);
+      if (eventSnapshot) {
+        snapshots.push(eventSnapshot);
+      }
+    }
+  }
+  const sortedSpecs = sortSpecs(snapshots);
+  const hash = computeHash({ specs: sortedSpecs });
+  return {
+    version: "1.0.0",
+    generatedAt: new Date().toISOString(),
+    specs: sortedSpecs,
+    hash
+  };
+}
+function createOperationSnapshot(scanned, content) {
+  if (!scanned.key || scanned.version === undefined) {
+    return null;
+  }
+  const io = extractIoFromSource(content);
+  const http = extractHttpBinding(content);
+  return {
+    type: "operation",
+    key: scanned.key,
+    version: scanned.version,
+    kind: scanned.kind === "command" || scanned.kind === "query" ? scanned.kind : "command",
+    stability: scanned.stability ?? "experimental",
+    http: http ?? undefined,
+    io,
+    authLevel: extractAuthLevel(content),
+    emittedEvents: scanned.emittedEvents
+  };
+}
+function createEventSnapshot(scanned, content) {
+  if (!scanned.key || scanned.version === undefined) {
+    return null;
+  }
+  const payload = extractPayloadFromSource(content);
+  return {
+    type: "event",
+    key: scanned.key,
+    version: scanned.version,
+    stability: scanned.stability ?? "experimental",
+    payload
+  };
+}
+function extractIoFromSource(content) {
+  const input = extractSchemaFields(content, "input");
+  const output = extractSchemaFields(content, "output");
+  return {
+    input: sortFields(input),
+    output: sortFields(output)
+  };
+}
+function extractPayloadFromSource(content) {
+  const fields = extractSchemaFields(content, "payload");
+  return sortFields(fields);
+}
+function extractSchemaFields(content, section) {
+  const fields = {};
+  const sectionPattern = new RegExp(`${section}\\s*:\\s*z\\.object\\(\\{([^}]+)\\}`, "s");
+  const sectionMatch = content.match(sectionPattern);
+  if (!sectionMatch?.[1]) {
+    return fields;
+  }
+  const sectionContent = sectionMatch[1];
+  const fieldPattern = /(\w+)\s*:\s*z\.(\w+)\((.*?)\)/g;
+  let match;
+  while ((match = fieldPattern.exec(sectionContent)) !== null) {
+    const [, fieldName, zodType] = match;
+    if (!fieldName || !zodType)
+      continue;
+    const isOptional = sectionContent.includes(`${fieldName}:`) && sectionContent.slice(sectionContent.indexOf(`${fieldName}:`)).includes(".optional()");
+    const isNullable = sectionContent.includes(`${fieldName}:`) && sectionContent.slice(sectionContent.indexOf(`${fieldName}:`)).includes(".nullable()");
+    fields[fieldName] = {
+      name: fieldName,
+      type: mapZodTypeToFieldType(zodType),
+      required: !isOptional,
+      nullable: isNullable
+    };
+  }
+  return fields;
+}
+function mapZodTypeToFieldType(zodType) {
+  const mapping = {
+    string: "string",
+    number: "number",
+    boolean: "boolean",
+    object: "object",
+    array: "array",
+    enum: "enum",
+    union: "union",
+    literal: "literal",
+    date: "date",
+    coerce: "unknown"
+  };
+  return mapping[zodType] ?? "unknown";
+}
+function extractHttpBinding(content) {
+  const methodMatch = content.match(/method\s*:\s*['"](\w+)['"]/);
+  const pathMatch = content.match(/path\s*:\s*['"]([^'"]+)['"]/);
+  if (methodMatch?.[1] && pathMatch?.[1]) {
+    const method = methodMatch[1].toUpperCase();
+    if (["GET", "POST", "PUT", "PATCH", "DELETE"].includes(method)) {
+      return {
+        method,
+        path: pathMatch[1]
+      };
+    }
+  }
+  return null;
+}
+function extractAuthLevel(content) {
+  const authMatch = content.match(/auth\s*:\s*['"](\w+)['"]/);
+  return authMatch?.[1];
+}
+// src/analysis/impact/rules.ts
+var BREAKING_RULES = [
+  {
+    id: "endpoint-removed",
+    description: "Endpoint/operation was removed",
+    severity: "breaking",
+    matches: (delta) => delta.path.includes("spec.") && delta.type === "removed"
+  },
+  {
+    id: "field-removed",
+    description: "Field was removed from response",
+    severity: "breaking",
+    matches: (delta) => delta.path.includes(".output.") && delta.description.includes("removed")
+  },
+  {
+    id: "field-type-changed",
+    description: "Field type was changed",
+    severity: "breaking",
+    matches: (delta) => delta.path.includes(".type") && delta.description.includes("type changed")
+  },
+  {
+    id: "field-made-required",
+    description: "Optional field became required",
+    severity: "breaking",
+    matches: (delta) => delta.path.includes(".required") && delta.description.includes("optional to required")
+  },
+  {
+    id: "enum-value-removed",
+    description: "Enum value was removed",
+    severity: "breaking",
+    matches: (delta) => delta.path.includes(".enumValues") && delta.description.includes("removed")
+  },
+  {
+    id: "nullable-removed",
+    description: "Field is no longer nullable",
+    severity: "breaking",
+    matches: (delta) => delta.path.includes(".nullable") && delta.description.includes("no longer nullable")
+  },
+  {
+    id: "method-changed",
+    description: "HTTP method was changed",
+    severity: "breaking",
+    matches: (delta) => delta.path.includes(".http.method") || delta.path.includes(".method")
+  },
+  {
+    id: "path-changed",
+    description: "HTTP path was changed",
+    severity: "breaking",
+    matches: (delta) => delta.path.includes(".http.path") || delta.path.includes(".path")
+  },
+  {
+    id: "required-field-added-to-input",
+    description: "Required field was added to input",
+    severity: "breaking",
+    matches: (delta) => delta.path.includes(".input.") && delta.description.includes("Required field")
+  },
+  {
+    id: "event-payload-field-removed",
+    description: "Event payload field was removed",
+    severity: "breaking",
+    matches: (delta) => delta.path.includes(".payload.") && delta.description.includes("removed")
+  }
+];
+var NON_BREAKING_RULES = [
+  {
+    id: "optional-field-added",
+    description: "Optional field was added",
+    severity: "non_breaking",
+    matches: (delta) => delta.description.includes("Optional field") && delta.description.includes("added")
+  },
+  {
+    id: "endpoint-added",
+    description: "New endpoint/operation was added",
+    severity: "non_breaking",
+    matches: (delta) => delta.path.includes("spec.") && delta.type === "added"
+  },
+  {
+    id: "enum-value-added",
+    description: "Enum value was added",
+    severity: "non_breaking",
+    matches: (delta) => delta.path.includes(".enumValues") && delta.description.includes("added")
+  },
+  {
+    id: "field-made-optional",
+    description: "Required field became optional",
+    severity: "non_breaking",
+    matches: (delta) => delta.path.includes(".required") && delta.description.includes("required to optional")
+  },
+  {
+    id: "nullable-added",
+    description: "Field is now nullable",
+    severity: "non_breaking",
+    matches: (delta) => delta.path.includes(".nullable") && delta.description.includes("now nullable")
+  }
+];
+var INFO_RULES = [
+  {
+    id: "stability-changed",
+    description: "Stability level was changed",
+    severity: "info",
+    matches: (delta) => delta.path.includes(".stability")
+  },
+  {
+    id: "description-changed",
+    description: "Description was changed",
+    severity: "info",
+    matches: (delta) => delta.path.includes(".description")
+  },
+  {
+    id: "owners-changed",
+    description: "Owners were changed",
+    severity: "info",
+    matches: (delta) => delta.path.includes(".owners")
+  },
+  {
+    id: "tags-changed",
+    description: "Tags were changed",
+    severity: "info",
+    matches: (delta) => delta.path.includes(".tags")
+  }
+];
+var DEFAULT_RULES = [
+  ...BREAKING_RULES,
+  ...NON_BREAKING_RULES,
+  ...INFO_RULES
+];
+function getRulesBySeverity(severity) {
+  return DEFAULT_RULES.filter((rule) => rule.severity === severity);
+}
+function findMatchingRule(delta, rules = DEFAULT_RULES) {
+  return rules.find((rule) => rule.matches(delta));
+}
+// src/analysis/impact/classifier.ts
+function classifyImpact(baseSpecs, headSpecs, diffs, options = {}) {
+  const rules = options.customRules ?? DEFAULT_RULES;
+  const deltas = [];
+  const baseMap = new Map(baseSpecs.map((s) => [`${s.key}@${s.version}`, s]));
+  const headMap = new Map(headSpecs.map((s) => [`${s.key}@${s.version}`, s]));
+  const addedSpecs = [];
+  for (const spec of headSpecs) {
+    const lookupKey = `${spec.key}@${spec.version}`;
+    if (!baseMap.has(lookupKey)) {
+      addedSpecs.push({
+        key: spec.key,
+        version: spec.version,
+        type: spec.type
+      });
+    }
+  }
+  const removedSpecs = [];
+  for (const spec of baseSpecs) {
+    const lookupKey = `${spec.key}@${spec.version}`;
+    if (!headMap.has(lookupKey)) {
+      removedSpecs.push({
+        key: spec.key,
+        version: spec.version,
+        type: spec.type
+      });
+      deltas.push({
+        specKey: spec.key,
+        specVersion: spec.version,
+        specType: spec.type,
+        path: `spec.${spec.key}`,
+        severity: "breaking",
+        rule: "endpoint-removed",
+        description: `${spec.type === "operation" ? "Operation" : "Event"} '${spec.key}' was removed`
+      });
+    }
+  }
+  for (const diff of diffs) {
+    const matchingRule = findMatchingRule({ path: diff.path, description: diff.description, type: diff.type }, rules);
+    const specKey = extractSpecKey(diff.path, baseSpecs, headSpecs);
+    const specInfo = findSpecInfo(specKey, baseSpecs, headSpecs);
+    deltas.push({
+      specKey: specInfo?.key ?? "unknown",
+      specVersion: specInfo?.version ?? "1.0.0",
+      specType: specInfo?.type ?? "operation",
+      path: diff.path,
+      severity: matchingRule?.severity ?? mapDiffTypeToSeverity(diff.type),
+      rule: matchingRule?.id ?? "unknown",
+      description: diff.description,
+      oldValue: diff.oldValue,
+      newValue: diff.newValue
+    });
+  }
+  for (const spec of addedSpecs) {
+    deltas.push({
+      specKey: spec.key,
+      specVersion: spec.version,
+      specType: spec.type,
+      path: `spec.${spec.key}`,
+      severity: "non_breaking",
+      rule: "endpoint-added",
+      description: `${spec.type === "operation" ? "Operation" : "Event"} '${spec.key}' was added`
+    });
+  }
+  const summary = calculateSummary(deltas, addedSpecs, removedSpecs);
+  const hasBreaking = summary.breaking > 0 || summary.removed > 0;
+  const hasNonBreaking = summary.nonBreaking > 0 || summary.added > 0;
+  const status = determineStatus(hasBreaking, hasNonBreaking);
+  return {
+    status,
+    hasBreaking,
+    hasNonBreaking,
+    summary,
+    deltas,
+    addedSpecs,
+    removedSpecs,
+    timestamp: new Date().toISOString()
+  };
+}
+function calculateSummary(deltas, addedSpecs, removedSpecs) {
+  return {
+    breaking: deltas.filter((d) => d.severity === "breaking").length,
+    nonBreaking: deltas.filter((d) => d.severity === "non_breaking").length,
+    info: deltas.filter((d) => d.severity === "info").length,
+    added: addedSpecs.length,
+    removed: removedSpecs.length
+  };
+}
+function determineStatus(hasBreaking, hasNonBreaking) {
+  if (hasBreaking)
+    return "breaking";
+  if (hasNonBreaking)
+    return "non-breaking";
+  return "no-impact";
+}
+function mapDiffTypeToSeverity(type) {
+  switch (type) {
+    case "breaking":
+      return "breaking";
+    case "removed":
+      return "breaking";
+    case "added":
+      return "non_breaking";
+    case "changed":
+      return "info";
+    default:
+      return "info";
+  }
+}
+function extractSpecKey(_path, _baseSpecs, _headSpecs) {
+  return;
+}
+function findSpecInfo(key, baseSpecs, headSpecs) {
+  if (!key)
+    return headSpecs[0] ?? baseSpecs[0];
+  return headSpecs.find((s) => s.key === key) ?? baseSpecs.find((s) => s.key === key);
+}
+// src/analysis/spec-parser.ts
+import { readFile } from "fs/promises";
+async function loadSpecFromSource(filePath) {
+  try {
+    const code = await readFile(filePath, "utf-8");
+    if (isFeatureFile(filePath)) {
+      const featureResult = scanFeatureSource(code, filePath);
+      return [mapFeatureResultToParsedSpec(featureResult)];
+    }
+    const specResults = scanAllSpecsFromSource(code, filePath);
+    return specResults.map(mapSpecResultToParsedSpec);
+  } catch (error) {
+    console.warn(`Failed to parse spec from ${filePath}:`, error);
+    return [];
+  }
+}
+function mapFeatureResultToParsedSpec(result) {
+  const meta = {
+    key: result.key,
+    version: "1.0.0",
+    description: result.description,
+    stability: result.stability,
+    owners: result.owners,
+    tags: result.tags,
+    goal: result.goal,
+    context: result.context
+  };
+  return {
+    meta,
+    specType: "feature",
+    filePath: result.filePath,
+    sourceBlock: result.sourceBlock,
+    operations: result.operations.map(mapToSpecRef),
+    events: result.events.map(mapToSpecRef),
+    presentations: result.presentations.map(mapToSpecRef)
+  };
+}
+function mapSpecResultToParsedSpec(result) {
+  const meta = {
+    key: result.key ?? "unknown",
+    version: result.version ?? "1.0.0",
+    description: result.description,
+    stability: result.stability,
+    owners: result.owners,
+    tags: result.tags,
+    goal: result.goal,
+    context: result.context
+  };
+  return {
+    meta,
+    specType: result.specType,
+    kind: result.kind,
+    hasIo: result.hasIo,
+    hasPolicy: result.hasPolicy,
+    hasPayload: result.hasPayload,
+    hasContent: result.hasContent,
+    hasDefinition: result.hasDefinition,
+    emittedEvents: result.emittedEvents?.map(mapToSpecRef),
+    policyRefs: result.policyRefs?.map(mapToSpecRef),
+    testRefs: result.testRefs?.map(mapToSpecRef),
+    filePath: result.filePath,
+    sourceBlock: result.sourceBlock
+  };
+}
+function mapToSpecRef(ref) {
+  return {
+    name: ref.key,
+    version: ref.version
+  };
+}
+// src/templates/utils.ts
+function toCamelCase(str) {
+  const pascal = toPascalCase(str);
+  return pascal.charAt(0).toLowerCase() + pascal.slice(1);
+}
+function toPascalCase(str) {
+  return str.split(/[-_.]/).map((word) => word.charAt(0).toUpperCase() + word.slice(1)).join("");
+}
+function toKebabCase(str) {
+  return str.replace(/\./g, "-").replace(/([a-z])([A-Z])/g, "$1-$2").toLowerCase();
+}
+function capitalize(str) {
+  return str.charAt(0).toUpperCase() + str.slice(1);
+}
+function escapeString(value) {
+  return value.replace(/'/g, "\\'");
+}
+
+// src/templates/operation.ts
+function generateOperationSpec(data) {
+  const {
+    name,
+    version,
+    kind,
+    description,
+    goal,
+    context,
+    stability,
+    owners,
+    tags,
+    auth,
+    flags
+  } = data;
+  const specVarName = toPascalCase(name.split(".").pop() ?? "Unknown") + "Spec";
+  const inputSchemaName = specVarName.replace("Spec", "Input");
+  const outputSchemaName = specVarName.replace("Spec", "Output");
+  return `import { define${capitalize(kind)} } from '@contractspec/lib.contracts';
+import { ScalarTypeEnum, SchemaModel } from '@contractspec/lib.schema';
+
+// TODO: Define input schema
+export const ${inputSchemaName} = new SchemaModel({
+  name: '${inputSchemaName}',
+  description: 'Input for ${name}',
+  fields: {
+    // Add your fields here
+    // example: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+  },
+});
+
+// TODO: Define output schema
+export const ${outputSchemaName} = new SchemaModel({
+  name: '${outputSchemaName}',
+  description: 'Output for ${name}',
+  fields: {
+    // Add your fields here
+    ok: { type: ScalarTypeEnum.Boolean(), isOptional: false },
+  },
+});
+
+export const ${specVarName} = define${capitalize(kind)}({
+  meta: {
+    key: '${name}',
+    version: ${version},
+    stability: '${stability}',
+    owners: [${owners.map((o) => `'${o}'`).join(", ")}],
+    tags: [${tags.map((t) => `'${t}'`).join(", ")}],
+    description: '${description}',
+    goal: '${goal}',
+    context: '${context}',
+  },
+
+  io: {
+    input: ${inputSchemaName},
+    output: ${outputSchemaName},
+    errors: {
+      // Define possible errors
+      // EXAMPLE_ERROR: {
+      //   description: 'Example error description',
+      //   http: 400,
+      //   when: 'When this error occurs',
+      // },
+    },
+  },
+
+  policy: {
+    auth: '${auth}',
+    ${flags.length > 0 ? `flags: [${flags.map((f) => `'${f}'`).join(", ")}],` : "// flags: [],"}
+  },
+
+  sideEffects: {
+    ${data.emitsEvents ? `emits: [
+      // Define events to emit
+      // { ref: SomeEventSpec, when: 'always' }
+    ],` : "// emits: [],"}
+    analytics: [
+      // Define analytics events
+    ],
+  },
+
+  transport: {
+    rest: { method: '${kind === "command" ? "POST" : "GET"}' },
+    gql: { field: '${name.replace(/\./g, "_")}' },
+    mcp: { toolName: '${name}.v${version}' },
+  },
+
+  acceptance: {
+    scenarios: [
+      {
+        name: 'Happy path',
+        given: ['preconditions'],
+        when: ['action taken'],
+        then: ['expected outcome'],
+      },
+    ],
+    examples: [
+      {
+        name: 'Example usage',
+        input: { /* example input */ },
+        output: { ok: true },
+      },
+    ],
+  },
+});
+`;
+}
+// src/templates/event.ts
+function generateEventSpec(data) {
+  const { name, version, description, stability, owners, tags, piiFields } = data;
+  const eventVarName = toPascalCase(name.replace(/\./g, "_")) + "V" + version;
+  const payloadSchemaName = eventVarName + "Payload";
+  return `import { defineEvent } from '@contractspec/lib.contracts';
+import { ScalarTypeEnum, SchemaModel } from '@contractspec/lib.schema';
+
+// TODO: Define event payload schema
+export const ${payloadSchemaName} = new SchemaModel({
+  name: '${payloadSchemaName}',
+  description: 'Payload for ${name}',
+  fields: {
+    // Add your payload fields here
+    // example: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+  },
+});
+
+export const ${eventVarName} = defineEvent({
+  meta: {
+    name: '${name}',
+    version: ${version},
+    description: '${description}',
+    stability: '${stability}',
+    owners: [${owners.map((o) => `'${o}'`).join(", ")}],
+    tags: [${tags.map((t) => `'${t}'`).join(", ")}],
+  },
+  ${piiFields.length > 0 ? `pii: [${piiFields.map((f) => `'${f}'`).join(", ")}],` : "// pii: [],"}
+  payload: ${payloadSchemaName},
+});
+`;
+}
+// src/templates/presentation.ts
+function generatePresentationSpec(data) {
+  const {
+    name,
+    version,
+    description,
+    stability,
+    owners,
+    tags,
+    presentationKind
+  } = data;
+  const varName = toPascalCase(name.replace(/\./g, "_")) + "Presentation";
+  let contentBlock = "";
+  switch (presentationKind) {
+    case "web_component":
+      contentBlock = `  content: {
+    kind: 'web_component',
+    framework: 'react',
+    componentKey: '${name.replace(/\./g, "_")}',
+    props: new SchemaModel({
+      name: '${varName}Props',
+      description: 'Props for ${name}',
+      fields: {
+        // TODO: Define component props
+      },
+    }),
+    analytics: [
+      // TODO: Define analytics events
+    ],
+  },`;
+      break;
+    case "markdown":
+      contentBlock = `  content: {
+    kind: 'markdown',
+    content: \`
+# ${description}
+
+TODO: Add markdown content here
+    \`,
+    // Or use resourceUri: 'feature://${name}/guide.md'
+  },`;
+      break;
+    case "data":
+      contentBlock = `  content: {
+    kind: 'data',
+    mimeType: 'application/json',
+    model: new SchemaModel({
+      name: '${varName}Data',
+      description: 'Data structure for ${name}',
+      fields: {
+        // TODO: Define data structure
+      },
+    }),
+  },`;
+      break;
+  }
+  return `import type { PresentationSpec } from '@contractspec/lib.contracts/presentations';
+import { SchemaModel, ScalarTypeEnum } from '@contractspec/lib.schema';
+
+export const ${varName}: PresentationSpec = {
+  meta: {
+    key: '${name}',
+    version: ${version},
+    stability: '${stability}',
+    owners: [${owners.map((o) => `'${o}'`).join(", ")}],
+    tags: [${tags.map((t) => `'${t}'`).join(", ")}],
+    description: '${description}',
+  },
+  
+  policy: {
+    // flags: [],
+    // pii: [],
+  },
+  
+${contentBlock}
+};
+`;
+}
+// src/templates/workflow.ts
+function generateWorkflowSpec(data) {
+  const specVarName = toPascalCase(data.name.split(".").pop() ?? "Workflow") + "Workflow";
+  const stepsCode = data.steps.map((step) => formatStep(step)).join(`,
+`);
+  const transitionsCode = data.transitions.map((transition) => `    {
+      from: '${transition.from}',
+      to: '${transition.to}',
+${transition.condition ? `      condition: '${escapeString(transition.condition)}',` : ""}
+    }`).join(`,
+`);
+  return `import type { WorkflowSpec } from '@contractspec/lib.contracts/workflow';
+
+/**
+ * Workflow generated via contractspec CLI.
+ * TODO:
+ *  - Review step definitions and descriptions.
+ *  - Wire automation steps to actual operations.
+ *  - Provide form renderers for human steps.
+ *  - Add guards/conditions as needed.
+ */
+export const ${specVarName}: WorkflowSpec = {
+  meta: {
+    key: '${data.name}',
+    version: ${data.version},
+    title: '${escapeString(data.title)}',
+    description: '${escapeString(data.description)}',
+    domain: '${escapeString(data.domain)}',
+    stability: '${data.stability}',
+    owners: [${data.owners.map((owner) => `'${owner}'`).join(", ")}],
+    tags: [${data.tags.map((tag) => `'${tag}'`).join(", ")}],
+  },
+  definition: {
+${data.entryStepId ? `    entryStepId: '${data.entryStepId}',
+` : ""}    steps: [
+${stepsCode}
+    ],
+    transitions: [
+${transitionsCode}
+    ],
+  },
+  ${data.policyFlags.length > 0 ? `policy: {
+    flags: [${data.policyFlags.map((flag) => `'${flag}'`).join(", ")}],
+  },` : "// policy: { flags: [] },"}
+};
+`;
+}
+function formatStep(step) {
+  const lines = [
+    `    {`,
+    `      id: '${step.id}',`,
+    `      type: '${step.type}',`,
+    `      label: '${escapeString(step.label)}',`
+  ];
+  if (step.description) {
+    lines.push(`      description: '${escapeString(step.description)}',`);
+  }
+  const actionLines = [];
+  if (step.operation) {
+    actionLines.push(`operation: { name: '${step.operation.name}', version: ${step.operation.version} }`);
+  }
+  if (step.form) {
+    actionLines.push(`form: { key: '${step.form.key}', version: ${step.form.version} }`);
+  }
+  if (actionLines.length) {
+    lines.push(`      action: { ${actionLines.join(", ")} },`);
+  }
+  lines.push(`    }`);
+  return lines.join(`
+`);
+}
+// src/templates/workflow-runner.ts
+function generateWorkflowRunnerTemplate({
+  exportName,
+  specImportPath,
+  runnerName,
+  workflowName
+}) {
+  return `import {
+  InMemoryStateStore,
+  WorkflowRegistry,
+  WorkflowRunner,
+} from '@contractspec/lib.contracts/workflow';
+import { ${exportName} } from '${specImportPath}';
+
+/**
+ * Runner wiring for ${workflowName}.
+ *
+ * TODO:
+ *  - Replace the in-memory state store with a persistent adapter if needed.
+ *  - Implement opExecutor to invoke the correct contract handlers.
+ *  - Wire eventEmitter to telemetry sinks.
+ */
+const registry = new WorkflowRegistry();
+registry.register(${exportName});
+
+const stateStore = new InMemoryStateStore();
+
+export const ${runnerName} = new WorkflowRunner({
+  registry,
+  stateStore,
+  opExecutor: async (operation, input, ctx) => {
+    // TODO: route to the appropriate contract handler
+    // Example: return contractRegistry.execute(operation.name, operation.version, input, ctx);
+    throw new Error(
+      \`opExecutor for \${operation.name}.v\${operation.version} is not implemented\`
+    );
+  },
+  // appConfigProvider: async (state) => {
+  //   // TODO: return the ResolvedAppConfig for this workflow run (tenant/environment)
+  //   return undefined;
+  // },
+  // enforceCapabilities: async (operation, context) => {
+  //   // TODO: ensure required capabilities are satisfied using context.integrations/context.resolvedAppConfig
+  // },
+  eventEmitter: (_event, _payload) => {
+    // TODO: forward workflow events to telemetry or logging sinks
+  },
+});
+`;
+}
+// src/templates/data-view.ts
+function generateDataViewSpec(data) {
+  const viewVarName = toPascalCase(data.name.split(".").pop() ?? "DataView") + "DataView";
+  const fields = data.fields.map((field) => `      {
+        key: '${escapeString(field.key)}',
+        label: '${escape(field.label)}',
+        dataPath: '${escapeString(field.dataPath)}',
+        ${field.format ? `format: '${escapeString(field.format)}',` : ""}
+        ${field.sortable ? "sortable: true," : ""}
+        ${field.filterable ? "filterable: true," : ""}
+      }`).join(`,
+`);
+  const secondaryFields = data.secondaryFields?.length ? `secondaryFields: [${data.secondaryFields.map((key) => `'${escapeString(key)}'`).join(", ")}],` : "";
+  const itemOperation = data.itemOperation ? `item: { name: '${escapeString(data.itemOperation.name)}', version: ${data.itemOperation.version} },` : "";
+  return `import type { DataViewSpec } from '@contractspec/lib.contracts/data-views';
+
+export const ${viewVarName}: DataViewSpec = {
+  meta: {
+    key: '${escapeString(data.name)}',
+    version: ${data.version},
+    entity: '${escapeString(data.entity)}',
+    title: '${escape(data.title)}',
+    description: '${escape(data.description || "Describe the purpose of this data view.")}',
+    domain: '${escape(data.domain || data.entity)}',
+    owners: [${data.owners.map((owner) => `'${escapeString(owner)}'`).join(", ")}],
+    tags: [${data.tags.map((tag) => `'${escapeString(tag)}'`).join(", ")}],
+    stability: '${data.stability}',
+  },
+  source: {
+    primary: {
+      name: '${escapeString(data.primaryOperation.name)}',
+      version: ${data.primaryOperation.version},
+    },
+    ${itemOperation}
+    refreshEvents: [
+      // { name: 'entity.updated', version: '1.0.0' },
+    ],
+  },
+  view: {
+    kind: '${data.kind}',
+    fields: [
+${fields}
+    ],
+    ${data.primaryField ? `primaryField: '${escapeString(data.primaryField)}',` : ""}
+    ${secondaryFields}
+    filters: [
+      // Example filter:
+      // { key: 'search', label: 'Search', field: 'fullName', type: 'search' },
+    ],
+    actions: [
+      // Example action:
+      // { key: 'open', label: 'Open', kind: 'navigation' },
+    ],
+  },
+  states: {
+    // empty: { name: 'app.data.empty', version: '1.0.0' },
+    // error: { name: 'app.data.error', version: '1.0.0' },
+  },
+};
+`;
+}
+function escape(value) {
+  return value.replace(/'/g, "\\'");
+}
+// src/templates/telemetry.ts
+function generateTelemetrySpec(data) {
+  const specVar = toPascalCase(data.name.split(".").pop() ?? "Telemetry") + "Telemetry";
+  const providers = data.providers?.length ? `providers: [
+${data.providers.map((provider) => `      {
+        type: '${provider.type}',
+        config: ${formatConfigValue(provider.config)},
+      }`).join(`,
+`)}
+    ],` : "";
+  const events = data.events.map((event) => {
+    const properties = event.properties.map((prop) => `      '${prop.name}': {
+        type: '${prop.type}',
+        ${prop.required ? "required: true," : ""}
+        ${prop.pii ? "pii: true," : ""}
+        ${prop.redact ? "redact: true," : ""}
+        ${prop.description ? `description: '${escapeString2(prop.description)}',` : ""}
+      }`).join(`,
+`);
+    const anomalyRules = event.anomalyRules?.length ? `      anomalyDetection: {
+        enabled: true,
+        ${typeof event.anomalyMinimumSample === "number" ? `minimumSample: ${event.anomalyMinimumSample},` : ""}
+        thresholds: [
+${event.anomalyRules.map((rule) => `          {
+            metric: '${escapeString2(rule.metric)}',
+            ${typeof rule.min === "number" ? `min: ${rule.min},` : ""}
+            ${typeof rule.max === "number" ? `max: ${rule.max},` : ""}
+          }`).join(`,
+`)}
+        ],
+        actions: [${(event.anomalyActions ?? []).map((action) => `'${action}'`).join(", ")}],
+      },` : event.anomalyEnabled ? `      anomalyDetection: {
+        enabled: true,
+        ${typeof event.anomalyMinimumSample === "number" ? `minimumSample: ${event.anomalyMinimumSample},` : ""}
+      },` : "";
+    return `    {
+      name: '${escapeString2(event.name)}',
+      version: ${event.version},
+      semantics: {
+        what: '${escapeString2(event.what)}',
+        ${event.who ? `who: '${escapeString2(event.who)}',` : ""}
+        ${event.why ? `why: '${escapeString2(event.why)}',` : ""}
+      },
+      privacy: '${event.privacy}',
+      properties: {
+${properties}
+      },
+      ${typeof event.retentionDays === "number" ? `retention: { days: ${event.retentionDays}, ${event.retentionPolicy ? `policy: '${event.retentionPolicy}'` : ""} },` : ""}
+      ${typeof event.samplingRate === "number" ? `sampling: { rate: ${event.samplingRate}${event.samplingConditions ? `, conditions: ['${escapeString2(event.samplingConditions)}']` : ""} },` : ""}
+${anomalyRules}
+      ${event.tags?.length ? `tags: [${event.tags.map((tag) => `'${escapeString2(tag)}'`).join(", ")}],` : ""}
+    }`;
+  }).join(`,
+`);
+  return `import type { TelemetrySpec } from '@contractspec/lib.contracts/telemetry';
+
+export const ${specVar}: TelemetrySpec = {
+  meta: {
+    key: '${escapeString2(data.name)}',
+    version: ${data.version},
+    title: '${escapeString2(data.name)} telemetry',
+    description: '${escapeString2(data.description || "Describe the purpose of this telemetry spec.")}',
+    domain: '${escapeString2(data.domain)}',
+    owners: [${data.owners.map((owner) => `'${escapeString2(owner)}'`).join(", ")}],
+    tags: [${data.tags.map((tag) => `'${escapeString2(tag)}'`).join(", ")}],
+    stability: '${data.stability}',
+  },
+  config: {
+    ${typeof data.defaultRetentionDays === "number" ? `defaultRetentionDays: ${data.defaultRetentionDays},` : ""}
+    ${typeof data.defaultSamplingRate === "number" ? `defaultSamplingRate: ${data.defaultSamplingRate},` : ""}
+    ${data.anomalyEnabled ? `anomalyDetection: { enabled: true${typeof data.anomalyCheckIntervalMs === "number" ? `, checkIntervalMs: ${data.anomalyCheckIntervalMs}` : ""} },` : ""}
+${providers}
+  },
+  events: [
+${events}
+  ],
+};
+`;
+}
+function escapeString2(value) {
+  return value.replace(/\\/g, "\\\\").replace(/'/g, "\\'");
+}
+function formatConfigValue(value) {
+  const trimmed = value.trim();
+  if (!trimmed)
+    return "{}";
+  if (trimmed.startsWith("{") && trimmed.endsWith("}") || trimmed.startsWith("[") && trimmed.endsWith("]")) {
+    return trimmed;
+  }
+  return `'${escapeString2(trimmed)}'`;
+}
+// src/templates/experiment.ts
+function generateExperimentSpec(data) {
+  const specVar = toPascalCase(data.name.split(".").pop() ?? "Experiment") + "Experiment";
+  const variants = data.variants.map((variant) => {
+    const overrides = variant.overrides?.length ? `      overrides: [
+${variant.overrides.map((override) => `        {
+          type: '${override.type}',
+          target: '${escapeString3(override.target)}',
+          ${typeof override.version === "number" ? `version: ${override.version},` : ""}
+        }`).join(`,
+`)}
+      ],` : "";
+    return `    {
+      id: '${escapeString3(variant.id)}',
+      name: '${escapeString3(variant.name)}',
+      ${variant.description ? `description: '${escapeString3(variant.description)}',` : ""}
+      ${typeof variant.weight === "number" ? `weight: ${variant.weight},` : ""}
+${overrides}
+    }`;
+  }).join(`,
+`);
+  const allocation = renderAllocation(data.allocation);
+  const metrics = data.successMetrics?.length ? `  successMetrics: [
+${data.successMetrics.map((metric) => `    {
+      name: '${escapeString3(metric.name)}',
+      telemetryEvent: { name: '${escapeString3(metric.eventName)}', version: ${metric.eventVersion} },
+      aggregation: '${metric.aggregation}',
+      ${typeof metric.target === "number" ? `target: ${metric.target},` : ""}
+    }`).join(`,
+`)}
+  ],` : "";
+  return `import type { ExperimentSpec } from '@contractspec/lib.contracts/experiments';
+
+export const ${specVar}: ExperimentSpec = {
+  meta: {
+    key: '${escapeString3(data.name)}',
+    version: ${data.version},
+    title: '${escapeString3(data.name)} experiment',
+    description: '${escapeString3(data.description || "Describe the experiment goal.")}',
+    domain: '${escapeString3(data.domain)}',
+    owners: [${data.owners.map((owner) => `'${escapeString3(owner)}'`).join(", ")}],
+    tags: [${data.tags.map((tag) => `'${escapeString3(tag)}'`).join(", ")}],
+    stability: '${data.stability}',
+  },
+  controlVariant: '${escapeString3(data.controlVariant)}',
+  variants: [
+${variants}
+  ],
+  allocation: ${allocation},
+${metrics}
+};
+`;
+}
+function renderAllocation(allocation) {
+  switch (allocation.type) {
+    case "random":
+      return `{
+    type: 'random',
+    ${allocation.salt ? `salt: '${escapeString3(allocation.salt)}',` : ""}
+  }`;
+    case "sticky":
+      return `{
+    type: 'sticky',
+    attribute: '${allocation.attribute}',
+    ${allocation.salt ? `salt: '${escapeString3(allocation.salt)}',` : ""}
+  }`;
+    case "targeted":
+      return `{
+    type: 'targeted',
+    rules: [
+${allocation.rules.map((rule) => `      {
+        variantId: '${escapeString3(rule.variantId)}',
+        ${typeof rule.percentage === "number" ? `percentage: ${rule.percentage},` : ""}
+        ${rule.policy ? `policy: { name: '${escapeString3(rule.policy.name)}'${typeof rule.policy.version === "number" ? `, version: ${rule.policy.version}` : ""} },` : ""}
+        ${rule.expression ? `expression: '${escapeString3(rule.expression)}',` : ""}
+      }`).join(`,
+`)}
+    ],
+    fallback: '${allocation.fallback ?? "control"}',
+  }`;
+    default:
+      return renderUnsupportedAllocation(allocation);
+  }
+}
+function escapeString3(value) {
+  return value.replace(/\\/g, "\\\\").replace(/'/g, "\\'");
+}
+function renderUnsupportedAllocation(allocation) {
+  throw new Error(`Unsupported allocation type ${allocation}`);
+}
+// src/templates/app-config.ts
+function generateAppBlueprintSpec(data) {
+  const exportName = toPascalCase(data.name.split(".").pop() ?? "App") + "AppConfig";
+  const capabilitiesSection = buildCapabilitiesSection(data);
+  const featuresSection = buildFeaturesSection(data);
+  const dataViewsSection = buildMappingSection("dataViews", data.dataViews);
+  const workflowsSection = buildMappingSection("workflows", data.workflows);
+  const policiesSection = buildPolicySection(data);
+  const themeSection = buildThemeSection(data);
+  const telemetrySection = buildTelemetrySection(data);
+  const experimentsSection = buildExperimentsSection(data);
+  const flagsSection = buildFeatureFlagsSection(data);
+  const routesSection = buildRoutesSection(data);
+  const notesSection = data.notes ? `  notes: '${escapeString4(data.notes)}',
+` : "";
+  return `import type { AppBlueprintSpec } from '@contractspec/lib.contracts/app-config';
+
+export const ${exportName}: AppBlueprintSpec = {
+  meta: {
+    key: '${escapeString4(data.name)}',
+    version: '${data.version}',
+    title: '${escapeString4(data.title)}',
+    description: '${escapeString4(data.description)}',
+    domain: '${escapeString4(data.domain)}',
+    owners: [${data.owners.map((owner) => `'${escapeString4(owner)}'`).join(", ")}],
+    tags: [${data.tags.map((tag) => `'${escapeString4(tag)}'`).join(", ")}],
+    stability: '${data.stability}',
+    appId: '${escapeString4(data.appId)}',
+  },
+${capabilitiesSection}${featuresSection}${dataViewsSection}${workflowsSection}${policiesSection}${themeSection}${telemetrySection}${experimentsSection}${flagsSection}${routesSection}${notesSection}};
+`;
+}
+function buildCapabilitiesSection(data) {
+  if (data.capabilitiesEnabled.length === 0 && data.capabilitiesDisabled.length === 0) {
+    return "";
+  }
+  const enabled = data.capabilitiesEnabled.length > 0 ? `    enabled: [${data.capabilitiesEnabled.map((key) => formatCapabilityRef(key)).join(", ")}],
+` : "";
+  const disabled = data.capabilitiesDisabled.length > 0 ? `    disabled: [${data.capabilitiesDisabled.map((key) => formatCapabilityRef(key)).join(", ")}],
+` : "";
+  return `  capabilities: {
+${enabled}${disabled}  },
+`;
+}
+function buildFeaturesSection(data) {
+  if (data.featureIncludes.length === 0 && data.featureExcludes.length === 0) {
+    return "";
+  }
+  const include = data.featureIncludes.length > 0 ? `    include: [${data.featureIncludes.map((key) => `{ key: '${escapeString4(key)}' }`).join(", ")}],
+` : "";
+  const exclude = data.featureExcludes.length > 0 ? `    exclude: [${data.featureExcludes.map((key) => `{ key: '${escapeString4(key)}' }`).join(", ")}],
+` : "";
+  return `  features: {
+${include}${exclude}  },
+`;
+}
+function buildMappingSection(prop, mappings) {
+  if (mappings.length === 0)
+    return "";
+  const body = mappings.map((mapping) => `    ${mapping.slot}: {
+      name: '${escapeString4(mapping.name)}',
+      version: '${mapping.version}',
+    }`).join(`,
+`);
+  return `  ${prop}: {
+${body}
+  },
+`;
+}
+function buildPolicySection(data) {
+  if (data.policyRefs.length === 0)
+    return "";
+  const entries = data.policyRefs.map((policy) => `    {
+      name: '${escapeString4(policy.name)}',
+      version: '${policy.version}',
+    }`).join(`,
+`);
+  return `  policies: [
+${entries}
+  ],
+`;
+}
+function buildThemeSection(data) {
+  if (!data.theme)
+    return "";
+  const primary = `    primary: { name: '${escapeString4(data.theme.name)}', version: ${data.theme.version} },
+`;
+  const fallbacks = data.themeFallbacks.length > 0 ? `    fallbacks: [${data.themeFallbacks.map((theme) => `{ name: '${escapeString4(theme.name)}', version: '${theme.version}' }`).join(", ")}],
+` : "";
+  return `  theme: {
+${primary}${fallbacks}  },
+`;
+}
+function buildTelemetrySection(data) {
+  if (!data.telemetry)
+    return "";
+  return `  telemetry: {
+    spec: {
+      name: '${escapeString4(data.telemetry.name)}'${data.telemetry.version !== undefined ? `,
+      version: '${data.telemetry.version}'` : ""}
+    },
+  },
+`;
+}
+function buildExperimentsSection(data) {
+  if (data.activeExperiments.length === 0 && data.pausedExperiments.length === 0) {
+    return "";
+  }
+  const active = data.activeExperiments.length > 0 ? `    active: [${data.activeExperiments.map((exp) => formatExperimentRef(exp)).join(", ")}],
+` : "";
+  const paused = data.pausedExperiments.length > 0 ? `    paused: [${data.pausedExperiments.map((exp) => formatExperimentRef(exp)).join(", ")}],
+` : "";
+  return `  experiments: {
+${active}${paused}  },
+`;
+}
+function buildFeatureFlagsSection(data) {
+  if (data.featureFlags.length === 0)
+    return "";
+  const flags = data.featureFlags.map((flag) => `    {
+      key: '${escapeString4(flag.key)}',
+      enabled: ${flag.enabled},
+      ${flag.variant ? `variant: '${escapeString4(flag.variant)}',` : ""}
+      ${flag.description ? `description: '${escapeString4(flag.description)}',` : ""}
+    }`).join(`,
+`);
+  return `  featureFlags: [
+${flags}
+  ],
+`;
+}
+function buildRoutesSection(data) {
+  if (data.routes.length === 0)
+    return "";
+  const routes = data.routes.map((route) => {
+    const entries = [
+      `path: '${escapeString4(route.path)}'`,
+      route.label ? `label: '${escapeString4(route.label)}'` : null,
+      route.dataView ? `dataView: '${escapeString4(route.dataView)}'` : null,
+      route.workflow ? `workflow: '${escapeString4(route.workflow)}'` : null,
+      route.guardName ? `guard: { name: '${escapeString4(route.guardName)}'${route.guardVersion !== undefined ? `, version: '${route.guardVersion}'` : ""} }` : null,
+      route.featureFlag ? `featureFlag: '${escapeString4(route.featureFlag)}'` : null,
+      route.experimentName ? `experiment: { name: '${escapeString4(route.experimentName)}'${route.experimentVersion !== undefined ? `, version: '${route.experimentVersion}'` : ""} }` : null
+    ].filter(Boolean);
+    return `    { ${entries.join(", ")} }`;
+  }).join(`,
+`);
+  return `  routes: [
+${routes}
+  ],
+`;
+}
+function formatCapabilityRef(key) {
+  return `{ key: '${escapeString4(key)}' }`;
+}
+function formatExperimentRef(exp) {
+  const version = typeof exp.version === "string" ? `, version: ${exp.version}` : "";
+  return `{ name: '${escapeString4(exp.name)}'${version} }`;
+}
+function escapeString4(value) {
+  return value.replace(/\\/g, "\\\\").replace(/'/g, "\\'");
+}
+// src/templates/migration.ts
+function generateMigrationSpec(data) {
+  const specName = toPascalCase(data.name.split(".").pop() ?? "Migration");
+  const migrationVar = `${specName}Migration`;
+  const dependencies = data.dependencies.length > 0 ? `dependencies: [${data.dependencies.map((dep) => `'${escapeString(dep)}'`).join(", ")}],` : "";
+  return `import type { MigrationSpec } from '@contractspec/lib.contracts/migrations';
+
+export const ${migrationVar}: MigrationSpec = {
+  meta: {
+    key: '${escapeString(data.name)}',
+    version: ${data.version},
+    title: '${escape2(data.title)}',
+    description: '${escape2(data.description ?? "")}',
+    domain: '${escape2(data.domain)}',
+    owners: [${data.owners.map((owner) => `'${escapeString(owner)}'`).join(", ")}],
+    tags: [${data.tags.map((tag) => `'${escapeString(tag)}'`).join(", ")}],
+    stability: '${data.stability}',
+  },
+  plan: {
+    up: [
+${renderSteps(data.up)}
+    ],${data.down && data.down.length ? `
+    down: [
+${renderSteps(data.down)}
+    ],` : ""}
+  },
+  ${dependencies}
+};
+`;
+}
+function renderSteps(steps) {
+  return steps.map((step) => {
+    const description = step.description ? `description: '${escape2(step.description)}',` : "";
+    switch (step.kind) {
+      case "schema":
+        return `      {
+        kind: 'schema',
+        ${description}
+        sql: \`${escape2(step.sql ?? "")}\`,
+      }`;
+      case "data":
+        return `      {
+        kind: 'data',
+        ${description}
+        script: \`${escape2(step.script ?? "")}\`,
+      }`;
+      case "validation":
+      default:
+        return `      {
+        kind: 'validation',
+        ${description}
+        assertion: \`${escape2(step.assertion ?? "")}\`,
+      }`;
+    }
+  }).join(`,
+`);
+}
+function escape2(value) {
+  return value.replace(/`/g, "\\`").replace(/'/g, "\\'");
+}
+// src/templates/integration-utils.ts
+function renderConfigSchema(fields) {
+  const requiredFields = fields.filter((field) => field.required);
+  const requiredBlock = requiredFields.length > 0 ? `      required: [${requiredFields.map((field) => `'${field.key}'`).join(", ")}],
+` : "";
+  const properties = fields.length ? fields.map((field) => {
+    const description = field.description ? `, description: '${escape3(field.description)}'` : "";
+    return `        ${field.key}: { type: '${mapConfigType(field.type)}'${description} }`;
+  }).join(`,
+`) : "";
+  return `    schema: {
+      type: 'object',
+${requiredBlock}      properties: {
+${properties || "      "}
+      },
+    },
+`;
+}
+function renderSecretSchema(fields) {
+  const requiredFields = fields.filter((field) => field.required);
+  const requiredBlock = requiredFields.length > 0 ? `      required: [${requiredFields.map((field) => `'${field.key}'`).join(", ")}],
+` : "";
+  const properties = fields.length ? fields.map((field) => {
+    const description = field.description ? `, description: '${escape3(field.description)}'` : "";
+    return `        ${field.key}: { type: 'string'${description} }`;
+  }).join(`,
+`) : "";
+  return `    schema: {
+      type: 'object',
+${requiredBlock}      properties: {
+${properties || "      "}
+      },
+    },
+`;
+}
+function renderConfigExample(fields) {
+  if (fields.length === 0) {
+    return `{}`;
+  }
+  const exampleEntries = fields.map((field) => {
+    switch (field.type) {
+      case "number":
+        return `    ${field.key}: 0`;
+      case "boolean":
+        return `    ${field.key}: true`;
+      case "string":
+      default:
+        return `    ${field.key}: '${field.key.toUpperCase()}_VALUE'`;
+    }
+  });
+  return `{
+${exampleEntries.join(`,
+`)}
+  }`;
+}
+function renderSecretExample(fields) {
+  if (fields.length === 0) {
+    return `{}`;
+  }
+  const exampleEntries = fields.map((field) => `    ${field.key}: '${field.key.toUpperCase()}_SECRET'`);
+  return `{
+${exampleEntries.join(`,
+`)}
+  }`;
+}
+function renderConstraints(rpm, rph) {
+  if (rpm == null && rph == null)
+    return "";
+  const entries = [];
+  if (rpm != null)
+    entries.push(`      rpm: ${rpm}`);
+  if (rph != null)
+    entries.push(`      rph: ${rph}`);
+  return `  constraints: {
+    rateLimit: {
+${entries.join(`,
+`)}
+    },
+  },
+`;
+}
+function renderByokSetup(modes, instructions, scopes) {
+  if (!modes.includes("byok")) {
+    return "";
+  }
+  const instructionsLine = instructions ? `    setupInstructions: '${escape3(instructions)}',
+` : "";
+  const scopesLine = scopes && scopes.length ? `    requiredScopes: [${scopes.map((scope) => `'${escape3(scope)}'`).join(", ")}],
+` : "";
+  if (!instructionsLine && !scopesLine) {
+    return "";
+  }
+  return `  byokSetup: {
+${instructionsLine}${scopesLine}  },
+`;
+}
+function mapConfigType(type) {
+  switch (type) {
+    case "number":
+      return "number";
+    case "boolean":
+      return "boolean";
+    case "string":
+    default:
+      return "string";
+  }
+}
+function stabilityToEnum(stability) {
+  switch (stability) {
+    case "beta":
+      return "Beta";
+    case "stable":
+      return "Stable";
+    case "deprecated":
+      return "Deprecated";
+    case "experimental":
+    default:
+      return "Experimental";
+  }
+}
+function renderProvides(data) {
+  return data.capabilitiesProvided.map((cap) => `      { key: '${cap.key}', version: ${cap.version} }`).join(`,
+`);
+}
+function renderRequires(data) {
+  if (data.capabilitiesRequired.length === 0)
+    return "";
+  return `    requires: [
+${data.capabilitiesRequired.map((req) => {
+    const version = typeof req.version === "number" ? `, version: ${req.version}` : "";
+    const optional = req.optional ? ", optional: true" : "";
+    const reason = req.reason ? `, reason: '${escape3(req.reason)}'` : "";
+    return `      { key: '${req.key}'${version}${optional}${reason} }`;
+  }).join(`,
+`)}
+    ],`;
+}
+function escape3(value) {
+  return value.replace(/`/g, "\\`").replace(/'/g, "\\'");
+}
+
+// src/templates/integration.ts
+function generateIntegrationSpec(data) {
+  const specName = toPascalCase(data.name.split(".").pop() ?? "Integration");
+  const varName = `${specName}IntegrationSpec`;
+  const registerFn = `register${specName}Integration`;
+  const supportedModes = data.supportedModes.length ? data.supportedModes : ["managed"];
+  const supportedModesLine = supportedModes.map((mode) => `'${mode}'`).join(", ");
+  const provides = renderProvides(data);
+  const requires = renderRequires(data);
+  const configSchema = renderConfigSchema(data.configFields);
+  const configExample = renderConfigExample(data.configFields);
+  const secretSchema = renderSecretSchema(data.secretFields);
+  const secretExample = renderSecretExample(data.secretFields);
+  const docsUrl = data.docsUrl ? `  docsUrl: '${escape3(data.docsUrl)}',
+` : "";
+  const constraints = renderConstraints(data.rateLimitRpm, data.rateLimitRph);
+  const byokSetup = renderByokSetup(supportedModes, data.byokSetupInstructions, data.byokRequiredScopes);
+  return `import { StabilityEnum, defineIntegration } from '@contractspec/lib.contracts';
+import type { IntegrationSpecRegistry } from '@contractspec/lib.contracts/integrations/spec';
+
+export const ${varName} = defineIntegration({
+  meta: {
+    key: '${escape3(data.name)}',
+    version: ${data.version},
+    category: '${data.category}',
+    displayName: '${escape3(data.displayName)}',
+    title: '${escape3(data.title)}',
+    description: '${escape3(data.description)}',
+    domain: '${escape3(data.domain)}',
+    owners: [${data.owners.map((owner) => `'${escape3(owner)}'`).join(", ")}],
+    tags: [${data.tags.map((tag) => `'${escape3(tag)}'`).join(", ")}],
+    stability: StabilityEnum.${stabilityToEnum(data.stability)},
+  },
+  supportedModes: [${supportedModesLine}],
+  capabilities: {
+    provides: [
+${provides}
+    ],
+${requires.length > 0 ? `${requires}
+` : ""}  },
+  configSchema: {
+${configSchema}    example: ${configExample},
+  },
+  secretSchema: {
+${secretSchema}    example: ${secretExample},
+  },
+${docsUrl}${constraints}${byokSetup}  healthCheck: {
+    method: '${data.healthCheckMethod}',
+    timeoutMs: ${data.healthCheckTimeoutMs ?? 5000},
+  },
+});
+
+export function ${registerFn}(registry: IntegrationSpecRegistry): IntegrationSpecRegistry {
+  return registry.register(${varName});
+}
+`;
+}
+// src/templates/knowledge.ts
+function generateKnowledgeSpaceSpec(data) {
+  const specName = toPascalCase(data.name.split(".").pop() ?? "KnowledgeSpace");
+  const varName = `${specName}KnowledgeSpace`;
+  const registerFn = `register${specName}KnowledgeSpace`;
+  const retention = renderRetention(data);
+  const access = renderAccess(data);
+  const indexing = renderIndexing(data);
+  const policyComment = data.policyName && !data.policyVersion ? ` // defaults to latest version` : "";
+  return `import { StabilityEnum } from '@contractspec/lib.contracts/ownership';
+import type { KnowledgeSpaceSpec } from '@contractspec/lib.contracts/knowledge/spec';
+import type { KnowledgeSpaceRegistry } from '@contractspec/lib.contracts/knowledge/spec';
+
+export const ${varName}: KnowledgeSpaceSpec = {
+  meta: {
+    key: '${escapeString(data.name)}',
+    version: ${data.version},
+    category: '${data.category}',
+    displayName: '${escape4(data.displayName)}',
+    title: '${escape4(data.title)}',
+    description: '${escape4(data.description)}',
+    domain: '${escape4(data.domain)}',
+    owners: [${data.owners.map((owner) => `'${escapeString(owner)}'`).join(", ")}],
+    tags: [${data.tags.map((tag) => `'${escapeString(tag)}'`).join(", ")}],
+    stability: StabilityEnum.${stabilityToEnum2(data.stability)},
+  },
+  retention: ${retention},
+  access: {
+${access}${data.policyName ? `    policy: { name: '${escapeString(data.policyName)}',${data.policyVersion ? ` version: ${data.policyVersion}` : ""} },${policyComment}
+` : ""}  },
+${indexing}  description: '${escape4(data.description || data.displayName)}',
+};
+
+export function ${registerFn}(registry: KnowledgeSpaceRegistry): KnowledgeSpaceRegistry {
+  return registry.register(${varName});
+}
+`;
+}
+function renderRetention(data) {
+  const ttl = data.retention.ttlDays === null ? "null" : typeof data.retention.ttlDays === "number" ? String(data.retention.ttlDays) : "null";
+  const archive = typeof data.retention.archiveAfterDays === "number" ? `, archiveAfterDays: ${data.retention.archiveAfterDays}` : "";
+  return `{ ttlDays: ${ttl}${archive} }`;
+}
+function renderAccess(data) {
+  const trustLine = `    trustLevel: '${data.trustLevel}',
+`;
+  const automationLine = `    automationWritable: ${data.automationWritable},
+`;
+  return `${trustLine}${automationLine}`;
+}
+function renderIndexing(data) {
+  const entries = [];
+  if (data.embeddingModel) {
+    entries.push(`    embeddingModel: '${escape4(data.embeddingModel)}'`);
+  }
+  if (typeof data.chunkSize === "number") {
+    entries.push(`    chunkSize: ${data.chunkSize}`);
+  }
+  if (data.vectorDbIntegration) {
+    entries.push(`    vectorDbIntegration: '${escape4(data.vectorDbIntegration)}'`);
+  }
+  if (entries.length === 0) {
+    return "";
+  }
+  return `  indexing: {
+${entries.join(`,
+`)}
+  },
+`;
+}
+function stabilityToEnum2(stability) {
+  switch (stability) {
+    case "beta":
+      return "Beta";
+    case "stable":
+      return "Stable";
+    case "deprecated":
+      return "Deprecated";
+    case "experimental":
+    default:
+      return "Experimental";
+  }
+}
+function escape4(value) {
+  return value.replace(/`/g, "\\`").replace(/'/g, "\\'");
+}
+// src/templates/handler.ts
+function generateHandlerTemplate(specName, kind) {
+  const handlerName = toCamelCase(specName.split(".").pop() ?? "unknown") + "Handler";
+  const specVarName = toPascalCase(specName.split(".").pop() ?? "Unknown") + "Spec";
+  return `import type { ContractHandler } from '@contractspec/lib.contracts';
+import { ${specVarName} } from '../contracts/${toKebabCase(specName)}.contracts';
+
+/**
+ * Handler for ${specName}
+ */
+export const ${handlerName}: ContractHandler<typeof ${specVarName}> = async (
+  input,
+  context
+) => {
+  // TODO: Implement ${kind} logic
+  
+  try {
+    // 1. Validate prerequisites
+    // 2. Perform business logic
+    // 3. Emit events if needed
+    // 4. Return result
+    
+    return {
+      ok: true,
+    };
+  } catch (error) {
+    // Handle and map errors to spec.io.errors
+    throw error;
+  }
+};
+`;
+}
+function generateComponentTemplate(componentName, description) {
+  const pascalName = toPascalCase(componentName);
+  return `import React from 'react';
+
+interface ${pascalName}Props {
+  // TODO: Define props based on presentation spec
+}
+
+/**
+ * ${description}
+ */
+export const ${pascalName}: React.FC<${pascalName}Props> = (props) => {
+  return (
+    <div>
+      {/* TODO: Implement component UI */}
+      <p>Component: ${pascalName}</p>
+    </div>
+  );
+};
+`;
+}
+function generateTestTemplate(targetName, type) {
+  const importPath = type === "handler" ? "../handlers" : "../components";
+  const testName = toPascalCase(targetName);
+  return `import { describe, it, expect } from 'bun:test';
+import { ${testName} } from '${importPath}/${toKebabCase(targetName)}';
+
+describe('${testName}', () => {
+  it('should ${type === "handler" ? "handle valid input" : "render correctly"}', async () => {
+    // TODO: Implement test
+    expect(true).toBe(true);
+  });
+
+  it('should handle edge cases', async () => {
+    // TODO: Test edge cases
+  });
+
+  ${type === "handler" ? `it('should handle errors appropriately', async () => {
+    // TODO: Test error scenarios
+  });` : `it('should be accessible', async () => {
+    // TODO: Test accessibility
+  });`}
+});
+`;
+}
+// src/ai/prompts/spec-creation.ts
+function buildOperationSpecPrompt(description, kind) {
+  return `You are a senior software architect creating a contract specification for an operation.
+
+The operation is a ${kind} (${kind === "command" ? "changes state, has side effects" : "read-only, idempotent"}).
+
+User description: ${description}
+
+Create a complete contract specification following these guidelines:
+
+1. **Name**: Use dot notation like "domain.operationName" (e.g., "user.signup", "payment.charge")
+2. **Version**: Start at 1
+3. **Description**: Clear, concise summary (1-2 sentences)
+4. **Goal**: Business purpose - why this operation exists
+5. **Context**: Background, constraints, scope (what it does and doesn't do)
+6. **Input/Output**: Describe the shape (we'll create schemas separately)
+7. **Auth**: Who can call this - anonymous, user, or admin
+8. **Feature Flags**: Any flags that gate this operation
+9. **Side Effects**: What events might be emitted, analytics to track
+
+Respond with a structured spec.`;
+}
+function buildEventSpecPrompt(description) {
+  return `You are a senior software architect creating an event specification.
+
+User description: ${description}
+
+Create a complete event specification following these guidelines:
+
+1. **Name**: Use dot notation like "domain.event_name" (e.g., "user.signup_completed", "payment.charged")
+2. **Version**: Start at 1
+3. **Description**: Clear description of when this event is emitted
+4. **Payload**: Describe what data the event carries
+5. **PII Fields**: List any personally identifiable information fields (e.g., ["email", "name"])
+
+Events represent things that have already happened and should use past tense.
+
+Respond with a structured spec.`;
+}
+function buildPresentationSpecPrompt(description, kind) {
+  const kindDescriptions = {
+    web_component: "a React component with props schema",
+    markdown: "markdown/MDX documentation or guide",
+    data: "structured data export (JSON/XML)"
+  };
+  return `You are a senior software architect creating a presentation specification.
+
+This is a ${kind} presentation - ${kindDescriptions[kind]}.
+
+User description: ${description}
+
+Create a complete presentation specification following these guidelines:
+
+1. **Name**: Use dot notation like "domain.presentation_name" (e.g., "user.profile_card", "docs.api_guide")
+2. **Version**: Start at 1
+3. **Description**: What this presentation shows/provides
+4. **Kind-specific details**:
+   ${kind === "web_component" ? `- Component key (symbolic, resolved by host app)
+   - Props structure
+   - Analytics events to track` : kind === "markdown" ? `- Content or resource URI
+   - Target audience` : `- MIME type (e.g., application/json)
+   - Data structure description`}
+
+Respond with a structured spec.`;
+}
+function getSystemPrompt() {
+  return `You are an expert software architect specializing in API design and contract-driven development.
+
+You create clear, well-documented specifications that serve as the single source of truth for operations, events, and presentations.
+
+Your specs are:
+- Precise and unambiguous
+- Following TypeScript conventions
+- Business-oriented (capturing the "why" not just "what")
+- Designed for both humans and AI agents to understand
+
+Always use proper dot notation for names and ensure all metadata is meaningful and accurate.`;
+}
+function addExampleContext(basePrompt, examples) {
+  if (examples.length === 0)
+    return basePrompt;
+  return `${basePrompt}
+
+Here are some good examples for reference:
+
+${examples.join(`
+
+`)}
+
+Follow this structure and quality level.`;
+}
+// src/ai/prompts/code-generation.ts
+function buildHandlerPrompt(specCode) {
+  return `You are a senior TypeScript developer implementing a handler for a contract specification.
+
+Here is the contract spec:
+
+\`\`\`typescript
+${specCode}
+\`\`\`
+
+Generate a complete handler implementation that:
+
+1. **Matches the spec signature**: Input/output types from the spec
+2. **Handles errors**: Implement error cases defined in spec.io.errors
+3. **Emits events**: Use the events declared in spec.sideEffects.emits
+4. **Validates input**: Use zod validation from the schema
+5. **Follows best practices**: Clean, type-safe TypeScript
+6. **Includes comments**: Explain business logic
+
+The handler should be production-ready with proper error handling, logging points, and clear structure.
+
+Return only the TypeScript code for the handler function.`;
+}
+function buildComponentPrompt(specCode) {
+  return `You are a senior React developer creating a component for a presentation specification.
+
+Here is the presentation spec:
+
+\`\`\`typescript
+${specCode}
+\`\`\`
+
+Generate a complete React component that:
+
+1. **Props interface**: Typed props from the spec
+2. **Accessibility**: Proper ARIA labels, roles, keyboard navigation
+3. **Mobile-first**: Optimized for small screens and touch
+4. **Clean UI**: Simple, intuitive interface
+5. **Type-safe**: Full TypeScript with no 'any' types
+6. **Best practices**: React hooks, proper state management
+
+The component should follow Atomic Design principles and be reusable.
+
+Return only the TypeScript/TSX code for the component.`;
+}
+function buildFormPrompt(specCode) {
+  return `You are a senior React developer creating a form component from a form specification.
+
+Here is the form spec:
+
+\`\`\`typescript
+${specCode}
+\`\`\`
+
+Generate a complete form component using react-hook-form that:
+
+1. **Form validation**: Use zod schema for validation
+2. **Field types**: Proper inputs for each field type
+3. **Conditional logic**: Support visibleWhen, enabledWhen, requiredWhen predicates
+4. **Error handling**: Clear, user-friendly error messages
+5. **Accessibility**: Labels, hints, ARIA attributes
+6. **Mobile-optimized**: Touch-friendly, appropriate input types
+7. **Type-safe**: Full TypeScript
+
+The form should provide excellent UX with real-time validation and helpful feedback.
+
+Return only the TypeScript/TSX code for the form component.`;
+}
+function buildTestPrompt(specCode, implementationCode, testType) {
+  const testFocus = testType === "handler" ? `
+  - Test all acceptance scenarios from the spec
+  - Test error cases defined in spec.io.errors
+  - Verify events are emitted correctly
+  - Test input validation
+  - Test happy path and edge cases` : `
+  - Test rendering with various props
+  - Test user interactions
+  - Test accessibility (a11y)
+  - Test responsive behavior
+  - Test error states`;
+  return `You are a senior developer writing comprehensive tests.
+
+Spec:
+\`\`\`typescript
+${specCode}
+\`\`\`
+
+Implementation:
+\`\`\`typescript
+${implementationCode}
+\`\`\`
+
+Generate complete test suite using Vitest that:
+${testFocus}
+
+Use clear test descriptions and follow AAA pattern (Arrange, Act, Assert).
+
+Return only the TypeScript test code.`;
+}
+function getCodeGenSystemPrompt() {
+  return `You are an expert TypeScript developer with deep knowledge of:
+- Type-safe API design
+- React and modern hooks
+- Test-driven development
+- Accessibility best practices
+- Clean code principles
+
+Generate production-ready code that is:
+- Fully typed (no 'any' or type assertions unless absolutely necessary)
+- Well-documented with TSDoc comments
+- Following project conventions
+- Defensive and error-safe
+- Easy to maintain and extend
+
+Always prioritize code quality, safety, and user experience.`;
+}
+// src/formatter.ts
+import { exec } from "child_process";
+import { promisify } from "util";
+import { existsSync } from "fs";
+import { dirname, resolve } from "path";
+import { readFile as readFile2 } from "fs/promises";
+var execAsync = promisify(exec);
+var FORMATTER_CONFIG_FILES = {
+  prettier: [
+    ".prettierrc",
+    ".prettierrc.json",
+    ".prettierrc.yaml",
+    ".prettierrc.yml",
+    ".prettierrc.js",
+    ".prettierrc.cjs",
+    ".prettierrc.mjs",
+    "prettier.config.js",
+    "prettier.config.cjs",
+    "prettier.config.mjs"
+  ],
+  eslint: [
+    ".eslintrc",
+    ".eslintrc.json",
+    ".eslintrc.yaml",
+    ".eslintrc.yml",
+    ".eslintrc.js",
+    ".eslintrc.cjs",
+    "eslint.config.js",
+    "eslint.config.mjs",
+    "eslint.config.cjs"
+  ],
+  biome: ["biome.json", "biome.jsonc"],
+  dprint: ["dprint.json", ".dprint.json"],
+  custom: []
+};
+var FORMATTER_PACKAGES = {
+  prettier: ["prettier"],
+  eslint: ["eslint"],
+  biome: ["@biomejs/biome"],
+  dprint: ["dprint"],
+  custom: []
+};
+async function detectFormatter(cwd = process.cwd()) {
+  const priority = ["prettier", "biome", "eslint", "dprint"];
+  for (const formatter of priority) {
+    if (await isFormatterAvailable(formatter, cwd)) {
+      return formatter;
+    }
+  }
+  return null;
+}
+async function isFormatterAvailable(formatter, cwd) {
+  const configFiles = FORMATTER_CONFIG_FILES[formatter] || [];
+  for (const configFile of configFiles) {
+    if (existsSync(resolve(cwd, configFile))) {
+      return true;
+    }
+  }
+  const packageJsonPath = resolve(cwd, "package.json");
+  if (existsSync(packageJsonPath)) {
+    try {
+      const packageJson = JSON.parse(await readFile2(packageJsonPath, "utf-8"));
+      const allDeps = {
+        ...packageJson.dependencies,
+        ...packageJson.devDependencies
+      };
+      const packages = FORMATTER_PACKAGES[formatter] || [];
+      for (const pkg of packages) {
+        if (pkg in allDeps) {
+          return true;
+        }
+      }
+    } catch {}
+  }
+  const parentDir = dirname(cwd);
+  if (parentDir !== cwd && parentDir !== "/") {
+    return isFormatterAvailable(formatter, parentDir);
+  }
+  return false;
+}
+function getFormatterCommand(type, files, config) {
+  const fileArgs = files.map((f) => `"${f}"`).join(" ");
+  const extraArgs = config?.args?.join(" ") || "";
+  switch (type) {
+    case "prettier":
+      return `bunx prettier --write ${extraArgs} ${fileArgs}`;
+    case "eslint":
+      return `bunx eslint --fix ${extraArgs} ${fileArgs}`;
+    case "biome":
+      return `bunx @biomejs/biome format --write ${extraArgs} ${fileArgs}`;
+    case "dprint":
+      return `bunx dprint fmt ${extraArgs} ${fileArgs}`;
+    case "custom":
+      if (!config?.command) {
+        throw new Error("Custom formatter requires a command to be specified in config");
+      }
+      return `${config.command} ${extraArgs} ${fileArgs}`;
+    default:
+      throw new Error(`Unknown formatter type: ${type}`);
+  }
+}
+async function formatFiles(files, config, options, logger) {
+  const startTime = Date.now();
+  const fileList = Array.isArray(files) ? files : [files];
+  const cwd = options?.cwd || process.cwd();
+  if (options?.skip || config?.enabled === false) {
+    return {
+      success: true,
+      formatted: false,
+      duration: Date.now() - startTime
+    };
+  }
+  let formatterType = options?.type || config?.type;
+  if (!formatterType) {
+    const detected = await detectFormatter(cwd);
+    if (!detected) {
+      return {
+        success: true,
+        formatted: false,
+        duration: Date.now() - startTime
+      };
+    }
+    formatterType = detected;
+  }
+  const command = getFormatterCommand(formatterType, fileList, config);
+  const timeout = config?.timeout || 30000;
+  if (!options?.silent && logger) {
+    logger.log(`\uD83C\uDFA8 Formatting ${fileList.length} file(s) with ${formatterType}...`);
+  }
+  try {
+    await execAsync(command, {
+      cwd,
+      timeout
+    });
+    if (!options?.silent && logger) {
+      logger.success(`\u2705 Formatted ${fileList.length} file(s)`);
+    }
+    return {
+      success: true,
+      formatted: true,
+      duration: Date.now() - startTime,
+      formatterUsed: formatterType
+    };
+  } catch (error) {
+    const errorMessage = error instanceof Error ? error.message : String(error);
+    if (!options?.silent && logger) {
+      logger.warn(`\u26A0\uFE0F Formatting failed (continuing anyway): ${errorMessage}`);
+    }
+    return {
+      success: false,
+      formatted: false,
+      error: errorMessage,
+      duration: Date.now() - startTime,
+      formatterUsed: formatterType
+    };
+  }
+}
+async function formatFilesBatch(files, config, options, logger) {
+  return formatFiles(files, config, options, logger);
+}
+// src/formatters/spec-markdown.ts
+import * as path from "path";
+function specToMarkdown(spec, format, optionsOrDepth = 0) {
+  const options = typeof optionsOrDepth === "number" ? { depth: optionsOrDepth } : optionsOrDepth;
+  const depth = options.depth ?? 0;
+  const rootPath = options.rootPath;
+  const lines = [];
+  const indent = depth > 0 ? "  ".repeat(depth) : "";
+  const headerLevel = Math.min(depth + 1, 6);
+  const headerPrefix = "#".repeat(headerLevel);
+  lines.push(`${indent}${headerPrefix} ${spec.meta.key}`);
+  lines.push("");
+  if (spec.meta.description) {
+    lines.push(`${indent}${spec.meta.description}`);
+    lines.push("");
+  }
+  if (format === "context") {
+    return formatContextMode(spec, lines, indent);
+  }
+  if (format === "prompt") {
+    return formatPromptMode(spec, lines, indent);
+  }
+  return formatFullMode(spec, lines, indent, rootPath);
+}
+function formatContextMode(spec, lines, indent) {
+  const metaParts = [];
+  metaParts.push(`**${spec.specType}**`);
+  if (spec.kind && spec.kind !== "unknown")
+    metaParts.push(`(${spec.kind})`);
+  metaParts.push(`v${spec.meta.version}`);
+  if (spec.meta.stability)
+    metaParts.push(`[${spec.meta.stability}]`);
+  lines.push(`${indent}${metaParts.join(" ")}`);
+  lines.push("");
+  if (spec.specType === "feature") {
+    const counts = [];
+    if (spec.operations?.length)
+      counts.push(`${spec.operations.length} operation(s)`);
+    if (spec.events?.length)
+      counts.push(`${spec.events.length} event(s)`);
+    if (spec.presentations?.length)
+      counts.push(`${spec.presentations.length} presentation(s)`);
+    if (counts.length > 0) {
+      lines.push(`${indent}Contains: ${counts.join(", ")}`);
+      lines.push("");
+    }
+  }
+  if (spec.specType === "operation") {
+    const indicators = [];
+    if (spec.hasIo)
+      indicators.push("I/O");
+    if (spec.hasPolicy)
+      indicators.push("Policy");
+    if (spec.emittedEvents?.length)
+      indicators.push(`${spec.emittedEvents.length} event(s)`);
+    if (indicators.length > 0) {
+      lines.push(`${indent}Includes: ${indicators.join(", ")}`);
+      lines.push("");
+    }
+  }
+  return lines.join(`
+`);
+}
+function formatPromptMode(spec, lines, indent) {
+  lines.push(`${indent}**Type**: ${spec.specType}${spec.kind && spec.kind !== "unknown" ? ` (${spec.kind})` : ""}`);
+  lines.push(`${indent}**Version**: ${spec.meta.version}`);
+  if (spec.meta.stability)
+    lines.push(`${indent}**Stability**: ${spec.meta.stability}`);
+  if (spec.meta.owners?.length)
+    lines.push(`${indent}**Owners**: ${spec.meta.owners.join(", ")}`);
+  if (spec.meta.tags?.length)
+    lines.push(`${indent}**Tags**: ${spec.meta.tags.join(", ")}`);
+  lines.push("");
+  if (spec.meta.goal) {
+    lines.push(`${indent}**Goal**: ${spec.meta.goal}`);
+    lines.push("");
+  }
+  if (spec.meta.context) {
+    lines.push(`${indent}**Context**: ${spec.meta.context}`);
+    lines.push("");
+  }
+  if (spec.specType === "operation") {
+    const structure = [];
+    if (spec.hasIo)
+      structure.push("Input/Output Schema");
+    if (spec.hasPolicy)
+      structure.push("Policy Enforcement");
+    if (spec.hasPayload)
+      structure.push("Payload");
+    if (spec.hasContent)
+      structure.push("Content");
+    if (structure.length > 0) {
+      lines.push(`${indent}**Structure**: ${structure.join(", ")}`);
+      lines.push("");
+    }
+  }
+  if (spec.specType === "feature") {
+    appendFeatureRefs(spec, lines, indent);
+  }
+  if (spec.emittedEvents?.length) {
+    lines.push(`${indent}**Emits**: ${formatRefs(spec.emittedEvents)}`);
+    lines.push("");
+  }
+  lines.push(`${indent}---`);
+  lines.push("");
+  lines.push(`${indent}**Implementation Instructions**:`);
+  lines.push("");
+  appendImplementationInstructions(spec, lines, indent);
+  return lines.join(`
+`);
+}
+function formatFullMode(spec, lines, indent, rootPath) {
+  lines.push(`${indent}## Metadata`);
+  lines.push("");
+  lines.push(`${indent}- **Type**: ${spec.specType}${spec.kind && spec.kind !== "unknown" ? ` (${spec.kind})` : ""}`);
+  lines.push(`${indent}- **Version**: ${spec.meta.version}`);
+  if (spec.meta.stability) {
+    lines.push(`${indent}- **Stability**: ${spec.meta.stability}`);
+  }
+  if (spec.meta.owners?.length) {
+    lines.push(`${indent}- **Owners**: ${spec.meta.owners.join(", ")}`);
+  }
+  if (spec.meta.tags?.length) {
+    lines.push(`${indent}- **Tags**: ${spec.meta.tags.join(", ")}`);
+  }
+  if (spec.filePath) {
+    const displayPath = rootPath ? path.relative(rootPath, spec.filePath) : spec.filePath;
+    lines.push(`${indent}- **File**: \`${displayPath}\``);
+  }
+  lines.push("");
+  if (spec.meta.goal) {
+    lines.push(`${indent}## Goal`);
+    lines.push("");
+    lines.push(`${indent}${spec.meta.goal}`);
+    lines.push("");
+  }
+  if (spec.meta.context) {
+    lines.push(`${indent}## Context`);
+    lines.push("");
+    lines.push(`${indent}${spec.meta.context}`);
+    lines.push("");
+  }
+  if (spec.specType === "feature") {
+    appendFeatureSections(spec, lines, indent);
+  }
+  if (spec.emittedEvents?.length) {
+    lines.push(`${indent}## Emitted Events`);
+    lines.push("");
+    for (const ev of spec.emittedEvents) {
+      lines.push(`${indent}- \`${ev.name}\` (v${ev.version})`);
+    }
+    lines.push("");
+  }
+  if (spec.policyRefs?.length) {
+    lines.push(`${indent}## Policy References`);
+    lines.push("");
+    for (const policy of spec.policyRefs) {
+      lines.push(`${indent}- \`${policy.name}\` (v${policy.version})`);
+    }
+    lines.push("");
+  }
+  if (spec.testRefs?.length) {
+    lines.push(`${indent}## Test Specifications`);
+    lines.push("");
+    for (const test of spec.testRefs) {
+      lines.push(`${indent}- \`${test.name}\` (v${test.version})`);
+    }
+    lines.push("");
+  }
+  if (spec.sourceBlock) {
+    lines.push(`${indent}## Source Definition`);
+    lines.push("");
+    lines.push(`${indent}\`\`\`typescript`);
+    const sourceLines = spec.sourceBlock.split(`
+`);
+    for (const sourceLine of sourceLines) {
+      lines.push(`${indent}${sourceLine}`);
+    }
+    lines.push(`${indent}\`\`\``);
+    lines.push("");
+  }
+  return lines.join(`
+`);
+}
+function formatRefs(refs) {
+  return refs.map((r) => `\`${r.name}\``).join(", ");
+}
+function appendFeatureRefs(spec, lines, indent) {
+  if (spec.operations?.length) {
+    lines.push(`${indent}**Operations**: ${formatRefs(spec.operations)}`);
+  }
+  if (spec.events?.length) {
+    lines.push(`${indent}**Events**: ${formatRefs(spec.events)}`);
+  }
+  if (spec.presentations?.length) {
+    lines.push(`${indent}**Presentations**: ${formatRefs(spec.presentations)}`);
+  }
+  lines.push("");
+}
+function appendFeatureSections(spec, lines, indent) {
+  if (spec.operations?.length) {
+    lines.push(`${indent}## Operations (${spec.operations.length})`);
+    lines.push("");
+    for (const op of spec.operations) {
+      lines.push(`${indent}- \`${op.name}\` (v${op.version})`);
+    }
+    lines.push("");
+  }
+  if (spec.events?.length) {
+    lines.push(`${indent}## Events (${spec.events.length})`);
+    lines.push("");
+    for (const ev of spec.events) {
+      lines.push(`${indent}- \`${ev.name}\` (v${ev.version})`);
+    }
+    lines.push("");
+  }
+  if (spec.presentations?.length) {
+    lines.push(`${indent}## Presentations (${spec.presentations.length})`);
+    lines.push("");
+    for (const pres of spec.presentations) {
+      lines.push(`${indent}- \`${pres.name}\` (v${pres.version})`);
+    }
+    lines.push("");
+  }
+}
+function appendImplementationInstructions(spec, lines, indent) {
+  if (spec.specType === "operation") {
+    lines.push(`${indent}Implement the \`${spec.meta.key}\` ${spec.kind ?? "operation"} ensuring:`);
+    if (spec.hasIo) {
+      lines.push(`${indent}- Input validation per schema`);
+      lines.push(`${indent}- Output matches expected schema`);
+    }
+    if (spec.hasPolicy) {
+      lines.push(`${indent}- Policy rules are enforced`);
+    }
+    if (spec.emittedEvents?.length) {
+      lines.push(`${indent}- Events are emitted on success`);
+    }
+  } else if (spec.specType === "feature") {
+    lines.push(`${indent}Implement the \`${spec.meta.key}\` feature including:`);
+    if (spec.operations?.length) {
+      lines.push(`${indent}- ${spec.operations.length} operation(s)`);
+    }
+    if (spec.presentations?.length) {
+      lines.push(`${indent}- ${spec.presentations.length} presentation(s)`);
+    }
+  } else if (spec.specType === "event") {
+    lines.push(`${indent}Implement the \`${spec.meta.key}\` event ensuring:`);
+    lines.push(`${indent}- Payload matches expected schema`);
+    lines.push(`${indent}- Event is properly typed`);
+  } else if (spec.specType === "presentation") {
+    lines.push(`${indent}Implement the \`${spec.meta.key}\` presentation ensuring:`);
+    lines.push(`${indent}- Component renders correctly`);
+    lines.push(`${indent}- Accessibility requirements are met`);
+  } else {
+    lines.push(`${indent}Implement the \`${spec.meta.key}\` ${spec.specType} according to the specification.`);
+  }
+  lines.push("");
+}
+function specToMarkdownWithOptions(spec, options) {
+  return specToMarkdown(spec, options.format, options.depth ?? 0);
+}
+function generateSpecsSummaryHeader(specs, format) {
+  const lines = [];
+  lines.push("# ContractSpec Export");
+  lines.push("");
+  lines.push(`**Format**: ${format}`);
+  lines.push(`**Specs**: ${specs.length}`);
+  lines.push("");
+  const byType = new Map;
+  for (const spec of specs) {
+    byType.set(spec.specType, (byType.get(spec.specType) ?? 0) + 1);
+  }
+  if (byType.size > 0) {
+    lines.push("**Contents**:");
+    for (const [type, count] of byType) {
+      lines.push(`- ${count} ${type}(s)`);
+    }
+    lines.push("");
+  }
+  lines.push("---");
+  lines.push("");
+  return lines.join(`
+`);
+}
+function combineSpecMarkdowns(specs, format) {
+  const header = generateSpecsSummaryHeader(specs, format);
+  const specMarkdowns = specs.map((spec) => specToMarkdown(spec, format));
+  return header + specMarkdowns.join(`
+---
+
+`);
+}
+// src/formatters/spec-to-docblock.ts
+function convertSpecToDocBlock(spec, options) {
+  const body = specToMarkdown(spec, "full", { rootPath: options?.rootPath });
+  return {
+    id: spec.meta.key,
+    title: spec.meta.description ? `${spec.meta.key} - ${spec.meta.description}` : spec.meta.key,
+    body,
+    summary: spec.meta.description,
+    kind: mapSpecTypeToDocKind(spec.specType),
+    visibility: "public",
+    version: spec.meta.version,
+    tags: spec.meta.tags,
+    owners: spec.meta.owners,
+    stability: spec.meta.stability,
+    domain: inferDomain(spec.meta.key),
+    relatedSpecs: extractRelatedSpecs(spec)
+  };
+}
+function mapSpecTypeToDocKind(specType) {
+  switch (specType) {
+    case "feature":
+      return "goal";
+    case "operation":
+      return "reference";
+    case "event":
+      return "reference";
+    case "presentation":
+      return "usage";
+    default:
+      return "reference";
+  }
+}
+function inferDomain(key) {
+  const parts = key.split(".");
+  if (parts.length > 2) {
+    return parts[0];
+  }
+  return;
+}
+function extractRelatedSpecs(spec) {
+  const related = [];
+  if (spec.emittedEvents) {
+    related.push(...spec.emittedEvents.map((r) => r.name));
+  }
+  if (spec.operations) {
+    related.push(...spec.operations.map((r) => r.name));
+  }
+  if (spec.events) {
+    related.push(...spec.events.map((r) => r.name));
+  }
+  if (spec.testRefs) {
+    related.push(...spec.testRefs.map((r) => r.name));
+  }
+  return [...new Set(related)];
+}
+export {
+  validateSpecStructure,
+  toPascalCase,
+  toKebabCase,
+  toDot,
+  toCanonicalJson,
+  toCamelCase,
+  specToMarkdownWithOptions,
+  specToMarkdown,
+  sortSpecs,
+  sortFields,
+  scanSpecSource,
+  scanFeatureSource,
+  scanExampleSource,
+  scanAllSpecsFromSource,
+  parseImportedSpecNames,
+  normalizeValue,
+  loadSpecFromSource,
+  isFeatureFile,
+  isExampleFile,
+  isBreakingChange,
+  inferSpecTypeFromFilePath,
+  inferSpecTypeFromCodeBlock,
+  groupSpecsToArray,
+  groupSpecs,
+  getUniqueSpecTags,
+  getUniqueSpecOwners,
+  getUniqueSpecDomains,
+  getSystemPrompt,
+  getRulesBySeverity,
+  getCodeGenSystemPrompt,
+  generateWorkflowSpec,
+  generateWorkflowRunnerTemplate,
+  generateTestTemplate,
+  generateTelemetrySpec,
+  generateSpecsSummaryHeader,
+  generateSnapshot,
+  generatePresentationSpec,
+  generateOperationSpec,
+  generateMigrationSpec,
+  generateKnowledgeSpaceSpec,
+  generateIntegrationSpec,
+  generateHandlerTemplate,
+  generateExperimentSpec,
+  generateEventSpec,
+  generateDataViewSpec,
+  generateComponentTemplate,
+  generateAppBlueprintSpec,
+  formatFilesBatch,
+  formatFiles,
+  findMissingDependencies,
+  findMatchingRule,
+  filterSpecs,
+  filterFeatures,
+  extractTestTarget,
+  extractTestCoverage,
+  escapeString,
+  detectFormatter,
+  detectCycles,
+  createContractGraph,
+  convertSpecToDocBlock,
+  computeSemanticDiff,
+  computeIoDiff,
+  computeHash,
+  computeFieldsDiff,
+  computeFieldDiff,
+  combineSpecMarkdowns,
+  classifyImpact,
+  capitalize,
+  buildTestPrompt,
+  buildReverseEdges,
+  buildPresentationSpecPrompt,
+  buildOperationSpecPrompt,
+  buildHandlerPrompt,
+  buildFormPrompt,
+  buildEventSpecPrompt,
+  buildComponentPrompt,
+  addExampleContext,
+  addContractNode,
+  SpecGroupingStrategies,
+  NON_BREAKING_RULES,
+  INFO_RULES,
+  DEFAULT_RULES,
+  BREAKING_RULES
+};