@open-mercato/core 0.7.0 → 0.7.1-develop.7102.1.b41f7e3e51

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

@@ -0,0 +1,76 @@
+import type { EntityManager } from '@mikro-orm/postgresql'
+import { findWithDecryption } from '@open-mercato/shared/lib/encryption/find'
+import { CustomerPipelineStage } from '../data/entities'
+
+export type DealClosureOutcome = 'won' | 'lost'
+
+export type PipelineStageSnapshot = {
+  id: string
+  pipelineId: string
+  label: string
+  order: number
+}
+
+// Stage labels that mark a pipeline as terminal for a given closure outcome. Matching is
+// label-based because stages are tenant-configurable rows; see #5107.
+export const TERMINAL_PIPELINE_STAGE_LABELS: Record<DealClosureOutcome, ReadonlySet<string>> = {
+  won: new Set(['won', 'win', 'closed won', 'closed win']),
+  lost: new Set(['lost', 'loose', 'closed lost', 'closed loose']),
+}
+
+/**
+ * Map a deal status spelling (UI `win`/`loose` or AI `won`/`lost`) to its closure
+ * outcome. Case-insensitive because callers such as the AI tool pass free-form model
+ * text through, while every persisted status is lower-case.
+ */
+export function dealClosureOutcomeFromStatus(status: string | null | undefined): DealClosureOutcome | null {
+  const normalized = typeof status === 'string' ? status.trim().toLowerCase() : status
+  if (normalized === 'win' || normalized === 'won') return 'won'
+  if (normalized === 'loose' || normalized === 'lost') return 'lost'
+  return null
+}
+
+export function normalizePipelineStageLabel(value: string): string {
+  return value
+    .trim()
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, ' ')
+    .trim()
+}
+
+/**
+ * Resolve the terminal stage of the deal's pipeline for a closure outcome, so every
+ * writer (command, AI tool preview) agrees on where a closed deal lands (#5107).
+ */
+export async function loadClosurePipelineStageSnapshot(
+  em: EntityManager,
+  input: {
+    pipelineId: string | null
+    closureOutcome: DealClosureOutcome
+    tenantId: string
+    organizationId: string
+  },
+): Promise<PipelineStageSnapshot | null> {
+  if (!input.pipelineId) return null
+
+  const stages = await findWithDecryption(
+    em,
+    CustomerPipelineStage,
+    {
+      pipelineId: input.pipelineId,
+      tenantId: input.tenantId,
+      organizationId: input.organizationId,
+    },
+    { orderBy: { order: 'ASC' } },
+    { tenantId: input.tenantId, organizationId: input.organizationId },
+  )
+  const aliases = TERMINAL_PIPELINE_STAGE_LABELS[input.closureOutcome]
+  const stage = stages.find((candidate) => aliases.has(normalizePipelineStageLabel(candidate.label)))
+  if (!stage) return null
+  return {
+    id: stage.id,
+    pipelineId: stage.pipelineId,
+    label: stage.label,
+    order: stage.order,
+  }
+}

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

@@ -46,3 +46,45 @@ export function isClosedDealStatus(value: string | null | undefined): boolean {
 export function isOpenDealStatus(value: string | null | undefined): boolean {
   return !isClosedDealStatus(value)
 }
+
+export function canonicalDealStatus(value: string): string {
+  const lower = value.toLowerCase()
+  if (lower === 'won') return DEAL_STATUS_WIN
+  if (lower === 'lost') return DEAL_STATUS_LOSE
+  // Canonical spellings normalize to lower-case too, so an upper-case selection still
+  // matches the lower-case persisted values and dictionary options.
+  if (lower === 'win' || lower === 'loose' || lower === 'open' || lower === 'closed') return lower
+  return value
+}
+
+/**
+ * Expand operator-selected status filter values into the canonical vocabulary so a
+ * single selection matches every spelling the supported writers persist (#5107).
+ *
+ * Alias groups (`win`/`won`, `loose`/`lost`, `closed`) are matched case-insensitively,
+ * expanded to their canonical spellings, and also keep the caller's original token so
+ * the result is always a strict superset of a verbatim match. Unknown values emit both
+ * the trimmed original and its lower-case form — mixed-case tenant dictionary statuses
+ * match exactly while `?status=Open` still hits lower-case stored rows.
+ */
+export function expandDealStatusAliases(values: string[]): string[] {
+  const out = new Set<string>()
+  for (const value of values) {
+    const trimmed = value.trim()
+    const lower = trimmed.toLowerCase()
+    if (lower === 'win' || lower === 'won') {
+      WON_DEAL_STATUS_LIST.forEach((entry) => out.add(entry))
+      out.add(trimmed)
+    } else if (lower === 'loose' || lower === 'lost') {
+      LOST_DEAL_STATUS_LIST.forEach((entry) => out.add(entry))
+      out.add(trimmed)
+    } else if (lower === 'closed') {
+      CLOSED_DEAL_STATUS_LIST.forEach((entry) => out.add(entry))
+      out.add(trimmed)
+    } else {
+      out.add(trimmed)
+      out.add(lower)
+    }
+  }
+  return Array.from(out)
+}

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

@@ -0,0 +1,35 @@
+import { NextResponse } from 'next/server'
+import {
+  isOrganizationReadAccessAllowed,
+  type OrganizationReadAccessInput,
+} from '@open-mercato/core/modules/directory/utils/organizationScopeGuard'
+
+/**
+ * Single-record customers detail routes (person / company / deal) must not leak
+ * whether a record exists through the organization-scope check.
+ *
+ * The API dispatcher already enforces each route's `metadata.requireFeatures`
+ * before the handler runs, returning a uniform `403` for callers who lack the
+ * grant — so that path never distinguishes an existing id from a missing one.
+ * The only remaining existence signal is the *post-load* organization guard: a
+ * caller who holds the feature but whose scope excludes the record's
+ * organization previously received `403` (record exists in another org) while a
+ * non-existent id received `404`. That 403-vs-404 split is an existence oracle
+ * (issue #5504).
+ *
+ * Collapse the organization-scope denial into the route's own not-found
+ * response so an out-of-scope caller cannot tell "exists in an organization you
+ * cannot see" from "does not exist" — the shape the api_keys hardening
+ * (#4033 / PR-4051) established. Sharing this decision keeps the three customers
+ * detail routes from drifting apart again.
+ *
+ * @returns the `404` response to return when read access is denied, or `null`
+ * when the caller may read the record.
+ */
+export function denyCustomerDetailReadAsNotFound(
+  input: OrganizationReadAccessInput,
+  notFoundMessage: string,
+): NextResponse | null {
+  if (isOrganizationReadAccessAllowed(input)) return null
+  return NextResponse.json({ error: notFoundMessage }, { status: 404 })
+}

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

@@ -32,13 +32,15 @@ export interface MatchedPerson {
 }
 
 /**
- * Max person rows scanned by the in-memory fallback match. `primary_email` is
- * GDPR-encrypted with a random IV (see `customers/encryption.ts`), so it cannot
- * be filtered by value in SQL when tenant data encryption is on — recent rows are
- * decrypted and compared in memory instead. Bounded to keep the inbound path cheap;
- * a `primary_email` blind-index (hash) column is the follow-up if tenants outgrow it.
+ * Max rows scanned by in-memory fallback matches over encrypted contact
+ * columns (`primary_email` here, `primary_phone` in the check-phone route).
+ * These columns are GDPR-encrypted with a random IV (see
+ * `customers/encryption.ts`), so they cannot be filtered by value in SQL when
+ * tenant data encryption is on — fallbacks decrypt recent rows and compare in
+ * memory instead. Bounded to keep interactive lookups cheap; a blind-index
+ * (hash) column per field is the follow-up if tenants outgrow it (#5515).
  */
-const MATCH_CANDIDATE_LIMIT = 500
+export const MATCH_CANDIDATE_LIMIT = 500
 
 /**
  * Batch lookup of CustomerEntity rows (kind='person') whose `primaryEmail`

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

@@ -56,6 +56,136 @@ async function requireCompany(
   return company
 }
 
+export type CompanyPersonUnionEntry = {
+  entity: CustomerEntity
+  profile: CustomerPersonProfile | null
+  linkedAt: string | null
+}
+
+/**
+ * Resolve "people belonging to this company" as the union of active
+ * `CustomerPersonCompanyLink` rows and `CustomerPersonProfile.company`
+ * profile-only assignments (data that never got a link row, e.g. from
+ * migrated CRM imports). This is the single source of truth for both the
+ * company People tab list and its badge count — see #5114.
+ */
+export async function loadCompanyPeopleUnion(
+  em: EntityManager,
+  company: CustomerEntity,
+  scope: { tenantId?: string | null; organizationId?: string | null },
+): Promise<CompanyPersonUnionEntry[]> {
+  const decryptionScope = {
+    tenantId: scope.tenantId ?? company.tenantId ?? null,
+    organizationId: scope.organizationId ?? company.organizationId ?? null,
+  }
+  const relatedPeopleById = new Map<string, CompanyPersonUnionEntry>()
+
+  const companyLinkWhere = await withActiveCustomerPersonCompanyLinkFilter(
+    em,
+    { company: company.id, organizationId: company.organizationId, tenantId: company.tenantId },
+    'customers.companies.loadCompanyPeopleUnion',
+  )
+  const companyLinks = filterActivePersonCompanyLinks(
+    await findWithDecryption(
+      em,
+      CustomerPersonCompanyLink,
+      companyLinkWhere,
+      { populate: ['person', 'person.personProfile'], orderBy: { isPrimary: 'desc', createdAt: 'asc' } },
+      decryptionScope,
+    ),
+  )
+  companyLinks.forEach((link) => {
+    const entity = typeof link.person === 'string' ? null : link.person
+    if (!entity || entity.kind !== 'person' || entity.deletedAt) return
+    const personProfile =
+      entity.personProfile && typeof entity.personProfile !== 'string' ? entity.personProfile : null
+    relatedPeopleById.set(entity.id, {
+      entity,
+      profile: personProfile,
+      linkedAt: link.createdAt instanceof Date ? link.createdAt.toISOString() : null,
+    })
+  })
+
+  const profiles = await findWithDecryption(
+    em,
+    CustomerPersonProfile,
+    {
+      company: company.id,
+      tenantId: company.tenantId,
+      organizationId: company.organizationId,
+      entity: { deletedAt: null },
+    },
+    { populate: ['entity'] },
+    decryptionScope,
+  )
+  profiles.forEach((entry) => {
+    const entity = entry.entity as CustomerEntity | null
+    if (!entity || entity.kind !== 'person' || entity.deletedAt) return
+    if (!relatedPeopleById.has(entity.id)) {
+      relatedPeopleById.set(entity.id, {
+        entity,
+        profile: entry ?? null,
+        linkedAt: entry.createdAt instanceof Date ? entry.createdAt.toISOString() : null,
+      })
+    }
+  })
+
+  return Array.from(relatedPeopleById.values())
+}
+
+/**
+ * Count-only sibling of `loadCompanyPeopleUnion` for the company People badge, which
+ * needs the size of the union and nothing else. Both queries project just the foreign
+ * key column and push the `kind: 'person'` / `deletedAt: null` predicates into the
+ * WHERE clause, so no person row is hydrated and no PII is decrypted to produce a
+ * number — `findWithDecryption` is deliberately not used here because the projections
+ * select no encrypted column.
+ */
+export async function countCompanyPeopleUnion(
+  em: EntityManager,
+  company: CustomerEntity,
+): Promise<number> {
+  const personIds = new Set<string>()
+
+  const companyLinkWhere = await withActiveCustomerPersonCompanyLinkFilter(
+    em,
+    {
+      company: company.id,
+      organizationId: company.organizationId,
+      tenantId: company.tenantId,
+      person: { kind: 'person', deletedAt: null },
+    },
+    'customers.companies.countCompanyPeopleUnion',
+  )
+  const companyLinks = filterActivePersonCompanyLinks(
+    await em.find(CustomerPersonCompanyLink, companyLinkWhere as any, {
+      fields: ['person', 'deletedAt'],
+    } as any),
+  )
+  companyLinks.forEach((link) => {
+    const personId = typeof link.person === 'string' ? link.person : link.person?.id
+    if (personId) personIds.add(personId)
+  })
+
+  const profiles = await em.find(
+    CustomerPersonProfile,
+    {
+      company: company.id,
+      tenantId: company.tenantId,
+      organizationId: company.organizationId,
+      entity: { kind: 'person', deletedAt: null },
+    } as any,
+    { fields: ['entity'] } as any,
+  )
+  profiles.forEach((entry) => {
+    const entity = entry.entity as CustomerEntity | string | null
+    const entityId = typeof entity === 'string' ? entity : entity?.id
+    if (entityId) personIds.add(entityId)
+  })
+
+  return personIds.size
+}
+
 export async function loadPersonCompanyLinks(
   em: EntityManager,
   person: CustomerEntity,
@@ -298,7 +428,12 @@ export async function removePersonCompanyLink(
 
   if (!link) {
     if (profile.company && typeof profile.company !== 'string' && profile.company.id === linkId) {
-      profile.company = null
+      // Profile-only assignment: no link row backs it, so only the legacy field is
+      // cleared. It must keep mirroring the primary link the way every other detach
+      // path leaves it, so promote a remaining primary link instead of nulling blindly.
+      const primary = existingLinks.find((entry) => entry.isPrimary) ?? null
+      const primaryCompany = primary ? resolveLinkedCompany(primary) : null
+      profile.company = primaryCompany ?? null
       return
     }
     throw notFound('Company link not found')

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

@@ -78,6 +78,17 @@ export type CanonicalTodoListResult = {
   total: number
 }
 
+function emptyCanonicalTodoList(): CanonicalTodoListResult {
+  return { items: [], bridgeIds: new Set(), total: 0 }
+}
+
+function isCollapsedRestrictedOrganizationScope(
+  organizationIds: string[] | null | undefined,
+  isUnrestricted: boolean | undefined,
+): boolean {
+  return isUnrestricted !== true && (!organizationIds || organizationIds.length === 0)
+}
+
 export type ListTodosPagination = { page: number; pageSize: number }
 
 function resolveLegacyTodoSource(source: string | null | undefined): string {
@@ -377,8 +388,11 @@ export async function listLegacyTodoRows(
   tenantId: string,
   organizationIds: string[] | null,
   entityId: string | undefined,
-  options?: { limit?: number | null },
+  options?: { limit?: number | null; isUnrestricted?: boolean },
 ): Promise<CustomerTodoRow[]> {
+  if (isCollapsedRestrictedOrganizationScope(organizationIds, options?.isUnrestricted)) {
+    return []
+  }
   const where: Record<string, unknown> = { tenantId }
   if (organizationIds && organizationIds.length > 0) {
     where.organizationId = { $in: organizationIds }
@@ -425,8 +439,12 @@ export async function listCanonicalTodoRows(
     pagination?: ListTodosPagination | null
     searchText?: string | null
     limit?: number | null
+    isUnrestricted?: boolean
   },
 ): Promise<CanonicalTodoListResult> {
+  if (isCollapsedRestrictedOrganizationScope(organizationIds, options?.isUnrestricted)) {
+    return emptyCanonicalTodoList()
+  }
   const where: Record<string, unknown> = {
     tenantId: auth.tenantId,
     interactionType: 'task',

package/src/modules/dashboards/i18n/es.json

@@ -7,10 +7,10 @@
   "dashboards.analytics.comparison.vsLastWeek": "vs semana pasada",
   "dashboards.analytics.comparison.vsLastYear": "vs año pasado",
   "dashboards.analytics.comparison.vsMonthBefore": "vs mes anterior",
-  "dashboards.analytics.comparison.vsPrevious30Days": "vs 30 dias anteriores",
-  "dashboards.analytics.comparison.vsPrevious7Days": "vs 7 dias anteriores",
-  "dashboards.analytics.comparison.vsPrevious90Days": "vs 90 dias anteriores",
-  "dashboards.analytics.comparison.vsPreviousPeriod": "vs periodo anterior",
+  "dashboards.analytics.comparison.vsPrevious30Days": "vs 30 días anteriores",
+  "dashboards.analytics.comparison.vsPrevious7Days": "vs 7 días anteriores",
+  "dashboards.analytics.comparison.vsPrevious90Days": "vs 90 días anteriores",
+  "dashboards.analytics.comparison.vsPreviousPeriod": "vs período anterior",
   "dashboards.analytics.comparison.vsQuarterBefore": "vs trimestre anterior",
   "dashboards.analytics.comparison.vsWeekBefore": "vs semana anterior",
   "dashboards.analytics.comparison.vsYearBefore": "vs año anterior",

package/src/modules/dashboards/i18n/pl.json

@@ -2,18 +2,18 @@
   "dashboards.analytics.chartVariant.donut": "Pierścieniowy",
   "dashboards.analytics.chartVariant.pie": "Kołowy",
   "dashboards.analytics.comparison.vsDayBefore": "vs przedwczoraj",
-  "dashboards.analytics.comparison.vsLastMonth": "vs poprzedni miesiac",
-  "dashboards.analytics.comparison.vsLastQuarter": "vs poprzedni kwartal",
-  "dashboards.analytics.comparison.vsLastWeek": "vs poprzedni tydzien",
+  "dashboards.analytics.comparison.vsLastMonth": "vs poprzedni miesiąc",
+  "dashboards.analytics.comparison.vsLastQuarter": "vs poprzedni kwartał",
+  "dashboards.analytics.comparison.vsLastWeek": "vs poprzedni tydzień",
   "dashboards.analytics.comparison.vsLastYear": "vs poprzedni rok",
-  "dashboards.analytics.comparison.vsMonthBefore": "vs miesiac wczesniej",
+  "dashboards.analytics.comparison.vsMonthBefore": "vs miesiąc wcześniej",
   "dashboards.analytics.comparison.vsPrevious30Days": "vs poprzednie 30 dni",
   "dashboards.analytics.comparison.vsPrevious7Days": "vs poprzednie 7 dni",
   "dashboards.analytics.comparison.vsPrevious90Days": "vs poprzednie 90 dni",
   "dashboards.analytics.comparison.vsPreviousPeriod": "vs poprzedni okres",
-  "dashboards.analytics.comparison.vsQuarterBefore": "vs kwartal wczesniej",
-  "dashboards.analytics.comparison.vsWeekBefore": "vs tydzien wczesniej",
-  "dashboards.analytics.comparison.vsYearBefore": "vs rok wczesniej",
+  "dashboards.analytics.comparison.vsQuarterBefore": "vs kwartał wcześniej",
+  "dashboards.analytics.comparison.vsWeekBefore": "vs tydzień wcześniej",
+  "dashboards.analytics.comparison.vsYearBefore": "vs rok wcześniej",
   "dashboards.analytics.comparison.vsYesterday": "vs wczoraj",
   "dashboards.analytics.currency.unlabelled": "Kwoty pokazane bez waluty",
   "dashboards.analytics.currency.unlabelledHint": "Nie udało się wiarygodnie ustalić waluty, dlatego kwota jest wyświetlana bez jej oznaczenia.",

package/src/modules/dashboards/lib/widgetScope.ts

@@ -1,6 +1,7 @@
 import type { EntityManager } from '@mikro-orm/postgresql'
 import { createRequestContainer, type AppContainer } from '@open-mercato/shared/lib/di/container'
 import { getAuthFromRequest } from '@open-mercato/shared/lib/auth/server'
+import { isUnrestrictedOrganizationScope } from '@open-mercato/shared/lib/auth/organizationAccess'
 import { CrudHttpError } from '@open-mercato/shared/lib/crud/errors'
 import { resolveOrganizationScopeForRequest } from '@open-mercato/core/modules/directory/utils/organizationScope'
 
@@ -9,6 +10,7 @@ export type WidgetScopeContext = {
   em: EntityManager
   tenantId: string
   organizationIds: string[] | null
+  isUnrestrictedOrganizationScope?: boolean
 }
 
 function normalizeScopeId(value: string | null | undefined): string | null {
@@ -91,5 +93,9 @@ export async function resolveWidgetScope(
     em,
     tenantId,
     organizationIds,
+    isUnrestrictedOrganizationScope: isUnrestrictedOrganizationScope({
+      isSuperAdmin,
+      allowedOrganizationIds: scope?.allowedIds,
+    }),
   }
 }

package/src/modules/data_sync/AGENTS.md

@@ -206,7 +206,7 @@ If the sync provider needs bootstrap credentials, mappings, locales, channels, o
 - **Resetting an opt-out**: A reset flow that deletes the shared `SyncCursor` row MUST also call `syncRunService.resetResumePosition(integrationId, entityType, direction, scope)`. An opted-out entity type has no shared row to delete, so deleting only that leaves the resume position on the last interrupted run and the next incremental run re-imports just the tail of the walk it was reset against. The call is a no-op when nothing is interrupted, so make it unconditionally
 - **Resume**: Retry reads the last successful cursor, resumes from there
 - **Progress**: Linked to `ProgressJob` via `progressJobId` for `ProgressTopBar` display
-- **Cancellation**: Via `progressService.isCancellationRequested()`
+- **Cancellation**: The engine polls `progressService.isCancellationRequested()` in the batch handler AND on the heartbeat tick while a batch is still in flight, aborting `StreamImportInput.signal` / `StreamExportInput.signal`. Adapters SHOULD honour the signal wherever the work is divisible (per page, per record, around a long flush) and `return` — with the `return` ABOVE the `yield`, never below it, or the engine commits a cursor for a half-applied page. Adapters that ignore the signal keep the old between-batches behavior.
 - **Tracing**: The engine emits one **root** span per batch (`data_sync.import.batch` / `data_sync.export.batch`) linked back to the run, covering the adapter's read *and* the engine's bookkeeping. Adapters MUST NOT hand-roll their own batch span — they cannot root it, so a multi-day run would ride on the single sampling decision taken for the request that triggered it. Inner spans an adapter creates nest under the batch span normally. The final read — the one that finds the stream drained — is traced as `data_sync.import.drain` / `data_sync.export.drain`, so N batches emit exactly N `*.batch` spans plus one `*.drain`.
 - **Stream shape**: The engine drives the adapter's async iterator explicitly (`batch-stream.ts`) so the span wraps `next()`, where a generator does its real work before yielding. Closing follows the language's own `IteratorClose` rules, so `finally` blocks in an adapter generator behave exactly as under `for await`: no `return()` when the stream exhausts or `next()` throws (already closed), `return()` with its failure surfaced on an early stop, and `return()` with its failure swallowed when the engine's own handler threw (that error wins). Keep cleanup in `finally`.
 

package/src/modules/data_sync/backend/data-sync/page.tsx

@@ -74,6 +74,7 @@ type ResponsePayload = {
   total: number
   page: number
   totalPages: number
+  totalIsCapped?: boolean
 }
 
 type SyncOption = {
@@ -153,6 +154,7 @@ export default function SyncRunsDashboardPage() {
   const [page, setPage] = React.useState(1)
   const [total, setTotal] = React.useState(0)
   const [totalPages, setTotalPages] = React.useState(1)
+  const [totalIsCapped, setTotalIsCapped] = React.useState(false)
   const [search, setSearch] = React.useState('')
   const [filterValues, setFilterValues] = React.useState<FilterValues>({})
   const [isLoading, setIsLoading] = React.useState(true)
@@ -200,6 +202,7 @@ export default function SyncRunsDashboardPage() {
         setRows(Array.isArray(payload.items) ? payload.items : [])
         setTotal(payload.total || 0)
         setTotalPages(payload.totalPages || 1)
+        setTotalIsCapped(payload?.totalIsCapped === true)
         setIsLoading(false)
       }
     }
@@ -1065,7 +1068,7 @@ export default function SyncRunsDashboardPage() {
               }] : []),
             ]} />
           )}
-          pagination={{ page, pageSize: 20, total, totalPages, onPageChange: setPage }}
+          pagination={{ page, pageSize: 20, total, totalPages, totalIsCapped, onPageChange: setPage }}
           isLoading={isLoading}
         />
       </PageBody>

package/src/modules/data_sync/lib/abandoned-run.ts

@@ -0,0 +1,56 @@
+import type { AbandonedJobInfo } from '@open-mercato/queue'
+
+/**
+ * Fail the run behind a job the queue gave up on.
+ *
+ * A resumable data_sync job is ONE long-lived job for a whole run — `runImport` is entered once and
+ * stays there for the duration, which for a full backfill is days. Every worker death (a deploy, an
+ * OOM) therefore stalls that job, and BullMQ's stalled counter is cumulative for the job's life:
+ * past `DATA_SYNC_MAX_STALLED_COUNT` it writes a deferred failure and the next worker fails the job
+ * BEFORE calling the processor.
+ *
+ * So `runImport` never runs, never throws, and never finalizes — and `sync_runs` is left saying
+ * `running` for a run nothing is running, forever. That is the residual state `queue-policy.ts`
+ * describes as what remains after a job exhausts its stall budget; this repairs it.
+ *
+ * It only ever moves a non-terminal run: `markStatus` refuses to overwrite `completed` / `failed` /
+ * `cancelled`, so a job abandoned after its run has ended is a no-op. `onJobAbandoned` may deliver
+ * the same job more than once, which for the same reason is also a no-op.
+ *
+ * The run's progress job is failed alongside it, the way the worker's own catch path does in
+ * `workers/sync-import.ts`. Without that the two halves disagree — the run reads `failed` while the
+ * operation still shows as in flight in the top bar — until the progress staleness sweep eventually
+ * fails it with a generic no-heartbeat message instead of the reason the queue recorded.
+ */
+export async function failAbandonedRun(payload: unknown, info: AbandonedJobInfo): Promise<void> {
+  const data = payload as { payload?: { runId?: unknown; scope?: { organizationId?: unknown; tenantId?: unknown } } } | undefined
+  const runId = data?.payload?.runId
+  const scope = data?.payload?.scope
+  // Nothing to repair without both: the run row is keyed by id AND tenant scope.
+  if (typeof runId !== 'string' || typeof scope?.organizationId !== 'string' || typeof scope?.tenantId !== 'string') return
+
+  const runScope = { organizationId: scope.organizationId, tenantId: scope.tenantId }
+  const errorMessage = `the queue abandoned this run's job without running it: ${info.reason}`
+
+  const { createRequestContainer } = await import('@open-mercato/shared/lib/di/container')
+  const container = await createRequestContainer()
+  const runService = container.resolve('dataSyncRunService') as {
+    markStatus(
+      runId: string,
+      status: string,
+      scope: { organizationId: string; tenantId: string },
+      error?: string,
+    ): Promise<{ progressJobId?: string | null } | null>
+  }
+  const run = await runService.markStatus(runId, 'failed', runScope, errorMessage)
+  if (!run?.progressJobId) return
+
+  const progressService = container.resolve('progressService') as {
+    failJob(
+      jobId: string,
+      input: { errorMessage: string },
+      ctx: { organizationId: string; tenantId: string },
+    ): Promise<unknown>
+  }
+  await progressService.failJob(run.progressJobId, { errorMessage }, runScope)
+}

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

@@ -45,6 +45,27 @@ export interface StreamImportInput {
    * declares no parameters.
    */
   parameters?: Record<string, RunParameterValue>
+  /**
+   * Aborted when the run is cancelled, so an adapter can stop INSIDE a batch.
+   *
+   * The engine only gets to look at cancellation between batches — its check sits in the batch
+   * handler, which runs after the adapter has yielded. An adapter whose batch takes minutes (a
+   * whole-table walk over a slow link) therefore keeps working, keeps writing, and keeps its
+   * advisory lock for that whole time, however long ago the operator pressed Cancel.
+   *
+   * Honour it wherever the work is divisible — per page, per record, around a long flush — and just
+   * return: the generator's own `finally` runs, which is where a lock or a connection is released.
+   * Adapters that ignore it behave exactly as they do today.
+   *
+   * The `return` MUST sit ABOVE the `yield` for the page you abandoned, never below it. The engine
+   * commits `batch.cursor` for every batch it receives, so yielding a half-applied page advances the
+   * cursor past records that were never applied and no later run ever walks them again.
+   *
+   * The signal only reaches work running in THIS process. An adapter that hands part of a batch to
+   * other workers must give that work its own cancellation check against the same progress job —
+   * aborting here stops the generator, not anything already queued elsewhere.
+   */
+  signal?: AbortSignal
 }
 
 export interface ImportItem {
@@ -57,6 +78,18 @@ export interface ImportItem {
 export interface ImportBatch {
   items: ImportItem[]
   cursor: string
+  /**
+   * Whether the source has more to give after this batch. The final batch MUST report `false`.
+   *
+   * This is not advisory. The engine uses the last batch's value to tell a stream that DRAINED from
+   * one the adapter STOPPED EARLY on {@link StreamImportInput.signal}, because both end the same way
+   * — the generator simply returns. An adapter that reports `true` on its final batch will have a
+   * complete run misreported as `cancelled` whenever a cancel lands during the final read: the
+   * operator is told a finished sync was partial, and the run stays resumable with nothing left to
+   * resume.
+   *
+   * Derive it from the source rather than hardcoding it — `Boolean(nextPage)`, `offset < total`.
+   */
   hasMore: boolean
   totalEstimate?: number
   processedCount?: number
@@ -76,6 +109,8 @@ export interface StreamExportInput {
   runId?: string
   /** See {@link StreamImportInput.parameters}. */
   parameters?: Record<string, RunParameterValue>
+  /** Aborted when the run is cancelled — see {@link StreamImportInput.signal}. */
+  signal?: AbortSignal
 }
 
 export interface ExportItemResult {
@@ -88,6 +123,7 @@ export interface ExportItemResult {
 export interface ExportBatch {
   results: ExportItemResult[]
   cursor: string
+  /** Whether the source has more to give; the final batch MUST report `false`. See {@link ImportBatch.hasMore}. */
   hasMore: boolean
   batchIndex: number
 }