@classytic/primitives 0.16.0 → 0.19.0

package/dist/state-diagram.d.mts

@@ -0,0 +1,68 @@
+import { StateMachine } from "./state-machine.mjs";
+
+//#region src/workflow/state-diagram.d.ts
+interface StateDiagramOptions<TStatus extends string> {
+  /**
+   * The state a new aggregate starts in. Drawn as `[*] --> initial`.
+   *
+   * NOT inferred: a machine's entry point is a domain fact the adjacency list does
+   * not carry. "The state with no inbound transitions" guesses wrong the moment a
+   * machine has a legal return path into its own start (a retry going
+   * `sent → pending`), and silently drawing the wrong entry point is worse than
+   * drawing none.
+   */
+  readonly initial?: TStatus;
+  /**
+   * Highlight one state — "you are here" for an operator looking at a record.
+   */
+  readonly current?: TStatus;
+  /** Diagram title, rendered above the graph. */
+  readonly title?: string;
+  /**
+   * Label a transition, keyed `"from->to"`. For naming the VERB that causes it
+   * (`"sent->acked": "device confirmed"`), which is the part a reader actually
+   * wants and the table cannot know.
+   */
+  readonly labels?: Readonly<Record<string, string>>;
+  /**
+   * Draw `terminal --> [*]` edges. Default true — a reader needs to see which
+   * states end the lifecycle. Turn off for a dense machine where the extra edges
+   * cost more than they explain.
+   */
+  readonly showTerminal?: boolean;
+}
+/**
+ * A `stateDiagram-v2` for this machine.
+ *
+ * Self-transitions are emitted as-is — mermaid draws them as a loop, and they are
+ * meaningful (`sent → sent` is the device-command re-lease after a lapsed lease),
+ * so suppressing them would hide a real rule.
+ */
+declare function toMermaid<TStatus extends string>(machine: StateMachine<TStatus>, options?: StateDiagramOptions<TStatus>): string;
+/** One row of `describeStateMachine` — a table a UI or a doc can render directly. */
+interface StateDescription<TStatus extends string> {
+  readonly status: TStatus;
+  readonly targets: readonly TStatus[];
+  readonly sources: readonly TStatus[];
+  readonly terminal: boolean;
+}
+/**
+ * The machine as data, for a UI that wants a table rather than a picture — an
+ * action bar asking "which transitions are legal from where this record is now"
+ * reads `targets`, and never has to hardcode a list that drifts from the kernel.
+ */
+declare function describeStateMachine<TStatus extends string>(machine: StateMachine<TStatus>): {
+  readonly name: string;
+  readonly states: readonly StateDescription<TStatus>[];
+};
+/**
+ * States that can never be reached from `initial`.
+ *
+ * A design smell worth a CI check: an unreachable state is either a transition
+ * somebody forgot to declare, or dead vocabulary nobody removed. Both are cheap to
+ * find here and expensive to notice in production, where the symptom is a record
+ * that can never leave the state it is stuck in.
+ */
+declare function unreachableStates<TStatus extends string>(machine: StateMachine<TStatus>, initial: TStatus): readonly TStatus[];
+//#endregion
+export { StateDescription, StateDiagramOptions, describeStateMachine, toMermaid, unreachableStates };

package/dist/state-diagram.mjs

@@ -0,0 +1,66 @@
+//#region src/workflow/state-diagram.ts
+/** Mermaid ids must be identifier-safe; domain statuses are usually snake_case. */
+function safeId(status) {
+	const id = status.replace(/[^A-Za-z0-9_]/g, "_");
+	return /^[0-9]/.test(id) ? `s_${id}` : id;
+}
+/**
+* A `stateDiagram-v2` for this machine.
+*
+* Self-transitions are emitted as-is — mermaid draws them as a loop, and they are
+* meaningful (`sent → sent` is the device-command re-lease after a lapsed lease),
+* so suppressing them would hide a real rule.
+*/
+function toMermaid(machine, options = {}) {
+	const { initial, current, title, labels = {}, showTerminal = true } = options;
+	const lines = [];
+	if (title !== void 0) lines.push("---", `title: ${title}`, "---");
+	lines.push("stateDiagram-v2");
+	if (initial !== void 0) lines.push(`    [*] --> ${safeId(initial)}`);
+	const states = Object.keys(machine.transitions).sort();
+	for (const from of states) for (const to of [...machine.validTargets(from)].sort()) {
+		const label = labels[`${from}->${to}`];
+		lines.push(`    ${safeId(from)} --> ${safeId(to)}${label !== void 0 ? `: ${label}` : ""}`);
+	}
+	if (showTerminal) {
+		for (const state of states) if (machine.isTerminal(state)) lines.push(`    ${safeId(state)} --> [*]`);
+	}
+	if (current !== void 0) lines.push("    classDef current fill:#2563eb,stroke:#1e40af,color:#fff,font-weight:bold", `    class ${safeId(current)} current`);
+	return lines.join("\n");
+}
+/**
+* The machine as data, for a UI that wants a table rather than a picture — an
+* action bar asking "which transitions are legal from where this record is now"
+* reads `targets`, and never has to hardcode a list that drifts from the kernel.
+*/
+function describeStateMachine(machine) {
+	const states = Object.keys(machine.transitions).sort();
+	return {
+		name: machine.name,
+		states: states.map((status) => ({
+			status,
+			targets: [...machine.validTargets(status)].sort(),
+			sources: [...machine.validSources(status)].sort(),
+			terminal: machine.isTerminal(status)
+		}))
+	};
+}
+/**
+* States that can never be reached from `initial`.
+*
+* A design smell worth a CI check: an unreachable state is either a transition
+* somebody forgot to declare, or dead vocabulary nobody removed. Both are cheap to
+* find here and expensive to notice in production, where the symptom is a record
+* that can never leave the state it is stuck in.
+*/
+function unreachableStates(machine, initial) {
+	const seen = new Set([initial]);
+	const queue = [initial];
+	while (queue.length > 0) for (const next of machine.validTargets(queue.pop())) if (!seen.has(next)) {
+		seen.add(next);
+		queue.push(next);
+	}
+	return Object.keys(machine.transitions).filter((s) => !seen.has(s)).sort();
+}
+//#endregion
+export { describeStateMachine, toMermaid, unreachableStates };

package/dist/subject.d.mts

@@ -0,0 +1,65 @@
+//#region src/identity/subject.d.ts
+/**
+ * `SubjectRef` — WHO a record is about, polymorphically.
+ *
+ * The pairing `{ subjectModel, subjectRef }` appears across every package that
+ * has to talk about a person without owning them: an attendance punch, an access
+ * entitlement, a device credential, a loyalty balance. Each of those kernels
+ * deliberately keeps the model a plain `string`, because attendance serves
+ * employees, students and gym members and no kernel can know which.
+ *
+ * ## Why this is NOT `ExternalRef`
+ *
+ * `composition/reference.ts` already models `{ sourceId, sourceModel }` — the
+ * identical SHAPE. They are kept apart because they answer different questions and
+ * that difference is load-bearing:
+ *
+ * - `ExternalRef` — "this record CAME FROM there" (an Order, a Stripe charge, a
+ *   Postgres invoice). Provenance. Used for reconciliation and cascades.
+ * - `SubjectRef` — "this record is ABOUT them". Identity. Used for authorization
+ *   and lookup.
+ *
+ * A grant carries both at once and they mean different things: `originModel:
+ * 'Order'` (what paid) and `subjectModel: 'Party'` (who holds it). Collapsing them
+ * into one type would make that sentence unsayable, and renaming the persisted
+ * `subjectModel`/`subjectRef` fields to `sourceModel`/`sourceId` is the harmful
+ * rename — a migration across many collections that buys nothing.
+ *
+ * ## Why a shared type at all
+ *
+ * The pairing spans SERVER and CLIENT. A server writes it when a membership grant
+ * projects an entitlement; a web app writes it when staff bind a card. When the two
+ * disagree nothing throws — the synchronizer matches on both fields, so it finds
+ * ZERO rows, and freezing a membership silently stops touching the member's card.
+ * That bug shipped: a UI hardcoded `'Customer'` against a server writing `'Party'`.
+ * One shared type plus one shared constant per domain is the fix.
+ */
+/** A polymorphic reference to the subject a record is about. */
+interface SubjectRef {
+  /** Logical model / type name — e.g. 'Party', 'Employee', 'Student', 'ApiKey'. */
+  subjectModel: string;
+  /** Opaque identifier of the subject within that model. */
+  subjectRef: string;
+}
+/**
+ * Build a `SubjectRef`, or `null` when the id is absent/blank.
+ *
+ * Returning null rather than a ref containing `"undefined"` or `""` is the whole
+ * point: a malformed binding does not fail loudly, it silently matches nothing
+ * forever — an entitlement nobody holds, a credential no revoke can find.
+ */
+declare function makeSubjectRef(subjectModel: string, id: string | number | null | undefined): SubjectRef | null;
+/**
+ * The canonical `"Model:id"` string form.
+ *
+ * One formatter so log lines, dedupe keys and command payloads agree. Two
+ * hand-rolled variants (`Party:1` vs `party/1`) look equivalent until one is used
+ * as an idempotency key and the other as a lookup.
+ */
+declare function formatSubjectRef(subject: SubjectRef): string;
+/** Exact equality on both halves — never on the id alone. */
+declare function subjectRefsEqual(a: SubjectRef | null, b: SubjectRef | null): boolean;
+/** Structural guard for data crossing a wire. */
+declare function isSubjectRef(value: unknown): value is SubjectRef;
+//#endregion
+export { SubjectRef, formatSubjectRef, isSubjectRef, makeSubjectRef, subjectRefsEqual };

package/dist/subject.mjs

@@ -0,0 +1,40 @@
+//#region src/identity/subject.ts
+/**
+* Build a `SubjectRef`, or `null` when the id is absent/blank.
+*
+* Returning null rather than a ref containing `"undefined"` or `""` is the whole
+* point: a malformed binding does not fail loudly, it silently matches nothing
+* forever — an entitlement nobody holds, a credential no revoke can find.
+*/
+function makeSubjectRef(subjectModel, id) {
+	const subjectRef = id === null || id === void 0 ? "" : String(id).trim();
+	const model = subjectModel.trim();
+	if (subjectRef.length === 0 || model.length === 0) return null;
+	return {
+		subjectModel: model,
+		subjectRef
+	};
+}
+/**
+* The canonical `"Model:id"` string form.
+*
+* One formatter so log lines, dedupe keys and command payloads agree. Two
+* hand-rolled variants (`Party:1` vs `party/1`) look equivalent until one is used
+* as an idempotency key and the other as a lookup.
+*/
+function formatSubjectRef(subject) {
+	return `${subject.subjectModel}:${subject.subjectRef}`;
+}
+/** Exact equality on both halves — never on the id alone. */
+function subjectRefsEqual(a, b) {
+	if (!a || !b) return false;
+	return a.subjectModel === b.subjectModel && a.subjectRef === b.subjectRef;
+}
+/** Structural guard for data crossing a wire. */
+function isSubjectRef(value) {
+	if (typeof value !== "object" || value === null) return false;
+	const v = value;
+	return typeof v.subjectModel === "string" && v.subjectModel.length > 0 && typeof v.subjectRef === "string" && v.subjectRef.length > 0;
+}
+//#endregion
+export { formatSubjectRef, isSubjectRef, makeSubjectRef, subjectRefsEqual };

package/dist/suspension.d.mts

@@ -0,0 +1,151 @@
+import { UtcOffsetMinutes } from "./calendar.mjs";
+import { DateRange } from "./period.mjs";
+import { StatusChangeEntry } from "./status-history.mjs";
+
+//#region src/workflow/suspension.d.ts
+/**
+ * One suspension, past or current.
+ *
+ * `endedAt` absent or `null` means STILL OPEN — counted up to the evaluation
+ * instant, because an open freeze is consuming allowance right now. Treating an
+ * open span as zero is how an indefinite pause looks free.
+ */
+interface SuspensionSpan {
+  readonly startedAt: Date;
+  readonly endedAt?: Date | null;
+  readonly reason?: string;
+}
+/**
+ * The rulebook. Every field optional; an empty policy permits an unbounded pause,
+ * so a host that has not decided yet gets today's (lenient) behaviour rather than
+ * a surprise refusal.
+ */
+interface SuspensionPolicy {
+  /** `false` refuses outright — many gyms allow a freeze only on medical grounds. */
+  readonly allowed?: boolean;
+  /** Total suspended days permitted per period. Omit for unlimited. */
+  readonly maxDaysPerPeriod?: number;
+  /** Length of the allowance period in months. Default 12. */
+  readonly periodMonths?: number;
+  /** Shortest permitted single pause — stops pause-every-weekend gaming. */
+  readonly minDays?: number;
+  /** Longest permitted single pause, independent of the period allowance. */
+  readonly maxDays?: number;
+  /** How many may be open at once. Default 1. */
+  readonly maxConcurrent?: number;
+  /** Days of advance notice required before a pause may start. */
+  readonly noticeDays?: number;
+  /**
+   * Does resuming push the access window out by the frozen duration?
+   *
+   * Carried here because it is the same decision, made by the same person, as the
+   * rest of the pause rules — but note this primitive only REPORTS it. Applying it
+   * is the entitlement kernel's job (`resume({ creditFrozenDays })`), because only
+   * that kernel owns the window.
+   */
+  readonly creditsWindow?: boolean;
+}
+type SuspensionRefusal = 'not_allowed' | 'allowance_exhausted' | 'below_minimum' | 'above_maximum' | 'already_suspended' | 'insufficient_notice';
+interface SuspensionDecision {
+  readonly allowed: boolean;
+  readonly reason: SuspensionRefusal | 'approved';
+  /** Operator-facing explanation. Present on every refusal. */
+  readonly message?: string;
+  /**
+   * When the pause must end — `min(requested end, allowance cap)`.
+   *
+   * `null` only when the policy sets no bound at all. A sweep resumes on this
+   * instant regardless of whether the subject asks.
+   */
+  readonly autoResumeAt?: Date | null;
+  /** Days already consumed in the period containing the requested start. */
+  readonly daysUsedInPeriod: number;
+  /** Remaining allowance, or `null` when unlimited. */
+  readonly daysRemainingInPeriod: number | null;
+}
+interface SuspensionRequest {
+  readonly startsAt: Date;
+  /** Requested end. Omit for open-ended — the allowance then decides. */
+  readonly endsAt?: Date | null;
+  /** When the request is being made, for the notice check. Defaults to `startsAt`. */
+  readonly requestedAt?: Date;
+}
+interface SuspensionEvalOptions {
+  /** Minutes east of UTC for day boundaries — the BUSINESS timezone offset. */
+  readonly offsetMinutes?: UtcOffsetMinutes;
+}
+/** The allowance period containing `at`, as a half-open range. */
+declare function allowancePeriod(at: Date, periodMonths?: number, offsetMinutes?: UtcOffsetMinutes): DateRange;
+/**
+ * Whole days of suspension inside `period`.
+ *
+ * Counts the OVERLAP, not the spans that merely start inside — a freeze running
+ * 15 Dec → 15 Feb must consume only its December days against the period ending in
+ * December. Ignoring that double-counts a straddling pause in both periods and
+ * refuses a member who is within their allowance.
+ */
+declare function suspendedDaysInPeriod(history: readonly SuspensionSpan[], period: DateRange, /** Now — bounds still-open spans. Defaults to the period end. */at?: Date): number;
+/** Is any span still open at `at`? */
+declare function openSpans(history: readonly SuspensionSpan[], at: Date): readonly SuspensionSpan[];
+/**
+ * Decide a pause request, and say when it must end.
+ *
+ * Refusal precedence is deliberate — most categorical first, so the message names
+ * the reason a human would give:
+ *   1. `not_allowed`          — the product has no freeze at all
+ *   2. `already_suspended`    — concurrency
+ *   3. `insufficient_notice`  — asked too late
+ *   4. `below_minimum` / `above_maximum` — this single pause is the wrong length
+ *   5. `allowance_exhausted`  — nothing left in the period
+ */
+declare function evaluateSuspension(request: SuspensionRequest, history: readonly SuspensionSpan[], policy?: SuspensionPolicy, options?: SuspensionEvalOptions): SuspensionDecision;
+/**
+ * Is this open pause past the instant it should have ended?
+ *
+ * What an auto-resume sweep asks. Kept separate from `evaluateSuspension` because
+ * the sweep has an ALREADY-DECIDED `autoResumeAt` and must not re-derive it — the
+ * policy may have changed since the pause began, and silently re-deciding would
+ * move a date the member was told.
+ */
+declare function dueForAutoResume(span: SuspensionSpan & {
+  readonly autoResumeAt?: Date | null;
+}, at: Date): boolean;
+/**
+ * Derive suspension spans from a status log — the seam that makes an allowance
+ * ENFORCEABLE rather than caller-supplied.
+ *
+ * ## Why this exists
+ *
+ * `evaluateSuspension` needs the history of every past pause. Aggregates do not
+ * carry that: they carry a single `suspendedAt` that each new freeze overwrites, so
+ * "60 days per year" is unenforceable — a member could freeze twelve times and the
+ * eleventh looks identical to the first.
+ *
+ * What they DO carry (or should, per `/status-history`) is an append-only status
+ * log. Every pause is already in there as a transition INTO the paused status, and
+ * every resume as the transition out. This turns that log into the spans the
+ * allowance maths needs, so nothing has to be denormalised twice and the two
+ * primitives compose instead of overlapping.
+ *
+ * ## Assumes the log is chronological
+ *
+ * `appendStatus` guarantees that by construction (it appends and computes
+ * `durationInPriorMs` from the previous element), so this does not re-sort — a sort
+ * here would silently paper over a corrupt log that the caller should be told
+ * about, and would cost O(n log n) on a hot read.
+ *
+ * @param pausedStatus the status that MEANS suspended (`'suspended'`, `'paused'`,
+ *   `'on_hold'` — domains name it differently, so it is a parameter)
+ */
+declare function spansFromStatusHistory<TStatus extends string>(history: readonly StatusChangeEntry<TStatus>[], pausedStatus: TStatus, options?: {
+  /**
+   * The aggregate's status NOW. When it is not the paused status, a trailing
+   * paused entry is treated as CLOSED — the log simply has not recorded the
+   * resume yet (a crash between the write and the append). Leaving it open would
+   * charge the member allowance for time they were not frozen.
+   */
+  readonly currentStatus?: TStatus | undefined; /** Closes a genuinely-open trailing span for counting. Defaults to open. */
+  readonly openEndedAt?: Date | undefined;
+}): SuspensionSpan[];
+//#endregion
+export { SuspensionDecision, SuspensionEvalOptions, SuspensionPolicy, SuspensionRefusal, SuspensionRequest, SuspensionSpan, allowancePeriod, dueForAutoResume, evaluateSuspension, openSpans, spansFromStatusHistory, suspendedDaysInPeriod };

package/dist/suspension.mjs

@@ -0,0 +1,194 @@
+import { rangesOverlap } from "./period.mjs";
+import { addMonths, startOfDay } from "./calendar.mjs";
+//#region src/workflow/suspension.ts
+/**
+* Suspension policy — a time-bounded pause with a per-period allowance.
+*
+* ## What this is, and what it is not
+*
+* `/hold` already models a BLOCKING hold: a document cannot progress until someone
+* resolves it (fraud review, customs detention). It has no duration, no allowance
+* and no automatic end, because those are meaningless for a blocker.
+*
+* This models the other thing: a pause the subject is ENTITLED to take, bounded by
+* an allowance, that ends by itself. Three unrelated kernels need exactly that:
+*
+*   - a gym membership freeze — "60 days a year, minimum a week"
+*   - a subscription pause — the Netflix-style hold
+*   - unpaid leave — an annual cap, distinct from accrued paid leave
+*
+* (`hr/leave`'s balance is an accruing PERSISTED document — a different shape.
+* This is pure computation over a history, so it stays a primitive.)
+*
+* ## `autoResumeAt` is the whole point
+*
+* Without a computed end, "pause" is an indefinite free hold. Someone freezes in
+* February and the business quietly stops earning until an audit notices — which
+* is a revenue hole, not a bug report, so nobody files it. `evaluateSuspension`
+* always returns the instant the pause MUST end, so a sweep can resume it whether
+* or not the subject ever comes back.
+*
+* ## Dates
+*
+* Day boundaries come from `/calendar`'s offset-based helpers and periods from
+* `/period` — never server-local getters. A "60 days per year" allowance computed
+* with `getMonth()` shifts with the deploy machine's `TZ`, so the same member would
+* have a different balance in two regions. The offset is a CALLER decision
+* (business timezone), which is why it is a parameter with no default beyond UTC.
+*
+* PURE: no clock reads beyond the `at` you pass, no I/O. The same evaluation runs
+* on the server, in an admin preview, and in a test.
+*/
+const MS_PER_DAY = 1440 * 60 * 1e3;
+/** The allowance period containing `at`, as a half-open range. */
+function allowancePeriod(at, periodMonths = 12, offsetMinutes = 0) {
+	return {
+		start: addMonths(startOfDay(at, offsetMinutes), -periodMonths),
+		end: at
+	};
+}
+/**
+* Whole days of suspension inside `period`.
+*
+* Counts the OVERLAP, not the spans that merely start inside — a freeze running
+* 15 Dec → 15 Feb must consume only its December days against the period ending in
+* December. Ignoring that double-counts a straddling pause in both periods and
+* refuses a member who is within their allowance.
+*/
+function suspendedDaysInPeriod(history, period, at) {
+	const openEnd = at ?? period.end;
+	let ms = 0;
+	for (const span of history) {
+		const spanEnd = span.endedAt ?? openEnd;
+		if (spanEnd.getTime() <= span.startedAt.getTime()) continue;
+		const range = {
+			start: span.startedAt,
+			end: spanEnd
+		};
+		if (!rangesOverlap(range, period)) continue;
+		const from = Math.max(range.start.getTime(), period.start.getTime());
+		const to = Math.min(range.end.getTime(), period.end.getTime());
+		ms += Math.max(0, to - from);
+	}
+	return Math.round(ms / MS_PER_DAY);
+}
+/** Is any span still open at `at`? */
+function openSpans(history, at) {
+	return history.filter((s) => (s.endedAt ?? null) === null && s.startedAt.getTime() <= at.getTime());
+}
+/**
+* Decide a pause request, and say when it must end.
+*
+* Refusal precedence is deliberate — most categorical first, so the message names
+* the reason a human would give:
+*   1. `not_allowed`          — the product has no freeze at all
+*   2. `already_suspended`    — concurrency
+*   3. `insufficient_notice`  — asked too late
+*   4. `below_minimum` / `above_maximum` — this single pause is the wrong length
+*   5. `allowance_exhausted`  — nothing left in the period
+*/
+function evaluateSuspension(request, history, policy = {}, options = {}) {
+	const offset = options.offsetMinutes ?? 0;
+	const periodMonths = policy.periodMonths ?? 12;
+	const daysUsed = suspendedDaysInPeriod(history, allowancePeriod(request.startsAt, periodMonths, offset), request.startsAt);
+	const cap = policy.maxDaysPerPeriod;
+	const remaining = cap === void 0 ? null : Math.max(0, cap - daysUsed);
+	const refuse = (reason, message) => ({
+		allowed: false,
+		reason,
+		message,
+		daysUsedInPeriod: daysUsed,
+		daysRemainingInPeriod: remaining
+	});
+	if (policy.allowed === false) return refuse("not_allowed", "Pausing is not available on this product.");
+	const maxConcurrent = policy.maxConcurrent ?? 1;
+	if (openSpans(history, request.startsAt).length >= maxConcurrent) return refuse("already_suspended", "There is already an active pause.");
+	if (policy.noticeDays !== void 0 && policy.noticeDays > 0) {
+		const requestedAt = request.requestedAt ?? request.startsAt;
+		const noticeGiven = Math.round((startOfDay(request.startsAt, offset).getTime() - startOfDay(requestedAt, offset).getTime()) / MS_PER_DAY);
+		if (noticeGiven < policy.noticeDays) return refuse("insufficient_notice", `${policy.noticeDays} day(s) notice required; ${noticeGiven} given.`);
+	}
+	const requestedDays = request.endsAt != null ? Math.round((request.endsAt.getTime() - request.startsAt.getTime()) / MS_PER_DAY) : null;
+	if (requestedDays !== null) {
+		if (requestedDays <= 0) return refuse("below_minimum", "A pause must end after it starts.");
+		if (policy.minDays !== void 0 && requestedDays < policy.minDays) return refuse("below_minimum", `The shortest pause is ${policy.minDays} day(s); ${requestedDays} requested.`);
+		if (policy.maxDays !== void 0 && requestedDays > policy.maxDays) return refuse("above_maximum", `The longest single pause is ${policy.maxDays} day(s); ${requestedDays} requested.`);
+	}
+	if (remaining !== null && remaining <= 0) return refuse("allowance_exhausted", `The ${periodMonths}-month allowance of ${cap} day(s) is used up.`);
+	const candidates = [];
+	if (request.endsAt != null) candidates.push(request.endsAt.getTime());
+	if (remaining !== null) candidates.push(request.startsAt.getTime() + remaining * MS_PER_DAY);
+	if (policy.maxDays !== void 0) candidates.push(request.startsAt.getTime() + policy.maxDays * MS_PER_DAY);
+	return {
+		allowed: true,
+		reason: "approved",
+		autoResumeAt: candidates.length > 0 ? new Date(Math.min(...candidates)) : null,
+		daysUsedInPeriod: daysUsed,
+		daysRemainingInPeriod: remaining
+	};
+}
+/**
+* Is this open pause past the instant it should have ended?
+*
+* What an auto-resume sweep asks. Kept separate from `evaluateSuspension` because
+* the sweep has an ALREADY-DECIDED `autoResumeAt` and must not re-derive it — the
+* policy may have changed since the pause began, and silently re-deciding would
+* move a date the member was told.
+*/
+function dueForAutoResume(span, at) {
+	if ((span.endedAt ?? null) !== null) return false;
+	const due = span.autoResumeAt ?? null;
+	return due !== null && due.getTime() <= at.getTime();
+}
+/**
+* Derive suspension spans from a status log — the seam that makes an allowance
+* ENFORCEABLE rather than caller-supplied.
+*
+* ## Why this exists
+*
+* `evaluateSuspension` needs the history of every past pause. Aggregates do not
+* carry that: they carry a single `suspendedAt` that each new freeze overwrites, so
+* "60 days per year" is unenforceable — a member could freeze twelve times and the
+* eleventh looks identical to the first.
+*
+* What they DO carry (or should, per `/status-history`) is an append-only status
+* log. Every pause is already in there as a transition INTO the paused status, and
+* every resume as the transition out. This turns that log into the spans the
+* allowance maths needs, so nothing has to be denormalised twice and the two
+* primitives compose instead of overlapping.
+*
+* ## Assumes the log is chronological
+*
+* `appendStatus` guarantees that by construction (it appends and computes
+* `durationInPriorMs` from the previous element), so this does not re-sort — a sort
+* here would silently paper over a corrupt log that the caller should be told
+* about, and would cost O(n log n) on a hot read.
+*
+* @param pausedStatus the status that MEANS suspended (`'suspended'`, `'paused'`,
+*   `'on_hold'` — domains name it differently, so it is a parameter)
+*/
+function spansFromStatusHistory(history, pausedStatus, options = {}) {
+	const spans = [];
+	for (let i = 0; i < history.length; i += 1) {
+		const entry = history[i];
+		if (entry.status !== pausedStatus) continue;
+		const next = history[i + 1];
+		if (next !== void 0) {
+			spans.push({
+				startedAt: entry.occurredAt,
+				endedAt: next.occurredAt,
+				...entry.note !== void 0 ? { reason: entry.note } : {}
+			});
+			continue;
+		}
+		const stillPaused = options.currentStatus === void 0 || options.currentStatus === pausedStatus;
+		spans.push({
+			startedAt: entry.occurredAt,
+			endedAt: stillPaused ? options.openEndedAt ?? null : entry.occurredAt,
+			...entry.note !== void 0 ? { reason: entry.note } : {}
+		});
+	}
+	return spans;
+}
+//#endregion
+export { allowancePeriod, dueForAutoResume, evaluateSuspension, openSpans, spansFromStatusHistory, suspendedDaysInPeriod };