@kernhq/module-hr 0.13.1 → 0.14.0

package/src/client/settings/GeneralSettings.svelte

@@ -30,13 +30,18 @@ import { t } from '../i18n.js'
  * `workspaces.modules.list` and written with `workspaces.modules.updateSettings` — the same
  * mechanism the capabilities screen uses, and the reason the module never needs a settings table.
  *
- * **The write carries the whole `HrSettings` object.** Core merges a partial write now, but this
- * page owns every field in that schema and sending it whole is what makes the round trip
- * self-evident: nothing here can be a field somebody forgot to carry forward.
+ * **Core merges a partial write; it does not replace the stored object.** `setModuleSettings` in
+ * core patches the incoming keys over what is stored — an omitted key is left exactly as it was,
+ * and only an explicit `null` removes one — and then parses the merged blob through this module's
+ * schema, so even a key that is somehow absent comes back as the schema's default rather than as
+ * nothing. A field this page never sends is therefore carried forward by the server; saving this
+ * form cannot drop it.
  *
- * `directoryVisibleToMembers` is in the schema and is deliberately *not* on this page. Nothing in
- * `src/server` reads it, so a switch for it would promise a rule the API does not enforce. It is
- * carried through the write unchanged until it is either enforced or removed.
+ * The write below still spreads `stored` before the three edited fields. Under those semantics it
+ * costs nothing — it re-sends values identical to the ones already held — and it is what keeps the
+ * round trip correct if core ever replaces instead of merges: whatever the schema gains goes back
+ * as it came, without this page having to grow a control for it first. `stored` is the *parsed*
+ * settings, so `$capabilities` is not in it and cannot be echoed back over the platform's own key.
  */
 const api = coreApi<CoreApi>()
 const queryClient = useQueryClient()
@@ -136,12 +141,10 @@ const save = createMutation(() => ({
       workspaceId,
       moduleId: 'hr',
       settings: {
+        ...stored,
         country,
         employeeNumberPrefix: prefix,
         employeeNumberNext: parsedNext,
-        // Not editable here, and carried through rather than dropped: omitting it would leave the
-        // stored value to core's merge, which is a fact about core rather than about this page.
-        directoryVisibleToMembers: stored.directoryVisibleToMembers,
       },
     }),
   onSuccess: () => {

package/src/client/settings/SchedulesSettings.svelte

@@ -43,6 +43,19 @@ import { formatDuration, hrKeys, isoDate } from '../query.js'
  * the week runs down the dialog rather than across it, and the label column lands on whichever side
  * the reader's language starts from without a single `left` or `right` in the stylesheet.
  *
+ * **A schedule sets the hours, not the zone, and this screen used to say otherwise.** There was a
+ * "Time zone" field here offering the person's office, the person's own zone, or one fixed zone,
+ * and `schedules.tz_mode` / `schedules.tz` do store whichever was picked. Nothing ever reads them:
+ * `attendance.scheduleFor` builds a `ResolvedSchedule` of shifts, rounding and the automatic close
+ * and carries neither, and the zone a day is attributed in comes from `resolve.forPerson` — the
+ * person's own override if their profile sets one, otherwise their primary office. That ladder is
+ * the module's stated rule rather than an accident (`OfficeAssignment` in the contract: only the
+ * primary decides "which timezone the person's day is attributed in"), so the control was offering
+ * to change something it could not reach, and `fixed` was the option with no rung at all. The
+ * control is gone; the two columns stay. They hold what somebody once chose, dropping them would
+ * destroy that, and switching a setting off must never destroy data — so the screen states where
+ * the zone comes from instead of asking.
+ *
  * No stat tiles. Every number worth one here — how many schedules, how long each week is — is
  * already a column of the table below, and OfficesPage learned the hard way that a tile restating
  * the list is noise. The one figure that would earn a tile, how many people are on no schedule at
@@ -199,8 +212,6 @@ let editing = $state<{ schedule: Schedule | null } | null>(null)
 let name = $state('')
 let kind = $state('fixed')
 let week = $state<Week>(defaultWeek())
-let tzMode = $state('office')
-let tz = $state('')
 let graceIn = $state('0')
 let graceOut = $state('0')
 let roundingStep = $state('0')
@@ -215,8 +226,6 @@ function openEditor(schedule: Schedule | null) {
   name = schedule?.name ?? ''
   kind = schedule?.kind ?? 'fixed'
   week = schedule ? readWeek(schedule.week) : defaultWeek()
-  tzMode = schedule?.tzMode ?? 'office'
-  tz = schedule?.tz ?? ''
   graceIn = String(schedule?.graceInMinutes ?? 0)
   graceOut = String(schedule?.graceOutMinutes ?? 0)
   roundingStep = String(schedule?.roundingStepMinutes ?? 0)
@@ -261,22 +270,15 @@ const timesMissing = $derived(
   }),
 )
 const noWorkingDays = $derived(workingDays.length === 0)
-const zoneMissing = $derived(tzMode === 'fixed' && !tz)
 
 const weekError = $derived(
   noWorkingDays ? t('schedule_week_empty') : timesMissing ? t('schedule_time_missing') : null,
 )
-const canSave = $derived(manage && name.trim().length > 0 && !weekError && !zoneMissing)
+const canSave = $derived(manage && name.trim().length > 0 && !weekError)
 
 /** Why Save is off, in the order somebody would fix them. Null when nothing is blocking. */
 const blockedReason = $derived(
-  canSave
-    ? null
-    : !manage
-      ? t('schedules_readonly')
-      : !name.trim()
-        ? t('schedule_name_required')
-        : (weekError ?? (zoneMissing ? t('schedule_tz_required') : null)),
+  canSave ? null : !manage ? t('schedules_readonly') : !name.trim() ? t('schedule_name_required') : weekError,
 )
 
 const save = createMutation(() => ({
@@ -292,16 +294,15 @@ const save = createMutation(() => ({
       roundingDirection: roundingDirection as Schedule['roundingDirection'],
       autoClockOutAfterMinutes: autoClockOut ? Number(autoClockOut) : null,
     }
-    // Kind and time zone are create-only in the contract, and deliberately: the days already
-    // computed were measured with them, so changing one would rewrite history rather than the rule.
+    // Kind is create-only in the contract, and deliberately: the days already computed were
+    // measured with it, so changing it would rewrite history rather than the rule.
+    //
+    // `tzMode`/`tz` are not sent. The contract defaults `tzMode` to `office` and leaves `tz` null,
+    // which is the only combination that describes what attendance actually does — see the
+    // docblock. Sending anything else would record a choice no computation will honour.
     return current
       ? api.attendance.schedules.update({ ...common, scheduleId: current.id })
-      : api.attendance.schedules.create({
-          ...common,
-          kind: kind as Schedule['kind'],
-          tzMode: tzMode as Schedule['tzMode'],
-          tz: tzMode === 'fixed' ? tz : null,
-        })
+      : api.attendance.schedules.create({ ...common, kind: kind as Schedule['kind'] })
   },
   onSuccess: (schedule) => {
     toast.success(isNew ? t('schedule_created', { name: schedule.name }) : t('schedule_saved'))
@@ -418,34 +419,6 @@ const kindOptions = $derived([
   { value: 'shift', label: t('schedule_kind_shift'), description: t('schedule_kind_shift_desc') },
 ])
 
-const tzModeOptions = $derived([
-  { value: 'office', label: t('schedule_tz_office') },
-  { value: 'person', label: t('schedule_tz_person') },
-  { value: 'fixed', label: t('schedule_tz_fixed') },
-])
-
-/**
- * Every zone the runtime knows, grouped by area.
- *
- * `supportedValuesOf` is the only complete list available to a browser; where it is missing there
- * is exactly one zone worth offering, the one this machine is in. Reading it is not formatting, so
- * it does not go through the shared formatters.
- */
-const ZONES: string[] = (() => {
-  try {
-    const supported = (Intl as { supportedValuesOf?: (key: string) => string[] }).supportedValuesOf
-    const list = supported?.call(Intl, 'timeZone') ?? []
-    return list.length ? list : [Intl.DateTimeFormat().resolvedOptions().timeZone]
-  } catch {
-    return [Intl.DateTimeFormat().resolvedOptions().timeZone]
-  }
-})()
-const zoneOptions = ZONES.map((zone) => ({
-  value: zone,
-  label: zone.split('/').slice(1).join(' / ').replace(/_/g, ' ') || zone,
-  group: zone.split('/')[0]?.replace(/_/g, ' ') ?? '',
-}))
-
 /** A break somebody actually typed into the database keeps its place in the list. */
 const breakOptions = (current: number) =>
   [...new Set([0, 15, 30, 45, 60, 90, current])]
@@ -716,35 +689,15 @@ const autoClockOutOptions = $derived([
       </div>
     </section>
 
-    <!-- Time zone -->
-    {#if isNew}
-      <div class="pair">
-        <Field label={t('schedule_tz_mode')} hint={t('schedule_tz_hint')}>
-          {#snippet children(id)}
-            <Select {id} bind:value={tzMode} options={tzModeOptions} />
-          {/snippet}
-        </Field>
-        {#if tzMode === 'fixed'}
-          <Field
-            label={t('schedule_tz_label')}
-            required
-            error={zoneMissing ? t('schedule_tz_required') : null}
-          >
-            {#snippet children(id)}
-              <Select {id} bind:value={tz} options={zoneOptions} placeholder={t('schedule_tz_label')} />
-            {/snippet}
-          </Field>
-        {/if}
-      </div>
-    {:else}
-      <div class="ro">
-        <span class="rolabel">{t('schedule_tz_mode')}</span>
-        <p class="rovalue">
-          {tzModeOptions.find((option) => option.value === tzMode)?.label ?? tzMode}{#if tz}&nbsp;· {tz}{/if}
-        </p>
-        <p class="note">{t('schedule_immutable_hint')}</p>
-      </div>
-    {/if}
+    <!--
+      Whose clock the readings above are on — a sentence, because it is not a choice.
+
+      A control stood here offering to pick the zone. Nothing read what it stored, and the answer it
+      was asking for is the same for every schedule in the workspace, so the honest version of the
+      field is the fact it was hiding. Read-only on an existing schedule was the same claim in the
+      past tense, so that went with it.
+    -->
+    <p class="note">{t('schedule_tz_note')}</p>
 
     <!-- Grace -->
     <div class="pair">

package/src/contract/attendance.ts

@@ -19,9 +19,35 @@ const ws = { workspaceId: WorkspaceId }
 export const PunchDirection = z.enum(['in', 'out', 'break_start', 'break_end'])
 export type PunchDirection = z.infer<typeof PunchDirection>
 
-export const PunchMethod = z.enum(['web', 'mobile', 'kiosk', 'qr', 'device', 'import', 'manual'])
+/**
+ * What recorded the punch.
+ *
+ * `manual` means **a person typed it** — a void carrying the reason somebody wrote, or an approved
+ * regularization. `auto` is the machine's own: the `auto-clock-out` job closing a shift nobody
+ * clocked out of, at an instant it computed rather than observed. They are different facts about
+ * whose hand is on somebody's timesheet, and for a while the job wrote `manual`, so an employee
+ * reading their own day was told a colleague had entered a punch that no colleague had touched.
+ *
+ * **Widening this is additive for parsing and not for reading.** Every already-stored punch still
+ * validates, and a client built before `auto` existed has no label for it — it falls through to
+ * whatever its unknown-method default is, which is the sentence above. So the value lands in the
+ * contract, and in a reader that knows what to call it, before anything writes one.
+ */
+export const PunchMethod = z.enum(['web', 'mobile', 'kiosk', 'qr', 'device', 'import', 'manual', 'auto'])
 export type PunchMethod = z.infer<typeof PunchMethod>
 
+/**
+ * The methods a **caller** may claim, which is every one except `auto`.
+ *
+ * `clockIn` and `clockOut` take the method out of the request and store it unread, so widening
+ * `PunchMethod` widens the input alongside the output: without this, anybody holding
+ * `attendancePunch` could post `method: 'auto'` and have a punch they made themselves presented as
+ * the machine's. `auto` is written by the `auto-clock-out` job and by nothing else, and this is the
+ * schema the two punch inputs take so that stays true.
+ */
+export const ClientPunchMethod = PunchMethod.exclude(['auto'])
+export type ClientPunchMethod = z.infer<typeof ClientPunchMethod>
+
 /**
  * How much the recorded instant can be trusted.
  *

package/src/contract/capabilities.ts

@@ -82,6 +82,16 @@ export const hrCapabilities = defineCapabilities([
     // Off by default. Plenty of companies grant a fixed allowance on 1 January and never accrue —
     // and for them an accrual engine is a screen full of settings that change nothing.
     defaultEnabled: false,
+    // Carry-forward and expiry are named here because they are part of the same switch: a
+    // `carry_forward` policy is a `policies` row, and every `policies.*` procedure is gated by
+    // *this* capability rather than by `leave` — the `leave_accrual` list in
+    // `hrCapabilityProcedures` below names all eight, and each carries `cap('leave_accrual')` in
+    // `src/server/router.ts`. There is no `policies` capability; the whole record type lives behind
+    // accrual, which is why switching accrual off takes carry-forward and expiry with it. The
+    // policy is written on the accrual settings screen beside the accrual policies. The engine had
+    // both from the start (`carryForward`, the `carry-forward` job, `carry_in` / `carry_out` /
+    // `expiry` in the ledger) while nothing could write the policy, which is the one way this
+    // description was ever untrue: the product did it and no administrator could reach it.
     level: 2,
   },
   {

package/src/contract/events.ts

@@ -65,13 +65,6 @@ export const hrEvents = {
     'hr.office.created',
     z.object({ officeId: z.uuid(), workspaceId: WorkspaceId, country: z.string() }),
   ),
-  /**
-   * A calendar's days changed — a holiday added, a pack applied.
-   *
-   * Everything derived from a calendar (working days, leave day counts, later the attendance day
-   * sheet) is stale from here. The payload names the date range touched so a consumer can recompute
-   * that window rather than everything.
-   */
   leaveRequested: defineEvent(
     'hr.leave.requested',
     z.object({
@@ -109,6 +102,18 @@ export const hrEvents = {
       deltaMinutes: z.number().int(),
     }),
   ),
+  /**
+   * Something needs signing off, and these are the people it is waiting on.
+   *
+   * Raised once per approval request, after the transaction that created the subject has committed —
+   * a rollback must not leave an approver holding a card for a leave request that does not exist.
+   * `approverIds` is the *first* step only: later steps are resolved at request time but nobody on
+   * them is waiting yet, and telling somebody to act before their turn is worse than telling them
+   * late. The step that becomes current later announces itself through `hr.approval.decided`.
+   *
+   * Nothing is emitted for a chain that resolved to nobody. Auto-approval is not a request, and an
+   * empty `approverIds` would only teach a subscriber to filter it back out.
+   */
   approvalRequested: defineEvent(
     'hr.approval.requested',
     z.object({
@@ -139,20 +144,19 @@ export const hrEvents = {
       businessDate: z.iso.date(),
     }),
   ),
+  // `hr.attendance.day_computed` was declared here and never emitted. It fires on every punch —
+  // four a day per person, every workday — so declaring it committed us to a stampede on behalf of
+  // nobody: nothing in the product subscribes, and a subscriber that appeared would have had to
+  // debounce it before doing anything useful. `hr.punch.recorded` already says a day is stale and
+  // costs the same. It comes back when something needs the derived totals *and* the emit can afford
+  // the fan-out — batched per day rather than per punch, most likely from the nightly job.
   /**
-   * A derived day changed. Carries the date so a consumer recomputes that window rather than
-   * everything — this fires on every punch, so a coarse payload would be a stampede.
+   * A calendar's days changed — a holiday added, a pack applied.
+   *
+   * Everything derived from a calendar (working days, leave day counts, the attendance day sheet)
+   * is stale from here. The payload names the date range touched so a consumer can recompute that
+   * window rather than everything.
    */
-  attendanceDayComputed: defineEvent(
-    'hr.attendance.day_computed',
-    z.object({
-      workspaceId: WorkspaceId,
-      personId: z.uuid(),
-      businessDate: z.iso.date(),
-      status: z.string(),
-      workedMinutes: z.number().int(),
-    }),
-  ),
   calendarChanged: defineEvent(
     'hr.calendar.changed',
     z.object({

package/src/contract/models.ts

@@ -60,6 +60,17 @@ export const Person = z.object({
   /** Overrides the primary office's zone for somebody who genuinely works elsewhere. */
   timezone: TimeZone.nullable(),
   custom: z.record(z.string(), z.unknown()),
+  /**
+   * The server withheld the personnel fields on this record — `personalEmail`, `phone`, `hiredOn`
+   * and `terminatedOn` are null because the reader may not see them, not because they are empty.
+   *
+   * Without this the two are indistinguishable, and they are different facts: an empty phone field
+   * reads as "this person has no phone number". The client cannot work it out for itself, because
+   * *which* people fall inside a reader's team or office is resolved server-side from the org chart
+   * — headship over an ltree subtree, office headship, and `manager_person_id`, all as of today —
+   * from data the directory does not even fetch. So the one place that does the nulling says so.
+   */
+  personnelHidden: z.boolean().default(false),
   createdAt: Timestamp,
   updatedAt: Timestamp,
 })

package/src/contract/router.ts

@@ -9,10 +9,10 @@ import {
 } from './approvals.js'
 import {
   AttendanceDay,
+  ClientPunchMethod,
   ClockState,
   Punch,
   PunchDirection,
-  PunchMethod,
   Regularization,
   Schedule,
   ScheduleAssignment,
@@ -769,7 +769,11 @@ export const hrContract = {
       .input(
         ws.extend({
           personId: z.uuid().optional(),
-          method: PunchMethod.default('web'),
+          // `ClientPunchMethod`, which is `PunchMethod` minus `auto`: `auto` means "the nightly
+          // sweep closed a shift nobody clocked out of", and it is the one value a caller must not
+          // be able to claim for itself. The employee's timeline labels it "Closed automatically",
+          // so accepting it here would let a punch dressed as the machine's disown a person's own.
+          method: ClientPunchMethod.default('web'),
           clientReportedAt: z.iso.datetime({ offset: true }).nullish(),
           geo: z.object({ lat: z.number(), lng: z.number(), accuracyM: z.number().optional() }).nullish(),
           note: z.string().max(500).nullish(),
@@ -782,7 +786,11 @@ export const hrContract = {
       .input(
         ws.extend({
           personId: z.uuid().optional(),
-          method: PunchMethod.default('web'),
+          // `ClientPunchMethod`, which is `PunchMethod` minus `auto`: `auto` means "the nightly
+          // sweep closed a shift nobody clocked out of", and it is the one value a caller must not
+          // be able to claim for itself. The employee's timeline labels it "Closed automatically",
+          // so accepting it here would let a punch dressed as the machine's disown a person's own.
+          method: ClientPunchMethod.default('web'),
           clientReportedAt: z.iso.datetime({ offset: true }).nullish(),
           geo: z.object({ lat: z.number(), lng: z.number(), accuracyM: z.number().optional() }).nullish(),
           note: z.string().max(500).nullish(),

package/src/contract/settings.ts

@@ -24,12 +24,18 @@ export const HrSettings = z.object({
   /** Employee numbers are generated from this when a person is created without one. */
   employeeNumberPrefix: z.string().max(8).default(''),
   employeeNumberNext: z.number().int().min(1).default(1),
-  /**
-   * Whether a member who is not in HR can see the directory at all.
+  /*
+   * `directoryVisibleToMembers` was declared here and removed. The idea is sound — some companies
+   * publish their org chart to everyone and some treat it as HR-only, which is coarser than
+   * `hr.person.view` and would sit above it — but nothing read the field, and no route in shell
+   * renders a module settings schema, so it could not be flipped through the product either. A
+   * setting whose documented rule nothing enforces teaches an administrator that settings do not
+   * mean anything, which is the same failure as a capability nothing checks.
    *
-   * Some companies publish their org chart to everyone; some treat it as HR-only. This is coarser
-   * than the permission and sits above it: off, and `hr.person.view` is not enough on its own.
+   * Bringing it back honestly needs both halves in the change that declares it: an enforcement site
+   * (`people.list` and `people.get` in `src/server/services/people.ts`, refusing a caller who has
+   * only `hr.person.view` while the flag is off), and a way for an administrator to reach it —
+   * a control on `src/client/settings/GeneralSettings.svelte`, which is already routed.
    */
-  directoryVisibleToMembers: z.boolean().default(true),
 })
 export type HrSettings = z.infer<typeof HrSettings>