@open-mercato/cli 0.6.8-develop.6931.1.4a1e1c786b → 0.6.8-develop.6940.1.177ea30c6e

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@open-mercato/cli",
-  "version": "0.6.8-develop.6931.1.4a1e1c786b",
+  "version": "0.6.8-develop.6940.1.177ea30c6e",
   "license": "MIT",
   "type": "module",
   "main": "./dist/index.js",
@@ -60,9 +60,9 @@
     "@mikro-orm/decorators": "^7.1.8",
     "@mikro-orm/migrations": "^7.1.8",
     "@mikro-orm/postgresql": "^7.1.8",
-    "@open-mercato/queue": "0.6.8-develop.6931.1.4a1e1c786b",
-    "@open-mercato/shared": "0.6.8-develop.6931.1.4a1e1c786b",
-    "@open-mercato/telemetry": "0.6.8-develop.6931.1.4a1e1c786b",
+    "@open-mercato/queue": "0.6.8-develop.6940.1.177ea30c6e",
+    "@open-mercato/shared": "0.6.8-develop.6940.1.177ea30c6e",
+    "@open-mercato/telemetry": "0.6.8-develop.6940.1.177ea30c6e",
     "cross-spawn": "^7.0.6",
     "pg": "8.22.0",
     "semver": "^7.8.5",
@@ -73,10 +73,10 @@
     "typescript-js": "npm:typescript@6.0.3"
   },
   "peerDependencies": {
-    "@open-mercato/shared": "0.6.8-develop.6931.1.4a1e1c786b"
+    "@open-mercato/shared": "0.6.8-develop.6940.1.177ea30c6e"
   },
   "devDependencies": {
-    "@open-mercato/shared": "0.6.8-develop.6931.1.4a1e1c786b",
+    "@open-mercato/shared": "0.6.8-develop.6940.1.177ea30c6e",
     "@types/jest": "^30.0.0",
     "jest": "^30.4.2",
     "ts-jest": "^29.4.12"

package/src/lib/__integration__/TC-INT-008.spec.ts

@@ -247,12 +247,14 @@ function expectedGuideOutputNames(): string[] {
   }
 
   // Generated fact-sheet artifacts (spec 2026-06-27-ts-morph-module-fact-sheets):
-  // the module-facts.json sidecar is copied as-is and fact-sheets are filtered to the
-  // fixture's enabled modules. The legacy core.<module>.md redirect stubs are no longer
+  // the v1 module-facts.json and corrected module-facts.v2.json sidecars are copied
+  // as-is and fact-sheets are filtered to the fixture's enabled modules. The legacy
+  // core.<module>.md redirect stubs are no longer
   // emitted (#3754). framework-extension-points.md is likewise generated into
   // dist/agentic/guides by both build.mjs pipelines (#4810) rather than checked in
   // alongside the static conceptual guides, so it needs an explicit entry here.
   collected.add('module-facts.json')
+  collected.add('module-facts.v2.json')
   collected.add('framework-extension-points.md')
   collected.add('upstream/AGENTS.md')
   collected.add('upstream/BACKWARD_COMPATIBILITY.md')

package/src/lib/__tests__/resolve-environment.test.ts

@@ -208,6 +208,24 @@ describe('resolveEnvironment', () => {
     })
   })
 
+  describe('monorepo — materialized workspace node_modules', () => {
+    it('prefers checked-out package sources when the workspace package is a real directory', async () => {
+      await makeDir(tempRoot, 'node_modules', '@open-mercato', 'core')
+      await makeDir(tempRoot, 'packages', 'core', 'src', 'modules')
+      await makeDir(tempRoot, 'apps', 'mercato')
+      const packageDir = await makeDir(tempRoot, 'packages', 'create-app')
+
+      const env = resolveEnvironment(packageDir)
+
+      expect(env.mode).toBe('monorepo')
+      expect(normalizePath(env.rootDir)).toBe(normalizePath(tempRoot))
+      expect(normalizePath(env.appDir)).toBe(normalizePath(path.join(tempRoot, 'apps', 'mercato')))
+      expect(normalizePath(env.packageRoot('@open-mercato/core'))).toBe(
+        normalizePath(path.join(tempRoot, 'packages', 'core')),
+      )
+    })
+  })
+
   describe('no @open-mercato packages present', () => {
     it('falls back to standalone mode with rootDir = cwd', async () => {
       const env = resolveEnvironment(tempRoot)

package/src/lib/agentic-setup.ts

@@ -439,7 +439,9 @@ function finalizeHarnessManifest(config: AgenticConfig, selectedTools: string[])
     ...targetPathsForTree(join(srcDir, 'scripts'), join(targetDir, 'scripts')),
   ])
   for (const file of readdirSync(GUIDES_DIR)) {
-    if (file.endsWith('.md') || file === 'module-facts.json') paths.add(join(targetDir, '.ai', 'guides', file))
+    if (file.endsWith('.md') || file === 'module-facts.json' || file === 'module-facts.v2.json') {
+      paths.add(join(targetDir, '.ai', 'guides', file))
+    }
   }
   for (const file of listFiles(join(GUIDES_DIR, 'upstream'))) {
     paths.add(join(targetDir, '.ai', 'guides', 'upstream', relative(join(GUIDES_DIR, 'upstream'), file)))
@@ -619,7 +621,7 @@ function generateShared(config: AgenticConfig): void {
 
   // Routed conceptual guides are copied wholesale (framework-wide). Per-module
   // fact-sheets (.ai/guides/modules/<module>.md) are filtered to the app's enabled
-  // module set; the combined module-facts.json sidecar is copied as-is.
+  // module set; the combined v1 and corrected v2 module-facts sidecars are copied as-is.
   if (existsSync(GUIDES_DIR)) {
     const guidesDestDir = join(targetDir, '.ai', 'guides')
     for (const file of readdirSync(GUIDES_DIR)) {
@@ -637,6 +639,12 @@ function generateShared(config: AgenticConfig): void {
       copyFileSync(moduleFactsPath, destPath)
     }
 
+    const moduleFactsV2Path = join(GUIDES_DIR, 'module-facts.v2.json')
+    if (existsSync(moduleFactsV2Path)) {
+      const destPath = join(guidesDestDir, 'module-facts.v2.json')
+      ensureDir(destPath)
+      copyFileSync(moduleFactsV2Path, destPath)
+    }
 
     copyTree(join(GUIDES_DIR, 'upstream'), join(guidesDestDir, 'upstream'), config)
 

package/src/lib/generators/__tests__/helpers/override-target-diagnostic-fixtures.ts

@@ -0,0 +1,150 @@
+import type { ModuleFactsJsonEntry } from '../../module-facts'
+import { getFrameworkOverrideHostOperations } from '../../module-extension-facts'
+import {
+  collectModuleOverrideTargets,
+  type ModuleOverrideTargetDiagnostic,
+  type ModuleOverrideTargetDiagnosticCode,
+  type ModuleOverrideTargetsResult,
+} from '../../module-override-targets'
+
+/**
+ * Real producers for every override-target diagnostic the projector can emit.
+ *
+ * The `factCoverage` ledger classifies four diagnostic codes as `negative-fixture`,
+ * which is a claim that a fixture really drives that code out of
+ * {@link collectModuleOverrideTargets}. These fixtures ARE that claim's evidence, and
+ * the coverage test asserts the produced set matches the ledger rows exactly — so a
+ * row can never name a fixture that does not exist, and a code no fixture reaches
+ * cannot be published as `negative-fixture`.
+ */
+
+export const FIXTURE_MODULE_ID = 'fixture'
+export const FIXTURE_SOURCE_ROOT = `node_modules/@open-mercato/core/src/modules/${FIXTURE_MODULE_ID}`
+
+export function fixtureFacts(overrides: Partial<ModuleFactsJsonEntry> = {}): ModuleFactsJsonEntry {
+  return {
+    title: 'Fixture',
+    description: null,
+    coreVersion: null,
+    sourcePackage: '@open-mercato/core',
+    sourceVersion: null,
+    sourceRoot: FIXTURE_SOURCE_ROOT,
+    entities: [],
+    events: [],
+    aclFeatures: [],
+    apiRoutes: [],
+    diTokens: [],
+    searchEntities: [],
+    hostTokens: { entityIds: [], tableIds: [] },
+    notifications: [],
+    cli: ['fixture:seed'],
+    backendPages: [],
+    frontendPages: [],
+    cliCommands: [{ command: 'fixture:seed', sourcePath: `${FIXTURE_SOURCE_ROOT}/cli.ts` }],
+    aiTools: [],
+    aiAgents: [],
+    ...overrides,
+  }
+}
+
+function fixtureWorkerFacts(): ModuleFactsJsonEntry {
+  return fixtureFacts({
+    ownedContracts: {
+      worker: [
+        {
+          kind: 'worker',
+          id: 'fixture.worker',
+          source: { sourcePath: `${FIXTURE_SOURCE_ROOT}/workers/fixture.ts`, line: 1 },
+        },
+      ],
+    },
+  })
+}
+
+/**
+ * The framework catalog's real declared operations, which the projector reads at
+ * import time. Tests derive their stub catalogs from this so a stub differs from
+ * production in exactly the one host under test.
+ */
+export function realCatalogOperations(): Record<string, string> {
+  return getFrameworkOverrideHostOperations()
+}
+
+export function catalogWithout(dottedHost: string): Record<string, string> {
+  const operations = realCatalogOperations()
+  delete operations[dottedHost]
+  return operations
+}
+
+export function catalogWith(dottedHost: string, operation: string): Record<string, string> {
+  return { ...realCatalogOperations(), [dottedHost]: operation }
+}
+
+/**
+ * Re-imports the projector against a stubbed framework catalog, so the two "no
+ * modes" causes reach the real `pushTarget` wiring instead of only the pure
+ * resolver. Every catalog host ships a valid operation today, so a stub is the only
+ * way to drive the unknown-domain/unknown-mode branches through production code.
+ */
+export function collectWithCatalogOperations(
+  hostOperations: Record<string, string>,
+  facts: ModuleFactsJsonEntry,
+): ModuleOverrideTargetsResult {
+  let result: ModuleOverrideTargetsResult | undefined
+  jest.isolateModules(() => {
+    jest.doMock('../../module-extension-facts', () => ({
+      ...jest.requireActual('../../module-extension-facts'),
+      getFrameworkOverrideHostOperations: () => hostOperations,
+    }))
+    const projector = require('../../module-override-targets') as typeof import('../../module-override-targets')
+    result = projector.collectModuleOverrideTargets(facts)
+  })
+  jest.dontMock('../../module-extension-facts')
+  if (!result) throw new Error('[internal] isolated override-target collection produced no result')
+  return result
+}
+
+export type OverrideTargetDiagnosticFixture = {
+  code: ModuleOverrideTargetDiagnosticCode
+  description: string
+  run: () => ModuleOverrideTargetDiagnostic[]
+}
+
+export const OVERRIDE_TARGET_DIAGNOSTIC_FIXTURES: OverrideTargetDiagnosticFixture[] = [
+  {
+    code: 'missing-source',
+    description: 'a cli command whose provenance cannot be proven',
+    run: () =>
+      collectModuleOverrideTargets(fixtureFacts({ cliCommands: [{ command: 'fixture:seed', sourcePath: null }] }))
+        .overrideTargetDiagnostics,
+  },
+  {
+    code: 'unsupported-dynamic-key',
+    description: 'an api route whose method the runtime cannot address',
+    run: () =>
+      collectModuleOverrideTargets(
+        fixtureFacts({
+          apiRoutes: [
+            {
+              path: '/fixture/items',
+              methods: ['FETCH'],
+              auth: {},
+              sourcePath: `${FIXTURE_SOURCE_ROOT}/api/items/route.ts`,
+            },
+          ],
+        }),
+      ).overrideTargetDiagnostics,
+  },
+  {
+    code: 'unknown-framework-domain',
+    description: 'the framework catalog does not describe the cli host at all',
+    run: () => collectWithCatalogOperations(catalogWithout('cli'), fixtureFacts()).overrideTargetDiagnostics,
+  },
+  {
+    code: 'unknown-framework-mode',
+    description: 'the framework catalog describes the workers host with an operation that is not a public mode',
+    run: () =>
+      collectWithCatalogOperations(catalogWith('workers', 'merge-deep'), fixtureWorkerFacts())
+        .overrideTargetDiagnostics,
+  },
+]

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

@@ -312,6 +312,296 @@ describe('module extension facts', () => {
     ]))
   })
 
+  it('fails closed on an unknown member call instead of publishing its first argument', () => {
+    // The generic call fallback used to forward the FIRST ARGUMENT of any call expression.
+    // For a member call that COMPUTES its value from the arguments — a handle builder, an
+    // enum lookup, anything namespaced — that publishes an id the argument merely contributed
+    // to, which resolves to nothing. `ComponentReplacementHandles.*` is intercepted by an
+    // explicit formula above, so only a builder the reader does NOT know exercises this path.
+    // The failure is silent (the fact vanishes rather than erroring), so it needs its own test.
+    write(moduleRoot, 'widgets/components.ts', `
+      import { SomeOtherRegistry } from '@open-mercato/shared/modules/widgets/component-registry'
+      export const componentOverrides = [
+        {
+          target: { componentId: SomeOtherRegistry.derive('alpha.records.list') },
+          priority: 50,
+          wrapper: (Original) => Original,
+        },
+      ]
+    `)
+
+    const facts = extractModuleExtensionFacts({
+      moduleId: 'alpha',
+      moduleRoot,
+      sourceRoot: 'node_modules/pkg/src/modules/alpha',
+      entities: [],
+      events: [],
+      apiRoutes: [],
+      searchEntities: [],
+    })
+
+    const overrides = facts.contributions.filter((contribution) => contribution.kind === 'component-override')
+    expect(overrides).toEqual([])
+    expect(JSON.stringify(facts)).not.toContain('alpha.records.list')
+
+    const legacyFacts = extractModuleExtensionFacts({
+      moduleId: 'alpha',
+      moduleRoot,
+      sourceRoot: 'node_modules/pkg/src/modules/alpha',
+      entities: [],
+      events: [],
+      apiRoutes: [],
+      searchEntities: [],
+      factsContractVersion: 1,
+    })
+    expect(legacyFacts.contributions).toEqual(expect.arrayContaining([
+      expect.objectContaining({
+        id: 'alpha.component-override.0:alpha.records.list',
+        details: expect.objectContaining({ handle: 'alpha.records.list', mode: 'replace' }),
+      }),
+    ]))
+  })
+
+  it('classifies component overrides by the ComponentOverride discriminant and resolves handle builders', () => {
+    write(moduleRoot, 'widgets/components.ts', `
+      import { ComponentReplacementHandles } from '@open-mercato/shared/modules/widgets/component-registry'
+      function wrapRecords(Original) { return Original }
+      export const componentOverrides = [
+        {
+          target: { componentId: ComponentReplacementHandles.section('ui.detail', 'NotesSection') },
+          priority: 50,
+          wrapper: (Original) => Original,
+        },
+        {
+          target: { componentId: ComponentReplacementHandles.dataTable('alpha.records.list') },
+          priority: 50,
+          wrapper: wrapRecords,
+        },
+        {
+          target: { componentId: ComponentReplacementHandles.crudForm('alpha.record') },
+          priority: 50,
+          propsTransform: (props) => props,
+        },
+        {
+          target: { componentId: ComponentReplacementHandles.page('/backend/alpha') },
+          priority: 50,
+          replacement: AlphaPage,
+          propsSchema: alphaPropsSchema,
+        },
+        {
+          target: { componentId: ComponentReplacementHandles.mystery('alpha') },
+          priority: 50,
+          wrapper: (Original) => Original,
+        },
+      ]
+    `)
+
+    const facts = extractModuleExtensionFacts({
+      moduleId: 'alpha',
+      moduleRoot,
+      sourceRoot: 'node_modules/pkg/src/modules/alpha',
+      entities: [],
+      events: [],
+      apiRoutes: [],
+      searchEntities: [],
+    })
+
+    const overrides = facts.contributions
+      .filter((contribution) => contribution.kind === 'component-override')
+      .map((contribution) => contribution.kind === 'component-override'
+        ? { id: contribution.id, ...contribution.details }
+        : null)
+
+    expect(overrides).toEqual([
+      {
+        id: 'alpha.component-override.0:section:ui.detail.NotesSection',
+        handle: 'section:ui.detail.NotesSection',
+        mode: 'wrapper',
+        propsContract: 'component-props-schema',
+      },
+      {
+        id: 'alpha.component-override.1:data-table:alpha.records.list',
+        handle: 'data-table:alpha.records.list',
+        mode: 'wrapper',
+        propsContract: 'component-props-schema',
+      },
+      {
+        id: 'alpha.component-override.2:crud-form:alpha.record',
+        handle: 'crud-form:alpha.record',
+        mode: 'props',
+        propsContract: 'component-props-schema',
+      },
+      {
+        id: 'alpha.component-override.3:page:/backend/alpha',
+        handle: 'page:/backend/alpha',
+        mode: 'replace',
+        propsContract: 'component-props-schema',
+      },
+    ])
+    // A handle the framework builder catalog does not describe never becomes a
+    // guessed id built from the call's first argument.
+    expect(JSON.stringify(facts.contributions)).not.toContain('ui.detail"')
+    expect(JSON.stringify(facts.contributions)).not.toContain('"alpha"')
+
+    const legacyFacts = extractModuleExtensionFacts({
+      moduleId: 'alpha',
+      moduleRoot,
+      sourceRoot: 'node_modules/pkg/src/modules/alpha',
+      entities: [],
+      events: [],
+      apiRoutes: [],
+      searchEntities: [],
+      factsContractVersion: 1,
+    })
+    expect(legacyFacts.contributions
+      .filter((contribution) => contribution.kind === 'component-override')
+      .map((contribution) => contribution.kind === 'component-override'
+        ? { id: contribution.id, ...contribution.details }
+        : null)).toEqual([
+      {
+        id: 'alpha.component-override.0:ui.detail',
+        handle: 'ui.detail',
+        mode: 'replace',
+        propsContract: 'component-props-schema',
+      },
+      {
+        id: 'alpha.component-override.1:alpha.records.list',
+        handle: 'alpha.records.list',
+        mode: 'replace',
+        propsContract: 'component-props-schema',
+      },
+      {
+        id: 'alpha.component-override.2:alpha.record',
+        handle: 'alpha.record',
+        mode: 'replace',
+        propsContract: 'component-props-schema',
+      },
+      {
+        id: 'alpha.component-override.3:/backend/alpha',
+        handle: '/backend/alpha',
+        mode: 'replace',
+        propsContract: 'component-props-schema',
+      },
+      {
+        id: 'alpha.component-override.4:alpha',
+        handle: 'alpha',
+        mode: 'replace',
+        propsContract: 'component-props-schema',
+      },
+    ])
+  })
+
+  it('reads arrow-function convention hooks as declared surfaces', () => {
+    write(moduleRoot, 'data/enrichers.ts', `
+      const enrichList = async (records) => records
+      export const enrichers = [{
+        id: 'alpha.arrow', targetEntity: 'alpha:record',
+        enrichMany: enrichList,
+        enrichOne: async (record) => record,
+      }]
+    `)
+
+    const facts = extractModuleExtensionFacts({
+      moduleId: 'alpha',
+      moduleRoot,
+      sourceRoot: 'node_modules/pkg/src/modules/alpha',
+      entities: [{ id: 'alpha:record' }],
+      events: [],
+      apiRoutes: [],
+      searchEntities: [],
+    })
+
+    expect(facts.contributions).toEqual(expect.arrayContaining([
+      expect.objectContaining({
+        id: 'alpha.arrow',
+        details: expect.objectContaining({ surfaces: ['list', 'detail'] }),
+      }),
+    ]))
+
+    const legacyFacts = extractModuleExtensionFacts({
+      moduleId: 'alpha',
+      moduleRoot,
+      sourceRoot: 'node_modules/pkg/src/modules/alpha',
+      entities: [{ id: 'alpha:record' }],
+      events: [],
+      apiRoutes: [],
+      searchEntities: [],
+      factsContractVersion: 1,
+    })
+    expect(legacyFacts.contributions).toEqual(expect.arrayContaining([
+      expect.objectContaining({ id: 'alpha.arrow', details: expect.objectContaining({ surfaces: [] }) }),
+    ]))
+  })
+
+  it('reads every injection-table slot form the runtime loader accepts', () => {
+    write(moduleRoot, 'extension-points.ts', `
+      export const extensionPoints = defineModuleExtensionPoints({
+        moduleId: 'alpha',
+        hosts: {
+          records: dataTableExtensionHost({ tableId: 'alpha.records', source: 'Records.tsx' }),
+          editor: crudFormExtensionHost({ entityId: 'alpha.record', source: 'Edit.tsx' }),
+        },
+      })
+    `)
+    write(moduleRoot, 'Records.tsx', 'export const tableId = extensionPoints.hosts.records.tableId')
+    write(moduleRoot, 'Edit.tsx', 'export const entityId = extensionPoints.hosts.editor.entityId')
+    write(moduleRoot, 'widgets/injection-table.ts', `
+      export const injectionTable = {
+        'crud-form:alpha.record': 'alpha.bare-string',
+        'data-table:alpha.records:bulk-actions': { widgetId: 'alpha.single-object', priority: 40, features: ['alpha.manage'] },
+        'data-table:alpha.records:columns': [{ widgetId: 'alpha.array-entry', priority: 20 }],
+      }
+    `)
+
+    const facts = extractModuleExtensionFacts({
+      moduleId: 'alpha',
+      moduleRoot,
+      sourceRoot: 'node_modules/pkg/src/modules/alpha',
+      entities: [],
+      events: [],
+      apiRoutes: [],
+      searchEntities: [],
+    })
+    const injected = facts.contributions.filter((contribution) => contribution.source.symbol === 'injectionTable')
+
+    expect(injected).toEqual(expect.arrayContaining([
+      expect.objectContaining({
+        id: 'alpha.bare-string@crud-form:alpha.record',
+        kind: 'crud-form',
+        features: [],
+        placement: undefined,
+        details: expect.objectContaining({ entityId: 'alpha.record', payload: 'render' }),
+      }),
+      expect.objectContaining({
+        id: 'alpha.single-object@data-table:alpha.records:bulk-actions',
+        kind: 'data-table',
+        features: ['alpha.manage'],
+        placement: { priority: 40 },
+        details: expect.objectContaining({ payload: 'bulk-action', tableId: 'alpha.records', executionGuard: 'both' }),
+      }),
+      expect.objectContaining({
+        id: 'alpha.array-entry@data-table:alpha.records:columns',
+        kind: 'data-table',
+        placement: { priority: 20 },
+        details: expect.objectContaining({ payload: 'column', executionGuard: 'host' }),
+      }),
+    ]))
+    expect(injected).toHaveLength(3)
+
+    const legacyFacts = extractModuleExtensionFacts({
+      moduleId: 'alpha',
+      moduleRoot,
+      sourceRoot: 'node_modules/pkg/src/modules/alpha',
+      entities: [],
+      events: [],
+      apiRoutes: [],
+      searchEntities: [],
+      factsContractVersion: 1,
+    })
+    expect(legacyFacts.contributions.filter((contribution) => contribution.source.symbol === 'injectionTable'))
+      .toEqual([expect.objectContaining({ id: 'alpha.array-entry@data-table:alpha.records:columns' })])
+  })
+
   it('reports declarations whose authoritative source no longer binds the host key', () => {
     write(moduleRoot, 'extension-points.ts', `
       export const extensionPoints = defineModuleExtensionPoints({

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, renderModuleFactsJson } from '../module-facts'
+import { extractAllModuleFacts, isExactSourceFilePath, renderModuleFactsJson } from '../module-facts'
 import { discoverPackageModuleSources } from '../module-facts-discovery'
 import { createResolver } from '../../resolver'
 
@@ -17,11 +17,18 @@ function isUnique(values: string[]): boolean {
   return values.length === new Set(values).size
 }
 
+const MARKDOWN_LINK_TARGET = /\]\(\.\.\/\.\.\/\.\.\/([^)#]+)(?:#L\d+)?\)/g
+
+function collectLinkTargets(markdown: string): string[] {
+  return [...markdown.matchAll(MARKDOWN_LINK_TARGET)].map((match) => match[1])
+}
+
 describe('module-facts BC resolve guard (T2)', () => {
   const repoRoot = findRepoRoot()
   const sources = discoverPackageModuleSources(createResolver(repoRoot))
   const extractionStartedAt = process.cpuUsage()
   const { factsByModule, markdownByModule, frameworkMarkdown } = extractAllModuleFacts({ sources })
+  const legacyFactsByModule = extractAllModuleFacts({ sources, factsContractVersion: 1 }).factsByModule
   const extractionCpuUsage = process.cpuUsage(extractionStartedAt)
   const extractionCpuDurationMs = (extractionCpuUsage.user + extractionCpuUsage.system) / 1_000
 
@@ -36,6 +43,23 @@ describe('module-facts BC resolve guard (T2)', () => {
     }
   })
 
+  it('preserves stable v1 extension arrays while exposing corrected v2 facts separately', () => {
+    const legacySecurity = legacyFactsByModule.security.extensionSurfaces?.contributions.find(
+      (contribution) => contribution.id.includes('section:auth.login.form'),
+    )
+    const v2Security = factsByModule.security.extensionSurfaces?.contributions.find(
+      (contribution) => contribution.id.includes('section:auth.login.form'),
+    )
+    expect(legacySecurity?.kind === 'component-override' ? legacySecurity.details.mode : null).toBe('replace')
+    expect(v2Security?.kind === 'component-override' ? v2Security.details.mode : null).toBe('wrapper')
+
+    const recoveredContribution = 'catalog.injection.product-bulk-delete@data-table:catalog.products.list:bulk-actions'
+    expect(legacyFactsByModule.catalog.extensionSurfaces?.contributions.map((entry) => entry.id))
+      .not.toContain(recoveredContribution)
+    expect(factsByModule.catalog.extensionSurfaces?.contributions.map((entry) => entry.id))
+      .toContain(recoveredContribution)
+  })
+
   it('keeps generated extension facts within bounded build-time and context budgets', () => {
     const completeJson = renderModuleFactsJson(factsByModule)
     const legacyJson = renderModuleFactsJson(Object.fromEntries(
@@ -82,13 +106,16 @@ describe('module-facts BC resolve guard (T2)', () => {
     // 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.
-    //
-    // Whole-repo output caps include the additive EUDR module. Measured with the
-    // same extractor, EUDR adds 147,395 JSON bytes and 66,037 Markdown bytes for
-    // its real routes, ACL, events, entities, and extension surfaces; removing
-    // only EUDR leaves 3,486,786 JSON bytes and 1,519,856 Markdown bytes. The
-    // extension-only delta remains below its existing 1.8 MB blow-up guard.
     expect(extractionCpuDurationMs).toBeLessThan(90_000)
+    // JSON cap raised a fourth time by the injection-table slot normalization:
+    // `extractInjectionTable` previously did `if (!Array.isArray(entries)) continue`,
+    // silently dropping every string and single-object slot form that
+    // `ModuleInjectionTable` allows. Twelve real contributions across catalog, sales,
+    // wms, staff, integrations and checkout were therefore invisible to every fact
+    // consumer — `integrations` published no contributions at all. Reading them costs
+    // ~28KB, which is the fix working, not drift.
+    // The additive EUDR module contributes its real routes, ACL, events,
+    // entities, and extension surfaces without changing the extraction shape.
     expect(Buffer.byteLength(completeJson)).toBeLessThan(3_750_000)
     expect(Buffer.byteLength(completeJson) - Buffer.byteLength(legacyJson)).toBeLessThan(1_800_000)
     // Markdown cap raised with the source-link contract: entities, events, ACL
@@ -98,6 +125,44 @@ describe('module-facts BC resolve guard (T2)', () => {
     expect(markdownBytes).toBeLessThan(1_650_000)
   })
 
+  it('links every generated fact to an exact resolvable file, never a directory', () => {
+    const packageLinkRoot = path.join(repoRoot, 'node_modules', '@open-mercato')
+    const canCheckDisk = fs.existsSync(packageLinkRoot)
+    const nonExactTargets = new Set<string>()
+    const unresolvedTargets = new Set<string>()
+    let checkedTargets = 0
+
+    for (const markdown of Object.values(markdownByModule)) {
+      for (const target of collectLinkTargets(markdown)) {
+        checkedTargets += 1
+        if (!isExactSourceFilePath(target)) {
+          nonExactTargets.add(target)
+          continue
+        }
+        if (!canCheckDisk) continue
+        const absolute = path.join(repoRoot, target)
+        if (!fs.existsSync(absolute) || !fs.statSync(absolute).isFile()) unresolvedTargets.add(target)
+      }
+    }
+
+    expect(checkedTargets).toBeGreaterThan(1_000)
+    expect([...nonExactTargets]).toEqual([])
+    expect([...unresolvedTargets]).toEqual([])
+  })
+
+  it('keeps directory-valued provenance readable as plain text', () => {
+    const frameworkHostMarkdowns = Object.values(markdownByModule)
+      .filter((markdown) => markdown.includes('packages/ui/src'))
+    expect(frameworkHostMarkdowns.length).toBeGreaterThan(0)
+    for (const markdown of frameworkHostMarkdowns) {
+      expect(markdown).not.toContain('(../../../packages/ui/src)')
+    }
+    for (const [moduleId, facts] of Object.entries(factsByModule)) {
+      expect(markdownByModule[moduleId]).toContain(`Source root: ${facts.sourceRoot}\n`)
+      expect(markdownByModule[moduleId]).not.toContain(`(../../../${facts.sourceRoot})`)
+    }
+  })
+
   it('discovers a superset of the historical core modules', () => {
     const discovered = new Set(Object.keys(factsByModule))
     for (const moduleId of ['auth', 'catalog', 'customers', 'sales', 'workflows']) {