@letpeoplework/lighthouse-client 1.10.0 → 1.12.0

package/dist/index.d.cts

@@ -8,8 +8,10 @@ export type PlainUsageDataEventName = "TeamCreated" | "TeamDeleted" | "Portfolio
 export type SizingUsageDataEventName = "TeamSizingVoteCast" | "TeamSizingReadinessReached";
 /** The usage event that says which verdict a Team's Refinement showed on its Refinement day. */
 export type VerdictUsageDataEventName = "TeamRefinementDayVerdictShown";
+/** The usage event that says a report was read, and of which type. */
+export type ReportUsageDataEventName = "ReportOpened";
 /** The usage events a client reports, by the names Lighthouse already counts for the web. */
-export type UsageDataEventName = PlainUsageDataEventName | SizingUsageDataEventName | VerdictUsageDataEventName;
+export type UsageDataEventName = PlainUsageDataEventName | SizingUsageDataEventName | VerdictUsageDataEventName | ReportUsageDataEventName;
 /** Fewer Work Items ready than needed, enough, more than enough, or no number at all. */
 export type UsageDataRefinementVerdict = "Below" | "In" | "Above" | "None";
 export type UsageDataSizingMoment = "NoCadence" | "OnRefinementDay" | "OnOtherDay";
@@ -22,7 +24,19 @@ export type UsageDataOccurrence = {
 } | {
   readonly name: VerdictUsageDataEventName;
   readonly refinementVerdict: UsageDataRefinementVerdict;
+} | {
+  readonly name: ReportUsageDataEventName;
+  readonly reportTemplate: UsageDataReportTemplate;
 };
+/** A report's type as Lighthouse names it when it sends the report. */
+export type ReportTemplateKey = "then-and-now";
+/** A report's type in the words usage data publishes, the same the web uses. */
+export type UsageDataReportTemplate = "ThenAndNow";
+/**
+ * The opening of a report Lighthouse sent: its type and nothing else about it. A refused read, or a report of a
+ * type this version does not know, counts nothing.
+ */
+export declare const reportOpenedOccurrencesOf: (answered: LighthouseApiResult<unknown>) => readonly UsageDataOccurrence[];
 /** What Lighthouse's answer about a Team's Refinement says about today. */
 export type RefinementMomentFacts = {
   readonly nextRefinementDate: string | null;
@@ -195,6 +209,7 @@ export type DeliveryListItem = {
   readonly hasSufficientData: boolean | undefined;
   readonly isOverdue: boolean | undefined;
   readonly likelyBy: string | undefined;
+  readonly likelyByBeyondHorizonYears?: number;
 };
 /** The Portfolio whose Deliveries are listed; its name stays undefined when it could not be read. */
 export type DeliveryListOwner = {
@@ -269,7 +284,7 @@ export declare const describeDeliveryFeatureHeadings: (terms: Terms) => string[]
 export declare const describeDeliveryFeatureRow: (feature: DeliveryFeatureMetric) => string[];
 /** The forecast distribution's column headings. */
 export declare const describeDeliveryChanceHeadings: () => string[];
-/** One chance of the day's forecast: "85%" and the day it is that likely to be done by. */
+/** One chance of the day's forecast: "85%" and the day it is that likely to be done by, or "More than 5 years". */
 export declare const describeDeliveryChanceRow: (chance: DeliveryWhenDistributionPoint) => string[];
 //#endregion
 //#region src/featureWording.d.ts
@@ -277,6 +292,7 @@ export declare const describeDeliveryChanceRow: (chance: DeliveryWhenDistributio
 export type FeatureStart = {
   readonly observedOn: string | undefined;
   readonly likelyBy: string | undefined;
+  readonly likelyByBeyondHorizonYears?: number;
 };
 /** One Feature as a row of the Feature list states it. */
 export type FeatureListItem = {
@@ -288,6 +304,7 @@ export type FeatureListItem = {
   readonly cannotBeForecast: boolean;
   readonly start: FeatureStart;
   readonly likelyBy: string | undefined;
+  readonly likelyByBeyondHorizonYears?: number;
 };
 /**
  * Every Feature in the answer, or null when it is not a list or any one of them comes without its
@@ -305,8 +322,11 @@ export declare const describeFeatureProgress: (feature: Pick<FeatureListItem, "t
  * Team without history; that Team only stops anyone saying when work will begin.
  */
 export declare const describeFeatureStart: (feature: Pick<FeatureListItem, "start" | "cannotBeForecast">) => string;
-/** The day the Feature is 85% likely to be done by, "Cannot forecast", or the mark when none was sent. */
-export declare const describeFeatureCompletion: (feature: Pick<FeatureListItem, "likelyBy" | "cannotBeForecast">) => string;
+/**
+ * The day the Feature is 85% likely to be done by, "More than 5 years" when that lies beyond the simulation
+ * horizon, "Cannot forecast", or the mark when none was sent.
+ */
+export declare const describeFeatureCompletion: (feature: Pick<FeatureListItem, "likelyBy" | "likelyByBeyondHorizonYears" | "cannotBeForecast">) => string;
 /** One Feature as a row of the list, in the order of its headings. */
 export declare const describeFeatureRow: (feature: FeatureListItem, terms: Terms) => string[];
 /** One Work Item of a Feature as the Feature's Work Items list states it. */
@@ -357,11 +377,33 @@ export declare const deliveryLikelihoodAnswer: (facts: Parameters<typeof likelih
   readonly isOverdue?: boolean;
 }) => string;
 //#endregion
+//#region src/forecastPercentileText.d.ts
+/**
+ * A forecast percentile as Lighthouse sends it. A percentile too few simulated runs reached carries
+ * `beyondHorizon` and the horizon's length in `horizonYears`; its `expectedDate` is then only a stand-in
+ * that nothing forecast, kept so an older client still reads a date. An older Lighthouse sends neither.
+ */
+export type ForecastPercentileDate = {
+  readonly expectedDate: string;
+  readonly beyondHorizon?: boolean;
+  readonly horizonYears?: number | null;
+};
+/**
+ * The years of the horizon a percentile lies beyond, or undefined when its date is the forecast. Keyed on
+ * the flag itself, never on the server's version: an older Lighthouse never sends it.
+ */
+export declare const yearsBeyondHorizon: (percentile: unknown) => number | undefined;
+/** The words shown in place of a date for a percentile too few simulated runs reached. */
+export declare const moreThanYearsText: (horizonYears: number) => string;
+/** A percentile's day as a person reads it, or "More than 5 years" when it lies beyond that horizon. */
+export declare const describePercentileDay: (expectedDate: string, horizonYearsBeyond: number | undefined) => string;
+/** One percentile as text: its day, or the words when it lies beyond the horizon. */
+export declare const describePercentileDate: (percentile: ForecastPercentileDate) => string;
+//#endregion
 //#region src/forecastWording.d.ts
 /** One row of the When table: the chance of being done by a calendar day. */
-export type ForecastChanceByDay = {
+export type ForecastChanceByDay = ForecastPercentileDate & {
   readonly probability: number;
-  readonly expectedDate: string;
 };
 /** One row of the How Many table: the chance of getting this many done. */
 export type ForecastChanceOfCount = {
@@ -532,7 +574,15 @@ export declare const readArrivals: typeof readDailyCountChart;
  * range's first day, read as the total and the count of each day. Without a total the days are summed.
  */
 export declare const readRunChart: (value: unknown, range: MetricsDateRange) => DailyCountChartView | null;
-/** A Work Item in progress; an older Lighthouse does not say whether it is blocked. */
+declare const STALE_REASON_KINDS: readonly ["TimeInState", "BlockedDuration", "TimeInStateWhileBlocked"];
+type StaleReasonKind = (typeof STALE_REASON_KINDS)[number];
+/** Why Lighthouse marks a Work Item stale, in whole days on the instance's calendar. */
+export type StaleReason = {
+  readonly kind: StaleReasonKind;
+  readonly days: number;
+  readonly stateName?: string;
+};
+/** A Work Item in progress; an older Lighthouse does not say whether it is blocked, or stale. */
 export type InProgressItem = {
   readonly isBlocked: boolean | undefined;
   readonly referenceId?: string;
@@ -540,6 +590,8 @@ export type InProgressItem = {
   readonly state?: string;
   readonly workItemAge?: number;
   readonly blockedSince?: string;
+  readonly isStale?: boolean;
+  readonly staleReasons?: readonly StaleReason[];
 };
 export type InProgressNowView = {
   readonly asOfDate: string;
@@ -621,7 +673,7 @@ export declare const PREDICTABILITY_SCORE_EXPLANATION = "The predictability scor
 /** What an empty over-time chart says on the web. */
 export declare const OVER_TIME_EMPTY_SENTENCE = "Nothing to show for the selected range. Days appear here as Lighthouse records them.";
 /** Every part of the headline that can be refused or unreadable on its own. */
-export type MetricsHeadlinePart = "wip" | "throughput" | "arrivals" | "blocked" | "totalWorkItemAge" | "predictabilityScore" | "cycleTimePercentiles" | "workItemAgePercentiles" | "workItemAge" | "cumulativeStateTime" | "percentilesOverTime" | "processBehaviorOverTime";
+export type MetricsHeadlinePart = "wip" | "throughput" | "arrivals" | "blocked" | "stale" | "totalWorkItemAge" | "predictabilityScore" | "cycleTimePercentiles" | "workItemAgePercentiles" | "workItemAge" | "cumulativeStateTime" | "percentilesOverTime" | "processBehaviorOverTime";
 /** "1 day", "12 days". */
 export declare const describeDays: (days: number) => string;
 /** The label each part of the headline goes by, in the instance's words. */
@@ -640,10 +692,13 @@ export declare const describeAsOfHeading: (subject: Pick<MetricsSubject, "endDat
 export declare const describeInProgressNow: (now: InProgressNowView, scope: MetricsScope, terms: Terms, systemWipLimit: number | undefined) => MetricLine;
 /** "Blocked Work Items  2", or null when Lighthouse does not say which items are blocked. */
 export declare const describeBlockedNow: (now: InProgressNowView, scope: MetricsScope, terms: Terms) => MetricLine | null;
+/** "Stale Work Items  2", or null when Lighthouse does not say which items are stale. */
+export declare const describeStaleNow: (now: InProgressNowView, scope: MetricsScope, terms: Terms) => MetricLine | null;
 /**
  * The sentences that stand in for what a WIP answer cannot show: no System WIP Limit, a Lighthouse that does
- * not say which Work Items are Blocked (which is not the same as none being Blocked), and nothing in progress.
- * A limit of null means the Team or Portfolio could not be read; it may well have one, so nothing is said.
+ * not say which Work Items are Blocked or Stale (which is not the same as none being so), and nothing in
+ * progress. A limit of null means the Team or Portfolio could not be read; it may well have one, so nothing
+ * is said.
  */
 export declare const describeWhatWipLeavesUnsaid: (now: InProgressNowView, scope: MetricsScope, terms: Terms, systemWipLimit: number | undefined | null) => readonly string[];
 /** "Total Throughput  31  1.0 / day". */
@@ -1010,6 +1065,86 @@ export declare const myVoteOn: (refinement: Pick<TeamRefinement, "workItems">, w
 /** {@link nameOfMyVote}, read from Lighthouse; null when the log cannot be read either. */
 export declare const readNameOfMyVote: (client: Pick<LighthouseClient, "getRefinementLog">, teamId: number, workItem: string, voterKey: string | undefined) => Promise<string | null>;
 //#endregion
+//#region src/reportWording.d.ts
+/** Who a report belongs to: a Team or a Portfolio. */
+export type ReportOwnerKind = "team" | "portfolio";
+/** The Team or Portfolio whose reports are read, by its id. */
+export type ReportOwner = {
+  readonly kind: ReportOwnerKind;
+  readonly id: number;
+};
+/** A window of days as Lighthouse sends it: its first and its last day. */
+export type ReportWindow = {
+  readonly start: string;
+  readonly end: string;
+};
+/** What a report's summary says: its name and its two windows. */
+export type ReportView = {
+  readonly name: string;
+  readonly thenWindow: ReportWindow;
+  readonly nowWindow: ReportWindow;
+};
+/** One report as a list row shows it. Fields Lighthouse did not send stay undefined. */
+export type ReportListItem = {
+  readonly id: number;
+  readonly name: string;
+  readonly templateKey: string | undefined;
+  readonly createdOn: string | undefined;
+};
+/** The report's name and windows, or null when the answer does not carry all three. */
+export declare const readReport: (value: unknown) => ReportView | null;
+/**
+ * Every report in the list, or null when the answer holds no list or any one report comes without its id or
+ * name: a row that cannot say which report it is would misname the whole list.
+ */
+export declare const readReportList: (value: unknown) => ReportListItem[] | null;
+/** The owner as the instance names it, "Team Lightspeed", or by its id when its name could not be read. */
+export declare const describeReportOwner: (kind: ReportOwnerKind, id: number, owner: unknown, terms: Terms) => string;
+/** The report's name, its owner and its two windows, one to a line. */
+export declare const describeReportSummary: (report: ReportView, owner: string) => string;
+/** How many reports the owner has, then each report's name, type and created day. */
+export declare const describeReportListSummary: (reports: readonly ReportListItem[], owner: string) => string;
+/** A summary of Lighthouse's answer, said of its owner; null when the answer is not one the summary can read. */
+export type ReportSummariser = (value: unknown, owner: string) => string | null;
+export declare const summariseReport: ReportSummariser;
+export declare const summariseReportList: ReportSummariser;
+/** What was read: the owner's list of reports, or one report. */
+export type ReportRead = "list" | "report";
+/**
+ * Why a report or a list could not be read, in words the reader can act on: the web's sentence where it has
+ * one. Any other refusal, the client's own "upgrade Lighthouse" among them, keeps its category and reason.
+ */
+export declare const describeReportRefusal: (error: LighthouseApiError, kind: ReportOwnerKind, read: ReportRead, terms: Terms) => string;
+/**
+ * {@link describeReportRefusal} in the instance's own words. A refusal the client made before asking, as for a
+ * Lighthouse too old for reports, asks that Lighthouse nothing more, not even its words.
+ */
+export declare const readReportRefusal: (source: TermsSource, error: LighthouseApiError, kind: ReportOwnerKind, read: ReportRead) => Promise<string>;
+//#endregion
+//#region src/reportReads.d.ts
+/** The four report reads, a Team's and a Portfolio's list and one report of each. */
+export type ReportReads = Pick<LighthouseClient, "getTeamReports" | "getTeamReport" | "getPortfolioReports" | "getPortfolioReport">;
+/** The owner's list of reports, exactly as Lighthouse answers it. */
+export declare const readOwnersReports: (reads: ReportReads, owner: ReportOwner) => Promise<LighthouseApiResult<unknown>>;
+/** One of the owner's reports, exactly as Lighthouse answers it. */
+export declare const readOwnersReport: (reads: ReportReads, owner: ReportOwner, reportId: number) => Promise<LighthouseApiResult<unknown>>;
+type OwnerRead = (id: number) => Promise<{
+  readonly ok: true;
+  readonly value: unknown;
+} | {
+  readonly ok: false;
+}>;
+/** Where the owner's name and the instance's words are read from. */
+export type ReportOwnerSource = TermsSource & {
+  readonly getTeam: OwnerRead;
+  readonly getPortfolio: OwnerRead;
+};
+/**
+ * {@link describeReportOwner} for an owner read from Lighthouse. Its name only labels a summary, so an owner that
+ * cannot be read is named by its id instead, and this never fails.
+ */
+export declare const readReportOwner: (source: ReportOwnerSource, owner: ReportOwner) => Promise<string>;
+//#endregion
 //#region src/usageDataStore.d.ts
 /** The answer kept for a Lighthouse, undefined when never asked there, or "unreadable" when the file is not ours. */
 export type UsageDataStoreReading = StoredUsageDataAnswer | undefined | "unreadable";
@@ -1431,6 +1566,10 @@ export type DeliveryFeatureMetric = {
 export type DeliveryWhenDistributionPoint = {
   readonly probability: number;
   readonly expectedDate: string;
+  /** True when too few simulated runs reached this chance: `expectedDate` is then only a stand-in. Absent on an older Lighthouse. */
+  readonly beyondHorizon?: boolean;
+  /** The simulation horizon, in years, this chance was forecast with. Absent on an older Lighthouse and on days recorded before it. */
+  readonly horizonYears?: number | null;
 };
 /** A delivery as it stood on one recorded day. Dates are ISO strings. */
 export type DeliveryMetricsHistoryPoint = {
@@ -1754,6 +1893,11 @@ export type LighthouseClient = {
   readonly addRefinementComment: (teamId: number, workItem: string, comment: RefinementCommentInput) => Promise<LighthouseApiResult<VotedRow>>;
   readonly takeBackRefinementVote: (teamId: number, workItem: string, takeBack: RefinementTakeBackInput) => Promise<LighthouseApiResult<VotedRow>>;
   readonly getRefinementLog: (teamId: number, workItem: string, options?: RefinementReadOptions) => Promise<LighthouseApiResult<SizingLog>>;
+  /** A report list or a report exactly as Lighthouse answers it, so nothing on the way rounds or judges a value. */
+  readonly getTeamReports: (teamId: number) => Promise<LighthouseApiResult<unknown>>;
+  readonly getTeamReport: (teamId: number, reportId: number) => Promise<LighthouseApiResult<unknown>>;
+  readonly getPortfolioReports: (portfolioId: number) => Promise<LighthouseApiResult<unknown>>;
+  readonly getPortfolioReport: (portfolioId: number, reportId: number) => Promise<LighthouseApiResult<unknown>>;
   readonly getTerminology: () => Promise<LighthouseApiResult<readonly TerminologyEntry[]>>;
   readonly listPortfolios: () => Promise<LighthouseApiResult<readonly unknown[]>>;
   readonly getPortfolio: (portfolioId: number) => Promise<LighthouseApiResult<unknown>>;
@@ -1851,6 +1995,8 @@ export declare const FEATURE_REQUIRES_SERVER_NEWER_THAN: {
   readonly sleRisk: "v26.9.19.10";
   readonly teamRefinement: "v26.10.3.6";
   readonly refinementVotes: "v26.10.3.6";
+  readonly staleness: "v26.10.16.6";
+  readonly reports: "v26.10.10.1";
 };
 /**
  * Returns true when `candidate` is strictly newer than `baseline`, false when
@@ -1861,4 +2007,5 @@ export declare const isServerVersionNewerThan: (candidate: string, baseline: str
 /** The header a client sends its voter key in, so Lighthouse can tell its votes from anyone else's. */
 export declare const VOTER_KEY_HEADER = "X-Lighthouse-Voter-Key";
 export declare const createLighthouseClient: (configuration: LighthouseClientConfiguration, dependencies?: LighthouseClientDependencies) => LighthouseClient;
-//#endregion
+//#endregion
+export {};

package/dist/index.d.ts

@@ -8,8 +8,10 @@ export type PlainUsageDataEventName = "TeamCreated" | "TeamDeleted" | "Portfolio
 export type SizingUsageDataEventName = "TeamSizingVoteCast" | "TeamSizingReadinessReached";
 /** The usage event that says which verdict a Team's Refinement showed on its Refinement day. */
 export type VerdictUsageDataEventName = "TeamRefinementDayVerdictShown";
+/** The usage event that says a report was read, and of which type. */
+export type ReportUsageDataEventName = "ReportOpened";
 /** The usage events a client reports, by the names Lighthouse already counts for the web. */
-export type UsageDataEventName = PlainUsageDataEventName | SizingUsageDataEventName | VerdictUsageDataEventName;
+export type UsageDataEventName = PlainUsageDataEventName | SizingUsageDataEventName | VerdictUsageDataEventName | ReportUsageDataEventName;
 /** Fewer Work Items ready than needed, enough, more than enough, or no number at all. */
 export type UsageDataRefinementVerdict = "Below" | "In" | "Above" | "None";
 export type UsageDataSizingMoment = "NoCadence" | "OnRefinementDay" | "OnOtherDay";
@@ -22,7 +24,19 @@ export type UsageDataOccurrence = {
 } | {
   readonly name: VerdictUsageDataEventName;
   readonly refinementVerdict: UsageDataRefinementVerdict;
+} | {
+  readonly name: ReportUsageDataEventName;
+  readonly reportTemplate: UsageDataReportTemplate;
 };
+/** A report's type as Lighthouse names it when it sends the report. */
+export type ReportTemplateKey = "then-and-now";
+/** A report's type in the words usage data publishes, the same the web uses. */
+export type UsageDataReportTemplate = "ThenAndNow";
+/**
+ * The opening of a report Lighthouse sent: its type and nothing else about it. A refused read, or a report of a
+ * type this version does not know, counts nothing.
+ */
+export declare const reportOpenedOccurrencesOf: (answered: LighthouseApiResult<unknown>) => readonly UsageDataOccurrence[];
 /** What Lighthouse's answer about a Team's Refinement says about today. */
 export type RefinementMomentFacts = {
   readonly nextRefinementDate: string | null;
@@ -195,6 +209,7 @@ export type DeliveryListItem = {
   readonly hasSufficientData: boolean | undefined;
   readonly isOverdue: boolean | undefined;
   readonly likelyBy: string | undefined;
+  readonly likelyByBeyondHorizonYears?: number;
 };
 /** The Portfolio whose Deliveries are listed; its name stays undefined when it could not be read. */
 export type DeliveryListOwner = {
@@ -269,7 +284,7 @@ export declare const describeDeliveryFeatureHeadings: (terms: Terms) => string[]
 export declare const describeDeliveryFeatureRow: (feature: DeliveryFeatureMetric) => string[];
 /** The forecast distribution's column headings. */
 export declare const describeDeliveryChanceHeadings: () => string[];
-/** One chance of the day's forecast: "85%" and the day it is that likely to be done by. */
+/** One chance of the day's forecast: "85%" and the day it is that likely to be done by, or "More than 5 years". */
 export declare const describeDeliveryChanceRow: (chance: DeliveryWhenDistributionPoint) => string[];
 //#endregion
 //#region src/featureWording.d.ts
@@ -277,6 +292,7 @@ export declare const describeDeliveryChanceRow: (chance: DeliveryWhenDistributio
 export type FeatureStart = {
   readonly observedOn: string | undefined;
   readonly likelyBy: string | undefined;
+  readonly likelyByBeyondHorizonYears?: number;
 };
 /** One Feature as a row of the Feature list states it. */
 export type FeatureListItem = {
@@ -288,6 +304,7 @@ export type FeatureListItem = {
   readonly cannotBeForecast: boolean;
   readonly start: FeatureStart;
   readonly likelyBy: string | undefined;
+  readonly likelyByBeyondHorizonYears?: number;
 };
 /**
  * Every Feature in the answer, or null when it is not a list or any one of them comes without its
@@ -305,8 +322,11 @@ export declare const describeFeatureProgress: (feature: Pick<FeatureListItem, "t
  * Team without history; that Team only stops anyone saying when work will begin.
  */
 export declare const describeFeatureStart: (feature: Pick<FeatureListItem, "start" | "cannotBeForecast">) => string;
-/** The day the Feature is 85% likely to be done by, "Cannot forecast", or the mark when none was sent. */
-export declare const describeFeatureCompletion: (feature: Pick<FeatureListItem, "likelyBy" | "cannotBeForecast">) => string;
+/**
+ * The day the Feature is 85% likely to be done by, "More than 5 years" when that lies beyond the simulation
+ * horizon, "Cannot forecast", or the mark when none was sent.
+ */
+export declare const describeFeatureCompletion: (feature: Pick<FeatureListItem, "likelyBy" | "likelyByBeyondHorizonYears" | "cannotBeForecast">) => string;
 /** One Feature as a row of the list, in the order of its headings. */
 export declare const describeFeatureRow: (feature: FeatureListItem, terms: Terms) => string[];
 /** One Work Item of a Feature as the Feature's Work Items list states it. */
@@ -357,11 +377,33 @@ export declare const deliveryLikelihoodAnswer: (facts: Parameters<typeof likelih
   readonly isOverdue?: boolean;
 }) => string;
 //#endregion
+//#region src/forecastPercentileText.d.ts
+/**
+ * A forecast percentile as Lighthouse sends it. A percentile too few simulated runs reached carries
+ * `beyondHorizon` and the horizon's length in `horizonYears`; its `expectedDate` is then only a stand-in
+ * that nothing forecast, kept so an older client still reads a date. An older Lighthouse sends neither.
+ */
+export type ForecastPercentileDate = {
+  readonly expectedDate: string;
+  readonly beyondHorizon?: boolean;
+  readonly horizonYears?: number | null;
+};
+/**
+ * The years of the horizon a percentile lies beyond, or undefined when its date is the forecast. Keyed on
+ * the flag itself, never on the server's version: an older Lighthouse never sends it.
+ */
+export declare const yearsBeyondHorizon: (percentile: unknown) => number | undefined;
+/** The words shown in place of a date for a percentile too few simulated runs reached. */
+export declare const moreThanYearsText: (horizonYears: number) => string;
+/** A percentile's day as a person reads it, or "More than 5 years" when it lies beyond that horizon. */
+export declare const describePercentileDay: (expectedDate: string, horizonYearsBeyond: number | undefined) => string;
+/** One percentile as text: its day, or the words when it lies beyond the horizon. */
+export declare const describePercentileDate: (percentile: ForecastPercentileDate) => string;
+//#endregion
 //#region src/forecastWording.d.ts
 /** One row of the When table: the chance of being done by a calendar day. */
-export type ForecastChanceByDay = {
+export type ForecastChanceByDay = ForecastPercentileDate & {
   readonly probability: number;
-  readonly expectedDate: string;
 };
 /** One row of the How Many table: the chance of getting this many done. */
 export type ForecastChanceOfCount = {
@@ -532,7 +574,15 @@ export declare const readArrivals: typeof readDailyCountChart;
  * range's first day, read as the total and the count of each day. Without a total the days are summed.
  */
 export declare const readRunChart: (value: unknown, range: MetricsDateRange) => DailyCountChartView | null;
-/** A Work Item in progress; an older Lighthouse does not say whether it is blocked. */
+declare const STALE_REASON_KINDS: readonly ["TimeInState", "BlockedDuration", "TimeInStateWhileBlocked"];
+type StaleReasonKind = (typeof STALE_REASON_KINDS)[number];
+/** Why Lighthouse marks a Work Item stale, in whole days on the instance's calendar. */
+export type StaleReason = {
+  readonly kind: StaleReasonKind;
+  readonly days: number;
+  readonly stateName?: string;
+};
+/** A Work Item in progress; an older Lighthouse does not say whether it is blocked, or stale. */
 export type InProgressItem = {
   readonly isBlocked: boolean | undefined;
   readonly referenceId?: string;
@@ -540,6 +590,8 @@ export type InProgressItem = {
   readonly state?: string;
   readonly workItemAge?: number;
   readonly blockedSince?: string;
+  readonly isStale?: boolean;
+  readonly staleReasons?: readonly StaleReason[];
 };
 export type InProgressNowView = {
   readonly asOfDate: string;
@@ -621,7 +673,7 @@ export declare const PREDICTABILITY_SCORE_EXPLANATION = "The predictability scor
 /** What an empty over-time chart says on the web. */
 export declare const OVER_TIME_EMPTY_SENTENCE = "Nothing to show for the selected range. Days appear here as Lighthouse records them.";
 /** Every part of the headline that can be refused or unreadable on its own. */
-export type MetricsHeadlinePart = "wip" | "throughput" | "arrivals" | "blocked" | "totalWorkItemAge" | "predictabilityScore" | "cycleTimePercentiles" | "workItemAgePercentiles" | "workItemAge" | "cumulativeStateTime" | "percentilesOverTime" | "processBehaviorOverTime";
+export type MetricsHeadlinePart = "wip" | "throughput" | "arrivals" | "blocked" | "stale" | "totalWorkItemAge" | "predictabilityScore" | "cycleTimePercentiles" | "workItemAgePercentiles" | "workItemAge" | "cumulativeStateTime" | "percentilesOverTime" | "processBehaviorOverTime";
 /** "1 day", "12 days". */
 export declare const describeDays: (days: number) => string;
 /** The label each part of the headline goes by, in the instance's words. */
@@ -640,10 +692,13 @@ export declare const describeAsOfHeading: (subject: Pick<MetricsSubject, "endDat
 export declare const describeInProgressNow: (now: InProgressNowView, scope: MetricsScope, terms: Terms, systemWipLimit: number | undefined) => MetricLine;
 /** "Blocked Work Items  2", or null when Lighthouse does not say which items are blocked. */
 export declare const describeBlockedNow: (now: InProgressNowView, scope: MetricsScope, terms: Terms) => MetricLine | null;
+/** "Stale Work Items  2", or null when Lighthouse does not say which items are stale. */
+export declare const describeStaleNow: (now: InProgressNowView, scope: MetricsScope, terms: Terms) => MetricLine | null;
 /**
  * The sentences that stand in for what a WIP answer cannot show: no System WIP Limit, a Lighthouse that does
- * not say which Work Items are Blocked (which is not the same as none being Blocked), and nothing in progress.
- * A limit of null means the Team or Portfolio could not be read; it may well have one, so nothing is said.
+ * not say which Work Items are Blocked or Stale (which is not the same as none being so), and nothing in
+ * progress. A limit of null means the Team or Portfolio could not be read; it may well have one, so nothing
+ * is said.
  */
 export declare const describeWhatWipLeavesUnsaid: (now: InProgressNowView, scope: MetricsScope, terms: Terms, systemWipLimit: number | undefined | null) => readonly string[];
 /** "Total Throughput  31  1.0 / day". */
@@ -1010,6 +1065,86 @@ export declare const myVoteOn: (refinement: Pick<TeamRefinement, "workItems">, w
 /** {@link nameOfMyVote}, read from Lighthouse; null when the log cannot be read either. */
 export declare const readNameOfMyVote: (client: Pick<LighthouseClient, "getRefinementLog">, teamId: number, workItem: string, voterKey: string | undefined) => Promise<string | null>;
 //#endregion
+//#region src/reportWording.d.ts
+/** Who a report belongs to: a Team or a Portfolio. */
+export type ReportOwnerKind = "team" | "portfolio";
+/** The Team or Portfolio whose reports are read, by its id. */
+export type ReportOwner = {
+  readonly kind: ReportOwnerKind;
+  readonly id: number;
+};
+/** A window of days as Lighthouse sends it: its first and its last day. */
+export type ReportWindow = {
+  readonly start: string;
+  readonly end: string;
+};
+/** What a report's summary says: its name and its two windows. */
+export type ReportView = {
+  readonly name: string;
+  readonly thenWindow: ReportWindow;
+  readonly nowWindow: ReportWindow;
+};
+/** One report as a list row shows it. Fields Lighthouse did not send stay undefined. */
+export type ReportListItem = {
+  readonly id: number;
+  readonly name: string;
+  readonly templateKey: string | undefined;
+  readonly createdOn: string | undefined;
+};
+/** The report's name and windows, or null when the answer does not carry all three. */
+export declare const readReport: (value: unknown) => ReportView | null;
+/**
+ * Every report in the list, or null when the answer holds no list or any one report comes without its id or
+ * name: a row that cannot say which report it is would misname the whole list.
+ */
+export declare const readReportList: (value: unknown) => ReportListItem[] | null;
+/** The owner as the instance names it, "Team Lightspeed", or by its id when its name could not be read. */
+export declare const describeReportOwner: (kind: ReportOwnerKind, id: number, owner: unknown, terms: Terms) => string;
+/** The report's name, its owner and its two windows, one to a line. */
+export declare const describeReportSummary: (report: ReportView, owner: string) => string;
+/** How many reports the owner has, then each report's name, type and created day. */
+export declare const describeReportListSummary: (reports: readonly ReportListItem[], owner: string) => string;
+/** A summary of Lighthouse's answer, said of its owner; null when the answer is not one the summary can read. */
+export type ReportSummariser = (value: unknown, owner: string) => string | null;
+export declare const summariseReport: ReportSummariser;
+export declare const summariseReportList: ReportSummariser;
+/** What was read: the owner's list of reports, or one report. */
+export type ReportRead = "list" | "report";
+/**
+ * Why a report or a list could not be read, in words the reader can act on: the web's sentence where it has
+ * one. Any other refusal, the client's own "upgrade Lighthouse" among them, keeps its category and reason.
+ */
+export declare const describeReportRefusal: (error: LighthouseApiError, kind: ReportOwnerKind, read: ReportRead, terms: Terms) => string;
+/**
+ * {@link describeReportRefusal} in the instance's own words. A refusal the client made before asking, as for a
+ * Lighthouse too old for reports, asks that Lighthouse nothing more, not even its words.
+ */
+export declare const readReportRefusal: (source: TermsSource, error: LighthouseApiError, kind: ReportOwnerKind, read: ReportRead) => Promise<string>;
+//#endregion
+//#region src/reportReads.d.ts
+/** The four report reads, a Team's and a Portfolio's list and one report of each. */
+export type ReportReads = Pick<LighthouseClient, "getTeamReports" | "getTeamReport" | "getPortfolioReports" | "getPortfolioReport">;
+/** The owner's list of reports, exactly as Lighthouse answers it. */
+export declare const readOwnersReports: (reads: ReportReads, owner: ReportOwner) => Promise<LighthouseApiResult<unknown>>;
+/** One of the owner's reports, exactly as Lighthouse answers it. */
+export declare const readOwnersReport: (reads: ReportReads, owner: ReportOwner, reportId: number) => Promise<LighthouseApiResult<unknown>>;
+type OwnerRead = (id: number) => Promise<{
+  readonly ok: true;
+  readonly value: unknown;
+} | {
+  readonly ok: false;
+}>;
+/** Where the owner's name and the instance's words are read from. */
+export type ReportOwnerSource = TermsSource & {
+  readonly getTeam: OwnerRead;
+  readonly getPortfolio: OwnerRead;
+};
+/**
+ * {@link describeReportOwner} for an owner read from Lighthouse. Its name only labels a summary, so an owner that
+ * cannot be read is named by its id instead, and this never fails.
+ */
+export declare const readReportOwner: (source: ReportOwnerSource, owner: ReportOwner) => Promise<string>;
+//#endregion
 //#region src/usageDataStore.d.ts
 /** The answer kept for a Lighthouse, undefined when never asked there, or "unreadable" when the file is not ours. */
 export type UsageDataStoreReading = StoredUsageDataAnswer | undefined | "unreadable";
@@ -1431,6 +1566,10 @@ export type DeliveryFeatureMetric = {
 export type DeliveryWhenDistributionPoint = {
   readonly probability: number;
   readonly expectedDate: string;
+  /** True when too few simulated runs reached this chance: `expectedDate` is then only a stand-in. Absent on an older Lighthouse. */
+  readonly beyondHorizon?: boolean;
+  /** The simulation horizon, in years, this chance was forecast with. Absent on an older Lighthouse and on days recorded before it. */
+  readonly horizonYears?: number | null;
 };
 /** A delivery as it stood on one recorded day. Dates are ISO strings. */
 export type DeliveryMetricsHistoryPoint = {
@@ -1754,6 +1893,11 @@ export type LighthouseClient = {
   readonly addRefinementComment: (teamId: number, workItem: string, comment: RefinementCommentInput) => Promise<LighthouseApiResult<VotedRow>>;
   readonly takeBackRefinementVote: (teamId: number, workItem: string, takeBack: RefinementTakeBackInput) => Promise<LighthouseApiResult<VotedRow>>;
   readonly getRefinementLog: (teamId: number, workItem: string, options?: RefinementReadOptions) => Promise<LighthouseApiResult<SizingLog>>;
+  /** A report list or a report exactly as Lighthouse answers it, so nothing on the way rounds or judges a value. */
+  readonly getTeamReports: (teamId: number) => Promise<LighthouseApiResult<unknown>>;
+  readonly getTeamReport: (teamId: number, reportId: number) => Promise<LighthouseApiResult<unknown>>;
+  readonly getPortfolioReports: (portfolioId: number) => Promise<LighthouseApiResult<unknown>>;
+  readonly getPortfolioReport: (portfolioId: number, reportId: number) => Promise<LighthouseApiResult<unknown>>;
   readonly getTerminology: () => Promise<LighthouseApiResult<readonly TerminologyEntry[]>>;
   readonly listPortfolios: () => Promise<LighthouseApiResult<readonly unknown[]>>;
   readonly getPortfolio: (portfolioId: number) => Promise<LighthouseApiResult<unknown>>;
@@ -1851,6 +1995,8 @@ export declare const FEATURE_REQUIRES_SERVER_NEWER_THAN: {
   readonly sleRisk: "v26.9.19.10";
   readonly teamRefinement: "v26.10.3.6";
   readonly refinementVotes: "v26.10.3.6";
+  readonly staleness: "v26.10.16.6";
+  readonly reports: "v26.10.10.1";
 };
 /**
  * Returns true when `candidate` is strictly newer than `baseline`, false when
@@ -1861,4 +2007,5 @@ export declare const isServerVersionNewerThan: (candidate: string, baseline: str
 /** The header a client sends its voter key in, so Lighthouse can tell its votes from anyone else's. */
 export declare const VOTER_KEY_HEADER = "X-Lighthouse-Voter-Key";
 export declare const createLighthouseClient: (configuration: LighthouseClientConfiguration, dependencies?: LighthouseClientDependencies) => LighthouseClient;
-//#endregion
+//#endregion
+export {};