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

package/CHANGELOG.md

@@ -3,6 +3,20 @@
 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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@reventlessdev/reventless-spec",
-  "version": "3.0.0-alpha.164",
+  "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 ───────────────────────────────────────────
@@ -117,6 +125,17 @@ type context = {
   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.
 
@@ -148,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>
 }
 
 /**
@@ -233,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>
 }
 
 /**
@@ -314,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 => ({