@open-mercato/cli 0.6.8-develop.6931.1.4a1e1c786b → 0.6.8-develop.6941.1.3c26284542

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

@@ -1,6 +1,25 @@
+import { createHash } from "node:crypto";
 import fs from "node:fs";
 import path from "node:path";
 import ts from "typescript-js";
+import {
+  COMPONENT_OVERRIDE_MODES,
+  CRUD_FORM_EXTENSION_SURFACE_KEYS,
+  CRUD_FORM_LIFECYCLE_PHASES,
+  CRUD_FORM_OPERATIONS,
+  DATA_TABLE_EXTENSION_SURFACE_KEYS,
+  EXTENSION_HOST_ACTIVATIONS,
+  EXTENSION_HOST_CAPABILITIES,
+  EXTENSION_HOST_FAMILIES,
+  MODULE_EXTENSION_ACTIVATION_KINDS,
+  MODULE_EXTENSION_CONTRIBUTION_KINDS,
+  MODULE_EXTENSION_HOST_RESOLUTIONS,
+  MODULE_EXTENSION_RESOLUTIONS,
+  MODULE_EXTENSION_TARGET_KINDS,
+  MODULE_EXTENSION_TARGET_RESOLUTIONS,
+  MODULE_EXTENSION_UNRESOLVED_REASONS,
+  MODULE_SPECIALIZED_REGISTRIES
+} from "@open-mercato/shared/modules/widgets/extension-points";
 import { toSnake } from "../utils.js";
 import { extractCommandIdsFromSource } from "./module-registry.js";
 import { MODULE_CODE_EXTENSIONS } from "./scanner.js";
@@ -16,9 +35,55 @@ import {
   withModuleExtensionFactExtractionCache
 } from "./module-extension-facts.js";
 import {
+  ALL_OVERRIDE_DOMAINS,
+  MODULE_OVERRIDE_MODES,
+  MODULE_OVERRIDE_TARGET_DIAGNOSTIC_CODES,
+  MODULE_OVERRIDE_TARGET_NOTES,
   collectModuleOverrideTargets
 } from "./module-override-targets.js";
 import { buildFactSourceLookup } from "./module-fact-sources.js";
+import { appendLocalReferenceModuleSource } from "./module-facts-discovery.js";
+const MODULE_FACT_SOURCE_KINDS = [
+  "module-metadata",
+  "entity",
+  "event",
+  "acl-feature",
+  "api-route",
+  "di-registration",
+  "search",
+  "vector",
+  "notification",
+  "cli-command",
+  "backend-page",
+  "frontend-page",
+  "ai-tool",
+  "ai-agent",
+  "ai-extension",
+  "command",
+  "subscriber",
+  "worker",
+  "page-middleware",
+  "setup",
+  "encryption",
+  "custom-entity",
+  "integration",
+  "generator-plugin",
+  "extension-host",
+  "extension-contribution"
+];
+const MODULE_OWNED_CONTRACT_KINDS = [
+  "module-metadata",
+  "command",
+  "worker",
+  "page-middleware",
+  "setup",
+  "encryption",
+  "di-registration",
+  "custom-entity",
+  "ai-extension",
+  "generator-plugin"
+];
+const MODULE_FACT_DIAGNOSTIC_CODES = ["duplicate-source", "unresolved-static-contract"];
 function readSourceFile(filePath) {
   if (!fs.existsSync(filePath)) return null;
   const source = fs.readFileSync(filePath, "utf8");
@@ -79,42 +144,45 @@ 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;
   const sourceFile = readSourceFile(ceFilePath);
   if (!sourceFile) return result;
-  const readEntityId = (expression) => {
-    const current = unwrapExpression(expression);
-    if (ts.isStringLiteralLike(current)) {
-      return current.text.includes(":") ? current.text : void 0;
-    }
-    const readAccessPath = (candidate) => {
-      const access = unwrapExpression(candidate);
-      if (ts.isIdentifier(access)) return [access.text];
-      if (ts.isPropertyAccessExpression(access)) {
-        const parent = readAccessPath(access.expression);
-        return parent ? [...parent, access.name.text] : null;
-      }
-      if (ts.isElementAccessExpression(access) && access.argumentExpression) {
-        const parent = readAccessPath(access.expression);
-        const key = unwrapExpression(access.argumentExpression);
-        return parent && ts.isStringLiteralLike(key) ? [...parent, key.text] : null;
-      }
-      return null;
-    };
-    const accessPath = readAccessPath(current);
-    if (accessPath?.length === 3 && accessPath[0] === "E") {
-      return `${accessPath[1]}:${accessPath[2]}`;
-    }
-    return void 0;
-  };
   const visit = (node) => {
     if (ts.isObjectLiteralExpression(node)) {
       const initializer = getObjectPropertyInitializer(node, "id");
       if (initializer) {
-        const id = readEntityId(initializer);
-        if (id) result.add(id);
+        const id = resolveEntityIdReference(initializer);
+        if (id && id.includes(":")) result.add(id);
       }
     }
     node.forEachChild(visit);
@@ -163,8 +231,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;
@@ -454,15 +543,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;
 }
@@ -538,6 +637,15 @@ function listSourceFilesRecursive(directory) {
 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);
@@ -973,6 +1081,34 @@ function readResolvedStringProperty(objectLiteral, propertyName, initializers) {
   }
   return void 0;
 }
+function readImportedStringIdentifier(sourceFile, sourcePath, identifier) {
+  for (const statement of sourceFile.statements) {
+    if (!ts.isImportDeclaration(statement) || !ts.isStringLiteralLike(statement.moduleSpecifier)) continue;
+    const importClause = statement.importClause;
+    const bindings = importClause?.namedBindings;
+    if (!bindings || !ts.isNamedImports(bindings)) continue;
+    const imported = bindings.elements.find((element) => element.name.text === identifier);
+    if (!imported) continue;
+    const request = statement.moduleSpecifier.text;
+    if (!request.startsWith(".")) return void 0;
+    const basePath = path.resolve(path.dirname(sourcePath), request);
+    const candidates = [
+      `${basePath}.ts`,
+      `${basePath}.tsx`,
+      path.join(basePath, "index.ts"),
+      path.join(basePath, "index.tsx")
+    ];
+    const importedPath = candidates.find((candidate) => fs.existsSync(candidate));
+    if (!importedPath) return void 0;
+    const importedSource = readSourceFile(importedPath);
+    if (!importedSource) return void 0;
+    const exportName = imported.propertyName?.text ?? imported.name.text;
+    const declaration = importedSource.statements.filter(ts.isVariableStatement).flatMap((variable) => [...variable.declarationList.declarations]).find((candidate) => ts.isIdentifier(candidate.name) && candidate.name.text === exportName);
+    const initializer = declaration?.initializer ? unwrapExpression(declaration.initializer) : null;
+    return initializer && ts.isStringLiteralLike(initializer) ? initializer.text : void 0;
+  }
+  return void 0;
+}
 function extractWorkerContracts(moduleId, moduleRoot, sourceRoot) {
   const workersRoot = path.join(moduleRoot, "workers");
   if (!fs.existsSync(workersRoot)) return { facts: [], unresolved: [] };
@@ -988,7 +1124,8 @@ function extractWorkerContracts(moduleId, moduleRoot, sourceRoot) {
     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);
+    const queueInitializer = getObjectPropertyInitializer(metadata, "queue");
+    const queue = readResolvedStringProperty(metadata, "queue", initializers) ?? (queueInitializer && ts.isIdentifier(unwrapExpression(queueInitializer)) ? readImportedStringIdentifier(sourceFile, filePath, unwrapExpression(queueInitializer).text) : void 0);
     if (!hasQueueProperty) {
       unresolved.push({ code: "unresolved-static-contract", kind: "worker", id: workerId, source });
       continue;
@@ -1318,7 +1455,7 @@ function extractModuleFacts(options) {
   if (!moduleRoot) {
     throw new Error(`[internal] extractModuleFacts requires moduleRoot or coreSrcRoot for module "${moduleId}"`);
   }
-  const sourceRoot = toPortableSourceRoot(moduleId, sourcePackage);
+  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");
@@ -1370,7 +1507,8 @@ function extractModuleFacts(options) {
     searchEntities,
     notifications,
     aiTools,
-    aiAgents
+    aiAgents,
+    factsContractVersion: options.factsContractVersion ?? 2
   });
   const indexSourcePath = portableOf(indexFilePath);
   const diSourcePath = portableOf(diFilePath);
@@ -1556,6 +1694,7 @@ function extractModuleFacts(options) {
     sourcePackage,
     sourceVersion,
     sourceRoot,
+    ...options.sourceKind === "local-reference" ? { sourceKind: options.sourceKind } : {},
     entities,
     events,
     aclFeatures,
@@ -1630,12 +1769,17 @@ ${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) {
@@ -1865,13 +2009,24 @@ ${EMPTY_SECTION_MARKER}`;
   });
   return ["## Exact override targets", "", header, divider, ...rows].join("\n");
 }
-function renderModuleFactsMarkdown(facts) {
+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 sections = [
+  const header = facts.sourceKind === "local-reference" && referenceProjection ? renderReferenceProjectionHeader(facts, referenceProjection) : [
     `# ${facts.module} \u2014 module facts (generated, do not edit)`,
     renderVersionStamp(facts.coreVersion, facts.sourcePackage, facts.sourceVersion),
-    `Source root: ${renderSourceLink(facts.sourceRoot)}`,
+    `Source root: ${renderSourceLink(facts.sourceRoot)}`
+  ];
+  const sections = [
+    ...header,
     "",
     renderEntitiesSection(facts.entities, lookup),
     "",
@@ -1946,6 +2101,7 @@ function toModuleFactsJsonEntry(facts) {
     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,
@@ -1985,10 +2141,169 @@ 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, propertyName) {
+  if (Array.isArray(value)) {
+    const items = value.map((item) => {
+      const canonical = canonicalizeFingerprintValue(item);
+      return { canonical, text: JSON.stringify(canonical) ?? "" };
+    });
+    if (propertyName === "path") return items.map((item) => item.canonical);
+    return items.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], 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,
+      factCoverage: activated.factCoverage ?? buildModuleFactCoverageLedger(),
+      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 factCoverage = buildModuleFactCoverageLedger();
   const sources = options.sources ? [...options.sources] : options.coreSrcRoot ? (options.moduleIds ?? []).map((moduleId) => ({
     moduleId,
     moduleRoot: path.join(options.coreSrcRoot, moduleId)
@@ -2004,7 +2319,10 @@ function extractAllModuleFactsWithCache(options) {
       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 } : {},
+      factsContractVersion: options.factsContractVersion ?? 2
     });
     factsByModule[source.moduleId] = facts;
     warnings.push(...facts.warnings);
@@ -2023,9 +2341,11 @@ function extractAllModuleFactsWithCache(options) {
       ...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)))
+    commandIds: new Set(sources.flatMap((source) => extractKnownCommandIds(source.moduleId, source.moduleRoot))),
+    factsContractVersion: options.factsContractVersion ?? 2
   });
-  assertNoUnresolvedExtensionTargets(correlated);
+  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))) {
@@ -2057,14 +2377,622 @@ function extractAllModuleFactsWithCache(options) {
       (entry) => `[module-facts] ${moduleId} ${entry.reason}: ${entry.key} (${entry.source.path})`
     ));
   }
-  return { factsByModule, markdownByModule, warnings, frameworkMarkdown: renderFrameworkExtensionPointsMarkdown() };
+  return {
+    factsByModule,
+    markdownByModule,
+    warnings,
+    frameworkMarkdown: renderFrameworkExtensionPointsMarkdown(),
+    unresolvedFirstPartyTargets,
+    factCoverage
+  };
+}
+const FACT_SOURCE_KIND_COVERAGE = {
+  "module-metadata": { value: "module-metadata", status: "emitted-example", note: "example/index.ts ModuleInfo export" },
+  entity: { value: "entity", status: "emitted-example", note: "example/data/entities.ts ORM entities" },
+  event: { value: "event", status: "emitted-example", note: "example/events.ts typed event definitions" },
+  "acl-feature": { value: "acl-feature", status: "emitted-example", note: "example/acl.ts RBAC features" },
+  "api-route": {
+    value: "api-route",
+    status: "emitted-example",
+    note: "example/api/**/route.ts; route facts are read from the generated module registry, not from module source",
+    requiresGeneratedRegistry: true
+  },
+  "di-registration": { value: "di-registration", status: "emitted-example", note: "example/di.ts Awilix container.register" },
+  search: { value: "search", status: "emitted-example", note: "example/search.ts indexed entity declaration" },
+  vector: {
+    value: "vector",
+    status: "emitted-example",
+    note: "example/vector.ts deterministic Todo vector declaration"
+  },
+  notification: { value: "notification", status: "emitted-example", note: "example/notifications.ts notification types" },
+  "cli-command": { value: "cli-command", status: "emitted-example", note: "example/cli.ts module commands" },
+  "backend-page": { value: "backend-page", status: "emitted-example", note: "example/backend/**/page.tsx admin pages" },
+  "frontend-page": { value: "frontend-page", status: "emitted-example", note: "example/frontend/**/page.tsx portal pages" },
+  "ai-tool": { value: "ai-tool", status: "emitted-example", note: "example/ai-tools.ts defineAiTool declarations" },
+  "ai-agent": { value: "ai-agent", status: "emitted-example", note: "example/ai-agents.ts defineAiAgent declarations" },
+  "ai-extension": { value: "ai-extension", status: "emitted-example", note: "example AI agent/tool override and extension records" },
+  command: { value: "command", status: "emitted-example", note: "example/commands/todos.ts command handlers" },
+  subscriber: { value: "subscriber", status: "emitted-example", note: "example/subscribers/*.ts event subscribers" },
+  worker: { value: "worker", status: "emitted-example", note: "example/workers/*.ts queue workers" },
+  "page-middleware": { value: "page-middleware", status: "emitted-example", note: "example/backend/middleware.ts page guard" },
+  setup: { value: "setup", status: "emitted-example", note: "example/setup.ts tenant setup hooks" },
+  encryption: { value: "encryption", status: "emitted-example", note: "example/encryption.ts field encryption map" },
+  "custom-entity": { value: "custom-entity", status: "emitted-example", note: "example/ce.ts custom entity and field DSL" },
+  integration: { value: "integration", status: "emitted-example", note: "example/lib/mock-*-adapter.ts integration registrations" },
+  "generator-plugin": {
+    value: "generator-plugin",
+    status: "emitted-example",
+    note: "example/generators.ts deterministic reference-index generator plugin"
+  },
+  "extension-host": { value: "extension-host", status: "emitted-example", note: "example/extension-points.ts declared hosts" },
+  "extension-contribution": {
+    value: "extension-contribution",
+    status: "emitted-example",
+    note: "example widget, DataTable, CrudForm, interceptor and enricher contributions"
+  }
+};
+const OWNED_CONTRACT_KIND_COVERAGE = {
+  "module-metadata": { value: "module-metadata", status: "emitted-example", note: "ModuleInfo owned contract" },
+  command: { value: "command", status: "emitted-example", note: "example/commands/todos.ts" },
+  worker: { value: "worker", status: "emitted-example", note: "example/workers/*.ts" },
+  "page-middleware": { value: "page-middleware", status: "emitted-example", note: "example/backend/middleware.ts" },
+  setup: { value: "setup", status: "emitted-example", note: "example/setup.ts" },
+  encryption: { value: "encryption", status: "emitted-example", note: "example/encryption.ts" },
+  "di-registration": {
+    value: "di-registration",
+    status: "emitted-example",
+    note: "example/di.ts scoped Todo summary cache service consumed by a route"
+  },
+  "custom-entity": { value: "custom-entity", status: "emitted-example", note: "example/ce.ts" },
+  "ai-extension": { value: "ai-extension", status: "emitted-example", note: "example AI override/extension record" },
+  "generator-plugin": {
+    value: "generator-plugin",
+    status: "emitted-example",
+    note: "example/generators.ts deterministic reference-index generator plugin"
+  }
+};
+const OVERRIDE_DOMAIN_COVERAGE = {
+  ai: { value: "ai", status: "emitted-example", note: "ai.agents, ai.tools and ai.extensions targets" },
+  routes: { value: "routes", status: "emitted-example", note: "routes.api and routes.pages targets" },
+  events: { value: "events", status: "emitted-example", note: "events.subscribers targets" },
+  workers: { value: "workers", status: "emitted-example", note: "workers targets" },
+  widgets: { value: "widgets", status: "emitted-example", note: "widgets.injection, .components and .dashboard targets" },
+  notifications: { value: "notifications", status: "emitted-example", note: "notifications.types and notifications.handlers targets" },
+  interceptors: { value: "interceptors", status: "emitted-example", note: "API interceptor targets" },
+  commandInterceptors: { value: "commandInterceptors", status: "emitted-example", note: "command interceptor targets" },
+  enrichers: { value: "enrichers", status: "emitted-example", note: "response enricher targets" },
+  guards: { value: "guards", status: "emitted-example", note: "page-middleware guard targets" },
+  cli: { value: "cli", status: "emitted-example", note: "CLI command targets" },
+  setup: { value: "setup", status: "emitted-example", note: "setup hook and default-role targets" },
+  acl: { value: "acl", status: "emitted-example", note: "acl.features targets" },
+  di: { value: "di", status: "emitted-example", note: "DI token targets" },
+  encryption: { value: "encryption", status: "emitted-example", note: "encryption.maps targets" },
+  nav: {
+    value: "nav",
+    status: "framework-only",
+    note: "nav.groupOrder is an app-level framework setting; no module target is ever emitted for it"
+  }
+};
+const OVERRIDE_MODE_COVERAGE = {
+  "disable-replace": {
+    value: "disable-replace",
+    status: "emitted-example",
+    note: "default mode for most example override hosts"
+  },
+  replace: { value: "replace", status: "emitted-example", note: "the setup host replaces wholesale" },
+  additive: { value: "additive", status: "emitted-example", note: "the ai.extensions host merges additively" }
+};
+const OVERRIDE_NOTE_COVERAGE = {
+  "safe-metadata-only": {
+    value: "safe-metadata-only",
+    status: "emitted-example",
+    note: "emitted on the metadata-only override target"
+  },
+  "page-middleware-not-mutation-guard": {
+    value: "page-middleware-not-mutation-guard",
+    status: "emitted-example",
+    note: "emitted on the guards target so a page guard is not read as a mutation guard"
+  }
+};
+const OVERRIDE_DIAGNOSTIC_COVERAGE = {
+  "missing-owned-fact": {
+    value: "missing-owned-fact",
+    status: "currently-unbound",
+    note: "reserved by the spec's closed diagnostic set; no adapter emits it today, so not even a broken fixture can produce it"
+  },
+  "missing-source": {
+    value: "missing-source",
+    status: "negative-fixture",
+    note: "a fact whose provenance cannot be proven yields this and no target; activated canonical output emits none"
+  },
+  "unsupported-dynamic-key": {
+    value: "unsupported-dynamic-key",
+    status: "negative-fixture",
+    note: "a key the runtime cannot address yields this and no target; activated canonical output emits none"
+  },
+  "unknown-framework-domain": {
+    value: "unknown-framework-domain",
+    status: "negative-fixture",
+    note: "the framework catalog does not describe the dotted host at all"
+  },
+  "unknown-framework-mode": {
+    value: "unknown-framework-mode",
+    status: "negative-fixture",
+    note: "the framework catalog describes the host but names an operation that is not a public mode"
+  }
+};
+const CONTRIBUTION_KIND_COVERAGE = {
+  widget: { value: "widget", status: "emitted-example", note: "example widget injection and dashboard registrations" },
+  "data-table": { value: "data-table", status: "emitted-example", note: "example DataTable extension entries" },
+  "crud-form": { value: "crud-form", status: "emitted-example", note: "example CrudForm field and lifecycle entries" },
+  "component-override": { value: "component-override", status: "emitted-example", note: "example replace, wrapper and props component entries" },
+  "response-enricher": { value: "response-enricher", status: "emitted-example", note: "example customer priority response enricher" },
+  "api-interceptor": { value: "api-interceptor", status: "emitted-example", note: "example CRUD API interceptor entries" },
+  "command-interceptor": { value: "command-interceptor", status: "emitted-example", note: "example command interceptor entries" },
+  "mutation-guard": { value: "mutation-guard", status: "emitted-example", note: "example Todo mutation guard" },
+  "entity-extension": { value: "entity-extension", status: "emitted-example", note: "example customer entity extension" },
+  subscriber: { value: "subscriber", status: "emitted-example", note: "example synchronous and asynchronous subscribers" },
+  "browser-reaction": { value: "browser-reaction", status: "emitted-example", note: "example client, portal and notification reactions" },
+  "specialized-registry": { value: "specialized-registry", status: "emitted-example", note: "example notification, search, AI and mock adapter registries" },
+  "module-override": { value: "module-override", status: "catalog-only", note: "app-owned configuration is not an outgoing module contribution" }
+};
+const ACTIVATION_KIND_COVERAGE = {
+  "crud-response-enricher": { value: "crud-response-enricher", status: "currently-unbound", note: "example contributes a response enricher but owns no CRUD response call site for its customer target" },
+  "query-enricher": { value: "query-enricher", status: "currently-unbound", note: "example contributes a query enricher but owns no query-engine call site for its customer target" },
+  "mutation-guard": { value: "mutation-guard", status: "emitted-example", note: "Todo mutation-guard route bridge" },
+  "api-interceptor-bridge": { value: "api-interceptor-bridge", status: "emitted-example", note: "CRUD route interceptor pipeline" },
+  "command-interceptor-bridge": { value: "command-interceptor-bridge", status: "emitted-example", note: "exact Todo command bus target" },
+  "widget-injection-consumer": { value: "widget-injection-consumer", status: "emitted-example", note: "bound injection host consumer" },
+  "component-extension-consumer": { value: "component-extension-consumer", status: "emitted-example", note: "bound component handle consumer" },
+  "dashboard-host-consumer": { value: "dashboard-host-consumer", status: "emitted-example", note: "framework dashboard registry consumer" }
+};
+const HOST_FAMILY_COVERAGE = {
+  generic: { value: "generic", status: "emitted-example", note: "example headless injection host" },
+  menu: { value: "menu", status: "framework-only", note: "framework menu hosts consumed by example widgets" },
+  "data-table": { value: "data-table", status: "emitted-example", note: "example Todo DataTable host" },
+  "crud-form": { value: "crud-form", status: "emitted-example", note: "example Todo CrudForm host" },
+  detail: { value: "detail", status: "framework-only", note: "framework detail hosts consumed by example widgets" },
+  "portal-page": { value: "portal-page", status: "framework-only", note: "framework portal host consumed by example widgets" },
+  "component-handle": { value: "component-handle", status: "emitted-example", note: "example replaceable component host" },
+  entity: { value: "entity", status: "emitted-example", note: "example entity fact-reference hosts" },
+  "api-route": { value: "api-route", status: "framework-only", note: "API route hosts are owned by the target module and consumed by example interceptors" },
+  command: { value: "command", status: "framework-only", note: "command hosts are owned by the target module and consumed by example interceptors" },
+  event: { value: "event", status: "emitted-example", note: "example event fact-reference hosts" },
+  "query-lifecycle": { value: "query-lifecycle", status: "emitted-example", note: "example Todo query lifecycle hosts" },
+  dashboard: { value: "dashboard", status: "framework-only", note: "framework dashboard host consumed by example widgets" },
+  notification: { value: "notification", status: "framework-only", note: "framework notification host consumed by the example registry" },
+  integration: { value: "integration", status: "framework-only", note: "framework integration detail host consumed by example widgets" },
+  "specialized-registry": { value: "specialized-registry", status: "framework-only", note: "framework-owned specialist registries accept example entries" },
+  "module-override": { value: "module-override", status: "framework-only", note: "framework override catalog owns these hosts" }
+};
+const HOST_CAPABILITY_COVERAGE = {
+  "render-widget": { value: "render-widget", status: "emitted-example", note: "example render widget host and contributions" },
+  "headless-widget": { value: "headless-widget", status: "currently-unbound", note: "injection-table facts do not yet distinguish headless widget payloads" },
+  "menu-item": { value: "menu-item", status: "currently-unbound", note: "injection-table facts do not yet distinguish menu item payloads" },
+  "column-widget": { value: "column-widget", status: "emitted-example", note: "example DataTable column host" },
+  "row-action": { value: "row-action", status: "emitted-example", note: "example DataTable row-action host" },
+  "bulk-action": { value: "bulk-action", status: "emitted-example", note: "example DataTable bulk-action host" },
+  "filter-widget": { value: "filter-widget", status: "emitted-example", note: "example DataTable filter host" },
+  "toolbar-widget": { value: "toolbar-widget", status: "emitted-example", note: "example DataTable toolbar host" },
+  "field-widget": { value: "field-widget", status: "emitted-example", note: "example CrudForm field host" },
+  "lifecycle-handler": { value: "lifecycle-handler", status: "emitted-example", note: "example CrudForm lifecycle host" },
+  "component-replacement": { value: "component-replacement", status: "emitted-example", note: "example replaceable DataTable, CrudForm and component hosts" },
+  "response-enricher": { value: "response-enricher", status: "emitted-example", note: "example entity enricher host" },
+  "query-enricher": { value: "query-enricher", status: "emitted-example", note: "example query-enricher host" },
+  "api-interceptor": { value: "api-interceptor", status: "emitted-example", note: "example API interceptor contribution and route bridge" },
+  "command-interceptor": { value: "command-interceptor", status: "emitted-example", note: "example command interceptor and exact command owner" },
+  "mutation-guard": { value: "mutation-guard", status: "emitted-example", note: "example entity mutation guard host" },
+  "entity-extension": { value: "entity-extension", status: "emitted-example", note: "example entity extension host" },
+  "async-subscriber": { value: "async-subscriber", status: "emitted-example", note: "example event subscriber host" },
+  "sync-subscriber": { value: "sync-subscriber", status: "emitted-example", note: "example synchronous event subscriber host" },
+  "browser-client": { value: "browser-client", status: "emitted-example", note: "example client-broadcast event host" },
+  "browser-portal": { value: "browser-portal", status: "emitted-example", note: "example portal-broadcast event host" },
+  "registry-contribution": { value: "registry-contribution", status: "emitted-example", note: "example specialized registry contributions" },
+  "module-override": { value: "module-override", status: "framework-only", note: "framework override hosts; app configuration is not a contribution" }
+};
+const HOST_ACTIVATION_COVERAGE = {
+  always: { value: "always", status: "emitted-example", note: "always-active example declarations" },
+  "host-opt-in": { value: "host-opt-in", status: "emitted-example", note: "example entity extension and response-enricher hosts" },
+  "caller-opt-in": { value: "caller-opt-in", status: "emitted-example", note: "example query lifecycle and query enricher" },
+  "feature-gated": { value: "feature-gated", status: "currently-unbound", note: "feature requirements are emitted but are not a distinct activation value" }
+};
+const TARGET_KIND_COVERAGE = {
+  module: { value: "module", status: "emitted-example", note: "example module-scoped registry target" },
+  entity: { value: "entity", status: "emitted-example", note: "example entity extension, enricher and guard targets" },
+  "api-route": { value: "api-route", status: "emitted-example", note: "example API interceptor targets" },
+  command: { value: "command", status: "emitted-example", note: "example exact and wildcard command targets" },
+  "widget-spot": { value: "widget-spot", status: "emitted-example", note: "example injection targets" },
+  component: { value: "component", status: "emitted-example", note: "example component override targets" },
+  event: { value: "event", status: "emitted-example", note: "example subscriber targets" },
+  notification: { value: "notification", status: "emitted-example", note: "example notification registry target" },
+  wildcard: { value: "wildcard", status: "emitted-example", note: "example wildcard subscriber and interceptor targets" }
+};
+const HOST_RESOLUTION_COVERAGE = {
+  exact: { value: "exact", status: "emitted-example", note: "example exact declared hosts" },
+  pattern: { value: "pattern", status: "emitted-example", note: "example patterned host surfaces" },
+  framework: { value: "framework", status: "framework-only", note: "framework catalog host identity" },
+  "fact-ref": { value: "fact-ref", status: "emitted-example", note: "example entity, event and query fact-reference hosts" }
+};
+const TARGET_RESOLUTION_COVERAGE = {
+  exact: { value: "exact", status: "emitted-example", note: "example exact target correlation" },
+  pattern: { value: "pattern", status: "emitted-example", note: "example wildcard and patterned target correlation" },
+  framework: { value: "framework", status: "emitted-example", note: "example contribution to a framework host" },
+  "fact-ref": { value: "fact-ref", status: "emitted-example", note: "example contribution to a generated fact owner" },
+  "optional-external": { value: "optional-external", status: "emitted-example", note: "example optional module target remains fail-soft" },
+  unresolved: { value: "unresolved", status: "negative-fixture", note: "only malformed targets remain unresolved" }
+};
+const TOPOLOGY_RESOLUTION_COVERAGE = {
+  bound: { value: "bound", status: "emitted-example", note: "example contribution reaches a verified runtime activation" },
+  "capability-only": { value: "capability-only", status: "emitted-example", note: "declaration-backed capability without a separate caller activation" },
+  "optional-target-missing": { value: "optional-target-missing", status: "emitted-example", note: "optional external target absent from the selected module set" },
+  wildcard: { value: "wildcard", status: "emitted-example", note: "wildcard contribution resolves against selected targets" },
+  unresolved: { value: "unresolved", status: "negative-fixture", note: "only malformed first-party targets remain unresolved" }
+};
+const SPECIALIZED_REGISTRY_COVERAGE = {
+  notification: { value: "notification", status: "emitted-example", note: "example notification type registry" },
+  integration: { value: "integration", status: "emitted-example", note: "example credential-free integration bundle identity" },
+  search: { value: "search", status: "emitted-example", note: "example Todo search registry" },
+  vector: { value: "vector", status: "emitted-example", note: "example deterministic Todo vector registry" },
+  ai: { value: "ai", status: "emitted-example", note: "example AI tool and agent registries" },
+  payment: { value: "payment", status: "emitted-example", note: "example mock payment descriptors" },
+  shipping: { value: "shipping", status: "emitted-example", note: "example mock shipping registry identity" },
+  currency: { value: "currency", status: "emitted-example", note: "example deterministic currency provider identity" },
+  workflow: { value: "workflow", status: "emitted-example", note: "example event-triggered Todo workflow identity" }
+};
+const COMPONENT_MODE_COVERAGE = {
+  replace: { value: "replace", status: "emitted-example", note: "example replacement component" },
+  wrapper: { value: "wrapper", status: "emitted-example", note: "example decorating wrapper component" },
+  props: { value: "props", status: "emitted-example", note: "example props-transform component" }
+};
+const FACT_DIAGNOSTIC_COVERAGE = {
+  "duplicate-source": { value: "duplicate-source", status: "negative-fixture", note: "duplicate provenance fixture; canonical output emits none" },
+  "unresolved-static-contract": { value: "unresolved-static-contract", status: "negative-fixture", note: "dynamic contract fixture; canonical output emits none" }
+};
+const UNRESOLVED_REASON_COVERAGE = {
+  "unclassified-binding": { value: "unclassified-binding", status: "negative-fixture", note: "malformed extension declaration fixture" },
+  "unbound-declaration": { value: "unbound-declaration", status: "negative-fixture", note: "declared host without a real caller fixture" },
+  "dynamic-without-pattern": { value: "dynamic-without-pattern", status: "negative-fixture", note: "dynamic host without a declared pattern fixture" },
+  "unresolved-first-party-target": { value: "unresolved-first-party-target", status: "negative-fixture", note: "broken first-party target fixture" }
+};
+const DATA_TABLE_SURFACE_COVERAGE = {
+  header: { value: "header", status: "emitted-example", note: "bound Todo table header" },
+  footer: { value: "footer", status: "emitted-example", note: "bound Todo table footer" },
+  toolbar: { value: "toolbar", status: "emitted-example", note: "bound Todo table toolbar" },
+  searchTrailing: { value: "searchTrailing", status: "emitted-example", note: "bound Todo table search trailing surface" },
+  columns: { value: "columns", status: "emitted-example", note: "bound Todo table columns" },
+  rowActions: { value: "rowActions", status: "emitted-example", note: "bound Todo table row actions" },
+  bulkActions: { value: "bulkActions", status: "emitted-example", note: "bound Todo table bulk actions" },
+  filters: { value: "filters", status: "emitted-example", note: "bound Todo table filters" },
+  replacement: { value: "replacement", status: "emitted-example", note: "bound Todo table replacement" },
+  emptyState: { value: "emptyState", status: "currently-unbound", note: "catalog-declared DataTable surface has no runtime host" }
+};
+const CRUD_FORM_SURFACE_COVERAGE = {
+  base: { value: "base", status: "emitted-example", note: "bound Todo form base" },
+  header: { value: "header", status: "emitted-example", note: "bound Todo form header" },
+  fields: { value: "fields", status: "emitted-example", note: "bound Todo form fields" },
+  replacement: { value: "replacement", status: "emitted-example", note: "bound Todo form replacement" },
+  beforeFields: { value: "beforeFields", status: "currently-unbound", note: "catalog-declared CrudForm surface has no runtime host" },
+  afterFields: { value: "afterFields", status: "currently-unbound", note: "catalog-declared CrudForm surface has no runtime host" },
+  footer: { value: "footer", status: "currently-unbound", note: "catalog-declared CrudForm surface has no runtime host" },
+  sidebar: { value: "sidebar", status: "currently-unbound", note: "catalog-declared CrudForm surface has no runtime host" },
+  group: { value: "group", status: "currently-unbound", note: "catalog-declared CrudForm surface has no runtime host" },
+  fieldBefore: { value: "fieldBefore", status: "currently-unbound", note: "catalog-declared CrudForm surface has no runtime host" },
+  fieldAfter: { value: "fieldAfter", status: "currently-unbound", note: "catalog-declared CrudForm surface has no runtime host" }
+};
+const CRUD_FORM_LIFECYCLE_COVERAGE = {
+  transformValidation: { value: "transformValidation", status: "emitted-example", note: "example Todo form lifecycle transformValidation" },
+  transformDisplayData: { value: "transformDisplayData", status: "emitted-example", note: "example Todo form lifecycle transformDisplayData" },
+  onBeforeNavigate: { value: "onBeforeNavigate", status: "emitted-example", note: "example Todo form lifecycle onBeforeNavigate" },
+  onAppEvent: { value: "onAppEvent", status: "emitted-example", note: "example Todo form lifecycle onAppEvent" },
+  onVisibilityChange: { value: "onVisibilityChange", status: "emitted-example", note: "example Todo form lifecycle onVisibilityChange" },
+  onBeforeDelete: { value: "onBeforeDelete", status: "emitted-example", note: "example Todo form lifecycle onBeforeDelete" },
+  onDelete: { value: "onDelete", status: "emitted-example", note: "example Todo form lifecycle onDelete" },
+  onAfterDelete: { value: "onAfterDelete", status: "emitted-example", note: "example Todo form lifecycle onAfterDelete" },
+  onDeleteError: { value: "onDeleteError", status: "emitted-example", note: "example Todo form lifecycle onDeleteError" },
+  onFieldChange: { value: "onFieldChange", status: "emitted-example", note: "example Todo form lifecycle onFieldChange" },
+  transformFormData: { value: "transformFormData", status: "emitted-example", note: "example Todo form lifecycle transformFormData" },
+  onBeforeSave: { value: "onBeforeSave", status: "emitted-example", note: "example Todo form lifecycle onBeforeSave" },
+  onSave: { value: "onSave", status: "emitted-example", note: "example Todo form lifecycle onSave" },
+  onAfterSave: { value: "onAfterSave", status: "emitted-example", note: "example Todo form lifecycle onAfterSave" }
+};
+const CRUD_FORM_OPERATION_COVERAGE = {
+  create: { value: "create", status: "emitted-example", note: "example Todo create lifecycle" },
+  update: { value: "update", status: "currently-unbound", note: "example lifecycle contribution is currently registered for create only" },
+  delete: { value: "delete", status: "currently-unbound", note: "example lifecycle contribution is currently registered for create only" }
+};
+function buildCoverageFamily(family, enumSource, values, coverage) {
+  const rows = [];
+  const missing = [];
+  for (const value of values) {
+    const row = coverage[value];
+    if (!row) {
+      missing.push(value);
+      continue;
+    }
+    rows.push(row);
+  }
+  if (missing.length > 0) {
+    throw new Error(
+      `[module-facts] factCoverage family "${family}" has no row for: ${missing.join(", ")}. Add an explicit classification instead of leaving the value unclassified.`
+    );
+  }
+  const extra = Object.keys(coverage).filter((value) => !values.includes(value));
+  if (extra.length > 0) {
+    throw new Error(
+      `[module-facts] factCoverage family "${family}" classifies values absent from the enum: ${extra.join(", ")}.`
+    );
+  }
+  return { family, enumSource, rows };
+}
+function buildModuleFactCoverageLedger() {
+  return [
+    buildCoverageFamily(
+      "ModuleFactSourceKind",
+      "packages/cli/src/lib/generators/module-facts.ts#MODULE_FACT_SOURCE_KINDS",
+      MODULE_FACT_SOURCE_KINDS,
+      FACT_SOURCE_KIND_COVERAGE
+    ),
+    buildCoverageFamily(
+      "ModuleOwnedContractKind",
+      "packages/cli/src/lib/generators/module-facts.ts#MODULE_OWNED_CONTRACT_KINDS",
+      MODULE_OWNED_CONTRACT_KINDS,
+      OWNED_CONTRACT_KIND_COVERAGE
+    ),
+    buildCoverageFamily(
+      "ModuleOverrideDomain",
+      "packages/cli/src/lib/generators/module-override-targets.ts#ALL_OVERRIDE_DOMAINS",
+      ALL_OVERRIDE_DOMAINS,
+      OVERRIDE_DOMAIN_COVERAGE
+    ),
+    buildCoverageFamily(
+      "ModuleOverrideMode",
+      "packages/cli/src/lib/generators/module-override-targets.ts#MODULE_OVERRIDE_MODES",
+      MODULE_OVERRIDE_MODES,
+      OVERRIDE_MODE_COVERAGE
+    ),
+    buildCoverageFamily(
+      "ModuleOverrideTargetNote",
+      "packages/cli/src/lib/generators/module-override-targets.ts#MODULE_OVERRIDE_TARGET_NOTES",
+      MODULE_OVERRIDE_TARGET_NOTES,
+      OVERRIDE_NOTE_COVERAGE
+    ),
+    buildCoverageFamily(
+      "ModuleOverrideTargetDiagnosticCode",
+      "packages/cli/src/lib/generators/module-override-targets.ts#MODULE_OVERRIDE_TARGET_DIAGNOSTIC_CODES",
+      MODULE_OVERRIDE_TARGET_DIAGNOSTIC_CODES,
+      OVERRIDE_DIAGNOSTIC_COVERAGE
+    ),
+    buildCoverageFamily(
+      "ModuleExtensionContributionKind",
+      "packages/shared/src/modules/widgets/extension-points.ts#MODULE_EXTENSION_CONTRIBUTION_KINDS",
+      MODULE_EXTENSION_CONTRIBUTION_KINDS,
+      CONTRIBUTION_KIND_COVERAGE
+    ),
+    buildCoverageFamily(
+      "ModuleExtensionActivationKind",
+      "packages/shared/src/modules/widgets/extension-points.ts#MODULE_EXTENSION_ACTIVATION_KINDS",
+      MODULE_EXTENSION_ACTIVATION_KINDS,
+      ACTIVATION_KIND_COVERAGE
+    ),
+    buildCoverageFamily(
+      "ExtensionHostFamily",
+      "packages/shared/src/modules/widgets/extension-points.ts#EXTENSION_HOST_FAMILIES",
+      EXTENSION_HOST_FAMILIES,
+      HOST_FAMILY_COVERAGE
+    ),
+    buildCoverageFamily(
+      "ExtensionHostCapability",
+      "packages/shared/src/modules/widgets/extension-points.ts#EXTENSION_HOST_CAPABILITIES",
+      EXTENSION_HOST_CAPABILITIES,
+      HOST_CAPABILITY_COVERAGE
+    ),
+    buildCoverageFamily(
+      "ExtensionHostActivation",
+      "packages/shared/src/modules/widgets/extension-points.ts#EXTENSION_HOST_ACTIVATIONS",
+      EXTENSION_HOST_ACTIVATIONS,
+      HOST_ACTIVATION_COVERAGE
+    ),
+    buildCoverageFamily(
+      "ModuleExtensionTargetKind",
+      "packages/shared/src/modules/widgets/extension-points.ts#MODULE_EXTENSION_TARGET_KINDS",
+      MODULE_EXTENSION_TARGET_KINDS,
+      TARGET_KIND_COVERAGE
+    ),
+    buildCoverageFamily(
+      "ModuleExtensionHostResolution",
+      "packages/shared/src/modules/widgets/extension-points.ts#MODULE_EXTENSION_HOST_RESOLUTIONS",
+      MODULE_EXTENSION_HOST_RESOLUTIONS,
+      HOST_RESOLUTION_COVERAGE
+    ),
+    buildCoverageFamily(
+      "ModuleExtensionTargetResolution",
+      "packages/shared/src/modules/widgets/extension-points.ts#MODULE_EXTENSION_TARGET_RESOLUTIONS",
+      MODULE_EXTENSION_TARGET_RESOLUTIONS,
+      TARGET_RESOLUTION_COVERAGE
+    ),
+    buildCoverageFamily(
+      "ModuleExtensionResolution",
+      "packages/shared/src/modules/widgets/extension-points.ts#MODULE_EXTENSION_RESOLUTIONS",
+      MODULE_EXTENSION_RESOLUTIONS,
+      TOPOLOGY_RESOLUTION_COVERAGE
+    ),
+    buildCoverageFamily(
+      "SpecializedRegistry",
+      "packages/shared/src/modules/widgets/extension-points.ts#MODULE_SPECIALIZED_REGISTRIES",
+      MODULE_SPECIALIZED_REGISTRIES,
+      SPECIALIZED_REGISTRY_COVERAGE
+    ),
+    buildCoverageFamily(
+      "ComponentOverrideMode",
+      "packages/shared/src/modules/widgets/extension-points.ts#COMPONENT_OVERRIDE_MODES",
+      COMPONENT_OVERRIDE_MODES,
+      COMPONENT_MODE_COVERAGE
+    ),
+    buildCoverageFamily(
+      "ModuleFactDiagnosticCode",
+      "packages/cli/src/lib/generators/module-facts.ts#MODULE_FACT_DIAGNOSTIC_CODES",
+      MODULE_FACT_DIAGNOSTIC_CODES,
+      FACT_DIAGNOSTIC_COVERAGE
+    ),
+    buildCoverageFamily(
+      "ModuleExtensionUnresolvedReason",
+      "packages/shared/src/modules/widgets/extension-points.ts#MODULE_EXTENSION_UNRESOLVED_REASONS",
+      MODULE_EXTENSION_UNRESOLVED_REASONS,
+      UNRESOLVED_REASON_COVERAGE
+    ),
+    buildCoverageFamily(
+      "DataTableExtensionSurface",
+      "packages/shared/src/modules/widgets/extension-points.ts#DATA_TABLE_EXTENSION_SURFACE_KEYS",
+      DATA_TABLE_EXTENSION_SURFACE_KEYS,
+      DATA_TABLE_SURFACE_COVERAGE
+    ),
+    buildCoverageFamily(
+      "CrudFormExtensionSurface",
+      "packages/shared/src/modules/widgets/extension-points.ts#CRUD_FORM_EXTENSION_SURFACE_KEYS",
+      CRUD_FORM_EXTENSION_SURFACE_KEYS,
+      CRUD_FORM_SURFACE_COVERAGE
+    ),
+    buildCoverageFamily(
+      "CrudFormLifecyclePhase",
+      "packages/shared/src/modules/widgets/extension-points.ts#CRUD_FORM_LIFECYCLE_PHASES",
+      CRUD_FORM_LIFECYCLE_PHASES,
+      CRUD_FORM_LIFECYCLE_COVERAGE
+    ),
+    buildCoverageFamily(
+      "CrudFormOperation",
+      "packages/shared/src/modules/widgets/extension-points.ts#CRUD_FORM_OPERATIONS",
+      CRUD_FORM_OPERATIONS,
+      CRUD_FORM_OPERATION_COVERAGE
+    )
+  ];
+}
+function countModuleFactCoverage(facts) {
+  const increment = (counts, value) => {
+    counts[value] = (counts[value] ?? 0) + 1;
+  };
+  const factSourceKind = {};
+  for (const entry of facts.factSources ?? []) {
+    increment(factSourceKind, entry.kind);
+  }
+  const ownedContractKind = {};
+  for (const [kind, list] of Object.entries(facts.ownedContracts ?? {})) {
+    ownedContractKind[kind] = (list ?? []).length;
+  }
+  const overrideDomain = {};
+  const overrideMode = {};
+  const overrideNote = {};
+  for (const target of facts.overrideTargets ?? []) {
+    overrideDomain[target.domain] = (overrideDomain[target.domain] ?? 0) + 1;
+    for (const mode of target.modes) overrideMode[mode] = (overrideMode[mode] ?? 0) + 1;
+    for (const note of target.notes ?? []) overrideNote[note] = (overrideNote[note] ?? 0) + 1;
+  }
+  const overrideDiagnosticCode = {};
+  for (const diagnostic of facts.overrideTargetDiagnostics ?? []) {
+    increment(overrideDiagnosticCode, diagnostic.code);
+  }
+  const contributionKind = {};
+  const activationKind = {};
+  const hostFamily = {};
+  const hostCapability = {};
+  const hostActivation = {};
+  const targetKind = {};
+  const hostResolution = {};
+  const targetResolution = {};
+  const topologyResolution = {};
+  const specializedRegistry = {};
+  const componentMode = {};
+  const factDiagnosticCode = {};
+  const unresolvedReason = {};
+  const dataTableSurface = {};
+  const crudFormSurface = {};
+  const crudFormLifecycle = {};
+  const crudFormOperation = {};
+  const surfaces = facts.extensionSurfaces;
+  for (const host of surfaces?.hosts ?? []) {
+    increment(hostFamily, host.family);
+    increment(hostResolution, host.resolution);
+    increment(hostActivation, host.activation ?? "always");
+    for (const capability of host.capabilities) increment(hostCapability, capability);
+    for (const phase of host.phases ?? []) increment(crudFormLifecycle, phase);
+    for (const operation of host.operations ?? []) increment(crudFormOperation, operation);
+    const [owner, surface] = host.key.split(".");
+    if (owner === "todosTable" && surface) increment(dataTableSurface, surface);
+    if (owner === "todoForm" && surface) increment(crudFormSurface, surface);
+  }
+  for (const contribution of surfaces?.contributions ?? []) {
+    increment(contributionKind, contribution.kind);
+    increment(hostActivation, contribution.activation ?? "always");
+    for (const target of contribution.targets) increment(targetResolution, target.resolution);
+    for (const operation of contribution.operations ?? []) increment(crudFormOperation, operation);
+    if (contribution.kind === "specialized-registry") increment(specializedRegistry, contribution.details.registry);
+    if (contribution.kind === "component-override") increment(componentMode, contribution.details.mode);
+    if (contribution.kind === "widget") {
+      if (contribution.details.payload === "headless") increment(hostCapability, "headless-widget");
+      if (contribution.details.payload === "menu") increment(hostCapability, "menu-item");
+      if (contribution.details.payload === "dashboard" || contribution.details.payload === "notification" || contribution.details.payload === "integration") {
+        increment(hostCapability, "registry-contribution");
+      }
+    }
+    if (contribution.kind === "api-interceptor") increment(hostCapability, "api-interceptor");
+    if (contribution.kind === "command-interceptor") increment(hostCapability, "command-interceptor");
+  }
+  for (const activation of surfaces?.activations ?? []) increment(activationKind, activation.kind);
+  for (const resolution of surfaces?.contributionResolutions ?? []) {
+    increment(targetKind, resolution.target.kind);
+    increment(topologyResolution, resolution.resolution);
+    for (const id of resolution.activationIds) {
+      const kind = MODULE_EXTENSION_ACTIVATION_KINDS.find((candidate) => id.endsWith(`:${candidate}`));
+      if (kind) increment(activationKind, kind);
+    }
+  }
+  for (const diagnostic of facts.factDiagnostics ?? []) increment(factDiagnosticCode, diagnostic.code);
+  for (const unresolved of surfaces?.unresolved ?? []) increment(unresolvedReason, unresolved.reason);
+  return {
+    ModuleFactSourceKind: factSourceKind,
+    ModuleOwnedContractKind: ownedContractKind,
+    ModuleOverrideDomain: overrideDomain,
+    ModuleOverrideMode: overrideMode,
+    ModuleOverrideTargetNote: overrideNote,
+    ModuleOverrideTargetDiagnosticCode: overrideDiagnosticCode,
+    ModuleExtensionContributionKind: contributionKind,
+    ModuleExtensionActivationKind: activationKind,
+    ExtensionHostFamily: hostFamily,
+    ExtensionHostCapability: hostCapability,
+    ExtensionHostActivation: hostActivation,
+    ModuleExtensionTargetKind: targetKind,
+    ModuleExtensionHostResolution: hostResolution,
+    ModuleExtensionTargetResolution: targetResolution,
+    ModuleExtensionResolution: topologyResolution,
+    SpecializedRegistry: specializedRegistry,
+    ComponentOverrideMode: componentMode,
+    ModuleFactDiagnosticCode: factDiagnosticCode,
+    ModuleExtensionUnresolvedReason: unresolvedReason,
+    DataTableExtensionSurface: dataTableSurface,
+    CrudFormExtensionSurface: crudFormSurface,
+    CrudFormLifecyclePhase: crudFormLifecycle,
+    CrudFormOperation: crudFormOperation
+  };
 }
 export {
+  MODULE_FACT_DIAGNOSTIC_CODES,
+  MODULE_FACT_SOURCE_KINDS,
+  MODULE_OWNED_CONTRACT_KINDS,
+  assertPackageModuleFactsOnly,
+  assertPortableSourceRoot,
+  buildCoverageFamily,
+  buildModuleFactCoverageLedger,
   buildModuleFactsJsonObject,
+  collectUnresolvedFirstPartyTargets,
+  computeModuleSourceFingerprint,
+  computeModuleTaxonomyFingerprint,
+  countModuleFactCoverage,
   extractAllModuleFacts,
+  extractLocalReferenceModuleFacts,
   extractModuleFacts,
+  isExactSourceFilePath,
   renderModuleFactsJson,
   renderModuleFactsMarkdown,
+  renderReferenceModuleFactsJson,
   toModuleFactsJsonEntry
 };
 //# sourceMappingURL=module-facts.js.map