@kernhq/module-hr 0.18.1 → 0.20.0

package/dist/server/router.js

@@ -6,18 +6,20 @@ import { AccrualConfig, CarryForwardConfig, OvertimeConfig, RoundingConfig, Work
 import { accrueForPeriod } from '../policy/accrual.js';
 import { countWorkingDays, datesBetween, workingDays } from '../policy/calendar.js';
 import { COUNTRY_PACKS, packDays, packFor } from './packs/index.js';
-import { approvalChains, approvalDecisions, approvalRequests, approvalSteps, attendanceDays, calendarDays, calendars, costCenters, customFieldDefs, delegations, employments, leaveLedger, leaveRequestDays, leaveRequests, leaveTypes, legalEntities, officeAssignments, offices, orgUnits, people, peopleSensitive, periods, personDocuments, personHistory, policies, policyAssignments, positions, punches, regularizations, scheduleAssignments, schedules, } from './schema.js';
+import { approvalChains, approvalDecisions, approvalRequests, approvalSteps, attendanceDays, calendarDays, calendars, costCenters, customFieldDefs, delegations, employments, leaveLedger, leaveRequestDays, leaveRequests, leaveTypes, legalEntities, officeAssignments, offices, orgUnits, people, peopleSensitive, periods, personDocuments, personHistory, policies, policyAssignments, positions, punches, regularizations, rosterAssignments, rosterOverrides, rosterPatterns, rosterShifts, scheduleAssignments, schedules, } from './schema.js';
 import { forViewer, HrAccessService, seesRecordOf, visibleSet } from './services/access.js';
 import { ApprovalService } from './services/approvals.js';
 import { AttendanceService } from './services/attendance.js';
 import { accessLogSort, HrAuditService } from './services/audit.js';
 import { inForceOn, todayIso } from './services/db.js';
+import { assembleExport, exportManifest, PayrollExportService, } from './services/exports.js';
 import { LedgerService, MINUTES_PER_DAY, yearOf } from './services/ledger.js';
 import { PeopleService } from './services/people.js';
 import { hashConfig, PolicyService } from './services/policies.js';
 import { closingBalance, PrivacyService, RETENTION_CLASSES, stripSensitiveCustom, } from './services/privacy.js';
 import { absenceBasis, absenceSplit, capTotal, expectedDaysFor, mergeFinality, ReportsService, rangeRefusal, ratio, round2, } from './services/reports.js';
 import { DEFAULT_WORKING_WEEK, ResolveService } from './services/resolve.js';
+import { RosterService, rosterRefusal } from './services/rosters.js';
 const os = implement(hrContract).$context();
 /** Shared so the ordinary case — no sensitive custom fields defined — allocates nothing per page. */
 const NO_HIDDEN_FIELDS = new Set();
@@ -446,6 +448,8 @@ export function implement_(kernel) {
     const approvals = new ApprovalService(kernel, subjects.appliersFor(null));
     const privacy = new PrivacyService();
     const reports = new ReportsService(resolve);
+    const rosters = new RosterService();
+    const payroll = new PayrollExportService(reports);
     const audit = new HrAuditService(kernel, access);
     const db = kernel.database;
     const settingsOf = (workspaceId) => kernel.settings.module(workspaceId, MODULE_ID, HrSettings);
@@ -2420,6 +2424,411 @@ export function implement_(kernel) {
                 }),
             },
         },
+        // ================================================================= rosters
+        rosters: {
+            shifts: {
+                list: scoped.rosters.shifts.list
+                    .use(cap('rosters'))
+                    .use(requires('hr.attendance.view'))
+                    .handler(({ input }) => db.withWorkspace(input.workspaceId, async (tx) => {
+                    const where = [eq(rosterShifts.workspaceId, input.workspaceId)];
+                    if (!input.includeArchived)
+                        where.push(isNull(rosterShifts.archivedAt));
+                    const rows = await tx
+                        .select()
+                        .from(rosterShifts)
+                        .where(and(...where))
+                        .orderBy(asc(rosterShifts.startTime), asc(rosterShifts.name));
+                    return rows.map(toRosterShift);
+                })),
+                create: scoped.rosters.shifts.create
+                    .use(cap('rosters'))
+                    .use(requires('hr.attendance.manage'))
+                    .handler(async ({ input }) => {
+                    const row = await db.withWorkspace(input.workspaceId, async (tx) => {
+                        const [created] = await tx
+                            .insert(rosterShifts)
+                            .values({
+                            id: uuidv7(),
+                            workspaceId: input.workspaceId,
+                            name: input.name,
+                            code: input.code ?? null,
+                            startTime: input.start,
+                            endTime: input.end,
+                            breakMinutes: input.breakMinutes,
+                            graceInMinutes: input.graceInMinutes,
+                            graceOutMinutes: input.graceOutMinutes,
+                            color: input.color ?? null,
+                        })
+                            .returning();
+                        return created;
+                    });
+                    await changed(input.workspaceId, 'roster_shift', row.id, 'created');
+                    return toRosterShift(row);
+                }),
+                update: scoped.rosters.shifts.update
+                    .use(cap('rosters'))
+                    .use(requires('hr.attendance.manage'))
+                    .handler(async ({ input }) => {
+                    const row = await db.withWorkspace(input.workspaceId, async (tx) => {
+                        // Written out rather than looped over the patch, because two of the fields are named
+                        // differently in the contract and in the table: `start`/`end` read well on a shift and
+                        // are `start_time`/`end_time` in SQL, where `end` is a keyword.
+                        const set = { updatedAt: new Date() };
+                        if (input.name !== undefined)
+                            set.name = input.name;
+                        if (input.code !== undefined)
+                            set.code = input.code ?? null;
+                        if (input.start !== undefined)
+                            set.startTime = input.start;
+                        if (input.end !== undefined)
+                            set.endTime = input.end;
+                        if (input.breakMinutes !== undefined)
+                            set.breakMinutes = input.breakMinutes;
+                        if (input.graceInMinutes !== undefined)
+                            set.graceInMinutes = input.graceInMinutes;
+                        if (input.graceOutMinutes !== undefined)
+                            set.graceOutMinutes = input.graceOutMinutes;
+                        if (input.color !== undefined)
+                            set.color = input.color ?? null;
+                        const [updated] = await tx
+                            .update(rosterShifts)
+                            .set(set)
+                            .where(and(eq(rosterShifts.workspaceId, input.workspaceId), eq(rosterShifts.id, input.shiftId)))
+                            .returning();
+                        if (!updated)
+                            throw KernError.notFound('Shift');
+                        return updated;
+                    });
+                    await changed(input.workspaceId, 'roster_shift', row.id, 'updated');
+                    return toRosterShift(row);
+                }),
+                archive: scoped.rosters.shifts.archive
+                    .use(cap('rosters'))
+                    .use(requires('hr.attendance.manage'))
+                    .handler(async ({ input }) => {
+                    // Archived, not deleted. Rotations and stored overrides point at a shift by id, and a
+                    // deleted one would empty out every day it has ever appeared on — history included.
+                    await db.withWorkspace(input.workspaceId, (tx) => tx
+                        .update(rosterShifts)
+                        .set({ archivedAt: new Date(), updatedAt: new Date() })
+                        .where(and(eq(rosterShifts.workspaceId, input.workspaceId), eq(rosterShifts.id, input.shiftId))));
+                    await changed(input.workspaceId, 'roster_shift', input.shiftId, 'deleted');
+                    return { ok: true };
+                }),
+            },
+            patterns: {
+                list: scoped.rosters.patterns.list
+                    .use(cap('rosters'))
+                    .use(requires('hr.attendance.view'))
+                    .handler(({ input }) => db.withWorkspace(input.workspaceId, async (tx) => {
+                    const where = [eq(rosterPatterns.workspaceId, input.workspaceId)];
+                    if (!input.includeArchived)
+                        where.push(isNull(rosterPatterns.archivedAt));
+                    const rows = await tx
+                        .select()
+                        .from(rosterPatterns)
+                        .where(and(...where))
+                        .orderBy(asc(rosterPatterns.name));
+                    return rows.map(toRosterPattern);
+                })),
+                create: scoped.rosters.patterns.create
+                    .use(cap('rosters'))
+                    .use(requires('hr.attendance.manage'))
+                    .handler(async ({ input }) => {
+                    const row = await db.withWorkspace(input.workspaceId, async (tx) => {
+                        await rosters.assertShiftsExist(tx, input.workspaceId, input.days.flat());
+                        const [created] = await tx
+                            .insert(rosterPatterns)
+                            .values({
+                            id: uuidv7(),
+                            workspaceId: input.workspaceId,
+                            name: input.name,
+                            anchorDate: input.anchorDate,
+                            days: input.days.map((d) => [...d]),
+                        })
+                            .returning();
+                        return created;
+                    });
+                    await changed(input.workspaceId, 'roster_pattern', row.id, 'created');
+                    return toRosterPattern(row);
+                }),
+                update: scoped.rosters.patterns.update
+                    .use(cap('rosters'))
+                    .use(requires('hr.attendance.manage'))
+                    .handler(async ({ input }) => {
+                    const row = await db.withWorkspace(input.workspaceId, async (tx) => {
+                        if (input.days)
+                            await rosters.assertShiftsExist(tx, input.workspaceId, input.days.flat());
+                        const set = { updatedAt: new Date() };
+                        if (input.name !== undefined)
+                            set.name = input.name;
+                        if (input.anchorDate !== undefined)
+                            set.anchorDate = input.anchorDate;
+                        if (input.days !== undefined)
+                            set.days = input.days.map((d) => [...d]);
+                        const [updated] = await tx
+                            .update(rosterPatterns)
+                            .set(set)
+                            .where(and(eq(rosterPatterns.workspaceId, input.workspaceId), eq(rosterPatterns.id, input.patternId)))
+                            .returning();
+                        if (!updated)
+                            throw KernError.notFound('Rotation');
+                        return updated;
+                    });
+                    await changed(input.workspaceId, 'roster_pattern', row.id, 'updated');
+                    return toRosterPattern(row);
+                }),
+                archive: scoped.rosters.patterns.archive
+                    .use(cap('rosters'))
+                    .use(requires('hr.attendance.manage'))
+                    .handler(async ({ input }) => {
+                    // Hidden from the pickers, still read by everybody already on it. Archiving a rotation
+                    // people are working is not the same as taking them off it, and silently emptying their
+                    // roster would be a worse answer than leaving it visible until somebody unassigns them.
+                    await db.withWorkspace(input.workspaceId, (tx) => tx
+                        .update(rosterPatterns)
+                        .set({ archivedAt: new Date(), updatedAt: new Date() })
+                        .where(and(eq(rosterPatterns.workspaceId, input.workspaceId), eq(rosterPatterns.id, input.patternId))));
+                    await changed(input.workspaceId, 'roster_pattern', input.patternId, 'deleted');
+                    return { ok: true };
+                }),
+            },
+            assignments: scoped.rosters.assignments
+                .use(cap('rosters'))
+                .use(requires('hr.attendance.view_team'))
+                .handler(({ input }) => db.withWorkspace(input.workspaceId, async (tx) => {
+                const where = [eq(rosterAssignments.workspaceId, input.workspaceId)];
+                if (input.personId)
+                    where.push(eq(rosterAssignments.personId, input.personId));
+                if (input.patternId)
+                    where.push(eq(rosterAssignments.patternId, input.patternId));
+                const rows = await tx
+                    .select()
+                    .from(rosterAssignments)
+                    .where(and(...where))
+                    .orderBy(desc(rosterAssignments.effectiveFrom), asc(rosterAssignments.id));
+                return rows.map(toRosterAssignment);
+            })),
+            assign: scoped.rosters.assign
+                .use(cap('rosters'))
+                .use(requires('hr.attendance.manage'))
+                .handler(async ({ input }) => {
+                const rows = await db.withWorkspace(input.workspaceId, async (tx) => {
+                    const [pattern] = await tx
+                        .select()
+                        .from(rosterPatterns)
+                        .where(and(eq(rosterPatterns.workspaceId, input.workspaceId), eq(rosterPatterns.id, input.patternId)))
+                        .limit(1);
+                    if (!pattern)
+                        throw KernError.notFound('Rotation');
+                    const personIds = [...new Set(input.personIds)];
+                    const known = await tx
+                        .select({ id: people.id, displayName: people.displayName })
+                        .from(people)
+                        .where(and(eq(people.workspaceId, input.workspaceId), inArray(people.id, personIds)));
+                    if (known.length !== personIds.length)
+                        throw KernError.badRequest('This list names somebody who is not in this workspace.');
+                    const nameOf = new Map(known.map((p) => [p.id, p.displayName]));
+                    // An assignment already running when this one starts is closed the day before, which is
+                    // how "which rotation was she on in March" stays answerable.
+                    await tx
+                        .update(rosterAssignments)
+                        .set({ effectiveTo: sql `${input.effectiveFrom}::date - 1` })
+                        .where(and(eq(rosterAssignments.workspaceId, input.workspaceId), inArray(rosterAssignments.personId, personIds), lte(rosterAssignments.effectiveFrom, sql `${input.effectiveFrom}::date - 1`), or(isNull(rosterAssignments.effectiveTo), gte(rosterAssignments.effectiveTo, input.effectiveFrom))));
+                    // One that starts *later* cannot be trimmed backwards without deleting somebody's plan,
+                    // so it is refused by name instead. The exclusion constraint would refuse it too, as
+                    // `23P01` — a Postgres error code is not something the person at the screen can act on.
+                    const clashWhere = [
+                        eq(rosterAssignments.workspaceId, input.workspaceId),
+                        inArray(rosterAssignments.personId, personIds),
+                        gte(rosterAssignments.effectiveFrom, input.effectiveFrom),
+                    ];
+                    if (input.effectiveTo)
+                        clashWhere.push(lte(rosterAssignments.effectiveFrom, input.effectiveTo));
+                    const clashes = await tx
+                        .select()
+                        .from(rosterAssignments)
+                        .where(and(...clashWhere))
+                        .orderBy(asc(rosterAssignments.effectiveFrom))
+                        .limit(3);
+                    if (clashes.length) {
+                        const first = clashes[0];
+                        const who = nameOf.get(first.personId) ?? 'Somebody in this list';
+                        throw KernError.badRequest(`${who} already starts a rotation on ${first.effectiveFrom}. End that one first, or give this assignment an end date before it.`);
+                    }
+                    await tx.insert(rosterAssignments).values(personIds.map((personId) => ({
+                        id: uuidv7(),
+                        workspaceId: input.workspaceId,
+                        personId,
+                        patternId: input.patternId,
+                        effectiveFrom: input.effectiveFrom,
+                        effectiveTo: input.effectiveTo ?? null,
+                        cycleOffset: input.cycleOffset,
+                    })));
+                    return tx
+                        .select()
+                        .from(rosterAssignments)
+                        .where(and(eq(rosterAssignments.workspaceId, input.workspaceId), inArray(rosterAssignments.personId, personIds)))
+                        .orderBy(desc(rosterAssignments.effectiveFrom), asc(rosterAssignments.id));
+                });
+                await changed(input.workspaceId, 'roster_assignment', input.patternId, 'updated');
+                return rows.map(toRosterAssignment);
+            }),
+            unassign: scoped.rosters.unassign
+                .use(cap('rosters'))
+                .use(requires('hr.attendance.manage'))
+                .handler(async ({ input }) => {
+                const closed = await db.withWorkspace(input.workspaceId, async (tx) => {
+                    // Only assignments that have actually started by that date. Ending one before it begins
+                    // is a deletion wearing an end date, and this procedure never deletes: an assignment
+                    // somebody set up for next month is left for them to remove deliberately.
+                    const rows = await tx
+                        .update(rosterAssignments)
+                        .set({ effectiveTo: input.effectiveTo })
+                        .where(and(eq(rosterAssignments.workspaceId, input.workspaceId), inArray(rosterAssignments.personId, [...new Set(input.personIds)]), isNull(rosterAssignments.effectiveTo), lte(rosterAssignments.effectiveFrom, input.effectiveTo)))
+                        .returning({ id: rosterAssignments.id });
+                    return rows.length;
+                });
+                for (const personId of new Set(input.personIds))
+                    await changed(input.workspaceId, 'roster_assignment', personId, 'updated');
+                return { closed };
+            }),
+            days: scoped.rosters.days
+                .use(cap('rosters'))
+                .use(requires('hr.attendance.view'))
+                .handler(({ input, context }) => db.withWorkspace(input.workspaceId, async (tx) => {
+                const personId = await rosterPersonFor(tx, input.workspaceId, context, input.personId);
+                const refusal = rosterRefusal({ from: input.from, to: input.to, coverage: false });
+                if (refusal)
+                    throw KernError.badRequest(refusal);
+                const days = await rosters.forPerson(tx, input.workspaceId, personId, input.from, input.to);
+                return days.map((day) => toRosterDay(personId, day));
+            })),
+            set: scoped.rosters.set
+                .use(cap('rosters'))
+                .use(requires('hr.attendance.manage'))
+                .handler(async ({ input, context }) => {
+                const day = await db.withWorkspace(input.workspaceId, async (tx) => {
+                    const [person] = await tx
+                        .select({ id: people.id })
+                        .from(people)
+                        .where(and(eq(people.workspaceId, input.workspaceId), eq(people.id, input.personId)))
+                        .limit(1);
+                    if (!person)
+                        throw KernError.notFound('Employee');
+                    await rosters.assertShiftsExist(tx, input.workspaceId, input.shiftIds);
+                    const me = await svc.byUserId(tx, input.workspaceId, context.principal.userId ?? '');
+                    await tx
+                        .insert(rosterOverrides)
+                        .values({
+                        id: uuidv7(),
+                        workspaceId: input.workspaceId,
+                        personId: input.personId,
+                        businessDate: input.businessDate,
+                        shiftIds: [...input.shiftIds],
+                        note: input.note ?? null,
+                        createdBy: me?.id ?? null,
+                    })
+                        // One override per person-day, so a second edit of the same Tuesday replaces the
+                        // first rather than adding a row nothing would ever choose between.
+                        .onConflictDoUpdate({
+                        target: [rosterOverrides.workspaceId, rosterOverrides.personId, rosterOverrides.businessDate],
+                        set: {
+                            shiftIds: [...input.shiftIds],
+                            note: input.note ?? null,
+                            createdBy: me?.id ?? null,
+                            updatedAt: new Date(),
+                        },
+                    });
+                    const [resolved] = await rosters.forPerson(tx, input.workspaceId, input.personId, input.businessDate, input.businessDate);
+                    return resolved;
+                });
+                await changed(input.workspaceId, 'roster_day', input.personId, 'updated');
+                return toRosterDay(input.personId, day);
+            }),
+            clear: scoped.rosters.clear
+                .use(cap('rosters'))
+                .use(requires('hr.attendance.manage'))
+                .handler(async ({ input }) => {
+                await db.withWorkspace(input.workspaceId, (tx) => tx
+                    .delete(rosterOverrides)
+                    .where(and(eq(rosterOverrides.workspaceId, input.workspaceId), eq(rosterOverrides.personId, input.personId), eq(rosterOverrides.businessDate, input.businessDate))));
+                await changed(input.workspaceId, 'roster_day', input.personId, 'updated');
+                return { ok: true };
+            }),
+            coverage: scoped.rosters.coverage
+                .use(cap('rosters'))
+                .use(requires('hr.attendance.view_team'))
+                .handler(({ input }) => db.withWorkspace(input.workspaceId, async (tx) => {
+                const shape = rosterRefusal({ from: input.from, to: input.to, coverage: true });
+                if (shape)
+                    throw KernError.badRequest(shape);
+                // The population is whoever a rotation covers — narrowed to one office when asked. A
+                // grid over people no rotation touches is a page of empty rows.
+                const rostered = await tx
+                    .selectDistinct({ personId: rosterAssignments.personId })
+                    .from(rosterAssignments)
+                    .where(and(eq(rosterAssignments.workspaceId, input.workspaceId), lte(rosterAssignments.effectiveFrom, input.to), or(isNull(rosterAssignments.effectiveTo), gte(rosterAssignments.effectiveTo, input.from))));
+                let personIds = rostered.map((r) => r.personId);
+                if (input.officeId) {
+                    const here = await tx
+                        .select({ personId: officeAssignments.personId })
+                        .from(officeAssignments)
+                        .where(and(eq(officeAssignments.workspaceId, input.workspaceId), eq(officeAssignments.officeId, input.officeId), isNull(officeAssignments.effectiveTo)));
+                    const inOffice = new Set(here.map((h) => h.personId));
+                    personIds = personIds.filter((id) => inOffice.has(id));
+                }
+                const dates = datesBetween(input.from, input.to);
+                if (!personIds.length)
+                    return dates.map((businessDate) => ({ businessDate, slots: [], off: [] }));
+                const tooWide = rosterRefusal({
+                    from: input.from,
+                    to: input.to,
+                    coverage: true,
+                    population: personIds.length,
+                });
+                if (tooWide)
+                    throw KernError.badRequest(tooWide);
+                const plan = await rosters.plan(tx, input.workspaceId, personIds, dates);
+                const named = await tx
+                    .select({ personId: people.id, displayName: people.displayName })
+                    .from(people)
+                    .where(and(eq(people.workspaceId, input.workspaceId), inArray(people.id, personIds)));
+                const nameOf = new Map(named.map((p) => [p.personId, p.displayName]));
+                const person = (personId) => ({
+                    personId,
+                    displayName: nameOf.get(personId) ?? '',
+                });
+                return dates.map((businessDate, index) => {
+                    const slots = new Map();
+                    const off = [];
+                    for (const personId of personIds) {
+                        const day = plan.get(personId)?.[index];
+                        // `none` means nothing rosters this person on this date, which is not the same as a
+                        // planned day off and does not belong in either column.
+                        if (!day || day.source === 'none')
+                            continue;
+                        if (!day.shifts.length) {
+                            off.push(personId);
+                            continue;
+                        }
+                        for (const shift of day.shifts) {
+                            const slot = slots.get(shift.id) ?? { shift: toRosterShift(shift), people: [] };
+                            slot.people.push(personId);
+                            slots.set(shift.id, slot);
+                        }
+                    }
+                    return {
+                        businessDate,
+                        slots: [...slots.values()]
+                            .sort((a, b) => a.shift.start.localeCompare(b.shift.start) || a.shift.name.localeCompare(b.shift.name))
+                            .map((slot) => ({ shift: slot.shift, people: slot.people.map(person) })),
+                        off: off.map(person),
+                    };
+                });
+            })),
+        },
         // ================================================================= leave
         leave: {
             types: {
@@ -3538,6 +3947,92 @@ export function implement_(kernel) {
                 };
             })),
         },
+        // ================================================================= payroll export
+        /**
+         * The monthly handover to whoever runs payroll, for one legal entity, frozen at v1.
+         *
+         * **Three keys, and the middle one is new.** `hr.payroll.export` ships in this change because
+         * this is the change that makes a writer exist — it is granted to nobody by default, like
+         * `hr.person.view_sensitive` and `hr.privacy.manage`, so on a fresh workspace only an owner can
+         * reach it. On top of it, the same second-check rule the reports follow:
+         * `hr.attendance.view_team` for the hours file and `hr.leave.view_team` for the leave file,
+         * because an export must not answer what the row-level procedure would refuse.
+         *
+         * **One capability gate, and it carries two more inside it.** `payroll_export` declares
+         * `dependsOn: ['core', 'periods', 'attendance']`, and `kernel.capabilities` prunes a capability
+         * whose dependencies are off — so a workspace with attendance off has no day sheet to hand over
+         * and this answers 404, and a workspace with periods off would have every day open, the refusal
+         * below would fire on every call, and a switch that only ever produces an error is worse than no
+         * switch. Gating on the three separately would say the same thing three times and let them drift;
+         * the dependency list is where that belongs.
+         *
+         * That pruning is measured rather than assumed, because the whole gate rests on it: against a real
+         * kernel, `payroll.export.v1` answers `NOT_FOUND` with `attendance` off, with `periods` off, and
+         * with `payroll_export` itself off, and reaches the handler only when all three are on. Worth
+         * knowing when reading a support ticket: all three refusals say *`hr.payroll_export` is not
+         * enabled*, so an administrator looking at a switch that is plainly on is looking at a dependency
+         * that is off.
+         *
+         * **Nothing here writes**, including no `sensitive_access_log` row: this export reads no
+         * sensitive field. Adding `iban` would make it a bulk decrypt of every employee's bank account
+         * and would owe one audit row per person with `via: 'export'` — a different procedure with its
+         * own key, not a column on this one.
+         */
+        payroll: {
+            export: {
+                /**
+                 * One entity, one period, two CSVs and a manifest.
+                 *
+                 * Synchronous, and that is checked rather than preferred: `core.files.createUpload` needs a
+                 * user principal and returns a presigned PUT for a browser, so a background job cannot mint a
+                 * `FileObject` at all, and writing bytes straight into `kernel.storage` would orphan an
+                 * object `core.files.*` cannot see and nothing will ever delete.
+                 *
+                 * It throws the first refusal `collect` found rather than emitting a row of zeros — an open
+                 * period without `draft`, an entity with nobody in it, or somebody with no employment record
+                 * covering their days here. The preview below returns all of them instead, so a screen can
+                 * show the reader every reason at once before anybody downloads anything.
+                 */
+                v1: scoped.payroll.export.v1
+                    .use(cap('payroll_export'))
+                    .use(requires('hr.payroll.export'))
+                    .use(requires('hr.attendance.view_team'))
+                    .use(requires('hr.leave.view_team'))
+                    .handler(({ input }) => db.withWorkspace(input.workspaceId, async (tx) => {
+                    const data = await payroll.collect(tx, input);
+                    const [first] = data.refusals;
+                    // `conflict` rather than `badRequest`: the request is well formed and the state is not
+                    // ready. `hr.period.not_locked` mirrors the spelling of `hr.period.locked`, which
+                    // `PolicyService.assertOpen` throws pointed the other way.
+                    if (first)
+                        throw KernError.conflict(first.message, first.code);
+                    return assembleExport(payrollAssembly(data, input.draft));
+                })),
+                /**
+                 * The same rows as JSON, with no file and no refusal thrown.
+                 *
+                 * The manifest it carries is the manifest the export *would* write, filenames included, so a
+                 * screen can name the files before they exist and a reader can see `DRAFT` in the name before
+                 * choosing to send it.
+                 */
+                preview: scoped.payroll.export.preview
+                    .use(cap('payroll_export'))
+                    .use(requires('hr.payroll.export'))
+                    .use(requires('hr.attendance.view_team'))
+                    .use(requires('hr.leave.view_team'))
+                    .handler(({ input }) => db.withWorkspace(input.workspaceId, async (tx) => {
+                    const data = await payroll.collect(tx, input);
+                    return {
+                        manifest: exportManifest(payrollAssembly(data, input.draft)),
+                        refusals: data.refusals,
+                        exportable: data.refusals.length === 0,
+                        totals: data.totals,
+                        hours: data.hours,
+                        leave: data.leave,
+                    };
+                })),
+            },
+        },
         // ================================================================= privacy
         /**
          * Subject access, erasure and retention.
@@ -4036,6 +4531,30 @@ export function implement_(kernel) {
         });
         return personId;
     }
+    /**
+     * The same rule as `personFor`, asking for the attendance key rather than the leave one.
+     *
+     * A roster is what somebody is expected to turn up for, which is an attendance fact — reusing
+     * `personFor` here would mean a manager needed permission to read a colleague's *leave balance*
+     * before they could see who is on Tuesday's late shift. Reading your own needs nothing beyond
+     * being an employee, exactly as `attendance.days.list` already decides it.
+     */
+    async function rosterPersonFor(tx, workspaceId, context, personId) {
+        const me = await svc.byUserId(tx, workspaceId, context.principal.userId ?? '');
+        if (!personId) {
+            if (!me)
+                throw KernError.notFound('Your employee record');
+            return me.id;
+        }
+        if (me && me.id === personId)
+            return personId;
+        await kernel.authz.require(context.principal, 'hr.attendance.view_team', {
+            kind: 'workspace',
+            id: workspaceId,
+            workspaceId,
+        });
+        return personId;
+    }
     // ------------------------------------------------------------------ reports
     /** What the caller asked to narrow to, refusing a slice with nothing to narrow *to*. */
     function sliceOf(input) {
@@ -4103,6 +4622,34 @@ export function implement_(kernel) {
             rows,
         };
     }
+    /**
+     * The provenance half of a payroll export's manifest — the part that is the router's to supply.
+     *
+     * `kernVersion` is the platform version this image was built as, recorded so a file can be traced
+     * back to what wrote it. It is **not** the contract identity: `PAYROLL_EXPORT_CONTRACT` is a
+     * literal that moves only when the column set does, and reading the module version into that field
+     * would rename the format on every patch release.
+     *
+     * The three permissions are the ones the middlewares above actually asked for, written out rather
+     * than inferred, for the reason `ReportScope` exists: two readers must never hold one file's
+     * figures under one title without being told which grants produced them.
+     */
+    function payrollAssembly(data, draft) {
+        return {
+            entity: data.entity,
+            period: data.period,
+            draft,
+            generatedAt: new Date().toISOString(),
+            kernVersion: kernel.version,
+            permissions: ['hr.payroll.export', 'hr.attendance.view_team', 'hr.leave.view_team'],
+            dayLengthMinutes: MINUTES_PER_DAY,
+            population: data.population,
+            counted: data.counted,
+            attendance: data.attendance,
+            hours: data.hours,
+            leave: data.leave,
+        };
+    }
     /** The request a retry is a retry *of*, or undefined the first time a key is seen. */
     async function byIdempotencyKey(tx, workspaceId, key) {
         const [row] = await tx
@@ -4611,6 +5158,36 @@ const toScheduleAssignment = (r) => ({
     ...r,
     createdAt: r.createdAt.toISOString(),
 });
+/**
+ * `start_time` / `end_time` in the table, `start` / `end` on the wire.
+ *
+ * The column names carry the suffix because `end` is a SQL keyword and a quoted keyword in every
+ * hand-written query is a trap for whoever writes the next one; the contract does not, because a
+ * shift reads as "start 06:00, end 14:00". The spread leaves both spellings on the object and zod
+ * strips the ones the schema does not name.
+ */
+const toRosterShift = (r) => ({
+    ...r,
+    start: r.startTime,
+    end: r.endTime,
+    archivedAt: r.archivedAt?.toISOString() ?? null,
+});
+const toRosterPattern = (r) => ({
+    ...r,
+    days: r.days ?? [],
+    archivedAt: r.archivedAt?.toISOString() ?? null,
+});
+const toRosterAssignment = (r) => ({
+    ...r,
+    createdAt: r.createdAt.toISOString(),
+});
+const toRosterDay = (personId, day) => ({
+    personId,
+    businessDate: day.businessDate,
+    shifts: day.shifts.map(toRosterShift),
+    source: day.source,
+    note: day.note,
+});
 const toRegularization = (r) => ({
     ...r,
     status: r.status,