@opencxh/domain 1.232.0 → 1.233.1

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

@@ -3,6 +3,7 @@ export * from './dimensions';
 export * from './fact';
 export * from './metric';
 export * from './period';
+export * from './picker';
 export * from './report';
 export * from './source';
 export * from './usage';

package/dist/entities/analytics/picker.d.ts

@@ -0,0 +1,49 @@
+import { DimensionDefinition, DimensionOption } from './dimensions';
+import { MetricDefinition } from './metric';
+/**
+ * Turning a metric catalogue into a picker: which axes a thing may be narrowed on, and what
+ * their values are called.
+ *
+ * In `domain` because it is not one screen's logic. A goal in `apps/work` and a workstream in
+ * `apps/planning` ask the same question of the same catalogue, and the two rules below are the
+ * kind of knowledge that must not be discovered twice — both of them exist because of a silent
+ * failure, not a preference.
+ *
+ * Which axes a thing may be narrowed on, and what their values are called.
+ *
+ * Two rules decide, and both have a silent failure behind them:
+ *
+ * 1. **Only what the metric declares.** The report engine drops a fact that misses the dimension
+ *    it is asked about, so filtering `comms.reply_time.first` on an axis its extractor never
+ *    emits yields `0` rather than an error — a goal that reads as "we achieved nothing", or a
+ *    workstream that needs nobody. `apps/context`'s own metrics carry that warning verbatim.
+ * 2. **Only what we can name.** A dimension is offerable here when the catalogue carries its
+ *    value labels (`options`, which is how a source federates them) or when this app happens to
+ *    hold the entity list — teams and users. `inbox`, `channel` and `provider` are entity-backed
+ *    and live in another app, so offering them would mean a picker full of raw ids. A missing
+ *    option beats an unreadable one.
+ */
+export interface FilterableDimension {
+    id: string;
+    label: string;
+    options: DimensionOption[];
+}
+/** Entity lists this app already holds, keyed by the dimension they name. */
+export interface NamedEntities {
+    team?: DimensionOption[];
+    agent?: DimensionOption[];
+}
+export declare function filterableDimensions(metric: MetricDefinition | undefined, dimensions: readonly DimensionDefinition[], named: NamedEntities): FilterableDimension[];
+/** The readable form of one stored clause: "Team · Support". Falls back to the raw value. */
+export declare function describeClause(clause: {
+    dimensionId: string;
+    value: string;
+}, dimensions: readonly FilterableDimension[]): string;
+/**
+ * One metric as a picker row: its category leads, because that is how somebody looks for it
+ * ("something about response time") and the kit's `Select` has no groups.
+ */
+export declare function metricOption(metric: MetricDefinition): {
+    value: string;
+    label: string;
+};

package/dist/entities/analytics/picker.test.d.ts

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

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/capacity.test.d.ts

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

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

@@ -0,0 +1,118 @@
+import { Grain } from '../analytics/fact';
+/** The provider role group, as a constant so a typo does not silently yield an empty list. */
+export declare const DEMAND_SOURCE_PROVIDER_GROUP = "demand-source";
+/**
+ * `GET /provider/demand/describe` — what this app can be a demand source for.
+ *
+ * `configResource` is the app's own settings UI for a workstream pointed at it, keyed
+ * `"<app>:<Component>"` like every other federated resource. That is deliberately not a
+ * parameter schema: this platform renders a source's configuration by loading the source's own
+ * component, so a new demand source needs zero changes in the workstream form.
+ */
+export interface DemandSourceDescribe {
+    /** The declaring app (== manifest.name == req.source.app). */
+    source: string;
+    /** Human-readable, in the source language; the UI may localise. */
+    label: string;
+    icon?: string;
+    configResource?: string;
+}
+/**
+ * `POST /provider/demand/query` — how much work is coming, bucketed.
+ *
+ * `params` is opaque to planning and validated by the source: the same arrangement a sync
+ * connector's parameters have. Planning stores it on the workstream and hands it back unread.
+ */
+export interface DemandQueryRequest {
+    workstreamId: string;
+    /** Epoch ms, half-open `[from, to)`. */
+    from: number;
+    to: number;
+    grain: Grain;
+    params?: Record<string, unknown>;
+}
+/**
+ * One bucket of demand.
+ *
+ * A source answers in **seconds of work**, because that is the one unit every staffing model
+ * takes. `volume` rides along only when the source counts things a person would recognise
+ * (conversations, orders) — it is shown, never recomputed.
+ */
+export interface DemandPointResponse {
+    /** Period key matching the requested grain: "2026-09-17T09" or "2026-09-17". */
+    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 {
+    /** 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;
+}
+/**
+ * `POST /availability` — who is working right now, and on what.
+ *
+ * The question routing, nudging and assignment all ask, and the reason planning is worth calling
+ * from another app at all: a conversation should not land with somebody who is off shift, and an
+ * agent should not be nudged while on leave.
+ *
+ * ponytail: one instant, not a range. "Is this person free on Thursday afternoon" is a different
+ * question — it needs the calendar's free/busy, which does not exist yet — and answering it here
+ * would mean inventing a half version of it.
+ */
+export interface AvailabilityRequest {
+    /** Ask about these people, or about a whole team. One of the two. */
+    userIds?: string[];
+    teamId?: string;
+    /** Epoch ms. Absent = now. */
+    at?: number;
+}
+export interface AvailabilitySlot {
+    userId: string;
+    /** Is there a published shift covering this instant? */
+    onShift: boolean;
+    /** Is approved leave, sickness or a holiday covering it? Distinct from merely not on shift. */
+    absent: boolean;
+    /** The workstreams this person's time is attributed to right now. Empty = unallocated. */
+    workstreamIds: string[];
+    /** When the current shift ends, if on one. Lets a caller avoid handing over work at 16:58. */
+    shiftEndsAt?: number;
+}
+export interface AvailabilityResponse {
+    at: number;
+    slots: AvailabilitySlot[];
+}

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

@@ -0,0 +1,73 @@
+import { Grain } from '../analytics/fact';
+import { DateRange } from '../analytics/report';
+import { WorkType } from '../time-entry/types';
+import { ScheduleKind } from './kinds';
+import { CoverageInterval, ScheduleEntry, StaffingPolicy, Workstream } from './types';
+/** Do two half-open spans `[start, end)` touch? Ends that meet do not overlap. */
+export declare function overlaps(a: {
+    start: number;
+    end: number;
+}, b: {
+    start: number;
+    end: number;
+}): boolean;
+/** How many seconds of `entry` fall inside `[from, to)`. Zero when they only touch. */
+export declare function overlapSeconds(entry: {
+    start: number;
+    end: number;
+}, from: number, to: number): number;
+/** What one interval asks for, before staffing turns it into people. */
+export interface DemandPoint {
+    /** Contacts/items arriving in this interval (metric-driven). */
+    volume?: number;
+    /** Work seconds needed in this interval (work-driven or fixed). */
+    seconds?: number;
+    /** Average handle time; required alongside `volume`. */
+    handleSeconds?: number;
+}
+/**
+ * Turn one interval's demand into required work and required people.
+ *
+ * `queue` needs a volume and a handle time; asked without them (a work- or fixed-driven
+ * workstream) it falls back to flat hours rather than refusing — the number would otherwise be
+ * missing on exactly the screens that mix both kinds of workstream.
+ */
+export declare function requirementFor(point: DemandPoint, staffing: StaffingPolicy, intervalSeconds: number): {
+    seconds: number;
+    headcount: number;
+};
+export interface CoverageRequest {
+    entries: readonly ScheduleEntry[];
+    workstreamId: string;
+    staffing: StaffingPolicy;
+    /** Demand per period key. A missing key is an interval nothing is expected in. */
+    demand?: Record<string, DemandPoint>;
+    range: DateRange;
+    grain?: Grain;
+    kinds?: readonly ScheduleKind[];
+}
+/**
+ * Required versus scheduled, interval by interval — the whole feature in one function.
+ *
+ * Walks the range once per interval and the entries once per interval; at an hour grain over
+ * eight weeks that is ~1300 buckets, which is why the range is capped at the route rather than
+ * here. Everything it reads is already in memory, so there is no I/O to batch.
+ */
+export declare function coverageFor(request: CoverageRequest): CoverageInterval[];
+/**
+ * The work type a planned block books under, if anything says so.
+ *
+ * The entry beats the workstream default — the same precedence `TimeEntry.billable` has over
+ * `WorkType.defaultBillable`: the concrete row wins from the setting it inherited.
+ */
+export declare function plannedWorkTypeKey(entry: Pick<ScheduleEntry, "workTypeKey">, workstream?: Pick<Workstream, "defaultWorkTypeKey">): string | undefined;
+/**
+ * Does this planned block bill to somebody?
+ *
+ * Resolved through `WorkType.defaultBillable` and nowhere else, so planned and booked hours
+ * answer it from the same row. A block with no work type is not billable: unattributed time
+ * that silently counts as revenue is the error worth being wrong about in the other direction.
+ */
+export declare function plannedBillable(entry: Pick<ScheduleEntry, "workTypeKey">, workstream: Pick<Workstream, "defaultWorkTypeKey"> | undefined, workTypes: readonly Pick<WorkType, "key" | "defaultBillable">[]): boolean;
+/** The intervals that are short-staffed — what a nudge and the shortage badge both read. */
+export declare function shortfalls(intervals: readonly CoverageInterval[]): CoverageInterval[];

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

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

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

@@ -0,0 +1,37 @@
+/**
+ * Erlang C: how many people a queue needs to hit a service level.
+ *
+ * The 1917 formula every WFM product still runs on. Kept here as ~40 lines of arithmetic rather
+ * than a dependency, and computed through the Erlang B recursion because the textbook form
+ * (`A^N / N!`) overflows a double somewhere around N = 170.
+ */
+/**
+ * The probability that an arriving contact has to wait.
+ *
+ * Returns 1 when the queue is offered at least as much traffic as it has agents: without a free
+ * agent in the long run, everybody waits.
+ */
+export declare function erlangC(agents: number, traffic: number): number;
+/**
+ * The fraction of contacts answered within `targetSeconds`.
+ *
+ * `SL = 1 - C · e^(-(N - A)·target / AHT)` — the standard waiting-time tail of the M/M/N queue.
+ */
+export declare function serviceLevel(agents: number, traffic: number, targetSeconds: number, handleSeconds: number): number;
+/** Traffic intensity in erlangs: the share of the interval all the work adds up to. */
+export declare function trafficIntensity(volume: number, handleSeconds: number, intervalSeconds: number): number;
+export interface QueuePolicy {
+    /** e.g. 80 for "80% answered within `targetSeconds`". */
+    serviceLevelPercent: number;
+    targetSeconds: number;
+    /** Cap on `traffic / agents`, e.g. 85. Absent = no cap. */
+    maxOccupancyPercent?: number;
+}
+/**
+ * The smallest number of agents that meets the service level and respects the occupancy cap.
+ *
+ * Walks up from `ceil(A)` rather than solving, because the answer is a small integer and a loop
+ * is easier to read than an inversion. An occupancy cap can push the answer well past what the
+ * service level alone needs — that is its purpose: agents who are busy 98% of an hour burn out.
+ */
+export declare function requiredAgents(volume: number, handleSeconds: number, intervalSeconds: number, policy: QueuePolicy): number;

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

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

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

@@ -0,0 +1,34 @@
+import { DateRange } from '../analytics/report';
+import { ForecastAdjustment } from './types';
+/** One historical bucket, exactly as the analytics report engine returns it. */
+export interface HistoryPoint {
+    /** "YYYY-MM-DDTHH", hour grain, UTC. */
+    period: string;
+    value: number;
+}
+export interface ForecastPoint {
+    period: string;
+    volume: number;
+}
+export interface ForecastOptions {
+    /** How many weeks back to average. More weeks is steadier and slower to react. */
+    weeks?: number;
+    adjustments?: readonly ForecastAdjustment[];
+}
+export declare const DEFAULT_FORECAST_WEEKS = 8;
+/**
+ * Forecast per hour from the same hour in recent weeks, with a trend and human overrides.
+ *
+ * Seasonal-naive on purpose. A support desk's week repeats, so "this Thursday at 10:00 looks
+ * like the last eight Thursdays at 10:00" is most of the signal, and a team lead can read the
+ * number back off the history. Anything cleverer has to be believed rather than checked.
+ *
+ * **A missing bucket is a zero, not a gap — but only on a day the source reported at all.**
+ * Analytics stores no fact for an hour with no traffic, so treating every absence as unknown
+ * would forecast the night away; treating a day the connector was down as zeros would forecast a
+ * quiet week that never happened.
+ *
+ * ponytail: seasonal-naive + linear trend. Swap in a real model only once somebody can show a
+ * week where this was materially wrong — the signature stays the same.
+ */
+export declare function forecastIntervals(history: readonly HistoryPoint[], target: DateRange, options?: ForecastOptions): ForecastPoint[];

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

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

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

@@ -0,0 +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/keys.d.ts

@@ -0,0 +1,12 @@
+/**
+ * The scope kinds this layer claims.
+ *
+ * In `domain` and not in the app because they are a contract: the client builds a key to open a
+ * picker, the planning server authorises it, and an hour booked on an allocation carries it.
+ * Two places spelling a prefix separately drift apart on the first typo, and the symptom is
+ * "no access to this scope" rather than an error that says what is wrong.
+ */
+export declare const SCHEDULE_ENTRY_SCOPE_KIND = "schedule_entry";
+export declare const WORKSTREAM_SCOPE_KIND = "workstream";
+export declare function scheduleEntryScopeKey(entryId: string): string;
+export declare function workstreamScopeKey(workstreamId: string): string;

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

@@ -0,0 +1,56 @@
+import { ScheduleEntry, ScheduleStatus } from './types';
+/**
+ * One kind of scheduled time, and the three questions every consumer asks of it.
+ *
+ * Same shape as `FIXED_LEVELS` in strategy: a fixed set that is ours, plus a resolution that
+ * decides what an unknown key means. The flags are separate because they are independent — a
+ * shift makes capacity without covering anything, an allocation covers without making capacity.
+ */
+export interface ScheduleKind {
+    key: string;
+    /** An i18n key, not a literal: a string here would fix the language at module load. */
+    label: string;
+    /** Does this kind make capacity? Only a shift does. */
+    capacity: boolean;
+    /** Does this kind cover its workstream? */
+    productive: boolean;
+    /** Does this kind take capacity away (leave, sick, holiday)? */
+    absent: boolean;
+    /** Does this kind need approving before it counts? */
+    approvable?: boolean;
+    /** Lucide icon name. */
+    icon?: string;
+}
+/**
+ * The kinds that are **ours** — the legend of the schedule grid.
+ *
+ * Taken from Intercom's activity legend and Float's allocation model, which agree on the same
+ * eight: they are the categories a person's working day actually splits into.
+ */
+export declare const FIXED_KINDS: readonly ScheduleKind[];
+/**
+ * What an unrecognised kind key means: time that blocks the person and covers nothing.
+ *
+ * The safe direction. A key some import invented must never silently *add* capacity or coverage;
+ * being merely busy is the reading that cannot inflate a staffing number.
+ */
+export declare const UNKNOWN_KIND: ScheduleKind;
+export declare function kindFor(kindKey: string, kinds?: readonly ScheduleKind[]): ScheduleKind;
+/**
+ * Does this row count as planned reality?
+ *
+ * The one status gate, in one place. A draft covers nothing, a leave request takes nothing away
+ * until somebody approves it, and a declined or cancelled row is history. Everything that reads
+ * a schedule — coverage, capacity, the calendar push, the analytics rollup — asks exactly this.
+ */
+export declare function countsAsPlanned(status: ScheduleStatus): boolean;
+/**
+ * Does this row cover `workstreamId`?
+ *
+ * A shift that names a workstream covers it directly — the support case, where the whole shift
+ * *is* inbox time and a second row per day would be bookkeeping for its own sake. An allocation
+ * covers by being productive. Absent kinds never cover, whatever they name.
+ */
+export declare function coversWorkstream(entry: Pick<ScheduleEntry, "kindKey" | "workstreamId">, workstreamId: string, kinds?: readonly ScheduleKind[]): boolean;
+/** Does this row belong on the person's calendar once published? Breaks and drafts do not. */
+export declare function belongsOnCalendar(entry: Pick<ScheduleEntry, "kindKey" | "status" | "userId">, kinds?: readonly ScheduleKind[]): boolean;

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

@@ -0,0 +1,63 @@
+/**
+ * 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 calendar days between two instants.
+ *
+ * Counted through `Date`, not by dividing milliseconds: two days a year are 23 or 25 hours long,
+ * and a rotation that slips a day every March is a rota nobody trusts again.
+ */
+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 {};