@open-mercato/core 0.8.1-develop.7221.1.ece7ca874e → 0.8.1-develop.7227.1.9248c14599

package/src/modules/communication_channels/lib/adapter.ts

@@ -368,7 +368,10 @@ export interface ApplyPushNotificationInput {
 export interface ImportHistoryInput {
   credentials: Record<string, unknown>
   scope: TenantScope
-  /** Look back at most this many days. Clamped 1..365 by the hub. */
+  /**
+   * Look back at most this many days. The hub accepts 1..`OM_IMPORT_HISTORY_MAX_SINCE_DAYS`
+   * (default ceiling 3650, i.e. ten years) and defaults to 30 when omitted.
+   */
   sinceDays: number
   /**
    * Optional sender-filter hint. Adapters SHOULD use it for server-side
@@ -376,7 +379,10 @@ export interface ImportHistoryInput {
    * import scans the entire `SINCE` window.
    */
   contactEmails?: string[]
-  /** Total cap across all pages. Hub default 1000. Adapter MUST respect. */
+  /**
+   * Total cap across all pages. Hub default 1000, accepted up to
+   * `OM_IMPORT_HISTORY_MAX_MESSAGES` (default ceiling 50000). Adapter MUST respect.
+   */
   maxMessages?: number
   /** Opaque resumption cursor returned by the previous page. */
   cursor?: string
@@ -519,6 +525,14 @@ export interface ValidateCredentialsResult {
    * that don't emit codes keep working and callers fall back to `errors`.
    */
   errorCodes?: Record<string, string>
+  /**
+   * Stable identity of the connected account, for providers whose credentials
+   * carry no email-shaped `username` / `email` / `fromAddress` (e.g. a Discord
+   * bot). When present on a successful validation the connect flow uses it as
+   * `CommunicationChannel.externalIdentifier`, so reconnecting the same account
+   * heals the existing channel instead of inserting a duplicate row.
+   */
+  externalIdentifier?: string
 }
 
 // ── The adapter contract ─────────────────────────────────────

package/src/modules/communication_channels/lib/connect-channel.ts

@@ -1,4 +1,5 @@
 import type { EntityManager } from '@mikro-orm/postgresql'
+import { withAtomicFlush } from '@open-mercato/shared/lib/commands/flush'
 import { findOneWithDecryption, findWithDecryption } from '@open-mercato/shared/lib/encryption/find'
 import { CommunicationChannel } from '../data/entities'
 import type { ChannelAdapter } from './adapter'
@@ -44,6 +45,14 @@ export interface CreateConnectedChannelRowArgs {
    * the adapter's push capability (push-capable → null, polling-only → 300).
    */
   pollIntervalSeconds?: number | null
+  /**
+   * The identifier was reported by the adapter itself (not sniffed from the
+   * credential bag). Rows this user created for the same provider before the
+   * adapter reported one carry `external_identifier = NULL` and would never match
+   * the heal key, so the newest such row is adopted instead of inserting another
+   * one next to it.
+   */
+  adoptUnidentifiedChannel?: boolean
 }
 
 /**
@@ -163,6 +172,46 @@ export async function createConnectedChannelRow(
     }
   }
 
+  if (args.adoptUnidentifiedChannel && effectiveExternalIdentifier && !isTenantWidePush) {
+    const unidentified = (await findWithDecryption(
+      em,
+      CommunicationChannel,
+      { tenantId: scope.tenantId, userId, providerKey, externalIdentifier: null, deletedAt: null },
+      { orderBy: { createdAt: 'desc' } },
+      dscope,
+    )) as CommunicationChannel[]
+    const [adopted, ...superseded] = unidentified
+    if (adopted) {
+      // Per-user credentials are stored once per provider, so every older
+      // identifier-less row is a duplicate of the adopted one. Left active, a
+      // stuck `requires_reauth` duplicate would keep its reauth banner forever.
+      const inheritsPrimary = superseded.some((duplicate) => duplicate.isPrimary)
+      // Postgres checks the partial `communication_channels_one_primary_per_user_uq`
+      // index per statement and one flush does not order the SET-false before
+      // the SET-true, so the old primary is cleared in its own phase (each phase
+      // flushes) before the adopted row takes the flag, inside one transaction.
+      await withAtomicFlush(
+        em,
+        [
+          () => {
+            for (const duplicate of superseded) {
+              duplicate.isActive = false
+              duplicate.isPrimary = false
+              duplicate.status = 'disconnected'
+              duplicate.lastError = 'superseded_by_reconnect'
+            }
+          },
+          () => {
+            applyConnectionState(adopted)
+            if (inheritsPrimary) adopted.isPrimary = true
+          },
+        ],
+        { transaction: true },
+      )
+      return adopted
+    }
+  }
+
   const channel = em.create(CommunicationChannel, {
     providerKey,
     channelType: adapter.channelType,

package/src/modules/communication_channels/lib/import-history-limits.ts

@@ -0,0 +1,109 @@
+/**
+ * Single source of truth for the operator-triggered history-import bounds.
+ *
+ * Defaults are the values a request gets when it omits the field; ceilings are
+ * the largest value the hub accepts. Ceilings are deliberately wide enough for
+ * a multi-year backfill and can be raised or lowered per deployment through
+ * `OM_IMPORT_HISTORY_MAX_SINCE_DAYS` / `OM_IMPORT_HISTORY_MAX_MESSAGES`.
+ *
+ * Env is read at call time (not module load) so a deployment can change the
+ * ceiling without a rebuild, and so tests can exercise the override. In the
+ * browser bundle the variables are absent and the built-in ceilings apply —
+ * client-side validation is a UX affordance, the API remains the authority.
+ */
+
+export const IMPORT_HISTORY_DEFAULT_SINCE_DAYS = 30
+export const IMPORT_HISTORY_DEFAULT_MAX_MESSAGES = 1000
+
+export const IMPORT_HISTORY_MAX_SINCE_DAYS_FALLBACK = 3650
+export const IMPORT_HISTORY_MAX_MESSAGES_FALLBACK = 50000
+
+export const IMPORT_HISTORY_MAX_CONTACT_EMAILS = 200
+
+export const IMPORT_HISTORY_MIN_PAGE_BUDGET = 100
+export const IMPORT_HISTORY_ABSOLUTE_MAX_PAGES = 10000
+
+/**
+ * Consecutive pages that may return no messages while the adapter still claims
+ * `hasMore` and advances its cursor. Empty pages are legitimate: the Gmail
+ * adapter drops messages that returned 404/410 between listing and fetching,
+ * and server-side filters can eliminate a whole page. A stuck adapter is caught
+ * by the repeated-cursor check, so this counter only has to bound the run when
+ * the cursor keeps moving but nothing is ever returned.
+ */
+export const IMPORT_HISTORY_MAX_EMPTY_PAGES = 10
+
+export const IMPORT_HISTORY_MAX_SINCE_DAYS_ENV = 'OM_IMPORT_HISTORY_MAX_SINCE_DAYS'
+export const IMPORT_HISTORY_MAX_MESSAGES_ENV = 'OM_IMPORT_HISTORY_MAX_MESSAGES'
+
+export type ImportHistoryLimits = {
+  defaultSinceDays: number
+  defaultMaxMessages: number
+  maxSinceDays: number
+  maxMessages: number
+}
+
+function readPositiveIntEnv(name: string, fallback: number): number {
+  const raw = typeof process !== 'undefined' ? process.env?.[name] : undefined
+  const parsed = Number.parseInt(raw ?? '', 10)
+  return Number.isFinite(parsed) && parsed > 0 ? parsed : fallback
+}
+
+export function getImportHistoryMaxSinceDays(): number {
+  return Math.max(
+    IMPORT_HISTORY_DEFAULT_SINCE_DAYS,
+    readPositiveIntEnv(IMPORT_HISTORY_MAX_SINCE_DAYS_ENV, IMPORT_HISTORY_MAX_SINCE_DAYS_FALLBACK),
+  )
+}
+
+export function getImportHistoryMaxMessages(): number {
+  return Math.max(
+    IMPORT_HISTORY_DEFAULT_MAX_MESSAGES,
+    readPositiveIntEnv(IMPORT_HISTORY_MAX_MESSAGES_ENV, IMPORT_HISTORY_MAX_MESSAGES_FALLBACK),
+  )
+}
+
+/**
+ * Per-provider ceilings, lower than the deployment-wide ceiling above.
+ *
+ * The IMAP adapter's cursor embeds the *entire* remaining UID list discovered
+ * by `SEARCH` (unlike Gmail's opaque `nextPageToken` cursor), so a wide ceiling
+ * there means a multi-megabyte cursor round-tripping through the worker on
+ * every page. Until that adapter gets a paging cursor of its own, its ceiling
+ * stays at the pre-widening values so the dialog, the hub's validation, and the
+ * adapter's own clamp (`packages/channel-imap/.../adapter.ts`) agree — a
+ * request above this is rejected rather than silently truncated.
+ */
+const PROVIDER_MAX_SINCE_DAYS: Record<string, number> = {
+  imap: 365,
+}
+const PROVIDER_MAX_MESSAGES: Record<string, number> = {
+  imap: 5000,
+}
+
+export function getImportHistoryLimits(providerKey?: string): ImportHistoryLimits {
+  const maxSinceDays = getImportHistoryMaxSinceDays()
+  const maxMessages = getImportHistoryMaxMessages()
+  const providerMaxSinceDays = providerKey ? PROVIDER_MAX_SINCE_DAYS[providerKey] : undefined
+  const providerMaxMessages = providerKey ? PROVIDER_MAX_MESSAGES[providerKey] : undefined
+  return {
+    defaultSinceDays: IMPORT_HISTORY_DEFAULT_SINCE_DAYS,
+    defaultMaxMessages: IMPORT_HISTORY_DEFAULT_MAX_MESSAGES,
+    maxSinceDays: providerMaxSinceDays !== undefined ? Math.min(maxSinceDays, providerMaxSinceDays) : maxSinceDays,
+    maxMessages: providerMaxMessages !== undefined ? Math.min(maxMessages, providerMaxMessages) : maxMessages,
+  }
+}
+
+/**
+ * Page budget for the import drain loop, derived from the effective message cap
+ * so a large import is never truncated before it reaches that cap. It is only a
+ * backstop: an adapter that never makes progress is stopped much earlier by the
+ * consecutive-empty-page guard.
+ */
+export function resolveImportHistoryPageBudget(maxMessages: number): number {
+  if (!Number.isFinite(maxMessages) || maxMessages <= 0) return IMPORT_HISTORY_MIN_PAGE_BUDGET
+  return Math.min(
+    IMPORT_HISTORY_ABSOLUTE_MAX_PAGES,
+    Math.max(IMPORT_HISTORY_MIN_PAGE_BUDGET, Math.ceil(maxMessages)),
+  )
+}

package/src/modules/communication_channels/workers/channel-import-history.ts

@@ -10,6 +10,10 @@ import {
 import { COMMUNICATION_CHANNELS_QUEUES } from '../lib/queue'
 import { refreshCredentialsIfNeeded } from '../lib/credential-refresh'
 import { classifyOutboundError } from '../lib/error-classification'
+import {
+  IMPORT_HISTORY_MAX_EMPTY_PAGES,
+  resolveImportHistoryPageBudget,
+} from '../lib/import-history-limits'
 import type { ChannelAdapterRegistry } from '../lib/registry'
 import type {
   ChannelImportHistoryJobPayload,
@@ -159,16 +163,21 @@ export default async function handle(
     let totalCount = maxMessages
     let firstPage = true
 
-    // Bounded loop guards against a misbehaving adapter (infinite hasMore).
-    // 100 pages * HARD_CAP (default 200) = 20k messages — far above the 5k cap
-    // enforced by the schema, so this only trips on adapter bugs.
-    const MAX_PAGES = 100
-    for (let pageIndex = 0; pageIndex < MAX_PAGES; pageIndex += 1) {
+    // Guards against an adapter that claims `hasMore` forever. An empty page is
+    // NOT a fault on its own — adapters legitimately drop every message on a
+    // page (Gmail 404/410 between listing and fetching, server-side filters) —
+    // so the hard stop is a cursor that stops advancing; the empty-page counter
+    // and the page budget are backstops.
+    const maxPages = resolveImportHistoryPageBudget(maxMessages)
+    let consecutiveEmptyPages = 0
+    let truncationReason: string | null = null
+    for (let pageIndex = 0; pageIndex < maxPages; pageIndex += 1) {
       if (await progressService.isCancellationRequested(progressJobId, scope.tenantId, scope.organizationId)) {
         await progressService.markCancelled(progressJobId, progressContext)
         return
       }
 
+      const requestedCursor = cursor
       const page = await adapter.importHistory!({
         credentials,
         scope: { tenantId: scope.tenantId, organizationId: scope.organizationId },
@@ -178,6 +187,21 @@ export default async function handle(
         cursor,
       })
 
+      if (page.hasMore && page.nextCursor !== undefined && page.nextCursor === requestedCursor) {
+        truncationReason = 'adapter repeated the same pagination cursor'
+        break
+      }
+
+      if (page.messages.length === 0 && page.hasMore) {
+        consecutiveEmptyPages += 1
+        if (consecutiveEmptyPages >= IMPORT_HISTORY_MAX_EMPTY_PAGES) {
+          truncationReason = `adapter returned no messages on ${consecutiveEmptyPages} consecutive pages`
+          break
+        }
+      } else {
+        consecutiveEmptyPages = 0
+      }
+
       if (firstPage && typeof page.totalCandidates === 'number') {
         totalCount = Math.min(maxMessages, page.totalCandidates)
         await progressService.updateProgress(
@@ -225,6 +249,23 @@ export default async function handle(
       if (processedCount >= maxMessages) break
       if (!page.hasMore || !page.nextCursor) break
       cursor = page.nextCursor
+      if (pageIndex === maxPages - 1) {
+        truncationReason = `page budget of ${maxPages} exhausted while the adapter still reported more messages`
+      }
+    }
+
+    if (truncationReason) {
+      // Surfaced as a failed job on purpose: the operator must see that the
+      // backlog is incomplete rather than a clean "imported N" summary.
+      logger.warn('history import stopped early', { channelId: channel.id, reason: truncationReason, processedCount })
+      await progressService.failJob(
+        progressJobId,
+        {
+          errorMessage: `History import stopped early after ${processedCount} messages: ${truncationReason}`,
+        },
+        progressContext,
+      )
+      return
     }
 
     await progressService.completeJob(

package/src/modules/messages/api/route.ts

@@ -470,8 +470,14 @@ export async function POST(req: Request) {
         sourceHint.data,
       )
     : undefined
-  const { sourceChannelType: _clientSuppliedChannelType, ...clientBody } =
-    (body ?? {}) as Record<string, unknown>
+  // `inboundFromChannel` is likewise server-only (#6093): channel ingest sets
+  // it so an inbound message can be addressed to the conversation's assignee,
+  // and a request body must not be able to waive the recipients rule with it.
+  const {
+    sourceChannelType: _clientSuppliedChannelType,
+    inboundFromChannel: _clientSuppliedInboundFlag,
+    ...clientBody
+  } = (body ?? {}) as Record<string, unknown>
   const input = composeMessageSchema.parse({
     ...clientBody,
     ...(sourceChannelType ? { sourceChannelType } : {}),

package/src/modules/messages/commands/messages.ts

@@ -30,6 +30,13 @@ type MessageSentEventPayload = {
   senderUserId: string
   recipientUserIds: string[]
   sendViaEmail: boolean
+  /**
+   * The message arrived from an external channel (#6093). Its `senderUserId`
+   * is the channel's system user and its real correspondent lives in
+   * `externalName` / `externalEmail`; subscribers that show a sender read it
+   * from there.
+   */
+  inboundFromChannel?: boolean
   externalEmail?: string | null
   forwardedFrom?: string
   replyTo?: string
@@ -303,7 +310,13 @@ const composeMessageCommand: CommandHandler<unknown, { id: string; threadId: str
         : undefined
 
       const isPublicVisibility = input.visibility === 'public'
-      const sendViaEmail = isPublicVisibility ? true : input.sendViaEmail
+      // #6093: a channel-ingested message was RECEIVED, not sent. Ingest passes
+      // `sendViaEmail: false` on purpose; forcing it for public visibility would
+      // mail the assignee a copy and echo the message to its external sender
+      // (#6089) the moment the recipients waiver lets it compose. #6090 removes
+      // the forcing for every caller; until then it is skipped here for the
+      // ingest path only.
+      const sendViaEmail = isPublicVisibility && !input.inboundFromChannel ? true : input.sendViaEmail
       const message = trx.create(Message, {
         type: input.type,
         visibility: input.visibility ?? null,
@@ -407,7 +420,9 @@ const composeMessageCommand: CommandHandler<unknown, { id: string; threadId: str
         messageId,
         senderUserId: input.userId,
         recipientUserIds: input.recipients.map((recipient) => recipient.userId),
-        sendViaEmail: input.visibility === 'public' ? true : input.sendViaEmail,
+        sendViaEmail:
+          input.visibility === 'public' && !input.inboundFromChannel ? true : input.sendViaEmail,
+        inboundFromChannel: input.inboundFromChannel === true,
         externalEmail: responseExternalEmail,
         tenantId: input.tenantId,
         organizationId: input.organizationId,

package/src/modules/messages/data/validators.ts

@@ -116,6 +116,16 @@ const composeMessageBaseSchema = z.object({
    * asserting its own channel type.
    */
   sourceChannelType: z.string().min(1).max(64).optional(),
+  /**
+   * Set by channel ingest for a message that arrived FROM an external channel
+   * (#6093). On such a message `recipients` are not external addressees — a
+   * public message has none — but the internal users the hub routes it to
+   * (the conversation's assignee), so the "no recipients on a public message"
+   * rule does not apply. Server-only like `sourceChannelType`: the HTTP route
+   * strips any client-sent value, so a caller cannot waive the rule by
+   * asserting its message came in from a channel.
+   */
+  inboundFromChannel: z.boolean().optional(),
   recipients: z.array(messageRecipientSchema).max(100).optional().default([]),
   subject: z.string().max(500).optional().default(''),
   body: z.string().max(50000).optional().default(''),
@@ -155,7 +165,11 @@ function refineComposeMessage(value: ComposeMessageRefinementValue, ctx: z.Refin
           message: 'externalEmail is required when visibility is public',
         })
       }
-      if (recipientCount > 0) {
+      // #6093: a channel-ingested message is addressed to the assignee of its
+      // conversation; that recipient is internal routing, not a second
+      // external addressee, so only a user-composed public message is bound
+      // by this rule.
+      if (recipientCount > 0 && !value.inboundFromChannel) {
         ctx.addIssue({
           code: z.ZodIssueCode.custom,
           path: ['recipients'],
@@ -199,22 +213,23 @@ function refineComposeMessage(value: ComposeMessageRefinementValue, ctx: z.Refin
 }
 
 /**
- * Full compose contract, including the server-resolved `sourceChannelType`.
- * Used by the `messages.messages.compose` command and by the HTTP route AFTER
- * it has resolved the channel type itself.
+ * Full compose contract, including the server-resolved `sourceChannelType` and
+ * the ingest-only `inboundFromChannel`. Used by the `messages.messages.compose`
+ * command and by the HTTP route AFTER it has resolved the channel type itself.
  */
 export const composeMessageSchema = composeMessageBaseSchema.superRefine(refineComposeMessage)
 
 /**
- * Client-facing compose contract — the same rules minus `sourceChannelType`,
- * which is never accepted from a request body (#4975). Published in OpenAPI so
- * the documented request shape matches what `POST /api/messages` actually reads:
- * the route discards any client-sent channel type, resolves the real one from
- * the referenced conversation or parent message, and only then validates against
- * {@link composeMessageSchema}.
+ * Client-facing compose contract — the same rules minus the server-only fields:
+ * `sourceChannelType` is never accepted from a request body (#4975) and neither
+ * is `inboundFromChannel` (#6093). Published in OpenAPI so the documented
+ * request shape matches what `POST /api/messages` actually reads: the route
+ * discards any client-sent value for these, resolves the real channel type from
+ * the referenced conversation or parent message, and only then validates
+ * against {@link composeMessageSchema}.
  */
 export const composeMessageRequestSchema = composeMessageBaseSchema
-  .omit({ sourceChannelType: true })
+  .omit({ sourceChannelType: true, inboundFromChannel: true })
   .superRefine(refineComposeMessage)
 
 export const updateDraftSchema = z.object({

package/src/modules/messages/subscribers/message-notification.ts

@@ -22,6 +22,8 @@ type MessageSentPayload = {
   senderUserId: string
   recipientUserIds: string[]
   sendViaEmail: boolean
+  /** Set by compose for channel-ingested messages (#6093); see `resolveNotificationVariables`. */
+  inboundFromChannel?: boolean
   externalEmail?: string | null
   forwardedFrom?: string
   replyTo?: string
@@ -72,13 +74,23 @@ async function resolveNotificationVariables(payload: MessageSentPayload, ctx: Re
       ),
     ])
 
+    // #6093: a channel-ingested message is composed on behalf of the channel's
+    // system user (or, without one, the assignee), so `senderUserId` is not who
+    // wrote it. The correspondent is on the message itself.
+    const externalFrom = payload.inboundFromChannel
+      ? [message?.externalName, message?.externalEmail].find(
+          (value): value is string => typeof value === 'string' && value.trim().length > 0,
+        )
+      : undefined
+
     return {
       title: typeof message?.subject === 'string' ? message.subject : '',
-      from: typeof sender?.name === 'string' && sender.name.trim().length > 0
-        ? sender.name
-        : typeof sender?.email === 'string'
-          ? sender.email
-          : '',
+      from: externalFrom
+        ?? (typeof sender?.name === 'string' && sender.name.trim().length > 0
+          ? sender.name
+          : typeof sender?.email === 'string'
+            ? sender.email
+            : ''),
     }
   } catch {
     return { title: '', from: '' }

package/src/modules/query_index/lib/engine.ts

@@ -38,6 +38,7 @@ import { resolveListCountCap } from '@open-mercato/shared/lib/query/count-cap'
 import { mapWithConcurrency } from '@open-mercato/shared/lib/query/bounded-decrypt'
 import { createLogger } from '@open-mercato/shared/lib/logger'
 import { parseNumberWithDefault } from '@open-mercato/shared/lib/number'
+import { createBoundedTtlMemo } from '@open-mercato/shared/lib/query/bounded-ttl-memo'
 
 const logger = createLogger('query_index').child({ component: 'engine' })
 
@@ -83,6 +84,24 @@ function markAutoReindexScheduled(key: string, debounceMs: number, now: number):
   return true
 }
 
+/** Only `true` is cached: a cached `false` would keep routing to the fallback engine after a migration creates the table. */
+const baseTableExistsCache = createBoundedTtlMemo<true>({
+  ttlEnv: 'OM_QUERY_INDEX_BASE_TABLE_EXISTS_CACHE_MS',
+  maxEntriesEnv: 'OM_QUERY_INDEX_BASE_TABLE_EXISTS_CACHE_MAX_ENTRIES',
+  defaultTtlMs: 3_600_000,
+  defaultMaxEntries: 1_000,
+})
+
+/** Test-only: the module-scoped memo would otherwise leak state across specs. */
+export function clearBaseTableExistsCache(): void {
+  baseTableExistsCache.clear()
+}
+
+/** Test-only: entry count of the table-existence memo, for the cap regression test. */
+export function baseTableExistsCacheSize(): number {
+  return baseTableExistsCache.size()
+}
+
 function buildFilterableCustomFieldJoins(
   sources: QueryCustomFieldSource[] | undefined,
 ): Array<{
@@ -2162,13 +2181,16 @@ export class HybridQueryEngine implements QueryEngine {
   }
 
   private async tableExists(table: string): Promise<boolean> {
+    if (baseTableExistsCache.get(table)) return true
     const db = this.getDb() as any
     const exists = await db
       .selectFrom('information_schema.tables')
       .select(sql<number>`1`.as('one'))
       .where('table_name', '=', table)
       .executeTakeFirst()
-    return !!exists
+    const present = !!exists
+    if (present) baseTableExistsCache.set(table, true)
+    return present
   }
 
   private async resolveAvailableCustomFieldKeys(entityIds: string[], tenantId: string | null): Promise<string[]> {

package/src/modules/sales/AGENTS.md

@@ -6,8 +6,7 @@ Use the sales module for orders, quotes, invoices, shipments, and payments. This
 
 1. **MUST use `salesCalculationService` from DI** for document math.
 2. **MUST follow document flow**: Quote → Order → Invoice — no skipping steps
-3. **MUST use `selectBestPrice`** from catalog pricing helpers.
-4. **MUST scope all documents to a channel** — channel selection affects pricing, numbering, and visibility
+3. **MUST scope all documents to a channel** — channel selection affects pricing, numbering, and visibility
 
 ## Ask First
 
@@ -51,7 +50,7 @@ const calcService = container.resolve('salesCalculationService')
 
 - Dispatches `sales.line.calculate.*` / `sales.document.calculate.*` events
 - Register line/totals calculators or override via DI
-- For catalog pricing: use `selectBestPrice`, `resolvePriceVariantId` from catalog module
+- **Not yet wired:** no code here calls catalog's `selectBestPrice`/`catalogPricingService` — lines are priced directly, not resolved from `CatalogProductPrice`. Out of scope for the pricing-engine spec; future wiring routes through `catalogPricingService` — never reimplement pricing inline.
 
 ## Data Model Constraints