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

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

@@ -0,0 +1,135 @@
+/**
+ * EP-51 — the recalculation registry.
+ *
+ * A recalculation is a tenant-wide restatement of a derived time-tracking value:
+ * the module ships one, the retro-rounding pass behind
+ * `POST /api/staff/timesheets/settings/reapply-rounding`, and a third party that
+ * plugs in its own rate resolver (EP-33) or billability chain (EP-34) needs the
+ * same thing — a way to re-apply the new rule to the rows that already exist,
+ * with the progress bar, the cancel button and the queue worker the module
+ * already has.
+ *
+ * The contract is deliberately narrow. A hook receives a scope and a reporter and
+ * answers a count summary; it does NOT own the `ProgressJob`, because several
+ * hooks share one job when the CLI runs them together, and a hook that started or
+ * completed the job would fight the next one.
+ *
+ * **`run` is a write over a tenant's history.** Two rules that are not optional:
+ * every query must carry `tenantId` (and honour `organizationIds` when it is not
+ * `null`), and a locked entry — one frozen into a closed report — must never be
+ * touched. The built-in excludes locked entries twice, in its own candidate query
+ * and again in the command it drives.
+ */
+
+import type { AwilixContainer } from 'awilix'
+import { extensionPoints } from '@open-mercato/core/modules/staff/extension-points'
+import { createStrategyRegistry, BUILT_IN_STRATEGY_PRIORITY } from './registries/registry'
+
+export const TIME_TRACKING_RECALCULATION_REGISTRY_ID =
+  extensionPoints.hosts.recalculationRegistry.spotId
+
+export const BUILT_IN_RECALCULATION_ID = 'staff.time_tracking.recalculation.rounding'
+
+export type TimeTrackingRecalculationScope = {
+  tenantId: string
+  /** Organizations the caller may act in; `null` means every organization of the tenant. */
+  organizationIds: string[] | null
+  userId?: string | null
+}
+
+/**
+ * The slice of the progress job a hook is allowed to touch. `advance` is additive
+ * so two hooks sharing one job cannot rewind each other's count.
+ */
+export type TimeTrackingRecalculationReporter = {
+  setTotal(total: number): Promise<void>
+  advance(processed: number): Promise<void>
+  isCancellationRequested(): Promise<boolean>
+}
+
+export type TimeTrackingRecalculationContext = {
+  container: AwilixContainer
+  scope: TimeTrackingRecalculationScope
+  report: TimeTrackingRecalculationReporter
+}
+
+export type TimeTrackingRecalculationSummary = {
+  totalCount: number
+  processedCount: number
+  updatedCount: number
+  unchangedCount: number
+  skippedCount: number
+  cancelled: boolean
+}
+
+export type TimeTrackingRecalculation = {
+  id: string
+  labelKey: string
+  priority?: number
+  run(ctx: TimeTrackingRecalculationContext): Promise<TimeTrackingRecalculationSummary>
+}
+
+const registry = createStrategyRegistry<TimeTrackingRecalculation>(
+  TIME_TRACKING_RECALCULATION_REGISTRY_ID,
+)
+
+export function registerTimeTrackingRecalculation(
+  recalculation: TimeTrackingRecalculation,
+): () => void {
+  if (typeof recalculation?.run !== 'function') {
+    throw new Error('[internal] a time-tracking recalculation must declare a run() function')
+  }
+  return registry.register(recalculation)
+}
+
+export function listTimeTrackingRecalculations(): TimeTrackingRecalculation[] {
+  return registry.list()
+}
+
+export function timeTrackingRecalculationIds(): string[] {
+  return registry.ids()
+}
+
+export function getTimeTrackingRecalculation(
+  id: string | null | undefined,
+): TimeTrackingRecalculation | null {
+  return registry.get(id)
+}
+
+export function emptyRecalculationSummary(): TimeTrackingRecalculationSummary {
+  return {
+    totalCount: 0,
+    processedCount: 0,
+    updatedCount: 0,
+    unchangedCount: 0,
+    skippedCount: 0,
+    cancelled: false,
+  }
+}
+
+/**
+ * Resolves the hooks a job should run.
+ *
+ * An empty or absent request resolves to the built-in alone — which is what keeps
+ * the settings route byte-identical: it enqueues no hook ids, so a contribution
+ * cannot attach itself to the retro-rounding button a tenant pressed. Running
+ * more than one is an explicit act, and the CLI is where it is made.
+ *
+ * An unknown id is an error rather than a silent skip: a backfill that quietly
+ * did nothing is worse than one that refused to start.
+ */
+export function resolveTimeTrackingRecalculations(
+  ids?: readonly string[] | null,
+): TimeTrackingRecalculation[] {
+  if (!ids || ids.length === 0) {
+    const builtIn = registry.get(BUILT_IN_RECALCULATION_ID)
+    return builtIn ? [builtIn] : []
+  }
+  const resolved: TimeTrackingRecalculation[] = []
+  for (const id of ids) {
+    const entry = registry.get(id)
+    if (!entry) throw new Error(`[internal] unknown time-tracking recalculation id: ${id}`)
+    if (!resolved.some((candidate) => candidate.id === entry.id)) resolved.push(entry)
+  }
+  return resolved
+}

package/src/modules/staff/lib/time-tracking/registries/invoke.ts

@@ -0,0 +1,122 @@
+/**
+ * Calling a contributed strategy safely.
+ *
+ * Every registry in `EP-32…EP-41` hands third-party code a function the module then
+ * calls in the middle of a write path or a report render. None of those call sites
+ * originally wrapped the call, so one contributed `round`, `sort` or `serialize`
+ * that threw took the surrounding operation down — for the whole process, not just
+ * the tenant that installed the contribution, because the registries are plain
+ * module-scope maps shared by every request the process serves.
+ *
+ * The rule these helpers encode: **a broken contribution degrades to the module's
+ * own behaviour, loudly.** It never propagates, and it never silently wins either —
+ * every fallback logs the registry and the strategy id, because a strategy that
+ * quietly stopped applying is the failure mode that takes weeks to notice.
+ *
+ * Which helper to reach for:
+ *
+ *  - `runStrategy` — single-winner registries, where there is exactly one right
+ *    answer and the built-in is it when the contribution cannot produce one.
+ *  - `tryStrategy` — chain registries, where the next candidate is asked anyway, so
+ *    a thrower is skipped rather than replaced.
+ */
+
+import { createLogger } from '@open-mercato/shared/lib/logger'
+
+const logger = createLogger('staff').child({ component: 'time-tracking/registries' })
+
+export function runStrategy<TResult>(
+  registryId: string,
+  strategyId: string,
+  run: () => TResult,
+  fallback: () => TResult,
+): TResult {
+  try {
+    return run()
+  } catch (err) {
+    logger.error('a time-tracking strategy threw; falling back to the built-in', {
+      registryId,
+      strategyId,
+      err,
+    })
+    return fallback()
+  }
+}
+
+/** `undefined` means "this candidate could not answer"; ask the next one. */
+export function tryStrategy<TResult>(
+  registryId: string,
+  strategyId: string,
+  run: () => TResult,
+): TResult | undefined {
+  try {
+    return run()
+  } catch (err) {
+    logger.error('a time-tracking strategy threw; skipping this candidate', {
+      registryId,
+      strategyId,
+      err,
+    })
+    return undefined
+  }
+}
+
+/** The largest value `staff_time_entries.rounded_minutes` — a PostgreSQL `integer` — can hold. */
+export const MAX_STORED_MINUTES = 2_147_483_647
+
+/**
+ * Clamps a strategy's answer to something the column it lands in can hold.
+ *
+ * `staff_time_entries.rounded_minutes` is an `integer` and the sole input to every
+ * amount the suite computes, so a `NaN`, a fraction or a negative from a
+ * contributed strategy is not a cosmetic problem: the write either fails or stores
+ * garbage, and on read `entryAmount` substitutes `0`, which bills the entry at
+ * nothing without saying so. The shipped default `unitMinutes: 0` makes this the
+ * FIRST thing a plausible contribution hits — `Math.floor(raw / ctx.settings.unitMinutes)`
+ * is division by zero.
+ *
+ * Three answers are refused rather than stored, and each one logs, because the rule
+ * this file encodes is that a degraded contribution degrades *loudly*:
+ *
+ *  - **Not a finite number** — nothing to clamp toward; take the built-in.
+ *  - **Negative** — a duration that ran backwards is not a value to clamp to zero.
+ *    Storing `0` is exactly the silent zero-bill the paragraph above describes, so a
+ *    negative takes the built-in arm alongside `NaN`.
+ *  - **Larger than the column** — the INSERT would fail with an out-of-range error
+ *    and 500 the write, which is the propagation these helpers exist to prevent.
+ *    Clamped down to the column's ceiling so the write still lands.
+ */
+export function clampToStoredMinutes(
+  registryId: string,
+  strategyId: string,
+  value: unknown,
+  fallback: () => number,
+): number {
+  if (typeof value !== 'number' || !Number.isFinite(value)) {
+    logger.error('a time-tracking strategy answered a non-finite duration; falling back to the built-in', {
+      registryId,
+      strategyId,
+      value: String(value),
+    })
+    return fallback()
+  }
+  if (value < 0) {
+    logger.error('a time-tracking strategy answered a negative duration; falling back to the built-in', {
+      registryId,
+      strategyId,
+      value,
+    })
+    return fallback()
+  }
+  const rounded = Math.round(value)
+  if (rounded > MAX_STORED_MINUTES) {
+    logger.error('a time-tracking strategy answered more minutes than the column can hold; clamping', {
+      registryId,
+      strategyId,
+      value,
+      max: MAX_STORED_MINUTES,
+    })
+    return MAX_STORED_MINUTES
+  }
+  return rounded
+}

package/src/modules/staff/lib/time-tracking/registries/registry.ts

@@ -0,0 +1,124 @@
+/**
+ * The one registry shape every time-tracking strategy registry is built from
+ * (EP-32…EP-41 of `.ai/specs/2026-08-24-time-tracking-umes-extension-points.md`).
+ *
+ * It follows the house provider idiom — `registerPaymentProvider` /
+ * `registerShippingProvider` in `modules/sales/lib/providers/registry.ts`: a
+ * module-level `Map`, a `register` that returns its own disposer, and plain
+ * lookup helpers. That makes every registry reachable from the browser bundle as
+ * well as the server, which matters because four of these strategies are
+ * consulted by client previews that cannot resolve DI.
+ *
+ * Ordering is the only thing added on top of the sales idiom, and it is what
+ * keeps "no contribution means no behaviour change" true: entries are served in
+ * descending `priority`, ties broken by registration order, and every built-in
+ * registers at `BUILT_IN_STRATEGY_PRIORITY` — far below the default of `0` — so
+ * a built-in is always the last candidate considered.
+ *
+ * **A built-in is not just a low-priority entry, it is a separate slot.** The
+ * fail-closed rule in `scope.ts` lands an unscoped call on "the built-in", and the
+ * whole point of that rule is that the built-in is the same pure code the module
+ * shipped before the registries existed. With one map keyed by id and last-writer-
+ * wins semantics, a contribution registering under a published built-in id BECAME
+ * the built-in: it ran on the unscoped path the gate exists to keep byte-identical,
+ * and its disposer then deleted the real built-in permanently, after which every
+ * resolver that requires one throws. So `registerBuiltIn` writes to a map
+ * `register` cannot reach, `register` refuses a built-in id outright, and no
+ * disposer can remove a built-in.
+ */
+
+export const BUILT_IN_STRATEGY_PRIORITY = -1000
+
+export type RegisteredStrategy = {
+  id: string
+  priority?: number
+}
+
+export type StrategyRegistry<TEntry extends RegisteredStrategy> = {
+  registryId: string
+  /**
+   * Registers the module's own default. Not part of the contribution surface —
+   * module-load code only. The returned entry is the identity every resolver
+   * should compare against rather than re-looking the id up.
+   */
+  registerBuiltIn(entry: TEntry): TEntry
+  /** Contributes a strategy. Throws on a built-in id. Returns its own disposer. */
+  register(entry: TEntry): () => void
+  get(id: string | null | undefined): TEntry | null
+  has(id: string | null | undefined): boolean
+  isBuiltIn(id: string | null | undefined): boolean
+  list(): TEntry[]
+  ids(): string[]
+}
+
+type Slot<TEntry extends RegisteredStrategy> = {
+  entry: TEntry
+  sequence: number
+}
+
+function orderSlots<TEntry extends RegisteredStrategy>(left: Slot<TEntry>, right: Slot<TEntry>): number {
+  const leftPriority = left.entry.priority ?? 0
+  const rightPriority = right.entry.priority ?? 0
+  if (leftPriority !== rightPriority) return rightPriority - leftPriority
+  return left.sequence - right.sequence
+}
+
+export function createStrategyRegistry<TEntry extends RegisteredStrategy>(
+  registryId: string,
+): StrategyRegistry<TEntry> {
+  const builtInSlots = new Map<string, Slot<TEntry>>()
+  const contributedSlots = new Map<string, Slot<TEntry>>()
+  let sequence = 0
+
+  const readId = (entry: TEntry): string => {
+    const id = typeof entry?.id === 'string' ? entry.id.trim() : ''
+    if (!id) throw new Error(`[internal] ${registryId} requires a non-empty strategy id`)
+    return id
+  }
+
+  const registerBuiltIn = (entry: TEntry): TEntry => {
+    const id = readId(entry)
+    if (builtInSlots.has(id)) {
+      throw new Error(`[internal] ${registryId} already has a built-in registered as ${id}`)
+    }
+    sequence += 1
+    const slot: Slot<TEntry> = { entry: { ...entry, id }, sequence }
+    builtInSlots.set(id, slot)
+    return slot.entry
+  }
+
+  const register = (entry: TEntry): (() => void) => {
+    const id = readId(entry)
+    if (builtInSlots.has(id)) {
+      throw new Error(
+        `[internal] ${id} is a built-in ${registryId} strategy and cannot be replaced; register your own id`,
+      )
+    }
+    sequence += 1
+    const slot: Slot<TEntry> = { entry: { ...entry, id }, sequence }
+    contributedSlots.set(id, slot)
+    return () => {
+      if (contributedSlots.get(id) === slot) contributedSlots.delete(id)
+    }
+  }
+
+  const list = (): TEntry[] =>
+    [...contributedSlots.values(), ...builtInSlots.values()].sort(orderSlots).map((slot) => slot.entry)
+
+  const get = (id: string | null | undefined): TEntry | null => {
+    if (typeof id !== 'string') return null
+    const trimmed = id.trim()
+    return contributedSlots.get(trimmed)?.entry ?? builtInSlots.get(trimmed)?.entry ?? null
+  }
+
+  return {
+    registryId,
+    registerBuiltIn,
+    register,
+    get,
+    has: (id) => get(id) !== null,
+    isBuiltIn: (id) => typeof id === 'string' && builtInSlots.has(id.trim()),
+    list,
+    ids: () => list().map((entry) => entry.id),
+  }
+}

package/src/modules/staff/lib/time-tracking/registries/scope.ts

@@ -0,0 +1,56 @@
+/**
+ * The scope contract every time-tracking strategy resolver receives, and the
+ * fail-closed rule the spec's cross-cutting requirements attach to it: a
+ * contributed strategy runs only when the caller supplied BOTH a tenant and an
+ * organization, matching `resolveProjectAccess` in `../access.ts`.
+ *
+ * A built-in never needs the scope — it is the same pure arithmetic the module
+ * shipped before the registries existed — so failing closed lands on the
+ * built-in rather than on an error. That is what makes a client preview
+ * (`TimeEntryDialog`, `timeTrackingSettingsForm`, `ProjectCodeField`), which has
+ * no tenant id to hand, keep producing exactly the number it produced before.
+ */
+
+export type TimeTrackingResolverScope = {
+  tenantId: string
+  organizationId: string
+}
+
+export type ScopedResolverContext = Partial<TimeTrackingResolverScope>
+
+function isNonEmpty(value: unknown): value is string {
+  return typeof value === 'string' && value.trim().length > 0
+}
+
+export function readResolverScope(
+  ctx: ScopedResolverContext | null | undefined,
+): TimeTrackingResolverScope | null {
+  if (!ctx) return null
+  if (!isNonEmpty(ctx.tenantId) || !isNonEmpty(ctx.organizationId)) return null
+  return { tenantId: ctx.tenantId, organizationId: ctx.organizationId }
+}
+
+export function hasResolverScope(ctx: ScopedResolverContext | null | undefined): boolean {
+  return readResolverScope(ctx) !== null
+}
+
+/**
+ * Picks the strategy a scoped call site should run: the highest-priority
+ * contribution when the scope is complete, the built-in otherwise. `candidates`
+ * arrives already ordered by the registry.
+ *
+ * The built-in is passed **by reference**, not looked up by id among the
+ * candidates. An id is a string anyone can register; identity is not. Resolving
+ * the fail-closed default by id meant a contribution that named itself after the
+ * built-in was served on the unscoped path the rule exists to keep byte-identical
+ * — `registry.ts` now refuses that registration, and this makes the second half of
+ * the same guarantee structural rather than conventional.
+ */
+export function selectScopedStrategy<TEntry extends { id: string }>(
+  candidates: readonly TEntry[],
+  builtIn: TEntry,
+  ctx: ScopedResolverContext | null | undefined,
+): TEntry {
+  if (!hasResolverScope(ctx)) return builtIn
+  return candidates[0] ?? builtIn
+}

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

@@ -0,0 +1,59 @@
+export type RollupTask = {
+  id: string
+  parentTaskId?: string | null
+  deletedAt?: Date | string | null
+}
+
+export type RollupEntry = {
+  durationMinutes?: number | null
+  deletedAt?: Date | string | null
+}
+
+export type EntriesByTaskId =
+  | ReadonlyMap<string, readonly RollupEntry[]>
+  | Record<string, readonly RollupEntry[] | undefined>
+
+export type TaskRollup = {
+  ownMinutes: number
+  loggedMinutes: number
+  childCount: number
+}
+
+function readEntries(source: EntriesByTaskId | null | undefined, taskId: string): readonly RollupEntry[] {
+  if (!source) return []
+  if (source instanceof Map) return source.get(taskId) ?? []
+  return (source as Record<string, readonly RollupEntry[] | undefined>)[taskId] ?? []
+}
+
+function sumEntryMinutes(entries: readonly RollupEntry[]): number {
+  let total = 0
+  for (const entry of entries) {
+    if (!entry || entry.deletedAt) continue
+    const minutes = entry.durationMinutes
+    if (minutes === null || minutes === undefined || !Number.isFinite(minutes)) continue
+    total += minutes
+  }
+  return total
+}
+
+export function loggedMinutes(
+  task: RollupTask,
+  allTasks: readonly RollupTask[],
+  entriesByTaskId: EntriesByTaskId,
+): TaskRollup {
+  const ownMinutes = sumEntryMinutes(readEntries(entriesByTaskId, task.id))
+  const children = (allTasks ?? []).filter(
+    (candidate) => candidate.parentTaskId === task.id && candidate.id !== task.id && !candidate.deletedAt,
+  )
+
+  let childMinutes = 0
+  for (const child of children) {
+    childMinutes += sumEntryMinutes(readEntries(entriesByTaskId, child.id))
+  }
+
+  return {
+    ownMinutes,
+    loggedMinutes: ownMinutes + childMinutes,
+    childCount: children.length,
+  }
+}

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

@@ -0,0 +1,126 @@
+/**
+ * EP-32 — the rounding strategy registry.
+ *
+ * `roundMinutes` is still the single rounding entry point every call site uses,
+ * and with no contribution it runs the built-in `staff.time_tracking.rounding.unit`
+ * strategy, which is the same `up`/`nearest` × `0|5|10|15` arithmetic this file
+ * has always held. A contribution outranks it only when the call site supplies a
+ * complete tenant + organization scope (`registries/scope.ts`), so an unscoped
+ * client preview keeps producing the built-in's number.
+ */
+
+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 { clampToStoredMinutes, runStrategy } from './registries/invoke'
+
+export type RoundingUnitMinutes = 0 | 5 | 10 | 15
+
+export type RoundingDirection = 'up' | 'nearest'
+
+export type RoundingSettings = {
+  unitMinutes: RoundingUnitMinutes
+  direction: RoundingDirection
+}
+
+export const DEFAULT_ROUNDING_SETTINGS: RoundingSettings = {
+  unitMinutes: 0,
+  direction: 'up',
+}
+
+export type TimeRoundingContext = ScopedResolverContext & {
+  settings: RoundingSettings
+  /** Present on write paths; absent on the settings-screen and dialog previews. */
+  timeProjectId?: string | null
+  taskId?: string | null
+  staffMemberId?: string | null
+  date?: string | null
+}
+
+export type TimeRoundingStrategy = {
+  id: string
+  labelKey: string
+  priority?: number
+  round(rawMinutes: number, ctx: TimeRoundingContext): number
+}
+
+export const TIME_ROUNDING_REGISTRY_ID = extensionPoints.hosts.timeRoundingRegistry.spotId
+
+export const BUILT_IN_TIME_ROUNDING_STRATEGY_ID = 'staff.time_tracking.rounding.unit'
+
+const registry = createStrategyRegistry<TimeRoundingStrategy>(TIME_ROUNDING_REGISTRY_ID)
+
+export function registerTimeRoundingStrategy(strategy: TimeRoundingStrategy): () => void {
+  return registry.register(strategy)
+}
+
+export function listTimeRoundingStrategies(): TimeRoundingStrategy[] {
+  return registry.list()
+}
+
+export function getTimeRoundingStrategy(id: string | null | undefined): TimeRoundingStrategy | null {
+  return registry.get(id)
+}
+
+function roundToUnit(raw: number, settings: RoundingSettings): number {
+  if (!Number.isFinite(raw)) return 0
+  const unit = settings?.unitMinutes ?? 0
+  if (!unit) return Math.round(raw)
+
+  const sign = raw < 0 ? -1 : 1
+  const magnitude = Math.abs(raw) / unit
+  const units = settings.direction === 'nearest' ? Math.round(magnitude) : Math.ceil(magnitude)
+  return sign * units * unit
+}
+
+const builtInRoundingStrategy: TimeRoundingStrategy = registry.registerBuiltIn({
+  id: BUILT_IN_TIME_ROUNDING_STRATEGY_ID,
+  labelKey: 'staff.time_tracking.rounding.strategy.unit',
+  priority: BUILT_IN_STRATEGY_PRIORITY,
+  round: (rawMinutes, ctx) => roundToUnit(rawMinutes, ctx.settings),
+})
+
+export function resolveTimeRoundingStrategy(
+  ctx?: ScopedResolverContext | null,
+): TimeRoundingStrategy {
+  return selectScopedStrategy(registry.list(), builtInRoundingStrategy, ctx)
+}
+
+/**
+ * The single rounding entry point, and the boundary a contributed strategy's answer
+ * has to survive.
+ *
+ * The result is written straight into `staff_time_entries.rounded_minutes` — an
+ * `integer` column, and the only input to every amount the suite computes — so an
+ * unusable answer is clamped back to the built-in's rather than stored, and one
+ * larger than the column can hold is capped at its ceiling rather than 500ing the
+ * write. The built-in is exempt from the clamp on purpose: it is the arithmetic the
+ * module shipped, it cannot produce a non-finite or fractional value, and re-shaping
+ * its output would be the behaviour change the registries exist to avoid.
+ *
+ * A strategy that *threw* has already been logged and replaced by `runStrategy`, so
+ * it returns the built-in directly instead of routing its `NaN` through the clamp,
+ * which would log the same failure a second time under the wrong description.
+ */
+export function roundMinutes(
+  raw: number,
+  settings: RoundingSettings,
+  ctx?: ScopedResolverContext | null,
+): number {
+  const strategy = resolveTimeRoundingStrategy(ctx)
+  const builtIn = () => roundToUnit(raw, settings)
+  if (strategy === builtInRoundingStrategy) return builtIn()
+
+  let threw = false
+  const answer = runStrategy(
+    TIME_ROUNDING_REGISTRY_ID,
+    strategy.id,
+    () => strategy.round(raw, { ...(ctx ?? {}), settings }),
+    () => {
+      threw = true
+      return Number.NaN
+    },
+  )
+  if (threw) return builtIn()
+  return clampToStoredMinutes(TIME_ROUNDING_REGISTRY_ID, strategy.id, answer, builtIn)
+}