@qilin-agent/schedule 3.1.7 → 3.1.9

package/lib/types/domain.js

@@ -1,36 +1,14 @@
 /**
- * Strict Schedule decoding, replay, time validation, and framing.
+ * Host task decoding, timing validation, occurrence selection, and reminder framing.
  * @module @qilin-agent/schedule
  */
 import { Temporal } from '@js-temporal/polyfill';
-import { SessionLogOffset } from '@qilin-agent/session';
-/** Durable Schedule protocol version implemented by this package. */
-export const SCHEDULE_CHANGE_VERSION = 1;
-/** Fixed v1 lower bound for a fixed-rate reminder. */
+import { Cron, RRule, MAX_FOUR_DIGIT_YEAR_MS, MIN_FOUR_DIGIT_YEAR_MS, canonicalizeTimeZone as canonicalizeSharedTimeZone, formatFourDigitYearInstant, fourDigitYearEpoch, isFourDigitYearInstant, parseLocalCalendar, parseOffsetInstant, resolveLocalInstant, } from '@qilin-agent/util-time';
+/** Minimum supported fixed-rate interval. */
 export const MIN_EVERY_INTERVAL_SECONDS = 60;
-/** Fixed v1 upper bound for a stored task title. */
+/** Maximum stored task title length. */
 export const MAX_TITLE_LENGTH = 120;
-/**
- * Longest forward or backward walk of the cron date search, in years.
- *
- * The proleptic Gregorian leap-year and weekday alignment repeats every 400
- * years, so a rule that matches any local date has a match within this window;
- * walking further can only reach a rule that never matches. Bounding the walk
- * keeps a valid but unsatisfiable rule's creation and decision cost fixed
- * instead of enumerating candidate dates toward the four-digit-year ceiling.
- */
-export const CRON_SEARCH_HORIZON_YEARS = 400;
-const MIN_FOUR_DIGIT_YEAR_MS = Date.parse('0001-01-01T00:00:00.000Z');
-const MAX_FOUR_DIGIT_YEAR_MS = Date.parse('9999-12-31T23:59:59.999Z');
-const UTC_INSTANT = /^(?!0000)\d{4}-(?:0[1-9]|1[0-2])-(?:0[1-9]|[12]\d|3[01])T(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d\.\d{3}Z$/;
-const OFFSET_INSTANT = new RegExp(String.raw `^(?<year>\d{4})-(?<month>\d{2})-(?<day>\d{2})`
-    + String.raw `T(?<hour>\d{2}):(?<minute>\d{2}):(?<second>\d{2})`
-    + String.raw `(?:\.(?<fraction>\d{1,3}))?(?<zone>Z|(?<sign>[+-])`
-    + String.raw `(?<offsetHour>\d{2}):(?<offsetMinute>\d{2}))$`);
-const LOCAL_DATE = /^(?<year>\d{4})-(?<month>\d{2})-(?<day>\d{2})$/;
-const LOCAL_TIME = /^(?<hour>\d{2}):(?<minute>\d{2}):(?<second>\d{2})(?:\.(?<fraction>\d{1,3}))?$/;
 const LOCAL_CLOCK_TIME = /^(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d{1,3})?$/;
-const IANA_ZONE = /^[A-Za-z][A-Za-z0-9_+.-]*(?:\/[A-Za-z0-9_+.-]+)+$/;
 /** Error from malformed or transition-invalid durable Schedule data. */
 export class ScheduleLogError extends Error {
     /** Stable machine-readable error code. */
@@ -61,27 +39,31 @@ export class ScheduleInputError extends Error {
     }
 }
 /**
- * Brand a raw session-local id without changing its runtime value.
- * @param value - Raw session-local id.
+ * Brand a raw task id without changing its runtime value.
+ * @param value - Raw task id.
  * @returns The same string with the Schedule brand.
  */
 export function ScheduleId(value) {
     return value;
 }
-/** Whether an unknown value is a non-array object. */
-function isRecord(value) {
+/**
+ * Narrow an unknown value to a non-array object.
+ * @param value - Value to inspect.
+ * @returns Whether the value is a non-null, non-array object.
+ */
+export function isRecord(value) {
     return typeof value === 'object' && value !== null && !Array.isArray(value);
 }
-/** Require exactly the named durable object keys. */
-function hasExactKeys(value, expected) {
+/**
+ * Require exactly the named durable object keys.
+ * @param value - Object to inspect.
+ * @param expected - Complete allowed key set.
+ * @returns Whether every expected key is present and no other key is present.
+ */
+export function hasExactKeys(value, expected) {
     const allowed = new Set(expected);
     return expected.every(key => key in value) && Object.keys(value).every(key => allowed.has(key));
 }
-/** Require the named durable keys while admitting further optional members. */
-function hasExactKeysWithOptional(value, required, optional) {
-    const allowed = new Set([...required, ...optional]);
-    return required.every(key => key in value) && Object.keys(value).every(key => allowed.has(key));
-}
 /** Stable diagnostic for a title that is missing or empty after trimming. */
 export const REQUIRED_TITLE_MESSAGE = 'title is required and must be non-empty after trimming.';
 /**
@@ -140,117 +122,75 @@ function decodeRecordTitle(value, expected, message) {
     return title;
 }
 /**
- * Decode the stored title of one historical `schedule/change` create record.
- *
- * A version-1 event written before names existed has no `title` member, so the
- * key set is required without it and the absent member decodes as undefined. A
- * present title stays subject to the canonical stored form.
- * @param value - Untrusted durable record already known to be an object.
- * @param expected - Exact keys the record may carry; `title` is optional within them.
- * @param message - Diagnostic naming the record's keys.
- * @returns The stored title, or undefined when the historical record predates it.
+ * Validate one stable task id at the durable boundary.
+ * @param value - Untrusted durable id field.
+ * @returns The branded id; an invalid id throws ScheduleLogError.
  */
-function decodeHistoricalRecordTitle(value, expected, message) {
-    const keys = expected.filter(key => key !== 'title');
-    if (!hasExactKeysWithOptional(value, keys, ['title']))
-        throw new ScheduleLogError(message);
-    return value['title'] === undefined ? undefined : decodeStoredTitle(value['title']);
-}
-/** Validate one stable session-local id at the durable boundary. */
-function decodeId(value) {
+export function decodeId(value) {
     if (typeof value !== 'string' || value.length === 0 || value.trim() !== value) {
         throw new ScheduleLogError('schedule id must be a non-empty string without surrounding whitespace');
     }
     return ScheduleId(value);
 }
-/** Validate one canonical four-digit-year UTC instant. */
-function decodeInstant(value) {
-    if (typeof value !== 'string' || !UTC_INSTANT.test(value)) {
-        throw new ScheduleLogError('scheduledAt must be a canonical four-digit-year RFC 3339 UTC instant');
-    }
-    const epoch = Date.parse(value);
-    if (!Number.isFinite(epoch) || new Date(epoch).toISOString() !== value) {
-        throw new ScheduleLogError('scheduledAt is not a real UTC calendar instant');
+/** Stable Schedule diagnostic for a `scheduledAt` outside the canonical profile. */
+const NON_CANONICAL_INSTANT_MESSAGE = 'scheduledAt must be a canonical four-digit-year RFC 3339 UTC instant';
+/**
+ * Validate one canonical four-digit-year UTC instant at the durable boundary.
+ * @param value - Untrusted durable instant field.
+ * @returns The canonical instant; an invalid instant throws ScheduleLogError.
+ */
+export function decodeInstant(value) {
+    if (typeof value !== 'string') {
+        throw new ScheduleLogError(NON_CANONICAL_INSTANT_MESSAGE);
     }
+    const parsed = fourDigitYearEpoch(value);
+    if (parsed.kind === 'rejected')
+        throw new ScheduleLogError(instantDiagnostic(parsed.reason));
     return value;
 }
-/** Read one required named regular-expression group as a number. */
-function groupNumber(groups, name) {
-    const value = groups[name];
-    /* v8 ignore next -- successful fixed regexes always provide every requested group. */
-    if (value === undefined)
-        throw new ScheduleInputError('invalid_rule', 'The at value has an invalid shape.');
-    return Number(value);
-}
-/** Convert exact calendar fields to a UTC-shaped epoch while rejecting normalization. */
-function calendarEpoch(parts) {
-    const value = new Date(0);
-    value.setUTCHours(0, 0, 0, 0);
-    value.setUTCFullYear(parts.year, parts.month - 1, parts.day);
-    value.setUTCHours(parts.hour, parts.minute, parts.second, parts.millisecond);
-    const epoch = value.getTime();
-    if (!Number.isFinite(epoch)
-        || value.getUTCFullYear() !== parts.year
-        || value.getUTCMonth() + 1 !== parts.month
-        || value.getUTCDate() !== parts.day
-        || value.getUTCHours() !== parts.hour
-        || value.getUTCMinutes() !== parts.minute
-        || value.getUTCSeconds() !== parts.second
-        || value.getUTCMilliseconds() !== parts.millisecond) {
-        throw new ScheduleInputError('invalid_rule', 'The at value must be a real ISO calendar date and time.');
-    }
-    return epoch;
-}
-/** Normalize an optional one-to-three digit fractional second to milliseconds. */
-function milliseconds(value) {
-    return value === undefined ? 0 : Number(value.padEnd(3, '0'));
-}
-/** Require a safe, representable, strictly future UTC target. */
-function futureInstant(epoch, now) {
-    if (!Number.isSafeInteger(now) || !Number.isSafeInteger(epoch)
-        || epoch < MIN_FOUR_DIGIT_YEAR_MS || epoch > MAX_FOUR_DIGIT_YEAR_MS) {
-        throw new ScheduleInputError('time_out_of_range', 'The scheduled time must be representable as a four-digit-year RFC 3339 UTC instant.');
-    }
-    if (epoch <= now) {
-        throw new ScheduleInputError('not_future', 'The scheduled time must be strictly in the future.');
-    }
-    const instant = new Date(epoch).toISOString();
-    /* v8 ignore next -- an in-range integral Date always formats as the canonical UTC profile. */
-    if (!UTC_INSTANT.test(instant)) {
-        throw new ScheduleInputError('time_out_of_range', 'The scheduled time must be representable as a four-digit-year RFC 3339 UTC instant.');
+/**
+ * Map one shared instant rejection onto the stable stored-data diagnostic.
+ * @param reason - Reason the shared vocabulary refused the instant.
+ * @returns The Schedule log diagnostic for that refusal.
+ */
+function instantDiagnostic(reason) {
+    switch (reason) {
+        case 'not_a_calendar_date':
+            return 'scheduledAt is not a real UTC calendar instant';
+        case 'not_rfc3339':
+        case 'out_of_range':
+        case 'invalid_numeric_offset':
+            return NON_CANONICAL_INSTANT_MESSAGE;
+        /* v8 ignore next 3 -- the shared parser returns a closed rejection union. */
+        default: {
+            const unreachable = reason;
+            throw new ScheduleLogError(`unknown instant rejection ${String(unreachable)}`);
+        }
     }
-    return instant;
 }
-/** Parse a strict RFC 3339 instant whose numeric offset is part of the input. */
-function parseOffsetInstant(value) {
-    const match = OFFSET_INSTANT.exec(value);
-    const groups = match?.groups;
-    if (groups === undefined) {
-        throw new ScheduleInputError('invalid_rule', 'at must use YYYY-MM-DDTHH:mm:ss with optional 1-3 digit fractional seconds and an explicit Z or numeric offset.');
-    }
-    const parts = {
-        year: groupNumber(groups, 'year'),
-        month: groupNumber(groups, 'month'),
-        day: groupNumber(groups, 'day'),
-        hour: groupNumber(groups, 'hour'),
-        minute: groupNumber(groups, 'minute'),
-        second: groupNumber(groups, 'second'),
-        millisecond: milliseconds(groups['fraction']),
-    };
-    if (parts.year === 0 || parts.hour > 23 || parts.minute > 59 || parts.second > 59) {
-        throw new ScheduleInputError('invalid_rule', 'The at value must be a real ISO calendar date and time.');
-    }
-    const localEpoch = calendarEpoch(parts);
-    if (groups['zone'] === 'Z')
-        return localEpoch;
-    const offsetHour = groupNumber(groups, 'offsetHour');
-    const offsetMinute = groupNumber(groups, 'offsetMinute');
-    if (offsetHour > 23 || offsetMinute > 59
-        || (groups['sign'] === '-' && offsetHour === 0 && offsetMinute === 0)) {
-        throw new ScheduleInputError('invalid_rule', 'The at numeric offset is invalid.');
+/**
+ * Map one shared zone rejection onto the stable Schedule input code.
+ * @param reason - Reason the shared vocabulary refused the name.
+ * @param cause - Platform refusal the shared vocabulary caught, when it carried one.
+ * @returns The public Schedule diagnostic for that refusal.
+ */
+function timeZoneError(reason, cause) {
+    const options = cause === undefined ? undefined : { cause };
+    switch (reason) {
+        case 'blank':
+        case 'padded':
+        case 'not_area_location':
+        case 'unsupported':
+            return new ScheduleInputError('invalid_time_zone', 'time_zone must be UTC or a valid IANA Area/Location name.', options);
+        /* v8 ignore next 2 -- the shared parser does not answer not_canonical_shape for a canonical zone. */
+        case 'not_canonical_shape':
+            return new ScheduleInputError('invalid_time_zone', 'time_zone must resolve to UTC or an IANA Area/Location name.', options);
+        /* v8 ignore next 3 -- TimeZoneRejection is closed; this arm only makes adding a reason a compile error. */
+        default: {
+            const unreachable = reason;
+            return unreachable;
+        }
     }
-    const direction = groups['sign'] === '+' ? 1 : -1;
-    return localEpoch - direction * (offsetHour * 60 + offsetMinute) * 60_000;
 }
 /**
  * Validate and canonicalize one raw IANA time-zone selector.
@@ -258,65 +198,82 @@ function parseOffsetInstant(value) {
  * @returns The runtime's canonical IANA name.
  */
 export function canonicalizeTimeZone(value) {
-    if (value.length === 0 || value.trim() !== value || (value !== 'UTC' && !IANA_ZONE.test(value))) {
-        throw new ScheduleInputError('invalid_time_zone', 'time_zone must be UTC or a valid IANA Area/Location name.');
-    }
-    let canonical;
-    try {
-        canonical = new Intl.DateTimeFormat('en-US', { timeZone: value }).resolvedOptions().timeZone;
-    }
-    catch (error) {
-        throw new ScheduleInputError('invalid_time_zone', 'time_zone must be UTC or a valid IANA Area/Location name.', { cause: error });
-    }
-    /* v8 ignore next -- Intl returns the requested canonical zone or an IANA canonical alias. */
-    if (canonical !== 'UTC' && !IANA_ZONE.test(canonical)) {
-        throw new ScheduleInputError('invalid_time_zone', 'time_zone must resolve to UTC or an IANA Area/Location name.');
-    }
-    return canonical;
+    const resolved = canonicalizeSharedTimeZone(value);
+    if (resolved.kind === 'rejected')
+        throw timeZoneError(resolved.reason, resolved.cause);
+    return resolved.timeZone;
 }
 /** Parse strict local calendar fields without consulting a process time zone. */
 function parseLocalAt(value) {
-    const dateMatch = LOCAL_DATE.exec(value.date);
-    const timeMatch = LOCAL_TIME.exec(value.time);
-    const date = dateMatch?.groups;
-    const time = timeMatch?.groups;
-    if (date === undefined || time === undefined) {
-        throw new ScheduleInputError('invalid_rule', 'Local at requires date YYYY-MM-DD and time HH:mm:ss with optional one-to-three digit milliseconds.');
-    }
-    const parts = {
-        year: groupNumber(date, 'year'),
-        month: groupNumber(date, 'month'),
-        day: groupNumber(date, 'day'),
-        hour: groupNumber(time, 'hour'),
-        minute: groupNumber(time, 'minute'),
-        second: groupNumber(time, 'second'),
-        millisecond: milliseconds(time['fraction']),
-    };
-    if (parts.year === 0 || parts.hour > 23 || parts.minute > 59 || parts.second > 59) {
-        throw new ScheduleInputError('invalid_rule', 'The local at value must be a real ISO calendar date and time.');
+    const parsed = parseLocalCalendar(value.date, value.time);
+    if (parsed.kind === 'rejected') {
+        throw new ScheduleInputError('invalid_rule', localCalendarDiagnostic(parsed.reason));
+    }
+    return parsed.time;
+}
+/** Map one shared local-calendar rejection onto the stable Schedule diagnostic. */
+function localCalendarDiagnostic(reason) {
+    switch (reason) {
+        case 'malformed':
+            return 'Local at requires date YYYY-MM-DD and time HH:mm:ss with optional one-to-three digit milliseconds.';
+        case 'not_a_calendar_date':
+            return 'The at value must be a real ISO calendar date and time.';
+        case 'out_of_range':
+            return 'The local at value must be a real ISO calendar date and time.';
+        /* v8 ignore next 3 -- the shared parser returns a closed rejection union. */
+        default: {
+            const unreachable = reason;
+            throw new Error(`unknown local calendar rejection ${String(unreachable)}`);
+        }
     }
-    calendarEpoch(parts);
-    return parts;
-}
-/** Resolve only the earlier overlap instant; a gap fails the local-field round trip. */
-function localInstant(local, timeZone) {
-    const zoned = local.toZonedDateTime(timeZone, { disambiguation: 'earlier' });
-    return zoned.toPlainDateTime().equals(local) ? zoned.epochMilliseconds : undefined;
 }
 /** Resolve a local one-shot, rejecting nonexistent wall-clock times. */
-function resolveLocalInstant(parts, timeZone) {
-    const target = localInstant(Temporal.PlainDateTime.from(parts, { overflow: 'reject' }), timeZone);
+function resolveLocalAt(parts, timeZone) {
+    const target = resolveLocalInstant(parts, timeZone);
     if (target === undefined) {
         throw new ScheduleInputError('invalid_rule', 'The local at time does not exist in the selected time zone.');
     }
     return target;
 }
-/** Decode the exact v1 after record shape. */
+/**
+ * Require a safe, representable, strictly future UTC target.
+ * @param epoch - Candidate target in epoch milliseconds.
+ * @param now - Exclusive lower bound in epoch milliseconds.
+ * @returns The canonical UTC instant; an out-of-range or past target throws ScheduleInputError.
+ */
+export function futureInstant(epoch, now) {
+    const instant = formatFourDigitYearInstant(epoch);
+    if (!Number.isSafeInteger(now) || instant === undefined) {
+        throw new ScheduleInputError('time_out_of_range', 'The scheduled time must be representable as a four-digit-year RFC 3339 UTC instant.');
+    }
+    if (epoch <= now) {
+        throw new ScheduleInputError('not_future', 'The scheduled time must be strictly in the future.');
+    }
+    return instant;
+}
+/** Parse a strict RFC 3339 instant whose numeric offset is part of the input. */
+function parseAtOffsetInstant(value) {
+    const parsed = parseOffsetInstant(value);
+    if (parsed.kind === 'accepted')
+        return parsed.epoch;
+    switch (parsed.reason) {
+        case 'not_rfc3339':
+            throw new ScheduleInputError('invalid_rule', 'at must use YYYY-MM-DDTHH:mm:ss with optional 1-3 digit fractional seconds and an explicit Z or numeric offset.');
+        case 'invalid_numeric_offset':
+            throw new ScheduleInputError('invalid_rule', 'The at numeric offset is invalid.');
+        case 'not_a_calendar_date':
+        case 'out_of_range':
+            throw new ScheduleInputError('invalid_rule', 'The at value must be a real ISO calendar date and time.');
+        /* v8 ignore next 3 -- the shared parser returns a closed rejection union. */
+        default: {
+            const unreachable = parsed.reason;
+            throw new Error(`unknown instant rejection ${String(unreachable)}`);
+        }
+    }
+}
+/** Decode a delayed one-shot Host record. */
 function decodeAfterRecord(value) {
-    /* v8 ignore next -- decodeLegacyScheduleRecord rejects a non-object before it dispatches here. */
-    if (!isRecord(value))
-        throw new ScheduleLogError('after schedule must be an object');
-    const title = decodeHistoricalRecordTitle(value, ['id', 'kind', 'title', 'prompt', 'afterSeconds', 'scheduledAt'], 'after schedule must contain exactly id, kind, title, prompt, afterSeconds, and scheduledAt');
+    const title = decodeRecordTitle(value, ['id', 'kind', 'title', 'prompt', 'afterSeconds', 'scheduledAt'], 'after schedule must contain exactly id, kind, title, prompt, afterSeconds, and scheduledAt');
     const prompt = value['prompt'];
     if (typeof prompt !== 'string' || prompt.length === 0 || prompt.trim() !== prompt) {
         throw new ScheduleLogError('after prompt must be non-empty and already trimmed');
@@ -328,18 +285,15 @@ function decodeAfterRecord(value) {
     return Object.freeze({
         id: decodeId(value['id']),
         kind: 'after',
-        ...(title === undefined ? {} : { title }),
+        title,
         prompt,
         afterSeconds: afterSeconds,
         scheduledAt: decodeInstant(value['scheduledAt']),
     });
 }
-/** Decode the exact v1 absolute one-shot record shape. */
+/** Decode an absolute one-shot Host record. */
 function decodeAtRecord(value) {
-    /* v8 ignore next -- decodeLegacyScheduleRecord rejects a non-object before it dispatches here. */
-    if (!isRecord(value))
-        throw new ScheduleLogError('at schedule must be an object');
-    const title = decodeHistoricalRecordTitle(value, ['id', 'kind', 'title', 'prompt', 'scheduledAt'], 'at schedule must contain exactly id, kind, title, prompt, and scheduledAt');
+    const title = decodeRecordTitle(value, ['id', 'kind', 'title', 'prompt', 'scheduledAt'], 'at schedule must contain exactly id, kind, title, prompt, and scheduledAt');
     const prompt = value['prompt'];
     if (typeof prompt !== 'string' || prompt.length === 0 || prompt.trim() !== prompt) {
         throw new ScheduleLogError('at prompt must be non-empty and already trimmed');
@@ -347,17 +301,14 @@ function decodeAtRecord(value) {
     return Object.freeze({
         id: decodeId(value['id']),
         kind: 'at',
-        ...(title === undefined ? {} : { title }),
+        title,
         prompt,
         scheduledAt: decodeInstant(value['scheduledAt']),
     });
 }
-/** Decode the exact v1 fixed-rate record shape. */
+/** Decode a fixed-rate Host record. */
 function decodeEveryRecord(value) {
-    /* v8 ignore next -- decodeLegacyScheduleRecord rejects a non-object before it dispatches here. */
-    if (!isRecord(value))
-        throw new ScheduleLogError('every schedule must be an object');
-    const title = decodeHistoricalRecordTitle(value, ['id', 'kind', 'title', 'prompt', 'everySeconds', 'scheduledAt'], 'every schedule must contain exactly id, kind, title, prompt, everySeconds, and scheduledAt');
+    const title = decodeRecordTitle(value, ['id', 'kind', 'title', 'prompt', 'everySeconds', 'scheduledAt'], 'every schedule must contain exactly id, kind, title, prompt, everySeconds, and scheduledAt');
     const prompt = value['prompt'];
     if (typeof prompt !== 'string' || prompt.length === 0 || prompt.trim() !== prompt) {
         throw new ScheduleLogError('every prompt must be non-empty and already trimmed');
@@ -372,7 +323,7 @@ function decodeEveryRecord(value) {
     return Object.freeze({
         id: decodeId(value['id']),
         kind: 'every',
-        ...(title === undefined ? {} : { title }),
+        title,
         prompt,
         everySeconds: everySeconds,
         scheduledAt: decodeInstant(value['scheduledAt']),
@@ -404,9 +355,6 @@ export function weeklyTime(value) {
 }
 /** Fail already-typed durable values without wrapping the stored-data diagnostic. */
 function rethrowLogError(error) {
-    /* v8 ignore next -- every wrapped call raises ScheduleInputError, so this pass-through never fires. */
-    if (error instanceof ScheduleLogError)
-        throw error;
     throw new ScheduleLogError(String(error));
 }
 /** Decode a Host daily rule without re-resolving its committed UTC target. */
@@ -531,7 +479,7 @@ function decodeCronRecord(value) {
     }
     let canonical;
     try {
-        canonical = parseCronExpression(expression).expression;
+        canonical = canonicalizeCronExpression(expression);
     }
     catch (error) {
         rethrowLogError(error);
@@ -544,94 +492,22 @@ function decodeCronRecord(value) {
     });
 }
 /**
- * Decode a current Host task record, preserving its committed target and stored zone spelling.
- *
- * Every variant of a stored Host task carries its title, so the historical
- * one-shot variants are re-checked for that member after their shape decodes.
+ * Decode one of the seven current Host timing records without recomputing its committed occurrence.
  * @param value - Untrusted durable JSON record.
- * @returns Detached frozen record; malformed fields throw ScheduleLogError.
+ * @returns Detached frozen record with its required title and authoritative timing fields.
  */
 export function decodeScheduleRecord(value) {
-    if (isRecord(value) && value['kind'] === 'daily')
-        return decodeDailyRecord(value);
-    if (isRecord(value) && value['kind'] === 'weekly')
-        return decodeWeeklyRecord(value);
-    if (isRecord(value) && value['kind'] === 'cron')
-        return decodeCronRecord(value);
-    const record = decodeLegacyScheduleRecord(value);
-    if (record.title === undefined)
-        throw new ScheduleLogError(REQUIRED_TITLE_MESSAGE);
-    return record;
-}
-/**
- * Decode only the variants admitted by historical version-1 Session events.
- *
- * A record written before titles existed decodes without that member, so the
- * fold keeps reading a log that the current creation path could not write.
- * @param value - Untrusted durable JSON record from a Session event.
- * @returns Detached frozen record, without a title when the event omitted it.
- */
-function decodeLegacyScheduleRecord(value) {
     if (!isRecord(value))
         throw new ScheduleLogError('schedule record must be an object');
     switch (value['kind']) {
         case 'after': return decodeAfterRecord(value);
         case 'at': return decodeAtRecord(value);
         case 'every': return decodeEveryRecord(value);
-        default: throw new ScheduleLogError('v1 schedule kind must be "after", "at", or "every"');
-    }
-}
-/**
- * Decode one strict version-1 `schedule/change` payload.
- * @param value - Untrusted durable JSON value.
- * @returns Detached, frozen Schedule change.
- */
-export function decodeScheduleChange(value) {
-    if (!isRecord(value))
-        throw new ScheduleLogError('schedule/change payload must be an object');
-    if (value['version'] !== SCHEDULE_CHANGE_VERSION) {
-        throw new ScheduleLogError('schedule/change version must be 1');
-    }
-    switch (value['operation']) {
-        case 'create':
-            if (!hasExactKeys(value, ['version', 'operation', 'schedule'])) {
-                throw new ScheduleLogError('schedule create must contain exactly version, operation, and schedule');
-            }
-            return Object.freeze({
-                version: SCHEDULE_CHANGE_VERSION,
-                operation: 'create',
-                schedule: decodeLegacyScheduleRecord(value['schedule']),
-            });
-        case 'delete': {
-            if (!hasExactKeys(value, ['version', 'operation', 'id'])) {
-                throw new ScheduleLogError('schedule delete must contain exactly version, operation, and id');
-            }
-            return Object.freeze({
-                version: SCHEDULE_CHANGE_VERSION,
-                operation: 'delete',
-                id: decodeId(value['id']),
-            });
-        }
-        case 'dispatch': {
-            if (hasExactKeys(value, ['version', 'operation', 'id'])) {
-                return Object.freeze({
-                    version: SCHEDULE_CHANGE_VERSION,
-                    operation: 'dispatch',
-                    id: decodeId(value['id']),
-                });
-            }
-            if (hasExactKeys(value, ['version', 'operation', 'id', 'acceptedAt'])) {
-                return Object.freeze({
-                    version: SCHEDULE_CHANGE_VERSION,
-                    operation: 'dispatch',
-                    id: decodeId(value['id']),
-                    acceptedAt: decodeInstant(value['acceptedAt']),
-                });
-            }
-            throw new ScheduleLogError('schedule dispatch must contain id and optional acceptedAt only');
-        }
-        default:
-            throw new ScheduleLogError('schedule/change operation must be create, delete, or dispatch');
+        case 'daily': return decodeDailyRecord(value);
+        case 'weekly': return decodeWeeklyRecord(value);
+        case 'cron': return decodeCronRecord(value);
+        case 'rrule': return decodeRRuleScheduleRecord(value);
+        default: throw new ScheduleLogError('schedule kind must be "after", "at", "every", "daily", "weekly", "cron", or "rrule"');
     }
 }
 /**
@@ -643,9 +519,7 @@ export function decodeScheduleChange(value) {
 export function resolveEveryOccurrence(record, acceptedAt) {
     const target = Date.parse(record.scheduledAt);
     const interval = record.everySeconds * 1_000;
-    if (!Number.isSafeInteger(acceptedAt)
-        || acceptedAt < MIN_FOUR_DIGIT_YEAR_MS
-        || acceptedAt > MAX_FOUR_DIGIT_YEAR_MS) {
+    if (!isFourDigitYearInstant(acceptedAt)) {
         throw new ScheduleLogError('every acceptedAt must be a representable four-digit-year instant');
     }
     if (!Number.isSafeInteger(interval) || interval <= 0) {
@@ -662,7 +536,7 @@ export function resolveEveryOccurrence(record, acceptedAt) {
     }
     const occurrenceAt = new Date(occurrence).toISOString();
     const next = occurrence + interval;
-    if (!Number.isSafeInteger(next) || next > MAX_FOUR_DIGIT_YEAR_MS) {
+    if (!isFourDigitYearInstant(next)) {
         return Object.freeze({ occurrenceAt });
     }
     return Object.freeze({
@@ -691,7 +565,7 @@ function nextMatchingTarget(time, timeZone, now, matches, afterDate) {
     for (; Temporal.PlainDate.compare(date, lastDate) <= 0; date = date.add({ days: 1 })) {
         if (!matches(date))
             continue;
-        const target = localInstant(date.toPlainDateTime(time), timeZone);
+        const target = resolveLocalInstant(date.toPlainDateTime(time), timeZone);
         if (target === undefined)
             continue;
         if (target > MAX_FOUR_DIGIT_YEAR_MS)
@@ -708,17 +582,21 @@ function latestDueOccurrence(timeZone, matches, time, acceptedAt, savedTarget) {
     for (;; date = date.subtract({ days: 1 })) {
         if (!matches(date))
             continue;
-        const candidate = localInstant(date.toPlainDateTime(time), timeZone);
+        const candidate = resolveLocalInstant(date.toPlainDateTime(time), timeZone);
         if (candidate === undefined || candidate > acceptedAt)
             continue;
         // A committed target remains due even if current tzdata places the rule before it.
         return Math.max(candidate, savedTarget);
     }
 }
-/** Resolve a wall-clock rule only when its decision is at a representable four-digit-year instant. */
-function acceptedDecision(selector, acceptedAt) {
-    if (!Number.isSafeInteger(acceptedAt)
-        || acceptedAt < MIN_FOUR_DIGIT_YEAR_MS || acceptedAt > MAX_FOUR_DIGIT_YEAR_MS) {
+/**
+ * Resolve a wall-clock rule only when its decision is at a representable four-digit-year instant.
+ * @param selector - Rule kind named in the failure message.
+ * @param acceptedAt - Explicit wall-clock decision time in epoch milliseconds.
+ * @returns The validated decision time.
+ */
+export function acceptedDecision(selector, acceptedAt) {
+    if (!isFourDigitYearInstant(acceptedAt)) {
         throw new ScheduleLogError(`${selector} acceptedAt must be a representable four-digit-year instant`);
     }
     return acceptedAt;
@@ -775,158 +653,16 @@ export function resolveWeeklyOccurrence(record, acceptedAt) {
     return Object.freeze(nextScheduledAt === undefined ? { occurrenceAt } : { occurrenceAt, nextScheduledAt });
 }
 /**
- * Build the local-date predicate of one parsed cron rule under Vixie day-of-month/day-of-week semantics.
- *
- * The star flag selects the branch only; it never excuses a field's matched values.
- * When either field text starts with `*`, a local date must satisfy BOTH fields, so a
- * stepped star such as `*` followed by `/2` still restricts the dates it matches. A bare
- * `*` matches every value, which makes that field's match always true and degrades the
- * AND to the other field, exactly like Vixie's `DOM_STAR`/`DOW_STAR` test. Only when
- * neither field text starts with `*` does either field matching suffice.
- * @param parsed - Parsed cron rule with canonical field text and matched values.
- * @returns Whether one local date matches the rule.
- */
-function cronDateMatch(parsed) {
-    const months = new Set(parsed.months);
-    const daysOfMonth = new Set(parsed.daysOfMonth);
-    const daysOfWeek = new Set(parsed.daysOfWeek);
-    const dayOfMonthRestricted = !parsed.dayOfMonthStar;
-    const dayOfWeekRestricted = !parsed.dayOfWeekStar;
-    return (date) => {
-        /* v8 ignore next -- both callers pre-filter by month before matching a date. */
-        if (!months.has(date.month))
-            return false;
-        const dayOfMonth = daysOfMonth.has(date.day);
-        const dayOfWeek = daysOfWeek.has(date.dayOfWeek % 7);
-        if (dayOfMonthRestricted && dayOfWeekRestricted)
-            return dayOfMonth || dayOfWeek;
-        return dayOfMonth && dayOfWeek;
-    };
-}
-/** Enumerate one parsed cron rule's local times of day in ascending wall-clock order. */
-function cronTimes(parsed) {
-    const times = [];
-    for (const hour of parsed.hours) {
-        for (const minute of parsed.minutes)
-            times.push(Temporal.PlainTime.from({ hour, minute }));
-    }
-    return times;
-}
-/**
- * Find the first strictly future cron occurrence without leaving the four-digit UTC year range.
- *
- * The walk stops at {@link CRON_SEARCH_HORIZON_YEARS} past the floor date when that
- * horizon precedes the four-digit ceiling: a rule with no match inside the horizon
- * never matches, so its search resolves to exhaustion instead of scanning to the ceiling.
- * @param parsed - Parsed cron rule.
- * @param timeZone - Explicit zone interpreting its local date and time.
- * @param floor - Instant every returned target must exceed.
- * @returns The first matching target, or exhaustion as undefined.
- */
-function nextCronTarget(parsed, timeZone, floor) {
-    const times = cronTimes(parsed);
-    const matches = cronDateMatch(parsed);
-    const months = new Set(parsed.months);
-    const firstDate = localDate(floor, timeZone);
-    let date = firstDate;
-    // The floor's own local wall clock, so the first date converts only candidates
-    // that can exceed it instead of its whole day of times.
-    const floorTime = Temporal.Instant.fromEpochMilliseconds(floor).toZonedDateTimeISO(timeZone).toPlainTime();
-    const ceiling = localDate(MAX_FOUR_DIGIT_YEAR_MS, 'UTC').add({ days: 1 });
-    const horizon = date.add({ years: CRON_SEARCH_HORIZON_YEARS });
-    const lastDate = Temporal.PlainDate.compare(horizon, ceiling) < 0 ? horizon : ceiling;
-    while (Temporal.PlainDate.compare(date, lastDate) <= 0) {
-        if (!months.has(date.month)) {
-            date = date.add({ months: 1 }).with({ day: 1 });
-            continue;
-        }
-        if (matches(date)) {
-            for (const time of times) {
-                if (date.equals(firstDate) && Temporal.PlainTime.compare(time, floorTime) < 0)
-                    continue;
-                const target = localInstant(date.toPlainDateTime(time), timeZone);
-                if (target === undefined)
-                    continue;
-                if (target > MAX_FOUR_DIGIT_YEAR_MS)
-                    return undefined;
-                if (target >= MIN_FOUR_DIGIT_YEAR_MS && target > floor)
-                    return new Date(target).toISOString();
-            }
-        }
-        date = date.add({ days: 1 });
-    }
-    return undefined;
-}
-/**
- * Find the latest matching cron occurrence at or before a decision without leaving the committed floor.
- *
- * The walk stops at {@link CRON_SEARCH_HORIZON_YEARS} before the decision date when that
- * horizon follows the four-digit floor, which is the local date holding that floor instant
- * in the rule's own zone: a rule with no match inside the horizon keeps the committed target
- * instead of scanning back to the floor, and a candidate before the floor instant is skipped.
- * @param parsed - Parsed cron rule.
- * @param timeZone - Explicit zone interpreting its local date and time.
- * @param decision - Wall-clock decision time in epoch milliseconds.
- * @param savedTarget - Committed target that stays due even when current zone data resolves past it.
- * @returns The latest due occurrence, or the committed target when no local occurrence is representable.
- */
-function latestCronOccurrence(parsed, timeZone, decision, savedTarget) {
-    const times = cronTimes(parsed);
-    const matches = cronDateMatch(parsed);
-    const months = new Set(parsed.months);
-    // Offsets are less than 24 hours; a date-line rollback can make a due local date
-    // later than the UTC decision date, which is why the walk starts one day after it.
-    let date = localDate(decision, 'UTC').add({ days: 1 });
-    // The floor is an instant: the earliest local date the walk may reach is the one
-    // holding it in the rule's own zone, and candidates below it are skipped, so a
-    // negative offset can still resolve a due local minute dated before the UTC floor.
-    const floorDate = localDate(MIN_FOUR_DIGIT_YEAR_MS, timeZone);
-    const horizon = date.subtract({ years: CRON_SEARCH_HORIZON_YEARS });
-    const firstDate = Temporal.PlainDate.compare(horizon, floorDate) > 0 ? horizon : floorDate;
-    while (Temporal.PlainDate.compare(date, firstDate) >= 0) {
-        if (!months.has(date.month)) {
-            date = date.with({ day: 1 }).subtract({ days: 1 });
-            continue;
-        }
-        if (matches(date)) {
-            // One conversion of the date's earliest wall clock decides whether the whole
-            // date lies beyond the decision: every later time on it is later too, so the
-            // walk steps back instead of converting the rest of a day that cannot match.
-            // An earliest time that a DST gap removes leaves the bound to the first time
-            // that does exist, and a date with no existing time keeps the full walk.
-            const earliest = times.reduce((found, time) => found ?? localInstant(date.toPlainDateTime(time), timeZone), undefined);
-            if (earliest !== undefined && earliest > decision) {
-                date = date.subtract({ days: 1 });
-                continue;
-            }
-            for (const time of [...times].reverse()) {
-                const candidate = localInstant(date.toPlainDateTime(time), timeZone);
-                if (candidate === undefined || candidate > decision || candidate < MIN_FOUR_DIGIT_YEAR_MS)
-                    continue;
-                // A committed target remains due even if current tzdata places the rule before it.
-                return Math.max(candidate, savedTarget);
-            }
-        }
-        date = date.subtract({ days: 1 });
-    }
-    return savedTarget;
-}
-/**
- * Resolve a cron decision near the decision's local date, not across its missed history.
- * @param record - Cron rule with a committed earliest unaccepted UTC target.
- * @param acceptedAt - Explicit wall-clock decision time, at or after the committed target.
- * @returns Latest actual due occurrence and the first future occurrence.
+ * Resolve a Cron rule through the shared bounded recurrence engine.
+ * @param record - Authoritative Cron expression, zone, and committed occurrence.
+ * @param acceptedAt - Decision time at or after the committed occurrence.
+ * @returns The latest due occurrence and optional future successor.
  */
 export function resolveCronOccurrence(record, acceptedAt) {
-    const decision = acceptedDecision('cron', acceptedAt);
-    const savedTarget = Date.parse(record.scheduledAt);
-    if (decision < savedTarget)
+    acceptedDecision('cron', acceptedAt);
+    if (acceptedAt < Date.parse(record.scheduledAt))
         throw new ScheduleLogError('cron dispatch cannot precede the active scheduledAt');
-    const parsed = parseCronExpression(record.expression);
-    const occurrence = latestCronOccurrence(parsed, record.timeZone, decision, savedTarget);
-    const occurrenceAt = new Date(occurrence).toISOString();
-    const nextScheduledAt = nextCronTarget(parsed, record.timeZone, decision);
-    return Object.freeze(nextScheduledAt === undefined ? { occurrenceAt } : { occurrenceAt, nextScheduledAt });
+    return readRecurrence(Cron.parse(record.expression, record.timeZone)).resolve(record.scheduledAt, acceptedAt);
 }
 /**
  * Identify recurring Host records explicitly, excluding both one-shot variants.
@@ -934,7 +670,7 @@ export function resolveCronOccurrence(record, acceptedAt) {
  * @returns Whether the record uses a recurring rule.
  */
 export function isRecurringScheduleRecord(record) {
-    return record.kind === 'every' || record.kind === 'daily' || record.kind === 'weekly' || record.kind === 'cron';
+    return record.kind === 'every' || record.kind === 'daily' || record.kind === 'weekly' || record.kind === 'cron' || record.kind === 'rrule';
 }
 /**
  * Resolve one due recurring Host record with its rule-specific calendar or interval arithmetic.
@@ -948,112 +684,9 @@ export function resolveRecurringOccurrence(record, acceptedAt) {
         case 'daily': return resolveDailyOccurrence(record, acceptedAt);
         case 'weekly': return resolveWeeklyOccurrence(record, acceptedAt);
         case 'cron': return resolveCronOccurrence(record, acceptedAt);
+        case 'rrule': return resolveRRuleOccurrence(record, acceptedAt);
     }
 }
-/** Apply one decoded dispatch to its exact active record. */
-function dispatchedRecord(record, change) {
-    const hasAcceptedAt = 'acceptedAt' in change;
-    if (record.kind !== 'every') {
-        if (hasAcceptedAt)
-            throw new ScheduleLogError('one-shot dispatch must not contain acceptedAt');
-        return undefined;
-    }
-    if (!hasAcceptedAt)
-        throw new ScheduleLogError('every dispatch must contain acceptedAt');
-    const occurrence = resolveEveryOccurrence(record, Date.parse(change.acceptedAt));
-    return occurrence.nextScheduledAt === undefined
-        ? undefined
-        : Object.freeze({ ...record, scheduledAt: occurrence.nextScheduledAt });
-}
-/**
- * Apply already-decoded Schedule changes to one complete fold value.
- *
- * The transition authority for full-log replay. One mutable Map/Set pair spans
- * the whole batch; the returned arrays are materialized and frozen once.
- * @param folded - complete active records and used-id history before the changes.
- * @param changes - strictly decoded durable mutations in log order.
- * @returns the complete fold value after every mutation.
- */
-export function applyScheduleChanges(folded, changes) {
-    const active = new Map(folded.active.map(record => [record.id, record]));
-    const seen = new Set(folded.seenIds);
-    for (const change of changes) {
-        switch (change.operation) {
-            case 'create':
-                if (seen.has(change.schedule.id)) {
-                    throw new ScheduleLogError(`schedule id ${JSON.stringify(change.schedule.id)} was reused`);
-                }
-                seen.add(change.schedule.id);
-                active.set(change.schedule.id, change.schedule);
-                break;
-            case 'delete':
-                if (!active.delete(change.id)) {
-                    throw new ScheduleLogError(`schedule delete targets inactive id ${JSON.stringify(change.id)}`);
-                }
-                break;
-            case 'dispatch': {
-                const record = active.get(change.id);
-                if (record === undefined) {
-                    throw new ScheduleLogError(`schedule dispatch targets inactive id ${JSON.stringify(change.id)}`);
-                }
-                const next = dispatchedRecord(record, change);
-                if (next === undefined)
-                    active.delete(change.id);
-                else
-                    active.set(change.id, next);
-                break;
-            }
-            /* v8 ignore next 3 -- decodeScheduleChange returns a closed operation union. */
-            default: {
-                const unreachable = change;
-                throw new ScheduleLogError(`unknown decoded schedule change ${String(unreachable)}`);
-            }
-        }
-    }
-    return Object.freeze({
-        active: Object.freeze([...active.values()]),
-        seenIds: Object.freeze([...seen]),
-    });
-}
-/**
- * Fold the package-owned stream after the durable fork seed boundary.
- * @param events - Complete ordered session log or candidate-extended log.
- * @param inheritedEventCount - Inherited prefix length excluded from child ownership.
- * @returns Active records and all previously used ids.
- */
-export function foldScheduleEvents(events, inheritedEventCount = SessionLogOffset(0)) {
-    if (!Number.isSafeInteger(inheritedEventCount)
-        || inheritedEventCount < 0
-        || inheritedEventCount > events.length) {
-        throw new ScheduleLogError('schedule inheritedEventCount must be within the supplied event log');
-    }
-    const initial = Object.freeze({
-        active: Object.freeze([]),
-        seenIds: Object.freeze([]),
-    });
-    const changes = function* () {
-        for (const event of events.slice(inheritedEventCount)) {
-            if (event.type === 'schedule/change')
-                yield decodeScheduleChange(event.data);
-        }
-    };
-    return applyScheduleChanges(initial, changes());
-}
-/**
- * Allocate the next readable id without reusing any prior session-local id.
- * @param folded - Fold containing every previously created id.
- * @returns A fresh `schedule-N` identity.
- */
-export function allocateScheduleId(folded) {
-    const seen = new Set(folded.seenIds);
-    let sequence = seen.size + 1;
-    let candidate = ScheduleId(`schedule-${sequence}`);
-    while (seen.has(candidate)) {
-        sequence += 1;
-        candidate = ScheduleId(`schedule-${sequence}`);
-    }
-    return candidate;
-}
 /**
  * Validate a model after rule and compute its durable target.
  * @param id - Already allocated task id.
@@ -1112,7 +745,7 @@ export function createAtScheduleRecord(id, prompt, at, now, title) {
 export function parseAtInput(at) {
     let target;
     if (typeof at === 'string') {
-        target = parseOffsetInstant(at);
+        target = parseAtOffsetInstant(at);
     }
     else if (isRecord(at)) {
         if (!hasExactKeys(at, ['date', 'time', 'time_zone'])) {
@@ -1130,7 +763,7 @@ export function parseAtInput(at) {
             time: at['time'],
             time_zone: rawTimeZone,
         };
-        target = resolveLocalInstant(parseLocalAt(local), canonicalizeTimeZone(rawTimeZone));
+        target = resolveLocalAt(parseLocalAt(local), canonicalizeTimeZone(rawTimeZone));
     }
     else {
         throw new ScheduleInputError('invalid_rule', 'at must be an explicit-offset string or local calendar object.');
@@ -1183,7 +816,7 @@ export function createDailyScheduleRecord(id, prompt, daily, now, title) {
         throw new ScheduleInputError('invalid_prompt', 'prompt must be non-empty after trimming.');
     }
     const { time, timeZone } = parseDailyInput(daily);
-    if (!Number.isSafeInteger(now) || now < MIN_FOUR_DIGIT_YEAR_MS || now > MAX_FOUR_DIGIT_YEAR_MS) {
+    if (!isFourDigitYearInstant(now)) {
         throw new ScheduleInputError('time_out_of_range', 'Daily creation time must be a representable four-digit-year UTC instant.');
     }
     const scheduledAt = nextDailyTarget(dailyTime(time), timeZone, now);
@@ -1226,7 +859,7 @@ export function createWeeklyScheduleRecord(id, prompt, weekly, now, title) {
         throw new ScheduleInputError('invalid_prompt', 'prompt must be non-empty after trimming.');
     }
     const { time, timeZone, weekdays } = parseWeeklyInput(weekly);
-    if (!Number.isSafeInteger(now) || now < MIN_FOUR_DIGIT_YEAR_MS || now > MAX_FOUR_DIGIT_YEAR_MS) {
+    if (!isFourDigitYearInstant(now)) {
         throw new ScheduleInputError('time_out_of_range', 'Weekly creation time must be a representable four-digit-year UTC instant.');
     }
     const scheduledAt = nextWeeklyTarget(weeklyTime(time), timeZone, weekdays, now);
@@ -1253,10 +886,10 @@ export function createCronScheduleRecord(id, prompt, cron, now, title) {
         throw new ScheduleInputError('invalid_prompt', 'prompt must be non-empty after trimming.');
     }
     const { expression, timeZone } = parseCronInput(cron);
-    if (!Number.isSafeInteger(now) || now < MIN_FOUR_DIGIT_YEAR_MS || now > MAX_FOUR_DIGIT_YEAR_MS) {
+    if (!isFourDigitYearInstant(now)) {
         throw new ScheduleInputError('time_out_of_range', 'Cron creation time must be a representable four-digit-year UTC instant.');
     }
-    const scheduledAt = nextCronTarget(parseCronExpression(expression), timeZone, now);
+    const scheduledAt = readRecurrence(Cron.parse(expression, timeZone)).next(now);
     if (scheduledAt === undefined) {
         throw new ScheduleInputError('time_out_of_range', 'No future cron occurrence is representable as a four-digit-year UTC instant.');
     }
@@ -1284,242 +917,20 @@ export function parseWeeklyInput(weekly) {
         weekdays: normalizeWeekdays(weekly['weekdays']),
     };
 }
-const CRON_FIELDS = [
-    { name: 'minute', min: 0, max: 59, canonicalMax: 59 },
-    { name: 'hour', min: 0, max: 23, canonicalMax: 23 },
-    { name: 'day-of-month', min: 1, max: 31, canonicalMax: 31 },
-    { name: 'month', min: 1, max: 12, canonicalMax: 12 },
-    { name: 'day-of-week', min: 0, max: 7, canonicalMax: 6 },
-];
-/** Build the stable diagnostic for one malformed cron field element. */
-function invalidCronField(spec, element) {
-    return new ScheduleInputError('invalid_rule', `cron.expression ${spec.name} field element ${JSON.stringify(element)} must be *, a value, a-b, */n, a-b/n, `
-        + 'or a comma-separated list of those.');
-}
-/** Read one in-range cron field value. */
-function cronFieldValue(text, spec) {
-    const value = Number(text);
-    if (!Number.isSafeInteger(value) || value < spec.min || value > spec.max) {
-        throw new ScheduleInputError('invalid_rule', `cron.expression ${spec.name} field value ${text} is outside ${spec.min}-${spec.max}.`);
-    }
-    return value;
-}
-/** Read one positive cron field step. */
-function cronFieldStep(text, spec) {
-    const step = Number(text);
-    if (!Number.isSafeInteger(step) || step < 1) {
-        throw new ScheduleInputError('invalid_rule', `cron.expression ${spec.name} field step must be a positive integer.`);
-    }
-    return step;
-}
-/** Expand one comma-separated cron field into its matched value set. */
-function cronFieldValues(raw, spec) {
-    const matched = new Set();
-    for (const element of raw.split(',')) {
-        if (element.length === 0) {
-            throw new ScheduleInputError('invalid_rule', `cron.expression ${spec.name} field must not contain an empty list element.`);
-        }
-        if (element === '*') {
-            for (let value = spec.min; value <= spec.max; value += 1)
-                matched.add(value);
-            continue;
-        }
-        if (element.startsWith('*')) {
-            const stepped = /^\*\/(?<step>\d+)$/.exec(element);
-            const groups = stepped?.groups;
-            if (groups === undefined)
-                throw invalidCronField(spec, element);
-            const stepText = groups['step'];
-            /* v8 ignore next -- a successful fixed regex always provides the step group. */
-            if (stepText === undefined)
-                throw invalidCronField(spec, element);
-            const step = cronFieldStep(stepText, spec);
-            for (let value = spec.min; value <= spec.max; value += step)
-                matched.add(value);
-            continue;
-        }
-        const parsed = /^(?<start>\d+)(?:-(?<end>\d+))?(?:\/(?<step>\d+))?$/.exec(element);
-        const groups = parsed?.groups;
-        if (groups === undefined)
-            throw invalidCronField(spec, element);
-        const startText = groups['start'];
-        /* v8 ignore next -- a successful fixed regex always provides the start group. */
-        if (startText === undefined)
-            throw invalidCronField(spec, element);
-        const start = cronFieldValue(startText, spec);
-        const end = groups['end'];
-        const stepText = groups['step'];
-        if (end === undefined) {
-            if (stepText !== undefined)
-                throw invalidCronField(spec, element);
-            matched.add(start);
-            continue;
-        }
-        const last = cronFieldValue(end, spec);
-        if (start > last) {
-            throw new ScheduleInputError('invalid_rule', `cron.expression ${spec.name} field range ${start}-${last} is inverted.`);
-        }
-        const step = stepText === undefined ? 1 : cronFieldStep(stepText, spec);
-        for (let value = start; value <= last; value += step)
-            matched.add(value);
-    }
-    const values = new Set();
-    for (const value of matched) {
-        values.add(spec.canonicalMax !== spec.max && value === spec.max ? spec.min : value);
-    }
-    return [...values].sort((left, right) => left - right);
-}
-/**
- * Read one value the encoder already proved present.
- * @param values - matched value set the parser always fills.
- * @param index - index the caller derived from that set.
- * @returns the value at that index.
- */
-function cronFieldValueAt(values, index) {
-    const value = values[index];
-    /* v8 ignore next -- a parsed cron field always matches at least one value. */
-    if (value === undefined)
-        throw new ScheduleLogError('cron field encoding requires a non-empty value set');
-    return value;
-}
-/** Encode one matched value set as the shortest equivalent comma-separated cron field.
- * @param values - Matched values in ascending order.
- * @returns Field text that re-parses to exactly `values`, never spelled with a leading `*`.
- */
-function encodeCronField(values) {
-    const first = cronFieldValueAt(values, 0);
-    if (values.length === 1)
-        return String(first);
-    const last = cronFieldValueAt(values, values.length - 1);
-    const step = cronFieldValueAt(values, 1) - first;
-    let uniform = true;
-    for (let index = 2; index < values.length; index += 1) {
-        if (cronFieldValueAt(values, index) - cronFieldValueAt(values, index - 1) !== step) {
-            uniform = false;
-            break;
-        }
-    }
-    if (uniform) {
-        if (step === 1)
-            return `${first}-${last}`;
-        return `${first}-${last}/${step}`;
-    }
-    const parts = [];
-    let runStart = first;
-    for (let index = 1; index < values.length; index += 1) {
-        const current = cronFieldValueAt(values, index);
-        const previous = cronFieldValueAt(values, index - 1);
-        if (current === previous + 1)
-            continue;
-        parts.push(runStart === previous ? String(runStart) : `${runStart}-${previous}`);
-        runStart = current;
-    }
-    const final = cronFieldValueAt(values, values.length - 1);
-    parts.push(runStart === final ? String(runStart) : `${runStart}-${final}`);
-    return parts.join(',');
-}
-/**
- * One uniform walk from a field's minimum, folded exactly as a parsed field folds.
- * @param spec - Field range and canonical maximum.
- * @param step - Positive step of the walk.
- * @returns Ascending values `step` produces from the minimum.
- */
-function starWalk(spec, step) {
-    const walked = new Set();
-    for (let value = spec.min; value <= spec.max; value += step) {
-        walked.add(spec.canonicalMax !== spec.max && value === spec.max ? spec.min : value);
-    }
-    return [...walked].sort((left, right) => left - right);
-}
-/**
- * Canonical spelling of a field whose text started with `*`.
- *
- * Only a `*`-prefixed spelling keeps the star flag, and only the bare star or a star-step
- * (a `*` followed by `/n`) admits a leading `*`, so the encoding is the bare star for every
- * value, otherwise the widest star-step walk plus any remaining values as a list.
- * Re-parsing therefore reproduces both the star flag and the matched set, which is what
- * keeps day-of-month/day-of-week AND/OR selection stable across a stored canonical
- * expression.
- * @param values - Matched values in ascending order.
- * @param spec - Field range and canonical maximum.
- * @returns Canonical field text that starts with `*`.
- */
-function encodeStarCronField(values, spec) {
-    if (values.length === spec.canonicalMax - spec.min + 1)
-        return '*';
-    const present = new Set(values);
-    let bestStep;
-    let bestWalk = [];
-    for (let step = 1; step <= spec.max - spec.min + 1; step += 1) {
-        const walk = starWalk(spec, step);
-        if (walk.length > bestWalk.length && walk.every(value => present.has(value))) {
-            bestStep = step;
-            bestWalk = walk;
-        }
-    }
-    /* v8 ignore next -- the widest step yields the single minimum, which every `*`-led field matches. */
-    if (bestStep === undefined)
-        throw new ScheduleInputError('invalid_rule', `${spec.name} cannot keep a leading \`*\`.`);
-    const walked = new Set(bestWalk);
-    const remaining = values.filter(value => !walked.has(value));
-    const walkText = `*/${bestStep}`;
-    return remaining.length === 0
-        ? walkText
-        : `${walkText},${encodeCronField(remaining)}`;
-}
-/**
- * Parse one cron field into its matched values, canonical spelling, and star flag.
- *
- * The star flag tests the field text's first character, which is how Vixie sets
- * `DOM_STAR`/`DOW_STAR`: a stepped star (`*` followed by `/2`) is a star although
- * it matches half the range, while an explicit full range such as `1-31` is
- * restricted. Canonicalization preserves the flag: a `*`-led field keeps a `*`-led
- * spelling, and a field that did not start with `*` is never spelled as a star-step.
- */
-function parseCronField(raw, spec) {
-    const values = cronFieldValues(raw, spec);
-    const star = raw.startsWith('*');
-    return Object.freeze({
-        values: Object.freeze(values),
-        canonical: star ? encodeStarCronField(values, spec) : encodeCronField(values),
-        star,
-    });
-}
-/** Parse and canonicalize one strict five-field cron expression. */
-function parseCronExpression(expression) {
-    if (typeof expression !== 'string' || expression.length === 0 || expression.trim() !== expression) {
-        throw new ScheduleInputError('invalid_rule', 'cron.expression must be a non-empty trimmed string.');
-    }
-    const fields = expression.split(/\s+/);
-    if (fields.length !== 5) {
-        throw new ScheduleInputError('invalid_rule', 'cron.expression must contain exactly five whitespace-separated fields: '
-            + 'minute hour day-of-month month day-of-week.');
-    }
-    const [minute, hour, dayOfMonth, month, dayOfWeek] = fields.map((field, index) => {
-        const fieldSpec = CRON_FIELDS[index];
-        /* v8 ignore next -- the five-field split bounds this index. */
-        if (fieldSpec === undefined)
-            throw new ScheduleLogError('cron field specification is missing');
-        return parseCronField(field, fieldSpec);
-    });
-    return Object.freeze({
-        expression: [minute, hour, dayOfMonth, month, dayOfWeek].map(field => field.canonical).join(' '),
-        minutes: minute.values,
-        hours: hour.values,
-        daysOfMonth: dayOfMonth.values,
-        months: month.values,
-        daysOfWeek: dayOfWeek.values,
-        dayOfMonthStar: dayOfMonth.star,
-        dayOfWeekStar: dayOfWeek.star,
-    });
+/** Map a shared time-parser reason into Schedule's public error vocabulary. */
+function readRecurrence(result) {
+    if (result.kind === 'accepted')
+        return result.rule;
+    const codes = { syntax: 'invalid_rule', time_zone: 'invalid_time_zone', density: 'frequency_too_high' };
+    throw new ScheduleInputError(codes[result.reason], result.detail, { cause: result.cause });
 }
 /**
- * Canonicalize one strict five-field cron expression.
- * @param expression - Candidate `minute hour day-of-month month day-of-week` expression.
- * @returns The canonical expression; malformed or unsupported input throws ScheduleInputError.
+ * Canonicalize one supported five-field Cron expression.
+ * @param expression - Strict five-field input text.
+ * @returns Canonical text preserving the Vixie day-matching semantics.
  */
 export function canonicalizeCronExpression(expression) {
-    return parseCronExpression(expression).expression;
+    return readRecurrence(Cron.parse(expression, 'UTC')).expression;
 }
 /**
  * Normalize a cron selector without calculating a new committed target.
@@ -1534,28 +945,15 @@ export function parseCronInput(cron) {
         throw new ScheduleInputError('invalid_time_zone', 'time_zone must be a string.');
     }
     return {
-        expression: parseCronExpression(cron['expression']).expression,
+        expression: canonicalizeCronExpression(cron['expression']),
         timeZone: canonicalizeTimeZone(cron['time_zone']),
     };
 }
-/**
- * Derive one execution-local management view.
- * @param record - Active durable record.
- * @param now - Wall-clock sample used for its timing state.
- * @returns Complete Host delivery view.
- */
-export function scheduleView(record, now) {
-    return Object.freeze({
-        ...record,
-        state: now >= Date.parse(record.scheduledAt) ? 'overdue' : 'scheduled',
-        deliveryMode: 'host',
-    });
-}
 /** Fixed model-facing origin line shared by one-shot and recurring reminder delivery. */
 const SCHEDULED_MESSAGE_FRAMING = 'This is a scheduled message from the user';
 /**
- * Render the fixed model framing for a due reminder.
- * @param record - Due active record.
+ * Render the fixed model framing for one due reminder.
+ * @param record - Due task identity, instruction, and delivered occurrence.
  * @returns Stable model-visible text with JSON-escaped dynamic fields.
  */
 export function renderReminderFraming(record) {
@@ -1584,4 +982,120 @@ export function renderRecurringReminderBatchFraming(reminders) {
         `reminders_json: ${JSON.stringify(payload)}`,
     ].join('\n');
 }
+/** Freeze a record whose scheduledAt is the first occurrence of a prepared rule strictly after a time. */
+function firstRecord(id, title, prompt, prepared, now) {
+    if (!isFourDigitYearInstant(now))
+        throw new ScheduleInputError('time_out_of_range', 'The recurrence reference time is outside the supported range.');
+    const scheduledAt = prepared.next(now);
+    if (scheduledAt === undefined) {
+        throw new ScheduleInputError('not_future', 'rrule must contain an occurrence strictly in the future.');
+    }
+    return Object.freeze({ id, kind: 'rrule', title, prompt, rrule: prepared.expression, scheduledAt });
+}
+/**
+ * Validate and normalize the supported RFC 5545 recurrence content.
+ * @param value - Two-line DTSTART and RRULE input.
+ * @returns The trimmed newline-separated recurrence; an unsupported rule throws ScheduleInputError.
+ */
+export function normalizeRRule(value) {
+    return readRecurrence(RRule.parse(value)).expression;
+}
+/**
+ * Create one Host task record with its first committed occurrence.
+ * @param id - Host-allocated canonical schedule id.
+ * @param title - User-facing schedule title.
+ * @param prompt - Instruction delivered when the schedule fires.
+ * @param rrule - DTSTART and RRULE content.
+ * @param now - Exclusive creation-time lower bound in epoch milliseconds.
+ * @returns Frozen schedule record.
+ */
+export function createRRuleScheduleRecord(id, title, prompt, rrule, now) {
+    const normalizedTitle = scheduleTitle(title);
+    const normalizedPrompt = prompt.trim();
+    if (normalizedPrompt.length === 0) {
+        throw new ScheduleInputError('invalid_prompt', 'prompt must be non-empty after trimming.');
+    }
+    const prepared = readRecurrence(RRule.parse(rrule, { rejectIneffectiveSetPositions: true }));
+    return firstRecord(id, normalizedTitle, normalizedPrompt, prepared, now);
+}
+/**
+ * Update descriptive fields and optionally recompute the next occurrence.
+ * @param current - Existing schedule record.
+ * @param change - Supplied editable record fields.
+ * @param now - Exclusive edit-time lower bound in epoch milliseconds.
+ * @param recompute - Whether to derive a fresh next occurrence.
+ * @returns Frozen updated schedule record.
+ */
+export function updateRRuleScheduleRecord(current, change, now, recompute) {
+    const title = scheduleTitle(change.title ?? current.title);
+    const prompt = (change.prompt ?? current.prompt).trim();
+    if (prompt.length === 0)
+        throw new ScheduleInputError('invalid_prompt', 'prompt must be non-empty after trimming.');
+    const prepared = change.rrule === undefined
+        ? readRecurrence(RRule.parse(current.rrule))
+        : readRecurrence(RRule.parse(change.rrule, { rejectIneffectiveSetPositions: true }));
+    if (recompute)
+        return firstRecord(current.id, title, prompt, prepared, now);
+    return Object.freeze({ ...current, title, prompt, rrule: prepared.expression });
+}
+/**
+ * Resolve the latest due occurrence and the first later occurrence without replaying a backlog.
+ * @param record - Due schedule record.
+ * @param acceptedAt - Dispatch admission time in epoch milliseconds.
+ * @returns Latest due occurrence and optional next occurrence.
+ */
+export function resolveRRuleOccurrence(record, acceptedAt) {
+    const decision = acceptedDecision('rrule', acceptedAt);
+    const savedTarget = Date.parse(record.scheduledAt);
+    if (decision < savedTarget)
+        throw new ScheduleLogError('rrule dispatch cannot precede the active scheduledAt');
+    return readRecurrence(RRule.parse(record.rrule)).resolve(record.scheduledAt, decision);
+}
+/**
+ * Decode a current Host task record.
+ * @param value - Untrusted durable JSON record.
+ * @returns Detached frozen record; malformed fields throw ScheduleLogError.
+ */
+export function decodeRRuleScheduleRecord(value) {
+    if (!isRecord(value) || value['kind'] !== 'rrule' || !hasExactKeys(value, ['id', 'kind', 'title', 'prompt', 'rrule', 'scheduledAt'])) {
+        throw new ScheduleLogError('rrule schedule must contain exactly id, kind, title, prompt, rrule, and scheduledAt');
+    }
+    const title = decodeStoredTitle(value['title']);
+    const prompt = value['prompt'];
+    const rrule = value['rrule'];
+    if (typeof prompt !== 'string' || prompt.length === 0 || prompt.trim() !== prompt) {
+        throw new ScheduleLogError('schedule prompt must be non-empty and already trimmed');
+    }
+    if (typeof rrule !== 'string')
+        throw new ScheduleLogError('schedule rrule must be a string');
+    let normalized;
+    try {
+        normalized = normalizeRRule(rrule);
+    }
+    catch (error) {
+        throw new ScheduleLogError(`invalid schedule rrule: ${String(error)}`);
+    }
+    if (normalized !== rrule)
+        throw new ScheduleLogError('schedule rrule must be normalized');
+    return Object.freeze({
+        id: decodeId(value['id']),
+        kind: 'rrule',
+        title,
+        prompt,
+        rrule,
+        scheduledAt: decodeInstant(value['scheduledAt']),
+    });
+}
+/**
+ * Render an instant in the authoritative zone of any timing kind; elapsed and absolute rules use UTC.
+ * @param record - Timing record that owns the display zone.
+ * @param instant - UTC instant to render with second precision.
+ * @returns Local ISO date-time with its numeric offset.
+ */
+export function formatScheduleLocalTime(record, instant) {
+    const timeZone = record.kind === 'rrule' ? readRecurrence(RRule.parse(record.rrule)).timeZone
+        : 'timeZone' in record ? record.timeZone : 'UTC';
+    return Temporal.Instant.from(instant).toZonedDateTimeISO(timeZone)
+        .toString({ timeZoneName: 'never', smallestUnit: 'second' });
+}
 //# sourceMappingURL=domain.js.map