@wildo-ai/saas-models 1.1.5 → 1.1.6

package/dist/esm/flows-actors/review-deadlines.shared.schemas.js

@@ -0,0 +1,576 @@
+/**
+ * #1628 — deadlines, reminders and escalation for pending human decisions: the declaration a gate carries,
+ * the application's business calendar, and the pure arithmetic both planes arm and advance clocks with.
+ *
+ * Nothing here reads a store or a clock. Every function takes the instants it reasons about, which is what
+ * lets the sweep, the pause/resume doors and the tests share one definition of "when is this due".
+ *
+ * ## The model (researched 2026-09-25; the sources are on #1628)
+ *
+ * - Two SERVICE-TARGET clocks — CLAIM and DECISION — separate from the LAPSE, the hard stop. Missing a target
+ *   fires actions and changes nothing else (WS-HumanTask 1.1 §4.9: "The state of the task is not changed").
+ *   spec-cite: OASIS WS-HumanTask 1.1 (cs-01) §4.9 "Elements for Handling Timeouts and Escalations", fetched 2026-09-27 from https://docs.oasis-open.org/bpel4people/ws-humantask-1.1-spec-cs-01.html
+ * - Durations are ISO-8601 durations (`PT12H`, `P2D`), the form BPMN 2.0.2 timer events and Camunda use.
+ *   Years and months are refused: their length depends on the calendar date, so they are not durations.
+ * - A target counts ELAPSED time by default, or only the working hours of the application's calendar.
+ *   The lapse always counts ELAPSED time: it bounds how long a turn stays open, and a calendar lapse would
+ *   let one stay open for a week of holidays.
+ */
+import { z } from 'zod';
+import { FLOW_ACTOR_APPROVAL_DEFAULT_TIMEOUT_MS } from './flows-actors-execution.shared.schemas.js';
+import { isLabelKeySegment } from '../i18n/application-config-vocabulary.shared.js';
+import { ReviewClockBasis, ReviewDeadlineKind, ReviewDeadlineOutcome, ReviewDeadlineStage, ReviewEscalationActionKind, HumanDecision_Outcome, HumanDecision_RouteKind } from './human-decision.shared.schemas.js';
+//===============================================================
+//  Durations
+//===============================================================
+/**
+ * `P[nW][nD][T[nH][nM][n[.n]S]]`. No years or months, and at least one component. A week is seven days
+ * of elapsed time; on a CALENDAR clock the milliseconds are then counted inside working hours only.
+ */
+const REVIEW_DURATION_PATTERN = /^P(?:(\d+)W)?(?:(\d+)D)?(?:T(?:(\d+)H)?(?:(\d+)M)?(?:(\d+(?:\.\d+)?)S)?)?$/;
+const MS_PER_SECOND = 1000;
+const MS_PER_MINUTE = 60 * MS_PER_SECOND;
+const MS_PER_HOUR = 60 * MS_PER_MINUTE;
+const MS_PER_DAY = 24 * MS_PER_HOUR;
+/** The duration in milliseconds, or `undefined` when `value` is not a positive ISO-8601 duration this model admits. */
+export function parseReviewDurationMs(value) {
+    const match = REVIEW_DURATION_PATTERN.exec(value);
+    if (!match || value === 'P' || value.endsWith('T'))
+        return undefined;
+    const [, weeks, days, hours, minutes, seconds] = match;
+    const ms = Number(weeks ?? 0) * 7 * MS_PER_DAY
+        + Number(days ?? 0) * MS_PER_DAY
+        + Number(hours ?? 0) * MS_PER_HOUR
+        + Number(minutes ?? 0) * MS_PER_MINUTE
+        + Math.round(Number(seconds ?? 0) * MS_PER_SECOND);
+    return ms > 0 ? ms : undefined;
+}
+/** An ISO-8601 duration such as `PT12H` or `P2D`. */
+export const ReviewDurationSchema = z.string().refine((value) => parseReviewDurationMs(value) !== undefined, {
+    message: 'Expected a positive ISO-8601 duration without years or months, such as "PT12H", "P2D" or "PT30M".',
+});
+//===============================================================
+//  Business calendar
+//===============================================================
+/** A day of the week, as the business calendar names working days. */
+export var CalendarWeekday;
+(function (CalendarWeekday) {
+    CalendarWeekday["MONDAY"] = "monday";
+    CalendarWeekday["TUESDAY"] = "tuesday";
+    CalendarWeekday["WEDNESDAY"] = "wednesday";
+    CalendarWeekday["THURSDAY"] = "thursday";
+    CalendarWeekday["FRIDAY"] = "friday";
+    CalendarWeekday["SATURDAY"] = "saturday";
+    CalendarWeekday["SUNDAY"] = "sunday";
+})(CalendarWeekday || (CalendarWeekday = {}));
+/** `Intl`'s short English weekday names, mapped to the vocabulary. Only this module formats dates in English, and never for display. */
+const WEEKDAY_OF_INTL_SHORT_NAME = Object.freeze({
+    Mon: CalendarWeekday.MONDAY,
+    Tue: CalendarWeekday.TUESDAY,
+    Wed: CalendarWeekday.WEDNESDAY,
+    Thu: CalendarWeekday.THURSDAY,
+    Fri: CalendarWeekday.FRIDAY,
+    Sat: CalendarWeekday.SATURDAY,
+    Sun: CalendarWeekday.SUNDAY,
+});
+const LOCAL_TIME_PATTERN = /^([01]\d|2[0-3]):([0-5]\d)$/;
+const LOCAL_DATE_PATTERN = /^\d{4}-(0[1-9]|1[0-2])-(0[1-9]|[12]\d|3[01])$/;
+function minutesOfLocalTime(value) {
+    const match = LOCAL_TIME_PATTERN.exec(value);
+    if (!match)
+        throw new ReviewCalendarError(`"${value}" is not a local time of the form HH:MM.`);
+    return Number(match[1]) * 60 + Number(match[2]);
+}
+function isKnownTimeZone(timeZone) {
+    try {
+        new Intl.DateTimeFormat('en-US', { timeZone });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/** @wildo_source:part:start saas.models.flows-actors.review-calendar facet:layer:shared facet:family:flows-actors facet:audience:app-developer */
+/**
+ * The application's business calendar (#1628): when reviewers are expected to be working. Declared ONCE by
+ * the application, in its backend configuration as `reviewCalendar`, and read by every gate whose CLAIM or
+ * DECISION clock asks for the `CALENDAR` basis.
+ *
+ * - `timeZone` is an IANA zone (`Europe/Paris`). Working hours and holidays are read in it, so a deadline
+ *   stays right across a daylight-saving change.
+ * - `workingHours` is one window per working day, `start` before `end`; a window crossing midnight is refused.
+ * - `holidays` are local dates (`2026-12-25`) on which no working time counts, whatever the weekday.
+ *
+ * A decision submitted on Friday evening with a `PT8H` CALENDAR target is due at the end of Monday's
+ * working day, not on Saturday morning. The lapse is never counted on this calendar.
+ *
+ * One calendar per application, not per tenant: a second calendar would be a second source for the same
+ * fact, and nothing asks for one yet. The shape allows a per-tenant calendar later without a reshape.
+ */
+export const ReviewCalendarSchema = z.object({
+    timeZone: z.string().min(1).refine(isKnownTimeZone, { message: 'Expected an IANA time zone such as "Europe/Paris".' }),
+    workingDays: z.array(z.enum(CalendarWeekday)).min(1).default([
+        CalendarWeekday.MONDAY, CalendarWeekday.TUESDAY, CalendarWeekday.WEDNESDAY, CalendarWeekday.THURSDAY, CalendarWeekday.FRIDAY,
+    ]),
+    workingHours: z.object({
+        start: z.string().regex(LOCAL_TIME_PATTERN, 'Expected HH:MM'),
+        end: z.string().regex(LOCAL_TIME_PATTERN, 'Expected HH:MM'),
+    }).refine((hours) => minutesOfLocalTime(hours.start) < minutesOfLocalTime(hours.end), {
+        message: 'workingHours.start must be before workingHours.end (a window crossing midnight is not supported).',
+    }).default({ start: '09:00', end: '17:00' }),
+    holidays: z.array(z.string().regex(LOCAL_DATE_PATTERN, 'Expected a local date YYYY-MM-DD')).default([]),
+});
+/** @wildo_source:part:end saas.models.flows-actors.review-calendar */
+/** A calendar that cannot answer — refused at startup when declared, so reaching this at run time is a defect. */
+export class ReviewCalendarError extends Error {
+}
+const formatterCache = new Map();
+function formatterFor(timeZone) {
+    let formatter = formatterCache.get(timeZone);
+    if (!formatter) {
+        formatter = new Intl.DateTimeFormat('en-US', {
+            timeZone, hourCycle: 'h23', year: 'numeric', month: '2-digit', day: '2-digit', hour: '2-digit', minute: '2-digit', second: '2-digit', weekday: 'short',
+        });
+        formatterCache.set(timeZone, formatter);
+    }
+    return formatter;
+}
+function zonedPartsOf(instant, timeZone) {
+    const parts = {};
+    for (const part of formatterFor(timeZone).formatToParts(new Date(instant)))
+        parts[part.type] = part.value;
+    const weekday = WEEKDAY_OF_INTL_SHORT_NAME[parts.weekday ?? ''];
+    if (!weekday)
+        throw new ReviewCalendarError(`Could not read the weekday of ${new Date(instant).toISOString()} in "${timeZone}".`);
+    return {
+        year: Number(parts.year), month: Number(parts.month), day: Number(parts.day),
+        hour: Number(parts.hour), minute: Number(parts.minute), second: Number(parts.second), weekday,
+    };
+}
+/** The zone's offset from UTC at `instant`, in milliseconds. */
+function zoneOffsetMs(instant, timeZone) {
+    const p = zonedPartsOf(instant, timeZone);
+    return Date.UTC(p.year, p.month - 1, p.day, p.hour, p.minute, p.second) - Math.floor(instant / MS_PER_SECOND) * MS_PER_SECOND;
+}
+/**
+ * The instant at which the zone's wall clock reads `minutesOfDay` on `date`. Iterates to a fixed point, the
+ * standard way to invert an offset that itself depends on the instant. In a spring-forward gap the wall time
+ * does not exist and the answer lands just after the gap, which is where working time resumes.
+ */
+function instantOfLocalTime(date, minutesOfDay, timeZone) {
+    const wall = Date.UTC(date.year, date.month - 1, date.day, 0, minutesOfDay);
+    let guess = wall;
+    for (let attempt = 0; attempt < 4; attempt += 1) {
+        const next = wall - zoneOffsetMs(guess, timeZone);
+        if (next === guess)
+            break;
+        guess = next;
+    }
+    return guess;
+}
+function nextLocalDate(date) {
+    const next = new Date(Date.UTC(date.year, date.month - 1, date.day + 1));
+    return { year: next.getUTCFullYear(), month: next.getUTCMonth() + 1, day: next.getUTCDate() };
+}
+function isoLocalDate(date) {
+    return `${String(date.year).padStart(4, '0')}-${String(date.month).padStart(2, '0')}-${String(date.day).padStart(2, '0')}`;
+}
+/** Ten years of days. A calendar with at least one working day finds a window long before this. */
+const MAX_CALENDAR_DAYS_SCANNED = 3660;
+function previousLocalDate(date) {
+    const previous = new Date(Date.UTC(date.year, date.month - 1, date.day - 1));
+    return { year: previous.getUTCFullYear(), month: previous.getUTCMonth() + 1, day: previous.getUTCDate() };
+}
+function compareLocalDates(a, b) {
+    return (a.year - b.year) || (a.month - b.month) || (a.day - b.day);
+}
+const WEEKDAY_OF_UTC_DAY = Object.freeze([
+    CalendarWeekday.SUNDAY, CalendarWeekday.MONDAY, CalendarWeekday.TUESDAY, CalendarWeekday.WEDNESDAY,
+    CalendarWeekday.THURSDAY, CalendarWeekday.FRIDAY, CalendarWeekday.SATURDAY,
+]);
+/** The local date an instant falls on, in the calendar's zone. */
+function localDateOf(instant, calendar) {
+    const parts = zonedPartsOf(instant, calendar.timeZone);
+    return { year: parts.year, month: parts.month, day: parts.day };
+}
+/**
+ * The working window on a local DATE, or `undefined` on a day off.
+ *
+ * Every walk below steps from DATE to date, never from "the instant a day begins" to the next: in a zone
+ * whose daylight-saving change happens AT MIDNIGHT (America/Havana, America/Santiago) the local midnight of
+ * the changeover day does not exist, and an instant computed for it lands on the day before — so a walk
+ * keyed on day-start instants stops advancing (#1628 review M1). A date always advances.
+ */
+function workingWindowOn(date, calendar) {
+    const weekday = WEEKDAY_OF_UTC_DAY[new Date(Date.UTC(date.year, date.month - 1, date.day)).getUTCDay()];
+    if (!calendar.workingDays.includes(weekday) || calendar.holidays.includes(isoLocalDate(date)))
+        return undefined;
+    return {
+        start: instantOfLocalTime(date, minutesOfLocalTime(calendar.workingHours.start), calendar.timeZone),
+        end: instantOfLocalTime(date, minutesOfLocalTime(calendar.workingHours.end), calendar.timeZone),
+    };
+}
+/**
+ * `start` moved by `durationMs` of WORKING time on `calendar` — forward for a positive duration, backward
+ * for a negative one (a warning `warnBefore` a CALENDAR deadline). A zero duration answers `start`.
+ *
+ * Forward from outside working hours, the first working minute is where counting begins: a `PT1H` target
+ * raised on Saturday is due one hour into Monday's window.
+ */
+export function addBusinessDuration(start, durationMs, calendar) {
+    if (durationMs === 0)
+        return new Date(start.getTime());
+    const origin = start.getTime();
+    if (durationMs > 0) {
+        let date = localDateOf(origin, calendar);
+        let remaining = durationMs;
+        for (let scanned = 0; scanned < MAX_CALENDAR_DAYS_SCANNED; scanned += 1, date = nextLocalDate(date)) {
+            const window = workingWindowOn(date, calendar);
+            if (!window)
+                continue;
+            const from = Math.max(origin, window.start);
+            if (from >= window.end)
+                continue;
+            const available = window.end - from;
+            if (remaining <= available)
+                return new Date(from + remaining);
+            remaining -= available;
+        }
+        throw new ReviewCalendarError('The review calendar has no working time in the next ten years.');
+    }
+    let date = localDateOf(origin, calendar);
+    let remaining = -durationMs;
+    for (let scanned = 0; scanned < MAX_CALENDAR_DAYS_SCANNED; scanned += 1, date = previousLocalDate(date)) {
+        const window = workingWindowOn(date, calendar);
+        if (!window)
+            continue;
+        const to = Math.min(origin, window.end);
+        if (to <= window.start)
+            continue;
+        const available = to - window.start;
+        if (remaining <= available)
+            return new Date(to - remaining);
+        remaining -= available;
+    }
+    throw new ReviewCalendarError('The review calendar has no working time in the previous ten years.');
+}
+/** How much WORKING time on `calendar` lies between `from` and `to`; zero when `to` is not after `from`. */
+export function businessDurationBetween(from, to, calendar) {
+    const begin = from.getTime();
+    const end = to.getTime();
+    if (end <= begin)
+        return 0;
+    const lastDate = localDateOf(end, calendar);
+    let total = 0;
+    let date = localDateOf(begin, calendar);
+    for (let scanned = 0; scanned < MAX_CALENDAR_DAYS_SCANNED && compareLocalDates(date, lastDate) <= 0; scanned += 1, date = nextLocalDate(date)) {
+        const window = workingWindowOn(date, calendar);
+        if (!window)
+            continue;
+        const overlapStart = Math.max(begin, window.start);
+        const overlapEnd = Math.min(end, window.end);
+        if (overlapEnd > overlapStart)
+            total += overlapEnd - overlapStart;
+    }
+    return total;
+}
+/** `start` moved by `durationMs` on the given clock basis. CALENDAR without a calendar is refused. */
+export function shiftOnReviewClock(start, durationMs, basis, calendar) {
+    if (basis === ReviewClockBasis.ELAPSED)
+        return new Date(start.getTime() + durationMs);
+    if (!calendar)
+        throw new ReviewCalendarError('A CALENDAR review clock needs the application\'s `reviewCalendar`, and none is declared.');
+    return addBusinessDuration(start, durationMs, calendar);
+}
+/** How much time the given clock counts between two instants. */
+function countedOnReviewClock(from, to, basis, calendar) {
+    if (basis === ReviewClockBasis.ELAPSED)
+        return Math.max(0, to.getTime() - from.getTime());
+    if (!calendar)
+        throw new ReviewCalendarError('A CALENDAR review clock needs the application\'s `reviewCalendar`, and none is declared.');
+    return businessDurationBetween(from, to, calendar);
+}
+//===============================================================
+//  The gate's declaration
+//===============================================================
+/** @wildo_source:part:start saas.models.flows-actors.review-deadlines-declaration facet:layer:shared facet:family:flows-actors facet:audience:app-developer */
+/** The CLAIM target every gate gets when it declares none: half of its lapse window. */
+export const DEFAULT_REVIEW_CLAIM_FRACTION_OF_LAPSE = 0.5;
+/** The DECISION target every gate gets when it declares none: three quarters of its lapse window. */
+export const DEFAULT_REVIEW_DECISION_FRACTION_OF_LAPSE = 0.75;
+/**
+ * When a service-target deadline falls: a duration after the decision was requested (`'PT4H'`), or a
+ * fraction of the gate's lapse window (`{ fractionOfLapse: 0.5 }`), counted on the target's clock basis.
+ */
+export const ReviewDeadlineAtSchema = z.union([
+    ReviewDurationSchema,
+    z.object({ fractionOfLapse: z.number().gt(0).lt(1) }),
+]);
+/** One service-target clock of a gate: CLAIM or DECISION. */
+export const ReviewDeadlineTargetSchema = z.object({
+    at: ReviewDeadlineAtSchema,
+    /** Elapsed time (the default) or the application's business calendar. */
+    basis: z.enum(ReviewClockBasis).optional(),
+    /** Arms a WARNING stage this long before the deadline, on the same basis. Absent: no warning stage. */
+    warnBefore: ReviewDurationSchema.optional(),
+});
+/**
+ * What a stage does when it fires. The data half of a gate's escalation rule; a REASSIGN rule also names a
+ * target resolver, declared on the backend gate beside it.
+ */
+export const ReviewEscalationRuleSchema = z.object({
+    stage: z.enum(ReviewDeadlineStage),
+    action: z.enum(ReviewEscalationActionKind),
+});
+/**
+ * A gate's deadlines (`humanApproval.deadlines`). Every field is optional, and a gate declaring nothing
+ * still gets the defaults: a 24-hour elapsed lapse, a CLAIM reminder at half of it and a DECISION reminder
+ * at three quarters, each notifying the people who may answer. Notifications grant nothing, so this is on
+ * for every gate; a silent lapse was the surprising behaviour.
+ *
+ * - `lapseAfter` — when the decision ends LAPSED. Always elapsed time.
+ * - `claim` / `decision` — the two service targets.
+ * - `rules` — what fires at each stage, in declaration order. Declaring `rules` REPLACES the default
+ *   reminders, so a gate that wants a reassignment and a reminder declares both. When several REASSIGN rules
+ *   fire at one stage, the first declared wins.
+ * - `pauseStates` — the application's own names for why a reviewer may stop the clocks
+ *   (`'awaiting-requester-information'`), labelled through i18n. A gate declaring none cannot be paused.
+ */
+export const ReviewDeadlinesDeclarationSchema = z.object({
+    lapseAfter: ReviewDurationSchema.optional(),
+    claim: ReviewDeadlineTargetSchema.optional(),
+    decision: ReviewDeadlineTargetSchema.optional(),
+    rules: z.array(ReviewEscalationRuleSchema).optional(),
+    pauseStates: z.array(z.string().trim().min(1)).optional(),
+});
+function resolveTarget(target, defaultFraction, lapseAfterMs) {
+    const at = target?.at ?? { fractionOfLapse: defaultFraction };
+    const afterMs = typeof at === 'string' ? (parseReviewDurationMs(at) ?? 0) : Math.round(at.fractionOfLapse * lapseAfterMs);
+    const warnBeforeMs = target?.warnBefore ? parseReviewDurationMs(target.warnBefore) : undefined;
+    return { afterMs, basis: target?.basis ?? ReviewClockBasis.ELAPSED, ...(warnBeforeMs ? { warnBeforeMs } : {}) };
+}
+/** The rules a gate gets when it declares none: a reminder at each MISSED stage, and at each armed WARNING. */
+function defaultRules(claim, decision) {
+    const notify = (stage) => ({ stage, action: ReviewEscalationActionKind.NOTIFY });
+    return [
+        ...(claim.warnBeforeMs ? [notify(ReviewDeadlineStage.CLAIM_WARNING)] : []),
+        notify(ReviewDeadlineStage.CLAIM_MISSED),
+        ...(decision.warnBeforeMs ? [notify(ReviewDeadlineStage.DECISION_WARNING)] : []),
+        notify(ReviewDeadlineStage.DECISION_MISSED),
+    ];
+}
+/** A gate's declaration (possibly absent) with every default applied. */
+export function resolveReviewDeadlinePolicy(declaration) {
+    // The lapse a gate declaring none gets is the framework's approval window, one source for both.
+    const lapseAfterMs = (declaration?.lapseAfter ? parseReviewDurationMs(declaration.lapseAfter) : undefined) ?? FLOW_ACTOR_APPROVAL_DEFAULT_TIMEOUT_MS;
+    const claim = resolveTarget(declaration?.claim, DEFAULT_REVIEW_CLAIM_FRACTION_OF_LAPSE, lapseAfterMs);
+    const decision = resolveTarget(declaration?.decision, DEFAULT_REVIEW_DECISION_FRACTION_OF_LAPSE, lapseAfterMs);
+    return {
+        lapseAfterMs, claim, decision,
+        rules: declaration?.rules ? [...declaration.rules] : defaultRules(claim, decision),
+        pauseStates: [...(declaration?.pauseStates ?? [])],
+    };
+}
+/** The deadline kind a stage belongs to. */
+export function reviewDeadlineKindOfStage(stage) {
+    switch (stage) {
+        case ReviewDeadlineStage.CLAIM_WARNING:
+        case ReviewDeadlineStage.CLAIM_MISSED:
+            return ReviewDeadlineKind.CLAIM;
+        case ReviewDeadlineStage.DECISION_WARNING:
+        case ReviewDeadlineStage.DECISION_MISSED:
+            return ReviewDeadlineKind.DECISION;
+        default: {
+            const unmapped = stage;
+            throw new Error(`Review deadline stage "${String(unmapped)}" has no kind.`);
+        }
+    }
+}
+/** Whether a stage is a WARNING (before a deadline) rather than the deadline being missed. */
+export function isReviewWarningStage(stage) {
+    return stage === ReviewDeadlineStage.CLAIM_WARNING || stage === ReviewDeadlineStage.DECISION_WARNING;
+}
+/** The MISSED stage a WARNING stage warns about. */
+function missedStageOf(stage) {
+    return reviewDeadlineKindOfStage(stage) === ReviewDeadlineKind.CLAIM ? ReviewDeadlineStage.CLAIM_MISSED : ReviewDeadlineStage.DECISION_MISSED;
+}
+/**
+ * Everything wrong with a gate's deadline declaration, as sentences naming the fix. Empty when it is sound.
+ * Startup refuses a gate with any, so a declaration that can never do what it says never ships:
+ *
+ * - a CALENDAR clock in an application that declares no calendar (#1628 I6) — never silently ELAPSED;
+ * - an ELAPSED target at or after the lapse, which could never fire before the decision ends;
+ * - a warning no earlier than the start of its own clock;
+ * - a rule on a WARNING stage whose `warnBefore` is not declared, which could never fire;
+ * - a REASSIGN rule on an OWNER gate, whose route cannot move.
+ */
+export function reviewDeadlinesDeclarationIssues(declaration, context) {
+    if (!declaration)
+        return [];
+    const parsed = ReviewDeadlinesDeclarationSchema.safeParse(declaration);
+    if (!parsed.success)
+        return parsed.error.issues.map((issue) => `deadlines.${issue.path.join('.')}: ${issue.message}`);
+    const policy = resolveReviewDeadlinePolicy(parsed.data);
+    const issues = [];
+    const targets = [
+        [ReviewDeadlineKind.CLAIM, policy.claim, parsed.data.claim],
+        [ReviewDeadlineKind.DECISION, policy.decision, parsed.data.decision],
+    ];
+    for (const [kind, target] of targets) {
+        if (target.basis === ReviewClockBasis.CALENDAR && !context.calendarDeclared) {
+            issues.push(`deadlines.${kind} counts on the CALENDAR basis, but the application declares no \`reviewCalendar\`. Declare one, or use the ELAPSED basis.`);
+        }
+        if (target.basis === ReviewClockBasis.ELAPSED && target.afterMs >= policy.lapseAfterMs) {
+            issues.push(`deadlines.${kind} falls at or after the lapse (${parsed.data.lapseAfter ?? 'the default 24 hours'}), so it could never fire before the decision ends. Make it earlier, or lengthen lapseAfter.`);
+        }
+        if (target.warnBeforeMs !== undefined && target.warnBeforeMs >= target.afterMs) {
+            issues.push(`deadlines.${kind}.warnBefore is not shorter than the ${kind} target itself, so the warning would fall at or before the request.`);
+        }
+    }
+    for (const rule of policy.rules) {
+        const target = reviewDeadlineKindOfStage(rule.stage) === ReviewDeadlineKind.CLAIM ? policy.claim : policy.decision;
+        if (isReviewWarningStage(rule.stage) && target.warnBeforeMs === undefined) {
+            issues.push(`deadlines.rules names the ${rule.stage} stage, but its clock declares no warnBefore, so that stage is never armed.`);
+        }
+        if (rule.action === ReviewEscalationActionKind.REASSIGN && context.routeKind === HumanDecision_RouteKind.OWNER) {
+            issues.push(`deadlines.rules REASSIGNs at ${rule.stage}, but this gate routes to its OWNER, whose route cannot move.`);
+        }
+    }
+    if (new Set(policy.pauseStates).size !== policy.pauseStates.length) {
+        issues.push('deadlines.pauseStates names a pause state twice.');
+    }
+    // A pause state is also the last segment of its label key, `system_enums.HumanDecisionPauseState.<state>` (#1864),
+    // and the label tree is addressed by dotted path: a state with a dot could never show its word.
+    for (const pauseState of policy.pauseStates) {
+        if (!isLabelKeySegment(pauseState)) {
+            issues.push(`deadlines.pauseStates "${pauseState}" may contain only letters, digits, "_" and "-": it is also the last segment of its label key.`);
+        }
+    }
+    return issues;
+}
+/** Arm a decision's clocks at the moment it is requested. */
+export function armReviewDeadlines(input) {
+    const { requestedAt, policy, calendar } = input;
+    const claimDeadlineAt = shiftOnReviewClock(requestedAt, policy.claim.afterMs, policy.claim.basis, calendar);
+    const decisionDeadlineAt = shiftOnReviewClock(requestedAt, policy.decision.afterMs, policy.decision.basis, calendar);
+    return {
+        lapseAt: new Date(requestedAt.getTime() + policy.lapseAfterMs),
+        claimDeadlineAt,
+        ...(policy.claim.warnBeforeMs ? { claimWarningAt: shiftOnReviewClock(claimDeadlineAt, -policy.claim.warnBeforeMs, policy.claim.basis, calendar) } : {}),
+        claimBasis: policy.claim.basis,
+        decisionDeadlineAt,
+        ...(policy.decision.warnBeforeMs ? { decisionWarningAt: shiftOnReviewClock(decisionDeadlineAt, -policy.decision.warnBeforeMs, policy.decision.basis, calendar) } : {}),
+        decisionBasis: policy.decision.basis,
+    };
+}
+/** The stages in the order they fire when due together. */
+export const REVIEW_DEADLINE_STAGE_ORDER = Object.freeze([
+    ReviewDeadlineStage.CLAIM_WARNING,
+    ReviewDeadlineStage.CLAIM_MISSED,
+    ReviewDeadlineStage.DECISION_WARNING,
+    ReviewDeadlineStage.DECISION_MISSED,
+]);
+/**
+ * May this stage still fire? Not once fired; not a CLAIM stage while the decision is claimed; and not a
+ * WARNING whose deadline has already been missed (or is missed at the same moment) — a warning after the
+ * fact is noise, and leaving it unmarked is honest: it never fired.
+ */
+function stageMayFire(stage, schedule, now) {
+    const dueAt = schedule.dueAt[stage];
+    if (schedule.firedAt[stage] || !dueAt)
+        return false;
+    if (schedule.lapseAt && dueAt.getTime() >= schedule.lapseAt.getTime())
+        return false;
+    if (schedule.claimed && reviewDeadlineKindOfStage(stage) === ReviewDeadlineKind.CLAIM)
+        return false;
+    if (isReviewWarningStage(stage)) {
+        const missed = missedStageOf(stage);
+        if (schedule.firedAt[missed])
+            return false;
+        const missedDue = schedule.dueAt[missed];
+        if (now && missedDue && missedDue.getTime() <= now.getTime())
+            return false;
+        // A warning about a deadline that falls at or after the lapse warns of something that will never come.
+        if (schedule.lapseAt && missedDue && missedDue.getTime() >= schedule.lapseAt.getTime())
+            return false;
+    }
+    return true;
+}
+/** The stages due at `now`, in firing order. */
+export function dueReviewDeadlineStages(schedule, now) {
+    return REVIEW_DEADLINE_STAGE_ORDER.filter((stage) => stageMayFire(stage, schedule, now) && schedule.dueAt[stage].getTime() <= now.getTime());
+}
+/**
+ * The earliest instant any stage may still fire at — what the row's indexed next-due column holds, so the
+ * sweep selects due rows by index. `undefined` when nothing is left to fire.
+ */
+export function nextReviewDeadlineDueAt(schedule) {
+    let next;
+    for (const stage of REVIEW_DEADLINE_STAGE_ORDER) {
+        if (!stageMayFire(stage, schedule))
+            continue;
+        const dueAt = schedule.dueAt[stage];
+        if (!next || dueAt.getTime() < next.getTime())
+            next = dueAt;
+    }
+    return next;
+}
+/**
+ * The service targets after a pause from `pausedAt` to `resumedAt`. Each clock stopped at `pausedAt`: an
+ * instant still ahead of it keeps the time that was left, counted on its own basis, from `resumedAt`. An
+ * instant already behind it has passed and does not move.
+ */
+export function resumeReviewServiceTargets(targets, pausedAt, resumedAt, calendar) {
+    const move = (instant, basis) => {
+        if (!instant || instant.getTime() <= pausedAt.getTime())
+            return instant;
+        return shiftOnReviewClock(resumedAt, countedOnReviewClock(pausedAt, instant, basis, calendar), basis, calendar);
+    };
+    return {
+        ...targets,
+        claimDeadlineAt: move(targets.claimDeadlineAt, targets.claimBasis),
+        claimWarningAt: move(targets.claimWarningAt, targets.claimBasis),
+        decisionDeadlineAt: move(targets.decisionDeadlineAt, targets.decisionBasis),
+        decisionWarningAt: move(targets.decisionWarningAt, targets.decisionBasis),
+    };
+}
+/**
+ * Whether each armed service target was MET or MISSED, as the RESOLVED event records it.
+ *
+ * - DECISION is missed when its MISSED stage fired, when the decision lapsed (nobody decided), or when it
+ *   ended after the deadline.
+ * - CLAIM is met when the decision was claimed, or settled by a person, by the CLAIM deadline; missed when
+ *   its MISSED stage fired, or when it was taken — or lapsed — only after the deadline.
+ *
+ * - A WITHDRAWN decision was taken by nobody and answered by nobody, so it is measured only where a
+ *   deadline had ALREADY been missed before the withdrawal; a clock it was withdrawn inside is omitted,
+ *   never reported as met.
+ *
+ * The deadlines passed in must already include any pause, including one still open when the decision
+ * ended (see `resumeReviewServiceTargets`): a clock that was stopped cannot have been missed while it was.
+ *
+ * A clock that was never armed (a row from before #1628) is omitted rather than guessed.
+ */
+export function reviewDeadlineOutcomesOf(input) {
+    const outcomes = {};
+    if (input.outcome === HumanDecision_Outcome.WITHDRAWN) {
+        if (input.claimDeadlineAt && input.claimMissedFiredAt)
+            outcomes[ReviewDeadlineKind.CLAIM] = ReviewDeadlineOutcome.MISSED;
+        if (input.decisionDeadlineAt && input.decisionMissedFiredAt)
+            outcomes[ReviewDeadlineKind.DECISION] = ReviewDeadlineOutcome.MISSED;
+        return outcomes;
+    }
+    const lapsed = input.outcome === HumanDecision_Outcome.LAPSED;
+    if (input.decisionDeadlineAt) {
+        const missed = !!input.decisionMissedFiredAt || lapsed || input.resolvedAt.getTime() > input.decisionDeadlineAt.getTime();
+        outcomes[ReviewDeadlineKind.DECISION] = missed ? ReviewDeadlineOutcome.MISSED : ReviewDeadlineOutcome.MET;
+    }
+    if (input.claimDeadlineAt) {
+        const deadline = input.claimDeadlineAt.getTime();
+        const takenBy = input.claimedAt ?? (lapsed ? undefined : input.resolvedAt);
+        const met = !input.claimMissedFiredAt && takenBy !== undefined && takenBy.getTime() <= deadline;
+        outcomes[ReviewDeadlineKind.CLAIM] = met ? ReviewDeadlineOutcome.MET : ReviewDeadlineOutcome.MISSED;
+    }
+    return outcomes;
+}
+//# sourceMappingURL=review-deadlines.shared.schemas.js.map