@opencxh/domain 1.232.0 → 1.233.0

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

@@ -0,0 +1,100 @@
+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;
+}
+export interface DemandQueryResponse {
+    points: DemandPointResponse[];
+    /** 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[];
+}
+/**
+ * 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/contracts.test.d.ts

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

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,7 @@
+export * from './contracts';
+export * from './coverage';
+export * from './erlang';
+export * from './forecast';
+export * from './keys';
+export * from './kinds';
+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/types.d.ts

@@ -0,0 +1,188 @@
+import { FilterClause } from '../analytics/report';
+import { OwnerScope } from '../scope/types';
+/**
+ * Where a planned row stands.
+ *
+ * `draft` is the whole reason this field exists: a planner builds next week over an afternoon,
+ * and half a roster must not read as coverage while they do. `requested`/`declined` only ever
+ * occur on an approvable kind (leave) — see {@link ScheduleKind.approvable}.
+ */
+export type ScheduleStatus = "draft" | "published" | "requested" | "approved" | "declined" | "cancelled";
+/** Who asked for this row, and why when a system did. */
+export interface ScheduleEntrySource {
+    initiator: "user" | "system";
+    /** Free reason on `system` ("copy_week", "playbook"). Same shape as WorkItemSource. */
+    reason?: string;
+}
+/**
+ * One person, one time span, one kind of time.
+ *
+ * Shift, break, training, leave request, project allocation and customer appointment are all
+ * this row with a different `kindKey`. They share the span, the person, the overlap rules, the
+ * grid, publication and the capacity arithmetic; what differs is whether the kind *makes*
+ * capacity, *spends* it or *takes it away*, and that is two flags on the kind — not three tables.
+ */
+export interface ScheduleEntry {
+    id: string;
+    organizationId: string;
+    /** Who. **Absent = an open shift** — planned work with no name on it, visible as a gap. */
+    userId?: string;
+    /** Only on an open shift: the role being looked for. A free string until skills exist. */
+    placeholderRole?: string;
+    /** Which kind of time. See `FIXED_KINDS`; an unknown key is treated as unproductive. */
+    kindKey: string;
+    /** Epoch ms, half-open `[start, end)` — the same convention as analytics' DateRange. */
+    start: number;
+    end: number;
+    status: ScheduleStatus;
+    /** Where this time goes on the demand side. Absent on a shift = unallocated capacity. */
+    workstreamId?: string;
+    /** Where it goes on the work side: `work_project:7`, `work_item:42`, `company:9`. */
+    scopeKey?: string;
+    /** Which team this time is worked for. Feeds `WorkMode.source = "roster"` later. */
+    teamId?: string;
+    /**
+     * Which `WorkType` the hours on this block will be booked under.
+     *
+     * The join with `apps/time`: planned and booked time land on the same key, so planned-versus-
+     * actual is one grouping instead of a mapping table. Absent = the workstream's default.
+     */
+    workTypeKey?: string;
+    note?: string;
+    /** Set once a published row reached the person's calendar. Absent = never pushed. */
+    calendarEventId?: string;
+    externalIds?: string[];
+    source: ScheduleEntrySource;
+    createdBy: string;
+    createdAt?: number;
+    updatedAt?: number;
+}
+/**
+ * How a workstream's demand is derived.
+ *
+ * Three shapes, one output: required person-seconds per interval. `metric` is the support case
+ * (history → forecast), `source` the delivery case (an app that knows what work is coming),
+ * `fixed` the back-office case (always two people on it).
+ *
+ * `source` is a provider role and not a list of app names on purpose: planning must not grow a
+ * branch per app that can generate work. `metric` needs no provider because analytics already
+ * federates every app's volume — a source only declares itself when its demand is not a
+ * countable stream with a handle time.
+ */
+export type WorkstreamDemand = {
+    kind: "metric";
+    /** An analytics metric id, e.g. "comms.conversations.created". */
+    metricId: string;
+    /** The mapping rule. There is no second rule engine — this *is* it. */
+    filters?: FilterClause[];
+    /** Average handle time per unit, in seconds. */
+    handleSeconds: number;
+    /** A duration metric to read AHT from instead of the fixed number. Not in v1. */
+    handleSecondsMetricId?: string;
+} | {
+    kind: "source";
+    /** The app answering `POST /provider/demand/query`. See {@link DemandSourceDescribe}. */
+    sourceApp: string;
+    /** Opaque to planning, validated by the source: `{ projectIds, cycleId }` for apps/work. */
+    params?: Record<string, unknown>;
+} | {
+    kind: "fixed";
+    headcount: number;
+    /** Local hours the fixed staffing applies to, e.g. `[8, 18]`. Absent = around the clock. */
+    weekdayHours?: [number, number];
+};
+/**
+ * How required work turns into required people.
+ *
+ * `queue` is for work that arrives and waits — you steer on how fast it gets picked up. `hours`
+ * is for work that is already known — you divide it by the clock. Named after the question a
+ * planner answers, not after the maths: `queue` runs Erlang C underneath (see `erlang.ts`), and
+ * a field called `erlang_c` asks every reader to know a 1917 formula before they can pick one.
+ *
+ * `unplannedLossPercent` — shrinkage, in the trade — defaults to 0 on purpose: most WFM tools
+ * assume 25-35% because breaks, training and meetings are not in their roster. Here they are, as
+ * rows that give no coverage. It is only for what you *cannot* roster (sick leave, ad hoc), and
+ * counting it twice is the classic error.
+ */
+export type StaffingPolicy = {
+    model: "hours";
+    unplannedLossPercent?: number;
+} | {
+    model: "queue";
+    /** e.g. 80 for "80% of contacts answered within `targetSeconds`". */
+    serviceLevelPercent: number;
+    targetSeconds: number;
+    /** Cap on how busy an agent may be, e.g. 85. Absent = no cap. */
+    maxOccupancyPercent?: number;
+    unplannedLossPercent?: number;
+};
+/** A bucket demand comes from: an inbox, a project, a process, a pipeline. */
+export interface Workstream {
+    id: string;
+    organizationId: string;
+    /** Org-unique slug — the same shape as `WorkType.key`. */
+    key: string;
+    name: string;
+    description?: string;
+    color?: string;
+    icon?: string;
+    /** Team or org, never personal: a workstream nobody but you can see plans nothing. */
+    ownerScope: OwnerScope;
+    demand: WorkstreamDemand;
+    staffing: StaffingPolicy;
+    /**
+     * The `WorkType` blocks on this workstream get when nobody picks one.
+     *
+     * Deliberately not a `billable` flag of its own. Billability already has a home —
+     * `WorkType.defaultBillable`, which every booked hour resolves through — and a second flag
+     * here would drift from it the first time somebody changes one of the two.
+     */
+    defaultWorkTypeKey?: string;
+    archived?: boolean;
+    order?: number;
+    createdBy: string;
+    createdAt?: number;
+    updatedAt?: number;
+}
+/**
+ * A human override on a forecast, and the only forecast row that is stored.
+ *
+ * The forecast itself is a pure function of history + these; recomputing it on read costs less
+ * than a job plus the "why is this number stale" question that a stored forecast creates.
+ */
+export interface ForecastAdjustment {
+    id: string;
+    organizationId: string;
+    workstreamId: string;
+    /** Epoch ms, half-open `[from, to)`. */
+    from: number;
+    to: number;
+    /** A multiplier (1.3 = campaign week). Ignored when `absoluteVolume` is set. */
+    factor?: number;
+    /** An absolute volume per interval. Wins over `factor`. */
+    absoluteVolume?: number;
+    note?: string;
+    createdBy: string;
+    createdAt?: number;
+}
+/**
+ * One interval of the coverage answer. Derived on read, never stored.
+ *
+ * Headcounts are FTE-equivalents (`seconds / intervalSeconds`) and may be fractional: somebody
+ * who works half the hour covers half of it. Rounding to whole people here would make a
+ * half-staffed interval look either fully covered or empty.
+ */
+export interface CoverageInterval {
+    /** "2026-09-17T09" — the same period key `MetricFact` uses. */
+    period: string;
+    forecastVolume?: number;
+    requiredSeconds: number;
+    requiredHeadcount: number;
+    scheduledSeconds: number;
+    scheduledHeadcount: number;
+    /** `scheduled - required`. Negative = short. */
+    netHeadcount: number;
+    /** All shift time, whether or not it is allocated to this workstream. */
+    capacitySeconds: number;
+    absentSeconds: number;
+}

package/dist/entities/strategy/levels.d.ts

@@ -60,6 +60,18 @@ export declare function levelOrder(levelKey: string, levels?: readonly StrategyL
  * key this platform does not recognise.
  */
 export declare function canParent(childLevelKey: string, parentLevelKey: string, levels?: readonly StrategyLevel[]): boolean;
+/**
+ * The rung a child of this row gets by default.
+ *
+ * What the inline "+" on a row creates: one step down the ladder, so a focus area yields a goal
+ * and a goal yields a key result. **The deepest rung yields itself** rather than nothing — a key
+ * result under a key result is unusual but legal (`canParent` allows equal rungs), and returning
+ * `undefined` would mean the affordance disappears exactly where a team is working deepest.
+ *
+ * An unknown level ranks last, so it also yields itself. That is the safe direction: a level a
+ * source invented gets a sibling, not a guess at what sits under it.
+ */
+export declare function nextLevelBelow(levelKey: string, levels?: readonly StrategyLevel[]): string;
 /**
  * Which of our own rungs a source's name means, or `null`.
  *

package/dist/entities/strategy/progress.d.ts

@@ -4,11 +4,19 @@ import { StrategyHealth, StrategyItem, StrategyMeasure, StrategyProgress } from
  *
  * Measured from `startValue`, not from zero: "from 5h30m down to 2h" is 0% on day one, while a
  * zero baseline would report that same goal as already two-thirds done before anyone did
- * anything. `direction` is what makes the falling case work at all.
+ * anything.
  *
- * When target and start are equal there is no distance to travel, so the ratio is the answer to
- * "are we there": 1 if the current value has reached the target in the intended direction,
- * otherwise 0. Dividing would be `Infinity` or `NaN`, and both render as a full bar.
+ * **`direction` and the bounds have to agree, and this is where they are checked.** The maths
+ * needs no `direction` at all — a falling goal is one whose target lies below its start, and the
+ * division handles that by itself. The field exists for the one case the bounds cannot express
+ * (holding a number steady, where start equals target) and for the label on the form. So when the
+ * two disagree — "lower is better" with a target *above* the start, which a form will happily
+ * accept — the bounds are not a scale at all, and this falls back to the only honest answer:
+ * "are we there, yes or no". Dividing anyway is what reported a goal as 100% done the moment its
+ * value went the wrong way.
+ *
+ * A value that cannot be a number is 0, never `NaN`: a `NaN` ratio renders as an empty bar with
+ * no width and reads as "not started".
  */
 export declare function measureRatio(measure: Pick<StrategyMeasure, "direction" | "startValue" | "targetValue">, currentValue: number): number;
 /**