@opencxh/domain 1.231.0 → 1.233.0

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

@@ -0,0 +1,85 @@
+import { StrategyHealth, StrategyHealthCategory } from './types';
+/**
+ * The ladder, and the two vocabularies read off it.
+ *
+ * Same split as `ladder.ts` + `item-types.ts` in work: a fixed set that is ours, plus the
+ * resolution that decides what applies. The difference is that a level carries something a work
+ * type does not — an **order** — because the one structural rule in this model is about depth.
+ */
+/** One rung. */
+export interface StrategyLevel {
+    key: string;
+    /** An i18n key for the fixed three; a name somebody typed for anything else. */
+    label: string;
+    /**
+     * Rank, not depth. A parent's order must be at most the child's, so gaps of ten leave room for
+     * an org to slot a rung in between later without renumbering what exists.
+     */
+    order: number;
+    /**
+     * Does this rung carry a measure?
+     *
+     * It steers the form and nothing else — no query branches on it. A measured area is odd but not
+     * wrong, and refusing it here would mean a validation error for something harmless.
+     */
+    measurable: boolean;
+    /** Lucide icon name. */
+    icon?: string;
+}
+/**
+ * The three rungs that are **ours**.
+ *
+ * Labels are i18n keys, for the reason `LOOSE_STATUSES` spells out: a literal string here fixes
+ * the language at module load.
+ *
+ * Three and not more, on purpose. Atlassian Focus lets an admin define several *area* levels
+ * (Market → Business unit → Group); here that is the same rung nested under itself, which
+ * {@link canParent} allows. One key means one meaning in every report, which a per-org level per
+ * customer would not.
+ */
+export declare const FIXED_LEVELS: readonly StrategyLevel[];
+/** The order an unknown level sorts at: below everything declared. */
+export declare const UNKNOWN_LEVEL_ORDER = 999;
+/** How often a check-in is expected when the row does not say. */
+export declare const DEFAULT_CHECK_IN_DAYS = 7;
+/** The rung with this key, or `undefined`. */
+export declare function levelIn(levelKey: string, levels?: readonly StrategyLevel[]): StrategyLevel | undefined;
+/**
+ * The rank of a level key — the sort key of the whole tree.
+ *
+ * An unknown key ranks last rather than first, the same direction `cycleOrder` chose: something
+ * nobody has classified belongs after everything that is classified, not on top of it.
+ */
+export declare function levelOrder(levelKey: string, levels?: readonly StrategyLevel[]): number;
+/**
+ * May a row of `childLevel` hang under one of `parentLevel`?
+ *
+ * One predicate instead of a table of allowed pairs. Equal is allowed and that is the point: it
+ * is what gives an org several area levels without a second concept. An unknown level ranks last,
+ * so it can sit under anything and nothing can sit under it — which is the safe direction for a
+ * 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`.
+ *
+ * On the **name**, like `fixedTypeForName`: an id is per site, a name is what a person
+ * recognises. Nothing here guesses — a level this platform does not know keeps its own key under
+ * its own name, which is the honest outcome.
+ */
+export declare function fixedLevelForName(name: string): string | null;
+export declare function healthCategory(health: StrategyHealth): StrategyHealthCategory;
+/** Every health value in one bucket — what a `healthCategories` filter expands to. */
+export declare function healthsInCategory(categories: readonly StrategyHealthCategory[]): StrategyHealth[];

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

@@ -0,0 +1,85 @@
+import { StrategyHealth, StrategyItem, StrategyMeasure, StrategyProgress } from './types';
+/**
+ * How far along a measurement is, 0..1.
+ *
+ * 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` 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;
+/**
+ * Where a linear pace would stand now, 0..1.
+ *
+ * `undefined` without both dates, and that absence is the contract: a goal with no window has no
+ * expected pace, and defaulting to "now over target" would invent one. A window whose end is not
+ * after its start is refused for the same reason — it cannot state a pace, only a division.
+ */
+export declare function paceRatio(item: Pick<StrategyItem, "startDate" | "targetDate">, now: number): number | undefined;
+/** How far behind the expected pace counts as "at risk" rather than "on track". */
+export declare const AT_RISK_GAP = 0.1;
+/** And how far behind counts as off track. */
+export declare const OFF_TRACK_GAP = 0.25;
+/**
+ * What the numbers would say, if they got a vote.
+ *
+ * **A suggestion, never a write.** It fills the pre-selected chip in the check-in dialog and
+ * nothing else; `health` is only ever set by the person checking in. A goal that is behind
+ * because the work lands in December is on track, and no formula knows that.
+ *
+ * `undefined` when there is nothing to compare against — no ratio, or no pace. A hint with no
+ * basis is worse than no hint.
+ */
+export declare function suggestedHealth(ratio?: number, pace?: number): StrategyHealth | undefined;
+/**
+ * A parent's ratio, from its children.
+ *
+ * The mean of the children that **have** a ratio, and the filter is the whole point: an area
+ * usually holds a measured objective beside an unmeasured sub-area, and counting the latter as
+ * zero would park every area at half of what it is really doing.
+ *
+ * `undefined` when no child carries a measurement — the honest answer, which the screen renders
+ * as "no measurement yet" rather than an empty bar at 0%.
+ *
+ * Unweighted on purpose. Weighting by anything available here (child count, estimate, level)
+ * would be us deciding which bet matters more; an org that wants that says it by splitting the
+ * goal.
+ */
+/**
+ * The share of a linked work set that is done, 0..1.
+ *
+ * `undefined` on an empty set, and that is the whole reason this is not `done / total` at the
+ * call site: nothing linked yet is "no measurement", while `0/0` is `NaN` and a hand-written
+ * guard would render it as an honest-looking 0%.
+ */
+export declare function workRatio(done: number, total: number): number | undefined;
+export declare function rollupChildren(children: readonly {
+    progress?: Pick<StrategyProgress, "ratio">;
+}[]): number | undefined;
+/**
+ * Is a check-in overdue, and by how much?
+ *
+ * Counted from the last check-in, or from creation when there has never been one — a goal created
+ * three weeks ago and never touched is exactly the one worth nudging. Returns `0` when it is not
+ * due yet, so a caller can sort on lateness without a second branch.
+ */
+export declare function checkInOverdueMs(item: Pick<StrategyItem, "checkInEveryDays" | "lastCheckInAt" | "createdAt">, now: number): number;
+/**
+ * The sort key of a strategy item's window: its target date, or the far end of time.
+ *
+ * Same shape and same direction as `cycleOrder`: a row nobody has put a date on belongs *after*
+ * everything that is planned, and `?? 0` would put it on top. Never a bare subtraction — one
+ * `NaN` from a comparator makes `Array.prototype.sort` implementation-defined for every row.
+ */
+export declare function targetOrder(item: Pick<StrategyItem, "targetDate">): number;

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

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

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

@@ -0,0 +1,227 @@
+import { MutationAuthor } from '../../platform/author';
+import { ReportFilters } from '../analytics/report';
+import { OwnerScope } from '../scope/types';
+import { WorkItemSource } from '../work/types';
+/**
+ * Strategy: the layer above execution — what we are betting on, and whether we are getting there.
+ *
+ * One entity for a focus area, an objective and a key result, for the same reason `WorkItem` is
+ * one entity for a task, a case and a deal: they differ in *words*, not in behaviour. Hierarchy,
+ * health, check-ins, linking, access and rollup are identical on all three; the only real
+ * difference is that an area leaves {@link StrategyItem.measure} empty. That is a field, not a
+ * second table.
+ *
+ * The rule that bounds this model, in three questions:
+ *
+ * 1. *Is it a bet, or the work that pays it off?* A bet → a `StrategyItem`. The work → a
+ *    `WorkItem`, linked here, never copied here.
+ * 2. *Is the number judged, or counted?* Judged → {@link StrategyItem.health}, written by a
+ *    person in a check-in. Counted → {@link StrategyItem.progress}, written only by the rollup.
+ *    Nothing writes both.
+ * 3. *Is the answer a number this platform can already produce?* Then it is a
+ *    {@link MeasureSource}, not a new column — every app that reports to analytics is a source.
+ */
+/**
+ * Where something stands, as a person declares it.
+ *
+ * Deliberately **not** derived from {@link StrategyProgress}. A goal at 40% halfway through the
+ * quarter can be perfectly on track (the work lands in December) or already lost (the team was
+ * reassigned), and no formula knows which. `suggestedHealth` offers an opinion in the check-in
+ * dialog; the owner decides.
+ *
+ * `achieved` and `missed` are two values rather than one `closed`, and that is the one place this
+ * model deviates from `WorkResolution` — which is a free label with no outcome flag, at the stated
+ * price that "nothing can compute how much ended well". Answering exactly that is why a goal
+ * exists, so the flag belongs here.
+ */
+export type StrategyHealth = "pending" | "on_track" | "at_risk" | "off_track" | "paused" | "achieved" | "missed";
+/**
+ * The three buckets every list, counter and report asks for.
+ *
+ * Same shape and the same reason as `WorkStatusCategory`: the question "is this still running"
+ * must be answerable without a configuration lookup.
+ */
+export type StrategyHealthCategory = "open" | "paused" | "closed";
+/** How a measured value is read and formatted. */
+export type MeasureUnit = "number" | "percent" | "currency" | "duration_ms";
+/**
+ * Which way is good.
+ *
+ * Without this a falling number reads as failure, and "bring the first reply time back under two
+ * hours" is exactly the goal a team sets first.
+ */
+export type MeasureDirection = "up" | "down";
+/**
+ * Where the current value comes from.
+ *
+ * Four kinds and no fifth: anything else a customer wants to measure is already a metric in the
+ * analytics catalogue, and that is what `metric` is for.
+ */
+export type MeasureSource = 
+/** Somebody types the number at a check-in. The floor — works with no other app installed. */
+{
+    kind: "manual";
+}
+/** The mean of the children that have a ratio. See `rollupChildren`. */
+ | {
+    kind: "children";
+}
+/**
+ * The share of the linked work that is done.
+ *
+ * The set is not stored here: it is the relations on this item's scopeKey, which land in
+ * `WorkItem.keys` and make "everything under this goal" one indexed query. `count` says what a
+ * unit is — one item, or one second of estimated effort. The second is what makes a goal about
+ * a big epic and twenty small chores mean anything.
+ */
+ | {
+    kind: "work";
+    count: "items" | "estimate";
+}
+/**
+ * A counter from the analytics catalogue — this is what makes the layer generic: every app
+ * that is already an `analytics-source` becomes a goal source with no code.
+ *
+ * `window` says which range to count over: `target` is the goal's own start→target window,
+ * `rolling_30d` the last thirty days (for a goal about a *rate* that should hold, not a total
+ * that should accumulate).
+ */
+ | {
+    kind: "metric";
+    metricId: string;
+    filters?: ReportFilters;
+    window: "target" | "rolling_30d";
+};
+/** What "achieved" means as a number. Absent on a row that carries no measurement. */
+export interface StrategyMeasure {
+    unit: MeasureUnit;
+    direction: MeasureDirection;
+    /**
+     * Where we started, and where we are going.
+     *
+     * **Both are absent for a `work` source, and that is the point.** What "done" means there is
+     * the linked set itself — link a fourteenth item and the target is fourteen. A typed target
+     * beside a set that moves is two answers to one question, and the stored one goes stale
+     * silently. For `manual` and `children` they are required, enforced on the write path.
+     *
+     * Not defaulted to zero either: "from 5h30m to 2h" is 0% at the start, while a zero baseline
+     * would report that same goal as already two-thirds done on day one.
+     */
+    startValue?: number;
+    targetValue?: number;
+    source: MeasureSource;
+}
+/**
+ * The outcome of the last rollup. **Never written by a person** — the check-in writes
+ * `currentValue` only when the source is `manual`, and even then through the same path.
+ */
+export interface StrategyProgress {
+    currentValue: number;
+    /** 0..1, clamped. */
+    ratio: number;
+    /** Where a linear pace would stand now, 0..1. Absent without both dates — no invented pace. */
+    paceRatio?: number;
+    /**
+     * The counted set, for a `work` source only.
+     *
+     * Kept beside `ratio` so the screen can say "12 of 20 done" instead of "60%": the fraction is
+     * what was actually counted, and the percentage is the derived thing.
+     */
+    done?: number;
+    total?: number;
+    computedAt: number;
+    /**
+     * The last rollup failed for this row; the value above is stale.
+     *
+     * A separate field rather than a silent old number: a figure with no date on it is the one
+     * thing a strategy screen must not show.
+     */
+    problem?: string;
+}
+/**
+ * A strategy item: a focus area, an objective or a key result.
+ *
+ * Note what is **not** here: no `workItemIds`, no `focusAreaIds`. Everything this row points at
+ * runs through the platform's relation store, and a work item linked here carries
+ * `strategy_item:<id>` in its own `keys` — so "the work under this goal" is one indexed `$in`
+ * in the app that owns the work, not a join this store cannot do.
+ */
+export interface StrategyItem {
+    id: string;
+    organizationId: string;
+    /** A rung of the ladder — see `FIXED_LEVELS`. An unknown key sorts to the bottom. */
+    levelKey: string;
+    name: string;
+    description?: string;
+    /** Lucide icon name. Absent = the reader picks one from the level. */
+    icon?: string;
+    color?: string;
+    /** The gate, in exactly `WorkProject`'s shape so one predicate serves both. */
+    ownerScope: OwnerScope;
+    memberUserIds?: string[];
+    memberTeamIds?: string[];
+    /**
+     * The one accountable person, apart from who may read it.
+     *
+     * Separate from `ownerScope` on purpose: an org-wide goal is visible to everybody and is still
+     * somebody's to answer for. This is also what the check-in reminder is addressed to.
+     */
+    ownerUserId?: string;
+    parentId?: string;
+    /**
+     * The scopeKeys of all ancestors, flattened at write time, top to bottom.
+     *
+     * The same mechanism as `WorkItem.ancestorKeys` and for the same reason: this store cannot
+     * recurse, so "everything under this area" has to be one indexed `$in`. The price is the same
+     * too — moving a row rewrites its whole subtree, and that is a job, not a request.
+     */
+    ancestorKeys?: string[];
+    /**
+     * Epoch ms. Both optional: an imported area may genuinely have no window, and inventing one
+     * would make up the fact the row exists to state. Never sort these with a bare `a - b`.
+     */
+    startDate?: number;
+    targetDate?: number;
+    health: StrategyHealth;
+    /**
+     * How often a check-in is expected, in days. Absent = `DEFAULT_CHECK_IN_DAYS`.
+     *
+     * A number rather than a cron-ish rule: the only question anything asks is "is it overdue",
+     * and that is `lastCheckInAt + days`.
+     */
+    checkInEveryDays?: number;
+    lastCheckInAt?: number;
+    measure?: StrategyMeasure;
+    progress?: StrategyProgress;
+    archived?: boolean;
+    order?: number;
+    /** Ids of this row in source systems (`atlassian-goal:<ari>`). Empty on one created here. */
+    externalIds?: string[];
+    /** Where it came from, in the shape a work item carries. Only the landing writes it. */
+    source?: WorkItemSource;
+    createdBy: string;
+    createdAt?: number;
+    updatedAt?: number;
+}
+/**
+ * One check-in: the rhythm the whole layer runs on.
+ *
+ * Its own table and not a `work_activity` row — that column means a *work item* id, and two id
+ * spaces in one indexed column is the kind of confusion that surfaces months later as the wrong
+ * rows in a feed.
+ *
+ * `value` doubles as the history series: six check-ins are six points, with no separate snapshot
+ * job. That is the same call `WorkCycleSummary` makes — write the number when it is stated, not
+ * every night.
+ */
+export interface StrategyUpdate {
+    id: string;
+    organizationId: string;
+    itemId: string;
+    health: StrategyHealth;
+    note?: string;
+    /** The measured value at that moment. Absent when the row carries no measure. */
+    value?: number;
+    author: MutationAuthor;
+    createdAt?: number;
+}

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

@@ -1,5 +1,6 @@
 export * from './activity';
 export * from './attention';
+export * from './item-types';
 export * from './keys';
 export * from './ladder';
 export * from './types';

package/dist/entities/work/item-types.d.ts

@@ -0,0 +1,59 @@
+import { WorkItemType, WorkProject } from './types';
+/**
+ * Item kinds — the same shape as the status ladder, and for the same reason.
+ *
+ * A kind used to be a key out of a fixed set of four, with `WorkProject.typeKeys` narrowing which
+ * of them a project offered. That works until a project's kinds come from somewhere else: a Jira
+ * project has Story, Epic and whatever the customer invented, and a bare `string[]` has nowhere
+ * to put what they are called. Everything not recognisably a bug flattened onto "task".
+ *
+ * So a kind is now `{ key, label }` per project, exactly like a status — and the two halves of
+ * this file are the two halves of `ladder.ts`: the fixed set that is ours, and the resolution that
+ * decides which set applies.
+ */
+/**
+ * The kinds that are **ours**, available to a project that declares none and to loose work.
+ *
+ * Their labels are **i18n keys, not text**, for the reason `LOOSE_STATUSES` spells out: a literal
+ * string here fixes the language at module level. A kind that came from a source carries a name
+ * somebody typed instead, and {@link labelOfType} is what keeps those apart.
+ *
+ * These keys are **reserved**: a source-defined kind that happens to be called "Bug" resolves onto
+ * `bug` rather than minting a second key for the same idea, which is what keeps a cross-project
+ * filter from listing "Bug" three times. Anything a source calls something else gets a key of its
+ * own, namespaced by project.
+ */
+export declare const FIXED_TYPES: readonly WorkItemType[];
+/** The keys {@link FIXED_TYPES} occupies. A project-defined kind may not claim one. */
+export declare const RESERVED_TYPE_KEYS: readonly string[];
+/**
+ * The kinds that apply to this item.
+ *
+ * A project *without* kinds falls back to ours instead of yielding an empty list — the same
+ * reasoning as `ladderFor`: a picker with zero options is a dead end, and a half-created project
+ * should not be unusable.
+ */
+export declare function typesFor(project?: WorkProject | null): readonly WorkItemType[];
+/** The kind with this key, within a set. `undefined` on a key the set does not have. */
+export declare function typeIn(typeKey: string, types: readonly WorkItemType[]): WorkItemType | undefined;
+/**
+ * Which of our own kinds a source's name means, or `null` when it means none of them.
+ *
+ * Read on the **name** and not on an id, because an id is per site and a name is what a person
+ * recognises. A site that renamed "Bug" to "Defect" still gets `bug`; one that invented "Onderhoud"
+ * gets nothing from here and keeps its own kind under its own name, which is the honest outcome —
+ * guessing would put maintenance work in the bug list.
+ *
+ * Deliberately no `deal`: no source this platform talks to has the concept, and producing one from
+ * a name would be a claim about the work rather than a translation of it.
+ */
+export declare function fixedTypeForName(name: string): string | null;
+/**
+ * Some of {@link FIXED_TYPES}, by key, in the order given.
+ *
+ * For a caller that wants to *narrow* to a few of our own kinds — a project template saying "this
+ * one is about deals". That narrowing is all `typeKeys: string[]` could ever express, and it is
+ * still worth expressing; what it could not do was carry a kind that is not ours. An unknown key
+ * is dropped rather than invented.
+ */
+export declare function fixedTypes(...keys: string[]): WorkItemType[];

package/dist/entities/work/item-types.test.d.ts

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

package/dist/entities/work/types.d.ts

@@ -58,6 +58,25 @@ export interface WorkResolution {
     label: string;
     order: number;
 }
+/**
+ * An item kind: an icon with a label, never a workflow.
+ *
+ * The same shape as {@link WorkStatus} minus the category, because a kind carries no meaning a
+ * query can act on — nothing counts by kind the way `categoryOf` counts by status. `label` is an
+ * i18n key for one of `FIXED_TYPES` and a name somebody typed for anything else; `labelOfType`
+ * is what tells them apart.
+ */
+export interface WorkItemType {
+    key: string;
+    label: string;
+    /**
+     * A hint for the glyph, for a kind that came from a source.
+     *
+     * Absent = the reader picks one from the key, which is right for ours. Deliberately not a URL:
+     * a vendor's icon lives behind that vendor's auth, and a broken image is worse than a shape.
+     */
+    icon?: string;
+}
 /**
  * A project: the carrier of a work process.
  *
@@ -98,8 +117,13 @@ export interface WorkProject {
     statuses: WorkStatus[];
     /** Resolutions, free per project. Empty = closing asks for no reason. */
     resolutions?: WorkResolution[];
-    /** Which item types this project offers. Empty = all of them. */
-    typeKeys?: string[];
+    /**
+     * The kinds this project offers, with their names. Empty = the fixed set.
+     *
+     * Replaced `typeKeys: string[]`, which could only *narrow* a fixed list and had nowhere to put
+     * a label — so a project whose kinds come from elsewhere lost every name it had.
+     */
+    types?: WorkItemType[];
     /** Keys of the `CustomFieldDef`s enabled on this project, in display order. */
     fieldKeys?: string[];
     /** Where a new item starts. Absent = the first status in `order`. */