@qilin-agent/schedule 3.1.7 → 3.1.9

package/lib/types/delivery-history.d.ts

@@ -1,12 +1,10 @@
-/** Saved delivery interpretation and identity-based pagination without Session reads. */
+/** Saved delivery retention and identity-based pagination without Session reads. */
 import type { ScheduleTask } from './storage.ts';
 import type { DeliveryRetentionBounds, ScheduleDeliveryHistoryRequest, ScheduleDeliveryHistoryResult, ScheduleDeliveryReceipt } from './types.ts';
 /**
  * Prepare one real inbox acknowledgment for the same task write as its status and target.
- * Prunes to the configured window and record cap here, on the only write path: the
- * domain publishes one whole-unit document per write, so an unbounded array would
- * grow that document with every acknowledgment. The read path states no bound of
- * its own, because a whole-unit document over the schema's limits refuses to open.
+ * Prunes to the configured window and record cap here, on the only write path, so a task record does not grow
+ * with every acknowledgment.
  * @param task - Task supplying the immutable sent prompt and retained history.
  * @param receipt - Acknowledgment obtained after successful Session flush.
  * @param bounds - Configured retention window and record cap for the appended history.
@@ -15,7 +13,7 @@ import type { DeliveryRetentionBounds, ScheduleDeliveryHistoryRequest, ScheduleD
 export declare function appendDelivery(task: ScheduleTask, receipt: ScheduleDeliveryReceipt, bounds: DeliveryRetentionBounds): Required<Pick<ScheduleTask, 'lastDelivery' | 'deliveryHistory'>>;
 /**
  * Read one newest-first page in append order, independent of wall-clock ordering.
- * @param task - Task already checked against the requested Session binding.
+ * @param task - Task already selected by the caller.
  * @param request - Validated explicit page size and optional exclusive message cursor.
  * @param retention - Current configured limits shared with the delivery writer.
  * @returns Copied delivery records or a cursor-not-found result.

package/lib/types/delivery-history.js

@@ -1,29 +1,16 @@
 /** Milliseconds in one day, the unit the retention window is stated in. */
 const DAY_MS = 86_400_000;
-/**
- * Read retained history; missing history exposes only the actual legacy receipt.
- * @param task - Immutable stored task.
- * @returns Oldest-first retained deliveries without changing storage.
- */
-function deliveryHistoryOf(task) {
-    return task.deliveryHistory ?? {
-        records: task.lastDelivery === undefined ? [] : [task.lastDelivery],
-        earlierRecordsUnavailable: true,
-    };
-}
 /**
  * Prepare one real inbox acknowledgment for the same task write as its status and target.
- * Prunes to the configured window and record cap here, on the only write path: the
- * domain publishes one whole-unit document per write, so an unbounded array would
- * grow that document with every acknowledgment. The read path states no bound of
- * its own, because a whole-unit document over the schema's limits refuses to open.
+ * Prunes to the configured window and record cap here, on the only write path, so a task record does not grow
+ * with every acknowledgment.
  * @param task - Task supplying the immutable sent prompt and retained history.
  * @param receipt - Acknowledgment obtained after successful Session flush.
  * @param bounds - Configured retention window and record cap for the appended history.
  * @returns Receipt and retained history; the caller publishes them only after task persistence.
  */
 export function appendDelivery(task, receipt, bounds) {
-    const history = deliveryHistoryOf(task);
+    const history = task.deliveryHistory;
     const appended = [...history.records, { ...receipt, prompt: task.record.prompt }];
     const floor = Date.parse(receipt.deliveredAt) - bounds.days * DAY_MS;
     const retained = appended
@@ -34,19 +21,19 @@ export function appendDelivery(task, receipt, bounds) {
         deliveryHistory: {
             records: retained,
             earlierRecordsUnavailable: history.earlierRecordsUnavailable || retained.length !== appended.length,
-            earlierRecordsPruned: history.earlierRecordsPruned === true || retained.length !== appended.length,
+            earlierRecordsPruned: history.earlierRecordsPruned || retained.length !== appended.length,
         },
     };
 }
 /**
  * Read one newest-first page in append order, independent of wall-clock ordering.
- * @param task - Task already checked against the requested Session binding.
+ * @param task - Task already selected by the caller.
  * @param request - Validated explicit page size and optional exclusive message cursor.
  * @param retention - Current configured limits shared with the delivery writer.
  * @returns Copied delivery records or a cursor-not-found result.
  */
 export function deliveryHistoryPage(task, request, retention) {
-    const history = deliveryHistoryOf(task);
+    const history = task.deliveryHistory;
     const end = request.before === undefined
         ? history.records.length
         : history.records.findIndex(record => record.messageId === request.before);
@@ -59,7 +46,7 @@ export function deliveryHistoryPage(task, request, retention) {
     const oldest = records.at(-1);
     return {
         id: request.id, records, earlierRecordsUnavailable: history.earlierRecordsUnavailable,
-        earlierRecordsPruned: history.earlierRecordsPruned === true, retention: { ...retention },
+        earlierRecordsPruned: history.earlierRecordsPruned, retention: { ...retention },
         ...(oldest !== undefined && start > 0 ? { nextBefore: oldest.messageId } : {}),
     };
 }

package/lib/types/domain.d.ts

@@ -1,26 +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 type { SessionEvent, SessionLogOffset as SessionLogOffsetType } from '@qilin-agent/session';
-import type { AfterScheduleRecord, AtInput, AtScheduleRecord, EveryScheduleRecord, CronInput, CronScheduleRecord, DailyInput, DailyScheduleRecord, WeeklyInput, WeeklyScheduleRecord, LegacyScheduleRecord, RecurringScheduleRecord, OneShotScheduleRecord, ScheduleChange, ScheduleId as ScheduleIdType, ScheduleRecord, ScheduleView } from './types.ts';
-/** Durable Schedule protocol version implemented by this package. */
-export declare const SCHEDULE_CHANGE_VERSION: 1;
-/** Fixed v1 lower bound for a fixed-rate reminder. */
+import type { AfterScheduleRecord, AtInput, AtScheduleRecord, EveryScheduleRecord, CronInput, CronScheduleRecord, DailyInput, DailyScheduleRecord, WeeklyInput, WeeklyScheduleRecord, RecurringScheduleRecord, ScheduleId as ScheduleIdType, ScheduleInputErrorCode } from './types.ts';
+import type { ScheduleRecord, RRuleScheduleRecord } from './types.ts';
+/** Minimum supported fixed-rate interval. */
 export declare const MIN_EVERY_INTERVAL_SECONDS = 60;
-/** Fixed v1 upper bound for a stored task title. */
+/** Maximum stored task title length. */
 export declare 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 declare const CRON_SEARCH_HORIZON_YEARS = 400;
 /** Error from malformed or transition-invalid durable Schedule data. */
 export declare class ScheduleLogError extends Error {
     /** Stable machine-readable error code. */
@@ -34,21 +22,14 @@ export declare class ScheduleLogError extends Error {
 /** Error from a model-supplied Schedule rule or target Session that cannot become a record. */
 export declare class ScheduleInputError extends Error {
     /** Stable public Schedule input code. */
-    readonly code: 'invalid_prompt' | 'invalid_selector' | 'invalid_rule' | 'invalid_time_zone' | 'not_future' | 'time_out_of_range' | 'frequency_too_high' | 'subagent_session';
+    readonly code: ScheduleInputErrorCode;
     /**
      * Construct a stable input failure.
      * @param code - Public Schedule error discriminator.
      * @param message - Stable public diagnostic.
      * @param options - Optional contained implementation cause.
      */
-    constructor(code: 'invalid_prompt' | 'invalid_selector' | 'invalid_rule' | 'invalid_time_zone' | 'not_future' | 'time_out_of_range' | 'frequency_too_high' | 'subagent_session', message: string, options?: ErrorOptions);
-}
-/** Pure replay result, retaining active create order and every used id. */
-export interface FoldedSchedules {
-    /** Active records in their original create order. */
-    readonly active: readonly LegacyScheduleRecord[];
-    /** Every id ever created in this session-local suffix. */
-    readonly seenIds: readonly ScheduleIdType[];
+    constructor(code: ScheduleInputErrorCode, message: string, options?: ErrorOptions);
 }
 /** One latest-only recurring decision derived without enumerating a backlog. */
 export interface RecurringOccurrence {
@@ -58,11 +39,24 @@ export interface RecurringOccurrence {
     readonly nextScheduledAt?: string;
 }
 /**
- * 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 declare function ScheduleId(value: string): ScheduleIdType;
+/**
+ * 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 declare function isRecord(value: unknown): value is Record<string, unknown>;
+/**
+ * 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 declare function hasExactKeys(value: Record<string, unknown>, expected: readonly string[]): boolean;
 /** Stable diagnostic for a title that is missing or empty after trimming. */
 export declare const REQUIRED_TITLE_MESSAGE = "title is required and must be non-empty after trimming.";
 /**
@@ -84,12 +78,31 @@ export declare function scheduleTitle(title: string): string;
  * @returns The stored title; an invalid title throws ScheduleLogError.
  */
 export declare function decodeStoredTitle(value: unknown): string;
+/**
+ * Validate one stable task id at the durable boundary.
+ * @param value - Untrusted durable id field.
+ * @returns The branded id; an invalid id throws ScheduleLogError.
+ */
+export declare function decodeId(value: unknown): ScheduleIdType;
+/**
+ * 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 declare function decodeInstant(value: unknown): string;
 /**
  * Validate and canonicalize one raw IANA time-zone selector.
  * @param value - Candidate `UTC` or IANA Area/Location name.
  * @returns The runtime's canonical IANA name.
  */
 export declare function canonicalizeTimeZone(value: string): string;
+/**
+ * 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 declare function futureInstant(epoch: number, now: number): string;
 /**
  * Parse one strict local clock time accepted by the weekly selector.
  * @param value - Candidate `HH:mm:ss` time with optional one-to-three fractional digits.
@@ -103,20 +116,11 @@ export declare function weeklyTime(value: string): Temporal.PlainTime;
  */
 export declare function normalizeWeekdays(weekdays: unknown): number[];
 /**
- * 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 declare function decodeScheduleRecord(value: unknown): ScheduleRecord;
-/**
- * Decode one strict version-1 `schedule/change` payload.
- * @param value - Untrusted durable JSON value.
- * @returns Detached, frozen Schedule change.
- */
-export declare function decodeScheduleChange(value: unknown): ScheduleChange;
 /** Timing fields one fixed-rate decision needs from its record. */
 type EveryOccurrenceInput = Pick<EveryScheduleRecord, 'everySeconds' | 'scheduledAt'>;
 /**
@@ -126,6 +130,13 @@ type EveryOccurrenceInput = Pick<EveryScheduleRecord, 'everySeconds' | 'schedule
  * @returns The latest due occurrence and first strictly future target, if representable.
  */
 export declare function resolveEveryOccurrence(record: EveryOccurrenceInput, acceptedAt: number): RecurringOccurrence;
+/**
+ * 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 declare function acceptedDecision(selector: string, acceptedAt: number): number;
 /**
  * Resolve a daily decision near the decision's local date, not across its missed history.
  * @param record - Daily rule with a committed earliest unaccepted UTC target.
@@ -141,10 +152,10 @@ export declare function resolveDailyOccurrence(record: DailyScheduleRecord, acce
  */
 export declare function resolveWeeklyOccurrence(record: WeeklyScheduleRecord, acceptedAt: number): RecurringOccurrence;
 /**
- * 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 declare function resolveCronOccurrence(record: CronScheduleRecord, acceptedAt: number): RecurringOccurrence;
 /**
@@ -160,29 +171,6 @@ export declare function isRecurringScheduleRecord(record: ScheduleRecord): recor
  * @returns Latest due occurrence and optional future target.
  */
 export declare function resolveRecurringOccurrence(record: RecurringScheduleRecord, acceptedAt: number): RecurringOccurrence;
-/**
- * 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 declare function applyScheduleChanges(folded: FoldedSchedules, changes: Iterable<ScheduleChange>): FoldedSchedules;
-/**
- * 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 declare function foldScheduleEvents(events: readonly SessionEvent[], inheritedEventCount?: SessionLogOffsetType): FoldedSchedules;
-/**
- * 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 declare function allocateScheduleId(folded: FoldedSchedules): ScheduleIdType;
 /**
  * Validate a model after rule and compute its durable target.
  * @param id - Already allocated task id.
@@ -269,9 +257,9 @@ export declare function parseWeeklyInput(weekly: WeeklyInput): {
     readonly weekdays: number[];
 };
 /**
- * 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 declare function canonicalizeCronExpression(expression: string): string;
 /**
@@ -284,26 +272,75 @@ export declare function parseCronInput(cron: CronInput): {
     readonly timeZone: string;
 };
 /**
- * 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 declare function scheduleView(record: ScheduleRecord, now: number): ScheduleView;
-/**
- * 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 declare function renderReminderFraming(record: OneShotScheduleRecord): string;
+export declare function renderReminderFraming(record: {
+    readonly id: ScheduleIdType;
+    readonly prompt: string;
+    readonly scheduledAt: string;
+}): string;
 /**
  * Render one recurring reminder batch in the supplied order.
  * @param reminders - Complete admitted batch with one latest occurrence per record.
  * @returns Stable model-visible text whose dynamic payload is canonical JSON.
  */
 export declare function renderRecurringReminderBatchFraming(reminders: readonly {
-    readonly record: RecurringScheduleRecord;
+    readonly record: {
+        readonly id: ScheduleIdType;
+        readonly prompt: string;
+    };
     readonly occurrenceAt: string;
 }[]): string;
+/**
+ * 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 declare function normalizeRRule(value: string): string;
+/**
+ * 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 declare function createRRuleScheduleRecord(id: ScheduleIdType, title: string, prompt: string, rrule: string, now: number): RRuleScheduleRecord;
+/**
+ * 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 declare function updateRRuleScheduleRecord(current: RRuleScheduleRecord, change: {
+    readonly title?: string;
+    readonly prompt?: string;
+    readonly rrule?: string;
+}, now: number, recompute: boolean): RRuleScheduleRecord;
+/**
+ * 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 declare function resolveRRuleOccurrence(record: RRuleScheduleRecord, acceptedAt: number): RecurringOccurrence;
+/**
+ * Decode a current Host task record.
+ * @param value - Untrusted durable JSON record.
+ * @returns Detached frozen record; malformed fields throw ScheduleLogError.
+ */
+export declare function decodeRRuleScheduleRecord(value: unknown): RRuleScheduleRecord;
+/**
+ * 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 declare function formatScheduleLocalTime(record: ScheduleRecord, instant: string): string;
 export {};
 //# sourceMappingURL=domain.d.ts.map