@open-mercato/core 0.6.8-develop.6992.1.00c90fecff → 0.6.8-develop.6998.1.d2bc46c56c

package/generated/entities/sync_run/index.ts

@@ -14,6 +14,7 @@ export const last_error = "last_error";
 export const progress_job_id = "progress_job_id";
 export const job_id = "job_id";
 export const triggered_by = "triggered_by";
+export const parameters = "parameters";
 export const organization_id = "organization_id";
 export const tenant_id = "tenant_id";
 export const created_at = "created_at";

package/generated/entity-fields-registry.ts

@@ -3096,6 +3096,7 @@ export const entityFieldsRegistry: Record<string, Record<string, string>> = {
       "progress_job_id": "progress_job_id",
       "job_id": "job_id",
       "triggered_by": "triggered_by",
+      "parameters": "parameters",
       "organization_id": "organization_id",
       "tenant_id": "tenant_id",
       "created_at": "created_at",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@open-mercato/core",
-  "version": "0.6.8-develop.6992.1.00c90fecff",
+  "version": "0.6.8-develop.6998.1.d2bc46c56c",
   "license": "MIT",
   "type": "module",
   "main": "./dist/index.js",
@@ -254,16 +254,16 @@
     "zod": "^4.4.3"
   },
   "peerDependencies": {
-    "@open-mercato/ai-assistant": "0.6.8-develop.6992.1.00c90fecff",
-    "@open-mercato/shared": "0.6.8-develop.6992.1.00c90fecff",
-    "@open-mercato/ui": "0.6.8-develop.6992.1.00c90fecff",
+    "@open-mercato/ai-assistant": "0.6.8-develop.6998.1.d2bc46c56c",
+    "@open-mercato/shared": "0.6.8-develop.6998.1.d2bc46c56c",
+    "@open-mercato/ui": "0.6.8-develop.6998.1.d2bc46c56c",
     "react": "^19.0.0",
     "react-dom": "^19.0.0"
   },
   "devDependencies": {
-    "@open-mercato/ai-assistant": "0.6.8-develop.6992.1.00c90fecff",
-    "@open-mercato/shared": "0.6.8-develop.6992.1.00c90fecff",
-    "@open-mercato/ui": "0.6.8-develop.6992.1.00c90fecff",
+    "@open-mercato/ai-assistant": "0.6.8-develop.6998.1.d2bc46c56c",
+    "@open-mercato/shared": "0.6.8-develop.6998.1.d2bc46c56c",
+    "@open-mercato/ui": "0.6.8-develop.6998.1.d2bc46c56c",
     "@testing-library/dom": "^10.4.1",
     "@testing-library/jest-dom": "^7.0.0",
     "@testing-library/react": "^16.3.1",

package/src/modules/auth/api/sidebar/preferences/route.ts

@@ -9,9 +9,9 @@ import {
   sidebarPreferencesScopeSchema,
 } from '../../../data/validators'
 import {
+  findSidebarPreference,
   loadRoleSidebarPreferenceUpdatedAt,
   loadRoleSidebarPreferences,
-  loadSidebarPreference,
   loadSidebarPreferenceUpdatedAt,
   saveRoleSidebarPreference,
   saveSidebarPreference,
@@ -204,7 +204,7 @@ export async function GET(req: Request) {
   // For API key auth, use userId (the actual user) if available
   const effectiveUserId = auth.isApiKey ? auth.userId : auth.sub
   const settings = effectiveUserId
-    ? await loadSidebarPreference(em, {
+    ? await findSidebarPreference(em, {
         userId: effectiveUserId,
         tenantId: auth.tenantId ?? null,
         organizationId: auth.orgId ?? null,

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

@@ -33,8 +33,8 @@ import { Role } from '@open-mercato/core/modules/auth/data/entities'
 import { findOneWithDecryption } from '@open-mercato/shared/lib/encryption/find'
 import {
   applySidebarPreference,
+  findSidebarPreference,
   loadFirstRoleSidebarPreference,
-  loadSidebarPreference,
 } from '@open-mercato/core/modules/auth/services/sidebarPreferencesService'
 import type { SidebarPreferencesSettings } from '@open-mercato/shared/modules/navigation/sidebarPreferences'
 
@@ -436,7 +436,7 @@ export async function resolveBackendChromePayload({
 
   const effectiveUserId = auth.isApiKey ? auth.userId : auth.sub
   if (effectiveUserId) {
-    userPreference = await loadSidebarPreference(em, {
+    userPreference = await findSidebarPreference(em, {
       userId: effectiveUserId,
       tenantId: scopedTenantId,
       organizationId: scopedOrganizationId,

package/src/modules/auth/services/sidebarPreferencesService.ts

@@ -37,10 +37,10 @@ export type SidebarGroupLike<T = Record<string, unknown>> = {
   weight?: number
 } & T
 
-export async function loadSidebarPreference(
+export async function findSidebarPreference(
   em: EntityManager,
   scope: SidebarPreferenceScope,
-): Promise<SidebarPreferencesSettings> {
+): Promise<SidebarPreferencesSettings | null> {
   // Cross-locale: variants & preferences are scoped per (user, tenant, org) only.
   // The `locale` field on the row is kept for audit / when the row was created.
   const { userId, tenantId, organizationId } = normalizeScope(scope)
@@ -51,7 +51,26 @@ export async function loadSidebarPreference(
     undefined,
     { tenantId, organizationId },
   )
-  return normalizeSidebarSettings(existing?.settingsJson as SidebarPreferencesSettings | undefined)
+  // `null` means "no saved preference" and is distinct from "a preference exists but is empty":
+  // callers layer role defaults beneath the user layout and must skip the user pass entirely,
+  // because applying empty settings overwrites the role state instead of merging with it.
+  if (!existing) return null
+  return normalizeSidebarSettings(existing.settingsJson as SidebarPreferencesSettings | null | undefined)
+}
+
+/**
+ * @deprecated Since 0.7.1, slated for removal in 0.9.0. Use `findSidebarPreference` and handle
+ * `null`. This function fabricates a default settings object for a user with no saved row, which
+ * is indistinguishable from a saved-but-empty preference — applying that result erases any role
+ * layer underneath it, because `applySidebarPreference` overwrites `hidden` rather than merging.
+ * Migration: `(await findSidebarPreference(em, scope)) ?? normalizeSidebarSettings(null)`
+ * reproduces this exact return value if you genuinely want the defaults.
+ */
+export async function loadSidebarPreference(
+  em: EntityManager,
+  scope: SidebarPreferenceScope,
+): Promise<SidebarPreferencesSettings> {
+  return (await findSidebarPreference(em, scope)) ?? normalizeSidebarSettings(null)
 }
 
 export async function loadSidebarPreferenceUpdatedAt(

package/src/modules/data_sync/AGENTS.md

@@ -54,6 +54,7 @@ packages/core/src/modules/data_sync/
 │   ├── adapter-registry.ts      # Register/get adapters by providerKey
 │   ├── id-mapping.ts            # External ID ↔ local ID lookup and storage
 │   ├── queue.ts                 # Queue helper for enqueuing sync jobs
+│   ├── run-parameters.ts        # Validate/coerce operator run parameters vs. adapter declaration
 │   ├── sync-engine.ts           # Orchestrates streaming import/export with progress
 │   └── sync-run-service.ts      # CRUD for SyncRun + cursor management
 ├── api/
@@ -97,23 +98,97 @@ Provider modules implement `DataSyncAdapter`:
 
 ```typescript
 interface DataSyncAdapter {
-  providerKey: string
-  direction: 'import' | 'export' | 'bidirectional'
-  supportedEntities: string[]
-  streamImport(entityType: string, cursor: string | null, config: SyncConfig): AsyncIterable<ImportBatch>
-  streamExport?(entityType: string, cursor: string | null, config: SyncConfig): AsyncIterable<ExportBatch>
-  getInitialCursor?(entityType: string): Promise<string | null>
-  getMapping?(entityType: string): Promise<FieldMapping[]>
+  readonly providerKey: string
+  readonly direction: 'import' | 'export' | 'bidirectional'
+  readonly supportedEntities: string[]
+  readonly runMode?: 'generic' | 'provider'
+  readonly operationalTelemetry?: boolean
+  readonly runParameters?: RunParameter[]
+
+  streamImport?(input: StreamImportInput): AsyncIterable<ImportBatch>
+  streamExport?(input: StreamExportInput): AsyncIterable<ExportBatch>
+  getInitialCursor?(input: { entityType: string; scope: TenantScope }): Promise<string | null>
+  getMapping(input: { entityType: string; scope: TenantScope }): Promise<DataMapping>
   persistsSharedCursor?(entityType: string): boolean
-  validateConnection?(credentials: Record<string, unknown>): Promise<{ valid: boolean; message?: string }>
+  validateConnection?(input: {
+    entityType: string
+    credentials: Record<string, unknown>
+    mapping: DataMapping
+    scope: TenantScope
+  }): Promise<ValidationResult>
 }
 ```
 
+All hooks take a single input object — see `lib/adapter.ts` for the authoritative
+shapes.
+
 Register adapters in your provider module's `di.ts`:
 ```typescript
 registerDataSyncAdapter(myAdapter)
 ```
 
+### Run parameters
+
+Adapters may declare optional, operator-facing `runParameters`. The dashboard
+renders a generic input per declared parameter, the run API validates and
+coerces the submitted values against the declaration (`lib/run-parameters.ts`),
+and the normalized values are persisted on the run and passed back on
+`StreamImportInput.parameters` / `StreamExportInput.parameters`. Keep
+declarations provider-agnostic — never special-case a provider in `data_sync`.
+
+```typescript
+runParameters: [
+  { key: 'dryRun', label: 'Dry run', type: 'boolean', defaultValue: false,
+    description: 'Report what would change without writing.' },
+  { key: 'startId', label: 'Start id', type: 'number', min: 0 },
+  { key: 'mode', label: 'Mode', type: 'select',
+    options: [{ value: 'fast' }, { value: 'thorough' }] },
+  // Only offered when the orders entity is selected:
+  { key: 'bulk', label: 'Bulk reindex', type: 'boolean', entityType: 'sales_orders' },
+]
+```
+
+Supported types: `boolean`, `string`, `number`, `select`. A parameter may set
+`direction` to apply to only `import` or `export` runs, and `entityType`
+(a `supportedEntities` value or an array of them) to apply only when that
+entity is selected — use it when a knob only makes sense for one entity's run.
+Params without `direction` / `entityType` apply to every run. Blank values fall
+back to `defaultValue`; values are retained across retries.
+
+Run parameters are **operator-visible and stored in clear text** on
+`sync_runs.parameters`, and rendered read-only on the run detail page. Never
+declare a parameter that carries a secret — credentials belong in
+`integrationCredentialsService`.
+
+**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
+back to the literal. Validation failures come back from the API as
+`{ key, code, params, message }` — the UI renders `code` through
+`data_sync.runParameters.errors.<code>` and only uses the English `message` as
+a fallback, so never rely on the sentence text.
+
+**Retry re-validates.** `POST /api/data_sync/runs/[id]/retry` re-runs the stored
+values through `normalizeRunParameters` against the *current* declaration:
+parameters you have since removed or re-scoped fall away, and a value that no
+longer satisfies its declaration fails the retry with a 422 instead of reaching
+the adapter. An adapter therefore never receives a set the run API would reject
+today — tighten a bound freely.
+
+The integration detail page's schedule table also starts runs, but has no room
+for a parameter form: it submits the declared defaults and refuses the run when
+an applicable parameter is `required` with no `defaultValue`, pointing the
+operator at the Data Sync dashboard. Declare a `defaultValue` for anything that
+should stay launchable from that table.
+
+**Recurring runs get your defaults, not operator values.** A `SyncSchedule`
+cannot yet pin a chosen value, but the scheduled worker normalizes an empty
+input against your declaration, so a scheduled run hands you the same set an
+untouched dashboard form would — never an empty object. Write your adapter
+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.
+
 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

@@ -55,6 +55,7 @@ export async function GET(req: Request) {
           runMode: adapter.runMode ?? 'generic',
           canStartRun: adapter.runMode !== 'provider',
           supportedEntities: adapter.supportedEntities,
+          runParameters: adapter.runParameters ?? [],
           hasCredentials: Boolean(credentials),
           isEnabled,
           settingsPath: `/backend/integrations/${encodeURIComponent(integration.id)}`,

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

@@ -10,6 +10,7 @@ import type { SyncRunService } from '../lib/sync-run-service'
 import { runSyncSchema } from '../data/validators'
 import { startDataSyncRun } from '../lib/start-run'
 import { getDataSyncAdapter } from '../lib/adapter-registry'
+import { normalizeRunParameters } from '../lib/run-parameters'
 import { resolveStartCursor } from '../lib/start-cursor'
 import {
   runCrudMutationGuardAfterSuccess,
@@ -78,6 +79,19 @@ export async function POST(req: Request) {
       return NextResponse.json({ error: 'Unsupported entity type for this integration' }, { status: 422 })
     }
 
+    const normalizedParameters = normalizeRunParameters(
+      adapter.runParameters,
+      parsed.data.direction,
+      parsed.data.parameters,
+      parsed.data.entityType,
+    )
+    if (!normalizedParameters.ok) {
+      return NextResponse.json(
+        { error: 'Invalid run parameters', details: { parameters: normalizedParameters.errors } },
+        { status: 422 },
+      )
+    }
+
     const integrationEnabled = await integrationStateService.isEnabled(parsed.data.integrationId, scope)
     if (!integrationEnabled) {
       return NextResponse.json({ error: 'Integration is disabled' }, { status: 409 })
@@ -133,6 +147,9 @@ export async function POST(req: Request) {
         cursor,
         triggeredBy: parsed.data.triggeredBy ?? auth.sub,
         batchSize: parsed.data.batchSize,
+        parameters: Object.keys(normalizedParameters.values).length > 0
+          ? normalizedParameters.values
+          : null,
       },
     })
 

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

@@ -8,6 +8,7 @@ import type { ProgressService } from '../../../../progress/lib/progressService'
 import type { SyncRunService } from '../../../lib/sync-run-service'
 import { retrySyncSchema } from '../../../data/validators'
 import { startDataSyncRun } from '../../../lib/start-run'
+import { normalizeRunParameters } from '../../../lib/run-parameters'
 import { resolveAdapterForIntegration, resolveStartCursor } from '../../../lib/start-cursor'
 import {
   runCrudMutationGuardAfterSuccess,
@@ -88,11 +89,40 @@ export async function POST(req: Request, ctx: { params?: Promise<{ id?: string }
     return NextResponse.json(guardResult.body, { status: guardResult.status })
   }
 
+  // A retry replays the stored parameters, but the adapter's declaration may
+  // have moved on since the original run — a parameter dropped, a bound
+  // tightened, a select option removed, a scope narrowed. Re-normalize against
+  // the current declaration so an adapter never receives a set the run API
+  // would reject today. Undeclared keys fall away silently; values that are now
+  // invalid stop the retry, because the operator has no form here to fix them.
+  const retryAdapter = resolveAdapterForIntegration(previous.integrationId)
+  const normalizedParameters = normalizeRunParameters(
+    retryAdapter?.runParameters,
+    previous.direction,
+    previous.parameters ?? null,
+    previous.entityType,
+  )
+  if (!normalizedParameters.ok) {
+    return NextResponse.json(
+      {
+        error: 'Stored run parameters are no longer valid for this integration. Start a new run from the Data Sync dashboard.',
+        // Machine-readable so the dashboard can render the way out in the
+        // operator's language; the English sentence stays for non-UI callers.
+        code: 'parametersStale',
+        details: { parameters: normalizedParameters.errors },
+      },
+      { status: 422 },
+    )
+  }
+  const retryParameters = Object.keys(normalizedParameters.values).length > 0
+    ? normalizedParameters.values
+    : null
+
   const cursor = parsedBody.data.fromBeginning
     ? null
     : previous.cursor ?? await resolveStartCursor({
       syncRunService,
-      adapter: resolveAdapterForIntegration(previous.integrationId),
+      adapter: retryAdapter,
       integrationId: previous.integrationId,
       entityType: previous.entityType,
       direction: previous.direction,
@@ -113,6 +143,7 @@ export async function POST(req: Request, ctx: { params?: Promise<{ id?: string }
       cursor,
       triggeredBy: auth.sub,
       batchSize: 100,
+      parameters: retryParameters,
       progressJob: {
         name: `Retry data sync ${previous.integrationId} — ${previous.entityType}`,
       },

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

@@ -69,6 +69,7 @@ export async function GET(req: Request, ctx: { params?: Promise<{ id?: string }>
     batchesCompleted: run.batchesCompleted,
     lastError: run.lastError ?? null,
     progressJobId: run.progressJobId ?? null,
+    parameters: run.parameters ?? null,
     progressJob: progressJob
       ? {
         id: progressJob.id,

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

@@ -44,6 +44,18 @@ import {
   ShieldCheck,
 } from 'lucide-react'
 import { getSyncRunStatusVariant, getSyncSummaryVariant } from '../../lib/syncRunStatus'
+import type { RunParameter } from '../../lib/adapter'
+import { getApplicableRunParameters } from '../../lib/run-parameters'
+import {
+  RunParameterFields,
+  buildDefaultRunParameterValues,
+  buildRetryFailureMessage,
+  buildRunFailureMessage,
+  buildRunParametersPayload,
+  type RetryFailureBody,
+  type RunFailureBody,
+  type RunParameterFormValue,
+} from '../../components/RunParameterFields'
 
 type SyncRunRow = {
   id: string
@@ -73,6 +85,7 @@ type SyncOption = {
   runMode?: 'generic' | 'provider'
   canStartRun?: boolean
   supportedEntities: string[]
+  runParameters?: RunParameter[]
   hasCredentials: boolean
   isEnabled: boolean
   settingsPath: string
@@ -149,6 +162,7 @@ export default function SyncRunsDashboardPage() {
   const [selectedDirection, setSelectedDirection] = React.useState<'import' | 'export'>('import')
   const [batchSize, setBatchSize] = React.useState('100')
   const [fullSync, setFullSync] = React.useState(false)
+  const [paramValues, setParamValues] = React.useState<Record<string, RunParameterFormValue>>({})
   const [scheduleEditor, setScheduleEditor] = React.useState<SyncScheduleEditorState>(() => buildDefaultScheduleState(''))
   const [isLoadingSchedule, setIsLoadingSchedule] = React.useState(false)
   const [isSavingSchedule, setIsSavingSchedule] = React.useState(false)
@@ -231,6 +245,27 @@ export default function SyncRunsDashboardPage() {
     [selectedIntegration],
   )
 
+  const runParameters = React.useMemo(
+    () => getApplicableRunParameters(
+      selectedIntegration?.runParameters,
+      selectedDirection,
+      // Pass the state through as-is. Before an entity is chosen it is '',
+      // which matches no `entityType` and so hides scoped parameters — the
+      // wanted outcome. Mapping '' to `undefined` would mean "skip entity
+      // scoping" and show every scoped parameter instead.
+      selectedEntityType,
+    ),
+    [selectedIntegration, selectedDirection, selectedEntityType],
+  )
+
+  React.useEffect(() => {
+    setParamValues(buildDefaultRunParameterValues(runParameters))
+  }, [runParameters])
+
+  const updateParamValue = React.useCallback((key: string, value: RunParameterFormValue) => {
+    setParamValues((current) => ({ ...current, [key]: value }))
+  }, [])
+
   React.useEffect(() => {
     if (!selectedIntegration) {
       setSelectedEntityType('')
@@ -325,7 +360,7 @@ export default function SyncRunsDashboardPage() {
       flash(t('data_sync.runs.detail.retrySuccess'), 'success')
       setReloadToken((token) => token + 1)
     } else {
-      flash(t('data_sync.runs.detail.retryError'), 'error')
+      flash(buildRetryFailureMessage(call.result as RetryFailureBody | null, t), 'error')
     }
   }, [t])
 
@@ -352,27 +387,25 @@ export default function SyncRunsDashboardPage() {
       return
     }
 
+    const parameters = buildRunParametersPayload(runParameters, paramValues)
+    const requestBody: Record<string, unknown> = {
+      integrationId: selectedIntegration.integrationId,
+      entityType: selectedEntityType,
+      direction: selectedDirection,
+      batchSize: parsedBatchSize,
+      fullSync,
+    }
+    if (runParameters.length > 0) requestBody.parameters = parameters
+
     try {
       const call = await runMutation({
         // optimistic-lock-exempt: starts a new sync run (create), not a concurrent record edit
         operation: () => apiCall<{ id: string }>('/api/data_sync/run', {
           method: 'POST',
           headers: { 'Content-Type': 'application/json' },
-          body: JSON.stringify({
-            integrationId: selectedIntegration.integrationId,
-            entityType: selectedEntityType,
-            direction: selectedDirection,
-            batchSize: parsedBatchSize,
-            fullSync,
-          }),
+          body: JSON.stringify(requestBody),
         }, { fallback: null }),
-        mutationPayload: {
-          integrationId: selectedIntegration.integrationId,
-          entityType: selectedEntityType,
-          direction: selectedDirection,
-          batchSize: parsedBatchSize,
-          fullSync,
-        },
+        mutationPayload: requestBody,
         context: {
           operation: 'create',
           actionId: 'start-sync-run',
@@ -381,7 +414,11 @@ export default function SyncRunsDashboardPage() {
       })
 
       if (!call.ok || !call.result?.id) {
-        flash((call.result as { error?: string } | null)?.error ?? t('data_sync.dashboard.start.error', 'Failed to start sync run'), 'error')
+        flash(buildRunFailureMessage(
+          call.result as RunFailureBody | null,
+          t('data_sync.dashboard.start.error', 'Failed to start sync run'),
+          t,
+        ), 'error')
         return
       }
 
@@ -392,7 +429,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, router, runMutation, selectedDirection, selectedEntityType, selectedIntegration, t])
+  }, [batchSize, fullSync, paramValues, router, runMutation, runParameters, selectedDirection, selectedEntityType, selectedIntegration, t])
 
   const handleSaveSchedule = React.useCallback(async () => {
     if (!selectedIntegration || !selectedEntityType) return
@@ -784,6 +821,25 @@ export default function SyncRunsDashboardPage() {
                   </div>
                 </div>
 
+                {runParameters.length > 0 ? (
+                  <div className="mt-4 space-y-3">
+                    <div className="flex items-center gap-2">
+                      <Settings2 className="size-4 text-muted-foreground" />
+                      <h4 className="text-sm font-semibold">
+                        {t('data_sync.dashboard.start.parameters', 'Run parameters')}
+                      </h4>
+                    </div>
+                    <p className="text-xs text-muted-foreground">
+                      {t('data_sync.dashboard.start.parametersHelp', 'Optional values this integration accepts for the manual run.')}
+                    </p>
+                    <RunParameterFields
+                      params={runParameters}
+                      values={paramValues}
+                      onChange={updateParamValue}
+                    />
+                  </div>
+                ) : null}
+
                 <div className="mt-4 flex flex-wrap items-center justify-between gap-3">
                   <p className="text-xs text-muted-foreground">
                     {t('data_sync.dashboard.start.runNowFootnote', 'Manual runs show progress immediately and land on the run detail page after launch.')}

package/src/modules/data_sync/backend/data-sync/runs/[id]/page.tsx

@@ -19,6 +19,17 @@ import { LoadingMessage, ErrorMessage, RecordNotFoundState } from '@open-mercato
 import { useAppEvent } from '@open-mercato/ui/backend/injection/useAppEvent'
 import { RotateCcw, XCircle } from 'lucide-react'
 import { getSyncRunStatusVariant } from '../../../../lib/syncRunStatus'
+import {
+  buildRetryFailureMessage,
+  resolveRunParameterText,
+  type RetryFailureBody,
+} from '../../../../components/RunParameterFields'
+
+type RunParameterDeclaration = {
+  key: string
+  label?: string
+  labelKey?: string
+}
 
 type SyncRunDetail = {
   id: string
@@ -33,6 +44,7 @@ type SyncRunDetail = {
   batchesCompleted: number
   lastError: string | null
   progressJobId: string | null
+  parameters: Record<string, unknown> | null
   progressJob: {
     id: string
     status: string
@@ -111,6 +123,11 @@ export default function SyncRunDetailPage({ params }: SyncRunDetailPageProps) {
   const [logsTotal, setLogsTotal] = React.useState(0)
   const [logsPage, setLogsPage] = React.useState(1)
   const logsPageRef = React.useRef(1)
+  const [parameterLabels, setParameterLabels] = React.useState<Record<string, string>>({})
+  // Declarations cannot change between two refreshes of the same run, so the
+  // options list is fetched once per integration rather than on every progress
+  // event that re-reads the run.
+  const parameterLabelsIntegrationRef = React.useRef<string | null>(null)
 
   const resolveCurrentRunId = React.useCallback(() => {
     return runId ?? (
@@ -120,6 +137,26 @@ export default function SyncRunDetailPage({ params }: SyncRunDetailPageProps) {
     )
   }, [runId])
 
+  // The run row stores machine keys. Resolve the adapter's declared labels so a
+  // past run reads as "Start id" rather than "startId"; keys the adapter no
+  // longer declares keep their raw form, which keeps historical runs readable.
+  const loadParameterLabels = React.useCallback(async (integrationId: string) => {
+    if (parameterLabelsIntegrationRef.current === integrationId) return
+    parameterLabelsIntegrationRef.current = integrationId
+    const call = await apiCall<{ items?: Array<{ integrationId: string; runParameters?: RunParameterDeclaration[] }> }>(
+      '/api/data_sync/options',
+      undefined,
+      { fallback: { items: [] } },
+    )
+    const declared = (call.result?.items ?? []).find((item) => item.integrationId === integrationId)?.runParameters ?? []
+    const labels: Record<string, string> = {}
+    for (const param of declared) {
+      const resolved = resolveRunParameterText(t, param.labelKey, param.label)
+      if (resolved) labels[param.key] = resolved
+    }
+    setParameterLabels(labels)
+  }, [t])
+
   const loadRun = React.useCallback(async () => {
     const currentRunId = resolveCurrentRunId()
     if (!currentRunId) {
@@ -144,7 +181,10 @@ export default function SyncRunDetailPage({ params }: SyncRunDetailPageProps) {
     }
     setRun(call.result)
     setIsLoading(false)
-  }, [resolveCurrentRunId, t])
+    if (call.result.parameters && Object.keys(call.result.parameters).length > 0) {
+      void loadParameterLabels(call.result.integrationId)
+    }
+  }, [loadParameterLabels, resolveCurrentRunId, t])
 
   const loadLogs = React.useCallback(async (page?: number) => {
     const currentRunId = resolveCurrentRunId()
@@ -268,7 +308,7 @@ export default function SyncRunDetailPage({ params }: SyncRunDetailPageProps) {
       flash(t('data_sync.runs.detail.retrySuccess'), 'success')
       router.push(`/backend/data-sync/runs/${encodeURIComponent(call.result.id)}`)
     } else {
-      flash(t('data_sync.runs.detail.retryError'), 'error')
+      flash(buildRetryFailureMessage(call.result as RetryFailureBody | null, t), 'error')
     }
   }, [resolveCurrentRunId, router, runMutation, t])
 
@@ -404,6 +444,26 @@ export default function SyncRunDetailPage({ params }: SyncRunDetailPageProps) {
           </Card>
         </div>
 
+        {run.parameters && Object.keys(run.parameters).length > 0 ? (
+          <Card>
+            <CardHeader>
+              <CardTitle>{t('data_sync.runs.detail.parameters', 'Run parameters')}</CardTitle>
+            </CardHeader>
+            <CardContent>
+              <dl className="grid grid-cols-1 gap-2 sm:grid-cols-2">
+                {Object.entries(run.parameters).map(([key, value]) => (
+                  <div key={key} className="flex items-center justify-between gap-3 rounded-md border bg-card px-3 py-2 text-sm">
+                    <dt className="font-medium text-muted-foreground">{parameterLabels[key] ?? key}</dt>
+                    <dd className="font-mono text-foreground">
+                      {typeof value === 'boolean' ? String(value) : String(value ?? '')}
+                    </dd>
+                  </div>
+                ))}
+              </dl>
+            </CardContent>
+          </Card>
+        ) : null}
+
         {run.lastError && (
           <Card className="border-status-error-border bg-status-error-bg">
             <CardHeader>