@opencxh/domain 1.233.0 → 1.234.0

package/dist/entities/planning/capacity.d.ts

@@ -0,0 +1,69 @@
+import { DateRange } from '../analytics/report';
+import { DemandPointResponse } from './contracts';
+import { WorkPattern } from './pattern';
+import { EmploymentTerms } from './terms';
+import { ScheduleEntry } from './types';
+/**
+ * How much capacity somebody has, and how precisely we can say it.
+ *
+ * Three layers, each with its own grain, each overriding the one below for the period it covers.
+ * They do not compete, because they do not measure the same thing:
+ *
+ * | Layer | Says | Grain |
+ * |---|---|---|
+ * | roster | this person, this span | interval |
+ * | pattern | the shape of this day | day, or interval with a start time |
+ * | terms | the amount of this week | week |
+ *
+ * > **Per person per day the highest layer that says anything wins, whole.**
+ * > A rostered day ignores the pattern; a patterned day ignores the terms. Without that rule the
+ * > sources add up — the shrinkage mistake in a new coat, for the third time.
+ *
+ * And the honest consequence: with only terms there is no answer at interval grain. Smearing
+ * thirty-two hours over a hundred and sixty-eight intervals is invented data, so `precision` says
+ * `"week"` and the screen shows a week instead of drawing an hourly chart.
+ */
+/** The weakest link decides: a total is only as precise as its vaguest contributing day. */
+export type CapacityPrecision = "interval" | "day" | "week";
+export interface CapacityTotal {
+    seconds: number;
+    precision: CapacityPrecision;
+    /** Per person, same arithmetic. The key is the user id. */
+    byUser: Record<string, number>;
+}
+export interface CapacitySources {
+    entries: readonly ScheduleEntry[];
+    patterns?: readonly WorkPattern[];
+    terms?: readonly EmploymentTerms[];
+    /** Who to count. Absent = everybody the entries, patterns and terms mention. */
+    userIds?: readonly string[];
+    teamIdsOf?: (userId: string) => readonly string[];
+}
+/**
+ * The capacity in a window, by the ladder above.
+ *
+ * Days are walked rather than intervals: the layers switch per day, and a week's worth of terms
+ * is shared out over the days no higher layer covered — `weeklyMinutes × uncoveredDays / 7`. That
+ * is the only division that needs no assumption about which days are working days.
+ */
+export declare function capacityTotal(range: DateRange, sources: CapacitySources): CapacityTotal;
+export interface PersonCoverage {
+    /** `null` is the pot nobody has taken yet — what is still to be divided. */
+    userId: string | null;
+    requiredSeconds: number;
+    capacitySeconds: number;
+    /** `capacity − required`. Negative = this person is over-committed. */
+    netSeconds: number;
+}
+/**
+ * Required against capacity, per person.
+ *
+ * The number that blocks a sprint. "Ten hours short on the team" is rarely the problem; "Daan has
+ * twelve hours of work and eight hours of time while Iris has four and eight" is, every time — and
+ * a team total hides exactly the imbalance somebody can do something about.
+ *
+ * Work nobody has taken stays a pot of its own rather than being divided over the team: it is
+ * precisely what is still to be assigned, and pretending it is already somebody's would erase the
+ * one thing that is actionable.
+ */
+export declare function coverageByPerson(points: readonly DemandPointResponse[], capacity: CapacityTotal): PersonCoverage[];

package/dist/entities/planning/contracts.d.ts

@@ -43,9 +43,43 @@ export interface DemandPointResponse {
     period: string;
     seconds: number;
     volume?: number;
+    /**
+     * Whose work this already is, carried through from the lump it came from.
+     *
+     * The interval view ignores it and sums; the per-person view groups on it. Without it, placing
+     * a lump would throw away the one thing that makes a sprint's imbalance visible.
+     */
+    userId?: string;
+}
+/**
+ * Work the source knows the size of but not the shape of.
+ *
+ * "748 hours, due by the ninth, 64 of them Bram's" — that is everything a work source can
+ * honestly say. *When* those hours land is a question about when people are available, and the
+ * source has no idea: it cannot see a roster, a working pattern or a holiday.
+ *
+ * So it answers in lumps and planning places them. That is also what keeps office hours out of
+ * `packages/domain`: an earlier version spread work over Monday-to-Friday 09:00-17:00 because
+ * somebody had to decide, and every source inherited the assumption.
+ */
+export interface DemandLump {
+    seconds: number;
+    /** Deadline in epoch ms. Absent = no later than the end of the asked window. */
+    by?: number;
+    /** Whose work this already is. A forecast never knows; an assigned work item always does. */
+    userId?: string;
 }
 export interface DemandQueryResponse {
-    points: DemandPointResponse[];
+    /** Bucketed, for a source that knows its own shape (an hourly forecast). */
+    points?: DemandPointResponse[];
+    /** Unplaced, for a source that knows the size and the deadline. See {@link DemandLump}. */
+    lumps?: DemandLump[];
+    /** The source's natural period, if it has one — a sprint, a phase. Feeds the range picker. */
+    window?: {
+        from: number;
+        to: number;
+        label: string;
+    };
     /** Optional note the source wants shown next to the numbers ("14 items zonder schatting"). */
     caveat?: string;
 }
@@ -82,19 +116,3 @@ export interface AvailabilityResponse {
     at: number;
     slots: AvailabilitySlot[];
 }
-/**
- * Spread a lump of work evenly over the working days of a range.
- *
- * What every work-driven demand source needs and none of them should write twice: a project with
- * 240 open hours and a deadline in three weeks is not 240 hours on the deadline, it is what you
- * have to place per day to get there.
- *
- * **Weekends get nothing.** Not a setting: a source that genuinely runs seven days a week says
- * so by asking for a range of seven-day weeks, and a five-day office that got its estimate
- * smeared over Saturday would read as short every Monday.
- *
- * ponytail: even spread, no calendar of public holidays and no per-person capacity. Both are
- * knowable — holidays from the roster, capacity from the shifts — the day the difference between
- * "what must be done" and "who can do it" is worth two numbers instead of one.
- */
-export declare function spreadSeconds(totalSeconds: number, from: number, to: number, grain?: Grain): DemandPointResponse[];

package/dist/entities/planning/index.d.ts

@@ -1,7 +1,11 @@
+export * from './capacity';
 export * from './contracts';
 export * from './coverage';
 export * from './erlang';
 export * from './forecast';
 export * from './keys';
 export * from './kinds';
+export * from './pattern';
+export * from './spread';
+export * from './terms';
 export * from './types';

package/dist/entities/planning/pattern.d.ts

@@ -0,0 +1,67 @@
+/**
+ * A working pattern: capacity that is simply there, without anybody rostering it.
+ *
+ * A development team works nine to five and never opens a roster; a nurse works four on, four
+ * off; somebody on standby carries a week in every three. All three are the same thing — a cycle
+ * of days that repeats from a fixed starting point — so this is one shape, not a weekly one plus
+ * a rotating one later.
+ *
+ * **The pattern never becomes rows.** It is the fallback for a day nobody planned. See
+ * `capacityOn` for the precedence rule, which exists to stop the two sources adding up.
+ */
+export interface WorkPattern {
+    id: string;
+    organizationId: string;
+    /** Whose. Absent with `teamId` set = the team default, inherited by members without their own. */
+    userId?: string;
+    teamId?: string;
+    /**
+     * Minutes per day of the repeating cycle, starting at {@link WorkPattern.anchor}.
+     *
+     * Seven entries is an ordinary week. Eight is four-on-four-off. Twenty-one is a three-shift
+     * rotation. The length *is* the cycle, which is why there is no separate "repeats every" field
+     * to keep in step with it.
+     */
+    cycleMinutes: number[];
+    /**
+     * The day `cycleMinutes[0]` applies to, at local midnight.
+     *
+     * A rotation needs a fixed point in the calendar or it cannot be placed; a plain week needs one
+     * too, and any Monday will do.
+     */
+    anchor: number;
+    /**
+     * Local start time per cycle day (`"09:00"`), only to draw the implied block on the grid.
+     * Never used by the arithmetic — capacity is an amount, not a position.
+     */
+    startTimes?: (string | undefined)[];
+    /** From when this holds. A changed contract is a new row, never a patch on the old one. */
+    effectiveFrom?: number;
+    createdBy?: string;
+    createdAt?: number;
+    updatedAt?: number;
+}
+/**
+ * Whole days between two instants, rounded.
+ *
+ * **Deliberately timezone-free.** An earlier version normalised both sides to local noon, which
+ * reads the *evaluating* machine's clock — and the two timestamps come from the browser. On a
+ * UTC server a CEST Monday midnight floors to the previous Sunday, the week walks eight days
+ * instead of seven, and the eighth wraps onto cycle day zero: five eight-hour days silently
+ * became six. Rounding the raw difference needs no shared timezone and absorbs the 23- and
+ * 25-hour days of a daylight-saving change on its own.
+ */
+export declare function calendarDaysBetween(from: number, to: number): number;
+/** Which day of the cycle a date falls on. Negative offsets wrap the right way round. */
+export declare function cycleDayIndex(pattern: Pick<WorkPattern, "cycleMinutes" | "anchor">, day: number): number;
+/** Minutes this pattern gives on this day. Zero before it takes effect. */
+export declare function minutesOn(pattern: WorkPattern, day: number): number;
+/** The block the grid draws for a pattern day, if the pattern says where it sits. */
+export declare function patternStartTime(pattern: WorkPattern, day: number): string | undefined;
+/**
+ * The pattern that applies to somebody: their own, else their team's.
+ *
+ * The most recent `effectiveFrom` that has already started wins, so a contract change is made by
+ * adding a row and the old one stays readable next to the weeks it governed.
+ */
+export declare function patternFor(patterns: readonly WorkPattern[], userId: string, teamIds: readonly string[], day: number): WorkPattern | undefined;

package/dist/entities/planning/spread.d.ts

@@ -0,0 +1,61 @@
+import { Grain } from '../analytics/fact';
+import { DateRange } from '../analytics/report';
+import { DemandLump, DemandPointResponse } from './contracts';
+import { WorkPattern } from './pattern';
+import { ScheduleEntry } from './types';
+/**
+ * Placing work: how a lump of hours gets spread across a window.
+ *
+ * **Over the hours people are actually there, in proportion to how many.** Not over office
+ * hours — an earlier version of this file hardcoded Monday-to-Friday 09:00-17:00 in
+ * `packages/domain`, which every work-driven source then inherited, and a twenty-four-hour desk
+ * got its backlog smeared over a working day it does not have.
+ *
+ * It makes demand depend on capacity, and that is the right direction for the question this
+ * serves: *does this fit?* A human placing the same work would do exactly this — look at when
+ * people are in, and fill those hours. The totals do not move when you add somebody, only the
+ * shape does, so "how much is short" stays an honest number.
+ */
+export interface IntervalWeight {
+    period: string;
+    /** Relative, not absolute: only the ratios between intervals matter. */
+    weight: number;
+}
+export interface CapacityWeightOptions {
+    grain?: Grain;
+    /** Working patterns, for the days nobody rostered. See the precedence rule below. */
+    patterns?: readonly WorkPattern[];
+    /** Who to count. Absent = everybody the entries mention. */
+    userIds?: readonly string[];
+    /** Team membership, so a team pattern can be inherited. */
+    teamIdsOf?: (userId: string) => readonly string[];
+}
+/**
+ * Capacity per interval, as weights.
+ *
+ * > **Per person per day, a rostered row wins the whole day.**
+ * > Is there any capacity row for that person that day, the pattern contributes nothing for that
+ * > day; is there none, the pattern does. Without that rule capacity comes from two sources that
+ * > add up — the shrinkage mistake in a new coat.
+ *
+ * A pattern day with a start time becomes a real window. Without one its minutes are spread
+ * evenly across that day's intervals: a fallback inside one day, not a guess about office hours.
+ */
+export declare function capacityWeights(entries: readonly ScheduleEntry[], range: DateRange, options?: CapacityWeightOptions): IntervalWeight[];
+/**
+ * Spread seconds across intervals in proportion to their weight.
+ *
+ * **All the weight at zero means an even spread.** Work that has to be done in a week nobody is
+ * available is still work: bunching it on one interval would read as a single catastrophic hour
+ * instead of a week that is short throughout, and the second is what is true.
+ */
+export declare function spreadOverWeights(totalSeconds: number, weights: readonly IntervalWeight[]): DemandPointResponse[];
+/**
+ * Place every lump a source handed over, each one no later than its own deadline.
+ *
+ * A lump with a deadline is spread only over the intervals before it — work due Friday does not
+ * get planned on Saturday, however available everybody is then. A lump whose deadline is already
+ * past falls back on the whole window, because refusing to show it would hide the one thing that
+ * is certainly late.
+ */
+export declare function placeLumps(lumps: readonly DemandLump[], weights: readonly IntervalWeight[], periodToMs: (period: string) => number): DemandPointResponse[];

package/dist/entities/planning/spread.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/entities/planning/terms.d.ts

@@ -0,0 +1,42 @@
+/**
+ * How many hours somebody is available in a week.
+ *
+ * An employment fact, not a planning one — it changes because a contract changes, and it has
+ * readers outside planning waiting: overtime is booked time above these hours, utilisation is
+ * billable divided by them, and leave accrual is a function of them.
+ *
+ * **It lives in `apps/planning` on purpose, and temporarily.** Three things keep the eventual move
+ * to an HR app a hostname rather than a project: this type is in `domain` and not in the app; the
+ * app keeps it in one resource folder with no terms logic scattered elsewhere; and every reader
+ * reads it over HTTP, which is the only option anyway since apps share no store.
+ */
+export interface EmploymentTerms {
+    id: string;
+    organizationId: string;
+    userId: string;
+    /**
+     * Contract hours, as minutes per week.
+     *
+     * **Known limit:** a Dutch contract is often "36 hours averaged over 13 weeks". This field
+     * cannot say that. An averaging period is one field more the day somebody needs it; it is
+     * written down here so it is not a surprise.
+     */
+    weeklyMinutes: number;
+    /** From when this holds. A changed contract is a new row, never a patch on the old one. */
+    effectiveFrom?: number;
+    note?: string;
+    createdBy: string;
+    createdAt?: number;
+    updatedAt?: number;
+}
+/**
+ * The terms that applied to somebody on a given day.
+ *
+ * The most recent `effectiveFrom` that had already started wins, so the row that governed last
+ * quarter stays readable next to the weeks it governed.
+ *
+ * Deliberately no `fte`: that is `weeklyMinutes` divided by a full-time norm which differs per
+ * organisation — forty hours here, thirty-six elsewhere. Storing it would be a second truth;
+ * showing it can wait until there is a norm to divide by.
+ */
+export declare function termsFor(terms: readonly EmploymentTerms[], userId: string, day: number): EmploymentTerms | undefined;