feat(reports): cascade an unmet plan onto the periods that remain

A target is a quota, not a flat allowance. The Plan column spread it evenly
and kept asking for the same twelfth of a yearly figure no matter how far
behind the year had fallen, so the one number operations actually needs —
what must move per month for the rest of the year — was nowhere on the
page.

Plan now keeps its meaning and a Required column sits beside it. Plan is
the committed spread and never moves, which is the whole reason it stays:
Implement Rate is measured against it, so a month that missed still reads
as a month that missed. Required is the same target read as a quota — at
each bucket, whatever is still outstanding spread across the time still
left. A 1,200 t year 20% met by June asks 140 t of June and 960 t of
December, which is 1,200 less the 240 delivered. Over-delivery clamps to
zero rather than going negative.

Attainment is deliberately measured with the user's date bounds stripped
(attainmentCtx) and every other filter left in place. Reusing the report's
own filtered aggregate would make a July-only view read year-to-date as
nothing delivered and demand the entire year's tonnage from one month —
the failure would look like a plausible number, not an error.

Granularity gains half-year, nine-month and 90-day. Postgres has no
date_trunc for any of them, so PERIOD_UNITS entries became builders rather
than fragments to interpolate, and all eight blocks anchor to the calendar
year. Nine does not divide twelve and 90 does not divide 365: a nine-month
year is Jan-Sep plus a short Oct-Dec, and the fourth 90-day block absorbs
the remainder at 95 days. That last one is a choice — uncapped floor
division opens a five-day stub bucket every December, which is noise
rather than a period.

Two consequences of the shared unit table, both handled here:

- plannedRowsSql now generates a day at a time and groups, instead of
  stepping by the bucket width. The ragged blocks restart each January, so
  stepping 90 days from January 1st walks off the anchor in the second
  year. Day grain also gets partial-bucket overlap for free, at the same
  sub-day precision the old clipping had.
- nextPeriodOrdinalExpr asks the unit for its next block start rather than
  adding its own step. revenue-by-period evaluates a regression there, and
  a ragged unit's final block is shorter than its nominal width, so + step
  would land past the next block and forecast at the wrong x.

Verified against Postgres 16 with the entities synchronised into it: all
272 report/granularity combinations in the registry EXPLAIN clean, and the
1,200 t drill-down sums back to 1,200 at every one of the eight grains.

apps/edr-freight-api/src/modules/reports/revenue-classification.ts

@@ -230,22 +230,103 @@ END`;
 // ---------------------------------------------------------------------------
 
 /**
- * Frozen whitelist. The runner coerces a `select` filter to a trimmed string
- * or null; that string is used only as an object key here, so the user's value
- * never reaches SQL — one of five compile-time constants does.
+ * A granularity, as SQL builders rather than fragments to interpolate.
  *
- * Every format is zero-padded, so lexicographic order equals chronological
- * order. The growth window depends on that.
+ * Five of the eight are plain `date_trunc` units. The other three — half-year,
+ * nine-month, ninety-day — have no `date_trunc` equivalent in Postgres, so they
+ * are offset arithmetic from the start of the calendar year. Builders let both
+ * kinds live behind one interface.
  */
-const PERIOD_UNITS = {
-  day: { trunc: 'day', fmt: 'YYYY-MM-DD', label: 'Daily', step: '1 day' },
-  week: { trunc: 'week', fmt: 'IYYY-"W"IW', label: 'Weekly', step: '1 week' },
-  month: { trunc: 'month', fmt: 'YYYY-MM', label: 'Monthly', step: '1 month' },
+interface PeriodUnit {
+  label: string;
+  /** Interval one whole block wide. Only exact for the six regular units. */
+  step: string;
+  /** Timestamp expression → the start of the block that timestamp falls in. */
+  truncOn: (dateExpr: string) => string;
+  /** Block-start expression → its display label. */
+  labelOn: (truncExpr: string) => string;
+  /**
+   * Block-start expression → the start of the NEXT block. Not always
+   * `+ step`: a ragged unit's final block of the year is shorter than its own
+   * step, so stepping past it overshoots into the wrong block.
+   */
+  nextStartOn: (truncExpr: string) => string;
+}
+
+const regular = (trunc: string, fmt: string, label: string, step: string): PeriodUnit => ({
+  label,
+  step,
+  truncOn: (dateExpr) => `date_trunc('${trunc}', ${dateExpr})`,
+  labelOn: (truncExpr) => `to_char(${truncExpr}, '${fmt}')`,
+  nextStartOn: (truncExpr) => `(${truncExpr} + INTERVAL '${step}')`,
+});
+
+/**
+ * Blocks of `months` months counted from January, so they reset every calendar
+ * year. Six divides twelve and nine does not: a nine-month year is Jan–Sep plus
+ * a short Oct–Dec. That ragged tail is inherent to the unit — the alternative
+ * is blocks that drift out of the calendar, which is not what "calendar
+ * anchored" means.
+ */
+const monthBlocks = (months: number, marker: string, label: string): PeriodUnit => ({
+  label,
+  step: `${months} months`,
+  truncOn: (dateExpr) =>
+    `(date_trunc('year', ${dateExpr})` +
+    ` + (((EXTRACT(MONTH FROM ${dateExpr})::int - 1) / ${months}) * INTERVAL '${months} months'))`,
+  labelOn: (truncExpr) =>
+    `(to_char(${truncExpr}, 'YYYY') || '-${marker}' ||` +
+    ` ((EXTRACT(MONTH FROM ${truncExpr})::int - 1) / ${months} + 1)::text)`,
+  nextStartOn: (truncExpr) =>
+    `LEAST(${truncExpr} + INTERVAL '${months} months',` +
+    ` date_trunc('year', ${truncExpr}) + INTERVAL '1 year')`,
+});
+
+/**
+ * Frozen whitelist. The runner coerces a `select` filter to a trimmed string or
+ * null; that string is used only as an object key here, so the user's value
+ * never reaches SQL — one of eight compile-time constants does.
+ *
+ * Every label is zero-padded or single-digit-bounded, so lexicographic order
+ * equals chronological order. The growth windows depend on that.
+ */
+const PERIOD_UNITS: Record<string, PeriodUnit> = {
+  day: regular('day', 'YYYY-MM-DD', 'Daily', '1 day'),
+  week: regular('week', 'IYYY-"W"IW', 'Weekly', '1 week'),
+  month: regular('month', 'YYYY-MM', 'Monthly', '1 month'),
   // `quarter` is a valid date_trunc unit but NOT a valid interval unit —
   // INTERVAL '1 quarter' is a syntax error, so the step is spelled in months.
-  quarter: { trunc: 'quarter', fmt: 'YYYY-"Q"Q', label: 'Quarterly', step: '3 months' },
-  year: { trunc: 'year', fmt: 'YYYY', label: 'Yearly', step: '1 year' },
-} as const;
+  quarter: regular('quarter', 'YYYY-"Q"Q', 'Quarterly', '3 months'),
+  half_year: monthBlocks(6, 'H', 'Half-yearly'),
+  nine_month: monthBlocks(9, 'N', 'Nine-monthly'),
+  /**
+   * Four 90-day blocks from January 1st: days 1, 91, 181, 271.
+   *
+   * The block index is capped at 3 on purpose. Uncapped, `(doy - 1) / 90` puts
+   * December 27th onwards in a fifth block — a 5-day stub bucket at the end of
+   * every year, which is noise rather than a period. Capping instead lets the
+   * fourth block absorb the remainder and run 95 or 96 days.
+   *
+   * The label carries the zero-padded start day-of-year, which keeps it sorting
+   * chronologically and — unlike an ordinal — says out loud that the blocks are
+   * day-counted rather than month-aligned.
+   */
+  ninety_day: {
+    label: '90-day',
+    step: '90 days',
+    truncOn: (dateExpr) =>
+      `(date_trunc('year', ${dateExpr})` +
+      ` + (LEAST((EXTRACT(DOY FROM ${dateExpr})::int - 1) / 90, 3) * INTERVAL '90 days'))`,
+    labelOn: (truncExpr) =>
+      `(to_char(${truncExpr}, 'YYYY') || '-D' || lpad(EXTRACT(DOY FROM ${truncExpr})::int::text, 3, '0'))`,
+    // The fourth block ends with the year, not 90 days after it started.
+    nextStartOn: (truncExpr) =>
+      `(CASE WHEN EXTRACT(DOY FROM ${truncExpr})::int >= 271` +
+      ` THEN date_trunc('year', ${truncExpr}) + INTERVAL '1 year'` +
+      ` ELSE ${truncExpr} + INTERVAL '90 days' END)`,
+  },
+  year: regular('year', 'YYYY', 'Yearly', '1 year'),
+};
 
 export const PERIOD_FILTER: ReportFilterDef = {
   key: 'period',
@@ -274,10 +355,8 @@ export function periodExpr(params: Record<string, unknown>): string {
   return periodExprOn(REVENUE_DATE, params);
 }
 
-export function resolvePeriod(
-  params: Record<string, unknown>,
-): (typeof PERIOD_UNITS)[keyof typeof PERIOD_UNITS] {
-  const key = String(params.period ?? '') as keyof typeof PERIOD_UNITS;
+export function resolvePeriod(params: Record<string, unknown>): PeriodUnit {
+  const key = String(params.period ?? '');
   return PERIOD_UNITS[key] ?? PERIOD_UNITS.month;
 }
 
@@ -287,10 +366,10 @@ export function resolvePeriod(
  * these units so a month means the same thing on both sides of the product.
  */
 export const periodExprOn = (dateExpr: string, params: Record<string, unknown>): string =>
-  `to_char(${periodTruncExprOn(dateExpr, params)}, '${resolvePeriod(params).fmt}')`;
+  resolvePeriod(params).labelOn(periodTruncExprOn(dateExpr, params));
 
 export const periodTruncExprOn = (dateExpr: string, params: Record<string, unknown>): string =>
-  `date_trunc('${resolvePeriod(params).trunc}', ${dateExpr})`;
+  resolvePeriod(params).truncOn(dateExpr);
 
 /** The period's start timestamp — what to GROUP BY when a report needs it numerically. */
 export const periodTruncExpr = (params: Record<string, unknown>): string =>
@@ -305,9 +384,16 @@ export const periodTruncExpr = (params: Record<string, unknown>): string =>
 export const periodOrdinalExpr = (params: Record<string, unknown>): string =>
   `EXTRACT(EPOCH FROM ${periodTruncExpr(params)})`;
 
-/** Same scale, one period later — where a one-step-ahead projection lands. */
+/**
+ * Same scale, one period later — where a one-step-ahead projection lands.
+ *
+ * Asks the unit rather than adding its step, because the two differ for the
+ * ragged units: a nine-month year's second block is three months long, and a
+ * 90-day year's fourth is 95, so `+ step` would land past the next block start
+ * and evaluate the regression at the wrong x.
+ */
 export const nextPeriodOrdinalExpr = (params: Record<string, unknown>): string =>
-  `EXTRACT(EPOCH FROM ${periodTruncExpr(params)} + INTERVAL '${resolvePeriod(params).step}')`;
+  `EXTRACT(EPOCH FROM ${resolvePeriod(params).nextStartOn(periodTruncExpr(params))})`;
 
 // ---------------------------------------------------------------------------
 // Volume — measured at line grain, never joined from the booking