@open-mercato/core 0.7.1-develop.7178.1.ab93fbaf4e → 0.7.1-develop.7180.1.9717fbbb43

package/src/helpers/integration/timesheetFixtures.ts

@@ -2,16 +2,46 @@ import { expect, type APIRequestContext } from '@playwright/test'
 import { apiRequest } from './api'
 import { deleteStaffEntityIfExists } from './staffFixtures'
 
+export type CreateTimeProjectFixtureInput = {
+  /**
+   * Required in practice: US-B1 makes a customer mandatory on project create, so a
+   * call without it cannot succeed. Pass an id from `customers.customer_entities`;
+   * `createCompanyFixture` returns one.
+   *
+   * It is typed optional only because this module is published as
+   * `@open-mercato/core/helpers/integration/timesheetFixtures`, and tightening the
+   * parameter would break every third-party spec at compile time with no
+   * deprecation window. The check below turns the omission into a named error
+   * instead of the 422 that six in-repo specs hit (T2.10).
+   */
+  customerId?: string
+  name?: string
+  code?: string
+}
+
+/**
+ * Creates a time project. `input.customerId` must be supplied — see the type above
+ * for why it is not enforced by the compiler.
+ */
 export async function createTimeProjectFixture(
   request: APIRequestContext,
   token: string,
-  input?: { name?: string; code?: string },
+  input?: CreateTimeProjectFixtureInput,
 ): Promise<string> {
+  const customerId = input?.customerId
+  if (!customerId) {
+    throw new Error(
+      '[internal] createTimeProjectFixture requires input.customerId: a customer is mandatory on ' +
+        'POST /api/staff/timesheets/time-projects, and there is no safe default to fall back to. ' +
+        'Create one first (e.g. createCompanyFixture from crmFixtures) and pass its id.',
+    )
+  }
   const response = await apiRequest(request, 'POST', '/api/staff/timesheets/time-projects', {
     token,
     data: {
       name: input?.name ?? `QA Project ${Date.now()}`,
       code: input?.code ?? `QA-${Date.now()}`,
+      customerId,
       projectType: 'internal',
       status: 'active',
     },

package/src/modules/auth/README.md

@@ -9,7 +9,7 @@ Features:
   - `mercato auth seed-roles`
   - `mercato auth add-org --name <org>`
   - `mercato auth setup --orgName <org> --email <e> --password <p> [--roles superadmin,admin] [--skip-password-policy]`
-  - `mercato auth sync-role-acls [--tenant <tenantId>] [--no-superadmin]` — re-applies each enabled module's `defaultRoleFeatures` to existing tenants. Idempotent and additive (existing custom features are preserved). Run after deploying new module features to ensure existing tenants pick them up; without `--tenant` it iterates every tenant.
+  - `mercato auth sync-role-acls [--tenant <tenantId>] [--no-superadmin]` — re-applies each enabled module's `defaultRoleFeatures` (staff roles) **and** `defaultCustomerRoleFeatures` (customer/portal roles) to existing tenants. Idempotent and additive (existing custom features are preserved; no role or ACL row is created). Run after deploying new module features to ensure existing tenants pick them up; without `--tenant` it iterates every tenant. The portal half is skipped in deployments without the `customer_accounts` module.
 
 DB entities used (defined in root schema):
 - `users` with: `email`, `password_hash`, `is_confirmed`, `last_login_at`, `organization_id`, timestamps.

package/src/modules/auth/cli.ts

@@ -21,7 +21,7 @@ import type { KmsService, TenantDek } from '@open-mercato/shared/lib/encryption/
 import crypto from 'node:crypto'
 import { formatPasswordRequirements, getPasswordPolicy, validatePassword } from '@open-mercato/shared/lib/auth/passwordPolicy'
 import { parseBooleanToken } from '@open-mercato/shared/lib/boolean'
-import { getCliModules } from '@open-mercato/shared/modules/registry'
+import { getCliModules, type Module } from '@open-mercato/shared/modules/registry'
 
 async function resolveTenantScopedRole(em: any, name: string, normalizedTenantId: string | null) {
   const existing = await em.findOne(Role, { name, tenantId: normalizedTenantId })
@@ -784,6 +784,34 @@ const setPassword: ModuleCli = {
   },
 }
 
+/**
+ * The portal half of the same sync.
+ *
+ * Staff roles pick up a module's newly declared features here; customer roles used
+ * to pick theirs up only at tenant bootstrap, so a portal feature that shipped
+ * after a tenant existed never reached that tenant's `Buyer`/`Viewer` roles and the
+ * page stayed invisible to every real customer. `customer_accounts` owns those
+ * entities and is optional, so it is reached through a guarded dynamic import: a
+ * deployment without the module syncs its staff roles exactly as before.
+ */
+async function syncCustomerRoleAcls(
+  em: EntityManager,
+  tenantId: string,
+  modules: Module[],
+): Promise<{ updatedRoleSlugs: string[]; addedFeatures: string[] } | null> {
+  let ensure: typeof import('@open-mercato/core/modules/customer_accounts/lib/customerRoleAcls').ensureDefaultCustomerRoleAcls
+  try {
+    ;({ ensureDefaultCustomerRoleAcls: ensure } = await import(
+      '@open-mercato/core/modules/customer_accounts/lib/customerRoleAcls'
+    ))
+  } catch {
+    // The portal module is not part of this deployment; staff roles are still synced.
+    return null
+  }
+  // Deliberately outside the guard: a failure of the sync itself is a real error.
+  return ensure(em, tenantId, modules)
+}
+
 const syncRoleAcls: ModuleCli = {
   command: 'sync-role-acls',
   async run(rest) {
@@ -841,7 +869,13 @@ const syncRoleAcls: ModuleCli = {
     for (const tenantId of targetTenantIds) {
       await ensureDefaultRoleAcls(em, tenantId, modules, { includeSuperadminRole })
       await ensureCustomRoleAcls(em, tenantId, modules)
+      const portal = await syncCustomerRoleAcls(em, tenantId, modules)
       console.log(`✅ Synced role ACLs for tenant ${tenantId}`)
+      if (portal && portal.addedFeatures.length) {
+        console.log(
+          `   ↳ portal roles ${portal.updatedRoleSlugs.join(', ')} gained ${portal.addedFeatures.join(', ')}`,
+        )
+      }
     }
   },
 }

package/src/modules/auth/i18n/de.json

@@ -277,6 +277,13 @@
   "auth.acl.features.staff.timesheets.manage_own": "Create/edit/delete own entries",
   "auth.acl.features.staff.timesheets.projects.manage": "Manage time projects",
   "auth.acl.features.staff.timesheets.projects.view": "View time projects",
+  "auth.acl.features.staff.timesheets.rates.view": "Sätze und Kosten ansehen",
+  "auth.acl.features.staff.timesheets.reports.manage": "Kundenberichte erstellen/bearbeiten",
+  "auth.acl.features.staff.timesheets.reports.unlock": "Berichtete Einträge entsperren",
+  "auth.acl.features.staff.timesheets.reports.view": "Kundenberichte ansehen",
+  "auth.acl.features.staff.timesheets.settings.manage": "Zeiterfassungseinstellungen verwalten",
+  "auth.acl.features.staff.timesheets.tasks.manage": "Aufgaben erstellen/bearbeiten",
+  "auth.acl.features.staff.timesheets.tasks.view": "Aufgaben ansehen",
   "auth.acl.features.staff.timesheets.view": "View own time entries",
   "auth.acl.features.staff.view": "View employees",
   "auth.acl.features.storage_providers.manage": "Manage storage providers",

package/src/modules/auth/i18n/en.json

@@ -277,6 +277,13 @@
   "auth.acl.features.staff.timesheets.manage_own": "Create/edit/delete own entries",
   "auth.acl.features.staff.timesheets.projects.manage": "Manage time projects",
   "auth.acl.features.staff.timesheets.projects.view": "View time projects",
+  "auth.acl.features.staff.timesheets.rates.view": "View rates and cost",
+  "auth.acl.features.staff.timesheets.reports.manage": "Create/edit customer reports",
+  "auth.acl.features.staff.timesheets.reports.unlock": "Unlock reported entries",
+  "auth.acl.features.staff.timesheets.reports.view": "View customer reports",
+  "auth.acl.features.staff.timesheets.settings.manage": "Manage time tracking settings",
+  "auth.acl.features.staff.timesheets.tasks.manage": "Create/edit tasks",
+  "auth.acl.features.staff.timesheets.tasks.view": "View tasks",
   "auth.acl.features.staff.timesheets.view": "View own time entries",
   "auth.acl.features.staff.view": "View employees",
   "auth.acl.features.storage_providers.manage": "Manage storage providers",

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

@@ -277,6 +277,13 @@
   "auth.acl.features.staff.timesheets.manage_own": "Create/edit/delete own entries",
   "auth.acl.features.staff.timesheets.projects.manage": "Manage time projects",
   "auth.acl.features.staff.timesheets.projects.view": "View time projects",
+  "auth.acl.features.staff.timesheets.rates.view": "Ver tarifas y costes",
+  "auth.acl.features.staff.timesheets.reports.manage": "Crear/editar informes de cliente",
+  "auth.acl.features.staff.timesheets.reports.unlock": "Desbloquear entradas reportadas",
+  "auth.acl.features.staff.timesheets.reports.view": "Ver informes de cliente",
+  "auth.acl.features.staff.timesheets.settings.manage": "Gestionar ajustes de control horario",
+  "auth.acl.features.staff.timesheets.tasks.manage": "Crear/editar tareas",
+  "auth.acl.features.staff.timesheets.tasks.view": "Ver tareas",
   "auth.acl.features.staff.timesheets.view": "View own time entries",
   "auth.acl.features.staff.view": "View employees",
   "auth.acl.features.storage_providers.manage": "Manage storage providers",

package/src/modules/auth/i18n/ko.json

@@ -277,6 +277,13 @@
   "auth.acl.features.staff.timesheets.manage_own": "Create/edit/delete own entries",
   "auth.acl.features.staff.timesheets.projects.manage": "Manage time projects",
   "auth.acl.features.staff.timesheets.projects.view": "View time projects",
+  "auth.acl.features.staff.timesheets.rates.view": "요율 및 비용 보기",
+  "auth.acl.features.staff.timesheets.reports.manage": "고객 리포트 생성/편집",
+  "auth.acl.features.staff.timesheets.reports.unlock": "보고된 항목 잠금 해제",
+  "auth.acl.features.staff.timesheets.reports.view": "고객 리포트 보기",
+  "auth.acl.features.staff.timesheets.settings.manage": "시간 추적 설정 관리",
+  "auth.acl.features.staff.timesheets.tasks.manage": "작업 생성/편집",
+  "auth.acl.features.staff.timesheets.tasks.view": "작업 보기",
   "auth.acl.features.staff.timesheets.view": "View own time entries",
   "auth.acl.features.staff.view": "View employees",
   "auth.acl.features.storage_providers.manage": "Manage storage providers",

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

@@ -277,6 +277,13 @@
   "auth.acl.features.staff.timesheets.manage_own": "Twórz, edytuj i usuwaj własne wpisy",
   "auth.acl.features.staff.timesheets.projects.manage": "Zarządzaj projektami czasu pracy",
   "auth.acl.features.staff.timesheets.projects.view": "Wyświetl projekty czasu pracy",
+  "auth.acl.features.staff.timesheets.rates.view": "Podgląd stawek i kosztów",
+  "auth.acl.features.staff.timesheets.reports.manage": "Tworzenie/edycja raportów klienta",
+  "auth.acl.features.staff.timesheets.reports.unlock": "Odblokowanie zaraportowanych wpisów",
+  "auth.acl.features.staff.timesheets.reports.view": "Podgląd raportów klienta",
+  "auth.acl.features.staff.timesheets.settings.manage": "Zarządzanie ustawieniami śledzenia czasu",
+  "auth.acl.features.staff.timesheets.tasks.manage": "Tworzenie/edycja zadań",
+  "auth.acl.features.staff.timesheets.tasks.view": "Podgląd zadań",
   "auth.acl.features.staff.timesheets.view": "Wyświetl własne wpisy czasu pracy",
   "auth.acl.features.staff.view": "Wyświetl pracowników",
   "auth.acl.features.storage_providers.manage": "Zarządzaj dostawcami pamięci masowej",

package/src/modules/auth/lib/backendChrome.tsx

@@ -220,6 +220,7 @@ const defaultGroupOrder = [
   'wms.nav.group',
   'resources.nav.group',
   'staff.nav.group',
+  'staff.time_tracking.nav.group',
   'entities.nav.group',
   'directory.nav.group',
   'attachments.nav.group',

package/src/modules/customer_accounts/lib/customerRoleAcls.ts

@@ -0,0 +1,79 @@
+/**
+ * Merging every enabled module's `setup.defaultCustomerRoleFeatures` into the
+ * `CustomerRoleAcl` rows a tenant already has.
+ *
+ * The staff side of this has always had two entry points: tenant bootstrap, and
+ * `mercato auth sync-role-acls` for tenants that already existed when a module
+ * declared a new feature. The customer side only ever ran at bootstrap, so a
+ * portal feature shipped after a tenant was created never reached the `Buyer` and
+ * `Viewer` roles that tenant is actually using — the page was simply invisible to
+ * every real customer until somebody granted it by hand. It lives here rather than
+ * in `setup.ts` so both entry points can call the same merge.
+ *
+ * Additive and idempotent: a feature is only ever added, never removed, and a role
+ * or ACL row that does not exist is skipped rather than created — seeding roles is
+ * `seedDefaultRoles`' job.
+ */
+
+import type { EntityManager } from '@mikro-orm/postgresql'
+import type { Module } from '@open-mercato/shared/modules/registry'
+import {
+  CustomerRole,
+  CustomerRoleAcl,
+} from '@open-mercato/core/modules/customer_accounts/data/entities'
+
+export type CustomerRoleAclSyncResult = {
+  /** Role slugs whose ACL row gained at least one feature. */
+  updatedRoleSlugs: string[]
+  /** Features added, across every role, deduplicated — what to report to an operator. */
+  addedFeatures: string[]
+}
+
+export async function ensureDefaultCustomerRoleAcls(
+  em: EntityManager,
+  tenantId: string,
+  modules: Module[],
+): Promise<CustomerRoleAclSyncResult> {
+  const featuresByRole: Record<string, string[]> = {}
+
+  for (const mod of modules) {
+    const customerRoleFeatures = mod.setup?.defaultCustomerRoleFeatures
+    if (!customerRoleFeatures) continue
+    for (const [roleSlug, features] of Object.entries(customerRoleFeatures)) {
+      if (!features || !features.length) continue
+      if (!featuresByRole[roleSlug]) featuresByRole[roleSlug] = []
+      featuresByRole[roleSlug].push(...features)
+    }
+  }
+
+  const result: CustomerRoleAclSyncResult = { updatedRoleSlugs: [], addedFeatures: [] }
+  const roleSlugs = Object.keys(featuresByRole)
+  if (!roleSlugs.length) return result
+
+  const added = new Set<string>()
+  for (const roleSlug of roleSlugs) {
+    const role = await em.findOne(CustomerRole, { tenantId, slug: roleSlug, deletedAt: null })
+    if (!role) continue
+
+    const acl = await em.findOne(CustomerRoleAcl, { role: role.id as any, tenantId })
+    if (!acl) continue
+
+    const currentFeatures = Array.isArray(acl.featuresJson) ? acl.featuresJson : []
+    const merged = Array.from(new Set([...currentFeatures, ...featuresByRole[roleSlug]]))
+    const changed =
+      merged.length !== currentFeatures.length ||
+      merged.some((value, index) => value !== currentFeatures[index])
+    if (!changed) continue
+
+    const known = new Set(currentFeatures)
+    acl.featuresJson = merged
+    em.persist(acl)
+    result.updatedRoleSlugs.push(roleSlug)
+    for (const feature of merged) {
+      if (!known.has(feature)) added.add(feature)
+    }
+  }
+  result.addedFeatures = Array.from(added)
+  await em.flush()
+  return result
+}

package/src/modules/customer_accounts/setup.ts

@@ -1,7 +1,7 @@
 import type { ModuleSetupConfig, DefaultCustomerRoleFeatures } from '@open-mercato/shared/modules/setup'
 import type { EntityManager } from '@mikro-orm/postgresql'
-import type { Module } from '@open-mercato/shared/modules/registry'
 import { hash } from 'bcryptjs'
+import { ensureDefaultCustomerRoleAcls } from '@open-mercato/core/modules/customer_accounts/lib/customerRoleAcls'
 import { hashForLookup } from '@open-mercato/shared/lib/encryption/aes'
 import { EXAMPLE_PORTAL_ACCOUNTS } from '@open-mercato/core/modules/customer_accounts/lib/exampleAccounts'
 import {
@@ -142,50 +142,6 @@ const DEFAULT_CUSTOMER_ROLE_FEATURES = Object.fromEntries(
   DEFAULT_ROLES.map((role) => [role.slug, [...role.acl.features]]),
 )
 
-/**
- * Collect defaultCustomerRoleFeatures from all enabled modules and merge
- * them into the corresponding CustomerRoleAcl records.
- */
-async function ensureDefaultCustomerRoleAcls(
-  em: EntityManager,
-  tenantId: string,
-  modules: Module[],
-): Promise<void> {
-  const featuresByRole: Record<string, string[]> = {}
-
-  for (const mod of modules) {
-    const customerRoleFeatures = mod.setup?.defaultCustomerRoleFeatures
-    if (!customerRoleFeatures) continue
-    for (const [roleSlug, features] of Object.entries(customerRoleFeatures)) {
-      if (!features || !features.length) continue
-      if (!featuresByRole[roleSlug]) featuresByRole[roleSlug] = []
-      featuresByRole[roleSlug].push(...features)
-    }
-  }
-
-  const roleSlugs = Object.keys(featuresByRole)
-  if (!roleSlugs.length) return
-
-  for (const roleSlug of roleSlugs) {
-    const role = await em.findOne(CustomerRole, { tenantId, slug: roleSlug, deletedAt: null })
-    if (!role) continue
-
-    const acl = await em.findOne(CustomerRoleAcl, { role: role.id as any, tenantId })
-    if (!acl) continue
-
-    const currentFeatures = Array.isArray(acl.featuresJson) ? acl.featuresJson : []
-    const merged = Array.from(new Set([...currentFeatures, ...featuresByRole[roleSlug]]))
-    const changed =
-      merged.length !== currentFeatures.length ||
-      merged.some((value, index) => value !== currentFeatures[index])
-    if (changed) {
-      acl.featuresJson = merged
-      em.persist(acl)
-    }
-  }
-  await em.flush()
-}
-
 async function seedDefaultRoles(em: EntityManager, scope: SeedScope): Promise<void> {
   for (const roleDef of DEFAULT_ROLES) {
     const existing = await em.findOne(CustomerRole, {

package/src/modules/data_sync/AGENTS.md

@@ -111,6 +111,7 @@ interface DataSyncAdapter {
   getInitialCursor?(input: { entityType: string; scope: TenantScope }): Promise<string | null>
   getMapping(input: { entityType: string; scope: TenantScope }): Promise<DataMapping>
   persistsSharedCursor?(entityType: string): boolean
+  supportsStartControl?(control: 'fullSync' | 'batchSize', entityType: string): boolean
   validateConnection?(input: {
     entityType: string
     credentials: Record<string, unknown>
@@ -190,6 +191,39 @@ against the defaults, not against `undefined`. A default that violates its own
 declaration skips the scheduled run with a logged error instead of starting it
 with a half-applied set.
 
+### Start controls
+
+The dashboard's "Run once now" card also renders two controls the framework owns
+— **Run as full sync** and **Batch size**. Whether either is meaningful for an
+entity type is adapter knowledge, so an adapter may declare it per entity type:
+
+```typescript
+supportsStartControl: (control, entityType) =>
+  !(control === 'fullSync' && entityType.endsWith('.backfill')),
+```
+
+Only an explicit `false` removes a control; an adapter that declares nothing —
+or returns nothing — keeps today's form exactly. Return `false` where the
+operator's choice reaches the adapter and changes nothing observable: an entity
+type whose cursor carries identity, so an inherited cursor is discarded and the
+run starts from the top whichever way `fullSync` is set; or one whose paging the
+source fixes, so `batchSize` is read and ignored.
+
+`api/options.ts` evaluates the predicate across `supportedEntities` and ships the
+result as `startControls` — a **sparse** map, so an entity type with no
+restriction is omitted and an adapter that declares nothing serializes to `{}`.
+`lib/start-controls.ts` owns both halves (`resolveStartControlMap` server-side,
+`applicableStartControls` in the dashboard); a predicate that throws is treated
+as *applies*, because the options route resolves every registered adapter in one
+response.
+
+**This governs what the dashboard offers, never what the API accepts.**
+`POST /api/data_sync/run` keeps honouring both fields, so a client posting
+`fullSync: true` still gets a `null` start cursor whatever the adapter declares.
+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.
+
 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

package/src/modules/data_sync/api/options.ts

@@ -6,6 +6,7 @@ import { getAllIntegrations } from '@open-mercato/shared/modules/integrations/ty
 import type { CredentialsService } from '../../integrations/lib/credentials-service'
 import type { IntegrationStateService } from '../../integrations/lib/state-service'
 import { getDataSyncAdapter } from '../lib/adapter-registry'
+import { resolveStartControlMap } from '../lib/start-controls'
 
 export const metadata = {
   GET: { requireAuth: true, requireFeatures: ['data_sync.view'] },
@@ -56,6 +57,7 @@ export async function GET(req: Request) {
           canStartRun: adapter.runMode !== 'provider',
           supportedEntities: adapter.supportedEntities,
           runParameters: adapter.runParameters ?? [],
+          startControls: resolveStartControlMap(adapter),
           hasCredentials: Boolean(credentials),
           isEnabled,
           settingsPath: `/backend/integrations/${encodeURIComponent(integration.id)}`,

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

@@ -31,6 +31,7 @@ import { surfaceRecordConflict } from '@open-mercato/ui/backend/conflicts'
 import { flash } from '@open-mercato/ui/backend/FlashMessages'
 import { useOrganizationScopeVersion } from '@open-mercato/shared/lib/frontend/useOrganizationScope'
 import { useT } from '@open-mercato/shared/lib/i18n/context'
+import { cn } from '@open-mercato/shared/lib/utils'
 import {
   ArrowRightLeft,
   Boxes,
@@ -46,6 +47,11 @@ import {
 import { getSyncRunStatusVariant, getSyncSummaryVariant } from '../../lib/syncRunStatus'
 import type { RunParameter } from '../../lib/adapter'
 import { getApplicableRunParameters } from '../../lib/run-parameters'
+import {
+  applicableStartControls,
+  type StartControlApplicability,
+  type StartControlMap,
+} from '../../lib/start-controls'
 import {
   RunParameterFields,
   buildDefaultRunParameterValues,
@@ -87,6 +93,7 @@ type SyncOption = {
   canStartRun?: boolean
   supportedEntities: string[]
   runParameters?: RunParameter[]
+  startControls?: StartControlMap
   hasCredentials: boolean
   isEnabled: boolean
   settingsPath: string
@@ -127,6 +134,20 @@ type SyncScheduleEditorState = {
 
 const DEFAULT_TIMEZONE = Intl.DateTimeFormat().resolvedOptions().timeZone || 'UTC'
 
+/** Matches `runSyncSchema`'s own default, so omitting the field submits this value. */
+const DEFAULT_BATCH_SIZE = '100'
+
+/**
+ * Keeps the batch size input at its own narrow width without leaving a phantom
+ * track: the second column exists only when the full sync card fills it. With
+ * only that card the row falls back to one full-width column.
+ */
+function startControlsGridClass(controls: StartControlApplicability): string | undefined {
+  if (controls.batchSize && controls.fullSync) return 'sm:grid-cols-[minmax(0,180px)_1fr]'
+  if (controls.batchSize) return 'sm:grid-cols-[minmax(0,180px)]'
+  return undefined
+}
+
 function formatEntityTypeLabel(entityType: string): string {
   return entityType
     .replace(/[_-]+/g, ' ')
@@ -162,7 +183,7 @@ export default function SyncRunsDashboardPage() {
   const [selectedIntegrationId, setSelectedIntegrationId] = React.useState('')
   const [selectedEntityType, setSelectedEntityType] = React.useState('')
   const [selectedDirection, setSelectedDirection] = React.useState<'import' | 'export'>('import')
-  const [batchSize, setBatchSize] = React.useState('100')
+  const [batchSize, setBatchSize] = React.useState(DEFAULT_BATCH_SIZE)
   const [fullSync, setFullSync] = React.useState(false)
   const [paramValues, setParamValues] = React.useState<Record<string, RunParameterFormValue>>({})
   const [scheduleEditor, setScheduleEditor] = React.useState<SyncScheduleEditorState>(() => buildDefaultScheduleState(''))
@@ -261,10 +282,27 @@ export default function SyncRunsDashboardPage() {
     [selectedIntegration, selectedDirection, selectedEntityType],
   )
 
+  // Before an entity is chosen the state is '', which matches no declaration and
+  // so renders both controls — the unselected form as it is today.
+  const startControls = React.useMemo(
+    () => applicableStartControls(selectedIntegration?.startControls, selectedEntityType),
+    [selectedIntegration, selectedEntityType],
+  )
+
   React.useEffect(() => {
     setParamValues(buildDefaultRunParameterValues(runParameters))
   }, [runParameters])
 
+  // A control the form stopped showing must not keep submitting the value the
+  // operator last set for another entity type.
+  React.useEffect(() => {
+    if (!startControls.fullSync) setFullSync(false)
+  }, [startControls.fullSync])
+
+  React.useEffect(() => {
+    if (!startControls.batchSize) setBatchSize(DEFAULT_BATCH_SIZE)
+  }, [startControls.batchSize])
+
   const updateParamValue = React.useCallback((key: string, value: RunParameterFormValue) => {
     setParamValues((current) => ({ ...current, [key]: value }))
   }, [])
@@ -384,20 +422,23 @@ export default function SyncRunsDashboardPage() {
   const handleStartSync = React.useCallback(async () => {
     if (!selectedIntegration || !selectedEntityType) return
 
-    const parsedBatchSize = Number.parseInt(batchSize, 10)
-    if (!Number.isFinite(parsedBatchSize) || parsedBatchSize < 1 || parsedBatchSize > 1000) {
-      flash(t('data_sync.dashboard.start.invalidBatchSize', 'Batch size must be between 1 and 1000.'), 'error')
-      return
-    }
-
     const parameters = buildRunParametersPayload(runParameters, paramValues)
+    // A control the adapter declared inapplicable is left out entirely, so
+    // `runSyncSchema`'s defaults supply exactly what the rendered form sends.
     const requestBody: Record<string, unknown> = {
       integrationId: selectedIntegration.integrationId,
       entityType: selectedEntityType,
       direction: selectedDirection,
-      batchSize: parsedBatchSize,
-      fullSync,
     }
+    if (startControls.batchSize) {
+      const parsedBatchSize = Number.parseInt(batchSize, 10)
+      if (!Number.isFinite(parsedBatchSize) || parsedBatchSize < 1 || parsedBatchSize > 1000) {
+        flash(t('data_sync.dashboard.start.invalidBatchSize', 'Batch size must be between 1 and 1000.'), 'error')
+        return
+      }
+      requestBody.batchSize = parsedBatchSize
+    }
+    if (startControls.fullSync) requestBody.fullSync = fullSync
     if (runParameters.length > 0) requestBody.parameters = parameters
 
     try {
@@ -432,7 +473,7 @@ export default function SyncRunsDashboardPage() {
       const message = error instanceof Error ? error.message : t('data_sync.dashboard.start.error', 'Failed to start sync run')
       flash(message, 'error')
     }
-  }, [batchSize, fullSync, paramValues, router, runMutation, runParameters, selectedDirection, selectedEntityType, selectedIntegration, t])
+  }, [batchSize, fullSync, paramValues, router, runMutation, runParameters, selectedDirection, selectedEntityType, selectedIntegration, startControls, t])
 
   const handleSaveSchedule = React.useCallback(async () => {
     if (!selectedIntegration || !selectedEntityType) return
@@ -791,7 +832,9 @@ export default function SyncRunsDashboardPage() {
                       <h3 className="text-sm font-semibold">{t('data_sync.dashboard.start.runNowTitle', 'Run once now')}</h3>
                     </div>
                     <p className="text-sm text-muted-foreground">
-                      {t('data_sync.dashboard.start.runNowDescription', 'Use this for the next immediate sync. Batch size and full-sync mode apply only to this manual run.')}
+                      {startControls.batchSize && startControls.fullSync
+                        ? t('data_sync.dashboard.start.runNowDescription', 'Use this for the next immediate sync. Batch size and full-sync mode apply only to this manual run.')
+                        : t('data_sync.dashboard.start.runNowDescriptionScoped', 'Use this for the next immediate sync. Anything set here applies only to this manual run.')}
                     </p>
                   </div>
                   <Badge variant="outline">{selectedEntityLabel}</Badge>
@@ -799,30 +842,36 @@ export default function SyncRunsDashboardPage() {
 
                 <Separator className="my-4" />
 
-                <div className="grid gap-4 sm:grid-cols-[minmax(0,180px)_1fr]">
-                  <div className="space-y-2">
-                    <Label className="flex items-center gap-2 text-sm font-medium">
-                      <Gauge className="size-4 text-muted-foreground" />
-                      <span>{t('data_sync.dashboard.start.batchSize', 'Batch size')}</span>
-                    </Label>
-                    <Input
-                      value={batchSize}
-                      onChange={(event) => setBatchSize(event.target.value)}
-                      inputMode="numeric"
-                    />
-                  </div>
-                  <div className="rounded-lg border bg-background p-3">
-                    <div className="flex items-center justify-between gap-3">
-                      <div className="space-y-1">
-                        <Label className="text-sm font-medium">{t('data_sync.dashboard.start.fullSync', 'Run as full sync')}</Label>
-                        <p className="text-xs text-muted-foreground">
-                          {t('data_sync.dashboard.start.fullSyncHelp', 'Ignore the saved cursor and process the entire source again for this run.')}
-                        </p>
+                {startControls.batchSize || startControls.fullSync ? (
+                  <div className={cn('grid gap-4', startControlsGridClass(startControls))}>
+                    {startControls.batchSize ? (
+                      <div className="space-y-2">
+                        <Label className="flex items-center gap-2 text-sm font-medium">
+                          <Gauge className="size-4 text-muted-foreground" />
+                          <span>{t('data_sync.dashboard.start.batchSize', 'Batch size')}</span>
+                        </Label>
+                        <Input
+                          value={batchSize}
+                          onChange={(event) => setBatchSize(event.target.value)}
+                          inputMode="numeric"
+                        />
                       </div>
-                      <Switch checked={fullSync} onCheckedChange={setFullSync} />
-                    </div>
+                    ) : null}
+                    {startControls.fullSync ? (
+                      <div className="rounded-lg border bg-background p-3">
+                        <div className="flex items-center justify-between gap-3">
+                          <div className="space-y-1">
+                            <Label className="text-sm font-medium">{t('data_sync.dashboard.start.fullSync', 'Run as full sync')}</Label>
+                            <p className="text-xs text-muted-foreground">
+                              {t('data_sync.dashboard.start.fullSyncHelp', 'Ignore the saved cursor and process the entire source again for this run.')}
+                            </p>
+                          </div>
+                          <Switch checked={fullSync} onCheckedChange={setFullSync} />
+                        </div>
+                      </div>
+                    ) : null}
                   </div>
-                </div>
+                ) : null}
 
                 {runParameters.length > 0 ? (
                   <div className="mt-4 space-y-3">

package/src/modules/data_sync/i18n/de.json

@@ -59,6 +59,7 @@
   "data_sync.dashboard.start.parametersHelp": "Optionale Werte, die diese Integration für den manuellen Lauf akzeptiert.",
   "data_sync.dashboard.start.providerManaged": "Diese Integration startet Synchronisierungsläufe über ihren eigenen Einrichtungsablauf. Öffne die Integrationseinstellungen, um fortzufahren.",
   "data_sync.dashboard.start.runNowDescription": "Use this for the next immediate sync. Batch size and full-sync mode apply only to this manual run.",
+  "data_sync.dashboard.start.runNowDescriptionScoped": "Use this for the next immediate sync. Anything set here applies only to this manual run.",
   "data_sync.dashboard.start.runNowFootnote": "Manual runs show progress immediately and land on the run detail page after launch.",
   "data_sync.dashboard.start.runNowTitle": "Run once now",
   "data_sync.dashboard.start.status.credentialsMissing": "Credentials missing",

package/src/modules/data_sync/i18n/en.json

@@ -59,6 +59,7 @@
   "data_sync.dashboard.start.parametersHelp": "Optional values this integration accepts for the manual run.",
   "data_sync.dashboard.start.providerManaged": "This integration starts sync runs from its own setup flow. Open the integration settings page to continue.",
   "data_sync.dashboard.start.runNowDescription": "Use this for the next immediate sync. Batch size and full-sync mode apply only to this manual run.",
+  "data_sync.dashboard.start.runNowDescriptionScoped": "Use this for the next immediate sync. Anything set here applies only to this manual run.",
   "data_sync.dashboard.start.runNowFootnote": "Manual runs show progress immediately and land on the run detail page after launch.",
   "data_sync.dashboard.start.runNowTitle": "Run once now",
   "data_sync.dashboard.start.status.credentialsMissing": "Credentials missing",

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

@@ -59,6 +59,7 @@
   "data_sync.dashboard.start.parametersHelp": "Valores opcionales que esta integración acepta para la ejecución manual.",
   "data_sync.dashboard.start.providerManaged": "Esta integración inicia las sincronizaciones desde su propio flujo de configuración. Abre la página de ajustes de la integración para continuar.",
   "data_sync.dashboard.start.runNowDescription": "Use this for the next immediate sync. Batch size and full-sync mode apply only to this manual run.",
+  "data_sync.dashboard.start.runNowDescriptionScoped": "Use this for the next immediate sync. Anything set here applies only to this manual run.",
   "data_sync.dashboard.start.runNowFootnote": "Manual runs show progress immediately and land on the run detail page after launch.",
   "data_sync.dashboard.start.runNowTitle": "Run once now",
   "data_sync.dashboard.start.status.credentialsMissing": "Credentials missing",

package/src/modules/data_sync/i18n/ko.json

@@ -59,6 +59,7 @@
   "data_sync.dashboard.start.parametersHelp": "이 통합이 수동 실행에 대해 허용하는 선택적 값입니다.",
   "data_sync.dashboard.start.providerManaged": "이 통합은 자체 설정 흐름에서 동기화 실행을 시작합니다. 계속하려면 통합 설정 페이지를 여세요.",
   "data_sync.dashboard.start.runNowDescription": "다음 즉시 동기화에 사용하세요. 배치 크기와 전체 동기화 모드는 이 수동 실행에만 적용됩니다.",
+  "data_sync.dashboard.start.runNowDescriptionScoped": "다음 즉시 동기화에 사용하세요. 여기에서 설정한 값은 이 수동 실행에만 적용됩니다.",
   "data_sync.dashboard.start.runNowFootnote": "수동 실행은 즉시 진행 상황을 표시하며 시작 후 실행 상세 페이지로 이동합니다.",
   "data_sync.dashboard.start.runNowTitle": "지금 한 번 실행",
   "data_sync.dashboard.start.status.credentialsMissing": "자격 증명 누락",