anbaric 1.23.2 → 1.24.0

package/README.md

@@ -266,6 +266,37 @@ re-evaluates its transitions, so the input drives it on and the wait clears once
 it moves to another state. Actions placed after an `Await` in the same state do
 not run when the job resumes.
 
+Some work is started by the clock rather than by a person or an event. The
+**`JobRunScheduler`** starts jobs on a timetable — give it a machine and a
+`Schedule` and it does the rest:
+
+```ts
+import {JobRunScheduler, Schedule} from "anbaric";
+
+// 02:00 every day
+JobRunScheduler.instance().schedule(
+    reconciliation,
+    new Schedule(Schedule.everyDay(), [{ hours: 2, minutes: 0 }]),
+);
+
+// weekdays at 09:00 and 17:30
+JobRunScheduler.instance().schedule(
+    digest,
+    new Schedule(Schedule.daysOfWeek([1, 2, 3, 4, 5]), [{ hours: 9, minutes: 0 }, { hours: 17, minutes: 30 }]),
+);
+```
+
+The day test is a predicate, so anything expressible in code is a schedule.
+Runs are **planned ahead and stored** rather than discovered at the last moment,
+so a restart keeps the timetable and a scheduler that was down starts the runs
+it missed instead of skipping them; each job carries the run it belongs to in
+`scheduledFor`. Machines due at the same moment are spread by a small random
+offset, applied when the run is planned so the stored time is the real one.
+Locally the plan is in memory; deployed it lives in the platform database, where
+claiming a due run is atomic — so several instances of your app can run the
+scheduler and each run still starts exactly once. See
+[Scheduled runs](anbaric/docs/features/scheduled-runs.md).
+
 Everything is pluggable through env-driven factories: locally (no env vars)
 you get in-memory persistence and queueing; deployed, the same factories talk
 to the platform automatically. The same applies to `JsonStoreFactory`

package/docs/README.md

@@ -21,6 +21,7 @@ What the framework gives you, one capability at a time.
 - [State machines](features/state-machines.md) — defining and running a workflow
 - [Actions and actors](features/actions-and-actors.md) — who does the work, and how
 - [Awaiting input](features/awaiting-input.md) — pausing a job for a human or external system
+- [Scheduled runs](features/scheduled-runs.md) — starting jobs on a timetable
 - [AI agents](features/ai-agents.md) — letting a model drive a state
 - [Documents and secrets](features/documents-and-secrets.md) — the JSON and secret stores
 - [The SQL store](features/sql-store.md) — a relational database for structured data

package/docs/api/environment.md

@@ -29,6 +29,7 @@ defaulting to a local implementation otherwise).
 | --- | --- | --- |
 | `ANBARIC_JOB_PERSISTENCE_TYPE` | where jobs are stored | in-memory |
 | `ANBARIC_QUEUE_TYPE` | the job queue | in-memory |
+| `ANBARIC_JOB_RUN_SCHEDULE_PERSISTENCE_TYPE` | where planned [scheduled runs](../features/scheduled-runs.md) are kept | in-memory |
 | `ANBARIC_AUDITOR_TYPE` | the audit sink (`cloud` → platform) | console |
 | `ANBARIC_JSON_STORE_TYPE` | the JSON document store | in-memory |
 | `ANBARIC_SECRET_STORE_TYPE` | the secret store | in-memory (encrypted) |

package/docs/api/state-machine.md

@@ -265,6 +265,7 @@ have a definition, or writes to it are rejected.
 ```ts
 id : string
 required : boolean = false
+example? : any                          // a realistic value, for tooling
 validation : (value : any) => boolean   // default: () => true
 
 constructor(id : string)
@@ -275,11 +276,65 @@ Configure by mutation:
 ```ts
 const email = new PropertyDefinition("email");
 email.required = true;
+email.example = "someone@example.com";
 email.validation = (value) => typeof value === "string" && value.includes("@");
 ```
 
 Pass the definitions as the `StateMachine`'s fourth argument.
 
+`example` is carried into the machine's published definition, so tools that
+start a job — the admin console's **Start** dialog, generated documentation —
+can offer a realistic value instead of an empty box. It is never validated and
+never becomes a default; it is purely descriptive.
+
+---
+
+## `Schedule`
+
+Which days a machine runs on, and at what times on those days. See
+[Scheduled runs](../features/scheduled-runs.md).
+
+```ts
+constructor(dayTest : (date : Date) => boolean, times : Array<{ hours : number, minutes : number }>)
+
+getRuns(from : Date, to : Date) : Array<Date>   // exclusive of `from`, inclusive of `to`
+
+static everyDay() : (date : Date) => boolean
+static daysOfWeek(days : Array<number>)         // 0 = Sunday … 6 = Saturday
+static daysOfMonth(days : Array<number>)        // calendar dates
+```
+
+The day test is an ordinary predicate, so any rule you can write in code — the
+last working day of a quarter, every other Tuesday — is a schedule.
+
+---
+
+## `JobRunScheduler`
+
+Starts jobs on a timetable. Runs are planned ahead and stored, so the plan
+survives a restart and missed runs are caught up rather than skipped.
+
+```ts
+static instance() : JobRunScheduler
+
+schedule(machine : StateMachine, at : Schedule,
+         lookaheadMs : number = 86_400_000,
+         randomRunOffsetMs : [number, number] = [0, 120_000]) : void
+
+tick(now? : Date) : Promise<void>   // plan and start everything owed; mostly for tests
+cleanUp() : Promise<void>
+```
+
+`lookaheadMs` is how far ahead runs are planned; `randomRunOffsetMs` spreads
+machines that would otherwise all start on the same second, and is applied when
+the run is planned so the stored time is the time it runs. Pass `[0, 0]` to
+start exactly on the minute. Each scheduled job carries its run in the
+`scheduledFor` property.
+
+Storage comes from `JobRunSchedulePersistenceFactory` — in memory locally, the
+platform database when deployed, where claiming a due run is atomic so several
+instances can schedule the same machines safely.
+
 ---
 
 ## `Actor`

package/docs/features/scheduled-runs.md

@@ -0,0 +1,106 @@
+# Scheduled runs
+
+Some work isn't started by a person or an event — it just needs to happen at a
+certain time. A nightly reconciliation, a weekly digest, an invoice run on the
+1st of the month. The **job run scheduler** starts jobs on a timetable, so a
+machine that should run at 09:00 gets a job at 09:00 without anything asking it
+to.
+
+## Scheduling a machine
+
+Give the scheduler a machine and a `Schedule`:
+
+```ts
+import {JobRunScheduler, Schedule, StateMachine} from "anbaric";
+
+const reconciliation = new StateMachine("reconciliation", [/* … */]);
+
+JobRunScheduler.instance().schedule(
+    reconciliation,
+    new Schedule(Schedule.everyDay(), [{ hours: 2, minutes: 0 }]),
+);
+```
+
+That's it. From then on a job is started on `reconciliation` at 02:00 every day,
+in its start state, and progresses like any other job.
+
+## Describing a timetable
+
+A `Schedule` is **which days** and **what times on those days**, kept separate so
+one shape covers everything:
+
+```ts
+new Schedule(Schedule.everyDay(), [{ hours: 9, minutes: 0 }]);                       // 09:00 daily
+new Schedule(Schedule.daysOfWeek([1, 2, 3, 4, 5]), [{ hours: 9, minutes: 0 },
+                                                    { hours: 17, minutes: 30 }]);    // weekdays, twice
+new Schedule(Schedule.daysOfMonth([1]), [{ hours: 0, minutes: 0 }]);                 // the 1st, midnight
+```
+
+`daysOfWeek` takes 0 (Sunday) to 6 (Saturday); `daysOfMonth` takes calendar
+dates. The day test is just a predicate, so anything you can express in code —
+last working day of the quarter, every other Tuesday — is a schedule:
+
+```ts
+const quarterEnd = (date : Date) => [2, 5, 8, 11].includes(date.getMonth()) && date.getDate() === 28;
+new Schedule(quarterEnd, [{ hours: 23, minutes: 0 }]);
+```
+
+## Runs are planned before they happen
+
+The scheduler doesn't wake up and ask "is anything due?". It **plans ahead** —
+by default a day at a time — writing each future run to storage, then starts
+runs as they come due. Two things follow from that, both deliberate:
+
+- **A restart doesn't lose the timetable.** The plan is already stored, so the
+  scheduler picks up where it left off.
+- **Downtime doesn't silently skip runs.** A scheduler that was down for two
+  days starts the runs it missed as soon as it comes back, rather than
+  pretending they never existed. If you don't want that catch-up for a
+  particular machine, make its action check `scheduledFor` and return early.
+
+Every scheduled job carries the run it belongs to:
+
+```ts
+processRun.run = async (job) => {
+    const scheduledFor = new Date(job.properties.get("scheduledFor"));
+    // …reconcile everything up to scheduledFor
+};
+```
+
+## Spreading the load
+
+Machines scheduled at the same time would otherwise all start on the same
+second. Each machine gets a small random offset — up to two minutes by default —
+applied **when the run is planned**, so the stored time is the time it really
+runs. Control it per machine:
+
+```ts
+JobRunScheduler.instance().schedule(
+    digest,
+    new Schedule(Schedule.everyDay(), [{ hours: 6, minutes: 0 }]),
+    1000 * 60 * 60 * 24,   // plan a day ahead
+    [0, 1000 * 60 * 15],   // start somewhere in the 15 minutes after 06:00
+);
+```
+
+Pass `[0, 0]` for a machine that must start exactly on the minute.
+
+## Local and deployed
+
+Like every other service, the scheduler resolves its storage through a factory.
+Locally the plan is held in memory, so scheduling works on your laptop with no
+setup — though a plan in memory dies with the process. Deployed, the platform
+sets `ANBARIC_JOB_RUN_SCHEDULE_PERSISTENCE_TYPE=cloud` and the plan lives in the
+platform database, surviving restarts and redeploys. **Your code is identical
+either way** — see [Environment and factories](../api/environment.md).
+
+Because the plan is shared, more than one instance of your app can run the
+scheduler safely: claiming a due run is atomic, so each run is started exactly
+once no matter how many instances are up.
+
+## Scheduling and queueing are different things
+
+A scheduled run is a **timetable entry**: "this machine should get a job at
+09:00". `Queue.schedule` delays an **existing job**: "look at this job again in
+ten minutes". Reach for the scheduler when the trigger is the clock, and for a
+delayed enqueue when a job needs to wait before continuing.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "anbaric",
-  "version": "1.23.2",
+  "version": "1.24.0",
   "description": "Everything needed to write an Anbaric app: state machines, jobs, document and secret stores, local in-memory implementations and the Anbaric Cloud clients",
   "license": "MIT",
   "type": "module",
@@ -24,9 +24,9 @@
     "prepublishOnly": "npm run build"
   },
   "dependencies": {
-    "anbaric-impl-cloud": "^1.23.2",
-    "anbaric-data-store": "^1.23.2",
-    "anbaric-state-machine": "^1.23.2",
-    "anbaric-tsapi": "^1.23.2"
+    "anbaric-impl-cloud": "^1.24.0",
+    "anbaric-data-store": "^1.24.0",
+    "anbaric-state-machine": "^1.24.0",
+    "anbaric-tsapi": "^1.24.0"
   }
 }