@open-mercato/core 0.10.1-develop.7847.1.7d83dc5794 → 0.10.1-develop.7857.1.259928eb85

package/src/modules/attachments/lib/drivers/driverFactory.ts

@@ -3,40 +3,48 @@ import type { StorageDriver } from './types'
 import { LocalStorageDriver } from './localDriver'
 import { LegacyPublicStorageDriver } from './legacyPublicDriver'
 import { AttachmentPartition } from '../../data/entities'
-import { createLogger } from '@open-mercato/shared/lib/logger'
-
-const logger = createLogger('attachments').child({ component: 'storage-driver-factory' })
-
-type DriverScope = { tenantId: string; organizationId: string }
+import {
+  AttachmentStorageConfigurationError,
+  assertAttachmentStoragePartitionExists,
+  getAttachmentStoragePolicy,
+  validateAttachmentStorageConfiguration,
+  type AttachmentStorageScope,
+  type AttachmentStorageValidationStage,
+} from './storageValidation'
+
+type DriverScope = AttachmentStorageScope
 type CredentialEnhancer = (config: Record<string, unknown>, scope: DriverScope) => Promise<Record<string, unknown>>
+type DriverFactory = (config: Record<string, unknown>) => StorageDriver
 
-type DriverRegistration = { factory: (config: Record<string, unknown>) => StorageDriver }
-type EnhancerRegistration = { enhancer: CredentialEnhancer }
+type ModuleRegistry = {
+  drivers: Map<string, DriverFactory>
+  enhancers: Map<string, CredentialEnhancer>
+}
+const REGISTRY_KEY = Symbol.for('@open-mercato/AttachmentStorageDrivers')
 
-const moduleDriverRegistry = new Map<string, DriverRegistration>()
-const moduleEnhancerRegistry = new Map<string, EnhancerRegistration>()
+function moduleRegistry(): ModuleRegistry {
+  const registry = globalThis as typeof globalThis & { [REGISTRY_KEY]?: ModuleRegistry }
+  return registry[REGISTRY_KEY] ??= { drivers: new Map(), enhancers: new Map() }
+}
 
-export function registerExternalStorageDriver(
-  key: string,
-  factory: (config: Record<string, unknown>) => StorageDriver,
-): void {
-  moduleDriverRegistry.set(key, { factory })
+export function registerExternalStorageDriver(key: string, factory: DriverFactory): void {
+  moduleRegistry().drivers.set(key, factory)
 }
 
 export function registerExternalCredentialEnhancer(key: string, enhancer: CredentialEnhancer): void {
-  moduleEnhancerRegistry.set(key, { enhancer })
+  moduleRegistry().enhancers.set(key, enhancer)
 }
 
 export class StorageDriverFactory {
   private readonly cache = new Map<string, StorageDriver>()
-  private readonly localDriver = new LocalStorageDriver()
-  private readonly legacyPublicDriver = new LegacyPublicStorageDriver()
-  private readonly externalDrivers = new Map<string, (config: Record<string, unknown>) => StorageDriver>()
+  private localDriver?: LocalStorageDriver
+  private legacyPublicDriver?: LegacyPublicStorageDriver
+  private readonly externalDrivers = new Map<string, DriverFactory>()
   private readonly credentialEnhancers = new Map<string, CredentialEnhancer>()
 
   constructor(private readonly em: EntityManager) {}
 
-  registerDriver(key: string, factory: (config: Record<string, unknown>) => StorageDriver): void {
+  registerDriver(key: string, factory: DriverFactory): void {
     this.externalDrivers.set(key, factory)
   }
 
@@ -44,51 +52,67 @@ export class StorageDriverFactory {
     this.credentialEnhancers.set(key, enhancer)
   }
 
-  resolveForAttachment(
-    storageDriver: string,
-    configJson?: Record<string, unknown> | null,
-  ): StorageDriver {
-    switch (storageDriver) {
-      case 'legacyPublic':
-        return this.legacyPublicDriver
-
-      case 'local':
-        return this.localDriver
-
-      default: {
-        const externalFactory =
-          this.externalDrivers.get(storageDriver) ?? moduleDriverRegistry.get(storageDriver)?.factory
-        if (externalFactory) {
-          const cacheKey = `${storageDriver}:${JSON.stringify(configJson ?? {})}`
-          const cached = this.cache.get(cacheKey)
-          if (cached) return cached
-          const driver = externalFactory(configJson ?? {})
-          this.cache.set(cacheKey, driver)
-          return driver
-        }
-        return this.localDriver
-      }
-    }
+  resolveForAttachment(storageDriver: string, configJson?: Record<string, unknown> | null): StorageDriver {
+    const config = configJson ?? {}
+    this.validate(storageDriver, config, 'configured')
+    this.validate(storageDriver, config, 'resolved')
+    return this.resolveValidated(storageDriver, config)
   }
 
   async resolveForPartition(partitionCode: string, scope?: DriverScope): Promise<StorageDriver> {
+    getAttachmentStoragePolicy()
     const partition = await this.em.findOne(AttachmentPartition, { code: partitionCode })
-    if (!partition) return this.localDriver
+    assertAttachmentStoragePartitionExists(Boolean(partition))
+    if (!partition) return this.localDriver ??= new LocalStorageDriver()
 
-    const driverKey = partition.storageDriver ?? 'local'
-    logger.debug('Resolving storage driver for partition', { partition: partitionCode, driverKey, moduleDrivers: [...moduleDriverRegistry.keys()], instanceDrivers: [...this.externalDrivers.keys()] })
     let config: Record<string, unknown> = partition.configJson ?? {}
-
-    const activeEnhancer =
-      this.credentialEnhancers.get(driverKey) ?? moduleEnhancerRegistry.get(driverKey)?.enhancer
+    this.validate(partition.storageDriver, config, 'configured', partitionCode, scope)
+    const driverKey = partition.storageDriver ?? 'local'
+    const activeEnhancer = this.credentialEnhancers.get(driverKey) ?? moduleRegistry().enhancers.get(driverKey)
     if (scope && activeEnhancer) {
-      config = await activeEnhancer(config, scope)
-      // Skip shared cache for scope-enhanced configs (credentials are per-tenant)
-      const externalFactory =
-        this.externalDrivers.get(driverKey) ?? moduleDriverRegistry.get(driverKey)?.factory
+      try {
+        config = await activeEnhancer(config, scope)
+      } catch (error) {
+        if (getAttachmentStoragePolicy() === 'strict') {
+          throw new AttachmentStorageConfigurationError('enhancement_failed')
+        }
+        throw error
+      }
+      this.validate(driverKey, config, 'resolved', partitionCode, scope)
+      const externalFactory = this.externalDrivers.get(driverKey) ?? moduleRegistry().drivers.get(driverKey)
       if (externalFactory) return externalFactory(config)
+    } else {
+      this.validate(driverKey, config, 'resolved', partitionCode, scope)
     }
+    return this.resolveValidated(driverKey, config)
+  }
+
+  private validate(
+    driverKey: unknown,
+    config: unknown,
+    stage: AttachmentStorageValidationStage,
+    partitionCode?: string,
+    scope?: DriverScope,
+  ): void {
+    const registered = typeof driverKey === 'string' && (
+      driverKey === 'local' || driverKey === 'legacyPublic'
+      || this.externalDrivers.has(driverKey) || moduleRegistry().drivers.has(driverKey)
+    )
+    validateAttachmentStorageConfiguration({ driverKey, config, stage, partitionCode, scope }, registered)
+  }
 
-    return this.resolveForAttachment(driverKey, config)
+  private resolveValidated(driverKey: string, config: Record<string, unknown>): StorageDriver {
+    if (driverKey === 'legacyPublic') return this.legacyPublicDriver ??= new LegacyPublicStorageDriver()
+    if (driverKey === 'local') return this.localDriver ??= new LocalStorageDriver()
+    const externalFactory = this.externalDrivers.get(driverKey) ?? moduleRegistry().drivers.get(driverKey)
+    if (externalFactory) {
+      const cacheKey = `${driverKey}:${JSON.stringify(config)}`
+      const cached = this.cache.get(cacheKey)
+      if (cached) return cached
+      const driver = externalFactory(config)
+      this.cache.set(cacheKey, driver)
+      return driver
+    }
+    return this.localDriver ??= new LocalStorageDriver()
   }
 }

package/src/modules/attachments/lib/drivers/index.ts

@@ -2,3 +2,16 @@ export type { PrepareFilePayload, StorageDriver, StoreFilePayload, StoredFile, R
 export { LocalStorageDriver } from './localDriver'
 export { LegacyPublicStorageDriver } from './legacyPublicDriver'
 export { StorageDriverFactory, registerExternalStorageDriver, registerExternalCredentialEnhancer } from './driverFactory'
+
+export {
+  AttachmentStorageConfigurationError,
+  getAttachmentStoragePolicy,
+  isAttachmentStorageConfigurationError,
+  registerStorageDriverValidator,
+  type AttachmentStoragePolicy,
+  type AttachmentStorageScope,
+  type AttachmentStorageValidationStage,
+  type AttachmentStorageValidationContext,
+  type AttachmentStorageValidator,
+  type AttachmentStorageConfigurationReason,
+} from './storageValidation'

package/src/modules/attachments/lib/drivers/storageValidation.ts

@@ -0,0 +1,114 @@
+import type { z } from 'zod'
+import { CrudHttpError } from '@open-mercato/shared/lib/crud/errors'
+import { attachmentStorageConfigurationSchema, attachmentStorageScopeSchema } from '../../data/validators'
+
+export type AttachmentStoragePolicy = 'legacy' | 'strict'
+export type AttachmentStorageScope = z.infer<typeof attachmentStorageScopeSchema>
+export type AttachmentStorageValidationStage = 'configured' | 'resolved'
+export type AttachmentStorageValidationContext = {
+  readonly driverKey: string
+  readonly config: Readonly<Record<string, unknown>>
+  readonly partitionCode?: string
+  readonly scope?: Readonly<AttachmentStorageScope>
+  readonly stage: AttachmentStorageValidationStage
+}
+export type AttachmentStorageValidator = (context: AttachmentStorageValidationContext) => boolean
+export type AttachmentStorageConfigurationReason =
+  | 'invalid_policy'
+  | 'partition_missing'
+  | 'driver_missing'
+  | 'unknown_driver'
+  | 'invalid_config'
+  | 'invalid_scope'
+  | 'validator_missing'
+  | 'validator_rejected'
+  | 'enhancement_failed'
+
+const ERROR_MARKER = Symbol.for('@open-mercato/AttachmentStorageConfigurationError')
+const VALIDATORS_KEY = Symbol.for('@open-mercato/AttachmentStorageValidators')
+type ValidatorRegistry = Map<string, AttachmentStorageValidator>
+
+function validators(): ValidatorRegistry {
+  const registry = globalThis as typeof globalThis & { [VALIDATORS_KEY]?: ValidatorRegistry }
+  return registry[VALIDATORS_KEY] ??= new Map()
+}
+
+export class AttachmentStorageConfigurationError extends CrudHttpError {
+  readonly [ERROR_MARKER] = true
+  readonly code = 'ATTACHMENT_STORAGE_CONFIGURATION_INVALID'
+
+  constructor(readonly reason: AttachmentStorageConfigurationReason) {
+    super(503, {
+      error: 'attachments.errors.storageConfigurationInvalid',
+      code: 'ATTACHMENT_STORAGE_CONFIGURATION_INVALID',
+      reason,
+    })
+    this.name = 'AttachmentStorageConfigurationError'
+  }
+}
+
+export function isAttachmentStorageConfigurationError(error: unknown): error is AttachmentStorageConfigurationError {
+  return Boolean(error) && typeof error === 'object'
+    && (error as Record<symbol, unknown>)[ERROR_MARKER] === true
+}
+
+export function getAttachmentStoragePolicy(): AttachmentStoragePolicy {
+  const policy = process.env.OM_ATTACHMENT_STORAGE_POLICY?.trim()
+  if (!policy || policy === 'legacy') return 'legacy'
+  if (policy === 'strict') return 'strict'
+  throw new AttachmentStorageConfigurationError('invalid_policy')
+}
+
+export function registerStorageDriverValidator(key: string, validator: AttachmentStorageValidator): () => void {
+  const registry = validators()
+  registry.set(key, validator)
+  return () => {
+    if (registry.get(key) === validator) registry.delete(key)
+  }
+}
+
+export function assertAttachmentStoragePartitionExists(exists: boolean): void {
+  if (getAttachmentStoragePolicy() === 'strict' && !exists) {
+    throw new AttachmentStorageConfigurationError('partition_missing')
+  }
+}
+
+export function validateAttachmentStorageConfiguration(
+  context: Omit<AttachmentStorageValidationContext, 'driverKey' | 'config'> & {
+    driverKey: unknown
+    config: unknown
+  },
+  registered: boolean,
+): void {
+  if (getAttachmentStoragePolicy() === 'legacy') return
+  if (typeof context.driverKey !== 'string' || !context.driverKey.trim()) {
+    throw new AttachmentStorageConfigurationError('driver_missing')
+  }
+  if (!registered) throw new AttachmentStorageConfigurationError('unknown_driver')
+  if (!attachmentStorageConfigurationSchema.safeParse(context.config).success) {
+    throw new AttachmentStorageConfigurationError('invalid_config')
+  }
+  if (context.scope && !attachmentStorageScopeSchema.safeParse(context.scope).success) {
+    throw new AttachmentStorageConfigurationError('invalid_scope')
+  }
+  const validator = validators().get(context.driverKey)
+  if (!validator) {
+    if (context.driverKey === 'local' || context.driverKey === 'legacyPublic') return
+    throw new AttachmentStorageConfigurationError('validator_missing')
+  }
+  try {
+    const accepted: unknown = validator({
+      ...context,
+      driverKey: context.driverKey,
+      config: context.config as Record<string, unknown>,
+    })
+    if (accepted !== true) {
+      if (accepted && typeof accepted === 'object' && 'then' in accepted) {
+        void Promise.resolve(accepted).catch(() => undefined)
+      }
+      throw new AttachmentStorageConfigurationError('validator_rejected')
+    }
+  } catch {
+    throw new AttachmentStorageConfigurationError('validator_rejected')
+  }
+}

package/src/modules/attachments/lib/scoped-upload-service.ts

@@ -7,6 +7,7 @@ import { createLogger } from '@open-mercato/shared/lib/logger'
 import { Attachment, AttachmentPartition } from '../data/entities'
 import { attachmentCrudEvents, attachmentCrudIndexer } from './crud'
 import type { StorageDriverFactory } from './drivers'
+import { assertAttachmentStoragePartitionExists, getAttachmentStoragePolicy } from './drivers/storageValidation'
 import { buildAttachmentFileUrl } from './imageUrls'
 import { ensureAttachmentPartitionProtection } from './access-protection'
 import { ensureDefaultPartitions, resolveDefaultPartitionCode } from './partitions'
@@ -129,7 +130,7 @@ export class ScopedAttachmentUploadService {
     }
 
     const { em, storageDriverFactory, attachmentQuotaService, attachmentQuotaRecoveryScheduler } = this.deps
-    await ensureDefaultPartitions(em)
+    if (getAttachmentStoragePolicy() === 'legacy') await ensureDefaultPartitions(em)
     const partitionCode = input.partitionCode ?? resolveDefaultPartitionCode(input.entityId)
     const partition = await em.findOne(AttachmentPartition, {
       code: partitionCode,
@@ -138,6 +139,7 @@ export class ScopedAttachmentUploadService {
         { tenantId: input.tenantId, organizationId: input.organizationId },
       ],
     })
+    assertAttachmentStoragePartitionExists(Boolean(partition))
     if (!partition) throw new ScopedAttachmentUploadError('partition_unavailable', 400)
     if (input.requirePrivatePartition && partition.isPublic) {
       throw new ScopedAttachmentUploadError('partition_unavailable', 403)

package/src/modules/attachments/lib/storageErrors.ts

@@ -0,0 +1,21 @@
+import { NextResponse } from 'next/server'
+import { resolveTranslations } from '@open-mercato/shared/lib/i18n/server'
+import { isAttachmentStorageConfigurationError } from './drivers/storageValidation'
+
+export function withAttachmentStorageErrors<Args extends unknown[]>(
+  handler: (...args: Args) => Promise<Response>,
+): (...args: Args) => Promise<Response> {
+  return async (...args) => {
+    try {
+      return await handler(...args)
+    } catch (error) {
+      if (!isAttachmentStorageConfigurationError(error)) throw error
+      const { t } = await resolveTranslations()
+      return NextResponse.json({
+        error: t('attachments.errors.storageConfigurationInvalid', 'Attachment storage configuration is unavailable.'),
+        code: error.code,
+        reason: error.reason,
+      }, { status: 503 })
+    }
+  }
+}

package/src/modules/customer_accounts/AGENTS.md

@@ -319,7 +319,7 @@ Both link to `/backend/customer_accounts/{sourceEntityId}` for staff review.
 | Spot ID | Widget | Purpose |
 |---------|--------|---------|
 | `customers.person` | `account-status` | Alias for hosts requesting the bare `customers.person` entity spot |
-| `crud-form:customers.person` | `account-status` | Shows portal account status on the person v2 detail page (`people-v2/[id]`) |
+| `crud-form:customers.person` | `account-status` | Person detail/create, company/sales dialogs; hidden without `recordId` |
 | `customers.company` | `company-users` | Alias for hosts requesting the bare `customers.company` entity spot |
 | `crud-form:customers.company` | `company-users` | Shows portal users on every company surface that publishes the host — the company v2 detail page (`companies-v2/[id]`), the company create page (`companies/create`), and the sales document "Create company" quick dialog — where it has no `recordId` and renders its empty state |
 

package/src/modules/customers/api/companies/[id]/route.ts

@@ -38,6 +38,7 @@ import {
   mapInteractionRecordToTodoSummary,
 } from '../../../lib/interactionCompatibility'
 import { resolveCustomerInteractionFeatureFlags } from '../../../lib/interactionFeatureFlags'
+import { countCustomerTodos } from '../../../lib/todoCompatibility'
 import { hydrateCanonicalInteractions } from '../../../lib/interactionReadModel'
 import { buildEmailVisibilityMikroFilter } from '../../../lib/visibilityFilter'
 import { listGrantsForViewer, listSharedChannelIds } from '../../../lib/conversationShares'
@@ -895,19 +896,11 @@ export async function GET(_req: Request, ctx: { params?: { id?: string } }) {
       deletedAt: null,
       ...emailVisibilityFilter,
     }),
-    interactionFlags.unified
-      ? em.count(CustomerInteraction, {
-          entity: company.id,
-          organizationId: company.organizationId,
-          tenantId: company.tenantId,
-          deletedAt: null,
-          interactionType: 'task',
-        })
-      : em.count(CustomerTodoLink, {
-          entity: company.id,
-          organizationId: company.organizationId,
-          tenantId: company.tenantId,
-        }),
+    countCustomerTodos(em, {
+      entityId: company.id,
+      organizationId: company.organizationId,
+      tenantId: company.tenantId,
+    }, interactionFlags.unified),
     includeComments
       ? Promise.resolve(comments.length)
       : em.count(CustomerComment, {

package/src/modules/customers/api/people/[id]/route.ts

@@ -34,6 +34,7 @@ import {
   mapInteractionRecordToTodoSummary,
 } from '../../../lib/interactionCompatibility'
 import { resolveCustomerInteractionFeatureFlags } from '../../../lib/interactionFeatureFlags'
+import { countCustomerTodos } from '../../../lib/todoCompatibility'
 import { hydrateCanonicalInteractions } from '../../../lib/interactionReadModel'
 import type { QueryEngine } from '@open-mercato/shared/lib/query/types'
 import type { EntityId } from '@open-mercato/shared/modules/entities'
@@ -878,19 +879,11 @@ export async function GET(_req: Request, ctx: { params?: { id?: string } }) {
         deletedAt: null,
         ...emailVisibilityFilter,
       }),
-      interactionFlags.unified
-        ? em.count(CustomerInteraction, {
-            entity: person.id,
-            organizationId: person.organizationId,
-            tenantId: person.tenantId,
-            deletedAt: null,
-            interactionType: 'task',
-          })
-        : em.count(CustomerTodoLink, {
-            entity: person.id,
-            organizationId: person.organizationId,
-            tenantId: person.tenantId,
-          }),
+      countCustomerTodos(em, {
+        entityId: person.id,
+        organizationId: person.organizationId,
+        tenantId: person.tenantId,
+      }, interactionFlags.unified),
       includeAddresses
         ? Promise.resolve(addresses.length)
         : em.count(CustomerAddress, {

package/src/modules/customers/components/detail/TaskDialog.tsx

@@ -45,6 +45,8 @@ export function TaskDialog({ open, mode, onOpenChange, initialValues, onSubmit,
         event.currentTarget.querySelector('form')?.requestSubmit()
       }
       if (event.key === 'Escape') {
+        if (event.defaultPrevented) return
+        if (event.target instanceof Node && !event.currentTarget.contains(event.target)) return
         event.preventDefault()
         handleCancel()
       }

package/src/modules/customers/lib/todoCompatibility.ts

@@ -10,6 +10,7 @@ import {
 import type { InteractionRecord } from './interactionCompatibility'
 import {
   CUSTOMER_INTERACTION_TASK_SOURCE,
+  CUSTOMER_INTERACTION_TODO_ADAPTER_SOURCE,
   EXAMPLE_TODO_SOURCE,
   resolveExampleIntegrationHref,
 } from './interactionCompatibility'
@@ -18,6 +19,33 @@ import { createLogger } from '@open-mercato/shared/lib/logger'
 
 const logger = createLogger('customers')
 
+export async function countCustomerTodos(
+  em: EntityManager,
+  scope: { entityId: string; tenantId: string; organizationId: string },
+  unified: boolean,
+): Promise<number> {
+  const entityScope = {
+    entity: scope.entityId,
+    tenantId: scope.tenantId,
+    organizationId: scope.organizationId,
+  }
+  if (unified) {
+    return em.count(CustomerInteraction, { ...entityScope, interactionType: 'task', deletedAt: null })
+  }
+
+  const adapterScope = {
+    ...entityScope,
+    interactionType: 'task',
+    source: CUSTOMER_INTERACTION_TODO_ADAPTER_SOURCE,
+  }
+  const adapterIds = em.createQueryBuilder(CustomerInteraction).select('id').where(adapterScope)
+  const [legacyCount, adapterCount] = await Promise.all([
+    em.count(CustomerTodoLink, { ...entityScope, todoId: { $nin: adapterIds } }),
+    em.count(CustomerInteraction, { ...adapterScope, deletedAt: null }),
+  ])
+  return legacyCount + adapterCount
+}
+
 export type CustomerTodoRow = {
   id: string
   todoId: string

package/src/modules/sales/AGENTS.md

@@ -5,7 +5,7 @@ Use the sales module for orders, quotes, invoices, shipments, and payments. This
 ## Always
 
 1. **MUST use `salesCalculationService` from DI** for document math.
-2. **MUST follow document flow**: Quote → Order → Invoice — no skipping steps
+2. **MUST follow document flow**: Quote → Order → Invoice (quote optional)
 3. **MUST scope all documents to a channel** — channel selection affects pricing, numbering, and visibility
 
 ## Ask First
@@ -36,7 +36,7 @@ Quote → Order → Invoice
     Shipments + Payments
 ```
 
-- Quotes convert to orders — MUST NOT create orders without a source quote (unless configured)
+- Quotes convert via `sales.quotes.convert_to_order`; orders MAY also be created without a quote
 - Orders track shipments and payments independently
 - Each entity has its own status workflow — MUST NOT skip workflow states
 
@@ -56,7 +56,7 @@ const calcService = container.resolve('salesCalculationService')
 
 ### Core Entities
 - **Sales Orders** — confirmed customer orders. MUST have a channel and at least one line
-- **Sales Quotes** — proposed orders. MUST track conversion status
+- **Sales Quotes** — proposed orders; deleted on conversion
 - **Order/Quote Lines** — individual items. MUST reference valid products
 - **Adjustments** — discounts/surcharges. MUST use registered `AdjustmentKind`