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

package/src/modules/customers/migrations/.snapshot-open-mercato.json

@@ -2956,6 +2956,220 @@
       "foreignKeys": {},
       "comment": null
     },
+    {
+      "name": "customer_email_conversation_shares",
+      "schema": "public",
+      "columns": {
+        "created_at": {
+          "name": "created_at",
+          "type": "timestamptz(6)",
+          "unsigned": false,
+          "autoincrement": false,
+          "primary": false,
+          "nullable": false,
+          "unique": false,
+          "length": 6,
+          "precision": null,
+          "scale": null,
+          "default": null,
+          "comment": null,
+          "collation": null,
+          "enumItems": [],
+          "mappedType": "datetime"
+        },
+        "deleted_at": {
+          "name": "deleted_at",
+          "type": "timestamptz(6)",
+          "unsigned": false,
+          "autoincrement": false,
+          "primary": false,
+          "nullable": true,
+          "unique": false,
+          "length": 6,
+          "precision": null,
+          "scale": null,
+          "default": null,
+          "comment": null,
+          "collation": null,
+          "enumItems": [],
+          "mappedType": "datetime"
+        },
+        "id": {
+          "name": "id",
+          "type": "uuid",
+          "unsigned": false,
+          "autoincrement": false,
+          "primary": true,
+          "nullable": false,
+          "unique": false,
+          "length": null,
+          "precision": null,
+          "scale": null,
+          "default": "gen_random_uuid()",
+          "comment": null,
+          "collation": null,
+          "enumItems": [],
+          "mappedType": "uuid"
+        },
+        "organization_id": {
+          "name": "organization_id",
+          "type": "uuid",
+          "unsigned": false,
+          "autoincrement": false,
+          "primary": false,
+          "nullable": false,
+          "unique": false,
+          "length": null,
+          "precision": null,
+          "scale": null,
+          "default": null,
+          "comment": null,
+          "collation": null,
+          "enumItems": [],
+          "mappedType": "uuid"
+        },
+        "owner_user_id": {
+          "name": "owner_user_id",
+          "type": "uuid",
+          "unsigned": false,
+          "autoincrement": false,
+          "primary": false,
+          "nullable": false,
+          "unique": false,
+          "length": null,
+          "precision": null,
+          "scale": null,
+          "default": null,
+          "comment": null,
+          "collation": null,
+          "enumItems": [],
+          "mappedType": "uuid"
+        },
+        "person_entity_id": {
+          "name": "person_entity_id",
+          "type": "uuid",
+          "unsigned": false,
+          "autoincrement": false,
+          "primary": false,
+          "nullable": false,
+          "unique": false,
+          "length": null,
+          "precision": null,
+          "scale": null,
+          "default": null,
+          "comment": null,
+          "collation": null,
+          "enumItems": [],
+          "mappedType": "uuid"
+        },
+        "shared_by_user_id": {
+          "name": "shared_by_user_id",
+          "type": "uuid",
+          "unsigned": false,
+          "autoincrement": false,
+          "primary": false,
+          "nullable": false,
+          "unique": false,
+          "length": null,
+          "precision": null,
+          "scale": null,
+          "default": null,
+          "comment": null,
+          "collation": null,
+          "enumItems": [],
+          "mappedType": "uuid"
+        },
+        "tenant_id": {
+          "name": "tenant_id",
+          "type": "uuid",
+          "unsigned": false,
+          "autoincrement": false,
+          "primary": false,
+          "nullable": false,
+          "unique": false,
+          "length": null,
+          "precision": null,
+          "scale": null,
+          "default": null,
+          "comment": null,
+          "collation": null,
+          "enumItems": [],
+          "mappedType": "uuid"
+        },
+        "updated_at": {
+          "name": "updated_at",
+          "type": "timestamptz(6)",
+          "unsigned": false,
+          "autoincrement": false,
+          "primary": false,
+          "nullable": true,
+          "unique": false,
+          "length": 6,
+          "precision": null,
+          "scale": null,
+          "default": null,
+          "comment": null,
+          "collation": null,
+          "enumItems": [],
+          "mappedType": "datetime"
+        }
+      },
+      "indexes": [
+        {
+          "columnNames": [],
+          "composite": false,
+          "constraint": false,
+          "keyName": "customer_email_conv_shares_lookup_idx",
+          "primary": false,
+          "unique": false,
+          "expression": "create index \"customer_email_conv_shares_lookup_idx\" on \"customer_email_conversation_shares\" (\"tenant_id\", \"organization_id\", \"person_entity_id\") where \"deleted_at\" is null"
+        },
+        {
+          "columnNames": [],
+          "composite": false,
+          "constraint": false,
+          "keyName": "customer_email_conv_shares_owner_idx",
+          "primary": false,
+          "unique": false,
+          "expression": "create index \"customer_email_conv_shares_owner_idx\" on \"customer_email_conversation_shares\" (\"tenant_id\", \"owner_user_id\") where \"deleted_at\" is null"
+        },
+        {
+          "columnNames": [],
+          "composite": false,
+          "constraint": false,
+          "keyName": "customer_email_conv_shares_uq",
+          "primary": false,
+          "unique": false,
+          "expression": "create unique index \"customer_email_conv_shares_uq\" on \"customer_email_conversation_shares\" (\"tenant_id\", \"person_entity_id\", \"owner_user_id\") where \"deleted_at\" is null"
+        },
+        {
+          "columnNames": [
+            "id"
+          ],
+          "composite": false,
+          "constraint": true,
+          "keyName": "customer_email_conversation_shares_pkey",
+          "primary": true,
+          "unique": true
+        }
+      ],
+      "checks": [],
+      "triggers": [],
+      "foreignKeys": {
+        "customer_email_conversation_shares_person_entity_id_foreign": {
+          "columnNames": [
+            "person_entity_id"
+          ],
+          "constraintName": "customer_email_conversation_shares_person_entity_id_foreign",
+          "localTableName": "public.customer_email_conversation_shares",
+          "referencedColumnNames": [
+            "id"
+          ],
+          "referencedTableName": "public.customer_entities"
+        }
+      },
+      "comment": null
+    },
     {
       "name": "customer_entities",
       "schema": "public",
@@ -3729,6 +3943,23 @@
           "enumItems": [],
           "mappedType": "text"
         },
+        "channel_id": {
+          "name": "channel_id",
+          "type": "uuid",
+          "unsigned": false,
+          "autoincrement": false,
+          "primary": false,
+          "nullable": true,
+          "unique": false,
+          "length": null,
+          "precision": null,
+          "scale": null,
+          "default": null,
+          "comment": null,
+          "collation": null,
+          "enumItems": [],
+          "mappedType": "uuid"
+        },
         "channel_provider_key": {
           "name": "channel_provider_key",
           "type": "text",
@@ -4281,6 +4512,15 @@
           "primary": false,
           "unique": false,
           "expression": "create index \"customer_interactions_email_visibility_idx\" on \"customer_interactions\" (\"entity_id\", \"interaction_type\", \"visibility\", \"author_user_id\") where \"interaction_type\" = 'email' and \"deleted_at\" is null"
+        },
+        {
+          "columnNames": [],
+          "composite": false,
+          "constraint": false,
+          "keyName": "customer_interactions_email_channel_idx",
+          "primary": false,
+          "unique": false,
+          "expression": "create index \"customer_interactions_email_channel_idx\" on \"customer_interactions\" (\"channel_id\", \"entity_id\") where \"interaction_type\" = 'email' and \"channel_id\" is not null and \"deleted_at\" is null"
         }
       ],
       "checks": [],

package/src/modules/customers/migrations/Migration20260825120000_customers.ts

@@ -0,0 +1,19 @@
+import { Migration } from '@mikro-orm/migrations';
+
+export class Migration20260825120000_customers extends Migration {
+
+  override async up(): Promise<void> {
+    this.addSql(`create table "customer_email_conversation_shares" ("id" uuid not null default gen_random_uuid(), "organization_id" uuid not null, "tenant_id" uuid not null, "person_entity_id" uuid not null, "owner_user_id" uuid not null, "shared_by_user_id" uuid not null, "created_at" timestamptz not null, "updated_at" timestamptz null, "deleted_at" timestamptz null, constraint "customer_email_conversation_shares_pkey" primary key ("id"));`);
+    this.addSql(`create index "customer_email_conv_shares_lookup_idx" on "customer_email_conversation_shares" ("tenant_id", "organization_id", "person_entity_id") where "deleted_at" is null;`);
+    this.addSql(`create index "customer_email_conv_shares_owner_idx" on "customer_email_conversation_shares" ("tenant_id", "owner_user_id") where "deleted_at" is null;`);
+    this.addSql(`create unique index "customer_email_conv_shares_uq" on "customer_email_conversation_shares" ("tenant_id", "person_entity_id", "owner_user_id") where "deleted_at" is null;`);
+
+    this.addSql(`alter table "customer_email_conversation_shares" add constraint "customer_email_conversation_shares_person_entity_id_foreign" foreign key ("person_entity_id") references "customer_entities" ("id") on update cascade;`);
+  }
+
+  override async down(): Promise<void> {
+    this.addSql(`alter table "customer_email_conversation_shares" drop constraint if exists "customer_email_conversation_shares_person_entity_id_foreign";`);
+    this.addSql(`drop table if exists "customer_email_conversation_shares" cascade;`);
+  }
+
+}

package/src/modules/customers/migrations/Migration20260825140000_customers.ts

@@ -0,0 +1,41 @@
+import { Migration } from '@mikro-orm/migrations';
+
+export class Migration20260825140000_customers extends Migration {
+
+  override async up(): Promise<void> {
+    this.addSql(`alter table "customer_interactions" add column "channel_id" uuid null;`);
+
+    // Backfill the denormalized channel id for pre-existing email rows.
+    //
+    // This is the only available chain — `message_channel_links` carries no
+    // channel id of its own:
+    //   customer_interactions.external_message_id -> message_channel_links.id
+    //   message_channel_links.external_conversation_id -> external_conversations.id
+    //   external_conversations.channel_id -> communication_channels.id
+    //
+    // Rows whose chain cannot be resolved keep channel_id NULL, which every read
+    // predicate treats as "not shared" (fail closed). Scoped by tenant on both
+    // joins so a backfill can never attribute an interaction to another tenant's
+    // channel.
+    this.addSql(`
+      update "customer_interactions" ci
+      set "channel_id" = ec."channel_id"
+      from "message_channel_links" mcl
+      join "external_conversations" ec
+        on ec."id" = mcl."external_conversation_id"
+       and ec."tenant_id" = mcl."tenant_id"
+      where ci."external_message_id" = mcl."id"
+        and ci."tenant_id" = mcl."tenant_id"
+        and ci."interaction_type" = 'email'
+        and ci."channel_id" is null;
+    `);
+
+    this.addSql(`create index "customer_interactions_email_channel_idx" on "customer_interactions" ("channel_id", "entity_id") where "interaction_type" = 'email' and "channel_id" is not null and "deleted_at" is null;`);
+  }
+
+  override async down(): Promise<void> {
+    this.addSql(`drop index if exists "customer_interactions_email_channel_idx";`);
+    this.addSql(`alter table "customer_interactions" drop column if exists "channel_id";`);
+  }
+
+}

package/src/modules/customers/setup.ts

@@ -108,6 +108,7 @@ export const setup: ModuleSetupConfig = {
       'customers.roles.view',
       'customers.roles.manage',
       'customers.email.compose',
+      'customers.email.share_conversation',
       // Required so the staff-absent fallback to /api/auth/users succeeds for employees too.
       // See `admin` entry above for full rationale.
       'auth.users.list',

package/src/modules/customers/subscribers/channel-visibility-changed.ts

@@ -0,0 +1,50 @@
+/**
+ * Subscriber for `communication_channels.channel.visibility_changed`.
+ *
+ * Flipping a whole mailbox between private and shared changes which email rows
+ * the person-detail read filter admits, without writing any resource whose
+ * collection tags the cached person-detail payload observes — so nothing else
+ * invalidates it. The revoke direction is the one that matters: without this a
+ * teammate keeps reading now-private email from their own warm cache entry for
+ * the rest of the TTL.
+ *
+ * The invalidation lives on the CUSTOMERS side because the cache it clears is
+ * this module's. `communication_channels` declares `requires: ['progress']` and
+ * must not grow a dependency on `customers` to do its own writes — the hub emits
+ * the event with the tenant/organization scope, and whoever cares reacts. Same
+ * direction as the two `link-channel-message-*` subscribers.
+ *
+ * Ephemeral on purpose. Under single-delivery, persistent subscribers run ONLY
+ * in the events worker, which would leave the stale entry readable until the
+ * queue drains; inline delivery keeps the invalidation on the same path the
+ * write already takes, matching the behaviour when the channel route called the
+ * helper directly. Cache invalidation is a read-your-writes concern, the same
+ * reason `query_index.upsert_one` is ephemeral.
+ */
+import { invalidatePersonDetailCache } from '../lib/personDetailCacheTags'
+
+type ChannelVisibilityChangedPayload = {
+  tenantId?: string | null
+  organizationId?: string | null
+}
+
+type SubscriberContext = {
+  resolve: <T = unknown>(name: string) => T
+}
+
+export const metadata = {
+  event: 'communication_channels.channel.visibility_changed',
+  persistent: false,
+  id: 'customers:channel-visibility-changed',
+}
+
+export default async function handler(
+  payload: ChannelVisibilityChangedPayload,
+  ctx: SubscriberContext,
+): Promise<void> {
+  // Fail closed: the cache tags are tenant-scoped, and building them from a null
+  // tenant would clear a tag set that belongs to no one.
+  const tenantId = typeof payload?.tenantId === 'string' && payload.tenantId ? payload.tenantId : null
+  if (!tenantId) return
+  await invalidatePersonDetailCache(ctx, tenantId, payload?.organizationId ?? null)
+}

package/src/modules/dashboards/api/widgets/data/batch/route.ts

@@ -5,6 +5,7 @@ import type { CacheStrategy } from '@open-mercato/cache'
 import { getAuthFromRequest } from '@open-mercato/shared/lib/auth/server'
 import { createRequestContainer } from '@open-mercato/shared/lib/di/container'
 import { resolveOrganizationScopeForRequest } from '@open-mercato/core/modules/directory/utils/organizationScope'
+import { resolveOrganizationScopeFilter } from '@open-mercato/core/modules/directory/utils/organizationScopeFilter'
 import {
   createWidgetDataService,
   type WidgetDataRequest,
@@ -96,13 +97,7 @@ export async function POST(req: Request) {
 
   const scope = await resolveOrganizationScopeForRequest({ container, auth, request: req })
 
-  const organizationIds = (() => {
-    if (scope?.selectedId) return [scope.selectedId]
-    if (Array.isArray(scope?.filterIds) && scope.filterIds.length > 0) return scope.filterIds
-    if (scope?.allowedIds === null) return undefined
-    if (auth.orgId) return [auth.orgId]
-    return undefined
-  })()
+  const { organizationIds, rbacOrganizationId } = resolveOrganizationScopeFilter(scope, auth)
 
   const cache = container.resolve<CacheStrategy>('cache')
   const service = createWidgetDataService(
@@ -128,7 +123,7 @@ export async function POST(req: Request) {
         if (features.length === 0) return Promise.resolve(true)
         return rbacService.userHasAllFeatures(auth.sub, features, {
           tenantId,
-          organizationId: auth.orgId,
+          organizationId: rbacOrganizationId,
         })
       },
       fetchOne: (request) => service.fetchWidgetData(request),

package/src/modules/dashboards/api/widgets/data/route.ts

@@ -4,6 +4,7 @@ import type { CacheStrategy } from '@open-mercato/cache'
 import { getAuthFromRequest } from '@open-mercato/shared/lib/auth/server'
 import { createRequestContainer } from '@open-mercato/shared/lib/di/container'
 import { resolveOrganizationScopeForRequest } from '@open-mercato/core/modules/directory/utils/organizationScope'
+import { resolveOrganizationScopeFilter } from '@open-mercato/core/modules/directory/utils/organizationScopeFilter'
 import {
   createWidgetDataService,
   type WidgetDataRequest,
@@ -49,6 +50,14 @@ export async function POST(req: Request) {
   const container = await createRequestContainer()
   const analyticsRegistry = container.resolve<AnalyticsRegistry>('analyticsRegistry')
 
+  const tenantId = auth.tenantId ?? null
+  if (!tenantId) {
+    return NextResponse.json({ error: 'Tenant context is required' }, { status: 400 })
+  }
+
+  const scope = await resolveOrganizationScopeForRequest({ container, auth, request: req })
+  const { organizationIds, rbacOrganizationId } = resolveOrganizationScopeFilter(scope, auth)
+
   const entityFeatures = analyticsRegistry.getRequiredFeatures(parsed.data.entityType)
   if (entityFeatures && entityFeatures.length > 0) {
     const rbacService = container.resolve<{
@@ -59,8 +68,8 @@ export async function POST(req: Request) {
       ) => Promise<boolean>
     }>('rbacService')
     const hasAccess = await rbacService.userHasAllFeatures(auth.sub, entityFeatures, {
-      tenantId: auth.tenantId!,
-      organizationId: auth.orgId,
+      tenantId,
+      organizationId: rbacOrganizationId,
     })
     if (!hasAccess) {
       return NextResponse.json({ error: 'Forbidden' }, { status: 403 })
@@ -73,21 +82,6 @@ export async function POST(req: Request) {
     useContext: true,
   })
 
-  const tenantId = auth.tenantId ?? null
-  if (!tenantId) {
-    return NextResponse.json({ error: 'Tenant context is required' }, { status: 400 })
-  }
-
-  const scope = await resolveOrganizationScopeForRequest({ container, auth, request: req })
-
-  const organizationIds = (() => {
-    if (scope?.selectedId) return [scope.selectedId]
-    if (Array.isArray(scope?.filterIds) && scope.filterIds.length > 0) return scope.filterIds
-    if (scope?.allowedIds === null) return undefined
-    if (auth.orgId) return [auth.orgId]
-    return undefined
-  })()
-
   const userFeatures = Array.isArray(auth.features)
     ? auth.features.filter((value): value is string => typeof value === 'string')
     : []
@@ -111,7 +105,7 @@ export async function POST(req: Request) {
       container,
       userId: auth.sub ?? '',
       tenantId,
-      organizationId: organizationIds?.[0] ?? auth.orgId ?? '',
+      organizationId: rbacOrganizationId ?? '',
       userFeatures,
     },
   })

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

@@ -198,7 +198,7 @@ function buildWhereClause(
   whereClauses.push(`tenant_id = ?`)
   params.push(options.scope.tenantId)
 
-  if (options.scope.organizationIds && options.scope.organizationIds.length > 0) {
+  if (options.scope.organizationIds !== undefined) {
     whereClauses.push(`organization_id = ANY(?::uuid[])`)
     params.push(`{${options.scope.organizationIds.join(',')}}`)
   }

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

@@ -4,6 +4,7 @@ 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'
+import { resolveOrganizationScopeFilter } from '@open-mercato/core/modules/directory/utils/organizationScopeFilter'
 
 export type WidgetScopeContext = {
   container: AppContainer
@@ -74,13 +75,7 @@ export async function resolveWidgetScope(
     throw forbiddenScope()
   }
 
-  const organizationIds = (() => {
-    if (scope?.selectedId) return [scope.selectedId]
-    if (Array.isArray(scope?.filterIds) && scope.filterIds.length > 0) return scope.filterIds
-    if (scope?.allowedIds === null) return null
-    if (auth.orgId) return [auth.orgId]
-    return [] as string[]
-  })()
+  const organizationIds = resolveOrganizationScopeFilter(scope, auth).organizationIds ?? null
 
   if (organizationIds !== null && organizationIds.length === 0) {
     throw new CrudHttpError(400, { error: translate('dashboards.errors.organization_required', 'Organization context is required') })

package/src/modules/data_sync/AGENTS.md

@@ -56,6 +56,7 @@ packages/core/src/modules/data_sync/
 │   ├── queue.ts                 # Queue helper for enqueuing sync jobs
 │   ├── batch-stream.ts          # Drives adapter streams; one root span per batch
 │   ├── run-parameters.ts        # Validate/coerce operator run parameters vs. adapter declaration
+│   ├── resume-point.ts          # What a retry of a run would do — shared by list + detail
 │   ├── sync-engine.ts           # Orchestrates streaming import/export with progress
 │   └── sync-run-service.ts      # CRUD for SyncRun + cursor management
 ├── api/
@@ -112,6 +113,10 @@ interface DataSyncAdapter {
   getMapping(input: { entityType: string; scope: TenantScope }): Promise<DataMapping>
   persistsSharedCursor?(entityType: string): boolean
   supportsStartControl?(control: 'fullSync' | 'batchSize', entityType: string): boolean
+  describeProgressJob?(input: {
+    entityType: string
+    direction: 'import' | 'export'
+  }): DataSyncProgressJobDescription | undefined
   validateConnection?(input: {
     entityType: string
     credentials: Record<string, unknown>
@@ -162,6 +167,10 @@ Run parameters are **operator-visible and stored in clear text** on
 declare a parameter that carries a secret — credentials belong in
 `integrationCredentialsService`.
 
+A **cursor is operator-visible too** — `cursor` and `initialCursor` are rendered
+verbatim on the dashboard and invited into support tickets — so never encode a
+credential or personal data in one either.
+
 **Translation.** `label`, `description` and `placeholder` are literals, so an
 adapter shipping to more than one locale MUST also set `labelKey` /
 `descriptionKey` / `placeholderKey`; the dashboard prefers the key and falls
@@ -224,6 +233,31 @@ Do not derive applicability from `persistsSharedCursor` — where a cursor is
 stored and whether restarting from scratch is meaningful are independent facts,
 and both belong to the adapter to state.
 
+### Progress job description
+
+Unless the caller passes `createProgressJob: false`, every run started through
+`startDataSyncRun` (`lib/start-run.ts`) — the run route, Retry, the scheduled
+worker and provider-owned routes — creates a `ProgressJob` that `ProgressTopBar`
+shows to every user with `progress.view`, with Cancel for anyone holding
+`progress.cancel`. An adapter may describe that
+job per entity type:
+
+```typescript
+describeProgressJob: ({ entityType }) =>
+  entityType === 'orders.feed' ? { meta: { hiddenFromTopBar: true } } : undefined,
+```
+
+Use it for an entity type whose run is long-lived — a continuously running feed
+never reaches 100%, so without it the top bar reads as running forever and
+offers a Cancel that stops the feed. `name`, `description` and `meta` merge as
+core default < adapter < the caller's own `progressJob` (meta key by key), so a
+provider route that passes `progressJob.meta` still wins. The run's identity
+keys in `meta` — `integrationId`, `entityType`, `direction` — are not the
+adapter's to overwrite. The hook is not
+consulted when the caller passes `createProgressJob: false`, and an answer that
+throws or has the wrong shape is ignored with a warning — an adapter cannot make
+itself unstartable over how its progress job reads.
+
 If the sync provider needs bootstrap credentials, mappings, locales, channels, or other default sync settings after a fresh install, implement a provider-owned env preset flow:
 
 - read env vars in the provider package
@@ -238,7 +272,7 @@ If the sync provider needs bootstrap credentials, mappings, locales, channels, o
 - **Cursor persistence**: After each batch, the cursor is saved on the run row and mirrored into the shared `SyncCursor` row
 - **Shared cursor opt-out**: An adapter returning `persistsSharedCursor(entityType) === false` keeps that entity type's cursor on the run row only — use it for whole-table backfills whose cursor is one run's scan state, not a durable log position. Those entity types resolve an incremental start position from the most recent run (`resolveResumeCursor`) instead of the shared row, and from `null` when that run completed
 - **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
+- **Retry / Resume / Run again**: three operator actions over two endpoints. **Retry** (`failed`) and **Resume** (`cancelled`) are the same request — `runs/[id]/retry` with `fromBeginning: false` — resuming from the run's committed `cursor`, or from `resolveStartCursor(...)` when it committed none. **Retry from the beginning** sends `fromBeginning: true` for a `null` start cursor; it is UI-gated on `supportsStartControl('fullSync', entityType)` while the endpoint keeps accepting the field. **Run again** (`completed`) opens the prefilled start form at `/backend/data-sync?from=<runId>` and posts `data_sync/run`. `lib/resume-point.ts` (`resolveResumePoint`) turns a run row into the one sentence both surfaces render, and never claims a start position for a run that committed no batch
 - **Progress**: Linked to `ProgressJob` via `progressJobId` for `ProgressTopBar` display
 - **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.
 - **Error reporting**: Every `level: 'error'` row the engine writes is also reported to the active telemetry backend, grouped by a `code`. A `failed` import item MAY carry `data.errorCode` (a stable `module.reason` token, never an interpolated string) alongside `data.errorMessage`; the engine ENFORCES that shape — it is a metric label, so an interpolated value would blow up cardinality and, unlike attributes, would egress unredacted — and substitutes `data_sync.item_failed` for anything else, including a missing value. A run that finishes with `failedCount > 0` additionally reports one `data_sync.run_partial_failure` summary, independent of `adapter.operationalTelemetry` — that flag decides how chatty the operational log is, never whether a failure is observable. Policy: [`error-reporting.mdx`](../../../../../apps/docs/docs/framework/runtime/error-reporting.mdx)

package/src/modules/data_sync/api/runs/[id]/cancel.ts

@@ -78,6 +78,11 @@ export async function POST(req: Request, ctx: { params?: Promise<{ id?: string }
     userId: auth.sub,
   }
 
+  const cancelledRun = await syncRunService.markStatus(run.id, 'cancelled', scope)
+  if (cancelledRun?.status !== 'cancelled') {
+    return NextResponse.json({ error: 'Only pending or running runs can be cancelled' }, { status: 409 })
+  }
+
   if (run.progressJobId) {
     try {
       await progressService.markCancelled(run.progressJobId, progressCtx)
@@ -93,7 +98,6 @@ export async function POST(req: Request, ctx: { params?: Promise<{ id?: string }
     }
   }
 
-  await syncRunService.markStatus(run.id, 'cancelled', scope)
   await integrationStateService.upsert(run.integrationId, {
     lastHealthStatus: 'degraded',
     lastHealthCheckedAt: new Date(),