@reventlessdev/reventless-spec 3.0.0-alpha.163 → 3.0.0-alpha.165

package/CHANGELOG.md

@@ -3,6 +3,39 @@
 All notable changes to this project will be documented in this file.
 See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
 
+# 3.0.0-alpha.165 (2026-10-16)
+
+* feat!(automation): schedules set by events ([53bc436](https://github.com/ReventlessDev/reventless-core/commit/53bc4363dffce81ef36475728bf0dae704716021))
+* feat!(automation): declared schedules tick an automation ([420acd2](https://github.com/ReventlessDev/reventless-core/commit/420acd2233aadf700141a31d9d3e0fdc8074bef7))
+
+### BREAKING CHANGES
+
+* a hand-written AutomationSlice.Mapping.Make the PPX does
+not see must define `let reschedule = _ => []`.
+* a hand-written AutomationSlice spec the PPX does not see must
+declare `let schedule = None`.
+
+
+
+# 3.0.0-alpha.164 (2026-10-15)
+
+### Bug Fixes
+
+* **spec:** generate-plugin writes Plugin.res as the formatter prints it ([3fcfd2b](https://github.com/ReventlessDev/reventless-core/commit/3fcfd2b38632bb9550413f88f410766934b6f609))
+* feat!: an automation's process takes ~now, and collect the event's recorded time ([8c8f3f5](https://github.com/ReventlessDev/reventless-core/commit/8c8f3f570474b1658b605b726077debc7d6a1dc7))
+* feat!: schedules take a Schedule.time, run on EventBridge Scheduler on AWS ([2d74557](https://github.com/ReventlessDev/reventless-core/commit/2d74557a6304917ded8f2b9f4107af9298c91ac0))
+
+### BREAKING CHANGES
+
+* a process the PPX does not see — in an Automation module
+written by hand, or a SliceSpec given to the deprecated Automation_GWT.Make
+or Flow_GWT.AutomationStep — must take ~now.
+* Schedule.rate is replaced by Schedule.time, and a
+schedule's `rate` field is now `time`. A once-only time already past
+never fires, locally as on AWS.
+
+
+
 # 3.0.0-alpha.163 (2026-10-12)
 
 **Note:** Version bump only for package @reventlessdev/reventless-spec

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@reventlessdev/reventless-spec",
-  "version": "3.0.0-alpha.163",
+  "version": "3.0.0-alpha.165",
   "description": "Specifications for Reventless",
   "license": "Apache-2.0",
   "bin": {

package/schema/platform-api.graphql

@@ -47,6 +47,7 @@ type Platform_AutomationSliceDef {
   consumedEventTypes: [String!]!
   name: String!
   producedCommandTypes: [String!]!
+  schedule: String
   targetName: String
 }
 

package/src/components/AutomationSlice.res

@@ -72,6 +72,14 @@ module type Spec = {
 
   /** Name of the aggregate or StateChangeSlice that receives the produced command. */
   let targetName: string
+
+  /**
+  The time this automation runs on, or `None` for one started by events only. A
+  declared time is the slice's schedule under `Clock.defaultKey`; each time it comes,
+  the slice's `Clock` mapping receives a `Tick`. The `@@reventless.spec` PPX injects
+  `None` when the spec declares none.
+  */
+  let schedule: option<Schedule.time>
 }
 
 // ── Plan 04: Mixed-source mappings ───────────────────────────────────────────
@@ -111,8 +119,23 @@ type context = {
   platformName: string,
   pluginName: string,
   sliceName: string,
+  /** When the source event was recorded, in milliseconds since 1970 (UTC): what a
+      due time is counted from. The runtime sets it for every event it delivers;
+      it is absent only in a context built by hand. */
+  recordedAt?: float,
 }
 
+/**
+What an event does to one of the slice's schedules. `key` names the schedule:
+`Clock.defaultKey` for the slice-wide one (replacing a declared time), or an id for a
+time per entity, which the tick carries back to `collect`. `Set` replaces the key's
+time, the last one winning; `Clear` of a key with no schedule does nothing. An
+`After` is counted from when the event was recorded.
+*/
+type scheduleChange =
+  | Set({key: string, time: Schedule.time})
+  | Clear({key: string})
+
 /**
 A compiled per-source-to-AutomationSlice mapping.
 
@@ -144,6 +167,9 @@ module type Mapping = {
   */
   let collect: (sourceEvent, ~sourceId: string, context) => array<(string, todoItem)>
   let resolve: sourceEvent => option<string>
+  /** The schedules the event sets or clears. The `@@reventless.automation` PPX adds
+      `let reschedule = _ => []` to a mapping written without it. */
+  let reschedule: sourceEvent => array<scheduleChange>
 }
 
 /**
@@ -166,9 +192,14 @@ module type Automation = {
   /**
   Process: given a pending TODO item, produce a command.
   The processor calls this for each pending item. Returns the target ID and command.
-  May return `None` to skip processing (e.g., wait for more data).
+  May return `None` to skip processing (e.g., wait for more data, or a due time
+  not yet reached); the item stays pending and the sweep offers it again.
+
+  `~now` is the current time in milliseconds since 1970 (UTC), from Effect's
+  `Clock`, so a test can fix it. The `@@reventless.automation` PPX adds `~now as _`
+  to a `process` written without it.
   */
-  let process: (string, Spec.todoItem) => option<(string, Spec.command)>
+  let process: (string, Spec.todoItem, ~now: float) => option<(string, Spec.command)>
 
   /**
   The retry budget is spent: this item will never be processed again.
@@ -224,6 +255,9 @@ module type MappingImpl = {
   */
   let collect: (sourceEvent, ~sourceId: string, context) => array<(string, todoItem)>
   let resolve: sourceEvent => option<string>
+  /** The schedules the event sets or clears. The `@@reventless.automation` PPX adds
+      `let reschedule = _ => []` to a mapping written without it. */
+  let reschedule: sourceEvent => array<scheduleChange>
 }
 
 /**
@@ -305,6 +339,7 @@ module Mapping = {
     let sourceName = Source.name
     let collect = Impl.collect
     let resolve = Impl.resolve
+    let reschedule = Impl.reschedule
   }
 }
 

package/src/components/AutomationSlice.res.mjs

@@ -7,7 +7,8 @@ function Make(Source) {
     sourceEventSchema: Source.eventSchema,
     sourceName: Source.name,
     collect: Impl.collect,
-    resolve: Impl.resolve
+    resolve: Impl.resolve,
+    reschedule: Impl.reschedule
   }));
 }
 

package/src/components/Clock.res

@@ -0,0 +1,38 @@
+/**
+The framework source a scheduled automation maps. When one of the slice's
+schedules comes due, the platform's Scheduler fires and the slice receives
+`Tick({key, at})`: which of its schedules fired (`default` for the declared one)
+and the time it was scheduled for, in milliseconds since 1970 (UTC). What the tick
+means is the slice's own: a mapping's `collect` makes the item, `process` sends the
+command. Never written by an application.
+
+@example
+```rescript
+module FromClock = Mapping.Make(
+  Reventless.Clock,
+  DemandReport,
+  {
+    open Reventless.Clock
+    let collect = (Tick({key, at}), ~sourceId as _, _ctx) =>
+      [(itemId(key, at), ({day: at}: DemandReport.todoItem))]
+    let resolve = _ => None
+  },
+)
+```
+*/
+module Id = Id.String
+
+let name = "Clock"
+
+@schema
+type event = Tick({key: string, at: float})
+
+/** The key a declared `schedule` is held under. */
+let defaultKey = "default"
+
+/**
+The to-do item id for a tick: `<key>@<scheduled time in UTC, to the minute>`, such
+as `default@2026-10-16T06:00Z`. The same tick delivered twice names the same item.
+*/
+let itemId = (key, at) =>
+  `${key}@${at->Date.fromTime->Date.toISOString->String.slice(~start=0, ~end=16)}Z`

package/src/components/Clock.res.mjs

@@ -0,0 +1,28 @@
+// Generated by ReScript, PLEASE EDIT WITH CARE
+
+import * as Sury from "sury";
+
+let eventSchema = Sury.$schema(s => ({
+  TAG: "Tick",
+  key: s.m(Sury.string),
+  at: s.m(Sury.number)
+}));
+
+function itemId(key, at) {
+  return key + `@` + new Date(at).toISOString().slice(0, 16) + `Z`;
+}
+
+let Id;
+
+let name = "Clock";
+
+let defaultKey = "default";
+
+export {
+  Id,
+  name,
+  eventSchema,
+  defaultKey,
+  itemId,
+}
+/* eventSchema Not a pure module */

package/src/components/Plugin.res

@@ -301,6 +301,9 @@ type automationSliceDef = {
   targetName: string,
   /** Chapter grouping band — see `queryableDef.chapter`. */
   chapter: option<string>,
+  /** The declared `schedule`, as the JSON of `Schedule.timeSchema`; `None` for an
+      automation started by events only, and in a structure from before the field. */
+  schedule?: string,
 }
 
 @schema

package/src/components/Plugin.res.mjs

@@ -158,7 +158,8 @@ let automationSliceDefSchema = Sury.$schema(s => ({
   consumedEventTypes: s.m(Sury.array(Sury.string)),
   producedCommandTypes: s.m(Sury.array(Sury.string)),
   targetName: s.m(Sury.string),
-  chapter: s.m(Sury.$option(Sury.string))
+  chapter: s.m(Sury.$option(Sury.string)),
+  schedule: s.m(Sury.$option(Sury.string))
 }));
 
 let outboundTranslationSliceDefSchema = Sury.$schema(s => ({

package/src/generator/PluginGenerator.res

@@ -24,6 +24,18 @@ let parseArgs = (argv: array<string>): result<args, string> =>
 
 let cli: CliArgs.cli<args> = {bin: "generate-plugin", usage, parse: parseArgs}
 
+/** The generated files sit in the plugin's source tree, so they face its format
+    gate like any other source. Codegen lays text out for reading, not for the
+    formatter, so the formatter settles the layout before the file is written.
+    Raising beats falling back: unformatted output would build and then fail the
+    format gate on every regeneration. */
+let formatted = (source: string, ~cwd: string): string =>
+  NodeChildProcess.execFileSync(
+    "pnpm",
+    ["exec", "rescript", "format", "--stdin", ".res"],
+    {cwd, encoding: "utf8", input: source},
+  )
+
 // A usage mistake exits non-zero, so `prebuild` (and CI) fail instead of
 // continuing green with no Plugin.res generated.
 let main = () =>
@@ -46,7 +58,7 @@ let main = () =>
     }
 
     let pluginPath = NodePath.join([outputDir, "Plugin.res"])
-    NodeFs.writeFileSync(pluginPath, source)
+    NodeFs.writeFileSync(pluginPath, source->formatted(~cwd=outputDir))
     Console.log("Generated: " ++ pluginPath)
 
     switch variant {
@@ -54,7 +66,7 @@ let main = () =>
     | Config.Aws(_) =>
       let mainSource = Codegen.renderMain(~config)
       let mainPath = NodePath.join([outputDir, "Main.res"])
-      NodeFs.writeFileSync(mainPath, mainSource)
+      NodeFs.writeFileSync(mainPath, mainSource->formatted(~cwd=outputDir))
       Console.log("Generated: " ++ mainPath)
     }
   })

package/src/generator/PluginGenerator.res.mjs

@@ -7,6 +7,7 @@ import * as Config$Reventless from "./Config.res.mjs";
 import * as CliArgs$Reventless from "../CliArgs.res.mjs";
 import * as Codegen$Reventless from "./Codegen.res.mjs";
 import * as Pairing$Reventless from "./Pairing.res.mjs";
+import * as Nodechild_process from "node:child_process";
 import * as Discovery$Reventless from "./Discovery.res.mjs";
 
 let usage = `Usage: generate-plugin [--aws <Namespace>] <srcDir>
@@ -62,6 +63,20 @@ let cli = {
   parse: parseArgs
 };
 
+function formatted(source, cwd) {
+  return Nodechild_process.execFileSync("pnpm", [
+    "exec",
+    "rescript",
+    "format",
+    "--stdin",
+    ".res"
+  ], {
+    cwd: cwd,
+    encoding: "utf8",
+    input: source
+  });
+}
+
 function main() {
   return CliArgs$Reventless.run(cli, undefined, undefined, async param => {
     let variant = param.variant;
@@ -86,14 +101,14 @@ function main() {
     let outputDir;
     outputDir = typeof variant !== "object" ? srcDir : Nodepath.join(process.cwd(), "src");
     let pluginPath = Nodepath.join(outputDir, "Plugin.res");
-    Nodefs.writeFileSync(pluginPath, source, "utf8");
+    Nodefs.writeFileSync(pluginPath, formatted(source, outputDir), "utf8");
     console.log("Generated: " + pluginPath);
     if (typeof variant !== "object") {
       return;
     }
     let mainSource = Codegen$Reventless.renderMain(config);
     let mainPath = Nodepath.join(outputDir, "Main.res");
-    Nodefs.writeFileSync(mainPath, mainSource, "utf8");
+    Nodefs.writeFileSync(mainPath, formatted(mainSource, outputDir), "utf8");
     console.log("Generated: " + mainPath);
   });
 }
@@ -102,6 +117,7 @@ export {
   usage,
   parseArgs,
   cli,
+  formatted,
   main,
 }
 /* node:fs Not a pure module */

package/src/types/Schedule.res

@@ -9,44 +9,88 @@ type hour = int
 @schema
 type minute = int
 
+/** A fixed length, measured from the previous firing. */
+@schema
+type interval =
+  | Minutes(int)
+  | Hours(int)
+  | Days(int)
+  | Weeks(int)
+
+@schema
+type weekday = Mon | Tue | Wed | Thu | Fri | Sat | Sun
+
+/**
+A wall-clock time that recurs. `Monthly` with `every: 3` fires in January, April, July
+and October; a `day` a month does not have (the 31st) is skipped in that month.
+*/
+@schema
+type calendar =
+  | Daily({hour: hour, minute: minute})
+  | Weekly({days: array<weekday>, hour: hour, minute: minute})
+  | Monthly({day: day, hour: hour, minute: minute, every?: int})
+  | Yearly({month: month, day: day, hour: hour, minute: minute})
+
+/** A span counted once, from the moment a schedule is set; months and years by the calendar. */
+@schema
+type period =
+  | Minutes(int)
+  | Hours(int)
+  | Days(int)
+  | Weeks(int)
+  | Months(int)
+  | Years(int)
+
+/** A wall-clock date and time, read in the schedule's zone. */
+@schema
+type localTime = {year: year, month: month, day: day, hour: hour, minute: minute}
+
+/** `After` becomes `At` when the schedule is set. */
+@schema
+type moment = At(localTime) | After(period)
+
+/** An IANA zone name such as `Europe/Berlin`; absent means UTC. */
+@schema
+type zone = string
+
 /**
-The repetition rule for a scheduled event.
+When a schedule fires: `Every` an interval, `Calendar` a wall-clock time that recurs,
+or `Once` a single moment.
 
-- `Single(year, month, day, hour, minute)` — fires once at an absolute UTC time
-- `Minutes(n)` / `Hours(n)` / `Days(n)` — fires every n minutes / hours / days
-- `Daily(hour, minute)` — fires every day at the given UTC time
-- `Weekdays(hour, minute)` — fires Monday–Friday at the given UTC time
-- `WeekdaysAndSaturday(hour, minute)` — fires Monday–Saturday at the given UTC time
+A calendar time in the hour skipped by daylight saving does not fire that day; one in
+the repeated hour fires once, at the first.
 
 @example
 ```rescript
-// Fire every 15 minutes
-let rate = Schedule.Minutes(15)
+// every 15 minutes
+let every = Schedule.Every(Minutes(15))
+
+// weekdays at 07:30 in Berlin
+let weekdays = Schedule.Calendar({
+  calendar: Weekly({days: [Mon, Tue, Wed, Thu, Fri], hour: 7, minute: 30}),
+  zone: "Europe/Berlin",
+})
 
-// Fire once on 2024-12-31 at 23:59 UTC
-let oneTime = Schedule.Single(2024, 12, 31, 23, 59)
+// once, ten minutes after it is set
+let reminder = Schedule.Once({moment: After(Minutes(10))})
 ```
 */
 @schema
-type rate =
-  | Single(year, month, day, hour, minute)
-  | Minutes(int)
-  | Hours(int)
-  | Days(int)
-  | Daily(hour, minute)
-  | Weekdays(hour, minute)
-  | WeekdaysAndSaturday(hour, minute)
+type time =
+  | Every(interval)
+  | Calendar({calendar: calendar, zone?: zone})
+  | Once({moment: moment, zone?: zone})
 
 /**
-A named recurring or one-time schedule.
+A named schedule.
 
-`payload` is an opaque string forwarded to the task handler when the schedule fires.
+`payload` is an opaque string forwarded to the target when the schedule fires.
 
 @example
 ```rescript
 let dailySync: Schedule.schedule = {
   name: "DailyCatalogSync",
-  rate: Daily(2, 0),  // 02:00 UTC every day
+  time: Calendar({calendar: Daily({hour: 2, minute: 0})}),
   payload: `{"action": "sync"}`,
 }
 ```
@@ -54,7 +98,7 @@ let dailySync: Schedule.schedule = {
 @schema
 type schedule = {
   name: string,
-  rate: rate,
+  time: time,
   payload: string,
 }
 

package/src/types/Schedule.res.mjs

@@ -12,15 +12,7 @@ let hourSchema = Sury.int32;
 
 let minuteSchema = Sury.int32;
 
-let rateSchema = Sury.union([
-  Sury.$schema(s => ({
-    TAG: "Single",
-    _0: s.m(yearSchema),
-    _1: s.m(monthSchema),
-    _2: s.m(daySchema),
-    _3: s.m(hourSchema),
-    _4: s.m(minuteSchema)
-  })),
+let intervalSchema = Sury.union([
   Sury.$schema(s => ({
     TAG: "Minutes",
     _0: s.m(Sury.int32)
@@ -33,26 +25,118 @@ let rateSchema = Sury.union([
     TAG: "Days",
     _0: s.m(Sury.int32)
   })),
+  Sury.$schema(s => ({
+    TAG: "Weeks",
+    _0: s.m(Sury.int32)
+  }))
+]);
+
+let weekdaySchema = Sury.union([
+  Sury.literal("Mon"),
+  Sury.literal("Tue"),
+  Sury.literal("Wed"),
+  Sury.literal("Thu"),
+  Sury.literal("Fri"),
+  Sury.literal("Sat"),
+  Sury.literal("Sun")
+]);
+
+let calendarSchema = Sury.union([
   Sury.$schema(s => ({
     TAG: "Daily",
-    _0: s.m(hourSchema),
-    _1: s.m(minuteSchema)
+    hour: s.m(hourSchema),
+    minute: s.m(minuteSchema)
+  })),
+  Sury.$schema(s => ({
+    TAG: "Weekly",
+    days: s.m(Sury.array(weekdaySchema)),
+    hour: s.m(hourSchema),
+    minute: s.m(minuteSchema)
+  })),
+  Sury.$schema(s => ({
+    TAG: "Monthly",
+    day: s.m(daySchema),
+    hour: s.m(hourSchema),
+    minute: s.m(minuteSchema),
+    every: s.m(Sury.$option(Sury.int32))
+  })),
+  Sury.$schema(s => ({
+    TAG: "Yearly",
+    month: s.m(monthSchema),
+    day: s.m(daySchema),
+    hour: s.m(hourSchema),
+    minute: s.m(minuteSchema)
+  }))
+]);
+
+let periodSchema = Sury.union([
+  Sury.$schema(s => ({
+    TAG: "Minutes",
+    _0: s.m(Sury.int32)
+  })),
+  Sury.$schema(s => ({
+    TAG: "Hours",
+    _0: s.m(Sury.int32)
+  })),
+  Sury.$schema(s => ({
+    TAG: "Days",
+    _0: s.m(Sury.int32)
+  })),
+  Sury.$schema(s => ({
+    TAG: "Weeks",
+    _0: s.m(Sury.int32)
+  })),
+  Sury.$schema(s => ({
+    TAG: "Months",
+    _0: s.m(Sury.int32)
+  })),
+  Sury.$schema(s => ({
+    TAG: "Years",
+    _0: s.m(Sury.int32)
+  }))
+]);
+
+let localTimeSchema = Sury.$schema(s => ({
+  year: s.m(yearSchema),
+  month: s.m(monthSchema),
+  day: s.m(daySchema),
+  hour: s.m(hourSchema),
+  minute: s.m(minuteSchema)
+}));
+
+let momentSchema = Sury.union([
+  Sury.$schema(s => ({
+    TAG: "At",
+    _0: s.m(localTimeSchema)
+  })),
+  Sury.$schema(s => ({
+    TAG: "After",
+    _0: s.m(periodSchema)
+  }))
+]);
+
+let zoneSchema = Sury.string;
+
+let timeSchema = Sury.union([
+  Sury.$schema(s => ({
+    TAG: "Every",
+    _0: s.m(intervalSchema)
   })),
   Sury.$schema(s => ({
-    TAG: "Weekdays",
-    _0: s.m(hourSchema),
-    _1: s.m(minuteSchema)
+    TAG: "Calendar",
+    calendar: s.m(calendarSchema),
+    zone: s.m(Sury.$option(zoneSchema))
   })),
   Sury.$schema(s => ({
-    TAG: "WeekdaysAndSaturday",
-    _0: s.m(hourSchema),
-    _1: s.m(minuteSchema)
+    TAG: "Once",
+    moment: s.m(momentSchema),
+    zone: s.m(Sury.$option(zoneSchema))
   }))
 ]);
 
 let scheduleSchema = Sury.$schema(s => ({
   name: s.m(Sury.string),
-  rate: s.m(rateSchema),
+  time: s.m(timeSchema),
   payload: s.m(Sury.string)
 }));
 
@@ -62,7 +146,14 @@ export {
   daySchema,
   hourSchema,
   minuteSchema,
-  rateSchema,
+  intervalSchema,
+  weekdaySchema,
+  calendarSchema,
+  periodSchema,
+  localTimeSchema,
+  momentSchema,
+  zoneSchema,
+  timeSchema,
   scheduleSchema,
 }
 /* yearSchema Not a pure module */