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

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

@@ -0,0 +1,75 @@
+/**
+ * Rounding impact projection (T7.2) — the warning card on screen 16.
+ *
+ * Changing the rounding rule changes what clients are billed, and the effect is
+ * invisible until an invoice. The preview answers the only question that matters
+ * before saving: at the candidate rule, what would the last 90 days have billed?
+ *
+ * Two properties this file exists to guarantee:
+ *
+ *  1. **It rounds through `roundMinutes`, never a second implementation.** A
+ *     preview that disagreed with the write path would be worse than no preview.
+ *  2. **It rounds per entry, not per sum** (D-7). That is why the projection is
+ *     driven by `(durationMinutes, entryCount)` buckets rather than a SQL
+ *     `SUM(duration_minutes)`: the database groups identical durations, and each
+ *     distinct duration is rounded exactly once and multiplied by its count. The
+ *     result is arithmetically identical to rounding every row, at a fraction of
+ *     the rows.
+ */
+
+import { roundMinutes, type RoundingSettings } from './rounding'
+
+export type DurationBucket = {
+  durationMinutes: number
+  entryCount: number
+}
+
+export type RoundingImpact = {
+  entryCount: number
+  rawMinutes: number
+  roundedMinutes: number
+  /** Positive when the rule bills more than the raw time; negative when it bills less. */
+  deltaMinutes: number
+}
+
+export const EMPTY_ROUNDING_IMPACT: RoundingImpact = {
+  entryCount: 0,
+  rawMinutes: 0,
+  roundedMinutes: 0,
+  deltaMinutes: 0,
+}
+
+function toCount(value: unknown): number {
+  const parsed = typeof value === 'number' ? value : Number(value)
+  return Number.isFinite(parsed) && parsed > 0 ? Math.trunc(parsed) : 0
+}
+
+function toMinutes(value: unknown): number {
+  const parsed = typeof value === 'number' ? value : Number(value)
+  return Number.isFinite(parsed) ? Math.trunc(parsed) : 0
+}
+
+export function projectRoundingImpact(
+  buckets: readonly DurationBucket[],
+  settings: RoundingSettings,
+): RoundingImpact {
+  let entryCount = 0
+  let rawMinutes = 0
+  let roundedMinutes = 0
+
+  for (const bucket of buckets) {
+    const count = toCount(bucket.entryCount)
+    if (count === 0) continue
+    const duration = toMinutes(bucket.durationMinutes)
+    entryCount += count
+    rawMinutes += duration * count
+    roundedMinutes += roundMinutes(duration, settings) * count
+  }
+
+  return {
+    entryCount,
+    rawMinutes,
+    roundedMinutes,
+    deltaMinutes: roundedMinutes - rawMinutes,
+  }
+}

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

@@ -0,0 +1,274 @@
+/**
+ * EP-42 — the time-tracking settings key registry.
+ *
+ * `TIME_TRACKING_SETTING_KEYS` used to be a frozen array, `normalizeTimeTrackingSettings`
+ * a hand-written coercion per key, and `staffTimeTrackingSettingsSchema` a literal
+ * `z.object`. All three now read this registry, and the eight keys the module shipped
+ * are registered here as built-ins — so with no contribution the read, the write, the
+ * validating schema and the defaults are byte-identical to what they were.
+ *
+ * Storage is `ModuleConfigService` under module id `staff.time_tracking`, one config
+ * row per key, named `<group>.<key>` and scoped by **tenant only** (spec §10: time
+ * tracking settings are tenant-global; there is no per-organization override and no
+ * per-project override). A contributed key inherits exactly that scope — it is written
+ * with `{ tenantId }` and `organization_id` stays null.
+ */
+
+import { z } from 'zod'
+import { extensionPoints } from '@open-mercato/core/modules/staff/extension-points'
+import { BUILT_IN_STRATEGY_PRIORITY, createStrategyRegistry } from './registries/registry'
+import { DEFAULT_ROUNDING_SETTINGS } from './rounding'
+
+export const TIME_TRACKING_SETTING_KEY_REGISTRY_ID = extensionPoints.hosts.settingKeyRegistry.spotId
+
+export const TIME_TRACKING_ROUNDING_GROUP = 'rounding'
+export const TIME_TRACKING_DEFAULTS_GROUP = 'defaults'
+export const TIME_TRACKING_TARGETS_GROUP = 'targets'
+export const TIME_TRACKING_WARNINGS_GROUP = 'warnings'
+export const TIME_TRACKING_ACCESS_GROUP = 'access'
+
+/**
+ * Days past `assigned_end_date` that project access survives (spec D-12). The
+ * grace window exists so a consultant rolled off at the end of a month can still
+ * log and correct that month's time; `0` ends access the day the assignment ends.
+ */
+export const DEFAULT_ASSIGNMENT_GRACE_DAYS = 14
+
+export const MAX_ASSIGNMENT_GRACE_DAYS = 365
+
+export const timeTrackingRoundingUnitMinutesSchema = z.union([
+  z.literal(0),
+  z.literal(5),
+  z.literal(10),
+  z.literal(15),
+])
+
+export const timeTrackingRoundingDirectionSchema = z.enum(['up', 'nearest'])
+
+export type TimeTrackingSettingKeyInput = {
+  /** Group the value lives under in the settings object, e.g. `rounding`. */
+  group: string
+  /** Leaf name inside the group, e.g. `unitMinutes`. */
+  key: string
+  /** Validates the stored value; an invalid one falls back to `default`. */
+  schema: z.ZodTypeAny
+  /** Used when the tenant never stored the key and when the stored value no longer validates. */
+  default: unknown
+  /** i18n key for the label a settings section renders. Never a literal — the module holds no user-facing strings. */
+  labelKey: string
+  /** Higher first in `listTimeTrackingSettingKeys()`; built-ins sit below every contribution. */
+  priority?: number
+}
+
+export type TimeTrackingSettingKeyDefinition = TimeTrackingSettingKeyInput & {
+  /** `<group>.<key>` — the `ModuleConfigService` config name. */
+  id: string
+  builtIn: boolean
+}
+
+const registry = createStrategyRegistry<TimeTrackingSettingKeyDefinition>(
+  TIME_TRACKING_SETTING_KEY_REGISTRY_ID,
+)
+
+const builtInIds = new Set<string>()
+
+export function timeTrackingSettingStorageName(group: string, key: string): string {
+  return `${group}.${key}`
+}
+
+function registerKey(input: TimeTrackingSettingKeyInput, builtIn: boolean): () => void {
+  const group = input.group.trim()
+  const key = input.key.trim()
+  if (!group || !key) {
+    throw new Error('[internal] a time-tracking setting key requires a non-empty group and key')
+  }
+  const id = timeTrackingSettingStorageName(group, key)
+  if (!builtIn && builtInIds.has(id)) {
+    throw new Error(`[internal] ${id} is a built-in time-tracking setting key and cannot be replaced`)
+  }
+  const parsed = input.schema.safeParse(input.default)
+  if (!parsed.success) {
+    throw new Error(`[internal] the default for the time-tracking setting key ${id} fails its own schema`)
+  }
+  const definition = { ...input, group, key, id, builtIn }
+  if (builtIn) {
+    registry.registerBuiltIn(definition)
+    return () => {}
+  }
+  return registry.register(definition)
+}
+
+/**
+ * Contribute a tenant-scoped time-tracking setting key. Pair it with a widget on the
+ * `staff.time_tracking.settings:sections` injection spot (EP-26) to render it: the spot
+ * context carries `values` for every contributed key and a `setValue(id, value)` that
+ * writes into the page draft, so the page's own Save round-trips the contribution.
+ */
+export function registerTimeTrackingSettingKey(input: TimeTrackingSettingKeyInput): () => void {
+  return registerKey(input, false)
+}
+
+export function listTimeTrackingSettingKeys(): TimeTrackingSettingKeyDefinition[] {
+  return registry.list()
+}
+
+export function getTimeTrackingSettingKey(id: string | null | undefined): TimeTrackingSettingKeyDefinition | null {
+  return registry.get(id)
+}
+
+export function timeTrackingSettingKeyIds(): string[] {
+  return registry.ids()
+}
+
+/** The contributed keys only — the eight built-ins are rendered by the settings page's own form. */
+export function contributedTimeTrackingSettingKeys(): TimeTrackingSettingKeyDefinition[] {
+  return registry.list().filter((entry) => !entry.builtIn)
+}
+
+export function timeTrackingSettingGroups(): string[] {
+  const groups: string[] = []
+  for (const entry of registry.list()) {
+    if (!groups.includes(entry.group)) groups.push(entry.group)
+  }
+  return groups
+}
+
+const BUILT_IN_SETTING_KEYS: readonly TimeTrackingSettingKeyInput[] = [
+  {
+    group: TIME_TRACKING_ROUNDING_GROUP,
+    key: 'unitMinutes',
+    schema: timeTrackingRoundingUnitMinutesSchema,
+    default: DEFAULT_ROUNDING_SETTINGS.unitMinutes,
+    labelKey: 'staff.time_tracking.settings.rounding.unit',
+    priority: BUILT_IN_STRATEGY_PRIORITY,
+  },
+  {
+    group: TIME_TRACKING_ROUNDING_GROUP,
+    key: 'direction',
+    schema: timeTrackingRoundingDirectionSchema,
+    default: DEFAULT_ROUNDING_SETTINGS.direction,
+    labelKey: 'staff.time_tracking.settings.rounding.direction',
+    priority: BUILT_IN_STRATEGY_PRIORITY,
+  },
+  {
+    group: TIME_TRACKING_DEFAULTS_GROUP,
+    key: 'billable',
+    schema: z.boolean(),
+    default: true,
+    labelKey: 'staff.time_tracking.settings.defaults.billable',
+    priority: BUILT_IN_STRATEGY_PRIORITY,
+  },
+  {
+    group: TIME_TRACKING_DEFAULTS_GROUP,
+    key: 'chainStartFromPreviousEnd',
+    schema: z.boolean(),
+    default: true,
+    labelKey: 'staff.time_tracking.settings.defaults.chainStart',
+    priority: BUILT_IN_STRATEGY_PRIORITY,
+  },
+  {
+    group: TIME_TRACKING_TARGETS_GROUP,
+    key: 'dailyHours',
+    schema: z.number().min(0).max(24).nullable(),
+    default: 8,
+    labelKey: 'staff.time_tracking.settings.targets.dailyHours',
+    priority: BUILT_IN_STRATEGY_PRIORITY,
+  },
+  {
+    group: TIME_TRACKING_WARNINGS_GROUP,
+    key: 'overlap',
+    schema: z.boolean(),
+    default: true,
+    labelKey: 'staff.time_tracking.settings.warnings.overlap',
+    priority: BUILT_IN_STRATEGY_PRIORITY,
+  },
+  {
+    group: TIME_TRACKING_WARNINGS_GROUP,
+    key: 'runningTimer',
+    schema: z.boolean(),
+    default: true,
+    labelKey: 'staff.time_tracking.settings.warnings.runningTimer',
+    priority: BUILT_IN_STRATEGY_PRIORITY,
+  },
+  {
+    group: TIME_TRACKING_ACCESS_GROUP,
+    key: 'assignmentGraceDays',
+    schema: z.number().int().min(0).max(MAX_ASSIGNMENT_GRACE_DAYS),
+    default: DEFAULT_ASSIGNMENT_GRACE_DAYS,
+    labelKey: 'staff.time_tracking.settings.access.graceDays',
+    priority: BUILT_IN_STRATEGY_PRIORITY,
+  },
+]
+
+for (const input of BUILT_IN_SETTING_KEYS) {
+  registerKey(input, true)
+  builtInIds.add(timeTrackingSettingStorageName(input.group, input.key))
+}
+
+export const BUILT_IN_TIME_TRACKING_SETTING_KEY_IDS: readonly string[] = Object.freeze(
+  BUILT_IN_SETTING_KEYS.map((input) => timeTrackingSettingStorageName(input.group, input.key)),
+)
+
+export function isBuiltInTimeTrackingSettingKey(id: string): boolean {
+  return builtInIds.has(id)
+}
+
+export type TimeTrackingSettingsRecord = Record<string, Record<string, unknown>>
+
+/**
+ * The validating schema the settings route parses against, rebuilt per call so a key
+ * registered after this module first loaded still validates (the same reason EP-35's
+ * export-format enum is an OpenAPI getter).
+ */
+export function buildTimeTrackingSettingsSchema(): z.ZodObject<Record<string, z.ZodTypeAny>> {
+  const byGroup = new Map<string, Record<string, z.ZodTypeAny>>()
+  const defaultsByGroup = new Map<string, Record<string, unknown>>()
+  for (const entry of registry.list()) {
+    const shape = byGroup.get(entry.group) ?? {}
+    shape[entry.key] = entry.schema.optional().default(entry.default)
+    byGroup.set(entry.group, shape)
+    const defaults = defaultsByGroup.get(entry.group) ?? {}
+    defaults[entry.key] = entry.default
+    defaultsByGroup.set(entry.group, defaults)
+  }
+  const shape: Record<string, z.ZodTypeAny> = {}
+  for (const [group, groupShape] of byGroup) {
+    shape[group] = z.object(groupShape).optional().default(defaultsByGroup.get(group) ?? {})
+  }
+  return z.object(shape)
+}
+
+/** The canonical settings object with every registered key at its registered default. */
+export function buildDefaultTimeTrackingSettings(): TimeTrackingSettingsRecord {
+  const result: TimeTrackingSettingsRecord = {}
+  for (const entry of registry.list()) {
+    const group = result[entry.group] ?? {}
+    group[entry.key] = entry.default
+    result[entry.group] = group
+  }
+  return result
+}
+
+function readGroup(source: unknown, group: string): Record<string, unknown> | null {
+  if (!source || typeof source !== 'object') return null
+  const value = (source as Record<string, unknown>)[group]
+  if (!value || typeof value !== 'object' || Array.isArray(value)) return null
+  return value as Record<string, unknown>
+}
+
+/**
+ * Coerce an arbitrary (possibly partial or malformed) settings shape into the canonical
+ * one: every registered key present, every absent or invalid value replaced by the
+ * registered default.
+ */
+export function normalizeTimeTrackingSettingsRecord(input: unknown): TimeTrackingSettingsRecord {
+  const result: TimeTrackingSettingsRecord = {}
+  for (const entry of registry.list()) {
+    const group = result[entry.group] ?? {}
+    const raw = readGroup(input, entry.group)?.[entry.key]
+    const parsed = entry.schema.safeParse(raw)
+    group[entry.key] = parsed.success ? parsed.data : entry.default
+    result[entry.group] = group
+  }
+  return result
+}

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

@@ -0,0 +1,168 @@
+import type { ModuleConfigService } from '@open-mercato/core/modules/configs/lib/module-config-service'
+import type { StaffTimeTrackingSettingsInput } from '../../data/validators'
+import {
+  type RoundingDirection,
+  type RoundingSettings,
+  type RoundingUnitMinutes,
+} from './rounding'
+import {
+  DEFAULT_ASSIGNMENT_GRACE_DAYS,
+  MAX_ASSIGNMENT_GRACE_DAYS,
+  buildDefaultTimeTrackingSettings,
+  listTimeTrackingSettingKeys,
+  normalizeTimeTrackingSettingsRecord,
+  registerTimeTrackingSettingKey,
+  timeTrackingSettingKeyIds,
+  type TimeTrackingSettingKeyDefinition,
+  type TimeTrackingSettingKeyInput,
+  type TimeTrackingSettingsRecord,
+} from './settingKeys'
+
+export type { RoundingDirection, RoundingSettings, RoundingUnitMinutes }
+export type { TimeTrackingSettingKeyDefinition, TimeTrackingSettingKeyInput, TimeTrackingSettingsRecord }
+export { DEFAULT_ASSIGNMENT_GRACE_DAYS, MAX_ASSIGNMENT_GRACE_DAYS, registerTimeTrackingSettingKey }
+
+export const STAFF_TIME_TRACKING_MODULE_ID = 'staff.time_tracking'
+
+export const TIME_TRACKING_ROUNDING_UNIT_MINUTES_KEY = 'rounding.unitMinutes'
+export const TIME_TRACKING_ROUNDING_DIRECTION_KEY = 'rounding.direction'
+export const TIME_TRACKING_DEFAULTS_BILLABLE_KEY = 'defaults.billable'
+export const TIME_TRACKING_DEFAULTS_CHAIN_START_KEY = 'defaults.chainStartFromPreviousEnd'
+export const TIME_TRACKING_TARGETS_DAILY_HOURS_KEY = 'targets.dailyHours'
+export const TIME_TRACKING_WARNINGS_OVERLAP_KEY = 'warnings.overlap'
+export const TIME_TRACKING_WARNINGS_RUNNING_TIMER_KEY = 'warnings.runningTimer'
+export const TIME_TRACKING_ACCESS_ASSIGNMENT_GRACE_DAYS_KEY = 'access.assignmentGraceDays'
+
+/**
+ * The eight keys the module shipped. FROZEN — a stored config row is named after one
+ * of these, so none may be renamed or removed. The list is no longer the whole truth:
+ * `timeTrackingSettingKeyIds()` returns these plus every contributed key (EP-42).
+ */
+export const TIME_TRACKING_SETTING_KEYS = [
+  TIME_TRACKING_ROUNDING_UNIT_MINUTES_KEY,
+  TIME_TRACKING_ROUNDING_DIRECTION_KEY,
+  TIME_TRACKING_DEFAULTS_BILLABLE_KEY,
+  TIME_TRACKING_DEFAULTS_CHAIN_START_KEY,
+  TIME_TRACKING_TARGETS_DAILY_HOURS_KEY,
+  TIME_TRACKING_WARNINGS_OVERLAP_KEY,
+  TIME_TRACKING_WARNINGS_RUNNING_TIMER_KEY,
+  TIME_TRACKING_ACCESS_ASSIGNMENT_GRACE_DAYS_KEY,
+] as const
+
+export type TimeTrackingSettingKey = (typeof TIME_TRACKING_SETTING_KEYS)[number]
+
+export type TimeTrackingEntryDefaults = {
+  billable: boolean
+  chainStartFromPreviousEnd: boolean
+}
+
+export type TimeTrackingTargets = {
+  dailyHours: number | null
+}
+
+export type TimeTrackingWarnings = {
+  overlap: boolean
+  runningTimer: boolean
+}
+
+export type TimeTrackingAccess = {
+  assignmentGraceDays: number
+}
+
+export type TimeTrackingBuiltInSettings = {
+  rounding: RoundingSettings
+  defaults: TimeTrackingEntryDefaults
+  targets: TimeTrackingTargets
+  warnings: TimeTrackingWarnings
+  access: TimeTrackingAccess
+}
+
+/**
+ * The five built-in groups stay statically typed; a contributed group or key reaches
+ * a caller through the index signature and is read with `readTimeTrackingSettingValue`.
+ */
+export type TimeTrackingSettings = TimeTrackingBuiltInSettings & TimeTrackingSettingsRecord
+
+/**
+ * Settings are global per tenant (spec §10 fixes them there — no per-project or
+ * per-customer override), so the scope carries the tenant only and MUST be
+ * derived from the authenticated context, never from request input. A contributed
+ * key inherits exactly that scope.
+ */
+export type TimeTrackingSettingsScope = {
+  tenantId: string
+}
+
+export const DEFAULT_TIME_TRACKING_SETTINGS: TimeTrackingSettings =
+  buildDefaultTimeTrackingSettings() as TimeTrackingSettings
+
+/**
+ * Coerce an arbitrary (possibly partial or malformed) settings shape into the
+ * canonical one, filling every absent or invalid value from the registered defaults.
+ */
+export function normalizeTimeTrackingSettings(
+  input: Partial<TimeTrackingBuiltInSettings> | TimeTrackingSettingsRecord | StaffTimeTrackingSettingsInput | null | undefined,
+): TimeTrackingSettings {
+  return normalizeTimeTrackingSettingsRecord(input) as TimeTrackingSettings
+}
+
+/** Reads one registered key out of a normalized settings object by its `<group>.<key>` id. */
+export function readTimeTrackingSettingValue(
+  settings: TimeTrackingSettings,
+  id: string,
+): unknown {
+  const separator = id.indexOf('.')
+  if (separator <= 0) return undefined
+  const group = settings[id.slice(0, separator)]
+  if (!group || typeof group !== 'object') return undefined
+  return (group as Record<string, unknown>)[id.slice(separator + 1)]
+}
+
+export { listTimeTrackingSettingKeys, timeTrackingSettingKeyIds }
+
+/**
+ * Resolve the tenant's time tracking settings. Absent keys (and keys holding a
+ * value the schema no longer accepts) fall back to the registered default, so a
+ * tenant that never opened the settings screen still reads a complete record.
+ */
+export async function readTimeTrackingSettings(
+  configService: ModuleConfigService,
+  scope: TimeTrackingSettingsScope,
+): Promise<TimeTrackingSettings> {
+  const configScope = { tenantId: scope.tenantId }
+  // `getRecord` rather than `getValue` so an explicitly stored `null`
+  // (`targets.dailyHours` = "no daily target") stays distinguishable from an
+  // absent row, which must fall back to the default.
+  const stored: TimeTrackingSettingsRecord = {}
+  for (const entry of listTimeTrackingSettingKeys()) {
+    const record = await configService.getRecord(STAFF_TIME_TRACKING_MODULE_ID, entry.id, configScope)
+    if (!record) continue
+    const group = stored[entry.group] ?? {}
+    group[entry.key] = record.value
+    stored[entry.group] = group
+  }
+  return normalizeTimeTrackingSettings(stored)
+}
+
+/**
+ * Persist the tenant's time tracking settings and return the stored shape.
+ */
+export async function writeTimeTrackingSettings(
+  configService: ModuleConfigService,
+  scope: TimeTrackingSettingsScope,
+  input: Partial<TimeTrackingBuiltInSettings> | TimeTrackingSettingsRecord | StaffTimeTrackingSettingsInput,
+): Promise<TimeTrackingSettings> {
+  const settings = normalizeTimeTrackingSettings(input)
+  const configScope = { tenantId: scope.tenantId }
+
+  for (const entry of listTimeTrackingSettingKeys()) {
+    await configService.setValue(
+      STAFF_TIME_TRACKING_MODULE_ID,
+      entry.id,
+      readTimeTrackingSettingValue(settings, entry.id),
+      configScope,
+    )
+  }
+
+  return settings
+}

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

@@ -0,0 +1,22 @@
+/**
+ * Renders an id list into a raw-SQL `IN` clause with one placeholder per member.
+ *
+ * MikroORM does not bind parameters at the driver level: `AbstractSqlConnection.execute`
+ * calls `platform.formatQuery`, which interpolates each value through
+ * `BasePostgreSqlPlatform.escape`, and that renders a JavaScript array as a bare
+ * comma-separated list. `column = ANY(?)` therefore reaches PostgreSQL as
+ * `= ANY('a', 'b')` — or, for a single-element array, as the bare scalar, which fails
+ * with `malformed array literal`. The dashboards aggregation builder hit the same wall
+ * (#4669) and settled on one placeholder per member; this is that same fix, shared by
+ * the time-tracking raw queries.
+ *
+ * An empty list yields `IN (NULL)` rather than a dropped clause: a caller that narrowed
+ * to nothing must select nothing, never silently widen to every row.
+ */
+export type SqlInClause = { sql: string; params: unknown[] }
+
+export function buildSqlInClause(column: string, values: readonly string[]): SqlInClause {
+  if (values.length === 0) return { sql: `${column} IN (NULL)`, params: [] }
+  const placeholders = values.map(() => '?').join(', ')
+  return { sql: `${column} IN (${placeholders})`, params: [...values] }
+}

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

@@ -0,0 +1,85 @@
+/**
+ * EP-37 — the time-entry source registry.
+ *
+ * `staff_time_entries.source` used to be a four-value database enum, which made
+ * every import integration a core patch. It is now a plain text column whose
+ * accepted values are this registry, so a `jira`, `toggl` or `badge-terminal`
+ * source ships with its contributing module.
+ *
+ * `editable` is the flag the entry screens read: a source the user may still
+ * hand-correct (`manual`) versus one whose numbers belong to the system that
+ * produced them. It is advisory metadata, not an authorization decision — the
+ * lock rules stay with `locked_report_id` and the ACL features.
+ */
+
+import { extensionPoints } from '@open-mercato/core/modules/staff/extension-points'
+import { createStrategyRegistry, BUILT_IN_STRATEGY_PRIORITY } from './registries/registry'
+
+export const BUILT_IN_TIME_ENTRY_SOURCE_IDS = ['manual', 'timer', 'kiosk', 'mobile'] as const
+
+export type BuiltInTimeEntrySource = (typeof BUILT_IN_TIME_ENTRY_SOURCE_IDS)[number]
+
+/**
+ * Widened from the original four-value union so a contributed id is assignable.
+ * The union arm keeps the four built-ins as completions.
+ */
+export type TimeEntrySource = BuiltInTimeEntrySource | (string & {})
+
+export type TimeEntrySourceDefinition = {
+  id: string
+  labelKey: string
+  /** Lucide icon name the entry screens may render beside the row. */
+  icon: string
+  editable: boolean
+  priority?: number
+}
+
+export const TIME_ENTRY_SOURCE_REGISTRY_ID = extensionPoints.hosts.timeEntrySourceRegistry.spotId
+
+export const DEFAULT_TIME_ENTRY_SOURCE: BuiltInTimeEntrySource = 'manual'
+
+const registry = createStrategyRegistry<TimeEntrySourceDefinition>(TIME_ENTRY_SOURCE_REGISTRY_ID)
+
+export function registerTimeEntrySource(source: TimeEntrySourceDefinition): () => void {
+  return registry.register(source)
+}
+
+export function listTimeEntrySources(): TimeEntrySourceDefinition[] {
+  return registry.list()
+}
+
+export function getTimeEntrySource(id: string | null | undefined): TimeEntrySourceDefinition | null {
+  return registry.get(id)
+}
+
+export function hasTimeEntrySource(id: string | null | undefined): boolean {
+  return registry.has(id)
+}
+
+/** Built-ins first, in the order the module shipped them, then contributions. */
+export function timeEntrySourceIds(): string[] {
+  const builtIn = BUILT_IN_TIME_ENTRY_SOURCE_IDS.filter((id) => registry.has(id))
+  const contributed = registry.ids().filter((id) => !builtIn.includes(id as BuiltInTimeEntrySource))
+  return [...builtIn, ...contributed]
+}
+
+/**
+ * The write-path guard the dropped database check constraint used to provide.
+ * An unknown id falls back to `manual` rather than rejecting the write, matching
+ * the column default the enum carried.
+ */
+export function normalizeTimeEntrySource(value: unknown): TimeEntrySource {
+  if (typeof value === 'string' && registry.has(value)) return value
+  return DEFAULT_TIME_ENTRY_SOURCE
+}
+
+const builtInSources: readonly Omit<TimeEntrySourceDefinition, 'priority'>[] = [
+  { id: 'manual', labelKey: 'staff.time_tracking.entries.source.manual', icon: 'PenLine', editable: true },
+  { id: 'timer', labelKey: 'staff.time_tracking.entries.source.timer', icon: 'Timer', editable: true },
+  { id: 'kiosk', labelKey: 'staff.time_tracking.entries.source.kiosk', icon: 'Monitor', editable: false },
+  { id: 'mobile', labelKey: 'staff.time_tracking.entries.source.mobile', icon: 'Smartphone', editable: true },
+]
+
+for (const source of builtInSources) {
+  registry.registerBuiltIn({ ...source, priority: BUILT_IN_STRATEGY_PRIORITY })
+}