@open-mercato/cli 0.8.1-develop.7296.1.2111d779db → 0.9.0

package/src/lib/db/__tests__/encryption-backfill-check.test.ts

@@ -0,0 +1,146 @@
+import {
+  checkEncryptionMapBackfills,
+  findEncryptionBackfillGaps,
+  formatEncryptionBackfillWarning,
+  isBackfilledByMigration,
+  isEncryptionBackfillCheckEnabled,
+  readDeclaredEncryptionMaps,
+  type EncryptionMapRow,
+} from '../encryption-backfill-check'
+
+const TENANT_A = '11111111-1111-1111-1111-111111111111'
+const TENANT_B = '22222222-2222-2222-2222-222222222222'
+const ORG = '33333333-3333-3333-3333-333333333333'
+
+function row(tenantId: string, entityId: string, fields: string[], isActive = true): EncryptionMapRow {
+  return { tenantId, organizationId: ORG, entityId, fieldsJson: fields.map((field) => ({ field })), isActive }
+}
+
+describe('readDeclaredEncryptionMaps', () => {
+  it('reads defaultEncryptionMaps and skips system-scoped or malformed entries', () => {
+    const declared = readDeclaredEncryptionMaps('demo', {
+      defaultEncryptionMaps: [
+        { entityId: 'demo:thing', fields: [{ field: 'secret' }, { field: 'email', hashField: 'email_hash' }] },
+        { entityId: 'demo:system', keyScope: 'system', fields: [{ field: 'token' }] },
+        { entityId: 'demo:empty', fields: [] },
+        { fields: [{ field: 'orphan' }] },
+      ],
+    })
+
+    expect(declared).toEqual([{ moduleId: 'demo', entityId: 'demo:thing', fields: ['secret', 'email'] }])
+  })
+
+  it('falls back to the default export', () => {
+    expect(readDeclaredEncryptionMaps('demo', { default: [{ entityId: 'demo:thing', fields: [{ field: 'secret' }] }] }))
+      .toEqual([{ moduleId: 'demo', entityId: 'demo:thing', fields: ['secret'] }])
+  })
+})
+
+describe('isBackfilledByMigration', () => {
+  it('accepts a helper call or raw encryption_maps SQL naming the entity and field', () => {
+    const helperSource = `buildEncryptionMapBackfillSql({ entityId: 'demo:thing', fields: [{ field: 'secret' }] })`
+    const rawSource = `insert into "encryption_maps" select 'demo:thing', '[{"field":"secret"}]'::jsonb`
+
+    expect(isBackfilledByMigration([helperSource], 'demo:thing', 'secret')).toBe(true)
+    expect(isBackfilledByMigration([rawSource], 'demo:thing', 'secret')).toBe(true)
+  })
+
+  it('rejects migrations that do not write encryption maps or name another field', () => {
+    expect(isBackfilledByMigration([`alter table demo add column "secret" text; -- demo:thing`], 'demo:thing', 'secret')).toBe(false)
+    expect(isBackfilledByMigration([`buildEncryptionMapBackfillSql({ entityId: 'demo:thing', fields: [{ field: 'secret_hash' }] })`], 'demo:thing', 'secret')).toBe(false)
+  })
+})
+
+describe('findEncryptionBackfillGaps', () => {
+  const declared = [{ moduleId: 'demo', entityId: 'demo:thing', fields: ['secret', 'email'] }]
+
+  it('reports declared fields missing for existing encryption-enabled scopes', () => {
+    const gaps = findEncryptionBackfillGaps({
+      declared,
+      rows: [row(TENANT_A, 'other:x', ['a']), row(TENANT_B, 'demo:thing', ['secret', 'email'])],
+      migrationSources: [],
+    })
+
+    expect(gaps).toEqual([
+      { moduleId: 'demo', entityId: 'demo:thing', field: 'secret', missingScopes: 1, totalScopes: 2 },
+      { moduleId: 'demo', entityId: 'demo:thing', field: 'email', missingScopes: 1, totalScopes: 2 },
+    ])
+  })
+
+  it('reports a new field on an existing map', () => {
+    const gaps = findEncryptionBackfillGaps({ declared, rows: [row(TENANT_A, 'demo:thing', ['secret'])], migrationSources: [] })
+
+    expect(gaps.map((gap) => gap.field)).toEqual(['email'])
+  })
+
+  it('ignores scopes with encryption disabled and fields a migration backfills', () => {
+    expect(findEncryptionBackfillGaps({ declared, rows: [row(TENANT_A, 'other:x', ['a'], false)], migrationSources: [] })).toEqual([])
+    expect(
+      findEncryptionBackfillGaps({
+        declared,
+        rows: [row(TENANT_A, 'other:x', ['a'])],
+        migrationSources: [`buildEncryptionMapBackfillSql({ entityId: 'demo:thing', fields: [{ field: 'secret' }, { field: 'email' }] })`],
+      }),
+    ).toEqual([])
+  })
+})
+
+describe('checkEncryptionMapBackfills', () => {
+  it('warns once with every gap', async () => {
+    const warn = jest.fn()
+    const gaps = await checkEncryptionMapBackfills({
+      loadDeclaredMaps: async () => [{ moduleId: 'demo', entityId: 'demo:thing', fields: ['secret'] }],
+      loadMigrationSources: () => [],
+      queryEncryptionMaps: async () => [row(TENANT_A, 'other:x', ['a'])],
+      warn,
+    })
+
+    expect(gaps).toHaveLength(1)
+    expect(warn).toHaveBeenCalledTimes(1)
+    expect(warn.mock.calls[0][0]).toContain('demo: demo:thing [secret] (missing in 1/1 tenant scopes)')
+    expect(warn.mock.calls[0][0]).toContain('buildEncryptionMapBackfillSql')
+  })
+
+  it('does not query the database when no module declares maps', async () => {
+    const queryEncryptionMaps = jest.fn(async () => [])
+    await checkEncryptionMapBackfills({ loadDeclaredMaps: async () => [], loadMigrationSources: () => [], queryEncryptionMaps, warn: jest.fn() })
+
+    expect(queryEncryptionMaps).not.toHaveBeenCalled()
+  })
+
+  it('turns failures into a warning instead of throwing', async () => {
+    const warn = jest.fn()
+    const gaps = await checkEncryptionMapBackfills({
+      loadDeclaredMaps: async () => [{ moduleId: 'demo', entityId: 'demo:thing', fields: ['secret'] }],
+      loadMigrationSources: () => [],
+      queryEncryptionMaps: async () => {
+        throw new Error('connection refused')
+      },
+      warn,
+    })
+
+    expect(gaps).toEqual([])
+    expect(warn).toHaveBeenCalledWith(expect.stringContaining('connection refused'))
+  })
+})
+
+describe('formatEncryptionBackfillWarning', () => {
+  it('groups fields per entity and caps the list', () => {
+    const gaps = Array.from({ length: 22 }, (_unused, index) => [
+      { moduleId: 'demo', entityId: `demo:thing_${index}`, field: 'secret', missingScopes: 1, totalScopes: 2 },
+      { moduleId: 'demo', entityId: `demo:thing_${index}`, field: 'email', missingScopes: 2, totalScopes: 2 },
+    ]).flat()
+    const message = formatEncryptionBackfillWarning(gaps)
+
+    expect(message).toContain('   - demo: demo:thing_0 [secret, email] (missing in 2/2 tenant scopes)')
+    expect(message).not.toContain('demo:thing_20 ')
+    expect(message).toContain('… and 2 more entities')
+  })
+})
+
+describe('isEncryptionBackfillCheckEnabled', () => {
+  it('is on by default and can be switched off', () => {
+    expect(isEncryptionBackfillCheckEnabled({})).toBe(true)
+    expect(isEncryptionBackfillCheckEnabled({ OM_ENCRYPTION_BACKFILL_CHECK: 'off' })).toBe(false)
+  })
+})

package/src/lib/db/__tests__/migration-reindex.test.ts

@@ -1,4 +1,6 @@
+import fs from 'node:fs'
 import path from 'node:path'
+import { fileURLToPath } from 'node:url'
 import {
   collectQueryIndexReindexEntityTypes,
   formatManualReindexInstructions,
@@ -14,6 +16,10 @@ function migration(name: string, overrides: Partial<AppliedMigration> = {}): App
   return { moduleId: 'customers', migrationsPath: MIGRATIONS_PATH, name, ...overrides }
 }
 
+function resolveImportSpecifier(specifier: string): string {
+  return specifier.startsWith('file:') ? fileURLToPath(specifier) : specifier
+}
+
 describe('resolveMigrationFilePath', () => {
   const existing = new Set([path.join(MIGRATIONS_PATH, 'Migration20260901120000_reindex.ts')])
   const fileExists = (filePath: string) => existing.has(filePath)
@@ -61,7 +67,7 @@ describe('collectQueryIndexReindexEntityTypes', () => {
 
     const collected = await collectQueryIndexReindexEntityTypes(
       [migration('a'), migration('b'), migration('c')],
-      { importModule: async (filePath) => modules[filePath], fileExists },
+      { importModule: async (specifier) => modules[resolveImportSpecifier(specifier)], fileExists },
     )
 
     expect(collected).toEqual(['customers:customer_dictionary_entry', 'workflows:workflow_definition'])
@@ -74,8 +80,8 @@ describe('collectQueryIndexReindexEntityTypes', () => {
       {
         fileExists,
         onWarn,
-        importModule: async (filePath) => {
-          if (filePath.endsWith('broken.ts')) throw new Error('boom')
+        importModule: async (specifier) => {
+          if (resolveImportSpecifier(specifier).endsWith('broken.ts')) throw new Error('boom')
           return { queryIndexReindexEntityTypes: ['dictionaries:dictionary_entry'] }
         },
       },
@@ -118,6 +124,45 @@ describe('collectQueryIndexReindexEntityTypes', () => {
     expect(collected).toEqual([])
     expect(importModule).not.toHaveBeenCalled()
   })
+
+  it('imports cwd-relative node_modules migration paths via file: URLs (#6238)', async () => {
+    const relativePath = path.join(
+      'node_modules',
+      '@open-mercato',
+      'test-migration-reindex',
+      'Migration20260901120000_reindex.js',
+    )
+    const absolutePath = path.resolve(relativePath)
+    fs.mkdirSync(path.dirname(absolutePath), { recursive: true })
+    fs.writeFileSync(
+      absolutePath,
+      'module.exports = { queryIndexReindexEntityTypes: ["customers:deal"] };\n',
+    )
+
+    try {
+      const onWarn = jest.fn()
+      const collected = await collectQueryIndexReindexEntityTypes(
+        [{
+          moduleId: 'customers',
+          migrationsPath: path.dirname(absolutePath),
+          name: 'Migration20260901120000_reindex',
+          filePath: relativePath,
+        }],
+        {
+          onWarn,
+          importModule: async (specifier) => {
+            expect(specifier.startsWith('file:')).toBe(true)
+            return import(specifier)
+          },
+        },
+      )
+
+      expect(onWarn).not.toHaveBeenCalled()
+      expect(collected).toEqual(['customers:deal'])
+    } finally {
+      fs.rmSync(path.dirname(absolutePath), { recursive: true, force: true })
+    }
+  })
 })
 
 describe('isMigrationReindexEnabled', () => {

package/src/lib/db/commands.ts

@@ -9,6 +9,13 @@ import { PostgreSqlDriver } from '@mikro-orm/postgresql'
 import { getSslConfig } from '@open-mercato/shared/lib/db/ssl'
 import type { PackageResolver, ModuleEntry } from '../resolver'
 import { quotePostgresIdentifier } from './identifiers'
+import {
+  checkEncryptionMapBackfills,
+  isEncryptionBackfillCheckEnabled,
+  readDeclaredEncryptionMaps,
+  type DeclaredEncryptionMap,
+  type EncryptionMapRow,
+} from './encryption-backfill-check'
 import {
   collectQueryIndexReindexEntityTypes,
   isMigrationReindexEnabled,
@@ -59,18 +66,47 @@ function sortModules(mods: ModuleEntry[]): ModuleEntry[] {
 }
 
 /**
- * Custom dynamic import provider for MikroORM that properly handles Windows paths.
- * MikroORM's built-in handling has a bug where it converts file:// URLs back to
- * Windows paths when the extension isn't in require.extensions (which is always
- * true for .ts files in ESM mode).
+ * Convert a filesystem path into a specifier `import()` can resolve under plain
+ * Node ESM on every platform (#6238).
+ *
+ * Windows already needed `file:` URLs for drive-letter absolute paths. On POSIX,
+ * cwd-relative paths such as `node_modules/.../Migration.js` are treated as
+ * bare package names (`node_modules`), so migration reindex declarations were
+ * logged and skipped. Absolute paths become `file:` URLs on every platform.
+ * Already-URL / `node:` / bare package (and package-subpath) specifiers stay as-is.
  */
-async function dynamicImportProvider(id: string): Promise<any> {
-  // On Windows, convert absolute paths to file:// URLs
-  // Check if it's a Windows absolute path (e.g., C:\... or D:\...)
-  if (process.platform === 'win32' && /^[a-zA-Z]:[\\/]/.test(id)) {
-    id = pathToFileURL(id).href
+export function toImportableModuleSpecifier(id: string): string {
+  if (
+    id.startsWith('file:') ||
+    id.startsWith('data:') ||
+    id.startsWith('node:') ||
+    id.startsWith('http:') ||
+    id.startsWith('https:')
+  ) {
+    return id
   }
-  return import(id)
+
+  const isWindowsAbsolute = /^[a-zA-Z]:[\\/]/.test(id)
+  const isFilesystemRelative =
+    id.startsWith('./') ||
+    id.startsWith('../') ||
+    id.startsWith('.\\') ||
+    id.startsWith('..\\') ||
+    /(^|[\\/])node_modules([\\/]|$)/.test(id)
+
+  if (path.isAbsolute(id) || isWindowsAbsolute || isFilesystemRelative) {
+    return pathToFileURL(path.resolve(id)).href
+  }
+
+  return id
+}
+
+/**
+ * Custom dynamic import provider for MikroORM and migration reindex loading.
+ * Always converts filesystem paths to `file:` URLs before `import()` (#6238).
+ */
+async function dynamicImportProvider(id: string): Promise<any> {
+  return import(toImportableModuleSpecifier(id))
 }
 
 /**
@@ -228,6 +264,72 @@ function getMigrationsPath(entry: ModuleEntry, resolver: PackageResolver): strin
   return path.join(roots.pkgBase, 'migrations').replace(/\\/g, '/')
 }
 
+async function loadModuleEncryptionMaps(entry: ModuleEntry, resolver: PackageResolver): Promise<DeclaredEncryptionMap[]> {
+  const roots = resolver.getModulePaths(entry)
+  const appFile = path.join(roots.appBase, 'encryption.ts')
+  const pkgFile = path.join(roots.pkgBase, 'encryption.ts')
+  try {
+    if (fs.existsSync(appFile)) return readDeclaredEncryptionMaps(entry.id, await importWithTypeScriptFile(appFile))
+    if (entry.from === '@app' || resolver.isMonorepo()) {
+      return fs.existsSync(pkgFile) ? readDeclaredEncryptionMaps(entry.id, await importWithTypeScriptFile(pkgFile)) : []
+    }
+    return readDeclaredEncryptionMaps(entry.id, await import(`${resolver.getModuleImportBase(entry).pkgBase}/encryption`))
+  } catch {
+    return []
+  }
+}
+
+function readModuleMigrationSources(modules: ModuleEntry[], resolver: PackageResolver): string[] {
+  const sources: string[] = []
+  for (const entry of modules) {
+    const migrationsPath = getMigrationsPath(entry, resolver)
+    if (!fs.existsSync(migrationsPath)) continue
+    for (const file of fs.readdirSync(migrationsPath)) {
+      if (!/^Migration.*\.(ts|js)$/.test(file) || file.endsWith('.d.ts')) continue
+      sources.push(fs.readFileSync(path.join(migrationsPath, file), 'utf8'))
+    }
+  }
+  return sources
+}
+
+async function queryEncryptionMapRows(): Promise<EncryptionMapRow[] | null> {
+  const { Client } = await import('pg')
+  const client = new Client({ connectionString: getClientUrl(), ssl: getSslConfig(), connectionTimeoutMillis: 5000 })
+  await client.connect()
+  try {
+    const table = await client.query(`select to_regclass('encryption_maps') is not null as "exists"`)
+    if (!table.rows[0]?.exists) return null
+    const result = await client.query(
+      `select "tenant_id", "organization_id", "entity_id", "fields_json", "is_active" from "encryption_maps" where "deleted_at" is null`,
+    )
+    return result.rows.map((row) => ({
+      tenantId: row.tenant_id ?? null,
+      organizationId: row.organization_id ?? null,
+      entityId: String(row.entity_id),
+      fieldsJson: row.fields_json,
+      isActive: row.is_active === true,
+    }))
+  } finally {
+    try {
+      await client.end()
+    } catch { }
+  }
+}
+
+export async function warnAboutMissingEncryptionMapBackfills(modules: ModuleEntry[], resolver: PackageResolver): Promise<void> {
+  if (!isEncryptionBackfillCheckEnabled()) return
+  await checkEncryptionMapBackfills({
+    loadDeclaredMaps: async () => {
+      const declared: DeclaredEncryptionMap[] = []
+      for (const entry of modules) declared.push(...(await loadModuleEncryptionMaps(entry, resolver)))
+      return declared
+    },
+    loadMigrationSources: () => readModuleMigrationSources(modules, resolver),
+    queryEncryptionMaps: queryEncryptionMapRows,
+    warn: (message) => console.warn(message),
+  })
+}
+
 export interface DbOptions {
   quiet?: boolean
 }
@@ -338,6 +440,7 @@ export async function dbGenerate(resolver: PackageResolver, options: DbOptions =
   }
 
   console.log(results.join('\n'))
+  await warnAboutMissingEncryptionMapBackfills(ordered, resolver)
 }
 
 export async function dbMigrate(resolver: PackageResolver, options: DbOptions = {}): Promise<void> {

package/src/lib/db/encryption-backfill-check.ts

@@ -0,0 +1,163 @@
+import { parseBooleanWithDefault } from '@open-mercato/shared/lib/boolean'
+
+/**
+ * Advisory check run after `db:generate`. Tenant encryption maps are seeded only when a tenant is
+ * created, so an `encryption.ts` entry added after tenants exist never reaches them unless a module
+ * migration backfills it (`buildEncryptionMapBackfillSql`). The connected database is the evidence:
+ * a declared `(entityId, field)` that some existing encryption-enabled scope lacks, and that no
+ * migration mentions, is reported. The check only warns; it never fails generation.
+ */
+
+export type DeclaredEncryptionMap = {
+  moduleId: string
+  entityId: string
+  fields: string[]
+}
+
+export type EncryptionMapRow = {
+  tenantId: string | null
+  organizationId: string | null
+  entityId: string
+  fieldsJson: unknown
+  isActive: boolean
+}
+
+export type EncryptionBackfillGap = {
+  moduleId: string
+  entityId: string
+  field: string
+  missingScopes: number
+  totalScopes: number
+}
+
+export type EncryptionBackfillCheckDeps = {
+  loadDeclaredMaps: () => Promise<DeclaredEncryptionMap[]>
+  loadMigrationSources: () => string[]
+  queryEncryptionMaps: () => Promise<EncryptionMapRow[] | null>
+  warn: (message: string) => void
+}
+
+export function isEncryptionBackfillCheckEnabled(env: NodeJS.ProcessEnv = process.env): boolean {
+  return parseBooleanWithDefault(env.OM_ENCRYPTION_BACKFILL_CHECK, true)
+}
+
+export function readDeclaredEncryptionMaps(moduleId: string, moduleExports: unknown): DeclaredEncryptionMap[] {
+  if (!moduleExports || typeof moduleExports !== 'object') return []
+  const exportsRecord = moduleExports as Record<string, unknown>
+  const maps = exportsRecord.defaultEncryptionMaps ?? exportsRecord.encryptionMaps ?? exportsRecord.default
+  if (!Array.isArray(maps)) return []
+  const declared: DeclaredEncryptionMap[] = []
+  for (const map of maps) {
+    if (!map || typeof map !== 'object') continue
+    const { entityId, keyScope, fields } = map as Record<string, unknown>
+    if (typeof entityId !== 'string' || keyScope === 'system' || !Array.isArray(fields)) continue
+    const fieldNames = fields
+      .map((rule) => (rule && typeof rule === 'object' ? (rule as Record<string, unknown>).field : null))
+      .filter((field): field is string => typeof field === 'string' && field.length > 0)
+    if (fieldNames.length) declared.push({ moduleId, entityId, fields: fieldNames })
+  }
+  return declared
+}
+
+function readRuleFields(fieldsJson: unknown): Set<string> {
+  const fields = new Set<string>()
+  if (!Array.isArray(fieldsJson)) return fields
+  for (const rule of fieldsJson) {
+    if (rule && typeof rule === 'object' && typeof (rule as Record<string, unknown>).field === 'string') {
+      fields.add((rule as Record<string, string>).field)
+    }
+  }
+  return fields
+}
+
+function scopeKey(tenantId: string | null, organizationId: string | null): string {
+  return `${tenantId ?? ''}|${organizationId ?? ''}`
+}
+
+function mentionsLiteral(source: string, value: string): boolean {
+  return source.includes(`'${value}'`) || source.includes(`"${value}"`) || source.includes(`\`${value}\``)
+}
+
+export function isBackfilledByMigration(migrationSources: readonly string[], entityId: string, field: string): boolean {
+  return migrationSources.some(
+    (source) =>
+      (source.includes('encryption_maps') || source.includes('buildEncryptionMapBackfillSql')) &&
+      mentionsLiteral(source, entityId) &&
+      mentionsLiteral(source, field),
+  )
+}
+
+export function findEncryptionBackfillGaps(input: {
+  declared: readonly DeclaredEncryptionMap[]
+  rows: readonly EncryptionMapRow[]
+  migrationSources: readonly string[]
+}): EncryptionBackfillGap[] {
+  const activeScopes = new Set<string>()
+  const fieldsByScopeAndEntity = new Map<string, Set<string>>()
+  for (const row of input.rows) {
+    const scope = scopeKey(row.tenantId, row.organizationId)
+    if (row.isActive) activeScopes.add(scope)
+    const key = `${scope}|${row.entityId}`
+    const fields = fieldsByScopeAndEntity.get(key) ?? new Set<string>()
+    for (const field of readRuleFields(row.fieldsJson)) fields.add(field)
+    fieldsByScopeAndEntity.set(key, fields)
+  }
+  if (activeScopes.size === 0) return []
+
+  const gaps: EncryptionBackfillGap[] = []
+  for (const map of input.declared) {
+    for (const field of map.fields) {
+      let missingScopes = 0
+      for (const scope of activeScopes) {
+        if (!fieldsByScopeAndEntity.get(`${scope}|${map.entityId}`)?.has(field)) missingScopes += 1
+      }
+      if (missingScopes === 0) continue
+      if (isBackfilledByMigration(input.migrationSources, map.entityId, field)) continue
+      gaps.push({ moduleId: map.moduleId, entityId: map.entityId, field, missingScopes, totalScopes: activeScopes.size })
+    }
+  }
+  return gaps
+}
+
+const MAX_WARNING_ENTITIES = 20
+
+export function formatEncryptionBackfillWarning(gaps: readonly EncryptionBackfillGap[]): string {
+  const byEntity = new Map<string, { moduleId: string; fields: string[]; missingScopes: number; totalScopes: number }>()
+  for (const gap of gaps) {
+    const entry = byEntity.get(gap.entityId) ?? { moduleId: gap.moduleId, fields: [], missingScopes: 0, totalScopes: gap.totalScopes }
+    entry.fields.push(gap.field)
+    entry.missingScopes = Math.max(entry.missingScopes, gap.missingScopes)
+    byEntity.set(gap.entityId, entry)
+  }
+  const entities = [...byEntity.entries()]
+  const lines = entities
+    .slice(0, MAX_WARNING_ENTITIES)
+    .map(
+      ([entityId, entry]) =>
+        `   - ${entry.moduleId}: ${entityId} [${entry.fields.join(', ')}] (missing in ${entry.missingScopes}/${entry.totalScopes} tenant scopes)`,
+    )
+  if (entities.length > MAX_WARNING_ENTITIES) lines.push(`   … and ${entities.length - MAX_WARNING_ENTITIES} more entities`)
+  return [
+    '⚠️  Encryption maps declared in encryption.ts are missing for existing tenants, and no migration backfills them:',
+    ...lines,
+    '   Tenants that already exist keep writing these fields as plaintext. If the module may already be deployed,',
+    '   add a migration that calls buildEncryptionMapBackfillSql from @open-mercato/shared/lib/encryption/migration-backfill.',
+    '   Local database only: `yarn mercato entities seed-encryption --tenant <id>`. Silence with OM_ENCRYPTION_BACKFILL_CHECK=off.',
+  ].join('\n')
+}
+
+export async function checkEncryptionMapBackfills(deps: EncryptionBackfillCheckDeps): Promise<EncryptionBackfillGap[]> {
+  try {
+    const declared = await deps.loadDeclaredMaps()
+    if (!declared.length) return []
+    const rows = await deps.queryEncryptionMaps()
+    if (!rows?.length) return []
+    const gaps = findEncryptionBackfillGaps({ declared, rows, migrationSources: deps.loadMigrationSources() })
+    if (gaps.length) deps.warn(formatEncryptionBackfillWarning(gaps))
+    return gaps
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error)
+    deps.warn(`⚠️  Skipped the encryption map backfill check: ${message}`)
+    return []
+  }
+}

package/src/lib/db/migration-reindex.ts

@@ -1,5 +1,6 @@
 import fs from 'node:fs'
 import path from 'node:path'
+import { pathToFileURL } from 'node:url'
 import { parseBooleanWithDefault } from '@open-mercato/shared/lib/boolean'
 import {
   formatQueryIndexRebuildCommands,
@@ -58,7 +59,7 @@ export async function collectQueryIndexReindexEntityTypes(
     if (!filePath) continue
     let moduleExports: unknown
     try {
-      moduleExports = await deps.importModule(filePath)
+      moduleExports = await deps.importModule(pathToFileURL(path.resolve(filePath)).href)
     } catch (error) {
       deps.onWarn?.(
         `[query_index] Could not read reindex declarations from ${migration.moduleId}/${migration.name}: ${

package/src/lib/events-single-delivery.ts

@@ -2,8 +2,11 @@ import { parseBooleanWithDefault } from '@open-mercato/shared/lib/boolean'
 import type { AutoSpawnWorkersMode } from './auto-spawn-workers'
 
 // Keep these env names in sync with the runtime source of truth,
-// `@open-mercato/events/single-delivery`. The CLI cannot import the events
-// package (no dependency edge), so the reconcile logic is mirrored here for the
+// `@open-mercato/events/single-delivery`. This guard runs ahead of app
+// bootstrap (before the Postgres driver and the rest of the module graph
+// load), so it deliberately avoids importing `@open-mercato/events` here even
+// though the package is now a declared dependency (bin.ts's post-bootstrap
+// exit-flush uses it) — the reconcile logic is mirrored instead for this
 // server-bootstrap guard only; the bus and worker own the runtime behavior.
 //
 // This guard is the ONLY place that reconciles the flag against worker

package/src/lib/flush-before-exit.ts

@@ -0,0 +1,39 @@
+import { flushTelemetry } from './flush-telemetry'
+
+export type ExitFlushSteps = {
+  flushBroadcasts: () => Promise<void>
+  flushTelemetry: () => Promise<void>
+}
+
+async function flushPendingBrowserBroadcasts(): Promise<void> {
+  const { BROADCAST_FLUSH_DEADLINE_MS, flushPendingBroadcasts } = await import(
+    '@open-mercato/events/broadcast-coalescer'
+  )
+  await flushPendingBroadcasts({ deadlineMs: BROADCAST_FLUSH_DEADLINE_MS })
+}
+
+/**
+ * Runs before a returning CLI command's explicit `process.exit()`, which Node
+ * skips `beforeExit` for — the natural-exit path the broadcast-coalescer
+ * shutdown hook relies on to deliver a burst's trailing browser dispatch.
+ *
+ * The broadcast flush runs FIRST so its final `pg_notify` and the telemetry it
+ * produces are still captured by the telemetry flush that follows. It is capped
+ * at BROADCAST_FLUSH_DEADLINE_MS (3000ms), so a stalled Postgres connection at
+ * exit degrades to a dropped tail instead of hanging the command. Both steps are
+ * best-effort: neither can reject, and neither changes the command's exit code.
+ *
+ * Imported from the `broadcast-coalescer` deep path, and only after `run()` has
+ * bootstrapped the app, so it never loads the Postgres driver ahead of
+ * `initTelemetry()`.
+ */
+export async function flushBeforeExit(steps: Partial<ExitFlushSteps> = {}): Promise<void> {
+  const flushBroadcasts = steps.flushBroadcasts ?? flushPendingBrowserBroadcasts
+  try {
+    await flushBroadcasts()
+  } catch (error) {
+    const reason = error instanceof Error ? error.message : String(error)
+    console.warn(`[events] Broadcast flush on exit failed; the last browser refresh may be lost: ${reason}`)
+  }
+  await (steps.flushTelemetry ?? flushTelemetry)()
+}