@kernhq/module-hr 0.6.0 → 0.8.0

package/migrations/meta/_journal.json

@@ -29,6 +29,13 @@
       "when": 1787634652573,
       "tag": "0003_attendance",
       "breakpoints": true
+    },
+    {
+      "idx": 4,
+      "version": "7",
+      "when": 1787675369496,
+      "tag": "0004_policies",
+      "breakpoints": true
     }
   ]
 }

package/package.json

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

package/src/contract/capabilities.ts

@@ -74,6 +74,24 @@ export const hrCapabilities = defineCapabilities([
     defaultEnabled: true,
     level: 1,
   },
+  {
+    id: 'leave_accrual',
+    label: 'Accrual',
+    description: 'Earn leave over time, with proration, carry-forward and expiry',
+    dependsOn: ['leave'],
+    // 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,
+    level: 2,
+  },
+  {
+    id: 'periods',
+    label: 'Payroll periods',
+    description: 'Close a month so a filed payroll cannot move underneath it',
+    dependsOn: ['core'],
+    defaultEnabled: false,
+    level: 2,
+  },
   {
     id: 'approvals',
     label: 'Approval chains',
@@ -185,6 +203,19 @@ export const hrCapabilityProcedures: Record<string, readonly string[]> = {
     'attendance.regularizations.list',
     'attendance.regularizations.request',
   ],
+  leave_accrual: [
+    'policies.list',
+    'policies.get',
+    'policies.create',
+    'policies.update',
+    'policies.archive',
+    'policies.assign',
+    'policies.unassign',
+    'policies.resolveFor',
+    'accrual.preview',
+    'accrual.run',
+  ],
+  periods: ['periods.list', 'periods.create', 'periods.lock', 'periods.unlock'],
   approvals: [
     'approvals.chains.list',
     'approvals.chains.create',

package/src/contract/index.ts

@@ -13,5 +13,6 @@ export * from './events.js'
 export * from './leave.js'
 export * from './models.js'
 export * from './permissions.js'
+export * from './policies.js'
 export * from './router.js'
 export * from './settings.js'

package/src/contract/permissions.ts

@@ -273,6 +273,31 @@ export const hrPermissions = definePermissions([
     dangerous: false,
   },
 
+  // ---------------------------------------------------------------- policies and periods
+  {
+    key: 'hr.policy.view',
+    label: 'View accrual, overtime and rounding policies',
+    scope: 'workspace',
+    defaultRoles: ['owner', 'admin'],
+    dangerous: false,
+  },
+  {
+    key: 'hr.policy.manage',
+    label: 'Change policies and who they apply to',
+    description: 'Changes what everybody accrues. A retroactive change is an adjustment, not a rewrite.',
+    scope: 'workspace',
+    defaultRoles: ['owner'],
+    dangerous: true,
+  },
+  {
+    key: 'hr.period.manage',
+    label: 'Open, lock and unlock payroll periods',
+    description: 'Locking freezes a month against recomputation. Unlocking lets it move again.',
+    scope: 'workspace',
+    defaultRoles: ['owner'],
+    dangerous: true,
+  },
+
   // ---------------------------------------------------------------- approvals
   {
     key: 'hr.approval.manage',
@@ -334,6 +359,9 @@ export const HR_PERMISSIONS = {
   attendanceManage: 'hr.attendance.manage',
   overtimeView: 'hr.overtime.view',
   overtimeManage: 'hr.overtime.manage',
+  policyView: 'hr.policy.view',
+  policyManage: 'hr.policy.manage',
+  periodManage: 'hr.period.manage',
   approvalManage: 'hr.approval.manage',
   approvalDelegate: 'hr.approval.delegate',
 } as const

package/src/contract/policies.ts

@@ -0,0 +1,207 @@
+import { Timestamp, WorkspaceId } from '@kernhq/contracts'
+import { z } from 'zod'
+import { IsoDate } from './models.js'
+
+const ws = { workspaceId: WorkspaceId }
+
+/**
+ * Policies as data, and the ladder that decides which one applies.
+ *
+ * Leave entitlement, overtime rules and rounding differ per company and per country, and encoding
+ * that as `if (country === 'TR')` is how a product acquires a branch per customer. A policy is a
+ * row: a kind, a config validated by that kind's schema, an effective range, and an assignment to
+ * somebody — a person, an office, a department, or the whole workspace.
+ *
+ * **One ladder, used by everything**: `person → primary office → legal entity → org unit →
+ * position → workspace`, nearest wins. The same order resolves a calendar, so there is never a
+ * second precedence rule to remember.
+ */
+
+export const PolicyKind = z.enum(['accrual', 'carry_forward', 'overtime', 'rounding', 'working_time'])
+export type PolicyKind = z.infer<typeof PolicyKind>
+
+/**
+ * Rungs of the ladder, and the priority each carries.
+ *
+ * The numbers are the ladder made explicit so a query can order by them rather than a service
+ * knowing the sequence by heart.
+ */
+export const PolicySubjectKind = z.enum([
+  'person',
+  'office',
+  'legal_entity',
+  'org_unit',
+  'position',
+  'workspace',
+])
+export type PolicySubjectKind = z.infer<typeof PolicySubjectKind>
+
+export const SUBJECT_PRIORITY: Record<PolicySubjectKind, number> = {
+  person: 100,
+  office: 80,
+  legal_entity: 60,
+  org_unit: 40,
+  position: 30,
+  workspace: 0,
+}
+
+// ---------------------------------------------------------------- config per kind
+
+export const SeniorityTier = z.object({
+  afterYears: z.number().int().min(0).max(60),
+  daysPerYear: z.number().min(0).max(365),
+})
+
+export const AccrualConfig = z.object({
+  frequency: z.enum(['monthly', 'annual', 'anniversary', 'per_hour_worked']),
+  daysPerYear: z.number().min(0).max(365),
+  minutesPerDay: z.number().int().min(1).max(1440),
+  /** Most senior tier reached wins; the order they are written in does not matter. */
+  seniorityTiers: z.array(SeniorityTier).default([]),
+  waitingPeriodMonths: z.number().int().min(0).max(24).default(0),
+  /** Which calendar decides a period boundary. Iran accrues on Jalali months. */
+  calendar: z.enum(['gregorian', 'persian']).default('gregorian'),
+  roundToMinutes: z.number().int().min(0).max(480).default(0),
+  /** Which leave type this accrues into. */
+  leaveTypeKey: z.string().min(1).max(48),
+})
+export type AccrualConfig = z.infer<typeof AccrualConfig>
+
+export const CarryForwardConfig = z.object({
+  leaveTypeKey: z.string().min(1).max(48),
+  maxDays: z.number().min(0).max(365),
+  /** Months into the new year before carried leave lapses. Null never expires. */
+  expiresAfterMonths: z.number().int().min(1).max(24).nullable(),
+})
+export type CarryForwardConfig = z.infer<typeof CarryForwardConfig>
+
+export const OvertimeConfig = z.object({
+  /** Minutes past the schedule before overtime starts counting. */
+  thresholdMinutes: z.number().int().min(0).max(480).default(0),
+  /** Cap for the period. Null is uncapped — several jurisdictions cap hours *worked*, not just pay. */
+  capMinutesPerYear: z.number().int().min(0).nullable().default(null),
+  /** Multiplier for reporting and payroll export. Kern does not compute pay. */
+  rate: z.number().min(1).max(5).default(1.5),
+  /** Overtime must be approved before it counts towards anything. */
+  requiresApproval: z.boolean().default(true),
+  /** Convert approved overtime into compensatory leave of this type instead of paying it. */
+  compOffLeaveTypeKey: z.string().max(48).nullable().default(null),
+})
+export type OvertimeConfig = z.infer<typeof OvertimeConfig>
+
+export const RoundingConfig = z.object({
+  stepMinutes: z.number().int().min(0).max(60),
+  direction: z.enum(['nearest', 'employee', 'employer']),
+})
+export type RoundingConfig = z.infer<typeof RoundingConfig>
+
+export const WorkingTimeConfig = z.object({
+  minutesPerDay: z.number().int().min(1).max(1440),
+  maxMinutesPerWeek: z.number().int().min(1).max(10080).nullable(),
+  /** Minimum rest between shifts, in minutes. Reported, not enforced by refusing a punch. */
+  minRestMinutes: z.number().int().min(0).max(1440).nullable(),
+})
+export type WorkingTimeConfig = z.infer<typeof WorkingTimeConfig>
+
+/** The config union, keyed by kind. Each kind validates its own shape before it runs. */
+export const PolicyConfig = z.union([
+  AccrualConfig,
+  CarryForwardConfig,
+  OvertimeConfig,
+  RoundingConfig,
+  WorkingTimeConfig,
+])
+
+export const Policy = z.object({
+  id: z.uuid(),
+  ...ws,
+  kind: PolicyKind,
+  name: z.string().min(1).max(120),
+  config: z.record(z.string(), z.unknown()),
+  effectiveFrom: IsoDate,
+  effectiveTo: IsoDate.nullable(),
+  source: z.enum(['pack', 'custom']),
+  packKey: z.string().max(32).nullable(),
+  /** What a derived row records, so a recomputation can tell a stale figure from a current one. */
+  configHash: z.string().max(64),
+  archivedAt: Timestamp.nullable(),
+})
+export type Policy = z.infer<typeof Policy>
+
+export const PolicyAssignment = z.object({
+  id: z.uuid(),
+  ...ws,
+  policyId: z.uuid(),
+  subjectKind: PolicySubjectKind,
+  /** Null for `workspace`, which needs no id. */
+  subjectId: z.uuid().nullable(),
+  effectiveFrom: IsoDate,
+  effectiveTo: IsoDate.nullable(),
+  priority: z.number().int(),
+})
+export type PolicyAssignment = z.infer<typeof PolicyAssignment>
+
+/**
+ * Which policy of a kind applies to a person on a date, and which rung answered.
+ *
+ * The rung is not decoration: "why does she accrue differently from her team" is the question this
+ * module gets asked, and answering it without a database session is the whole reason the ladder is
+ * inspectable.
+ */
+export const ResolvedPolicy = z.object({
+  kind: PolicyKind,
+  policyId: z.uuid().nullable(),
+  policyName: z.string().nullable(),
+  config: z.record(z.string(), z.unknown()).nullable(),
+  from: PolicySubjectKind.nullable(),
+  fromSubjectId: z.uuid().nullable(),
+})
+export type ResolvedPolicy = z.infer<typeof ResolvedPolicy>
+
+// ---------------------------------------------------------------- periods
+
+/**
+ * A closed month, and the boundary every recomputation respects.
+ *
+ * Locking is what makes a filed payroll safe: nothing may silently move a day inside a locked
+ * period, so a policy changed with a retroactive `effectiveFrom` produces an adjustment in the open
+ * period rather than rewriting history.
+ *
+ * Per legal entity, because a Dutch entity closes on a different day from a Turkish one.
+ */
+export const Period = z.object({
+  id: z.uuid(),
+  ...ws,
+  kind: z.enum(['payroll', 'attendance']),
+  legalEntityId: z.uuid().nullable(),
+  startsOn: IsoDate,
+  endsOn: IsoDate,
+  status: z.enum(['open', 'locked']),
+  lockedAt: Timestamp.nullable(),
+  lockedBy: z.uuid().nullable(),
+  note: z.string().max(500).nullable(),
+})
+export type Period = z.infer<typeof Period>
+
+/** What an accrual run would do, per person, before it writes anything. */
+export const AccrualPreview = z.object({
+  periodFrom: IsoDate,
+  periodTo: IsoDate,
+  rows: z.array(
+    z.object({
+      personId: z.uuid(),
+      displayName: z.string(),
+      leaveTypeId: z.uuid(),
+      leaveTypeName: z.string(),
+      minutes: z.number().int(),
+      days: z.number(),
+      /** Why it is that number: entitlement, service, proration, FTE. */
+      reason: z.string(),
+      /** Already accrued for this period — a re-run must not double-credit. */
+      alreadyAccrued: z.boolean(),
+    }),
+  ),
+  totalMinutes: z.number().int(),
+  skipped: z.array(z.object({ personId: z.uuid(), displayName: z.string(), reason: z.string() })),
+})
+export type AccrualPreview = z.infer<typeof AccrualPreview>

package/src/contract/router.ts

@@ -53,6 +53,15 @@ import {
   TimeZone,
   WorkingWeek,
 } from './models.js'
+import {
+  AccrualPreview,
+  Period,
+  Policy,
+  PolicyAssignment,
+  PolicyKind,
+  PolicySubjectKind,
+  ResolvedPolicy,
+} from './policies.js'
 
 const ws = z.object({ workspaceId: WorkspaceId })
 const t = ['hr'] as const
@@ -602,6 +611,145 @@ export const hrContract = {
       .output(ok),
   },
 
+  // ---------------------------------------------------------------- policies
+  policies: {
+    list: baseContract
+      .route({ method: 'GET', path: '/policies', tags: t })
+      .input(ws.extend({ kind: PolicyKind.optional(), includeArchived: z.boolean().default(false) }))
+      .output(z.array(Policy.extend({ assignments: z.array(PolicyAssignment) }))),
+    get: baseContract
+      .route({ method: 'GET', path: '/policies/{policyId}', tags: t })
+      .input(ws.extend({ policyId: z.uuid() }))
+      .output(Policy.extend({ assignments: z.array(PolicyAssignment) })),
+    create: baseContract
+      .route({ method: 'POST', path: '/policies', tags: t })
+      .input(
+        ws.extend({
+          kind: PolicyKind,
+          name: z.string().min(1).max(120),
+          /** Validated against the schema for `kind` — a config for the wrong kind is refused. */
+          config: z.record(z.string(), z.unknown()),
+          effectiveFrom: IsoDate,
+          effectiveTo: IsoDate.nullish(),
+        }),
+      )
+      .output(Policy),
+    /**
+     * Edits a policy in place.
+     *
+     * A change that should apply from a date rather than retroactively is a **new** policy with a
+     * later `effectiveFrom`, not an edit — editing rewrites what was true in the past, and anything
+     * already derived from it becomes unexplainable.
+     */
+    update: baseContract
+      .route({ method: 'PATCH', path: '/policies/{policyId}', tags: t })
+      .input(
+        ws.extend({
+          policyId: z.uuid(),
+          name: z.string().min(1).max(120).optional(),
+          config: z.record(z.string(), z.unknown()).optional(),
+          effectiveTo: IsoDate.nullish(),
+        }),
+      )
+      .output(Policy),
+    archive: baseContract
+      .route({ method: 'DELETE', path: '/policies/{policyId}', tags: t })
+      .input(ws.extend({ policyId: z.uuid() }))
+      .output(ok),
+    assign: baseContract
+      .route({ method: 'POST', path: '/policies/{policyId}/assign', tags: t })
+      .input(
+        ws.extend({
+          policyId: z.uuid(),
+          subjectKind: PolicySubjectKind,
+          /** Null for `workspace`, which needs no id. */
+          subjectId: z.uuid().nullish(),
+          effectiveFrom: IsoDate,
+          effectiveTo: IsoDate.nullish(),
+        }),
+      )
+      .output(PolicyAssignment),
+    unassign: baseContract
+      .route({ method: 'DELETE', path: '/policies/assignments/{assignmentId}', tags: t })
+      .input(ws.extend({ assignmentId: z.uuid() }))
+      .output(ok),
+    /**
+     * Which policy of each kind applies to this person on this date, and which rung answered.
+     *
+     * "Why does she accrue differently from her team" is the question this module gets asked, and
+     * this is what answers it without a database session.
+     */
+    resolveFor: baseContract
+      .route({ method: 'GET', path: '/people/{personId}/policies', tags: t })
+      .input(ws.extend({ personId: z.uuid(), on: IsoDate.optional() }))
+      .output(z.array(ResolvedPolicy)),
+  },
+
+  // ---------------------------------------------------------------- accrual
+  accrual: {
+    /**
+     * What a run would credit, per person, before it writes anything.
+     *
+     * Runs the same code the run does. A preview computed differently from the thing it previews is
+     * a preview that eventually lies.
+     */
+    preview: baseContract
+      .route({ method: 'POST', path: '/accrual/preview', tags: t })
+      .input(ws.extend({ from: IsoDate, to: IsoDate, personId: z.uuid().optional() }))
+      .output(AccrualPreview),
+    /**
+     * Credits the ledger.
+     *
+     * Idempotent per person, per leave type, per period: a second run for the same window credits
+     * nothing, because an accrual job that double-credits when somebody clicks twice is worse than
+     * one that never ran.
+     */
+    run: baseContract
+      .route({ method: 'POST', path: '/accrual/run', tags: t })
+      .input(ws.extend({ from: IsoDate, to: IsoDate, personId: z.uuid().optional() }))
+      .output(
+        z.object({
+          credited: z.number().int(),
+          skipped: z.number().int(),
+          totalMinutes: z.number().int(),
+        }),
+      ),
+  },
+
+  // ---------------------------------------------------------------- periods
+  periods: {
+    list: baseContract
+      .route({ method: 'GET', path: '/periods', tags: t })
+      .input(ws.extend({ kind: Period.shape.kind.optional(), ...PageInput.shape }))
+      .output(page(Period)),
+    create: baseContract
+      .route({ method: 'POST', path: '/periods', tags: t })
+      .input(
+        ws.extend({
+          kind: Period.shape.kind.default('payroll'),
+          legalEntityId: z.uuid().nullish(),
+          startsOn: IsoDate,
+          endsOn: IsoDate,
+        }),
+      )
+      .output(Period),
+    /** Freezes the month. Every derived day inside it stops being recomputable. */
+    lock: baseContract
+      .route({ method: 'POST', path: '/periods/{periodId}/lock', tags: t })
+      .input(ws.extend({ periodId: z.uuid(), note: z.string().max(500).nullish() }))
+      .output(Period.extend({ lockedDays: z.number().int() })),
+    /**
+     * Reopens it.
+     *
+     * Dangerous on purpose: a payroll has usually been filed against a locked month, and reopening
+     * lets figures move underneath it. The response says how many days became recomputable again.
+     */
+    unlock: baseContract
+      .route({ method: 'POST', path: '/periods/{periodId}/unlock', tags: t })
+      .input(ws.extend({ periodId: z.uuid(), reason: z.string().min(1).max(500) }))
+      .output(Period.extend({ unlockedDays: z.number().int() })),
+  },
+
   // ---------------------------------------------------------------- attendance
   attendance: {
     /** Am I clocked in? The one call a clock widget makes. */