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

package/src/modules/data_sync/lib/sync-engine.ts

@@ -94,12 +94,28 @@ function applyExportCounters(batch: ExportBatch): SyncCounterDelta {
 }
 
 // Adapter batches can legitimately outlast the stale-job sweep window (slow upstream
-// APIs), so the engine must heartbeat while a batch is still being produced.
+// APIs), so the engine must heartbeat while a batch is still being produced. The same
+// tick also polls cancellation, so a cancel lands within one interval instead of waiting
+// out the batch — sharing this timer rather than adding a second one that would double
+// the per-interval round-trips for the whole life of a run.
 const HEARTBEAT_TICK_MS = (STALE_JOB_TIMEOUT_SECONDS * 1000) / 4
 
 // Runs `tick` on an interval only while the source iterator is pending, so heartbeats
 // stop the moment the producer dies and genuinely stale jobs still get swept. The outer
 // finally closes the adapter generator on early exits (cancellation, ownership conflict).
+// Our own abort, as opposed to a failure that merely coincided with one. Adapters are told to
+// return rather than throw, but `signal.throwIfAborted()` and an aborted `fetch` both surface as
+// this, and either is a cancellation rather than a fault.
+//
+// Matched structurally on `name` rather than with `instanceof Error`, because those two throw a
+// `DOMException`, and whether that inherits from `Error` depends on the runtime — it does under
+// bare Node 24 and does NOT under the jest environment this is tested in. An `instanceof` test
+// therefore passes or fails on where the code runs, which is not something cancellation should
+// depend on.
+function isAbortError(error: unknown): boolean {
+  return typeof error === 'object' && error !== null && (error as { name?: unknown }).name === 'AbortError'
+}
+
 async function* withHeartbeat<T>(source: AsyncIterable<T>, tick: () => void, intervalMs: number): AsyncGenerator<T, void, undefined> {
   const iterator = source[Symbol.asyncIterator]()
   try {
@@ -187,6 +203,32 @@ export function createSyncEngine(deps: EngineDeps) {
     }
   }
 
+  // Rides the heartbeat timer, which is the only thing that runs while the adapter is still
+  // producing a batch — the engine's own cancellation check sits in the batch handler and is
+  // reached only after a yield. Swallows its own errors because it runs on a timer, where an
+  // unhandled rejection is fatal, and stops polling once it has aborted.
+  function makeCancellationTick(progressJobId: string | null | undefined, scope: SyncScope, controller: AbortController): () => void {
+    if (!progressJobId) return () => {}
+    let inFlight = false
+    return () => {
+      if (inFlight || controller.signal.aborted) return
+      inFlight = true
+      progressService.isCancellationRequested(progressJobId, scope.tenantId, scope.organizationId)
+        .then((cancelled) => {
+          if (cancelled) controller.abort()
+        })
+        .catch((error) => {
+          logger.warn('Cancellation poll failed', {
+            progressJobId,
+            error: error instanceof Error ? error.message : String(error),
+          })
+        })
+        .finally(() => {
+          inFlight = false
+        })
+    }
+  }
+
   async function refreshCoverageSnapshots(entityTypes: string[] | undefined, scope: SyncScope): Promise<void> {
     if (!entityTypes || entityTypes.length === 0) return
 
@@ -559,10 +601,17 @@ export function createSyncEngine(deps: EngineDeps) {
       let processedCount = await seedProcessedCount(run.progressJobId, scope)
       let totalCount: number | null = null
       let committedBatches = activeRun.batchesCompleted ?? 0
+      // Whether the last committed batch said the source was exhausted. Distinguishes a stream that
+      // drained from one the adapter stopped early — see the post-stream finalize below.
+      let streamReportedDone = false
       // Captured while the triggering job's span is still the active one, so
       // every rooted batch trace can link back to it.
       const runTrace = captureTelemetryTrace()
       const spanAttributes = runSpanAttributes(run, providerKey, scope)
+      // Declared outside the try because both the catch and the completion path below read it.
+      const cancellation = new AbortController()
+      const heartbeat = makeHeartbeatTick(run.progressJobId, scope)
+      const pollCancellation = makeCancellationTick(run.progressJobId, scope, cancellation)
 
       try {
         const streamResult = await forEachBatch(
@@ -576,8 +625,11 @@ export function createSyncEngine(deps: EngineDeps) {
               scope: { organizationId: scope.organizationId, tenantId: scope.tenantId },
               runId: run.id,
               parameters: (run.parameters ?? {}) as RunParameters,
+              signal: cancellation.signal,
             }),
-            makeHeartbeatTick(run.progressJobId, scope),
+            // `finally` so a synchronous throw from the heartbeat cannot also stop cancellation
+            // from being observed for the rest of the run.
+            () => { try { heartbeat() } finally { pollCancellation() } },
             HEARTBEAT_TICK_MS,
           ),
           {
@@ -592,7 +644,7 @@ export function createSyncEngine(deps: EngineDeps) {
               'data_sync.batch_size': batch.items.length,
             })
 
-            if (run.progressJobId && await progressService.isCancellationRequested(run.progressJobId, scope.tenantId, scope.organizationId)) {
+            if (cancellation.signal.aborted || (run.progressJobId && await progressService.isCancellationRequested(run.progressJobId, scope.tenantId, scope.organizationId))) {
               await finalizeRun(run.id, 'cancelled', scope, undefined, operationalTelemetry)
               return 'stop'
             }
@@ -621,6 +673,7 @@ export function createSyncEngine(deps: EngineDeps) {
               { expectedBatchesCompleted: committedBatches, persistSharedCursor },
             )
             committedBatches += 1
+            streamReportedDone = batch.hasMore === false
 
             await updateProgress(run.progressJobId, processedCount, totalCount, scope)
             await refreshCoverageSnapshots(batch.refreshCoverageEntityTypes, scope)
@@ -657,6 +710,15 @@ export function createSyncEngine(deps: EngineDeps) {
           })
           return
         }
+        // An adapter that honours the signal may reject instead of returning, so our own abort is
+        // a cancellation rather than a fault — and must not leave an `error` entry in the
+        // integration log for a run the operator cancelled on purpose. Anything else that merely
+        // coincided with the cancel — a rejecting commit, an upstream 500 — is a genuine failure
+        // and keeps its log entry, its message, its `failed` status and its failed event.
+        if (cancellation.signal.aborted && isAbortError(error)) {
+          await finalizeRun(run.id, 'cancelled', scope, undefined, operationalTelemetry)
+          return
+        }
         const message = error instanceof Error ? error.message : 'Sync import failed'
         await integrationLogService.write(
           {
@@ -671,6 +733,19 @@ export function createSyncEngine(deps: EngineDeps) {
         return
       }
 
+      // An adapter that honours the signal stops mid-batch and returns WITHOUT yielding, so the
+      // batch handler — which owns the only other `cancelled` transition — never runs and the
+      // stream reports `completed`.
+      //
+      // `streamReportedDone` keeps that from swallowing a run that genuinely finished: an adapter
+      // that ignores the signal and drains after reporting `hasMore: false` delivered everything it
+      // had, even when the cancel landed during the final read. Calling that cancelled would tell
+      // the operator a complete sync was partial and leave a finished run resumable.
+      if (cancellation.signal.aborted && !streamReportedDone) {
+        await finalizeRun(run.id, 'cancelled', scope, undefined, operationalTelemetry)
+        return
+      }
+
       await finalizeRun(run.id, 'completed', scope, undefined, operationalTelemetry)
     },
 
@@ -753,10 +828,17 @@ export function createSyncEngine(deps: EngineDeps) {
       const mapping = await resolveMapping(adapter, run.entityType, scope)
       let processedCount = await seedProcessedCount(run.progressJobId, scope)
       let committedBatches = activeRun.batchesCompleted ?? 0
+      // Whether the last committed batch said the source was exhausted. Distinguishes a stream that
+      // drained from one the adapter stopped early — see the post-stream finalize below.
+      let streamReportedDone = false
       // Captured while the triggering job's span is still the active one, so
       // every rooted batch trace can link back to it.
       const runTrace = captureTelemetryTrace()
       const spanAttributes = runSpanAttributes(run, providerKey, scope)
+      // Declared outside the try because both the catch and the completion path below read it.
+      const cancellation = new AbortController()
+      const heartbeat = makeHeartbeatTick(run.progressJobId, scope)
+      const pollCancellation = makeCancellationTick(run.progressJobId, scope, cancellation)
 
       try {
         const streamResult = await forEachBatch(
@@ -770,8 +852,11 @@ export function createSyncEngine(deps: EngineDeps) {
               scope: { organizationId: scope.organizationId, tenantId: scope.tenantId },
               runId: run.id,
               parameters: (run.parameters ?? {}) as RunParameters,
+              signal: cancellation.signal,
             }),
-            makeHeartbeatTick(run.progressJobId, scope),
+            // `finally` so a synchronous throw from the heartbeat cannot also stop cancellation
+            // from being observed for the rest of the run.
+            () => { try { heartbeat() } finally { pollCancellation() } },
             HEARTBEAT_TICK_MS,
           ),
           {
@@ -786,7 +871,7 @@ export function createSyncEngine(deps: EngineDeps) {
               'data_sync.batch_size': batch.results.length,
             })
 
-            if (run.progressJobId && await progressService.isCancellationRequested(run.progressJobId, scope.tenantId, scope.organizationId)) {
+            if (cancellation.signal.aborted || (run.progressJobId && await progressService.isCancellationRequested(run.progressJobId, scope.tenantId, scope.organizationId))) {
               await finalizeRun(run.id, 'cancelled', scope, undefined, operationalTelemetry)
               return 'stop'
             }
@@ -815,6 +900,7 @@ export function createSyncEngine(deps: EngineDeps) {
               { expectedBatchesCompleted: committedBatches, persistSharedCursor },
             )
             committedBatches += 1
+            streamReportedDone = batch.hasMore === false
             await updateProgress(run.progressJobId, processedCount, null, scope)
             await logExportItemFailures(run.id, run.integrationId, batch.results, scope)
 
@@ -846,6 +932,15 @@ export function createSyncEngine(deps: EngineDeps) {
           })
           return
         }
+        // An adapter that honours the signal may reject instead of returning, so our own abort is
+        // a cancellation rather than a fault — and must not leave an `error` entry in the
+        // integration log for a run the operator cancelled on purpose. Anything else that merely
+        // coincided with the cancel — a rejecting commit, an upstream 500 — is a genuine failure
+        // and keeps its log entry, its message, its `failed` status and its failed event.
+        if (cancellation.signal.aborted && isAbortError(error)) {
+          await finalizeRun(run.id, 'cancelled', scope, undefined, operationalTelemetry)
+          return
+        }
         const message = error instanceof Error ? error.message : 'Sync export failed'
         await integrationLogService.write(
           {
@@ -860,6 +955,19 @@ export function createSyncEngine(deps: EngineDeps) {
         return
       }
 
+      // An adapter that honours the signal stops mid-batch and returns WITHOUT yielding, so the
+      // batch handler — which owns the only other `cancelled` transition — never runs and the
+      // stream reports `completed`.
+      //
+      // `streamReportedDone` keeps that from swallowing a run that genuinely finished: an adapter
+      // that ignores the signal and drains after reporting `hasMore: false` delivered everything it
+      // had, even when the cancel landed during the final read. Calling that cancelled would tell
+      // the operator a complete sync was partial and leave a finished run resumable.
+      if (cancellation.signal.aborted && !streamReportedDone) {
+        await finalizeRun(run.id, 'cancelled', scope, undefined, operationalTelemetry)
+        return
+      }
+
       await finalizeRun(run.id, 'completed', scope, undefined, operationalTelemetry)
     },
   }

package/src/modules/data_sync/workers/sync-export.ts

@@ -7,6 +7,7 @@ import {
   DATA_SYNC_LOCK_DURATION_MS,
   DATA_SYNC_MAX_STALLED_COUNT,
 } from '../lib/queue-policy'
+import { failAbandonedRun } from '../lib/abandoned-run'
 import { createLogger } from '@open-mercato/shared/lib/logger'
 
 const logger = createLogger('data_sync').child({ component: 'sync-export' })
@@ -27,6 +28,9 @@ export const metadata: WorkerMeta = {
   concurrency: 5,
   lockDuration: DATA_SYNC_LOCK_DURATION_MS,
   maxStalledCount: DATA_SYNC_MAX_STALLED_COUNT,
+  // Declared on the worker, not on the enqueueing queue: the abandonment this reports is a worker
+  // restart, and the process that restarts never constructs the producer's queue instance.
+  onJobAbandoned: failAbandonedRun,
 }
 
 type HandlerContext = JobContext & {

package/src/modules/data_sync/workers/sync-import.ts

@@ -7,6 +7,7 @@ import {
   DATA_SYNC_LOCK_DURATION_MS,
   DATA_SYNC_MAX_STALLED_COUNT,
 } from '../lib/queue-policy'
+import { failAbandonedRun } from '../lib/abandoned-run'
 import { createLogger } from '@open-mercato/shared/lib/logger'
 
 const logger = createLogger('data_sync').child({ component: 'sync-import' })
@@ -27,6 +28,9 @@ export const metadata: WorkerMeta = {
   concurrency: 5,
   lockDuration: DATA_SYNC_LOCK_DURATION_MS,
   maxStalledCount: DATA_SYNC_MAX_STALLED_COUNT,
+  // Declared on the worker, not on the enqueueing queue: the abandonment this reports is a worker
+  // restart, and the process that restarts never constructs the producer's queue instance.
+  onJobAbandoned: failAbandonedRun,
 }
 
 type HandlerContext = JobContext & {

package/src/modules/devices/AGENTS.md

@@ -23,6 +23,14 @@ delivery logic** (sender, providers, delivery rows, workers live in the `push_no
   — they carry undo snapshots, query-index side effects, and domain events.
 - Treat `push_token` as a secret: **never** include it in list/response field sets. Only
   `push_provider` and `push_token_updated_at` are exposed.
+- Serialize every GET response in **camelCase**, like every other module. The list routes run
+  `transformDeviceListItem` (`api/deviceList.ts`) over the query engine's raw projection and the admin
+  detail route uses `serializeDeviceDetail` (`api/deviceSerialization.ts`). Both also emit the legacy
+  snake_case keys as **deprecated aliases** via `toDeprecatedSnakeCaseAliases`, kept for one minor
+  version per `BACKWARD_COMPATIBILITY.md` § 7 and pinned by `TC-DEV-007`; when the bridge is dropped,
+  remove the alias spread from those two functions and the deprecated keys from `deviceListItemSchema`
+  / `deviceDetailItemSchema`. Adding a column means adding it to `deviceListFields`, the transform, and
+  the schemas. See `.ai/specs/2026-08-24-devices-api-camelcase-responses.md` (#5513).
 - Honor the `pushToken` tri-state on `PUT`: absent key = leave unchanged; explicit `null` = clear
   (revoked OS permission) and bump `push_token_updated_at`. The command uses own-property presence.
 - Keep the list route's CRUD cache tag aligned with the command's `resourceKind`. The list reads
@@ -89,9 +97,20 @@ write busts both caches (see cache-tag note above).
 ## ACL
 
 `devices.view`, `devices.manage` (self-serve), `devices.admin` (cross-user). Defaults in `setup.ts`:
-`superadmin`/`admin` get `devices.*`; `employee` gets `view` + `manage`. Run
+`superadmin`/`admin` get `devices.*` **plus `auth.users.list`**; `employee` gets `view` + `manage`. Run
 `yarn mercato auth sync-role-acls` after changing `acl.ts`/`setup.ts` to backfill existing tenants.
 
+`devices.admin` declares `dependsOn: ['auth.users.list']`: the admin screens name owners by person,
+and the register form's owner picker rejects values that do not resolve to a directory entry, so a
+role holding `devices.admin` without the dependency cannot complete that form. `dependsOn` only
+surfaces the gap in the ACL editor — it does not grant. Run the sync command above after deploying
+an ACL change here.
+
+The picker is `allowCustomValues: false`. That rejects free text and an id belonging to nobody; it
+does **not** reject a raw id that is already a known option, because `ComboboxInput` matches on
+`option.value` and `CrudForm` keeps the unfiltered first page as suggestions for the form's
+lifetime. Either way the submitted value is a real user in the caller's scope.
+
 ## Validation Commands
 
 ```bash

package/src/modules/devices/acl.ts

@@ -1,7 +1,15 @@
 export const features = [
   { id: 'devices.view', title: 'View own devices', module: 'devices' },
   { id: 'devices.manage', title: 'Manage own devices', module: 'devices' },
-  { id: 'devices.admin', title: 'Manage devices across users', module: 'devices' },
+  {
+    id: 'devices.admin',
+    title: 'Manage devices across users',
+    module: 'devices',
+    // Managing devices across users means naming the owner, and the admin screens name them by
+    // person rather than by UUID: the register form's owner picker and the owner column on both
+    // list and detail resolve through `GET /api/auth/users`, which `auth.users.list` gates.
+    dependsOn: ['auth.users.list'],
+  },
 ]
 
 export default features

package/src/modules/devices/api/admin/devices/[id]/route.ts

@@ -15,6 +15,8 @@ import { updateDeviceSchema } from '../../../../data/validators'
 import { isOrganizationReadAccessAllowed } from '@open-mercato/core/modules/directory/utils/organizationScopeGuard'
 import { resolveDeviceActorUserId } from '../../../auth'
 import { executeUpdate, executeDeactivate, type DeviceMutationContext } from '../../../deviceOps'
+import { serializeDeviceDetail, deviceDetailItemSchema } from '../../../deviceSerialization'
+import { DEPRECATED_SNAKE_CASE_NOTICE } from '../../../openapi'
 
 const logger = createLogger('devices')
 
@@ -38,23 +40,6 @@ async function loadDevice(
   return findOneWithDecryption(em, UserDevice, { id, tenantId, deletedAt: null }, undefined, { tenantId })
 }
 
-// push_token is a secret and is never returned.
-function serializeDevice(device: UserDevice) {
-  return {
-    id: device.id,
-    user_id: device.userId,
-    device_id: device.deviceId,
-    platform: device.platform,
-    client_app_version: device.clientAppVersion ?? null,
-    os_version: device.osVersion ?? null,
-    push_provider: device.pushProvider ?? null,
-    push_token_updated_at: device.pushTokenUpdatedAt ? device.pushTokenUpdatedAt.toISOString() : null,
-    last_seen_at: device.lastSeenAt ? device.lastSeenAt.toISOString() : null,
-    created_at: device.createdAt ? device.createdAt.toISOString() : null,
-    updated_at: device.updatedAt ? device.updatedAt.toISOString() : null,
-  }
-}
-
 export async function GET(req: Request, { params }: { params: { id: string } }) {
   const { translate } = await resolveTranslations()
   try {
@@ -76,7 +61,7 @@ export async function GET(req: Request, { params }: { params: { id: string } })
     if (!isOrganizationReadAccessAllowed({ scope, auth, organizationId: device.organizationId ?? null })) {
       return NextResponse.json({ error: translate('devices.errors.forbidden', 'Access denied') }, { status: 403 })
     }
-    return NextResponse.json({ item: serializeDevice(device) })
+    return NextResponse.json({ item: serializeDeviceDetail(device) })
   } catch (err) {
     if (isCrudHttpError(err)) {
       return NextResponse.json(err.body, { status: err.status })
@@ -177,21 +162,7 @@ export async function DELETE(req: Request, { params }: { params: { id: string }
 
 const okResponseSchema = z.object({ ok: z.literal(true), id: z.string().uuid().optional() })
 const errorResponseSchema = z.object({ error: z.string() })
-const detailResponseSchema = z.object({
-  item: z.object({
-    id: z.string().uuid(),
-    user_id: z.string().uuid(),
-    device_id: z.string(),
-    platform: z.enum(['ios', 'android', 'web']),
-    client_app_version: z.string().nullable(),
-    os_version: z.string().nullable(),
-    push_provider: z.string().nullable(),
-    push_token_updated_at: z.string().nullable(),
-    last_seen_at: z.string().nullable(),
-    created_at: z.string().nullable(),
-    updated_at: z.string().nullable(),
-  }),
-})
+const detailResponseSchema = z.object({ item: deviceDetailItemSchema })
 
 export const openApi: OpenApiRouteDoc = {
   tag: 'Devices (admin)',
@@ -199,7 +170,7 @@ export const openApi: OpenApiRouteDoc = {
   methods: {
     GET: {
       summary: 'Get any device',
-      description: 'Admin: fetch a single device by id (push_token is never returned).',
+      description: `Admin: fetch a single device by id (push_token is never returned). ${DEPRECATED_SNAKE_CASE_NOTICE}`,
       responses: [{ status: 200, description: 'Device', schema: detailResponseSchema }],
       errors: [
         { status: 400, description: 'Invalid id', schema: errorResponseSchema },

package/src/modules/devices/api/admin/devices/route.ts

@@ -2,6 +2,7 @@ import type { EntityManager } from '@mikro-orm/postgresql'
 import { NextResponse } from 'next/server'
 import { z } from 'zod'
 import { makeCrudRoute } from '@open-mercato/shared/lib/crud/factory'
+import { toHeaderLabel } from '@open-mercato/shared/lib/crud/exporters'
 import { createRequestContainer } from '@open-mercato/shared/lib/di/container'
 import { getAuthFromRequest } from '@open-mercato/shared/lib/auth/server'
 import { resolveOrganizationScopeForRequest } from '@open-mercato/core/modules/directory/utils/organizationScope'
@@ -21,7 +22,14 @@ import {
 } from '../../../data/validators'
 import { resolveDeviceActorUserId } from '../../auth'
 import { createDevicesCrudOpenApi, createPagedListResponseSchema } from '../../openapi'
-import { deviceListSchema, deviceListFields, deviceListSortFieldMap, deviceListItemSchema } from '../../deviceList'
+import {
+  deviceListSchema,
+  deviceListFields,
+  deviceListSortFieldMap,
+  deviceListItemSchema,
+  deviceExportColumnFields,
+  transformDeviceListItem,
+} from '../../deviceList'
 import { executeRegister, type DeviceMutationContext } from '../../deviceOps'
 
 const logger = createLogger('devices')
@@ -55,6 +63,11 @@ const crud = makeCrudRoute({
     entityId: E.devices.user_device,
     fields: deviceListFields,
     sortFieldMap: deviceListSortFieldMap,
+    // The query engine projects raw column names; expose them in camelCase like every other module.
+    transformItem: transformDeviceListItem,
+    // Without an explicit column set the factory's default export spreads each item, so the deprecated
+    // snake_case aliases would double every column in the CSV/JSON/XML export.
+    export: { columns: deviceExportColumnFields.map((field) => ({ field, header: toHeaderLabel(field) })) },
     // Tenant + org scope is enforced by the factory (orm.tenantField + orm.orgField); only the optional
     // userId/platform narrowing is left to do here.
     buildFilters: async (query) => {

package/src/modules/devices/api/deviceList.ts

@@ -30,25 +30,149 @@ export const deviceListFields: string[] = [
   'updated_at',
 ]
 
+// The admin list enables exports, and the factory's default export derives its columns by spreading
+// each item — which would emit both spellings of every aliased key. Pin the canonical camelCase set
+// so the export stays single-spelled and does not change shape when the aliases are dropped.
+export const deviceExportColumnFields: string[] = [
+  'id',
+  'tenantId',
+  'organizationId',
+  'userId',
+  'deviceId',
+  'platform',
+  'clientAppVersion',
+  'osVersion',
+  'locale',
+  'pushProvider',
+  'pushTokenUpdatedAt',
+  'lastSeenAt',
+  'createdAt',
+  'updatedAt',
+]
+
 export const deviceListSortFieldMap: Record<string, string> = {
   lastSeenAt: 'last_seen_at',
   createdAt: 'created_at',
   updatedAt: 'updated_at',
 }
 
+// The query engine projects the raw column names listed in `deviceListFields`. Every other module
+// serializes its list items in camelCase (`sales/orders` → `orderNumber`, `warranty_claims` →
+// `claimNumber`), so the list routes run this transform to expose the platform convention (#5513).
+// The snake_case keys stay alongside as deprecated aliases for one minor version, per the
+// deprecation protocol in BACKWARD_COMPATIBILITY.md § 7 (API Route URLs — response fields).
+export function transformDeviceListItem(item: unknown): unknown {
+  const record = toRecord(item)
+  if (!Object.keys(record).length) return item
+  const camel = {
+    id: readString(record, 'id', 'id'),
+    tenantId: readString(record, 'tenant_id', 'tenantId'),
+    organizationId: readString(record, 'organization_id', 'organizationId'),
+    userId: readString(record, 'user_id', 'userId'),
+    deviceId: readString(record, 'device_id', 'deviceId'),
+    platform: readString(record, 'platform', 'platform'),
+    clientAppVersion: readString(record, 'client_app_version', 'clientAppVersion'),
+    osVersion: readString(record, 'os_version', 'osVersion'),
+    locale: readString(record, 'locale', 'locale'),
+    pushProvider: readString(record, 'push_provider', 'pushProvider'),
+    pushTokenUpdatedAt: toIso(record.push_token_updated_at ?? record.pushTokenUpdatedAt),
+    lastSeenAt: toIso(record.last_seen_at ?? record.lastSeenAt),
+    createdAt: toIso(record.created_at ?? record.createdAt),
+    updatedAt: toIso(record.updated_at ?? record.updatedAt),
+  }
+  // Spread the raw record first so anything the projection carries beyond the declared field set
+  // (custom-field keys, future columns) survives; the aliases then restate the snake_case keys with
+  // the same normalized values as their camelCase counterparts.
+  return { ...record, ...camel, ...toDeprecatedSnakeCaseAliases(camel) }
+}
+
+/**
+ * @deprecated Snake_case device response keys are superseded by the camelCase keys and are removed in
+ * the next minor release. Read `deviceId`, `userId`, `lastSeenAt`, … instead. See UPGRADE_NOTES.md.
+ */
+export function toDeprecatedSnakeCaseAliases(item: DeviceResponseItem): Record<string, unknown> {
+  const aliases: Record<string, unknown> = {
+    tenant_id: item.tenantId,
+    organization_id: item.organizationId,
+    user_id: item.userId,
+    device_id: item.deviceId,
+    client_app_version: item.clientAppVersion,
+    os_version: item.osVersion,
+    push_provider: item.pushProvider,
+    push_token_updated_at: item.pushTokenUpdatedAt,
+    last_seen_at: item.lastSeenAt,
+    created_at: item.createdAt,
+    updated_at: item.updatedAt,
+  }
+  // The detail response never carried tenant/org, so an absent camelCase source must not grow a new
+  // key here — only keys the caller actually supplied get an alias.
+  for (const key of Object.keys(aliases)) {
+    if (aliases[key] === undefined) delete aliases[key]
+  }
+  return aliases
+}
+
+export type DeviceResponseItem = {
+  tenantId?: string | null
+  organizationId?: string | null
+  userId: string | null
+  deviceId: string | null
+  clientAppVersion: string | null
+  osVersion: string | null
+  pushProvider: string | null
+  pushTokenUpdatedAt?: string | null
+  lastSeenAt?: string | null
+  createdAt?: string | null
+  updatedAt: string | null
+}
+
+function toRecord(value: unknown): Record<string, unknown> {
+  return value && typeof value === 'object' && !Array.isArray(value) ? (value as Record<string, unknown>) : {}
+}
+
+function readString(record: Record<string, unknown>, snakeKey: string, camelKey: string): string | null {
+  const value = record[snakeKey] ?? record[camelKey]
+  return typeof value === 'string' ? value : null
+}
+
+export function toIso(value: unknown): string | null {
+  if (value instanceof Date) return Number.isNaN(value.getTime()) ? null : value.toISOString()
+  if (typeof value === 'string') {
+    const date = new Date(value)
+    return Number.isNaN(date.getTime()) ? value : date.toISOString()
+  }
+  return null
+}
+
+// In-code contract markers. The shared zodToJsonSchema converter does not currently emit per-property
+// descriptions for object schemas, so the rendered deprecation notice lives on the endpoint description
+// (`DEPRECATED_SNAKE_CASE_NOTICE` in ./openapi); these become visible for free if that changes.
+const deprecatedAlias = (of: string) => `Deprecated alias for \`${of}\`; removed in the next minor release.`
+
 export const deviceListItemSchema = z.object({
   id: z.string().uuid(),
-  tenant_id: z.string().uuid(),
-  organization_id: z.string().uuid().nullable().optional(),
-  user_id: z.string().uuid(),
-  device_id: z.string(),
+  tenantId: z.string().uuid(),
+  organizationId: z.string().uuid().nullable().optional(),
+  userId: z.string().uuid(),
+  deviceId: z.string(),
   platform: z.enum(['ios', 'android', 'web']),
-  client_app_version: z.string().nullable().optional(),
-  os_version: z.string().nullable().optional(),
+  clientAppVersion: z.string().nullable().optional(),
+  osVersion: z.string().nullable().optional(),
   locale: z.string().nullable().optional(),
-  push_provider: z.string().nullable().optional(),
-  push_token_updated_at: z.string().nullable().optional(),
-  last_seen_at: z.string().nullable().optional(),
-  created_at: z.string().nullable().optional(),
-  updated_at: z.string().nullable().optional(),
+  pushProvider: z.string().nullable().optional(),
+  pushTokenUpdatedAt: z.string().nullable().optional(),
+  lastSeenAt: z.string().nullable().optional(),
+  createdAt: z.string().nullable().optional(),
+  updatedAt: z.string().nullable().optional(),
+  tenant_id: z.string().uuid().describe(deprecatedAlias('tenantId')),
+  organization_id: z.string().uuid().nullable().optional().describe(deprecatedAlias('organizationId')),
+  user_id: z.string().uuid().describe(deprecatedAlias('userId')),
+  device_id: z.string().describe(deprecatedAlias('deviceId')),
+  client_app_version: z.string().nullable().optional().describe(deprecatedAlias('clientAppVersion')),
+  os_version: z.string().nullable().optional().describe(deprecatedAlias('osVersion')),
+  push_provider: z.string().nullable().optional().describe(deprecatedAlias('pushProvider')),
+  push_token_updated_at: z.string().nullable().optional().describe(deprecatedAlias('pushTokenUpdatedAt')),
+  last_seen_at: z.string().nullable().optional().describe(deprecatedAlias('lastSeenAt')),
+  created_at: z.string().nullable().optional().describe(deprecatedAlias('createdAt')),
+  updated_at: z.string().nullable().optional().describe(deprecatedAlias('updatedAt')),
 })

package/src/modules/devices/api/deviceSerialization.ts

@@ -0,0 +1,50 @@
+import { z } from 'zod'
+import type { UserDevice } from '../data/entities'
+import { toDeprecatedSnakeCaseAliases, toIso } from './deviceList'
+
+// Detail contract for `GET /api/devices/admin/devices/:id`. Keys are camelCase like every other
+// module's responses (#5513); the snake_case keys stay alongside as deprecated aliases for one minor
+// version, per the deprecation protocol in BACKWARD_COMPATIBILITY.md § 7.
+// push_token is a secret and is never returned.
+export function serializeDeviceDetail(device: UserDevice): Record<string, unknown> {
+  const camel = {
+    id: device.id,
+    userId: device.userId,
+    deviceId: device.deviceId,
+    platform: device.platform,
+    clientAppVersion: device.clientAppVersion ?? null,
+    osVersion: device.osVersion ?? null,
+    pushProvider: device.pushProvider ?? null,
+    pushTokenUpdatedAt: toIso(device.pushTokenUpdatedAt),
+    lastSeenAt: toIso(device.lastSeenAt),
+    createdAt: toIso(device.createdAt),
+    updatedAt: toIso(device.updatedAt),
+  }
+  return { ...camel, ...toDeprecatedSnakeCaseAliases(camel) }
+}
+
+// See the note in ./deviceList — the rendered deprecation notice lives on the endpoint description.
+const deprecatedAlias = (of: string) => `Deprecated alias for \`${of}\`; removed in the next minor release.`
+
+export const deviceDetailItemSchema = z.object({
+  id: z.string().uuid(),
+  userId: z.string().uuid(),
+  deviceId: z.string(),
+  platform: z.enum(['ios', 'android', 'web']),
+  clientAppVersion: z.string().nullable(),
+  osVersion: z.string().nullable(),
+  pushProvider: z.string().nullable(),
+  pushTokenUpdatedAt: z.string().nullable(),
+  lastSeenAt: z.string().nullable(),
+  createdAt: z.string().nullable(),
+  updatedAt: z.string().nullable(),
+  user_id: z.string().uuid().describe(deprecatedAlias('userId')),
+  device_id: z.string().describe(deprecatedAlias('deviceId')),
+  client_app_version: z.string().nullable().describe(deprecatedAlias('clientAppVersion')),
+  os_version: z.string().nullable().describe(deprecatedAlias('osVersion')),
+  push_provider: z.string().nullable().describe(deprecatedAlias('pushProvider')),
+  push_token_updated_at: z.string().nullable().describe(deprecatedAlias('pushTokenUpdatedAt')),
+  last_seen_at: z.string().nullable().describe(deprecatedAlias('lastSeenAt')),
+  created_at: z.string().nullable().describe(deprecatedAlias('createdAt')),
+  updated_at: z.string().nullable().describe(deprecatedAlias('updatedAt')),
+})

package/src/modules/devices/api/openapi.ts

@@ -12,10 +12,18 @@ export function createPagedListResponseSchema(itemSchema: ZodTypeAny) {
 
 // createCrudOpenApiFactory already falls back to the shared default create/ok response schemas
 // when omitted, so there is nothing module-specific to re-pass or re-export here.
+// The shared zodToJsonSchema converter does not emit per-property descriptions for object schemas, so
+// the `.describe()` markers on the deprecated keys in deviceList.ts never reach the document. State the
+// deprecation in the endpoint description, which does render (#5513).
+export const DEPRECATED_SNAKE_CASE_NOTICE =
+  'Response keys are camelCase. The snake_case keys (`user_id`, `device_id`, `last_seen_at`, …) are ' +
+  'deprecated aliases of their camelCase counterparts, retained for one minor version and removed in ' +
+  'the next; read `userId`, `deviceId`, `lastSeenAt`, … instead.'
+
 const buildDevicesCrudOpenApi = createCrudOpenApiFactory({
   defaultTag: 'Devices',
   makeListDescription: ({ pluralLower }) =>
-    `Returns the authenticated user's registered ${pluralLower} (admins may list across users).`,
+    `Returns the authenticated user's registered ${pluralLower} (admins may list across users). ${DEPRECATED_SNAKE_CASE_NOTICE}`,
 })
 
 export function createDevicesCrudOpenApi(options: CrudOpenApiOptions): OpenApiRouteDoc {