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

package/src/modules/staff/lib/timesheets/timeEntryCacheInvalidation.ts

@@ -1,28 +1,29 @@
 import type { AwilixContainer } from 'awilix'
 import {
   canonicalizeResourceTag,
-  deriveResourceFromCommandId,
   invalidateCrudCache,
   type CrudCacheIdentifiers,
 } from '@open-mercato/shared/lib/crud/cache'
 import { createLogger } from '@open-mercato/shared/lib/logger'
-import { staffTimeEntryCommandIds } from '../crud'
+import { staffTimeEntryCrudEvents } from '../crud'
 
 const logger = createLogger('staff').child({ component: 'timesheets-cache' })
 
 /**
  * The resource tag the CRUD list cache stores time-entry payloads under.
  *
- * `makeCrudRoute` derives it from the create action's command id (the route declares
- * no `events` config), which singularizes the command's SECOND segment — so the tag
- * is `staff.timesheet`, NOT the `staff.time_entry` the entity name suggests. Deriving
- * it here through the same shared helpers keeps the flush tag equal to the store tag;
- * a hand-typed literal is how a custom write route silently flushes nothing (#3143,
- * #3711). The literal fallback only guards against a null derivation at runtime — the
- * unit test pins the derived value so drift fails in CI instead of in production.
+ * `resolveResourceAliasesList` in the CRUD factory prefers the route's `events`
+ * config over the create command id, so the tag follows `staff.timesheets.time_entry`
+ * canonicalized (underscores become dots) rather than the command-derived
+ * `staff.timesheet`. Deriving it here from the very object the route passes as its
+ * `events` config keeps the flush tag equal to the store tag; a hand-typed literal is
+ * how a custom write route silently flushes nothing (#3143, #3711). The literal
+ * fallback only guards against a null derivation at runtime — the unit test pins the
+ * derived value so drift fails in CI instead of in production.
  */
 export const staffTimeEntryCacheResource =
-  canonicalizeResourceTag(deriveResourceFromCommandId(staffTimeEntryCommandIds.create)) ?? 'staff.timesheet'
+  canonicalizeResourceTag(`${staffTimeEntryCrudEvents.module}.${staffTimeEntryCrudEvents.entity}`)
+  ?? 'staff.timesheets.time.entry'
 
 /**
  * Flush the cached time-entry collections and record entries after a committed write.

package/src/modules/staff/lib/timesheets/timeEntryDecoration.ts

@@ -0,0 +1,256 @@
+/**
+ * The consulting-suite response fields on a time-entry row.
+ *
+ * This used to be a route-private `hooks.afterList` on
+ * `/api/staff/timesheets/time-entries`, which made it invisible to the extension
+ * system: a third-party enricher for `staff:staff_time_entry` could not see what
+ * the hook had already added, and could not compose with it. The logic lives here so
+ * the declared enricher in `data/enrichers.ts` owns it and the route keeps only its
+ * deprecated wrapper.
+ *
+ * Money is ADDED for a caller holding `staff.timesheets.rates.view` and is absent
+ * for everyone else — `cost`, `currencyCode` and the stored rate override are absent
+ * from the payload rather than blanked, which is the module-wide rule
+ * (`staff/AGENTS.md` → ACL feature IDs).
+ *
+ * **The addition is the whole gate, and that is deliberate.** The list route's
+ * projection does not select `rate_override_amount` or `rate_currency_code` at all,
+ * so an unentitled caller's response carries no money for the same reason a
+ * `SELECT` that never named the column carries none. Stripping money after the fact
+ * only holds while the stripper runs, and this decoration runs as a NON-critical
+ * response enricher: `enricher-runner.ts` leaves the items untouched when one times
+ * out or throws, so a subtractive gate here would fail OPEN under load. Reading the
+ * two columns here, only for an entitled caller, is fail-closed by construction.
+ */
+
+import type { EntityManager } from '@mikro-orm/postgresql'
+import { StaffTimeEntry, StaffTimeEntryTag, StaffTimeProject, StaffTimeTag } from '../../data/entities'
+import { entryAmount } from '../time-tracking/cost'
+
+export type TimeEntryTagSummary = {
+  id: string
+  slug: string
+  label: string
+  color: string | null
+}
+
+export type TimeEntryDecorationScope = {
+  em: EntityManager
+  tenantId: string | null
+  organizationId: string | null
+  canSeeRates: boolean
+  /** Called with a decoration failure; the rows themselves are already correct and scoped. */
+  onError?: (err: unknown) => void
+}
+
+type EntryRow = Record<string, unknown>
+
+const FIELD = {
+  id: ['id', 'id'],
+  roundedMinutes: ['rounded_minutes', 'roundedMinutes'],
+  notes: ['notes', 'notes'],
+  timeProjectId: ['time_project_id', 'timeProjectId'],
+  isBillable: ['is_billable', 'isBillable'],
+  rateOverrideAmount: ['rate_override_amount', 'rateOverrideAmount'],
+  rateCurrencyCode: ['rate_currency_code', 'rateCurrencyCode'],
+  lockedReportId: ['locked_report_id', 'lockedReportId'],
+} as const
+
+function readValue(row: EntryRow, field: readonly [string, string]): unknown {
+  const snake = row[field[0]]
+  if (snake !== undefined) return snake
+  return row[field[1]]
+}
+
+function toNullableString(value: unknown): string | null {
+  return typeof value === 'string' && value.length > 0 ? value : null
+}
+
+function toNullableNumber(value: unknown): number | null {
+  if (value === null || value === undefined) return null
+  const parsed = typeof value === 'number' ? value : Number(value)
+  return Number.isFinite(parsed) ? parsed : null
+}
+
+function toBoolean(value: unknown, fallback: boolean): boolean {
+  if (typeof value === 'boolean') return value
+  if (value === 'true' || value === 1) return true
+  if (value === 'false' || value === 0) return false
+  return fallback
+}
+
+async function loadEntryTags(
+  em: EntityManager,
+  entryIds: string[],
+  tenantId: string,
+  organizationId: string,
+): Promise<Map<string, TimeEntryTagSummary[]>> {
+  const byEntryId = new Map<string, TimeEntryTagSummary[]>()
+  if (entryIds.length === 0) return byEntryId
+  const assignments = await em.find(StaffTimeEntryTag, {
+    timeEntryId: { $in: entryIds },
+    tenantId,
+    organizationId,
+  })
+  if (assignments.length === 0) return byEntryId
+  const tags = await em.find(StaffTimeTag, {
+    id: { $in: Array.from(new Set(assignments.map((row) => row.tagId))) },
+    tenantId,
+    organizationId,
+    deletedAt: null,
+  })
+  const tagById = new Map(tags.map((tag) => [tag.id, tag]))
+  for (const assignment of assignments) {
+    const tag = tagById.get(assignment.tagId)
+    if (!tag) continue
+    const list = byEntryId.get(assignment.timeEntryId) ?? []
+    list.push({ id: tag.id, slug: tag.slug, label: tag.label, color: tag.color ?? null })
+    byEntryId.set(assignment.timeEntryId, list)
+  }
+  return byEntryId
+}
+
+/**
+ * The two money columns the list projection deliberately does not select, read back
+ * only for a caller entitled to them. The rate override keeps the `numeric` string
+ * MikroORM hands back, so the wire format of `rate_override_amount` is the one the
+ * published response schema always documented.
+ */
+type EntryMoney = { rateOverrideAmount: string | number | null; rateCurrencyCode: string | null }
+
+async function loadEntryMoney(
+  em: EntityManager,
+  entryIds: string[],
+  tenantId: string,
+  organizationId: string,
+): Promise<Map<string, EntryMoney>> {
+  const byId = new Map<string, EntryMoney>()
+  if (entryIds.length === 0) return byId
+  const entries = await em.find(StaffTimeEntry, {
+    id: { $in: entryIds },
+    tenantId,
+    organizationId,
+  })
+  for (const entry of entries) {
+    byId.set(entry.id, {
+      rateOverrideAmount: entry.rateOverrideAmount ?? null,
+      rateCurrencyCode: entry.rateCurrencyCode ?? null,
+    })
+  }
+  return byId
+}
+
+type ProjectMoney = { hourlyRate: number | null; currencyCode: string | null }
+
+async function loadProjectMoney(
+  em: EntityManager,
+  projectIds: string[],
+  tenantId: string,
+  organizationId: string,
+): Promise<Map<string, ProjectMoney>> {
+  const byId = new Map<string, ProjectMoney>()
+  if (projectIds.length === 0) return byId
+  const projects = await em.find(StaffTimeProject, {
+    id: { $in: projectIds },
+    tenantId,
+    organizationId,
+    deletedAt: null,
+  })
+  for (const project of projects) {
+    byId.set(project.id, {
+      hourlyRate: toNullableNumber(project.hourlyRate),
+      currencyCode: toNullableString(project.currencyCode),
+    })
+  }
+  return byId
+}
+
+/**
+ * Decorates the given rows IN PLACE. Callers that must not touch their input pass
+ * shallow copies — which is what the enricher does, so its contract stays additive.
+ */
+export async function decorateTimeEntryRows(
+  rows: EntryRow[],
+  scope: TimeEntryDecorationScope,
+): Promise<void> {
+  if (rows.length === 0) return
+
+  const { tenantId, organizationId, canSeeRates } = scope
+  let tagsByEntryId = new Map<string, TimeEntryTagSummary[]>()
+  let moneyByEntryId = new Map<string, EntryMoney>()
+  let moneyByProjectId = new Map<string, ProjectMoney>()
+
+  if (tenantId && organizationId) {
+    try {
+      const em = scope.em.fork()
+      const entryIds = rows
+        .map((row) => readValue(row, FIELD.id))
+        .filter((value): value is string => typeof value === 'string')
+      tagsByEntryId = await loadEntryTags(em, entryIds, tenantId, organizationId)
+      if (canSeeRates) {
+        moneyByEntryId = await loadEntryMoney(em, entryIds, tenantId, organizationId)
+        const projectIds = Array.from(
+          new Set(
+            rows
+              .map((row) => readValue(row, FIELD.timeProjectId))
+              .filter((value): value is string => typeof value === 'string'),
+          ),
+        )
+        moneyByProjectId = await loadProjectMoney(em, projectIds, tenantId, organizationId)
+      }
+    } catch (err) {
+      // A decoration failure must not fail the list; the entry rows themselves are
+      // already correct and scoped.
+      scope.onError?.(err)
+    }
+  }
+
+  for (const row of rows) {
+    const entryId = readValue(row, FIELD.id)
+    const lockedReportId = toNullableString(readValue(row, FIELD.lockedReportId))
+    const roundedMinutes = toNullableNumber(readValue(row, FIELD.roundedMinutes))
+    const isBillable = toBoolean(readValue(row, FIELD.isBillable), true)
+
+    // The published alias: same value, second name, both keys returned.
+    row.description = toNullableString(readValue(row, FIELD.notes))
+    row.roundedMinutes = roundedMinutes
+    row.isLocked = lockedReportId !== null
+    row.lockedReportId = lockedReportId
+    row.tags = typeof entryId === 'string' ? tagsByEntryId.get(entryId) ?? [] : []
+
+    if (!canSeeRates) {
+      // Belt and braces: the projection selects neither column, so there is
+      // normally nothing here to remove. A caller that assembled the row itself
+      // still loses the money keys rather than passing them through.
+      delete row[FIELD.rateOverrideAmount[0]]
+      delete row[FIELD.rateOverrideAmount[1]]
+      delete row[FIELD.rateCurrencyCode[0]]
+      delete row[FIELD.rateCurrencyCode[1]]
+      continue
+    }
+
+    const projectId = readValue(row, FIELD.timeProjectId)
+    const money = typeof projectId === 'string' ? moneyByProjectId.get(projectId) : undefined
+    const stored = typeof entryId === 'string' ? moneyByEntryId.get(entryId) : undefined
+    const rateOverrideAmount = stored
+      ? stored.rateOverrideAmount
+      : (readValue(row, FIELD.rateOverrideAmount) as string | number | null | undefined) ?? null
+    const rateCurrencyCode = stored
+      ? stored.rateCurrencyCode
+      : toNullableString(readValue(row, FIELD.rateCurrencyCode))
+
+    row[FIELD.rateOverrideAmount[0]] = rateOverrideAmount
+    row[FIELD.rateCurrencyCode[0]] = rateCurrencyCode
+    row.currencyCode = toNullableString(rateCurrencyCode) ?? money?.currencyCode ?? null
+    // A non-billable entry has no price at all — `null`, never `0`, which would
+    // read as free work rather than work that is out of scope.
+    row.cost = entryAmount(
+      {
+        isBillable,
+        roundedMinutes: roundedMinutes ?? 0,
+        rateOverrideAmount: toNullableNumber(rateOverrideAmount),
+      },
+      { hourlyRate: money?.hourlyRate ?? null },
+    )
+  }
+}

package/src/modules/staff/lib/timesheets-projects/budgetBurn.ts

@@ -0,0 +1,60 @@
+export type ProjectBudgetKind = 'none' | 'hours' | 'amount'
+
+export type BudgetBurnTone = 'accent' | 'warning' | 'destructive'
+
+export type ProjectBudgetBurn = {
+  kind: 'hours' | 'amount'
+  budgetValue: number
+  usedValue: number
+  percent: number
+  barPercent: number
+  tone: BudgetBurnTone
+}
+
+export type BudgetBurnInput = {
+  kind: ProjectBudgetKind | null | undefined
+  budgetValue: number | null | undefined
+  warnAtPercent: number | null | undefined
+  totalMinutes: number
+  cost: number | null
+}
+
+export const DEFAULT_BUDGET_WARN_AT_PERCENT = 80
+
+function clampPercent(value: number): number {
+  if (!Number.isFinite(value) || value < 0) return 0
+  return Math.min(100, value)
+}
+
+export function resolveBudgetWarnAtPercent(warnAtPercent: number | null | undefined): number {
+  if (typeof warnAtPercent !== 'number' || !Number.isFinite(warnAtPercent)) {
+    return DEFAULT_BUDGET_WARN_AT_PERCENT
+  }
+  if (warnAtPercent <= 0 || warnAtPercent > 100) return DEFAULT_BUDGET_WARN_AT_PERCENT
+  return warnAtPercent
+}
+
+export function computeBudgetBurn(input: BudgetBurnInput): ProjectBudgetBurn | null {
+  const kind = input.kind
+  if (kind !== 'hours' && kind !== 'amount') return null
+  const budgetValue = typeof input.budgetValue === 'number' ? input.budgetValue : null
+  if (budgetValue === null || !Number.isFinite(budgetValue) || budgetValue <= 0) return null
+
+  const usedValue =
+    kind === 'hours'
+      ? Math.max(0, input.totalMinutes) / 60
+      : Math.max(0, input.cost ?? 0)
+
+  const percent = Math.round((usedValue / budgetValue) * 100)
+  const warnAt = resolveBudgetWarnAtPercent(input.warnAtPercent)
+  const tone: BudgetBurnTone = percent >= 100 ? 'destructive' : percent >= warnAt ? 'warning' : 'accent'
+
+  return {
+    kind,
+    budgetValue,
+    usedValue,
+    percent,
+    barPercent: clampPercent(percent),
+    tone,
+  }
+}

package/src/modules/staff/lib/timesheets-projects/budgetThreshold.ts

@@ -0,0 +1,135 @@
+import {
+  computeBudgetBurn,
+  resolveBudgetWarnAtPercent,
+  type ProjectBudgetKind,
+} from './budgetBurn'
+
+export const FULL_BUDGET_PERCENT = 100
+
+/**
+ * Outcome of comparing a project's usage against its budget.
+ *
+ * - `disabled` — the project has no measurable budget at all (`budget_kind: 'none'`,
+ *   a null budget, or a budget of zero or less). Never notifies, and clears any
+ *   marker left behind by a budget that has since been switched off.
+ * - `unmeasurable` — the budget is an amount budget but the project cannot price its
+ *   hours (no rate anywhere, or no currency). Degrades quietly: no notification and
+ *   the marker is left untouched, because this is an inability to measure rather
+ *   than usage genuinely dropping.
+ * - `evaluated` — usage was compared against the thresholds.
+ */
+export type BudgetThresholdStatus = 'disabled' | 'unmeasurable' | 'evaluated'
+
+export type BudgetThresholdInput = {
+  budgetKind: ProjectBudgetKind | null | undefined
+  budgetValue: number | null | undefined
+  budgetWarnAtPercent: number | null | undefined
+  budgetAlertedAtPercent: number | null | undefined
+  totalMinutes: number
+  cost: number | null
+  currencyCode?: string | null
+}
+
+export type BudgetThresholdEvaluation = {
+  status: BudgetThresholdStatus
+  kind: 'hours' | 'amount' | null
+  budgetValue: number | null
+  usedValue: number | null
+  percent: number | null
+  /** The threshold to announce now, or null when nothing new was crossed. */
+  crossedThresholdPercent: number | null
+  /** The value `budget_alerted_at_percent` should hold after this write. */
+  nextAlertedAtPercent: number | null
+  shouldPersistAlertedAt: boolean
+}
+
+function normalizeAlertedAtPercent(value: number | null | undefined): number | null {
+  if (typeof value !== 'number' || !Number.isFinite(value)) return null
+  const rounded = Math.round(value)
+  if (rounded <= 0) return null
+  return Math.min(rounded, FULL_BUDGET_PERCENT)
+}
+
+function hasBillingCurrency(currencyCode: string | null | undefined): boolean {
+  return typeof currencyCode === 'string' && currencyCode.trim().length > 0
+}
+
+/**
+ * Decides whether a budget threshold notification is due for a project.
+ *
+ * Two thresholds exist: the project's `budget_warn_at_percent` (80 by default) and
+ * 100. A notification fires only on an UPWARD move into a threshold band that
+ * `budget_alerted_at_percent` has not already recorded, so repeated writes at the
+ * same usage level stay silent. When one write jumps past both thresholds, only the
+ * highest one is announced — a single "budget exhausted" alert beats two alerts
+ * describing the same write.
+ *
+ * The marker follows usage back down: when usage falls under the band it was raised
+ * for (an entry deleted or corrected), the marker is lowered to the band usage is
+ * actually in — null when it is under every threshold — so a later re-crossing
+ * notifies again. Moving down never notifies.
+ *
+ * Percent is taken from `computeBudgetBurn` so the notification and the burn bar on
+ * screens 3 and 4 can never disagree about whether the project is at 80%.
+ */
+export function evaluateBudgetThreshold(input: BudgetThresholdInput): BudgetThresholdEvaluation {
+  const alertedAtPercent = normalizeAlertedAtPercent(input.budgetAlertedAtPercent)
+
+  const burn = computeBudgetBurn({
+    kind: input.budgetKind,
+    budgetValue: input.budgetValue,
+    warnAtPercent: input.budgetWarnAtPercent,
+    totalMinutes: input.totalMinutes,
+    cost: input.cost,
+  })
+
+  if (!burn) {
+    return {
+      status: 'disabled',
+      kind: null,
+      budgetValue: null,
+      usedValue: null,
+      percent: null,
+      crossedThresholdPercent: null,
+      nextAlertedAtPercent: null,
+      shouldPersistAlertedAt: alertedAtPercent !== null,
+    }
+  }
+
+  if (burn.kind === 'amount' && (input.cost === null || input.cost === undefined || !hasBillingCurrency(input.currencyCode))) {
+    return {
+      status: 'unmeasurable',
+      kind: burn.kind,
+      budgetValue: burn.budgetValue,
+      usedValue: null,
+      percent: null,
+      crossedThresholdPercent: null,
+      nextAlertedAtPercent: alertedAtPercent,
+      shouldPersistAlertedAt: false,
+    }
+  }
+
+  const warnAtPercent = resolveBudgetWarnAtPercent(input.budgetWarnAtPercent)
+  const reachedThresholdPercent =
+    burn.percent >= FULL_BUDGET_PERCENT
+      ? FULL_BUDGET_PERCENT
+      : burn.percent >= warnAtPercent
+        ? warnAtPercent
+        : null
+
+  const crossedThresholdPercent =
+    reachedThresholdPercent !== null && (alertedAtPercent === null || reachedThresholdPercent > alertedAtPercent)
+      ? reachedThresholdPercent
+      : null
+
+  return {
+    status: 'evaluated',
+    kind: burn.kind,
+    budgetValue: burn.budgetValue,
+    usedValue: burn.usedValue,
+    percent: burn.percent,
+    crossedThresholdPercent,
+    nextAlertedAtPercent: reachedThresholdPercent,
+    shouldPersistAlertedAt: reachedThresholdPercent !== alertedAtPercent,
+  }
+}

package/src/modules/staff/lib/timesheets-projects/budgetThresholdState.ts

@@ -0,0 +1,137 @@
+import type { EntityManager } from '@mikro-orm/postgresql'
+import type { ProjectBudgetKind } from './budgetBurn'
+
+export type TimeProjectBudgetState = {
+  timeProjectId: string
+  name: string
+  ownerUserId: string | null
+  budgetKind: ProjectBudgetKind
+  budgetValue: number | null
+  budgetWarnAtPercent: number | null
+  budgetAlertedAtPercent: number | null
+  hourlyRate: number | null
+  currencyCode: string | null
+}
+
+export type TimeProjectBudgetScope = {
+  em: EntityManager
+  tenantId: string
+  organizationId: string
+}
+
+type BudgetStateRow = {
+  time_project_id: string
+  name: string | null
+  owner_user_id: string | null
+  budget_kind: string | null
+  budget_value: string | number | null
+  budget_warn_at_percent: string | number | null
+  budget_alerted_at_percent: string | number | null
+  hourly_rate: string | number | null
+  currency_code: string | null
+}
+
+const BUDGET_KINDS: readonly ProjectBudgetKind[] = ['none', 'hours', 'amount']
+
+function toNullableNumber(value: string | number | null | undefined): number | null {
+  if (value === null || value === undefined) return null
+  const parsed = typeof value === 'number' ? value : Number(value)
+  return Number.isFinite(parsed) ? parsed : null
+}
+
+function toBudgetKind(value: string | null | undefined): ProjectBudgetKind {
+  return BUDGET_KINDS.find((kind) => kind === value) ?? 'none'
+}
+
+/**
+ * Loads the budget state of the project a time entry belongs to, in one scoped
+ * round trip. The entry is looked up without a `deleted_at` filter on purpose: a
+ * delete is exactly the write that can push usage back under a threshold, and the
+ * soft-deleted row is still what tells us which project to re-evaluate.
+ */
+export async function loadTimeProjectBudgetStateForEntry(
+  scope: TimeProjectBudgetScope & { timeEntryId: string },
+): Promise<TimeProjectBudgetState | null> {
+  const sql = `
+    SELECT
+      project.id AS time_project_id,
+      project.name AS name,
+      project.owner_user_id AS owner_user_id,
+      project.budget_kind AS budget_kind,
+      project.budget_value AS budget_value,
+      project.budget_warn_at_percent AS budget_warn_at_percent,
+      project.budget_alerted_at_percent AS budget_alerted_at_percent,
+      project.hourly_rate AS hourly_rate,
+      project.currency_code AS currency_code
+    FROM staff_time_entries entry
+    JOIN staff_time_projects project
+      ON project.id = entry.time_project_id
+      AND project.tenant_id = entry.tenant_id
+      AND project.organization_id = entry.organization_id
+      AND project.deleted_at IS NULL
+    WHERE entry.id = ?
+      AND entry.tenant_id = ?
+      AND entry.organization_id = ?
+    LIMIT 1
+  `
+
+  const result = await scope.em.getConnection().execute(sql, [
+    scope.timeEntryId,
+    scope.tenantId,
+    scope.organizationId,
+  ])
+  const rows = (Array.isArray(result) ? result : []) as BudgetStateRow[]
+  const row = rows[0]
+  if (!row) return null
+
+  return {
+    timeProjectId: row.time_project_id,
+    name: row.name ?? '',
+    ownerUserId: row.owner_user_id ?? null,
+    budgetKind: toBudgetKind(row.budget_kind),
+    budgetValue: toNullableNumber(row.budget_value),
+    budgetWarnAtPercent: toNullableNumber(row.budget_warn_at_percent),
+    budgetAlertedAtPercent: toNullableNumber(row.budget_alerted_at_percent),
+    hourlyRate: toNullableNumber(row.hourly_rate),
+    currencyCode: row.currency_code ?? null,
+  }
+}
+
+/**
+ * Compare-and-swap on `budget_alerted_at_percent`, the column that makes the budget
+ * notification idempotent. Returns true only for the caller that actually moved the
+ * marker, so two concurrent entry writes crossing the same threshold produce one
+ * notification rather than two.
+ *
+ * `updated_at` is deliberately left alone: the marker is platform bookkeeping, not a
+ * user edit, and bumping the optimistic-lock version here would make an unrelated
+ * open project form fail to save with a spurious 409.
+ */
+export async function claimBudgetThresholdAlert(
+  scope: TimeProjectBudgetScope & {
+    timeProjectId: string
+    expectedAlertedAtPercent: number | null
+    nextAlertedAtPercent: number | null
+  },
+): Promise<boolean> {
+  const sql = `
+    UPDATE staff_time_projects
+    SET budget_alerted_at_percent = ?
+    WHERE id = ?
+      AND tenant_id = ?
+      AND organization_id = ?
+      AND deleted_at IS NULL
+      AND budget_alerted_at_percent IS NOT DISTINCT FROM ?
+    RETURNING id
+  `
+
+  const result = await scope.em.getConnection().execute(sql, [
+    scope.nextAlertedAtPercent,
+    scope.timeProjectId,
+    scope.tenantId,
+    scope.organizationId,
+    scope.expectedAlertedAtPercent,
+  ])
+  const rows = (Array.isArray(result) ? result : []) as Array<{ id: string }>
+  return rows.length > 0
+}