@kronos-ts/eventsourcing 0.1.5 → 0.2.1

package/dist/index.d.ts

@@ -12,5 +12,6 @@ export { type SnapshotPolicy, type EvolutionResult, afterEvents, whenSourcingTim
 export { type Snapshot, type SnapshotStore, createInMemorySnapshotStore, } from "./snapshot-store.js";
 export { createInterceptingEventStore } from "./intercepting-event-store.js";
 export { load, STATE_MANAGER_KEY } from "./load.js";
+export { schedule, scheduleAfter, cancelSchedule, EVENT_SCHEDULER_KEY, type ScheduleFunction, type ScheduleAfterFunction, } from "./schedule.js";
 export { append, BUFFERED_EVENTS_KEY, SOURCING_INFOS_KEY, STATE_CACHE_KEY, STATE_MODULES_KEY, } from "./append.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,KAAK,iBAAiB,EACtB,MAAM,EACN,QAAQ,EACR,mBAAmB,EACnB,QAAQ,EACR,QAAQ,EACR,gBAAgB,EAChB,gBAAgB,GACjB,MAAM,yBAAyB,CAAA;AAEhC,OAAO,EACL,KAAK,iBAAiB,EACtB,iBAAiB,GAClB,MAAM,yBAAyB,CAAA;AAEhC,OAAO,EACL,KAAK,eAAe,EACpB,eAAe,GAChB,MAAM,uBAAuB,CAAA;AAE9B,OAAO,EACL,KAAK,UAAU,EACf,KAAK,cAAc,GACpB,MAAM,kBAAkB,CAAA;AAEzB,OAAO,EACL,KAAK,qBAAqB,EAC1B,2BAA2B,GAC5B,MAAM,8BAA8B,CAAA;AAErC,OAAO,EACL,wBAAwB,EACxB,oBAAoB,GACrB,MAAM,4BAA4B,CAAA;AAEnC,OAAO,EAAE,KAAK,kBAAkB,EAAE,KAAK,iBAAiB,EAAE,MAAM,2BAA2B,CAAA;AAE3F,OAAO,EACL,KAAK,WAAW,EAChB,0BAA0B,EAC1B,wBAAwB,EACxB,gBAAgB,GACjB,MAAM,mBAAmB,CAAA;AAE1B,OAAO,EAAE,4BAA4B,EAAE,MAAM,+BAA+B,CAAA;AAC5E,YAAY,EAAE,6BAA6B,EAAE,MAAM,+BAA+B,CAAA;AAElF,OAAO,EACL,KAAK,cAAc,EACnB,KAAK,eAAe,EACpB,WAAW,EACX,uBAAuB,EACvB,gBAAgB,GACjB,MAAM,sBAAsB,CAAA;AAE7B,OAAO,EACL,KAAK,QAAQ,EACb,KAAK,aAAa,EAClB,2BAA2B,GAC5B,MAAM,qBAAqB,CAAA;AAE5B,OAAO,EAAE,4BAA4B,EAAE,MAAM,+BAA+B,CAAA;AAG5E,OAAO,EAAE,IAAI,EAAE,iBAAiB,EAAE,MAAM,WAAW,CAAA;AACnD,OAAO,EACL,MAAM,EACN,mBAAmB,EACnB,kBAAkB,EAClB,eAAe,EACf,iBAAiB,GAClB,MAAM,aAAa,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,KAAK,iBAAiB,EACtB,MAAM,EACN,QAAQ,EACR,mBAAmB,EACnB,QAAQ,EACR,QAAQ,EACR,gBAAgB,EAChB,gBAAgB,GACjB,MAAM,yBAAyB,CAAA;AAEhC,OAAO,EACL,KAAK,iBAAiB,EACtB,iBAAiB,GAClB,MAAM,yBAAyB,CAAA;AAEhC,OAAO,EACL,KAAK,eAAe,EACpB,eAAe,GAChB,MAAM,uBAAuB,CAAA;AAE9B,OAAO,EACL,KAAK,UAAU,EACf,KAAK,cAAc,GACpB,MAAM,kBAAkB,CAAA;AAEzB,OAAO,EACL,KAAK,qBAAqB,EAC1B,2BAA2B,GAC5B,MAAM,8BAA8B,CAAA;AAErC,OAAO,EACL,wBAAwB,EACxB,oBAAoB,GACrB,MAAM,4BAA4B,CAAA;AAEnC,OAAO,EAAE,KAAK,kBAAkB,EAAE,KAAK,iBAAiB,EAAE,MAAM,2BAA2B,CAAA;AAE3F,OAAO,EACL,KAAK,WAAW,EAChB,0BAA0B,EAC1B,wBAAwB,EACxB,gBAAgB,GACjB,MAAM,mBAAmB,CAAA;AAE1B,OAAO,EAAE,4BAA4B,EAAE,MAAM,+BAA+B,CAAA;AAC5E,YAAY,EAAE,6BAA6B,EAAE,MAAM,+BAA+B,CAAA;AAElF,OAAO,EACL,KAAK,cAAc,EACnB,KAAK,eAAe,EACpB,WAAW,EACX,uBAAuB,EACvB,gBAAgB,GACjB,MAAM,sBAAsB,CAAA;AAE7B,OAAO,EACL,KAAK,QAAQ,EACb,KAAK,aAAa,EAClB,2BAA2B,GAC5B,MAAM,qBAAqB,CAAA;AAE5B,OAAO,EAAE,4BAA4B,EAAE,MAAM,+BAA+B,CAAA;AAG5E,OAAO,EAAE,IAAI,EAAE,iBAAiB,EAAE,MAAM,WAAW,CAAA;AACnD,OAAO,EACL,QAAQ,EACR,aAAa,EACb,cAAc,EACd,mBAAmB,EACnB,KAAK,gBAAgB,EACrB,KAAK,qBAAqB,GAC3B,MAAM,eAAe,CAAA;AACtB,OAAO,EACL,MAAM,EACN,mBAAmB,EACnB,kBAAkB,EAClB,eAAe,EACf,iBAAiB,GAClB,MAAM,aAAa,CAAA"}

package/dist/index.js

@@ -12,5 +12,6 @@ export { createInMemorySnapshotStore, } from "./snapshot-store.js";
 export { createInterceptingEventStore } from "./intercepting-event-store.js";
 // Module-level handler helpers (Plan 04-01 / HDL-02 / D-42)
 export { load, STATE_MANAGER_KEY } from "./load.js";
+export { schedule, scheduleAfter, cancelSchedule, EVENT_SCHEDULER_KEY, } from "./schedule.js";
 export { append, BUFFERED_EVENTS_KEY, SOURCING_INFOS_KEY, STATE_CACHE_KEY, STATE_MODULES_KEY, } from "./append.js";
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,MAAM,EACN,QAAQ,EACR,mBAAmB,EACnB,QAAQ,EACR,QAAQ,EACR,gBAAgB,EAChB,gBAAgB,GACjB,MAAM,yBAAyB,CAAA;AAEhC,OAAO,EAEL,iBAAiB,GAClB,MAAM,yBAAyB,CAAA;AAEhC,OAAO,EAEL,eAAe,GAChB,MAAM,uBAAuB,CAAA;AAE9B,OAAO,EAGN,MAAM,kBAAkB,CAAA;AAEzB,OAAO,EAEL,2BAA2B,GAC5B,MAAM,8BAA8B,CAAA;AAErC,OAAO,EACL,wBAAwB,EACxB,oBAAoB,GACrB,MAAM,4BAA4B,CAAA;AAEnC,OAAO,EAAmD,MAAM,2BAA2B,CAAA;AAE3F,OAAO,EAEL,0BAA0B,EAC1B,wBAAwB,EACxB,gBAAgB,GACjB,MAAM,mBAAmB,CAAA;AAE1B,OAAO,EAAE,4BAA4B,EAAE,MAAM,+BAA+B,CAAA;AAG5E,OAAO,EAGL,WAAW,EACX,uBAAuB,EACvB,gBAAgB,GACjB,MAAM,sBAAsB,CAAA;AAE7B,OAAO,EAGL,2BAA2B,GAC5B,MAAM,qBAAqB,CAAA;AAE5B,OAAO,EAAE,4BAA4B,EAAE,MAAM,+BAA+B,CAAA;AAE5E,4DAA4D;AAC5D,OAAO,EAAE,IAAI,EAAE,iBAAiB,EAAE,MAAM,WAAW,CAAA;AACnD,OAAO,EACL,MAAM,EACN,mBAAmB,EACnB,kBAAkB,EAClB,eAAe,EACf,iBAAiB,GAClB,MAAM,aAAa,CAAA"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,MAAM,EACN,QAAQ,EACR,mBAAmB,EACnB,QAAQ,EACR,QAAQ,EACR,gBAAgB,EAChB,gBAAgB,GACjB,MAAM,yBAAyB,CAAA;AAEhC,OAAO,EAEL,iBAAiB,GAClB,MAAM,yBAAyB,CAAA;AAEhC,OAAO,EAEL,eAAe,GAChB,MAAM,uBAAuB,CAAA;AAE9B,OAAO,EAGN,MAAM,kBAAkB,CAAA;AAEzB,OAAO,EAEL,2BAA2B,GAC5B,MAAM,8BAA8B,CAAA;AAErC,OAAO,EACL,wBAAwB,EACxB,oBAAoB,GACrB,MAAM,4BAA4B,CAAA;AAEnC,OAAO,EAAmD,MAAM,2BAA2B,CAAA;AAE3F,OAAO,EAEL,0BAA0B,EAC1B,wBAAwB,EACxB,gBAAgB,GACjB,MAAM,mBAAmB,CAAA;AAE1B,OAAO,EAAE,4BAA4B,EAAE,MAAM,+BAA+B,CAAA;AAG5E,OAAO,EAGL,WAAW,EACX,uBAAuB,EACvB,gBAAgB,GACjB,MAAM,sBAAsB,CAAA;AAE7B,OAAO,EAGL,2BAA2B,GAC5B,MAAM,qBAAqB,CAAA;AAE5B,OAAO,EAAE,4BAA4B,EAAE,MAAM,+BAA+B,CAAA;AAE5E,4DAA4D;AAC5D,OAAO,EAAE,IAAI,EAAE,iBAAiB,EAAE,MAAM,WAAW,CAAA;AACnD,OAAO,EACL,QAAQ,EACR,aAAa,EACb,cAAc,EACd,mBAAmB,GAGpB,MAAM,eAAe,CAAA;AACtB,OAAO,EACL,MAAM,EACN,mBAAmB,EACnB,kBAAkB,EAClB,eAAe,EACf,iBAAiB,GAClB,MAAM,aAAa,CAAA"}

package/dist/schedule.d.ts

@@ -0,0 +1,50 @@
+import { type Metadata, type ResourceKey } from "@kronos-ts/common";
+import type { z } from "zod";
+import type { EventDescriptor, EventScheduler, ScheduleToken, CancelResult } from "@kronos-ts/messaging";
+/**
+ * Resource key for the event scheduler component.
+ * Written by handling modules + processors at handler-invocation entry,
+ * exactly like {@link STATE_MANAGER_KEY} — so the {@link schedule} helper
+ * resolves the framework-configured scheduler from the active UnitOfWork.
+ */
+export declare const EVENT_SCHEDULER_KEY: ResourceKey<EventScheduler>;
+/** Schedule an event for future append from inside a handler. */
+export interface ScheduleFunction {
+    <P extends z.ZodType>(event: EventDescriptor<P>, payload: z.infer<P>, at: Date): Promise<ScheduleToken>;
+    <P extends z.ZodType>(event: EventDescriptor<P>, payload: z.infer<P>, at: Date, metadata: Metadata): Promise<ScheduleToken>;
+}
+/**
+ * Schedule {@link event} to be appended at {@link at}.
+ *
+ * The same one-call ergonomics as {@link append}/{@link send}: pass the event
+ * descriptor + payload and the helper builds the {@link EventMessage} (tags,
+ * metadata, identifier) and hands it to the configured {@link EventScheduler}.
+ * No need to fetch the scheduler or construct a message by hand.
+ *
+ * Must be called from inside a UnitOfWork (throws otherwise). The schedule
+ * participates in the active transaction — if the handler's UoW rolls back,
+ * nothing is scheduled; if it commits, the event is durably scheduled and will
+ * fire at or after `at` unless cancelled. Metadata defaults to the UoW
+ * metadata, so correlation/causation lineage carries onto the fired event.
+ *
+ * Returns a {@link ScheduleToken} — persist it (e.g. in state via an event) to
+ * {@link cancelSchedule} later. That is the deadline/process-manager pattern.
+ */
+export declare const schedule: ScheduleFunction;
+/** Schedule an event a fixed delay from now, from inside a handler. */
+export interface ScheduleAfterFunction {
+    <P extends z.ZodType>(event: EventDescriptor<P>, payload: z.infer<P>, delayMs: number): Promise<ScheduleToken>;
+    <P extends z.ZodType>(event: EventDescriptor<P>, payload: z.infer<P>, delayMs: number, metadata: Metadata): Promise<ScheduleToken>;
+}
+/**
+ * Convenience wrapper over {@link schedule}: fire `delayMs` milliseconds from
+ * now instead of at an absolute {@link Date}.
+ */
+export declare const scheduleAfter: ScheduleAfterFunction;
+/**
+ * Attempt to cancel a previously {@link schedule}d event from inside a handler.
+ * UoW-aware: joins the active transaction, so cancelling then throwing does not
+ * leave the schedule cancelled. See {@link CancelResult} for outcomes.
+ */
+export declare const cancelSchedule: (token: ScheduleToken) => Promise<CancelResult>;
+//# sourceMappingURL=schedule.d.ts.map

package/dist/schedule.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"schedule.d.ts","sourceRoot":"","sources":["../src/schedule.ts"],"names":[],"mappings":"AAAA,OAAO,EAAsB,KAAK,QAAQ,EAAe,KAAK,WAAW,EAAE,MAAM,mBAAmB,CAAA;AAEpG,OAAO,KAAK,EAAE,CAAC,EAAE,MAAM,KAAK,CAAA;AAC5B,OAAO,KAAK,EACV,eAAe,EAEf,cAAc,EACd,aAAa,EACb,YAAY,EACb,MAAM,sBAAsB,CAAA;AAE7B;;;;;GAKG;AACH,eAAO,MAAM,mBAAmB,EAAE,WAAW,CAAC,cAAc,CAAiC,CAAA;AAE7F,iEAAiE;AACjE,MAAM,WAAW,gBAAgB;IAC/B,CAAC,CAAC,SAAS,CAAC,CAAC,OAAO,EAAE,KAAK,EAAE,eAAe,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,EAAE,EAAE,IAAI,GAAG,OAAO,CAAC,aAAa,CAAC,CAAA;IACvG,CAAC,CAAC,SAAS,CAAC,CAAC,OAAO,EAClB,KAAK,EAAE,eAAe,CAAC,CAAC,CAAC,EACzB,OAAO,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,EACnB,EAAE,EAAE,IAAI,EACR,QAAQ,EAAE,QAAQ,GACjB,OAAO,CAAC,aAAa,CAAC,CAAA;CAC1B;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,QAAQ,EAAE,gBA6BD,CAAA;AAEtB,uEAAuE;AACvE,MAAM,WAAW,qBAAqB;IACpC,CAAC,CAAC,SAAS,CAAC,CAAC,OAAO,EAAE,KAAK,EAAE,eAAe,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,CAAC,CAAA;IAC9G,CAAC,CAAC,SAAS,CAAC,CAAC,OAAO,EAClB,KAAK,EAAE,eAAe,CAAC,CAAC,CAAC,EACzB,OAAO,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,EACnB,OAAO,EAAE,MAAM,EACf,QAAQ,EAAE,QAAQ,GACjB,OAAO,CAAC,aAAa,CAAC,CAAA;CAC1B;AAED;;;GAGG;AACH,eAAO,MAAM,aAAa,EAAE,qBAaD,CAAA;AAE3B;;;;GAIG;AACH,eAAO,MAAM,cAAc,GAAU,OAAO,aAAa,KAAG,OAAO,CAAC,YAAY,CAK/E,CAAA"}

package/dist/schedule.js

@@ -0,0 +1,76 @@
+import { generateIdentifier, resourceKey } from "@kronos-ts/common";
+import { requireInvocationPhase } from "@kronos-ts/messaging/processing-state";
+/**
+ * Resource key for the event scheduler component.
+ * Written by handling modules + processors at handler-invocation entry,
+ * exactly like {@link STATE_MANAGER_KEY} — so the {@link schedule} helper
+ * resolves the framework-configured scheduler from the active UnitOfWork.
+ */
+export const EVENT_SCHEDULER_KEY = resourceKey("eventScheduler");
+/**
+ * Schedule {@link event} to be appended at {@link at}.
+ *
+ * The same one-call ergonomics as {@link append}/{@link send}: pass the event
+ * descriptor + payload and the helper builds the {@link EventMessage} (tags,
+ * metadata, identifier) and hands it to the configured {@link EventScheduler}.
+ * No need to fetch the scheduler or construct a message by hand.
+ *
+ * Must be called from inside a UnitOfWork (throws otherwise). The schedule
+ * participates in the active transaction — if the handler's UoW rolls back,
+ * nothing is scheduled; if it commits, the event is durably scheduled and will
+ * fire at or after `at` unless cancelled. Metadata defaults to the UoW
+ * metadata, so correlation/causation lineage carries onto the fired event.
+ *
+ * Returns a {@link ScheduleToken} — persist it (e.g. in state via an event) to
+ * {@link cancelSchedule} later. That is the deadline/process-manager pattern.
+ */
+export const schedule = (async (event, payload, at, metadata) => {
+    const state = requireInvocationPhase(); // D-43 mutator guard
+    const scheduler = state.resources.get(EVENT_SCHEDULER_KEY.symbol);
+    if (!scheduler)
+        throw new Error("No event scheduler configured");
+    // Reject malformed fire times. A past-but-valid `at` is allowed — it fires
+    // ASAP, which is the intended deadline semantic — but an Invalid Date is a
+    // caller bug that otherwise behaves inconsistently across schedulers (the
+    // in-memory one fires immediately; the postgres one throws on toISOString at
+    // insert time). Fail fast and uniformly here instead.
+    if (!(at instanceof Date) || Number.isNaN(at.getTime())) {
+        throw new Error(`schedule: \`at\` must be a valid Date, received ${String(at)}`);
+    }
+    const eventMessage = {
+        identifier: generateIdentifier(),
+        name: event.name,
+        version: event.version,
+        payload,
+        metadata: metadata ?? state.metadata,
+        timestamp: Date.now(),
+        tags: event.tags ? event.tags(payload) : [],
+    };
+    return scheduler.schedule(eventMessage, at);
+});
+/**
+ * Convenience wrapper over {@link schedule}: fire `delayMs` milliseconds from
+ * now instead of at an absolute {@link Date}.
+ */
+export const scheduleAfter = (async (event, payload, delayMs, metadata) => {
+    // A non-finite delay (NaN/Infinity) would produce an Invalid Date; reject it
+    // here so the error names the actual offending argument. A negative delay is
+    // allowed — it resolves to a past time and fires ASAP.
+    if (!Number.isFinite(delayMs)) {
+        throw new Error(`scheduleAfter: \`delayMs\` must be a finite number, received ${String(delayMs)}`);
+    }
+    return schedule(event, payload, new Date(Date.now() + delayMs), metadata);
+});
+/**
+ * Attempt to cancel a previously {@link schedule}d event from inside a handler.
+ * UoW-aware: joins the active transaction, so cancelling then throwing does not
+ * leave the schedule cancelled. See {@link CancelResult} for outcomes.
+ */
+export const cancelSchedule = async (token) => {
+    const state = requireInvocationPhase(); // D-43 mutator guard
+    const scheduler = state.resources.get(EVENT_SCHEDULER_KEY.symbol);
+    if (!scheduler)
+        throw new Error("No event scheduler configured");
+    return scheduler.cancel(token);
+};
+//# sourceMappingURL=schedule.js.map

package/dist/schedule.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"schedule.js","sourceRoot":"","sources":["../src/schedule.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,kBAAkB,EAAiB,WAAW,EAAoB,MAAM,mBAAmB,CAAA;AACpG,OAAO,EAAE,sBAAsB,EAAE,MAAM,uCAAuC,CAAA;AAU9E;;;;;GAKG;AACH,MAAM,CAAC,MAAM,mBAAmB,GAAgC,WAAW,CAAC,gBAAgB,CAAC,CAAA;AAa7F;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,CAAC,MAAM,QAAQ,GAAqB,CAAC,KAAK,EAC9C,KAAyB,EACzB,OAAmB,EACnB,EAAQ,EACR,QAAmB,EACK,EAAE;IAC1B,MAAM,KAAK,GAAG,sBAAsB,EAAE,CAAA,CAAC,qBAAqB;IAC5D,MAAM,SAAS,GAAG,KAAK,CAAC,SAAS,CAAC,GAAG,CAAC,mBAAmB,CAAC,MAAM,CAA+B,CAAA;IAC/F,IAAI,CAAC,SAAS;QAAE,MAAM,IAAI,KAAK,CAAC,+BAA+B,CAAC,CAAA;IAEhE,2EAA2E;IAC3E,2EAA2E;IAC3E,0EAA0E;IAC1E,6EAA6E;IAC7E,sDAAsD;IACtD,IAAI,CAAC,CAAC,EAAE,YAAY,IAAI,CAAC,IAAI,MAAM,CAAC,KAAK,CAAC,EAAE,CAAC,OAAO,EAAE,CAAC,EAAE,CAAC;QACxD,MAAM,IAAI,KAAK,CAAC,mDAAmD,MAAM,CAAC,EAAE,CAAC,EAAE,CAAC,CAAA;IAClF,CAAC;IAED,MAAM,YAAY,GAAiB;QACjC,UAAU,EAAE,kBAAkB,EAAE;QAChC,IAAI,EAAE,KAAK,CAAC,IAAI;QAChB,OAAO,EAAE,KAAK,CAAC,OAAO;QACtB,OAAO;QACP,QAAQ,EAAE,QAAQ,IAAI,KAAK,CAAC,QAAQ;QACpC,SAAS,EAAE,IAAI,CAAC,GAAG,EAAE;QACrB,IAAI,EAAE,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,EAAE;KAC5C,CAAA;IACD,OAAO,SAAS,CAAC,QAAQ,CAAC,YAAY,EAAE,EAAE,CAAC,CAAA;AAC7C,CAAC,CAAqB,CAAA;AAatB;;;GAGG;AACH,MAAM,CAAC,MAAM,aAAa,GAA0B,CAAC,KAAK,EACxD,KAA2B,EAC3B,OAAgB,EAChB,OAAe,EACf,QAAmB,EACnB,EAAE;IACF,6EAA6E;IAC7E,6EAA6E;IAC7E,uDAAuD;IACvD,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,OAAO,CAAC,EAAE,CAAC;QAC9B,MAAM,IAAI,KAAK,CAAC,gEAAgE,MAAM,CAAC,OAAO,CAAC,EAAE,CAAC,CAAA;IACpG,CAAC;IACD,OAAO,QAAQ,CAAC,KAAK,EAAE,OAAO,EAAE,IAAI,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,GAAG,OAAO,CAAC,EAAE,QAAoB,CAAC,CAAA;AACvF,CAAC,CAA0B,CAAA;AAE3B;;;;GAIG;AACH,MAAM,CAAC,MAAM,cAAc,GAAG,KAAK,EAAE,KAAoB,EAAyB,EAAE;IAClF,MAAM,KAAK,GAAG,sBAAsB,EAAE,CAAA,CAAC,qBAAqB;IAC5D,MAAM,SAAS,GAAG,KAAK,CAAC,SAAS,CAAC,GAAG,CAAC,mBAAmB,CAAC,MAAM,CAA+B,CAAA;IAC/F,IAAI,CAAC,SAAS;QAAE,MAAM,IAAI,KAAK,CAAC,+BAA+B,CAAC,CAAA;IAChE,OAAO,SAAS,CAAC,MAAM,CAAC,KAAK,CAAC,CAAA;AAChC,CAAC,CAAA"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kronos-ts/eventsourcing",
-  "version": "0.1.5",
+  "version": "0.2.1",
   "description": "Event sourcing for Kronos — dynamic-consistency-boundary event store with load/append.",
   "license": "Apache-2.0",
   "type": "module",
@@ -48,11 +48,11 @@
   },
   "dependencies": {
     "@kronos-ts/common": "0.1.1",
-    "@kronos-ts/messaging": "0.4.0",
-    "@kronos-ts/modelling": "0.2.2",
+    "@kronos-ts/messaging": "0.5.1",
+    "@kronos-ts/modelling": "0.2.4",
     "zod": "^4.3.6"
   },
   "devDependencies": {
-    "@kronos-ts/app": "0.3.2"
+    "@kronos-ts/app": "0.3.4"
   }
 }

package/src/index.ts

@@ -64,6 +64,14 @@ export { createInterceptingEventStore } from "./intercepting-event-store.js"
 
 // Module-level handler helpers (Plan 04-01 / HDL-02 / D-42)
 export { load, STATE_MANAGER_KEY } from "./load.js"
+export {
+  schedule,
+  scheduleAfter,
+  cancelSchedule,
+  EVENT_SCHEDULER_KEY,
+  type ScheduleFunction,
+  type ScheduleAfterFunction,
+} from "./schedule.js"
 export {
   append,
   BUFFERED_EVENTS_KEY,

package/src/schedule.ts

@@ -0,0 +1,119 @@
+import { generateIdentifier, type Metadata, resourceKey, type ResourceKey } from "@kronos-ts/common"
+import { requireInvocationPhase } from "@kronos-ts/messaging/processing-state"
+import type { z } from "zod"
+import type {
+  EventDescriptor,
+  EventMessage,
+  EventScheduler,
+  ScheduleToken,
+  CancelResult,
+} from "@kronos-ts/messaging"
+
+/**
+ * Resource key for the event scheduler component.
+ * Written by handling modules + processors at handler-invocation entry,
+ * exactly like {@link STATE_MANAGER_KEY} — so the {@link schedule} helper
+ * resolves the framework-configured scheduler from the active UnitOfWork.
+ */
+export const EVENT_SCHEDULER_KEY: ResourceKey<EventScheduler> = resourceKey("eventScheduler")
+
+/** Schedule an event for future append from inside a handler. */
+export interface ScheduleFunction {
+  <P extends z.ZodType>(event: EventDescriptor<P>, payload: z.infer<P>, at: Date): Promise<ScheduleToken>
+  <P extends z.ZodType>(
+    event: EventDescriptor<P>,
+    payload: z.infer<P>,
+    at: Date,
+    metadata: Metadata,
+  ): Promise<ScheduleToken>
+}
+
+/**
+ * Schedule {@link event} to be appended at {@link at}.
+ *
+ * The same one-call ergonomics as {@link append}/{@link send}: pass the event
+ * descriptor + payload and the helper builds the {@link EventMessage} (tags,
+ * metadata, identifier) and hands it to the configured {@link EventScheduler}.
+ * No need to fetch the scheduler or construct a message by hand.
+ *
+ * Must be called from inside a UnitOfWork (throws otherwise). The schedule
+ * participates in the active transaction — if the handler's UoW rolls back,
+ * nothing is scheduled; if it commits, the event is durably scheduled and will
+ * fire at or after `at` unless cancelled. Metadata defaults to the UoW
+ * metadata, so correlation/causation lineage carries onto the fired event.
+ *
+ * Returns a {@link ScheduleToken} — persist it (e.g. in state via an event) to
+ * {@link cancelSchedule} later. That is the deadline/process-manager pattern.
+ */
+export const schedule: ScheduleFunction = (async <P extends z.ZodType>(
+  event: EventDescriptor<P>,
+  payload: z.infer<P>,
+  at: Date,
+  metadata?: Metadata,
+): Promise<ScheduleToken> => {
+  const state = requireInvocationPhase() // D-43 mutator guard
+  const scheduler = state.resources.get(EVENT_SCHEDULER_KEY.symbol) as EventScheduler | undefined
+  if (!scheduler) throw new Error("No event scheduler configured")
+
+  // Reject malformed fire times. A past-but-valid `at` is allowed — it fires
+  // ASAP, which is the intended deadline semantic — but an Invalid Date is a
+  // caller bug that otherwise behaves inconsistently across schedulers (the
+  // in-memory one fires immediately; the postgres one throws on toISOString at
+  // insert time). Fail fast and uniformly here instead.
+  if (!(at instanceof Date) || Number.isNaN(at.getTime())) {
+    throw new Error(`schedule: \`at\` must be a valid Date, received ${String(at)}`)
+  }
+
+  const eventMessage: EventMessage = {
+    identifier: generateIdentifier(),
+    name: event.name,
+    version: event.version,
+    payload,
+    metadata: metadata ?? state.metadata,
+    timestamp: Date.now(),
+    tags: event.tags ? event.tags(payload) : [],
+  }
+  return scheduler.schedule(eventMessage, at)
+}) as ScheduleFunction
+
+/** Schedule an event a fixed delay from now, from inside a handler. */
+export interface ScheduleAfterFunction {
+  <P extends z.ZodType>(event: EventDescriptor<P>, payload: z.infer<P>, delayMs: number): Promise<ScheduleToken>
+  <P extends z.ZodType>(
+    event: EventDescriptor<P>,
+    payload: z.infer<P>,
+    delayMs: number,
+    metadata: Metadata,
+  ): Promise<ScheduleToken>
+}
+
+/**
+ * Convenience wrapper over {@link schedule}: fire `delayMs` milliseconds from
+ * now instead of at an absolute {@link Date}.
+ */
+export const scheduleAfter: ScheduleAfterFunction = (async (
+  event: EventDescriptor<any>,
+  payload: unknown,
+  delayMs: number,
+  metadata?: Metadata,
+) => {
+  // A non-finite delay (NaN/Infinity) would produce an Invalid Date; reject it
+  // here so the error names the actual offending argument. A negative delay is
+  // allowed — it resolves to a past time and fires ASAP.
+  if (!Number.isFinite(delayMs)) {
+    throw new Error(`scheduleAfter: \`delayMs\` must be a finite number, received ${String(delayMs)}`)
+  }
+  return schedule(event, payload, new Date(Date.now() + delayMs), metadata as Metadata)
+}) as ScheduleAfterFunction
+
+/**
+ * Attempt to cancel a previously {@link schedule}d event from inside a handler.
+ * UoW-aware: joins the active transaction, so cancelling then throwing does not
+ * leave the schedule cancelled. See {@link CancelResult} for outcomes.
+ */
+export const cancelSchedule = async (token: ScheduleToken): Promise<CancelResult> => {
+  const state = requireInvocationPhase() // D-43 mutator guard
+  const scheduler = state.resources.get(EVENT_SCHEDULER_KEY.symbol) as EventScheduler | undefined
+  if (!scheduler) throw new Error("No event scheduler configured")
+  return scheduler.cancel(token)
+}