@kernhq/module-hr 0.19.0 → 0.20.0

package/migrations/meta/_journal.json

@@ -78,6 +78,13 @@
       "when": 1787858088123,
       "tag": "0011_privacy",
       "breakpoints": true
+    },
+    {
+      "idx": 12,
+      "version": "7",
+      "when": 1787864979651,
+      "tag": "0012_rosters",
+      "breakpoints": true
     }
   ]
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kernhq/module-hr",
-  "version": "0.19.0",
+  "version": "0.20.0",
   "description": "Kern HR module: people, offices, org chart, calendars",
   "license": "AGPL-3.0-only",
   "type": "module",

package/src/contract/capabilities.ts

@@ -122,6 +122,18 @@ export const hrCapabilities = defineCapabilities([
     defaultEnabled: false,
     level: 1,
   },
+  {
+    id: 'rosters',
+    label: 'Shift rosters',
+    description: 'Rotating shifts on a calendar, and who covers which office-day',
+    // Depends on attendance rather than on core: a roster is what the clock and the day sheet are
+    // judged against, and rostering a workspace that never clocks anybody in is a planning grid
+    // nothing reads. Off by default and level 3 — most companies work a week that repeats, and for
+    // them a rotation editor is a screen full of settings that change nothing.
+    dependsOn: ['attendance'],
+    defaultEnabled: false,
+    level: 3,
+  },
   {
     id: 'documents',
     label: 'Employee documents',
@@ -248,6 +260,23 @@ export const hrCapabilityProcedures: Record<string, readonly string[]> = {
     'reports.overtime',
     'reports.absence',
   ],
+  rosters: [
+    'rosters.shifts.list',
+    'rosters.shifts.create',
+    'rosters.shifts.update',
+    'rosters.shifts.archive',
+    'rosters.patterns.list',
+    'rosters.patterns.create',
+    'rosters.patterns.update',
+    'rosters.patterns.archive',
+    'rosters.assignments',
+    'rosters.assign',
+    'rosters.unassign',
+    'rosters.days',
+    'rosters.set',
+    'rosters.clear',
+    'rosters.coverage',
+  ],
   leave_accrual: [
     'policies.list',
     'policies.get',

package/src/contract/index.ts

@@ -17,5 +17,6 @@ export * from './permissions.js'
 export * from './policies.js'
 export * from './privacy.js'
 export * from './reports.js'
+export * from './rosters.js'
 export * from './router.js'
 export * from './settings.js'

package/src/contract/permissions.ts

@@ -252,8 +252,11 @@ export const hrPermissions = definePermissions([
   },
   {
     key: 'hr.attendance.manage',
-    label: 'Correct punches, schedules and day sheets',
-    description: 'Voids punches and recomputes days. Every change leaves the original visible.',
+    label: 'Correct punches and set schedules, rosters and day sheets',
+    description:
+      'Voids punches and recomputes days. Every change leaves the original visible. Also edits ' +
+      'shifts and rotations and puts people on them, which decides what a shift worker is ' +
+      'expected to turn up for.',
     scope: 'workspace',
     defaultRoles: ['owner', 'admin'],
     dangerous: true,
@@ -262,6 +265,14 @@ export const hrPermissions = definePermissions([
   // nothing asks a question these keys could answer — a role checkbox that gates nothing teaches an
   // administrator the same lesson a dead capability switch does. They come back with the approval
   // flow that needs them.
+  //
+  // No `hr.roster.*` either, for the same reason and after weighing it. Rostering is `manage`:
+  // deciding what somebody was meant to work is the same authority as correcting what they did, and
+  // both feed the same day sheet. Reading a roster is `hr.attendance.view` for your own and
+  // `hr.attendance.view_team` for anybody else's — the coverage grid asks for the second, which is
+  // already what `attendance.days.list` costs to read a whole office. Four new keys would gate
+  // nothing the three existing ones do not already gate, which is how `hr.overtime.*` came to be
+  // deleted. They arrive if a workspace ever needs a planner who may roster and may not correct.
 
   // ---------------------------------------------------------------- reports
   {

package/src/contract/rosters.ts

@@ -0,0 +1,156 @@
+import { Timestamp, WorkspaceId } from '@kernhq/contracts'
+import { z } from 'zod'
+import { IsoDate, WallClock } from './models.js'
+
+const ws = { workspaceId: WorkspaceId }
+
+/**
+ * Rosters: which shift a person works on a **date**.
+ *
+ * A `Schedule` is a week that repeats for ever, so `ScheduleWeek` is keyed by weekday name. That is
+ * the right shape for an office and cannot express a factory: 4-on-4-off has no weekly period at
+ * all, and neither does any 2- or 3-week rotation, so there is no length of `ScheduleWeek` that
+ * describes one. A roster is keyed by the calendar instead, and adds exactly three things a
+ * schedule does not have:
+ *
+ * - **A shift on a date.** The key is the day, not a modulus of seven.
+ * - **Coverage** — "who is on Early on Tuesday" is a question about an office-day, not about a
+ *   person, and it cannot be asked of a set of weekly schedules without walking everybody's week.
+ * - **A one-day exception that survives.** A schedule change is effective-dated and rewrites every
+ *   day after it; a roster override changes one day and leaves the rotation alone.
+ *
+ * Everything else attendance already does — grace, rounding, overnight shifts, night-shift business
+ * date attribution, the auto-close sweep — stays where it is. A roster is not a second computation
+ * of hours; it is a different answer to "what was this person meant to work today".
+ *
+ * **The rotation is computed, never stored per day.** A `RosterPattern` is a cycle of days and the
+ * date `days[0]` falls on; what somebody works on any date at all is arithmetic from those two.
+ * Generating a year of rows per person is what makes a roster impossible to change afterwards —
+ * moving a crew forward by a day becomes a bulk rewrite of thousands of rows with no way to say
+ * which of them a human had touched. Only the exceptions are rows.
+ */
+
+/**
+ * A named shift: Early, Late, Night.
+ *
+ * Named rather than inlined into each pattern because coverage groups by it — "Early" in the
+ * warehouse pattern and "Early" in the picking pattern have to be the same column of the same grid.
+ * `graceInMinutes` / `graceOutMinutes` sit here rather than on the schedule for the same reason a
+ * night shift usually has a wider grace than a day one: they are properties of the shift.
+ */
+export const RosterShift = z.object({
+  id: z.uuid(),
+  ...ws,
+  name: z.string().min(1).max(80),
+  /** A one- or two-letter code, for a grid too dense to carry a name. */
+  code: z.string().max(8).nullable(),
+  start: WallClock,
+  /** Earlier than `start` for a shift that ends the next morning — the same rule `ShiftSpec` uses. */
+  end: WallClock,
+  breakMinutes: z.number().int().min(0).max(480),
+  graceInMinutes: z.number().int().min(0).max(240),
+  graceOutMinutes: z.number().int().min(0).max(240),
+  color: z.string().max(32).nullable(),
+  archivedAt: Timestamp.nullable(),
+})
+export type RosterShift = z.infer<typeof RosterShift>
+
+/**
+ * One position in a rotation: the shifts worked on that day of the cycle.
+ *
+ * An **array**, so a split shift — 06:00–10:00 and 16:00–20:00, ordinary in hospitality — is a
+ * cycle day with two entries rather than something the model forbids. An empty array is a rest day,
+ * which is a different fact from "nothing is rostered": a rest day is planned.
+ */
+export const RosterCycleDay = z.array(z.uuid()).max(4)
+export type RosterCycleDay = z.infer<typeof RosterCycleDay>
+
+/**
+ * A rotation, as a cycle and the date it starts from.
+ *
+ * The cycle length is `days.length` and is not stored separately — two numbers that must agree is
+ * one number and a bug. `anchorDate` is the date `days[0]` applies to; every other date is
+ * `(dayNumber(date) - dayNumber(anchorDate) + cycleOffset) mod days.length`, which answers for
+ * dates before the anchor as readily as after it.
+ */
+export const RosterPattern = z.object({
+  id: z.uuid(),
+  ...ws,
+  name: z.string().min(1).max(120),
+  /** The date `days[0]` falls on. Moving it rotates every assignment on this pattern at once. */
+  anchorDate: IsoDate,
+  days: z.array(RosterCycleDay).min(1).max(56),
+  archivedAt: Timestamp.nullable(),
+})
+export type RosterPattern = z.infer<typeof RosterPattern>
+
+/**
+ * A person on a rotation, over a period.
+ *
+ * Effective-dated like every other assignment here, and at most one may be in force on a day — the
+ * exclusion constraint in migration 0012 is what guarantees that rather than the handler, because
+ * two concurrent requests cannot both win against a constraint.
+ *
+ * `cycleOffset` is what puts two crews on one pattern out of phase: crew B on a 4-on-4-off cycle
+ * with `cycleOffset: 4` works exactly the days crew A is off. Without it every crew needs its own
+ * copy of the same rotation, and a change to the rotation has to be made once per crew.
+ */
+export const RosterAssignment = z.object({
+  id: z.uuid(),
+  ...ws,
+  personId: z.uuid(),
+  patternId: z.uuid(),
+  effectiveFrom: IsoDate,
+  effectiveTo: IsoDate.nullable(),
+  cycleOffset: z.number().int().min(0).max(55),
+  createdAt: Timestamp,
+})
+export type RosterAssignment = z.infer<typeof RosterAssignment>
+
+/**
+ * Where a rostered day came from.
+ *
+ * `none` is not the same as a rest day: it means nothing rosters this person on this date at all,
+ * and a screen that renders it identically to a planned day off is telling somebody their absence
+ * was intended. A rest day is `pattern` with no shifts.
+ */
+export const RosterDaySource = z.enum(['pattern', 'override', 'none'])
+export type RosterDaySource = z.infer<typeof RosterDaySource>
+
+export const RosterDay = z.object({
+  personId: z.uuid(),
+  businessDate: IsoDate,
+  shifts: z.array(RosterShift),
+  source: RosterDaySource,
+  /** Why this day differs from the rotation. Only ever set on an override. */
+  note: z.string().max(500).nullable(),
+})
+export type RosterDay = z.infer<typeof RosterDay>
+
+/** Enough of a person to fill a coverage grid. The name every member may already read. */
+export const RosterPerson = z.object({ personId: z.uuid(), displayName: z.string() })
+export type RosterPerson = z.infer<typeof RosterPerson>
+
+/**
+ * One office-day, which is the question a roster exists to answer.
+ *
+ * `off` carries the people a pattern covers on this date and does not put on a shift — the answer
+ * to "who could I call in", which is the second thing anybody looking at a coverage grid wants and
+ * the one a list of who is working cannot give.
+ */
+export const RosterCoverageDay = z.object({
+  businessDate: IsoDate,
+  slots: z.array(z.object({ shift: RosterShift, people: z.array(RosterPerson) })),
+  off: z.array(RosterPerson),
+})
+export type RosterCoverageDay = z.infer<typeof RosterCoverageDay>
+
+/**
+ * How long a roster range may be.
+ *
+ * Expansion is arithmetic and cheap; the cost is the person-days a coverage grid resolves and the
+ * size of what comes back. A quarter covers the longest rotation anybody plans by hand, and
+ * coverage is capped tighter because it multiplies by the population of an office.
+ */
+export const MAX_ROSTER_DAYS = 186
+export const MAX_COVERAGE_DAYS = 42

package/src/contract/router.ts

@@ -52,6 +52,7 @@ import {
   RegionCode,
   ResolvedCalendarDay,
   TimeZone,
+  WallClock,
   WorkingWeek,
 } from './models.js'
 import {
@@ -77,6 +78,14 @@ import {
   OvertimeReport,
   ReportSliceBy,
 } from './reports.js'
+import {
+  RosterAssignment,
+  RosterCoverageDay,
+  RosterCycleDay,
+  RosterDay,
+  RosterPattern,
+  RosterShift,
+} from './rosters.js'
 
 const ws = z.object({ workspaceId: WorkspaceId })
 const t = ['hr'] as const
@@ -974,6 +983,180 @@ export const hrContract = {
     },
   },
 
+  // ---------------------------------------------------------------- rosters
+  /**
+   * Who works which shift on which **date**.
+   *
+   * Separate from `attendance.schedules` rather than folded into it, because the two answer
+   * different questions and only one of them has a weekly period. A schedule is a week that repeats
+   * for ever; a rotation is a cycle of any length anchored to a date, which is the only shape
+   * 4-on-4-off has. Nothing here recomputes hours — grace, rounding, overnight attribution and the
+   * auto-close sweep all stay in attendance, and a roster only decides what the day was meant to be.
+   */
+  rosters: {
+    shifts: {
+      list: baseContract
+        .route({ method: 'GET', path: '/rosters/shifts', tags: t })
+        .input(ws.extend({ includeArchived: z.boolean().default(false) }))
+        .output(z.array(RosterShift)),
+      create: baseContract
+        .route({ method: 'POST', path: '/rosters/shifts', tags: t })
+        .input(
+          ws.extend({
+            name: z.string().min(1).max(80),
+            code: z.string().max(8).nullish(),
+            start: WallClock,
+            end: WallClock,
+            breakMinutes: z.number().int().min(0).max(480).default(0),
+            graceInMinutes: z.number().int().min(0).max(240).default(0),
+            graceOutMinutes: z.number().int().min(0).max(240).default(0),
+            color: z.string().max(32).nullish(),
+          }),
+        )
+        .output(RosterShift),
+      update: baseContract
+        .route({ method: 'PATCH', path: '/rosters/shifts/{shiftId}', tags: t })
+        .input(
+          ws.extend({
+            shiftId: z.uuid(),
+            name: z.string().min(1).max(80).optional(),
+            code: z.string().max(8).nullish(),
+            start: WallClock.optional(),
+            end: WallClock.optional(),
+            breakMinutes: z.number().int().min(0).max(480).optional(),
+            graceInMinutes: z.number().int().min(0).max(240).optional(),
+            graceOutMinutes: z.number().int().min(0).max(240).optional(),
+            color: z.string().max(32).nullish(),
+          }),
+        )
+        .output(RosterShift),
+      /**
+       * Archive, never delete. Patterns and stored overrides point at a shift by id, so deleting
+       * one would empty out every day it appears on — past days included.
+       */
+      archive: baseContract
+        .route({ method: 'DELETE', path: '/rosters/shifts/{shiftId}', tags: t })
+        .input(ws.extend({ shiftId: z.uuid() }))
+        .output(ok),
+    },
+
+    patterns: {
+      list: baseContract
+        .route({ method: 'GET', path: '/rosters/patterns', tags: t })
+        .input(ws.extend({ includeArchived: z.boolean().default(false) }))
+        .output(z.array(RosterPattern)),
+      create: baseContract
+        .route({ method: 'POST', path: '/rosters/patterns', tags: t })
+        .input(
+          ws.extend({
+            name: z.string().min(1).max(120),
+            anchorDate: IsoDate,
+            days: z.array(RosterCycleDay).min(1).max(56),
+          }),
+        )
+        .output(RosterPattern),
+      /**
+       * Editing a rotation moves every crew on it, on every date, at once — which is the point of a
+       * rotation being computed rather than generated, and worth saying out loud on the screen that
+       * does it.
+       */
+      update: baseContract
+        .route({ method: 'PATCH', path: '/rosters/patterns/{patternId}', tags: t })
+        .input(
+          ws.extend({
+            patternId: z.uuid(),
+            name: z.string().min(1).max(120).optional(),
+            anchorDate: IsoDate.optional(),
+            days: z.array(RosterCycleDay).min(1).max(56).optional(),
+          }),
+        )
+        .output(RosterPattern),
+      archive: baseContract
+        .route({ method: 'DELETE', path: '/rosters/patterns/{patternId}', tags: t })
+        .input(ws.extend({ patternId: z.uuid() }))
+        .output(ok),
+    },
+
+    /** Who is on which rotation, and when. `attendance.schedules` has no equivalent and should. */
+    assignments: baseContract
+      .route({ method: 'GET', path: '/rosters/assignments', tags: t })
+      .input(ws.extend({ personId: z.uuid().optional(), patternId: z.uuid().optional() }))
+      .output(z.array(RosterAssignment)),
+
+    /**
+     * Put a crew on a rotation.
+     *
+     * Takes a list of people because a rotation is a crew's, not a person's — assigning eleven
+     * people one at a time is eleven chances to get the offset wrong. The previous assignment is
+     * closed the day before, so "which rotation was she on in March" stays answerable.
+     */
+    assign: baseContract
+      .route({ method: 'POST', path: '/rosters/assign', tags: t })
+      .input(
+        ws.extend({
+          patternId: z.uuid(),
+          personIds: z.array(z.uuid()).min(1).max(200),
+          effectiveFrom: IsoDate,
+          /** The last day covered, inclusive. Null leaves the assignment open. */
+          effectiveTo: IsoDate.nullish(),
+          /** Which position of the cycle `effectiveFrom` starts at — how two crews run out of phase. */
+          cycleOffset: z.number().int().min(0).max(55).default(0),
+        }),
+      )
+      .output(z.array(RosterAssignment)),
+
+    /** Take a crew off its rotation, from the day after `effectiveTo`. Nothing is deleted. */
+    unassign: baseContract
+      .route({ method: 'POST', path: '/rosters/unassign', tags: t })
+      .input(
+        ws.extend({
+          personIds: z.array(z.uuid()).min(1).max(200),
+          /** The last day the rotation still applies. */
+          effectiveTo: IsoDate,
+        }),
+      )
+      .output(z.object({ closed: z.number().int() })),
+
+    /** One person's roster over a range, rotation and overrides already resolved. */
+    days: baseContract
+      .route({ method: 'GET', path: '/rosters/days', tags: t })
+      .input(ws.extend({ personId: z.uuid().optional(), from: IsoDate, to: IsoDate }))
+      .output(z.array(RosterDay)),
+
+    /**
+     * Change one day, leaving the rotation alone.
+     *
+     * An empty `shiftIds` is "off that day" and is stored — a planned rest day and a day nothing
+     * rosters at all are different facts, and only one of them is somebody's decision.
+     */
+    set: baseContract
+      .route({ method: 'POST', path: '/rosters/days', tags: t })
+      .input(
+        ws.extend({
+          personId: z.uuid(),
+          businessDate: IsoDate,
+          shiftIds: RosterCycleDay,
+          note: z.string().max(500).nullish(),
+        }),
+      )
+      .output(RosterDay),
+
+    /** Drop the exception and let the rotation speak for that day again. */
+    clear: baseContract
+      .route({ method: 'DELETE', path: '/rosters/days', tags: t })
+      .input(ws.extend({ personId: z.uuid(), businessDate: IsoDate }))
+      .output(ok),
+
+    /**
+     * Who is on which shift, per day — the question a roster exists for and the one a set of weekly
+     * schedules cannot be asked without walking everybody's week.
+     */
+    coverage: baseContract
+      .route({ method: 'GET', path: '/rosters/coverage', tags: t })
+      .input(ws.extend({ from: IsoDate, to: IsoDate, officeId: z.uuid().optional() }))
+      .output(z.array(RosterCoverageDay)),
+  },
+
   // ---------------------------------------------------------------- leave
   leave: {
     types: {