@open-mercato/cli 0.6.7 → 0.6.8-canary.319.1.5b4be4bc52

package/dist/lib/generators/module-facts.js

@@ -1,7 +1,26 @@
+import { createHash } from "node:crypto";
 import fs from "node:fs";
 import path from "node:path";
 import ts from "typescript-js";
 import { toSnake } from "../utils.js";
+import { extractCommandIdsFromSource } from "./module-registry.js";
+import { MODULE_CODE_EXTENSIONS } from "./scanner.js";
+import {
+  assertNoUnresolvedExtensionTargets,
+  correlateIncomingExtensions,
+  correlateModuleExtensionFacts,
+  extractActivationTargetOwners,
+  extractKnownApiRouteIds,
+  extractKnownCommandIds,
+  extractModuleExtensionFacts,
+  renderFrameworkExtensionPointsMarkdown,
+  withModuleExtensionFactExtractionCache
+} from "./module-extension-facts.js";
+import {
+  collectModuleOverrideTargets
+} from "./module-override-targets.js";
+import { buildFactSourceLookup } from "./module-fact-sources.js";
+import { appendLocalReferenceModuleSource } from "./module-facts-discovery.js";
 function readSourceFile(filePath) {
   if (!fs.existsSync(filePath)) return null;
   const source = fs.readFileSync(filePath, "utf8");
@@ -62,6 +81,34 @@ function classHasUpdatedAtColumn(node) {
   }
   return false;
 }
+function readStaticAccessPath(candidate) {
+  const access = unwrapExpression(candidate);
+  if (ts.isIdentifier(access)) return [access.text];
+  if (ts.isPropertyAccessExpression(access)) {
+    const parent = readStaticAccessPath(access.expression);
+    return parent ? [...parent, access.name.text] : null;
+  }
+  if (ts.isElementAccessExpression(access) && access.argumentExpression) {
+    const parent = readStaticAccessPath(access.expression);
+    const key = unwrapExpression(access.argumentExpression);
+    return parent && ts.isStringLiteralLike(key) ? [...parent, key.text] : null;
+  }
+  return null;
+}
+function resolveEntityIdReference(expression, initializers, visitedIdentifiers = /* @__PURE__ */ new Set()) {
+  const current = unwrapExpression(expression);
+  if (ts.isStringLiteralLike(current)) return current.text;
+  const accessPath = readStaticAccessPath(current);
+  if (accessPath?.length === 3 && accessPath[0] === "E") {
+    return `${accessPath[1]}:${accessPath[2]}`;
+  }
+  if (initializers && ts.isIdentifier(current) && !visitedIdentifiers.has(current.text)) {
+    visitedIdentifiers.add(current.text);
+    const declaration = initializers.get(current.text);
+    if (declaration) return resolveEntityIdReference(declaration, initializers, visitedIdentifiers);
+  }
+  return void 0;
+}
 function collectCustomFieldEntityIds(ceFilePath) {
   const result = /* @__PURE__ */ new Set();
   if (!ceFilePath) return result;
@@ -69,8 +116,11 @@ function collectCustomFieldEntityIds(ceFilePath) {
   if (!sourceFile) return result;
   const visit = (node) => {
     if (ts.isObjectLiteralExpression(node)) {
-      const id = readStringPropertyInitializer(node, "id");
-      if (id && id.includes(":")) result.add(id);
+      const initializer = getObjectPropertyInitializer(node, "id");
+      if (initializer) {
+        const id = resolveEntityIdReference(initializer);
+        if (id && id.includes(":")) result.add(id);
+      }
     }
     node.forEachChild(visit);
   };
@@ -118,8 +168,29 @@ function getPropertyName(property) {
   if (!name) return void 0;
   if (ts.isIdentifier(name)) return name.text;
   if (ts.isStringLiteralLike(name)) return name.text;
+  if (ts.isComputedPropertyName(name)) return resolveComputedPropertyKey(name.expression);
   return void 0;
 }
+function resolveComputedPropertyKey(expression) {
+  if (ts.isStringLiteralLike(expression)) return expression.text;
+  if (ts.isAsExpression(expression) || ts.isSatisfiesExpression(expression)) {
+    return resolveComputedPropertyKey(expression.expression);
+  }
+  if (ts.isParenthesizedExpression(expression)) return resolveComputedPropertyKey(expression.expression);
+  if (!ts.isIdentifier(expression)) return void 0;
+  const sourceFile = expression.getSourceFile();
+  if (!sourceFile) return void 0;
+  let resolved;
+  const visit = (node) => {
+    if (resolved) return;
+    if (ts.isVariableDeclaration(node) && ts.isIdentifier(node.name) && node.name.text === expression.text) {
+      if (node.initializer) resolved = resolveComputedPropertyKey(node.initializer);
+    }
+    node.forEachChild(visit);
+  };
+  sourceFile.forEachChild(visit);
+  return resolved;
+}
 function getObjectPropertyInitializer(objectLiteral, propertyName) {
   for (const property of objectLiteral.properties) {
     if (!ts.isPropertyAssignment(property)) continue;
@@ -212,7 +283,11 @@ function extractEvents(eventsFilePath) {
       category: category ?? null,
       entity: entity ?? null
     };
+    const clientBroadcast = readBooleanPropertyInitializer(element, "clientBroadcast");
+    const portalBroadcast = readBooleanPropertyInitializer(element, "portalBroadcast");
     if (label !== void 0) fact.label = label;
+    if (clientBroadcast !== void 0) fact.clientBroadcast = clientBroadcast;
+    if (portalBroadcast !== void 0) fact.portalBroadcast = portalBroadcast;
     facts.push(fact);
   }
   return facts;
@@ -302,9 +377,9 @@ function parseApiRouteEntry(entryLiteral) {
       }
     }
   }
-  return { path: routePath, methods, auth };
+  return { path: routePath, methods, auth, sourcePath: null };
 }
-function extractApiRoutes(moduleId, registrySource, registryDescription, warnings) {
+function extractApiRoutes(moduleId, registrySource, registryDescription, routeSourcePaths, warnings) {
   if (registrySource == null) {
     warnings.push(`[module-facts] module registry unavailable (${registryDescription}); API route auth omitted for ${moduleId}`);
     return [];
@@ -328,7 +403,7 @@ function extractApiRoutes(moduleId, registrySource, registryDescription, warning
           const route = parseApiRouteEntry(element);
           if (route && !seenPaths.has(route.path)) {
             seenPaths.add(route.path);
-            routes.push(route);
+            routes.push({ ...route, sourcePath: routeSourcePaths.get(route.path) ?? null });
           }
         }
       }
@@ -405,15 +480,25 @@ function extractSearchEntities(searchFilePath, warnings) {
     warnings.push(`[module-facts] searchConfig.entities is not an array literal: ${searchFilePath}`);
     return [];
   }
+  const initializers = buildVariableInitializerMap(sourceFile);
   const entityIds = [];
   const seen = /* @__PURE__ */ new Set();
   for (const element of entitiesArray.elements) {
     if (!ts.isObjectLiteralExpression(element)) continue;
-    const entityId = readStringPropertyInitializer(element, "entityId");
-    if (entityId && !seen.has(entityId)) {
-      seen.add(entityId);
-      entityIds.push(entityId);
+    const initializer = getObjectPropertyInitializer(element, "entityId");
+    const location = `${searchFilePath}:${nodeLine(sourceFile, element)}`;
+    if (!initializer) {
+      warnings.push(`[module-facts] searchConfig entity declares no entityId: ${location}`);
+      continue;
+    }
+    const entityId = resolveEntityIdReference(initializer, initializers);
+    if (!entityId) {
+      warnings.push(`[module-facts] searchConfig entityId is not statically resolvable: ${location}`);
+      continue;
     }
+    if (seen.has(entityId)) continue;
+    seen.add(entityId);
+    entityIds.push(entityId);
   }
   return entityIds;
 }
@@ -476,31 +561,204 @@ function extractCli(cliFilePath, warnings) {
 function listSourceFilesRecursive(directory) {
   const files = [];
   for (const entry of fs.readdirSync(directory, { withFileTypes: true })) {
-    if (entry.name === "__tests__" || entry.name === "node_modules") continue;
+    if (entry.name === "__tests__" || entry.name === "__mocks__" || entry.name === "node_modules") continue;
     const fullPath = path.join(directory, entry.name);
     if (entry.isDirectory()) {
       files.push(...listSourceFilesRecursive(fullPath));
-    } else if (/\.tsx?$/.test(entry.name) && !entry.name.endsWith(".d.ts")) {
+    } else if (/\.tsx?$/.test(entry.name) && !entry.name.endsWith(".d.ts") && !/\.(?:test|spec)\.tsx?$/.test(entry.name)) {
       files.push(fullPath);
     }
   }
   return files;
 }
-function extractTableIds(backendDir) {
-  if (!fs.existsSync(backendDir)) return [];
+function toPortableSourceRoot(moduleId, sourcePackage) {
+  return path.posix.join("node_modules", sourcePackage ?? "@open-mercato/core", "src", "modules", moduleId);
+}
+function assertPortableSourceRoot(moduleId, portableSourceRoot) {
+  const invalid = portableSourceRoot.length === 0 || path.posix.isAbsolute(portableSourceRoot) || /^[A-Za-z]:/.test(portableSourceRoot) || portableSourceRoot.includes("\\") || portableSourceRoot.split("/").includes("..");
+  if (invalid) {
+    throw new Error(
+      `[module-facts] portableSourceRoot for module "${moduleId}" must be a relative POSIX app path, received "${portableSourceRoot}"`
+    );
+  }
+  return portableSourceRoot;
+}
+function toPortableSourcePath(moduleRoot, sourceRoot, filePath) {
+  const relativePath = path.relative(moduleRoot, filePath).split(path.sep).join("/");
+  return path.posix.join(sourceRoot, relativePath);
+}
+function sourceHasDefaultExport(sourceFile) {
+  return sourceFile.statements.some((statement) => {
+    if (ts.isExportAssignment(statement) && !statement.isExportEquals) return true;
+    if (!ts.isFunctionDeclaration(statement) && !ts.isClassDeclaration(statement)) return false;
+    return statement.modifiers?.some((modifier) => modifier.kind === ts.SyntaxKind.DefaultKeyword) ?? false;
+  });
+}
+function readRouteMetadataPath(sourceFile) {
+  const metadata = findObjectLiteralDeclaration(sourceFile, "metadata");
+  return metadata ? readStringPropertyInitializer(metadata, "path") ?? null : null;
+}
+function extractApiRouteSourcePaths(moduleId, moduleRoot, sourceRoot) {
+  const apiRoot = path.join(moduleRoot, "api");
+  const sources = /* @__PURE__ */ new Map();
+  if (!fs.existsSync(apiRoot)) return sources;
+  const methodDirectories = /* @__PURE__ */ new Set(["get", "post", "put", "patch", "delete"]);
+  for (const filePath of listSourceFilesRecursive(apiRoot)) {
+    const relativePath = path.relative(apiRoot, filePath).split(path.sep).join("/");
+    const segments = relativePath.split("/");
+    const fileName = segments.pop();
+    const fileStem = fileName.replace(/\.tsx?$/, "");
+    let routeSegments;
+    if (fileStem === "route") {
+      routeSegments = segments;
+    } else if (segments[0] && methodDirectories.has(segments[0].toLowerCase())) {
+      routeSegments = [...segments.slice(1), fileStem];
+    } else {
+      routeSegments = [...segments, fileStem];
+    }
+    const defaultPath = `/${[moduleId, ...routeSegments].filter(Boolean).join("/")}`;
+    const sourceFile = readSourceFile(filePath);
+    const routePath = sourceFile ? readRouteMetadataPath(sourceFile) ?? defaultPath : defaultPath;
+    sources.set(routePath, toPortableSourcePath(moduleRoot, sourceRoot, filePath));
+  }
+  return sources;
+}
+function extractModulePages(moduleId, moduleRoot, sourceRoot, surface) {
+  const pageRoot = path.join(moduleRoot, surface);
+  if (!fs.existsSync(pageRoot)) return [];
+  const pages = [];
+  const seen = /* @__PURE__ */ new Set();
+  for (const filePath of listSourceFilesRecursive(pageRoot)) {
+    if (!filePath.endsWith(".tsx")) continue;
+    const relativePath = path.relative(pageRoot, filePath).split(path.sep).join("/");
+    const segments = relativePath.split("/");
+    const fileName = segments.pop();
+    const fileStem = fileName.replace(/\.tsx$/, "");
+    const isModernPage = fileStem === "page";
+    if (!isModernPage && (fileStem === "meta" || fileStem.endsWith(".meta") || /^[A-Z]/.test(fileStem))) continue;
+    const sourceFile = readSourceFile(filePath);
+    if (!sourceFile || !sourceHasDefaultExport(sourceFile)) continue;
+    const routeSegments = isModernPage ? segments : [...segments, fileStem];
+    const routePath = surface === "frontend" ? `/${routeSegments.filter(Boolean).join("/")}` : isModernPage ? `/backend/${routeSegments.join("/") || moduleId}` : `/backend/${routeSegments[0] === moduleId ? routeSegments.filter(Boolean).join("/") : [moduleId, ...routeSegments].filter(Boolean).join("/")}`;
+    if (seen.has(routePath)) continue;
+    seen.add(routePath);
+    const metadataFilePath = resolvePageMetadataFile(path.dirname(filePath));
+    const metadataSourceFile = metadataFilePath ? readSourceFile(metadataFilePath) : sourceFile;
+    const metadata = metadataSourceFile ? readPageMetadata(metadataSourceFile) : void 0;
+    pages.push({
+      path: routePath,
+      sourcePath: toPortableSourcePath(moduleRoot, sourceRoot, filePath),
+      ...metadataFilePath ? { metadataSourcePath: toPortableSourcePath(moduleRoot, sourceRoot, metadataFilePath) } : {},
+      ...metadata ? { metadata } : {}
+    });
+  }
+  return pages.sort((left, right) => left.path.localeCompare(right.path));
+}
+function findAncestorVariableDeclaration(node) {
+  let current = node.parent;
+  while (current) {
+    if (ts.isVariableDeclaration(current)) return current;
+    current = current.parent;
+  }
+  return null;
+}
+function findAncestorCallExpression(node) {
+  let current = node.parent;
+  while (current) {
+    if (ts.isCallExpression(current)) return current;
+    if (ts.isVariableDeclaration(current) || ts.isStatement(current)) return null;
+    current = current.parent;
+  }
+  return null;
+}
+function extractNamedAiFacts(filePaths, moduleRoot, sourceRoot, propertyName) {
+  const facts = [];
+  const seen = /* @__PURE__ */ new Set();
+  for (const filePath of filePaths) {
+    const sourceFile = readSourceFile(filePath);
+    if (!sourceFile) continue;
+    const initializers = buildVariableInitializerMap(sourceFile);
+    const readDefinitionValue = (objectLiteral) => {
+      const initializer = getObjectPropertyInitializer(objectLiteral, propertyName);
+      if (!initializer) return void 0;
+      const resolved = unwrapExpression(initializer);
+      if (ts.isStringLiteralLike(resolved)) return resolved.text;
+      if (ts.isIdentifier(resolved)) {
+        const declarationInitializer = initializers.get(resolved.text);
+        if (declarationInitializer) {
+          const declarationValue = unwrapExpression(declarationInitializer);
+          if (ts.isStringLiteralLike(declarationValue)) return declarationValue.text;
+        }
+      }
+      return void 0;
+    };
+    const visit = (node) => {
+      if (ts.isObjectLiteralExpression(node)) {
+        const value = readDefinitionValue(node);
+        if (value && !seen.has(value)) {
+          const declaration = findAncestorVariableDeclaration(node);
+          const declarationName = declaration && ts.isIdentifier(declaration.name) ? declaration.name.text : "";
+          const declarationType = declaration?.type?.getText(sourceFile) ?? "";
+          const call = findAncestorCallExpression(node);
+          const callee = call?.expression.getText(sourceFile) ?? "";
+          const isDefinition = propertyName === "name" ? /AiTool/.test(declarationType) || /tool$/i.test(declarationName) || /AiTool/.test(callee) : /AiAgentDefinition/.test(declarationType) || /agent$/i.test(declarationName) || /defineAiAgent/.test(callee);
+          if (isDefinition) {
+            seen.add(value);
+            facts.push({
+              value,
+              sourcePath: toPortableSourcePath(moduleRoot, sourceRoot, filePath)
+            });
+          }
+        }
+      }
+      node.forEachChild(visit);
+    };
+    sourceFile.forEachChild(visit);
+  }
+  return facts.sort((left, right) => left.value.localeCompare(right.value));
+}
+function extractAiTools(moduleRoot, sourceRoot) {
+  const files = /* @__PURE__ */ new Set();
+  const rootFile = resolveConventionFile(moduleRoot, "ai-tools");
+  if (rootFile) files.add(rootFile);
+  const toolsDirectory = path.join(moduleRoot, "ai-tools");
+  if (fs.existsSync(toolsDirectory)) {
+    for (const filePath of listSourceFilesRecursive(toolsDirectory)) files.add(filePath);
+  }
+  return extractNamedAiFacts([...files], moduleRoot, sourceRoot, "name").map((fact) => ({ name: fact.value, sourcePath: fact.sourcePath }));
+}
+function extractAiAgents(moduleRoot, sourceRoot) {
+  const agentsFile = resolveConventionFile(moduleRoot, "ai-agents");
+  if (!agentsFile) return [];
+  return extractNamedAiFacts([agentsFile], moduleRoot, sourceRoot, "id").map((fact) => ({ id: fact.value, sourcePath: fact.sourcePath }));
+}
+function extractTableIds(moduleRoot) {
+  if (!fs.existsSync(moduleRoot)) return [];
   const tableIds = [];
   const seen = /* @__PURE__ */ new Set();
-  for (const filePath of listSourceFilesRecursive(backendDir)) {
+  const collectLiteralValues = (expression) => {
+    const current = unwrapExpression(expression);
+    if (ts.isStringLiteralLike(current)) return [current.text];
+    if (ts.isConditionalExpression(current)) {
+      return [
+        ...collectLiteralValues(current.whenTrue),
+        ...collectLiteralValues(current.whenFalse)
+      ];
+    }
+    return [];
+  };
+  for (const filePath of listSourceFilesRecursive(moduleRoot)) {
     const sourceFile = readSourceFile(filePath);
     if (!sourceFile) continue;
     const visit = (node) => {
       if (ts.isPropertyAssignment(node)) {
         const propertyName = getPropertyName(node);
-        if ((propertyName === "tableId" || propertyName === "extensionTableId") && ts.isStringLiteralLike(node.initializer)) {
-          const value = node.initializer.text;
-          if (value && !seen.has(value)) {
-            seen.add(value);
-            tableIds.push(value);
+        if (propertyName === "tableId" || propertyName === "extensionTableId") {
+          for (const value of collectLiteralValues(node.initializer)) {
+            if (value && !seen.has(value)) {
+              seen.add(value);
+              tableIds.push(value);
+            }
           }
         }
       }
@@ -525,12 +783,587 @@ function extractModuleMeta(indexFilePath) {
     description: readStringPropertyInitializer(metadata, "description") ?? null
   };
 }
+function nodeLine(sourceFile, node) {
+  return sourceFile.getLineAndCharacterOfPosition(node.getStart(sourceFile)).line + 1;
+}
+function readPropertyNameText(name) {
+  if (ts.isIdentifier(name) || ts.isStringLiteralLike(name)) return name.text;
+  return void 0;
+}
+function readMethodBearingPropertyNames(objectLiteral) {
+  const names = [];
+  for (const property of objectLiteral.properties) {
+    if (ts.isMethodDeclaration(property)) {
+      const name = readPropertyNameText(property.name);
+      if (name) names.push(name);
+      continue;
+    }
+    if (ts.isPropertyAssignment(property)) {
+      const name = readPropertyNameText(property.name);
+      if (!name) continue;
+      const initializer = unwrapExpression(property.initializer);
+      if (ts.isArrowFunction(initializer) || ts.isFunctionExpression(initializer)) names.push(name);
+    }
+  }
+  return names.sort((left, right) => left.localeCompare(right));
+}
+function readObjectKeyNames(objectLiteral) {
+  const names = [];
+  for (const property of objectLiteral.properties) {
+    const name = getPropertyName(property);
+    if (name) names.push(name);
+  }
+  return names.sort((left, right) => left.localeCompare(right));
+}
+function mapDiRegistrationKind(base) {
+  switch (base) {
+    case "asFunction":
+      return "function";
+    case "asClass":
+      return "class";
+    case "asValue":
+      return "value";
+    case "aliasTo":
+      return "alias";
+    default:
+      return null;
+  }
+}
+function readDiChainMetadata(initializer) {
+  const result = {};
+  let current = unwrapExpression(initializer);
+  while (ts.isCallExpression(current) && ts.isPropertyAccessExpression(current.expression)) {
+    const method = current.expression.name.text;
+    if ((method === "singleton" || method === "scoped" || method === "transient") && !result.lifetime) {
+      result.lifetime = method;
+    } else if (method === "proxy" && !result.injectionMode) {
+      result.injectionMode = "proxy";
+    } else if (method === "classic" && !result.injectionMode) {
+      result.injectionMode = "classic";
+    }
+    current = unwrapExpression(current.expression.expression);
+  }
+  return result;
+}
+function readDiProviderSymbol(initializer, kind) {
+  let current = unwrapExpression(initializer);
+  while (ts.isCallExpression(current) && ts.isPropertyAccessExpression(current.expression)) {
+    current = unwrapExpression(current.expression.expression);
+  }
+  if (!ts.isCallExpression(current)) return void 0;
+  const argument = current.arguments[0];
+  if (!argument) return void 0;
+  if (kind === "value") return void 0;
+  if (kind === "alias" && ts.isStringLiteralLike(argument)) return argument.text;
+  if ((kind === "function" || kind === "class") && ts.isIdentifier(argument)) return argument.text;
+  return void 0;
+}
+function extractDiRegistrationFacts(diFilePath, sourcePath) {
+  if (!diFilePath) return { facts: [], unresolvedTokens: [] };
+  const sourceFile = readSourceFile(diFilePath);
+  if (!sourceFile) return { facts: [], unresolvedTokens: [] };
+  const facts = [];
+  const unresolvedTokens = [];
+  const visit = (node) => {
+    if (ts.isCallExpression(node) && ts.isPropertyAccessExpression(node.expression) && node.expression.name.text === "register") {
+      const argument = node.arguments[0];
+      if (argument && ts.isObjectLiteralExpression(argument)) {
+        for (const property of argument.properties) {
+          if (!ts.isPropertyAssignment(property)) continue;
+          const token = getPropertyName(property);
+          if (!token) continue;
+          const kind = mapDiRegistrationKind(detectAwilixRegistrationKind(property.initializer));
+          if (!kind) {
+            if (!unresolvedTokens.includes(token)) unresolvedTokens.push(token);
+            continue;
+          }
+          const chain = readDiChainMetadata(property.initializer);
+          const providerSymbol = readDiProviderSymbol(property.initializer, kind);
+          facts.push({
+            token,
+            registrationKind: kind,
+            ...providerSymbol ? { providerSymbol } : {},
+            ...chain.lifetime ? { lifetime: chain.lifetime } : {},
+            ...chain.injectionMode ? { injectionMode: chain.injectionMode } : {},
+            source: { sourcePath, exportName: token, line: nodeLine(sourceFile, property) }
+          });
+        }
+      }
+    }
+    node.forEachChild(visit);
+  };
+  sourceFile.forEachChild(visit);
+  return { facts, unresolvedTokens };
+}
+function deriveLegacyDiTokens(facts) {
+  const tokens = [];
+  const seen = /* @__PURE__ */ new Set();
+  for (const fact of facts) {
+    if (fact.registrationKind !== "function" && fact.registrationKind !== "class") continue;
+    if (seen.has(fact.token)) continue;
+    seen.add(fact.token);
+    tokens.push(fact.token);
+  }
+  return tokens;
+}
+function dedupeOwnedContractFacts(facts) {
+  const byId = /* @__PURE__ */ new Map();
+  for (const fact of facts) {
+    const existing = byId.get(fact.id);
+    if (!existing) {
+      byId.set(fact.id, fact);
+      continue;
+    }
+    if (fact.source.sourcePath.localeCompare(existing.source.sourcePath) < 0) byId.set(fact.id, fact);
+  }
+  return [...byId.values()].sort((left, right) => left.id.localeCompare(right.id));
+}
+const PAGE_CONTEXT_VALUES = /* @__PURE__ */ new Set(["main", "admin", "settings", "profile"]);
+function readAliasedStringProperty(metadata, preferred, fallback) {
+  return readStringPropertyInitializer(metadata, preferred) ?? readStringPropertyInitializer(metadata, fallback);
+}
+function readNumericProperty(metadata, propertyName) {
+  const initializer = getObjectPropertyInitializer(metadata, propertyName);
+  if (!initializer || !ts.isNumericLiteral(initializer)) return void 0;
+  return Number(initializer.text);
+}
+function readPageMetadata(sourceFile) {
+  const metadata = findObjectLiteralDeclaration(sourceFile, "metadata");
+  if (!metadata) return void 0;
+  const result = {};
+  const requireAuth = readBooleanPropertyInitializer(metadata, "requireAuth");
+  if (requireAuth !== void 0) result.requireAuth = requireAuth;
+  const requireCustomerAuth = readBooleanPropertyInitializer(metadata, "requireCustomerAuth");
+  if (requireCustomerAuth !== void 0) result.requireCustomerAuth = requireCustomerAuth;
+  const requireFeatures = readStringArrayPropertyInitializer(metadata, "requireFeatures");
+  if (requireFeatures && requireFeatures.length > 0) result.requireFeatures = requireFeatures;
+  const requireCustomerFeatures = readStringArrayPropertyInitializer(metadata, "requireCustomerFeatures");
+  if (requireCustomerFeatures && requireCustomerFeatures.length > 0) {
+    result.requireCustomerFeatures = requireCustomerFeatures;
+  }
+  const navHidden = readBooleanPropertyInitializer(metadata, "navHidden");
+  if (navHidden !== void 0) result.navHidden = navHidden;
+  const navGroup = readAliasedStringProperty(metadata, "pageGroup", "group");
+  if (navGroup) result.navGroup = navGroup;
+  const navGroupKey = readAliasedStringProperty(metadata, "pageGroupKey", "groupKey");
+  if (navGroupKey) result.navGroupKey = navGroupKey;
+  const navOrder = readNumericProperty(metadata, "pageOrder") ?? readNumericProperty(metadata, "order");
+  if (navOrder !== void 0) result.navOrder = navOrder;
+  const pageContext = readStringPropertyInitializer(metadata, "pageContext");
+  if (pageContext && PAGE_CONTEXT_VALUES.has(pageContext)) {
+    result.pageContext = pageContext;
+  }
+  return Object.keys(result).length > 0 ? result : void 0;
+}
+function resolvePageMetadataFile(pageDirectory) {
+  for (const baseName of ["page.meta", "meta"]) {
+    for (const extension of MODULE_CODE_EXTENSIONS) {
+      const candidate = path.join(pageDirectory, `${baseName}${extension}`);
+      if (fs.existsSync(candidate)) return candidate;
+    }
+  }
+  return null;
+}
+function extractModuleMetadataContract(indexFilePath, moduleId, sourcePath) {
+  if (!indexFilePath || !sourcePath) return null;
+  const sourceFile = readSourceFile(indexFilePath);
+  if (!sourceFile) return null;
+  const metadata = findObjectLiteralDeclaration(sourceFile, "metadata");
+  if (!metadata) return null;
+  const facts = {};
+  const name = readStringPropertyInitializer(metadata, "name");
+  if (name) facts.name = name;
+  const version = readStringPropertyInitializer(metadata, "version");
+  if (version) facts.version = version;
+  const requires = readStringArrayPropertyInitializer(metadata, "requires");
+  if (requires && requires.length > 0) facts.requires = requires;
+  const ejectable = readBooleanPropertyInitializer(metadata, "ejectable");
+  if (ejectable !== void 0) facts.ejectable = ejectable;
+  return {
+    kind: "module-metadata",
+    id: moduleId,
+    source: { sourcePath, exportName: "metadata", line: nodeLine(sourceFile, metadata) },
+    ...Object.keys(facts).length > 0 ? { metadata: facts } : {}
+  };
+}
+function extractCommandContractCandidates(moduleId, moduleRoot, sourceRoot) {
+  const commandsRoot = path.join(moduleRoot, "commands");
+  if (!fs.existsSync(commandsRoot)) return [];
+  const candidates = [];
+  for (const filePath of listSourceFilesRecursive(commandsRoot)) {
+    if (path.basename(filePath).replace(/\.tsx?$/, "") === "interceptors") continue;
+    const sourcePath = toPortableSourcePath(moduleRoot, sourceRoot, filePath);
+    for (const id of extractCommandIdsFromSource(filePath)) candidates.push({ id, sourcePath });
+  }
+  return candidates;
+}
+function deriveWorkerId(moduleId, workersRoot, filePath) {
+  const relativePath = path.relative(workersRoot, filePath).split(path.sep).join("/");
+  const segments = relativePath.split("/");
+  const fileName = segments.pop();
+  const fileStem = fileName.replace(/\.tsx?$/, "");
+  return [moduleId, "workers", ...segments, fileStem].filter(Boolean).join(":");
+}
+function readResolvedStringProperty(objectLiteral, propertyName, initializers) {
+  const initializer = getObjectPropertyInitializer(objectLiteral, propertyName);
+  if (!initializer) return void 0;
+  const resolved = unwrapExpression(initializer);
+  if (ts.isStringLiteralLike(resolved)) return resolved.text;
+  if (ts.isIdentifier(resolved)) {
+    const declaration = initializers.get(resolved.text);
+    if (declaration) {
+      const declarationValue = unwrapExpression(declaration);
+      if (ts.isStringLiteralLike(declarationValue)) return declarationValue.text;
+    }
+  }
+  return void 0;
+}
+function extractWorkerContracts(moduleId, moduleRoot, sourceRoot) {
+  const workersRoot = path.join(moduleRoot, "workers");
+  if (!fs.existsSync(workersRoot)) return { facts: [], unresolved: [] };
+  const facts = [];
+  const unresolved = [];
+  for (const filePath of listSourceFilesRecursive(workersRoot)) {
+    const sourceFile = readSourceFile(filePath);
+    if (!sourceFile) continue;
+    const metadata = findObjectLiteralDeclaration(sourceFile, "metadata");
+    if (!metadata) continue;
+    const sourcePath = toPortableSourcePath(moduleRoot, sourceRoot, filePath);
+    const source = { sourcePath, exportName: "metadata", line: nodeLine(sourceFile, metadata) };
+    const initializers = buildVariableInitializerMap(sourceFile);
+    const workerId = readResolvedStringProperty(metadata, "id", initializers) ?? deriveWorkerId(moduleId, workersRoot, filePath);
+    const hasQueueProperty = getObjectPropertyInitializer(metadata, "queue") !== void 0;
+    const queue = readResolvedStringProperty(metadata, "queue", initializers);
+    if (!hasQueueProperty) {
+      unresolved.push({ code: "unresolved-static-contract", kind: "worker", id: workerId, source });
+      continue;
+    }
+    const workerMetadata = {};
+    if (queue) workerMetadata.queue = queue;
+    else unresolved.push({ code: "unresolved-static-contract", kind: "worker", id: workerId, source });
+    const name = readResolvedStringProperty(metadata, "name", initializers);
+    if (name) workerMetadata.name = name;
+    const concurrencyInitializer = getObjectPropertyInitializer(metadata, "concurrency");
+    if (concurrencyInitializer && ts.isNumericLiteral(concurrencyInitializer)) {
+      workerMetadata.concurrency = Number(concurrencyInitializer.text);
+    }
+    facts.push({
+      kind: "worker",
+      id: workerId,
+      source,
+      ...Object.keys(workerMetadata).length > 0 ? { metadata: workerMetadata } : {}
+    });
+  }
+  return { facts: dedupeOwnedContractFacts(facts), unresolved };
+}
+function extractPageMiddlewareContracts(moduleRoot, sourceRoot) {
+  const facts = [];
+  const unresolved = [];
+  for (const surface of ["backend", "frontend"]) {
+    const filePath = resolveConventionFile(path.join(moduleRoot, surface), "middleware");
+    if (!filePath) continue;
+    const sourceFile = readSourceFile(filePath);
+    if (!sourceFile) continue;
+    const sourcePath = toPortableSourcePath(moduleRoot, sourceRoot, filePath);
+    const middlewareArray = findArrayLiteralDeclaration(sourceFile, "middleware") ?? (() => {
+      const defaultExport = findDefaultExportExpression(sourceFile);
+      return defaultExport ? unwrapArrayLiteral(defaultExport) : null;
+    })();
+    if (!middlewareArray) continue;
+    let index = 0;
+    for (const element of middlewareArray.elements) {
+      if (!ts.isObjectLiteralExpression(element)) continue;
+      const middlewareId = readStringPropertyInitializer(element, "id");
+      if (!middlewareId) {
+        unresolved.push({
+          code: "unresolved-static-contract",
+          kind: "page-middleware",
+          id: `${sourcePath}#${index}`,
+          source: { sourcePath, line: nodeLine(sourceFile, element) }
+        });
+        index += 1;
+        continue;
+      }
+      const metadata = { surface };
+      const mode = readStringPropertyInitializer(element, "mode");
+      if (mode) metadata.mode = mode;
+      const priorityInitializer = getObjectPropertyInitializer(element, "priority");
+      if (priorityInitializer && ts.isNumericLiteral(priorityInitializer)) {
+        metadata.priority = Number(priorityInitializer.text);
+      }
+      facts.push({
+        kind: "page-middleware",
+        id: middlewareId,
+        source: { sourcePath, exportName: "middleware", line: nodeLine(sourceFile, element) },
+        metadata
+      });
+      index += 1;
+    }
+  }
+  return { facts: dedupeOwnedContractFacts(facts), unresolved };
+}
+function extractSetupContract(moduleId, setupFilePath, sourcePath) {
+  if (!setupFilePath || !sourcePath) return null;
+  const sourceFile = readSourceFile(setupFilePath);
+  if (!sourceFile) return null;
+  const setupObject = findObjectLiteralDeclaration(sourceFile, "setup") ?? (() => {
+    const defaultExport = findDefaultExportExpression(sourceFile);
+    if (!defaultExport) return null;
+    const unwrapped = unwrapExpression(defaultExport);
+    return ts.isObjectLiteralExpression(unwrapped) ? unwrapped : null;
+  })();
+  if (!setupObject) return null;
+  const hooks = readMethodBearingPropertyNames(setupObject);
+  const metadata = {};
+  if (hooks.length > 0) metadata.hooks = hooks;
+  const roleFeatures = getObjectPropertyInitializer(setupObject, "defaultRoleFeatures");
+  if (roleFeatures && ts.isObjectLiteralExpression(roleFeatures)) {
+    const roles = readObjectKeyNames(roleFeatures);
+    if (roles.length > 0) metadata.roles = roles;
+  }
+  const customerRoleFeatures = getObjectPropertyInitializer(setupObject, "defaultCustomerRoleFeatures");
+  if (customerRoleFeatures && ts.isObjectLiteralExpression(customerRoleFeatures)) {
+    const customerRoles = readObjectKeyNames(customerRoleFeatures);
+    if (customerRoles.length > 0) metadata.customerRoles = customerRoles;
+  }
+  return {
+    kind: "setup",
+    id: `${moduleId}:setup`,
+    source: { sourcePath, exportName: "setup", line: nodeLine(sourceFile, setupObject) },
+    ...Object.keys(metadata).length > 0 ? { metadata } : {}
+  };
+}
+function extractEncryptionContracts(encryptionFilePath, sourcePath) {
+  if (!encryptionFilePath || !sourcePath) return [];
+  const sourceFile = readSourceFile(encryptionFilePath);
+  if (!sourceFile) return [];
+  const mapsArray = findArrayLiteralDeclaration(sourceFile, "defaultEncryptionMaps") ?? findArrayLiteralDeclaration(sourceFile, "encryptionMaps");
+  if (!mapsArray) return [];
+  const facts = [];
+  for (const element of mapsArray.elements) {
+    if (!ts.isObjectLiteralExpression(element)) continue;
+    const entityId = readStringPropertyInitializer(element, "entityId");
+    if (!entityId) continue;
+    const fieldsInitializer = getObjectPropertyInitializer(element, "fields");
+    const fields = [];
+    if (fieldsInitializer) {
+      const fieldsArray = unwrapArrayLiteral(fieldsInitializer);
+      if (fieldsArray) {
+        for (const fieldElement of fieldsArray.elements) {
+          if (!ts.isObjectLiteralExpression(fieldElement)) continue;
+          const field = readStringPropertyInitializer(fieldElement, "field");
+          if (field) fields.push(field);
+        }
+      }
+    }
+    facts.push({
+      kind: "encryption",
+      id: entityId,
+      source: { sourcePath, exportName: "defaultEncryptionMaps", line: nodeLine(sourceFile, element) },
+      ...fields.length > 0 ? { metadata: { fields: fields.sort((left, right) => left.localeCompare(right)) } } : {}
+    });
+  }
+  return dedupeOwnedContractFacts(facts);
+}
+function extractCustomEntityContracts(ceFilePath, sourcePath) {
+  if (!ceFilePath || !sourcePath) return [];
+  const entityIds = [...collectCustomFieldEntityIds(ceFilePath)].sort((left, right) => left.localeCompare(right));
+  return entityIds.map((id) => ({
+    kind: "custom-entity",
+    id,
+    source: { sourcePath, exportName: "default" }
+  }));
+}
+const AI_OVERRIDE_EXPORTS = [
+  { exportName: "aiAgentOverrides", target: "agent" },
+  { exportName: "aiToolOverrides", target: "tool" }
+];
+function extractAiExtensionContracts(moduleRoot, sourceRoot) {
+  const facts = [];
+  const sources = [
+    { basename: "ai-agents", relativeDir: "." },
+    { basename: "ai-tools", relativeDir: "." },
+    { basename: "ai-agents.extensions", relativeDir: "." },
+    { basename: "ai-tools.extensions", relativeDir: "." }
+  ];
+  for (const entry of sources) {
+    const filePath = resolveConventionFile(path.join(moduleRoot, entry.relativeDir), entry.basename);
+    if (!filePath) continue;
+    const sourceFile = readSourceFile(filePath);
+    if (!sourceFile) continue;
+    const sourcePath = toPortableSourcePath(moduleRoot, sourceRoot, filePath);
+    const extensionsArray = findArrayLiteralDeclaration(sourceFile, "aiAgentExtensions");
+    if (extensionsArray) {
+      for (const element of extensionsArray.elements) {
+        const objectLiteral = ts.isObjectLiteralExpression(element) ? element : ts.isCallExpression(element) && element.arguments[0] && ts.isObjectLiteralExpression(element.arguments[0]) ? element.arguments[0] : null;
+        if (!objectLiteral) continue;
+        const targetAgentId = readStringPropertyInitializer(objectLiteral, "targetAgentId");
+        if (!targetAgentId) continue;
+        facts.push({
+          kind: "ai-extension",
+          id: `agent-extension:${targetAgentId}`,
+          source: { sourcePath, exportName: "aiAgentExtensions", line: nodeLine(sourceFile, objectLiteral) },
+          metadata: { target: "agent", mode: "extension", targetAgentId }
+        });
+      }
+    }
+    for (const { exportName, target } of AI_OVERRIDE_EXPORTS) {
+      const overridesObject = findObjectLiteralDeclaration(sourceFile, exportName);
+      if (!overridesObject) continue;
+      for (const property of overridesObject.properties) {
+        const overrideId = getPropertyName(property);
+        if (!overrideId) continue;
+        facts.push({
+          kind: "ai-extension",
+          id: `${target}-override:${overrideId}`,
+          source: { sourcePath, exportName, line: nodeLine(sourceFile, property) },
+          metadata: { target, mode: "override", overrideKey: overrideId }
+        });
+      }
+    }
+  }
+  return dedupeOwnedContractFacts(facts);
+}
+function extractGeneratorPluginContracts(moduleRoot, sourceRoot) {
+  const filePath = resolveConventionFile(moduleRoot, "generators");
+  if (!filePath) return { facts: [], unresolved: [] };
+  const sourceFile = readSourceFile(filePath);
+  if (!sourceFile) return { facts: [], unresolved: [] };
+  const pluginsArray = findArrayLiteralDeclaration(sourceFile, "generatorPlugins");
+  if (!pluginsArray) return { facts: [], unresolved: [] };
+  const sourcePath = toPortableSourcePath(moduleRoot, sourceRoot, filePath);
+  const initializers = buildVariableInitializerMap(sourceFile);
+  const facts = [];
+  const unresolved = [];
+  let index = 0;
+  for (const element of pluginsArray.elements) {
+    const objectLiteral = resolveToObjectLiteral(element, initializers);
+    if (!objectLiteral) {
+      index += 1;
+      continue;
+    }
+    const pluginId = readStringPropertyInitializer(objectLiteral, "id");
+    if (!pluginId) {
+      unresolved.push({
+        code: "unresolved-static-contract",
+        kind: "generator-plugin",
+        id: `${sourcePath}#${index}`,
+        source: { sourcePath, exportName: "generatorPlugins", line: nodeLine(sourceFile, objectLiteral) }
+      });
+      index += 1;
+      continue;
+    }
+    const metadata = {};
+    const conventionFile = readStringPropertyInitializer(objectLiteral, "conventionFile");
+    if (conventionFile) metadata.conventionFile = conventionFile;
+    const outputFileName = readStringPropertyInitializer(objectLiteral, "outputFileName");
+    if (outputFileName) metadata.outputFileName = outputFileName;
+    facts.push({
+      kind: "generator-plugin",
+      id: pluginId,
+      source: { sourcePath, exportName: "generatorPlugins", line: nodeLine(sourceFile, objectLiteral) },
+      ...Object.keys(metadata).length > 0 ? { metadata } : {}
+    });
+    index += 1;
+  }
+  return { facts: dedupeOwnedContractFacts(facts), unresolved };
+}
+function compareSourceRefs(left, right) {
+  return left.sourcePath.localeCompare(right.sourcePath) || (left.line ?? 0) - (right.line ?? 0) || (left.exportName ?? "").localeCompare(right.exportName ?? "");
+}
+function sameSourceRef(left, right) {
+  return left.sourcePath === right.sourcePath && (left.line ?? null) === (right.line ?? null) && (left.exportName ?? null) === (right.exportName ?? null);
+}
+function provenanceCandidateOrderKey(candidate) {
+  if (candidate.source) {
+    return JSON.stringify([
+      0,
+      candidate.source.sourcePath,
+      candidate.source.line ?? 0,
+      candidate.source.exportName ?? ""
+    ]);
+  }
+  return JSON.stringify([1, candidate.factRef?.factSection ?? "", candidate.factRef?.factKey ?? ""]);
+}
+function buildProvenanceIndex(candidates) {
+  const grouped = /* @__PURE__ */ new Map();
+  for (const candidate of candidates) {
+    const key = JSON.stringify([candidate.kind, candidate.id]);
+    const group = grouped.get(key) ?? [];
+    group.push(candidate);
+    grouped.set(key, group);
+  }
+  const factSources = [];
+  const diagnostics = [];
+  for (const group of grouped.values()) {
+    const sorted = [...group].sort(
+      (left, right) => provenanceCandidateOrderKey(left).localeCompare(provenanceCandidateOrderKey(right))
+    );
+    const canonical = sorted[0];
+    factSources.push(
+      canonical.factRef ? {
+        kind: canonical.kind,
+        id: canonical.id,
+        factRef: {
+          factSection: canonical.factRef.factSection,
+          ...canonical.factRef.factKey === canonical.id ? {} : { factKey: canonical.factRef.factKey }
+        }
+      } : {
+        kind: canonical.kind,
+        id: canonical.id,
+        source: { sourcePath: canonical.source.sourcePath }
+      }
+    );
+    const canonicalKey = provenanceCandidateOrderKey(canonical);
+    for (const rejected of sorted.slice(1)) {
+      if (provenanceCandidateOrderKey(rejected) === canonicalKey) continue;
+      diagnostics.push({
+        code: "duplicate-source",
+        kind: rejected.kind,
+        id: rejected.id,
+        ...rejected.source ? { source: rejected.source } : {}
+      });
+    }
+  }
+  factSources.sort(
+    (left, right) => left.kind.localeCompare(right.kind) || left.id.localeCompare(right.id)
+  );
+  diagnostics.sort(
+    (left, right) => left.code.localeCompare(right.code) || left.kind.localeCompare(right.kind) || left.id.localeCompare(right.id) || compareSourceRefs(left.source ?? { sourcePath: "" }, right.source ?? { sourcePath: "" })
+  );
+  return { factSources, diagnostics };
+}
+function buildOwnedContracts(families) {
+  const result = {};
+  for (const [kind, facts] of families) {
+    if (facts.length === 0) continue;
+    result[kind] = facts.map((fact) => ({
+      ...fact,
+      source: {
+        sourcePath: fact.source.sourcePath,
+        ...fact.source.line ? { line: fact.source.line } : {}
+      }
+    }));
+  }
+  return Object.keys(result).length > 0 ? result : void 0;
+}
+const CONTRIBUTION_KIND_TO_SOURCE_KIND = {
+  subscriber: "subscriber"
+};
+const REGISTRY_TO_SOURCE_KIND = {
+  vector: "vector",
+  integration: "integration",
+  payment: "integration",
+  shipping: "integration",
+  currency: "integration"
+};
 function extractModuleFacts(options) {
-  const { moduleId, coreVersion = null } = options;
+  const { moduleId, coreVersion = null, sourcePackage = null, sourceVersion = null } = options;
   const moduleRoot = options.moduleRoot ?? (options.coreSrcRoot ? path.join(options.coreSrcRoot, moduleId) : null);
   if (!moduleRoot) {
     throw new Error(`[internal] extractModuleFacts requires moduleRoot or coreSrcRoot for module "${moduleId}"`);
   }
+  const sourceRoot = options.portableSourceRoot ? assertPortableSourceRoot(moduleId, options.portableSourceRoot) : toPortableSourceRoot(moduleId, sourcePackage);
   const entitiesFilePath = resolveConventionFile(path.join(moduleRoot, "data"), "entities") ?? resolveConventionFile(path.join(moduleRoot, "db"), "entities") ?? resolveConventionFile(path.join(moduleRoot, "data"), "schema");
   const ceFilePath = resolveConventionFile(moduleRoot, "ce");
   const eventsFilePath = resolveConventionFile(moduleRoot, "events");
@@ -540,7 +1373,9 @@ function extractModuleFacts(options) {
   const notificationsFilePath = resolveConventionFile(moduleRoot, "notifications");
   const cliFilePath = resolveConventionFile(moduleRoot, "cli");
   const indexFilePath = resolveConventionFile(moduleRoot, "index");
-  const backendDir = path.join(moduleRoot, "backend");
+  const setupFilePath = resolveConventionFile(moduleRoot, "setup");
+  const encryptionFilePath = resolveConventionFile(moduleRoot, "encryption");
+  const portableOf = (filePath) => filePath ? toPortableSourcePath(moduleRoot, sourceRoot, filePath) : null;
   const warnings = [];
   const { title, description } = extractModuleMeta(indexFilePath);
   const customFieldEntityIds = collectCustomFieldEntityIds(ceFilePath);
@@ -548,20 +1383,225 @@ function extractModuleFacts(options) {
   const events = extractEvents(eventsFilePath);
   const aclFeatures = extractAclFeatures(aclFilePath);
   const { source: registrySource, description: registryDescription } = resolveRegistrySource(options);
-  const apiRoutes = extractApiRoutes(moduleId, registrySource, registryDescription, warnings);
-  const diTokens = extractDiTokens(diFilePath);
+  const apiRouteSourcePaths = extractApiRouteSourcePaths(moduleId, moduleRoot, sourceRoot);
+  const apiRoutes = extractApiRoutes(moduleId, registrySource, registryDescription, apiRouteSourcePaths, warnings);
+  const diRegistrations = extractDiRegistrationFacts(diFilePath, portableOf(diFilePath) ?? "");
+  const diTokens = deriveLegacyDiTokens(diRegistrations.facts);
+  for (const legacyToken of extractDiTokens(diFilePath)) {
+    if (!diTokens.includes(legacyToken)) diTokens.push(legacyToken);
+  }
   const searchEntities = extractSearchEntities(searchFilePath, warnings);
   const notifications = extractNotifications(notificationsFilePath, warnings);
   const cli = extractCli(cliFilePath, warnings);
+  const cliCommands = cliFilePath ? cli.map((command) => ({
+    command,
+    sourcePath: toPortableSourcePath(moduleRoot, sourceRoot, cliFilePath)
+  })) : [];
+  const backendPages = extractModulePages(moduleId, moduleRoot, sourceRoot, "backend");
+  const frontendPages = extractModulePages(moduleId, moduleRoot, sourceRoot, "frontend");
+  const aiTools = extractAiTools(moduleRoot, sourceRoot);
+  const aiAgents = extractAiAgents(moduleRoot, sourceRoot);
   const hostTokens = {
     entityIds: extractHostEntityIds(entities),
-    tableIds: extractTableIds(backendDir)
+    tableIds: extractTableIds(moduleRoot)
   };
-  return {
+  const extensionSurfaces = extractModuleExtensionFacts({
+    moduleId,
+    moduleRoot,
+    sourceRoot,
+    entities,
+    events,
+    apiRoutes,
+    searchEntities,
+    notifications,
+    aiTools,
+    aiAgents
+  });
+  const indexSourcePath = portableOf(indexFilePath);
+  const diSourcePath = portableOf(diFilePath);
+  const moduleMetadataFact = extractModuleMetadataContract(indexFilePath, moduleId, indexSourcePath);
+  const commandCandidates = extractCommandContractCandidates(moduleId, moduleRoot, sourceRoot);
+  const commandFacts = dedupeOwnedContractFacts(
+    commandCandidates.map((candidate) => ({
+      kind: "command",
+      id: candidate.id,
+      source: { sourcePath: candidate.sourcePath }
+    }))
+  );
+  const workers = extractWorkerContracts(moduleId, moduleRoot, sourceRoot);
+  const pageMiddleware = extractPageMiddlewareContracts(moduleRoot, sourceRoot);
+  const setupFact = extractSetupContract(moduleId, setupFilePath, portableOf(setupFilePath));
+  const encryptionFacts = extractEncryptionContracts(encryptionFilePath, portableOf(encryptionFilePath));
+  const customEntityFacts = extractCustomEntityContracts(ceFilePath, portableOf(ceFilePath));
+  const aiExtensionFacts = extractAiExtensionContracts(moduleRoot, sourceRoot);
+  const generatorPlugins = extractGeneratorPluginContracts(moduleRoot, sourceRoot);
+  const diContractFacts = dedupeOwnedContractFacts(
+    diRegistrations.facts.map((fact) => ({
+      kind: "di-registration",
+      id: fact.token,
+      source: fact.source,
+      metadata: {
+        registrationKind: fact.registrationKind,
+        ...fact.providerSymbol ? { providerSymbol: fact.providerSymbol } : {},
+        ...fact.lifetime ? { lifetime: fact.lifetime } : {},
+        ...fact.injectionMode ? { injectionMode: fact.injectionMode } : {}
+      }
+    }))
+  );
+  const ownedContracts = buildOwnedContracts([
+    ["module-metadata", moduleMetadataFact ? [moduleMetadataFact] : []],
+    ["command", commandFacts],
+    ["worker", workers.facts],
+    ["page-middleware", pageMiddleware.facts],
+    ["setup", setupFact ? [setupFact] : []],
+    ["encryption", encryptionFacts],
+    ["di-registration", diContractFacts],
+    ["custom-entity", customEntityFacts],
+    ["ai-extension", aiExtensionFacts],
+    ["generator-plugin", generatorPlugins.facts]
+  ]);
+  const provenanceCandidates = [];
+  const pushSource = (kind, id, source) => {
+    provenanceCandidates.push({ kind, id, source });
+  };
+  const pushRef = (kind, id, source, factSection, factKey) => {
+    provenanceCandidates.push({ kind, id, source, factRef: { factSection, factKey } });
+  };
+  const pushOwnedRefs = (kind, facts2) => {
+    for (const fact of facts2) pushRef(kind, fact.id, fact.source, `ownedContracts.${kind}`, fact.id);
+  };
+  if (moduleMetadataFact) {
+    pushRef(
+      "module-metadata",
+      moduleId,
+      moduleMetadataFact.source,
+      "ownedContracts.module-metadata",
+      moduleMetadataFact.id
+    );
+  }
+  if (entitiesFilePath) {
+    const entitiesSourcePath = portableOf(entitiesFilePath);
+    for (const entity of entities) {
+      pushSource("entity", entity.id, { sourcePath: entitiesSourcePath, exportName: entity.class });
+    }
+  }
+  if (eventsFilePath) {
+    const eventsSourcePath = portableOf(eventsFilePath);
+    for (const event of events) pushSource("event", event.id, { sourcePath: eventsSourcePath, exportName: "events" });
+  }
+  if (aclFilePath) {
+    const aclSourcePath = portableOf(aclFilePath);
+    for (const feature of aclFeatures) pushSource("acl-feature", feature, { sourcePath: aclSourcePath, exportName: "features" });
+  }
+  for (const route of apiRoutes) {
+    if (route.sourcePath) {
+      pushRef("api-route", route.path, { sourcePath: route.sourcePath }, "apiRoutes", route.path);
+    }
+  }
+  if (searchFilePath) {
+    const searchSourcePath = portableOf(searchFilePath);
+    for (const entityId of searchEntities) pushSource("search", entityId, { sourcePath: searchSourcePath, exportName: "searchConfig" });
+  }
+  if (notificationsFilePath) {
+    const notificationsSourcePath = portableOf(notificationsFilePath);
+    for (const id of notifications) pushSource("notification", id, { sourcePath: notificationsSourcePath });
+  }
+  for (const command of cliCommands) {
+    pushRef("cli-command", command.command, { sourcePath: command.sourcePath }, "cliCommands", command.command);
+  }
+  for (const page of backendPages) {
+    pushRef("backend-page", page.path, { sourcePath: page.sourcePath }, "backendPages", page.path);
+  }
+  for (const page of frontendPages) {
+    pushRef("frontend-page", page.path, { sourcePath: page.sourcePath }, "frontendPages", page.path);
+  }
+  for (const tool of aiTools) pushRef("ai-tool", tool.name, { sourcePath: tool.sourcePath }, "aiTools", tool.name);
+  for (const agent of aiAgents) pushRef("ai-agent", agent.id, { sourcePath: agent.sourcePath }, "aiAgents", agent.id);
+  for (const candidate of commandCandidates) {
+    pushRef("command", candidate.id, { sourcePath: candidate.sourcePath }, "ownedContracts.command", candidate.id);
+  }
+  pushOwnedRefs("worker", workers.facts);
+  pushOwnedRefs("page-middleware", pageMiddleware.facts);
+  if (setupFact) pushOwnedRefs("setup", [setupFact]);
+  pushOwnedRefs("encryption", encryptionFacts);
+  for (const fact of diRegistrations.facts) {
+    pushRef("di-registration", fact.token, fact.source, "ownedContracts.di-registration", fact.token);
+  }
+  pushOwnedRefs("custom-entity", customEntityFacts);
+  pushOwnedRefs("ai-extension", aiExtensionFacts);
+  pushOwnedRefs("generator-plugin", generatorPlugins.facts);
+  const contributionRef = (contributionId) => ({
+    factSection: "extensionSurfaces.contributions",
+    factKey: contributionId
+  });
+  for (const contribution of extensionSurfaces.contributions) {
+    const contributionSource = {
+      sourcePath: contribution.source.path,
+      ...contribution.source.symbol ? { exportName: contribution.source.symbol } : {}
+    };
+    const ref = contributionRef(contribution.id);
+    if (contribution.kind === "subscriber") {
+      pushRef("subscriber", contribution.id, contributionSource, ref.factSection, ref.factKey);
+      continue;
+    }
+    if (contribution.kind === "specialized-registry") {
+      const details = contribution.details;
+      const sourceKind = details.registry ? REGISTRY_TO_SOURCE_KIND[details.registry] : void 0;
+      if (sourceKind) {
+        pushRef(
+          sourceKind,
+          details.registryId ?? contribution.id,
+          contributionSource,
+          ref.factSection,
+          ref.factKey
+        );
+      }
+      continue;
+    }
+    const mapped = CONTRIBUTION_KIND_TO_SOURCE_KIND[contribution.kind];
+    if (mapped) pushRef(mapped, contribution.id, contributionSource, ref.factSection, ref.factKey);
+  }
+  for (const host of extensionSurfaces.hosts) {
+    provenanceCandidates.push({
+      kind: "extension-host",
+      id: host.key,
+      ...host.source.kind === "fact-ref" ? {} : { source: { sourcePath: host.source.path } },
+      factRef: { factSection: "extensionSurfaces.hosts", factKey: host.key }
+    });
+  }
+  for (const contribution of extensionSurfaces.contributions) {
+    pushRef(
+      "extension-contribution",
+      contribution.id,
+      { sourcePath: contribution.source.path },
+      "extensionSurfaces.contributions",
+      contribution.id
+    );
+  }
+  const provenance = buildProvenanceIndex(provenanceCandidates);
+  const factDiagnostics = [
+    ...provenance.diagnostics,
+    ...workers.unresolved,
+    ...pageMiddleware.unresolved,
+    ...generatorPlugins.unresolved,
+    ...diRegistrations.unresolvedTokens.map((token) => ({
+      code: "unresolved-static-contract",
+      kind: "di-registration",
+      id: token,
+      ...diSourcePath ? { source: { sourcePath: diSourcePath, exportName: token } } : {}
+    }))
+  ].sort(
+    (left, right) => left.code.localeCompare(right.code) || left.kind.localeCompare(right.kind) || left.id.localeCompare(right.id)
+  );
+  const facts = {
     module: moduleId,
     title,
     description,
     coreVersion,
+    sourcePackage,
+    sourceVersion,
+    sourceRoot,
+    ...options.sourceKind === "local-reference" ? { sourceKind: options.sourceKind } : {},
     entities,
     events,
     aclFeatures,
@@ -571,33 +1611,54 @@ function extractModuleFacts(options) {
     hostTokens,
     notifications,
     cli,
+    backendPages,
+    frontendPages,
+    cliCommands,
+    aiTools,
+    aiAgents,
+    extensionSurfaces,
+    ...provenance.factSources.length > 0 ? { factSources: provenance.factSources } : {},
+    ...ownedContracts ? { ownedContracts } : {},
+    ...factDiagnostics.length > 0 ? { factDiagnostics } : {},
     warnings
   };
+  const overrides = collectModuleOverrideTargets(facts, buildFactSourceLookup(facts));
+  if (overrides.overrideTargets.length > 0) facts.overrideTargets = overrides.overrideTargets;
+  if (overrides.overrideTargetDiagnostics.length > 0) {
+    facts.overrideTargetDiagnostics = overrides.overrideTargetDiagnostics;
+  }
+  return facts;
 }
 const EMPTY_SECTION_MARKER = "_none_";
-function renderVersionStamp(coreVersion) {
+function renderVersionStamp(coreVersion, sourcePackage, sourceVersion) {
+  if (sourcePackage) {
+    return `<!-- generated from ${sourcePackage} ${sourceVersion || "<unknown>"}; core ${coreVersion || "<unknown>"} \u2014 R1 staleness stamp -->`;
+  }
   const version = coreVersion && coreVersion.length > 0 ? coreVersion : "<unknown>";
   return `<!-- generated from @open-mercato/core ${version} \u2014 R1 staleness stamp -->`;
 }
-function renderEntitiesSection(entities) {
+function renderEntitiesSection(entities, lookup) {
   if (entities.length === 0) return `## Entities
 
 ${EMPTY_SECTION_MARKER}`;
-  const header = "| Entity ID | Class | Table | Editable | CustomFields |";
-  const divider = "|---|---|---|---|---|";
+  const header = "| Entity ID | Class | Table | Editable | CustomFields | Source |";
+  const divider = "|---|---|---|---|---|---|";
   const rows = entities.map(
-    (entity) => `| ${entity.id} | ${entity.class} | ${entity.table} | ${entity.editable ? "yes" : "no"} | ${entity.customFields ? "yes" : "no"} |`
+    (entity) => `| ${entity.id} | ${entity.class} | ${entity.table} | ${entity.editable ? "yes" : "no"} | ${entity.customFields ? "yes" : "no"} | ${renderLookedUpSource(lookup, "entity", entity.id)} |`
   );
   return ["## Entities", "", header, divider, ...rows].join("\n");
 }
-function renderEventsSection(events) {
+function renderEventsSection(events, lookup) {
   const heading = `## Events  (${events.length})`;
   if (events.length === 0) return `${heading}
 
 ${EMPTY_SECTION_MARKER}`;
-  const header = "| ID | Category | Entity |";
-  const divider = "|---|---|---|";
-  const rows = events.map((event) => `| ${event.id} | ${event.category ?? "\u2014"} | ${event.entity ?? "\u2014"} |`);
+  const header = "| ID | Category | Entity | Browser transport | Source |";
+  const divider = "|---|---|---|---|---|";
+  const rows = events.map((event) => {
+    const transports = [event.clientBroadcast ? "client" : null, event.portalBroadcast ? "portal" : null].filter((value) => value !== null);
+    return `| ${event.id} | ${event.category ?? "\u2014"} | ${event.entity ?? "\u2014"} | ${transports.join(", ") || "\u2014"} | ${renderLookedUpSource(lookup, "event", event.id)} |`;
+  });
   return [heading, "", header, divider, ...rows].join("\n");
 }
 function renderInlineListSection(heading, values) {
@@ -608,6 +1669,62 @@ ${EMPTY_SECTION_MARKER}`;
 
 ${values.join(" \xB7 ")}`;
 }
+function renderSourceLinkedListSection(heading, values, lookup, kind, idColumnLabel) {
+  if (values.length === 0) return `${heading}
+
+${EMPTY_SECTION_MARKER}`;
+  const rows = values.map((value) => `| ${value} | ${renderLookedUpSource(lookup, kind, value)} |`);
+  return [heading, "", `| ${idColumnLabel} | Source |`, "|---|---|", ...rows].join("\n");
+}
+function isExactSourceFilePath(sourcePath) {
+  return MODULE_CODE_EXTENSIONS.some((extension) => sourcePath.endsWith(extension));
+}
+function renderSourceLink(sourcePath) {
+  if (!isExactSourceFilePath(sourcePath)) return sourcePath;
+  return `[${sourcePath}](../../../${sourcePath})`;
+}
+function renderSourceRefLink(source) {
+  const anchor = source.line ? `#L${source.line}` : "";
+  const label = source.line ? `${source.sourcePath}:${source.line}` : source.sourcePath;
+  if (!isExactSourceFilePath(source.sourcePath)) return label;
+  return `[${label}](../../../${source.sourcePath}${anchor})`;
+}
+function renderLookedUpSource(lookup, kind, id) {
+  const source = lookup(kind, id);
+  return source ? renderSourceRefLink(source) : "\u2014";
+}
+function renderSafeScalar(value) {
+  if (value === void 0 || value === null) return "\u2014";
+  if (Array.isArray(value)) return value.length > 0 ? value.map((entry) => String(entry)).join(", ") : "\u2014";
+  return String(value);
+}
+function renderOwnedContractMetadata(metadata) {
+  if (!metadata) return "\u2014";
+  const keys = Object.keys(metadata).sort((left, right) => left.localeCompare(right));
+  if (keys.length === 0) return "\u2014";
+  return keys.map((key) => `${key}=${renderSafeScalar(metadata[key])}`).join("; ");
+}
+function renderOwnedContractSection(heading, facts) {
+  if (!facts || facts.length === 0) return "";
+  const rows = facts.map(
+    (fact) => `| ${fact.id} | ${renderOwnedContractMetadata(fact.metadata)} | ${renderSourceRefLink(fact.source)} |`
+  );
+  return [heading, "", "| ID | Metadata | Source |", "|---|---|---|", ...rows].join("\n");
+}
+function renderDiRegistrationsSection(facts) {
+  if (!facts || facts.length === 0) return "";
+  const rows = facts.map((fact) => {
+    const metadata = fact.metadata ?? {};
+    return `| ${fact.id} | ${renderSafeScalar(metadata.registrationKind)} | ${renderSafeScalar(metadata.lifetime)} | ${renderSafeScalar(metadata.injectionMode)} | ${renderSafeScalar(metadata.providerSymbol)} | ${renderSourceRefLink(fact.source)} |`;
+  });
+  return [
+    "## DI registrations (rich)",
+    "",
+    "| Token | Kind | Lifetime | Injection | Provider | Source |",
+    "|---|---|---|---|---|---|",
+    ...rows
+  ].join("\n");
+}
 function describeAuthRule(rule) {
   if (!rule) return "public";
   if (rule.requireFeatures && rule.requireFeatures.length > 0) return rule.requireFeatures.join(", ");
@@ -630,42 +1747,257 @@ function renderApiRoutesSection(routes) {
   if (routes.length === 0) return `## API routes
 
 ${EMPTY_SECTION_MARKER}`;
-  const header = "| Path | Methods | Auth (per-method requireFeatures) |";
-  const divider = "|---|---|---|";
+  const header = "| Path | Methods | Auth (per-method requireFeatures) | Source |";
+  const divider = "|---|---|---|---|";
   const rows = routes.map(
-    (route) => `| ${route.path} | ${route.methods.join(" ")} | ${renderApiRouteAuthCell(route)} |`
+    (route) => `| ${route.path} | ${route.methods.join(" ")} | ${renderApiRouteAuthCell(route)} | ${route.sourcePath ? renderSourceLink(route.sourcePath) : "\u2014"} |`
   );
   return ["## API routes", "", header, divider, ...rows].join("\n");
 }
+function renderLinkedFactsSection(heading, facts) {
+  if (facts.length === 0) return `${heading}
+
+${EMPTY_SECTION_MARKER}`;
+  const rows = facts.map((fact) => `| ${fact.label} | ${renderSourceLink(fact.sourcePath)} |`);
+  return [heading, "", "| ID / path | Source |", "|---|---|", ...rows].join("\n");
+}
 function renderHostTokensSection(hostTokens) {
   const entityIdsLine = hostTokens.entityIds.length > 0 ? hostTokens.entityIds.join(" \xB7 ") : EMPTY_SECTION_MARKER;
   const tableIdsLine = hostTokens.tableIds.length > 0 ? hostTokens.tableIds.join(" \xB7 ") : EMPTY_SECTION_MARKER;
   return ["## Host extension points", "", `- Entity IDs: ${entityIdsLine}`, `- Table IDs: ${tableIdsLine}`].join("\n");
 }
-function renderModuleFactsMarkdown(facts) {
-  const sections = [
+function renderExtensionHostContext(host) {
+  return host.contextContract ?? host.runtimeContract ?? host.scopeContract ?? "\u2014";
+}
+function renderExtensionHostSource(host) {
+  if (host.source.kind === "fact-ref") return `${host.source.factSection}:${host.source.factKey}`;
+  return renderSourceRefLink({ sourcePath: host.source.path });
+}
+function renderExtensionHostsSection(extensionSurfaces) {
+  const boundHosts = extensionSurfaces.hosts.filter((host) => host.bound);
+  if (boundHosts.length === 0) return `## UMES hosts
+
+${EMPTY_SECTION_MARKER}`;
+  const rows = boundHosts.map(
+    (host) => `| ${host.id} | ${host.family} | ${host.capabilities.join(", ") || "\u2014"} | ${renderExtensionHostContext(host)} | ${host.stability.toUpperCase()} | ${renderExtensionHostSource(host)} |`
+  );
+  return [
+    "## UMES hosts",
+    "",
+    "| ID / pattern | Family | Supports | Context | Stability | Source |",
+    "|---|---|---|---|---|---|",
+    ...rows
+  ].join("\n");
+}
+function compactContributionDetails(contribution) {
+  const details = contribution.details;
+  return Object.keys(details).sort((left, right) => left.localeCompare(right)).flatMap((key) => {
+    const value = details[key];
+    if (value === void 0) return [];
+    if (Array.isArray(value)) return [`${key}=${value.join(",") || "none"}`];
+    if (value && typeof value === "object") {
+      const nested = Object.keys(value).sort((left, right) => left.localeCompare(right)).map((nestedKey) => {
+        const nestedValue = value[nestedKey];
+        return `${nestedKey}:${Array.isArray(nestedValue) ? nestedValue.join(",") : String(nestedValue)}`;
+      });
+      return [`${key}={${nested.join(";")}}`];
+    }
+    return [`${key}=${String(value)}`];
+  }).join("; ");
+}
+function renderExtensionContributionsSection(extensionSurfaces) {
+  if (extensionSurfaces.contributions.length === 0) return `## UMES contributions
+
+${EMPTY_SECTION_MARKER}`;
+  const rows = extensionSurfaces.contributions.map((contribution) => {
+    const targets = contribution.targets.map((entry) => entry.id).join(", ");
+    const resolution = contribution.targets.map((entry) => entry.resolution).join(", ");
+    const phases = [...contribution.phases ?? [], ...contribution.operations ?? []].join(", ") || "\u2014";
+    const source = renderSourceRefLink({ sourcePath: contribution.source.path });
+    return `| ${contribution.id} | ${contribution.kind} | ${targets || "\u2014"} | ${phases} | ${compactContributionDetails(contribution)} | ${resolution || "\u2014"} | ${source} |`;
+  });
+  return [
+    "## UMES contributions",
+    "",
+    "| ID | Kind | Target | Phase / operations | Contract | Resolution | Source |",
+    "|---|---|---|---|---|---|---|",
+    ...rows
+  ].join("\n");
+}
+function renderExtensionDiagnosticsSection(extensionSurfaces) {
+  const unbound = extensionSurfaces.hosts.filter((host) => !host.bound);
+  if (unbound.length === 0 && extensionSurfaces.unresolved.length === 0) return "";
+  const diagnostics = [
+    ...unbound.map((host) => `- unbound-helper: ${host.id}`),
+    ...extensionSurfaces.unresolved.map((entry) => `- ${entry.reason}: ${entry.key} (${entry.source.path})`)
+  ];
+  return ["## UMES diagnostics", "", ...diagnostics].join("\n");
+}
+function renderExtensionTargetRef(target) {
+  const method = target.method ? ` ${target.method}` : "";
+  const owner = target.moduleId ? ` @${target.moduleId}` : "";
+  return `${target.kind}:${target.id}${method}${owner}`;
+}
+function renderActivationBindingsSection(extensionSurfaces) {
+  const activations = extensionSurfaces.activations ?? [];
+  if (activations.length === 0) return `## Active extension bindings
+
+${EMPTY_SECTION_MARKER}`;
+  const rows = activations.map((activation) => {
+    const phases = activation.phases && activation.phases.length > 0 ? activation.phases.join(", ") : "\u2014";
+    const source = activation.source ? renderSourceRefLink(activation.source) : "\u2014";
+    const bridge = activation.bridge ? `${activation.bridge.factSection}:${activation.bridge.factKey}` : "\u2014";
+    return `| ${activation.id} | ${activation.kind} | ${renderExtensionTargetRef(activation.host)} | ${activation.contributionKinds.join(", ") || "\u2014"} | ${phases} | ${bridge} | ${source} |`;
+  });
+  return [
+    "## Active extension bindings",
+    "",
+    "| Activation | Kind | Host | Contribution kinds | Phases | Bridge | Source |",
+    "|---|---|---|---|---|---|---|",
+    ...rows
+  ].join("\n");
+}
+function renderIncomingContributionsSection(extensionSurfaces) {
+  const incoming = extensionSurfaces.incoming ?? [];
+  if (incoming.length === 0) return `## Incoming installed contributions
+
+${EMPTY_SECTION_MARKER}`;
+  const rows = incoming.map((entry) => {
+    const activation = entry.activationId ?? "\u2014";
+    const source = entry.source ? renderSourceRefLink(entry.source) : "\u2014";
+    return `| ${entry.contributorModuleId} | ${entry.contributionKind} | ${renderExtensionTargetRef(entry.target)} | ${entry.resolution} | ${activation} | ${entry.contributionId} \xB7 ${source} |`;
+  });
+  return [
+    "## Incoming installed contributions",
+    "",
+    "| Contributor | Kind | Target | Resolution | Activation | Contribution \xB7 Source |",
+    "|---|---|---|---|---|---|",
+    ...rows
+  ].join("\n");
+}
+function renderContributionResolutionsSection(extensionSurfaces, lookup) {
+  const resolutions = extensionSurfaces.contributionResolutions ?? [];
+  if (resolutions.length === 0) return `## Contribution resolutions
+
+${EMPTY_SECTION_MARKER}`;
+  const rows = resolutions.map((resolution) => {
+    const activations = resolution.activationIds.length > 0 ? resolution.activationIds.join(", ") : "\u2014";
+    const source = renderLookedUpSource(lookup, "extension-contribution", resolution.contributionId);
+    return `| ${resolution.contributionId} | ${renderExtensionTargetRef(resolution.target)} | ${resolution.resolution} | ${activations} | ${source} |`;
+  });
+  return [
+    "## Contribution resolutions",
+    "",
+    "| Contribution | Target | Resolution | Activations | Source |",
+    "|---|---|---|---|---|",
+    ...rows
+  ].join("\n");
+}
+function renderOverrideTargetPath(target) {
+  let display = "overrides";
+  for (let index = 0; index < target.path.length; index += 1) {
+    const segment = target.path[index];
+    const isKeyedTerminal = target.key !== void 0 && index === target.path.length - 1;
+    display += isKeyedTerminal ? `[${JSON.stringify(segment)}]` : `.${segment}`;
+  }
+  return display;
+}
+function renderOverrideTargetsSection(targets) {
+  if (!targets || targets.length === 0) return `## Exact override targets
+
+${EMPTY_SECTION_MARKER}`;
+  const header = "| Domain | Path / key | Supported modes | Referenced fact | Source |";
+  const divider = "|---|---|---|---|---|";
+  const rows = targets.map((target) => {
+    const path2 = `\`${renderOverrideTargetPath(target)}\``;
+    const modes = target.modes.join(", ") || "\u2014";
+    const fact = `${target.factRef.factSection}:${target.factRef.factKey}`;
+    return `| ${target.domain} | ${path2} | ${modes} | ${fact} | ${renderSourceRefLink(target.source)} |`;
+  });
+  return ["## Exact override targets", "", header, divider, ...rows].join("\n");
+}
+function renderReferenceProjectionHeader(facts, fingerprints) {
+  return [
+    `# ${facts.module} \u2014 module facts (generated reference projection, do not edit)`,
+    `<!-- generated from local reference ${facts.sourceRoot}; source-fingerprint ${fingerprints.sourceFingerprint}; taxonomy-fingerprint ${fingerprints.taxonomyFingerprint} \u2014 R1 staleness stamp -->`,
+    `> Reference projection: \`${facts.module}\` is not selected by the current runtime. Its activations and exact override targets describe behavior only after opt-in in \`src/modules.ts\`.`,
+    `Source root: ${renderSourceLink(facts.sourceRoot)}`
+  ];
+}
+function renderModuleFactsMarkdown(facts, referenceProjection) {
+  const extensionSurfaces = facts.extensionSurfaces ?? { hosts: [], contributions: [], unresolved: [] };
+  const lookup = buildFactSourceLookup(facts);
+  const header = facts.sourceKind === "local-reference" && referenceProjection ? renderReferenceProjectionHeader(facts, referenceProjection) : [
     `# ${facts.module} \u2014 module facts (generated, do not edit)`,
-    renderVersionStamp(facts.coreVersion),
+    renderVersionStamp(facts.coreVersion, facts.sourcePackage, facts.sourceVersion),
+    `Source root: ${renderSourceLink(facts.sourceRoot)}`
+  ];
+  const sections = [
+    ...header,
     "",
-    renderEntitiesSection(facts.entities),
+    renderEntitiesSection(facts.entities, lookup),
     "",
-    renderEventsSection(facts.events),
+    renderEventsSection(facts.events, lookup),
     "",
-    renderInlineListSection(`## ACL features  (${facts.aclFeatures.length})`, facts.aclFeatures),
+    renderSourceLinkedListSection(
+      `## ACL features  (${facts.aclFeatures.length})`,
+      facts.aclFeatures,
+      lookup,
+      "acl-feature",
+      "Feature"
+    ),
     "",
     renderApiRoutesSection(facts.apiRoutes),
     "",
-    renderInlineListSection("## DI service tokens", facts.diTokens),
+    renderLinkedFactsSection("## Backend pages", facts.backendPages.map((page) => ({ label: page.path, sourcePath: page.sourcePath }))),
+    "",
+    renderLinkedFactsSection("## Frontend pages", facts.frontendPages.map((page) => ({ label: page.path, sourcePath: page.sourcePath }))),
+    "",
+    renderSourceLinkedListSection("## DI service tokens", facts.diTokens, lookup, "di-registration", "Token"),
     "",
-    renderInlineListSection("## Search entities", facts.searchEntities),
+    renderSourceLinkedListSection("## Search entities", facts.searchEntities, lookup, "search", "Entity ID"),
     "",
     renderHostTokensSection(facts.hostTokens),
     "",
-    renderInlineListSection("## Notifications", facts.notifications),
+    renderExtensionHostsSection(extensionSurfaces),
+    "",
+    renderExtensionContributionsSection(extensionSurfaces),
+    "",
+    renderActivationBindingsSection(extensionSurfaces),
+    "",
+    renderIncomingContributionsSection(extensionSurfaces),
+    "",
+    renderContributionResolutionsSection(extensionSurfaces, lookup),
+    "",
+    renderExtensionDiagnosticsSection(extensionSurfaces),
+    "",
+    renderSourceLinkedListSection("## Notifications", facts.notifications, lookup, "notification", "Notification ID"),
+    "",
+    renderLinkedFactsSection("## CLI commands", facts.cliCommands.map((command) => ({ label: command.command, sourcePath: command.sourcePath }))),
+    "",
+    renderLinkedFactsSection("## AI tools / MCP capabilities", facts.aiTools.map((tool) => ({ label: tool.name, sourcePath: tool.sourcePath }))),
+    "",
+    renderLinkedFactsSection("## AI agents", facts.aiAgents.map((agent) => ({ label: agent.id, sourcePath: agent.sourcePath }))),
     "",
-    renderInlineListSection("## CLI", facts.cli),
+    renderOverrideTargetsSection(facts.overrideTargets),
     ""
   ];
+  const owned = facts.ownedContracts ?? {};
+  const ownedSections = [
+    renderOwnedContractSection("## Owned contract \u2014 module metadata", owned["module-metadata"]),
+    renderOwnedContractSection("## Domain commands", owned.command),
+    renderOwnedContractSection("## Workers", owned.worker),
+    renderOwnedContractSection("## Page middleware", owned["page-middleware"]),
+    renderOwnedContractSection("## Setup", owned.setup),
+    renderOwnedContractSection("## Encryption", owned.encryption),
+    renderDiRegistrationsSection(owned["di-registration"]),
+    renderOwnedContractSection("## Custom entities", owned["custom-entity"]),
+    renderOwnedContractSection("## AI extensions", owned["ai-extension"]),
+    renderOwnedContractSection("## Generator plugins", owned["generator-plugin"])
+  ].filter((section) => section.length > 0);
+  for (const section of ownedSections) {
+    sections.push(section, "");
+  }
   return sections.join("\n");
 }
 function toModuleFactsJsonEntry(facts) {
@@ -673,15 +2005,36 @@ function toModuleFactsJsonEntry(facts) {
     title: facts.title,
     description: facts.description,
     coreVersion: facts.coreVersion,
+    sourcePackage: facts.sourcePackage,
+    sourceVersion: facts.sourceVersion,
+    sourceRoot: facts.sourceRoot,
+    ...facts.sourceKind === "local-reference" ? { sourceKind: facts.sourceKind } : {},
     entities: facts.entities,
-    events: facts.events.map((event) => ({ id: event.id, category: event.category, entity: event.entity })),
+    events: facts.events.map((event) => ({
+      id: event.id,
+      category: event.category,
+      entity: event.entity,
+      ...event.clientBroadcast !== void 0 ? { clientBroadcast: event.clientBroadcast } : {},
+      ...event.portalBroadcast !== void 0 ? { portalBroadcast: event.portalBroadcast } : {}
+    })),
     aclFeatures: facts.aclFeatures,
     apiRoutes: facts.apiRoutes,
     diTokens: facts.diTokens,
     searchEntities: facts.searchEntities,
     hostTokens: facts.hostTokens,
     notifications: facts.notifications,
-    cli: facts.cli
+    cli: facts.cli,
+    backendPages: facts.backendPages,
+    frontendPages: facts.frontendPages,
+    cliCommands: facts.cliCommands,
+    aiTools: facts.aiTools,
+    aiAgents: facts.aiAgents,
+    ...facts.extensionSurfaces ? { extensionSurfaces: facts.extensionSurfaces } : {},
+    ...facts.factSources && facts.factSources.length > 0 ? { factSources: facts.factSources } : {},
+    ...facts.ownedContracts && Object.keys(facts.ownedContracts).length > 0 ? { ownedContracts: facts.ownedContracts } : {},
+    ...facts.factDiagnostics && facts.factDiagnostics.length > 0 ? { factDiagnostics: facts.factDiagnostics } : {},
+    ...facts.overrideTargets && facts.overrideTargets.length > 0 ? { overrideTargets: facts.overrideTargets } : {},
+    ...facts.overrideTargetDiagnostics && facts.overrideTargetDiagnostics.length > 0 ? { overrideTargetDiagnostics: facts.overrideTargetDiagnostics } : {}
   };
 }
 function buildModuleFactsJsonObject(factsByModule) {
@@ -695,7 +2048,165 @@ function renderModuleFactsJson(factsByModule) {
   return `${JSON.stringify(buildModuleFactsJsonObject(factsByModule), null, 2)}
 `;
 }
+function assertPackageModuleFactsOnly(factsByModule) {
+  const offenders = Object.values(factsByModule).filter((facts) => facts.sourceKind === "local-reference" || !facts.sourceRoot.startsWith("node_modules/")).map((facts) => `${facts.module} (${facts.sourceRoot})`).sort((left, right) => left.localeCompare(right));
+  if (offenders.length > 0) {
+    throw new Error(
+      `[module-facts] normal package output must not contain app-local modules: ${offenders.join(", ")}`
+    );
+  }
+}
+function sha256Hex(value) {
+  return createHash("sha256").update(value).digest("hex");
+}
+function canonicalizeFingerprintValue(value) {
+  if (Array.isArray(value)) {
+    return value.map((item) => {
+      const canonical = canonicalizeFingerprintValue(item);
+      return { canonical, text: JSON.stringify(canonical) ?? "" };
+    }).sort((left, right) => left.text < right.text ? -1 : left.text > right.text ? 1 : 0).map((item) => item.canonical);
+  }
+  if (value !== null && typeof value === "object") {
+    const record = value;
+    const result = {};
+    for (const key of Object.keys(record).sort((left, right) => left < right ? -1 : left > right ? 1 : 0)) {
+      if (record[key] === void 0) continue;
+      result[key] = canonicalizeFingerprintValue(record[key]);
+    }
+    return result;
+  }
+  return value;
+}
+function canonicalFingerprintJson(value) {
+  return JSON.stringify(canonicalizeFingerprintValue(value));
+}
+const REFERENCE_FINGERPRINT_SKIPPED_DIRECTORIES = /* @__PURE__ */ new Set(["__tests__", "__integration__", "node_modules"]);
+function computeModuleSourceFingerprint(moduleRoot, portableSourceRoot) {
+  assertPortableSourceRoot(path.basename(portableSourceRoot), portableSourceRoot);
+  const records = [];
+  const walk = (directory) => {
+    const entries = fs.readdirSync(directory, { withFileTypes: true });
+    for (const entry of entries) {
+      const fullPath = path.join(directory, entry.name);
+      if (entry.isDirectory()) {
+        if (REFERENCE_FINGERPRINT_SKIPPED_DIRECTORIES.has(entry.name)) continue;
+        walk(fullPath);
+        continue;
+      }
+      if (!entry.isFile()) continue;
+      records.push({
+        path: toPortableSourcePath(moduleRoot, portableSourceRoot, fullPath),
+        sha256: sha256Hex(fs.readFileSync(fullPath))
+      });
+    }
+  };
+  walk(moduleRoot);
+  records.sort((left, right) => left.path < right.path ? -1 : left.path > right.path ? 1 : 0);
+  return sha256Hex(canonicalFingerprintJson(records));
+}
+const TAXONOMY_EXCLUDED_SECTIONS = /* @__PURE__ */ new Set([
+  "title",
+  "description",
+  "coreVersion",
+  "sourcePackage",
+  "sourceVersion",
+  "sourceRoot",
+  "sourceKind"
+]);
+function collectTaxonomyRecords(setName, value, records) {
+  if (value === void 0) return;
+  if (Array.isArray(value)) {
+    for (const item of value) records.push({ setName, value: canonicalizeFingerprintValue(item) });
+    return;
+  }
+  if (value !== null && typeof value === "object") {
+    for (const [key, child] of Object.entries(value)) {
+      collectTaxonomyRecords(`${setName}.${key}`, child, records);
+    }
+    return;
+  }
+  records.push({ setName, value });
+}
+function computeModuleTaxonomyFingerprint(entry) {
+  const records = [];
+  for (const [setName, value] of Object.entries(entry)) {
+    if (TAXONOMY_EXCLUDED_SECTIONS.has(setName)) continue;
+    collectTaxonomyRecords(setName, value, records);
+  }
+  const decorated = records.map((record) => ({ record, text: JSON.stringify(record.value) ?? "" })).sort(
+    (left, right) => left.record.setName < right.record.setName ? -1 : left.record.setName > right.record.setName ? 1 : left.text < right.text ? -1 : left.text > right.text ? 1 : 0
+  );
+  return sha256Hex(JSON.stringify(decorated.map((item) => item.record)));
+}
+function renderReferenceModuleFactsJson(bundle) {
+  const ordered = {};
+  for (const moduleId of Object.keys(bundle).sort((left, right) => left < right ? -1 : left > right ? 1 : 0)) {
+    ordered[moduleId] = bundle[moduleId];
+  }
+  return `${JSON.stringify(ordered, null, 2)}
+`;
+}
+function extractLocalReferenceModuleFacts(options) {
+  const { reference } = options;
+  if (reference.sourceKind !== "local-reference") {
+    throw new Error(
+      `[module-facts] reference source "${reference.moduleId}" must declare sourceKind "local-reference"`
+    );
+  }
+  const portableSourceRoot = reference.portableSourceRoot;
+  if (!portableSourceRoot) {
+    throw new Error(`[module-facts] reference source "${reference.moduleId}" must declare portableSourceRoot`);
+  }
+  assertPortableSourceRoot(reference.moduleId, portableSourceRoot);
+  const sources = appendLocalReferenceModuleSource(options.packageSources, reference);
+  const activated = extractAllModuleFacts({
+    sources,
+    registryPath: options.registryPath ?? null,
+    registrySource: options.registrySource ?? null,
+    coreVersion: options.coreVersion ?? null,
+    // The disposable projection collects rather than throws: an app-local module can name
+    // a target whose classification is still missing from the shared extension reader, and
+    // aborting there would delete the whole reference bundle instead of publishing the
+    // exact gap. Normal package output keeps the strict default.
+    unresolvedFirstPartyTargets: "collect"
+  });
+  const facts = activated.factsByModule[reference.moduleId];
+  if (!facts) {
+    throw new Error(`[module-facts] reference module "${reference.moduleId}" produced no facts`);
+  }
+  if (facts.sourceRoot !== portableSourceRoot) {
+    throw new Error(
+      `[module-facts] reference module "${reference.moduleId}" emitted non-portable source root "${facts.sourceRoot}"`
+    );
+  }
+  const jsonEntry = toModuleFactsJsonEntry(facts);
+  const fingerprints = {
+    sourceFingerprint: computeModuleSourceFingerprint(reference.moduleRoot, portableSourceRoot),
+    taxonomyFingerprint: computeModuleTaxonomyFingerprint(jsonEntry)
+  };
+  return {
+    entry: {
+      moduleId: reference.moduleId,
+      projectionKind: "activated-reference",
+      sourceKind: "local-reference",
+      runtimeSelected: false,
+      ...fingerprints,
+      facts: jsonEntry
+    },
+    markdown: renderModuleFactsMarkdown(facts, fingerprints),
+    warnings: activated.warnings,
+    unresolvedTargets: activated.unresolvedFirstPartyTargets
+  };
+}
+function collectUnresolvedFirstPartyTargets(surfacesByModule) {
+  return Object.entries(surfacesByModule).flatMap(
+    ([moduleId, surface]) => surface.unresolved.filter((entry) => entry.reason === "unresolved-first-party-target").map((entry) => `${moduleId}:${entry.key}`)
+  ).sort((left, right) => left.localeCompare(right));
+}
 function extractAllModuleFacts(options) {
+  return withModuleExtensionFactExtractionCache(() => extractAllModuleFactsWithCache(options));
+}
+function extractAllModuleFactsWithCache(options) {
   const sources = options.sources ? [...options.sources] : options.coreSrcRoot ? (options.moduleIds ?? []).map((moduleId) => ({
     moduleId,
     moduleRoot: path.join(options.coreSrcRoot, moduleId)
@@ -708,21 +2219,87 @@ function extractAllModuleFacts(options) {
       moduleId: source.moduleId,
       moduleRoot: source.moduleRoot,
       coreVersion: options.coreVersion ?? null,
+      sourcePackage: source.from ?? null,
+      sourceVersion: source.packageVersion ?? null,
       registryPath: options.registryPath ?? null,
-      registrySource: options.registrySource ?? null
+      registrySource: options.registrySource ?? null,
+      ...source.portableSourceRoot ? { portableSourceRoot: source.portableSourceRoot } : {},
+      ...source.sourceKind ? { sourceKind: source.sourceKind } : {}
     });
     factsByModule[source.moduleId] = facts;
-    markdownByModule[source.moduleId] = renderModuleFactsMarkdown(facts);
     warnings.push(...facts.warnings);
   }
-  return { factsByModule, markdownByModule, warnings };
+  const surfacesByModule = Object.fromEntries(
+    Object.entries(factsByModule).map(([moduleId, facts]) => [
+      moduleId,
+      facts.extensionSurfaces ?? { hosts: [], contributions: [], unresolved: [] }
+    ])
+  );
+  const correlated = correlateModuleExtensionFacts({
+    surfacesByModule,
+    entityIds: new Set(Object.values(factsByModule).flatMap((facts) => facts.entities.map((entity) => entity.id))),
+    eventIds: new Set(Object.values(factsByModule).flatMap((facts) => facts.events.map((event) => event.id))),
+    apiRoutes: /* @__PURE__ */ new Set([
+      ...Object.values(factsByModule).flatMap((facts) => facts.apiRoutes.map((route) => route.path)),
+      ...sources.flatMap((source) => extractKnownApiRouteIds(source.moduleId, source.moduleRoot))
+    ]),
+    commandIds: new Set(sources.flatMap((source) => extractKnownCommandIds(source.moduleId, source.moduleRoot)))
+  });
+  const unresolvedFirstPartyTargets = collectUnresolvedFirstPartyTargets(correlated);
+  if ((options.unresolvedFirstPartyTargets ?? "throw") === "throw") assertNoUnresolvedExtensionTargets(correlated);
+  const apiRouteOwners = /* @__PURE__ */ new Map();
+  const commandOwners = /* @__PURE__ */ new Map();
+  for (const source of [...sources].sort((left, right) => left.moduleId.localeCompare(right.moduleId))) {
+    const facts = factsByModule[source.moduleId];
+    const sourceRoot = facts ? facts.sourceRoot : source.moduleId;
+    const owners = extractActivationTargetOwners({
+      moduleId: source.moduleId,
+      moduleRoot: source.moduleRoot,
+      sourceRoot
+    });
+    for (const route of owners.apiRoutes) {
+      if (!apiRouteOwners.has(route.id)) {
+        apiRouteOwners.set(route.id, { moduleId: source.moduleId, source: route.source, bridges: route.bridges });
+      }
+    }
+    for (const command of owners.commands) {
+      if (!commandOwners.has(command.id)) commandOwners.set(command.id, { moduleId: source.moduleId, source: command.source });
+    }
+  }
+  const withIncoming = correlateIncomingExtensions({
+    surfacesByModule: correlated,
+    apiRouteOwners,
+    commandOwners
+  });
+  for (const moduleId of Object.keys(factsByModule).sort((left, right) => left.localeCompare(right))) {
+    factsByModule[moduleId].extensionSurfaces = withIncoming[moduleId];
+    markdownByModule[moduleId] = renderModuleFactsMarkdown(factsByModule[moduleId]);
+    warnings.push(...correlated[moduleId].unresolved.map(
+      (entry) => `[module-facts] ${moduleId} ${entry.reason}: ${entry.key} (${entry.source.path})`
+    ));
+  }
+  return {
+    factsByModule,
+    markdownByModule,
+    warnings,
+    frameworkMarkdown: renderFrameworkExtensionPointsMarkdown(),
+    unresolvedFirstPartyTargets
+  };
 }
 export {
+  assertPackageModuleFactsOnly,
+  assertPortableSourceRoot,
   buildModuleFactsJsonObject,
+  collectUnresolvedFirstPartyTargets,
+  computeModuleSourceFingerprint,
+  computeModuleTaxonomyFingerprint,
   extractAllModuleFacts,
+  extractLocalReferenceModuleFacts,
   extractModuleFacts,
+  isExactSourceFilePath,
   renderModuleFactsJson,
   renderModuleFactsMarkdown,
+  renderReferenceModuleFactsJson,
   toModuleFactsJsonEntry
 };
 //# sourceMappingURL=module-facts.js.map