@kernhq/module-hr 0.18.0 → 0.19.0

package/dist/contract/capabilities.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"capabilities.d.ts","sourceRoot":"","sources":["../../src/contract/capabilities.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,eAAO,MAAM,cAAc;;;;;;;;GA2GzB,CAAA;AAEF,MAAM,MAAM,cAAc,GAAG,CAAC,OAAO,cAAc,CAAC,CAAC,MAAM,CAAC,CAAC,IAAI,CAAC,CAAA;AAElE;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,kBAAkB,GAAI,IAAI,MAAM,WAAmB,CAAA;AAChE,eAAO,MAAM,wBAAwB,GAAI,IAAI,MAAM,WAAwB,CAAA;AAE3E;;;;;;;;;GASG;AACH,eAAO,MAAM,sBAAsB,EAAE,MAAM,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,CAmFpE,CAAA"}
+{"version":3,"file":"capabilities.d.ts","sourceRoot":"","sources":["../../src/contract/capabilities.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,eAAO,MAAM,cAAc;;;;;;;;GA0HzB,CAAA;AAEF,MAAM,MAAM,cAAc,GAAG,CAAC,OAAO,cAAc,CAAC,CAAC,MAAM,CAAC,CAAC,IAAI,CAAC,CAAA;AAElE;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,kBAAkB,GAAI,IAAI,MAAM,WAAmB,CAAA;AAChE,eAAO,MAAM,wBAAwB,GAAI,IAAI,MAAM,WAAwB,CAAA;AAE3E;;;;;;;;;GASG;AACH,eAAO,MAAM,sBAAsB,EAAE,MAAM,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,CA8FpE,CAAA"}

package/dist/contract/capabilities.js

@@ -129,6 +129,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,
+    },
 ]);
 /**
  * The message ids a screen reads a capability's `label` and `description` through.
@@ -184,6 +199,7 @@ export const hrCapabilityProcedures = {
         'calendars.workingDays',
     ],
     documents: ['documents.list', 'documents.attach', 'documents.remove'],
+    payroll_export: ['payroll.export.v1', 'payroll.export.preview'],
     leave: [
         'leave.types.list',
         'leave.types.create',
@@ -198,6 +214,9 @@ export const hrCapabilityProcedures = {
         'leave.requests.create',
         'leave.requests.cancel',
         'leave.team.calendar',
+        // Same reason as the attendance reports above: a balance report in a workspace with no leave is
+        // not zero days, it is a question that does not apply.
+        'reports.leaveBalance',
     ],
     attendance: [
         'attendance.state',
@@ -216,6 +235,13 @@ export const hrCapabilityProcedures = {
         'attendance.schedules.assign',
         'attendance.regularizations.list',
         'attendance.regularizations.request',
+        // The three reports built from `attendance_days`. A workspace that never switched attendance on
+        // has no day sheet to aggregate, so a report over it would answer zero rather than 404 — which
+        // is the shape of lie this map exists to prevent: a number is a worse "not available" than an
+        // error, because it looks like an answer.
+        'reports.attendance',
+        'reports.overtime',
+        'reports.absence',
     ],
     leave_accrual: [
         'policies.list',

package/dist/contract/capabilities.js.map

@@ -1 +1 @@
-{"version":3,"file":"capabilities.js","sourceRoot":"","sources":["../../src/contract/capabilities.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAA;AAEtD;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,MAAM,CAAC,MAAM,cAAc,GAAG,kBAAkB,CAAC;IAC/C;QACE,EAAE,EAAE,MAAM;QACV,KAAK,EAAE,QAAQ;QACf,WAAW,EAAE,6DAA6D;QAC1E,QAAQ,EAAE,IAAI;QACd,KAAK,EAAE,CAAC;KACT;IACD;QACE,EAAE,EAAE,SAAS;QACb,KAAK,EAAE,SAAS;QAChB,WAAW,EAAE,+EAA+E;QAC5F,SAAS,EAAE,CAAC,MAAM,CAAC;QACnB,iGAAiG;QACjG,+FAA+F;QAC/F,4FAA4F;QAC5F,+FAA+F;QAC/F,+BAA+B;QAC/B,cAAc,EAAE,KAAK;QACrB,KAAK,EAAE,CAAC;KACT;IACD;QACE,EAAE,EAAE,gBAAgB;QACpB,KAAK,EAAE,gBAAgB;QACvB,WAAW,EAAE,mEAAmE;QAChF,iGAAiG;QACjG,4EAA4E;QAC5E,SAAS,EAAE,CAAC,SAAS,CAAC;QACtB,cAAc,EAAE,KAAK;QACrB,KAAK,EAAE,CAAC;KACT;IACD;QACE,EAAE,EAAE,WAAW;QACf,KAAK,EAAE,mBAAmB;QAC1B,WAAW,EAAE,wDAAwD;QACrE,SAAS,EAAE,CAAC,MAAM,CAAC;QACnB,gGAAgG;QAChG,4CAA4C;QAC5C,cAAc,EAAE,IAAI;QACpB,KAAK,EAAE,CAAC;KACT;IACD;QACE,EAAE,EAAE,OAAO;QACX,KAAK,EAAE,OAAO;QACd,WAAW,EAAE,mDAAmD;QAChE,SAAS,EAAE,CAAC,MAAM,EAAE,WAAW,CAAC;QAChC,6FAA6F;QAC7F,6EAA6E;QAC7E,cAAc,EAAE,IAAI;QACpB,KAAK,EAAE,CAAC;KACT;IACD;QACE,EAAE,EAAE,eAAe;QACnB,KAAK,EAAE,SAAS;QAChB,WAAW,EAAE,gEAAgE;QAC7E,SAAS,EAAE,CAAC,OAAO,CAAC;QACpB,8FAA8F;QAC9F,mFAAmF;QACnF,cAAc,EAAE,KAAK;QACrB,sFAAsF;QACtF,2FAA2F;QAC3F,yEAAyE;QACzE,6FAA6F;QAC7F,gGAAgG;QAChG,0FAA0F;QAC1F,+FAA+F;QAC/F,2FAA2F;QAC3F,0FAA0F;QAC1F,uFAAuF;QACvF,KAAK,EAAE,CAAC;KACT;IACD;QACE,EAAE,EAAE,SAAS;QACb,KAAK,EAAE,iBAAiB;QACxB,WAAW,EAAE,4DAA4D;QACzE,SAAS,EAAE,CAAC,MAAM,CAAC;QACnB,cAAc,EAAE,KAAK;QACrB,KAAK,EAAE,CAAC;KACT;IACD;QACE,EAAE,EAAE,WAAW;QACf,KAAK,EAAE,iBAAiB;QACxB,WAAW,EAAE,yEAAyE;QACtF,SAAS,EAAE,CAAC,MAAM,CAAC;QACnB,8FAA8F;QAC9F,yEAAyE;QACzE,cAAc,EAAE,KAAK;QACrB,KAAK,EAAE,CAAC;KACT;IACD;QACE,EAAE,EAAE,YAAY;QAChB,KAAK,EAAE,YAAY;QACnB,WAAW,EAAE,+CAA+C;QAC5D,SAAS,EAAE,CAAC,MAAM,EAAE,WAAW,CAAC;QAChC,4FAA4F;QAC5F,yEAAyE;QACzE,cAAc,EAAE,KAAK;QACrB,KAAK,EAAE,CAAC;KACT;IACD;QACE,EAAE,EAAE,WAAW;QACf,KAAK,EAAE,oBAAoB;QAC3B,WAAW,EAAE,iEAAiE;QAC9E,SAAS,EAAE,CAAC,MAAM,CAAC;QACnB,cAAc,EAAE,KAAK;QACrB,KAAK,EAAE,CAAC;KACT;CACF,CAAC,CAAA;AAIF;;;;;;;;;;;;;GAaG;AACH,MAAM,CAAC,MAAM,kBAAkB,GAAG,CAAC,EAAU,EAAE,EAAE,CAAC,UAAU,EAAE,EAAE,CAAA;AAChE,MAAM,CAAC,MAAM,wBAAwB,GAAG,CAAC,EAAU,EAAE,EAAE,CAAC,UAAU,EAAE,OAAO,CAAA;AAE3E;;;;;;;;;GASG;AACH,MAAM,CAAC,MAAM,sBAAsB,GAAsC;IACvE,OAAO,EAAE;QACP,cAAc;QACd,aAAa;QACb,gBAAgB;QAChB,gBAAgB;QAChB,iBAAiB;QACjB,oBAAoB;QACpB,gBAAgB;QAChB,kBAAkB;QAClB,gBAAgB;KACjB;IACD,cAAc,EAAE,CAAC,eAAe,EAAE,cAAc,EAAE,iBAAiB,EAAE,iBAAiB,EAAE,kBAAkB,CAAC;IAC3G,SAAS,EAAE;QACT,gBAAgB;QAChB,eAAe;QACf,kBAAkB;QAClB,kBAAkB;QAClB,mBAAmB;QACnB,qBAAqB;QACrB,oBAAoB;QACpB,uBAAuB;QACvB,uBAAuB;QACvB,wBAAwB;QACxB,sBAAsB;QACtB,uBAAuB;KACxB;IACD,SAAS,EAAE,CAAC,gBAAgB,EAAE,kBAAkB,EAAE,kBAAkB,CAAC;IACrE,KAAK,EAAE;QACL,kBAAkB;QAClB,oBAAoB;QACpB,oBAAoB;QACpB,qBAAqB;QACrB,mBAAmB;QACnB,mBAAmB;QACnB,cAAc;QACd,qBAAqB;QACrB,oBAAoB;QACpB,yBAAyB;QACzB,uBAAuB;QACvB,uBAAuB;QACvB,qBAAqB;KACtB;IACD,UAAU,EAAE;QACV,kBAAkB;QAClB,oBAAoB;QACpB,qBAAqB;QACrB,uBAAuB;QACvB,qBAAqB;QACrB,yBAAyB;QACzB,yBAAyB;QACzB,sBAAsB;QACtB,2BAA2B;QAC3B,2BAA2B;QAC3B,6BAA6B;QAC7B,6BAA6B;QAC7B,8BAA8B;QAC9B,6BAA6B;QAC7B,iCAAiC;QACjC,oCAAoC;KACrC;IACD,aAAa,EAAE;QACb,eAAe;QACf,cAAc;QACd,iBAAiB;QACjB,iBAAiB;QACjB,kBAAkB;QAClB,iBAAiB;QACjB,mBAAmB;QACnB,qBAAqB;QACrB,iBAAiB;QACjB,aAAa;KACd;IACD,OAAO,EAAE,CAAC,cAAc,EAAE,gBAAgB,EAAE,cAAc,EAAE,gBAAgB,CAAC;IAC7E,SAAS,EAAE;QACT,uBAAuB;QACvB,yBAAyB;QACzB,yBAAyB;QACzB,0BAA0B;QAC1B,oBAAoB;QACpB,4BAA4B;QAC5B,uBAAuB;KACxB;CACF,CAAA"}
+{"version":3,"file":"capabilities.js","sourceRoot":"","sources":["../../src/contract/capabilities.ts"],"names":[],"mappings":"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"}

package/dist/contract/exports.d.ts

@@ -0,0 +1,459 @@
+import { z } from 'zod';
+/**
+ * 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 declare 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 declare const PAYROLL_HOURS_COLUMNS: readonly ["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"];
+/**
+ * `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 declare const PAYROLL_LEAVE_COLUMNS: readonly ["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"];
+export declare const PayrollHoursRow: z.ZodObject<{
+    personId: z.ZodUUID;
+    employeeNo: z.ZodNullable<z.ZodString>;
+    displayName: z.ZodString;
+    employmentType: z.ZodString;
+    fte: z.ZodNumber;
+    contractHoursWeek: z.ZodNullable<z.ZodNumber>;
+    costCenterCode: z.ZodNullable<z.ZodString>;
+    positionTitle: z.ZodNullable<z.ZodString>;
+    hiredOn: z.ZodNullable<z.ZodISODate>;
+    terminatedOn: z.ZodNullable<z.ZodISODate>;
+    employmentChangedInPeriod: z.ZodBoolean;
+    daySheets: z.ZodNumber;
+    scheduledMinutes: z.ZodNumber;
+    workedMinutes: z.ZodNumber;
+    scheduledWorkedMinutes: z.ZodNumber;
+    breakMinutes: z.ZodNumber;
+    overtimeMinutes: z.ZodNumber;
+    lateMinutes: z.ZodNumber;
+    earlyLeaveMinutes: z.ZodNumber;
+    beyondCapMinutes: z.ZodNullable<z.ZodNumber>;
+    cappedDays: z.ZodNumber;
+    uncappedDays: z.ZodNumber;
+    lockedDays: z.ZodNumber;
+    openDays: z.ZodNumber;
+    paidLeaveDays: z.ZodNumber;
+    unpaidLeaveDays: z.ZodNumber;
+}, z.core.$strip>;
+export type PayrollHoursRow = z.infer<typeof PayrollHoursRow>;
+export declare const PayrollLeaveRow: z.ZodObject<{
+    personId: z.ZodUUID;
+    employeeNo: z.ZodNullable<z.ZodString>;
+    leaveTypeKey: z.ZodString;
+    leaveTypeName: z.ZodString;
+    paid: z.ZodBoolean;
+    unit: z.ZodEnum<{
+        half_day: "half_day";
+        day: "day";
+        hour: "hour";
+    }>;
+    days: z.ZodNumber;
+    requests: z.ZodNumber;
+}, z.core.$strip>;
+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 declare const PayrollExportTotals: z.ZodObject<{
+    people: z.ZodNumber;
+    daySheets: z.ZodNumber;
+    scheduledMinutes: z.ZodNumber;
+    workedMinutes: z.ZodNumber;
+    scheduledWorkedMinutes: z.ZodNumber;
+    breakMinutes: z.ZodNumber;
+    overtimeMinutes: z.ZodNumber;
+    lateMinutes: z.ZodNumber;
+    earlyLeaveMinutes: z.ZodNumber;
+    beyondCapMinutes: z.ZodNullable<z.ZodNumber>;
+    cappedDays: z.ZodNumber;
+    uncappedDays: z.ZodNumber;
+    lockedDays: z.ZodNumber;
+    openDays: z.ZodNumber;
+    paidLeaveDays: z.ZodNumber;
+    unpaidLeaveDays: z.ZodNumber;
+}, z.core.$strip>;
+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 declare const PayrollExportRefusalCode: z.ZodEnum<{
+    "hr.period.not_locked": "hr.period.not_locked";
+    "hr.payroll.empty": "hr.payroll.empty";
+    "hr.payroll.no_employment": "hr.payroll.no_employment";
+}>;
+export type PayrollExportRefusalCode = z.infer<typeof PayrollExportRefusalCode>;
+export declare const PayrollExportRefusal: z.ZodObject<{
+    code: z.ZodEnum<{
+        "hr.period.not_locked": "hr.period.not_locked";
+        "hr.payroll.empty": "hr.payroll.empty";
+        "hr.payroll.no_employment": "hr.payroll.no_employment";
+    }>;
+    message: z.ZodString;
+    personIds: z.ZodArray<z.ZodUUID>;
+}, z.core.$strip>;
+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 declare const PayrollExportFormat: z.ZodObject<{
+    encoding: z.ZodLiteral<"utf-8">;
+    byteOrderMark: z.ZodLiteral<true>;
+    delimiter: z.ZodLiteral<",">;
+    lineEnding: z.ZodLiteral<"crlf">;
+    quoting: z.ZodLiteral<"rfc4180">;
+    decimalSeparator: z.ZodLiteral<".">;
+    decimalPlaces: z.ZodLiteral<2>;
+    dateFormat: z.ZodLiteral<"iso-8601">;
+}, z.core.$strip>;
+export type PayrollExportFormat = z.infer<typeof PayrollExportFormat>;
+export declare const PayrollExportManifest: z.ZodObject<{
+    contract: z.ZodLiteral<"kern-payroll-v1">;
+    generatedAt: z.ZodISODateTime;
+    kernVersion: z.ZodString;
+    finality: z.ZodEnum<{
+        draft: "draft";
+        final: "final";
+    }>;
+    draft: z.ZodBoolean;
+    legalEntityId: z.ZodUUID;
+    legalEntityName: z.ZodString;
+    country: z.ZodString;
+    currency: z.ZodNullable<z.ZodString>;
+    periodId: z.ZodUUID;
+    periodStart: z.ZodISODate;
+    periodEnd: z.ZodISODate;
+    periodStatus: z.ZodEnum<{
+        locked: "locked";
+        open: "open";
+    }>;
+    population: z.ZodNumber;
+    counted: z.ZodNumber;
+    scope: z.ZodObject<{
+        permissions: z.ZodArray<z.ZodString>;
+        askedAt: z.ZodLiteral<"workspace">;
+    }, z.core.$strip>;
+    attendance: z.ZodObject<{
+        lockedDays: z.ZodNumber;
+        openDays: z.ZodNumber;
+        final: z.ZodBoolean;
+        firstOpenDay: z.ZodNullable<z.ZodISODate>;
+        lastLockedDay: z.ZodNullable<z.ZodISODate>;
+    }, z.core.$strip>;
+    dayLengthMinutes: z.ZodNumber;
+    format: z.ZodObject<{
+        encoding: z.ZodLiteral<"utf-8">;
+        byteOrderMark: z.ZodLiteral<true>;
+        delimiter: z.ZodLiteral<",">;
+        lineEnding: z.ZodLiteral<"crlf">;
+        quoting: z.ZodLiteral<"rfc4180">;
+        decimalSeparator: z.ZodLiteral<".">;
+        decimalPlaces: z.ZodLiteral<2>;
+        dateFormat: z.ZodLiteral<"iso-8601">;
+    }, z.core.$strip>;
+    files: z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        columns: z.ZodArray<z.ZodString>;
+        rows: z.ZodNumber;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type PayrollExportManifest = z.infer<typeof PayrollExportManifest>;
+export declare const PayrollExportFile: z.ZodObject<{
+    name: z.ZodString;
+    contentType: z.ZodString;
+    content: z.ZodString;
+}, z.core.$strip>;
+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 declare const PayrollExport: z.ZodObject<{
+    manifest: z.ZodObject<{
+        contract: z.ZodLiteral<"kern-payroll-v1">;
+        generatedAt: z.ZodISODateTime;
+        kernVersion: z.ZodString;
+        finality: z.ZodEnum<{
+            draft: "draft";
+            final: "final";
+        }>;
+        draft: z.ZodBoolean;
+        legalEntityId: z.ZodUUID;
+        legalEntityName: z.ZodString;
+        country: z.ZodString;
+        currency: z.ZodNullable<z.ZodString>;
+        periodId: z.ZodUUID;
+        periodStart: z.ZodISODate;
+        periodEnd: z.ZodISODate;
+        periodStatus: z.ZodEnum<{
+            locked: "locked";
+            open: "open";
+        }>;
+        population: z.ZodNumber;
+        counted: z.ZodNumber;
+        scope: z.ZodObject<{
+            permissions: z.ZodArray<z.ZodString>;
+            askedAt: z.ZodLiteral<"workspace">;
+        }, z.core.$strip>;
+        attendance: z.ZodObject<{
+            lockedDays: z.ZodNumber;
+            openDays: z.ZodNumber;
+            final: z.ZodBoolean;
+            firstOpenDay: z.ZodNullable<z.ZodISODate>;
+            lastLockedDay: z.ZodNullable<z.ZodISODate>;
+        }, z.core.$strip>;
+        dayLengthMinutes: z.ZodNumber;
+        format: z.ZodObject<{
+            encoding: z.ZodLiteral<"utf-8">;
+            byteOrderMark: z.ZodLiteral<true>;
+            delimiter: z.ZodLiteral<",">;
+            lineEnding: z.ZodLiteral<"crlf">;
+            quoting: z.ZodLiteral<"rfc4180">;
+            decimalSeparator: z.ZodLiteral<".">;
+            decimalPlaces: z.ZodLiteral<2>;
+            dateFormat: z.ZodLiteral<"iso-8601">;
+        }, z.core.$strip>;
+        files: z.ZodArray<z.ZodObject<{
+            name: z.ZodString;
+            columns: z.ZodArray<z.ZodString>;
+            rows: z.ZodNumber;
+        }, z.core.$strip>>;
+    }, z.core.$strip>;
+    files: z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        contentType: z.ZodString;
+        content: z.ZodString;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+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 declare const PayrollExportPreview: z.ZodObject<{
+    manifest: z.ZodObject<{
+        contract: z.ZodLiteral<"kern-payroll-v1">;
+        generatedAt: z.ZodISODateTime;
+        kernVersion: z.ZodString;
+        finality: z.ZodEnum<{
+            draft: "draft";
+            final: "final";
+        }>;
+        draft: z.ZodBoolean;
+        legalEntityId: z.ZodUUID;
+        legalEntityName: z.ZodString;
+        country: z.ZodString;
+        currency: z.ZodNullable<z.ZodString>;
+        periodId: z.ZodUUID;
+        periodStart: z.ZodISODate;
+        periodEnd: z.ZodISODate;
+        periodStatus: z.ZodEnum<{
+            locked: "locked";
+            open: "open";
+        }>;
+        population: z.ZodNumber;
+        counted: z.ZodNumber;
+        scope: z.ZodObject<{
+            permissions: z.ZodArray<z.ZodString>;
+            askedAt: z.ZodLiteral<"workspace">;
+        }, z.core.$strip>;
+        attendance: z.ZodObject<{
+            lockedDays: z.ZodNumber;
+            openDays: z.ZodNumber;
+            final: z.ZodBoolean;
+            firstOpenDay: z.ZodNullable<z.ZodISODate>;
+            lastLockedDay: z.ZodNullable<z.ZodISODate>;
+        }, z.core.$strip>;
+        dayLengthMinutes: z.ZodNumber;
+        format: z.ZodObject<{
+            encoding: z.ZodLiteral<"utf-8">;
+            byteOrderMark: z.ZodLiteral<true>;
+            delimiter: z.ZodLiteral<",">;
+            lineEnding: z.ZodLiteral<"crlf">;
+            quoting: z.ZodLiteral<"rfc4180">;
+            decimalSeparator: z.ZodLiteral<".">;
+            decimalPlaces: z.ZodLiteral<2>;
+            dateFormat: z.ZodLiteral<"iso-8601">;
+        }, z.core.$strip>;
+        files: z.ZodArray<z.ZodObject<{
+            name: z.ZodString;
+            columns: z.ZodArray<z.ZodString>;
+            rows: z.ZodNumber;
+        }, z.core.$strip>>;
+    }, z.core.$strip>;
+    refusals: z.ZodArray<z.ZodObject<{
+        code: z.ZodEnum<{
+            "hr.period.not_locked": "hr.period.not_locked";
+            "hr.payroll.empty": "hr.payroll.empty";
+            "hr.payroll.no_employment": "hr.payroll.no_employment";
+        }>;
+        message: z.ZodString;
+        personIds: z.ZodArray<z.ZodUUID>;
+    }, z.core.$strip>>;
+    exportable: z.ZodBoolean;
+    totals: z.ZodObject<{
+        people: z.ZodNumber;
+        daySheets: z.ZodNumber;
+        scheduledMinutes: z.ZodNumber;
+        workedMinutes: z.ZodNumber;
+        scheduledWorkedMinutes: z.ZodNumber;
+        breakMinutes: z.ZodNumber;
+        overtimeMinutes: z.ZodNumber;
+        lateMinutes: z.ZodNumber;
+        earlyLeaveMinutes: z.ZodNumber;
+        beyondCapMinutes: z.ZodNullable<z.ZodNumber>;
+        cappedDays: z.ZodNumber;
+        uncappedDays: z.ZodNumber;
+        lockedDays: z.ZodNumber;
+        openDays: z.ZodNumber;
+        paidLeaveDays: z.ZodNumber;
+        unpaidLeaveDays: z.ZodNumber;
+    }, z.core.$strip>;
+    hours: z.ZodArray<z.ZodObject<{
+        personId: z.ZodUUID;
+        employeeNo: z.ZodNullable<z.ZodString>;
+        displayName: z.ZodString;
+        employmentType: z.ZodString;
+        fte: z.ZodNumber;
+        contractHoursWeek: z.ZodNullable<z.ZodNumber>;
+        costCenterCode: z.ZodNullable<z.ZodString>;
+        positionTitle: z.ZodNullable<z.ZodString>;
+        hiredOn: z.ZodNullable<z.ZodISODate>;
+        terminatedOn: z.ZodNullable<z.ZodISODate>;
+        employmentChangedInPeriod: z.ZodBoolean;
+        daySheets: z.ZodNumber;
+        scheduledMinutes: z.ZodNumber;
+        workedMinutes: z.ZodNumber;
+        scheduledWorkedMinutes: z.ZodNumber;
+        breakMinutes: z.ZodNumber;
+        overtimeMinutes: z.ZodNumber;
+        lateMinutes: z.ZodNumber;
+        earlyLeaveMinutes: z.ZodNumber;
+        beyondCapMinutes: z.ZodNullable<z.ZodNumber>;
+        cappedDays: z.ZodNumber;
+        uncappedDays: z.ZodNumber;
+        lockedDays: z.ZodNumber;
+        openDays: z.ZodNumber;
+        paidLeaveDays: z.ZodNumber;
+        unpaidLeaveDays: z.ZodNumber;
+    }, z.core.$strip>>;
+    leave: z.ZodArray<z.ZodObject<{
+        personId: z.ZodUUID;
+        employeeNo: z.ZodNullable<z.ZodString>;
+        leaveTypeKey: z.ZodString;
+        leaveTypeName: z.ZodString;
+        paid: z.ZodBoolean;
+        unit: z.ZodEnum<{
+            half_day: "half_day";
+            day: "day";
+            hour: "hour";
+        }>;
+        days: z.ZodNumber;
+        requests: z.ZodNumber;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type PayrollExportPreview = z.infer<typeof PayrollExportPreview>;
+//# sourceMappingURL=exports.d.ts.map

package/dist/contract/exports.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"exports.d.ts","sourceRoot":"","sources":["../../src/contract/exports.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAA;AAKvB;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAEH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,eAAO,MAAM,uBAAuB,oBAAoB,CAAA;AAExD;;;;;;;;;;;;;;;;;;;GAmBG;AACH,eAAO,MAAM,qBAAqB,ojBAgCxB,CAAA;AAEV;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,qBAAqB,kMAcxB,CAAA;AAEV,eAAO,MAAM,eAAe;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAyC1B,CAAA;AACF,MAAM,MAAM,eAAe,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,eAAe,CAAC,CAAA;AAE7D,eAAO,MAAM,eAAe;;;;;;;;;;;;;iBAU1B,CAAA;AACF,MAAM,MAAM,eAAe,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,eAAe,CAAC,CAAA;AAE7D,sGAAsG;AACtG,eAAO,MAAM,mBAAmB;;;;;;;;;;;;;;;;;iBAiB9B,CAAA;AACF,MAAM,MAAM,mBAAmB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,mBAAmB,CAAC,CAAA;AAErE;;;;;;GAMG;AACH,eAAO,MAAM,wBAAwB;;;;EAOnC,CAAA;AACF,MAAM,MAAM,wBAAwB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,wBAAwB,CAAC,CAAA;AAE/E,eAAO,MAAM,oBAAoB;;;;;;;;iBAM/B,CAAA;AACF,MAAM,MAAM,oBAAoB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,oBAAoB,CAAC,CAAA;AAEvE;;;;;;;GAOG;AACH,eAAO,MAAM,mBAAmB;;;;;;;;;iBAS9B,CAAA;AACF,MAAM,MAAM,mBAAmB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,mBAAmB,CAAC,CAAA;AAErE,eAAO,MAAM,qBAAqB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAkChC,CAAA;AACF,MAAM,MAAM,qBAAqB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,qBAAqB,CAAC,CAAA;AAEzE,eAAO,MAAM,iBAAiB;;;;iBAK5B,CAAA;AACF,MAAM,MAAM,iBAAiB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,iBAAiB,CAAC,CAAA;AAEjE;;;;;;;;;;GAUG;AACH,eAAO,MAAM,aAAa;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAIxB,CAAA;AACF,MAAM,MAAM,aAAa,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,aAAa,CAAC,CAAA;AAEzD;;;;;GAKG;AACH,eAAO,MAAM,oBAAoB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAO/B,CAAA;AACF,MAAM,MAAM,oBAAoB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,oBAAoB,CAAC,CAAA"}