@kernhq/module-hr 0.13.1 → 0.14.0

package/dist/server/router.js

@@ -1,12 +1,13 @@
 import { KernError, requires, requiresCapability, uuidv7, workspaceScoped, } from '@kernhq/kernel';
 import { implement } from '@orpc/server';
-import { and, asc, count, desc, eq, gte, ilike, inArray, isNull, lte, or, sql } from 'drizzle-orm';
+import { and, asc, count, desc, eq, getTableColumns, gte, ilike, inArray, isNull, lte, or, sql, } from 'drizzle-orm';
 import { HrSettings, hrContract, hrEvents, MODULE_ID } from '../contract/index.js';
 import { AccrualConfig, CarryForwardConfig, OvertimeConfig, RoundingConfig, WorkingTimeConfig, } from '../contract/policies.js';
 import { accrueForPeriod } from '../policy/accrual.js';
 import { countWorkingDays, 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 { forViewer, HrAccessService, seesRecordOf, visibleSet } from './services/access.js';
 import { ApprovalService } from './services/approvals.js';
 import { AttendanceService } from './services/attendance.js';
 import { inForceOn, todayIso } from './services/db.js';
@@ -15,6 +16,74 @@ import { PeopleService } from './services/people.js';
 import { hashConfig, PolicyService } from './services/policies.js';
 import { DEFAULT_WORKING_WEEK, ResolveService } from './services/resolve.js';
 const os = implement(hrContract).$context();
+const encodeCursor = (key, id) => Buffer.from(JSON.stringify([key, id]), 'utf8').toString('base64url');
+function decodeCursor(raw) {
+    if (!raw)
+        return null;
+    try {
+        const [key, id] = JSON.parse(Buffer.from(raw, 'base64url').toString('utf8'));
+        if (typeof key !== 'string' || typeof id !== 'string')
+            throw new Error('malformed cursor');
+        return { key, id };
+    }
+    catch {
+        // A cursor is opaque to the caller, so a broken one is a tampered URL or a bug on our side —
+        // never something the reader can fix by asking again. Refusing beats quietly serving page one,
+        // which reads as a list that jumps back to the top for no reason anybody can see.
+        throw KernError.badRequest('That page cursor is not valid.');
+    }
+}
+/**
+ * `(sort, id) > (…)` as one row comparison rather than `sort > k or (sort = k and id > i)`:
+ * Postgres can drive a row comparison straight off an index on `(sort, id)` and cannot do that with
+ * the `or` spelling. Both halves of the cursor are cast to the column's own type, because an
+ * untyped bind parameter beside a `date` or a `timestamptz` is not something to make the planner
+ * guess at.
+ */
+const after = (sort, id, dir, c) => {
+    const from = sql `(${c.key}::${sql.raw(sort.getSQLType())}, ${c.id}::uuid)`;
+    return dir === 'asc' ? sql `(${sort}, ${id}) > ${from}` : sql `(${sort}, ${id}) < ${from}`;
+};
+/**
+ * Did this error come from one named unique index?
+ *
+ * The cause chain is walked rather than the error itself, because drizzle wraps what the driver
+ * threw and the `code` a duplicate key arrives as — `23505` — is on the pg error underneath. The
+ * index name is checked too: a handler that treats *any* duplicate key as its own idempotency
+ * replay would silently swallow a collision on some other constraint, which is a bug reported as a
+ * success.
+ */
+function isUniqueViolation(err, constraint) {
+    for (let e = err, depth = 0; e && depth < 5; e = e.cause, depth++) {
+        const pg = e;
+        if (pg.code === '23505' && pg.constraint === constraint)
+            return true;
+    }
+    return false;
+}
+/**
+ * Cut a page out of the `limit + 1` rows the query asked for.
+ *
+ * The extra row is how "there is more" is known without a second count, and why a page that happens
+ * to fill exactly does not advertise a next page that turns out to be empty.
+ *
+ * **The key is `string`, never a `Date`, and that is load-bearing.** A `timestamptz` is stored at
+ * microsecond precision and node-postgres hands it back as a JS `Date`, which is milliseconds — so
+ * a cursor built from the row object is *strictly less* than the value it came from, and
+ * `(at, id) < (key, id)` then excludes every row that ties with the last row of the page. That is
+ * silent: no error, the list just ends early, and it bites hardest exactly where the id tiebreaker
+ * was supposed to save it — one edit writing several rows in a transaction, all sharing `now()`.
+ * Measured on `person_history`: five rows in one statement, page size two, page two returned none
+ * of the remaining three. A timestamp cursor therefore has to select the value `::text` and pass
+ * that, which the type here forces rather than trusts.
+ */
+function paginate(rows, limit, cursorOf) {
+    if (rows.length <= limit)
+        return { items: rows, nextCursor: null };
+    const items = rows.slice(0, limit);
+    const [key, id] = cursorOf(items[items.length - 1]);
+    return { items, nextCursor: encodeCursor(key, id) };
+}
 /**
  * The router.
  *
@@ -32,6 +101,7 @@ export function implement_(kernel) {
     const cap = (id) => requiresCapability(MODULE_ID, id);
     const resolve = new ResolveService();
     const svc = new PeopleService(kernel);
+    const access = new HrAccessService(kernel);
     const ledger = new LedgerService();
     const approvals = new ApprovalService(kernel);
     const policySvc = new PolicyService(resolve);
@@ -42,7 +112,18 @@ export function implement_(kernel) {
     return os.router({
         // ================================================================= people
         people: {
-            list: scoped.people.list.use(requires('hr.person.view')).handler(({ input }) => db.withWorkspace(input.workspaceId, async (tx) => {
+            /**
+             * The directory: every person in the workspace, and as much of each as the reader may have.
+             *
+             * `hr.person.view` is a `member` default and stays one — a staff directory a colleague cannot
+             * open is a worse product, not a safer one. What the three widening keys decide is how much
+             * of each row comes back: `HrAccessService` resolves the people whose *personnel record* this
+             * reader may see, and everybody else arrives as a card with the four personnel fields nulled.
+             * The filters, the count and the cursor are unaffected — the page is the same page for
+             * everybody, which is what keeps `total` honest.
+             */
+            list: scoped.people.list.use(requires('hr.person.view')).handler(({ input, context }) => db.withWorkspace(input.workspaceId, async (tx) => {
+                const visible = visibleSet(await access.visiblePersonIds(tx, input.workspaceId, context.principal));
                 const where = [eq(people.workspaceId, input.workspaceId)];
                 if (input.q)
                     where.push(ilike(people.displayName, `%${input.q}%`));
@@ -72,16 +153,21 @@ export function implement_(kernel) {
                         ? inArray(people.id, holders.map((r) => r.personId))
                         : sql `false`);
                 }
-                const rows = await tx
-                    .select()
-                    .from(people)
-                    .where(and(...where))
-                    .orderBy(asc(people.displayName))
-                    .limit(input.limit);
+                // The count is of everything the filters match, so it is taken before the cursor narrows
+                // the set — `total` is the size of the directory, not of the page being looked at.
                 const [total] = await tx
                     .select({ n: count() })
                     .from(people)
                     .where(and(...where));
+                const cursor = decodeCursor(input.cursor);
+                if (cursor)
+                    where.push(after(people.displayName, people.id, 'asc', cursor));
+                const { items: rows, nextCursor } = paginate(await tx
+                    .select()
+                    .from(people)
+                    .where(and(...where))
+                    .orderBy(asc(people.displayName), asc(people.id))
+                    .limit(input.limit + 1), input.limit, (r) => [r.displayName, r.id]);
                 // One query for the whole page rather than a resolution per row: a directory of five
                 // hundred people would otherwise be five hundred ladder walks.
                 const assignments = rows.length
@@ -97,21 +183,29 @@ export function implement_(kernel) {
                     : [];
                 const officeBy = new Map(assignments.map((a) => [a.personId, a]));
                 return {
-                    items: rows.map((r) => ({
+                    items: rows.map((r) => forViewer({
                         ...PeopleService.toPerson(r),
                         // Spreading into a fresh literal drops the branded WorkspaceId that flowed through
                         // `toPerson`, so it is restored rather than widened to `string`.
                         workspaceId: r.workspaceId,
                         officeId: officeBy.get(r.id)?.officeId ?? null,
                         officeName: officeBy.get(r.id)?.name ?? null,
-                    })),
-                    nextCursor: null,
+                    }, visible)),
+                    nextCursor,
                     total: total?.n ?? 0,
                 };
             })),
-            get: scoped.people.get
-                .use(requires('hr.person.view'))
-                .handler(({ input }) => db.withWorkspace(input.workspaceId, async (tx) => PeopleService.toPerson(await svc.load(tx, input.workspaceId, input.personId)))),
+            /**
+             * One person, at the width `people.list` would have shown them.
+             *
+             * Not a 404 for somebody outside the reader's record scope: the person exists, the directory
+             * says so, and answering "no such person" to a colleague looking up a work email would be a
+             * lie the whole product contradicts. They get the card.
+             */
+            get: scoped.people.get.use(requires('hr.person.view')).handler(({ input, context }) => db.withWorkspace(input.workspaceId, async (tx) => {
+                const visible = visibleSet(await access.visiblePersonIds(tx, input.workspaceId, context.principal));
+                return forViewer(PeopleService.toPerson(await svc.load(tx, input.workspaceId, input.personId)), visible);
+            })),
             /**
              * No permission check: everybody may read their own record, and a permission nobody can lack
              * is noise in the role editor. Returns null rather than 404 when the signed-in user has no HR
@@ -186,7 +280,15 @@ export function implement_(kernel) {
                 await changed(workspaceId, 'person', personId, 'updated');
                 return PeopleService.toPerson(row.updated);
             }),
-            /** Ends employment and keeps the record. A terminated person is history, not a deletion. */
+            /**
+             * Ends employment and keeps the record. A terminated person is history, not a deletion.
+             *
+             * The reason the dialog collects is written to `person_history` rather than to a column on
+             * `people`: "why did she leave" is a fact about the *event*, it is asked for by an audit
+             * alongside who ended the employment and when, and `person_history` is the append-only table
+             * that already answers exactly that question. It used to be accepted and dropped on the
+             * floor, which is the one thing an offboarding record must not do.
+             */
             offboard: scoped.people.offboard
                 .use(requires('hr.person.manage'))
                 .handler(async ({ input, context }) => {
@@ -205,9 +307,13 @@ export function implement_(kernel) {
                         .update(officeAssignments)
                         .set({ effectiveTo: input.on })
                         .where(and(eq(officeAssignments.workspaceId, input.workspaceId), eq(officeAssignments.personId, input.personId), isNull(officeAssignments.effectiveTo)));
+                    const reason = input.reason?.trim();
                     await svc.record(tx, input.workspaceId, input.personId, context.principal.userId ?? null, [
                         { field: 'status', from: before.status, to: 'terminated' },
                         { field: 'terminatedOn', from: before.terminatedOn, to: input.on },
+                        // Only when there is one. A row saying the reason changed from nothing to nothing is
+                        // noise in the trail somebody reads to find out what happened.
+                        ...(reason ? [{ field: 'terminationReason', from: null, to: reason }] : []),
                     ]);
                     return { before, updated: updated };
                 });
@@ -221,13 +327,38 @@ export function implement_(kernel) {
                 await changed(input.workspaceId, 'person', input.personId, 'updated');
                 return PeopleService.toPerson(row.updated);
             }),
-            history: scoped.people.history.use(requires('hr.person.view')).handler(({ input }) => db.withWorkspace(input.workspaceId, async (tx) => {
-                const rows = await tx
-                    .select()
+            /**
+             * The audit trail, and the reason redacting the record alone would have been theatre.
+             *
+             * Every row carries the old and new *value* of a field — so `personalEmail`, `phone` and
+             * `hiredOn` are all in here, in plain sight, for anybody who can list the history. It is a
+             * personnel read however narrow the query looks, and it is refused for somebody whose record
+             * the reader may not see. No permission is named on the refusal: three different keys would
+             * each have opened it, and naming one of them would send the reader to ask for the wrong one.
+             */
+            history: scoped.people.history.use(requires('hr.person.view')).handler(({ input, context }) => db.withWorkspace(input.workspaceId, async (tx) => {
+                const visible = visibleSet(await access.visiblePersonIds(tx, input.workspaceId, context.principal));
+                if (!seesRecordOf(visible, input.personId))
+                    throw KernError.forbidden();
+                const where = [
+                    eq(personHistory.workspaceId, input.workspaceId),
+                    eq(personHistory.personId, input.personId),
+                ];
+                // The id tiebreaker earns its keep here more than anywhere: one edit writes several rows
+                // in one statement, and `now()` is frozen for a transaction, so they all share an `at`.
+                const cursor = decodeCursor(input.cursor);
+                if (cursor)
+                    where.push(after(personHistory.at, personHistory.id, 'desc', cursor));
+                const { items: rows, nextCursor } = paginate(
+                // `atText` rather than the `Date`: see `paginate`. `now()` is frozen for a transaction,
+                // so a single edit's rows all share an `at` to the microsecond, and a millisecond cursor
+                // would drop every one of them after the first page.
+                await tx
+                    .select({ ...getTableColumns(personHistory), atText: sql `${personHistory.at}::text` })
                     .from(personHistory)
-                    .where(and(eq(personHistory.workspaceId, input.workspaceId), eq(personHistory.personId, input.personId)))
-                    .orderBy(desc(personHistory.at))
-                    .limit(input.limit);
+                    .where(and(...where))
+                    .orderBy(desc(personHistory.at), desc(personHistory.id))
+                    .limit(input.limit + 1), input.limit, (r) => [r.atText, r.id]);
                 return {
                     items: rows.map((r) => ({
                         id: r.id,
@@ -238,7 +369,7 @@ export function implement_(kernel) {
                         actorId: r.actorId,
                         source: r.source,
                     })),
-                    nextCursor: null,
+                    nextCursor,
                 };
             })),
             sensitive: {
@@ -678,37 +809,61 @@ export function implement_(kernel) {
                 await changed(input.workspaceId, 'office', row.id, 'updated');
                 return toOffice(row);
             }),
+            /**
+             * The office's people, and its headcount.
+             *
+             * One join rather than the two round trips this used to be. The old shape limited the
+             * *assignments* and then sorted the people it had fetched, so a page was an arbitrary subset
+             * put in alphabetical order — and it reported `rows.length` as `total`, which told an office
+             * of forty that it had twenty as soon as one page stopped holding everybody. The headcount is
+             * counted now, over the same predicate and without the cursor.
+             */
             people: scoped.offices.people
                 .use(cap('offices'))
                 .use(requires('hr.office.view'))
-                .handler(({ input }) => db.withWorkspace(input.workspaceId, async (tx) => {
+                .handler(({ input, context }) => db.withWorkspace(input.workspaceId, async (tx) => {
+                // An office roster is the directory filtered to one place, so it is read at the same
+                // width — `hr.office.view` is a `member` default too, and returning whole records here
+                // would be a way round `people.list` rather than a different question.
+                const visible = visibleSet(await access.visiblePersonIds(tx, input.workspaceId, context.principal));
+                const here = and(eq(people.id, officeAssignments.personId), eq(people.workspaceId, officeAssignments.workspaceId));
+                // As of today, not "the row with no end date" — the same predicate `HrAccessService`
+                // uses, and they have to agree because both answer this one screen. An office move and
+                // an offboarding are both *dated*: `people.offboard` writes a last working day that is
+                // normally in the future, so a null-end-date test drops somebody the moment their
+                // leaving is recorded, while a future-dated transfer adds them weeks early. The roster
+                // showed one set and the record scope another, on the same response.
                 const where = [
                     eq(officeAssignments.workspaceId, input.workspaceId),
                     eq(officeAssignments.officeId, input.officeId),
-                    isNull(officeAssignments.effectiveTo),
+                    inForceOn(officeAssignments.effectiveFrom, officeAssignments.effectiveTo, todayIso()),
                 ];
                 if (input.primaryOnly)
                     where.push(eq(officeAssignments.isPrimary, true));
-                const assignments = await tx
-                    .select()
+                const [total] = await tx
+                    .select({ n: count() })
                     .from(officeAssignments)
+                    .innerJoin(people, here)
+                    .where(and(...where));
+                const cursor = decodeCursor(input.cursor);
+                if (cursor)
+                    where.push(after(people.displayName, people.id, 'asc', cursor));
+                const { items: rows, nextCursor } = paginate(await tx
+                    .select({ person: people, isPrimary: officeAssignments.isPrimary })
+                    .from(officeAssignments)
+                    .innerJoin(people, here)
                     .where(and(...where))
-                    .limit(input.limit);
-                if (!assignments.length)
-                    return { items: [], nextCursor: null, total: 0 };
-                const rows = await tx
-                    .select()
-                    .from(people)
-                    .where(and(eq(people.workspaceId, input.workspaceId), inArray(people.id, assignments.map((a) => a.personId))))
-                    .orderBy(asc(people.displayName));
-                const primaryHere = new Set(assignments.filter((a) => a.isPrimary).map((a) => a.personId));
+                    .orderBy(asc(people.displayName), asc(people.id))
+                    .limit(input.limit + 1), input.limit, (r) => [r.person.displayName, r.person.id]);
                 return {
-                    items: rows.map((r) => ({
-                        ...PeopleService.toPerson(r),
-                        isPrimaryHere: primaryHere.has(r.id),
-                    })),
-                    nextCursor: null,
-                    total: rows.length,
+                    items: rows.map((r) => forViewer({
+                        ...PeopleService.toPerson(r.person),
+                        // Migration 0001 allows one open assignment per person per office, so the join
+                        // cannot produce a person twice and this flag cannot disagree with itself.
+                        isPrimaryHere: r.isPrimary,
+                    }, visible)),
+                    nextCursor,
+                    total: total?.n ?? 0,
                 };
             })),
             assign: scoped.offices.assign
@@ -1444,13 +1599,16 @@ export function implement_(kernel) {
                 const where = [eq(periods.workspaceId, input.workspaceId)];
                 if (input.kind)
                     where.push(eq(periods.kind, input.kind));
-                const rows = await tx
+                const cursor = decodeCursor(input.cursor);
+                if (cursor)
+                    where.push(after(periods.startsOn, periods.id, 'desc', cursor));
+                const { items, nextCursor } = paginate(await tx
                     .select()
                     .from(periods)
                     .where(and(...where))
-                    .orderBy(desc(periods.startsOn))
-                    .limit(input.limit);
-                return { items: rows.map(toPeriod), nextCursor: null };
+                    .orderBy(desc(periods.startsOn), desc(periods.id))
+                    .limit(input.limit + 1), input.limit, (r) => [r.startsOn, r.id]);
+                return { items: items.map(toPeriod), nextCursor };
             })),
             create: scoped.periods.create
                 .use(cap('periods'))
@@ -1616,13 +1774,21 @@ export function implement_(kernel) {
                     ];
                     if (!input.includeVoided)
                         where.push(isNull(punches.voidedByPunchId));
-                    const rows = await tx
-                        .select()
+                    const cursor = decodeCursor(input.cursor);
+                    if (cursor)
+                        where.push(after(punches.at, punches.id, 'asc', cursor));
+                    const { items, nextCursor } = paginate(
+                    // `atText`, for the reason in `paginate`. Every insert here supplies a JS `Date`, so
+                    // nothing sub-millisecond is stored today and the bug is latent rather than live —
+                    // but the column carries `.defaultNow()`, so one insert that omits `at` would start
+                    // dropping punches off the end of a page with nothing to show for it.
+                    await tx
+                        .select({ ...getTableColumns(punches), atText: sql `${punches.at}::text` })
                         .from(punches)
                         .where(and(...where))
-                        .orderBy(asc(punches.at))
-                        .limit(input.limit);
-                    return { items: rows.map(toPunch), nextCursor: null };
+                        .orderBy(asc(punches.at), asc(punches.id))
+                        .limit(input.limit + 1), input.limit, (r) => [r.atText, r.id]);
+                    return { items: items.map(toPunch), nextCursor };
                 })),
                 void: scoped.attendance.punches.void
                     .use(cap('attendance'))
@@ -1669,13 +1835,16 @@ export function implement_(kernel) {
                         const personId = await personFor(tx, input.workspaceId, context, input.personId);
                         where.push(eq(attendanceDays.personId, personId));
                     }
-                    const rows = await tx
+                    const cursor = decodeCursor(input.cursor);
+                    if (cursor)
+                        where.push(after(attendanceDays.businessDate, attendanceDays.id, 'asc', cursor));
+                    const { items, nextCursor } = paginate(await tx
                         .select()
                         .from(attendanceDays)
                         .where(and(...where))
-                        .orderBy(asc(attendanceDays.businessDate))
-                        .limit(input.limit);
-                    return { items: rows.map(toAttendanceDay), nextCursor: null };
+                        .orderBy(asc(attendanceDays.businessDate), asc(attendanceDays.id))
+                        .limit(input.limit + 1), input.limit, (r) => [r.businessDate, r.id]);
+                    return { items: items.map(toAttendanceDay), nextCursor };
                 })),
                 recompute: scoped.attendance.days.recompute
                     .use(cap('attendance'))
@@ -1813,19 +1982,22 @@ export function implement_(kernel) {
                     ];
                     if (input.status?.length)
                         where.push(inArray(regularizations.status, input.status));
-                    const rows = await tx
+                    const cursor = decodeCursor(input.cursor);
+                    if (cursor)
+                        where.push(after(regularizations.businessDate, regularizations.id, 'desc', cursor));
+                    const { items, nextCursor } = paginate(await tx
                         .select()
                         .from(regularizations)
                         .where(and(...where))
-                        .orderBy(desc(regularizations.businessDate))
-                        .limit(input.limit);
-                    return { items: rows.map(toRegularization), nextCursor: null };
+                        .orderBy(desc(regularizations.businessDate), desc(regularizations.id))
+                        .limit(input.limit + 1), input.limit, (r) => [r.businessDate, r.id]);
+                    return { items: items.map(toRegularization), nextCursor };
                 })),
                 request: scoped.attendance.regularizations.request
                     .use(cap('attendance'))
                     .use(requires('hr.attendance.punch'))
                     .handler(async ({ input, context }) => {
-                    const row = await db.withWorkspace(input.workspaceId, async (tx) => {
+                    const filed = await db.withWorkspace(input.workspaceId, async (tx) => {
                         const personId = await personFor(tx, input.workspaceId, context, input.personId);
                         const [created] = await tx
                             .insert(regularizations)
@@ -1861,10 +2033,22 @@ export function implement_(kernel) {
                             .select()
                             .from(regularizations)
                             .where(eq(regularizations.id, created.id));
-                        return fresh;
+                        // Same reason as leave: the approvers are told after this commits, never inside it.
+                        return {
+                            row: fresh,
+                            approval: { requestId: raised.request.id, approverIds: raised.firstStepApprovers },
+                        };
                     });
-                    await changed(input.workspaceId, 'regularization', row.id, 'created');
-                    return toRegularization(row);
+                    if (filed.approval.approverIds.length)
+                        await kernel.emit(hrEvents.approvalRequested, {
+                            requestId: filed.approval.requestId,
+                            workspaceId: input.workspaceId,
+                            subjectType: 'regularization',
+                            subjectId: filed.row.id,
+                            approverIds: filed.approval.approverIds,
+                        }, { workspaceId: input.workspaceId, actorId: context.principal.userId });
+                    await changed(input.workspaceId, 'regularization', filed.row.id, 'created');
+                    return toRegularization(filed.row);
                 }),
             },
         },
@@ -1971,13 +2155,19 @@ export function implement_(kernel) {
                         where.push(eq(leaveLedger.leaveTypeId, input.leaveTypeId));
                     if (input.periodYear)
                         where.push(eq(leaveLedger.periodYear, input.periodYear));
-                    const rows = await tx
+                    const cursor = decodeCursor(input.cursor);
+                    if (cursor)
+                        where.push(after(leaveLedger.effectiveOn, leaveLedger.id, 'desc', cursor));
+                    // The second sort key is the id rather than `created_at`, and means the same thing:
+                    // ids here are uuidv7, so they already run in creation order — and unlike `created_at`
+                    // no two rows can share one, which is what makes the cursor land in exactly one place.
+                    const { items, nextCursor } = paginate(await tx
                         .select()
                         .from(leaveLedger)
                         .where(and(...where))
-                        .orderBy(desc(leaveLedger.effectiveOn), desc(leaveLedger.createdAt))
-                        .limit(input.limit);
-                    return { items: rows.map(toLedgerEntry), nextCursor: null };
+                        .orderBy(desc(leaveLedger.effectiveOn), desc(leaveLedger.id))
+                        .limit(input.limit + 1), input.limit, (r) => [r.effectiveOn, r.id]);
+                    return { items: items.map(toLedgerEntry), nextCursor };
                 })),
             },
             adjust: scoped.leave.adjust
@@ -2013,11 +2203,34 @@ export function implement_(kernel) {
                     .use(requires('hr.leave.view'))
                     .handler(({ input, context }) => db.withWorkspace(input.workspaceId, async (tx) => {
                     const where = [eq(leaveRequests.workspaceId, input.workspaceId)];
-                    if (input.personId)
+                    // An office is other people's absences, so asking for one costs the same permission
+                    // the team calendar costs. `hr.leave.view` alone must not become a way of reading the
+                    // whole company — which is exactly what a filter the server ignores had made of it.
+                    if (input.officeId) {
+                        await kernel.authz.require(context.principal, 'hr.leave.view_team', {
+                            kind: 'workspace',
+                            id: input.workspaceId,
+                            workspaceId: input.workspaceId,
+                        });
+                        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)));
+                        // An empty office matches nobody, not everybody.
+                        where.push(here.length
+                            ? inArray(leaveRequests.personId, here.map((h) => h.personId))
+                            : sql `false`);
+                    }
+                    if (input.personId) {
+                        // Naming somebody else is the same act as naming their office, and was the one way
+                        // through this handler that cost nothing: `hr.leave.view` and a person id read
+                        // anybody's absences. `personFor` is the rule everywhere else in this module.
+                        await personFor(tx, input.workspaceId, context, input.personId);
                         where.push(eq(leaveRequests.personId, input.personId));
-                    else if (!context.principal.instanceAdmin) {
-                        // Without an explicit person, this is "my requests". Seeing everybody's by default
-                        // would leak the whole company's absences to any member with hr.leave.view.
+                    }
+                    else if (!input.officeId && !context.principal.instanceAdmin) {
+                        // Without an explicit person or office, this is "my requests". Seeing everybody's by
+                        // default would leak the whole company's absences to any member with hr.leave.view.
                         const me = await svc.byUserId(tx, input.workspaceId, context.principal.userId ?? '');
                         where.push(me ? eq(leaveRequests.personId, me.id) : sql `false`);
                     }
@@ -2027,13 +2240,16 @@ export function implement_(kernel) {
                         where.push(gte(leaveRequests.endsOn, input.from));
                     if (input.to)
                         where.push(lte(leaveRequests.startsOn, input.to));
-                    const rows = await tx
+                    const cursor = decodeCursor(input.cursor);
+                    if (cursor)
+                        where.push(after(leaveRequests.startsOn, leaveRequests.id, 'desc', cursor));
+                    const { items, nextCursor } = paginate(await tx
                         .select()
                         .from(leaveRequests)
                         .where(and(...where))
-                        .orderBy(desc(leaveRequests.startsOn))
-                        .limit(input.limit);
-                    return { items: rows.map(toLeaveRequest), nextCursor: null };
+                        .orderBy(desc(leaveRequests.startsOn), desc(leaveRequests.id))
+                        .limit(input.limit + 1), input.limit, (r) => [r.startsOn, r.id]);
+                    return { items: items.map(toLeaveRequest), nextCursor };
                 })),
                 get: scoped.leave.requests.get
                     .use(cap('leave'))
@@ -2046,11 +2262,31 @@ export function implement_(kernel) {
                     const personId = await personFor(tx, input.workspaceId, context, input.personId);
                     return simulate(tx, input.workspaceId, personId, input);
                 })),
+                /**
+                 * File a request.
+                 *
+                 * `idempotencyKey` is the contract's promise that a retried submission is safe, and the
+                 * server used to store the key without ever reading it. So a retry filed a second request,
+                 * or died on whichever unique index it reached first — the exploded days for a counted
+                 * absence, the key itself otherwise. Neither is what the caller was promised.
+                 *
+                 * `hr_leave_requests_idem_uq` is what there is to lean on: it already refuses a second row
+                 * for a key, so honouring the promise is a read before the insert and an answer for the
+                 * loser of the race.
+                 */
                 create: scoped.leave.requests.create
                     .use(cap('leave'))
                     .use(requires('hr.leave.request'))
                     .handler(async ({ input, context }) => {
-                    const result = await db.withWorkspace(input.workspaceId, async (tx) => {
+                    const key = input.idempotencyKey;
+                    // Held as a promise rather than awaited here, so that the duplicate recovery below is
+                    // one step at the end instead of ninety lines wrapped in a `try`.
+                    const filing = db.withWorkspace(input.workspaceId, async (tx) => {
+                        // Before anything is locked or simulated: the same key is the same submission, and
+                        // answering it with the request it already filed is what "safe to retry" means.
+                        const already = key ? await byIdempotencyKey(tx, input.workspaceId, key) : undefined;
+                        if (already)
+                            return { request: already, personId: already.personId, replay: true };
                         const personId = await personFor(tx, input.workspaceId, context, input.personId);
                         // Everything that spends balance takes the cursor lock first, inside this
                         // transaction. Two overlapping requests for the last day cannot both read "enough".
@@ -2114,8 +2350,34 @@ export function implement_(kernel) {
                         if (raised.autoApproved)
                             await applyApproval(tx, input.workspaceId, request.id, context.principal.userId ?? null);
                         const [fresh] = await tx.select().from(leaveRequests).where(eq(leaveRequests.id, request.id));
-                        return { request: fresh, approvers: raised.firstStepApprovers, personId };
+                        // Carried out of the transaction rather than emitted here: an approver must not be
+                        // handed a card for a request a rollback is about to erase. `firstStepApprovers` is
+                        // empty exactly when the chain resolved to nobody — the auto-approval above.
+                        return {
+                            request: fresh,
+                            personId,
+                            replay: false,
+                            approval: { requestId: raised.request.id, approverIds: raised.firstStepApprovers },
+                        };
                     });
+                    const result = await filing.catch(async (err) => {
+                        // The other half of a double submit: two clicks a browser sends before the first has
+                        // answered both pass the read above, both reach the insert, and the unique index
+                        // refuses one. The loser lost a race it was never meant to enter, so it is answered
+                        // with the request that won rather than with a constraint error. The re-read needs a
+                        // new transaction — the failed one is aborted and will not answer another query.
+                        if (!key || !isUniqueViolation(err, 'hr_leave_requests_idem_uq'))
+                            throw err;
+                        const won = await db.withWorkspace(input.workspaceId, (tx) => byIdempotencyKey(tx, input.workspaceId, key));
+                        if (!won)
+                            throw err;
+                        return { request: won, personId: won.personId, replay: true };
+                    });
+                    // A replay files nothing, so it announces nothing. Emitting `leaveRequested` again would
+                    // put a second card in an approver's inbox for one request — the outcome the key exists
+                    // to prevent, arriving by a different route.
+                    if (result.replay)
+                        return toLeaveRequest(result.request);
                     await kernel.emit(hrEvents.leaveRequested, {
                         requestId: result.request.id,
                         workspaceId: input.workspaceId,
@@ -2123,6 +2385,18 @@ export function implement_(kernel) {
                         startsOn: input.startsOn,
                         endsOn: input.endsOn,
                     }, { workspaceId: input.workspaceId, actorId: context.principal.userId });
+                    // Second, and only when somebody is actually waiting: the request exists, and these are
+                    // the people the *first* step is on. Nothing for a chain that resolved to nobody — that
+                    // was approved on the way in and is not waiting on anyone. The ids are person ids, the
+                    // same identity the rest of `hr.*` carries.
+                    if (result.approval.approverIds.length)
+                        await kernel.emit(hrEvents.approvalRequested, {
+                            requestId: result.approval.requestId,
+                            workspaceId: input.workspaceId,
+                            subjectType: 'leave',
+                            subjectId: result.request.id,
+                            approverIds: result.approval.approverIds,
+                        }, { workspaceId: input.workspaceId, actorId: context.principal.userId });
                     await changed(input.workspaceId, 'leave_request', result.request.id, 'created');
                     return toLeaveRequest(result.request);
                 }),
@@ -2236,6 +2510,13 @@ export function implement_(kernel) {
             /**
              * Everything waiting on the caller. No permission: an inbox of what *you* must decide is
              * yours by definition, and the engine only lists steps you are named on.
+             *
+             * The one paged list here that still answers `nextCursor: null`, and the only one that cannot
+             * be fixed from this file: the page is cut inside `ApprovalService.inboxFor`, which takes a
+             * limit and no cursor. Honouring one means widening that signature and pushing
+             * `after(approvalRequests.requestedAt, approvalRequests.id, 'desc', …)` into its final query —
+             * ordering it by `(requested_at, id)` on the way, so the cursor has something unique to land
+             * on. Filtering the rows it returns would not do: it has already truncated them.
              */
             inbox: scoped.approvals.inbox.handler(({ input, context }) => db.withWorkspace(input.workspaceId, async (tx) => {
                 const me = await svc.byUserId(tx, input.workspaceId, context.principal.userId ?? '');
@@ -2454,6 +2735,14 @@ export function implement_(kernel) {
         },
         // ================================================================= custom fields
         fields: {
+            /**
+             * Deliberately not narrowed by the record scope, unlike everything else on `hr.person.view`.
+             *
+             * These are field *definitions* — a workspace's shape, not anybody's data. Every screen that
+             * renders a person has to know what "hire_buddy" is called and whether it is a date before it
+             * can draw a single row, and a reader who may see one person's record needs the whole schema
+             * to read that one person. There is nothing here to scope to a person.
+             */
             list: scoped.fields.list.use(requires('hr.person.view')).handler(({ input }) => db.withWorkspace(input.workspaceId, async (tx) => {
                 const where = [eq(customFieldDefs.workspaceId, input.workspaceId)];
                 if (!input.includeArchived)
@@ -2774,6 +3063,15 @@ export function implement_(kernel) {
         });
         return personId;
     }
+    /** 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
+            .select()
+            .from(leaveRequests)
+            .where(and(eq(leaveRequests.workspaceId, workspaceId), eq(leaveRequests.idempotencyKey, key)))
+            .limit(1);
+        return row;
+    }
     async function loadRequest(tx, workspaceId, requestId) {
         const [row] = await tx
             .select()