@lostgradient/weft 0.2.0

package/dist/core/review/index.js

@@ -0,0 +1,96 @@
+import { KEYS } from "../../storage/interface.js";
+import { decode, encode } from "../codec.js";
+import { WeftError } from "../weft-error.js";
+import { ReviewRequestedEvent } from "./events.js";
+
+export class ReviewTimeoutError extends WeftError {
+  reviewId;
+  elapsed;
+  constructor(reviewId, elapsed) {
+    super("ReviewTimeoutError", `Review ${reviewId} timed out after ${elapsed}ms`);
+    this.reviewId = reviewId;
+    this.elapsed = elapsed;
+  }
+}
+
+export class ReviewCoordinator {
+  #storage;
+  #getNow;
+  #eventTarget;
+  constructor(storage, optionsOrGetNow) {
+    this.#storage = storage;
+    if (typeof optionsOrGetNow === "function")
+      this.#getNow = optionsOrGetNow;
+    else {
+      this.#getNow = optionsOrGetNow?.getNow ?? Date.now;
+      this.#eventTarget = optionsOrGetNow?.eventTarget;
+    }
+  }
+  async createReview(workflowId, options) {
+    const reviewId = crypto.randomUUID(), request = {
+      reviewId,
+      workflowId,
+      artifact: options.artifact,
+      reviewType: options.reviewType ?? "general",
+      reviewers: options.reviewers ?? [],
+      allowPartial: options.allowPartial ?? !1,
+      createdAt: this.#getNow()
+    };
+    if (options.timeout !== void 0)
+      request.timeout = options.timeout;
+    if (options.webhookUrl !== void 0)
+      request.webhookUrl = options.webhookUrl;
+    const key = KEYS.review(workflowId, reviewId);
+    await this.#storage.put(key, encode(request));
+    if (this.#eventTarget)
+      this.#eventTarget.dispatchEvent(new ReviewRequestedEvent(workflowId, reviewId, request.reviewType, request.reviewers));
+    return request;
+  }
+  async submitDecision(reviewId, decision) {
+    const full = {
+      reviewId,
+      decision: decision.decision,
+      reviewer: decision.reviewer,
+      timestamp: this.#getNow()
+    };
+    if (decision.feedback !== void 0)
+      full.feedback = decision.feedback;
+    if (decision.sectionDecisions !== void 0)
+      full.sectionDecisions = decision.sectionDecisions;
+    return full;
+  }
+  async getReview(workflowId, reviewId) {
+    const key = KEYS.review(workflowId, reviewId), raw = await this.#storage.get(key);
+    if (!raw)
+      return null;
+    return decode(raw);
+  }
+  async listPendingReviews() {
+    const prefix = "review:", results = [];
+    for await (const [, value] of this.#storage.scan(prefix))
+      results.push(decode(value));
+    return results;
+  }
+  cleanupOperations(workflowId, reviewId) {
+    return [{ type: "delete", key: KEYS.review(workflowId, reviewId) }];
+  }
+  checkEscalations(review, escalation, now) {
+    const elapsed = now - review.createdAt;
+    for (let i = escalation.length - 1;i >= 0; i--) {
+      const step = escalation[i];
+      if (elapsed < step.after)
+        continue;
+      if (step.action !== void 0) {
+        const decision = step.action === "auto-approve" ? "approved" : "rejected";
+        return {
+          type: "auto-decide",
+          decision,
+          auditReason: step.auditReason ?? `Auto-${decision} after ${step.after}ms`
+        };
+      }
+      if (step.to !== void 0)
+        return { type: "escalate", to: step.to };
+    }
+    return null;
+  }
+}

package/dist/core/runtime-workflow-engine.d.ts

@@ -0,0 +1,16 @@
+import type { Engine } from './engine.ts';
+import type { ActivityFunction, AnyWorkflowDefinition, WorkflowRegistryEntry } from './types.ts';
+type RuntimeWorkflowRegistry = Record<string, WorkflowRegistryEntry>;
+type RuntimeActivityTypes = Record<string, ActivityFunction>;
+export type RuntimeWorkflowEngine = Engine<RuntimeWorkflowRegistry, RuntimeActivityTypes>;
+export declare function runtimeWorkflowEngine(engine: unknown): RuntimeWorkflowEngine;
+/**
+ * Register a workflow definition on a runtime-typed engine view, bypassing the
+ * `WorkflowAlreadyRegistered` parameter-position guard. The runtime engine
+ * types every workflow name as already-present, so the brand always intersects
+ * — but transport adapters, schedule-driven loaders, and benchmark harnesses
+ * legitimately need to dispatch into the same dynamic surface. This helper is
+ * the documented escape hatch.
+ */
+export declare function registerOnRuntimeEngine(engine: RuntimeWorkflowEngine, definition: AnyWorkflowDefinition): void;
+export {};

package/dist/core/runtime-workflow-engine.js

@@ -0,0 +1,6 @@
+export function runtimeWorkflowEngine(engine) {
+  return engine;
+}
+export function registerOnRuntimeEngine(engine, definition) {
+  engine.register(definition);
+}

package/dist/core/schedule/cron-formatter.d.ts

@@ -0,0 +1,10 @@
+import type { LocalDateTime, ParsedCronExpression, ZonedParts } from './cron-types.ts';
+export declare function getDefaultTimeZone(): string;
+export declare function getZonedParts(timestamp: number, timeZone: string): ZonedParts;
+export declare function localDateTimeToTimestamp(localDateTime: LocalDateTime, timeZone: string, minimumTimestamp: number): number | null;
+export declare function shiftLocalDateTime(localDateTime: LocalDateTime, adjustment: Partial<Record<'days' | 'hours' | 'minutes', number>>): LocalDateTime;
+export declare function selectNextValue(values: number[], currentValue: number): {
+    value: number;
+    wrapped: boolean;
+};
+export declare function matchesDay(parts: ZonedParts, expression: ParsedCronExpression): boolean;

package/dist/core/schedule/cron-formatter.js

@@ -0,0 +1,103 @@
+const WEEKDAY_FROM_PART = new Map([
+  ["Sun", 0],
+  ["Mon", 1],
+  ["Tue", 2],
+  ["Wed", 3],
+  ["Thu", 4],
+  ["Fri", 5],
+  ["Sat", 6]
+]), formatterCache = new Map;
+export function getDefaultTimeZone() {
+  return "UTC";
+}
+function getFormatter(timeZone) {
+  const cached = formatterCache.get(timeZone);
+  if (cached)
+    return cached;
+  const formatter = new Intl.DateTimeFormat("en-US", {
+    timeZone,
+    calendar: "iso8601",
+    year: "numeric",
+    month: "2-digit",
+    day: "2-digit",
+    hour: "2-digit",
+    minute: "2-digit",
+    second: "2-digit",
+    weekday: "short",
+    hourCycle: "h23",
+    timeZoneName: "shortOffset"
+  });
+  formatterCache.set(timeZone, formatter);
+  return formatter;
+}
+function getOffsetMilliseconds(timestamp, timeZone) {
+  const offsetPart = getFormatter(timeZone).formatToParts(new Date(timestamp)).find((part) => part.type === "timeZoneName")?.value, match = /^GMT([+-])(\d{1,2})(?::(\d{2}))?$/.exec(offsetPart ?? "");
+  if (!match)
+    return 0;
+  const sign = match[1] === "-" ? -1 : 1, hours = Number.parseInt(match[2], 10), minutes = Number.parseInt(match[3] ?? "0", 10);
+  return sign * (hours * 60 + minutes) * 60000;
+}
+export function getZonedParts(timestamp, timeZone) {
+  const formattedParts = getFormatter(timeZone).formatToParts(new Date(timestamp)), record = new Map(formattedParts.map((part) => [part.type, part.value])), weekdayValue = record.get("weekday"), dayOfWeek = weekdayValue ? WEEKDAY_FROM_PART.get(weekdayValue) : void 0;
+  if (dayOfWeek === void 0)
+    throw Error(`Unable to resolve weekday for time zone "${timeZone}"`);
+  return {
+    year: Number.parseInt(record.get("year") ?? "", 10),
+    month: Number.parseInt(record.get("month") ?? "", 10),
+    day: Number.parseInt(record.get("day") ?? "", 10),
+    hour: Number.parseInt(record.get("hour") ?? "", 10),
+    minute: Number.parseInt(record.get("minute") ?? "", 10),
+    second: Number.parseInt(record.get("second") ?? "", 10),
+    dayOfWeek
+  };
+}
+function sameLocalDateTime(left, right) {
+  return left.year === right.year && left.month === right.month && left.day === right.day && left.hour === right.hour && left.minute === right.minute && left.second === right.second;
+}
+export function localDateTimeToTimestamp(localDateTime, timeZone, minimumTimestamp) {
+  const naiveTimestamp = Date.UTC(localDateTime.year, localDateTime.month - 1, localDateTime.day, localDateTime.hour, localDateTime.minute, localDateTime.second);
+  let candidate = naiveTimestamp;
+  for (let iteration = 0;iteration < 6; iteration += 1) {
+    const offsetMilliseconds = getOffsetMilliseconds(candidate, timeZone), adjustedCandidate = naiveTimestamp - offsetMilliseconds;
+    if (adjustedCandidate === candidate)
+      break;
+    candidate = adjustedCandidate;
+  }
+  const candidates = new Set;
+  for (let offsetMinutes = -120;offsetMinutes <= 120; offsetMinutes += 15)
+    candidates.add(candidate + offsetMinutes * 60000);
+  return [...candidates].filter((timestamp) => timestamp >= minimumTimestamp).filter((timestamp) => sameLocalDateTime(localDateTime, getZonedParts(timestamp, timeZone))).toSorted((left, right) => left - right)[0] ?? null;
+}
+export function shiftLocalDateTime(localDateTime, adjustment) {
+  const date = new Date(Date.UTC(localDateTime.year, localDateTime.month - 1, localDateTime.day, localDateTime.hour, localDateTime.minute, localDateTime.second));
+  if (adjustment.days !== void 0)
+    date.setUTCDate(date.getUTCDate() + adjustment.days);
+  if (adjustment.hours !== void 0)
+    date.setUTCHours(date.getUTCHours() + adjustment.hours);
+  if (adjustment.minutes !== void 0)
+    date.setUTCMinutes(date.getUTCMinutes() + adjustment.minutes);
+  return {
+    year: date.getUTCFullYear(),
+    month: date.getUTCMonth() + 1,
+    day: date.getUTCDate(),
+    hour: date.getUTCHours(),
+    minute: date.getUTCMinutes(),
+    second: date.getUTCSeconds()
+  };
+}
+export function selectNextValue(values, currentValue) {
+  for (const value of values)
+    if (value > currentValue)
+      return { value, wrapped: !1 };
+  return { value: values[0], wrapped: !0 };
+}
+export function matchesDay(parts, expression) {
+  const matchesDayOfMonth = expression.daysOfMonth.values.includes(parts.day), matchesDayOfWeek = expression.daysOfWeek.values.includes(parts.dayOfWeek);
+  if (expression.daysOfMonth.wildcard && expression.daysOfWeek.wildcard)
+    return !0;
+  if (expression.daysOfMonth.wildcard)
+    return matchesDayOfWeek;
+  if (expression.daysOfWeek.wildcard)
+    return matchesDayOfMonth;
+  return matchesDayOfMonth || matchesDayOfWeek;
+}

package/dist/core/schedule/cron-occurrence.d.ts

@@ -0,0 +1,3 @@
+import type { CronOccurrenceOptions, ParsedCronExpression } from './cron-types.ts';
+export declare function getNextCronOccurrence(expression: string | ParsedCronExpression, afterTimestamp: number, options?: CronOccurrenceOptions): number;
+export declare function collectDueCronOccurrences(expression: string | ParsedCronExpression, firstDueAt: number, throughTimestamp: number, options?: CronOccurrenceOptions): number[];

package/dist/core/schedule/cron-occurrence.js

@@ -0,0 +1,129 @@
+import { normalizeStorageTimestamp } from "../scheduler.js";
+import {
+  getDefaultTimeZone,
+  getZonedParts,
+  localDateTimeToTimestamp,
+  matchesDay,
+  selectNextValue,
+  shiftLocalDateTime
+} from "./cron-formatter.js";
+import { parseCronExpression } from "./cron-parser.js";
+function nextSearchTimestamp(candidate) {
+  return candidate + 1000;
+}
+function startOfLocalDay(parts) {
+  return {
+    year: parts.year,
+    month: parts.month,
+    day: parts.day,
+    hour: 0,
+    minute: 0,
+    second: 0
+  };
+}
+function advanceToNextMonth(candidate, parts, parsedExpression, timeZone) {
+  const nextMonth = selectNextValue(parsedExpression.months.values, parts.month);
+  return localDateTimeToTimestamp({
+    year: parts.year + (nextMonth.wrapped ? 1 : 0),
+    month: nextMonth.value,
+    day: 1,
+    hour: 0,
+    minute: 0,
+    second: 0
+  }, timeZone, nextSearchTimestamp(candidate)) ?? candidate + 86400000;
+}
+function advanceToNextDay(candidate, parts, timeZone) {
+  return localDateTimeToTimestamp(shiftLocalDateTime(startOfLocalDay(parts), { days: 1 }), timeZone, nextSearchTimestamp(candidate)) ?? candidate + 86400000;
+}
+function advanceToNextHour(candidate, parts, parsedExpression, timeZone) {
+  const nextHour = selectNextValue(parsedExpression.hours.values, parts.hour);
+  return localDateTimeToTimestamp({
+    year: parts.year,
+    month: parts.month,
+    day: parts.day,
+    hour: nextHour.value,
+    minute: 0,
+    second: 0
+  }, timeZone, nextSearchTimestamp(candidate)) ?? advanceToNextDay(candidate, parts, timeZone);
+}
+function advanceToNextMinute(candidate, parts, parsedExpression, timeZone) {
+  const nextMinute = selectNextValue(parsedExpression.minutes.values, parts.minute), minuteCandidate = localDateTimeToTimestamp({
+    year: parts.year,
+    month: parts.month,
+    day: parts.day,
+    hour: parts.hour,
+    minute: nextMinute.value,
+    second: 0
+  }, timeZone, nextSearchTimestamp(candidate));
+  if (minuteCandidate !== null)
+    return minuteCandidate;
+  return localDateTimeToTimestamp(shiftLocalDateTime({
+    year: parts.year,
+    month: parts.month,
+    day: parts.day,
+    hour: parts.hour,
+    minute: 0,
+    second: 0
+  }, { hours: 1 }), timeZone, nextSearchTimestamp(candidate)) ?? candidate + 3600000;
+}
+function advanceToNextSecond(candidate, parts, parsedExpression, timeZone) {
+  const nextSecond = selectNextValue(parsedExpression.seconds.values, parts.second), secondCandidate = localDateTimeToTimestamp({
+    year: parts.year,
+    month: parts.month,
+    day: parts.day,
+    hour: parts.hour,
+    minute: parts.minute,
+    second: nextSecond.value
+  }, timeZone, nextSearchTimestamp(candidate));
+  if (secondCandidate !== null)
+    return secondCandidate;
+  return localDateTimeToTimestamp(shiftLocalDateTime({
+    year: parts.year,
+    month: parts.month,
+    day: parts.day,
+    hour: parts.hour,
+    minute: parts.minute,
+    second: 0
+  }, { minutes: 1 }), timeZone, nextSearchTimestamp(candidate)) ?? candidate + 60000;
+}
+export function getNextCronOccurrence(expression, afterTimestamp, options) {
+  const parsedExpression = typeof expression === "string" ? parseCronExpression(expression) : expression, timeZone = options?.timeZone ?? getDefaultTimeZone();
+  let candidate = normalizeStorageTimestamp(Math.floor(afterTimestamp / 1000) * 1000 + 1000, "Cron occurrence candidate");
+  for (let iteration = 0;iteration < 1e5; iteration += 1) {
+    const parts = getZonedParts(candidate, timeZone);
+    if (!parsedExpression.months.values.includes(parts.month)) {
+      candidate = advanceToNextMonth(candidate, parts, parsedExpression, timeZone);
+      continue;
+    }
+    if (!matchesDay(parts, parsedExpression)) {
+      candidate = advanceToNextDay(candidate, parts, timeZone);
+      continue;
+    }
+    if (!parsedExpression.hours.values.includes(parts.hour)) {
+      candidate = advanceToNextHour(candidate, parts, parsedExpression, timeZone);
+      continue;
+    }
+    if (!parsedExpression.minutes.values.includes(parts.minute)) {
+      candidate = advanceToNextMinute(candidate, parts, parsedExpression, timeZone);
+      continue;
+    }
+    if (!parsedExpression.seconds.values.includes(parts.second)) {
+      candidate = advanceToNextSecond(candidate, parts, parsedExpression, timeZone);
+      continue;
+    }
+    return candidate;
+  }
+  throw Error(`Could not find the next cron occurrence for "${parsedExpression.expression}"`);
+}
+export function collectDueCronOccurrences(expression, firstDueAt, throughTimestamp, options) {
+  const parsedExpression = typeof expression === "string" ? parseCronExpression(expression) : expression, dueOccurrences = [], requestedMaxOccurrences = options?.maxOccurrences;
+  if (requestedMaxOccurrences !== void 0 && (!Number.isSafeInteger(requestedMaxOccurrences) || requestedMaxOccurrences <= 0))
+    throw Error("Cron occurrence maxOccurrences must be a positive safe integer");
+  const maximumOccurrences = requestedMaxOccurrences ?? Number.POSITIVE_INFINITY;
+  let nextOccurrence = firstDueAt;
+  while (nextOccurrence <= throughTimestamp && dueOccurrences.length < maximumOccurrences) {
+    dueOccurrences.push(nextOccurrence);
+    nextOccurrence = getNextCronOccurrence(parsedExpression, nextOccurrence, options);
+  }
+  return dueOccurrences;
+}

package/dist/core/schedule/cron-parser.d.ts

@@ -0,0 +1,2 @@
+import type { ParsedCronExpression } from './cron-types.ts';
+export declare function parseCronExpression(expression: string): ParsedCronExpression;

package/dist/core/schedule/cron-parser.js

@@ -0,0 +1,93 @@
+const MONTH_NAMES = new Map([
+  ["JAN", 1],
+  ["FEB", 2],
+  ["MAR", 3],
+  ["APR", 4],
+  ["MAY", 5],
+  ["JUN", 6],
+  ["JUL", 7],
+  ["AUG", 8],
+  ["SEP", 9],
+  ["OCT", 10],
+  ["NOV", 11],
+  ["DEC", 12]
+]), DAY_NAMES = new Map([
+  ["SUN", 0],
+  ["MON", 1],
+  ["TUE", 2],
+  ["WED", 3],
+  ["THU", 4],
+  ["FRI", 5],
+  ["SAT", 6]
+]);
+function parseNamedValue(token, names, minimum, maximum) {
+  const upperToken = token.toUpperCase();
+  if (names?.has(upperToken))
+    return names.get(upperToken);
+  const numericValue = Number.parseInt(token, 10);
+  if (!Number.isInteger(numericValue))
+    throw Error(`Invalid cron token "${token}"`);
+  const normalizedValue = maximum === 6 && numericValue === 7 ? 0 : numericValue;
+  if (normalizedValue < minimum || normalizedValue > maximum)
+    throw Error(`Cron token "${token}" is outside the allowed range ${minimum}-${maximum}`);
+  return normalizedValue;
+}
+function buildWildcardCronField(minimum, maximum) {
+  return {
+    values: Array.from({ length: maximum - minimum + 1 }, (_, index) => minimum + index),
+    wildcard: !0
+  };
+}
+function parseCronStep(segment, stepPart) {
+  const step = stepPart === void 0 ? 1 : Number.parseInt(stepPart, 10);
+  if (!Number.isInteger(step) || step <= 0)
+    throw Error(`Invalid cron step "${segment}"`);
+  return step;
+}
+function addSteppedValues(values, start, end, step) {
+  for (let value = start;value <= end; value += step)
+    values.add(value);
+}
+function addCronSegmentValues(values, segment, minimum, maximum, names) {
+  const [rangePart = "", stepPart] = segment.split("/"), step = parseCronStep(segment, stepPart);
+  if (rangePart === "*" || rangePart === "?") {
+    addSteppedValues(values, minimum, maximum, step);
+    return;
+  }
+  const [startToken, endToken] = rangePart.split("-"), start = parseNamedValue(startToken, names, minimum, maximum), end = endToken === void 0 ? start : parseNamedValue(endToken, names, minimum, maximum);
+  if (start > end)
+    throw Error(`Invalid cron range "${segment}"`);
+  addSteppedValues(values, start, end, step);
+}
+function parseCronField(field, minimum, maximum, names) {
+  const trimmedField = field.trim();
+  if (trimmedField === "*" || trimmedField === "?")
+    return buildWildcardCronField(minimum, maximum);
+  const values = new Set, segments = trimmedField.split(",");
+  for (const rawSegment of segments) {
+    const segment = rawSegment.trim();
+    if (segment.length === 0)
+      throw Error(`Invalid cron field "${field}"`);
+    addCronSegmentValues(values, segment, minimum, maximum, names);
+  }
+  return {
+    values: [...values].toSorted((left, right) => left - right),
+    wildcard: !1
+  };
+}
+export function parseCronExpression(expression) {
+  const fields = expression.trim().split(/\s+/).filter((field) => field.length > 0);
+  if (fields.length !== 5 && fields.length !== 6)
+    throw Error("Cron expression must have 5 fields or 6 fields with seconds");
+  const hasSeconds = fields.length === 6, [secondField, minuteField, hourField, dayField, monthField, weekdayField] = hasSeconds ? fields : ["0", ...fields];
+  return {
+    expression,
+    hasSeconds,
+    seconds: parseCronField(secondField, 0, 59),
+    minutes: parseCronField(minuteField, 0, 59),
+    hours: parseCronField(hourField, 0, 23),
+    daysOfMonth: parseCronField(dayField, 1, 31),
+    months: parseCronField(monthField, 1, 12, MONTH_NAMES),
+    daysOfWeek: parseCronField(weekdayField, 0, 6, DAY_NAMES)
+  };
+}

package/dist/core/schedule/cron-types.d.ts

@@ -0,0 +1,35 @@
+export type CronField = {
+    values: number[];
+    wildcard: boolean;
+};
+export type ParsedCronExpression = {
+    expression: string;
+    hasSeconds: boolean;
+    seconds: CronField;
+    minutes: CronField;
+    hours: CronField;
+    daysOfMonth: CronField;
+    months: CronField;
+    daysOfWeek: CronField;
+};
+export type ZonedParts = {
+    year: number;
+    month: number;
+    day: number;
+    hour: number;
+    minute: number;
+    second: number;
+    dayOfWeek: number;
+};
+export type LocalDateTime = {
+    year: number;
+    month: number;
+    day: number;
+    hour: number;
+    minute: number;
+    second: number;
+};
+export type CronOccurrenceOptions = {
+    timeZone?: string;
+    maxOccurrences?: number;
+};

package/dist/core/schedule/index.d.ts

@@ -0,0 +1,3 @@
+export { collectDueCronOccurrences, getNextCronOccurrence } from './cron-occurrence.ts';
+export { parseCronExpression } from './cron-parser.ts';
+export type { CronOccurrenceOptions } from './cron-types.ts';

package/dist/core/schedule/index.js

@@ -0,0 +1,2 @@
+export { collectDueCronOccurrences, getNextCronOccurrence } from "./cron-occurrence.js";
+export { parseCronExpression } from "./cron-parser.js";

package/dist/core/schedule/interval-occurrence.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Options shared by the interval occurrence helpers. `maxOccurrences` bounds the
+ * number of due occurrences {@link collectDueIntervalOccurrences} returns in a
+ * single call so a long backfill window cannot generate an unbounded list.
+ */
+export type IntervalOccurrenceOptions = {
+    maxOccurrences?: number;
+};
+/**
+ * Compute the first interval occurrence strictly after `afterTimestamp`.
+ *
+ * Occurrences are anchored at `anchorTimestamp` and spaced exactly
+ * `intervalMilliseconds` apart: `anchor + n * interval` for `n >= 1`. The result
+ * is the smallest such timestamp greater than `afterTimestamp`, so repeatedly
+ * feeding the previous result back in walks forward one interval at a time.
+ *
+ * For example, a 1-hour interval anchored at epoch (`0`), asked for the next
+ * occurrence after 90 minutes (`5_400_000`), returns the 2-hour mark
+ * (`7_200_000`).
+ */
+export declare function getNextIntervalOccurrence(anchorTimestamp: number, intervalMilliseconds: number, afterTimestamp: number): number;
+/**
+ * Collect every interval occurrence in the inclusive window
+ * `[firstDueAt, throughTimestamp]`, anchored at `anchorTimestamp`. Mirrors the
+ * cron occurrence collector so the schedule timer can drive backfill through a
+ * single code path regardless of spec kind.
+ *
+ * For example, a 1-hour interval first due at the 1-hour mark, collected through
+ * the 3-hour mark, yields the 1-hour, 2-hour, and 3-hour timestamps.
+ */
+export declare function collectDueIntervalOccurrences(anchorTimestamp: number, intervalMilliseconds: number, firstDueAt: number, throughTimestamp: number, options?: IntervalOccurrenceOptions): number[];

package/dist/core/schedule/interval-occurrence.js

@@ -0,0 +1,26 @@
+import { normalizeStorageTimestamp } from "../scheduler.js";
+function assertPositiveInterval(intervalMilliseconds) {
+  if (!Number.isSafeInteger(intervalMilliseconds) || intervalMilliseconds <= 0)
+    throw Error("Interval schedule period must be a positive safe integer of milliseconds");
+}
+export function getNextIntervalOccurrence(anchorTimestamp, intervalMilliseconds, afterTimestamp) {
+  assertPositiveInterval(intervalMilliseconds);
+  const normalizedAnchor = normalizeStorageTimestamp(anchorTimestamp, "Interval anchor"), normalizedAfter = normalizeStorageTimestamp(afterTimestamp, "Interval occurrence candidate");
+  if (normalizedAfter < normalizedAnchor)
+    return normalizedAnchor + intervalMilliseconds;
+  const elapsed = normalizedAfter - normalizedAnchor, completedIntervals = Math.floor(elapsed / intervalMilliseconds), candidate = normalizedAnchor + (completedIntervals + 1) * intervalMilliseconds;
+  return normalizeStorageTimestamp(candidate, "Interval occurrence");
+}
+export function collectDueIntervalOccurrences(anchorTimestamp, intervalMilliseconds, firstDueAt, throughTimestamp, options) {
+  assertPositiveInterval(intervalMilliseconds);
+  const requestedMaxOccurrences = options?.maxOccurrences;
+  if (requestedMaxOccurrences !== void 0 && (!Number.isSafeInteger(requestedMaxOccurrences) || requestedMaxOccurrences <= 0))
+    throw Error("Interval occurrence maxOccurrences must be a positive safe integer");
+  const maximumOccurrences = requestedMaxOccurrences ?? Number.POSITIVE_INFINITY, dueOccurrences = [];
+  let nextOccurrence = firstDueAt;
+  while (nextOccurrence <= throughTimestamp && dueOccurrences.length < maximumOccurrences) {
+    dueOccurrences.push(nextOccurrence);
+    nextOccurrence = getNextIntervalOccurrence(anchorTimestamp, intervalMilliseconds, nextOccurrence);
+  }
+  return dueOccurrences;
+}

package/dist/core/schedule.d.ts

@@ -0,0 +1 @@
+export * from './schedule/index.ts';

package/dist/core/schedule.js

@@ -0,0 +1 @@
+export * from "./schedule/index.js";

package/dist/core/scheduler/duration.d.ts

@@ -0,0 +1,44 @@
+import type { Duration, RetryPolicy } from '../types.ts';
+export declare function normalizeStorageTimestamp(timestamp: number, fieldName: string): number;
+/**
+ * Parse a human-readable duration string or number to milliseconds.
+ *
+ * @example
+ * ```ts
+ * import { parseDuration } from '@lostgradient/weft';
+ *
+ * console.log(parseDuration(5000));       // 5000
+ * console.log(parseDuration('250ms'));    // 250
+ * console.log(parseDuration('30s'));      // 30000
+ * console.log(parseDuration('5 minutes')); // 300000
+ * console.log(parseDuration('2h'));       // 7200000
+ * console.log(parseDuration('1d'));       // 86400000
+ * ```
+ *
+ * @throws Error when the string uses an invalid format or unknown unit.
+ * @throws RangeError when the resulting duration is negative or non-finite.
+ */
+export declare function parseDuration(duration: Duration): number;
+/**
+ * Calculate exponential backoff delay for a given retry attempt.
+ * `attempt` is 1-indexed: `calculateBackoff(1, policy)` returns
+ * `initialBackoff` directly. Pass `0` only for non-retry probes; the result is
+ * `initialBackoff / backoffMultiplier`.
+ *
+ * @example
+ * ```ts
+ * import { calculateBackoff, type RetryPolicy } from '@lostgradient/weft';
+ *
+ * const policy: RetryPolicy = {
+ *   maxAttempts: 5,
+ *   initialBackoff: '1s',
+ *   backoffMultiplier: 2,
+ *   maxBackoff: '30s',
+ * };
+ *
+ * console.log(calculateBackoff(1, policy)); // 1000   (attempt 1: 1s)
+ * console.log(calculateBackoff(2, policy)); // 2000   (attempt 2: 2s)
+ * console.log(calculateBackoff(5, policy)); // 16000  (attempt 5: 16s, capped at 30s)
+ * ```
+ */
+export declare function calculateBackoff(attempt: number, policy: RetryPolicy): number;