@open-mercato/cli 0.6.7 → 0.6.8-develop.6875.1.871a4afc94

package/src/lib/generators/__tests__/module-extension-facts.test.ts

@@ -0,0 +1,404 @@
+import fs from 'node:fs'
+import os from 'node:os'
+import path from 'node:path'
+import {
+  assertNoUnresolvedExtensionTargets,
+  correlateModuleExtensionFacts,
+  extractModuleExtensionFacts,
+  getFrameworkExtensionHosts,
+  renderFrameworkExtensionPointsMarkdown,
+} from '../module-extension-facts'
+import type { ModuleFactsJsonEntry } from '../module-facts'
+
+function write(root: string, relativePath: string, source: string): void {
+  const filePath = path.join(root, relativePath)
+  fs.mkdirSync(path.dirname(filePath), { recursive: true })
+  fs.writeFileSync(filePath, source)
+}
+
+describe('module extension facts', () => {
+  let moduleRoot: string
+
+  beforeEach(() => {
+    moduleRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'module-extension-facts-'))
+  })
+
+  afterEach(() => {
+    fs.rmSync(moduleRoot, { recursive: true, force: true })
+  })
+
+  it('expands declared host families and preserves fact references and browser transports', () => {
+    write(moduleRoot, 'extension-points.ts', `
+      import { defineModuleExtensionPoints, dataTableExtensionHost, crudFormExtensionHost, injectionExtensionHost } from 'x'
+      export const extensionPoints = defineModuleExtensionPoints({
+        moduleId: 'alpha',
+        hosts: {
+          records: dataTableExtensionHost({ tableId: 'alpha.records.list', baseSpotId: 'data-table:alpha.records', source: 'Records.tsx' }),
+          editor: crudFormExtensionHost({ entityId: 'alpha.record', source: 'Edit.tsx' }),
+          detail: injectionExtensionHost({
+            family: 'detail', pattern: 'detail:alpha.record:{recordId}',
+            parameters: { recordId: { source: 'record.id', pattern: '^[a-z]+$' } },
+            supported: ['render-widget'], source: 'Detail.tsx', fallbacks: ['detail:alpha.record'],
+          }),
+        },
+      })
+    `)
+    write(moduleRoot, 'Records.tsx', 'export const tableId = extensionPoints.hosts.records.tableId')
+    write(moduleRoot, 'Edit.tsx', 'export const entityId = extensionPoints.hosts.editor.entityId')
+    write(moduleRoot, 'Detail.tsx', 'export const spotId = extensionPoints.hosts.detail.pattern')
+
+    const facts = extractModuleExtensionFacts({
+      moduleId: 'alpha',
+      moduleRoot,
+      sourceRoot: 'node_modules/pkg/src/modules/alpha',
+      entities: [{ id: 'alpha:record' }],
+      events: [{ id: 'alpha.record.updated', clientBroadcast: true, portalBroadcast: true }],
+      apiRoutes: [{ path: '/alpha/records', methods: ['GET', 'POST'] }],
+      searchEntities: ['alpha:record'],
+    })
+
+    expect(facts.hosts).toEqual(expect.arrayContaining([
+      expect.objectContaining({ id: 'data-table:alpha.records:header', bound: true }),
+      expect.objectContaining({ id: 'data-table:alpha.records.list:columns', capabilities: ['column-widget'] }),
+      expect.objectContaining({ id: 'data-table:alpha.records:empty-state', bound: false }),
+      expect.objectContaining({ id: 'crud-form:alpha.record:fields', capabilities: ['field-widget'] }),
+      expect.objectContaining({ id: 'detail:alpha.record:{recordId}', resolution: 'pattern' }),
+      expect.objectContaining({ id: 'alpha:record', resolution: 'fact-ref' }),
+      expect.objectContaining({
+        id: 'alpha.record.updated',
+        capabilities: ['async-subscriber', 'sync-subscriber', 'browser-client', 'browser-portal'],
+      }),
+      expect.objectContaining({ id: 'alpha.record.querying', activation: 'caller-opt-in' }),
+      expect.objectContaining({ id: 'alpha.record.queried', phases: ['result-transform', 'scope-reapply'] }),
+    ]))
+    expect(facts.unresolved).toEqual([])
+    const hostOrder = facts.hosts.map((host) => `${host.family}\u0000${host.id}`)
+    expect(hostOrder).toEqual([...hostOrder].sort((left, right) => left.localeCompare(right)))
+  })
+
+  it('extracts outgoing mechanisms with kind-specific contracts and correlates targets', () => {
+    write(moduleRoot, 'extension-points.ts', `
+      import { defineModuleExtensionPoints, dataTableExtensionHost } from 'x'
+      export const extensionPoints = defineModuleExtensionPoints({
+        moduleId: 'alpha', hosts: { records: dataTableExtensionHost({ tableId: 'alpha.records', source: 'Records.tsx' }) },
+      })
+    `)
+    write(moduleRoot, 'Records.tsx', 'export const tableId = extensionPoints.hosts.records.tableId')
+    write(moduleRoot, 'widgets/injection-table.ts', `
+      export const injectionTable = {
+        'data-table:alpha.records:columns': [{ widgetId: 'alpha.columns', priority: 20, features: ['alpha.view'] }],
+        'menu:backend.sidebar': [{ widgetId: 'alpha.menu' }],
+      }
+    `)
+    write(moduleRoot, 'data/enrichers.ts', `
+      const enricher = {
+        id: 'alpha.records.enricher', targetEntity: 'alpha:record', features: ['alpha.view'], timeout: 750,
+        fallback: {}, queryEngine: { enabled: true, engines: ['json'], applyOn: ['list'] },
+        async enrichOne() {}, async enrichMany() {},
+      }
+      export const enrichers = [enricher]
+    `)
+    write(moduleRoot, 'api/interceptors.ts', `
+      export const interceptors = [{
+        id: 'alpha.records.interceptor', targetRoute: 'alpha/records', methods: ['POST'],
+        async before() {}, async after() {},
+      }]
+    `)
+    write(moduleRoot, 'commands/interceptors.ts', `
+      export const interceptors = [{
+        id: 'alpha.records.command', targetCommand: 'alpha.records.update',
+        async beforeExecute() {}, async afterUndo() {},
+      }]
+    `)
+    write(moduleRoot, 'commands/update.ts', `
+      const updateCommand = { id: 'alpha.records.update', async execute() {} }
+      registerCommand(updateCommand)
+    `)
+    write(moduleRoot, 'data/guards.ts', `
+      const guard = { id: 'alpha.records.guard', targetEntity: 'alpha:record', operations: ['update', 'delete'], async validate() {}, async afterSuccess() {} }
+      export const guards = [guard]
+    `)
+    write(moduleRoot, 'data/extensions.ts', `
+      export const extensions = [{ base: 'alpha:record', extension: 'beta:record_meta', join: { baseKey: 'id', extensionKey: 'record_id' } }]
+    `)
+    write(moduleRoot, 'subscribers/updated.ts', `
+      export const metadata = { event: 'alpha.record.updated', id: 'alpha:record-updated', persistent: true, priority: 10 }
+    `)
+
+    const surface = extractModuleExtensionFacts({
+      moduleId: 'alpha',
+      moduleRoot,
+      sourceRoot: 'node_modules/pkg/src/modules/alpha',
+      entities: [{ id: 'alpha:record' }],
+      events: [{ id: 'alpha.record.updated', clientBroadcast: true }],
+      apiRoutes: [{ path: '/alpha/records', methods: ['POST'] }],
+      searchEntities: [],
+    })
+    const correlated = correlateModuleExtensionFacts({
+      surfacesByModule: { alpha: surface },
+      entityIds: new Set(['alpha:record']),
+      eventIds: new Set(['alpha.record.updated']),
+      apiRoutes: new Set(['/alpha/records']),
+      commandIds: new Set(['alpha.records.update']),
+    }).alpha
+
+    expect(correlated.contributions).toEqual(expect.arrayContaining([
+      expect.objectContaining({
+        id: 'alpha.records.enricher',
+        kind: 'response-enricher',
+        details: expect.objectContaining({
+          targetEntity: 'alpha:record', surfaces: ['list', 'detail'], timeoutMs: 750,
+          queryEngine: { engines: ['json'], applyOn: ['list'], activation: 'caller-opt-in' },
+        }),
+      }),
+      expect.objectContaining({
+        id: 'alpha.records.interceptor', kind: 'api-interceptor',
+        targets: [expect.objectContaining({
+          resolution: 'fact-ref',
+          factRef: { factSection: 'apiRoutes', factKey: '/alpha/records' },
+        })],
+        details: expect.objectContaining({ phases: ['before', 'after'] }),
+      }),
+      expect.objectContaining({
+        id: 'alpha.records.command',
+        targets: [expect.objectContaining({
+          factRef: { factSection: 'ownedContracts.command', factKey: 'alpha.records.update' },
+        })],
+        details: expect.objectContaining({ phases: ['before-execute', 'after-undo'] }),
+      }),
+      expect.objectContaining({ id: 'alpha.records.guard', details: expect.objectContaining({ optimisticLock: 'preserved' }) }),
+      expect.objectContaining({ kind: 'entity-extension', details: expect.objectContaining({ linkId: 'id:record_id' }) }),
+      expect.objectContaining({ id: 'alpha:record-updated', details: expect.objectContaining({ persistent: true, sync: false, priority: 10 }) }),
+      expect.objectContaining({ id: 'alpha.columns@data-table:alpha.records:columns', targets: [expect.objectContaining({ resolution: 'exact' })] }),
+      expect.objectContaining({ id: 'alpha.menu@menu:backend.sidebar', targets: [expect.objectContaining({ resolution: 'framework' })] }),
+      expect.objectContaining({ id: 'alpha.record.updated.browser', kind: 'browser-reaction' }),
+    ]))
+    expect(correlated.unresolved).toEqual([])
+    const contributionOrder = correlated.contributions.map((contribution) => `${contribution.kind}\u0000${contribution.id}`)
+    expect(contributionOrder).toEqual([...contributionOrder].sort((left, right) => left.localeCompare(right)))
+  })
+
+  it('renders a deterministic separate framework catalog', () => {
+    type ExtensionSurfacesAreOptional = {} extends Pick<ModuleFactsJsonEntry, 'extensionSurfaces'> ? true : false
+    const extensionSurfacesAreOptional: ExtensionSurfacesAreOptional = true
+    const first = renderFrameworkExtensionPointsMarkdown()
+    const second = renderFrameworkExtensionPointsMarkdown()
+    expect(second).toBe(first)
+    expect(first).toContain('# Framework extension points (generated, do not edit)')
+    expect(first).toContain('integrations.detail:{integrationId}')
+    expect(first).toContain('menu:backend.sidebar')
+    expect(extensionSurfacesAreOptional).toBe(true)
+  })
+
+  it('projects every wired unified override key with its supported mode', () => {
+    const overrides = getFrameworkExtensionHosts()
+      .filter((host) => host.family === 'module-override')
+      .map((host) => [host.id, host.operations?.[0]])
+
+    expect(overrides).toEqual([
+      ['module-override:acl.features', 'disable-replace'],
+      ['module-override:ai.agents', 'disable-replace'],
+      ['module-override:ai.extensions', 'additive'],
+      ['module-override:ai.tools', 'disable-replace'],
+      ['module-override:cli', 'disable-replace'],
+      ['module-override:commandInterceptors', 'disable-replace'],
+      ['module-override:di', 'disable-replace'],
+      ['module-override:encryption.maps', 'disable-replace'],
+      ['module-override:enrichers', 'disable-replace'],
+      ['module-override:events.subscribers', 'disable-replace'],
+      ['module-override:guards', 'disable-replace'],
+      ['module-override:interceptors', 'disable-replace'],
+      ['module-override:nav.groupOrder', 'additive'],
+      ['module-override:notifications.handlers', 'disable-replace'],
+      ['module-override:notifications.types', 'disable-replace'],
+      ['module-override:routes.api', 'disable-replace'],
+      ['module-override:routes.pages', 'disable-replace'],
+      ['module-override:setup', 'replace'],
+      ['module-override:widgets.components', 'disable-replace'],
+      ['module-override:widgets.dashboard', 'disable-replace'],
+      ['module-override:widgets.injection', 'disable-replace'],
+      ['module-override:workers', 'disable-replace'],
+    ])
+  })
+
+  it('projects dashboard, notification, integration, vector, provider, and workflow registries', () => {
+    write(moduleRoot, 'notifications.handlers.ts', `
+      export const notificationHandlers = [{
+        id: 'alpha.alert-toast', notificationType: 'alpha.alert', features: ['alpha.view'], priority: 80,
+        handle() {},
+      }]
+    `)
+    write(moduleRoot, 'integration.ts', `
+      export const integration = { id: 'alpha_gateway', category: 'payment', providerKey: 'alpha-pay' }
+      export const integrations = [integration]
+    `)
+    write(moduleRoot, 'vector.ts', `
+      export const vectorConfig = { entities: [{ entityId: 'alpha:record' }] }
+      export default vectorConfig
+    `)
+    write(moduleRoot, 'workflows.ts', `
+      const approval = defineWorkflow({ workflowId: 'alpha.approval', steps: [], transitions: [] })
+      export const workflowsConfig = createWorkflowsModuleConfig({ moduleId: 'alpha', workflows: [approval] })
+    `)
+    write(moduleRoot, 'di.ts', `
+      export function register() {
+        registerPaymentGatewayDescriptor({ providerKey: 'alpha-pay', label: 'Alpha Pay' })
+        registerShippingAdapter({ providerKey: 'alpha-ship' })
+        registerCurrencyProvider({ id: 'alpha-rates' })
+      }
+    `)
+    write(moduleRoot, 'widgets/dashboard/summary/widget.ts', `
+      const widget = { metadata: { id: 'alpha.dashboard.summary', features: ['alpha.view'] }, Widget() {} }
+      export default widget
+    `)
+
+    const facts = extractModuleExtensionFacts({
+      moduleId: 'alpha',
+      moduleRoot,
+      sourceRoot: 'node_modules/pkg/src/modules/alpha',
+      entities: [],
+      events: [],
+      apiRoutes: [],
+      searchEntities: ['alpha:record'],
+      notifications: ['alpha.alert'],
+      aiTools: [{ name: 'alpha_lookup', sourcePath: 'node_modules/pkg/src/modules/alpha/ai-tools.ts' }],
+      aiAgents: [{ id: 'alpha_agent', sourcePath: 'node_modules/pkg/src/modules/alpha/ai-agents.ts' }],
+    })
+
+    expect(facts.contributions).toEqual(expect.arrayContaining([
+      expect.objectContaining({
+        id: 'alpha.alert-toast',
+        kind: 'browser-reaction',
+        targets: [expect.objectContaining({ id: 'alpha.alert', resolution: 'fact-ref' })],
+        details: expect.objectContaining({ transports: ['notification-effect'], hooks: ['useNotificationEffect'] }),
+      }),
+      expect.objectContaining({ id: 'dashboard:alpha.dashboard.summary', kind: 'widget', details: expect.objectContaining({ payload: 'dashboard' }) }),
+      expect.objectContaining({ id: 'integration:alpha_gateway', details: expect.objectContaining({ specialistRoute: 'integrations' }) }),
+      expect.objectContaining({ id: 'notification:alpha.alert', details: expect.objectContaining({ registry: 'notification' }) }),
+      expect.objectContaining({ id: 'search:alpha:record', details: expect.objectContaining({ registry: 'search' }) }),
+      expect.objectContaining({ id: 'vector:alpha:record', details: expect.objectContaining({ registry: 'vector' }) }),
+      expect.objectContaining({ id: 'ai:alpha_lookup', details: expect.objectContaining({ specialistRoute: 'aiTools' }) }),
+      expect.objectContaining({ id: 'ai:alpha_agent', details: expect.objectContaining({ specialistRoute: 'aiAgents' }) }),
+      expect.objectContaining({ id: 'payment:alpha-pay', source: expect.objectContaining({ symbol: 'registerPaymentGatewayDescriptor' }) }),
+      expect.objectContaining({ id: 'shipping:alpha-ship', details: expect.objectContaining({ specialistRoute: 'shippingCarriers' }) }),
+      expect.objectContaining({ id: 'currency:alpha-rates', details: expect.objectContaining({ specialistRoute: 'currencies' }) }),
+      expect.objectContaining({ id: 'workflow:alpha.approval', details: expect.objectContaining({ specialistRoute: 'workflows' }) }),
+    ]))
+    expect(facts.contributions.filter((fact) => fact.id === 'payment:alpha-pay')).toHaveLength(1)
+  })
+
+  it('resolves factory-built contributions and generated entity registry references', () => {
+    write(moduleRoot, 'data/enrichers.ts', `
+      function makeEnricher(targetEntity) {
+        return { id: \`alpha.image:\${targetEntity}\`, targetEntity, async enrichMany(records) { return records } }
+      }
+      const registryEnricher = { id: 'alpha.registry', targetEntity: E.alpha.record, async enrichOne(record) { return record } }
+      export const enrichers = [makeEnricher('alpha:line'), registryEnricher]
+    `)
+
+    const facts = extractModuleExtensionFacts({
+      moduleId: 'alpha',
+      moduleRoot,
+      sourceRoot: 'node_modules/pkg/src/modules/alpha',
+      entities: [],
+      events: [],
+      apiRoutes: [],
+      searchEntities: [],
+    })
+
+    expect(facts.contributions).toEqual(expect.arrayContaining([
+      expect.objectContaining({ id: 'alpha.image:alpha:line', targets: [expect.objectContaining({ id: 'alpha:line' })] }),
+      expect.objectContaining({ id: 'alpha.registry', targets: [expect.objectContaining({ id: 'alpha:record' })] }),
+    ]))
+  })
+
+  it('reports declarations whose authoritative source no longer binds the host key', () => {
+    write(moduleRoot, 'extension-points.ts', `
+      export const extensionPoints = defineModuleExtensionPoints({
+        moduleId: 'alpha',
+        hosts: { records: dataTableExtensionHost({ tableId: 'alpha.records', source: 'Records.tsx' }) },
+      })
+    `)
+    write(moduleRoot, 'Records.tsx', "export const tableId = 'alpha.records'")
+
+    const facts = extractModuleExtensionFacts({
+      moduleId: 'alpha',
+      moduleRoot,
+      sourceRoot: 'node_modules/pkg/src/modules/alpha',
+      entities: [],
+      events: [],
+      apiRoutes: [],
+      searchEntities: [],
+    })
+
+    expect(facts.unresolved).toEqual([
+      expect.objectContaining({ key: 'alpha.records', reason: 'unbound-declaration' }),
+    ])
+    expect(facts.hosts.filter((host) => host.key.startsWith('records.')).every((host) => !host.bound)).toBe(true)
+  })
+
+  it('fails closed when a correlated first-party target remains unresolved', () => {
+    expect(() => assertNoUnresolvedExtensionTargets({
+      alpha: {
+        hosts: [],
+        contributions: [],
+        unresolved: [{
+          key: 'alpha.widget:data-table:alpha.missing',
+          source: { path: 'widgets/injection-table.ts' },
+          reason: 'unresolved-first-party-target',
+        }],
+      },
+    })).toThrow('alpha:alpha.widget:data-table:alpha.missing')
+  })
+
+  it('does not trust a claimed fact reference before matching a known first-party host', () => {
+    write(moduleRoot, 'data/enrichers.ts', `
+      export const enrichers = [{
+        id: 'alpha.typo', targetEntity: 'alpha.missing', async enrichOne(record) { return record },
+      }]
+    `)
+    const surface = extractModuleExtensionFacts({
+      moduleId: 'alpha',
+      moduleRoot,
+      sourceRoot: 'node_modules/pkg/src/modules/alpha',
+      entities: [{ id: 'alpha:record' }],
+      events: [],
+      apiRoutes: [],
+      searchEntities: [],
+    })
+    const correlated = correlateModuleExtensionFacts({
+      surfacesByModule: { alpha: surface },
+      entityIds: new Set(['alpha:record']),
+      eventIds: new Set(),
+      apiRoutes: new Set(),
+      commandIds: new Set(),
+    })
+
+    expect(() => assertNoUnresolvedExtensionTargets(correlated)).toThrow('alpha.typo:alpha.missing')
+  })
+
+  it('rejects wildcard targets that match no known first-party contract', () => {
+    const correlated = correlateModuleExtensionFacts({
+      surfacesByModule: {
+        alpha: {
+          hosts: [],
+          contributions: [{
+            id: 'alpha.typo-pattern',
+            kind: 'command-interceptor',
+            targets: [{ id: 'alpha.typo.*', resolution: 'unresolved' }],
+            scopeContract: 'tenant-and-organization',
+            source: { path: 'commands/interceptors.ts' },
+            details: { targetCommand: 'alpha.typo.*', phases: ['before-execute'] },
+          }],
+          unresolved: [],
+        },
+      },
+      entityIds: new Set(),
+      eventIds: new Set(),
+      apiRoutes: new Set(),
+      commandIds: new Set(['alpha.records.update']),
+    })
+
+    expect(() => assertNoUnresolvedExtensionTargets(correlated)).toThrow('alpha.typo-pattern:alpha.typo.*')
+  })
+})

package/src/lib/generators/__tests__/module-facts.bc-guard.test.ts

@@ -1,6 +1,6 @@
 import fs from 'node:fs'
 import path from 'node:path'
-import { extractAllModuleFacts } from '../module-facts'
+import { extractAllModuleFacts, renderModuleFactsJson } from '../module-facts'
 import { discoverPackageModuleSources } from '../module-facts-discovery'
 import { createResolver } from '../../resolver'
 
@@ -20,7 +20,77 @@ function isUnique(values: string[]): boolean {
 describe('module-facts BC resolve guard (T2)', () => {
   const repoRoot = findRepoRoot()
   const sources = discoverPackageModuleSources(createResolver(repoRoot))
-  const { factsByModule } = extractAllModuleFacts({ sources })
+  const extractionStartedAt = process.cpuUsage()
+  const { factsByModule, markdownByModule, frameworkMarkdown } = extractAllModuleFacts({ sources })
+  const extractionCpuUsage = process.cpuUsage(extractionStartedAt)
+  const extractionCpuDurationMs = (extractionCpuUsage.user + extractionCpuUsage.system) / 1_000
+
+  it('emits complete, deterministic extension catalogs for every resolved module', () => {
+    const repeated = extractAllModuleFacts({ sources })
+    expect(renderModuleFactsJson(repeated.factsByModule)).toBe(renderModuleFactsJson(factsByModule))
+    expect(repeated.markdownByModule).toEqual(markdownByModule)
+    expect(repeated.frameworkMarkdown).toBe(frameworkMarkdown)
+    for (const facts of Object.values(factsByModule)) {
+      expect(facts.extensionSurfaces).toBeDefined()
+      expect(facts.extensionSurfaces?.unresolved).toEqual([])
+    }
+  })
+
+  it('keeps generated extension facts within bounded build-time and context budgets', () => {
+    const completeJson = renderModuleFactsJson(factsByModule)
+    const legacyJson = renderModuleFactsJson(Object.fromEntries(
+      Object.entries(factsByModule).map(([moduleId, facts]) => [moduleId, { ...facts, extensionSurfaces: undefined }]),
+    ))
+    const markdownBytes = Object.values(markdownByModule)
+      .reduce((total, markdown) => total + Buffer.byteLength(markdown), Buffer.byteLength(frameworkMarkdown))
+
+    // Budget raised by the bidirectional-topology spec
+    // (2026-08-02-module-facts-extension-activation-and-incoming-index): the
+    // additive `activations`, cross-module `incoming`, and per-contribution
+    // `contributionResolutions` layers add ~210KB of compact references (no
+    // contribution payloads are duplicated). Incoming rows are cross-module only;
+    // resolution rows are required one-per-contribution by the spec's acceptance
+    // criteria and are the dominant term.
+    //
+    // JSON cap raised again by the exact-override-targets spec
+    // (2026-08-02-module-facts-exact-override-targets): the additive per-module
+    // `overrideTargets` project one exact key per real override entry (acl
+    // features, di tokens, subscribers, pages, workers, encryption, widgets,
+    // notifications, cli, setup, ai, interceptors/enrichers, page guards). These
+    // are required exhaustively by the spec's acceptance criteria; targets carry
+    // only compact structured path/key/factRef/source refs (no runtime values or
+    // contribution payloads). The delta cap is unchanged because `overrideTargets`
+    // live in both the complete and legacy renders (only `extensionSurfaces` is
+    // stripped for the legacy comparison).
+    //
+    // JSON cap raised a third time by the uniform provenance index
+    // (2026-08-02-module-facts-source-provenance-and-contract-inventory): every
+    // proven `(kind, id)` now reaches `factSources` (~630KB across the repo), so a
+    // consumer resolves any fact's origin through one lookup. Entries whose
+    // declaration site is already serialized inline (routes, pages, CLI commands,
+    // AI tools/agents, owned contracts, hosts, contributions) emit a typed
+    // `factRef` pointer instead of a duplicated source ref, and `factKey` is
+    // omitted when it equals the entry `id` — so the index costs references, never
+    // copied provenance payloads. The cap also covers the newly reachable
+    // framework-host activations (dashboard/menu/notification contributions now
+    // resolve as bound instead of silently falling back to capability-only).
+    // This is a blow-up detector, not a performance target. It measures CPU time
+    // for a whole-repo extraction, and CPU time for fixed work varies with the
+    // machine: the same extraction measures ~7.3s on a developer workstation and
+    // ~30.0s on a CI runner. At the previous 30s cap CI sat exactly on the line
+    // (an observed failure at 30,052.8ms), so the guard could not tell a genuine
+    // pathological regression from ordinary hardware variance and failed
+    // unrelated PRs at random. 90s keeps it meaningful — a real blow-up here is
+    // multiplicative, not a few percent — while leaving CI roughly 3x headroom.
+    expect(extractionCpuDurationMs).toBeLessThan(90_000)
+    expect(Buffer.byteLength(completeJson)).toBeLessThan(3_500_000)
+    expect(Buffer.byteLength(completeJson) - Buffer.byteLength(legacyJson)).toBeLessThan(1_800_000)
+    // Markdown cap raised with the source-link contract: entities, events, ACL
+    // features, DI tokens, search entities, notifications, UMES hosts and UMES
+    // contributions all render a resolved Source cell, and contribution
+    // resolutions render as their own source-linked section.
+    expect(markdownBytes).toBeLessThan(1_550_000)
+  })
 
   it('discovers a superset of the historical core modules', () => {
     const discovered = new Set(Object.keys(factsByModule))
@@ -30,11 +100,27 @@ describe('module-facts BC resolve guard (T2)', () => {
     expect(discovered.size).toBeGreaterThan(9)
   })
 
+  it('keeps factory-built and generated-registry enricher contributions visible', () => {
+    expect(factsByModule.sales.extensionSurfaces?.contributions).toEqual(expect.arrayContaining([
+      expect.objectContaining({ id: 'sales.catalog-image:sales:sales_quote_line', kind: 'response-enricher' }),
+      expect.objectContaining({ id: 'sales.catalog-image:sales:sales_order_line', kind: 'response-enricher' }),
+    ]))
+    expect(factsByModule.wms.extensionSurfaces?.contributions).toEqual(expect.arrayContaining([
+      expect.objectContaining({ id: 'wms.sales-order-inventory', kind: 'response-enricher' }),
+    ]))
+  })
+
   for (const source of sources) {
     const moduleId = source.moduleId
     describe(`${moduleId}`, () => {
       const facts = factsByModule[moduleId]
 
+      it('stamps the exact providing package and version without removing coreVersion', () => {
+        expect(facts.sourcePackage).toBe(source.from ?? null)
+        expect(facts.sourceVersion).toBe(source.packageVersion ?? null)
+        expect(facts).toHaveProperty('coreVersion')
+      })
+
       // Entity / search / host ids are colon-namespaced under the module by construction
       // and convention; drift here means the builder or a module's data model broke.
       it('colon-namespaces entity / search / host ids under the module and keeps ids unique', () => {

package/src/lib/generators/__tests__/module-facts.customers.fixture.test.ts

@@ -52,6 +52,7 @@ describe('module-facts customers fixture (T1 anti-drift guard)', () => {
       'customers.companies.list',
       'customers.deals.list',
       'customers.people.list',
+      'customers.todos.list',
     ])
     expect(facts.hostTokens.entityIds).toEqual(['customers:customer_entity'])
     expect(facts.diTokens).toEqual([])

package/src/lib/generators/__tests__/module-facts.discovery.test.ts

@@ -4,11 +4,13 @@ import path from 'node:path'
 import type { PackageResolver } from '../../resolver'
 import { discoverPackageModuleSources, hasReadableModuleSource } from '../module-facts-discovery'
 
-type FakePackage = { name: string; path: string; modulesPath: string }
+type FakePackage = { name: string; version?: string | null; path: string; modulesPath: string }
+type FakeModuleEntry = { id: string; from?: string }
 
-function makeResolver(packages: FakePackage[]): PackageResolver {
+function makeResolver(packages: FakePackage[], enabledModules: FakeModuleEntry[] = []): PackageResolver {
   return {
     discoverPackages: () => packages,
+    loadEnabledModules: () => enabledModules,
   } as unknown as PackageResolver
 }
 
@@ -62,27 +64,69 @@ describe('module-facts discovery (T1)', () => {
     writeModule(path.join(pkgSrc, 'src', 'modules'), 'gamma', 'events.ts')
 
     const resolver = makeResolver([
-      { name: '@open-mercato/tagged', path: pkgSrc, modulesPath: path.join(pkgSrc, 'src', 'modules') },
+      { name: '@open-mercato/tagged', version: '0.6.6', path: pkgSrc, modulesPath: path.join(pkgSrc, 'src', 'modules') },
     ])
 
     const [source] = discoverPackageModuleSources(resolver)
-    expect(source).toMatchObject({ moduleId: 'gamma', from: '@open-mercato/tagged' })
+    expect(source).toMatchObject({
+      moduleId: 'gamma',
+      from: '@open-mercato/tagged',
+      packageVersion: '0.6.6',
+    })
     expect(source.moduleRoot).toBe(path.join(pkgSrc, 'src', 'modules', 'gamma'))
   })
 
-  it('dedupes duplicate module ids first-wins', () => {
+  it('fails closed on duplicate module ids and reports every provider independent of discovery order', () => {
     const pkgA = path.join(tmp, 'dup-a')
     writeModule(path.join(pkgA, 'src', 'modules'), 'shared', 'index.ts')
     const pkgB = path.join(tmp, 'dup-b')
     writeModule(path.join(pkgB, 'src', 'modules'), 'shared', 'index.ts')
 
-    const resolver = makeResolver([
+    const packages = [
       { name: '@open-mercato/dup-a', path: pkgA, modulesPath: path.join(pkgA, 'src', 'modules') },
       { name: '@open-mercato/dup-b', path: pkgB, modulesPath: path.join(pkgB, 'src', 'modules') },
-    ])
+    ]
+    const expected = '[module-facts] duplicate module id "shared" is provided by '
+      + '@open-mercato/dup-a, @open-mercato/dup-b; src/modules.ts does not select a provider. '
+      + 'Select exactly one matching provider in src/modules.ts.'
+
+    expect(() => discoverPackageModuleSources(makeResolver(packages))).toThrow(expected)
+    expect(() => discoverPackageModuleSources(makeResolver([...packages].reverse()))).toThrow(expected)
+  })
+
+  it('uses the exact src/modules.ts provider even when package discovery order is reversed', () => {
+    const pkgA = path.join(tmp, 'selected-a')
+    writeModule(path.join(pkgA, 'src', 'modules'), 'shared', 'index.ts')
+    const pkgB = path.join(tmp, 'selected-b')
+    writeModule(path.join(pkgB, 'src', 'modules'), 'shared', 'index.ts')
+
+    const packages = [
+      { name: '@open-mercato/selected-a', path: pkgA, modulesPath: path.join(pkgA, 'src', 'modules') },
+      { name: '@open-mercato/selected-b', path: pkgB, modulesPath: path.join(pkgB, 'src', 'modules') },
+    ]
+    const enabled = [{ id: 'shared', from: '@open-mercato/selected-b' }]
+
+    for (const discoveredPackages of [packages, [...packages].reverse()]) {
+      const sources = discoverPackageModuleSources(makeResolver(discoveredPackages, enabled))
+      expect(sources).toHaveLength(1)
+      expect(sources[0]).toMatchObject({ moduleId: 'shared', from: '@open-mercato/selected-b' })
+      expect(sources[0].moduleRoot).toBe(path.join(pkgB, 'src', 'modules', 'shared'))
+    }
+  })
+
+  it('explains that an omitted provider implicitly selects core', () => {
+    const pkgA = path.join(tmp, 'implicit-a')
+    writeModule(path.join(pkgA, 'src', 'modules'), 'shared', 'index.ts')
+    const pkgB = path.join(tmp, 'implicit-b')
+    writeModule(path.join(pkgB, 'src', 'modules'), 'shared', 'index.ts')
+
+    const packages = [
+      { name: '@open-mercato/dup-a', path: pkgA, modulesPath: path.join(pkgA, 'src', 'modules') },
+      { name: '@open-mercato/dup-b', path: pkgB, modulesPath: path.join(pkgB, 'src', 'modules') },
+    ]
 
-    const sources = discoverPackageModuleSources(resolver)
-    expect(sources).toHaveLength(1)
-    expect(sources[0].moduleRoot).toBe(path.join(pkgA, 'src', 'modules', 'shared'))
+    expect(() => discoverPackageModuleSources(makeResolver(packages, [{ id: 'shared' }]))).toThrow(
+      'src/modules.ts omits "from", which defaults to @open-mercato/core',
+    )
   })
 })