@open-mercato/cli 0.6.7-develop.6756.1.5300c41145 → 0.6.7-develop.6766.1.40c9011995

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

@@ -0,0 +1,1185 @@
+import fs from "node:fs";
+import path from "node:path";
+import ts from "typescript-js";
+import {
+  CRUD_FORM_EXTENSION_SURFACES,
+  CRUD_FORM_LIFECYCLE_PHASES,
+  DATA_TABLE_EXTENSION_SURFACES
+} from "@open-mercato/shared/modules/widgets/extension-points";
+import { extractCommandIdsFromSource } from "./module-registry.js";
+import { scanModuleDir, SCAN_CONFIGS } from "./scanner.js";
+const FRAMEWORK_PREFIXES = [
+  "dashboard:",
+  "menu:",
+  "notification:",
+  "integration:",
+  "integrations.detail:",
+  "system-status:",
+  "topbar:"
+];
+const FRAMEWORK_HOSTS = [
+  frameworkHost("framework.backend.sidebar", "menu:backend.sidebar", "menu", ["menu-item"]),
+  frameworkHost("framework.settings.sidebar", "menu:settings.sidebar", "menu", ["menu-item"]),
+  frameworkHost("framework.profile.sidebar", "menu:profile.sidebar", "menu", ["menu-item"]),
+  frameworkHost("framework.portal.sidebar", "menu:portal.sidebar", "menu", ["menu-item"]),
+  frameworkHost("framework.dashboard", "dashboard:*", "dashboard", ["registry-contribution"]),
+  frameworkHost("framework.notifications", "notification:*", "notification", ["registry-contribution"]),
+  frameworkHost("framework.integration-detail", "integrations.detail:{integrationId}", "integration", ["render-widget"]),
+  frameworkHost("framework.integration-detail-fallback", "integrations.detail:tabs", "integration", ["render-widget"]),
+  frameworkHost("framework.backend-mutation", "backend-mutation:global", "generic", ["headless-widget"]),
+  frameworkHost("framework.crud-form-wildcard", "crud-form:*", "crud-form", ["field-widget", "lifecycle-handler"])
+];
+function frameworkHost(key, id, family, capabilities) {
+  return {
+    key,
+    id,
+    resolution: id.includes("*") || id.includes("{") ? "pattern" : "framework",
+    family,
+    ownerModule: "framework",
+    capabilities,
+    bound: true,
+    stability: "frozen",
+    source: { kind: "framework", path: "packages/ui/src", symbol: key }
+  };
+}
+function frameworkOverrideHost(key, mode) {
+  return {
+    key: `framework.module-override.${key}`,
+    id: `module-override:${key}`,
+    resolution: "framework",
+    family: "module-override",
+    ownerModule: "framework",
+    capabilities: ["module-override"],
+    operations: [mode],
+    bound: true,
+    stability: "stable",
+    source: {
+      kind: "framework",
+      path: "packages/shared/src/modules/overrides.ts",
+      symbol: `ModuleOverrides.${key}`
+    }
+  };
+}
+const FRAMEWORK_OVERRIDE_HOSTS = [
+  frameworkOverrideHost("ai.agents", "disable-replace"),
+  frameworkOverrideHost("ai.tools", "disable-replace"),
+  frameworkOverrideHost("ai.extensions", "additive"),
+  frameworkOverrideHost("routes.api", "disable-replace"),
+  frameworkOverrideHost("routes.pages", "disable-replace"),
+  frameworkOverrideHost("events.subscribers", "disable-replace"),
+  frameworkOverrideHost("workers", "disable-replace"),
+  frameworkOverrideHost("widgets.injection", "disable-replace"),
+  frameworkOverrideHost("widgets.components", "disable-replace"),
+  frameworkOverrideHost("widgets.dashboard", "disable-replace"),
+  frameworkOverrideHost("notifications.types", "disable-replace"),
+  frameworkOverrideHost("notifications.handlers", "disable-replace"),
+  frameworkOverrideHost("interceptors", "disable-replace"),
+  frameworkOverrideHost("commandInterceptors", "disable-replace"),
+  frameworkOverrideHost("enrichers", "disable-replace"),
+  frameworkOverrideHost("guards", "disable-replace"),
+  frameworkOverrideHost("cli", "disable-replace"),
+  frameworkOverrideHost("setup", "replace"),
+  frameworkOverrideHost("acl.features", "disable-replace"),
+  frameworkOverrideHost("di", "disable-replace"),
+  frameworkOverrideHost("encryption.maps", "disable-replace"),
+  frameworkOverrideHost("nav.groupOrder", "additive")
+];
+function allFrameworkHosts() {
+  return [...FRAMEWORK_HOSTS, ...FRAMEWORK_OVERRIDE_HOSTS];
+}
+function sourceFile(filePath) {
+  if (!fs.existsSync(filePath)) return null;
+  const scriptKind = filePath.endsWith(".tsx") ? ts.ScriptKind.TSX : ts.ScriptKind.TS;
+  return ts.createSourceFile(filePath, fs.readFileSync(filePath, "utf8"), ts.ScriptTarget.ES2020, true, scriptKind);
+}
+function unwrap(expression) {
+  let current = expression;
+  while (ts.isAsExpression(current) || ts.isTypeAssertionExpression(current) || ts.isParenthesizedExpression(current) || ts.isSatisfiesExpression(current)) {
+    current = current.expression;
+  }
+  return current;
+}
+function propertyName(node) {
+  if (ts.isIdentifier(node) || ts.isStringLiteralLike(node) || ts.isNumericLiteral(node)) return node.text;
+  return null;
+}
+function buildStaticContext(file) {
+  const initializers = /* @__PURE__ */ new Map();
+  const visit = (node) => {
+    if (ts.isVariableDeclaration(node) && ts.isIdentifier(node.name) && node.initializer) {
+      initializers.set(node.name.text, node.initializer);
+    }
+    if (ts.isFunctionDeclaration(node) && node.name && node.body) {
+      initializers.set(node.name.text, node);
+    }
+    node.forEachChild(visit);
+  };
+  file.forEachChild(visit);
+  return { initializers, sourceFile: file, resolving: /* @__PURE__ */ new Set() };
+}
+function entityRegistryValue(expression) {
+  const parts = [];
+  let current = expression;
+  while (ts.isPropertyAccessExpression(current)) {
+    parts.unshift(current.name.text);
+    current = current.expression;
+  }
+  return ts.isIdentifier(current) && current.text === "E" && parts.length === 2 ? `${parts[0]}:${parts[1]}` : null;
+}
+function staticTemplate(expression, context) {
+  let value = expression.head.text;
+  for (const span of expression.templateSpans) {
+    const substitution = staticValue(span.expression, context);
+    if (typeof substitution !== "string" && typeof substitution !== "number") return null;
+    value += `${substitution}${span.literal.text}`;
+  }
+  return value;
+}
+function staticObject(expression, context) {
+  const result = {};
+  for (const property of expression.properties) {
+    if (ts.isPropertyAssignment(property)) {
+      const name = propertyName(property.name);
+      if (!name) continue;
+      const value = staticValue(property.initializer, context);
+      if (value !== void 0) result[name] = value;
+      continue;
+    }
+    if (ts.isShorthandPropertyAssignment(property)) {
+      const value = staticValue(property.name, context);
+      if (value !== void 0) result[property.name.text] = value;
+      continue;
+    }
+    if (ts.isMethodDeclaration(property)) {
+      const name = propertyName(property.name);
+      if (name) result[name] = true;
+      continue;
+    }
+    if (ts.isSpreadAssignment(property)) {
+      const value = staticValue(property.expression, context);
+      if (isStaticObject(value)) Object.assign(result, value);
+    }
+  }
+  return result;
+}
+function staticValue(expression, context) {
+  const current = unwrap(expression);
+  if (ts.isStringLiteralLike(current) || ts.isNumericLiteral(current)) return current.text;
+  if (current.kind === ts.SyntaxKind.TrueKeyword) return true;
+  if (current.kind === ts.SyntaxKind.FalseKeyword) return false;
+  if (current.kind === ts.SyntaxKind.NullKeyword) return null;
+  if (ts.isNoSubstitutionTemplateLiteral(current)) return current.text;
+  if (ts.isTemplateExpression(current)) return staticTemplate(current, context) ?? void 0;
+  if (ts.isArrayLiteralExpression(current)) {
+    return current.elements.flatMap((element) => {
+      if (ts.isSpreadElement(element)) {
+        const spread = staticValue(element.expression, context);
+        return Array.isArray(spread) ? spread : [];
+      }
+      const value = staticValue(element, context);
+      return value === void 0 ? [] : [value];
+    });
+  }
+  if (ts.isObjectLiteralExpression(current)) return staticObject(current, context);
+  if (ts.isPropertyAccessExpression(current)) {
+    return entityRegistryValue(current) ?? void 0;
+  }
+  if (ts.isIdentifier(current)) {
+    if (context.resolving.has(current.text)) return void 0;
+    const initializer = context.initializers.get(current.text);
+    if (!initializer) return void 0;
+    context.resolving.add(current.text);
+    const value = ts.isFunctionDeclaration(initializer) ? void 0 : staticValue(initializer, context);
+    context.resolving.delete(current.text);
+    return value;
+  }
+  if (ts.isCallExpression(current)) {
+    if (ts.isIdentifier(current.expression)) {
+      const callable = context.initializers.get(current.expression.text);
+      if (callable && (ts.isArrowFunction(callable) || ts.isFunctionExpression(callable) || ts.isFunctionDeclaration(callable))) {
+        const initializers = new Map(context.initializers);
+        callable.parameters.forEach((parameter, index) => {
+          if (ts.isIdentifier(parameter.name) && current.arguments[index]) {
+            initializers.set(parameter.name.text, current.arguments[index]);
+          }
+        });
+        const childContext = {
+          initializers,
+          sourceFile: context.sourceFile,
+          resolving: new Set(context.resolving)
+        };
+        if (callable.body && ts.isExpression(callable.body)) return staticValue(callable.body, childContext);
+        const returnStatement = callable.body?.statements.find(ts.isReturnStatement);
+        if (returnStatement?.expression) return staticValue(returnStatement.expression, childContext);
+      }
+    }
+    const firstArgument = current.arguments[0];
+    if (firstArgument) {
+      const value = staticValue(firstArgument, context);
+      if (!isStaticObject(value) || !ts.isIdentifier(current.expression)) return value;
+      if (current.expression.text === "dataTableExtensionHost") return { family: "data-table", ...value };
+      if (current.expression.text === "crudFormExtensionHost") return { family: "crud-form", ...value };
+      if (current.expression.text === "componentExtensionHost") return { family: "component-handle", ...value };
+      return value;
+    }
+  }
+  if (ts.isConditionalExpression(current)) {
+    const left = staticValue(current.whenTrue, context);
+    const right = staticValue(current.whenFalse, context);
+    return left !== void 0 && JSON.stringify(left) === JSON.stringify(right) ? left : void 0;
+  }
+  return void 0;
+}
+function isStaticObject(value) {
+  return !!value && typeof value === "object" && !Array.isArray(value);
+}
+function strings(value) {
+  return Array.isArray(value) ? value.filter((entry) => typeof entry === "string") : [];
+}
+function stringValue(value) {
+  return typeof value === "string" ? value : void 0;
+}
+function numberValue(value) {
+  if (typeof value === "number") return value;
+  if (typeof value === "string" && /^\d+$/.test(value)) return Number(value);
+  return void 0;
+}
+function booleanValue(value) {
+  return typeof value === "boolean" ? value : void 0;
+}
+function portablePath(moduleRoot, sourceRoot, filePath) {
+  return path.posix.join(sourceRoot, path.relative(moduleRoot, filePath).split(path.sep).join("/"));
+}
+function conventionPath(moduleRoot, relativePath) {
+  const direct = path.join(moduleRoot, relativePath);
+  if (fs.existsSync(direct)) return direct;
+  if (relativePath.endsWith(".ts")) {
+    const tsx = `${direct.slice(0, -3)}.tsx`;
+    if (fs.existsSync(tsx)) return tsx;
+  }
+  return null;
+}
+function readConventionObjectArray(filePath, exportName) {
+  const file = sourceFile(filePath);
+  if (!file) return [];
+  const context = buildStaticContext(file);
+  const initializer = context.initializers.get(exportName);
+  if (!initializer || ts.isFunctionDeclaration(initializer)) return [];
+  const value = staticValue(initializer, context);
+  return Array.isArray(value) ? value.filter(isStaticObject) : [];
+}
+function readRootObject(filePath, variableName) {
+  const file = sourceFile(filePath);
+  if (!file) return null;
+  const context = buildStaticContext(file);
+  const initializer = context.initializers.get(variableName);
+  if (!initializer || ts.isFunctionDeclaration(initializer)) return null;
+  const value = staticValue(initializer, context);
+  return isStaticObject(value) ? value : null;
+}
+function readCallObjectArguments(filePath, calleeNames) {
+  const file = sourceFile(filePath);
+  if (!file) return [];
+  const context = buildStaticContext(file);
+  const result = [];
+  const visit = (node) => {
+    if (ts.isCallExpression(node) && ts.isIdentifier(node.expression) && calleeNames.has(node.expression.text)) {
+      const firstArgument = node.arguments[0];
+      const value = firstArgument ? staticValue(firstArgument, context) : void 0;
+      if (isStaticObject(value)) result.push({ callee: node.expression.text, value });
+    }
+    node.forEachChild(visit);
+  };
+  file.forEachChild(visit);
+  return result;
+}
+function sortHosts(hosts) {
+  const sourceKey = (host) => host.source.kind === "fact-ref" ? `${host.source.factSection}:${host.source.factKey}` : `${host.source.path}:${host.source.symbol}`;
+  return hosts.sort((left, right) => left.family.localeCompare(right.family) || left.id.localeCompare(right.id) || sourceKey(left).localeCompare(sourceKey(right)) || left.key.localeCompare(right.key));
+}
+function sortContributions(contributions) {
+  const targetKey = (contribution) => contribution.targets.map((entry) => entry.id).join("\0");
+  const sourceKey = (contribution) => `${contribution.source.path}:${contribution.source.symbol ?? ""}`;
+  return contributions.sort((left, right) => left.kind.localeCompare(right.kind) || left.id.localeCompare(right.id) || targetKey(left).localeCompare(targetKey(right)) || sourceKey(left).localeCompare(sourceKey(right)));
+}
+function target(id, resolution = "unresolved") {
+  return { id, resolution };
+}
+function factTarget(id, factSection, factKey = id) {
+  return { id, resolution: "fact-ref", factRef: { factSection, factKey } };
+}
+function openTarget(id) {
+  return target(id);
+}
+function declarationSource(sourceRoot, symbol) {
+  return { kind: "declaration", path: path.posix.join(sourceRoot, "extension-points.ts"), symbol };
+}
+function hasDeclarationBinding(moduleRoot, hostKey, declaration) {
+  const relativeSource = stringValue(declaration.source);
+  if (!relativeSource) return false;
+  const bindingFile = sourceFile(path.join(moduleRoot, relativeSource));
+  if (!bindingFile) return false;
+  const escapedHostKey = hostKey.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+  const bindingPattern = new RegExp(
+    `extensionPoints\\s*\\.\\s*hosts(?:\\s*\\.\\s*${escapedHostKey}|\\s*\\[\\s*['"]${escapedHostKey}['"]\\s*\\])`
+  );
+  if (bindingPattern.test(bindingFile.text)) return true;
+  return declaration.family === "integration" && typeof declaration.pattern === "string" && /resolveIntegrationDetailWidgetSpotId\s*\(/.test(bindingFile.text);
+}
+function baseHost(options) {
+  const { declaration } = options;
+  const aliases = strings(declaration.aliases);
+  const fallbacks = strings(declaration.fallbacks);
+  const fact = {
+    key: options.key,
+    id: options.id,
+    resolution: options.resolution ?? (options.id.includes("{") || options.id.includes("*") ? "pattern" : "exact"),
+    family: options.family,
+    ownerModule: options.moduleId,
+    capabilities: options.capabilities,
+    bound: options.bound ?? true,
+    stability: "frozen",
+    source: declarationSource(options.sourceRoot, `extensionPoints.hosts.${options.key.split(".")[0]}`)
+  };
+  const contextContract = stringValue(declaration.contextContract);
+  const dataContract = stringValue(declaration.dataContract);
+  const scopeContract = stringValue(declaration.scopeContract);
+  const runtimeContract = stringValue(declaration.runtimeContract);
+  const activation = stringValue(declaration.activation);
+  if (contextContract) fact.contextContract = contextContract;
+  if (dataContract) fact.dataContract = dataContract;
+  if (scopeContract) fact.scopeContract = scopeContract;
+  if (runtimeContract) fact.runtimeContract = runtimeContract;
+  if (activation) fact.activation = activation;
+  if (aliases.length > 0) fact.aliases = aliases;
+  if (fallbacks.length > 0) fact.fallbacks = fallbacks;
+  return fact;
+}
+function extractDeclaredHosts(options) {
+  const filePath = conventionPath(options.moduleRoot, "extension-points.ts");
+  if (!filePath) return { hosts: [], unresolved: [] };
+  const declaration = readRootObject(filePath, "extensionPoints");
+  const hostsObject = declaration && isStaticObject(declaration.hosts) ? declaration.hosts : null;
+  if (!hostsObject) {
+    return {
+      hosts: [],
+      unresolved: [{
+        key: `${options.moduleId}.extension-points`,
+        source: { path: portablePath(options.moduleRoot, options.sourceRoot, filePath), symbol: "extensionPoints" },
+        reason: "unclassified-binding"
+      }]
+    };
+  }
+  const hosts = [];
+  const unresolved = [];
+  for (const hostKey of Object.keys(hostsObject).sort((left, right) => left.localeCompare(right))) {
+    const host = hostsObject[hostKey];
+    if (!isStaticObject(host)) continue;
+    const family = stringValue(host.family);
+    if (!family) continue;
+    const declarationBound = hasDeclarationBinding(options.moduleRoot, hostKey, host);
+    if (!declarationBound) {
+      unresolved.push({
+        key: `${options.moduleId}.${hostKey}`,
+        source: {
+          path: stringValue(host.source) ?? portablePath(options.moduleRoot, options.sourceRoot, filePath),
+          symbol: `extensionPoints.hosts.${hostKey}`
+        },
+        reason: "unbound-declaration"
+      });
+    }
+    if (family === "data-table") {
+      const tableId = stringValue(host.tableId);
+      if (!tableId) continue;
+      const baseSpotId = stringValue(host.baseSpotId) ?? `data-table:${tableId}`;
+      for (const surface of DATA_TABLE_EXTENSION_SURFACES) {
+        const usesBase = ["header", "footer", "toolbar", "searchTrailing", "emptyState"].includes(surface.key);
+        const id2 = surface.key === "replacement" ? `data-table:${tableId}` : `${usesBase ? baseSpotId : `data-table:${tableId}`}:${surface.suffix}`;
+        hosts.push(baseHost({
+          key: `${hostKey}.${surface.key}`,
+          id: id2,
+          moduleId: options.moduleId,
+          family,
+          capabilities: [...surface.capabilities],
+          sourceRoot: options.sourceRoot,
+          declaration: host,
+          bound: surface.bound && declarationBound
+        }));
+      }
+      continue;
+    }
+    if (family === "crud-form") {
+      const entityId = stringValue(host.entityId);
+      if (!entityId) continue;
+      const spotId = stringValue(host.spotId) ?? `crud-form:${entityId}`;
+      for (const surface of CRUD_FORM_EXTENSION_SURFACES) {
+        const id2 = surface.suffix ? `${spotId}:${surface.suffix}` : spotId;
+        const fact2 = baseHost({
+          key: `${hostKey}.${surface.key}`,
+          id: id2,
+          moduleId: options.moduleId,
+          family,
+          capabilities: [...surface.capabilities],
+          sourceRoot: options.sourceRoot,
+          declaration: host,
+          bound: surface.bound && declarationBound
+        });
+        if (surface.key === "base") fact2.phases = [...CRUD_FORM_LIFECYCLE_PHASES];
+        hosts.push(fact2);
+      }
+      continue;
+    }
+    const id = stringValue(host.spotId) ?? stringValue(host.pattern) ?? stringValue(host.componentId);
+    if (!id) {
+      unresolved.push({
+        key: `${options.moduleId}.${hostKey}`,
+        source: { path: portablePath(options.moduleRoot, options.sourceRoot, filePath), symbol: hostKey },
+        reason: "dynamic-without-pattern"
+      });
+      continue;
+    }
+    const capabilities = family === "component-handle" ? ["component-replacement"] : strings(host.supported);
+    const fact = baseHost({
+      key: hostKey,
+      id,
+      moduleId: options.moduleId,
+      family,
+      capabilities,
+      sourceRoot: options.sourceRoot,
+      declaration: host,
+      bound: declarationBound
+    });
+    if (isStaticObject(host.parameters)) {
+      fact.patternParameters = Object.fromEntries(Object.entries(host.parameters).flatMap(([key, value]) => {
+        if (!isStaticObject(value) || typeof value.source !== "string") return [];
+        return [[key, {
+          source: value.source,
+          ...typeof value.pattern === "string" ? { pattern: value.pattern } : {}
+        }]];
+      }));
+    }
+    hosts.push(fact);
+  }
+  return { hosts: sortHosts(hosts), unresolved };
+}
+function factRefHost(options) {
+  return {
+    key: options.key,
+    id: options.id,
+    resolution: "fact-ref",
+    family: options.family,
+    ownerModule: options.moduleId,
+    capabilities: options.capabilities,
+    ...options.phases ? { phases: options.phases } : {},
+    ...options.activation ? { activation: options.activation } : {},
+    ...options.scopeContract ? { scopeContract: options.scopeContract } : {},
+    bound: true,
+    stability: "stable",
+    source: { kind: "fact-ref", factSection: options.factSection, factKey: options.id }
+  };
+}
+function sourceFilesBelow(directory) {
+  if (!fs.existsSync(directory)) return [];
+  const files = [];
+  const visit = (current) => {
+    for (const entry of fs.readdirSync(current, { withFileTypes: true }).sort((left, right) => left.name.localeCompare(right.name))) {
+      const entryPath = path.join(current, entry.name);
+      if (entry.isDirectory()) {
+        if (entry.name !== "__tests__" && entry.name !== "__integration__") visit(entryPath);
+        continue;
+      }
+      if (entry.isFile() && /\.(?:ts|tsx)$/.test(entry.name) && !/\.(?:test|spec)\./.test(entry.name)) files.push(entryPath);
+    }
+  };
+  visit(directory);
+  return files;
+}
+function apiRouteId(moduleId, moduleRoot, filePath) {
+  const relative = path.relative(path.join(moduleRoot, "api"), filePath).split(path.sep).join("/");
+  if (relative === "interceptors.ts" || relative === "openapi.ts") return null;
+  const withoutExtension = relative.replace(/\.tsx?$/, "");
+  const suffix = withoutExtension.endsWith("/route") ? withoutExtension.slice(0, -6) : withoutExtension;
+  return suffix && !suffix.includes("__tests__") ? `${moduleId.replace(/_/g, "-")}/${suffix}` : null;
+}
+function apiExtensionHostIds(moduleId, moduleRoot) {
+  const entityIds = /* @__PURE__ */ new Set();
+  const commandIds = /* @__PURE__ */ new Set();
+  const routeIds = /* @__PURE__ */ new Set();
+  for (const filePath of sourceFilesBelow(path.join(moduleRoot, "api"))) {
+    const routeId = apiRouteId(moduleId, moduleRoot, filePath);
+    if (routeId) routeIds.add(routeId);
+    const file = sourceFile(filePath);
+    if (!file) continue;
+    const context = buildStaticContext(file);
+    const visit = (node) => {
+      if (ts.isPropertyAssignment(node)) {
+        const name = propertyName(node.name);
+        if (name === "commandId") {
+          const id = stringValue(staticValue(node.initializer, context));
+          if (id) commandIds.add(id);
+        }
+        if (name === "enrichers") {
+          const config = staticValue(node.initializer, context);
+          const entityId = isStaticObject(config) ? stringValue(config.entityId) : void 0;
+          if (entityId) entityIds.add(entityId);
+        }
+      }
+      if (ts.isCallExpression(node) && ts.isIdentifier(node.expression) && node.expression.text === "validateCrudMutationGuard") {
+        const input = node.arguments[1] ? staticValue(node.arguments[1], context) : void 0;
+        const entityId = isStaticObject(input) ? stringValue(input.resourceKind) : void 0;
+        if (entityId) entityIds.add(entityId);
+      }
+      node.forEachChild(visit);
+    };
+    file.forEachChild(visit);
+  }
+  return {
+    entityIds: [...entityIds].sort((left, right) => left.localeCompare(right)),
+    commandIds: [...commandIds].sort((left, right) => left.localeCompare(right)),
+    routeIds: [...routeIds].sort((left, right) => left.localeCompare(right))
+  };
+}
+function moduleCommandIds(moduleRoot, apiCommandIds) {
+  const commandIds = new Set(apiCommandIds);
+  for (const filePath of sourceFilesBelow(path.join(moduleRoot, "commands"))) {
+    if (path.basename(filePath).replace(/\.(?:ts|tsx)$/, "") === "interceptors") continue;
+    for (const id of extractCommandIdsFromSource(filePath)) commandIds.add(id);
+  }
+  return [...commandIds].sort((left, right) => left.localeCompare(right));
+}
+function extractKnownApiRouteIds(moduleId, moduleRoot) {
+  return apiExtensionHostIds(moduleId, moduleRoot).routeIds;
+}
+function extractKnownCommandIds(moduleId, moduleRoot) {
+  const apiHosts = apiExtensionHostIds(moduleId, moduleRoot);
+  return moduleCommandIds(moduleRoot, apiHosts.commandIds);
+}
+function extractFactRefHosts(options) {
+  const hosts = [];
+  for (const entity of options.entities) {
+    hosts.push(factRefHost({
+      key: `entity.${entity.id}`,
+      id: entity.id,
+      moduleId: options.moduleId,
+      family: "entity",
+      capabilities: ["response-enricher", "query-enricher", "mutation-guard", "entity-extension"],
+      factSection: "entities",
+      activation: "host-opt-in",
+      scopeContract: "tenant-and-organization"
+    }));
+  }
+  for (const route of options.apiRoutes) {
+    hosts.push(factRefHost({
+      key: `api-route.${route.path}`,
+      id: route.path,
+      moduleId: options.moduleId,
+      family: "api-route",
+      capabilities: ["api-interceptor", "mutation-guard"],
+      factSection: "apiRoutes",
+      phases: ["before", "after"],
+      activation: "host-opt-in",
+      scopeContract: "request-auth-scope"
+    }));
+  }
+  for (const event of options.events) {
+    const capabilities = ["async-subscriber", "sync-subscriber"];
+    if (event.clientBroadcast) capabilities.push("browser-client");
+    if (event.portalBroadcast) capabilities.push("browser-portal");
+    hosts.push(factRefHost({
+      key: `event.${event.id}`,
+      id: event.id,
+      moduleId: options.moduleId,
+      family: "event",
+      capabilities,
+      factSection: "events",
+      scopeContract: "tenant-organization-and-audience"
+    }));
+  }
+  for (const entityId of options.searchEntities) {
+    const eventStem = entityId.replace(":", ".");
+    for (const phase of ["querying", "queried"]) {
+      hosts.push(factRefHost({
+        key: `query-lifecycle.${eventStem}.${phase}`,
+        id: `${eventStem}.${phase}`,
+        moduleId: options.moduleId,
+        family: "query-lifecycle",
+        capabilities: ["sync-subscriber"],
+        factSection: "searchEntities",
+        phases: phase === "querying" ? ["block", "query-transform"] : ["result-transform", "scope-reapply"],
+        activation: "caller-opt-in",
+        scopeContract: "tenant-and-organization-reapplied-after-result"
+      }));
+    }
+  }
+  const apiHosts = apiExtensionHostIds(options.moduleId, options.moduleRoot);
+  for (const entityId of apiHosts.entityIds) {
+    hosts.push(factRefHost({
+      key: `api-entity.${entityId}`,
+      id: entityId,
+      moduleId: options.moduleId,
+      family: "entity",
+      capabilities: ["response-enricher", "query-enricher", "mutation-guard"],
+      factSection: "apiRoutes",
+      activation: "host-opt-in",
+      scopeContract: "tenant-and-organization"
+    }));
+  }
+  return sortHosts([...new Map(hosts.map((host) => [`${host.family}:${host.id}`, host])).values()]);
+}
+function contributionBase(id, sourcePath, sourceSymbol) {
+  return {
+    id,
+    targets: [],
+    scopeContract: "tenant-and-organization",
+    source: { path: sourcePath, ...sourceSymbol ? { symbol: sourceSymbol } : {} }
+  };
+}
+function extractInjectionTable(options) {
+  const filePath = conventionPath(options.moduleRoot, "widgets/injection-table.ts");
+  if (!filePath) return [];
+  const table = readRootObject(filePath, "injectionTable");
+  if (!table) return [];
+  const sourcePath = portablePath(options.moduleRoot, options.sourceRoot, filePath);
+  const facts = [];
+  for (const targetId of Object.keys(table).sort((left, right) => left.localeCompare(right))) {
+    const entries = table[targetId];
+    if (!Array.isArray(entries)) continue;
+    for (const entry of entries) {
+      if (!isStaticObject(entry)) continue;
+      const widgetId = stringValue(entry.widgetId);
+      if (!widgetId) continue;
+      const payload = targetId.endsWith(":columns") ? "column" : targetId.endsWith(":row-actions") ? "row-action" : targetId.endsWith(":bulk-actions") ? "bulk-action" : targetId.endsWith(":filters") ? "filter" : targetId.endsWith(":fields") ? "field" : "render";
+      const base = contributionBase(`${widgetId}@${targetId}`, sourcePath, "injectionTable");
+      const shared = {
+        ...base,
+        targets: [target(targetId)],
+        features: strings(entry.features),
+        placement: numberValue(entry.priority) !== void 0 ? { priority: numberValue(entry.priority) } : void 0
+      };
+      if (targetId.startsWith("data-table:")) {
+        facts.push({
+          ...shared,
+          kind: "data-table",
+          details: {
+            payload: payload === "field" ? "render" : payload,
+            tableId: targetId.replace(/^data-table:/, "").replace(/:(?:columns|row-actions|bulk-actions|filters|toolbar|header|footer|search-trailing)$/, ""),
+            executionGuard: strings(entry.features).length > 0 ? "both" : "host"
+          }
+        });
+      } else if (targetId.startsWith("crud-form:")) {
+        facts.push({
+          ...shared,
+          kind: "crud-form",
+          details: {
+            payload: payload === "field" ? "field" : "render",
+            entityId: targetId.replace(/^crud-form:/, "").replace(/:(?:fields|header)$/, ""),
+            requestHeaderCapability: payload === "field"
+          }
+        });
+      } else {
+        facts.push({
+          ...shared,
+          kind: "widget",
+          details: {
+            payload: "render",
+            registryKey: widgetId,
+            executionGuard: strings(entry.features).length > 0 ? "both" : "host"
+          }
+        });
+      }
+    }
+  }
+  return facts;
+}
+function extractObjectConvention(options) {
+  const filePath = conventionPath(options.module.moduleRoot, options.relativePath);
+  if (!filePath) return [];
+  const exportNames = [options.exportName, ...options.exportAliases ?? []];
+  const entries = exportNames.reduce((found, exportName) => found.length > 0 ? found : readConventionObjectArray(filePath, exportName), []);
+  const sourcePath = portablePath(options.module.moduleRoot, options.module.sourceRoot, filePath);
+  return entries.flatMap((entry, index) => options.build(entry, sourcePath, index) ?? []);
+}
+function methodPhases(entry, map) {
+  return map.flatMap(([property, phase]) => entry[property] === true ? [phase] : []);
+}
+function extractEnrichers(options) {
+  return extractObjectConvention({
+    module: options,
+    relativePath: "data/enrichers.ts",
+    exportName: "enrichers",
+    build(entry, sourcePath, index) {
+      const id = stringValue(entry.id) ?? `${options.moduleId}.enricher.${index}`;
+      const targetEntity = stringValue(entry.targetEntity);
+      if (!targetEntity) return null;
+      const timeoutMs = numberValue(entry.timeout) ?? 2e3;
+      const queryEngine = isStaticObject(entry.queryEngine) ? entry.queryEngine : null;
+      const surfaces = [entry.enrichMany === true ? "list" : null, entry.enrichOne === true ? "detail" : null].filter((value) => value !== null);
+      const base = contributionBase(id, sourcePath, id);
+      return {
+        ...base,
+        kind: "response-enricher",
+        targets: [openTarget(targetEntity)],
+        features: strings(entry.features),
+        phases: surfaces,
+        activation: queryEngine ? "caller-opt-in" : "host-opt-in",
+        roundTripId: `${targetEntity}:read`,
+        details: {
+          targetEntity,
+          surfaces,
+          timeoutMs,
+          fallback: entry.fallback === void 0 ? "none" : "configured",
+          critical: booleanValue(entry.critical) ?? false,
+          cachePosture: "rerun-on-list-cache-hit",
+          ...queryEngine ? { queryEngine: {
+            engines: strings(queryEngine.engines),
+            applyOn: (strings(queryEngine.applyOn).length > 0 ? strings(queryEngine.applyOn) : ["list", "detail"]).filter((value) => value === "list" || value === "detail"),
+            activation: "caller-opt-in"
+          } } : {}
+        }
+      };
+    }
+  });
+}
+function extractApiInterceptors(options) {
+  return extractObjectConvention({
+    module: options,
+    relativePath: "api/interceptors.ts",
+    exportName: "interceptors",
+    build(entry, sourcePath, index) {
+      const id = stringValue(entry.id) ?? `${options.moduleId}.api-interceptor.${index}`;
+      const targetRoute = stringValue(entry.targetRoute);
+      if (!targetRoute) return null;
+      const phases = methodPhases(entry, [["before", "before"], ["after", "after"]]).filter((phase) => phase === "before" || phase === "after");
+      const methods = strings(entry.methods);
+      const base = contributionBase(id, sourcePath, id);
+      return {
+        ...base,
+        kind: "api-interceptor",
+        targets: [openTarget(targetRoute)],
+        phases,
+        features: strings(entry.features),
+        details: {
+          route: targetRoute,
+          methods,
+          phases,
+          activation: targetRoute.startsWith("/") ? "custom-route-bridge" : "crud-pipeline",
+          timeoutMs: numberValue(entry.timeout) ?? 2e3,
+          failurePosture: booleanValue(entry.critical) ? "fail-closed" : "fallback"
+        }
+      };
+    }
+  });
+}
+function extractCommandInterceptors(options) {
+  return extractObjectConvention({
+    module: options,
+    relativePath: "commands/interceptors.ts",
+    exportName: "interceptors",
+    build(entry, sourcePath, index) {
+      const id = stringValue(entry.id) ?? `${options.moduleId}.command-interceptor.${index}`;
+      const targetCommand = stringValue(entry.targetCommand);
+      if (!targetCommand) return null;
+      const phases = methodPhases(entry, [
+        ["beforeExecute", "before-execute"],
+        ["afterExecute", "after-execute"],
+        ["beforeUndo", "before-undo"],
+        ["afterUndo", "after-undo"]
+      ]).filter((phase) => phase === "before-execute" || phase === "after-execute" || phase === "before-undo" || phase === "after-undo");
+      const base = contributionBase(id, sourcePath, id);
+      return {
+        ...base,
+        kind: "command-interceptor",
+        targets: [openTarget(targetCommand)],
+        phases,
+        features: strings(entry.features),
+        details: { targetCommand, phases }
+      };
+    }
+  });
+}
+function extractGuards(options) {
+  return extractObjectConvention({
+    module: options,
+    relativePath: "data/guards.ts",
+    exportName: "guards",
+    build(entry, sourcePath, index) {
+      const id = stringValue(entry.id) ?? `${options.moduleId}.guard.${index}`;
+      const targetEntity = stringValue(entry.targetEntity);
+      if (!targetEntity) return null;
+      const operations = strings(entry.operations).filter((operation) => operation === "create" || operation === "update" || operation === "delete");
+      const capabilities = [entry.validate === true ? "block" : null, entry.validate === true ? "rewrite" : null, entry.afterSuccess === true ? "after-success" : null].filter((value) => value !== null);
+      const base = contributionBase(id, sourcePath, id);
+      return {
+        ...base,
+        kind: "mutation-guard",
+        targets: [openTarget(targetEntity)],
+        operations,
+        features: strings(entry.features),
+        roundTripId: `${targetEntity}:write`,
+        details: { entityId: targetEntity, operations, capabilities, optimisticLock: "preserved" }
+      };
+    }
+  });
+}
+function extractEntityExtensions(options) {
+  return extractObjectConvention({
+    module: options,
+    relativePath: "data/extensions.ts",
+    exportName: "entityExtensions",
+    exportAliases: ["extensions"],
+    build(entry, sourcePath, index) {
+      const baseEntity = stringValue(entry.base);
+      const extensionEntity = stringValue(entry.extension);
+      const join = isStaticObject(entry.join) ? entry.join : null;
+      if (!baseEntity || !extensionEntity || !join) return null;
+      const id = `${options.moduleId}.entity-extension.${index}:${baseEntity}->${extensionEntity}`;
+      const contribution = contributionBase(id, sourcePath, "extensions");
+      return {
+        ...contribution,
+        kind: "entity-extension",
+        targets: [openTarget(baseEntity)],
+        details: {
+          hostEntityId: baseEntity,
+          extensionEntityId: extensionEntity,
+          linkId: `${stringValue(join.baseKey) ?? "id"}:${stringValue(join.extensionKey) ?? "id"}`,
+          scopeContract: "tenant-and-organization",
+          orphanContract: booleanValue(entry.required) ? "required" : "optional"
+        }
+      };
+    }
+  });
+}
+function extractSubscribers(options) {
+  const directory = path.join(options.moduleRoot, "subscribers");
+  if (!fs.existsSync(directory)) return [];
+  const facts = [];
+  for (const entry of fs.readdirSync(directory, { withFileTypes: true }).sort((left, right) => left.name.localeCompare(right.name))) {
+    if (!entry.isFile() || !/\.(?:ts|tsx)$/.test(entry.name) || /\.(?:test|spec)\./.test(entry.name)) continue;
+    const filePath = path.join(directory, entry.name);
+    const metadata = readRootObject(filePath, "metadata");
+    if (!metadata) continue;
+    const event = stringValue(metadata.event);
+    if (!event) continue;
+    const subscriberId = stringValue(metadata.id) ?? `${options.moduleId}:${entry.name.replace(/\.tsx?$/, "")}`;
+    const persistent = booleanValue(metadata.persistent) ?? false;
+    const sync = booleanValue(metadata.sync) ?? !persistent;
+    const contribution = contributionBase(subscriberId, portablePath(options.moduleRoot, options.sourceRoot, filePath), "metadata");
+    facts.push({
+      ...contribution,
+      kind: "subscriber",
+      targets: [openTarget(event)],
+      phases: sync ? ["before-or-after"] : ["async-delivery"],
+      details: {
+        event,
+        subscriberId,
+        persistent,
+        sync,
+        ...numberValue(metadata.priority) !== void 0 ? { priority: numberValue(metadata.priority) } : {}
+      }
+    });
+  }
+  return facts;
+}
+function extractBrowserReactions(options) {
+  return options.events.flatMap((event) => {
+    const transports = [event.clientBroadcast ? "client" : null, event.portalBroadcast ? "portal" : null].filter((value) => value !== null);
+    if (transports.length === 0) return [];
+    const contribution = contributionBase(`${event.id}.browser`, path.posix.join(options.sourceRoot, "events.ts"), "events");
+    return [{
+      ...contribution,
+      kind: "browser-reaction",
+      targets: [factTarget(event.id, "events")],
+      details: {
+        transports,
+        hooks: transports.flatMap((transport) => transport === "client" ? ["useAppEvent", "useOperationProgress"] : ["usePortalAppEvent"]),
+        audienceScopeContract: "tenant-organization-user-role-and-customer"
+      }
+    }];
+  });
+}
+function extractNotificationReactions(options) {
+  return extractObjectConvention({
+    module: options,
+    relativePath: "notifications.handlers.ts",
+    exportName: "notificationHandlers",
+    build(entry, sourcePath, index) {
+      const notificationType = stringValue(entry.notificationType);
+      if (!notificationType) return null;
+      const id = stringValue(entry.id) ?? `${options.moduleId}.notification-handler.${index}`;
+      const contribution = contributionBase(id, sourcePath, "notificationHandlers");
+      return {
+        ...contribution,
+        kind: "browser-reaction",
+        targets: [factTarget(notificationType, "notifications")],
+        features: strings(entry.features),
+        placement: numberValue(entry.priority) !== void 0 ? { priority: numberValue(entry.priority) } : void 0,
+        details: {
+          transports: ["notification-effect"],
+          hooks: ["useNotificationEffect"],
+          audienceScopeContract: "tenant-organization-user-role-and-customer"
+        }
+      };
+    }
+  });
+}
+function extractComponentOverrides(options) {
+  return extractObjectConvention({
+    module: options,
+    relativePath: "widgets/components.ts",
+    exportName: "componentOverrides",
+    build(entry, sourcePath, index) {
+      const targetDefinition = isStaticObject(entry.target) ? entry.target : null;
+      const handle = targetDefinition ? stringValue(targetDefinition.componentId) : void 0;
+      if (!handle) return null;
+      const mode = entry.wrapper !== void 0 ? "wrapper" : entry.props !== void 0 ? "props" : "replace";
+      const id = `${options.moduleId}.component-override.${index}:${handle}`;
+      const contribution = contributionBase(id, sourcePath, "componentOverrides");
+      return {
+        ...contribution,
+        kind: "component-override",
+        targets: [target(handle)],
+        details: {
+          handle,
+          mode,
+          propsContract: stringValue(entry.propsContract) ?? "component-props-schema"
+        }
+      };
+    }
+  });
+}
+function extractSpecializedRegistries(options) {
+  const facts = [];
+  const add = (id, registry, sourcePath, specialistRoute, symbol = id) => {
+    const contributionId = `${registry}:${id}`;
+    const contribution = contributionBase(contributionId, sourcePath, id);
+    const fact = {
+      ...contribution,
+      kind: "specialized-registry",
+      targets: [factTarget(id, specialistRoute)],
+      source: { path: sourcePath, symbol },
+      details: { registry, registryId: id, specialistRoute }
+    };
+    const existingIndex = facts.findIndex((entry) => entry.id === contributionId);
+    if (existingIndex >= 0) facts[existingIndex] = fact;
+    else facts.push(fact);
+  };
+  for (const id of options.notifications ?? []) add(id, "notification", path.posix.join(options.sourceRoot, "notifications.ts"), "notifications");
+  for (const id of options.searchEntities) add(id, "search", path.posix.join(options.sourceRoot, "search.ts"), "search");
+  for (const tool of options.aiTools ?? []) add(tool.name, "ai", tool.sourcePath, "aiTools");
+  for (const agent of options.aiAgents ?? []) add(agent.id, "ai", agent.sourcePath, "aiAgents");
+  const vectorPath = conventionPath(options.moduleRoot, "vector.ts");
+  if (vectorPath) {
+    const vectorConfig = readRootObject(vectorPath, "vectorConfig") ?? readRootObject(vectorPath, "config");
+    const sourcePath = portablePath(options.moduleRoot, options.sourceRoot, vectorPath);
+    if (vectorConfig && Array.isArray(vectorConfig.entities)) {
+      for (const entity of vectorConfig.entities) {
+        if (!isStaticObject(entity)) continue;
+        const entityId = stringValue(entity.entityId);
+        if (entityId) add(entityId, "vector", sourcePath, "vector", "vectorConfig");
+      }
+    }
+  }
+  const integrationPath = conventionPath(options.moduleRoot, "integration.ts");
+  if (integrationPath) {
+    const integration = readRootObject(integrationPath, "integration");
+    const sourcePath = portablePath(options.moduleRoot, options.sourceRoot, integrationPath);
+    const integrationId = integration ? stringValue(integration.id) : void 0;
+    if (integrationId) add(integrationId, "integration", sourcePath, "integrations", "integration");
+    const providerKey = integration ? stringValue(integration.providerKey) : void 0;
+    const category = integration ? stringValue(integration.category) : void 0;
+    const categoryRegistry = category === "payment" ? "payment" : category === "shipping" ? "shipping" : category === "currency" ? "currency" : null;
+    if (providerKey && categoryRegistry) {
+      const specialistRoute = categoryRegistry === "payment" ? "paymentGateways" : categoryRegistry === "shipping" ? "shippingCarriers" : "currencies";
+      add(providerKey, categoryRegistry, sourcePath, specialistRoute, "integration.providerKey");
+    }
+  }
+  const workflowsPath = conventionPath(options.moduleRoot, "workflows.ts");
+  if (workflowsPath) {
+    const config = readRootObject(workflowsPath, "workflowsConfig");
+    const sourcePath = portablePath(options.moduleRoot, options.sourceRoot, workflowsPath);
+    if (config && Array.isArray(config.workflows)) {
+      for (const workflow of config.workflows) {
+        if (!isStaticObject(workflow)) continue;
+        const workflowId = stringValue(workflow.workflowId);
+        if (workflowId) add(workflowId, "workflow", sourcePath, "workflows", "workflowsConfig");
+      }
+    }
+  }
+  const diPath = conventionPath(options.moduleRoot, "di.ts");
+  if (diPath) {
+    const sourcePath = portablePath(options.moduleRoot, options.sourceRoot, diPath);
+    const registrations = readCallObjectArguments(diPath, /* @__PURE__ */ new Set([
+      "registerPaymentGatewayDescriptor",
+      "registerShippingAdapter",
+      "registerCurrencyProvider"
+    ]));
+    for (const registration of registrations) {
+      const registry = registration.callee === "registerPaymentGatewayDescriptor" ? "payment" : registration.callee === "registerShippingAdapter" ? "shipping" : "currency";
+      const registryId = stringValue(registration.value.providerKey) ?? stringValue(registration.value.key) ?? stringValue(registration.value.id);
+      if (!registryId) continue;
+      const specialistRoute = registry === "payment" ? "paymentGateways" : registry === "shipping" ? "shippingCarriers" : "currencies";
+      add(registryId, registry, sourcePath, specialistRoute, registration.callee);
+    }
+  }
+  const dashboardRoots = { appBase: path.join(options.moduleRoot, "__app__"), pkgBase: options.moduleRoot };
+  for (const widgetFile of scanModuleDir(dashboardRoots, SCAN_CONFIGS.dashboardWidgets)) {
+    const filePath = path.join(options.moduleRoot, "widgets", "dashboard", widgetFile.relPath);
+    const widget = readRootObject(filePath, "widget");
+    const metadata = widget && isStaticObject(widget.metadata) ? widget.metadata : null;
+    if (!metadata) continue;
+    const widgetId = stringValue(metadata.id);
+    if (!widgetId) continue;
+    const sourcePath = portablePath(options.moduleRoot, options.sourceRoot, filePath);
+    const contribution = contributionBase(`dashboard:${widgetId}`, sourcePath, "widget.metadata");
+    facts.push({
+      ...contribution,
+      kind: "widget",
+      targets: [target(`dashboard:${widgetId}`)],
+      features: strings(metadata.features),
+      details: {
+        payload: "dashboard",
+        registryKey: widgetId,
+        executionGuard: strings(metadata.features).length > 0 ? "both" : "host"
+      }
+    });
+  }
+  return facts;
+}
+function extractModuleExtensionFacts(options) {
+  const declared = extractDeclaredHosts(options);
+  const hosts = sortHosts([...declared.hosts, ...extractFactRefHosts(options)]);
+  const contributions = sortContributions([
+    ...extractInjectionTable(options),
+    ...extractEnrichers(options),
+    ...extractApiInterceptors(options),
+    ...extractCommandInterceptors(options),
+    ...extractGuards(options),
+    ...extractEntityExtensions(options),
+    ...extractSubscribers(options),
+    ...extractBrowserReactions(options),
+    ...extractNotificationReactions(options),
+    ...extractComponentOverrides(options),
+    ...extractSpecializedRegistries(options)
+  ]);
+  return { hosts, contributions, unresolved: declared.unresolved };
+}
+function patternMatches(pattern, targetId) {
+  const escaped = pattern.replace(/[.+?^${}()|[\]\\]/g, "\\$&").replace(/\\\{[^}]+\\\}/g, "[^:]+").replace(/\*/g, ".*");
+  return new RegExp(`^${escaped}$`).test(targetId);
+}
+function targetModuleId(targetId) {
+  const withoutPrefix = targetId.replace(/^(?:data-table|crud-form|detail|portal-page):/, "");
+  const match = /^([a-z][a-z0-9_]*)[.:]/.exec(withoutPrefix);
+  return match?.[1] ?? null;
+}
+function correlateExtensionTarget(targetFact, options) {
+  if (targetFact.resolution !== "unresolved") return targetFact;
+  const allHosts = Object.values(options.surfacesByModule).flatMap((surface) => surface.hosts);
+  if (targetFact.id.includes("*") || targetFact.id.includes("{")) {
+    const knownIds = [
+      ...allHosts.filter((host) => host.bound).map((host) => host.id),
+      ...options.entityIds,
+      ...options.eventIds,
+      ...options.apiRoutes,
+      ...options.commandIds ?? []
+    ];
+    if (targetFact.id === "*" || knownIds.some((knownId) => patternMatches(targetFact.id, knownId))) {
+      return { id: targetFact.id, resolution: "pattern" };
+    }
+  }
+  const exact = allHosts.find((host) => host.bound && (host.id === targetFact.id || host.aliases?.includes(targetFact.id) || host.family === "api-route" && host.id.endsWith(`/${targetFact.id}`)));
+  if (exact) {
+    return exact.source.kind === "fact-ref" ? factTarget(targetFact.id, exact.source.factSection, exact.source.factKey) : { id: targetFact.id, resolution: "exact" };
+  }
+  const patterned = allHosts.find((host) => host.bound && host.resolution === "pattern" && patternMatches(host.id, targetFact.id));
+  if (patterned) return { id: targetFact.id, resolution: "pattern" };
+  const framework = allFrameworkHosts().find((host) => patternMatches(host.id, targetFact.id)) ?? (FRAMEWORK_PREFIXES.some((prefix) => targetFact.id.startsWith(prefix)) ? FRAMEWORK_HOSTS[0] : void 0);
+  if (framework) return { id: targetFact.id, resolution: "framework" };
+  if (options.entityIds.has(targetFact.id)) {
+    return { id: targetFact.id, resolution: "fact-ref", factRef: { factSection: "entities", factKey: targetFact.id } };
+  }
+  if (options.eventIds.has(targetFact.id)) {
+    return { id: targetFact.id, resolution: "fact-ref", factRef: { factSection: "events", factKey: targetFact.id } };
+  }
+  if (options.commandIds?.has(targetFact.id)) {
+    return factTarget(targetFact.id, "commands");
+  }
+  const route = [...options.apiRoutes].find((apiRoute) => apiRoute === targetFact.id || apiRoute.endsWith(`/${targetFact.id}`));
+  if (route) return { id: targetFact.id, resolution: "fact-ref", factRef: { factSection: "apiRoutes", factKey: route } };
+  const ownerModule = targetModuleId(targetFact.id);
+  if (ownerModule && !options.surfacesByModule[ownerModule]) {
+    return { id: targetFact.id, resolution: "optional-external", optionalOwnerPackage: `module:${ownerModule}` };
+  }
+  if (ownerModule && options.contributingModuleId && ownerModule !== options.contributingModuleId) {
+    return { id: targetFact.id, resolution: "optional-external", optionalOwnerPackage: `module:${ownerModule}` };
+  }
+  return targetFact;
+}
+function correlateModuleExtensionFacts(options) {
+  const result = {};
+  for (const moduleId of Object.keys(options.surfacesByModule).sort((left, right) => left.localeCompare(right))) {
+    const surface = options.surfacesByModule[moduleId];
+    const unresolved = [...surface.unresolved];
+    const contributions = surface.contributions.map((contribution) => {
+      const targets = contribution.targets.map((entry) => correlateExtensionTarget(entry, {
+        ...options,
+        contributingModuleId: moduleId
+      }));
+      for (const entry of targets) {
+        if (entry.resolution !== "unresolved") continue;
+        unresolved.push({
+          key: `${contribution.id}:${entry.id}`,
+          source: contribution.source,
+          reason: "unresolved-first-party-target"
+        });
+      }
+      return { ...contribution, targets };
+    });
+    result[moduleId] = {
+      hosts: sortHosts([...surface.hosts]),
+      contributions: sortContributions(contributions),
+      unresolved: unresolved.sort((left, right) => left.key.localeCompare(right.key))
+    };
+  }
+  return result;
+}
+function assertNoUnresolvedExtensionTargets(surfacesByModule) {
+  const unresolved = 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));
+  if (unresolved.length > 0) {
+    throw new Error(`[module-facts] unresolved first-party extension targets: ${unresolved.join(", ")}`);
+  }
+}
+function getFrameworkExtensionHosts() {
+  return sortHosts(allFrameworkHosts().map((host) => ({
+    ...host,
+    capabilities: [...host.capabilities],
+    ...host.operations ? { operations: [...host.operations] } : {}
+  })));
+}
+function renderFrameworkExtensionPointsMarkdown() {
+  const rows = getFrameworkExtensionHosts().map(
+    (host) => `| ${host.id} | ${host.family} | ${[...host.capabilities, ...host.operations ?? []].join(", ")} | ${host.stability.toUpperCase()} |`
+  );
+  return [
+    "# Framework extension points (generated, do not edit)",
+    "",
+    "| ID / pattern | Family | Supports | Stability |",
+    "|---|---|---|---|",
+    ...rows,
+    ""
+  ].join("\n");
+}
+export {
+  assertNoUnresolvedExtensionTargets,
+  correlateExtensionTarget,
+  correlateModuleExtensionFacts,
+  extractKnownApiRouteIds,
+  extractKnownCommandIds,
+  extractModuleExtensionFacts,
+  getFrameworkExtensionHosts,
+  readConventionObjectArray,
+  renderFrameworkExtensionPointsMarkdown
+};
+//# sourceMappingURL=module-extension-facts.js.map