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

package/src/modules/staff/api/timesheets/time-entries/[id]/timer-stop/route.ts

@@ -10,14 +10,16 @@ import type { EntityManager } from '@mikro-orm/postgresql'
 import { LockMode } from '@mikro-orm/core'
 import type { OpenApiRouteDoc } from '@open-mercato/shared/lib/openapi'
 import { StaffTimeEntry, StaffTimeEntrySegment } from '../../../../../data/entities'
+import { assertTimeEntryUnlocked, resolveRoundedMinutes } from '../../../../../commands/timesheets-entries'
 import { getStaffMemberByUserId } from '../../../../../lib/staffMemberResolver'
 import {
-  resolveUserFeatures,
+  STAFF_TIME_TRACKING_RESOURCE_KINDS,
   runStaffMutationGuardAfterSuccess,
   runStaffMutationGuards,
 } from '../../../../guards'
 import { emitStaffEvent } from '../../../../../events'
 import { invalidateStaffTimeEntryCache } from '../../../../../lib/timesheets/timeEntryCacheInvalidation'
+import { runTimesheetInterceptors } from '../../../_shared/withTimesheetInterceptors'
 import { createLogger } from '@open-mercato/shared/lib/logger'
 
 const logger = createLogger('staff')
@@ -51,6 +53,14 @@ export async function POST(req: Request) {
       throw new CrudHttpError(400, { error: translate('staff.errors.missingScope', 'Missing tenant or organization scope.') })
     }
 
+    const interceptors = await runTimesheetInterceptors({
+      request: req,
+      method: 'POST',
+      scope: { container, userId: auth.sub, tenantId, organizationId },
+    })
+    if (!interceptors.ok) return interceptors.response
+    const { session } = interceptors
+
     const em = (container.resolve('em') as EntityManager).fork()
     const scopeCtx = { tenantId, organizationId }
 
@@ -75,19 +85,22 @@ export async function POST(req: Request) {
       throw new CrudHttpError(403, { error: translate('staff.timesheets.errors.notOwner', 'You can only manage your own time entries.') })
     }
 
+    // Stopping a timer rewrites `duration_minutes`, which is exactly what a
+    // closed report froze — same gate as the entries command.
+    assertTimeEntryUnlocked(entry, translate)
+
     const guardResult = await runStaffMutationGuards(
       container,
       {
         tenantId,
         organizationId,
         userId: auth.sub ?? '',
-        resourceKind: 'staff.timesheets.time_entry',
+        resourceKind: STAFF_TIME_TRACKING_RESOURCE_KINDS.timeEntry,
         resourceId: entry.id,
         operation: 'update',
         requestMethod: req.method,
         requestHeaders: req.headers,
       },
-      resolveUserFeatures(auth),
     )
     if (!guardResult.ok) {
       return NextResponse.json(
@@ -111,6 +124,9 @@ export async function POST(req: Request) {
       if (!lockedEntry) {
         throw new CrudHttpError(404, { error: translate('staff.timesheets.errors.entryNotFound', 'Time entry not found.') })
       }
+      // Re-checked under the row lock: a report close committed between the
+      // pre-flight read and this transaction would otherwise slip through.
+      assertTimeEntryUnlocked(lockedEntry, translate)
 
       const segments = await findWithDecryption(
         trx,
@@ -148,6 +164,16 @@ export async function POST(req: Request) {
 
       const computedMinutes = Math.round(totalWorkMinutes / 60000)
       lockedEntry.durationMinutes = computedMinutes
+      // This route writes a duration outside the entries command, and D-7 makes
+      // `rounded_minutes` the only input to cost — so it is restated here with the
+      // same tenant rule the command applies, not left stale from the zero-minute
+      // value the timer was created with.
+      lockedEntry.roundedMinutes = await resolveRoundedMinutes(
+        container,
+        tenantId,
+        computedMinutes,
+        organizationId,
+      )
 
       await trx.flush()
       return { now: stoppedAt, durationMinutes: computedMinutes }
@@ -176,7 +202,7 @@ export async function POST(req: Request) {
         tenantId,
         organizationId,
         userId: auth.sub ?? '',
-        resourceKind: 'staff.timesheets.time_entry',
+        resourceKind: STAFF_TIME_TRACKING_RESOURCE_KINDS.timeEntry,
         resourceId: entry.id,
         operation: 'update',
         requestMethod: req.method,
@@ -184,7 +210,7 @@ export async function POST(req: Request) {
       })
     }
 
-    return NextResponse.json({ ok: true, durationMinutes }, { status: 200 })
+    return session.respond(200, { ok: true, durationMinutes })
   } catch (err) {
     if (err instanceof CrudHttpError) {
       return NextResponse.json(err.body, { status: err.status })
@@ -212,7 +238,11 @@ export const openApi: OpenApiRouteDoc = {
           schema: z.object({ ok: z.literal(true), durationMinutes: z.number() }),
         },
         { status: 404, description: 'Time entry not found', schema: z.object({ error: z.string() }) },
-        { status: 409, description: 'No active timer segment', schema: z.object({ error: z.string() }) },
+        {
+          status: 409,
+          description: 'No active timer segment, or the entry is locked in a closed report (code time_entry_locked)',
+          schema: z.object({ error: z.string(), code: z.string().optional(), lockedReportId: z.string().uuid().nullable().optional() }),
+        },
         { status: 401, description: 'Unauthorized', schema: z.object({ error: z.string() }) },
       ],
     },

package/src/modules/staff/api/timesheets/time-entries/bulk/route.ts

@@ -11,19 +11,73 @@ import { emitCrudSideEffects, flushCrudSideEffects } from '@open-mercato/shared/
 import type { DataEngine } from '@open-mercato/shared/lib/data/engine'
 import type { EntityManager } from '@mikro-orm/postgresql'
 import type { OpenApiRouteDoc } from '@open-mercato/shared/lib/openapi'
-import { StaffTimeEntry, StaffTeamMember, StaffTimeProject } from '../../../../data/entities'
-import { staffTimeEntryBulkSaveSchema } from '../../../../data/validators'
+import { StaffTimeEntry, StaffTeamMember, StaffTimeProject, StaffTimeTask } from '../../../../data/entities'
+import {
+  staffTimeEntryBulkSaveSchema,
+  type StaffTimeEntryBulkSaveInput,
+} from '../../../../data/validators'
+import {
+  buildTimeEntryLockedError,
+  rebaseTimeEntryIntervalToDate,
+  reconcileTimeEntryInterval,
+  resolveTimeEntryBillable,
+  resolveTimeEntryNotesInput,
+  resolveTimeEntryProjectId,
+  resolveTimeEntrySettings,
+  roundedMinutesFor,
+  timeEntryTaskMatchesProject,
+  toStoredTimeEntryRateOverride,
+  type LockedTimeEntryRef,
+} from '../../../../commands/timesheets-entries'
 import { staffTimeEntryCrudEvents } from '../../../../lib/crud'
+import { emitStaffEvent } from '../../../../events'
 import { invalidateStaffTimeEntryCache } from '../../../../lib/timesheets/timeEntryCacheInvalidation'
 import {
-  resolveUserFeatures,
+  STAFF_TIME_TRACKING_RESOURCE_KINDS,
   runStaffMutationGuardAfterSuccess,
   runStaffMutationGuards,
 } from '../../../guards'
+import { runTimesheetInterceptors } from '../../_shared/withTimesheetInterceptors'
 import { createLogger } from '@open-mercato/shared/lib/logger'
 
 const logger = createLogger('staff')
 
+/**
+ * A grid cell is addressed by the day the work started, never by the timestamp,
+ * so both sides of the comparison collapse to `YYYY-MM-DD` (D-8).
+ */
+function cellDateKey(value: Date | string | null | undefined): string {
+  if (!value) return ''
+  const date = value instanceof Date ? value : new Date(value)
+  return Number.isNaN(date.getTime()) ? String(value) : date.toISOString().slice(0, 10)
+}
+
+type BulkRowError = { path: string; message: string; value?: unknown }
+
+/**
+ * The batch answers with a per-row error list rather than a thrown 422: one grid
+ * save spans a week of cells, so the client needs to know WHICH row it must fix.
+ * The single-entry command raises the same refusals as `CrudHttpError` field
+ * errors — same rule, different reporting shape.
+ */
+function bulkValidationError(errors: BulkRowError[]): NextResponse {
+  return NextResponse.json({ ok: false, errors }, { status: 422 })
+}
+
+/**
+ * A row as the write loop needs it: the payload plus the two things that must be
+ * settled before the lock gate can address a cell — the task it names (validated
+ * in scope) and the project the entry actually lands on, which a task-only row
+ * inherits from its task exactly as the single-entry path does.
+ */
+type BulkEntryInput = StaffTimeEntryBulkSaveInput['entries'][number]
+
+type ResolvedBulkRow = {
+  entry: BulkEntryInput
+  task: { id: string; timeProjectId: string } | null
+  timeProjectId: string
+}
+
 export const metadata = {
   POST: { requireAuth: true, requireFeatures: ['staff.timesheets.manage_own'] },
 }
@@ -42,8 +96,16 @@ export async function POST(req: Request) {
       throw new CrudHttpError(400, { error: translate('staff.errors.missingScope', 'Missing tenant or organization scope.') })
     }
 
-    const body = await readJsonSafe(req, {})
-    const parsed = staffTimeEntryBulkSaveSchema.safeParse(body)
+    const interceptors = await runTimesheetInterceptors({
+      request: req,
+      method: 'POST',
+      scope: { container, userId: auth.sub, tenantId, organizationId },
+      body: await readJsonSafe<Record<string, unknown>>(req, {}),
+    })
+    if (!interceptors.ok) return interceptors.response
+    const { session } = interceptors
+
+    const parsed = staffTimeEntryBulkSaveSchema.safeParse(session.body)
     if (!parsed.success) {
       const errors = parsed.error.issues.map((issue) => ({
         path: issue.path.join('.'),
@@ -54,6 +116,27 @@ export async function POST(req: Request) {
 
     const { entries } = parsed.data
 
+    // Tags are REFUSED here rather than accepted and dropped.
+    //
+    // The single-entry path assigns tags by dispatching the tag commands, which
+    // fork their own EntityManager so they can carry their own audit entry, undo
+    // and lock check. Inside this route's `em.transactional` that fork would not
+    // see the rows the transaction has not committed yet, and dispatching AFTER
+    // the commit would answer `{ ok: true, created: n }` for a batch whose tags
+    // silently failed — a response carrying only counts cannot say which cell
+    // lost them, which is the very silent-success class this route is being
+    // fixed for. So the row is rejected and the user is pointed at the entry
+    // dialog, which writes tags through the commands with all of their
+    // guarantees intact.
+    const taggedRows = entries.filter((entry) => entry.tagIds !== undefined)
+    if (taggedRows.length > 0) {
+      const message = translate(
+        'staff.timesheets.errors.bulkTagsUnsupported',
+        'Tags cannot be changed from the timesheet grid. Open the time entry to edit its tags.',
+      )
+      return bulkValidationError(taggedRows.map(() => ({ path: 'entries[].tagIds', message })))
+    }
+
     const em = (container.resolve('em') as EntityManager).fork()
     const scopeCtx = { tenantId, organizationId }
 
@@ -69,34 +152,94 @@ export async function POST(req: Request) {
     }
     const staffMemberId = staffMember.id
 
-    // Validate that all referenced timeProjectIds exist and are in-scope
-    const referencedProjectIds = [
+    // Validate that all referenced taskIds exist and are in-scope, in one query
+    // for the whole batch. Same rule the single-entry path applies through
+    // `requireTaskInScope`: a dangling task reference is refused rather than
+    // stored, because the task rollups aggregate entries by `task_id` and a stale
+    // or foreign UUID would silently move hours onto another project's card.
+    const referencedTaskIds = [
       ...new Set(
         entries
-          .map((e) => e.timeProjectId)
+          .map((entry) => entry.taskId)
           .filter((id): id is string => typeof id === 'string' && id.length > 0),
       ),
     ]
+    const tasksById = new Map<string, { id: string; timeProjectId: string }>()
+    if (referencedTaskIds.length > 0) {
+      const validTasks = await em.find(StaffTimeTask, {
+        id: { $in: referencedTaskIds },
+        tenantId,
+        organizationId,
+        deletedAt: null,
+      }, { fields: ['id', 'timeProjectId'] })
+      for (const task of validTasks) tasksById.set(task.id, { id: task.id, timeProjectId: task.timeProjectId })
+      const invalidTaskIds = referencedTaskIds.filter((id) => !tasksById.has(id))
+      if (invalidTaskIds.length > 0) {
+        const message = translate('staff.timesheets.errors.taskNotFound', 'Task not found or not accessible.')
+        return bulkValidationError(
+          invalidTaskIds.map((id) => ({ path: 'entries[].taskId', message, value: id })),
+        )
+      }
+    }
+
+    // Every row is pinned to the project it will actually land on BEFORE the lock
+    // gate runs, because the gate addresses a cell by (project, date) — a task row
+    // that inherited its project must be checked against that inherited cell, not
+    // against a blank one.
+    const resolvedRows: ResolvedBulkRow[] = []
+    const missingProjectErrors: BulkRowError[] = []
+    const taskProjectMismatchErrors: BulkRowError[] = []
+    for (const entry of entries) {
+      const task = entry.taskId ? tasksById.get(entry.taskId) ?? null : null
+      const timeProjectId = resolveTimeEntryProjectId(entry.timeProjectId, task)
+      if (!timeProjectId) {
+        missingProjectErrors.push({
+          path: 'entries[].timeProjectId',
+          message: translate('staff.timesheets.errors.projectRequired', 'Time project id is required.'),
+        })
+        continue
+      }
+      if (!timeEntryTaskMatchesProject(task, timeProjectId)) {
+        taskProjectMismatchErrors.push({
+          path: 'entries[].taskId',
+          message: translate('staff.timesheets.errors.taskNotFound', 'Task not found or not accessible.'),
+          value: entry.taskId,
+        })
+        continue
+      }
+      resolvedRows.push({ entry, task, timeProjectId })
+    }
+    if (missingProjectErrors.length > 0 || taskProjectMismatchErrors.length > 0) {
+      return bulkValidationError([...missingProjectErrors, ...taskProjectMismatchErrors])
+    }
+
+    // Validate that all referenced timeProjectIds exist and are in-scope. The
+    // project rows are kept, not just their ids: a created entry snapshots the
+    // project's currency and inherits its billable default (D-3), so one query
+    // serves validation and both defaults.
+    const referencedProjectIds = [...new Set(resolvedRows.map((row) => row.timeProjectId))]
+    const projectsById = new Map<string, { currencyCode?: string | null; billableByDefault?: boolean | null }>()
     if (referencedProjectIds.length > 0) {
       const validProjects = await em.find(StaffTimeProject, {
         id: { $in: referencedProjectIds },
         tenantId,
         organizationId,
         deletedAt: null,
-      }, { fields: ['id'] })
-      const validIds = new Set(validProjects.map((p) => p.id))
-      const invalidIds = referencedProjectIds.filter((id) => !validIds.has(id))
+      }, { fields: ['id', 'currencyCode', 'billableByDefault'] })
+      for (const project of validProjects) {
+        projectsById.set(project.id, {
+          currencyCode: project.currencyCode ?? null,
+          billableByDefault: project.billableByDefault ?? null,
+        })
+      }
+      const invalidIds = referencedProjectIds.filter((id) => !projectsById.has(id))
       if (invalidIds.length > 0) {
-        return NextResponse.json(
-          {
-            ok: false,
-            errors: invalidIds.map((id) => ({
-              path: 'entries[].timeProjectId',
-              message: translate('staff.timesheets.errors.projectNotFound', 'Time project not found or not accessible.'),
-              value: id,
-            })),
-          },
-          { status: 422 },
+        const message = translate(
+          'staff.timesheets.errors.projectNotFound',
+          'Time project not found or not accessible.',
+        )
+        return bulkValidationError(
+          invalidIds.map((id) => ({ path: 'entries[].timeProjectId', message, value: id })),
         )
       }
     }
@@ -105,14 +248,14 @@ export async function POST(req: Request) {
       tenantId,
       organizationId,
       userId: auth.sub ?? '',
-      resourceKind: 'staff.timesheets.time_entry',
+      resourceKind: STAFF_TIME_TRACKING_RESOURCE_KINDS.timeEntry,
       resourceId: staffMemberId,
       operation: 'update' as const,
       requestMethod: req.method,
       requestHeaders: req.headers,
       mutationPayload: parsed.data as unknown as Record<string, unknown>,
     }
-    const guardResult = await runStaffMutationGuards(container, guardInput, resolveUserFeatures(auth))
+    const guardResult = await runStaffMutationGuards(container, guardInput)
     if (!guardResult.ok) {
       return NextResponse.json(
         guardResult.errorBody ?? { error: 'Operation blocked by guard' },
@@ -120,8 +263,8 @@ export async function POST(req: Request) {
       )
     }
 
-    const existingIds = entries
-      .map((entry) => entry.id)
+    const existingIds = resolvedRows
+      .map((row) => row.entry.id)
       .filter((id): id is string => typeof id === 'string' && id.length > 0)
 
     // Validate referenced entry IDs upfront: a stale or foreign UUID would
@@ -153,11 +296,80 @@ export async function POST(req: Request) {
       }
     }
 
+    // --- Lock gate (risk R3) -------------------------------------------------
+    //
+    // This is the endpoint the lock is most likely to leak through, because the
+    // grid addresses a cell by (project, date) and only carries an id when the
+    // client happened to have one loaded. So both shapes are checked:
+    //
+    //  * a row naming an id that resolves to a frozen entry, and
+    //  * an id-less row landing on a (project, date) cell a frozen entry already
+    //    occupies — the grid renders one summed value per cell, so creating a
+    //    second row there silently restates hours a closed report has billed.
+    //
+    // The batch fails WHOLESALE, before the transaction opens. A grid save is one
+    // user gesture spanning a week of cells and the response carries only counts,
+    // so applying the unlocked rows would leave the client unable to tell which
+    // cells landed — and the route already rejects the whole payload for an
+    // unknown project or a stale entry id, so a partial 409 would be the odd one
+    // out. The 409 names every offending id and the reports that froze them, so
+    // the grid can mark exactly those cells read-only and the user retries the
+    // rest after reloading (which is also what makes the lock badge appear).
+    //
+    // The cell is addressed by the RESOLVED project, so a task row that inherited
+    // its project is checked against the cell it will really occupy.
+    const idlessRows = resolvedRows.filter((row) => !row.entry.id)
+    const idlessCells = idlessRows.map((row) => `${cellDateKey(row.entry.date)}|${row.timeProjectId}`)
+    const lockConditions: Record<string, unknown>[] = []
+    if (existingIds.length > 0) lockConditions.push({ id: { $in: existingIds } })
+    if (idlessCells.length > 0) {
+      lockConditions.push({
+        date: { $in: idlessRows.map((row) => row.entry.date) },
+        timeProjectId: { $in: [...new Set(idlessRows.map((row) => row.timeProjectId))] },
+      })
+    }
+    if (lockConditions.length > 0) {
+      const existingIdSet = new Set(existingIds)
+      const idlessCellSet = new Set(idlessCells)
+      const lockedCandidates = await em.find(
+        StaffTimeEntry,
+        {
+          tenantId,
+          organizationId,
+          staffMemberId,
+          deletedAt: null,
+          lockedReportId: { $ne: null },
+          $or: lockConditions,
+        },
+        { fields: ['id', 'lockedReportId', 'date', 'timeProjectId'] },
+      )
+      // The (date × project) condition above is a cross product, so it can match a
+      // locked entry on a cell the payload never touches — narrowed here.
+      const blocked: LockedTimeEntryRef[] = lockedCandidates.filter(
+        (row) =>
+          existingIdSet.has(row.id) ||
+          idlessCellSet.has(`${cellDateKey(row.date)}|${row.timeProjectId ?? ''}`),
+      )
+      if (blocked.length > 0) {
+        throw buildTimeEntryLockedError(
+          blocked.map((row) => ({ id: row.id, lockedReportId: row.lockedReportId })),
+          translate,
+        )
+      }
+    }
+
     type PendingChange = {
       action: 'created' | 'updated' | 'deleted'
       entity: StaffTimeEntry
     }
 
+    // D-7 makes `rounded_minutes` the only input to cost, and this route writes
+    // durations outside the entries command — so every row it touches is rounded
+    // with the same tenant rule the command uses. The settings read is hoisted out
+    // of the loop because it is tenant-scoped and identical for every row; the
+    // billable default a created row falls back to comes from the same snapshot.
+    const settings = await resolveTimeEntrySettings(container, tenantId)
+
     const { counts, pendingChanges } = await em.transactional(async (trx) => {
       let created = 0
       let updated = 0
@@ -176,7 +388,12 @@ export async function POST(req: Request) {
 
       const existingMap = new Map(existingEntries.map((entry) => [entry.id, entry]))
 
-      for (const entry of entries) {
+      for (const { entry, task, timeProjectId } of resolvedRows) {
+        const project = projectsById.get(timeProjectId) ?? null
+        // Both branches read the five fields the schema has always accepted
+        // through the SAME helpers the single-entry command uses, so a grid write
+        // and a dialog write cannot settle them differently (#silent-no-op).
+        const notes = resolveTimeEntryNotesInput(entry)
         if (entry.id && existingMap.has(entry.id)) {
           const existing = existingMap.get(entry.id)!
           if (entry.durationMinutes === 0) {
@@ -184,10 +401,52 @@ export async function POST(req: Request) {
             deleted++
             changes.push({ action: 'deleted', entity: existing })
           } else {
+            // T4.10(a). A grid cell carries a duration and nothing else, so writing
+            // it straight onto an entry that has clocks would store a two-hour
+            // duration against a 09:00–10:00 span — exactly the contradiction the
+            // single-entry path already refuses to store. The same reconciliation
+            // is called here rather than re-derived: only-a-duration means
+            // `started_at` anchors and `ended_at` shifts to match, a clock that
+            // does not exist is never manufactured (so a cell whose entry has no
+            // clocks keeps having none, and a running timer is not stopped), and a
+            // re-dated row takes its clocks with it.
+            const interval = reconcileTimeEntryInterval({
+              stored: rebaseTimeEntryIntervalToDate({
+                stored: {
+                  startedAt: existing.startedAt ?? null,
+                  endedAt: existing.endedAt ?? null,
+                  durationMinutes: existing.durationMinutes,
+                },
+                fromDate: existing.date,
+                toDate: entry.date,
+              }),
+              startedAt: undefined,
+              endedAt: undefined,
+              durationMinutes: entry.durationMinutes,
+            })
+            const projectChanged = timeProjectId !== (existing.timeProjectId ?? null)
             existing.date = entry.date
-            existing.timeProjectId = entry.timeProjectId
-            existing.durationMinutes = entry.durationMinutes
-            existing.notes = entry.notes ?? existing.notes
+            existing.timeProjectId = timeProjectId
+            // Snapshotted, never joined at read time, so a later project currency
+            // change cannot re-denominate money already reported (D-3) — and only
+            // restated when the entry actually moves between projects, exactly as
+            // the single-entry update command does it.
+            if (projectChanged) existing.rateCurrencyCode = project?.currencyCode ?? null
+            existing.startedAt = interval.startedAt
+            existing.endedAt = interval.endedAt
+            existing.durationMinutes = interval.durationMinutes
+            // D-7 keeps `rounded_minutes` the only input to cost, so it is restated
+            // from the effective duration the reconciliation settled on.
+            existing.roundedMinutes = roundedMinutesFor(interval.durationMinutes, settings, {
+              tenantId,
+              organizationId,
+            })
+            if (entry.taskId !== undefined) existing.taskId = task?.id ?? null
+            if (entry.isBillable !== undefined) existing.isBillable = entry.isBillable
+            if (entry.rateOverrideAmount !== undefined) {
+              existing.rateOverrideAmount = toStoredTimeEntryRateOverride(entry.rateOverrideAmount)
+            }
+            if (notes !== undefined) existing.notes = notes
             existing.updatedAt = new Date()
             updated++
             changes.push({ action: 'updated', entity: existing })
@@ -199,9 +458,22 @@ export async function POST(req: Request) {
             organizationId,
             staffMemberId,
             date: entry.date,
-            timeProjectId: entry.timeProjectId,
+            timeProjectId,
+            taskId: task?.id ?? null,
             durationMinutes: entry.durationMinutes,
-            notes: entry.notes ?? null,
+            roundedMinutes: roundedMinutesFor(entry.durationMinutes, settings, {
+              tenantId,
+              organizationId,
+            }),
+            notes: notes ?? null,
+            isBillable: resolveTimeEntryBillable({
+              requested: entry.isBillable,
+              project,
+              settings,
+              scope: { tenantId, organizationId },
+            }),
+            rateOverrideAmount: toStoredTimeEntryRateOverride(entry.rateOverrideAmount),
+            rateCurrencyCode: project?.currencyCode ?? null,
             source: 'manual',
             createdAt: now,
             updatedAt: now,
@@ -252,7 +524,7 @@ export async function POST(req: Request) {
         tenantId,
         organizationId,
         userId: auth.sub ?? '',
-        resourceKind: 'staff.timesheets.time_entry',
+        resourceKind: STAFF_TIME_TRACKING_RESOURCE_KINDS.timeEntry,
         resourceId: staffMemberId,
         operation: 'update',
         requestMethod: req.method,
@@ -260,7 +532,20 @@ export async function POST(req: Request) {
       })
     }
 
-    return NextResponse.json({ ok: true, ...counts }, { status: 200 })
+    // One batch-level event beside the per-row CRUD events already flushed above.
+    // It carries no `id`, so the entry-scoped subscribers that key off one record
+    // skip it and only the batch-aware ones (payroll exports, audit mirrors) react.
+    void emitStaffEvent('staff.timesheets.time_entry.bulk_updated', {
+      tenantId,
+      organizationId,
+      staffMemberId,
+      ...counts,
+      entryIds: pendingChanges.map((change) => change.entity.id),
+    }, { persistent: true }).catch((err) => {
+      logger.error('staff.timesheets emit time_entry.bulk_updated failed', { err })
+    })
+
+    return session.respond(200, { ok: true, ...counts })
   } catch (err) {
     if (err instanceof CrudHttpError) {
       return NextResponse.json(err.body, { status: err.status })
@@ -280,7 +565,8 @@ export const openApi: OpenApiRouteDoc = {
   methods: {
     POST: {
       summary: 'Bulk save time entries',
-      description: 'Creates, updates, or soft-deletes multiple time entries in a single request. Entries with durationMinutes=0 and an existing id are soft-deleted.',
+      description:
+        'Creates, updates, or soft-deletes multiple time entries in a single request. Entries with durationMinutes=0 and an existing id are soft-deleted. A row may name a taskId and let timeProjectId follow from it; task, description/notes precedence, isBillable defaulting, the rate override and the project currency snapshot follow the single-entry path exactly. tagIds is rejected with 422 — tags are edited from the time entry itself so their audit trail and undo stay intact. The whole batch is rejected with 409 time_entry_locked when any row targets — by id, or by landing on its (project, date) cell — an entry frozen in a closed report.',
       requestBody: {
         contentType: 'application/json',
         schema: staffTimeEntryBulkSaveSchema,
@@ -304,6 +590,17 @@ export const openApi: OpenApiRouteDoc = {
             errors: z.array(z.object({ path: z.string(), message: z.string() })),
           }),
         },
+        {
+          status: 409,
+          description: 'One or more rows target a time entry locked in a closed report; nothing was saved',
+          schema: z.object({
+            code: z.literal('time_entry_locked'),
+            error: z.string(),
+            lockedReportId: z.string().uuid().nullable(),
+            lockedEntryIds: z.array(z.string().uuid()),
+            lockedReportIds: z.array(z.string().uuid()),
+          }),
+        },
         { status: 401, description: 'Unauthorized', schema: z.object({ error: z.string() }) },
         { status: 403, description: 'Forbidden', schema: z.object({ error: z.string() }) },
       ],