@open-mercato/core 0.7.1-develop.7178.1.ab93fbaf4e → 0.7.1-develop.7179.1.e8c03264b6

package/src/modules/staff/lib/time-tracking/projectCode.ts

@@ -0,0 +1,221 @@
+/**
+ * EP-39 — the project code generator provider.
+ *
+ * `deriveProjectCode` keeps its signature and its meaning; the three-letter
+ * initials rule plus the collision counter now live in the built-in generator
+ * `staff.time_tracking.project_code.initials`, which `deriveProjectCode`
+ * delegates to. A contributed generator outranks it only when the caller passes
+ * a complete tenant + organization scope.
+ *
+ * Two runtime call sites exist and both are client-side —
+ * `lib/time-tracking-ui/ProjectCodeField.tsx` derives the suggestion as the user
+ * types a project name and again when the field is reset. Neither has a tenant
+ * id to hand, so both resolve the built-in today.
+ * `lib/time-tracking/migrateProjectCodes.ts` uses `deriveProjectCodeBase`, not
+ * this function.
+ */
+
+import { extensionPoints } from '@open-mercato/core/modules/staff/extension-points'
+import { createStrategyRegistry, BUILT_IN_STRATEGY_PRIORITY } from './registries/registry'
+import { selectScopedStrategy, type ScopedResolverContext } from './registries/scope'
+import { runStrategy } from './registries/invoke'
+
+export const PROJECT_CODE_MAX_LENGTH = 20
+
+/**
+ * The length a derived code aims for. Task references quote it on every card,
+ * drawer title and picker row (`ADS-21`), so a code that reads like a sentence
+ * makes the reference unusable as the thing people say to each other.
+ *
+ * It is a target, not a ceiling: a collision extends the code rather than
+ * mangling it, and a hand-typed code is still allowed up to
+ * `PROJECT_CODE_MAX_LENGTH`, because the person naming a project knows better
+ * than the transliterator does.
+ */
+export const PROJECT_CODE_TARGET_LENGTH = 3
+
+export const PROJECT_CODE_FALLBACK = 'PRJ'
+
+const WORD_BOUNDARY_BUDGET = PROJECT_CODE_MAX_LENGTH - 1
+
+const COMBINING_MARK_START = 0x300
+const COMBINING_MARK_END = 0x36f
+const ASCII_END = 0x7f
+
+const SPECIAL_CHARACTERS: Record<string, string> = {
+  'ł': 'l',
+  'Ł': 'L',
+  'đ': 'd',
+  'Đ': 'D',
+  'ð': 'd',
+  'Ð': 'D',
+  'ø': 'o',
+  'Ø': 'O',
+  'æ': 'ae',
+  'Æ': 'AE',
+  'œ': 'oe',
+  'Œ': 'OE',
+  'ß': 'ss',
+  'þ': 'th',
+  'Þ': 'TH',
+}
+
+function transliterate(value: string): string {
+  let result = ''
+  for (const character of value.normalize('NFD')) {
+    const code = character.codePointAt(0) ?? 0
+    if (code >= COMBINING_MARK_START && code <= COMBINING_MARK_END) continue
+    if (code <= ASCII_END) {
+      result += character
+      continue
+    }
+    result += SPECIAL_CHARACTERS[character] ?? character
+  }
+  return result
+}
+
+export function slugifyProjectName(name: string): string {
+  return transliterate(typeof name === 'string' ? name : '')
+    .toUpperCase()
+    .replace(/[^A-Z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '')
+}
+
+function truncateAtWordBoundary(slug: string, budget: number): string {
+  if (budget <= 0) return ''
+  if (slug.length <= budget) return slug
+  let result = ''
+  for (const word of slug.split('-')) {
+    const next = result ? `${result}-${word}` : word
+    if (next.length > budget) break
+    result = next
+  }
+  if (!result) result = slug.slice(0, budget)
+  return result.replace(/-+$/g, '')
+}
+
+/**
+ * The three letters a name reduces to.
+ *
+ * A multi-word name gives its initials — `Ergo Hestia Korpo` reads as `EHK`,
+ * which a person recognises, where the first three characters (`ERG`) do not.
+ * A single word gives its first three letters, so `Apollo` is `APO` and a name
+ * already at or under three characters (`HBH`) is left exactly as it is.
+ */
+export function deriveProjectCodeBase(name: string): string {
+  const slug = slugifyProjectName(name)
+  if (!slug) return PROJECT_CODE_FALLBACK
+  const words = slug.split('-').filter((word) => word.length > 0)
+  if (words.length === 0) return PROJECT_CODE_FALLBACK
+
+  const initials = words.map((word) => word[0]).join('')
+  const base = words.length >= PROJECT_CODE_TARGET_LENGTH
+    ? initials.slice(0, PROJECT_CODE_TARGET_LENGTH)
+    : words.join('').slice(0, PROJECT_CODE_TARGET_LENGTH)
+
+  return base || PROJECT_CODE_FALLBACK
+}
+
+/**
+ * Three letters is roughly 17,500 combinations and derived codes cluster hard —
+ * `Apollo`, `Aponia` and `Apex` all want `APO` — so a collision is the normal
+ * case rather than the exception, and the rule for resolving one has to be
+ * boring and predictable. The counter extends the code (`APO` → `APO2`) instead
+ * of substituting a letter, because a fourth character is still readable while
+ * `APQ` is a different project as far as anybody reading it is concerned.
+ */
+function deriveInitialsCode(name: string, taken: Set<string>): string {
+  const base = deriveProjectCodeBase(name)
+  const reserved = new Set(Array.from(taken ?? []).map((value) => String(value).toUpperCase()))
+  if (!reserved.has(base)) return base
+
+  for (let counter = 2; counter < 10000; counter += 1) {
+    const candidate = `${base}${counter}`
+    if (candidate.length > PROJECT_CODE_MAX_LENGTH) break
+    if (!reserved.has(candidate)) return candidate
+  }
+
+  // Every short candidate is taken. Fall back to the long form rather than
+  // failing the save — a save that refuses to happen is worse than a long code.
+  const longBase =
+    truncateAtWordBoundary(slugifyProjectName(name), WORD_BOUNDARY_BUDGET) || PROJECT_CODE_FALLBACK
+  if (!reserved.has(longBase)) return longBase
+  for (let counter = 2; counter < 10000; counter += 1) {
+    const suffix = `-${counter}`
+    const stem =
+      truncateAtWordBoundary(longBase, PROJECT_CODE_MAX_LENGTH - suffix.length) || PROJECT_CODE_FALLBACK
+    const candidate = `${stem}${suffix}`
+    if (!reserved.has(candidate)) return candidate
+  }
+  return longBase
+}
+
+export type ProjectCodeContext = ScopedResolverContext & {
+  customerId?: string | null
+  timeProjectId?: string | null
+}
+
+export type ProjectCodeGenerator = {
+  id: string
+  priority?: number
+  generate(name: string, taken: Set<string>, ctx: ProjectCodeContext): string
+}
+
+export const PROJECT_CODE_GENERATOR_REGISTRY_ID = extensionPoints.hosts.projectCodeGeneratorRegistry.spotId
+
+export const BUILT_IN_PROJECT_CODE_GENERATOR_ID = 'staff.time_tracking.project_code.initials'
+
+const generatorRegistry = createStrategyRegistry<ProjectCodeGenerator>(PROJECT_CODE_GENERATOR_REGISTRY_ID)
+
+export function registerProjectCodeGenerator(generator: ProjectCodeGenerator): () => void {
+  return generatorRegistry.register(generator)
+}
+
+export function listProjectCodeGenerators(): ProjectCodeGenerator[] {
+  return generatorRegistry.list()
+}
+
+export function getProjectCodeGenerator(id: string | null | undefined): ProjectCodeGenerator | null {
+  return generatorRegistry.get(id)
+}
+
+const builtInProjectCodeGenerator: ProjectCodeGenerator = generatorRegistry.registerBuiltIn({
+  id: BUILT_IN_PROJECT_CODE_GENERATOR_ID,
+  priority: BUILT_IN_STRATEGY_PRIORITY,
+  generate: (name, taken) => deriveInitialsCode(name, taken),
+})
+
+export function resolveProjectCodeGenerator(
+  ctx?: ScopedResolverContext | null,
+): ProjectCodeGenerator {
+  return selectScopedStrategy(generatorRegistry.list(), builtInProjectCodeGenerator, ctx)
+}
+
+/**
+ * The code lands in a column with a length limit and is quoted on every task
+ * reference, so a generator that throws or answers with a blank, an over-long or a
+ * non-string value falls back to the module's own initials rule. A save that refuses
+ * to happen, or a project whose reference is unreadable, is worse than a code the
+ * contributor did not choose.
+ */
+export function deriveProjectCode(
+  name: string,
+  taken: Set<string> = new Set(),
+  ctx?: ProjectCodeContext | null,
+): string {
+  const generator = resolveProjectCodeGenerator(ctx)
+  const reserved = taken ?? new Set<string>()
+  const builtIn = () => deriveInitialsCode(name, reserved)
+  if (generator === builtInProjectCodeGenerator) return builtIn()
+
+  const answer = runStrategy(
+    PROJECT_CODE_GENERATOR_REGISTRY_ID,
+    generator.id,
+    () => generator.generate(name, reserved, ctx ?? {}) as unknown,
+    () => null,
+  )
+  if (typeof answer !== 'string') return builtIn()
+  const trimmed = answer.trim()
+  if (!trimmed || trimmed.length > PROJECT_CODE_MAX_LENGTH) return builtIn()
+  return trimmed
+}

package/src/modules/staff/lib/time-tracking/reapplyRounding.ts

@@ -0,0 +1,313 @@
+/**
+ * Retroactive rounding, the long-running half (T7.3 / screen 16 note 3).
+ *
+ * "Apply the new rounding rule to entries that already exist" is a tenant-wide
+ * rewrite of a billing-relevant column, so it is a `ProgressJob` driven by a queue
+ * worker rather than a request that has to finish before a response — and, just as
+ * importantly, an action somebody deliberately takes rather than a passive toggle
+ * that rewrites history when the settings form is saved.
+ *
+ * What this file owns:
+ *
+ *  * **Candidate selection.** Only entries that are not deleted and not locked into
+ *    a closed report are ever selected. The command re-asserts the same condition in
+ *    its own WHERE clause, so a locked entry is excluded twice, independently.
+ *  * **Batching and progress.** Ids are paged with a stable `id > cursor` cursor and
+ *    handed to the command in batches, grouped by organization because a command
+ *    call is scoped to exactly one. Progress is reported per batch, and a cancel
+ *    request is honoured between batches.
+ *  * **Side-effect suppression.** Batches run with `bulkImport.skipEvents` /
+ *    `skipNotifications`: the query index still refreshes per entry, but a
+ *    thousand-entry restatement does not emit a thousand `time_entry.updated`
+ *    events (which would, among other things, re-evaluate every project budget
+ *    threshold a thousand times).
+ */
+
+import type { AwilixContainer } from 'awilix'
+import type { EntityManager } from '@mikro-orm/postgresql'
+import type { CommandBus, CommandRuntimeContext } from '@open-mercato/shared/lib/commands'
+import { createModuleQueue, type Queue } from '@open-mercato/queue'
+import { createLogger } from '@open-mercato/shared/lib/logger'
+import { buildSqlInClause } from './sqlInClause'
+import {
+  BUILT_IN_RECALCULATION_ID,
+  registerTimeTrackingRecalculation,
+} from './recalculations'
+import { BUILT_IN_STRATEGY_PRIORITY } from './registries/registry'
+import type { ProgressService, ProgressServiceContext } from '../../../progress/lib/progressService'
+import {
+  staffTimeEntryCommandIds,
+  type StaffTimeEntryReapplyRoundingResult,
+} from '../../commands/timesheets-entries'
+
+const logger = createLogger('staff').child({ component: 'time-tracking/reapply-rounding' })
+
+export const STAFF_TIME_REAPPLY_ROUNDING_QUEUE = 'staff-time-reapply-rounding'
+export const STAFF_TIME_REAPPLY_ROUNDING_JOB_TYPE = 'staff.timesheets.reapply_rounding'
+
+/** One command call per batch; the command itself caps the id list at 500. */
+export const REAPPLY_ROUNDING_BATCH_SIZE = 200
+
+export type ReapplyRoundingScope = {
+  tenantId: string
+  /** Organizations the caller may act in; `null` means every organization of the tenant. */
+  organizationIds: string[] | null
+  userId?: string | null
+}
+
+export type ReapplyRoundingJobPayload = {
+  progressJobId: string
+  scope: ReapplyRoundingScope
+  /**
+   * EP-51. The recalculation hooks this job should run, in the order given.
+   * Absent — which is every job the settings route enqueues — means the built-in
+   * rounding hook alone, so the retro-rounding button keeps doing exactly what it
+   * did before the registry existed.
+   */
+  hookIds?: string[] | null
+}
+
+export type ReapplyRoundingSummary = {
+  totalCount: number
+  processedCount: number
+  updatedCount: number
+  unchangedCount: number
+  skippedCount: number
+  cancelled: boolean
+}
+
+const queues = new Map<string, Queue<Record<string, unknown>>>()
+
+export function getStaffQueue(queueName: string): Queue<Record<string, unknown>> {
+  const existing = queues.get(queueName)
+  if (existing) return existing
+  const concurrency = Math.max(1, Number.parseInt(process.env.STAFF_QUEUE_CONCURRENCY ?? '1', 10) || 1)
+  const created = createModuleQueue<Record<string, unknown>>(queueName, { concurrency })
+  queues.set(queueName, created)
+  return created
+}
+
+type CandidateRow = {
+  id: string
+  organization_id: string
+}
+
+type CountRow = {
+  candidate_count: string | number | null
+}
+
+function buildCommandContext(
+  container: AwilixContainer,
+  tenantId: string,
+  organizationId: string,
+): CommandRuntimeContext {
+  return {
+    container,
+    auth: null,
+    // The job runs without an end user; the enqueuing route is the authorization
+    // gate (`staff.timesheets.settings.manage`), so the worker declares itself a
+    // system actor and passes the scope explicitly rather than inheriting one.
+    systemActor: true,
+    bulkImport: { skipEvents: true, skipNotifications: true },
+    organizationScope: {
+      selectedId: organizationId,
+      filterIds: [organizationId],
+      allowedIds: [organizationId],
+      tenantId,
+    },
+    selectedOrganizationId: organizationId,
+    organizationIds: [organizationId],
+  }
+}
+
+function organizationClause(organizationIds: string[] | null): { sql: string; params: unknown[] } {
+  if (!organizationIds) return { sql: '', params: [] }
+  const clause = buildSqlInClause('organization_id', organizationIds)
+  return { sql: ` AND ${clause.sql}`, params: clause.params }
+}
+
+export async function countReapplyRoundingCandidates(
+  em: EntityManager,
+  scope: ReapplyRoundingScope,
+): Promise<number> {
+  const org = organizationClause(scope.organizationIds)
+  const rows = (await em.getConnection().execute(
+    `
+      SELECT COUNT(*)::bigint AS candidate_count
+      FROM staff_time_entries
+      WHERE tenant_id = ?
+        AND deleted_at IS NULL
+        AND locked_report_id IS NULL${org.sql}
+    `,
+    [scope.tenantId, ...org.params],
+  )) as CountRow[]
+  const parsed = Number(rows?.[0]?.candidate_count ?? 0)
+  return Number.isFinite(parsed) ? parsed : 0
+}
+
+async function loadCandidatePage(
+  em: EntityManager,
+  scope: ReapplyRoundingScope,
+  cursor: string | null,
+  limit: number,
+): Promise<CandidateRow[]> {
+  const org = organizationClause(scope.organizationIds)
+  const cursorClause = cursor ? ' AND id > ?' : ''
+  const cursorParams = cursor ? [cursor] : []
+  return (await em.getConnection().execute(
+    `
+      SELECT id, organization_id
+      FROM staff_time_entries
+      WHERE tenant_id = ?
+        AND deleted_at IS NULL
+        AND locked_report_id IS NULL${org.sql}${cursorClause}
+      ORDER BY id ASC
+      LIMIT ?
+    `,
+    [scope.tenantId, ...org.params, ...cursorParams, limit],
+  )) as CandidateRow[]
+}
+
+function groupByOrganization(rows: readonly CandidateRow[]): Map<string, string[]> {
+  const grouped = new Map<string, string[]>()
+  for (const row of rows) {
+    const bucket = grouped.get(row.organization_id) ?? []
+    bucket.push(row.id)
+    grouped.set(row.organization_id, bucket)
+  }
+  return grouped
+}
+
+/**
+ * The restatement itself, with the `ProgressJob` lifecycle lifted out (EP-51).
+ *
+ * `reapplyRoundingWithProgress` below owns start/complete/cancel and is unchanged
+ * for its callers; the recalculation runner owns the same lifecycle when several
+ * hooks share one job. Both drive this function, so there is exactly one copy of
+ * the candidate query, the batching and the locked-entry exclusion.
+ */
+export async function reapplyRoundingBatches(params: {
+  container: AwilixContainer
+  scope: ReapplyRoundingScope
+  report: {
+    setTotal(total: number): Promise<void>
+    advance(processed: number): Promise<void>
+    isCancellationRequested(): Promise<boolean>
+  }
+}): Promise<ReapplyRoundingSummary> {
+  const { container, scope, report } = params
+  const em = (container.resolve('em') as EntityManager).fork()
+  const commandBus = container.resolve('commandBus') as CommandBus
+
+  const totalCount = await countReapplyRoundingCandidates(em, scope)
+  const summary: ReapplyRoundingSummary = {
+    totalCount,
+    processedCount: 0,
+    updatedCount: 0,
+    unchangedCount: 0,
+    skippedCount: 0,
+    cancelled: false,
+  }
+
+  if (totalCount === 0) return summary
+
+  await report.setTotal(totalCount)
+
+  let cursor: string | null = null
+  for (;;) {
+    const page: CandidateRow[] = await loadCandidatePage(em, scope, cursor, REAPPLY_ROUNDING_BATCH_SIZE)
+    if (page.length === 0) break
+    cursor = page[page.length - 1].id
+
+    let pageProcessed = 0
+    for (const [organizationId, entryIds] of groupByOrganization(page)) {
+      const executed = await commandBus.execute<
+        { tenantId: string; organizationId: string; entryIds: string[] },
+        StaffTimeEntryReapplyRoundingResult
+      >(staffTimeEntryCommandIds.reapplyRounding, {
+        input: { tenantId: scope.tenantId, organizationId, entryIds },
+        ctx: buildCommandContext(container, scope.tenantId, organizationId),
+      })
+      const result = executed?.result
+      summary.updatedCount += result?.updatedCount ?? 0
+      summary.unchangedCount += result?.unchangedCount ?? 0
+      summary.skippedCount += result?.skippedCount ?? 0
+      summary.processedCount += entryIds.length
+      pageProcessed += entryIds.length
+    }
+
+    await report.advance(pageProcessed)
+
+    if (await report.isCancellationRequested()) {
+      summary.cancelled = true
+      return summary
+    }
+  }
+
+  return summary
+}
+
+export async function reapplyRoundingWithProgress(params: {
+  container: AwilixContainer
+  progressJobId: string
+  scope: ReapplyRoundingScope
+}): Promise<ReapplyRoundingSummary> {
+  const { container, progressJobId, scope } = params
+  const progressService = container.resolve('progressService') as ProgressService
+  const progressContext: ProgressServiceContext = {
+    tenantId: scope.tenantId,
+    organizationId: scope.organizationIds?.length === 1 ? scope.organizationIds[0] : null,
+    userId: scope.userId ?? null,
+  }
+
+  await progressService.startJob(progressJobId, progressContext)
+
+  let totalCount = 0
+  let processedCount = 0
+  const summary = await reapplyRoundingBatches({
+    container,
+    scope,
+    report: {
+      setTotal: async (total) => {
+        totalCount = total
+        await progressService.updateProgress(progressJobId, { totalCount, processedCount: 0 }, progressContext)
+      },
+      advance: async (processed) => {
+        processedCount += processed
+        await progressService.updateProgress(
+          progressJobId,
+          { totalCount, processedCount: Math.min(processedCount, totalCount) },
+          progressContext,
+        )
+      },
+      isCancellationRequested: () =>
+        progressService.isCancellationRequested(progressJobId, scope.tenantId, progressContext.organizationId),
+    },
+  })
+
+  if (summary.cancelled) {
+    logger.info('staff.timesheets reapply-rounding cancelled', { progressJobId, ...summary })
+    await progressService.markCancelled(progressJobId, progressContext)
+    return summary
+  }
+
+  await progressService.completeJob(progressJobId, { resultSummary: { ...summary } }, progressContext)
+  if (summary.totalCount > 0) {
+    logger.info('staff.timesheets reapply-rounding finished', { progressJobId, ...summary })
+  }
+  return summary
+}
+
+/**
+ * EP-51. The retro-rounding pass registers itself as the built-in recalculation,
+ * so `registerTimeTrackingRecalculation` has a working reference implementation
+ * and the worker has one code path for the shipped hook and a contributed one.
+ * `BUILT_IN_STRATEGY_PRIORITY` keeps it last in the registry's order, the same as
+ * every other built-in in this module.
+ */
+registerTimeTrackingRecalculation({
+  id: BUILT_IN_RECALCULATION_ID,
+  labelKey: 'staff.time_tracking.settings.retro.jobName',
+  priority: BUILT_IN_STRATEGY_PRIORITY,
+  run: ({ container, scope, report }) => reapplyRoundingBatches({ container, scope, report }),
+})

package/src/modules/staff/lib/time-tracking/recalculationRunner.ts

@@ -0,0 +1,118 @@
+/**
+ * EP-51 — the job shell every registered recalculation runs inside.
+ *
+ * It owns the `ProgressJob` (start, totals, cancel, complete) and hands each hook
+ * a reporter scoped to that job, so N hooks share one progress bar instead of
+ * fighting over it. Hooks run **sequentially** and in registry order: they write
+ * the same rows, and two of them racing over `staff_time_entries` is the kind of
+ * bug that shows up as a wrong invoice a month later.
+ *
+ * A hook that throws does not silently vanish — the runner logs it and rethrows,
+ * because a half-finished restatement the operator believes succeeded is worse
+ * than a loud failure. Marking the `ProgressJob` failed is the worker's job: it
+ * already does that for every exception that reaches it, and doing it in both
+ * places would write the failure twice.
+ */
+
+import type { AwilixContainer } from 'awilix'
+import { createLogger } from '@open-mercato/shared/lib/logger'
+import type { ProgressService, ProgressServiceContext } from '../../../progress/lib/progressService'
+import {
+  emptyRecalculationSummary,
+  resolveTimeTrackingRecalculations,
+  type TimeTrackingRecalculationScope,
+  type TimeTrackingRecalculationSummary,
+} from './recalculations'
+
+const logger = createLogger('staff').child({ component: 'time-tracking/recalculation-runner' })
+
+export type TimeTrackingRecalculationRunSummary = TimeTrackingRecalculationSummary & {
+  hooks: Array<{ id: string } & TimeTrackingRecalculationSummary>
+}
+
+function progressContextFor(scope: TimeTrackingRecalculationScope): ProgressServiceContext {
+  return {
+    tenantId: scope.tenantId,
+    organizationId: scope.organizationIds?.length === 1 ? scope.organizationIds[0] : null,
+    userId: scope.userId ?? null,
+  }
+}
+
+function accumulate(
+  target: TimeTrackingRecalculationSummary,
+  addend: TimeTrackingRecalculationSummary,
+): void {
+  target.totalCount += addend.totalCount
+  target.processedCount += addend.processedCount
+  target.updatedCount += addend.updatedCount
+  target.unchangedCount += addend.unchangedCount
+  target.skippedCount += addend.skippedCount
+  target.cancelled = target.cancelled || addend.cancelled
+}
+
+export async function runTimeTrackingRecalculations(params: {
+  container: AwilixContainer
+  progressJobId: string
+  scope: TimeTrackingRecalculationScope
+  hookIds?: readonly string[] | null
+}): Promise<TimeTrackingRecalculationRunSummary> {
+  const { container, progressJobId, scope } = params
+  const hooks = resolveTimeTrackingRecalculations(params.hookIds)
+  const progressService = container.resolve('progressService') as ProgressService
+  const progressContext = progressContextFor(scope)
+
+  await progressService.startJob(progressJobId, progressContext)
+
+  const summary: TimeTrackingRecalculationRunSummary = { ...emptyRecalculationSummary(), hooks: [] }
+  let knownTotal = 0
+  let processed = 0
+
+  try {
+    for (const hook of hooks) {
+      const hookSummary = await hook.run({
+        container,
+        scope,
+        report: {
+          setTotal: async (total) => {
+            knownTotal += total
+            await progressService.updateProgress(
+              progressJobId,
+              { totalCount: knownTotal, processedCount: Math.min(processed, knownTotal) },
+              progressContext,
+            )
+          },
+          advance: async (count) => {
+            processed += count
+            await progressService.updateProgress(
+              progressJobId,
+              { totalCount: knownTotal, processedCount: Math.min(processed, knownTotal) },
+              progressContext,
+            )
+          },
+          isCancellationRequested: () =>
+            progressService.isCancellationRequested(
+              progressJobId,
+              scope.tenantId,
+              progressContext.organizationId,
+            ),
+        },
+      })
+      summary.hooks.push({ id: hook.id, ...hookSummary })
+      accumulate(summary, hookSummary)
+      if (hookSummary.cancelled) break
+    }
+  } catch (err) {
+    logger.error('staff.timesheets recalculation failed', { progressJobId, ...summary, err })
+    throw err
+  }
+
+  if (summary.cancelled) {
+    logger.info('staff.timesheets recalculation cancelled', { progressJobId, ...summary })
+    await progressService.markCancelled(progressJobId, progressContext)
+    return summary
+  }
+
+  await progressService.completeJob(progressJobId, { resultSummary: { ...summary } }, progressContext)
+  logger.info('staff.timesheets recalculation finished', { progressJobId, ...summary })
+  return summary
+}