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

package/CHANGELOG.md

@@ -3,6 +3,25 @@
 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.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.164",
   "description": "Specifications for Reventless",
   "license": "Apache-2.0",
   "bin": {

package/src/components/AutomationSlice.res

@@ -111,6 +111,10 @@ 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,
 }
 
 /**
@@ -166,9 +170,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.

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 */