@kernhq/module-hr 0.18.1 → 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.18.1",
+  "version": "0.20.0",
   "description": "Kern HR module: people, offices, org chart, calendars",
   "license": "AGPL-3.0-only",
   "type": "module",

package/src/client/messages.ts

@@ -490,6 +490,8 @@ export const en: Record<string, Message> = {
   'hr.cap_legal_entities_desc': 'Several employing companies, for a group operating across borders',
   'hr.cap_offices': 'Offices',
   'hr.cap_offices_desc': 'More than one place of work, each with its own country, timezone and holidays',
+  'hr.cap_payroll_export': 'Payroll export',
+  'hr.cap_payroll_export_desc': 'Hand a closed period to a payroll provider as CSV, per legal entity',
   'hr.cap_periods': 'Payroll periods',
   'hr.cap_periods_desc': 'Close a month so a filed payroll cannot move underneath it',
   'hr.capabilities_desc':
@@ -1946,6 +1948,8 @@ export const ar: Record<string, Message> = {
   'hr.cap_legal_entities_desc': 'عدة شركات موظِّفة، لمجموعة تعمل عبر الحدود',
   'hr.cap_offices': 'المكاتب',
   'hr.cap_offices_desc': 'أكثر من مكان عمل، لكلٍّ منه بلده ومنطقته الزمنية وعطلاته',
+  'hr.cap_payroll_export': 'تصدير كشوف الرواتب',
+  'hr.cap_payroll_export_desc': 'تسليم فترة مُقفلة إلى مزوّد كشوف الرواتب بصيغة CSV، لكل كيان قانوني',
   'hr.cap_periods': 'فترات الرواتب',
   'hr.cap_periods_desc': 'إغلاق الشهر حتى لا يتغيّر كشف رواتب مُعتمد بعد اعتماده',
   'hr.capabilities_desc':
@@ -3431,6 +3435,9 @@ export const de: Record<string, Message> = {
   'hr.cap_offices': 'Standorte',
   'hr.cap_offices_desc':
     'Mehr als ein Arbeitsort, jeder mit eigenem Land, eigener Zeitzone und eigenen Feiertagen',
+  'hr.cap_payroll_export': 'Lohnexport',
+  'hr.cap_payroll_export_desc':
+    'Einen abgeschlossenen Zeitraum je Rechtsträger als CSV an einen Lohndienstleister übergeben',
   'hr.cap_periods': 'Abrechnungszeiträume',
   'hr.cap_periods_desc':
     'Einen Monat schließen, damit eine eingereichte Abrechnung sich nicht nachträglich verschiebt',
@@ -4835,6 +4842,9 @@ export const fa: Record<string, Message> = {
   'hr.cap_legal_entities_desc': 'چند شرکت کارفرما، برای گروهی که در چند کشور فعالیت می‌کند',
   'hr.cap_offices': 'دفاتر',
   'hr.cap_offices_desc': 'بیش از یک محل کار، هرکدام با کشور، منطقهٔ زمانی و تعطیلات خودش',
+  'hr.cap_payroll_export': 'خروجی حقوق و دستمزد',
+  'hr.cap_payroll_export_desc':
+    'تحویل یک دورهٔ بسته‌شده به ارائه‌دهندهٔ حقوق و دستمزد به‌صورت CSV، به تفکیک شخصیت حقوقی',
   'hr.cap_periods': 'دوره‌های حقوق و دستمزد',
   'hr.cap_periods_desc': 'بستن یک ماه تا حقوق ثبت‌شده دیگر تغییر نکند',
   'hr.capabilities_desc':
@@ -6207,6 +6217,9 @@ export const tr: Record<string, Message> = {
   'hr.cap_legal_entities_desc': 'Sınır ötesinde faaliyet gösteren bir grup için birden fazla işveren şirket',
   'hr.cap_offices': 'Ofisler',
   'hr.cap_offices_desc': 'Birden fazla çalışma yeri; her biri kendi ülkesi, saat dilimi ve tatilleriyle',
+  'hr.cap_payroll_export': 'Bordro dışa aktarma',
+  'hr.cap_payroll_export_desc':
+    'Kapanmış bir dönemi, tüzel kişilik bazında CSV olarak bordro sağlayıcısına aktarın',
   'hr.cap_periods': 'Bordro dönemleri',
   'hr.cap_periods_desc': 'Bir ayı kapatın; böylece verilmiş bordro sonradan kaymaz',
   'hr.capabilities_desc':

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',
@@ -130,6 +142,21 @@ export const hrCapabilities = defineCapabilities([
     defaultEnabled: false,
     level: 2,
   },
+  {
+    id: 'payroll_export',
+    label: 'Payroll export',
+    description: 'Hand a closed period to a payroll provider as CSV, per legal entity',
+    // Everything it reads: the day sheet, the periods that say the numbers have stopped moving, and
+    // the employment facts under `core`.
+    dependsOn: ['core', 'periods', 'attendance'],
+    // Off by default, and its own switch rather than riding on the two above — which is the whole
+    // argument for it existing. A company can perfectly well clock people in and close its months
+    // and still not want every employee's pay basis leaving the building as a file. The permission
+    // decides *who* may export; this decides whether the workspace does that at all, and the two
+    // answer different questions.
+    defaultEnabled: false,
+    level: 3,
+  },
 ])
 
 export type HrCapabilityId = (typeof hrCapabilities)[number]['id']
@@ -189,6 +216,7 @@ export const hrCapabilityProcedures: Record<string, readonly string[]> = {
     'calendars.workingDays',
   ],
   documents: ['documents.list', 'documents.attach', 'documents.remove'],
+  payroll_export: ['payroll.export.v1', 'payroll.export.preview'],
   leave: [
     'leave.types.list',
     'leave.types.create',
@@ -232,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/exports.ts

@@ -0,0 +1,354 @@
+import { Timestamp } from '@kernhq/contracts'
+import { z } from 'zod'
+import { LeaveUnit } from './leave.js'
+import { IsoDate } from './models.js'
+import { ReportFinality, ReportScope } from './reports.js'
+
+/**
+ * The payroll handover, and the four rules that make it safe to hand over.
+ *
+ * Kern does not compute pay. This file carries identity, the period, the employment facts that let a
+ * provider pick a rate, and quantities — minutes and days. There is no gross, no net, no hourly rate,
+ * no deduction and no currency amount anywhere in it; the moment a column reads as money, Kern is a
+ * payroll system and owes the accuracy of one. `OvertimeConfig.rate` says the same thing one file
+ * over: a multiplier is a fact about a policy, and multiplying anything by it is somebody else's job.
+ *
+ * **1. Per legal entity, keyed by (entity, period, person).** A person who transfers mid-period
+ * produces two rows, one in each entity's file, each carrying only that entity's days. Two entities
+ * in one workspace are two filings, in two currencies, to two authorities, on two closing days —
+ * `periods.legal_entity_id` exists for exactly that reason and `PolicyService.isLocked` already
+ * answers per entity. So `legalEntityId` is a **required** input rather than an optional slice: there
+ * is no "export everything", because that is an invitation to send one provider another entity's
+ * people.
+ *
+ * **2. Two files, not one.** `hours.csv` has a fixed column set. `leave.csv` is long-form — one row
+ * per person per leave type — because leave types are workspace data (`leave_types` is keyed on
+ * `(workspace_id, key)`), so a wide file with a column per type would have a column set that depends
+ * on the customer's own rows, and a column set that depends on customer data cannot be frozen.
+ *
+ * **3. Frozen, and the version travels in four places.** See {@link PAYROLL_EXPORT_CONTRACT}.
+ *
+ * **4. Refuse rather than guess.** An open period, an entity with nobody in it, or a person with no
+ * employment row covering their days is a refusal with a sentence, never a row of zeros a payroll
+ * clerk will pay from. The one escape hatch is `draft`, and a draft stamps itself — in the manifest,
+ * in the filename, and in every row's `open_days`.
+ */
+
+/**
+ * The contract identity, and **not** the package version.
+ *
+ * `@kernhq/module-hr` bumps on every patch and every image in an instance carries one
+ * `KERN_VERSION`; the CSV shape has to move on its own axis, so this is a hardcoded literal rather
+ * than `packageVersion(import.meta.url)`. `kernVersion` sits in the manifest as provenance and is
+ * never the contract identity.
+ *
+ * It travels in four places, each doing a different job:
+ *
+ * 1. **The procedure and its route** — `payroll.export.v1`, `GET /payroll/export/v1`. A new shape is
+ *    a new procedure, never a parameter on this one: freezing a branch inside a function three people
+ *    will edit has never worked, and separate procedures are what make the freeze structural.
+ * 2. **The filename** — `kern-payroll-v1_<entity>_2026-06_hours.csv`. The only part that survives
+ *    being emailed to a bureau and opened by somebody who never saw the API.
+ * 3. **The manifest** — `contract: 'kern-payroll-v1'` beside `generatedAt`, `kernVersion` and the
+ *    report header triple.
+ * 4. **Every row**, as the first column. A manifest can be separated from its CSVs and a filename can
+ *    be changed on the way to a payroll system; a file that has lost both must still be able to say
+ *    what shape it is. This is a column in the frozen set, **not** a banner row above the header —
+ *    a version line above the column names breaks every importer that assumes row 1 is the header,
+ *    which is most of them and all of the spreadsheet ones.
+ *
+ * What "frozen" forbids, once v1 has shipped: no new column, not even appended at the end; no removed
+ * or renamed column; no reordering; no changed emptiness semantics (`beyond_cap_minutes` empty means
+ * "no ceiling was in force" and must never start meaning zero); no changed units, so minutes stay
+ * minutes and `dayLengthMinutes` stays 480 even if this module later grows a per-workspace working
+ * day; and no changed encoding, delimiter, line ending or quoting. A later column is
+ * `payroll.export.v2` — a new procedure, a new filename prefix, a new manifest `contract` — shipping
+ * alongside v1 with v1 untouched. That is expensive on purpose: the expense is what stops the column
+ * set drifting, and a contract nobody pays to change is not frozen.
+ */
+export const PAYROLL_EXPORT_CONTRACT = 'kern-payroll-v1'
+
+/**
+ * `hours.csv`, in order. **This array is the file format.**
+ *
+ * Every column exists in the schema today. The quantities come from `attendance_days` and never from
+ * `punches`: punches are append-only and a voided punch survives beside its correction, so summing
+ * them double-counts every fix ever made. The day sheet is the projection that has already applied
+ * the schedule, the calendar and the rounding.
+ *
+ * Three of these carry a decision rather than a number:
+ *
+ * - `beyond_cap_minutes` is **empty, never `0`**, where no statutory ceiling was in force. Zero means
+ *   a ceiling applied and nothing exceeded it. A provider reading 0 for empty is the one place this
+ *   export can cause a wrong payment, which is why `capped_days` and `uncapped_days` sit beside it.
+ * - `scheduled_worked_minutes` excludes work on unrostered days, because a numerator that includes
+ *   them over a denominator that excludes them is how a team that turned up exactly as asked reads
+ *   121%.
+ * - `employment_changed_in_period` is true when more than one employment row overlaps the period.
+ *   Without it the export hands over the end-state FTE for somebody who went 1.0 → 0.6 on the 15th,
+ *   and the provider pays the whole month at one of them.
+ */
+export const PAYROLL_HOURS_COLUMNS = [
+  'contract',
+  'legal_entity_id',
+  'legal_entity_name',
+  'period_start',
+  'period_end',
+  'person_id',
+  'employee_no',
+  'display_name',
+  'employment_type',
+  'fte',
+  'contract_hours_week',
+  'cost_center_code',
+  'position_title',
+  'hired_on',
+  'terminated_on',
+  'employment_changed_in_period',
+  'day_sheets',
+  'scheduled_minutes',
+  'worked_minutes',
+  'scheduled_worked_minutes',
+  'break_minutes',
+  'overtime_minutes',
+  'late_minutes',
+  'early_leave_minutes',
+  'beyond_cap_minutes',
+  'capped_days',
+  'uncapped_days',
+  'locked_days',
+  'open_days',
+  'paid_leave_days',
+  'unpaid_leave_days',
+] as const
+
+/**
+ * `leave.csv`, in order. One row per (person, entity, period, leave type).
+ *
+ * Built from `leave_request_days` filtered `counted and status = 'approved'`, joined out to
+ * `leave_requests` → `leave_types`. **Not** `leave_ledger`: the ledger is the balance and carries
+ * `grant`, `accrual`, `carry_in` and `expiry`, which are movements rather than leave anybody took in
+ * this period. **Not** `leave_requests.minutes` summed per day either — that counts a five-day
+ * request five times, an off-by-a-factor this module has already been bitten by once.
+ *
+ * `days` sums `fraction`, which is exact and needs no day length. `dayLengthMinutes` is published in
+ * the manifest for anyone who wants to convert; this file does not convert for them.
+ */
+export const PAYROLL_LEAVE_COLUMNS = [
+  'contract',
+  'legal_entity_id',
+  'legal_entity_name',
+  'period_start',
+  'period_end',
+  'person_id',
+  'employee_no',
+  'leave_type_key',
+  'leave_type_name',
+  'paid',
+  'unit',
+  'days',
+  'requests',
+] as const
+
+export const PayrollHoursRow = z.object({
+  personId: z.uuid(),
+  /**
+   * Unique per **workspace**, not per entity (`hr_people_ws_empno_uq`), and nullable.
+   *
+   * Exported, and deliberately not the key: a group whose Turkish and Dutch providers each want their
+   * own numbering has nowhere to put the second number today, and `HrSettings.employeeNumberPrefix`
+   * is one workspace-wide prefix. A per-entity number is a real schema change and it is not v1's job
+   * — but the file must not pretend the number it carries is the provider's.
+   */
+  employeeNo: z.string().nullable(),
+  /** Exactly as stored: an erased person keeps their row and carries the erasure token. */
+  displayName: z.string(),
+  employmentType: z.string(),
+  fte: z.number(),
+  contractHoursWeek: z.number().nullable(),
+  costCenterCode: z.string().nullable(),
+  positionTitle: z.string().nullable(),
+  /** A joiner or leaver mid-period is the case a provider prorates. */
+  hiredOn: IsoDate.nullable(),
+  terminatedOn: IsoDate.nullable(),
+  /** True when more than one employment row overlapped this person's days in this entity. */
+  employmentChangedInPeriod: z.boolean(),
+  /** The denominator. Publish it or no total means anything. */
+  daySheets: z.number().int(),
+  scheduledMinutes: z.number().int(),
+  workedMinutes: z.number().int(),
+  scheduledWorkedMinutes: z.number().int(),
+  breakMinutes: z.number().int(),
+  overtimeMinutes: z.number().int(),
+  lateMinutes: z.number().int(),
+  earlyLeaveMinutes: z.number().int(),
+  /** Null where no ceiling was in force — an **empty CSV field**, never zero. */
+  beyondCapMinutes: z.number().int().nullable(),
+  cappedDays: z.number().int(),
+  uncappedDays: z.number().int(),
+  /** A locked period can still hold an unlocked day, so both travel per row. */
+  lockedDays: z.number().int(),
+  openDays: z.number().int(),
+  paidLeaveDays: z.number(),
+  unpaidLeaveDays: z.number(),
+})
+export type PayrollHoursRow = z.infer<typeof PayrollHoursRow>
+
+export const PayrollLeaveRow = z.object({
+  personId: z.uuid(),
+  employeeNo: z.string().nullable(),
+  leaveTypeKey: z.string(),
+  leaveTypeName: z.string(),
+  paid: z.boolean(),
+  unit: LeaveUnit,
+  /** Days, summed from `fraction`. Never minutes: `MINUTES_PER_DAY` is a hardcoded eight hours. */
+  days: z.number(),
+  requests: z.number().int(),
+})
+export type PayrollLeaveRow = z.infer<typeof PayrollLeaveRow>
+
+/** The headline figures over the whole population, so a screen shows a total before a file exists. */
+export const PayrollExportTotals = z.object({
+  people: z.number().int(),
+  daySheets: z.number().int(),
+  scheduledMinutes: z.number().int(),
+  workedMinutes: z.number().int(),
+  scheduledWorkedMinutes: z.number().int(),
+  breakMinutes: z.number().int(),
+  overtimeMinutes: z.number().int(),
+  lateMinutes: z.number().int(),
+  earlyLeaveMinutes: z.number().int(),
+  beyondCapMinutes: z.number().int().nullable(),
+  cappedDays: z.number().int(),
+  uncappedDays: z.number().int(),
+  lockedDays: z.number().int(),
+  openDays: z.number().int(),
+  paidLeaveDays: z.number(),
+  unpaidLeaveDays: z.number(),
+})
+export type PayrollExportTotals = z.infer<typeof PayrollExportTotals>
+
+/**
+ * Why this export will not be written.
+ *
+ * `payroll.export.preview` returns these so a screen can show them **before** anybody downloads
+ * anything; `payroll.export.v1` throws the first of them. `hr.period.not_locked` mirrors the spelling
+ * of `hr.period.locked`, which `PolicyService.assertOpen` throws pointed the other way.
+ */
+export const PayrollExportRefusalCode = z.enum([
+  /** The period is open, and `draft` was not asked for. Tonight's `reconcile-days` may move it. */
+  'hr.period.not_locked',
+  /** Nobody was employed by this entity on any day of the period. */
+  'hr.payroll.empty',
+  /** Somebody in the population has no employment row covering their days here. */
+  'hr.payroll.no_employment',
+])
+export type PayrollExportRefusalCode = z.infer<typeof PayrollExportRefusalCode>
+
+export const PayrollExportRefusal = z.object({
+  code: PayrollExportRefusalCode,
+  /** A sentence naming the fix, not a code a reader has to look up. */
+  message: z.string(),
+  /** Whose rows caused it, where that is a fact about people. Empty otherwise. */
+  personIds: z.array(z.uuid()),
+})
+export type PayrollExportRefusal = z.infer<typeof PayrollExportRefusal>
+
+/**
+ * How the bytes are written, restated in the manifest so a reader never has to infer it.
+ *
+ * UTF-8 **with a byte order mark**, because Excel on Windows mangles Turkish and Persian names
+ * without one and this module ships country packs for both. Comma, CRLF, RFC 4180 quoting, ISO dates,
+ * `.` decimal separator with two places on `fte` and on leave-day fractions. Every one of these is
+ * frozen for as long as v1 is published.
+ */
+export const PayrollExportFormat = z.object({
+  encoding: z.literal('utf-8'),
+  byteOrderMark: z.literal(true),
+  delimiter: z.literal(','),
+  lineEnding: z.literal('crlf'),
+  quoting: z.literal('rfc4180'),
+  decimalSeparator: z.literal('.'),
+  decimalPlaces: z.literal(2),
+  dateFormat: z.literal('iso-8601'),
+})
+export type PayrollExportFormat = z.infer<typeof PayrollExportFormat>
+
+export const PayrollExportManifest = z.object({
+  contract: z.literal(PAYROLL_EXPORT_CONTRACT),
+  generatedAt: Timestamp,
+  /** Provenance — the platform version that wrote the file. Never the contract identity. */
+  kernVersion: z.string(),
+  /**
+   * `draft` when the caller asked for an open period, `final` otherwise.
+   *
+   * Not a warning in a toast: the toast does not travel with the CSV, and the CSV is what reaches the
+   * provider. So the filename says `DRAFT` too, and every row carries a non-zero `open_days`.
+   */
+  finality: z.enum(['final', 'draft']),
+  draft: z.boolean(),
+  legalEntityId: z.uuid(),
+  legalEntityName: z.string(),
+  /** The fields a filing is made under, so the file states which authority it belongs to. */
+  country: z.string(),
+  currency: z.string().nullable(),
+  periodId: z.uuid(),
+  periodStart: IsoDate,
+  periodEnd: IsoDate,
+  periodStatus: z.enum(['open', 'locked']),
+  /** Everybody the entity employed over the period — the denominator, and never omitted. */
+  population: z.number().int(),
+  /** How many of them have a day sheet or an approved leave day behind the figures. */
+  counted: z.number().int(),
+  /** Which grants produced this population. Two managers must not read one title over two sets. */
+  scope: ReportScope,
+  /** Locked against open day sheets. A locked period can still contain an unlocked day. */
+  attendance: ReportFinality,
+  /** 480. Published so a reader converting days to minutes uses the module's day, not their own. */
+  dayLengthMinutes: z.number().int(),
+  format: PayrollExportFormat,
+  files: z.array(z.object({ name: z.string(), columns: z.array(z.string()), rows: z.number().int() })),
+})
+export type PayrollExportManifest = z.infer<typeof PayrollExportManifest>
+
+export const PayrollExportFile = z.object({
+  name: z.string(),
+  contentType: z.string(),
+  /** The whole file as text. The CSVs begin with a byte order mark and end every line with CRLF. */
+  content: z.string(),
+})
+export type PayrollExportFile = z.infer<typeof PayrollExportFile>
+
+/**
+ * What `payroll.export.v1` hands back: the manifest, and the three files beside each other.
+ *
+ * Synchronous and streamed into the response rather than delivered as a job, and that is a checked
+ * constraint rather than a preference. Core exposes exactly one file procedure over the broker —
+ * `files.get` — so a module cannot mint a `FileObject`; `createUpload` requires a user principal and
+ * a background job has none. Writing bytes straight into `kernel.storage` would produce an object
+ * invisible to `core.files.*`, absent from the workspace file list, uncounted by the `storageBytes`
+ * entitlement and deleted by nothing — orphans by design. Async delivery becomes possible the day
+ * core grows a procedure that mints a file for a service principal, and that is a change to core.
+ */
+export const PayrollExport = z.object({
+  manifest: PayrollExportManifest,
+  /** `hours.csv`, `leave.csv`, `manifest.json`. Three, always, for as long as v1 exists. */
+  files: z.array(PayrollExportFile).length(3),
+})
+export type PayrollExport = z.infer<typeof PayrollExport>
+
+/**
+ * The same rows as JSON, with no file and no refusal thrown.
+ *
+ * So a screen can show the totals and the reasons it would be refused before anybody downloads
+ * anything. `exportable` is `refusals.length === 0`.
+ */
+export const PayrollExportPreview = z.object({
+  manifest: PayrollExportManifest,
+  refusals: z.array(PayrollExportRefusal),
+  exportable: z.boolean(),
+  totals: PayrollExportTotals,
+  hours: z.array(PayrollHoursRow),
+  leave: z.array(PayrollLeaveRow),
+})
+export type PayrollExportPreview = z.infer<typeof PayrollExportPreview>

package/src/contract/index.ts

@@ -10,11 +10,13 @@ export * from './approvals.js'
 export * from './attendance.js'
 export * from './capabilities.js'
 export * from './events.js'
+export * from './exports.js'
 export * from './leave.js'
 export * from './models.js'
 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
   {
@@ -285,9 +296,39 @@ export const hrPermissions = definePermissions([
   // Why a key of its own at all, when the two above would do: a reports surface is the one place a
   // whole population's figures are put in front of somebody in a form that goes into a payroll or a
   // performance conversation, and a workspace has to be able to grant a manager their team's day
-  // sheets without granting them that. There is deliberately **no** `hr.report.export`: nothing in
-  // this module writes a file, and a key gating a button nobody built is the thing the removed
-  // `hr.overtime.*` block below is a note about.
+  // sheets without granting them that. There is still no `hr.report.export` — the reports write no
+  // file — and the one thing in this module that does have its own key below.
+
+  // ---------------------------------------------------------------- payroll export
+  {
+    key: 'hr.payroll.export',
+    label: 'Export a payroll file',
+    description:
+      "Writes every employee's period, employment basis and hours out of Kern as CSV, for one " +
+      'legal entity. The file leaves the building. Grant to whoever files payroll, not to a role.',
+    scope: 'workspace',
+    // Nobody by default, like `hr.person.view_sensitive` and `hr.privacy.manage`. An owner passes
+    // every check regardless; every other holder had to be given it deliberately.
+    defaultRoles: [],
+    dangerous: true,
+  },
+  // This is the key the note above says did not exist yet, and it exists now because something
+  // finally writes a file: `payroll.export.v1` and `payroll.export.preview` both ship gated on it in
+  // this same change, which is the rule — a capability, a permission key and an entitlement key are
+  // all lies until something enforces them.
+  //
+  // It is not `hr.report.export`, and the difference is not cosmetic. A report is a screen somebody
+  // reads inside Kern; this is a file that leaves it, addressed to an organisation that will pay
+  // people from it. The two audiences are different and so is the blast radius, so a workspace has to
+  // be able to grant every report without granting this.
+  //
+  // Like the reports, it is a **second** check rather than a replacement: both procedures also ask
+  // for `hr.attendance.view_team` (the hours file) and `hr.leave.view_team` (the leave file), because
+  // an export must not answer what the row-level procedure would refuse.
+  //
+  // It reads no sensitive field, so it writes no `sensitive_access_log` row. A later version that
+  // adds `iban` becomes a bulk sensitive read and owes one row per person with `via: 'export'` — the
+  // enum member already exists — and its own key on top of this one.
 
   // ---------------------------------------------------------------- policies and periods
   {
@@ -395,6 +436,7 @@ export const HR_PERMISSIONS = {
   attendanceViewTeam: 'hr.attendance.view_team',
   attendanceManage: 'hr.attendance.manage',
   reportView: 'hr.report.view',
+  payrollExport: 'hr.payroll.export',
   policyView: 'hr.policy.view',
   policyManage: 'hr.policy.manage',
   periodManage: 'hr.period.manage',