@kernhq/module-hr 0.13.2 → 0.14.1

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/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>