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

package/src/modules/staff/lib/crud.ts

@@ -11,6 +11,11 @@ import type {
   StaffTimeEntry,
   StaffTimeProject,
   StaffTimeProjectMember,
+  StaffTimeReport,
+  StaffTimeTag,
+  StaffTimeTask,
+  StaffTimeTaskComment,
+  StaffTimeTaskStatus,
 } from '../data/entities'
 
 function buildCrudEvents<TEntity>(entity: string): CrudEventsConfig<TEntity> {
@@ -38,9 +43,10 @@ export const staffTeamMemberJobHistoryCrudEvents = buildCrudEvents<StaffTeamMemb
 // Timesheets
 /**
  * Command ids the time-entries CRUD route registers. Exported so the route and the
- * cache-invalidation helper share one string: `makeCrudRoute` derives the CRUD cache
- * resource tag from the create id, so a second copy of it drifting apart would leave
- * custom write routes flushing a tag nothing is stored under (#4970).
+ * custom write routes that drive the same commands share one string instead of
+ * re-typing it (#4970). The CRUD cache resource tag no longer follows these ids —
+ * the route declares an `events` config, which the factory prefers; see
+ * `lib/timesheets/timeEntryCacheInvalidation.ts`.
  */
 export const staffTimeEntryCommandIds = {
   create: 'staff.timesheets.time_entries.create',
@@ -51,3 +57,8 @@ export const staffTimeEntryCommandIds = {
 export const staffTimeEntryCrudEvents = buildCrudEvents<StaffTimeEntry>('timesheets.time_entry')
 export const staffTimeProjectCrudEvents = buildCrudEvents<StaffTimeProject>('timesheets.time_project')
 export const staffTimeProjectMemberCrudEvents = buildCrudEvents<StaffTimeProjectMember>('timesheets.time_project_member')
+export const staffTimeTaskCrudEvents = buildCrudEvents<StaffTimeTask>('timesheets.time_task')
+export const staffTimeTaskStatusCrudEvents = buildCrudEvents<StaffTimeTaskStatus>('timesheets.time_task_status')
+export const staffTimeTaskCommentCrudEvents = buildCrudEvents<StaffTimeTaskComment>('timesheets.time_task_comment')
+export const staffTimeTagCrudEvents = buildCrudEvents<StaffTimeTag>('timesheets.time_tag')
+export const staffTimeReportCrudEvents = buildCrudEvents<StaffTimeReport>('timesheets.time_report')

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

@@ -0,0 +1,155 @@
+import type { EntityManager } from '@mikro-orm/postgresql'
+import { authorizeFeatures } from '@open-mercato/shared/security/featurePolicy'
+import { findWithDecryption, findOneWithDecryption } from '@open-mercato/shared/lib/encryption/find'
+import { StaffTeamMember, StaffTimeProjectMember } from '../../data/entities'
+import { DEFAULT_ASSIGNMENT_GRACE_DAYS, MAX_ASSIGNMENT_GRACE_DAYS } from './settings'
+
+export const MANAGE_PROJECTS_FEATURE = 'staff.timesheets.projects.manage'
+
+export type ProjectAccessContext = {
+  em: EntityManager
+  userId?: string | null
+  tenantId?: string | null
+  organizationId?: string | null
+  userFeatures?: readonly string[]
+  /**
+   * The manage-all decision, resolved by the caller through `resolveFeatureAccess`.
+   * Preferred over `userFeatures`: a grant array cannot distinguish "denied" from
+   * "could not ask", and the difference is a silently downgraded manager.
+   */
+  canManageAll?: boolean
+  /**
+   * Resolved `access.assignmentGraceDays` setting. Passed in rather than read
+   * here so the resolver stays independent of `ModuleConfigService`; callers
+   * that already read the tenant settings avoid a second lookup.
+   */
+  assignmentGraceDays?: number | null
+  /** Injectable clock so the assignment window is testable; defaults to now. */
+  now?: Date
+}
+
+export type ProjectAccess = {
+  canManageAll: boolean
+  projectIds: string[]
+  staffMemberId: string | null
+}
+
+const DENIED: ProjectAccess = { canManageAll: false, projectIds: [], staffMemberId: null }
+
+const MS_PER_DAY = 86_400_000
+const ISO_DATE_PREFIX = /^(\d{4})-(\d{2})-(\d{2})/
+
+export function normalizeAssignmentGraceDays(value: unknown): number {
+  if (typeof value !== 'number' || !Number.isInteger(value)) return DEFAULT_ASSIGNMENT_GRACE_DAYS
+  if (value < 0 || value > MAX_ASSIGNMENT_GRACE_DAYS) return DEFAULT_ASSIGNMENT_GRACE_DAYS
+  return value
+}
+
+/**
+ * `assigned_start_date` / `assigned_end_date` are `date` columns, so both bounds
+ * are compared as whole days rather than timestamps. Date instances are read
+ * through their local calendar fields because the postgres driver materialises a
+ * `date` as local midnight, and "today" likewise means the server's local day.
+ */
+function toDayIndex(value: unknown): number | null {
+  if (value == null) return null
+  if (value instanceof Date) {
+    if (Number.isNaN(value.getTime())) return null
+    return Date.UTC(value.getFullYear(), value.getMonth(), value.getDate()) / MS_PER_DAY
+  }
+  if (typeof value === 'string') {
+    const match = ISO_DATE_PREFIX.exec(value.trim())
+    if (!match) return null
+    return Date.UTC(Number(match[1]), Number(match[2]) - 1, Number(match[3])) / MS_PER_DAY
+  }
+  return null
+}
+
+/**
+ * A membership only grants access inside its assignment window: from
+ * `assigned_start_date` until `assigned_end_date` plus the tenant's grace days.
+ * A null end date is open-ended and never expires.
+ */
+export function isWithinAssignmentWindow(
+  membership: Pick<StaffTimeProjectMember, 'assignedStartDate' | 'assignedEndDate'>,
+  todayIndex: number,
+  graceDays: number,
+): boolean {
+  if (membership.assignedStartDate != null) {
+    const startIndex = toDayIndex(membership.assignedStartDate)
+    if (startIndex === null || todayIndex < startIndex) return false
+  }
+  if (membership.assignedEndDate == null) return true
+  const endIndex = toDayIndex(membership.assignedEndDate)
+  if (endIndex === null) return false
+  return todayIndex <= endIndex + graceDays
+}
+
+export async function resolveProjectAccess(ctx: ProjectAccessContext): Promise<ProjectAccess> {
+  const tenantId = ctx.tenantId ?? null
+  const organizationId = ctx.organizationId ?? null
+  const userId = ctx.userId ?? null
+  const grantedFeatures = ctx.userFeatures ?? []
+
+  // The decision is the caller's to make, through `resolveFeatureAccess`, which
+  // asks the RBAC service once and fails closed loudly. Deriving it here from a
+  // grant array is what let a failed lookup pass as "no permission": the array
+  // came back empty, `canManageAll` went false, and a manager silently dropped to
+  // their own memberships while the KPI endpoint — asking the service directly —
+  // kept reporting the full portfolio.
+  //
+  // The array path remains for callers that have not been migrated, but it cannot
+  // distinguish "denied" from "could not ask", so it is deprecated.
+  const canManageAll =
+    ctx.canManageAll ??
+    authorizeFeatures([MANAGE_PROJECTS_FEATURE], {
+      grantedFeatures,
+      scopeAllowed: Boolean(tenantId) && Boolean(organizationId),
+    })
+
+  if (!tenantId || !organizationId || !userId) {
+    return canManageAll ? { ...DENIED, canManageAll } : { ...DENIED }
+  }
+
+  const scope = { tenantId, organizationId }
+  const staffMember = await findOneWithDecryption(
+    ctx.em,
+    StaffTeamMember,
+    { userId, tenantId, organizationId, deletedAt: null },
+    {},
+    scope,
+  )
+  const staffMemberId = staffMember?.id ?? null
+
+  if (canManageAll) return { canManageAll: true, projectIds: [], staffMemberId }
+  if (!staffMemberId) return { ...DENIED }
+
+  const memberships = await findWithDecryption(
+    ctx.em,
+    StaffTimeProjectMember,
+    { staffMemberId, tenantId, organizationId, status: 'active', deletedAt: null },
+    {},
+    scope,
+  )
+
+  const graceDays = normalizeAssignmentGraceDays(ctx.assignmentGraceDays)
+  const todayIndex = toDayIndex(ctx.now ?? new Date())
+
+  const projectIds: string[] = []
+  const seen = new Set<string>()
+  for (const membership of memberships) {
+    const projectId = membership.timeProjectId
+    if (!projectId || seen.has(projectId)) continue
+    if (todayIndex === null || !isWithinAssignmentWindow(membership, todayIndex, graceDays)) continue
+    seen.add(projectId)
+    projectIds.push(projectId)
+  }
+
+  return { canManageAll: false, projectIds, staffMemberId }
+}
+
+export function assertProjectAccess(access: ProjectAccess, projectId?: string | null): boolean {
+  if (access.canManageAll) return true
+  if (!projectId) return false
+  return access.projectIds.includes(projectId)
+}

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

@@ -0,0 +1,68 @@
+/**
+ * EP-34 — the billability resolver chain.
+ *
+ * The rule `commands/timesheets-entries.ts` documented in prose — an explicit
+ * value wins, then the project's own default, then the tenant setting — is now
+ * the built-in resolver `staff.time_tracking.billability.project_then_tenant`.
+ * Contributed resolvers are asked first, in descending priority, and the first
+ * non-null answer wins; a resolver that returns `null` abstains and the chain
+ * carries on, so an unopinionated contribution cannot change an entry.
+ *
+ * As everywhere else in this group, a contribution is consulted only when the
+ * caller supplies a complete tenant + organization scope.
+ */
+
+import { extensionPoints } from '@open-mercato/core/modules/staff/extension-points'
+import { createStrategyRegistry, BUILT_IN_STRATEGY_PRIORITY } from './registries/registry'
+import { tryStrategy } from './registries/invoke'
+import { hasResolverScope, type ScopedResolverContext } from './registries/scope'
+import type { TimeTrackingSettings } from './settings'
+
+export type BillabilityContext = ScopedResolverContext & {
+  requested?: boolean | null
+  project?: { id?: string | null; billableByDefault?: boolean | null } | null
+  task?: { id?: string | null } | null
+  staffMemberId?: string | null
+  date?: string | null
+  settings: TimeTrackingSettings
+}
+
+export type BillabilityResolver = {
+  id: string
+  priority?: number
+  resolve(ctx: BillabilityContext): boolean | null
+}
+
+export const BILLABILITY_REGISTRY_ID = extensionPoints.hosts.timeBillabilityRegistry.spotId
+
+export const BUILT_IN_BILLABILITY_RESOLVER_ID = 'staff.time_tracking.billability.project_then_tenant'
+
+const registry = createStrategyRegistry<BillabilityResolver>(BILLABILITY_REGISTRY_ID)
+
+export function registerBillabilityResolver(resolver: BillabilityResolver): () => void {
+  return registry.register(resolver)
+}
+
+export function listBillabilityResolvers(): BillabilityResolver[] {
+  return registry.list()
+}
+
+export function getBillabilityResolver(id: string | null | undefined): BillabilityResolver | null {
+  return registry.get(id)
+}
+
+const builtInBillabilityResolver: BillabilityResolver = registry.registerBuiltIn({
+  id: BUILT_IN_BILLABILITY_RESOLVER_ID,
+  priority: BUILT_IN_STRATEGY_PRIORITY,
+  resolve: (ctx) => ctx.requested ?? ctx.project?.billableByDefault ?? ctx.settings.defaults.billable,
+})
+
+export function resolveBillability(ctx: BillabilityContext): boolean {
+  const scoped = hasResolverScope(ctx)
+  for (const resolver of registry.list()) {
+    if (!scoped && resolver.id !== BUILT_IN_BILLABILITY_RESOLVER_ID) continue
+    const answer = tryStrategy(BILLABILITY_REGISTRY_ID, resolver.id, () => resolver.resolve(ctx))
+    if (typeof answer === 'boolean') return answer
+  }
+  return ctx.settings.defaults.billable
+}

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

@@ -0,0 +1,124 @@
+/**
+ * EP-40 — the capacity / target provider.
+ *
+ * The timesheet's "target" is one flat number today: `targets.dailyHours` from
+ * the tenant settings, applied to every working day of every person. The
+ * built-in `staff.time_tracking.capacity.flat_daily_hours` reproduces exactly
+ * that, including its two edge cases — a `null` setting means "no target", and a
+ * day the caller did not mark as working contributes nothing.
+ *
+ * A contributed provider answers per day instead, which is what a contract-hours
+ * or leave-aware capacity model needs. It is consulted only when the caller
+ * supplies a complete tenant + organization scope.
+ */
+
+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 type CapacityDateRange = {
+  /** `yyyy-mm-dd`, inclusive. */
+  from: string
+  /** `yyyy-mm-dd`, inclusive. */
+  to: string
+  /** The days the caller counts as working; the built-in targets only these. */
+  workingDays: readonly string[]
+}
+
+export type CapacityContext = ScopedResolverContext & {
+  /** The tenant's `targets.dailyHours`; `null` means the tenant set no target. */
+  dailyHours: number | null
+}
+
+export type CapacityResult = {
+  /** Target minutes per `yyyy-mm-dd`, for the working days that carry one. */
+  targetMinutesByDate: Record<string, number>
+  /** Sum of `targetMinutesByDate`, or `null` when the tenant set no target. */
+  totalTargetMinutes: number | null
+}
+
+export type CapacityProvider = {
+  id: string
+  priority?: number
+  resolve(
+    staffMemberId: string | null,
+    dateRange: CapacityDateRange,
+    ctx: CapacityContext,
+  ): CapacityResult
+}
+
+export const CAPACITY_PROVIDER_REGISTRY_ID = extensionPoints.hosts.capacityProviderRegistry.spotId
+
+export const BUILT_IN_CAPACITY_PROVIDER_ID = 'staff.time_tracking.capacity.flat_daily_hours'
+
+const registry = createStrategyRegistry<CapacityProvider>(CAPACITY_PROVIDER_REGISTRY_ID)
+
+export function registerCapacityProvider(provider: CapacityProvider): () => void {
+  return registry.register(provider)
+}
+
+export function listCapacityProviders(): CapacityProvider[] {
+  return registry.list()
+}
+
+export function getCapacityProvider(id: string | null | undefined): CapacityProvider | null {
+  return registry.get(id)
+}
+
+const builtInCapacityProvider: CapacityProvider = registry.registerBuiltIn({
+  id: BUILT_IN_CAPACITY_PROVIDER_ID,
+  priority: BUILT_IN_STRATEGY_PRIORITY,
+  resolve: (_staffMemberId, dateRange, ctx) => {
+    const dailyHours = ctx.dailyHours
+    if (dailyHours === null || !Number.isFinite(dailyHours)) {
+      return { targetMinutesByDate: {}, totalTargetMinutes: null }
+    }
+    const dailyMinutes = Math.round(dailyHours * 60)
+    const targetMinutesByDate: Record<string, number> = {}
+    for (const date of dateRange.workingDays ?? []) targetMinutesByDate[date] = dailyMinutes
+    return {
+      targetMinutesByDate,
+      totalTargetMinutes: dailyMinutes * (dateRange.workingDays?.length ?? 0),
+    }
+  },
+})
+
+export function resolveCapacityProvider(ctx?: ScopedResolverContext | null): CapacityProvider {
+  return selectScopedStrategy(registry.list(), builtInCapacityProvider, ctx)
+}
+
+function isCapacityResult(value: unknown): value is CapacityResult {
+  if (!value || typeof value !== 'object') return false
+  const candidate = value as { targetMinutesByDate?: unknown; totalTargetMinutes?: unknown }
+  if (!candidate.targetMinutesByDate || typeof candidate.targetMinutesByDate !== 'object') return false
+  const total = candidate.totalTargetMinutes
+  if (total !== null && (typeof total !== 'number' || !Number.isFinite(total))) return false
+  return Object.values(candidate.targetMinutesByDate as Record<string, unknown>).every(
+    (minutes) => typeof minutes === 'number' && Number.isFinite(minutes),
+  )
+}
+
+/**
+ * The targets the timesheet renders and compares logged minutes against. A provider
+ * that throws, or that answers with something the caller cannot subtract from, falls
+ * back to the flat daily target the module shipped — a timesheet showing the wrong
+ * target reads as the person being behind, which is worse than showing the default.
+ */
+export function resolveTimesheetCapacity(
+  staffMemberId: string | null,
+  dateRange: CapacityDateRange,
+  ctx: CapacityContext,
+): CapacityResult {
+  const provider = resolveCapacityProvider(ctx)
+  const builtIn = () => builtInCapacityProvider.resolve(staffMemberId, dateRange, ctx)
+  if (provider === builtInCapacityProvider) return builtIn()
+
+  const answer = runStrategy(
+    CAPACITY_PROVIDER_REGISTRY_ID,
+    provider.id,
+    () => provider.resolve(staffMemberId, dateRange, ctx) as unknown,
+    () => null,
+  )
+  return isCapacityResult(answer) ? answer : builtIn()
+}

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

@@ -0,0 +1,26 @@
+import { z } from 'zod'
+
+/**
+ * Shared building blocks for the `propsSchema` every replaceable time-tracking
+ * component publishes (EP-31).
+ *
+ * The schema is the contract a replacement must satisfy: `useRegisteredComponent`
+ * parses the resolved props against it in development and falls back to the
+ * original component when they do not match, so a schema that accepts anything
+ * would let a broken replacement render instead of being caught. Scalars are
+ * therefore described exactly; callbacks and React nodes, which zod cannot
+ * describe structurally, are narrowed to the one runtime check that matters.
+ */
+
+export const callbackProp = <TCallback>() =>
+  z.custom<TCallback>((value) => typeof value === 'function', {
+    message: '[internal] expected a function prop',
+  })
+
+export const optionalCallbackProp = <TCallback>() =>
+  z.custom<TCallback | undefined>(
+    (value) => value === undefined || typeof value === 'function',
+    { message: '[internal] expected a function prop or undefined' },
+  )
+
+export const opaqueProp = <TValue>() => z.custom<TValue>(() => true)

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

@@ -0,0 +1,144 @@
+/**
+ * EP-33 — the rate resolver chain.
+ *
+ * `applicableRate` is still the single place an hourly rate is chosen, and
+ * `entryAmount` still the single place an amount is produced (D-7). What changed
+ * is that the override → project-rate chain now lives in the built-in resolver
+ * `staff.time_tracking.rate.entry_override_then_project`, registered at module
+ * load, instead of being spelled inline. Contributed resolvers are consulted in
+ * descending priority ahead of it, but only when the caller supplies a complete
+ * tenant + organization scope; with no contribution — or with none of them
+ * answering — the built-in decides, so the number is the one this file always
+ * produced.
+ */
+
+import { extensionPoints } from '@open-mercato/core/modules/staff/extension-points'
+import { createStrategyRegistry, BUILT_IN_STRATEGY_PRIORITY } from './registries/registry'
+import { tryStrategy } from './registries/invoke'
+import { hasResolverScope, type ScopedResolverContext } from './registries/scope'
+
+export type CostEntry = {
+  isBillable: boolean
+  roundedMinutes: number
+  rateOverrideAmount?: number | null
+}
+
+export type CostProject = {
+  hourlyRate?: number | null
+}
+
+/**
+ * Everything a rate resolver may reason about. Only `entry` and `project` are
+ * populated by the module's own call sites; the remaining fields exist so a
+ * contributed resolver can key off seniority, task type, customer contract or an
+ * effective date without the call site having to invent its own context shape.
+ */
+export type TimeRateContext = ScopedResolverContext & {
+  entry?: Pick<CostEntry, 'rateOverrideAmount'> | null
+  project?: CostProject | null
+  task?: { id?: string | null; timeProjectId?: string | null } | null
+  staffMember?: { id?: string | null } | null
+  role?: { id?: string | null; name?: string | null } | null
+  customer?: { id?: string | null } | null
+  date?: string | null
+}
+
+export type TimeRateResolver = {
+  id: string
+  priority?: number
+  resolve(ctx: TimeRateContext): number | null
+}
+
+export const TIME_RATE_REGISTRY_ID = extensionPoints.hosts.timeRateRegistry.spotId
+
+export const BUILT_IN_TIME_RATE_RESOLVER_ID = 'staff.time_tracking.rate.entry_override_then_project'
+
+const registry = createStrategyRegistry<TimeRateResolver>(TIME_RATE_REGISTRY_ID)
+
+export function registerTimeRateResolver(resolver: TimeRateResolver): () => void {
+  return registry.register(resolver)
+}
+
+export function listTimeRateResolvers(): TimeRateResolver[] {
+  return registry.list()
+}
+
+export function getTimeRateResolver(id: string | null | undefined): TimeRateResolver | null {
+  return registry.get(id)
+}
+
+export function round2(value: number): number {
+  if (!Number.isFinite(value)) return 0
+  const sign = value < 0 ? -1 : 1
+  const magnitude = Math.abs(value)
+  const shifted = Number(`${magnitude}e2`)
+  if (!Number.isFinite(shifted)) return sign * (Math.round(magnitude * 100) / 100)
+  const rounded = Math.round(shifted)
+  const restored = Number(`${rounded}e-2`)
+  if (!Number.isFinite(restored)) return sign * (rounded / 100)
+  return sign * restored
+}
+
+function toCents(amount: number): number {
+  return Math.round(round2(amount) * 100)
+}
+
+function builtInRate(ctx: TimeRateContext): number | null {
+  const override = ctx.entry?.rateOverrideAmount
+  if (override !== null && override !== undefined && Number.isFinite(override)) return override
+  const projectRate = ctx.project?.hourlyRate
+  if (projectRate !== null && projectRate !== undefined && Number.isFinite(projectRate)) return projectRate
+  return null
+}
+
+const builtInRateResolver: TimeRateResolver = registry.registerBuiltIn({
+  id: BUILT_IN_TIME_RATE_RESOLVER_ID,
+  priority: BUILT_IN_STRATEGY_PRIORITY,
+  resolve: builtInRate,
+})
+
+/**
+ * Walks the registry in priority order and takes the first non-null answer.
+ * Contributed resolvers are skipped entirely when the context carries no
+ * complete scope, which leaves the built-in as the only candidate.
+ */
+export function resolveTimeRate(ctx: TimeRateContext): number | null {
+  const scoped = hasResolverScope(ctx)
+  for (const resolver of registry.list()) {
+    if (!scoped && resolver.id !== BUILT_IN_TIME_RATE_RESOLVER_ID) continue
+    // A chain asks the next candidate anyway, so a thrower is skipped rather than
+    // replaced — and the built-in is always the last candidate.
+    const rate = tryStrategy(TIME_RATE_REGISTRY_ID, resolver.id, () => resolver.resolve(ctx))
+    if (rate !== null && rate !== undefined && Number.isFinite(rate)) return rate
+  }
+  return null
+}
+
+export function applicableRate(
+  entry: Pick<CostEntry, 'rateOverrideAmount'> | null | undefined,
+  project: CostProject | null | undefined,
+  ctx?: Omit<TimeRateContext, 'entry' | 'project'> | null,
+): number | null {
+  return resolveTimeRate({ ...(ctx ?? {}), entry: entry ?? null, project: project ?? null })
+}
+
+export function entryAmount(
+  entry: CostEntry,
+  project: CostProject | null | undefined,
+  ctx?: Omit<TimeRateContext, 'entry' | 'project'> | null,
+): number | null {
+  if (!entry?.isBillable) return null
+  const rate = applicableRate(entry, project, ctx)
+  if (rate === null) return null
+  const minutes = Number.isFinite(entry.roundedMinutes) ? entry.roundedMinutes : 0
+  return round2((minutes / 60) * rate)
+}
+
+export function sumAmounts(amounts: readonly (number | null | undefined)[]): number {
+  let cents = 0
+  for (const amount of amounts) {
+    if (amount === null || amount === undefined || !Number.isFinite(amount)) continue
+    cents += toCents(amount)
+  }
+  return round2(cents / 100)
+}

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

@@ -0,0 +1,68 @@
+export const MAX_DURATION_MINUTES = 1440
+
+export type DurationParseFailureReason = 'empty' | 'unparseable'
+
+export type ParseDurationResult =
+  | { ok: true; minutes: number }
+  | { ok: false; reason: DurationParseFailureReason }
+
+export type DurationFormatStyle = 'hm' | 'clock' | 'decimal'
+
+const CLOCK_PATTERN = /^(\d{1,3}):([0-5]\d)$/
+const UNIT_PATTERN = /^(?:(\d+(?:[.,]\d+)?)h)?(?:(\d+(?:[.,]\d+)?)m(?:in)?)?$/
+const BARE_NUMBER_PATTERN = /^\d+(?:[.,]\d+)?$/
+
+function toNumber(value: string): number {
+  return Number.parseFloat(value.replace(',', '.'))
+}
+
+function clampMinutes(minutes: number): number {
+  if (!Number.isFinite(minutes)) return 0
+  if (minutes < 0) return 0
+  if (minutes > MAX_DURATION_MINUTES) return MAX_DURATION_MINUTES
+  return Math.round(minutes)
+}
+
+export function parseDuration(input: string): ParseDurationResult {
+  if (typeof input !== 'string') return { ok: false, reason: 'unparseable' }
+  const trimmed = input.trim()
+  if (!trimmed) return { ok: false, reason: 'empty' }
+
+  const compact = trimmed.replace(/\s+/g, '').toLowerCase()
+  if (compact.startsWith('-')) return { ok: false, reason: 'unparseable' }
+
+  const clock = CLOCK_PATTERN.exec(compact)
+  if (clock) {
+    const hours = Number.parseInt(clock[1], 10)
+    const minutes = Number.parseInt(clock[2], 10)
+    return { ok: true, minutes: clampMinutes(hours * 60 + minutes) }
+  }
+
+  const units = UNIT_PATTERN.exec(compact)
+  if (units && (units[1] !== undefined || units[2] !== undefined)) {
+    const hours = units[1] !== undefined ? toNumber(units[1]) : 0
+    const minutes = units[2] !== undefined ? toNumber(units[2]) : 0
+    if (!Number.isFinite(hours) || !Number.isFinite(minutes)) return { ok: false, reason: 'unparseable' }
+    return { ok: true, minutes: clampMinutes(hours * 60 + minutes) }
+  }
+
+  if (BARE_NUMBER_PATTERN.test(compact)) {
+    const hours = toNumber(compact)
+    if (!Number.isFinite(hours)) return { ok: false, reason: 'unparseable' }
+    return { ok: true, minutes: clampMinutes(hours * 60) }
+  }
+
+  return { ok: false, reason: 'unparseable' }
+}
+
+export function formatDuration(minutes: number, style: DurationFormatStyle): string {
+  const safe = Number.isFinite(minutes) && minutes > 0 ? Math.round(minutes) : 0
+  const hours = Math.floor(safe / 60)
+  const rest = safe % 60
+
+  if (style === 'clock') return `${hours}:${String(rest).padStart(2, '0')}`
+  if (style === 'decimal') return (safe / 60).toFixed(2)
+  if (hours === 0) return `${rest}m`
+  if (rest === 0) return `${hours}h`
+  return `${hours}h ${rest}m`
+}